npm - @haklex/rich-litexml - Versions diffs - 0.15.2 → 0.15.4 - Mend

@haklex/rich-litexml 0.15.2 → 0.15.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/package.json CHANGED Viewed

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

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

@@ -1,86 +0,0 @@
----
-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 DELETED Viewed

@@ -1,141 +0,0 @@
-# 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 DELETED Viewed

@@ -1,166 +0,0 @@
-# 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 DELETED Viewed

@@ -1,399 +0,0 @@
-# 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 DELETED Viewed

@@ -1,150 +0,0 @@
-# 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>`).