@glw907/cairn-cms 0.60.1 → 0.62.1

package/src/lib/media/store.ts

@@ -12,12 +12,16 @@ import type {
   R2Range,
 } from '@cloudflare/workers-types';
 
-/** The narrow R2 surface the media pipeline uses. The engine depends on this, not on R2Bucket, so the
- *  multipart, list, and conditional-read surface R2 also carries never leaks into the media code. */
+/**
+ * The narrow R2 surface the media pipeline uses. The engine depends on this, not on R2Bucket, so the
+ *  multipart, list, and conditional-read surface R2 also carries never leaks into the media code.
+ */
 export interface MediaStore {
-  /** Store bytes under a content-addressed key, with the response HTTP metadata (the content type)
+  /**
+   * Store bytes under a content-addressed key, with the response HTTP metadata (the content type)
    *  and optional custom metadata (the upload stores the full sha256 here, so a short-hash collision
-   *  is detectable on a later dedup probe). */
+   *  is detectable on a later dedup probe).
+   */
   put(
     key: string,
     bytes: ArrayBuffer | Uint8Array,
@@ -26,10 +30,12 @@ export interface MediaStore {
   ): Promise<void>;
   /** The object's metadata, or null when no object lives at the key (the dedup probe). */
   head(key: string): Promise<R2Object | null>;
-  /** The object body for streaming to a delivery response, or null when the key is absent. The
+  /**
+   * The object body for streaming to a delivery response, or null when the key is absent. The
    *  delivery route passes `onlyIf` and `range` through for conditional and partial reads: an
    *  `onlyIf` etag match returns a body-less R2Object (the 304 shape), so the return widens to
-   *  `R2Object` alongside `R2ObjectBody`. */
+   *  `R2Object` alongside `R2ObjectBody`.
+   */
   get(
     key: string,
     opts?: { range?: R2Range; onlyIf?: R2Conditional },
@@ -38,9 +44,11 @@ export interface MediaStore {
   delete(key: string): Promise<void>;
 }
 
-/** Wrap an R2 bucket binding as a MediaStore. Each method delegates to the binding; put folds the
+/**
+ * Wrap an R2 bucket binding as a MediaStore. Each method delegates to the binding; put folds the
  *  HTTP and custom metadata into R2's options shape and drops the returned R2Object the pipeline does
- *  not read. */
+ *  not read.
+ */
 export function r2Store(bucket: R2Bucket): MediaStore {
   return {
     async put(key, bytes, httpMetadata, customMetadata) {

package/src/lib/media/transform-url.ts

@@ -5,9 +5,11 @@
 // a CDN cache keys on it cleanly. The delivery path is appended unaltered, since it already carries
 // its own leading slash.
 
-/** A single image variant: the resize and format directives Cloudflare Images applies to the
+/**
+ * A single image variant: the resize and format directives Cloudflare Images applies to the
  *  original bytes. Every field is optional. width, height, quality, and fit are emitted only when
- *  set; format and gravity always appear, defaulting to auto. */
+ *  set; format and gravity always appear, defaulting to auto.
+ */
 export interface VariantSpec {
   /** Target width in pixels. */
   width?: number;
@@ -23,10 +25,12 @@ export interface VariantSpec {
   format?: 'auto' | 'webp' | 'avif' | string;
 }
 
-/** Build the on-demand Cloudflare Images transform URL for a delivery path. The options are
+/**
+ * Build the on-demand Cloudflare Images transform URL for a delivery path. The options are
  *  comma-joined in the stable order width, height, quality, fit, format, gravity, with width through
  *  fit emitted only when the spec sets them and format and gravity always present (defaulting to
- *  auto). The publicPath is appended unaltered, so the result is `/cdn-cgi/image/<options><publicPath>`. */
+ *  auto). The publicPath is appended unaltered, so the result is `/cdn-cgi/image/<options><publicPath>`.
+ */
 export function variantUrl(publicPath: string, spec: VariantSpec): string {
   const options: string[] = [];
   if (spec.width !== undefined) options.push(`width=${spec.width}`);
@@ -42,9 +46,11 @@ export function variantUrl(publicPath: string, spec: VariantSpec): string {
   return `/cdn-cgi/image/${options.join(',')}${source}`;
 }
 
-/** Build a variant URL from a named preset. Looks up presetName in variants and builds its spec with
+/**
+ * Build a variant URL from a named preset. Looks up presetName in variants and builds its spec with
  *  variantUrl. Throws a cairn:-prefixed error naming the unknown preset when the name is absent, so a
- *  typo in a preset name fails loudly rather than silently rendering an unsized image. */
+ *  typo in a preset name fails loudly rather than silently rendering an unsized image.
+ */
 export function presetUrl(
   publicPath: string,
   presetName: string,

package/src/lib/media/usage.ts

@@ -46,14 +46,18 @@ export interface UsageEntry {
   origin: UsageOrigin;
 }
 
-/** Content hash to the distinct entries that reference it. A hash with no row is "no references
- *  found" (see the raw-HTML caveat above), never a proven orphan. */
+/**
+ * Content hash to the distinct entries that reference it. A hash with no row is "no references
+ *  found" (see the raw-HTML caveat above), never a proven orphan.
+ */
 export type UsageIndex = Map<string, UsageEntry[]>;
 
-/** Build options. `branches` lets a caller that already listed the open cairn/* branches pass them
+/**
+ * Build options. `branches` lets a caller that already listed the open cairn/* branches pass them
  *  in so the index does not list them a second time (the load path lists once for the media-union).
  *  `strict` flips the per-branch read from degrade-and-skip to fail-closed: a delete gate must not
- *  treat a transient branch-read failure as an absent reference, so it rethrows instead. */
+ *  treat a transient branch-read failure as an absent reference, so it rethrows instead.
+ */
 export interface BuildUsageOptions {
   /** The open cairn/* branch names, already listed. When present the index skips its own listing. */
   branches?: string[];

package/src/lib/nav/site-config.ts

@@ -81,14 +81,18 @@ export interface SiteConfig {
   menus?: Record<string, unknown>;
   /** Per-concept URL policy: the permalink pattern and date-prefix granularity, keyed by concept id. */
   content?: Record<string, ConceptUrlPolicy>;
-  /** The editor spellcheck settings. The dialect is declared once per site (spec 1.2), so a British
+  /**
+   * The editor spellcheck settings. The dialect is declared once per site (spec 1.2), so a British
    *  site loads the British word list and "colour" reads as correct. Today only US English ships, so an
-   *  unset or unknown dialect resolves to it. */
+   *  unset or unknown dialect resolves to it.
+   */
   spellcheck?: { dialect?: string };
-  /** The editor tidy (LLM copy-edit) settings. Opt-in at the site level (spec 2.8): tidy is a remote,
+  /**
+   * The editor tidy (LLM copy-edit) settings. Opt-in at the site level (spec 2.8): tidy is a remote,
    *  costly model call, so the whole block is optional and `enabled` defaults false. The model is a
    *  developer-tier fact; the `conventions` block is the editor-tier per-convention config that builds
-   *  the prompt's CONVENTIONS section. The Anthropic API key is a Worker secret, never config. */
+   *  the prompt's CONVENTIONS section. The Anthropic API key is a Worker secret, never config.
+   */
   tidy?: TidyConfig;
   [key: string]: unknown;
 }
@@ -117,14 +121,18 @@ export const DEFAULT_TIDY_MODEL = 'claude-sonnet-4-6';
  * Sentence spacing is dropped on purpose and regional spelling is `spellcheck.dialect`, not a toggle.
  */
 export interface TidyConventions {
-  /** The objective Fixes group (spelling, grammar, doubled words, whitespace, capitals, terminal
+  /**
+   * The objective Fixes group (spelling, grammar, doubled words, whitespace, capitals, terminal
    *  punctuation). Default on. The always-on core governs it; this toggle lets the screen turn the
-   *  group off. */
+   *  group off.
+   */
   fixes: boolean;
   /** Oxford comma position. Off when undefined; `always` | `complex-only` (AP) | `never`. */
   oxfordComma?: 'always' | 'complex-only' | 'never';
-  /** Number style threshold. Off when undefined; the always-numeral exception sets (ages, dates,
-   *  measurements, percentages) apply at any threshold. */
+  /**
+   * Number style threshold. Off when undefined; the always-numeral exception sets (ages, dates,
+   *  measurements, percentages) apply at any threshold.
+   */
   numberStyle?: 'under-ten' | 'under-hundred' | 'always-numerals';
   /** Measurement notation only (never the system, never the number). Off when undefined. */
   measurements?: 'abbreviate' | 'spell-out';

package/src/lib/render/component-grammar.ts

@@ -33,6 +33,9 @@ function nestedSlots(def: ComponentDef): SlotDef[] {
   return (def.slots ?? []).filter((s) => s.name !== 'title' && s.name !== 'body');
 }
 
+/**
+ *
+ */
 export function serializeComponent(def: ComponentDef, values: ComponentValues): string {
   const fence = COLON.repeat(nestedSlots(def).length > 0 ? 4 : 3);
 
@@ -136,26 +139,33 @@ function rawKeysFromRoot(root: (RootContent & DirectiveNode) | undefined): strin
   return Object.keys(root?.attributes ?? {});
 }
 
-/** Parse a serialized component directive back into guided-form values, the inverse of
+/**
+ * Parse a serialized component directive back into guided-form values, the inverse of
  *  {@link serializeComponent}. The grammar is reversible, so the editor can round-trip a
- *  saved directive through the form. */
+ *  saved directive through the form.
+ */
 export async function parseComponent(markdown: string, def: ComponentDef): Promise<ComponentValues> {
   return valuesFromRoot(findComponentRoot(markdown, def), def);
 }
 
-/** The raw attribute keys present on the component's opening directive, read from the parsed tree
- *  (quote-aware, unlike a regex over the source). Used by validation to flag unknown keys. */
+/**
+ * The raw attribute keys present on the component's opening directive, read from the parsed tree
+ *  (quote-aware, unlike a regex over the source). Used by validation to flag unknown keys.
+ */
 export function parseRawAttributeKeys(markdown: string, def: ComponentDef): string[] {
   return rawKeysFromRoot(findComponentRoot(markdown, def));
 }
 
-/** The result of {@link componentRoundTripSafety}: whether re-opening a placed block into the
- *  guided form and re-serializing it is provably lossless. */
+/**
+ * The result of {@link componentRoundTripSafety}: whether re-opening a placed block into the
+ *  guided form and re-serializing it is provably lossless.
+ */
 export type RoundTripSafety =
   | { safe: true }
   | { safe: false; reason: 'unknown-attribute' | 'undeclared-child' | 'not-idempotent' | 'not-a-component' };
 
-/** Decide whether guided edit of this placed block is provably lossless. A block a person typed by
+/**
+ * Decide whether guided edit of this placed block is provably lossless. A block a person typed by
  *  hand can carry more than the schema models (an attribute the def does not list, a child container
  *  the def does not declare, slot content the form cannot represent stably), and parsing such a block
  *  into the form then re-serializing would silently drop it. The edit affordance is offered only when
@@ -165,7 +175,8 @@ export type RoundTripSafety =
  *  2. `unknown-attribute`: the block carries an attribute key the def does not declare.
  *  3. `undeclared-child`: the root has a direct child container directive that is not a declared
  *     nested slot. Such a child would otherwise fold into the body slot and move on re-serialize.
- *  4. `not-idempotent`: `parse -> serialize -> parse` does not recover the same values. */
+ *  4. `not-idempotent`: `parse -> serialize -> parse` does not recover the same values.
+ */
 export async function componentRoundTripSafety(markdown: string, def: ComponentDef): Promise<RoundTripSafety> {
   const root = findComponentRoot(markdown, def);
   if (!root) return { safe: false, reason: 'not-a-component' };
@@ -191,9 +202,11 @@ export async function componentRoundTripSafety(markdown: string, def: ComponentD
   return { safe: true };
 }
 
-/** Parse the component once and derive both the guided-form values and the raw attribute keys.
+/**
+ * Parse the component once and derive both the guided-form values and the raw attribute keys.
  *  Validation needs both, so this seam spares it the double parse that calling
- *  {@link parseComponent} and {@link parseRawAttributeKeys} separately would cost. */
+ *  {@link parseComponent} and {@link parseRawAttributeKeys} separately would cost.
+ */
 export async function parseComponentWithRawKeys(
   markdown: string,
   def: ComponentDef,

package/src/lib/render/component-insert.ts

@@ -2,12 +2,16 @@ import { serializeComponent } from './component-grammar.js';
 import { validateComponent } from './component-validate.js';
 import type { ComponentDef, ComponentValues } from './registry.js';
 
-/** The outcome of preparing a guided-form component for insertion: the markdown to insert, or the
- *  field-keyed errors to show on the form. */
+/**
+ * The outcome of preparing a guided-form component for insertion: the markdown to insert, or the
+ *  field-keyed errors to show on the form.
+ */
 export type ComponentInsert = { ok: true; markdown: string } | { ok: false; errors: Record<string, string> };
 
-/** Serialize a component's form values, then validate the result against its schema. Returns the
- *  markdown to insert at the cursor, or the field errors keyed by attribute key or slot name. */
+/**
+ * Serialize a component's form values, then validate the result against its schema. Returns the
+ *  markdown to insert at the cursor, or the field errors keyed by attribute key or slot name.
+ */
 export async function buildComponentInsert(def: ComponentDef, values: ComponentValues): Promise<ComponentInsert> {
   const markdown = serializeComponent(def, values);
   const verdict = await validateComponent(markdown, def);

package/src/lib/render/component-reference.ts

@@ -8,8 +8,10 @@ export interface ReferenceOptions {
   summary: string;
 }
 
-/** Build a self-contained markdown reference (the llms-full.txt shape) for a component registry, for
- *  authors and for pointing an LLM at one curated file. */
+/**
+ * Build a self-contained markdown reference (the llms-full.txt shape) for a component registry, for
+ *  authors and for pointing an LLM at one curated file.
+ */
 export function generateComponentReference(registry: ComponentRegistry, opts: ReferenceOptions): string {
   const sections = registry.defs.map((def) => componentSection(def));
   return `# ${opts.title}\n\n> ${opts.summary}\n\n${sections.join('\n\n')}\n`;

package/src/lib/render/component-validate.ts

@@ -4,6 +4,9 @@ import type { ComponentDef, ComponentValues } from './registry.js';
 /** A validation verdict: ok, or field-keyed error messages. */
 export type ComponentValidation = { ok: true } | { ok: false; errors: Record<string, string> };
 
+/**
+ *
+ */
 export async function validateComponent(markdown: string, def: ComponentDef): Promise<ComponentValidation> {
   const { values, rawKeys } = await parseComponentWithRawKeys(markdown, def);
   const errors: Record<string, string> = {};

package/src/lib/render/glyph.ts

@@ -4,10 +4,12 @@ import type { Element } from 'hast';
 /** A glyph name to SVG path-data map (the site owns the icon set). */
 export type IconSet = Record<string, string>;
 
-/** Inline SVG glyph as a real hast node: class ec-glyph, 256 viewBox, currentColor fill.
+/**
+ * Inline SVG glyph as a real hast node: class ec-glyph, 256 viewBox, currentColor fill.
  *  An unknown icon name yields the bare svg shell with no path child, so it never serializes
  *  a stray empty (or undefined) path. Callers always wrap the returned element, so the shell
- *  keeps them safe. */
+ *  keeps them safe.
+ */
 export function glyph(name: string, icons: IconSet): Element {
   const d = icons[name];
   return s(

package/src/lib/render/pipeline.ts

@@ -19,28 +19,38 @@ import { defineRegistry, type ComponentRegistry } from './registry.js';
 import type { LinkResolve } from '../content/links.js';
 
 export interface RendererOptions {
-  /** Stamp a `data-rise` ordinal (0, 1, 2, …) on each top-level component so a site's
+  /**
+   * Stamp a `data-rise` ordinal (0, 1, 2, …) on each top-level component so a site's
    *  CSS can drive an entrance-cascade delay off it. Omit for no stagger. The ordinal
-   *  is inert, so a consumer's sanitize floor can keep `data-rise` and drop `style`. */
+   *  is inert, so a consumer's sanitize floor can keep `data-rise` and drop `style`.
+   */
   stagger?: boolean;
-  /** Extend the sanitize allowlist. Receives cairn's default schema (defaultSchema plus the
+  /**
+   * Extend the sanitize allowlist. Receives cairn's default schema (defaultSchema plus the
    *  directive markers and the common benign tags) and returns the schema to use. Add to the
    *  allowlist for the benign HTML a site's content needs; start from the argument so the
-   *  dangerous strip is preserved. */
+   *  dangerous strip is preserved.
+   */
   sanitizeSchema?: (defaults: Schema) => Schema;
-  /** Developer-only escape hatch: disable the sanitize floor entirely. This reintroduces the XSS
+  /**
+   * Developer-only escape hatch: disable the sanitize floor entirely. This reintroduces the XSS
    *  vector the floor closes, so it is only for a site whose content is fully developer-controlled.
-   *  It is a code-level adapter decision, never an editor-facing setting. */
+   *  It is a code-level adapter decision, never an editor-facing setting.
+   */
   unsafeDisableSanitize?: boolean;
-  /** The `rel` value forced on every `target="_blank"` anchor, applied last so it also covers
+  /**
+   * The `rel` value forced on every `target="_blank"` anchor, applied last so it also covers
    *  component-built anchors. Defaults to `'noopener noreferrer'`. Set a different string to change
-   *  it, or `false` to disable the injection (a site that owns its own anchor hardening). */
+   *  it, or `false` to disable the injection (a site that owns its own anchor hardening).
+   */
   anchorRel?: string | false;
 }
 
-/** Compose a site's render pipeline from its component registry: directive syntax to
+/**
+ * Compose a site's render pipeline from its component registry: directive syntax to
  *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
- *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
+ *  rehype plugin arrays (so the admin editor preview can reuse the exact same set).
+ */
 export function createRenderer(
   registry: ComponentRegistry = defineRegistry({ components: [] }),
   options: RendererOptions = {},

package/src/lib/render/registry.ts

@@ -24,16 +24,20 @@ export interface AttributeField {
   help?: string;
   /** A RegExp `source` to validate the value against, plus the message to show on a mismatch. */
   pattern?: { source: string; message: string };
-  /** A pure, browser-safe cross-field validator. Returns an error string, or null when valid.
+  /**
+   * A pure, browser-safe cross-field validator. Returns an error string, or null when valid.
    *  Receives the field's value and the full {@link ComponentValues} so a rule can read sibling
-   *  fields. The picker wraps the call in try/catch so an author's throw never crashes the form. */
+   *  fields. The picker wraps the call in try/catch so an author's throw never crashes the form.
+   */
   validate?: (value: string | boolean, all: ComponentValues) => string | null;
 }
 
 export type SlotKind = 'markdown' | 'inline' | 'repeatable';
 
-/** One named content region of a component. The slots named `title` and `body` are special: `title`
- *  serializes to the directive `[label]` and `body` to the unmarked content (see the canonical grammar). */
+/**
+ * One named content region of a component. The slots named `title` and `body` are special: `title`
+ *  serializes to the directive `[label]` and `body` to the unmarked content (see the canonical grammar).
+ */
 export interface SlotDef {
   name: string;
   label: string;
@@ -42,15 +46,19 @@ export interface SlotDef {
   help?: string;
   /** For `kind: 'repeatable'`: the fields composing each list item (v1 uses the first field). */
   itemFields?: AttributeField[];
-  /** For `kind: 'repeatable'`: derives a row's label from its item values and zero-based index.
-   *  When it returns nothing, the picker falls back to `${label} ${index + 1}`. */
+  /**
+   * For `kind: 'repeatable'`: derives a row's label from its item values and zero-based index.
+   *  When it returns nothing, the picker falls back to `${label} ${index + 1}`.
+   */
   itemLabel?: (item: Record<string, string | boolean>, index: number) => string;
 }
 
-/** The structured input a component's `build` receives. The engine stamps the component's
+/**
+ * The structured input a component's `build` receives. The engine stamps the component's
  *  attributes and partitions its slots from the rendered hast, so `build` arranges hast and
  *  never walks the tree. `slot(name)` returns a slot's rendered children (title, body, or any
- *  named slot); `items(name)` returns a repeatable slot's items, one child list per item. */
+ *  named slot); `items(name)` returns a repeatable slot's items, one child list per item.
+ */
 export interface ComponentContext {
   /** Declared attribute values, keyed by attribute key. Booleans are real booleans. */
   attributes: Record<string, string | boolean>;
@@ -72,9 +80,11 @@ export interface ComponentDef {
   description: string;
   /** Markdown scaffold inserted at the cursor by the editor palette. */
   insertTemplate?: string;
-  /** Build the final hast element from the component context (attributes plus partitioned
+  /**
+   * Build the final hast element from the component context (attributes plus partitioned
    *  slots). The engine stamps the entrance-stagger ordinal (`data-rise`) on the top-level
-   *  result, so a build fn stays free of any motion concern. */
+   *  result, so a build fn stays free of any motion concern.
+   */
   build: (ctx: ComponentContext) => Element;
   /** Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. */
   defaultIconByRole?: Record<string, string>;
@@ -90,8 +100,10 @@ export interface ComponentDef {
   group?: string;
   /** Omit from the top-level picker (for a nested or round-trip-only component). */
   hidden?: boolean;
-  /** A structured sample the picker seeds the form with and renders through the same path a real
-   *  insert takes. Declaring `preview` is what opts the component into the two-pane configure layout. */
+  /**
+   * A structured sample the picker seeds the form with and renders through the same path a real
+   *  insert takes. Declaring `preview` is what opts the component into the two-pane configure layout.
+   */
   preview?: {
     attributes?: Record<string, string | boolean>;
     slots?: Record<string, string | string[]>;
@@ -107,16 +119,20 @@ export interface ComponentRegistry {
   iconField(name: string): AttributeField | undefined;
 }
 
-/** The hast property name carrying one declared attribute from stamp to dispatch, e.g. `tone`
+/**
+ * The hast property name carrying one declared attribute from stamp to dispatch, e.g. `tone`
  *  becomes `dataAttrTone`. The directive stamp writes it and the rehype dispatch reads it, so both
- *  sides derive the name from this one helper rather than spelling the capitalize twice. */
+ *  sides derive the name from this one helper rather than spelling the capitalize twice.
+ */
 export function dataAttrProp(key: string): string {
   return `dataAttr${key.charAt(0).toUpperCase()}${key.slice(1)}`;
 }
 
-/** A component's first `type:'icon'` attribute, or undefined when it declares none. Both the
+/**
+ * A component's first `type:'icon'` attribute, or undefined when it declares none. Both the
  *  construction-time guard and the registry's `iconField` derive the icon field from this one
- *  predicate rather than spelling the `type === 'icon'` find twice. */
+ *  predicate rather than spelling the `type === 'icon'` find twice.
+ */
 function findIconField(def: ComponentDef): AttributeField | undefined {
   return def.attributes?.find((field) => field.type === 'icon');
 }
@@ -151,15 +167,19 @@ export function defineRegistry({ components }: { components: ComponentDef[] }):
   };
 }
 
-/** Guided-form values for one component: attribute values keyed by attribute key, slot values keyed
- *  by slot name (a string, or a string list for a repeatable slot). */
+/**
+ * Guided-form values for one component: attribute values keyed by attribute key, slot values keyed
+ *  by slot name (a string, or a string list for a repeatable slot).
+ */
 export interface ComponentValues {
   attributes: Record<string, string | boolean>;
   slots: Record<string, string | string[]>;
 }
 
-/** Seed an empty {@link ComponentValues} from a component's schema: attribute defaults (or '' / false)
- *  and empty slot values ([] for repeatable, '' otherwise). */
+/**
+ * Seed an empty {@link ComponentValues} from a component's schema: attribute defaults (or '' / false)
+ *  and empty slot values ([] for repeatable, '' otherwise).
+ */
 export function emptyValues(def: ComponentDef): ComponentValues {
   const attributes: Record<string, string | boolean> = {};
   for (const field of def.attributes ?? []) {
@@ -172,9 +192,11 @@ export function emptyValues(def: ComponentDef): ComponentValues {
   return { attributes, slots };
 }
 
-/** Seed {@link ComponentValues} from a component's `preview` sample: the {@link emptyValues} base
+/**
+ * Seed {@link ComponentValues} from a component's `preview` sample: the {@link emptyValues} base
  *  with `def.preview.attributes` and `def.preview.slots` overlaid (a shallow merge per side). When
- *  the def declares no `preview`, returns exactly the {@link emptyValues} output. */
+ *  the def declares no `preview`, returns exactly the {@link emptyValues} output.
+ */
 export function previewValues(def: ComponentDef): ComponentValues {
   const base = emptyValues(def);
   if (!def.preview) return base;

package/src/lib/render/rehype-dispatch.ts

@@ -2,12 +2,17 @@ import type { Root, Element, ElementContent } from 'hast';
 import { h } from 'hastscript';
 import { dataAttrProp, type ComponentContext, type ComponentDef, type ComponentRegistry } from './registry.js';
 
+/**
+ *
+ */
 export function isElement(node: ElementContent | undefined): node is Element {
   return !!node && node.type === 'element';
 }
 
-/** Read a declared string attribute off the component context, returning undefined for a boolean or
- *  absent value. Replaces the `typeof ctx.attributes[key] === 'string'` narrowing a build repeats. */
+/**
+ * Read a declared string attribute off the component context, returning undefined for a boolean or
+ *  absent value. Replaces the `typeof ctx.attributes[key] === 'string'` narrowing a build repeats.
+ */
 export function strAttr(ctx: ComponentContext, key: string): string | undefined {
   const value = ctx.attributes[key];
   return typeof value === 'string' ? value : undefined;
@@ -16,6 +21,9 @@ export function strAttr(ctx: ComponentContext, key: string): string | undefined
 // hast Properties values are PropertyValue (string | number | boolean | array | null).
 // Directive markers (dataPrimitive/dataRole/dataAttr<Key>) are always stamped as strings;
 // this reads them back with that guarantee instead of casting at each call site.
+/**
+ *
+ */
 export function strProp(node: Element, name: string): string | undefined {
   const value = node.properties?.[name];
   return typeof value === 'string' ? value : undefined;
@@ -35,10 +43,12 @@ export function cardShell(classes: string[], body: ElementContent[]): Element {
   return h('section', { className: classes }, [h('div', { className: ['card-body'] }, body)]);
 }
 
-/** Card head row: `<div class="ec-head">[icon]<hN class="card-title">{title}</hN></div>`.
+/**
+ * Card head row: `<div class="ec-head">[icon]<hN class="card-title">{title}</hN></div>`.
  *  Pass the title's inline children, an optional pre-built icon element, and an optional heading
  *  level (default 2). This factors the icon-plus-heading head that a titled component build would
- *  otherwise rebuild by hand (the shape the removed `splitHead` produced). */
+ *  otherwise rebuild by hand (the shape the removed `splitHead` produced).
+ */
 export function headRow(title: ElementContent[], icon?: Element, level: number = 2): Element {
   const children: ElementContent[] = [];
   if (icon) children.push(icon);
@@ -46,8 +56,10 @@ export function headRow(title: ElementContent[], icon?: Element, level: number =
   return h('div', { className: ['ec-head'] }, children);
 }
 
-/** Tag the first <ul> among children with `ec-grid` and strip its whitespace-only
- *  text nodes so the bare list serializes without newlines. Returns that <ul>. */
+/**
+ * Tag the first <ul> among children with `ec-grid` and strip its whitespace-only
+ *  text nodes so the bare list serializes without newlines. Returns that <ul>.
+ */
 export function markFirstList(children: ElementContent[]): Element | undefined {
   const ul = children.find((c) => isElement(c) && c.tagName === 'ul') as Element | undefined;
   if (ul) {
@@ -142,12 +154,14 @@ function transformNode(node: Element, registry: ComponentRegistry): Element {
   return def.build(ctx);
 }
 
-/** Rehype transformer: dispatch each stamped element through its registry `build`
+/**
+ * Rehype transformer: dispatch each stamped element through its registry `build`
  *  fn. When `stagger` is on, each top-level primitive gets a `data-rise` attribute
  *  carrying its document-order index (0, 1, 2, …); the site's CSS maps that ordinal
  *  to an entrance delay. The index is inert, so a consumer's sanitize floor can keep
  *  `data-rise` while dropping `style`. Nested primitives never get it. Non-primitive
- *  content (lede, intro paragraphs, the page-toc nav) passes through untouched. */
+ *  content (lede, intro paragraphs, the page-toc nav) passes through untouched.
+ */
 export function rehypeDispatch(registry: ComponentRegistry, stagger?: boolean) {
   return (tree: Root) => {
     let idx = 0;

package/src/lib/render/remark-directives.ts

@@ -51,6 +51,9 @@ function restoreLiteral(node: TextDirective | LeafDirective): PhrasingContent[]
 // component name, icon, and role. No structure is built here; the rehype
 // dispatcher rewrites the marked elements once their children are hast.
 // Text and leaf directives are restored to literal text (accidental prose colons).
+/**
+ *
+ */
 export function remarkDirectiveStamp(registry: ComponentRegistry) {
   const known = new Set(registry.names);
   return (tree: Root) => {

package/src/lib/render/remark-figure.ts

@@ -69,8 +69,10 @@ function trimLeadingNewline(children: PhrasingContent[]): PhrasingContent[] {
   return children;
 }
 
-/** Rewrite the reserved `figure` container directive into a placed <figure>. Every other directive
- *  is left to remarkDirectiveStamp, which already skips unregistered names. */
+/**
+ * Rewrite the reserved `figure` container directive into a placed <figure>. Every other directive
+ *  is left to remarkDirectiveStamp, which already skips unregistered names.
+ */
 export function remarkFigure() {
   return (tree: Root): void => {
     visit(tree, 'containerDirective', (node: ContainerDirective) => {

package/src/lib/render/resolve-links.ts

@@ -15,9 +15,11 @@ interface LinkNode {
   data?: { hProperties?: Record<string, unknown> };
 }
 
-/** Resolve cairn: link nodes against the VFile's resolver. A non-cairn href and a malformed token
+/**
+ * Resolve cairn: link nodes against the VFile's resolver. A non-cairn href and a malformed token
  *  pass through. A missing target is marked with the cairn-broken-link class (the resolver returns
- *  undefined) or, when the resolver throws, the error propagates and fails the build. */
+ *  undefined) or, when the resolver throws, the error propagates and fails the build.
+ */
 export function remarkResolveCairnLinks() {
   return (tree: unknown, file: VFile): void => {
     const resolve = file.data[CAIRN_RESOLVE] as LinkResolve | undefined;