jyy-textkit-web

Diff, convert and format structured text. Mimics functionalities of websites like yamldiff.com, jsondiff.com, diffchecker.com, puts them all in one page with one set of keybindings.

Disclaimer: vibe-coded utility tool for myself

Tools

Tool	Status
YAML semantic diff	working
JSON semantic diff	working
Text diff	working
JSON ↔ YAML convert	working
JSON / YAML format	working

The three diff tools are one component (src/tools/diff/DiffTool.svelte) parameterised by format. Editing and diffing are separate stages: inputs are editable, the result is read-only, and what the result stage shows is exactly what was compared.

How it works

All four tools are one pipeline with different ends attached:

input --> parse (yaml | json | none) ──> canonicalize ──┬──> side-by-side text diff
                                                        └──> structural path list

The idea is in src/lib/core/canonicalize.ts: once two payloads are reduced to a canonical form — keys sorted, numbers normalised, anchors resolved — a plain text diff of the two canonical strings is the semantic diff. That means the diff tools can reuse one familiar side-by-side renderer instead of inventing a bespoke one, and "what counts as a difference" lives in exactly one auditable place.

Both diff views run over the same canonicalised values, so they cannot disagree about what counts as a difference. Plain text has nothing to parse, so it substitutes explicit line-level options (src/lib/core/textnorm.ts) for the parse step — same shape, same guarantee.

Convert is the same pipeline with one input and no diff step.

Format deliberately bypasses this pipeline. parse reduces YAML to plain values via toJS(), which throws away comments, blank lines and flow style — exactly right for diffing, exactly wrong for reformatting. So src/lib/core/prettify.ts stays on the yaml library's Document API end to end. Its contract, tested across every option combination: the parsed value never changes, and formatting twice gives the same text as formatting once.

Two behaviours worth knowing:

• Expand inline (on by default) rewrites {a: 1} and [1, 2] as block collections; without it a pasted one-liner comes back as the same one-liner. A comment trailing an inline collection gets moved inside the expanded block.
• Wrap folds long scalars at roughly the chosen width. It is a target, not a hard cap: nested lines can overshoot by their indent, and a string with nowhere to break (a long URL) is left whole.

Format auto-detects the same way Convert does, so JSON with trailing commas or comments falls through to YAML. Pin the source to JSON to get an error instead.

Layout

src/
├── lib/core/          parse, emit, canonicalize, structdiff, textnorm, prettify, router, theme
├── lib/components/    Editor, MergePanes, StructuralDiff, CommandPalette
├── tools/registry.ts  single source of truth for what the site can do
├── tools/diff/        the shared diff tool, used by the three diff entries
└── tools/<id>/        one directory per tool

Adding a tool

1. src/tools/<id>/<Name>.svelte
2. One entry in src/tools/registry.ts

That's it — the sidebar, routing, and command palette all read from the registry. Keep the registry a plain array; resist turning it into a plugin system until there's a real reason.

Running

npm install
npm run dev        # http://localhost:5173
npm test           # vitest, core logic
npm run test:watch
npm run check      # svelte-check + tsc
npm run build      # -> dist/

Tests cover src/lib/core — parsing, emitting, canonicalisation, and the canonical-form equivalence the diff tools depend on. Correctness is the product here, so new behaviour in core should arrive with a test.

Conventions

• Commits — Conventional Commits: feat:, fix:, test:, docs:, chore:, refactor:. Keep them small and single-purpose rather than one large drop.
• Changelog — notable changes go under Unreleased in CHANGELOG.md as they land (Keep a Changelog).
• Releases — move Unreleased under a vX.Y.Z heading, then tag the commit vX.Y.Z (SemVer).
• Backlog — unscoped ideas live in BACKLOG.md.

Deploying

vite.config.ts sets base: './', so dist/ is fully relative and portable:

• Cloudflare Pages / GitHub Pages — build command npm run build, output dist
• Homelab — copy dist/ behind nginx/Caddy, including at a sub-path
• Anywhere — cd dist && python3 -m http.server, or just open index.html

Routing is hash-based (#/convert) specifically so none of the above need SPA rewrite rules.

Stack

Vite · TypeScript · Svelte 5 · CodeMirror 6 · yaml · microdiff

Themed with Catppuccin — Mocha dark, Latte light, following the system preference until the toggle is used.

src/app.css keeps the raw --ctp-* palette and the semantic --bg/--fg/ --syn-* tokens in separate layers. Style components against the semantic tokens only; adding another variant should mean adding one palette block and touching nothing else.