@zvndev/darkmown 2.9.0 → 2.10.1

package/types/builder.d.ts

@@ -53,6 +53,12 @@ export function stripRuntimeComments(source: string): string;
  *
  * Clean URLs mean a route like `/docs/` is served at both `/docs` and `/docs/`,
  * so each static route emits a path glob (`/docs`, `/docs/*`) that covers both.
+ *
+ * A page whose `:embed`s frame hosts beyond the base policy (a booking widget,
+ * a map) carries those hosts on its manifest entry (`assets.embedHosts`), and
+ * its block — static or reactive — states the unioned per-route policy
+ * ({@link routeCsp}). A reactive route with embed hosts can no longer inherit
+ * the catch-all, so it always gets its own block.
  * @param {RouteManifestEntry[]} manifest
  * @returns {string}
  */
@@ -68,7 +74,10 @@ export function renderCloudflareHeaders(manifest: RouteManifestEntry[]): string;
  * @typedef {object} RouteManifestEntry
  * @property {string} route Public route path.
  * @property {string} file Source file path, relative to cwd, POSIX-separated.
- * @property {{ skins: string[], scripts: string[], runtime: boolean }} assets
+ * @property {{ skins: string[], scripts: string[], runtime: boolean, embedHosts?: string[] }} assets
+ *   `embedHosts` is present only when the page's `:embed`s frame at least one
+ *   source the base CSP does not already cover — absent keeps a no-embed
+ *   site's routes.json byte-identical.
  */
 /**
  * One source route's record in the dev dependency map (`dist/.wd-dev-deps.json`),
@@ -107,6 +116,15 @@ export type BuildResult = {
         cached: number;
         unavailable: boolean;
     };
+    /**
+     *   Font-subset post-pass counts (2.10.0): freshly subsetted, cache-served, and
+     *   whether harfbuzzjs/wawoff2 could not be loaded at all.
+     */
+    fonts: {
+        subsetted: number;
+        cached: number;
+        unavailable: boolean;
+    };
     incremental?: {
         changed: string[];
         rebuilt: string[];
@@ -168,10 +186,16 @@ export type RouteManifestEntry = {
      * Source file path, relative to cwd, POSIX-separated.
      */
     file: string;
+    /**
+     *   `embedHosts` is present only when the page's `:embed`s frame at least one
+     *   source the base CSP does not already cover — absent keeps a no-embed
+     *   site's routes.json byte-identical.
+     */
     assets: {
         skins: string[];
         scripts: string[];
         runtime: boolean;
+        embedHosts?: string[];
     };
 };
 /**

package/types/catalog.d.ts

@@ -107,9 +107,10 @@ export type DirectiveEntry = {
      */
     name: string;
     /**
-     * A single line, or an opener with a closer.
+     * A single line, an opener with a
+     * closer, or a line that may optionally open a block (`@include … @endinclude`).
      */
-    kind: "line" | "block";
+    kind: "line" | "block" | "either";
     /**
      * One-line schematic (`[…]` = optional, `<…>` = slot).
      */

package/types/compiler/context.d.ts

@@ -26,6 +26,12 @@
  *   that opted into scoping (`scoped` first line). The builder emits these with
  *   the scope attribute and runs the unused-selector warning against the stamped
  *   subtree; the HTML stamp uses them to scope the matching page/include subtree.
+ * @property {Set<string>} embedHosts Frame sources (origins like
+ *   `https://app.example.com`, or `'self'` for a same-origin embed) of every
+ *   `:embed` on the page, collected AFTER the YouTube/Vimeo rewrite. The builder
+ *   records them on the route manifest entry so the per-route CSP's `frame-src`
+ *   authorizes exactly the hosts this page frames (see `routeCsp` in
+ *   src/headers.js).
  */
 /**
  * The pagination intent a `@loop … paginate N` records during compile, so the
@@ -129,6 +135,11 @@
  *   opener's `file:line` + raw text, set when descending into a loop body so the
  *   reactive-nesting-depth error can point at the offending opener.
  * @property {boolean} [loopMeta] Inside a loop body, so `$index`/`$first`/… are valid.
+ * @property {number} [includeBlockDepth] Enclosing block-form `@include`
+ *   CHILDREN levels (0 at page level, absent on a fresh file compile). Set
+ *   while compiling a block's children so a block include nested past one
+ *   level inside children is a compile error (WD616, together with the
+ *   include-stack depth check for include bodies).
  * @property {import("markdown-it").default} [md] Markdown-it instance selected for this file.
  * @property {(lines: string[], ctx: Ctx) => string} compileBody The body
  *   dispatcher, threaded through the context so block handlers (`:if`, `:::`,
@@ -410,6 +421,15 @@ export type Assets = {
      * subtree; the HTML stamp uses them to scope the matching page/include subtree.
      */
     scopedSkins: Set<string>;
+    /**
+     * Frame sources (origins like
+     * `https://app.example.com`, or `'self'` for a same-origin embed) of every
+     * `:embed` on the page, collected AFTER the YouTube/Vimeo rewrite. The builder
+     * records them on the route manifest entry so the per-route CSP's `frame-src`
+     * authorizes exactly the hosts this page frames (see `routeCsp` in
+     * src/headers.js).
+     */
+    embedHosts: Set<string>;
 };
 /**
  * The pagination intent a `@loop … paginate N` records during compile, so the
@@ -630,6 +650,14 @@ export type Ctx = {
      * Inside a loop body, so `$index`/`$first`/… are valid.
      */
     loopMeta?: boolean | undefined;
+    /**
+     * Enclosing block-form `@include`
+     * CHILDREN levels (0 at page level, absent on a fresh file compile). Set
+     * while compiling a block's children so a block include nested past one
+     * level inside children is a compile error (WD616, together with the
+     * include-stack depth check for include bodies).
+     */
+    includeBlockDepth?: number | undefined;
     /**
      * Markdown-it instance selected for this file.
      */

package/types/compiler/includes.d.ts

@@ -101,6 +101,15 @@ export function resolveInclude(spec: string, fromFile: string, context: Paths, a
  * @returns {boolean}
  */
 export function isAllowedInclude(file: string, context: Paths, reader?: import("./reader.js").Reader): boolean;
+/**
+ * The compiled children HTML for the include currently compiling, or null when
+ * the file is not being compiled as an include at all (a top-level page) — in
+ * which case a `{ children }` line stays literal text. An include called
+ * WITHOUT a block carries "" (the slot renders empty).
+ * @param {import("./context.js").Ctx} ctx
+ * @returns {string | null}
+ */
+export function childrenSlot(ctx: import("./context.js").Ctx): string | null;
 /**
  * Warn when a plain `.md` file contains `.wd`-only syntax that stays inert.
  * @param {string} body
@@ -109,6 +118,20 @@ export function isAllowedInclude(file: string, context: Paths, reader?: import("
  * @returns {void}
  */
 export function scanMarkdownHints(body: string, file: string, comp: Compilation): void;
+/**
+ * Scope key carrying the compiled children HTML for the include currently
+ * being compiled. Control-character-prefixed so no author-visible name can
+ * collide with it or read it through `{ }` interpolation.
+ */
+export const INCLUDE_CHILDREN: "\0children";
+/**
+ * A line that is exactly the slot marker (`{ children }`, whitespace-tolerant),
+ * matching the spelling freedom of `{ name }` interpolation. Shared by the
+ * body parser (which splices the slot) and the include handler (which scans an
+ * include's body for whether the slot is ever used).
+ * @type {RegExp}
+ */
+export const CHILDREN_SLOT_LINE: RegExp;
 export type Paths = import("./context.js").Paths;
 export type Assets = import("./context.js").Assets;
 export type Compilation = import("./context.js").Compilation;

package/types/compiler/structure.d.ts

@@ -24,12 +24,64 @@ export function takeA11yAttrs(rest: string, ctx: Ctx, index: number, what: strin
  */
 export function a11yAttrHtml(attrs: [string, string][]): string;
 /**
+ * Compile an `@include` line — inline form (`@include /nav.wd`) or block form
+ * (`@include /card.wd … @endinclude`, with `childrenLines` holding the lines
+ * between opener and closer, captured by {@link scanIncludeBlock}).
+ *
+ * Block form is compile-time macro expansion and nothing more: the children
+ * lines compile in the CALLER's context (its scope, its `:state`, its loop
+ * item when the call sits in a `@loop` body) BEFORE the target compiles, and
+ * the resulting HTML rides into the include's scope under
+ * {@link INCLUDE_CHILDREN}, where the body parser splices it at each
+ * `{ children }` slot line. No runtime marker, no reactivity of its own.
+ * Children compile ONCE even when the include places the slot twice, so state
+ * a child line declares is declared once in the caller.
+ *
+ * The include file's own frontmatter may declare `defaults: [name="value" …]`
+ * fallback values for `with` arguments (see {@link parseIncludeDefaults}); a
+ * caller-provided argument always wins over a default, and an argument with
+ * neither keeps the literal-braces behavior.
  * @param {string} line
  * @param {Ctx} ctx
  * @param {number} index 0-based line index for `file:line` errors.
+ * @param {string[]} [childrenLines] Lines between `@include` and `@endinclude`
+ *   for the block form; undefined for the inline form.
  * @returns {string}
  */
-export function handleInclude(line: string, ctx: Ctx, index: number): string;
+export function handleInclude(line: string, ctx: Ctx, index: number, childrenLines?: string[]): string;
+/**
+ * Scan ahead from an `@include` opener for the `@endinclude` that pairs with
+ * it. Pairing is nearest-opener-first: a nested `@include` line pushes, an
+ * `@endinclude` line pops the most recent unclosed opener, and the first
+ * `@endinclude` found with nothing on the stack belongs to THIS opener — so
+ * nested blocks pair correctly, and an inline `@include` earlier in the file
+ * than a block (the common nav-include-then-card-block page) is unaffected.
+ * Fenced code is skipped, exactly as in the other block scanners.
+ *
+ * Returns null when no closer pairs — the include is the INLINE form, which
+ * stays legal (backward compatible): an opener that never pairs is an inline
+ * include followed by ordinary prose, and the two are indistinguishable, so
+ * there is deliberately no "unclosed block" error.
+ * @param {string[]} lines The current body slice.
+ * @param {number} start 0-based index of the `@include` opener line.
+ * @returns {{ body: string[], end: number } | null} The children lines and the
+ *   closer's 0-based index, or null for the inline form.
+ */
+export function scanIncludeBlock(lines: string[], start: number): {
+    body: string[];
+    end: number;
+} | null;
+/**
+ * `@endinclude` reached the body dispatcher, meaning no `@include` opener
+ * claimed it — the one-closer-too-many case (a typo'd closer, or a nested
+ * block attempted inside a children block, where the inner opener already
+ * took the closer the author meant for the outer one). Always throws.
+ * @param {string} line The offending line, for the message.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line`.
+ * @returns {never}
+ */
+export function strayEndinclude(line: string, ctx: Ctx, index: number): never;
 /**
  * @param {string} header
  * @param {string[]} bodyLines

package/types/errors.d.ts

@@ -33,8 +33,9 @@ export function errorsMarkdown(): string;
  * @property {string} title Short name for the mistake.
  * @property {string} cause What the author wrote that triggers it.
  * @property {string} fix The corrective action, in one line.
- * @property {string} [example] A concrete, compilable line, sourced from the
- *   compiler's own `*_EXAMPLE` constants.
+ * @property {string} [example] A concrete, compilable line (or, for block
+ *   constructs like the `.skin` at-rules, a minimal compilable block), sourced
+ *   from the compiler's own `*_EXAMPLE` constants.
  */
 /** The subsystem blocks, in code order. */
 /** @type {ErrorArea[]} */
@@ -93,8 +94,9 @@ export type ErrorEntry = {
      */
     fix: string;
     /**
-     * A concrete, compilable line, sourced from the
-     * compiler's own `*_EXAMPLE` constants.
+     * A concrete, compilable line (or, for block
+     * constructs like the `.skin` at-rules, a minimal compilable block), sourced
+     * from the compiler's own `*_EXAMPLE` constants.
      */
     example?: string | undefined;
 };

package/types/font-subset.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Subset every project-local font referenced by the emitted stylesheets and
+ * rewrite the dist CSS to lead with the subset woff2.
+ *
+ * Skips, none of them errors: remote/protocol-relative/data/relative URLs
+ * (silently), already-woff2 sources (silently), URLs that escape or miss the
+ * project (silently — a broken link is an authoring bug, not a subsetting one).
+ * An unreadable font file, and one the toolchain fails on, get a hint naming
+ * the file and ship as-is. With no `@font-face` in any emitted stylesheet the
+ * pass is a no-op and never even scans the HTML.
+ * @param {Paths} paths
+ * @param {{ cacheDir?: string, quiet?: boolean,
+ *   runJobs?: (payload: { charset: number[], jobs: SubsetJob[] }) => SubsetResult }} [options]
+ *   `quiet` suppresses the hints (dev-server rebuilds). `runJobs` is the subset
+ *   seam — the default spawns the worker process; tests inject fakes for the
+ *   unavailable/failure paths.
+ * @returns {FontSubsetPlan}
+ */
+export function subsetFonts(paths: Paths, options?: {
+    cacheDir?: string;
+    quiet?: boolean;
+    runJobs?: (payload: {
+        charset: number[];
+        jobs: SubsetJob[];
+    }) => SubsetResult;
+}): FontSubsetPlan;
+/**
+ * The default subset seam: run every pending job in ONE child process (the
+ * build is synchronous; the wasm API is not), communicating through temp JSON
+ * files rather than stdio so a large payload never hits a pipe buffer. The
+ * worker always writes a results file — a missing or unparsable one means the
+ * child itself died (crashed, or killed by the spawn timeout), which is
+ * reported as `unavailable` (the build then behaves as if the toolchain were
+ * absent: a hint, no subsets, no failure).
+ * @param {{ charset: number[], jobs: SubsetJob[] }} payload
+ * @param {(cmd: string, args: string[], opts: object) => unknown} [spawn]
+ *   Injectable for tests; the real one is `spawnSync`.
+ * @param {number} [timeoutMs] The worker is killed after this long (default
+ *   two minutes), so a hung toolchain call cannot stall a build forever. The
+ *   kill lands in the same `unavailable` path as any other dead child.
+ * @returns {SubsetResult}
+ */
+export function runSubsetJobs(payload: {
+    charset: number[];
+    jobs: SubsetJob[];
+}, spawn?: (cmd: string, args: string[], opts: object) => unknown, timeoutMs?: number): SubsetResult;
+/**
+ * The subset charset for a build: the base set plus every code point appearing
+ * in the given texts (the emitted pages' HTML). Numeric character references
+ * (`★`, `★`) are decoded first so a character the compiler emitted
+ * as an entity still lands in the union. Tags and attribute syntax contribute
+ * only ASCII, which the base set already carries, so the whole-file scan can
+ * only ever over-include by a handful of glyphs.
+ * @param {string[]} texts
+ * @returns {number[]} Sorted ascending, deduped.
+ */
+export function charsetFromTexts(texts: string[]): number[];
+/**
+ * Rewrite the `@font-face` blocks of an emitted stylesheet so each subsetted
+ * font's `src` leads with the subset woff2, the original kept as fallback:
+ *   src: url("/f/a-subset.woff2") format("woff2"), url("/f/a.ttf") format("truetype");
+ * Only the `src` declaration changes — font-display and every other descriptor
+ * pass through byte-identically. Idempotent: a block already carrying the
+ * subset reference (a previous build's rewrite of a since-unedited skin) is
+ * left alone.
+ * @param {string} css Emitted stylesheet contents.
+ * @param {Map<string, string>} subsetByUrl url() target as written → subset URL.
+ * @returns {string}
+ */
+export function rewriteFontFaceCss(css: string, subsetByUrl: Map<string, string>): string;
+/** The base charset, sorted ascending. */
+export const BASE_CODEPOINTS: number[];
+export type Paths = import("./config.js").Paths;
+/**
+ * One subset handed to the worker: reduce `source` to the shared charset and
+ * write the woff2 result to `out`, the cache path.
+ */
+export type SubsetJob = {
+    /**
+     * Absolute path of the original font file.
+     */
+    source: string;
+    /**
+     * Absolute cache path the subset woff2 is written to.
+     */
+    out: string;
+};
+/**
+ * What the worker reports back. `unavailable` means the toolchain could not be
+ * loaded at all (harfbuzzjs/wawoff2 not installed) — every pending font then
+ * ships unsubsetted. `failed` carries one entry per font the toolchain itself
+ * rejected (corrupt payload, unsupported format).
+ */
+export type SubsetResult = {
+    unavailable: boolean;
+    failed: {
+        file: string;
+        error: string;
+    }[];
+};
+/**
+ * The post-pass result, feeding the build summary. `unavailable` marks the
+ * toolchain-absent build (which is otherwise identical to not having the
+ * feature).
+ */
+export type FontSubsetPlan = {
+    /**
+     * Fonts freshly subsetted this build.
+     */
+    subsetted: number;
+    /**
+     * Fonts served from the on-disk cache.
+     */
+    cached: number;
+    /**
+     * harfbuzzjs/wawoff2 could not be loaded.
+     */
+    unavailable: boolean;
+};
+/**
+ * A project-local font referenced by an emitted `@font-face` rule.
+ */
+export type FontRef = {
+    /**
+     * The url() target exactly as written in the CSS.
+     */
+    url: string;
+    /**
+     * Absolute path of the font file it resolves to.
+     */
+    source: string;
+    /**
+     * Served URL of the subset (`<stem>-subset.woff2`).
+     */
+    subsetUrl: string;
+    /**
+     * Absolute dist path the subset is written to.
+     */
+    subsetDist: string;
+    /**
+     * Absolute cache path, set once the hashes are known.
+     */
+    cacheFile?: string | undefined;
+};

package/types/headers.d.ts

@@ -1,3 +1,17 @@
+/**
+ * The CSP for one route: its base policy (`REACTIVE_CSP`/`STATIC_CSP`) with the
+ * page's `:embed` frame hosts unioned into `frame-src`. The compiler records the
+ * FINAL iframe src of every `:embed` (after the YouTube/Vimeo rewrite), so a
+ * generic embed — a booking widget, a map — is authorized on exactly the pages
+ * that carry it instead of being blocked by the shipped policy. YouTube/Vimeo
+ * embeds dedupe against the base list, so a page whose embeds are all covered
+ * already produces a byte-identical policy, as does a page with no embeds.
+ * @param {boolean} reactive Whether the route ships the reactive runtime.
+ * @param {Iterable<string>} [embedHosts] Origins (`https://app.example.com`) or
+ *   `'self'` for a same-origin embed, collected at compile time.
+ * @returns {string}
+ */
+export function routeCsp(reactive: boolean, embedHosts?: Iterable<string>): string;
 /**
  * The full security-header set for one response, including the CSP variant.
  * @param {boolean} reactive Whether the route ships the reactive runtime.

package/types/image-variants.d.ts

@@ -29,14 +29,18 @@ export function generateImageVariants(paths: Paths, options?: {
  * build is synchronous; sharp is not), communicating through temp JSON files
  * rather than stdio so a large job list never hits a pipe buffer. The worker
  * always writes a results file — a missing or unparsable one means the child
- * itself died, which is reported as `unavailable` (the build then behaves as
- * if sharp were absent: a hint, no variants, no failure).
+ * itself died (crashed, or killed by the spawn timeout), which is reported as
+ * `unavailable` (the build then behaves as if sharp were absent: a hint, no
+ * variants, no failure).
  * @param {ResizeJob[]} jobs
  * @param {(cmd: string, args: string[], opts: object) => unknown} [spawn]
  *   Injectable for tests; the real one is `spawnSync`.
+ * @param {number} [timeoutMs] The worker is killed after this long (default
+ *   two minutes), so a hung sharp call cannot stall a build forever. The kill
+ *   lands in the same `unavailable` path as any other dead child.
  * @returns {ResizeResult}
  */
-export function runResizeJobs(jobs: ResizeJob[], spawn?: (cmd: string, args: string[], opts: object) => unknown): ResizeResult;
+export function runResizeJobs(jobs: ResizeJob[], spawn?: (cmd: string, args: string[], opts: object) => unknown, timeoutMs?: number): ResizeResult;
 /**
  * @typedef {import("./config.js").Paths} Paths
  */

package/types/router.d.ts

@@ -38,6 +38,11 @@ export function discoverRoutes(routesRoot: string, options?: {
 export function isDraft(meta: Meta): boolean;
 /**
  * Derive a public route path from a source file path.
+ *
+ * Fail-closed on control/whitespace characters: the route string flows RAW
+ * into generated config (`dist/_headers` blocks, llms.txt lines), where a
+ * newline in a filename would inject whole config lines. Rejecting here, at
+ * the one route-derivation chokepoint, protects every downstream sink at once.
  * @param {string} routesRoot Absolute path to `site/pages`.
  * @param {string} file Absolute path to the source file.
  * @returns {string}

package/types/skin.d.ts

@@ -33,16 +33,21 @@ export function scopeIdFor(relPath: string): string;
  * selectors), they are ALWAYS global (never scope-stamped, same contract as
  * `tokens`), and their declaration values use the same alias/`$token` pipeline.
  * @param {string} source
- * @param {{ scope?: string, subjects?: Set<string> }} [opts] `scope`: the scope
- *   id enabling scoped mode. `subjects`: an optional set the compiler fills with
- *   every scoped subject token (`.card`, `h2`, `#id`) for the unused-selector
- *   warning, so the caller need not re-parse the source.
+ * @param {{ scope?: string, subjects?: Set<string>, file?: string }} [opts]
+ *   `scope`: the scope id enabling scoped mode. `subjects`: an optional set the
+ *   compiler fills with every scoped subject token (`.card`, `h2`, `#id`) for
+ *   the unused-selector warning, so the caller need not re-parse the source.
+ *   `file`: the skin's path, threaded into author-facing errors so they report
+ *   `file:line` (the builder always passes it; a bare call reports `on line N`).
  * @returns {string}
  */
 export function compileSkin(source: string, opts?: {
     scope?: string;
     subjects?: Set<string>;
+    file?: string;
 }): string;
+export const FONT_FACE_EXAMPLE: "@font-face\n  font-family \"Newsreader\"";
+export const KEYFRAMES_EXAMPLE: "@keyframes fade-in\n  to\n    opacity 1";
 /**
  * A nesting frame in the indentation stack.
  */