tosijs-ui 1.6.15 → 1.6.17

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 1.6.17
+
+### Fixed
+
+- **`@resvg/resvg-js` is now an optional peer dependency** (it was only a dev
+  dependency). It rasterizes the generated ePub cover and belongs to the same
+  doc-site pipeline as `happy-dom`, which was already an optional peer — so an
+  adopter building ePubs via `tosijs-ui/site` got `happy-dom` surfaced by their
+  package manager but not `resvg`, and their book's cover silently failed to
+  generate. Both are still lazy-loaded with a graceful warning when absent.
+
+## 1.6.16
+
+Doc-system: prose/book adoption. Component APIs are unchanged; everything here is
+doc-site tooling (the `tosijs-ui/site` build system + live examples).
+
+### Added
+
+- **Book manifest — curate/reorder the book without touching site nav.** A new
+  `book` field on the site config (`BookManifest`) selects and sequences the ePub
+  (and, later, print) as a subset of the corpus while the live site still shows
+  everything — one source, two outputs. `include`/`exclude` globs pick docs,
+  `order: [...]` names the lead sequence (front/back matter are just docs you
+  name), and `sort: 'filename'` gives a folder of chapters natural order with no
+  metadata. It adds no new ordering mechanism — it overlays each doc's `order` so
+  the existing nav sort sequences the book (pins/parents still apply). Zero-config
+  is unchanged: the book is the whole visible corpus. Identity (title/author/
+  cover) still comes from `epub`.
+- **Prose Markdown (Batch A), activated only by its own syntax** so code docs are
+  byte-identical: **YAML frontmatter** (`title`/`order`/`author`/`date`/`draft`,
+  frontmatter wins over JSON-comment metadata), **wikilinks** `[[slug]]` /
+  `[[slug|label]]` → `/slug/`, and **footnotes** `[^id]` → numbered refs + an
+  endnotes section (ePub/web).
+- **Book/prose quick wins:** auto-serve `/iife.js` when `bundleEntry` is omitted;
+  skip `_`-prefixed scaffolding files; empty metadata `title` falls back to the
+  H1; warn when no ePub cover is generated.
+- **`epub.coverIcon`** — embed a custom flat SVG glyph into the generated ePub
+  cover (in place of the favicon); the source viewBox is preserved so any
+  square-ish icon scales correctly. tosijs-ui ships a `tosi-book` cover glyph.
+- **`<tosi-3d>` declarative attributes** — assemble a scene purely in HTML (no
+  `sceneCreated` callback): `src` (a `.glb` URL, auto-loads like `<img>`),
+  `hero-light` (a directional key light over a soft hemispheric fill), `fov` (a
+  field-of-view multiplier — `1` unchanged, `<1` a longer lens), and `clear-color`
+  (a hex color, or `transparent` to composite the 3D over the page). Aimed at
+  declarative narrative pages.
+
+### Fixed
+
+- **Multiple `<tosi-3d>` on one page.** Their scenes are created asynchronously and
+  interleave, so objects created without an explicit scene landed on Babylon's
+  `Engine.LastCreatedScene` (another instance's scene) — the built-in default
+  camera did this, leaving a scene with no camera and a blank canvas. The default
+  camera (and the doc examples' lights) now pass their scene explicitly.
+
+### Changed
+
+- **PDF is now the in-browser Print button, not a batch job.** The doc-browser's
+  Print action renders the shared book HTML (`book-html.ts`) and the browser
+  prints it to PDF. This is the single, supported PDF path going forward; a future
+  paginated/footnote-anchored PDF will build on it. (ePub is still generated at
+  build time and unaffected.)
+- **Live examples pinned to tjs-lang 0.8.7** (upstream subtle-bug fix).
+
+### Removed
+
+- **The headless PDF batch builder** (`buildPdf` / `BuildPdfOptions`, exported
+  from `tosijs-ui/site`, and the `book:pdf` / `--pdf` script) — a secondary code
+  path superseded by the Print button above. If you generated PDFs in a build,
+  print the book page to PDF (via the doc-browser) instead.
+
 ## 1.6.15
 
 Live-example fixes from tosijs-3d adoption. All fixes to the doc-system's

package/dist/babylon-3d.d.ts

@@ -9,6 +9,12 @@ interface B3dUIOptions {
 type MeshProcessCallback = (meshes: any[]) => void;
 export declare class B3d extends WebComponent {
     static preferredTagName: string;
+    static initAttributes: {
+        src: string;
+        clearColor: string;
+        fov: number;
+        heroLight: boolean;
+    };
     babylonReady: Promise<any>;
     BABYLON?: any;
     static shadowStyleSpec: {

package/dist/babylon-3d.js

@@ -21,7 +21,7 @@ preview.append(b3d({
     )
     camera.attachControl(element.parts.canvas, true)
 
-    new BABYLON.HemisphericLight('light', new BABYLON.Vector3(0.25, 1, -0.5))
+    new BABYLON.HemisphericLight('light', new BABYLON.Vector3(0.25, 1, -0.5), element.scene)
 
     this.loadScene('/', 'xin3d.glb')
 
@@ -129,7 +129,7 @@ preview.append(b3d({
     const { scene } = element
     const { createNoise2D } = await import('https://cdn.jsdelivr.net/npm/simplex-noise@4.0.1/+esm')
 
-    new BABYLON.HemisphericLight('light', new BABYLON.Vector3(0.25, 1, 2))
+    new BABYLON.HemisphericLight('light', new BABYLON.Vector3(0.25, 1, 2), scene)
 
     const terrain = new BABYLON.Mesh('terrain', scene)
     const vertexData = new BABYLON.VertexData()
@@ -168,10 +168,38 @@ preview.append(b3d({
 }))
 ```
 
+## Pure-HTML scenes (attributes)
+
+`<tosi-3d>` can assemble a scene entirely from HTML attributes — no `sceneCreated`
+callback, no JavaScript — so a 3D hero can be dropped into a declarative page. Set
+`src` and it works like an `<img>`; a default camera and lighting are added when
+the scene doesn't provide its own, so a model shows up out of the box.
+
+- **`src`** — a `.glb` URL; loads on connect (calls `loadScene` for you).
+- **`hero-light`** — adds a directional key light (front-upper-left) over the soft
+  hemispheric fill, for a "product photography" look.
+- **`fov`** — field-of-view *multiplier* on the camera's natural lens: `1` (default)
+  leaves it alone, `<1` is a longer lens (less perspective distortion), `>1` wider.
+- **`clear-color`** — scene background: a css hex color, or `transparent` to
+  composite the 3D over the page (great for themed narrative pages).
+
+This loads the same scene as the example above, in plain HTML, with a hero key
+light and a slightly longer lens:
+
+```html
+<tosi-3d src="/xin3d.glb" hero-light fov="0.6"></tosi-3d>
+```
+```css
+.preview tosi-3d {
+  width: 100%;
+  height: 100%;
+}
+```
+
 ## loadScene
 
 `<tosi-3d>.loadScene(path: string, file: string, callBack(meshes: any[]): void)` can
-be used to load `.glb` files.
+be used to load `.glb` files. Setting `src` calls this for you on connect.
 
 ## loadUI
 
@@ -184,8 +212,42 @@ import { icons, svg2DataUrl } from './icons';
 const noop = () => {
     /* do not care */
 };
+/** Parse a css hex color (#rgb/#rrggbb/#rrggbbaa) or the keyword `transparent`
+ * into a BABYLON.Color4. */
+function toColor4(BABYLON, css) {
+    if (!css || css.trim() === 'transparent')
+        return new BABYLON.Color4(0, 0, 0, 0);
+    let hex = css.trim().replace(/^#/, '');
+    if (hex.length === 3)
+        hex = hex
+            .split('')
+            .map((c) => c + c)
+            .join('');
+    if (hex.length === 6)
+        hex += 'ff';
+    const n = parseInt(hex, 16);
+    if (Number.isNaN(n) || hex.length !== 8)
+        return new BABYLON.Color4(0, 0, 0, 1);
+    return new BABYLON.Color4(((n >>> 24) & 255) / 255, ((n >>> 16) & 255) / 255, ((n >>> 8) & 255) / 255, (n & 255) / 255);
+}
 export class B3d extends WebComponent {
     static preferredTagName = 'tosi-3d';
+    // Declarative config so a scene can be assembled purely in HTML (no JS):
+    //   <tosi-3d src="/model.glb" hero-light fov="0.5" clear-color="transparent">
+    static initAttributes = {
+        // `src` (a .glb URL) makes <tosi-3d> work like <img>: the scene loads on connect.
+        src: '',
+        // scene background: a css hex color, or `transparent` to composite the 3D
+        // over the page (e.g. themed narrative pages). Empty = Babylon default.
+        clearColor: '',
+        // field-of-view MULTIPLIER on the camera's natural lens. 1 = unchanged,
+        // <1 = longer lens / less perspective distortion, >1 = wider. Author-friendly:
+        // no need to know Babylon's default fov in radians.
+        fov: 1,
+        // add a directional key light (front-upper-left) for a product-photography
+        // look, on top of the soft hemispheric fill.
+        heroLight: false,
+    };
     babylonReady;
     BABYLON;
     static shadowStyleSpec = {
@@ -281,15 +343,47 @@ export class B3d extends WebComponent {
         const { canvas } = this.parts;
         this.babylonReady.then(async (BABYLON) => {
             this.BABYLON = BABYLON;
-            this.engine = new BABYLON.Engine(canvas, true);
+            // A `transparent` (alpha < 1) clear-color needs an alpha WebGL context so
+            // the canvas composites over the page.
+            const clearColor = this.clearColor ? toColor4(BABYLON, this.clearColor) : null;
+            this.engine = new BABYLON.Engine(canvas, true, clearColor && clearColor.a < 1
+                ? { alpha: true, premultipliedAlpha: false }
+                : undefined);
             this.scene = new BABYLON.Scene(this.engine);
+            if (clearColor)
+                this.scene.clearColor = clearColor;
             if (this.sceneCreated) {
                 await this.sceneCreated(this, BABYLON);
             }
+            // `src` (pure-HTML usage): auto-load the .glb. Split into the rootUrl +
+            // filename that BABYLON.SceneLoader.Append expects.
+            if (this.src) {
+                const slash = this.src.lastIndexOf('/');
+                await this.loadScene(this.src.slice(0, slash + 1) || '/', this.src.slice(slash + 1));
+            }
             if (this.scene.activeCamera === undefined) {
-                const camera = new BABYLON.ArcRotateCamera('default-camera', -Math.PI / 2, Math.PI / 2.5, 3, new BABYLON.Vector3(0, 0, 0));
+                // Pass `this.scene` explicitly: with multiple <tosi-3d> on a page their
+                // scenes interleave, so BABYLON.Engine.LastCreatedScene (the implicit
+                // default) may point at another instance's scene.
+                const camera = new BABYLON.ArcRotateCamera('default-camera', -Math.PI / 2, Math.PI / 2.5, 3, new BABYLON.Vector3(0, 0, 0), this.scene);
                 camera.attachControl(this.parts.canvas, true);
             }
+            // `fov` multiplier: <1 gives a long "product photography" lens (less
+            // distortion), >1 a wider one. 1 (default) leaves the camera untouched.
+            if (this.fov && this.fov !== 1 && this.scene.activeCamera) {
+                this.scene.activeCamera.fov *= this.fov;
+            }
+            // A model loaded via `src` needs a light or it renders black; add a soft
+            // hemispheric fill from above only when the scene has none of its own.
+            if (this.scene.lights.length === 0) {
+                const hemi = new BABYLON.HemisphericLight('hemi', new BABYLON.Vector3(0, 1, 0), this.scene);
+                hemi.intensity = 0.6;
+            }
+            // `hero-light`: a directional key light (front-upper-left) over the fill.
+            if (this.heroLight) {
+                const dir = new BABYLON.DirectionalLight('hero', new BABYLON.Vector3(-1, -2, 1), this.scene);
+                dir.intensity = 0.8;
+            }
             this.engine.runRenderLoop(this._update);
         });
     }

package/dist/doc-system/book-html.d.ts

@@ -6,7 +6,7 @@ export interface BookDoc {
     parent?: string;
     hidden?: boolean;
 }
-export declare const DEFAULT_BOOK_CSS = "/* doc-system book stylesheet */\nhtml { font-size: 100%; }\nbody {\n  font-family: Georgia, 'Times New Roman', serif;\n  line-height: 1.5;\n  margin: 0 1em;\n  color: #1a1a1a;\n}\nh1, h2, h3, h4, h5, h6 {\n  font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif;\n  line-height: 1.2;\n  margin: 1.4em 0 0.5em;\n}\nh1 { font-size: 1.8em; }\nh2 { font-size: 1.4em; }\nh3 { font-size: 1.2em; }\np { margin: 0.6em 0; }\na { color: #08c; text-decoration: none; }\nul, ol { margin: 0.6em 0; padding-left: 1.4em; }\nblockquote {\n  margin: 0.8em 0;\n  padding: 0 0 0 1em;\n  border-left: 3px solid #ccc;\n  color: #555;\n}\nimg { max-width: 100%; height: auto; }\ntable { border-collapse: collapse; margin: 0.8em 0; font-size: 0.85em; }\nth, td { border: 1px solid #ccc; padding: 0.3em 0.6em; text-align: left; }\ncode, pre {\n  font-family: 'SF Mono', Menlo, Consolas, monospace;\n  font-size: 0.8em;\n}\n:not(pre) > code {\n  background: #f3f3f3;\n  padding: 0.1em 0.3em;\n  border-radius: 3px;\n}\npre {\n  background: #f6f8fa;\n  border: 1px solid #e1e4e8;\n  border-radius: 4px;\n  padding: 0.7em 0.9em;\n  margin: 0.8em 0;\n  white-space: pre-wrap;\n  word-break: break-word;\n  overflow-wrap: anywhere;\n}\npre code { background: none; padding: 0; }\n/* the in-flow Contents page (ePub spine TOC) */\n.toc-title { text-align: center; }\nol.toc, ol.toc ol { list-style: none; padding-left: 0; }\nol.toc ol { padding-left: 1.2em; }\nol.toc li { margin: 0.3em 0; }\nol.toc > li > a { font-weight: bold; }\n/* per-example \"run this live\" deep link */\n.example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }\n.example-live-link a { color: #08c; font-weight: bold; }\n";
+export declare const DEFAULT_BOOK_CSS = "/* doc-system book stylesheet */\nhtml { font-size: 100%; }\nbody {\n  font-family: Georgia, 'Times New Roman', serif;\n  line-height: 1.5;\n  margin: 0 1em;\n  color: #1a1a1a;\n}\nh1, h2, h3, h4, h5, h6 {\n  font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif;\n  line-height: 1.2;\n  margin: 1.4em 0 0.5em;\n}\nh1 { font-size: 1.8em; }\nh2 { font-size: 1.4em; }\nh3 { font-size: 1.2em; }\np { margin: 0.6em 0; }\na { color: #08c; text-decoration: none; }\nul, ol { margin: 0.6em 0; padding-left: 1.4em; }\nblockquote {\n  margin: 0.8em 0;\n  padding: 0 0 0 1em;\n  border-left: 3px solid #ccc;\n  color: #555;\n}\nimg { max-width: 100%; height: auto; }\ntable { border-collapse: collapse; margin: 0.8em 0; font-size: 0.85em; }\nth, td { border: 1px solid #ccc; padding: 0.3em 0.6em; text-align: left; }\ncode, pre {\n  font-family: 'SF Mono', Menlo, Consolas, monospace;\n  font-size: 0.8em;\n}\n:not(pre) > code {\n  background: #f3f3f3;\n  padding: 0.1em 0.3em;\n  border-radius: 3px;\n}\npre {\n  background: #f6f8fa;\n  border: 1px solid #e1e4e8;\n  border-radius: 4px;\n  padding: 0.7em 0.9em;\n  margin: 0.8em 0;\n  white-space: pre-wrap;\n  word-break: break-word;\n  overflow-wrap: anywhere;\n}\npre code { background: none; padding: 0; }\n/* the in-flow Contents page (ePub spine TOC) */\n.toc-title { text-align: center; }\nol.toc, ol.toc ol { list-style: none; padding-left: 0; }\nol.toc ol { padding-left: 1.2em; }\nol.toc li { margin: 0.3em 0; }\nol.toc > li > a { font-weight: bold; }\n/* per-example \"run this live\" deep link */\n.example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }\n.example-live-link a { color: #08c; font-weight: bold; }\n/* footnotes / endnotes + wikilinks */\nsup.footnote-ref { font-size: 0.7em; line-height: 0; }\nsup.footnote-ref a { text-decoration: none; }\n.footnotes { margin-top: 2em; font-size: 0.9em; }\n.footnotes hr { border: none; border-top: 1px solid #ccc; margin: 1em 0; }\n.footnote-backref { text-decoration: none; }\na.wikilink { text-decoration: none; border-bottom: 1px dotted currentColor; }\n";
 export declare const PRINT_CSS = "\n@page { margin: 18mm 16mm; }\n.book-title { text-align: center; margin: 30vh 0 1em; }\n.book-toc { page-break-after: always; }\n.book-toc h2 { page-break-before: avoid; }\n.book-toc ol { list-style: none; padding-left: 0; }\n.book-toc ol ol { padding-left: 1.2em; }\n.book-toc a { color: inherit; }\n.chapter { page-break-before: always; }\n";
 export declare function escapeHtml(s: string): string;
 export declare function slugify(s: string): string;

package/dist/doc-system/book-html.js

@@ -2,9 +2,9 @@
 Shared, browser-safe assembly of the whole doc corpus into one printable HTML
 "book": a title page, a generated table of contents, then every doc as a chapter
 that starts on a new page. Used by the client-side **Print** button in the
-doc-browser (the user's browser prints it to PDF) and by the headless PDF builder
-(site/pdf.ts). Pure rendering — no fs, no Node-only APIs — so it bundles into the
-iife. Live examples are pretty-printed, force-wrapped code listings, not executed.
+doc-browser (the user's browser prints it to PDF). Pure rendering — no fs, no
+Node-only APIs — so it bundles into the iife. Live examples are pretty-printed,
+force-wrapped code listings, not executed.
 */
 import { renderDocMarkdown } from './render';
 import { buildSlugMap } from './routing';
@@ -67,6 +67,13 @@ ol.toc > li > a { font-weight: bold; }
 /* per-example "run this live" deep link */
 .example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }
 .example-live-link a { color: #08c; font-weight: bold; }
+/* footnotes / endnotes + wikilinks */
+sup.footnote-ref { font-size: 0.7em; line-height: 0; }
+sup.footnote-ref a { text-decoration: none; }
+.footnotes { margin-top: 2em; font-size: 0.9em; }
+.footnotes hr { border: none; border-top: 1px solid #ccc; margin: 1em 0; }
+.footnote-backref { text-decoration: none; }
+a.wikilink { text-decoration: none; border-bottom: 1px dotted currentColor; }
 `;
 // Print-only layout: page margins, a chapter per page, an avoid-break TOC.
 export const PRINT_CSS = `

package/dist/doc-system/book-manifest.d.ts

@@ -0,0 +1,36 @@
+export interface BookManifest {
+    /**
+     * Globs selecting which docs are in the book (matched against each doc's
+     * `path` AND `filename`, so `chapters/**` or `*.md` both work). Default: every
+     * visible doc.
+     */
+    include?: string[];
+    /** Globs removed from the selection, applied after `include`. */
+    exclude?: string[];
+    /**
+     * Explicit reading order, by filename (with or without extension), slug, or
+     * title. Listed docs lead in this exact sequence; everything else follows in
+     * normal order. Unmatched keys are ignored.
+     */
+    order?: string[];
+    /**
+     * Baseline order for docs you neither pinned via metadata nor named in
+     * `order`: `'nav'` (default — today's pin / `order` / title sort) or
+     * `'filename'` (natural sort, so `01-*.md`, `02-*.md`, … sequence with zero
+     * metadata). A per-doc `order` still wins over `'filename'`.
+     */
+    sort?: 'nav' | 'filename';
+}
+interface BookDocLike {
+    filename: string;
+    path?: string;
+    title?: string;
+    order?: number;
+}
+/**
+ * Apply a book manifest to the (already visible) corpus. Returns a NEW array of
+ * shallow-copied docs with `order` overlaid for book sequencing. Pure — never
+ * mutates the input, so the caller's site-nav copy is untouched.
+ */
+export declare function selectBookDocs<T extends BookDocLike>(docs: T[], manifest?: BookManifest): T[];
+export {};

package/dist/doc-system/book-manifest.js

@@ -0,0 +1,96 @@
+/*
+Pure "book manifest" logic: curate a subset of the doc corpus into a book
+(ePub / print) WITHOUT touching the live-site navigation. One source, two
+outputs.
+
+Everything here is an overlay on the defaults — omit the manifest and you get the
+whole visible corpus in normal nav order (the doc system's zero-config behavior).
+The manifest never introduces a new ordering mechanism: it selects docs, then
+overlays each doc's `order` so the SHARED buildNavTree/flatten (used by the site,
+print, and ePub alike) sequences the book. So "front/back matter" are just
+regular docs you name in `order` (or position with a per-doc `order`), and pins /
+parents keep working exactly as on the site.
+
+No fs, no DOM — a pure function of the docs array, so it's shared + unit-testable.
+*/
+// glob → RegExp. `**` matches any run including `/`; `*` matches any run except
+// `/`; `?` matches a single non-`/`. Everything else is matched literally.
+function globToRegExp(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                re += '.*';
+                i += 1;
+            }
+            else {
+                re += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            re += '[^/]';
+        }
+        else {
+            re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp('^' + re + '$');
+}
+function matchesAny(doc, globs) {
+    return globs.some((re) => re.test(doc.path ?? '') || re.test(doc.filename));
+}
+const baseName = (filename) => filename.replace(/\.[^.]+$/, '');
+/** Does `key` (from an `order` list) name this doc? filename / basename / title. */
+function docMatchesKey(doc, key) {
+    const k = key.trim().toLowerCase();
+    return (doc.filename.toLowerCase() === k ||
+        baseName(doc.filename).toLowerCase() === k ||
+        (doc.title ?? '').toLowerCase() === k);
+}
+/**
+ * Apply a book manifest to the (already visible) corpus. Returns a NEW array of
+ * shallow-copied docs with `order` overlaid for book sequencing. Pure — never
+ * mutates the input, so the caller's site-nav copy is untouched.
+ */
+export function selectBookDocs(docs, manifest) {
+    if (!manifest)
+        return docs.slice();
+    // 1) select ────────────────────────────────────────────────────────────────
+    let selected = docs.slice();
+    if (manifest.include && manifest.include.length) {
+        const inc = manifest.include.map(globToRegExp);
+        selected = selected.filter((d) => matchesAny(d, inc));
+    }
+    if (manifest.exclude && manifest.exclude.length) {
+        const exc = manifest.exclude.map(globToRegExp);
+        selected = selected.filter((d) => !matchesAny(d, exc));
+    }
+    const copies = selected.map((d) => ({ ...d }));
+    // 2) baseline order overlay ─────────────────────────────────────────────────
+    // 'filename' fills only docs with no explicit `order`, so metadata still wins.
+    if (manifest.sort === 'filename') {
+        const natural = copies
+            .slice()
+            .sort((a, b) => (a.path ?? a.filename).localeCompare(b.path ?? b.filename, undefined, {
+            numeric: true,
+            sensitivity: 'base',
+        }));
+        natural.forEach((d, i) => {
+            if (d.order === undefined)
+                d.order = i * 10;
+        });
+    }
+    // 3) explicit `order` list leads, in the given sequence ─────────────────────
+    // Large-negative orders keep listed docs ahead of everything else while
+    // preserving their relative order; pins/parents still apply (navSortKey).
+    if (manifest.order && manifest.order.length) {
+        manifest.order.forEach((key, i) => {
+            for (const d of copies) {
+                if (docMatchesKey(d, key))
+                    d.order = -1_000_000 + i;
+            }
+        });
+    }
+    return copies;
+}

package/dist/doc-system/render.js

@@ -32,6 +32,109 @@ docMarked.use({
         },
     },
 });
+// ── Prose Markdown: wikilinks + footnotes ────────────────────────────────────
+// Enabled by default because each activates ONLY on its own syntax ([[…]] /
+// [^id]) — a doc that doesn't use them renders byte-identically (tosijs-ui's own
+// docs use neither). marked core supports neither; both are common in prose.
+function slugify(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+// Per-parse footnote state. `parse()` is synchronous and Marked tokenizes fully
+// before rendering, so a module-level object is safe: preprocess resets it, the
+// tokenizers fill it (defs during the block pass, refs during inline — refs set
+// the number by first-appearance order), postprocess renders the endnotes.
+const plainMarked = new Marked(); // renders footnote-definition markdown (no extensions)
+let footnoteDefs = new Map();
+let footnoteOrder = [];
+docMarked.use({
+    hooks: {
+        preprocess(markdown) {
+            footnoteDefs = new Map();
+            footnoteOrder = [];
+            return markdown;
+        },
+        postprocess(html) {
+            if (footnoteOrder.length === 0)
+                return html;
+            const items = footnoteOrder
+                .map((id) => {
+                const body = plainMarked.parseInline(footnoteDefs.get(id) ?? '');
+                const eid = slugify(id);
+                return `<li id="fn-${eid}"><p>${body} <a href="#fnref-${eid}" class="footnote-backref" aria-label="Back to reference">↩</a></p></li>`;
+            })
+                .join('\n');
+            return `${html}\n<section class="footnotes" role="doc-endnotes">\n<hr />\n<ol>\n${items}\n</ol>\n</section>\n`;
+        },
+    },
+    extensions: [
+        {
+            // [[slug]] / [[slug|label]] → link to /slug/. Not matched inside code spans
+            // (Marked tokenizes those first). Resolves by slugifying the target.
+            name: 'wikilink',
+            level: 'inline',
+            start(src) {
+                return src.match(/\[\[/)?.index;
+            },
+            tokenizer(src) {
+                const m = /^\[\[([^\]|]+?)(?:\|([^\]]+?))?\]\]/.exec(src);
+                if (!m)
+                    return undefined;
+                return {
+                    type: 'wikilink',
+                    raw: m[0],
+                    target: m[1].trim(),
+                    label: (m[2] ?? m[1]).trim(),
+                };
+            },
+            renderer(token) {
+                return `<a href="/${slugify(token.target)}/" class="wikilink">${escapeHtml(token.label)}</a>`;
+            },
+        },
+        {
+            // [^id]: definition (single line) — collected, rendered as endnotes.
+            name: 'footnoteDef',
+            level: 'block',
+            start(src) {
+                return src.match(/^\[\^[^\]]+\]:/m)?.index;
+            },
+            tokenizer(src) {
+                const m = /^\[\^([^\]]+)\]:[ \t]*([^\n]*)(?:\n|$)/.exec(src);
+                if (!m)
+                    return undefined;
+                footnoteDefs.set(m[1].trim(), m[2].trim());
+                return { type: 'footnoteDef', raw: m[0] }; // collected; renders nothing inline
+            },
+            renderer() {
+                return '';
+            },
+        },
+        {
+            // [^id] reference → superscript link to the endnote.
+            name: 'footnoteRef',
+            level: 'inline',
+            start(src) {
+                return src.match(/\[\^/)?.index;
+            },
+            tokenizer(src) {
+                const m = /^\[\^([^\]]+)\]/.exec(src);
+                if (!m)
+                    return undefined;
+                const id = m[1].trim();
+                if (!footnoteOrder.includes(id))
+                    footnoteOrder.push(id);
+                return { type: 'footnoteRef', raw: m[0], id };
+            },
+            renderer(token) {
+                const n = footnoteOrder.indexOf(token.id) + 1;
+                const eid = slugify(token.id);
+                return `<sup class="footnote-ref"><a href="#fn-${eid}" id="fnref-${eid}">${n}</a></sup>`;
+            },
+        },
+    ],
+});
 /** Render a doc's markdown text to HTML (synchronous, default marked options). */
 export function renderDocMarkdown(text) {
     return docMarked.parse(text);

package/dist/doc-system/site/docs.d.ts

@@ -14,11 +14,27 @@ export interface Doc {
     keywords?: string | string[];
     image?: string;
     noindex?: boolean;
+    author?: string;
+    date?: string;
 }
 export interface ExtractDocsOptions {
     paths: string[];
     ignore?: string[];
     output?: string;
 }
+/**
+ * Parse & strip a leading YAML frontmatter block (`---\n…\n---`). Every prose
+ * toolchain (Jekyll/Hugo/Astro/Obsidian/Pandoc) uses it, so authors paste it in;
+ * without this the `---` was rendered as content (and became the doc title).
+ *
+ * A minimal, dependency-free subset: `key: value` lines mapped onto doc metadata
+ * (`title`, `order`→number, `author`, `date`, `draft: true`→hidden). Only strips
+ * when the block actually parses as ≥1 key/value pair, so a genuine leading `---`
+ * horizontal rule is left alone. Frontmatter wins over the JSON-comment metadata.
+ */
+export declare function parseFrontmatter(content: string): {
+    data: Partial<Doc>;
+    body: string;
+};
 export declare function extractDocs(options: ExtractDocsOptions): Doc[];
 export declare function saveDocsJSON(docs: Doc[], outputPath: string): void;

package/dist/doc-system/site/docs.js

@@ -97,6 +97,55 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { pinnedSort } from '../nav-tree';
 const TRIM_REGEX = /^#+ |`/g;
+/**
+ * Parse & strip a leading YAML frontmatter block (`---\n…\n---`). Every prose
+ * toolchain (Jekyll/Hugo/Astro/Obsidian/Pandoc) uses it, so authors paste it in;
+ * without this the `---` was rendered as content (and became the doc title).
+ *
+ * A minimal, dependency-free subset: `key: value` lines mapped onto doc metadata
+ * (`title`, `order`→number, `author`, `date`, `draft: true`→hidden). Only strips
+ * when the block actually parses as ≥1 key/value pair, so a genuine leading `---`
+ * horizontal rule is left alone. Frontmatter wins over the JSON-comment metadata.
+ */
+export function parseFrontmatter(content) {
+    const m = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*/);
+    if (!m)
+        return { data: {}, body: content };
+    const data = {};
+    let matched = false;
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = line.match(/^([A-Za-z][\w-]*)\s*:\s*(.*)$/);
+        if (!kv)
+            continue;
+        matched = true;
+        const key = kv[1].toLowerCase();
+        const val = kv[2].trim().replace(/^["']|["']$/g, '');
+        if (key === 'title') {
+            if (val)
+                data.title = val; // empty title falls back to the H1
+        }
+        else if (key === 'order') {
+            const n = Number(val);
+            if (!Number.isNaN(n))
+                data.order = n;
+        }
+        else if (key === 'author') {
+            if (val)
+                data.author = val;
+        }
+        else if (key === 'date') {
+            if (val)
+                data.date = val;
+        }
+        else if (key === 'draft') {
+            if (/^(true|yes|1)$/i.test(val))
+                data.hidden = true; // drafts don't ship
+        }
+    }
+    if (!matched)
+        return { data: {}, body: content }; // a bare `---`, not frontmatter
+    return { data, body: content.slice(m[0].length).replace(/^\r?\n+/, '') };
+}
 function metadata(content, filePath) {
     // Ignore metadata-style comments INSIDE /*# ... */ doc blocks — those are
     // documentation examples, not real directives. Only line-starting blocks count
@@ -112,6 +161,10 @@ function metadata(content, filePath) {
             console.error('bad metadata in doc', filePath);
         }
     }
+    // An empty/blank `title` must not override the H1 (it produced blank nav
+    // entries) — drop it so the H1-derived title wins.
+    if (typeof data.title === 'string' && data.title.trim() === '')
+        delete data.title;
     return data;
 }
 function findMarkdownFiles(paths, ignore) {
@@ -129,6 +182,11 @@ function findMarkdownFiles(paths, ignore) {
             return;
         }
         files.forEach((file) => {
+            // Skip scaffolding / working files (Jekyll-style `_`-prefix): a
+            // `_template.md` or `_drafting-log.md` shouldn't leak into the corpus or
+            // the book.
+            if (file.startsWith('_'))
+                return;
             const filePath = path.join(dir, file);
             let stats;
             try {
@@ -141,13 +199,14 @@ function findMarkdownFiles(paths, ignore) {
                 traverseDirectory(filePath, ignore);
             }
             else if (path.extname(file) === '.md') {
-                const content = fs.readFileSync(filePath, 'utf8');
+                const { data: fm, body: content } = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
                 markdownFiles.push({
                     text: content,
                     title: content.split('\n')[0].replace(TRIM_REGEX, ''),
                     filename: file,
                     path: filePath,
                     ...metadata(content, filePath),
+                    ...fm, // frontmatter wins over JSON-comment metadata + the H1
                 });
             }
             else if (['.ts', '.js', '.css'].includes(path.extname(file))) {
@@ -180,13 +239,14 @@ function findMarkdownFiles(paths, ignore) {
             else if (stats.isFile()) {
                 const file = path.basename(dir);
                 if (path.extname(file) === '.md') {
-                    const content = fs.readFileSync(dir, 'utf8');
+                    const { data: fm, body: content } = parseFrontmatter(fs.readFileSync(dir, 'utf8'));
                     markdownFiles.push({
                         text: content,
                         title: content.split('\n')[0].replace(TRIM_REGEX, ''),
                         filename: file,
                         path: dir,
                         ...metadata(content, dir),
+                        ...fm,
                     });
                 }
             }