orz-paged 0.1.0 → 0.3.0

package/README.md

@@ -1,11 +1,11 @@
 # orz-paged
 
-> **Status: built and browser-verified** — 12 starter templates, 7 light themes,
-> the full document-element set, an in-file editor with a template picker, and a
-> dynamic switch (e.g. exam answer keys). **Not yet published to npm**, so use it
-> from a local checkout: `npm install`, `npm run build`, then
-> `npm run gen -- tests/sample.md` produces a working `.paged.html`. See
-> [DESIGN.md](./DESIGN.md) for the design.
+> **Status: published (v0.1.0) and browser-verified** — 12 starter templates,
+> 7 light themes, the full document-element set, an in-file editor with a
+> template picker, and a dynamic switch (e.g. exam answer keys). Two packages
+> publish in lockstep: [`orz-paged`](https://www.npmjs.com/package/orz-paged)
+> and [`orz-paged-browser`](https://www.npmjs.com/package/orz-paged-browser).
+> See [DESIGN.md](./DESIGN.md) for the design.
 
 Generate a single, self-contained, **editable** `.paged.html` from Markdown — a
 document shown as **print pages** in any browser (A4/Letter, real margins,
@@ -56,8 +56,7 @@ orz-paged --list-templates                        # list the templates
 ```
 
 `--inline` (default) embeds the engine + paged.js + every theme. `--cdn` instead
-references jsDelivr for the engine + theme — but that needs `orz-paged-browser`
-published, so **while orz-paged is unpublished, use the default `--inline`**.
+references jsDelivr for the published `orz-paged-browser` engine + theme.
 **Fonts, web images, and math/diagram libraries always load from CDN** (internet
 assumed) — so files stay small. The document's `{{nyml kind: document}}` block
 (`template:`, `theme:`, …) is the source of truth.
@@ -109,13 +108,22 @@ The package ships an **agent skill** that teaches an AI agent the document forma
 page templates, headers/footers, the curated elements (CVs, letters, exams), and
 the dynamic switch. The quickest way to produce a document is to let an agent do it:
 
-- **Claude Code** — copy `orz-paged-skills/` into `~/.claude/skills/orz-paged/`.
-- **Any agent** — point it at the local `orz-paged-skills/SKILL.md`, then describe
-  what you want.
+- **Any agent** — point it at
+  `https://cdn.jsdelivr.net/npm/orz-paged/orz-paged-skills/SKILL.md`, then
+  describe what you want.
+- **Claude Code** — copy `orz-paged-skills/` into `~/.claude/skills/orz-paged/`
+  from this repo or from the installed npm package.
 
-Once orz-paged is published to npm, the skill will also be loadable from jsDelivr
-(`https://cdn.jsdelivr.net/npm/orz-paged/orz-paged-skills/SKILL.md`), like the other
-orz tools. More install routes: <https://markdown.orz.how/agents.html>
+More install routes: <https://markdown.orz.how/agents.html>
+
+## Host embedding
+
+`.paged.html` files conform to **`orz-host-save@1`**: a platform can embed a
+document in an iframe, announce itself with a `postMessage` handshake, and
+receive saves (`{ source, html }`) instead of the file-system path —
+standalone behavior, Export to PDF, and downloads are unchanged, and nothing
+activates without the handshake. The canonical spec lives in the orz-mdhtml
+repo: [PROTOCOL.md](https://github.com/wangyu16/orz-mdhtml/blob/main/PROTOCOL.md).
 
 ## Security — treat these as programs, not documents
 

package/assets/app.js

@@ -10,6 +10,7 @@
   var CM_BASE = 'https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16';
   var cm = null;
   var rerenderTimer = null;
+  var dirty = false; // edit-state, surfaced to an embedding host (orz-host-dirty)
 
   function $(id) { return document.getElementById(id); }
   function api() { return window.orzpaged; }
@@ -123,6 +124,7 @@
   function applyDynChoiceToSource(key, value) {
     var next = setSourceDynamicChoice(currentSource(), key, value);
     if (next == null) return;
+    setDirty(true);
     if (cm) cm.setValue(next);
     else { var ta = $('orz-ta'); if (ta) ta.value = next; }
     syncSource();
@@ -207,6 +209,7 @@
   }
 
   function scheduleRerender() {
+    setDirty(true);
     if (rerenderTimer) clearTimeout(rerenderTimer);
     rerenderTimer = setTimeout(function () {
       syncSource();
@@ -262,7 +265,10 @@
     return Promise.resolve(false);
   }
   function save() {
-    persist(serialize()).then(function (inPlace) { if (inPlace) toast('Saved'); })
+    // A hosting platform (verified handshake) receives the save instead of the
+    // file system; the host acknowledges with orz-host-saved (see PROTOCOL.md).
+    if (isHosted()) { hostSave(currentSource(), serialize()); return; }
+    persist(serialize()).then(function (inPlace) { if (inPlace) { setDirty(false); toast('Saved'); } })
       .catch(function (e) { if (e && e.name !== 'AbortError') downloadFile(serialize()); });
   }
   function downloadFile(html) {
@@ -274,6 +280,59 @@
     toast('Downloaded a copy');
   }
 
+  /* ---- host embedding (orz-host-save@1) ----
+   * When a platform embeds this file in an iframe and announces the
+   * orz-host-save protocol (spec: PROTOCOL.md in the orz-mdhtml repo), Save
+   * posts the document to the host instead of touching the file system. Never
+   * enabled without the host's hello; protocol messages are accepted only from
+   * window.parent, and after the handshake only from the recorded host origin.
+   * Message content is read as data, never evaluated. Export/PDF keeps working. */
+  var HOST_PROTOCOL = 'orz-host-save';
+  var HOST_VERSION = 1;
+  var hostOrigin = null;    // recorded at handshake; null = unhosted
+  var hostSaveTimer = null; // watchdog for a save awaiting acknowledgement
+
+  function isHosted() { return hostOrigin !== null; }
+  // An opaque embedder (sandboxed/srcdoc host) serializes as the string 'null',
+  // which postMessage rejects as a targetOrigin — fall back to '*' (the payload
+  // contains nothing the host doesn't already have).
+  function hostTarget() { return hostOrigin && hostOrigin !== 'null' ? hostOrigin : '*'; }
+  function hostPost(msg) { try { window.parent.postMessage(msg, hostTarget()); } catch (e) {} }
+  function setDirty(d) {
+    d = !!d;
+    if (dirty === d) return;
+    dirty = d;
+    if (isHosted()) hostPost({ type: 'orz-host-dirty', protocol: HOST_PROTOCOL, version: HOST_VERSION, dirty: d });
+  }
+  function hostSave(src, html) {
+    if (hostSaveTimer) return; // one save in flight at a time
+    hostSaveTimer = setTimeout(function () {
+      hostSaveTimer = null;
+      toast('Save failed — no response from the host'); // document intact, still dirty
+    }, 10000);
+    hostPost({ type: 'orz-host-save', protocol: HOST_PROTOCOL, version: HOST_VERSION, source: src, html: html });
+  }
+  function onHostMessage(event) {
+    // only the embedding parent may speak the protocol
+    if (window.parent === window || event.source !== window.parent) return;
+    var d = event.data;
+    if (!d || typeof d !== 'object') return;
+    // after the handshake, hold the parent to the origin it introduced itself with
+    if (isHosted() && hostOrigin !== 'null' && event.origin !== hostOrigin) return;
+    if (d.type === 'orz-host-hello' && d.protocol === HOST_PROTOCOL && typeof d.version === 'number' && d.version >= 1) {
+      hostOrigin = event.origin;
+      // reply with the highest version we support ≤ the host's (we speak only 1)
+      hostPost({ type: 'orz-host-ready', protocol: HOST_PROTOCOL, version: HOST_VERSION, kind: 'paged' });
+      if (dirty) hostPost({ type: 'orz-host-dirty', protocol: HOST_PROTOCOL, version: HOST_VERSION, dirty: true });
+    } else if (d.type === 'orz-host-saved' && hostSaveTimer) {
+      clearTimeout(hostSaveTimer); hostSaveTimer = null;
+      if (d.ok) { setDirty(false); toast('Saved'); }
+      else { toast('Save failed' + (d.error ? ' — ' + String(d.error) : '')); }
+    }
+  }
+  // listen from script load so an early hello isn't missed
+  window.addEventListener('message', onHostMessage);
+
   /* ---- framework self-update (checked only in edit view) ---- */
   // SECURITY: the update source is HARDCODED here, never read from the file's
   // config — so a tampered/forged file cannot redirect "Update" to fetch
@@ -377,6 +436,7 @@
     // first one would close the wrapper early and leak the rest back in.
     if (cur) next += '\n\n<!-- Previous content (kept below — edit or delete):\n\n'
       + cur.replace(/--+>/g, '--​>') + '\n-->\n';
+    setDirty(true);
     if (cm) { cm.setValue(next); cm.focus(); }
     else { var ta = $('orz-ta'); if (ta) ta.value = next; syncSource(); if (api() && api().refresh) api().refresh(); }
     toast('Started from "' + t.label + '"');

package/dist/browser-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -8,57 +8,11 @@
  * references the published `orz-paged-browser` on jsDelivr. Fonts, images, and the
  * math/diagram libs always load from CDN at view time (DESIGN §4).
  */
-import { readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, basename, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { getBrowserRuntimeScript } from 'orz-markdown/runtime';
-import { PREVIEW_CDN } from 'orz-markdown/preview-frame';
 import { buildHtml } from './template.js';
-import { templateList } from './doc/templates.js';
-const HERE = dirname(fileURLToPath(import.meta.url));
-const ROOT = join(HERE, '..');
-const selfVersion = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version || '0.0.0';
-/** Pinned CDN assets used at view time — sourced from orz-markdown's shared
- *  preview-frame helper so every host app loads identical, tested versions.
- *  Paged is light-only, so highlight.js uses the light (github) stylesheet. */
-const CDN = {
-    katexCss: PREVIEW_CDN.katexCss,
-    mermaidJs: PREVIEW_CDN.mermaidJs,
-    smilesJs: PREVIEW_CDN.smilesJs,
-    chartJs: PREVIEW_CDN.chartJs,
-    hljsJs: PREVIEW_CDN.hljsJs,
-    hljsCss: PREVIEW_CDN.hljsLightCss,
-};
-function findAsset(rel) {
-    const p = join(ROOT, rel);
-    if (!existsSync(p))
-        throw new Error('missing asset: ' + rel + ' (run `npm run build` first)');
-    return p;
-}
-/** Drop a theme's `@import url("./base.css")` — base is inlined separately, so the
- *  relative import points nowhere (404 on http; a fetch hazard on file://). */
-function stripBaseImport(css) {
-    return css.replace(/@import\s+url\(\s*['"]?\.\/base\.css['"]?\s*\)\s*;?/gi, '');
-}
-function loadThemes() {
-    const dir = findAsset('assets/themes');
-    const baseCss = readFileSync(join(dir, 'base.css'), 'utf8');
-    const themes = readdirSync(dir)
-        .filter((f) => f.endsWith('.css') && f !== 'base.css')
-        .map((f) => ({ id: f.replace(/\.css$/, ''), css: stripBaseImport(readFileSync(join(dir, f), 'utf8')) }));
-    return { baseCss, themes };
-}
-/** Load every template's starter skeleton from `assets/templates/<stem>.md`. */
-function loadTemplates() {
-    const dir = findAsset('assets/templates');
-    return templateList().map((t) => ({
-        id: t.id,
-        label: t.label,
-        description: t.description,
-        group: t.group,
-        skeleton: readFileSync(join(dir, t.skeleton + '.md'), 'utf8'),
-    }));
-}
+import { selfVersion, CDN, findAsset, loadThemes, loadTemplates, pickDefaultTheme, composeInlineHtml, } from './lib.js';
 function parseArgs(argv) {
     const a = { mode: 'inline' };
     for (let i = 0; i < argv.length; i++) {
@@ -138,30 +92,39 @@ function main() {
     const inDir = args.input ? dirname(resolve(args.input)) : process.cwd();
     const outPath = args.out ? resolve(args.out) : join(inDir, base + '.paged.html');
     const title = args.title || base;
-    const { baseCss, themes } = loadThemes();
-    const appJs = readFileSync(findAsset('assets/app.js'), 'utf8');
-    const runtime = getBrowserRuntimeScript(); // copy-as-Markdown (+ qr) from orz-markdown
-    let renderer;
+    let html;
+    let themeCount;
     if (args.mode === 'cdn') {
-        renderer = { mode: 'cdn', src: `https://cdn.jsdelivr.net/npm/orz-paged-browser@${selfVersion}/orz-paged.browser.js` };
+        // CDN mode references the published engine on jsDelivr (not inlined), so it
+        // has its own composition; the default inline path shares composeInlineHtml.
+        const { baseCss, themes } = loadThemes();
+        const appJs = readFileSync(findAsset('assets/app.js'), 'utf8');
+        const runtime = getBrowserRuntimeScript(); // copy-as-Markdown (+ qr) from orz-markdown
+        const renderer = {
+            mode: 'cdn',
+            src: `https://cdn.jsdelivr.net/npm/orz-paged-browser@${selfVersion}/orz-paged.browser.js`,
+        };
+        themeCount = themes.length;
+        html = buildHtml({
+            source,
+            title,
+            rendererVersion: selfVersion,
+            renderer,
+            baseCss,
+            themes,
+            defaultTheme: pickDefaultTheme(themes),
+            templates,
+            cdn: CDN,
+            appJs,
+            runtime,
+        });
     }
     else {
-        renderer = { mode: 'inline', js: readFileSync(findAsset('dist/orz-paged.browser.js'), 'utf8') };
+        // Default: fully-inline, via the shared composition used by the library.
+        themeCount = loadThemes().themes.length;
+        html = composeInlineHtml(source, title);
     }
-    const html = buildHtml({
-        source,
-        title,
-        rendererVersion: selfVersion,
-        renderer,
-        baseCss,
-        themes,
-        defaultTheme: themes.some((t) => t.id === 'light-neat-1') ? 'light-neat-1' : (themes[0]?.id ?? 'none'),
-        templates,
-        cdn: CDN,
-        appJs,
-        runtime,
-    });
     writeFileSync(outPath, html, 'utf8');
-    console.log(`Wrote ${outPath} (${args.mode}, ${themes.length} themes)`);
+    console.log(`Wrote ${outPath} (${args.mode}, ${themeCount} themes)`);
 }
 main();

package/dist/doc/dynamic.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Dynamic switch — conditional content driven by the `dynamic_choices` document
+ * setting. Elements carry `data-show-when="key=value"` / `data-hide-when="key=value"`;
+ * at render time non-matching ones are removed and the attribute is stripped from
+ * those that stay. One source can then print several versions (e.g. an exam with
+ * `answer-key: hide` for students and `show` for the instructor key).
+ *
+ * Operates on a live DOM (browser render) so nested removals are correct.
+ */
+/** Normalize a choice key: lowercase, hyphens → underscores (matches settings). */
+export declare function normalizeChoiceKey(key: string): string;
+interface CondEl {
+    getAttribute(name: string): string | null;
+    removeAttribute(name: string): void;
+    remove(): void;
+}
+interface CondRoot {
+    querySelectorAll(sel: string): ArrayLike<CondEl>;
+}
+/**
+ * Resolve every `data-show-when` / `data-hide-when` under `root` against
+ * `choices`, mutating the DOM in place: drop non-matching elements, strip the
+ * attribute from the rest.
+ */
+export declare function applyDynamicChoices(root: CondRoot, choices: Record<string, string>): void;
+/**
+ * Collect the dynamic keys present under `root` and the set of values each is
+ * used with — for building a live switcher UI. Returns key → sorted values.
+ */
+export declare function collectDynamicChoices(root: CondRoot): Record<string, string[]>;
+export {};

package/dist/doc/elements.d.ts

@@ -0,0 +1,16 @@
+/**
+ * orz-paged — built-in document elements.
+ *
+ * `renderElement(spec, ctx)` turns one `{{nyml kind: element}}` block into
+ * semantic HTML + a small scoped stylesheet. Every element is wrapped in
+ * `<section class="orz-element orz-el-<kind>">…</section>`. Markdown-typed
+ * fields go through the injected `ctx.renderInline` / `ctx.renderBlock` so this
+ * module never depends on orz-markdown directly.
+ *
+ * The `css` returned per kind is identical on every call (the assembler dedupes
+ * by kind), uses `var(--accent)` for the accent color, and stays light-only.
+ *
+ * Spec: docs/document-model.md (Built-in Elements) — reimplemented cleanly.
+ */
+import type { ElementSpec, ElementCtx, ElementResult } from '../types.js';
+export declare function renderElement(spec: ElementSpec, ctx: ElementCtx): ElementResult;

package/dist/doc/fonts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Font presets — M3.
+ *
+ * Maps each curated {@link FontPresetName} to a {@link FontPreset}: a CDN
+ * stylesheet URL (`@fontsource/*` served via jsDelivr) plus the matching CSS
+ * `font-family` stack. orz-paged assumes internet access, so fonts load from
+ * the CDN rather than being bundled.
+ *
+ * `system-serif` is the one preset with **no** webfont — it relies on the
+ * platform's Times-style serif and ships an empty `cssUrl`.
+ *
+ * Source of truth for the curated list: `docs/document-model.md` (Tier A) and
+ * `src/types.ts` (`FontPresetName`).
+ */
+import type { FontPreset, FontPresetName } from '../types.js';
+/**
+ * Every curated preset → its CDN stylesheet + CSS family stack. `system-serif`
+ * carries an empty `cssUrl` (no network font).
+ */
+export declare const FONT_PRESETS: Record<FontPresetName, FontPreset>;
+/**
+ * Resolve a preset by name. Unknown names fall back to a webfont-less system
+ * serif (empty `cssUrl`) rather than throwing.
+ */
+export declare function fontPreset(name: string): FontPreset;

package/dist/doc/nyml.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Generic nyml-block scanner — shared by the settings reader (M1) and the
+ * assembler (A1).
+ *
+ * `settings.ts` parses the single `kind: document` block inline; this module is
+ * the reusable version: it finds **every** `{{nyml … }}` block in a source,
+ * parses its YAML-ish `key: value` body (including `key: |` multiline blocks),
+ * reads the `kind:` discriminator, and reports the block's char offsets so a
+ * caller can splice it out / replace it.
+ *
+ * Values are always strings: surrounding quotes are stripped, multiline `|`
+ * blocks are dedented and joined with `\n`. The `{{nyml … }}` grammar matches
+ * what `parseDocSettings` already accepts (`}` is allowed inside the body; only
+ * the first `}}` terminates the block).
+ */
+/** One scanned `{{nyml … }}` block: its kind, parsed fields, and char range. */
+export interface NymlBlock {
+    /** The `kind:` value (e.g. `'document'`, `'element'`), or `''` if absent. */
+    kind: string;
+    /** snake_case field → raw string value (multiline values preserved). */
+    fields: Record<string, string>;
+    /** Offset of the opening `{` of `{{nyml` in `source`. */
+    start: number;
+    /** Offset just past the closing `}}` (so `source.slice(start, end)` is the block). */
+    end: number;
+}
+/**
+ * Scan a source for every `{{nyml … }}` block, in document order. Each result
+ * carries its parsed `kind`, `fields`, and `[start, end)` char offsets. Blocks
+ * inside an HTML comment (`<!-- … -->`) are skipped — so a commented-out element
+ * (e.g. content the editor's template picker preserves) does not render.
+ */
+export declare function scanNymlBlocks(source: string): NymlBlock[];

package/dist/doc/page-css.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Page CSS — M5.
+ *
+ * Turns a fully-resolved {@link DocSettings} into the `@page` rules, margin-box
+ * running headers/footers, page-number counters, `:root` design tokens, and
+ * layout-behavior CSS that paged.js realizes into physical page boxes.
+ *
+ * Behavior SPEC: `docs/document-model.md`; token set + page model:
+ * `docs/dom-contract.md`. Reimplemented cleanly in TS (light-only output).
+ */
+import type { DocSettings } from '../types.js';
+/**
+ * Build the full page CSS string for a document. Pure: depends only on `s`.
+ */
+export declare function buildPageCss(s: DocSettings): string;

package/dist/doc/settings.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Document settings — M1.
+ *
+ * Reads the single `{{nyml kind: document}}` block from a Markdown source,
+ * normalizes its snake_case keys into a {@link DocSettingsLayer}, and merges
+ * template + user layers over {@link DEFAULTS} into a fully-resolved
+ * {@link DocSettings}.
+ *
+ * Source of truth for defaults and aliases: `docs/document-model.md`
+ * (the curated subset; see DESIGN.md §8).
+ */
+import type { DocSettings, RawDocSettings, DocSettingsLayer } from '../types.js';
+/** Every field at its documented default (docs/document-model.md). */
+export declare const DEFAULTS: DocSettings;
+/**
+ * Locate the first `{{nyml ... }}` block whose body declares `kind: document`,
+ * parse its `key: value` lines (including `key: |` multiline blocks) into a
+ * {@link RawDocSettings}, and return the source with that block removed so it
+ * is not rendered as content. No document block → `{ raw: {}, body: source }`.
+ */
+export declare function parseDocSettings(source: string): {
+    raw: RawDocSettings;
+    body: string;
+};
+/**
+ * Map snake_case raw keys → camelCase {@link DocSettings} fields, coercing
+ * types and normalizing aliases. Only keys present in `raw` are included;
+ * unknown keys are ignored.
+ */
+export declare function normalizeRawToLayer(raw: RawDocSettings): DocSettingsLayer;
+/**
+ * Shallow-merge layers left → right (later wins). Intended use:
+ * `mergeSettings(DEFAULTS, templateLayer, userLayer)`.
+ */
+export declare function mergeSettings(...layers: DocSettingsLayer[]): DocSettings;

package/dist/doc/templates.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Curated document templates — LAYOUT defaults + a starter skeleton.
+ *
+ * Responsibility split: a **template** owns layout only (page size, margins,
+ * furniture, and which elements appear / where). A **theme** owns the look —
+ * font, accent/decoration color, and element styling — so the same theme renders
+ * the same across every template (see ../doc/theme-fonts.ts + assets/themes/*).
+ * The default theme is `light-academic-1` (settings.ts DEFAULTS.theme).
+ *
+ * Each template carries:
+ *   - a {@link DocSettingsLayer} of *layout defaults* (page size; no font/theme),
+ *     merged under any `kind: document` field the user sets,
+ *   - picker metadata (`label`, `description`, `group`),
+ *   - a `skeleton` stem naming the starter Markdown in `assets/templates/<stem>.md`.
+ *
+ * `article` / `report` / `exam` ship in two variants — `-page` (a dedicated
+ * title/cover page) and `-section` (title-on-content) — that differ only in their
+ * skeleton (the title element's `placement: page | section`). Legacy names
+ * (`article`/`report`/`exam`) resolve to the `-section` variant.
+ */
+import type { TemplateName, DocSettingsLayer } from '../types.js';
+export interface TemplateDef {
+    /** Friendly name for the picker, e.g. "Article — title page". */
+    label: string;
+    /** One-line description (picker tooltip). */
+    description: string;
+    /** Grouping for the picker, e.g. "Article". */
+    group: string;
+    /** Starter-markdown file stem: `assets/templates/<skeleton>.md`. */
+    skeleton: string;
+    /** Settings defaults this template applies. */
+    settings: DocSettingsLayer;
+}
+/** The 10 curated templates. */
+export declare const TEMPLATES: Record<TemplateName, TemplateDef>;
+/** Canonicalize a (possibly legacy) template name, or `undefined` if unknown. */
+export declare function canonicalTemplate(name: string): TemplateName | undefined;
+/** Return a template's *settings* defaults layer, or `{}` for an unknown name. */
+export declare function resolveTemplate(name: TemplateName | string): DocSettingsLayer;
+/** The starter-markdown file stem for a template, or `undefined` if unknown. */
+export declare function templateSkeletonName(name: TemplateName | string): string | undefined;
+/** Picker catalog: id + metadata for every template (no settings/skeleton text). */
+export declare function templateList(): Array<{
+    id: TemplateName;
+    label: string;
+    description: string;
+    group: string;
+    skeleton: string;
+}>;

package/dist/doc/theme-fonts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Theme typography — each theme OWNS its font (alongside its colors + element
+ * style in the theme CSS). The engine loads the active theme's webfonts at view
+ * time and the theme CSS sets the matching `--font-body` / `--font-heading`, so
+ * the same theme yields the same font across every template. An explicit
+ * `font_preset` in the document settings still overrides this (page CSS wins).
+ */
+import type { ThemeName, FontPresetName } from '../types.js';
+export declare const THEME_FONTS: Record<ThemeName, {
+    body: FontPresetName;
+    heading: FontPresetName;
+}>;

package/dist/lib.d.ts

@@ -0,0 +1,59 @@
+import { type ThemeAsset, type TemplateAsset } from './template.js';
+export declare const selfVersion: string;
+/** Pinned CDN assets used at view time — sourced from orz-markdown's shared
+ *  preview-frame helper so every host app loads identical, tested versions.
+ *  Paged is light-only, so highlight.js uses the light (github) stylesheet. */
+export declare const CDN: {
+    katexCss: "https://cdn.jsdelivr.net/npm/katex@0.16.35/dist/katex.min.css";
+    mermaidJs: "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js";
+    smilesJs: "https://unpkg.com/smiles-drawer@1.0.10/dist/smiles-drawer.min.js";
+    chartJs: "https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js";
+    hljsJs: "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js";
+    hljsCss: "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css";
+};
+export declare function findAsset(rel: string): string;
+/** Drop a theme's `@import url("./base.css")` — base is inlined separately, so the
+ *  relative import points nowhere (404 on http; a fetch hazard on file://). */
+export declare function stripBaseImport(css: string): string;
+export declare function loadThemes(): {
+    baseCss: string;
+    themes: ThemeAsset[];
+};
+/** Load every template's starter skeleton from `assets/templates/<stem>.md`. */
+export declare function loadTemplates(): TemplateAsset[];
+/** The default theme id, matching the CLI: prefer `light-neat-1`, else the first
+ *  loaded theme, else `'none'`. */
+export declare function pickDefaultTheme(themes: ThemeAsset[]): string;
+/**
+ * The shared inline composition — called by both the CLI (`--inline`, the
+ * default) and {@link buildPagedHtml}. Loads all assets from the package, builds
+ * an inline renderer, and returns the full document string. Deterministic: paged
+ * has no per-document random id, so the same `(source, title, theme?)` always
+ * yields byte-identical output.
+ *
+ * @param theme  optional theme id; when omitted (or unknown) the default theme
+ *               ({@link pickDefaultTheme}) drives the picker's initial selection.
+ */
+export declare function composeInlineHtml(source: string, title: string, theme?: string): string;
+/**
+ * Generate a self-contained `.paged.html` document, fully inline.
+ *
+ * Mirrors the CLI's default `--inline` mode; the returned string is
+ * byte-identical to CLI inline output for the same source/title/theme.
+ *
+ * @param opts.markdown  the document source (the host passes content).
+ * @param opts.title     `<title>` + generator title; defaults to `'Untitled'`.
+ * @param opts.theme     initial theme id; unknown/omitted → the default theme.
+ * @param opts.template  a starter-skeleton selector, mirroring the CLI's
+ *   `--template <name>` with no input file: used as the source ONLY when
+ *   `opts.markdown` is empty/whitespace. When `markdown` has content, it wins.
+ *   The full template catalog is always embedded regardless (it powers the
+ *   in-editor picker), so this never changes the catalog — only the initial
+ *   source. An unknown template name is ignored (falls back to `markdown`).
+ */
+export declare function buildPagedHtml(opts: {
+    markdown: string;
+    title?: string;
+    theme?: string;
+    template?: string;
+}): string;