orz-slides 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

@@ -12,64 +12,19 @@
  *   --inline           embed the engine bundle + theme CSS in the file (default)
  *   --cdn              reference the engine + theme from jsDelivr (small files)
  *   --title <text>     document <title> (fallback; deck `title:` wins)
+ *
+ * The inline path (the default) is shared with the programmatic library entry
+ * `buildSlidesHtml` (src/lib.ts) — there is ONE composition path. The CDN path
+ * lives here.
  */
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { basename, extname, dirname, resolve, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import { getBrowserRuntimeScript } from 'orz-markdown/runtime';
 import { PREVIEW_CDN } from 'orz-markdown/preview-frame';
 import { parseDeck } from './slide-parser.js';
 import { buildHtml } from './template.js';
-/** The seven shipped slide themes (served from the orz-slides package on CDN). */
-const THEME_DEFS = [
-    { id: 'paper', name: 'Paper', scheme: 'light' },
-    { id: 'architect', name: 'Architect', scheme: 'light' },
-    { id: 'executive', name: 'Executive', scheme: 'light' },
-    { id: 'sage', name: 'Sage', scheme: 'light' },
-    { id: 'poppy', name: 'Poppy', scheme: 'light' },
-    { id: 'neon', name: 'Neon', scheme: 'dark' },
-    { id: 'chalk', name: 'Chalk', scheme: 'dark' },
-];
-const require = createRequire(import.meta.url);
-const HERE = dirname(fileURLToPath(import.meta.url));
-function pkgVersion(name, fallback = '0.0.0') {
-    try {
-        let dir = dirname(require.resolve(name));
-        while (!existsSync(join(dir, 'package.json')))
-            dir = dirname(dir);
-        return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version || fallback;
-    }
-    catch {
-        return fallback;
-    }
-}
-/** orz-slides' own version — pins the engine bundle + theme CDN + version check. */
-function selfVersion() {
-    for (const p of [join(HERE, '..', 'package.json'), join(HERE, '..', '..', 'package.json')]) {
-        try {
-            const j = JSON.parse(readFileSync(p, 'utf8'));
-            if (j.name === 'orz-slides' && j.version)
-                return j.version;
-        }
-        catch { /* keep looking */ }
-    }
-    return '0.0.0';
-}
-/** assets/ sits next to dist/ when published, and next to src/ in dev. */
-function findAsset(rel) {
-    for (const p of [join(HERE, '..', 'assets', rel), join(HERE, '..', '..', 'assets', rel)]) {
-        if (existsSync(p))
-            return p;
-    }
-    throw new Error(`asset not found: ${rel}`);
-}
-/** A theme's CSS without its `@import url('./base.css')` (base is inlined once). */
-function themeOnly(id) {
-    const css = readFileSync(findAsset(`themes/theme-${id}.css`), 'utf8');
-    return css.replace(/@import\s+url\(\s*['"]?\.\/base\.css['"]?\s*\)\s*;/, '');
-}
+import { THEME_DEFS, selfVersion, findAsset, pkgVersion, buildSlidesHtmlWithDocId, } from './lib.js';
 function parseArgs(argv) {
     const a = { delivery: 'inline' };
     for (let i = 0; i < argv.length; i++) {
@@ -89,74 +44,26 @@ function parseArgs(argv) {
     }
     return a;
 }
-function main() {
-    const args = parseArgs(process.argv.slice(2));
-    if (!args.input) {
-        console.error('Usage: orz-slides <input.md> [-o out] [--theme name] [--inline|--cdn]');
-        process.exit(1);
-    }
-    const inputPath = resolve(args.input);
-    const source = readFileSync(inputPath, 'utf8');
-    const base = basename(inputPath, extname(inputPath)).replace(/\.slides$/, '');
-    const outPath = args.out ? resolve(args.out) : join(dirname(inputPath), `${base}.slides.html`);
-    // The deck's own config wins; CLI flags are fallbacks.
-    const deck = parseDeck(source);
-    const ver = selfVersion();
-    const themeBase = `https://cdn.jsdelivr.net/npm/orz-slides@${ver}/assets/themes`;
-    const themes = THEME_DEFS.map((t) => ({ ...t, href: `${themeBase}/theme-${t.id}.css` }));
-    const wanted = deck.config.theme || args.theme || 'paper';
-    const defaultTheme = themes.some((t) => t.id === wanted) ? wanted : themes[0].id;
-    const ratio = deck.config.ratio || '16:9';
-    const title = deck.config.title || args.title || base;
-    // Engine + theme delivery.
-    let renderer;
-    let theme;
-    if (args.delivery === 'inline') {
-        const bundlePath = [
-            join(HERE, 'orz-slides.browser.js'),
-            join(HERE, '..', 'dist', 'orz-slides.browser.js'),
-        ].find(existsSync);
-        if (!bundlePath) {
-            console.error('Inline mode needs the engine bundle. Run: npm run bundle');
-            process.exit(1);
-        }
-        renderer = { mode: 'inline', js: readFileSync(bundlePath, 'utf8') };
-        theme = {
-            mode: 'inline',
-            base: readFileSync(findAsset('themes/base.css'), 'utf8'),
-            themes: THEME_DEFS.map((t) => ({ id: t.id, css: themeOnly(t.id) })),
-        };
-    }
-    else {
-        renderer = { mode: 'cdn', src: `https://cdn.jsdelivr.net/npm/orz-slides-browser@${ver}/orz-slides.browser.js` };
-        theme = { mode: 'cdn' };
-    }
+/** The CDN delivery path (engine + themes referenced from jsDelivr). */
+function buildCdnHtml(source, title, base, docId, ver, themes, defaultTheme, ratio) {
+    const renderer = {
+        mode: 'cdn',
+        src: `https://cdn.jsdelivr.net/npm/orz-slides-browser@${ver}/orz-slides.browser.js`,
+    };
+    const theme = { mode: 'cdn' };
     const revealVer = pkgVersion('reveal.js', '5.0.4');
-    // reveal's reset.css + reveal.css contain only data: URIs (no external refs),
-    // so --inline embeds them and the deck presents fully offline.
-    let revealCss;
-    if (args.delivery === 'inline') {
-        const revealDist = dirname(require.resolve('reveal.js'));
-        revealCss = {
-            mode: 'inline',
-            reset: readFileSync(join(revealDist, 'reset.css'), 'utf8'),
-            core: readFileSync(join(revealDist, 'reveal.css'), 'utf8'),
-        };
-    }
-    else {
-        revealCss = {
-            mode: 'cdn',
-            resetUrl: `https://cdn.jsdelivr.net/npm/reveal.js@${revealVer}/dist/reset.css`,
-            coreUrl: `https://cdn.jsdelivr.net/npm/reveal.js@${revealVer}/dist/reveal.css`,
-        };
-    }
+    const revealCss = {
+        mode: 'cdn',
+        resetUrl: `https://cdn.jsdelivr.net/npm/reveal.js@${revealVer}/dist/reset.css`,
+        coreUrl: `https://cdn.jsdelivr.net/npm/reveal.js@${revealVer}/dist/reveal.css`,
+    };
     const appJs = readFileSync(findAsset('app.js'), 'utf8');
     const CM = 'https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16';
-    const html = buildHtml({
+    return buildHtml({
         source,
         title,
         filename: base,
-        docId: randomUUID(),
+        docId,
         rendererVersion: ver,
         renderer,
         theme,
@@ -182,6 +89,39 @@ function main() {
             chartJs: PREVIEW_CDN.chartJs,
         },
     });
+}
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (!args.input) {
+        console.error('Usage: orz-slides <input.md> [-o out] [--theme name] [--inline|--cdn]');
+        process.exit(1);
+    }
+    const inputPath = resolve(args.input);
+    const source = readFileSync(inputPath, 'utf8');
+    const base = basename(inputPath, extname(inputPath)).replace(/\.slides$/, '');
+    const outPath = args.out ? resolve(args.out) : join(dirname(inputPath), `${base}.slides.html`);
+    const deck = parseDeck(source);
+    const docId = randomUUID();
+    // Resolve the effective (validated) theme once, for the log line and CDN path.
+    const wanted = deck.config.theme || args.theme || 'paper';
+    const defaultTheme = THEME_DEFS.some((t) => t.id === wanted) ? wanted : THEME_DEFS[0].id;
+    let html;
+    if (args.delivery === 'inline') {
+        // Shared inline composition — the library and the CLI produce byte-identical
+        // output for the same source (modulo docId). The deck-config precedence and
+        // the 'Untitled' fallbacks live in lib.ts; the CLI passes its filename-based
+        // title as the fallback so the deck's own title still wins.
+        html = buildSlidesHtmlWithDocId({ markdown: source, title: args.title ?? base, theme: args.theme }, docId);
+    }
+    else {
+        // The deck's own config wins; CLI flags are fallbacks.
+        const ver = selfVersion();
+        const themeBase = `https://cdn.jsdelivr.net/npm/orz-slides@${ver}/assets/themes`;
+        const themes = THEME_DEFS.map((t) => ({ ...t, href: `${themeBase}/theme-${t.id}.css` }));
+        const ratio = deck.config.ratio || '16:9';
+        const title = deck.config.title || args.title || base;
+        html = buildCdnHtml(source, title, base, docId, ver, themes, defaultTheme, ratio);
+    }
     writeFileSync(outPath, html, 'utf8');
     console.log(`Wrote ${outPath} (${args.delivery}, theme: ${defaultTheme}, ${deck.slides.length} slides)`);
 }

package/dist/layout.d.ts

@@ -0,0 +1,15 @@
+/**
+ * WP2 — Layout engine. Layout tree → nested CSS-grid DOM.
+ *
+ * Takes a fully-expanded `LayoutNode` (the parser has already expanded any
+ * preset alias), so this module depends only on ./types — nothing else.
+ * Pure string building; no DOM API.
+ *
+ * See BUILD-PLAN.md WP2 and docs/dom-contract.md ("Layout grid (WP2 output)").
+ */
+import type { LayoutNode, GridRender } from './types.js';
+/**
+ * Render a layout tree to nested grid DOM with empty region cells.
+ * Returns the inner HTML for `.orz-content` and the region names in order.
+ */
+export declare function renderLayout(node: LayoutNode): GridRender;

package/dist/lib.d.ts

@@ -0,0 +1,43 @@
+import { type ThemeEntry } from './template.js';
+/** The seven shipped slide themes (served from the orz-slides package on CDN). */
+export declare const THEME_DEFS: Array<Omit<ThemeEntry, 'href'>>;
+export declare function pkgVersion(name: string, fallback?: string): string;
+/** orz-slides' own version — pins the engine bundle + theme CDN + version check. */
+export declare function selfVersion(): string;
+/** assets/ sits next to dist/ when published, and next to src/ in dev. */
+export declare function findAsset(rel: string): string;
+/** A theme's CSS without its `@import url('./base.css')` (base is inlined once). */
+export declare function themeOnly(id: string): string;
+export interface BuildSlidesOptions {
+    /** The deck source (orz-markdown + slide layout syntax). */
+    markdown: string;
+    /** Document `<title>` fallback; the deck's own `title:` wins. */
+    title?: string;
+    /** Theme id fallback; the deck's own `theme:` wins. Validated against THEME_DEFS. */
+    theme?: string;
+    /** Renderer + theme + reveal CSS delivery: `inline` (default, offline) or
+     *  `cdn` (small file — engine, themes, and reveal.css load from jsDelivr at
+     *  view time; requires orz-slides-browser to be published at this version). */
+    delivery?: 'inline' | 'cdn';
+}
+/**
+ * Shared inline-composition path. Both {@link buildSlidesHtml} and the CLI's
+ * `--inline` branch call this; the ONLY difference between them is the `docId`
+ * they pass, so with the same `docId` the outputs are byte-identical.
+ *
+ * @internal — exported for tests / the CLI, not part of the primary API surface.
+ */
+export declare function buildSlidesHtmlWithDocId(opts: BuildSlidesOptions, docId: string): string;
+/**
+ * Generate a fully self-contained, presentable `.slides.html` document from a
+ * deck source string, in-process. Returns the FULL document string.
+ *
+ * The output is always fully-inline (engine + base/theme CSS + reveal CSS +
+ * embedded deck source), byte-identical to the CLI `--inline` output for the
+ * same markdown/title/theme (modulo the random docId).
+ *
+ * Deck-config precedence: the deck's own `title:`/`theme:`/`ratio:` always win;
+ * `opts.title`/`opts.theme` are fallbacks (title falls back to `'Untitled'`,
+ * theme to `'paper'`, validated against THEME_DEFS).
+ */
+export declare function buildSlidesHtml(opts: BuildSlidesOptions): string;

package/dist/lib.js

@@ -0,0 +1,189 @@
+/**
+ * orz-slides — programmatic library entry.
+ *
+ * Exposes {@link buildSlidesHtml}, which generates a fully self-contained,
+ * presentable `.slides.html` document IN-PROCESS from a deck source string
+ * (orz-markdown + the slide layout syntax) — no CLI, no shelling out, no
+ * filesystem input file.
+ *
+ * The output is ALWAYS fully-inline (inlined engine bundle + inlined base/theme
+ * CSS + inlined reveal.js CSS + embedded deck source; no CDN engine/theme pins),
+ * byte-identical to the CLI `--inline` path for the same markdown/title/theme
+ * (modulo the random docId).
+ *
+ * This module also owns the shared inline-composition helpers (`selfVersion`,
+ * `findAsset`, `themeOnly`, `THEME_DEFS`, reveal.js CSS reading, `pkgVersion`)
+ * so there is ONE composition path and the CLI imports them rather than
+ * duplicating the logic.
+ *
+ * Asset resolution is ALWAYS via `import.meta.url` (never `process.cwd()`), so
+ * the entry works when consumed from an installed npm package.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { getBrowserRuntimeScript } from 'orz-markdown/runtime';
+import { PREVIEW_CDN } from 'orz-markdown/preview-frame';
+import { parseDeck } from './slide-parser.js';
+import { buildHtml } from './template.js';
+/** The seven shipped slide themes (served from the orz-slides package on CDN). */
+export const THEME_DEFS = [
+    { id: 'paper', name: 'Paper', scheme: 'light' },
+    { id: 'architect', name: 'Architect', scheme: 'light' },
+    { id: 'executive', name: 'Executive', scheme: 'light' },
+    { id: 'sage', name: 'Sage', scheme: 'light' },
+    { id: 'poppy', name: 'Poppy', scheme: 'light' },
+    { id: 'neon', name: 'Neon', scheme: 'dark' },
+    { id: 'chalk', name: 'Chalk', scheme: 'dark' },
+];
+const require = createRequire(import.meta.url);
+// Asset resolution anchors on THIS module's location, never process.cwd().
+const HERE = dirname(fileURLToPath(import.meta.url));
+export function pkgVersion(name, fallback = '0.0.0') {
+    try {
+        let dir = dirname(require.resolve(name));
+        while (!existsSync(join(dir, 'package.json')))
+            dir = dirname(dir);
+        return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version || fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** orz-slides' own version — pins the engine bundle + theme CDN + version check. */
+export function selfVersion() {
+    for (const p of [join(HERE, '..', 'package.json'), join(HERE, '..', '..', 'package.json')]) {
+        try {
+            const j = JSON.parse(readFileSync(p, 'utf8'));
+            if (j.name === 'orz-slides' && j.version)
+                return j.version;
+        }
+        catch { /* keep looking */ }
+    }
+    return '0.0.0';
+}
+/** assets/ sits next to dist/ when published, and next to src/ in dev. */
+export function findAsset(rel) {
+    for (const p of [join(HERE, '..', 'assets', rel), join(HERE, '..', '..', 'assets', rel)]) {
+        if (existsSync(p))
+            return p;
+    }
+    throw new Error(`asset not found: ${rel}`);
+}
+/** A theme's CSS without its `@import url('./base.css')` (base is inlined once). */
+export function themeOnly(id) {
+    const css = readFileSync(findAsset(`themes/theme-${id}.css`), 'utf8');
+    return css.replace(/@import\s+url\(\s*['"]?\.\/base\.css['"]?\s*\)\s*;/, '');
+}
+/** The inlined engine bundle (dist/orz-slides.browser.js), read from disk. */
+function readEngineBundle() {
+    const bundlePath = [
+        join(HERE, 'orz-slides.browser.js'),
+        join(HERE, '..', 'dist', 'orz-slides.browser.js'),
+    ].find(existsSync);
+    if (!bundlePath) {
+        throw new Error('Inline mode needs the engine bundle. Run: npm run bundle');
+    }
+    return readFileSync(bundlePath, 'utf8');
+}
+/** reveal.js reset.css + reveal.css (both contain only data: URIs — offline-safe). */
+function readRevealCss() {
+    const revealDist = dirname(require.resolve('reveal.js'));
+    return {
+        reset: readFileSync(join(revealDist, 'reset.css'), 'utf8'),
+        core: readFileSync(join(revealDist, 'reveal.css'), 'utf8'),
+    };
+}
+/**
+ * Shared inline-composition path. Both {@link buildSlidesHtml} and the CLI's
+ * `--inline` branch call this; the ONLY difference between them is the `docId`
+ * they pass, so with the same `docId` the outputs are byte-identical.
+ *
+ * @internal — exported for tests / the CLI, not part of the primary API surface.
+ */
+export function buildSlidesHtmlWithDocId(opts, docId) {
+    // The deck's own config wins; the passed options are fallbacks. The library
+    // has no input filename, so 'Untitled' stands in where the CLI used `base`.
+    const deck = parseDeck(opts.markdown);
+    const ver = selfVersion();
+    const themeBase = `https://cdn.jsdelivr.net/npm/orz-slides@${ver}/assets/themes`;
+    const themes = THEME_DEFS.map((t) => ({ ...t, href: `${themeBase}/theme-${t.id}.css` }));
+    const wanted = deck.config.theme || opts.theme || 'paper';
+    const defaultTheme = themes.some((t) => t.id === wanted) ? wanted : themes[0].id;
+    const ratio = deck.config.ratio || '16:9';
+    const title = deck.config.title || opts.title || 'Untitled';
+    // Engine + theme + reveal CSS delivery: inline (default, offline) or CDN.
+    const cdn = opts.delivery === 'cdn';
+    const renderer = cdn
+        ? { mode: 'cdn', src: `https://cdn.jsdelivr.net/npm/orz-slides-browser@${ver}/orz-slides.browser.js` }
+        : { mode: 'inline', js: readEngineBundle() };
+    const theme = cdn
+        ? { mode: 'cdn' }
+        : {
+            mode: 'inline',
+            base: readFileSync(findAsset('themes/base.css'), 'utf8'),
+            themes: THEME_DEFS.map((t) => ({ id: t.id, css: themeOnly(t.id) })),
+        };
+    let revealCss;
+    if (cdn) {
+        const revealVer = pkgVersion('reveal.js', '5.0.4');
+        revealCss = {
+            mode: 'cdn',
+            resetUrl: `https://cdn.jsdelivr.net/npm/reveal.js@${revealVer}/dist/reset.css`,
+            coreUrl: `https://cdn.jsdelivr.net/npm/reveal.js@${revealVer}/dist/reveal.css`,
+        };
+    }
+    else {
+        const reveal = readRevealCss();
+        revealCss = { mode: 'inline', reset: reveal.reset, core: reveal.core };
+    }
+    const appJs = readFileSync(findAsset('app.js'), 'utf8');
+    const CM = 'https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16';
+    return buildHtml({
+        source: opts.markdown,
+        title,
+        filename: 'Untitled',
+        docId,
+        rendererVersion: ver,
+        renderer,
+        theme,
+        defaultTheme,
+        themes,
+        ratio,
+        versionManifest: 'https://data.jsdelivr.com/v1/packages/npm/orz-slides-browser/resolved',
+        appJs,
+        runtime: getBrowserRuntimeScript(),
+        editorLibs: {
+            codemirrorCss: `${CM}/codemirror.min.css`,
+            codemirrorLightThemeCss: `${CM}/theme/eclipse.min.css`,
+            codemirrorDarkThemeCss: `${CM}/theme/material-darker.min.css`,
+            codemirrorJs: `${CM}/codemirror.min.js`,
+            codemirrorMarkdownJs: `${CM}/mode/markdown/markdown.min.js`,
+            codemirrorContinuelistJs: `${CM}/addon/edit/continuelist.min.js`,
+        },
+        revealCss,
+        cdn: {
+            katexCss: PREVIEW_CDN.katexCss,
+            mermaidJs: PREVIEW_CDN.mermaidJs,
+            smilesJs: PREVIEW_CDN.smilesJs,
+            chartJs: PREVIEW_CDN.chartJs,
+        },
+    });
+}
+/**
+ * Generate a fully self-contained, presentable `.slides.html` document from a
+ * deck source string, in-process. Returns the FULL document string.
+ *
+ * The output is always fully-inline (engine + base/theme CSS + reveal CSS +
+ * embedded deck source), byte-identical to the CLI `--inline` output for the
+ * same markdown/title/theme (modulo the random docId).
+ *
+ * Deck-config precedence: the deck's own `title:`/`theme:`/`ratio:` always win;
+ * `opts.title`/`opts.theme` are fallbacks (title falls back to `'Untitled'`,
+ * theme to `'paper'`, validated against THEME_DEFS).
+ */
+export function buildSlidesHtml(opts) {
+    return buildSlidesHtmlWithDocId(opts, randomUUID());
+}