@markup-carve/carve-grammars 0.1.7 → 0.1.9

package/README.md

@@ -28,21 +28,25 @@ present here is not a promise that the editor grammars use the same one.
 npm install @markup-carve/carve-grammars
 ```
 
-All peer dependencies are optional - install only what you use:
-`@tiptap/core` + `@tiptap/starter-kit` (v2 or v3) for the editor, `prismjs` (v1)
-for Prism, `highlight.js` (v11) for highlight.js. CI runs the suite against both
-Tiptap majors.
+All peer dependencies are optional - install only what you use: the Tiptap
+packages below (v2 or v3) for the editor, `prismjs` (v1) for Prism,
+`highlight.js` (v11) for highlight.js. CI runs the suite against both Tiptap
+majors.
+
+`@markup-carve/carve-grammars/tiptap` loads `CarveKit`, which imports several
+standalone Tiptap extensions, so the editor entry needs all of these installed.
+Disabling one through `CarveKit.configure()` does not remove its import:
+
+```bash
+npm install @tiptap/core @tiptap/pm @tiptap/starter-kit \
+  @tiptap/extension-{bullet-list,code,code-block,hard-break,heading,highlight,image,link,list-item,ordered-list,subscript,superscript,table,table-cell,table-header,table-row,task-item,task-list,underline}
+```
 
 On Tiptap 3, `CarveKit` disables StarterKit's bundled Underline and Link, since
 it registers its own (underline carries Carve's `_text_` mapping). Pass
 `starterKit: { underline: true }` to opt back in, at the cost of a duplicate
 mark name.
 
-`CarveKit` also pulls in several standalone Tiptap marks/extensions (highlight,
-subscript, superscript, underline, link, image, table, task-list); install the
-`@tiptap/extension-*` packages you use, or disable them via
-`CarveKit.configure({ underline: false, ... })`.
-
 ## Usage
 
 ```js
@@ -96,7 +100,7 @@ Without it, the attribute stays literal: `<span abbr="...">`. The mark's
 `parseHTML` reads back the `<abbr title>` form.
 
 The tokens target carve-php's **parser** (the contract: serialized Carve must parse
-back to the same elements). Carve's inline syntax differs notably from Djot's:
+back to the same elements). Carve's inline syntax differs from Djot's:
 emphasis is `/text/` (Djot uses `_`), `_text_` is underline, `~text~` is
 strikethrough, highlight is `=text=`, and subscript/superscript are the
 braced `{,text,}` / `{^text^}` only (a bare `,` or `^` is literal text since
@@ -105,8 +109,9 @@ carve #259).
 Each single-char delimiter has two equivalent forms: a **bare** form
 (`=text=`) and a **forced brace** form (`{=text=}`) that also works intraword;
 both parse to the same element. The two columns above list bare / forced.
-`serializeToCarve` emits the bare form for `* / _ ~` and the forced `{…}` form
-for `= , ^` (round-trip-safe — those delimiters are likelier to be inert bare);
+`serializeToCarve` emits the bare form for `* / _ ~`, or the forced form where a
+letter or digit touches the delimiter, and the forced `{…}` form
+for `= , ^` (round-trip-safe: those delimiters are likelier to be inert bare);
 `{+…+}` / `{-…-}` (insert / delete) have only the brace form, since `+` / `-`
 are not emphasis delimiters.
 
@@ -259,6 +264,59 @@ available as the `editor` CSS part (`carve-editor::part(editor)`). Tiptap stays
 an implementation detail of the element, although its peer packages must be
 installed with `carve-grammars`.
 
+Document front matter appears as a collapsed **Document metadata** card. Expand
+it to edit the common `title`, `lang`, `author`, and `description` fields, or use
+the raw YAML/TOML field for custom metadata. Both paths update the document
+through the editor, so they participate in undo/redo and preserve unknown keys.
+
+### Quick fields
+
+The four quick fields are a default, not the contract. A product whose front
+matter means something else describes its own:
+
+```js
+CarveKit.configure({
+  carveFrontmatter: {
+    fields: [
+      { key: 'title', label: 'Note title', placeholder: 'Optional title', inputAttributes: { required: true, maxlength: 120 } },
+      { key: 'summary', label: 'Summary', multiline: true },
+    ],
+  },
+})
+```
+
+A descriptor needs a `key` - the front matter key it reads and writes. `label`
+defaults to the capitalized key, `placeholder` is optional, and `multiline`
+picks a `textarea` instead of an `input`. The list replaces the default one
+entirely, so an empty array renders the raw front matter editor with no quick
+fields at all:
+
+```js
+CarveKit.configure({ carveFrontmatter: { fields: [] } })
+```
+
+A key may appear only once; a second descriptor for it is refused, because the
+controls are held by key and the earlier one would render blank and write
+nowhere.
+
+`inputAttributes` carries native validation and input hints: `required`,
+`autocomplete`, `inputmode`, `minlength`, `maxlength`, `pattern` and
+`aria-describedby`. These are enforced: a change that fails the control's own
+`checkValidity()` is reported to the author and never reaches the document.
+Anything else is **refused with a `TypeError`** rather than ignored - the node view owns `name`, `type`, `value`, `disabled` and `readonly`,
+and an event handler set here would bypass the format-aware update path. A
+constraint that is silently dropped reads like a working one that never fires,
+which is why the rejection is loud.
+
+The collapsed summary still reads `title` and `lang` out of the document
+whatever the field list says, and writes still go through an editor transaction,
+so undo/redo and unknown-key preservation are unchanged.
+Unsupported-source atoms use the same compact/editable pattern for their exact
+Carve payload. Inline footnotes, cross-references, and citations open target
+pickers, while abbreviation and link-reference definitions use collapsible
+forms. Import `@markup-carve/carve-grammars/tiptap/editor.css` when mounting
+`CarveKit` directly to receive the associated editor chrome and table styling.
+
 ## Syntax highlighting
 
 Render Carve source as highlighted HTML on the web. Both grammars cover the full
@@ -364,6 +422,34 @@ can drop the one character a rule is about. The spec corpus is the exception and
 can afford to be - it marks `tests/corpus/**` as `-text`, so
 `250-line-endings-and-a-byte-order-mark-3.crv` really does begin `ef bb bf`.
 
+### Link destinations inside a bare run
+
+A delimiter inside a link destination, its title or an autolink does not close
+the bare run around it, so `/see [x](http://a.b/c) now/` stays one italic run.
+The three grammars follow the spec's productions for what counts: a `](` needs a
+complete label before it (`link_text`), a destination and a title take only
+their own escapes, a title follows exactly one space (`link_title`), a URL
+autolink holds only `url_char`, and an email autolink needs a dotted domain
+ending in letters (`email_autolink`). Anything else closes the run where the
+spec closes it.
+
+Known limits, shared by all three unless noted:
+
+- A label nested more than four brackets deep, or a destination holding three
+  levels of parentheses, is not recognized. A regex cannot count.
+- Prism and highlight.js compile without the `u` flag, so an email autolink
+  accepts any non-ASCII character other than whitespace where the spec asks for
+  a letter. The TextMate grammar uses `\p{L}`.
+
+### Substitutions
+
+A substitution splits at its first arrow outside code, math, a literal, a
+comment or an escape, and each half holds inline content. With no such arrow,
+`{~ ~}` is a forced strikethrough.
+
+Known limit: in highlight.js and TextMate, a link or autolink that spans the
+arrow stays whole in the deleted half. `{~[x](u~>v)~>c~}` splits after `u`.
+
 ### Fence words
 
 All three surfaces answer `carve` and `crv`. `.crv` is the canonical file
@@ -383,6 +469,33 @@ before resolving it. `tests/lib/aliases.js` holds the required set and
 `tests/alias-parity-test.js` asserts it on each surface through that surface's
 own registration API.
 
+### Attribute blocks
+
+Known limit, shared by all three: a block glued to a bare delimiter is read as
+attached even where the delimiter closes no run. In `` x*{title="`"} y `` the
+braces are text, so the backtick opens a code span, but all three scope an
+attribute block.
+
+### TextMate limits
+
+A TextMate rule sees one line at a time, so a few shapes color differently from
+how Carve reads them. vscode-carve declares the same three.
+
+- A bare bold run can cross a soft line break, so its opener can't check for a
+  closer first. When the only closer-shaped `*` sits inside a code span, or
+  there is none, the run colors to the end of its paragraph:
+  `` x *a `b* c` d `` renders as text but shows as bold.
+- A braced span whose closer is on a later line is not scoped as a span.
+- A bare italic, underline, strikethrough or highlight run is scoped only when
+  its closer is on the same line.
+
+### Prism and highlight.js limits
+
+- Prism scopes a bare run only when its closer is on the same line.
+- highlight.js compiles without the `u` flag, so it reads any non-ASCII
+  character after a bare closer as a letter. `/a/« b` renders `a` in italics
+  but shows as text.
+
 ### Prism
 
 The grammar registers itself against the global `Prism`, so `Prism` must be
@@ -452,6 +565,70 @@ Named exports for other setups: `carveGrammar`, `carveLightExtras` /
 `carveDarkExtras`, `carveLightTheme` / `carveDarkTheme`, `extendTheme`,
 `carveStylingTransformer`.
 
+#### Diff presentation with an underlying language
+
+Carve keeps a code block's presentation hooks separate from its language. The
+portable source convention for an instructional diff is a `.diff` block
+attribute above a language-tagged fence:
+
+````carve
+{.diff}
+```js
+- fileIcon.classList.add("icon-file-text");
++ fileIcon.classList.remove("icon-file-text");
+```
+````
+
+Core HTML preserves both channels as
+`<pre class="diff"><code class="language-js">`. A host can detect that shape
+and invoke the opt-in `diffCodeTransformer()` with the fence language:
+
+```js
+import { diffCodeTransformer } from '@markup-carve/carve-grammars/shiki/diff'
+import '@markup-carve/carve-grammars/shiki/carve.css'
+
+const transformers = pre.classList.contains('diff')
+    ? [diffCodeTransformer()]
+    : []
+
+const highlighted = highlighter.codeToHtml(code.textContent, {
+    lang: 'javascript',
+    theme: 'github-light',
+    transformers,
+})
+```
+
+Create a fresh transformer for every code block. It treats `+`, `-`, and a
+space as structural first characters, removes that character while Shiki
+tokenizes the underlying language, then restores it and marks added/removed
+lines. This first version targets compact instructional changes, not complete
+patch files with `@@` hunks or `---` / `+++` file headers. It is deliberately
+not enabled by `carveMarkdown()`, because ordinary code blocks must not lose
+their first character.
+
+A host that highlights with **highlight.js, Prism, or nothing** - where Shiki's
+per-line token model is not available - uses the highlighter-agnostic helper
+instead. It takes a per-line highlight callback (or defaults to HTML-escaping)
+and produces the same `line` / `diff add` / `diff remove` / `diff-marker`
+classes:
+
+```js
+import { applyLanguageDiff } from '@markup-carve/carve-grammars/diff'
+import '@markup-carve/carve-grammars/diff/carve-diff.css'
+
+document.querySelectorAll('pre.diff > code').forEach((code) => {
+    const language = [...code.classList]
+        .find((name) => name.startsWith('language-'))
+        ?.slice('language-'.length)
+    applyLanguageDiff(code, (body) => hljs.highlight(body, { language }).value)
+})
+```
+
+`renderLanguageDiff(code, highlightLine)` returns the HTML string if the host
+manages the DOM itself (a webview building a document string, a server writing
+markup). The marker is stripped before `highlightLine` runs, so the underlying
+language tokenizes the line body without its `+`/`-`/space.
+
 ## Diagram rendering
 
 Carve's `FencedRenderExtension` presets emit a `<pre class="LANG">source</pre>`
@@ -536,6 +713,7 @@ graphviz/d2 against a self-hosted server), `onError`, `fetch`.
 - `astToProseMirror(ast, options?)` - convert an existing `@markup-carve/carve`
   AST to ProseMirror JSON.
 - `serializeToCarve(doc)` - serialize an `editor.getJSON()` document to Carve markup.
+- `serializeToCarveWithReport(doc)` - the same, returning `{ source, dropped, degraded }`. `dropped` names what the source could not carry (a mention's display `label` that differs from its `id`), `degraded` a node written as literal text (a mention name with no Carve spelling, such as `Lea Thompson`, becomes `\@Lea Thompson`). A stock Tiptap `mention` node is written like `carveMention`: `id` is the name, a `null` label counts as absent, and `mentionSuggestionChar` is never written.
 - `escapeCarve(text)` - contextually escape literal Carve syntax in a plain-text run so it round-trips as text (used internally by `serializeToCarve`).
 - `CarveKit` - the bundled Tiptap extension set.
 - Individual extensions: `CarveInsert`, `CarveDelete`, `CarveCriticComment`, `CarveDiv`, `CarveSpan`, `CarveFootnote`, `CarveFootnoteDefinition`, `CarveMath`, `CarveEmbed`, `CarveAbbreviation`, `CarveDefinitionList`, `CarveUnsupported`.
@@ -604,207 +782,6 @@ implementation spelled it with underscores.
   `CarveFootnoteDefinition` is the matching body block, serialized as
   `[^label]: body`.
 
-## Tests
-
-```bash
-npm test
-```
-
-The suite holds all three grammars to one source of truth: the shared corpus
-from the [`markup-carve/carve`](https://github.com/markup-carve/carve) spec,
-vendored as the `spec/` git submodule (`git submodule update --init`).
-
-- `npm run test:coverage` - the coverage matrix. Each grammar (prism,
-  highlightjs, tiptap) declares a covered-category set and a skip set (with a
-  reason per skip); the test fails if the two do not partition every corpus
-  category, so a new spec category forces a deliberate decision.
-- `npm run test:snapshot` - golden token snapshots. Each covered `.crv` is
-  tokenized with Prism's and highlight.js's own tokenizers and the token stream
-  (type + text) is compared against a committed golden in `tests/snapshots/`.
-  Refresh intended changes with `npm run snapshots:update`.
-- `npm run test:roundtrip` - the Tiptap serializer round-trip. Each covered
-  `.crv` runs `parse -> ProseMirror JSON -> serializeToCarve -> parse` and the
-  two parsed ASTs must be identical, catching serializer drift. Categories the
-  serializer cannot represent are skipped with a reason.
-
-`npm test` runs all of the above plus the structural grammar and serializer
-unit tests. CI runs the same on Node 18, 20 and 22.
-
-### The construct ledger: ten surfaces, one derived list
-
-Carve's syntax lives on ten grammar surfaces - `tree-sitter-carve`, the four
-here (TextMate, Prism, highlight.js, Tiptap), `vscode-carve`, `intellij-carve`,
-`sublime-carve`, `vim-carve` and `emacs-carve` - and nothing used to measure
-them against the same construct list. `{%` comments landed on five of them and
-had no rule at all on the other five, with nothing going red
-(markup-carve/carve#1239, #284).
-
-`npm test` now runs `tests/construct-ledger-test.js`, which holds
-`tests/lib/construct-ledger.json` to three rules:
-
-- **The construct list is derived, never written.** `scripts/spec-constructs.mjs`
-  reads the alternatives of the `block` and `inline_element` productions out of
-  the spec's normative `spec/resources/grammar.ebnf`. A clause that adds a
-  construct makes every surface unclassified until someone says what it did
-  about it. A hand-maintained checklist would go stale in exactly that case,
-  because whoever forgot the grammar rule also forgot the checklist row.
-- **Three columns, not two.** Each construct on each surface is `IMPLEMENTED`
-  (with the name that surface gives it), `UNSUPPORTED` (with a reason - an empty
-  reason fails), or `GAP` (with a ticket). A construct in none of them fails the
-  test. Without the third column a legitimate gap - a Prism tokenizer cannot do
-  what a tree-sitter grammar does - reads as a defect, and a check with a high
-  noise floor gets muted.
-- **Two axes per construct.** Recognizing a construct and keeping its payload
-  inert are different questions, and a surface can be right about the first and
-  wrong about the second: on four editor surfaces `{% *not bold* %}` colored a
-  bold run inside a comment. Every entry declares which, and the answer is
-  measured on every run - by tokenizing a sample with a live marker inside the
-  payload - for Prism, highlight.js and every TextMate grammar whose checkout is
-  in front of the seeder, and by converting that sample through the bridge for
-  Tiptap. Those rows cannot rot. The rest are recorded, which is what
-  `payload: "unmeasured"` says out loud - a state no cell is in any more,
-  since intellij-carve's thirteen were the last of them (#329).
-
-  One sample per construct is a re-measurement, not a measurement.
-  `tests/opaque-payload-test.js` generates every payload up to three characters
-  over each construct's own delimiter alphabet - about ten thousand documents -
-  and it is what finds this class: of 1325 corpus documents exactly ONE exposed
-  the fenced-code leak in #309, and a comment leaking only when it spans a line
-  break is invisible to a single-line sample (#320).
-
-#### A red row is a question, not a defect
-
-Three surfaces have now been worked row by row, and the ratio is stable enough
-to plan against rather than be surprised by:
-
-| pass | rows | the instrument | genuinely absent |
-| --- | --- | --- | --- |
-| `tree-sitter-carve` (#245) | 14 | 9 | 3 |
-| `vim-carve` + `sublime-carve` (#318) | 20 | 11 | 6 |
-| `textmate`, `prism`, `tiptap`, `vscode-carve` (#307, #308, #310) | 47 | 31 | 9 |
-
-**Two rows in three are a name the probe cannot reach**, and the third pass also
-turned up six rows that read `IMPLEMENTED` and were not. So the first job on a
-per-surface ticket is deciding which rows are real, and the answer is expected
-to be "most of them are not". A GAP row means *the probe did not find a rule it
-recognizes*, which is a different claim from *this surface does not implement
-the construct*.
-
-A fold belongs in `SIGNATURE_OVERRIDES`, which the file calls a per-surface
-NAMING table - never in a rule renamed on a surface to satisfy the probe. Where
-a surface genuinely cannot express a construct, `UNSUPPORTED` **with a reason**
-is the entry; a wrong rule is worse than a missing one.
-
-#### The instrument can be wrong in the direction that looks green
-
-Five ways the probe has mis-read a surface, each found by opening the file:
-
-1. **It read too little.** `Object.keys(grammar.json.rules)` is 196 of
-   tree-sitter's 346 names; a `.sublime-syntax` scopes a capture as well as a
-   match (#315).
-2. **The signature list had holes** - `code_span` is `verbatim` on one surface
-   and `code_inline` on another (#315, #307).
-3. **One rule implements several constructs**, and one name cannot carry four
-   through a shared table (#318).
-4. **The evidence named a rule about a different construct.** `carveCommentInline`
-   is the braced comment and was cited for the trailing one (#318). The same
-   pair beat the word-boundary rank on the TextMate family, where both
-   candidates are whole-name hits and *length* picked the wrong one (#307).
-5. **The re-check read the file's prose as evidence.** `every IMPLEMENTED row
-   cites a name the shipped grammar really carries` asked whether the evidence
-   was a SUBSTRING of the source. `prism/carve.js` carries the comment "Prism
-   has no cross-reference token at all" beside the lookbehind that worked
-   around the absence - so a row citing `cross-ref` re-checked **green** for as
-   long as the rule was missing (#307). That is the trap the docblock at the
-   top of `scripts/surface-probe.mjs` describes, and that its extractors were
-   built to avoid, surviving in the check that verifies their output. It reads
-   `vocabulary()` now, so the seed and the re-check agree on what a name is.
-
-The lesson generalizes past this file: **a check that treats a file's prose as
-evidence that the file implements what the prose says it does NOT implement
-cannot fail.** Match against what a grammar DECLARES, never against its text.
-
-Re-measure after changing a grammar:
-
-```bash
-node scripts/seed-construct-ledger.mjs
-```
-
-That reads the four surfaces here directly. The six in other repositories are
-read from checkouts named by environment variables, and any that is not given
-keeps the row already recorded, with the commit it was read at:
-
-```bash
-CARVE_SURFACE_VIM_CARVE=../vim-carve \
-CARVE_SURFACE_EMACS_CARVE=../emacs-carve \
-  node scripts/seed-construct-ledger.mjs
-```
-
-Statuses are measured; reasons, per-construct notes, tickets and a surface's
-`note` are written by hand and carried across a re-measurement, so a re-run
-never drops a stated reason. A surface-level `note` is for what the rows cannot
-say - why a surface needed no work to reach zero, or what its measured payload
-column does NOT cover.
-
-One thing a re-run does NOT carry: the payload axis of a surface the seeder
-cannot tokenize. It is only carried over when the recorded value is already
-`inert` or `leaks`, so a construct that moves from `GAP` to `IMPLEMENTED` in the
-same run arrives with `payload: "unmeasured"` and a ticket, even when the person
-doing the run has just measured it. That is deliberate: a seeder cannot tokenize
-a Vim syntax file or an emacs font-lock table, so the alternative is inventing an
-answer. Measure the payload as part of the same pass and write `inert` (or
-`leaks`, with a note) by hand on those rows.
-
-It applies to fewer surfaces than it used to. `vscode-carve` and
-`intellij-carve` are TextMate grammars, and the seeder loads any of those through
-Shiki, so naming their checkout measures the recognition axis and the payload
-sample in the same run:
-
-```bash
-CARVE_SURFACE_VSCODE_CARVE=../vscode-carve node scripts/seed-construct-ledger.mjs
-CARVE_SURFACE_INTELLIJ_CARVE=../intellij-carve node scripts/seed-construct-ledger.mjs
-```
-
-**A `leaks` cell is still hand-written on those surfaces, and the seeder carries
-it rather than overwriting it.** The seeder tokenizes ONE sample per construct
-and the sweep below generates hundreds, and on all three surfaces measured for
-the first time since #320 the sample said every row was inert while the sweep
-disagreed - five rows on intellij-carve alone (#329). So a run whose sample says
-`inert` leaves a recorded `leaks` alone. That cannot hide a fix: the sweep
-asserts every recorded leak STILL leaks, so a fix fails that file, its entry
-comes out, and the ledger's own orphan check then fails until the cell is
-corrected too.
-
-### The payload sweep reaches nine of the ten surfaces
-
-`tests/opaque-payload-test.js` is the second axis measured over a GENERATED space
-rather than one sample per construct, and one sample is not enough. Every surface
-measured for the first time so far has had leaks the sample could not see:
-
-| surface | leaking rows | the sample found |
-| --- | --- | --- |
-| tree-sitter-carve (#328) | 3 | none of them |
-| emacs-carve (#328) | 2 | the `%%%` fence, not the verbatim run |
-| intellij-carve (#329) | 4 | none of them |
-
-Name a checkout and the sweep drives it:
-
-```bash
-CARVE_SURFACE_TREE_SITTER_CARVE=../tree-sitter-carve \
-CARVE_SURFACE_EMACS_CARVE=../emacs-carve \
-CARVE_SURFACE_VSCODE_CARVE=../vscode-carve \
-CARVE_SURFACE_INTELLIJ_CARVE=../intellij-carve \
-  node tests/opaque-payload-test.js
-```
+## Development
 
-tree-sitter needs its native addon built (`npm install` in that checkout), and
-emacs-carve needs an `emacs` on PATH - the mode is fontified in one batch Emacs
-per sweep row, which is what `prime` on that tokenizer is for. A surface whose
-checkout is not named, or not built, is simply not swept.
-
-A leak on a grammar in ANOTHER repository is a defect this suite can measure and
-not fix, so it is recorded in `KNOWN_LEAKS` with the ticket it lives on and
-asserted to STILL leak. A fix therefore fails this file and the entry comes out
-with the fix, the same arrangement the residual table at the end of it uses for
-one document at a time. A surface in THIS repository is deliberately absent from
-that table: a leak here is fixable here, so it stays red.
+Contributor setup, testing, and maintenance notes are in the [development guide](docs/development.md).

package/diff/carve-diff.css

@@ -0,0 +1,47 @@
+/* Companion CSS for carve-grammars/diff (the highlighter-agnostic helper).
+ *
+ * Frames the `{.diff}` presentation for output from renderLanguageDiff() /
+ * applyLanguageDiff() - a `<pre class="diff has-diff">` whose lines are
+ * `<span class="line diff add|remove">` prefixed with a `.diff-marker`. Keyed on
+ * `.has-diff` rather than a highlighter class, so it works with highlight.js,
+ * Prism, or no highlighter. The Shiki path has its own `../shiki/carve.css`.
+ *
+ * Hosts may override the variables without depending on a site framework; a
+ * VS Code / JetBrains webview points them at the editor's own diff theme. */
+pre.has-diff {
+  --carve-diff-add-background: rgb(46 160 67 / 15%);
+  --carve-diff-add-marker: #1a7f37;
+  --carve-diff-remove-background: rgb(248 81 73 / 15%);
+  --carve-diff-remove-marker: #cf222e;
+}
+
+pre.has-diff code {
+  display: block;
+}
+
+pre.has-diff .line {
+  display: inline-block;
+  width: 100%;
+}
+
+pre.has-diff .line.diff.add {
+  background: var(--carve-diff-add-background);
+}
+
+pre.has-diff .line.diff.remove {
+  background: var(--carve-diff-remove-background);
+}
+
+pre.has-diff .diff-marker {
+  display: inline-block;
+  width: 1ch;
+  font-weight: 700;
+}
+
+pre.has-diff .line.diff.add .diff-marker {
+  color: var(--carve-diff-add-marker);
+}
+
+pre.has-diff .line.diff.remove .diff-marker {
+  color: var(--carve-diff-remove-marker);
+}

package/diff/index.d.ts

@@ -0,0 +1,14 @@
+/** Turn a marker-stripped diff line into HTML (language highlighting or escaping). */
+export type HighlightLine = (body: string) => string
+
+/**
+ * Render a Carve `{.diff}` language fence to an HTML string of per-line spans,
+ * using any highlighter (or none). See the module JSDoc for the contract.
+ */
+export function renderLanguageDiff(code: string, highlightLine?: HighlightLine): string
+
+/**
+ * Apply the diff presentation to a rendered `<pre class="diff"><code>` in the
+ * DOM: replace the code's content with per-line diff spans and mark the `<pre>`.
+ */
+export function applyLanguageDiff(codeElement: Element, highlightLine?: HighlightLine): void

package/diff/index.js

@@ -0,0 +1,58 @@
+/**
+ * Present a Carve `{.diff}` language fence with any highlighter (or none).
+ *
+ * Carve core emits `{.diff}` on a language-tagged fence as
+ * `<pre class="diff"><code class="language-x">…</code></pre>` with the leading
+ * `+`, `-`, and context-space characters left as plain text - applying the
+ * presentation is the host's job. The Shiki hosts use `../shiki/diff.js`; this
+ * module covers hosts on highlight.js, Prism, or no highlighter, where the
+ * per-line token model Shiki provides is not available.
+ *
+ * The caller supplies a per-line highlighter. The marker is stripped before it
+ * runs (so `- old()` tokenizes as `old()`), then restored as a `diff-marker`
+ * span, and added/removed lines get `diff add` / `diff remove` classes - the
+ * same shape the Shiki transformer produces. Pair with
+ * `@markup-carve/carve-grammars/diff/carve-diff.css`.
+ *
+ * No Node imports: safe to bundle into a browser client or a webview.
+ */
+
+const MARKER = /^[+\- ]/;
+
+const escapeHtml = (value) =>
+  value.replace(/[&<>]/g, (character) => (character === '&' ? '&amp;' : character === '<' ? '&lt;' : '&gt;'));
+
+/**
+ * Render diff code to an HTML string of per-line spans.
+ *
+ * @param {string} code The code text, with each line's leading marker intact.
+ * @param {(body: string) => string} [highlightLine] Turns a marker-stripped line
+ *   into HTML. Defaults to HTML-escaping (no language highlighting).
+ * @returns {string} The `<span class="line …">…</span>` lines, newline-joined.
+ */
+export function renderLanguageDiff(code, highlightLine = escapeHtml) {
+  return code
+    .replace(/\n$/, '')
+    .split('\n')
+    .map((line) => {
+      const marker = MARKER.test(line) ? line[0] : '';
+      const body = marker ? line.slice(1) : line;
+      const lineClass = marker === '+' ? 'line diff add' : marker === '-' ? 'line diff remove' : 'line';
+      const markerSpan = marker ? `<span class="diff-marker">${escapeHtml(marker)}</span>` : '';
+      return `<span class="${lineClass}">${markerSpan}${highlightLine(body)}</span>`;
+    })
+    .join('\n');
+}
+
+/**
+ * Apply the diff presentation to a rendered `<pre class="diff"><code>` in the
+ * DOM: replace the code's content with per-line diff spans and mark the `<pre>`.
+ *
+ * @param {Element} codeElement The `<code>` inside a `<pre class="diff">`.
+ * @param {(body: string) => string} [highlightLine] See {@link renderLanguageDiff}.
+ */
+export function applyLanguageDiff(codeElement, highlightLine) {
+  const pre = codeElement.parentElement;
+  codeElement.innerHTML = renderLanguageDiff(codeElement.textContent || '', highlightLine);
+  if (pre) pre.classList.add('has-diff');
+}