carve-grammars 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 php-collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# Carve Grammars
+
+Grammars for the [Carve](https://github.com/markup-carve/carve) markup language:
+
+- a **Tiptap** integration (editor kit + serializer) that turns a Tiptap/ProseMirror document into Carve markup;
+- **Prism** and **highlight.js** syntax-highlighting grammars for rendering Carve source on the web.
+
+Modeled on [djot-grammars](https://github.com/php-collective/djot-grammars), adapted to Carve's syntax. The Tiptap mark mapping mirrors `carve-php`'s `HtmlToCarve` converter; the highlighting grammars mirror the canonical token set in [`carve/resources/grammar.ebnf`](https://github.com/markup-carve/carve) and the TextMate grammar in [vscode-carve](https://github.com/markup-carve/vscode-carve).
+
+> **Status:** Tiptap integration, plus Prism and highlight.js grammars.
+> Sibling editor grammars live in their own repos: **TextMate** in
+> [vscode-carve](https://github.com/markup-carve/vscode-carve) and
+> [intellij-carve](https://github.com/markup-carve/intellij-carve);
+> **Tree-sitter** in [tree-sitter-carve](https://github.com/markup-carve/tree-sitter-carve)
+> and [zed-carve](https://github.com/markup-carve/zed-carve).
+
+## Install
+
+```bash
+npm install carve-grammars
+```
+
+All peer dependencies are optional - install only what you use:
+`@tiptap/core` + `@tiptap/starter-kit` (v2) for the editor, `prismjs` (v1) for
+Prism, `highlight.js` (v11) for highlight.js.
+
+`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
+import { Editor } from '@tiptap/core'
+import { CarveKit, serializeToCarve } from 'carve-grammars/tiptap'
+
+const editor = new Editor({
+  element: document.getElementById('editor'),
+  extensions: [CarveKit],
+  onUpdate: ({ editor }) => {
+    const carve = serializeToCarve(editor.getJSON())
+    console.log(carve)
+  },
+})
+```
+
+### Individual extensions
+
+```js
+import StarterKit from '@tiptap/starter-kit'
+import { CarveInsert, CarveDelete, CarveDiv, serializeToCarve } from 'carve-grammars/tiptap'
+
+const editor = new Editor({
+  extensions: [StarterKit, CarveInsert, CarveDelete, CarveDiv],
+})
+```
+
+## Mark mapping
+
+| Tiptap mark | Carve token | Renders as |
+|-------------|-------------|------------|
+| bold        | `*text*` / `{*text*}` | `<strong>` |
+| italic      | `/text/` / `{/text/}` | `<em>`     |
+| underline   | `_text_` / `{_text_}` | `<u>`      |
+| code        | `` `text` `` | `<code>`  |
+| highlight   | `=text=` / `{=text=}` | `<mark>`   |
+| strike      | `~text~` / `{~text~}` | `<s>`      |
+| subscript   | `,text,` / `{,text,}` | `<sub>`    |
+| superscript | `^text^` / `{^text^}` | `<sup>`    |
+| insert      | `{+text+}`  | `<ins>`    |
+| delete      | `{-text-}`  | `<del>`    |
+| link        | `[text](url)` / `[text](url "title")` | `<a>` |
+| image       | `![alt](src)` / `![alt](src "title")` | `<img>` |
+| span        | `[text]{.class}` | `<span class>` |
+| abbreviation | `[text]{abbr="..."}` | `<abbr title>` \*\*\* |
+
+\*\*\* `[text]{abbr="..."}` renders a real `<abbr title>` only when carve's
+`SemanticSpanExtension` is enabled (the same opt-in extension also maps `{kbd}`
+-> `<kbd>`, `{dfn}` -> `<dfn>`, `{samp}` -> `<samp>`, `{var}` -> `<var>`).
+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:
+emphasis is `/text/` (Djot uses `_`), `_text_` is underline, `~text~` is
+strikethrough, subscript is `,text,`, and highlight is `=text=` (single-char
+delimiters since carve #108).
+
+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);
+`{+…+}` / `{-…-}` (insert / delete) have only the brace form, since `+` / `-`
+are not emphasis delimiters.
+
+### Escaping
+
+To honor that round-trip contract, `serializeToCarve` escapes literal Carve
+syntax in plain text so it parses back as text rather than markup - inline code,
+links, footnotes, CriticMarkup, mentions/tags/emoji, and an emphasis delimiter
+appearing inside its own span. Escaping is **contextual**: Carve's flanking rules
+already make most lone delimiters inert (`price * 2`, intraword `x_1`,
+`comma,, two`, `C:\path`, `a@b.com`), so those stay clean. The same logic is
+exposed as `escapeCarve(text)`.
+
+## Block elements
+
+Headings (`#`), bullet / ordered / task lists, blockquotes (`>`), fenced code
+blocks (`` ``` lang ``), horizontal rules (`---`), tables (with `|=` header
+cells and `^` / `<` row / column spans), container divs (`::: class`), and
+definition lists.
+
+## Syntax highlighting
+
+Render Carve source as highlighted HTML on the web. Both grammars cover the full
+Carve token set: headings, lists, tables, blockquotes, fenced/raw blocks,
+container divs, front matter and comments, plus inline emphasis
+(`*bold*` `/italic/` `_underline_` `~strike~` `=highlight=` `^sup^` `,sub,`),
+code, links, images, spans, attributes, footnotes, math (`` $`x`$ ``),
+CriticMarkup (`{+ins+}` `{-del-}`), mentions, tags and emoji.
+
+### Prism
+
+The grammar registers itself against the global `Prism`, so `Prism` must be
+global before the grammar module runs. Because static `import` statements are
+hoisted (they all evaluate before any top-level assignment), load the grammar
+with a dynamic `import` after assigning `globalThis.Prism`:
+
+```js
+import Prism from 'prismjs'
+
+globalThis.Prism = Prism                       // grammar reads the global Prism
+await import('carve-grammars/prism/carve.js')  // registers Prism.languages.carve
+
+const html = Prism.highlight(source, Prism.languages.carve, 'carve')
+```
+
+In the browser, load `prismjs` first (it sets the global `Prism`), then load
+`carve-grammars/prism/carve.js`.
+
+### highlight.js
+
+```js
+import hljs from 'highlight.js'
+import carve from 'carve-grammars/highlightjs/carve.js'
+
+hljs.registerLanguage('carve', carve)
+const { value } = hljs.highlight(source, { language: 'carve' })
+```
+
+Loaded as a classic `<script>` after highlight.js, it self-registers against
+the global `hljs`:
+
+```html
+<script src="highlight.min.js"></script>
+<script src="node_modules/carve-grammars/highlightjs/carve.js"></script>
+<script>hljs.highlightAll();</script>
+```
+
+## API
+
+- `serializeToCarve(doc)` - serialize an `editor.getJSON()` document to Carve markup.
+- `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`, `CarveDiv`, `CarveSpan`, `CarveFootnote`, `CarveFootnoteDefinition`, `CarveMath`, `CarveEmbed`, `CarveAbbreviation`, `CarveDefinitionList`.
+
+## Attributes, math and footnotes
+
+- **Attributes** - spans, headings and images serialize an `id` and `class`
+  (and any extra non-structural attrs) as a `{#id .class key="val"}` block, e.g.
+  `[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`.
+- **Math** - `CarveMath` (inline atom) serializes to `` $`x`$ `` and, with
+  `display: true`, `` $$`x`$$ ``.
+- **Footnotes** - `CarveFootnote` is the inline `[^label]` reference;
+  `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.

package/highlightjs/carve.js

@@ -0,0 +1,456 @@
+/**
+ * Carve language definition for highlight.js
+ *
+ * Carve is a Djot-derived markup language with distinct inline delimiters:
+ * emphasis is /text/ (not _text_), underline is _text_, strikethrough is
+ * ~text~ (Djot uses ~ for subscript), subscript is ,text, and highlight is
+ * =text= (Djot uses {=text=}). Strong (*text*), superscript (^text^),
+ * insert ({+text+}) and delete ({-text-}) match Djot.
+ *
+ * This file is a UMD module so it works in every documented integration:
+ *
+ * - ESM: `import carve from 'carve-grammars/highlightjs/carve.js'` (resolved to
+ *   the carve.mjs shim via the package `exports` map), then
+ *   `hljs.registerLanguage('carve', carve)`.
+ * - Classic `<script src=".../highlightjs/carve.js">` after highlight.js: it
+ *   self-registers against the global `hljs` (and exposes `globalThis.carveHljs`).
+ * - CommonJS contexts that load this file as CommonJS get the factory on
+ *   `module.exports`.
+ *
+ * A top-level `export default` is intentionally NOT used: that would be a
+ * syntax error when the file is loaded as a classic browser script.
+ *
+ * @see https://github.com/markup-carve/carve for the Carve specification
+ */
+(function (root, factory) {
+    var carve = factory();
+    if (typeof module === 'object' && module.exports) {
+        module.exports = carve;
+    }
+    if (root) {
+        // Exposed for the ESM shim (carve.mjs) and for classic <script> use.
+        root.carveHljs = carve;
+        if (root.hljs && typeof root.hljs.registerLanguage === 'function') {
+            root.hljs.registerLanguage('carve', carve);
+        }
+    }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+    'use strict';
+    /**
+     * @param {object} [hljs] - the highlight.js instance (unused, kept for the
+     *   standard language-definition signature).
+     * @returns {object} a highlight.js language definition.
+     */
+    return function carve(hljs) {
+    // Block attributes: {.class #id key=value} or boolean {reversed}
+    // Excludes special inline syntax like {= {+ {- {%
+    const ATTRIBUTE = {
+        className: 'attr',
+        begin: /\{(?![=+\-%])[^}]+\}/,
+        relevance: 5,
+    };
+
+    // Headings: # to ######
+    const HEADING = {
+        className: 'section',
+        begin: /^#{1,6}\s/,
+        end: /$/,
+        relevance: 10,
+    };
+
+    // Emphasis (Carve): /text/ - the begin guard avoids URLs and paths
+    // (a/b, ://); the end is a closing slash not followed by word char/slash.
+    const EMPHASIS = {
+        className: 'emphasis',
+        begin: /(?<![\w:/])\/(?=\S)/,
+        end: /\/(?![\w/])/,
+        relevance: 0,
+    };
+
+    // Underline (Carve): _text_ - not in the middle of words
+    const UNDERLINE = {
+        className: 'emphasis',
+        begin: /(?<!\w)_(?!\s)/,
+        end: /_(?!\w)/,
+        relevance: 0,
+    };
+
+    // Strong: *text* - not in the middle of words, can contain emphasis.
+    // Excludes *[ which is abbreviation-definition syntax.
+    const STRONG = {
+        className: 'strong',
+        begin: /(?<!\w)\*(?![\s\[])/,
+        end: /\*(?!\w)/,
+        relevance: 0,
+        contains: [EMPHASIS, UNDERLINE],
+    };
+
+    // Highlight (Carve): =text= (single-char; intraword as {=text=})
+    const HIGHLIGHT = {
+        className: 'addition',
+        begin: /(?<![=\w])=(?=\S)/,
+        end: /=(?![=\w])/,
+        relevance: 3,
+    };
+
+    // Insert: {+text+}
+    const INSERT = {
+        className: 'addition',
+        begin: /\{\+/,
+        end: /\+\}/,
+        relevance: 5,
+    };
+
+    // Delete: {-text-}
+    const DELETE = {
+        className: 'deletion',
+        begin: /\{-/,
+        end: /-\}/,
+        relevance: 5,
+    };
+
+    // Strikethrough (Carve): ~text~ (Djot uses ~ for subscript instead)
+    const STRIKETHROUGH = {
+        className: 'deletion',
+        begin: /(?<!\w)~(?=\S)/,
+        end: /~(?!\w)/,
+        relevance: 2,
+    };
+
+    // Subscript (Carve): ,text, (single-char; intraword as {,text,})
+    const SUBSCRIPT = {
+        className: 'built_in',
+        begin: /(?<!\w),(?=\S)/,
+        end: /,(?!\w)/,
+        relevance: 3,
+    };
+
+    // Superscript: ^text^
+    const SUPERSCRIPT = {
+        className: 'built_in',
+        begin: /\^(?!\s)/,
+        end: /\^/,
+        relevance: 2,
+    };
+
+    // Math: $$`...`$$ (display) and $`...`$ (inline). Must precede the inline
+    // code modes - the leading $ keeps them from matching, but order is clearer.
+    const MATH_DISPLAY = {
+        className: 'string',
+        begin: /\$\$`+/,
+        end: /`+\$\$/,
+        relevance: 5,
+    };
+    const MATH_INLINE = {
+        className: 'string',
+        begin: /\$`+/,
+        end: /`+\$/,
+        relevance: 5,
+    };
+
+    // Inline code: `code` or ``code``. highlight.js has no begin->end
+    // backreference to match fence widths, so handle the two common widths
+    // explicitly - double backticks first, so an embedded single backtick
+    // (``a ` b``) does not close the span early.
+    const INLINE_CODE_DOUBLE = {
+        className: 'code',
+        begin: /``/,
+        end: /``/,
+        relevance: 0,
+    };
+    const INLINE_CODE_SINGLE = {
+        className: 'code',
+        begin: /`/,
+        end: /`/,
+        relevance: 0,
+    };
+
+    // Inline links: [text](url) with optional trailing attributes
+    const LINK = {
+        className: 'link',
+        begin: /\[[^\]]*\]\([^)]*\)(\{[^}]+\})?/,
+        relevance: 5,
+    };
+
+    // Autolinks: <https://...> or <mailto:...>
+    const AUTOLINK = {
+        className: 'link',
+        begin: /<(?:https?:\/\/|mailto:)[^>]+>/,
+        relevance: 5,
+    };
+
+    // Email autolinks: <user@example.com>
+    const EMAIL_AUTOLINK = {
+        className: 'link',
+        begin: /<[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}>/,
+        relevance: 5,
+    };
+
+    // Images: ![alt](url) with optional trailing attributes
+    const IMAGE = {
+        className: 'link',
+        begin: /!\[[^\]]*\]\([^)]*\)(\{[^}]+\})?/,
+        relevance: 5,
+    };
+
+    // Reference links: [text][ref] with optional trailing attributes
+    const REFERENCE_LINK = {
+        className: 'link',
+        begin: /\[[^\]]+\]\[[^\]]*\](\{[^}]+\})?/,
+        relevance: 5,
+    };
+
+    // Spans with attributes: [text]{.class} or [text]{#id}
+    const SPAN = {
+        className: 'string',
+        begin: /\[[^\]]+\]\{[^}]+\}/,
+        relevance: 5,
+    };
+
+    // Reference definitions: [ref]: url
+    const REFERENCE_DEF = {
+        className: 'symbol',
+        begin: /^\[[^\]^\]]+\]:/,
+        end: /$/,
+        relevance: 10,
+    };
+
+    // Footnote references: [^note]
+    const FOOTNOTE_REF = {
+        className: 'symbol',
+        begin: /\[\^[^\]]+\]/,
+        relevance: 5,
+    };
+
+    // Citations (Tier-2 §22): [@key], [+@key], [@key, p.10], [@a; @b]
+    // A bracket whose content holds at least one `@key` with no trailing
+    // `(url)`, `[ref]`, or `{attrs}` suffix. The negative lookahead is handled
+    // by position in the contains array (SPAN and REFERENCE_LINK are checked
+    // first to claim those suffixed forms).
+    const CITATION = {
+        className: 'symbol',
+        begin: /\[\+?(?:[^\]@]*@[A-Za-z0-9_][A-Za-z0-9_.:#$%&+?<>~\/-]*[^\]]*)\](?!\(|\[|\{)/,
+        relevance: 8,
+    };
+
+    // Code callouts (Tier-2 §10): <n> markers trailing a code-fence line or
+    // leading a callout-list item.
+    const CODE_CALLOUT = {
+        className: 'symbol',
+        begin: /<\d+>/,
+        relevance: 5,
+    };
+
+    // Footnote definitions: [^note]: content
+    const FOOTNOTE_DEF = {
+        className: 'symbol',
+        begin: /^\[\^[^\]]+\]:/,
+        end: /$/,
+        relevance: 10,
+    };
+
+    // Abbreviation definitions: *[ABBR]: text
+    const ABBREVIATION_DEF = {
+        className: 'symbol',
+        begin: /^\*\[[^\]]+\]:/,
+        end: /$/,
+        relevance: 10,
+    };
+
+    // Blockquotes: > text
+    const BLOCKQUOTE = {
+        className: 'quote',
+        begin: /^>/,
+        end: /$/,
+        relevance: 0,
+    };
+
+    // Horizontal rules: --- or *** or ___
+    const HORIZONTAL_RULE = {
+        className: 'meta',
+        begin: /^(-{3,}|\*{3,}|_{3,})$/,
+        relevance: 10,
+    };
+
+    // Bullet list items: - or *
+    const LIST_BULLET = {
+        className: 'bullet',
+        begin: /^[ \t]*[-*](?=\s)/,
+        relevance: 0,
+    };
+
+    // Numbered list items: decimal (1.), alpha (a. A.), roman (i. I.)
+    const LIST_NUMBER = {
+        className: 'bullet',
+        begin: /^[ \t]*(\d+[.)]|[a-zA-Z][.)]|[ivxlcdmIVXLCDM]+[.)])(?=\s)/,
+        relevance: 0,
+    };
+
+    // Task list items: - [ ] or - [x]
+    const TASK_LIST = {
+        className: 'bullet',
+        begin: /^[ \t]*[-*]\s\[[ xX_]\]/,
+        relevance: 5,
+    };
+
+    // Definition list terms: : term
+    const DEFINITION_TERM = {
+        className: 'title',
+        begin: /^: /,
+        end: /$/,
+        relevance: 5,
+    };
+
+    // Code fence opening: ``` or ~~~ with optional language
+    const CODE_FENCE_START = {
+        className: 'keyword',
+        begin: /^[`~]{3,}\s*[a-zA-Z]*$/,
+        relevance: 10,
+    };
+
+    // Code fence closing: ``` or ~~~
+    const CODE_FENCE_END = {
+        className: 'keyword',
+        begin: /^[`~]{3,}$/,
+        relevance: 10,
+    };
+
+    // Div block opening: ::: with optional class
+    const DIV_BLOCK_START = {
+        className: 'keyword',
+        begin: /^:{3,}\s*\w*$/,
+        relevance: 10,
+    };
+
+    // Div block closing: :::
+    const DIV_BLOCK_END = {
+        className: 'keyword',
+        begin: /^:{3,}$/,
+        relevance: 10,
+    };
+
+    // Inline comments: {% comment %}
+    const INLINE_COMMENT = {
+        className: 'comment',
+        begin: /\{%/,
+        end: /%\}/,
+        relevance: 5,
+    };
+
+    // Table separator: |---|---|
+    const TABLE_SEPARATOR = {
+        className: 'meta',
+        begin: /^\|[-:| ]+\|$/,
+        relevance: 5,
+    };
+
+    // Line blocks: | text (for poetry) - must precede TABLE_ROW
+    const LINE_BLOCK = {
+        className: 'string',
+        begin: /^\| /,
+        end: /$/,
+        relevance: 3,
+    };
+
+    // Table rows: | cell | cell |
+    const TABLE_ROW = {
+        className: 'string',
+        begin: /^\|/,
+        end: /\|(\{[^}]*\})?$/,
+        relevance: 2,
+    };
+
+    // Captions: ^ caption text
+    const CAPTION = {
+        className: 'title',
+        begin: /^\^ /,
+        end: /$/,
+        relevance: 5,
+    };
+
+    // Raw format marker: {=html} or {=latex}
+    const RAW_FORMAT = {
+        className: 'meta',
+        begin: /\{=[a-zA-Z]+\}/,
+        relevance: 5,
+    };
+
+    // Escaped characters: \* \[ etc
+    const ESCAPE = {
+        className: 'symbol',
+        begin: /\\[!"#$%&'()*+,.\/:;<=>?@\[\\\]^_`{|}~-]/,
+        relevance: 0,
+    };
+
+    // Hard line break: \ at end of line
+    const HARD_BREAK = {
+        className: 'meta',
+        begin: /\\$/,
+        relevance: 2,
+    };
+
+    return {
+        name: 'Carve',
+        aliases: ['carve'],
+        case_insensitive: false,
+        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)
+            HEADING,
+            CODE_FENCE_START,
+            CODE_FENCE_END,
+            DIV_BLOCK_START,
+            DIV_BLOCK_END,
+            HORIZONTAL_RULE,
+            TABLE_SEPARATOR,
+            LINE_BLOCK,        // Must be before TABLE_ROW (both start with |)
+            TABLE_ROW,
+            BLOCKQUOTE,
+            CAPTION,
+            TASK_LIST,         // Must be before LIST_BULLET
+            LIST_BULLET,
+            LIST_NUMBER,
+            DEFINITION_TERM,
+            FOOTNOTE_DEF,      // Must be before REFERENCE_DEF
+            ABBREVIATION_DEF,  // Must be before REFERENCE_DEF (*[ABBR]: vs [ref]:)
+            REFERENCE_DEF,
+
+            // Inline elements (order matters - more specific first)
+            FOOTNOTE_REF,
+            IMAGE,             // Must be before LINK (starts with !)
+            SPAN,              // Must be before LINK ([text]{attr} vs [text](url))
+            REFERENCE_LINK,    // Must be before LINK ([text][ref] vs [text](url))
+            CITATION,          // Must be after SPAN/REF_LINK (no (url)/[ref]/{attr} tail)
+            CODE_CALLOUT,      // <n> callout markers
+            LINK,
+            AUTOLINK,
+            EMAIL_AUTOLINK,
+            RAW_FORMAT,        // {=html} - must be before INSERT/DELETE braces
+            INSERT,            // {+text+}
+            DELETE,            // {-text-}
+            INLINE_COMMENT,    // {% %} - must be before ATTRIBUTE
+            HIGHLIGHT,         // =text=
+            SUBSCRIPT,         // ,text,
+            SUPERSCRIPT,       // ^text^
+            STRONG,
+            EMPHASIS,          // /text/
+            UNDERLINE,         // _text_
+            STRIKETHROUGH,     // ~text~
+            MATH_DISPLAY,      // $$`...`$$ - before inline code (leading $)
+            MATH_INLINE,       // $`...`$
+            INLINE_CODE_DOUBLE, // ``code`` - before single
+            INLINE_CODE_SINGLE, // `code`
+            ATTRIBUTE,
+            ESCAPE,
+            HARD_BREAK,
+        ],
+    };
+    };
+}));