@glw907/cairn-cms 0.60.0 → 0.62.1

package/dist/content/media-rewrite.js

@@ -23,10 +23,12 @@ import remarkDirective from 'remark-directive';
 import { visit } from 'unist-util-visit';
 import { parseMediaToken } from '../media/reference.js';
 import { escapeLinkText } from './links.js';
-/** Drop any span that overlaps a span already kept, in source order. A final safety net so two
+/**
+ * Drop any span that overlaps a span already kept, in source order. A final safety net so two
  *  splices can never target the same or overlapping bytes and clobber each other into a corrupt
  *  result, no matter how the locating arms behaved. A pure-insert span (`start === end`) overlaps
- *  another span only when it sits strictly inside it, so adjacent inserts and edits are kept. */
+ *  another span only when it sits strictly inside it, so adjacent inserts and edits are kept.
+ */
 function dropOverlappingEdits(edits) {
     const kept = [];
     for (const e of edits) {
@@ -36,29 +38,37 @@ function dropOverlappingEdits(edits) {
     }
     return kept;
 }
-/** A locating scan for candidate `media:` token substrings. Deliberately broad (it accepts
+/**
+ * A locating scan for candidate `media:` token substrings. Deliberately broad (it accepts
  *  uppercase and other out-of-grammar characters) so a malformed token is still found and then
  *  rejected by parseMediaToken, never silently skipped by the locator. The character class stops at
  *  whitespace, a quote, or any YAML or markdown delimiter, so a frontmatter value or an image
- *  destination ends the candidate. */
+ *  destination ends the candidate.
+ */
 const MEDIA_TOKEN_SCAN = /media:[A-Za-z0-9._-]+/g;
-/** Split a leading frontmatter block off the markdown. `fmBlock` is the `---` fenced block including
+/**
+ * Split a leading frontmatter block off the markdown. `fmBlock` is the `---` fenced block including
  *  both fences and the trailing newline (empty when there is none); `body` is everything after it.
  *  The block leads the document, so a frontmatter offset is already absolute and a body offset needs
- *  `fmBlock.length` added. Shared by every arm so they agree on the boundary. */
+ *  `fmBlock.length` added. Shared by every arm so they agree on the boundary.
+ */
 function splitFrontmatter(markdown) {
     const m = markdown.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
     const fmBlock = m ? m[0] : '';
     return { fmBlock, body: markdown.slice(fmBlock.length) };
 }
-/** Parse a doc with the figure-aware pipeline, so the body arm agrees with what remarkFigure renders
- *  and can see the enclosing `:::figure` container. Mirrors parseFigureDoc in markdown-format.ts. */
+/**
+ * Parse a doc with the figure-aware pipeline, so the body arm agrees with what remarkFigure renders
+ *  and can see the enclosing `:::figure` container. Mirrors parseFigureDoc in markdown-format.ts.
+ */
 function parseFigureDoc(doc) {
     return unified().use(remarkParse).use(remarkGfm).use(remarkDirective).parse(doc);
 }
-/** Whether `target` sits inside a `figure`-named container directive. Walks the tree to find the
+/**
+ * Whether `target` sits inside a `figure`-named container directive. Walks the tree to find the
  *  ancestor, since unist-util-visit's per-call ancestors are not retained across the traversal.
- *  Mirrors enclosingFigure in markdown-format.ts, reduced to a boolean. */
+ *  Mirrors enclosingFigure in markdown-format.ts, reduced to a boolean.
+ */
 function inFigure(tree, target) {
     let found = false;
     visit(tree, 'containerDirective', (dir) => {
@@ -71,8 +81,10 @@ function inFigure(tree, target) {
     });
     return found;
 }
-/** Split fmBlock into lines once, so the locator helpers walk a shared structure instead of
- *  re-scanning the block per call. */
+/**
+ * Split fmBlock into lines once, so the locator helpers walk a shared structure instead of
+ *  re-scanning the block per call.
+ */
 function fmLines(fmBlock) {
     const lines = [];
     let pos = 0;
@@ -86,12 +98,14 @@ function fmLines(fmBlock) {
     }
     return lines;
 }
-/** The inclusive line-index range `[lo, hi]` of the block-style mapping a top-level key opens: the
+/**
+ * The inclusive line-index range `[lo, hi]` of the block-style mapping a top-level key opens: the
  *  line `^<key>:` at indent 0 through the last line before the next top-level key (or the document
  *  end). A flow-style value (`key: { ... }` all on one line) yields a single-line range. Returns null
  *  when the key has no top-level line, which a malformed or non-canonical block can cause. Scoping the
  *  per-key search to this range is what lets two image fields that share one hash, or an image field
- *  whose hash also appears in a sibling text value, resolve to distinct, correct spans. */
+ *  whose hash also appears in a sibling text value, resolve to distinct, correct spans.
+ */
 function frontmatterKeyRange(lines, fmBlock, key) {
     const opener = new RegExp(`^${escapeForRegExp(key)}:`);
     const topLevelKey = /^[^\s#][^:]*:/;
@@ -118,10 +132,12 @@ function frontmatterKeyRange(lines, fmBlock, key) {
     }
     return [lo, hi];
 }
-/** Find the block-style `src:` line within `[lo, hi]` whose value token parses to `hash`. The token
+/**
+ * Find the block-style `src:` line within `[lo, hi]` whose value token parses to `hash`. The token
  *  is located by the broad scan and validated through parseMediaToken (matching on hash), so a
  *  malformed token is found then rejected. Returns null for a flow-style value (no own `src:` line),
- *  which leaves that shape unanchorable rather than splicing a guessed span. */
+ *  which leaves that shape unanchorable rather than splicing a guessed span.
+ */
 function findSrcLineInRange(lines, fmBlock, range, hash) {
     const srcKeyRe = /^(\s*)src:[ \t]?/;
     for (let i = range[0]; i <= range[1]; i += 1) {
@@ -149,11 +165,13 @@ function findSrcLineInRange(lines, fmBlock, range, hash) {
     }
     return null;
 }
-/** The image-like top-level frontmatter keys whose `src` parses to `hash`, in source order. A key is
+/**
+ * The image-like top-level frontmatter keys whose `src` parses to `hash`, in source order. A key is
  *  image-like when its value is an object carrying a string `src`; this is the same shape
  *  extractMediaRefs reads, so a token in a plain-text value (a `title:`/`note:`) is never treated as a
  *  reference. The bucket-classifying data comes from gray-matter (which handles every quoting form);
- *  the byte edit is located structurally by the caller, keyed back to this key name. */
+ *  the byte edit is located structurally by the caller, keyed back to this key name.
+ */
 function imageFieldKeys(data, hash) {
     const out = [];
     for (const [key, value] of Object.entries(data)) {
@@ -169,11 +187,13 @@ function imageFieldKeys(data, hash) {
     }
     return out;
 }
-/** Collect hero src-token edits inside the frontmatter block. Only an image-field `src:` line is
+/**
+ * Collect hero src-token edits inside the frontmatter block. Only an image-field `src:` line is
  *  rewritten: the structure is read via gray-matter (image-like keys), and each key's `src:` line is
  *  located structurally within that key's block. A `media:` token sitting in a plain-text value (a
  *  `title:` or `description:`) is on no `src:` line, so it is left untouched, keeping the byte-exact
- *  contract and agreeing with extractMediaRefs. A flow-style hero has no `src:` line and is skipped. */
+ *  contract and agreeing with extractMediaRefs. A flow-style hero has no `src:` line and is skipped.
+ */
 function frontmatterEdits(markdown, fmBlock, oldHash) {
     if (fmBlock === '')
         return [];
@@ -191,10 +211,12 @@ function frontmatterEdits(markdown, fmBlock, oldHash) {
     }
     return edits;
 }
-/** Locate the exact `media:` token substring inside one image node's source span. The destination
+/**
+ * Locate the exact `media:` token substring inside one image node's source span. The destination
  *  begins at the `](` that follows the alt text, so the search starts there to avoid a false match on
  *  a `media:`-like string inside the alt. Returns null when the token cannot be located, which leaves
- *  the image untouched rather than splicing a guessed range. */
+ *  the image untouched rather than splicing a guessed range.
+ */
 function locateImageToken(span, url) {
     const destStart = span.indexOf('](');
     const from = destStart === -1 ? 0 : destStart + 2;
@@ -203,9 +225,11 @@ function locateImageToken(span, url) {
         return null;
     return { start: at, end: at + url.length };
 }
-/** Find every body image whose url parses to `hash`, in source order, with absolute offsets. Parses
+/**
+ * Find every body image whose url parses to `hash`, in source order, with absolute offsets. Parses
  *  with the figure-aware pipeline, so a `media:` token inside a code span or fence is not an image
- *  node and is correctly skipped, matching extractMediaRefs. */
+ *  node and is correctly skipped, matching extractMediaRefs.
+ */
 function matchedBodyImages(body, blockLength, hash) {
     const tree = parseFigureDoc(body);
     const hits = [];
@@ -226,9 +250,11 @@ function matchedBodyImages(body, blockLength, hash) {
     });
     return hits;
 }
-/** Collect body edits over the body slice. Each matching image is located within its own source span
+/**
+ * Collect body edits over the body slice. Each matching image is located within its own source span
  *  and recorded with an absolute offset. The kind is 'figure' when the image is inside a `:::figure`,
- *  else 'body'. */
+ *  else 'body'.
+ */
 function bodyEdits(body, blockLength, oldHash) {
     const edits = [];
     for (const hit of matchedBodyImages(body, blockLength, oldHash)) {
@@ -276,14 +302,18 @@ export function repointMediaRef(markdown, oldHash, newToken) {
     }
     return { markdown: out, placements };
 }
-/** Classify an existing alt into its non-decorative bucket: an empty (or whitespace-only) alt is
+/**
+ * Classify an existing alt into its non-decorative bucket: an empty (or whitespace-only) alt is
  *  filled, a non-empty alt is a custom alt the caller may opt in to overwrite. Mirrors the empty-alt
- *  test findMediaImagesNeedingAlt uses. */
+ *  test findMediaImagesNeedingAlt uses.
+ */
 function classifyAlt(existing) {
     return existing.trim() === '' ? 'will-fill' : 'customized';
 }
-/** Whether a bucket plus the overwrite choice means the alt text is actually rewritten. A will-fill
- *  always writes; a customized alt writes only on opt-in; a decorative hero never writes. */
+/**
+ * Whether a bucket plus the overwrite choice means the alt text is actually rewritten. A will-fill
+ *  always writes; a customized alt writes only on opt-in; a decorative hero never writes.
+ */
 function altIsEdited(bucket, overwrite) {
     if (bucket === 'will-fill')
         return true;
@@ -291,10 +321,12 @@ function altIsEdited(bucket, overwrite) {
         return overwrite;
     return false;
 }
-/** Collect the body and figure alt edits over the body slice. The alt source span sits between `![`
+/**
+ * Collect the body and figure alt edits over the body slice. The alt source span sits between `![`
  *  and the `](` inside the image node's span, so the new alt (escaped the way insertImage escapes it,
  *  so a `]` cannot break the syntax) is spliced there. The existing alt is the parser's already
- *  unescaped `node.alt`. A body image has no decorative slot, so an empty alt is always will-fill. */
+ *  unescaped `node.alt`. A body image has no decorative slot, so an empty alt is always will-fill.
+ */
 function bodyAltEdits(body, blockLength, hash, defaultAlt, overwrite) {
     const edits = [];
     for (const hit of matchedBodyImages(body, blockLength, hash)) {
@@ -333,17 +365,21 @@ function bodyAltEdits(body, blockLength, hash, defaultAlt, overwrite) {
     }
     return edits;
 }
-/** Escape a literal string for safe interpolation into a RegExp source. A key name or an indent is
- *  matched literally, so its characters must not act as metacharacters. */
+/**
+ * Escape a literal string for safe interpolation into a RegExp source. A key name or an indent is
+ *  matched literally, so its characters must not act as metacharacters.
+ */
 function escapeForRegExp(literal) {
     return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-/** Find a sibling key line (`alt:` or `decorative:`) at exactly `indent` within the inclusive
+/**
+ * Find a sibling key line (`alt:` or `decorative:`) at exactly `indent` within the inclusive
  *  line-index range `[lo, hi]` of one mapping. The range is the mapping's own block, so the search
  *  spans the whole mapping rather than a same-indent contiguous run: a blank line or a deeper-nested
  *  child between `src:` and `alt:` no longer hides the existing key (which would otherwise insert a
  *  duplicate key and break the YAML). Returns the key line's value span (after the key and its space,
- *  to end of line) or null when the mapping has no such key at that indent. */
+ *  to end of line) or null when the mapping has no such key at that indent.
+ */
 function findSiblingKeyValue(lines, fmBlock, range, indent, key) {
     const keyRe = new RegExp(`^${escapeForRegExp(indent)}${escapeForRegExp(key)}:[ \\t]?`);
     for (let i = range[0]; i <= range[1]; i += 1) {
@@ -354,7 +390,8 @@ function findSiblingKeyValue(lines, fmBlock, range, indent, key) {
     }
     return null;
 }
-/** Collect the hero alt edits inside the frontmatter block. The image-field objects (and their
+/**
+ * Collect the hero alt edits inside the frontmatter block. The image-field objects (and their
  *  decorative and alt values) are read via gray-matter to classify the bucket robustly across quoting
  *  forms; the byte edit is then located structurally, scoped to each field's own mapping block, keyed
  *  back by the top-level field name. Iterating the fields in source order keeps the hero placements in
@@ -363,7 +400,8 @@ function findSiblingKeyValue(lines, fmBlock, range, indent, key) {
  *  blank line or a nested child) has its value replaced; an absent one is inserted right after the
  *  `src:` line at the same indent. The new value is a JSON-quoted scalar, valid YAML that handles a
  *  colon, a quote, or an empty string. A flow-style hero (`image: { ... }`, no own `src:` line) is
- *  unanchorable, so it is reported from the gray-matter read but never spliced. */
+ *  unanchorable, so it is reported from the gray-matter read but never spliced.
+ */
 function heroAltEdits(markdown, fmBlock, hash, defaultAlt, overwrite) {
     if (fmBlock === '')
         return [];

package/dist/content/schema.d.ts

@@ -4,8 +4,10 @@ export interface StandardInput {
     frontmatter: Record<string, unknown>;
     body: string;
 }
-/** A minimal local copy of the Standard Schema v1 interface (https://standardschema.dev), so the
- *  schema is a drop-in where the ecosystem accepts a validator, with no runtime dependency. */
+/**
+ * A minimal local copy of the Standard Schema v1 interface (https://standardschema.dev), so the
+ *  schema is a drop-in where the ecosystem accepts a validator, with no runtime dependency.
+ */
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
     readonly '~standard': {
         readonly version: 1;
@@ -26,9 +28,11 @@ type StandardResult<Output> = {
         readonly path?: ReadonlyArray<PropertyKey>;
     }>;
 };
-/** Map one field descriptor to the TS type of its normalized value. text, textarea, and date
+/**
+ * Map one field descriptor to the TS type of its normalized value. text, textarea, and date
  *  normalize to a string; a closed-vocabulary `tags` field to the option-union array; an `image`
- *  field to its nested object. */
+ *  field to its nested object.
+ */
 type FieldValue<K extends FrontmatterField> = K extends {
     type: 'boolean';
 } ? boolean : K extends {
@@ -43,8 +47,10 @@ type FieldValue<K extends FrontmatterField> = K extends {
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
-/** The normalized frontmatter type inferred from a field tuple. A field declared
- *  `required: true` is a required key; every other field is optional. */
+/**
+ * The normalized frontmatter type inferred from a field tuple. A field declared
+ *  `required: true` is a required key; every other field is optional.
+ */
 export type InferFields<F extends readonly FrontmatterField[]> = Prettify<{
     [K in F[number] as K extends {
         required: true;
@@ -54,8 +60,10 @@ export type InferFields<F extends readonly FrontmatterField[]> = Prettify<{
         required: true;
     } ? never : K['name']]?: FieldValue<K>;
 }>;
-/** A concept's schema: the plain-data field projection, the generated validator, and the
- *  Standard Schema conformance property. */
+/**
+ * A concept's schema: the plain-data field projection, the generated validator, and the
+ *  Standard Schema conformance property.
+ */
 export interface ConceptSchema<F extends readonly FrontmatterField[] = readonly FrontmatterField[]> {
     /** The declared fields as plain serializable data, for the editor form. */
     readonly fields: FrontmatterField[];
@@ -66,9 +74,11 @@ export interface ConceptSchema<F extends readonly FrontmatterField[] = readonly
 }
 /** Extract the inferred frontmatter type from a `ConceptSchema`. */
 export type Infer<S> = S extends ConceptSchema<infer F> ? InferFields<F> : never;
-/** Options for `defineFields`. `refine` runs after the per-field rules pass, for cross-field and
+/**
+ * Options for `defineFields`. `refine` runs after the per-field rules pass, for cross-field and
  *  body-dependent checks. It is validation-only: it returns field-keyed errors to merge, or
- *  nothing, and never transforms the data. */
+ *  nothing, and never transforms the data.
+ */
 export interface DefineFieldsOptions<F extends readonly FrontmatterField[]> {
     refine?: (data: InferFields<F>, body: string) => Record<string, string> | undefined;
 }

package/dist/content/site-dictionary.d.ts

@@ -1,8 +1,10 @@
-/** True when a word is a single valid dictionary line (no whitespace, no control characters, non-empty
+/**
+ * True when a word is a single valid dictionary line (no whitespace, no control characters, non-empty
  *  and within the length bound). A leading "#" is rejected: parseDictionary re-reads such a line as a
  *  comment, so committing it would silently drop the word on the next read. The action uses this to
  *  reject untrusted input before the merge, so a newline or a control byte can never inject an extra
- *  line into the committed file. */
+ *  line into the committed file.
+ */
 export declare function isValidDictionaryWord(word: string, maxLength?: number): boolean;
 /**
  * Parse the committed dictionary file text into its word list. Comment lines (a `#` after optional

package/dist/content/site-dictionary.js

@@ -16,11 +16,13 @@ const HEADER = '# cairn personal dictionary: one word per line, sorted, kept in
 // the test is for whitespace and control bytes rather than an allow-list of letters. The action runs
 // inbound words through this before a merge.
 const WORD_RE = /^[^\s\p{Cc}]+$/u;
-/** True when a word is a single valid dictionary line (no whitespace, no control characters, non-empty
+/**
+ * True when a word is a single valid dictionary line (no whitespace, no control characters, non-empty
  *  and within the length bound). A leading "#" is rejected: parseDictionary re-reads such a line as a
  *  comment, so committing it would silently drop the word on the next read. The action uses this to
  *  reject untrusted input before the merge, so a newline or a control byte can never inject an extra
- *  line into the committed file. */
+ *  line into the committed file.
+ */
 export function isValidDictionaryWord(word, maxLength = 64) {
     if (word.startsWith('#'))
         return false;
@@ -45,8 +47,10 @@ export function parseDictionary(text) {
     }
     return words;
 }
-/** Case-insensitive, locale-stable comparator for the canonical sort. Words are compared lowercased
- *  so "Cairn" and "cairn" collapse to one entry, the same case-folding the Worker's merged set uses. */
+/**
+ * Case-insensitive, locale-stable comparator for the canonical sort. Words are compared lowercased
+ *  so "Cairn" and "cairn" collapse to one entry, the same case-folding the Worker's merged set uses.
+ */
 function byWord(a, b) {
     return a.toLowerCase().localeCompare(b.toLowerCase());
 }

package/dist/content/types.d.ts

@@ -12,6 +12,11 @@ interface FieldBase {
     label: string;
     /** A required field fails validation when empty (spec §7.4). */
     required?: boolean;
+    /**
+     * One author-facing sentence shown under the field in the editor, in plain end-user language.
+     * Optional; render nothing when absent. Not a validation rule.
+     */
+    description?: string;
 }
 /** A single-line text input. */
 export interface TextField extends FieldBase {
@@ -22,8 +27,10 @@ export interface TextField extends FieldBase {
     max?: number;
     /** Exact required character length. */
     length?: number;
-    /** A regular-expression source string the value must match. Stored as a string so the field
-     *  list stays plain serializable data; the validator compiles it. */
+    /**
+     * A regular-expression source string the value must match. Stored as a string so the field
+     *  list stays plain serializable data; the validator compiles it.
+     */
     pattern?: string;
 }
 /** A multi-line text input. */
@@ -83,8 +90,10 @@ export interface ImageField extends FieldBase {
  * arm in `schema.ts`, since its value is a nested object rather than a single string.
  */
 export type FrontmatterField = TextField | TextareaField | DateField | BooleanField | TagsField | FreeTagsField | ImageField;
-/** The stored value of an `image` field: a `media:` reference, a screen-reader description, and an
- *  optional caption. */
+/**
+ * The stored value of an `image` field: a `media:` reference, a screen-reader description, and an
+ *  optional caption.
+ */
 export interface ImageValue {
     src: string;
     alt: string;
@@ -120,8 +129,10 @@ export interface ConceptConfig<S extends ConceptSchema = ConceptSchema> {
     singular?: string;
     /** The concept's schema: the form projection, the generated validator, and the inferred type. */
     schema: S;
-    /** Frontmatter keys to surface on each `ContentSummary.fields`, so a list card reads an authored
-     *  field without a per-entry detail read. Each key should also be declared in `schema`. */
+    /**
+     * Frontmatter keys to surface on each `ContentSummary.fields`, so a list card reads an authored
+     *  field without a per-entry detail read. Each key should also be declared in `schema`.
+     */
     summaryFields?: string[];
 }
 /**
@@ -168,29 +179,39 @@ export interface NavMenuConfig {
  * stylesheet.
  */
 export interface PreviewConfig {
-    /** Absolute or root-relative URLs of the site's compiled stylesheets, linked inside the
-     *  preview document. A Vite `?url` import of the site's CSS resolves the hashed asset URL. */
+    /**
+     * Absolute or root-relative URLs of the site's compiled stylesheets, linked inside the
+     *  preview document. A Vite `?url` import of the site's CSS resolves the hashed asset URL.
+     */
     stylesheets: string[];
     /** Class list applied to the preview document's body, for theme or typography roots. */
     bodyClass?: string;
-    /** Class list for a wrapper element around the rendered content, reproducing the site's
-     *  content container (a prose or measure class). Omitted renders the content bare. */
+    /**
+     * Class list for a wrapper element around the rendered content, reproducing the site's
+     *  content container (a prose or measure class). Omitted renders the content bare.
+     */
     containerClass?: string;
-    /** Per-concept overrides of bodyClass and containerClass, keyed by concept id. An entry's
+    /**
+     * Per-concept overrides of bodyClass and containerClass, keyed by concept id. An entry's
      *  preview resolves the override for its concept over the top-level values; stylesheets are
-     *  always shared. */
+     *  always shared.
+     */
     byConcept?: Record<string, {
         bodyClass?: string;
         containerClass?: string;
     }>;
 }
-/** The flat preview shape `editLoad` ships to the edit page: the top-level `PreviewConfig`
- *  values with the entry's concept override applied, and no `byConcept` map. */
+/**
+ * The flat preview shape `editLoad` ships to the edit page: the top-level `PreviewConfig`
+ *  values with the entry's concept override applied, and no `byConcept` map.
+ */
 export type ResolvedPreview = Omit<PreviewConfig, 'byConcept'>;
-/** A site's media configuration (seam 4). A site sets this to turn on R2-backed media: uploads,
+/**
+ * A site's media configuration (seam 4). A site sets this to turn on R2-backed media: uploads,
  *  content-addressed storage, and Cloudflare Images variants. Omitting it leaves media off. The
  *  engine normalizes this into a `ResolvedAssetConfig` and merges the named variants over the
- *  built-in thumb, inline, card, and hero presets. */
+ *  built-in thumb, inline, card, and hero presets.
+ */
 export interface AssetConfig {
     /** The R2 bucket binding name on the Worker, e.g. "MEDIA_BUCKET". Required when a site declares media. */
     bucketBinding: string;
@@ -204,10 +225,12 @@ export interface AssetConfig {
     allowedTypes?: string[];
     /** Named transform presets, merged over the built-in thumb/inline/card/hero presets. */
     variants?: Record<string, VariantSpec>;
-    /** Whether Cloudflare Image Transformations are enabled for the zone (default false). The feature
+    /**
+     * Whether Cloudflare Image Transformations are enabled for the zone (default false). The feature
      *  is a per-zone setting that the dashboard or API turns on; it cannot be flipped from a Worker. With
      *  it off, the media resolver serves the bare full-size delivery path and ignores any preset, so
-     *  thumbnails stay correct (full-size-but-correct) rather than pointing at a dead /cdn-cgi/image URL. */
+     *  thumbnails stay correct (full-size-but-correct) rather than pointing at a dead /cdn-cgi/image URL.
+     */
     transformations?: boolean;
 }
 /** The single seam the engine consumes. A site implements this at `src/lib/cairn.config.ts`. */
@@ -223,33 +246,49 @@ export interface CairnAdapter {
     };
     backend: BackendConfig;
     sender: SenderConfig;
-    /** The site's one renderer: the editor preview and every public page call it (design decision 4).
+    /**
+     * Optional contact a stuck editor is pointed to from the in-admin help (an email address, a URL,
+     *  or a name and instruction). The help renders the hand-off only when this is set. Plain string,
+     *  passed through verbatim.
+     */
+    supportContact?: string;
+    /**
+     * The site's one renderer: the editor preview and every public page call it (design decision 4).
      *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-resolver-backed
      *  one, the preview a manifest one. The trailing `resolveMedia` is additive and optional: the build
-     *  passes a site-resolver-backed media resolver, the preview a manifest-backed one. */
+     *  passes a site-resolver-backed media resolver, the preview a manifest-backed one.
+     */
     render(md: string, opts?: {
         stagger?: boolean;
         resolve?: LinkResolve;
         resolveMedia?: import('../render/resolve-media.js').MediaResolve;
     }): string | Promise<string>;
-    /** Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
-     *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it. */
+    /**
+     * Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
+     *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it.
+     */
     manifestPath?: string;
-    /** Repo-relative path to the committed media manifest. Defaults to src/content/.cairn/media.json,
-     *  applied in composeRuntime. Sits outside any concept directory, like the content manifest. */
+    /**
+     * Repo-relative path to the committed media manifest. Defaults to src/content/.cairn/media.json,
+     *  applied in composeRuntime. Sits outside any concept directory, like the content manifest.
+     */
     mediaManifestPath?: string;
-    /** Repo-relative path to the committed personal dictionary file. Defaults to
+    /**
+     * Repo-relative path to the committed personal dictionary file. Defaults to
      *  src/content/.cairn/dictionary.txt, applied in composeRuntime: the same `.cairn/` content root the
      *  manifests use, so the spec's `content/.cairn/dictionary.txt` resolves the same configurable way the
-     *  manifest paths do. One word per line, sorted, comment lines allowed (see site-dictionary.ts). */
+     *  manifest paths do. One word per line, sorted, comment lines allowed (see site-dictionary.ts).
+     */
     dictionaryPath?: string;
     /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
     registry?: ComponentRegistry;
     /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
     icons?: IconSet;
     navMenu?: NavMenuConfig;
-    /** The live site's content styling for the preview frame. The admin's chrome isolation keeps
-     *  the site's CSS out of the admin document, so the preview frame links these instead. */
+    /**
+     * The live site's content styling for the preview frame. The admin's chrome isolation keeps
+     *  the site's CSS out of the admin document, so the preview frame links these instead.
+     */
     preview?: PreviewConfig;
     assets?: AssetConfig;
 }
@@ -273,8 +312,10 @@ export interface ConceptDescriptor {
     /** Concept id, the key under `content`, e.g. "posts". */
     id: string;
     label: string;
-    /** The singular noun for the create affordances ("New post"); resolved from `ConceptConfig.singular`,
-     *  defaulting to `label` when the config omits it. */
+    /**
+     * The singular noun for the create affordances ("New post"); resolved from `ConceptConfig.singular`,
+     *  defaulting to `label` when the config omits it.
+     */
     singular: string;
     dir: string;
     routing: RoutingRule;
@@ -283,8 +324,10 @@ export interface ConceptDescriptor {
     /** Filename date-prefix granularity for a dated concept; resolved by `normalizeConcepts`. */
     datePrefix: DatePrefix;
     fields: FrontmatterField[];
-    /** Frontmatter keys the index copies onto each summary's `fields` record. `normalizeConcepts`
-     *  resolves it to `[]` when a concept omits `summaryFields`. */
+    /**
+     * Frontmatter keys the index copies onto each summary's `fields` record. `normalizeConcepts`
+     *  resolves it to `[]` when a concept omits `summaryFields`.
+     */
     summaryFields: string[];
     validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
 }
@@ -339,9 +382,13 @@ export interface CairnRuntime {
     concepts: ConceptDescriptor[];
     backend: BackendConfig;
     sender: SenderConfig;
-    /** The site's one renderer: the editor preview and every public page call it (design decision 4).
+    /** The support contact passed through from the adapter; the in-admin help reads it. Optional. */
+    supportContact?: string;
+    /**
+     * The site's one renderer: the editor preview and every public page call it (design decision 4).
      *  The trailing `resolveMedia` is additive and optional: the build passes a site-resolver-backed
-     *  media resolver, the preview a manifest-backed one. */
+     *  media resolver, the preview a manifest-backed one.
+     */
     render(md: string, opts?: {
         stagger?: boolean;
         resolve?: LinkResolve;
@@ -350,15 +397,19 @@ export interface CairnRuntime {
     manifestPath: string;
     /** The repo-relative path to the committed media manifest, defaulted in composeRuntime. */
     mediaManifestPath: string;
-    /** The repo-relative path to the committed personal dictionary file (one word per line, sorted),
+    /**
+     * The repo-relative path to the committed personal dictionary file (one word per line, sorted),
      *  defaulted in composeRuntime to src/content/.cairn/dictionary.txt: the same `.cairn/` content root
      *  the manifests use. The edit load reads it and threads its words onto EditData; the
      *  addDictionaryWord action reads, merges, and commits it. Optional on the runtime so a hand-built
      *  runtime need not set it; composeRuntime always fills it, and the edit load and the action default
-     *  a missing value to the same content-root path. */
+     *  a missing value to the same content-root path.
+     */
     dictionaryPath?: string;
-    /** The adapter's asset config resolved once at compose: `{ enabled: false }` for a no-media site,
-     *  otherwise the filled config the upload, storage, delivery, and resolver paths read. */
+    /**
+     * The adapter's asset config resolved once at compose: `{ enabled: false }` for a no-media site,
+     *  otherwise the filled config the upload, storage, delivery, and resolver paths read.
+     */
     resolvedAssets: import('../media/config.js').ResolvedAssetConfig;
     registry?: ComponentRegistry;
     /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
@@ -367,18 +418,22 @@ export interface CairnRuntime {
     /** The live site's content styling for the preview frame; passed through from the adapter. */
     preview?: PreviewConfig;
     assets?: AssetConfig;
-    /** The editor's spellcheck dictionary file, resolved once at compose from the site config's
+    /**
+     * The editor's spellcheck dictionary file, resolved once at compose from the site config's
      *  `spellcheck.dialect` (defaulting to US English). The edit load threads it onto EditData and the
      *  editor resolves it to a real asset URL on the main thread, so the Worker receives the URL and
      *  never reads config. Just the filename, e.g. "dictionary-en-us.txt". Optional on the runtime so a
      *  hand-built runtime need not set it; composeRuntime always fills it, and the edit load defaults a
-     *  missing value to the US English dictionary. */
+     *  missing value to the US English dictionary.
+     */
     spellcheckDictionary?: string;
-    /** The editor tidy (LLM copy-edit) settings, passed through from the site config. Optional on the
+    /**
+     * The editor tidy (LLM copy-edit) settings, passed through from the site config. Optional on the
      *  runtime so a hand-built runtime need not set it; composeRuntime threads it from
      *  `siteConfig.tidy`. The tidy action reads `enabled` and `model` at call time, and builds its prompt
      *  from `conventions`. Absent (or `enabled` false) means tidy is off, and the action refuses with a
-     *  fail(503) before any model call. */
+     *  fail(503) before any model call.
+     */
     tidy?: import('../nav/site-config.js').TidyConfig;
     /** Admin panels contributed by extensions (Mode 2). Empty until Plan 09 wires the dispatch route. */
     adminPanels?: AdminPanel[];