orz-paged 0.2.0 → 0.4.0

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,62 @@
+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, delivery?: 'inline' | 'cdn'): 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;
+    /** `inline` (default, offline) or `cdn` (small file — engine from jsDelivr;
+     *  requires orz-paged-browser published at this version). */
+    delivery?: 'inline' | 'cdn';
+}): string;

package/dist/lib.js

@@ -0,0 +1,143 @@
+/**
+ * orz-paged library entry — generate a self-contained `.paged.html` in-process.
+ *
+ * This is the programmatic twin of the CLI's default (`--inline`) render path: a
+ * host platform calls {@link buildPagedHtml} and gets back the FULL document
+ * string, fully inline (inlined engine bundle + inlined base/theme CSS + full
+ * template catalog + embedded source). Math/diagram/font libs still load from
+ * CDN at view time — exactly as the CLI's inline output does.
+ *
+ * Both the CLI and this module compose through {@link composeInlineHtml}, so
+ * there is a single render path. The CLI keeps its argument parsing, template
+ * scaffolding (`--new`/`--list-templates`), source-selection (`--template`), and
+ * the `--cdn` mode; the shared inline composition lives here.
+ *
+ * Asset resolution is relative to this module (`import.meta.url`), never
+ * `process.cwd()`, so it works from an installed npm package.
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { dirname, join } 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, '..');
+export 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. */
+export 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,
+};
+export 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://). */
+export function stripBaseImport(css) {
+    return css.replace(/@import\s+url\(\s*['"]?\.\/base\.css['"]?\s*\)\s*;?/gi, '');
+}
+export 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`. */
+export 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'),
+    }));
+}
+/** The default theme id, matching the CLI: prefer `light-neat-1`, else the first
+ *  loaded theme, else `'none'`. */
+export function pickDefaultTheme(themes) {
+    return themes.some((t) => t.id === 'light-neat-1') ? 'light-neat-1' : (themes[0]?.id ?? 'none');
+}
+/**
+ * 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 function composeInlineHtml(source, title, theme, delivery) {
+    const templates = loadTemplates();
+    const { baseCss, themes } = loadThemes();
+    const appJs = readFileSync(findAsset('assets/app.js'), 'utf8');
+    const runtime = getBrowserRuntimeScript(); // copy-as-Markdown (+ qr) from orz-markdown
+    // `cdn` references the published engine on jsDelivr (small file); `inline`
+    // (default) embeds it. Only the renderer differs from the inline path.
+    const renderer = delivery === 'cdn'
+        ? {
+            mode: 'cdn',
+            src: `https://cdn.jsdelivr.net/npm/orz-paged-browser@${selfVersion}/orz-paged.browser.js`,
+        }
+        : {
+            mode: 'inline',
+            js: readFileSync(findAsset('dist/orz-paged.browser.js'), 'utf8'),
+        };
+    const known = theme && themes.some((t) => t.id === theme);
+    const defaultTheme = known ? theme : pickDefaultTheme(themes);
+    return buildHtml({
+        source,
+        title,
+        rendererVersion: selfVersion,
+        renderer,
+        baseCss,
+        themes,
+        defaultTheme,
+        templates,
+        cdn: CDN,
+        appJs,
+        runtime,
+    });
+}
+/**
+ * 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 function buildPagedHtml(opts) {
+    let source = opts.markdown;
+    if (opts.template && !opts.markdown.trim()) {
+        const templates = loadTemplates();
+        const t = templates.find((x) => x.id === opts.template)
+            ?? templates.find((x) => x.id === opts.template + '-section'); // legacy: article→article-section
+        if (t)
+            source = t.skeleton;
+    }
+    const title = opts.title || 'Untitled';
+    return composeInlineHtml(source, title, opts.theme, opts.delivery);
+}