@zvndev/darkmown 2.8.0 → 2.10.0

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/compiler.d.ts

@@ -4,7 +4,7 @@
  * a different source (see `compileFromMemory`).
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {import("./config.js").Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string }, site?: import("./compiler/page.js").SiteContext, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader }} [options]
+ * @param {{ feed?: { href: string, title: string }, site?: import("./compiler/page.js").SiteContext, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader, imageVariants?: Map<string, number[]> | null }} [options]
  * @returns {CompiledPage}
  */
 export function compilePage(file: string, context: import("./config.js").Paths, options?: {
@@ -16,6 +16,7 @@ export function compilePage(file: string, context: import("./config.js").Paths,
     collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>;
     vars?: Record<string, unknown>;
     reader?: import("./compiler/reader.js").Reader;
+    imageVariants?: Map<string, number[]> | null;
 }): CompiledPage;
 /**
  * Compile a source file into its body HTML, frontmatter, and assets (no page
@@ -26,9 +27,11 @@ export function compilePage(file: string, context: import("./config.js").Paths,
  * @param {Record<string, unknown>} [vars] Initial static scope variables.
  * @param {Map<string, import("./compiler/collections.js").CollectionRow[]>} [collections]
  * @param {import("./compiler/reader.js").Reader} [reader] Source reader.
+ * @param {Map<string, number[]> | null} [imageVariants] Builder-generated
+ *   responsive variants (original's absolute source path → widths).
  * @returns {CompiledDocument}
  */
-export function compileDocument(file: string, context: import("./config.js").Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, reader?: import("./compiler/reader.js").Reader): CompiledDocument;
+export function compileDocument(file: string, context: import("./config.js").Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, reader?: import("./compiler/reader.js").Reader, imageVariants?: Map<string, number[]> | null): CompiledDocument;
 /**
  * Harden every `<img>` in an assembled page body, reading intrinsic dimensions
  * from the real filesystem by default.

package/types/font-subset.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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, 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`.
+ * @returns {SubsetResult}
+ */
+export function runSubsetJobs(payload: {
+    charset: number[];
+    jobs: SubsetJob[];
+}, spawn?: (cmd: string, args: string[], opts: object) => unknown): 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

@@ -0,0 +1,131 @@
+/**
+ * Scan `site/pages` for raster images and generate `@<width>` variants into
+ * `dist`, returning the variant map the compiler wires into srcsets.
+ *
+ * Skips, none of them errors: `@<width>` variant files themselves (they are
+ * output, not sources), hidden-path and symlinked files (mirroring
+ * `emitPageAssets`, which would never publish them), images at or under 700px
+ * wide (already small), widths at or above the intrinsic size (never
+ * upscale), and widths the author already provided (their file wins). An image
+ * whose dimensions cannot be read, and one sharp fails on, get a hint naming
+ * the file and ship without variants.
+ * @param {Paths} paths
+ * @param {{ widths?: number[], cacheDir?: string, quiet?: boolean,
+ *   runJobs?: (jobs: ResizeJob[]) => ResizeResult }} [options]
+ *   `widths` overrides {@link DEFAULT_VARIANT_WIDTHS}. `quiet` suppresses the
+ *   hints (dev-server rebuilds, which already printed them at the initial
+ *   build). `runJobs` is the resize seam — the default spawns the worker
+ *   process; tests inject fakes for the unavailable/crash paths.
+ * @returns {ImageVariantPlan}
+ */
+export function generateImageVariants(paths: Paths, options?: {
+    widths?: number[];
+    cacheDir?: string;
+    quiet?: boolean;
+    runJobs?: (jobs: ResizeJob[]) => ResizeResult;
+}): ImageVariantPlan;
+/**
+ * The default resize seam: run every pending job in ONE child process (the
+ * 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).
+ * @param {ResizeJob[]} jobs
+ * @param {(cmd: string, args: string[], opts: object) => unknown} [spawn]
+ *   Injectable for tests; the real one is `spawnSync`.
+ * @returns {ResizeResult}
+ */
+export function runResizeJobs(jobs: ResizeJob[], spawn?: (cmd: string, args: string[], opts: object) => unknown): ResizeResult;
+/**
+ * @typedef {import("./config.js").Paths} Paths
+ */
+/**
+ * One resize handed to the worker: shrink `source` to `width` pixels wide and
+ * write it (in its own format) to `out`, the cache path.
+ * @typedef {object} ResizeJob
+ * @property {string} source Absolute path of the original image.
+ * @property {string} out Absolute cache path the resized variant is written to.
+ * @property {number} width Target width in pixels (always below the intrinsic).
+ * @property {"jpeg" | "png" | "webp"} format Output encoder, from the source extension.
+ */
+/**
+ * What the worker reports back. `unavailable` means sharp could not be loaded
+ * at all (not installed, or a broken native binding) — every pending image
+ * then ships without variants. `failed` carries one entry per image that
+ * sharp itself rejected (corrupt payload, unsupported encoding).
+ * @typedef {object} ResizeResult
+ * @property {boolean} unavailable
+ * @property {{ file: string, width: number, error: string }[]} failed
+ */
+/**
+ * The pre-pass result: `variants` is the map the compiler's srcset wiring
+ * consults (original's ABSOLUTE source path → sorted widths generated into
+ * dist), and the counts feed the build summary. `unavailable` marks the
+ * sharp-absent build (which is otherwise identical to not having the feature).
+ * @typedef {object} ImageVariantPlan
+ * @property {Map<string, number[]>} variants
+ * @property {number} generated Variants resized this build.
+ * @property {number} cached Variants served from the on-disk cache.
+ * @property {boolean} unavailable sharp could not be loaded.
+ */
+/** The widths generated by default, both comfortably under a typical source. */
+export const DEFAULT_VARIANT_WIDTHS: number[];
+export type Paths = import("./config.js").Paths;
+/**
+ * One resize handed to the worker: shrink `source` to `width` pixels wide and
+ * write it (in its own format) to `out`, the cache path.
+ */
+export type ResizeJob = {
+    /**
+     * Absolute path of the original image.
+     */
+    source: string;
+    /**
+     * Absolute cache path the resized variant is written to.
+     */
+    out: string;
+    /**
+     * Target width in pixels (always below the intrinsic).
+     */
+    width: number;
+    /**
+     * Output encoder, from the source extension.
+     */
+    format: "jpeg" | "png" | "webp";
+};
+/**
+ * What the worker reports back. `unavailable` means sharp could not be loaded
+ * at all (not installed, or a broken native binding) — every pending image
+ * then ships without variants. `failed` carries one entry per image that
+ * sharp itself rejected (corrupt payload, unsupported encoding).
+ */
+export type ResizeResult = {
+    unavailable: boolean;
+    failed: {
+        file: string;
+        width: number;
+        error: string;
+    }[];
+};
+/**
+ * The pre-pass result: `variants` is the map the compiler's srcset wiring
+ * consults (original's ABSOLUTE source path → sorted widths generated into
+ * dist), and the counts feed the build summary. `unavailable` marks the
+ * sharp-absent build (which is otherwise identical to not having the feature).
+ */
+export type ImageVariantPlan = {
+    variants: Map<string, number[]>;
+    /**
+     * Variants resized this build.
+     */
+    generated: number;
+    /**
+     * Variants served from the on-disk cache.
+     */
+    cached: number;
+    /**
+     * sharp could not be loaded.
+     */
+    unavailable: boolean;
+};