@zvndev/darkmown 2.9.0 → 2.10.0

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/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.