@markup-carve/carve-grammars 0.1.3 → 0.1.4

package/README.md

@@ -167,6 +167,30 @@ of figures, advanced tables, comments, raw passthrough, and source-layout edge
 cases. `tiptap/schema-map.json` is the public rich-mapping authority;
 `tests/lib/coverage.js` records why structured conversion falls back.
 
+## Framework-independent editor element
+
+Applications that do not otherwise use Tiptap can mount the same lossless
+bridge through a Web Component:
+
+```js
+import { defineCarveEditor } from '@markup-carve/carve-grammars/editor'
+
+defineCarveEditor()
+const editor = document.querySelector('carve-editor')
+editor.value = '# Hello'
+editor.addEventListener('input', event => save(event.detail.value))
+```
+
+```html
+<carve-editor></carve-editor>
+```
+
+The element exposes a string `value`, emits bubbling and composed `input`
+events, and uses `unsupported: 'preserve'` internally. Its editable surface is
+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`.
+
 ## Syntax highlighting
 
 Render Carve source as highlighted HTML on the web. Both grammars cover the full
@@ -452,6 +476,13 @@ the `CarveKit` schema with the declared node/mark kind, and every type in the
 pinned spec vocabulary must have a decision. Types the map covers ahead of the
 `spec/` pin are declared explicitly and must be removed once the pin catches up.
 
+Two sections are keyed by ProseMirror name rather than by Carve type, because
+neither names a Carve construct: `preservationNodes` (`carveUnsupported` and
+`carveUnsupportedInline`, the atoms holding a construct's exact source) and
+`markCarrierNodes` (`carveEmptyMark`, the atom a mark with no content rides on).
+Both are part of the wire - an unknown ProseMirror name is an error rather than a
+skip - so a bridge has to read them alongside `types`.
+
 Restating this mapping per engine is what the spec's own node-vocabulary test was
 written to prevent: carve-php once emitted `citation-group` while every other
 implementation spelled it with underscores.
@@ -463,6 +494,21 @@ implementation spelled it with underscores.
   `[text]{#me .note}`, `![alt](src){.wide}`. Inline attrs trail their target;
   block attrs (headings) sit on the **preceding** line (strict djot), e.g.
   `{#slug}` then `# Title`.
+- **Attribute order** - a run is written back in the order it was AUTHORED, not
+  in a canonical one. ProseMirror attributes are an unordered map, so the order
+  travels as its own attribute, `carveAttrOrder`: the AST's `order` field
+  verbatim, an array whose entries are `#id`, `.class` and each key by name.
+
+  ```js
+  carveToProseMirror('[x]{key=c .a #b}')
+  // the carveSpan mark carries: { id: 'b', class: 'a',
+  //   carveKeyValues: { key: 'c' }, carveAttrOrder: ['key', '.class', '#id'] }
+  ```
+
+  All of a node's classes stay contiguous at the position of the first one,
+  which is what the AST records. A document with no `carveAttrOrder` - anything
+  an editor builds from scratch - writes the canonical `#id .class key="val"`
+  order, and a slot the order names but the document no longer has is skipped.
 - **Math** - `CarveMath` (inline atom) serializes to `` $`x` `` and, with
   `display: true`, `` $$`x` ``. Math has no closing `$` sentinel (grammar.ebnf
   PART 9 §18): the `$` / `$$` prefix opens a verbatim span and the backtick run

package/highlightjs/carve.js

@@ -101,7 +101,39 @@
     // attribute block, and one invalid name is enough to leave the whole run
     // literal. A colon belongs to the VALUE grammar, not the key: an unquoted
     // value may contain dots and colons, so `{k=a:b}` is a real attribute block.
-    const ATTR_ITEM = /(?:[.#][A-Za-z_][\w-]*|[A-Za-z_][\w-]*(?:=(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|[^\s"'{}]+))?)/.source;
+    const ATTR_ITEM = /(?::(?:[A-Za-z0-9]{1,8}(?:-[A-Za-z0-9]{1,8})*)?|[.#][A-Za-z_][\w-]*|[A-Za-z_][\w-]*(?:=(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|[^\s"'{}]+))?)/.source;
+    // A LIST MARKER MAY BE GLUED TO AN ATTRIBUTE BLOCK (`-{#x} item`), so the
+    // marker rules have to look past a whole block to decide there is a marker
+    // at all. That lookahead spelled the item alternation out again, and the
+    // copies went stale: when the language attribute (`{:fr}`) joined
+    // `ATTR_ITEM`, `-{:fr} item` stopped colouring its `-` as a bullet while
+    // `-{.c} item` still did. Built from `ATTR_ITEM` now, so one spelling of
+    // what an attribute item is serves the attribute rule and both marker
+    // rules, and they cannot drift apart again.
+    const GLUED_ATTR_BLOCK =
+        '(?=\\{\\s*(?:' + ATTR_ITEM + '(?:\\s+' + ATTR_ITEM + ')*\\s*)?\\}[ \\t]+[^ \\t\\n])';
+    // BALANCED BRACKET TEXT - the body of a link label, an image alt text and a
+    // bracketed span. See the long note on Prism's `bracketText`, which this
+    // mirrors; the short version is that the spec closes a label at the
+    // MATCHING `]` and the scan is escape-aware, while a `[^\]]*` body closes
+    // at the FIRST `]`. That left `![t[z]](/i.png)` - an image - entirely
+    // unscoped, and scoped the unbalanced `[t[z](/u)` from the outer `[` where
+    // the engine reads `[t` as prose (carve-grammars#226).
+    //
+    // The nesting is unrolled to FOUR levels because a regex cannot count;
+    // deeper stays unscoped, which is what every depth did before.
+    //
+    // Every quantifier here is BOUNDED, for the reason Prism's copy gives: an
+    // unbounded body is a scan to the end of the document at every `[` the
+    // tokenizer tries, and it tries each position.
+    const BRACKET_CHAR = /(?:[^\[\]\\]|\\[\s\S])/.source;
+    const BRACKET_SCAN = '{0,512}';
+    let BRACKET_TEXT = BRACKET_CHAR + BRACKET_SCAN;
+    for (let depth = 0; depth < 3; depth++) {
+        BRACKET_TEXT = '(?:' + BRACKET_CHAR + '|\\[' + BRACKET_TEXT + '\\])' + BRACKET_SCAN;
+    }
+    // The same body, required to be non-empty, for the rules that reject `[]`.
+    const BRACKET_TEXT_NONEMPTY = '(?!\\])' + BRACKET_TEXT;
     /**
      * A begin/end mode opens its span the moment `begin` matches, whether or
      * not the closer ever arrives - so an unpartnered delimiter colors every
@@ -153,6 +185,20 @@
         relevance: 5,
     };
 
+    // Front matter is valid only at byte offset zero. Unlike the historical
+    // `^---$` rule, the negative lookbehind below cannot match a thematic break
+    // on a later line even though highlight.js compiles modes with `m`.
+    const FRONT_MATTER = {
+        className: 'meta',
+        begin: /^(?<![\s\S])\uFEFF?---(?:[A-Za-z0-9_-]+| [A-Za-z0-9_-]+)?[ \t]*$/,
+        end: /^---[ \t]*$/,
+        relevance: 10,
+        contains: [
+            { className: 'symbol', begin: /^[A-Za-z_][\w-]*(?=[ \t]*:)/ },
+            { className: 'punctuation', begin: /---/ },
+        ],
+    };
+
     // Headings: # to ######
     const HEADING = {
         className: 'section',
@@ -291,14 +337,14 @@
     // Inline links: [text](url) with optional trailing attributes
     const LINK = {
         className: 'link',
-        begin: /\[[^\]]*\]\([^)]*\)(\{[^}]+\})?/,
+        begin: new RegExp('\\[' + BRACKET_TEXT + '\\]\\([^)]*\\)(\\{[^}]+\\})?'),
         relevance: 5,
     };
 
     // Autolinks: <https://...> or <mailto:...>
     const AUTOLINK = {
         className: 'link',
-        begin: /<(?:https?:\/\/|mailto:)[^>]+>/,
+        begin: /<(?:https?:\/\/|mailto:)[^>]{1,2048}>/,
         relevance: 5,
     };
 
@@ -312,14 +358,14 @@
     // Images: ![alt](url) with optional trailing attributes
     const IMAGE = {
         className: 'link',
-        begin: /!\[[^\]]*\]\([^)]*\)(\{[^}]+\})?/,
+        begin: new RegExp('!\\[' + BRACKET_TEXT + '\\]\\([^)]*\\)(\\{[^}]+\\})?'),
         relevance: 5,
     };
 
     // Reference links: [text][ref] with optional trailing attributes
     const REFERENCE_LINK = {
         className: 'link',
-        begin: /\[[^\]]+\]\[[^\]]*\](\{[^}]+\})?/,
+        begin: new RegExp('\\[' + BRACKET_TEXT_NONEMPTY + '\\]\\[[^\\]]*\\](\\{[^}]+\\})?'),
         relevance: 5,
     };
 
@@ -328,7 +374,7 @@
         className: 'string',
         // Only the bracket run; the trailing `{...}` is left to ATTRIBUTE so it
         // scopes as an attribute block rather than vanishing into the span.
-        begin: /\[[^\]]+\](?=\{)/,
+        begin: new RegExp('\\[' + BRACKET_TEXT_NONEMPTY + '\\](?=\\{)'),
         relevance: 5,
     };
 
@@ -343,7 +389,7 @@
     // Footnote references: [^note]
     const FOOTNOTE_REF = {
         className: 'symbol',
-        begin: /\[\^[^\]]+\]/,
+        begin: /\[\^[^\]]{1,512}\]/,
         relevance: 5,
     };
 
@@ -351,7 +397,7 @@
     // leads, which is what separates it from the reference above.
     const INLINE_FOOTNOTE = {
         className: 'symbol',
-        begin: /\^\[[^\]\n]*\]/,
+        begin: /\^\[[^\]\n]{0,512}\]/,
         relevance: 5,
     };
 
@@ -404,7 +450,7 @@
     // first to claim those suffixed forms).
     const CITATION = {
         className: 'symbol',
-        begin: /\[\+?(?:[^\]@]*@[A-Za-z0-9_][A-Za-z0-9_.:#$%&+?<>~\/-]*[^\]]*)\](?!\(|\[|\{)/,
+        begin: /\[\+?(?:[^\]@]{0,512}@[A-Za-z0-9_][A-Za-z0-9_.:#$%&+?<>~\/-]*[^\]]{0,512})\](?!\(|\[|\{)/,
         relevance: 8,
     };
 
@@ -439,6 +485,93 @@
         relevance: 10,
     };
 
+    // A list item's MARKER, as it may appear before a block opener on the same
+    // line. Matched in a LOOKBEHIND everywhere it is used rather than consumed,
+    // so `TASK_LIST`/`LIST_BULLET`/`LIST_NUMBER` still scope it - which is
+    // tree-sitter-carve's split too, with the block INSIDE `list_item_content`
+    // beside the `list_marker_*` rather than over it.
+    //
+    // Used by the marker-line comment fence AND by the quote rules below: a
+    // quote may open on an item's own marker line (`- > x`), where carve-js
+    // nests the quote and everything after the marker inside the item.
+    // EVERY SEPARATOR IS A LITERAL SPACE, never a tab: `-<TAB>a`, `1.<TAB>a` and
+    // `- [x]<TAB>a` are paragraphs in the engine, which the shared block battery
+    // already pins per marker. Written `[ \t]+` this admitted `-<TAB>%%%` as a
+    // marker-line fence, and with the quote rules sharing the prefix it coloured
+    // `-<TAB>> q` as a quote on a line the language renders as prose
+    // (carve-grammars#259).
+    const LIST_MARKER_BEFORE_BLOCK =
+        '^(?:(?<![\\s\\S])\\uFEFF)?[ \\t]*'
+        + '(?:(?:[-*] +)*[-*] +(?:\\[[ xX\\-_>?]\\] +)?'
+        + '|(?:[0-9]+|[A-Za-z]|[ivxlcdm]+|[IVXLCDM]+)[.)] +|\\. +)';
+
+    // A comment fence may open on a BLOCK-QUOTE marker line (`> %%%`), and then
+    // its body is hidden exactly as it is anywhere else - \u00A724 S2 and \u00A728 make a
+    // comment's body verbatim and invisible WHEREVER the fence sits. Corpus 70
+    // pins this spelling: `> q` / `> %%%` / `> x` / `> %%%` / `> body` renders
+    // the quote with `q` and `body` only.
+    //
+    // `BLOCK_COMMENT` cannot reach it - its begin allows only whitespace before
+    // the run - so all three lines scoped as plain quote and nothing was marked
+    // hidden. It lives in BLOCKQUOTE's `contains` rather than in the top-level
+    // list because BLOCKQUOTE ends at `$`: a mode that begins at column 0 would
+    // out-rank it and take the marker, and a mode outside it never gets to run
+    // on a quote line at all. Reached from here the marker stays a quote, which
+    // is tree-sitter-carve's split too - the `fenced_comment_block` sits inside
+    // the quote's `content`, beside the `block_quote_marker`.
+    // The marker run may itself follow a LIST ITEM'S marker (`- > %%%`), so the
+    // list prefix is an alternative to the plain line start rather than a rule of
+    // its own. carve-grammars#246 left that shape out because two of the three
+    // grammars here could not reach it; a lookbehind reaches it here.
+    const QUOTE_MARKER_BEFORE_FENCE =
+        '(?:' + LIST_MARKER_BEFORE_BLOCK + '|^(?:(?<![\\s\\S])\\uFEFF)?[ \\t]*)(?:> )+';
+    // A line carrying a quote marker of its own. Every line from opener to
+    // closer must be one: an UNMARKED line is where the quote can end, and the
+    // engine degrades an unclosed opener to a line comment rather than hiding
+    // anything (`> %%%` / `> c` / blank leaves `c` VISIBLE). The engine does
+    // absorb an unmarked LAZY continuation into a fence that closes later;
+    // refusing it costs a mis-scope there and buys never hiding a visible block.
+    const QUOTE_MARKED_LINE = '(?:\\n[ \\t]*>[^\\n]*)';
+    const BLOCK_COMMENT_ON_QUOTE_MARKER_LINE = {
+        className: 'comment',
+        // The closer is REQUIRED up front, as in BLOCK_COMMENT_ON_MARKER_LINE
+        // below: highlight.js has no begin->end backreference, so without the
+        // guard an opener with no closer runs to end of file, and on this shape
+        // an unclosed opener is the common case.
+        begin: RegExp(
+            '(?<=' + QUOTE_MARKER_BEFORE_FENCE + ')(%{3,})(?!%)[^\\n]*$'
+            + '(?=' + QUOTE_MARKED_LINE + '*?\\n[ \\t]*(?:> )+\\1(?!%)[^\\n]*$)',
+        ),
+        'on:begin': (m, resp) => {
+            resp.data._quoteFenceWidth = m[1].length;
+        },
+        end: /^[ \t]*(?:> )+(%{3,})[^\n]*$/,
+        'on:end': (m, resp) => {
+            if (m[1].length !== resp.data._quoteFenceWidth) resp.ignoreMatch();
+        },
+        relevance: 10,
+    };
+
+    // The other half of the rule above: an UNTERMINATED `%{3,}` run opens
+    // nothing and degrades to a LINE comment (PART 9 S28), so it must still
+    // scope as one. Placed after `BLOCK_COMMENT` in `contains`, which consumes
+    // every fence that does have a closer - the same pair Prism carries, where
+    // the unterminated pattern sits after the block form for the same reason.
+    //
+    // The marker prefixes are here as well, so `- %%%` and `> %%%` with no
+    // closer grey their opener out too rather than losing the run entirely.
+    // Reached inside a quote through `BLOCKQUOTE.contains`, since a mode that
+    // begins at column 0 never runs on a quote line.
+    const UNTERMINATED_BLOCK_COMMENT = {
+        className: 'comment',
+        begin: RegExp(
+            '(?:^(?:(?<![\\s\\S])\\uFEFF)?[ \\t]*'
+            + '|(?<=' + LIST_MARKER_BEFORE_BLOCK + ')'
+            + '|(?<=' + QUOTE_MARKER_BEFORE_FENCE + '))%{3,}',
+        ),
+        end: /$/,
+        relevance: 5,
+    };
     // Blockquotes: a `>` marker followed by a SPACE, or alone on its line.
     //
     // Verified against carve-rs: `>no space`, `>>x`, `>> x` and `>\tx` are all
@@ -449,8 +582,24 @@
         className: 'quote',
         // Anchored `^[ \t]*` on purpose - no container model here, see the
         // indented-block-openers note in the module docblock (carve-grammars#138).
-        begin: /^(?:(?<![\s\S])\uFEFF)?[ \t]*>(?= |$)/,
+        // A LIST ITEM'S MARKER may stand before the `>` on the same line
+        // (`- > x`, `1. > x`, `- - > x`, `- [ ] > x`). Reached through a
+        // lookbehind so the marker is not consumed and the list rules still
+        // scope it. Without this branch the marker scoped as a bullet and the
+        // rest of the line carried no scope at all, where carve-js nests it
+        // (carve-grammars#259).
+        begin: RegExp(
+            '(?:^(?:(?<![\\s\\S])\\uFEFF)?[ \\t]*|(?<=' + LIST_MARKER_BEFORE_BLOCK + '))'
+            + '>(?= |$)',
+        ),
         end: /$/,
+        // The ONE construct a quote line contains: a comment fence opened on
+        // the marker line, which outlives the `$` that ends every other quote.
+        // The two constructs a quote line contains: a comment fence opened on
+        // the marker line, which outlives the `$` that ends every other quote,
+        // and the unterminated form of the same run, which does not (it is a
+        // line comment, so it ends where the quote line does).
+        contains: [BLOCK_COMMENT_ON_QUOTE_MARKER_LINE, UNTERMINATED_BLOCK_COMMENT],
         relevance: 0,
     };
 
@@ -469,7 +618,9 @@
     const LIST_BULLET = {
         className: 'bullet',
         // A marker line may carry several markers (`- - A`, corpus 103).
-        begin: /^(?:(?<![\s\S])\uFEFF)?[ \t]*(?:[-*] +)*[-*](?:(?= )|(?=\{\s*(?:(?:[.#][A-Za-z_][\w-]*|[A-Za-z_][\w-]*(?:=(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|[^\s"'{}]+))?)(?:\s+(?:[.#][A-Za-z_][\w-]*|[A-Za-z_][\w-]*(?:=(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|[^\s"'{}]+))?))*\s*)?\}[ \t]+[^ \t\n]))(?![ \t]*$)/,
+        begin: RegExp(
+            '^(?:(?<![\\s\\S])\\uFEFF)?[ \\t]*(?:[-*] +)*[-*](?:(?= )|' + GLUED_ATTR_BLOCK + ')(?![ \\t]*$)',
+        ),
         relevance: 0,
     };
 
@@ -485,7 +636,9 @@
     // stops in the wrong place and `{title="a}b"} x` is a valid item (#85).
     const LIST_NUMBER = {
         className: 'bullet',
-        begin: /^(?:(?<![\s\S])\uFEFF)?[ \t]*(\d+[.)]|[a-zA-Z][.)]|[ivxlcdm]+[.)]|[IVXLCDM]+[.)]|\.)(?:(?= )|(?=\{\s*(?:(?:[.#][A-Za-z_][\w-]*|[A-Za-z_][\w-]*(?:=(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|[^\s"'{}]+))?)(?:\s+(?:[.#][A-Za-z_][\w-]*|[A-Za-z_][\w-]*(?:=(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|[^\s"'{}]+))?))*\s*)?\}[ \t]+[^ \t\n]))(?![ \t]*$)/,
+        begin: RegExp(
+            '^(?:(?<![\\s\\S])\\uFEFF)?[ \\t]*(\\d+[.)]|[a-zA-Z][.)]|[ivxlcdm]+[.)]|[IVXLCDM]+[.)]|\\.)(?:(?= )|' + GLUED_ATTR_BLOCK + ')(?![ \\t]*$)',
+        ),
         relevance: 0,
     };
 
@@ -584,9 +737,101 @@
         relevance: 10,
     };
 
+    // Composite figure block: a BARE `::: figure` opener through its matching
+    // closer (PART 9 §4c, markup-carve/carve#1215).
+    //
+    // The kind word `figure` is RESERVED among the `:::` types: a bare opener -
+    // the fence, its separator, the word `figure`, and NOTHING else - is ONE
+    // figure of ordered panels, not an admonition. It carries `section` rather
+    // than DIV_BLOCK's `keyword` so a consumer can tell the two readings apart,
+    // and it is listed BEFORE DIV_BLOCK, whose begin also matches this line -
+    // highlight.js takes the earliest match and breaks a tie by mode order.
+    //
+    // The `[ \t]*$` tail is the whole distinction. An opener carrying a quoted
+    // title or a [label] (`::: figure "T"`, `::: figure [g]`) does not match
+    // here at all and falls to DIV_BLOCK, which is the generic Tier-2 container
+    // the clause says it stays.
+    //
+    // The separator is a SPACE run, never a tab (grammar.ebnf PART 7, MARKER
+    // SEPARATORS; corpus 254 renders `:::<TAB>note` as a paragraph). A
+    // tab-separated opener is not claimed here and falls to DIV_BLOCK, which
+    // over-colours it exactly as it does today - a pre-existing trade this mode
+    // neither widens nor fixes. Trailing whitespace after the kind word is
+    // insignificant and may be a tab.
+    //
+    // Closer width is carried in `resp.data` and compared on `on:end`, the same
+    // idiom DIV_BLOCK and BLOCK_COMMENT already use, so the closer matches the
+    // opener's colon run EXACTLY. `contains` is assigned below, once the full
+    // mode list is known.
+    // A STACK, where the modes above keep a single width. highlight.js hands
+    // every instance of a mode the SAME `resp.data` object, so one slot holds
+    // only the innermost fence: with `::: figure` > `:::: note` > `::::: x`,
+    // the width-5 opener overwrote the width-4 one, both outer closers then
+    // failed their check, and the group ran to end of input unscoped. These two
+    // modes nest inside each other by construction, so they push and pop
+    // instead. `container` names which stack, because the two modes are
+    // separate objects and each needs its own.
+    const pushFence = (container) => (m, resp) => {
+        (resp.data[container] ??= []).push(m[1].length);
+    };
+    const popFence = (container) => (m, resp) => {
+        const open = resp.data[container];
+        if (!open?.length || m[1].length !== open[open.length - 1]) {
+            resp.ignoreMatch();
+            return;
+        }
+        open.pop();
+    };
+
+    const FIGURE_GROUP_BLOCK = {
+        beginScope: 'section',
+        begin: /^(?:(?<![\s\S])\uFEFF)?[ \t]*(:{3,}) +figure[ \t]*$/,
+        'on:begin': pushFence('_groupFences'),
+        endScope: 'section',
+        end: /^[ \t]*(:{3,})[ \t]*$/,
+        'on:end': popFence('_groupFences'),
+        relevance: 10,
+    };
+
+    // The generic container reached only from INSIDE a composite figure group.
+    // Its `contains` differs from DIV_BLOCK's (assigned below), so a bare
+    // `::: figure` at any depth inside an open group reads as the generic
+    // container PART 9 §4c degrades it to (GROUPS DO NOT NEST; corpus
+    // 318-composite-figures-9). The scope stays `keyword` - it IS a div, and a
+    // consumer selecting that must keep seeing it.
+    //
+    // Its `begin` also differs, in the one way that lets a group close at all.
+    // highlight.js tries a mode's CONTAINS before its own `end`, so DIV_BLOCK's
+    // optional tail - which makes a bare `:::` line a typeless div opener -
+    // matched the group's own closing fence and opened a phantom container
+    // instead of closing the group. Measured before this line existed: a second
+    // `::: figure` later in the same document scoped `keyword`, because the
+    // whole rest of the file was still inside that phantom.
+    //
+    // Requiring the tail here is not a narrowing of what Carve accepts, it is
+    // the colon-fence depth rule (PART 9 §12) written where highlight.js can
+    // act on it: a `:::` line inside a `:::` container CLOSES it, and a
+    // container nested inside one has to open with a LONGER run. So a bare
+    // fence line inside a group is a closer, and reaching `end` is the correct
+    // reading of it. A longer bare run (`::::` inside a `:::` group) fails the
+    // width check in `on:end` and is left unscoped, which is the one case this
+    // trades away.
+    const DIV_BLOCK_IN_GROUP = {
+        ...DIV_BLOCK,
+        begin: /^(?:(?<![\s\S])\uFEFF)?[ \t]*(:{3,})(?:[ \t]*(?:\||\\)|[ \t]*[a-zA-Z_][\w-]*(?:[ \t]+"[^"\n]*")?(?:[ \t]+\[[^\]\n]*\])?|[ \t]*\[[^\]\n]*\])[ \t]*$/,
+        'on:begin': pushFence('_groupDivFences'),
+        'on:end': popFence('_groupDivFences'),
+    };
+
     // Carve comments: `%%` to end of line, a `%%%` fenced block, and the
-    // CriticMarkup comment `{# ... #}`. (An earlier rule here matched
-    // `{% ... %}`, which is Jinja/Liquid syntax and does not exist in Carve.)
+    // CriticMarkup comment `{# ... #}`.
+    //
+    const DELIMITED_COMMENT = {
+        className: 'comment',
+        begin: /\{%/,
+        end: /%\}/,
+        relevance: 5,
+    };
     const LINE_COMMENT = {
         className: 'comment',
         begin: /(?:^|(?<=\s))%%(?!%)/,
@@ -606,7 +851,36 @@
     // `ignoreMatch()` - the same idiom the bundled markdown grammar uses.
     const BLOCK_COMMENT = {
         className: 'comment',
-        begin: /^(?:(?<![\s\S])\uFEFF)?[ \t]*(%{3,})[^\n]*$/,
+        // THE CLOSER IS REQUIRED UP FRONT, as in both marker-line fences below,
+        // and for the reason they already give: highlight.js has no begin->end
+        // backreference, so an opener with no closer runs to END OF FILE. That
+        // is the worst failure a highlighter has - everything below one stray
+        // `%%%` is greyed out - and PART 9 S28 says the opposite happens: an
+        // UNTERMINATED run opens nothing, degrades to a line comment, and leaves
+        // the block below it visible (`%%%` / blank / `after` renders
+        // `<p>after</p>`). Measured at every indent, column 0 included, and the
+        // swallow reproduced at all of them (carve-grammars#260).
+        //
+        // The lookahead carries the width rule too: `\1(?!%)` matches the
+        // opener's run EXACTLY, so `%%%` offered a `%%%%` closer is still
+        // unterminated - which the engine renders with the body VISIBLE between
+        // two vanished runs, not hidden.
+        // THE FORWARD SCAN IS BOUNDED, and the bound is the whole reason this
+        // lookahead is affordable. Proving there is NO closer costs a scan to
+        // end of input, and a document can hold one unmatched run per fence
+        // WIDTH, so an adversarial file pays that scan many times over: 2000
+        // runs of increasing width (2 MB) took 2045 ms unbounded and 40 ms at
+        // 8000 characters, and the bounded form grows linearly where the
+        // unbounded one grows with the square. Prism carries the same unbounded
+        // scan and measured 14.2 s on the 8 MB case, so this is the rule's cost
+        // rather than this engine's (carve-grammars#260).
+        //
+        // A closer further than 8000 characters below its opener is therefore
+        // not found, and the fence degrades to a line comment. That is the SAFE
+        // direction and the one this whole rule is about: a run that opens
+        // nothing leaves the text below it VISIBLE, where the failure being
+        // fixed here hid it.
+        begin: /^(?:(?<![\s\S])\uFEFF)?[ \t]*(%{3,})(?!%)[^\n]*$(?=[\s\S]{0,8000}?\n[ \t]*\1(?!%)[^\n]*$)/,
         'on:begin': (m, resp) => {
             resp.data._fenceWidth = m[1].length;
         },
@@ -621,6 +895,48 @@
         },
         relevance: 10,
     };
+    // A fence may also open on a list item's MARKER LINE (`- %%%`), and then
+    // the body is hidden exactly as it is anywhere else - §24 S2 and §28 make a
+    // comment's body verbatim and invisible WHEREVER the fence sits (corpus
+    // 337). `BLOCK_COMMENT` above cannot reach that shape: its begin is
+    // line-anchored, so on `- %%%` it never fires, the scanner then takes the
+    // REAL closer on the next line for an opener, and the comment runs to end
+    // of file - swallowing every block after the item.
+    //
+    // The marker is matched in a LOOKBEHIND rather than consumed, so
+    // `TASK_LIST`/`LIST_BULLET`/`LIST_NUMBER` still scope it as a bullet (which
+    // is what tree-sitter-carve does too: a `fenced_comment_block` sits INSIDE
+    // `list_item_content`, beside a `list_marker_*`, not over it).
+    // `LIST_MARKER_BEFORE_BLOCK` is defined above BLOCKQUOTE, which needs the
+    // same prefix for `- > x`.
+    // A line that is blank, or indented by at least one column. A COLUMN-0 line
+    // is neither, and that is the point: it ends the container and with it the
+    // fence, so it must not be skipped over while looking for the closer
+    // (corpus 326-6 - `- %%%` / `c` / `%%%` leaves `c` and the trailing
+    // paragraph VISIBLE, with the unclosed opener degrading to a line comment).
+    const BLANK_OR_INDENTED_LINE = '(?:\\n(?![ \\t]*[^ \\t\\n])[^\\n]*|\\n[ \\t]+[^\\n]*)';
+    const BLOCK_COMMENT_ON_MARKER_LINE = {
+        className: 'comment',
+        // The closer is REQUIRED up front, unlike `BLOCK_COMMENT`. highlight.js
+        // has no begin->end backreference, so without this guard an opener with
+        // no closer would run to end of file - and on this shape an unclosed
+        // opener is the common case (a column-0 line ends the item), where the
+        // right answer is a one-line comment, not a swallowed document.
+        begin: RegExp(
+            '(?<=' + LIST_MARKER_BEFORE_BLOCK + ')(%{3,})(?!%)[^\\n]*$'
+            + '(?=' + BLANK_OR_INDENTED_LINE + '*?\\n[ \\t]+\\1(?!%)[^\\n]*$)',
+        ),
+        'on:begin': (m, resp) => {
+            resp.data._fenceWidth = m[1].length;
+        },
+        // `[ \t]+`, not `[ \t]*`: the closer sits at the item's content column,
+        // and a column-0 run is a different block entirely (see above).
+        end: /^[ \t]+(%{3,})[^\n]*$/,
+        'on:end': (m, resp) => {
+            if (m[1].length !== resp.data._fenceWidth) resp.ignoreMatch();
+        },
+        relevance: 10,
+    };
     const CRITIC_SUB = {
         className: 'meta',
         // The `~>` arrow is what distinguishes a substitution from a forced
@@ -633,7 +949,7 @@
         className: 'comment',
         // The closing `#}` is required, or this would swallow an attribute
         // block whose id comes first (`{#id .class}`).
-        begin: /\{#(?=[^}\n]*#\})/,
+        begin: /\{#(?=[^}\n]{0,4096}#\})/,
         end: /#\}/,
         relevance: 5,
     };
@@ -747,18 +1063,12 @@
     HEADING.contains = [HEADING_TAG];
 
     const CONTAINS = [
-        // NOTE: front matter is intentionally NOT highlighted. It is valid
-        // only at the very top of the document, but highlight.js has no
-        // document-start anchor, so a `^---$` begin would also match a bare
-        // `---` horizontal rule mid-document and swallow everything up to
-        // the next `---`. The horizontal-rule rule below handles `---`
-        // lines instead. (Prism anchors front matter via `^` with no `m`
-        // flag; see prism/carve.js.)
-
         // Block-level elements (order matters - more specific first)
+        FRONT_MATTER,
         HEADING,
         CODE_FENCE_START,
         CODE_FENCE_END,
+        FIGURE_GROUP_BLOCK,  // Must be before DIV_BLOCK (both match `::: figure`)
         DIV_BLOCK,
         HORIZONTAL_RULE,
         TABLE_SEPARATOR,
@@ -792,6 +1102,9 @@
         INSERT,            // {+text+}
         DELETE,            // {-text-}
         BLOCK_COMMENT,     // %%% fence - before LINE_COMMENT
+        BLOCK_COMMENT_ON_MARKER_LINE,  // `- %%%` - the marker is left to the list rules
+        UNTERMINATED_BLOCK_COMMENT,    // a `%%%` run with no closer - AFTER both fences
+        DELIMITED_COMMENT, // {% ... %}
         LINE_COMMENT,      // %% to end of line
         CRITIC_SUB,        // {~old~>new~} - before FORCED_STRIKE
         CRITIC_COMMENT,    // {# ... #} - must be before ATTRIBUTE
@@ -824,7 +1137,44 @@
     // so a nested div still scopes. highlight.js resolves the 'self' string
     // to this same mode natively, so this does not need the width-tracking
     // idiom above to also handle recursion.
-    DIV_BLOCK.contains = ['self', ...CONTAINS.filter((mode) => mode !== ABBREVIATION_DEF)];
+    // `'self'` sits LAST, not first. highlight.js takes the first mode in
+    // `contains` that matches at the earliest position, and DIV_BLOCK's own
+    // begin matches `::: figure` (its tail is optional), so a leading `'self'`
+    // out-ranked FIGURE_GROUP_BLOCK for every group nested inside a div - and
+    // because a div's closing fence opens a phantom `'self'` too, "inside a
+    // div" meant "anywhere after the first container in the document".
+    // Measured: `::: note` / `:::` / blank / `::: figure` scoped the group
+    // `keyword`. It is also redundant where it stands, since DIV_BLOCK is
+    // itself an entry in CONTAINS; it is kept, at the end, as the explicit
+    // statement that a div nests in a div.
+    DIV_BLOCK.contains = [...CONTAINS.filter((mode) => mode !== ABBREVIATION_DEF), 'self'];
+
+    // A composite figure's body is the div body MINUS FIGURE_GROUP_BLOCK (PART 9
+    // §4c: GROUPS DO NOT NEST - a bare `::: figure` inside an open group is a
+    // generic container at any depth, corpus 318-composite-figures-9). Dropping
+    // the mode is what makes the inner opener fall to the div mode, which is
+    // exactly the generic reading the clause asks for.
+    //
+    // The div reached from here is DIV_BLOCK_IN_GROUP rather than DIV_BLOCK, so
+    // the exclusion survives a level of nesting: DIV_BLOCK still offers
+    // FIGURE_GROUP_BLOCK (a bare opener inside a `::: note` IS a group - only a
+    // group suppresses one), and this variant does not, so
+    // `::: figure` > `::: note` > `::: figure` reads generic too. `'self'` would
+    // not do here: inside DIV_BLOCK_IN_GROUP it resolves to that same div, which
+    // is what is wanted, but the mode has to be a distinct object for its
+    // `contains` to differ from DIV_BLOCK's at all.
+    //
+    // RESIDUAL, written down rather than left to be rediscovered: a bare opener
+    // reached through a LIST ITEM or a BLOCKQUOTE inside a group is matched by
+    // the top-level modes again, so it over-colours as a group there. That is
+    // the same block-context limit every mode in this file has (see the
+    // indented-block-openers note in the module docblock); tree-sitter-carve is
+    // where a real container model lives.
+    const IN_GROUP = CONTAINS
+        .filter((mode) => mode !== ABBREVIATION_DEF && mode !== FIGURE_GROUP_BLOCK)
+        .map((mode) => (mode === DIV_BLOCK ? DIV_BLOCK_IN_GROUP : mode));
+    FIGURE_GROUP_BLOCK.contains = IN_GROUP;
+    DIV_BLOCK_IN_GROUP.contains = [...IN_GROUP.filter((mode) => mode !== DIV_BLOCK_IN_GROUP), 'self'];
 
     return {
         name: 'Carve',