@zvndev/darkmown 2.1.0 → 2.3.0

package/types/compiler/fetch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Parse a keyword-arg `:fetch` directive into a lifecycle-aware marker.
+ * Auto-declares four state keys (value/error/loading/empty), seeds them, and
+ * emits `data-wd-fetch-*` attributes (url/method/when/timeout/retry/headers/
+ * body/deps) consumed by the runtime's `startFetch`.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleFetch(line: string, ctx: Ctx, index: number): string;
+/**
+ * Validate a `:fetch` (or `refresh=`) URL's scheme at compile time. Mirrors the
+ * `:try` href guard: relative paths (`/`, `./`, `../`, bare), an `http(s)://`
+ * URL, or a leading `{ state }` interpolation are allowed; a protocol-relative
+ * `//host` or any non-http(s) scheme (`file:`, `data:`, `javascript:`, …) is
+ * rejected. Interpolated values are percent-encoded by the runtime, so a scheme
+ * cannot be injected through state at request time.
+ * @param {string} url
+ * @param {Ctx} ctx
+ * @param {string} [what] Option name for the error message.
+ * @returns {string}
+ */
+export function validateFetchUrl(url: string, ctx: Ctx, what?: string): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+export const FETCH_EXAMPLE: ":fetch todos from \"/api/todos.json\" when=visible";
+export type Ctx = import("./context.js").Ctx;

package/types/compiler/format.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Parse the inside of a `{ … }` binding into its path and an ordered list of
+ * pipe stages. `{ price | money }` → `{ path: "price", stages: [{name:"money",args:[]}] }`.
+ * Stage validation (unknown formatter) happens in {@link validatePipes}.
+ * @param {string} inner
+ * @returns {{ path: string, stages: Stage[] }}
+ */
+export function parsePipes(inner: string): {
+    path: string;
+    stages: Stage[];
+};
+/**
+ * Compile-time validation: every stage must name a known formatter. Throws a
+ * corrective compile error otherwise. Returns the parsed `{ path, stages }`.
+ * @param {string} inner
+ * @param {Ctx} ctx
+ * @returns {{ path: string, stages: Stage[] }}
+ */
+export function validatePipes(inner: string, ctx: Ctx): {
+    path: string;
+    stages: Stage[];
+};
+/**
+ * Run a resolved value through a pipe chain at build time. Returns the final
+ * value (a string or number); the caller stringifies for output. Mirrors the
+ * runtime's `applyFmt`.
+ * @param {any} value
+ * @param {Stage[]} stages
+ * @returns {any}
+ */
+export function applyPipeline(value: any, stages: Stage[]): any;
+/** @type {Record<string, (list: any[], field?: string) => number>} */
+export const AGGREGATES: Record<string, (list: any[], field?: string) => number>;
+/**
+ * The whitelist. Each formatter is a pure function of (value, args) — no clock,
+ * no DOM, no globals beyond `Intl` — so a static value folds deterministically at
+ * build time and a reactive value formats identically in the browser.
+ * @type {Record<string, (value: any, args: any[]) => string | number>}
+ */
+export const FORMATTERS: Record<string, (value: any, args: any[]) => string | number>;
+/** Formatter names, for error messages and the runtime mirror check. */
+export const FORMATTER_NAMES: string[];
+export function fmtAttr(stages: Stage[]): string;
+export function stagesFromAttr(json: string): Stage[];
+export type Ctx = import("./context.js").Ctx;
+export type Stage = {
+    name: string;
+    args: Array<string | number | boolean | null>;
+};

package/types/compiler/forms.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @param {string} line
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleForm(line: string, bodyLines: string[], ctx: Ctx, index: number): string;
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleInput(line: string, ctx: Ctx, index: number): string;
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleBind(line: string, ctx: Ctx, index: number): string;
+/**
+ * `:slider name [= value] [min=N] [max=N] [step=N] [aria-label="…"] [persist]` — a
+ * range input two-way bound to a NUMBER :state. With `= value` it declares the state
+ * inline (seeding it numeric) and may `persist`; without `=` it binds to an already-
+ * declared :state. Pure compile-time: it reuses the runtime's input binding (range
+ * values coerce to Number), so it ships NO behavior module.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleSlider(line: string, ctx: Ctx, index: number): string;
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleSubmit(line: string, ctx: Ctx, index: number): string;
+/**
+ * `:textarea name [placeholder="…"] [rows=N] [required]` → a `<textarea>`. Like
+ * `:input`, it derives a non-visual aria-label from the placeholder (else the
+ * humanized name) when the author supplies none. Captured by the runtime's
+ * FormData exactly like `:input` — no runtime change needed.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleTextarea(line: string, ctx: Ctx, index: number): string;
+/**
+ * `:select name [required]` followed by `- Label` list lines → a `<select>` with
+ * one `<option>` per label (value === label). Derives an aria-label from the
+ * humanized name when none is given. Captured by FormData like the other fields.
+ * @param {string} line
+ * @param {string[]} optionLines The following `- Label` lines consumed by dispatch.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleSelect(line: string, optionLines: string[], ctx: Ctx, index: number): string;
+/**
+ * `:checkbox name [required]` / `:radio name [required]` followed by `- Label`
+ * lines → a labelled group of `<input type=checkbox|radio>`, each sharing `name`
+ * with value === label and wrapped in its own `<label>`. The group is a
+ * `role="group"` / `role="radiogroup"` container with an aria-label (explicit or
+ * humanized from the name). Checkbox groups are marked `data-wd-multi="name"` so
+ * the runtime captures every checked value as an array (`FormData.getAll`); radio
+ * groups capture a single value like `:input`. Flags: `required` (radio → the
+ * group; not emitted on checkboxes, where "at least one" has no native HTML form),
+ * `disabled` (whole group), `autofocus` (first control).
+ * @param {string} line
+ * @param {string[]} optionLines The following `- Label` lines consumed by dispatch.
+ * @param {Ctx} ctx
+ * @param {"checkbox" | "radio"} kind
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleChoiceGroup(line: string, optionLines: string[], ctx: Ctx, kind: "checkbox" | "radio", index: number): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+export const FORM_EXAMPLE: ":form into contact";
+export const INPUT_EXAMPLE: ":input email type=email required";
+export const TEXTAREA_EXAMPLE: ":textarea message placeholder=\"Your message\" rows=4";
+export const SELECT_EXAMPLE: ":select topic";
+export const CHECKBOX_EXAMPLE: ":checkbox toppings";
+export const RADIO_EXAMPLE: ":radio size";
+export const SUBMIT_EXAMPLE: ":submit \"Send\"";
+export const BIND_EXAMPLE: ":bind query placeholder=\"Search\"";
+export const SLIDER_EXAMPLE: ":slider volume = 50 min=0 max=100 step=1";
+export type Ctx = import("./context.js").Ctx;

package/types/compiler/frontmatter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @typedef {import("./context.js").Meta} Meta
+ * @typedef {import("./context.js").FrontmatterValue} FrontmatterValue
+ * @typedef {import("./context.js").Compilation} Compilation
+ */
+/**
+ * Split a raw file into its frontmatter `meta` and `body`. `bodyLine` is the
+ * 0-based file line index the body starts on (the number of lines the
+ * frontmatter block consumed) so compile errors can report true file lines.
+ * @param {string} raw Full file contents.
+ * @param {string} [file] Source path, used only for error messages.
+ * @returns {{ meta: Meta, body: string, bodyLine: number }}
+ */
+export function parseFrontmatter(raw: string, file?: string): {
+    meta: Meta;
+    body: string;
+    bodyLine: number;
+};
+/**
+ * Warn (non-fatal) when a file looks like it MEANT to open frontmatter but forgot
+ * the leading `---`: the first content line is a `key: value` pair and a bare
+ * `---` fence appears within the opening lines. Conservative — a normal markdown
+ * body whose first line happens to contain a colon (with no early `---`) is left
+ * alone, since `---` is also a valid horizontal rule.
+ * @param {string} raw
+ * @param {string} file
+ * @param {Compilation} comp
+ * @returns {void}
+ */
+export function warnLikelyFrontmatter(raw: string, file: string, comp: Compilation): void;
+export type Meta = import("./context.js").Meta;
+export type FrontmatterValue = import("./context.js").FrontmatterValue;
+export type Compilation = import("./context.js").Compilation;

package/types/compiler/fs-reader.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A {@link import("./reader.js").Reader} backed by `node:fs`. Each method is a
+ * thin pass-through to the synchronous fs call the compiler used before the
+ * reader abstraction, so an fs-backed compile stays byte-identical.
+ * @returns {import("./reader.js").Reader}
+ */
+export function fsReader(): import("./reader.js").Reader;

package/types/compiler/image-size.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read an image's intrinsic dimensions from its header bytes.
+ * @param {Uint8Array} bytes Raw file contents (a Node `Buffer` is a `Uint8Array`).
+ * @returns {Dimensions | null} The size, or null when the bytes are empty, of an
+ *   unsupported format, or malformed. Never throws.
+ */
+export function imageSize(bytes: Uint8Array): Dimensions | null;
+/**
+ * Intrinsic pixel size.
+ */
+export type Dimensions = {
+    width: number;
+    height: number;
+};

package/types/compiler/includes.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @typedef {import("./context.js").Paths} Paths
+ * @typedef {import("./context.js").Assets} Assets
+ * @typedef {import("./context.js").Compilation} Compilation
+ */
+/**
+ * Read a `.skin` file's first meaningful line (skipping `//` line comments,
+ * `/* … *\/` block comments, blanks, and decorative dividers — the same skip
+ * rules `compileSkin` applies) to decide whether it opts into scoping. A skin
+ * scopes its selectors ONLY when that first line is exactly `scoped`; otherwise
+ * it is global and untouched. This is the single source for "is this skin
+ * scoped + what is its id", so the CSS rewrite (builder) and the HTML stamp
+ * (page/include) always agree on both.
+ * @param {string} skinPath Absolute path to the colocated `.skin` file.
+ * @param {string} cwd Project root, for the path-based scope id.
+ * @param {import("./reader.js").Reader} reader Source reader for the skin file.
+ * @returns {{ scoped: boolean, scopeId: string }}
+ */
+export function scopeInfoForSkin(skinPath: string, cwd: string, reader: import("./reader.js").Reader): {
+    scoped: boolean;
+    scopeId: string;
+};
+/**
+ * The scope info for a page/include's OWN colocated `.skin` sibling, or null
+ * when there is no sibling skin. Used by the HTML stamp sites: a route's own
+ * scoped skin → stamp the page body; an include's scoped skin → stamp the
+ * returned subtree. Resolution mirrors `collectColocatedAssets` (same stem,
+ * `.skin` extension).
+ * @param {string} file Absolute path to the page/include source file.
+ * @param {Paths} context
+ * @param {import("./reader.js").Reader} reader Source reader for the skin file.
+ * @returns {{ scoped: boolean, scopeId: string } | null}
+ */
+export function scopedSkinFor(file: string, context: Paths, reader: import("./reader.js").Reader): {
+    scoped: boolean;
+    scopeId: string;
+} | null;
+/**
+ * Stamp `data-wd-scope="<id>"` onto every opening tag of a subtree — the HTML
+ * half of compile-time scoped styles, mirroring {@link enhanceImages}: a
+ * compile-time post-pass over assembled HTML, zero runtime JS. Every element
+ * start tag that doesn't already carry a scope attribute gets one, so the scoped
+ * stylesheet (whose selectors end in `[data-wd-scope="<id>"]`) matches inside
+ * this subtree and nowhere else. Void/self-closing tags are stamped too (the
+ * attribute is valid on any element). Closing tags, comments, doctype, and the
+ * `<!`/`<?` families are left alone. A tag that ALREADY has a `data-wd-scope`
+ * (e.g. a nested include with its own scope) keeps its own — first stamp wins.
+ *
+ * Raw-text / escapable-raw-text elements (`script`, `style`, `textarea`,
+ * `title`) are special-cased: their OPENING tag is stamped (valid), but their
+ * BODY is left byte-intact — `<`/`>` inside a `<script>` are JavaScript, not
+ * markup, so stamping there would corrupt the content. A small tokenizer walks
+ * tag-by-tag (quote-aware in attribute lists) and, on entering a raw-text
+ * element, copies through verbatim until the matching close tag.
+ * @param {string} html Subtree HTML to scope.
+ * @param {string} scopeId Scope id (from {@link import("../skin.js").scopeIdFor}).
+ * @returns {string}
+ */
+export function stampScope(html: string, scopeId: string): string;
+/**
+ * Register a page's colocated `.skin`/`.js` siblings as emitted assets.
+ * @param {string} file
+ * @param {Paths} context
+ * @param {Assets} assets
+ * @param {import("./reader.js").Reader} reader Source reader for sibling probing.
+ * @returns {void}
+ */
+export function collectColocatedAssets(file: string, context: Paths, assets: Assets, reader: import("./reader.js").Reader): void;
+/**
+ * Resolve an include spec to an absolute path inside `site/pages` or `site/_`.
+ * @param {string} spec Include target (may be quoted).
+ * @param {string} fromFile File requesting the include.
+ * @param {Paths} context
+ * @param {boolean} allowAny Allow non-page extensions (e.g. JSON for `@loop`).
+ * @param {string} loc Source location (`file:line`) for the error messages, so
+ *   an unresolved/out-of-sandbox include reports the directive's line. Callers
+ *   with a line index pass `at(ctx, index)`; pass `fromFile` for the file-only
+ *   message.
+ * @param {import("./reader.js").Reader} reader Source reader for existence
+ *   probing, threaded from `ctx.comp.reader`.
+ * @returns {string}
+ */
+export function resolveInclude(spec: string, fromFile: string, context: Paths, allowAny: boolean, loc: string, reader: import("./reader.js").Reader): string;
+/**
+ * @param {string} file
+ * @param {Paths} context
+ * @returns {boolean}
+ */
+export function isAllowedInclude(file: string, context: Paths): boolean;
+/**
+ * Warn when a plain `.md` file contains `.wd`-only syntax that stays inert.
+ * @param {string} body
+ * @param {string} file
+ * @param {Compilation} comp
+ * @returns {void}
+ */
+export function scanMarkdownHints(body: string, file: string, comp: Compilation): void;
+export type Paths = import("./context.js").Paths;
+export type Assets = import("./context.js").Assets;
+export type Compilation = import("./context.js").Compilation;

package/types/compiler/index.d.ts

@@ -0,0 +1,5 @@
+export { parseFrontmatter } from "./frontmatter.js";
+export { stampScope } from "./includes.js";
+export { escapeHtml } from "./interpolation.js";
+export { loopKeyOf } from "./loops.js";
+export { compileDocument, compileFromMemory, compilePage, enhanceImages } from "./page.js";

package/types/compiler/interpolation.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @typedef {import("./context.js").Scope} Scope
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+/**
+ * Walk the scope chain for a top-level variable.
+ * @param {Scope} scope
+ * @param {string} name
+ * @returns {{ found: true, value: unknown } | { found: false }}
+ */
+export function lookupVar(scope: Scope, name: string): {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+};
+/**
+ * Resolve a dotted path against the static scope chain.
+ * @param {string} expr
+ * @param {Ctx} ctx
+ * @returns {{ found: true, value: unknown } | { found: false }}
+ */
+export function lookupPath(expr: string, ctx: Ctx): {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+};
+/**
+ * Safely read a dotted path off a value, rejecting prototype-pollution segments.
+ * @param {unknown} value
+ * @param {string[]} segments
+ * @returns {unknown}
+ */
+export function getPath(value: unknown, segments: string[]): unknown;
+/**
+ * Validate a dotted path shape, rejecting prototype-pollution segments at every
+ * level. Shared by actions/loops/fetch. Throws with a corrective `Use:` hint.
+ * @param {string} path Dotted path, e.g. `cart.items`.
+ * @param {Ctx} ctx
+ * @param {string} use Corrective suggestion for the error message.
+ * @returns {string[]} The validated segments.
+ */
+export function validatePath(path: string, ctx: Ctx, use: string): string[];
+/**
+ * Resolve a bare state name to its fully-qualified key, walking section scopes.
+ * @param {string} name
+ * @param {Ctx} ctx
+ * @returns {string | null}
+ */
+export function resolveStateKey(name: string, ctx: Ctx): string | null;
+/**
+ * Render an interpolated value as text. Arrays join with ", " (matching the
+ * documented `{ meta.tags }` behavior); a bare object is a mistake — fail
+ * loudly with a fix rather than emitting "[object Object]".
+ * @param {unknown} value
+ * @param {string} expr
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function interpolateLeaf(value: unknown, expr: string, ctx: Ctx): string;
+/**
+ * JSON-encode a value for an inline `<script>`, escaping `<` to stay HTML-safe.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function safeScriptJson(value: unknown): string;
+/**
+ * Parse a `:state`/`:store`/`:theme` value: quoted string, boolean, null, number,
+ * or JSON literal — falling back to the bare string. Multi-line array/object
+ * literals are joined into one line before reaching here (see `joinValueDirective`
+ * in body.js), so a value that opens a `[`/`{` but won't parse is genuinely
+ * unbalanced (a missing `]`/`}`) and throws, rather than being stored verbatim as
+ * the partial string `"["` — the silent-corruption footgun this guard replaces.
+ * @param {string} raw
+ * @param {string} [where] `file:line` for the error message.
+ * @returns {unknown}
+ */
+export function parseStateValue(raw: string, where?: string): unknown;
+/**
+ * @param {string} raw
+ * @returns {string | number | boolean}
+ */
+export function parseScalar(raw: string): string | number | boolean;
+/**
+ * @param {string} [value]
+ * @returns {string}
+ */
+export function stripQuotes(value?: string): string;
+/**
+ * Turn a field name / state key into a human-readable accessible name, e.g.
+ * `quest` → "Quest", `user-name` → "User name", `firstName` → "First name".
+ * Hyphens, underscores, and camelCase boundaries become spaces; the first letter
+ * is capitalized. Used to auto-derive aria-label on generated form inputs.
+ * @param {string} name
+ * @returns {string}
+ */
+export function humanizeName(name: string): string;
+/**
+ * Escape a value for safe inclusion in HTML text and attribute contexts.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeHtml(value: unknown): string;
+/**
+ * Reverse {@link escapeHtml}. Used by the loop initial-paint fill to read a
+ * `data-wd-fmt` attribute (HTML-escaped JSON) back into pipe stages at build
+ * time — the browser does the same decode for the runtime via getAttribute.
+ * `&amp;` is decoded last so `&amp;lt;` round-trips to `&lt;`, not `<`.
+ * @param {string} value
+ * @returns {string}
+ */
+export function unescapeHtml(value: string): string;
+export type Scope = import("./context.js").Scope;
+export type Ctx = import("./context.js").Ctx;

package/types/compiler/loops.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @param {string} line
+ * @param {string[]} bodyLines
+ * @param {string[] | null} emptyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index of the `@loop` opener.
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
+ * @returns {string}
+ */
+export function handleLoop(line: string, bodyLines: string[], emptyLines: string[] | null, ctx: Ctx, index: number, emptyStart?: number): string;
+/**
+ * @param {string} str
+ * @param {number} start
+ * @param {string} tag
+ * @returns {number}
+ */
+export function matchElement(str: string, start: number, tag: string): number;
+/**
+ * Stable per-render key for a loop row, disambiguating duplicates with `#n`.
+ * @param {unknown} item
+ * @param {Map<string, number>} counts Mutable seen-count accumulator.
+ * @returns {string}
+ */
+export function loopKeyOf(item: unknown, counts: Map<string, number>): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ * @typedef {import("./context.js").Predicate} Predicate
+ * @typedef {import("./context.js").NumArg} NumArg
+ * @typedef {import("./context.js").LoopOpts} LoopOpts
+ */
+export const LOOP_EXAMPLE: "@loop /products.json into p where p.price < 50 sort by p.price asc";
+export type Ctx = import("./context.js").Ctx;
+export type Predicate = import("./context.js").Predicate;
+export type NumArg = import("./context.js").NumArg;
+export type LoopOpts = import("./context.js").LoopOpts;

package/types/compiler/markdown.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pick the markdown-it instance for a page (raw HTML off by default, on with `html: true`).
+ * @param {Meta} [meta]
+ * @returns {MarkdownIt}
+ */
+export function selectMd(meta?: Meta): MarkdownIt;
+/**
+ * @param {string} text
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function renderProse(text: string, ctx: Ctx): string;
+/**
+ * The inline token an attr block attaches to: the immediately-preceding image
+ * (self-closing) or the open token matching the immediately-preceding close
+ * (link/em/strong/…). Returns null when nothing valid precedes. Exported so its
+ * contract — including the defensive unbalanced-close fallback that markdown-it's
+ * always-balanced token stream never triggers in practice — is unit-testable.
+ * @param {any[]} children markdown-it inline child tokens
+ * @param {number} i Index of the attr-block text token.
+ * @returns {any} the matching markdown-it Token, or null
+ */
+export function attrTarget(children: any[], i: number): any;
+/**
+ * GitHub-style heading slug: lowercase, punctuation stripped (letters, numbers,
+ * whitespace, `_`, and `-` survive), each whitespace character becomes a hyphen.
+ * Punctuation-only headings fall back to `"section"` so the id is never empty.
+ * @param {string} text Plain heading text.
+ * @returns {string}
+ */
+export function slugify(text: string): string;
+export type Meta = import("./context.js").Meta;
+export type Ctx = import("./context.js").Ctx;
+import MarkdownIt from "markdown-it";

package/types/compiler/media.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `:video /clip.mp4 [poster=…] [width=…] [height=…] [preload=…] [controls] [autoplay]
+ * [loop] [muted] [playsinline]` and `:audio /track.mp3 [preload=…] [controls] …` →
+ * a hardened `<video>`/`<audio>`. Defaults: `preload="metadata"`, and `controls`
+ * unless the clip is an `autoplay` background (autoplay also implies `muted`, which
+ * browsers require). Author flags/attrs always win. URLs use the `:fetch` scheme
+ * guard (relative or http(s)).
+ * @param {string} line
+ * @param {"video" | "audio"} kind
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleMedia(line: string, kind: "video" | "audio", ctx: Ctx, index: number): string;
+/**
+ * `:embed <url> [title="…"]` → a lazy, privacy-friendly responsive iframe. A
+ * YouTube or Vimeo URL is rewritten to its no-cookie / player embed; any other
+ * http(s) URL becomes a generic 16:9 iframe. Inline styles keep the wrapper
+ * self-contained (no framework CSS), so an embed-only page stays zero-JS/zero-CSS.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleEmbed(line: string, ctx: Ctx, index: number): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+export const VIDEO_EXAMPLE: ":video /demo.mp4 controls";
+export const AUDIO_EXAMPLE: ":audio /theme.mp3 controls";
+export const EMBED_EXAMPLE: ":embed https://youtu.be/dQw4w9WgXcQ title=\"Demo\"";
+export type Ctx = import("./context.js").Ctx;