orz-markdown 1.2.2 → 1.3.1

package/orz-markdown-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orz-markdown
-description: "orz-markdown usage skill. Use this skill whenever you need to render markdown with this parser, write markdown that uses {{...}} custom plugin syntax (mermaid, qrcode, youtube, smiles, toc, span, emoji, attrs, space, yaml, nyml, or their aliases mm/qr/yt/sm/sp/em), use :::container syntax (success/info/warning/danger/spoil/tabs/tab/cols/col/left/right/center), set up a complete HTML page to display parser output, choose or import one of the 10 bundled CSS themes, or create a custom theme stylesheet. Also invoke when asked about .markdown-body class, prepareSources, browser runtime scripts for QR codes or tabs, or any KaTeX math syntax in this project. ALWAYS invoke before editing documents whose headings carry stable block IDs ({{attrs[#blk-...]}})."
+description: "orz-markdown usage skill. Use this skill whenever you need to render markdown with this parser, write markdown that uses {{...}} custom plugin syntax (mermaid, chart, qrcode, youtube, smiles, toc, span, emoji, attrs, space, yaml, nyml, or their aliases mm/qr/yt/sm/sp/em), use :::container syntax (success/info/warning/danger/spoil/tabs/tab/cols/col/left/right/center), set up a complete HTML page to display parser output, choose or import one of the 12 bundled CSS themes, or create a custom theme stylesheet. Also invoke when asked about .markdown-body class, prepareSources, browser runtime scripts for QR codes or tabs, or any KaTeX math syntax in this project. ALWAYS invoke before editing documents whose headings carry stable block IDs ({{attrs[#blk-...]}})."
 compatibility:
   runtime: "Node.js 20+, ESM"
   package: "orz-markdown"
@@ -8,7 +8,7 @@ compatibility:
 
 # orz-markdown
 
-A deeply customized `markdown-it` instance with 10+ plugins, 9 official plugin bundles, and 10 ready-to-use CSS themes. All rendered HTML lives inside `<article class="markdown-body">`.
+A deeply customized `markdown-it` instance with 10+ custom plugins, 10 official plugin bundles, and 12 ready-to-use CSS themes. All rendered HTML lives inside `<article class="markdown-body">`.
 
 ## Rendering (Node.js / ESM)
 
@@ -38,14 +38,16 @@ const html = md.render(resolved, { markdownBasePath: '/local/base/path' });
 
 Every page that displays parser output needs **all five** of these:
 
-1. **Theme stylesheet** — one of the 10 bundled themes, or `assets/minimal.css`
+1. **Theme stylesheet** — one of the 12 bundled themes, or `assets/minimal.css`
 2. **KaTeX CSS** — `https://cdn.jsdelivr.net/npm/katex@0.16.35/dist/katex.min.css`
 3. **Highlight.js CSS** — match light/dark to the chosen theme
-4. **Three CDN scripts** — Highlight.js, Mermaid.js, SmilesDrawer (loaded in body)
+4. **Four CDN scripts** — Highlight.js, Mermaid.js, SmilesDrawer, Chart.js (loaded in body)
 5. **Two inline scripts** — tabs initializer and QR code runtime (also in body)
 
 **Use `assets/template.html`** — all CDN links, scripts, and the `.markdown-body` wrapper are pre-wired. Copy it and replace the `<!-- INSERT RENDERED HTML HERE -->` comment.
 
+**Mounting output in an `<iframe>` (viewer / editor / slide or page engine)?** Call `getPreviewFrameAssets()` from `orz-markdown/preview-frame` — it returns the pinned CDN URLs, the runtime, `headLinks(scheme)` / `bodyScripts()` strings, and a `window.__orzEnhance()` that does all of items 3–5 (highlight code, draw mermaid/SMILES/charts, init tabs + QR). One call instead of re-deriving the wiring. See `references/embedding.md`.
+
 CDN URLs (pinned versions):
 | Library | URL |
 |---|---|
@@ -54,6 +56,7 @@ CDN URLs (pinned versions):
 | Highlight.js dark CSS | `.../styles/atom-one-dark.min.css` |
 | Mermaid.js | `https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js` |
 | SmilesDrawer | `https://unpkg.com/smiles-drawer@1.0.10/dist/smiles-drawer.min.js` |
+| Chart.js | `https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js` |
 
 ### Browser runtime API
 
@@ -69,20 +72,22 @@ document.body.appendChild(script);
 
 The runtime also provides **copy-as-Markdown**: with it loaded, copying a selection inside `.markdown-body` puts Markdown source on the clipboard, not HTML (tables, lists, math, code, etc. are reconstructed). It skips selections inside `<input>`/`<textarea>`/`contenteditable`. Convert a node directly with `window.OrzMarkdownRuntime.elementToMarkdown(node)`.
 
-> **Do not strip `data-md` attributes.** `mermaid`, `smiles`, `qrcode`, and `youtube` output carry a `data-md` breadcrumb so copy recovers their source after client-side rendering (e.g. a copied QR yields `{{qr ...}}`, not its SVG). Preserve these attributes if you post-process the HTML.
+> **Do not strip `data-md` attributes.** `mermaid`, `smiles`, `qrcode`, `youtube`, and `chart` output carry a `data-md` breadcrumb so copy recovers their source after client-side rendering (e.g. a copied QR yields `{{qr ...}}`, not its SVG). Preserve these attributes if you post-process the HTML.
 
 ---
 
 ## Themes
 
-Ten bundled themes — each auto-imports `common.css` (structural rules for tables, images, QR overlays, print).
+Twelve bundled themes — each auto-imports `common.css` (structural rules for tables, images, QR overlays, print).
 
 | File | Style | Scheme |
 |---|---|---|
 | `dark-elegant-1.css` | Cinzel headings · scholarly serif | Dark |
 | `dark-elegant-2.css` | Dark elegant variant | Dark |
+| `dark-elegant-3.css` | Lora · VS Code-dark, colourful headings "Nocturne" | Dark |
 | `light-neat-1.css` | Figtree · clean modern sans | Light |
 | `light-neat-2.css` | Light neat variant | Light |
+| `light-neat-3.css` | Bricolage · calm green "Orchard" | Light |
 | `beige-decent-1.css` | Warm beige · print-like prose | Light |
 | `beige-decent-2.css` | Beige decent variant | Light |
 | `light-academic-1.css` | Alegreya · justified scholarly prose | Light |
@@ -98,7 +103,7 @@ import 'orz-markdown/themes/light-neat-1.css';
 // <link rel="stylesheet" href="node_modules/orz-markdown/themes/light-neat-1.css">
 ```
 
-For custom themes start from `assets/minimal.css` (structural only, no decoration) and add your visual layer. See `references/themes.md` for the design token pattern, element checklist, and design guidelines. See `references/css-classes.md` for the full list of every CSS class the parser emits.
+For custom themes start from `assets/minimal.css` (structural only, no decoration) and add your visual layer. See `references/themes.md` for the design token pattern, element checklist, and design guidelines. See `references/css-classes.md` for the full list of every CSS class the parser emits. **Building a host app that supplies its own CSS and page shell (a slide engine, viewer, or editor)?** Read `references/embedding.md` — it gathers the CSS contract, the JS runtime + diagram-drawing duties, and the copy-as-Markdown requirements into one checklist (and the non-obvious gotchas, like a host CSS reset stripping bold/sub/sup).
 
 ---
 
@@ -115,11 +120,12 @@ Escape with backslash: `\{{name}}` renders as literal `{{name}}`.
 |---|---|---|
 | **span** | `sp` | `{{sp[red] colored}}` · `{{sp[success] ✓ Done}}` |
 | **emoji** | `em` | `{{emoji wave}}` · `{{em tada}}` |
-| **space** | — | `{{space 4}}` → 4 × `&nbsp;` |
+| **space** | — | `{{space 4}}` → 4rem-wide inline-block spacer |
 | **qrcode** | `qr` | `{{qr https://example.com}}` (click-to-expand SVG) |
 | **youtube** | `yt` | `{{youtube dQw4w9WgXcQ}}` (responsive iframe) |
 | **mermaid** | `mm` | `{{mm\ngraph LR\nA-->B\n}}` |
 | **smiles** | `sm` | `{{smiles C1=CC=CC=C1}}` (chemical structure) |
+| **chart** | — | `{{chart\ntype: bar\nlabels: A, B\ndata: 1, 2\n}}` (Chart.js bar/line/pie/doughnut) |
 | **toc** | — | `{{toc}}` or `{{toc 2,3}}` (heading levels) |
 | **attrs** | — | `# Title{{attrs[id="hero"]}}` |
 | **markdown** | `md`, `md-include` | `{{md ./path/to/file.md}}` |
@@ -173,7 +179,8 @@ Documents may carry stable block IDs on headings: `## Title{{attrs[#blk-abc12345
 |---|---|
 | `references/syntax.md` | Full syntax with examples for every plugin, container, and extended markdown feature |
 | `references/block-ids.md` | Stable block-ID preservation rules — REQUIRED reading before editing documents that use `{{attrs[#blk-...]}}` |
-| `references/themes.md` | Custom theme guide: design tokens, element checklist, 10 design guidelines |
+| `references/themes.md` | Custom theme guide: design tokens, element checklist, 12 design guidelines |
 | `references/css-classes.md` | Every CSS class and HTML element the parser emits — the spec for theme authors |
+| `references/embedding.md` | Host-integration guide for apps that bring their own CSS/shell (slide engines, viewers, editors): the CSS contract + reset gotchas, the JS runtime + diagram drawing, and what copy-as-Markdown needs |
 | `assets/template.html` | Ready-to-use HTML page template with all scripts and CDN links wired up |
 | `assets/minimal.css` | Structural-only stylesheet — starting point for custom themes |

package/orz-markdown-skills/assets/template.html

@@ -19,8 +19,8 @@
 
   <!-- Parser stylesheet — choose one of the bundled themes or link your own.
        Bundled themes (each imports common.css automatically):
-         dark-elegant-1.css  dark-elegant-2.css
-         light-neat-1.css    light-neat-2.css
+         dark-elegant-1.css  dark-elegant-2.css  dark-elegant-3.css
+         light-neat-1.css    light-neat-2.css    light-neat-3.css
          beige-decent-1.css  beige-decent-2.css
          light-academic-1.css light-academic-2.css
          light-playful-1.css  light-playful-2.css
@@ -64,6 +64,26 @@ if (typeof SmilesDrawer !== 'undefined') {
 }
   </script>
 
+  <!-- Chart.js — renders {{chart}} canvases emitted by the parser. -->
+  <script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
+  <script>
+if (typeof Chart !== 'undefined') {
+  document.querySelectorAll('canvas.orz-chart[data-chart]').forEach(function (canvas) {
+    var wrap = document.createElement('div');
+    wrap.style.cssText = 'position:relative;width:100%;max-width:520px;margin:.6em auto';
+    canvas.parentNode.insertBefore(wrap, canvas);
+    wrap.appendChild(canvas);
+    canvas.removeAttribute('width');
+    canvas.removeAttribute('height');
+    try {
+      var config = JSON.parse(canvas.getAttribute('data-chart') || '{}');
+      config.options = Object.assign({ responsive: true, maintainAspectRatio: true, animation: false }, config.options || {});
+      new Chart(canvas, config);
+    } catch (e) {}
+  });
+}
+  </script>
+
   <!-- Tabs component — builds the .tabs-bar and activates .tab panels.
        Must run after the DOM is painted so .tabs elements are found.        -->
   <script>
@@ -184,7 +204,7 @@ if (typeof SmilesDrawer !== 'undefined') {
   // ---- copy-as-markdown: DOM -> Markdown walker ---------------------------
   // Converts a selected DOM fragment back to Markdown so that copying rendered
   // content yields source, not HTML. Standard constructs are reconstructed from
-  // their tags; generated constructs (math, mermaid, smiles, qr, youtube) carry
+  // their tags; generated constructs (math, mermaid, smiles, qr, youtube, chart) carry
   // a [data-md] breadcrumb that is emitted verbatim. Written without template
   // literals/backticks because this whole file is a String.raw template.
   var BT = String.fromCharCode(96);

package/orz-markdown-skills/references/css-classes.md

@@ -193,23 +193,30 @@ span.qrcode { background: #fff; padding: 4px; /* or 6px */ vertical-align: middl
 
 Note: `span.success/info/warning/danger` also have `display: inline-flex; align-items: center; line-height: 1; white-space: nowrap` set by `common.css`. Add `padding`, `border-radius`, `font-size`, and colors in the theme.
 
+### Chart
+
+| Class | Element | Description |
+|---|---|---|
+| `canvas.orz-chart` | `<canvas>` | Carries a Chart.js config as HTML-escaped JSON in `data-chart` (and a `data-md` breadcrumb). The host runtime reads `data-chart` and calls Chart.js. Cap its width. |
+
+```css
+canvas.orz-chart { max-width: 100%; height: auto; }
+```
+
 ### Table of Contents
 
 | Class | Element | Description |
 |---|---|---|
-| `.toc-wrapper` | `<div>` | Outer wrapper (for positioning). |
-| `nav.toc` / `.toc-list` | `<nav>` | The `<ul>` tree of heading links. Reset list bullets in TOC context. |
+| `.toc-list` | `<ul>` | The flat `<ul>` of heading links emitted by `{{toc}}`. Each `<li>` carries an inline `padding-left` for its depth. Reset list bullets. This is the **only** class the parser emits for the TOC. |
 
 ```css
-nav.toc, .toc-list {
-  padding: ...;
-  border: 1px solid var(--border);
-}
-nav.toc ul, .toc-list ul { margin: 0; padding-left: 1.1rem; }
-nav.toc li, .toc-list li { list-style: none; margin-bottom: 0.25rem; }
-nav.toc a, .toc-list a { text-decoration: none; color: var(--link); }
+.toc-list { padding: ...; border: 1px solid var(--border); list-style: none; }
+.toc-list li { list-style: none; margin-bottom: 0.25rem; }
+.toc-list a  { text-decoration: none; color: var(--link); }
 ```
 
+> Note: the parser does **not** emit a `<nav class="toc">` wrapper or a `.toc-wrapper`. `{{toc}}` produces a single `<ul class="toc-list">`. If your host wants a wrapper, add it around the rendered TOC yourself.
+
 ### Test elements (development only)
 
 | Class | Element | Description |

package/orz-markdown-skills/references/embedding.md

@@ -0,0 +1,196 @@
+# Embedding orz-markdown in a host app (custom stylesheet)
+
+Read this when you call `md.render()` and supply **your own CSS and page shell**
+instead of using a bundled theme — e.g. a slide engine, a doc viewer, an editor,
+or any app that embeds rendered output. The bundled themes already do everything
+below; this guide is the checklist for when you *don't* use them.
+
+> The sibling `orz-slides` project hit a long tail of bugs (unstyled containers,
+> bold that changed colour instead of weight, broken sub/sup, diagrams
+> overflowing, copy losing `{{sp}}`/`:::` source) precisely because these points
+> weren't gathered in one place. Follow this and you skip all of it.
+
+There are **three** things to get right: CSS, JavaScript, and copy-as-Markdown.
+
+> **Shortcut for iframe hosts — `getPreviewFrameAssets()`.** Most of the
+> JavaScript below is the same everywhere, so it lives in one helper:
+>
+> ```js
+> import { getPreviewFrameAssets } from 'orz-markdown/preview-frame';
+> const pa = getPreviewFrameAssets();
+> ```
+>
+> It returns the pinned CDN URLs (`pa.cdn`), the runtime (`pa.runtimeScript`), and
+> ready-made strings: `pa.headLinks(scheme)` (KaTeX + highlight.js CSS, the hljs
+> link carries `id="orz-hljs"`) for the iframe `<head>`, and `pa.bodyScripts()`
+> (loads the libs + runtime and defines `window.__orzEnhance()`) for the `<body>`.
+> After each render call `window.__orzEnhance()` — it highlights code, runs
+> mermaid, draws SMILES (honoring `window.__orzSmilesTheme`) and charts, and
+> re-inits the runtime (tabs + QR). On theme change swap
+> `doc.getElementById('orz-hljs').href = pa.hljsCss(scheme)`. `__orzEnhance`
+> scopes to `.markdown-body`, so it works whatever id/wrapper you use. The rest of
+> this page is what that helper does under the hood — read it if you hand-roll the
+> wiring or need to understand a failure.
+
+---
+
+## 1. CSS
+
+The parser emits plain HTML plus plugin/container classes. Two reference docs
+have the full detail:
+
+- `references/css-classes.md` — every class and element the parser emits.
+- `references/themes.md` — the element checklist and design guidance.
+
+When you bring your own stylesheet, the four things that bite hardest:
+
+### 1a. Wrap output in `.markdown-body` and scope your rules to it
+
+```html
+<article class="markdown-body"> …md.render() output… </article>
+```
+Every theme rule is scoped under `.markdown-body`; copy-as-Markdown also keys off
+this class (§3). For a region-based layout, each rendered region gets its own
+`.markdown-body`.
+
+### 1b. A host CSS *reset* will strip inline semantics — restore them
+
+This is the #1 non-obvious failure. Many app/framework resets (notably
+**reveal.js**'s `reset.css`) apply to `strong, b, em, i, sub, sup, small, …`:
+
+```css
+em, strong, sub, sup, b, i, small, … { font: inherit; font-size: 100%; vertical-align: baseline; }
+```
+
+`font: inherit` wipes `font-weight`/`font-style`, and `vertical-align: baseline`
++ `font-size: 100%` flattens sub/sup. The result: **bold isn't bold, italic
+isn't italic, H~2~O / x^2^ render flat.** (A theme that "fixed" bold with
+`strong { color: accent }` then makes bold *vanish* wherever the accent equals
+the background.) If your host has any such reset, restore the semantics
+explicitly — **bold is weight, not colour**:
+
+```css
+.markdown-body strong, .markdown-body b { font-weight: 700; }
+.markdown-body em, .markdown-body i     { font-style: italic; }
+.markdown-body s,  .markdown-body del   { text-decoration: line-through; }
+.markdown-body ins,.markdown-body u     { text-decoration: underline; }
+.markdown-body sub, .markdown-body sup  { font-size: 0.75em; line-height: 0; position: relative; vertical-align: baseline; }
+.markdown-body sub { bottom: -0.3em; }
+.markdown-body sup { top: -0.5em; }
+```
+
+### 1c. Style **every** plugin/container class, or it renders unstyled
+
+If you don't ship the bundled `common.css`/theme, these have **no** styling and
+look broken. Minimum set (see `css-classes.md` for the exact selectors):
+
+| Construct | Selectors to style |
+|---|---|
+| Admonitions | `div.info`, `div.success`, `div.warning`, `div.danger` |
+| Spans — colour | `span.red`, `span.green`, `span.blue`, `span.yellow` (colour only) |
+| Spans — badge | `span.success/info/warning/danger` — **need** `display:inline-flex; align-items:center; line-height:1; white-space:nowrap` + padding/radius (normally in `common.css`) |
+| Columns | `.cols` (CSS grid), `.col` |
+| Tabs | `.tabs`, `.tabs-bar`, `.tabs-bar-btn`(`.active`), `.tab`; **`.tabs:not([data-js]) .tab { display:block }`** (no-JS fallback) and `.tabs[data-js] .tab{display:none}` / `.tab.active{display:block}` |
+| Spoiler | `details.spoil`, `summary` |
+| Alignment | `div.left`, `div.center`, `div.right` (`text-align`) |
+| QR | `span.qrcode` — **must** have `background:#fff; padding` (the SVG is black-on-transparent) |
+| YouTube | `.youtube-embed` — the iframe has **no width/height**; make it a 16:9 responsive box or it defaults to 300×150 |
+| Math | `.katex`, `.katex-display` (load `katex.min.css`) |
+| Diagrams/chem | `.mermaid svg`, `.smiles-render canvas` / `canvas[data-smiles]` |
+
+### 1d. Constrain generated graphics so they fit
+
+Mermaid SVGs and smiles/chart canvases have intrinsic sizes and will overflow a
+bounded container. At minimum cap the width; in a fixed-size layout (slides),
+size them to the container in JS (measure the container, set explicit
+width/height by the SVG's `viewBox` aspect; for Chart.js use `responsive:false`
++ explicit `resize(w,h)` because it can't read a definite height through a CSS
+grid). Mermaid also sets an inline `max-width` you may need to override.
+
+```css
+.markdown-body .mermaid svg,
+.markdown-body canvas[data-smiles],
+.markdown-body canvas.orz-chart { max-width: 100%; height: auto; }
+```
+
+---
+
+## 2. JavaScript
+
+Rendering is pure HTML, but several constructs need client-side JS **after mount**.
+
+### 2a. Load the runtime — tabs, QR expand, and copy
+
+```js
+import { getBrowserRuntimeScript } from 'orz-markdown/runtime';
+const s = document.createElement('script');
+s.textContent = getBrowserRuntimeScript();
+document.body.appendChild(s);
+```
+
+It auto-runs `OrzMarkdownRuntime.init(document)` **once** on `DOMContentLoaded`
+and wires the global copy handler. It exposes
+`OrzMarkdownRuntime.{ init, initTabs, initQrCodes, elementToMarkdown }`.
+
+**If you render content dynamically** (after load, or re-render — e.g. an editor
+or a slide engine), the one-time `init` won't see it. Call
+`OrzMarkdownRuntime.init(newRoot)` (or `initTabs`/`initQrCodes`) on the new
+content yourself. `initTabs` guards on `data-js="1"` — if you also have your own
+tab init, use the **same** `data-js="1"` marker so the two don't both build a bar
+(double tab bar bug).
+
+### 2b. The runtime does **not** draw diagrams/charts — you do
+
+mermaid, smiles, and chart canvases are placeholders. Load the libraries and draw
+them (the bundled themes/`tests/example.html` show the calls):
+
+| Construct | You must load | Then |
+|---|---|---|
+| `.mermaid` | mermaid.js | `mermaid.run({ querySelector: '.mermaid' })` |
+| `canvas[data-smiles]` | smiles-drawer | `SmilesDrawer.parse(...)` → `drawer.draw(tree, canvas, scheme, false)` — pass `'dark'` on dark backgrounds so bonds are light |
+| `canvas.orz-chart` | Chart.js | `new Chart(canvas, JSON.parse(canvas.dataset.chart))` |
+| `$…$` / `$$…$$` | KaTeX **CSS** only | math is pre-rendered by `md.render()`; you just need `katex.min.css` |
+
+Draw on first display and re-draw when the container resizes; canvases drawn
+while their container is hidden (`display:none`) size to 0.
+
+---
+
+## 3. Copy-as-Markdown
+
+Selecting rendered content and copying yields **Markdown source** when (and only
+when) all of this holds:
+
+1. **The runtime is loaded** (§2a) — it installs the `copy` handler and the
+   DOM→Markdown walker (`elementToMarkdown`).
+2. **Content is inside `.markdown-body`** (or an element with `data-orz-copy`).
+   The handler ignores selections elsewhere and inside inputs/textareas.
+3. **`data-md` breadcrumbs are preserved.** Generated constructs whose source is
+   otherwise lost — `mermaid`, `smiles`, `qrcode`, `youtube`, `chart` (and any
+   plugin that adds one) — carry `data-md` with their original directive. The
+   walker emits it verbatim. **Never strip `data-md`** when you post-process HTML.
+4. **Plugin/container classes are preserved.** Constructs without a `data-md`
+   are recovered *by class/structure*: `<span class="red">` → `{{sp[red] …}}`,
+   `<div class="center">` → `::: center … :::`, nested `cols`/`tabs` get the
+   right fence length, and a `{{toc}}` is recovered as its rendered list of
+   heading links (not the `{{toc}}` directive). If you rewrite/strip these
+   classes, copy loses the source.
+
+Caveat: a container (`::: center`, `:::: cols`, spoiler, tabs) is recovered only
+when the **selection includes the container element**, not just the text inside
+it — select the whole block/region, not the inner words.
+
+Convert a node directly: `OrzMarkdownRuntime.elementToMarkdown(node)`.
+
+---
+
+## Pre-flight checklist
+
+- [ ] Output wrapped in `.markdown-body`; rules scoped under it.
+- [ ] Inline semantics restored if a host reset touches `strong/em/sub/sup/…` (§1b).
+- [ ] Every admonition / span / cols / tabs / spoil / align / qr / youtube / math / diagram class is styled (§1c, `css-classes.md`).
+- [ ] Span badges have the inline-flex structural CSS; QR has a white plate; tabs have the no-JS fallback; YouTube is a 16:9 box.
+- [ ] Graphics are width-capped (and size-fitted in fixed layouts) (§1d).
+- [ ] Runtime loaded; `init` re-run on dynamically rendered content; tab `data-js="1"` aligned (§2a).
+- [ ] mermaid / smiles-drawer / Chart.js loaded and drawn; KaTeX CSS loaded (§2b).
+- [ ] `data-md` and plugin/container classes preserved end-to-end for copy (§3).

package/orz-markdown-skills/references/syntax.md

@@ -310,10 +310,12 @@ Uses `node-emoji` for name lookup. The emoji text alias (e.g., `wave`, `smile`)
 ### space — Inline horizontal whitespace
 
 ```markdown
-{{space 4}}    →      (4 non-breaking spaces)
-{{space 1}}    →  
+{{space 4}}    → 4rem-wide inline-block spacer
+{{space 1}}    → 1rem-wide inline-block spacer
 ```
 
+The numeric argument is a `rem` width: `{{space 4}}` emits `<span style="display:inline-block;width:4rem"></span>`. Non-positive or non-numeric values render nothing.
+
 ---
 
 ### qrcode / qr — Inline QR code
@@ -381,7 +383,7 @@ Renders `<div class="smiles-render"><canvas data-smiles="...">`. SmilesDrawer.js
 {{toc 1,4}}
 ```
 
-Auto-generates a `<nav class="toc">` from all headings in the document. Optional argument is a comma-separated level range (`min,max`), defaulting to all levels. Must appear after the headings it references in the source (or at the start — the parser makes a pass over the full document).
+Auto-generates a `<ul class="toc-list">` of heading links (each `<li>` indented by depth). Optional argument is a comma-separated level range (`min,max`), defaulting to `1,3`. The placement in the source does not matter — a core rule scans the whole document, so `{{toc}}` works at the top or bottom.
 
 ---
 

package/orz-markdown-skills/references/themes.md

@@ -99,8 +99,8 @@ Follow this section order in every theme file for consistency:
 12. Semantic containers: `.success`, `.info`, `.warning`, `.danger`
 13. Layout utilities: `.left`, `.right`, `.center`
 14. Spoiler, tabs, and columns: `details.spoil`, `.tabs`, `.cols`
-15. TOC and footnotes: `nav.toc`, `.footnotes`
-16. Plugin output: `.youtube-embed`, `.mermaid`, `.smiles-render`, `.qrcode`, span color/badge classes
+15. TOC and footnotes: `.toc-list`, `.footnotes`
+16. Plugin output: `.youtube-embed`, `.mermaid`, `.smiles-render`, `canvas.orz-chart`, `.qrcode`, span color/badge classes
 17. Decorative pseudo-elements and theme-only flourishes
 18. Responsive rules (`@media`)
 19. Print rules (`@media print`)
@@ -165,12 +165,13 @@ Every theme must have CSS rules for all of the following. See `references/css-cl
 - [ ] `.tabs` `.tabs-bar` `.tabs-bar-btn` `.tabs-bar-btn.active` `.tab` `.tab.active`
 - [ ] `.tabs:not([data-js]) .tab` — no-JS fallback: show all panels
 - [ ] `.cols` `.col`
-- [ ] `nav.toc` `.toc-list` — list reset, link styles
+- [ ] `.toc-list` — list reset, link styles (the parser emits only `<ul class="toc-list">`, no `nav.toc` wrapper)
 - [ ] `span.red` `span.yellow` `span.green` `span.blue`
 - [ ] `span.success` `span.info` `span.warning` `span.danger` — inline badge variant
 - [ ] `div.youtube-embed` `div.youtube-embed iframe` — 16:9 responsive wrapper (structural)
 - [ ] `div.mermaid` `div.mermaid svg`
 - [ ] `div.smiles-render` `canvas[data-smiles]`
+- [ ] `canvas.orz-chart` — width-capped (Chart.js draws into it client-side)
 - [ ] `span.qrcode` — **must have `background: #fff`** (SVG is always black-on-white)
 
 ---

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "orz-markdown",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "Customized markdown-it parser with official and custom plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
     "./runtime": "./dist/runtime.js",
+    "./preview-frame": "./dist/preview-frame.js",
     "./themes/*": "./themes/*"
   },
   "files": [
@@ -64,7 +65,9 @@
     "@types/markdown-it-footnote": "^3.0.4",
     "@types/node": "^25.3.5",
     "@types/qrcode-svg": "^1.1.5",
+    "esbuild": "^0.21.5",
     "happy-dom": "^15.11.0",
+    "path-browserify": "^1.0.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/themes/README.md

@@ -0,0 +1,43 @@
+# orz-markdown themes
+
+Twelve ready-to-use CSS themes for the parser's output. All rendered HTML lives
+inside `<article class="markdown-body">`, so every theme is scoped to that class.
+Each theme `@import`s the shared `common.css` (structural rules for tables,
+images, KaTeX blocks, QR overlays, tabs/columns, and print), so you only ever
+import a **single** theme file.
+
+```js
+// With a bundler:
+import 'orz-markdown/themes/light-academic-1.css';
+
+// Or over a CDN (jsDelivr):
+// https://cdn.jsdelivr.net/npm/orz-markdown/themes/light-academic-1.css
+```
+
+## Bundled themes
+
+| File | Style | Scheme |
+|---|---|---|
+| `light-neat-1.css` | Figtree · clean modern sans | Light |
+| `light-neat-2.css` | Light neat variant | Light |
+| `light-neat-3.css` | Bricolage · calm green — "Orchard" | Light |
+| `light-academic-1.css` | Alegreya · justified scholarly prose | Light |
+| `light-academic-2.css` | Light academic variant | Light |
+| `beige-decent-1.css` | Warm beige · print-like prose | Light |
+| `beige-decent-2.css` | Beige decent variant | Light |
+| `light-playful-1.css` | Casual · personal blog | Light |
+| `light-playful-2.css` | Light playful variant | Light |
+| `dark-elegant-1.css` | Cinzel headings · scholarly serif | Dark |
+| `dark-elegant-2.css` | Dark elegant variant | Dark |
+| `dark-elegant-3.css` | Lora · VS Code-dark, colourful headings — "Nocturne" | Dark |
+
+`common.css` is not a theme — it is imported automatically by each theme above.
+
+## Theming your own output
+
+If you supply your **own** stylesheet instead of a bundled theme, the
+[embedding guide](../orz-markdown-skills/references/embedding.md) lists every CSS
+class the parser emits (semantic containers, tabs/columns, spoilers, KaTeX
+blocks, Mermaid/SMILES/chart canvases, clickable QR codes) and the JavaScript the
+browser runtime needs. Start from `common.css` for the structural rules and layer
+your visual design on top.

package/themes/beige-decent-1.css

@@ -27,7 +27,7 @@
   --line-height: 1.7;
 
   --markdown-body-max-width: 800px;
-  --markdown-body-padding: 4rem 2rem;
+  --markdown-body-padding: 2rem 2rem 4rem;
   --markdown-body-border: none;
   --markdown-body-radius: 0;
   --markdown-body-shadow: none;
@@ -56,6 +56,8 @@ body {
 }
 
 /* 2. Headings and body copy */
+.markdown-body > :first-child { margin-top: 0; }
+
 .markdown-body h1,
 .markdown-body h2,
 .markdown-body h3,
@@ -556,4 +558,27 @@ body {
     box-shadow: none;
   }
 
-}
+}
+/* code block — warm paper panel */
+.markdown-body pre { background: #f5f0e6; border: 1px solid #e7ddc9; border-radius: 8px; }
+.markdown-body pre code, .markdown-body pre code.hljs { background: transparent; padding: 0; }
+
+
+/* ============ modern decorative refresh ============ */
+/* blockquote — warm card with a soft corner quote glyph (replaces the top/bottom rules) */
+.markdown-body blockquote { position: relative; border: none; background: #f3ece0; border-radius: 12px;
+  padding: 1.1rem 1.4rem 1.1rem 1.6rem; margin: 1.9rem 0; font-style: italic; color: #5a4d42;
+  box-shadow: 0 2px 10px rgba(120, 90, 50, 0.06); }
+.markdown-body blockquote::before { content: '“'; position: absolute; left: 0.55rem; top: -0.3rem;
+  font-family: Georgia, serif; font-size: 2.6em; line-height: 1; color: #c8a98a; opacity: 0.55; }
+.markdown-body blockquote p { margin: 0 0 0.6em; } .markdown-body blockquote > :last-child { margin-bottom: 0; }
+.markdown-body blockquote blockquote { background: rgba(255, 255, 255, 0.4); box-shadow: none; }
+.markdown-body blockquote blockquote::before { display: none; }
+/* callouts — rounder, softer */
+.markdown-body .info, .markdown-body .success, .markdown-body .warning, .markdown-body .danger { border-radius: 10px; }
+
+/* spoiler — add a chevron indicator */
+.markdown-body details.spoil > summary { display: flex; align-items: center; gap: 0.55rem; list-style: none; }
+.markdown-body details.spoil > summary::-webkit-details-marker { display: none; }
+.markdown-body details.spoil > summary::before { content: '▸'; color: #b09a78; transition: transform 0.2s; }
+.markdown-body details.spoil[open] > summary::before { transform: rotate(90deg); }

package/themes/beige-decent-2.css

@@ -31,7 +31,7 @@
   --line-height: 1.8;
 
   --markdown-body-max-width: 760px;
-  --markdown-body-padding: 5rem 2rem;
+  --markdown-body-padding: 2.5rem 2rem 5rem;
   --markdown-body-border: none;
   --markdown-body-radius: 0;
   --markdown-body-shadow: none;
@@ -59,6 +59,8 @@ body {
 }
 
 /* 2. Headings and body copy */
+.markdown-body > :first-child { margin-top: 0; }
+
 .markdown-body h1,
 .markdown-body h2,
 .markdown-body h3,
@@ -545,7 +547,6 @@ body {
 @media (max-width: 640px) {
   .markdown-body {
     padding: 2.5rem 1.25rem;
-    font-size: 15px;
   }
   .markdown-body .left {
     float: none;
@@ -575,4 +576,23 @@ body {
     box-shadow: none;
   }
 
-}
+}
+/* code block — warm paper panel */
+.markdown-body pre { background: #f6f1e7; border: 1px solid #e6dac3; border-radius: 8px; box-shadow: 0 1px 2px rgba(120,90,50,.06); }
+.markdown-body pre code, .markdown-body pre code.hljs { background: transparent; padding: 0; color: inherit; }
+
+
+/* ============ modern decorative refresh ============ */
+/* blockquote — warm tint with a teal accent edge (pseudo-bar, not a heavy border) */
+.markdown-body blockquote { position: relative; background: #efe7d8; border: none; border-radius: 0 10px 10px 0;
+  padding: 0.9rem 1.3rem; margin: 1.9rem 0; font-style: italic; color: var(--text-muted); overflow: hidden; }
+.markdown-body blockquote::before { content: ''; position: absolute; left: 0; top: 0; bottom: 0; width: 4px;
+  background: var(--link-color); }
+.markdown-body blockquote p:last-child { margin-bottom: 0; }
+.markdown-body blockquote blockquote { background: rgba(255, 255, 255, 0.35); }
+
+/* spoiler — add a chevron indicator */
+.markdown-body details.spoil > summary { display: flex; align-items: center; gap: 0.55rem; list-style: none; }
+.markdown-body details.spoil > summary::-webkit-details-marker { display: none; }
+.markdown-body details.spoil > summary::before { content: '▸'; color: #9c8a6f; transition: transform 0.2s; }
+.markdown-body details.spoil[open] > summary::before { transform: rotate(90deg); }

package/themes/dark-elegant-1.css

@@ -727,3 +727,14 @@ details.spoil > summary:focus-visible {
     page-break-inside: avoid;
   }
 }
+
+/* code: uniform dark panel (no highlight.js inner box) */
+.markdown-body pre code, .markdown-body pre code.hljs { background: transparent; padding: 0; }
+
+
+/* ---- mermaid & charts: light panel for legibility on the dark background ---- */
+.markdown-body div.mermaid { background: rgba(255, 255, 255, 0.88); border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 10px; padding: 1.1rem; box-shadow: 0 1px 8px rgba(0, 0, 0, 0.22); }
+.markdown-body div.mermaid svg { max-width: 100%; height: auto; }
+.markdown-body canvas.orz-chart { background: rgba(255, 255, 255, 0.88); border-radius: 10px; padding: 0.6rem;
+  box-shadow: 0 1px 8px rgba(0, 0, 0, 0.22); max-width: 100%; height: auto; }