@haklex/rich-litexml 0.15.1 → 0.15.2

package/.claude/skills/litexml-authoring/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: litexml-authoring
+description: Use when writing Haklex articles with Markdown plus LiteXML, choosing the appropriate Haklex node for content, authoring LiteXML fragments, or converting a LightXML/LiteXML string or file into Lexical SerializedEditorState JSON, Markdown, or Static Render HTML via the `litexml` CLI.
+user_invocable: true
+---
+
+# LiteXML Authoring
+
+Use this skill when an article needs Haklex-specific rich nodes, or when the user asks to convert LiteXML to Lexical JSON / Markdown / HTML via the `litexml` CLI.
+
+The skill is split into a thin index (this file) plus per-topic references. Load the matching reference when you start the actual work — the index is intentionally short so the format decision table and node selection map fit in one read.
+
+## References
+
+| File                                                                   | When to load                                                                                                               |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| [`references/cli.md`](./references/cli.md)                             | Running the `litexml` binary — every flag, every input/output mode, every runtime caveat.                                  |
+| [`references/nodes-structural.md`](./references/nodes-structural.md)   | Authoring with structural tags (`<p>`, headings, lists, tables, links) and inline formatting (`<b>`, `<em>`, `<code>`, …). |
+| [`references/nodes-extensions.md`](./references/nodes-extensions.md)   | Authoring with Haklex extension tags (media, code, math, callouts, containers, footnotes, chat, poll, …).                  |
+| [`references/authoring-recipes.md`](./references/authoring-recipes.md) | CDATA usage, block IDs, nested-content rules, similar-node disambiguation, validation, adding new nodes.                   |
+
+`packages/rich-editor/docs/markdown-flavor-litexml.md` is the canonical tag contract — read it before changing any tag name or attribute schema.
+
+## Format decision
+
+| Content requirement                                                     | Use                                                               |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Plain prose, headings, simple links, lists, quotes, tables, code fences | **Markdown**                                                      |
+| Any Haklex extension tag is required                                    | **LiteXML** — for the whole fragment, including surrounding prose |
+| A block needs stable identity for later edits                           | LiteXML with `id="..."` (maps to `$.blockId`)                     |
+| Fresh poll/chat content                                                 | LiteXML without IDs — the reader mints them                       |
+
+Once a fragment contains any LiteXML tag, **all** surrounding prose in that fragment must also be LiteXML. Markdown is not parsed inside a LiteXML fragment.
+
+## CLI quick start
+
+```bash
+# inside the haklex monorepo
+pnpm --silent litexml input.xml --format json --compact # → SerializedEditorState
+pnpm --silent litexml input.xml --format markdown       # → Markdown
+pnpm --silent litexml input.xml --format html --open    # → HTML preview, browser
+
+# outside the monorepo
+npx --yes -p @haklex/rich-litexml-cli litexml input.xml --format json
+```
+
+Full flag reference, output forms, theme/variant/lang options, error modes, validation pipelines: [`references/cli.md`](./references/cli.md).
+
+## Node selection map
+
+Detailed `When` / `Avoid when` / params / body rules for each tag live in [`nodes-structural.md`](./references/nodes-structural.md) and [`nodes-extensions.md`](./references/nodes-extensions.md). Use this table only to decide which reference to open.
+
+| Need                                                   | Tag                                                                         | Reference  |
+| ------------------------------------------------------ | --------------------------------------------------------------------------- | ---------- |
+| Paragraph, heading, list, table, link, inline format   | `<p>` / `<h*>` / `<ul>` / `<ol>` / `<table>` / `<a>` / `<b>` / `<code>` / … | structural |
+| Quote (with optional `attribution`)                    | `<blockquote>`                                                              | structural |
+| Single image / multi-image / video / embed / link card | `<img>` / `<gallery>` / `<video>` / `<embed>` / `<link-card>`               | extensions |
+| Code (single / multi-file)                             | `<codeblock>` / `<code-snippet>`                                            | extensions |
+| Diagram (Mermaid / opaque)                             | `<mermaid>` / `<excalidraw>`                                                | extensions |
+| Math (inline / block)                                  | `<math>` / `<math display="block">`                                         | extensions |
+| Callout (semantic / page-wide)                         | `<alert>` / `<banner>`                                                      | extensions |
+| Collapsible / nested doc / multi-column                | `<details>` / `<nested-doc>` / `<grid><cell>`                               | extensions |
+| Inline annotation                                      | `<spoiler>` / `<ruby>` / `<mention>` / `<tag>` / `<comment>`                | extensions |
+| Footnote                                               | `<footnote>` + `<footnote-section>`                                         | extensions |
+| Chat / poll                                            | `<chat>` / `<poll>`                                                         | extensions |
+| Internal review marker                                 | `<agent-diff>`                                                              | extensions |
+
+## Cross-cutting rules
+
+- Canonical lowercase tag names. Do **not** emit legacy aliases (`<linkcard>`, `<codesnippet>`, `<nesteddoc>`, `<code-block>`).
+- Quote every attribute value.
+- Escape XML-sensitive text (`&amp;`, `&lt;`, `&gt;`, `&quot;`). Use CDATA for opaque JSON, drawing snapshots, and multi-line code bodies.
+- `<alert>`, `<banner>`, `<nested-doc>`, `<grid><cell>` hold a **fresh nested editor state** — wrap their body in block tags (`<p>`, `<h*>`, …), not bare text.
+- A fragment that mixes any extension tag with prose must be wholly LiteXML; Markdown syntax is not parsed inside.
+
+Details, gotchas, and the full disambiguation matrix: [`references/authoring-recipes.md`](./references/authoring-recipes.md).
+
+## Validation
+
+After producing or editing LiteXML, round-trip to compact JSON to confirm the registry parses every tag:
+
+```bash
+pnpm --silent litexml '<doc><p>Hello</p></doc>' --format json --compact
+```
+
+If the command succeeds but a downstream editor cannot materialize a node, the runtime is missing that Haklex node class — re-check the consumer's `nodes` registration, not the CLI.

package/.claude/skills/litexml-authoring/references/authoring-recipes.md

@@ -0,0 +1,141 @@
+# Authoring recipes and gotchas
+
+Recurring patterns that come up when writing LiteXML fragments. Each entry is intentionally small — pull the matching one when you hit the situation.
+
+## When to use CDATA
+
+Wrap body content in `<![CDATA[ ... ]]>` whenever the body is opaque or contains characters that XML would otherwise escape:
+
+| Situation                                        | Required?                                                           |
+| ------------------------------------------------ | ------------------------------------------------------------------- |
+| `<excalidraw>` JSON snapshot                     | yes                                                                 |
+| `<codeblock>` containing `<`, `>`, `&`, or `]]>` | yes                                                                 |
+| `<codeblock>` containing only safe characters    | optional, but preferred for multi-line code                         |
+| `<file>` body inside `<code-snippet>`            | same rules as `<codeblock>`                                         |
+| `<mermaid>` source                               | optional; usually unnecessary because Mermaid syntax is XML-safe    |
+| `<math>` equation                                | rarely needed; KaTeX source uses `\`, not XML metacharacters        |
+| `<p>`, `<h1>`, `<li>`, `<td>` prose              | never — escape entities instead (`&amp;`, `&lt;`, `&gt;`, `&quot;`) |
+
+CDATA inside `<codeblock>` and `<file>` is parsed via a small linkedom-specific extraction (`extractCdataText`). Do **not** nest CDATA sections or place trailing `]]>` inside the body.
+
+## Block IDs (`id` attribute)
+
+- **Omit** for fresh content. The hydrating editor generates an ID on insert.
+- **Add** when later tool calls need to target the exact block, or when porting an existing document that already carries IDs (so cross-references / diff entries stay attached).
+- The `id` attribute maps to `$.blockId`. It is preserved on round-trip (`litexml ... --format json` then back).
+- Tags that accept `id`: every block-level tag in [`nodes-structural.md`](./nodes-structural.md) and [`nodes-extensions.md`](./nodes-extensions.md) except inline tags and `<tr>` / `<th>` / `<td>`.
+
+## Quote attribution
+
+`<blockquote>` accepts an optional `attribution` attribute. The reader emits `type: "rich-quote"` when present and `type: "quote"` when absent — both materialize as the same `RichQuoteNode` in the editor.
+
+```xml
+<blockquote attribution="— Wang Xizhi, Lantingji Xu">
+  <p>未尝不临文嗟悼，不能喻之于怀。</p>
+</blockquote>
+
+<blockquote>
+  <p>An unattributed quote.</p>
+</blockquote>
+```
+
+## Nested block content vs inline content
+
+Containers that hold a fresh `SerializedEditorState` (and therefore need block children, not inline text):
+
+- `<alert>`
+- `<banner>`
+- `<nested-doc>`
+- `<grid><cell>`
+
+Always wrap the body in block tags (`<p>`, `<h2>`, `<ul>`, etc.):
+
+```xml
+<alert type="tip">
+  <p>Wrap the body in a paragraph.</p>
+</alert>
+
+<!-- bad: bare text body -->
+<alert type="tip">Bare text — works at parse time but won't round-trip cleanly.</alert>
+```
+
+`<details>` is different: it uses ordinary block children (no nested editor state). Either form is fine, but use `<p>` for consistency.
+
+## Mixing extension tags with prose
+
+If a fragment contains **any** LiteXML extension tag, the surrounding prose must also be expressed as LiteXML — Markdown is not parsed inside a LiteXML fragment.
+
+```xml
+<!-- correct -->
+<h2>Install</h2>
+<p>Run the command:</p>
+<codeblock lang="bash">pnpm add @haklex/rich-editor</codeblock>
+<p>Then import the editor.</p>
+
+<!-- wrong: Markdown syntax inside a LiteXML fragment is rendered literally -->
+## Install
+Run the command:
+<codeblock lang="bash">pnpm add @haklex/rich-editor</codeblock>
+Then import the editor.
+```
+
+The right time to write pure Markdown is when the whole document has no extension tags. As soon as one shows up, lift the whole document into LiteXML.
+
+## Choosing similar nodes
+
+| Decision                                 | Use                               | Not                                           |
+| ---------------------------------------- | --------------------------------- | --------------------------------------------- |
+| Quoted external text                     | `<blockquote>`                    | `<alert>` (use for warnings/tips, not quotes) |
+| Editorial warning                        | `<alert type="warning">`          | `<blockquote>`                                |
+| Page-wide announcement                   | `<banner>`                        | `<alert>`                                     |
+| Multi-column comparison data             | `<table>`                         | `<grid>`                                      |
+| Multi-column editorial layout            | `<grid>`                          | `<table>`                                     |
+| Inline citation                          | `<a>`                             | `<link-card>`                                 |
+| Standalone reference deserving a preview | `<link-card>`                     | `<a>`                                         |
+| YouTube / Vimeo embed                    | `<embed url="..." source="..."/>` | `<img>` (which would be a static thumbnail)   |
+| Direct video asset                       | `<video src="..."/>`              | `<embed>`                                     |
+| Single image                             | `<img>`                           | `<gallery>`                                   |
+| Image set                                | `<gallery>`                       | many `<img>`                                  |
+| Single-language code                     | `<codeblock>`                     | `<code-snippet>`                              |
+| Multi-file example                       | `<code-snippet>`                  | repeated `<codeblock>`                        |
+| Mermaid-expressible diagram              | `<mermaid>`                       | `<excalidraw>`                                |
+| Opaque hand-drawn snapshot               | `<excalidraw>`                    | `<mermaid>`                                   |
+| Inline equation                          | `<math>`                          | `<math display="block">`                      |
+| Standalone equation                      | `<math display="block">`          | inline `<math>`                               |
+| Collapsible secondary content            | `<details>`                       | `<spoiler>` (inline only)                     |
+| Hidden inline reveal                     | `<spoiler>`                       | `<details>`                                   |
+| Reader-visible callout                   | `<alert>` / `<banner>`            | `<comment>`                                   |
+| Reviewer note (not for end readers)      | `<comment>`                       | `<alert>`                                     |
+| Survey / live vote                       | `<poll>`                          | `<ul>` / `<ol>`                               |
+| Static option list                       | `<ul>`                            | `<poll>`                                      |
+| Task checklist                           | `<ul type="check">`               | `<poll>`                                      |
+| Transcript                               | `<chat>`                          | `<blockquote>`                                |
+
+## Validation
+
+After producing or editing a LiteXML fragment, convert to compact JSON to confirm the registry parses every tag:
+
+```bash
+pnpm --silent litexml '<doc><p>Hello</p></doc>' --format json --compact
+```
+
+For round-trip verification on an article file:
+
+```bash
+litexml article.xml --format json -o /tmp/state.json
+litexml /tmp/state.json --format markdown -o /tmp/article.md
+```
+
+Any node that disappears or changes shape across the round-trip is a writer/reader bug — file against `@haklex/rich-litexml`, not the CLI.
+
+When `litexml` succeeds but a downstream editor cannot materialize a node, the consumer is missing that Haklex node class. The CLI registry is authoritative for what _can_ be parsed; node class registration is the consumer's responsibility.
+
+## Adding a new node
+
+If you find yourself wanting a tag that this skill does not document, the underlying machinery is in `packages/rich-litexml/`. Following its `CLAUDE.md`:
+
+1. Add a writer in `packages/rich-litexml/src/writers/` (SerializedNode JSON → XML).
+2. Add a reader in `packages/rich-litexml/src/readers/` (XML → SerializedNode JSON).
+3. Register both in `createDefaultRegistry()` in `src/default-registry.ts`.
+4. Add a roundtrip test in `tests/`.
+5. Update this skill's [`nodes-extensions.md`](./nodes-extensions.md) so the new tag is discoverable from the authoring side.

package/.claude/skills/litexml-authoring/references/cli.md

@@ -0,0 +1,166 @@
+# litexml CLI reference
+
+`@haklex/rich-litexml-cli` publishes the `litexml` binary. It accepts **LiteXML** or **Lexical SerializedEditorState JSON** as input (auto-detected) and emits one of three target formats: **HTML preview**, **Lexical JSON**, or **Markdown**.
+
+This file is the canonical reference for every flag, every input/output mode, and the runtime caveats. The main `SKILL.md` only lists the format decision matrix; come here when you need the actual command.
+
+## Invocation forms
+
+### Inside this monorepo
+
+```bash
+pnpm --silent litexml INPUT --format FMT [options]
+```
+
+The repo's root `package.json` exposes `litexml` as a pnpm-runnable script that resolves the local workspace build. Always pair with `--silent` so pnpm chatter does not corrupt stdout when piping into a file.
+
+### Outside the repo
+
+```bash
+npx --yes -p @haklex/rich-litexml-cli@VERSION litexml INPUT --format FMT [options]
+```
+
+Or after a global install:
+
+```bash
+npm install -g @haklex/rich-litexml-cli
+litexml INPUT --format FMT [options]
+```
+
+`INPUT` is a file path, `-`, or an inline LiteXML / JSON string; `FMT` is one of `html | json | markdown`; `VERSION` is the published version tag. See the next sections for the concrete forms.
+
+The package depends on `@haklex/rich-compose`, `@haklex/rich-headless`, and `@haklex/rich-litexml` at the same version, and reads `@haklex/rich-compose/dist/style.css` plus `dist/litexml-html-preview-client.js` at runtime via `require.resolve`. Do not strip those packages in a custom install.
+
+## Input
+
+| Form               | Example                                      | Notes                                                                                         |
+| ------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| File path          | `litexml article.xml --format json`          | Path is detected via `existsSync`. Reads with `utf8`.                                         |
+| Stdin              | `cat article.xml \| litexml - --format json` | Explicit `-` reads from `fd 0`. Also used when input arg is omitted entirely.                 |
+| Inline string      | `litexml '<p>hi</p>' --format json`          | If the arg does not match an existing file and starts with `<` or `{`, it is parsed directly. |
+| Force input format | `litexml input.txt --input-format litexml`   | Use when auto-detection cannot decide (e.g. unusual whitespace or empty leading lines).       |
+
+**Auto-detection rule** (`src/input.ts`): first non-whitespace character — `<` → LiteXML, `{` → JSON, anything else → error. Override with `--input-format litexml|json` (alias `-i`).
+
+## Output
+
+| Form               | Example                                               |
+| ------------------ | ----------------------------------------------------- |
+| Stdout (default)   | `litexml input.xml --format html > article.html`      |
+| Explicit file      | `litexml input.xml --format html -o article.html`     |
+| Browser preview    | `litexml input.xml --format html --open`              |
+| Write **and** open | `litexml input.xml --format html -o page.html --open` |
+
+When `--open` is set without `-o`, the CLI writes the HTML to a tmp file (`mkdtemp` under `os.tmpdir()`) and opens it via `open` / `cmd /c start` / `xdg-open` depending on platform.
+
+Stdout EPIPE is handled gracefully (`process.stdout.on('error', ...)`), so piping into `head` / `less` will not crash the process.
+
+## Flags
+
+| Flag                    | Alias | Applies to  | Default      | Meaning                                                                       |
+| ----------------------- | ----- | ----------- | ------------ | ----------------------------------------------------------------------------- |
+| `--format <fmt>`        | `-f`  | all         | **required** | `html` \| `json` \| `markdown`.                                               |
+| `--input-format <fmt>`  | `-i`  | all         | auto         | Force `litexml` or `json`.                                                    |
+| `--output <file>`       | `-o`  | all         | stdout       | Write rendered output to a file.                                              |
+| `--compact`             |       | `json` only | off          | Strip indentation from emitted JSON.                                          |
+| `--theme <light\|dark>` |       | `html` only | `light`      | Sets `<meta color-scheme>` and `<html>` background.                           |
+| `--variant <v>`         |       | `html` only | `article`    | `article` (sans, 16px) \| `note` (CJK serif, 16px) \| `comment` (sans, 14px). |
+| `--title <t>`           |       | `html` only | derived      | Sets the HTML `<title>`. Default: input filename or `Haklex LiteXML Preview`. |
+| `--lang <l>`            |       | `html` only | `en`         | Sets `<html lang>`.                                                           |
+| `--open`                |       | `html` only | off          | Open the generated HTML in the system browser.                                |
+| `--help`                | `-h`  | —           | —            | Print help and exit `0`.                                                      |
+
+Irrelevant flags are not errors — the CLI prints a warning on stderr (`Warning: ignoring options not applicable to --format <fmt>: ...`) and continues. Use `2>/dev/null` to suppress.
+
+## Output formats in detail
+
+### `--format json` — Lexical SerializedEditorState
+
+Emits a full `SerializedEditorState` (i.e. `{ "root": { ... } }`), not a node array. Use this when you need to feed the result into `editor.parseEditorState(JSON.stringify(state))` or persist it to a database.
+
+```bash
+litexml input.xml --format json > state.json
+litexml input.xml --format json --compact # single-line, smallest
+litexml input.xml --format json -o state.json
+litexml '<p>hi</p>' --format json --compact # inline → JSON, one-shot
+```
+
+When the input is already JSON, the CLI still rebuilds it via `JSON.parse` → format → emit. This is intentional: it lets you re-format / compact existing state files via the same binary.
+
+### `--format markdown` — `$toMarkdown()` via rich-headless
+
+```bash
+litexml input.xml --format markdown > article.md
+litexml state.json --format markdown         # auto-detected as JSON
+litexml state.json --format markdown -i json # force
+```
+
+The Markdown writer is `@haklex/rich-headless`'s `$toMarkdown()`. Coverage includes all standard nodes plus haklex extensions (mentions, footnotes, KaTeX, code blocks, tables, banners, alerts, spoilers, etc.). When a Haklex node has no Markdown analogue, the headless writer emits a sensible textual fallback rather than failing.
+
+Useful pairings:
+
+```bash
+# Round-trip: render the canonical Markdown that an article would export as
+litexml article.xml --format markdown | diff - article.md
+
+# Convert a stored Lexical state back into editable Markdown
+litexml state.json --format markdown -o editable.md
+```
+
+### `--format html` — full preview document
+
+Writes a standalone HTML document with:
+
+- `@haklex/rich-compose/dist/style.css` inlined inside `<style>`.
+- The `SerializedEditorState` embedded as `<script id="haklex-litexml-payload" type="application/json">`.
+- `@haklex/rich-compose/dist/litexml-html-preview-client.js` inlined inside a trailing `<script>`. The bundle reads the payload script and renders into `#haklex-litexml-root` via the same Rich Compose renderer used by the static renderer.
+
+The resulting file is fully self-contained — no external network requests, no missing CSS — and can be opened from any disk path. Theme / variant / title / lang are baked into the document at render time.
+
+```bash
+litexml input.xml --format html > preview.html
+litexml input.xml --format html -o preview.html
+litexml input.xml --format html --open # tmpfile + system open
+litexml input.xml --format html --theme dark -o dark.html
+litexml input.xml --format html --variant note --lang ja -o note.html
+litexml input.xml --format html --title "Draft v3" -o draft.html
+```
+
+If you build the CLI from source and `@haklex/rich-compose` has not been built, the HTML format will fail with `Cannot resolve @haklex/rich-compose asset "style.css"`. Run `pnpm --filter @haklex/rich-compose build` first.
+
+## Exit behavior
+
+- Success: exit code `0`. Output goes to stdout (or `-o` path).
+- Error: exit code `1`, message + full `HELP` text written to stderr. Common causes: missing `--format`, unknown flag, empty input, malformed JSON, unresolvable compose asset.
+- `--help`: exit code `0`, help text written to stdout.
+- EPIPE on stdout (e.g. piping into `head`): exit code `0` silently.
+
+## Validation recipe
+
+After producing or editing a LiteXML fragment, convert to compact JSON to confirm the registry parses every tag:
+
+```bash
+pnpm --silent litexml '<doc><p>Hello</p></doc>' --format json --compact
+```
+
+If the command succeeds but a downstream editor cannot materialize a node, the runtime is missing that Haklex node class — re-check the consumer's `nodes` registration, not the CLI.
+
+For round-trip verification on a real article:
+
+```bash
+litexml article.xml --format json | litexml - --format markdown -i json
+```
+
+Any node that round-trips differently between LiteXML → JSON → Markdown is a writer/reader bug in `@haklex/rich-litexml` or a missing Markdown export in `@haklex/rich-headless`.
+
+## Common mistakes
+
+| Mistake                                          | Symptom                                                     | Fix                                                                                     |
+| ------------------------------------------------ | ----------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Omitting `--format`                              | `Missing required option: --format <html\|json\|markdown>.` | Always supply `-f` / `--format`.                                                        |
+| Forgetting `--silent` when piping                | pnpm progress lines mixed into the output file              | `pnpm --silent litexml ... > out.html`.                                                 |
+| Passing inline LiteXML without quotes            | Shell parses `<` as redirect                                | Wrap in single quotes: `litexml '<p>x</p>' -f json`.                                    |
+| Using `--compact` with `-f html`                 | Warning, no effect                                          | `--compact` is JSON-only.                                                               |
+| Running `-f html` without compose build          | `Cannot resolve @haklex/rich-compose asset "style.css".`    | Run `pnpm --filter @haklex/rich-compose build` (only inside a source checkout).         |
+| Treating output as node array                    | Downstream `editor.parseEditorState` rejects the JSON       | Output is `SerializedEditorState` (`{root: {...}}`), not a node list.                   |
+| Mixing Markdown syntax inside a LiteXML fragment | `**bold**` rendered literally                               | If the fragment contains any LiteXML tag, write the whole surrounding prose as LiteXML. |

package/.claude/skills/litexml-authoring/references/nodes-extensions.md

@@ -0,0 +1,399 @@
+# Haklex extension nodes
+
+These tags are not part of CommonMark. Each one maps to a Haklex-specific Lexical node and is the only way to author content that those node renderers can pick up. For prose scaffolding (paragraphs, lists, tables, links, inline formatting) see [`nodes-structural.md`](./nodes-structural.md).
+
+Every block-level extension may carry `id="..."` → `$.blockId`. Omit for fresh authoring; preserve when editing.
+
+## Media
+
+### `<img>` — image
+
+- **When**: A single image, optionally with caption and explicit dimensions.
+- **Avoid when**: Multiple related images — use `<gallery>`. Decorative inline glyph — use the renderer's icon system.
+- **Required**: `src`.
+- **Optional**: `id`, `alt`, `width` (numeric), `height` (numeric), `caption`, `thumbhash`, `accent` (color string for image rendering).
+- **Body**: self-closing.
+- **Inside `<gallery>`**: `<img>` becomes a gallery image item instead of a standalone image node — only `src` and `alt` are read.
+
+```xml
+<img src="/photo.jpg" alt="Cover" width="1200" height="800" caption="At dusk." accent="#ff8855" />
+```
+
+### `<video>` — video
+
+- **When**: A directly playable video asset.
+- **Avoid when**: Provider-hosted clip (YouTube, Vimeo) — use `<embed>`.
+- **Required**: `src`.
+- **Optional**: `id`, `poster` (preview image URL), `width`, `height`.
+- **Body**: self-closing.
+
+```xml
+<video src="/clip.mp4" poster="/thumb.jpg" />
+```
+
+### `<link-card>` — rich link preview
+
+- **When**: A standalone reference URL that deserves a visible card (title, description, favicon, hero image).
+- **Avoid when**: Inline citation in the middle of prose — use `<a>`.
+- **Required**: `url`.
+- **Optional**: `id`, `source`, `title`, `description`, `favicon`, `image`.
+- **Body**: self-closing.
+
+```xml
+<link-card url="https://haklex.dev"
+           title="Haklex"
+           description="Lexical-based rich editor ecosystem."
+           favicon="https://haklex.dev/icon.svg" />
+```
+
+### `<embed>` — provider embed
+
+- **When**: A third-party provider embed such as YouTube, Vimeo, CodePen, Tweet, etc. The renderer detects the provider and produces the right iframe / oEmbed payload.
+- **Avoid when**: A static screenshot — use `<img>`.
+- **Required**: `url`.
+- **Optional**: `id`, `source` (provider hint, e.g. `youtube`, `vimeo`).
+- **Body**: self-closing.
+
+```xml
+<embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" source="youtube" />
+```
+
+### `<gallery>` — image gallery
+
+- **When**: A related image set displayed together.
+- **Avoid when**: A single figure — use `<img>`.
+- **Required**: one or more `<img>` children.
+- **Optional**: `id`, `layout` (defaults to `grid`).
+- **Body**: only `<img src="..." alt="..." />` children. Other tags are ignored.
+
+```xml
+<gallery layout="grid">
+  <img src="/a.jpg" alt="A" />
+  <img src="/b.jpg" alt="B" />
+  <img src="/c.jpg" alt="C" />
+</gallery>
+```
+
+## Code
+
+### `<codeblock>` — single code listing
+
+- **When**: One code listing in a single language.
+- **Avoid when**: Multi-file example (e.g. `index.ts` + `package.json`) — use `<code-snippet>`. Short inline phrase — use `<code>`.
+- **Required**: none (empty body is allowed).
+- **Optional**: `id`, `lang`.
+- **Body**: raw code text. For shebangs, imports, template strings, XML-sensitive characters (`<`, `&`), or multi-line code, prefer `<![CDATA[...]]>` so the body is preserved verbatim.
+
+```xml
+<codeblock lang="ts"><![CDATA[
+import { foo } from './bar';
+const x = <T>(t: T): T => t;
+]]></codeblock>
+```
+
+Note: the canonical tag is `<codeblock>`, **not** `<code-block>`.
+
+### `<code-snippet>` — multi-file code example
+
+- **When**: An example that spans multiple named files.
+- **Avoid when**: Single file — use `<codeblock>`.
+- **Required**: one or more `<file name="..." lang="...">code</file>` children.
+- **Optional on `<code-snippet>`**: `id`.
+- **Required on `<file>`**: `name`.
+- **Optional on `<file>`**: `lang`.
+- **Body of `<file>`**: raw code text; use CDATA for multi-line or XML-sensitive code.
+
+```xml
+<code-snippet>
+  <file name="index.ts" lang="ts"><![CDATA[
+export const main = () => console.log('hi');
+]]></file>
+  <file name="package.json" lang="json"><![CDATA[
+{ "type": "module" }
+]]></file>
+</code-snippet>
+```
+
+## Math
+
+### `<math>` — inline or block equation
+
+- **When**: A KaTeX equation.
+- **Required**: equation text in the body.
+- **Optional**: `display` (`"block"` for standalone equation; omit for inline), `color` (only honored on inline math).
+- **Body**: equation source.
+
+```xml
+<p>Inline: <math>E = mc^2</math>.</p>
+
+<math display="block">\int_0^1 x^2\, dx = \tfrac{1}{3}</math>
+
+<p><math color="#ff5577">a^2 + b^2 = c^2</math></p>
+```
+
+The reader chooses `katex-block` vs `katex-inline` based on `display`. Block math is rendered in its own block; inline math sits inside paragraph text.
+
+## Diagrams
+
+### `<mermaid>` — Mermaid diagram
+
+- **When**: A diagram expressible as Mermaid source.
+- **Avoid when**: Freeform / hand-drawn diagram — use `<excalidraw>`.
+- **Required**: none.
+- **Optional**: `id`.
+- **Body**: Mermaid source text. Use `&#10;` to encode newlines if you must keep the body on one line; otherwise normal element text with real newlines is fine.
+
+```xml
+<mermaid>
+flowchart LR
+  A --> B
+  B --> C
+</mermaid>
+```
+
+### `<excalidraw>` — opaque Excalidraw snapshot
+
+- **When**: An opaque drawing snapshot that must round-trip exactly.
+- **Avoid when**: A diagram you would otherwise express in Mermaid — pick `<mermaid>`.
+- **Required**: snapshot body (preferred) or `snapshot` attribute (legacy).
+- **Optional**: `id`, `snapshot` (legacy attribute form).
+- **Body**: opaque JSON inside `<![CDATA[...]]>`. Empty snapshots may be self-closing.
+
+```xml
+<excalidraw><![CDATA[{"elements":[],"appState":{}}]]></excalidraw>
+```
+
+## Callouts and admonitions
+
+### `<alert>` — semantic admonition
+
+- **When**: Inline-of-section semantic admonitions (note, tip, warning, important, caution).
+- **Avoid when**: Top-of-page announcement — use `<banner>`.
+- **Required**: none (empty body allowed).
+- **Optional**: `id`, `type` (`note` default | `tip` | `important` | `warning` | `caution`).
+- **Body**: nested LiteXML block content (usually `<p>...</p>`). Stored as a nested `SerializedEditorState`.
+
+```xml
+<alert type="warning">
+  <p>This operation cannot be undone.</p>
+</alert>
+```
+
+### `<banner>` — prominent editorial notice
+
+- **When**: Page-level announcement or contextual banner.
+- **Avoid when**: Inline admonition — use `<alert>`.
+- **Required**: none.
+- **Optional**: `id`, `type`. Renderer-supported values include `note`, `tip`, `important`, `warning`, `caution`, plus informational `info` and `success`. Pick the value consistent with the target renderer.
+- **Body**: nested LiteXML block content.
+
+```xml
+<banner type="info">
+  <p>The article was updated on 2026-05-16.</p>
+</banner>
+```
+
+## Containers
+
+### `<details>` — collapsible
+
+- **When**: Optional secondary explanation that should default to collapsed.
+- **Avoid when**: Required reading — render inline.
+- **Required**: none.
+- **Optional**: `id`, `summary` (visible collapsed label), `open` (`"true"` to start expanded; omit otherwise).
+- **Body**: block children.
+
+```xml
+<details summary="Implementation notes" open="false">
+  <p>Internals…</p>
+</details>
+```
+
+### `<nested-doc>` — independently editable nested document
+
+- **When**: A nested editor state that the consumer renders or edits as its own document.
+- **Avoid when**: Plain grouping — use `<grid>` or just sequential blocks.
+- **Required**: none.
+- **Optional**: `id`.
+- **Body**: nested LiteXML block content (becomes its own `SerializedEditorState`).
+
+```xml
+<nested-doc>
+  <h3>Nested section</h3>
+  <p>Body.</p>
+</nested-doc>
+```
+
+### `<grid>` — editorial multi-column layout
+
+- **When**: Two-up / three-up editorial layout where each cell is independent.
+- **Avoid when**: Data with row/column semantics — use `<table>`.
+- **Required**: one or more `<cell>...</cell>` children.
+- **Optional**: `id`, `cols` (numeric, default `2`), `gap` (CSS length string, default `16px`).
+- **Body of `<cell>`**: nested LiteXML block content (becomes its own `SerializedEditorState`).
+
+```xml
+<grid cols="3" gap="24px">
+  <cell><h3>A</h3><p>One</p></cell>
+  <cell><h3>B</h3><p>Two</p></cell>
+  <cell><h3>C</h3><p>Three</p></cell>
+</grid>
+```
+
+## Inline annotations
+
+### `<spoiler>` — hidden inline text
+
+- **When**: Text the reader can intentionally reveal.
+- **Avoid when**: A collapsible block — use `<details>`.
+- **Required**: none.
+- **Optional**: none.
+- **Body**: inline children. Must appear inside an inline-accepting parent (e.g. `<p>`).
+
+```xml
+<p>The killer is <spoiler>the butler</spoiler>.</p>
+```
+
+### `<ruby>` — East Asian ruby annotation
+
+- **When**: A base text needs a pronunciation/reading overlay.
+- **Avoid when**: A plain parenthetical — use prose.
+- **Required**: base text in the body.
+- **Optional**: `rt` (the reading).
+- **Body**: inline base text.
+
+```xml
+<p><ruby rt="haklex">Haklex</ruby> エディタ。</p>
+```
+
+### `<mention>` — handle reference
+
+- **When**: A person or account reference that carries platform + handle metadata.
+- **Avoid when**: Plain name with no identity metadata — write prose.
+- **Required**: `platform`, `handle`.
+- **Optional**: none.
+- **Body**: display name text. Defaults to handle if empty.
+
+```xml
+<p>Author: <mention platform="github" handle="innei">Innei</mention>.</p>
+```
+
+### `<tag>` — inline topical label
+
+- **When**: An inline tag chip (`#ai`, `#editor`).
+- **Avoid when**: A document-level section category — use a heading.
+- **Required**: text body.
+- **Optional**: none.
+- **Body**: plain text.
+
+```xml
+<p>Topics: <tag>AI</tag> <tag>Lexical</tag>.</p>
+```
+
+### `<comment>` — inline reviewer annotation
+
+- **When**: An inline note that should render as a reviewer comment (yellow highlight, side margin marker, etc.).
+- **Avoid when**: Reader-facing aside — use prose, `<alert>`, or `<details>`.
+- **Required**: text body.
+- **Optional**: none.
+- **Body**: plain text.
+
+```xml
+<p>The pipeline scales linearly<comment>citation needed</comment>.</p>
+```
+
+### `<footnote>` and `<footnote-section>` — footnotes
+
+- **When**: Academic-style references with collapsible definitions.
+- **Avoid when**: Primary content — keep it in the body.
+
+`<footnote>`:
+
+- **Required**: `ref` — must match a `<def ref="...">` later.
+- **Optional**: none.
+- **Body**: self-closing.
+
+`<footnote-section>`:
+
+- **Required**: one or more `<def ref="...">definition text</def>`.
+- **Optional**: `id` on `<footnote-section>`.
+- **Body**: `<def>` children only.
+
+```xml
+<p>Lexical 0.44<footnote ref="1" /> is the runtime.</p>
+…
+<footnote-section>
+  <def ref="1">See Facebook's Lexical 0.44 release notes.</def>
+</footnote-section>
+```
+
+## Interactive
+
+### `<chat>` — conversation transcript
+
+- **When**: A user/agent or user/user transcript that should render as chat bubbles.
+- **Avoid when**: A normal quote — use `<blockquote>`.
+- **Required**: `<participants>` block + `<messages>` block.
+- **Optional on `<chat>`**: `id`, `variant` (`user-agent` default | `user-user`).
+- **Required on `<participant>`**: `kind` (`user` | `agent`).
+- **Optional on `<participant>`**: `id` (auto-minted if missing), `name`, `avatar`.
+- **Required on `<message>`**: `participant` (matching a participant `id`).
+- **Optional on `<message>`**: `id` (auto-minted if missing).
+- **Body of `<message>`**: plain text.
+
+```xml
+<chat variant="user-agent">
+  <participants>
+    <participant id="u1" kind="user" name="Innei" />
+    <participant id="a1" kind="agent" name="Haklex" />
+  </participants>
+  <messages>
+    <message id="m1" participant="u1">How do I add a node?</message>
+    <message id="m2" participant="a1">Register a reader and a writer in default-registry.ts.</message>
+  </messages>
+</chat>
+```
+
+### `<poll>` — reader choice / survey
+
+- **When**: A live poll readers can vote on.
+- **Avoid when**: A static list of options — use `<ul>` / `<ol>`.
+- **Required**: one `<question>` + one or more `<option>`.
+- **Optional on `<poll>`**: `id`, `poll-id` (auto-minted if missing), `mode` (`single` default | `multiple`), `close-at` (ISO-like timestamp), `show-results` (`always` | `after-vote` | `after-close`).
+- **Optional on `<option>`**: `id` (auto-minted if missing).
+- **Body of `<question>`** / **`<option>`**: plain text.
+
+```xml
+<poll mode="single" show-results="after-vote">
+  <question>Pick a runtime</question>
+  <option>Bun</option>
+  <option>Node</option>
+  <option>Deno</option>
+</poll>
+```
+
+For freshly authored polls, **omit** `poll-id` and option `id` — the reader mints them. Preserve them when editing an existing poll so vote counts stay attached to the right option.
+
+## Internal / agent
+
+### `<agent-diff>` — review/diff marker
+
+- **When**: Internal agent review UI rendering inline diff markers.
+- **Avoid when**: Normal article authoring — do not introduce unless implementing the review pipeline.
+- **Required**: none.
+- **Optional**: `id`, `op` (defaults to `insert`), `entry` (id of a diff entry to link to).
+- **Body**: self-closing.
+
+```xml
+<agent-diff op="insert" entry="diff-7" />
+```
+
+## Cross-cutting rules
+
+- **`id` attribute** on any block-level extension sets `$.blockId`. Omit for fresh content; preserve when editing.
+- **Quoting**: all attribute values must be quoted.
+- **Escaping**: in element text, escape `&` `<` `>` `"` as `&amp;` `&lt;` `&gt;` `&quot;`.
+- **CDATA**: required for opaque JSON snapshots (`<excalidraw>`), strongly recommended for multi-line or XML-sensitive code bodies (`<codeblock>`, `<code-snippet><file>`).
+- **Nested block content** is required inside `<alert>`, `<banner>`, `<nested-doc>`, `<details>`, `<grid><cell>`. The body becomes a fresh `SerializedEditorState` rooted at the container, so Markdown does **not** work inside them.
+- **Canonical tag names** only. Do not emit legacy aliases (`<linkcard>`, `<codesnippet>`, `<nesteddoc>`, `<code-block>`).
+- **Unregistered tags** serialize to `<node type="..." data='{...}' />` — data is preserved but opaque. Always prefer a registered tag.

package/.claude/skills/litexml-authoring/references/nodes-structural.md

@@ -0,0 +1,150 @@
+# Structural and inline-formatting nodes
+
+Tags in this file are the standard CommonMark-shaped building blocks. They are always available without any extension package. Use them to build the prose around extension nodes. If a fragment contains **any** LiteXML extension tag, the surrounding prose must also be expressed via these tags — Markdown syntax is not parsed inside LiteXML fragments.
+
+For the Haklex-specific tags (alerts, banners, code blocks, math, etc.), see [`nodes-extensions.md`](./nodes-extensions.md).
+
+## Block tags
+
+### `<p>` — paragraph
+
+- **When**: Default container for ordinary prose. The body of nearly every block-level extension (`<alert>`, `<banner>`, `<details>`, `<nested-doc>`, `<grid><cell>`, `<blockquote>`, `<li>`) is one or more `<p>` elements.
+- **Avoid when**: The content is a heading, list item, or any specialized container — use the matching tag instead.
+- **Required**: none.
+- **Optional**: `id` (sets `$.blockId` for stable references).
+- **Body**: inline content (text, links, inline formatting tags, inline extension nodes).
+
+```xml
+<p>Plain prose with an <a href="https://example.com">inline link</a>.</p>
+```
+
+### `<h1>` … `<h6>` — headings
+
+- **When**: Section hierarchy and document scan anchors.
+- **Avoid when**: You only want to style text — headings imply structural meaning and contribute to the document outline.
+- **Required**: none.
+- **Optional**: `id`.
+- **Body**: inline content.
+
+```xml
+<h2 id="install">Installation</h2>
+```
+
+### `<blockquote>` — quote
+
+- **When**: Quoted external text or cited excerpt. The reader emits `type: "rich-quote"` when `attribution` is present, otherwise `type: "quote"`. Both hydrate to `RichQuoteNode` in the editor; the distinction is a writer-side optimization for fixtures without attribution.
+- **Avoid when**: Warnings or editorial callouts — use `<alert>` or `<banner>`.
+- **Required**: at least one block child (typically `<p>`).
+- **Optional**: `id`, `attribution` (citation line — author, source, work).
+- **Body**: block children.
+
+```xml
+<blockquote attribution="— Wang Xizhi, Lantingji Xu">
+  <p>未尝不临文嗟悼，不能喻之于怀。</p>
+</blockquote>
+```
+
+### `<ul>`, `<ol>` — lists
+
+- **When**: Sequences of items. `<ul>` for unordered, `<ol>` for ordered. Set `type="check"` on `<ul>` for a task list.
+- **Avoid when**: Two-dimensional comparison — use `<table>` or `<grid>`. Boolean survey choices — use `<poll>`.
+- **Required**: one or more `<li>` children.
+- **Optional on `<ul>`**: `id`, `type="check"`.
+- **Optional on `<ol>`**: `id`, `start` (numeric starting value, default `1`).
+
+```xml
+<ul>
+  <li><p>First</p></li>
+  <li><p>Second</p></li>
+</ul>
+
+<ol start="3">
+  <li><p>Third</p></li>
+</ol>
+
+<ul type="check">
+  <li checked="true"><p>Done</p></li>
+  <li checked="false"><p>Todo</p></li>
+</ul>
+```
+
+### `<li>` — list item
+
+- **Required**: at least one block child.
+- **Optional**: `id`, `checked` (`"true"` / `"false"`, only meaningful inside `<ul type="check">`).
+- **Body**: block children (usually a single `<p>`; nested `<ul>` / `<ol>` is allowed).
+
+### `<table>`, `<tr>`, `<th>`, `<td>` — tables
+
+- **When**: Dense factual comparison with rows and columns.
+- **Avoid when**: Editorial multi-column layout — use `<grid>`.
+- **Required**: `<table>` contains `<tr>`; each `<tr>` contains `<th>` or `<td>`; each cell contains block children (typically `<p>`).
+- **Optional**: `id` on `<table>`.
+- **Body**: cells contain `<p>` (or other block content). Header state is encoded by the tag — `<th>` for headers, `<td>` for data cells.
+
+```xml
+<table>
+  <tr>
+    <th><p>Tag</p></th>
+    <th><p>Use</p></th>
+  </tr>
+  <tr>
+    <td><p>p</p></td>
+    <td><p>Paragraph</p></td>
+  </tr>
+</table>
+```
+
+### `<hr />` — horizontal rule
+
+- **When**: Hard section break.
+- **Required**: self-closing.
+- **Optional**: `id`.
+
+```xml
+<hr />
+```
+
+## Inline tags
+
+### `<a>` — link
+
+- **When**: Inline citation or hyperlink.
+- **Avoid when**: The URL deserves a rich preview — use `<link-card>` (see extensions).
+- **Required**: `href` attribute.
+- **Optional**: `target`, `title`.
+- **Body**: inline children (text and inline formatting tags).
+
+```xml
+<a href="https://example.com" target="_blank" title="More info">Example</a>
+```
+
+`<a>` writers emit either `type: "link"` or `type: "autolink"` depending on origin; both hydrate to a `LinkNode`. From an authoring perspective, always emit `<a>`.
+
+### `<br />` — line break
+
+Soft break inside a paragraph. Self-closing.
+
+### Inline formatting tags
+
+These map to text-node format flags. Wrap inline text only.
+
+| Format      | LiteXML                                                      |
+| ----------- | ------------------------------------------------------------ |
+| Bold        | `<b>text</b>` or `<strong>text</strong>`                     |
+| Italic      | `<i>text</i>` or `<em>text</em>`                             |
+| Strike      | `<s>text</s>`, `<del>text</del>`, or `<strike>text</strike>` |
+| Underline   | `<u>text</u>`                                                |
+| Inline code | `<code>text</code>`                                          |
+| Subscript   | `<sub>text</sub>`                                            |
+| Superscript | `<sup>text</sup>`                                            |
+| Highlight   | `<mark>text</mark>`                                          |
+
+These tags **must** appear inside an inline-accepting parent (`<p>`, `<h1>`-`<h6>`, `<li>`, `<th>`, `<td>`, etc.). Nesting is allowed: `<b><i>both</i></b>`.
+
+## Cross-cutting rules
+
+- **`id` attribute** on any block tag sets `$.blockId`, which is the Lexical-side anchor used by tool calls that need to target a specific block. Omit for fresh content; preserve when editing existing fragments.
+- **Attribute quoting**: all attribute values must be quoted (`<p id="intro">`, not `<p id=intro>`).
+- **XML escaping** in body text: `&amp;`, `&lt;`, `&gt;`, `&quot;`. Use CDATA when the body is opaque or contains many sensitive characters (typically only needed for code / drawing snapshots, not for ordinary prose).
+- **Canonical tag names**: lowercase, hyphenated. Do not emit legacy aliases (`<linkcard>`, `<codesnippet>`, `<nesteddoc>`, `<code-block>`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haklex/rich-litexml",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Bidirectional Lexical SerializedNode <-> XML conversion with plugin registry",
   "repository": {
     "type": "git",
@@ -27,7 +27,8 @@
   },
   "main": "./dist/node.mjs",
   "files": [
-    "dist"
+    "dist",
+    ".claude/skills/litexml-authoring/**"
   ],
   "dependencies": {
     "lexical": "^0.44.0",