@bendyline/squisq 1.3.0 → 1.4.0

package/src/jsonForm/pointer.ts

@@ -0,0 +1,109 @@
+/**
+ * JSON Pointer helpers (RFC 6901) plus immutable get/set, plus a tiny
+ * dotted-path normalizer so hosts can write `user.role` instead of
+ * `/user/role`. `$ref` resolution is local-only (`#/$defs/Foo`).
+ */
+
+import type { SquisqAnnotatedSchema } from './types.js';
+
+/** Normalize a path to a JSON Pointer string. Accepts both forms. */
+export function toPointer(path: string): string {
+  if (path === '' || path === '/') return '';
+  if (path.startsWith('/')) return path;
+  // Dotted form: split on `.` and escape per RFC 6901.
+  return (
+    '/' +
+    path
+      .split('.')
+      .map((seg) => seg.replace(/~/g, '~0').replace(/\//g, '~1'))
+      .join('/')
+  );
+}
+
+/** Split a JSON Pointer into decoded segments. Empty string → []. */
+export function pointerSegments(pointer: string): string[] {
+  if (pointer === '') return [];
+  return pointer
+    .slice(1)
+    .split('/')
+    .map((seg) => seg.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+
+/** Read a value from data by path (dotted or pointer). Returns undefined if missing. */
+export function getByPointer(data: unknown, path: string): unknown {
+  const segments = pointerSegments(toPointer(path));
+  let cur: unknown = data;
+  for (const seg of segments) {
+    if (cur === null || cur === undefined) return undefined;
+    if (Array.isArray(cur)) {
+      const idx = Number(seg);
+      if (!Number.isInteger(idx) || idx < 0 || idx >= cur.length) return undefined;
+      cur = cur[idx];
+    } else if (typeof cur === 'object') {
+      cur = (cur as Record<string, unknown>)[seg];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+/**
+ * Return a structurally-shared copy of `data` with the value at `path`
+ * replaced. Intermediate objects/arrays are cloned along the path; the
+ * rest is shared by reference. Creates intermediate objects if missing.
+ */
+export function setByPointer<T>(data: T, path: string, value: unknown): T {
+  const segments = pointerSegments(toPointer(path));
+  if (segments.length === 0) return value as T;
+  return setRec(data, segments, 0, value) as T;
+}
+
+function setRec(node: unknown, segments: string[], i: number, value: unknown): unknown {
+  const seg = segments[i];
+  const isLast = i === segments.length - 1;
+
+  // Decide whether the slot we're about to write into is an array index.
+  const nextSeg = isLast ? undefined : segments[i + 1];
+  const writingArrayChild = nextSeg !== undefined && /^\d+$/.test(nextSeg);
+
+  if (Array.isArray(node)) {
+    const idx = Number(seg);
+    const next = node.slice();
+    next[idx] = isLast
+      ? value
+      : setRec(node[idx] ?? (writingArrayChild ? [] : {}), segments, i + 1, value);
+    return next;
+  }
+
+  const obj = (node && typeof node === 'object' ? { ...(node as object) } : {}) as Record<
+    string,
+    unknown
+  >;
+  obj[seg] = isLast
+    ? value
+    : setRec(obj[seg] ?? (writingArrayChild ? [] : {}), segments, i + 1, value);
+  return obj;
+}
+
+/**
+ * Resolve a local `$ref` (e.g. `#/$defs/Foo`) against the root schema.
+ * Returns the original schema if no `$ref` is present, or `undefined`
+ * if the reference cannot be resolved. Cross-document refs are not
+ * supported.
+ */
+export function resolveRef(
+  schema: SquisqAnnotatedSchema,
+  root: SquisqAnnotatedSchema,
+): SquisqAnnotatedSchema | undefined {
+  if (!schema.$ref) return schema;
+  const ref = schema.$ref;
+  if (!ref.startsWith('#/')) return undefined;
+  const segments = pointerSegments(ref.slice(1));
+  let cur: unknown = root;
+  for (const seg of segments) {
+    if (cur === null || cur === undefined || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[seg];
+  }
+  return (cur as SquisqAnnotatedSchema | undefined) ?? undefined;
+}

package/src/jsonForm/types.ts

@@ -0,0 +1,167 @@
+/**
+ * JSON Form types — Squisq's hint vocabulary layered on JSON Schema.
+ *
+ * Hints live inline on a JSON Schema under a single `squisq` key. The
+ * schema remains a valid JSON Schema; the extra key is ignored by
+ * standard validators. Renderers consult the hints to pick a control
+ * and tune its presentation.
+ */
+
+/**
+ * Every concrete control rendered by `<JsonView>` and `<JsonEditor>`.
+ *
+ * Auto-defaults pick one based on schema shape; hosts override via
+ * `squisq.control` when they want something specific (e.g. radio over
+ * segmented for a long, descriptive enum).
+ */
+export type ControlKind =
+  | 'text'
+  | 'multiline'
+  | 'richtext'
+  | 'color'
+  | 'date'
+  | 'time'
+  | 'datetime'
+  | 'slider'
+  | 'stepper'
+  | 'segmented'
+  | 'radio'
+  | 'combobox'
+  | 'toggle'
+  | 'checkbox'
+  | 'card'
+  | 'card-stack'
+  | 'chip-bin'
+  | 'tabs'
+  | 'group';
+
+/**
+ * Conditional rule: looked up by field path against the root data and
+ * compared with one of the operators. The first defined operator wins
+ * (in declaration order: equals, oneOf, matches, truthy).
+ */
+export interface SquisqWhen {
+  /**
+   * Path to the controlling field, relative to the root data.
+   * Accepts dotted-path (`user.role`) or JSON Pointer (`/user/role`).
+   */
+  field: string;
+  equals?: unknown;
+  oneOf?: readonly unknown[];
+  /** ECMAScript regex source; matched against the string value. */
+  matches?: string;
+  /** When true, condition holds if value is truthy; when false, if falsy. */
+  truthy?: boolean;
+}
+
+/**
+ * Hints for a single schema node. Attach via `squisq` on any JSON
+ * Schema object — properties, items, the root, or sub-schemas inside
+ * `oneOf`/`anyOf`.
+ */
+export interface SquisqHints {
+  /** Force a specific control. If omitted, picked from type/format/enum cardinality. */
+  control?: ControlKind;
+
+  /** Override schema `title` for display. */
+  label?: string;
+  /** Override schema `description` for the inline helper text. */
+  help?: string;
+  /** Placeholder text for empty fields. */
+  placeholder?: string;
+
+  /** Suggested layout sizing in a parent grid. Renderers may ignore on narrow viewports. */
+  width?: 'full' | 'half' | 'third' | 'auto';
+
+  /** Hide the field — literal, or a `SquisqWhen` evaluated against root data. */
+  hidden?: boolean | SquisqWhen;
+  /** Disable the field — literal, or a `SquisqWhen` evaluated against root data. */
+  disabled?: boolean | SquisqWhen;
+
+  /** Override schema's required-ness for the UI only. */
+  required?: boolean;
+
+  /** For arrays of objects: how to label each card in a `card-stack`. */
+  itemLabel?: string | { fromField: string };
+  /** Label for the "+ Add" button on arrays. */
+  addLabel?: string;
+  /** Label for the remove button on arrays. */
+  removeLabel?: string;
+
+  /** Slider/stepper visual step. Falls back to schema `multipleOf`. */
+  step?: number;
+
+  /** Optional human-readable labels for enum values. */
+  enumLabels?: Record<string, string>;
+}
+
+/**
+ * The subset of JSON Schema we understand, with an optional `squisq`
+ * key. We deliberately keep this as a structural type so any JSON
+ * Schema authored elsewhere can be passed in without conversion.
+ */
+export interface SquisqAnnotatedSchema {
+  type?: string | readonly string[];
+  format?: string;
+  title?: string;
+  description?: string;
+  default?: unknown;
+  examples?: readonly unknown[];
+
+  enum?: readonly unknown[];
+  const?: unknown;
+
+  // Object
+  properties?: Record<string, SquisqAnnotatedSchema>;
+  required?: readonly string[];
+  additionalProperties?: boolean | SquisqAnnotatedSchema;
+
+  // Array
+  items?: SquisqAnnotatedSchema | readonly SquisqAnnotatedSchema[];
+  minItems?: number;
+  maxItems?: number;
+
+  // Number
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+
+  // String
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+
+  // Combinators
+  oneOf?: readonly SquisqAnnotatedSchema[];
+  anyOf?: readonly SquisqAnnotatedSchema[];
+  allOf?: readonly SquisqAnnotatedSchema[];
+
+  // References
+  $ref?: string;
+  $defs?: Record<string, SquisqAnnotatedSchema>;
+  definitions?: Record<string, SquisqAnnotatedSchema>;
+
+  // Squisq-native UI hints
+  squisq?: SquisqHints;
+}
+
+/**
+ * A validation error reported by the consumer-supplied `validate` prop.
+ * Matches the shape of common validators (ajv, etc.) without depending
+ * on any specific one.
+ */
+export interface JsonFormValidationError {
+  /** JSON Pointer to the failing value, e.g. `/sections/0/heading`. */
+  path: string;
+  /** Human-readable message. */
+  message: string;
+  /** Optional schema keyword that failed (e.g. "required", "minimum"). */
+  keyword?: string;
+}
+
+export type JsonFormValidator = (
+  value: unknown,
+  schema: SquisqAnnotatedSchema,
+) => readonly JsonFormValidationError[];

package/src/markdown/convert.ts

@@ -20,8 +20,10 @@ import type {
   MarkdownSourcePosition,
   HeadingTemplateAnnotation,
   MarkdownHeading,
+  MarkdownInlineIcon,
 } from './types.js';
 import { parseHtmlToNodes } from './htmlParse.js';
+import { resolveIcon } from '../icons/resolve.js';
 
 // ============================================
 // Generic mdast node shape
@@ -132,8 +134,13 @@ function extractText(node: MdastNode): string {
 /**
  * Regex matching a trailing `{[templateName key=value …]}` annotation.
  * Captures the content between `{[` and `]}`.
+ *
+ * The trailing `[\s\]\}]*` tolerates accidental doubled `]}` that users
+ * sometimes type when learning the syntax (e.g. `{[foo]}]}`). It does
+ * not allow trailing word characters, so a non-trailing annotation like
+ * `## The {[chart]} section` still doesn't match.
  */
-const TEMPLATE_ANNOTATION_RE = /\s*\{\[([^\]]+)\]\}\s*$/;
+const TEMPLATE_ANNOTATION_RE = /\s*\{\[([^\]]+)\]\}[\s\]}]*$/;
 
 /**
  * Extract a `{[templateName key=value …]}` annotation from a heading's
@@ -247,13 +254,130 @@ function convertBlockChildren(children: MdastNode[], parseHtml: boolean): Markdo
   return result;
 }
 
-function convertInlineChildren(children: MdastNode[], parseHtml: boolean): MarkdownInlineNode[] {
+function convertInlineChildren(
+  children: MdastNode[],
+  parseHtml: boolean,
+  /** When false, skip the inline-icon split. Headings opt out so the
+   *  `extractTemplateAnnotation` pass still sees the trailing
+   *  `{[…]}` in raw text form; the caller runs `splitInlineIcons`
+   *  itself afterward on the remaining children. */
+  applyIconSplit: boolean = true,
+): MarkdownInlineNode[] {
   const result: MarkdownInlineNode[] = [];
   for (const child of children) {
     const node = convertInlineNode(child, parseHtml);
     if (node) result.push(node);
   }
-  return coalesceMentions(result);
+  const mentioned = coalesceMentions(result);
+  return applyIconSplit ? splitInlineIcons(mentioned) : mentioned;
+}
+
+/**
+ * Walk an inline-children list and split each text node on `{[token]}`
+ * occurrences whose tokens resolve to known FontAwesome icons. Returns
+ * a new array — unresolved tokens are left as literal text so authors
+ * can write `{[notathing]}` verbatim if they really mean to.
+ *
+ * Exposed for the heading code path, which first strips the trailing
+ * template annotation and then runs this on what remains.
+ */
+export function splitInlineIcons(nodes: MarkdownInlineNode[]): MarkdownInlineNode[] {
+  // First pass: reassemble `text + textDirective + text` patterns
+  // formed when a qualified token like `{[fa-solid:user]}` was split
+  // by remark-directive's colon recognition. We collapse those triples
+  // back into a single text node containing the original token so the
+  // regex below can match.
+  const recombined = recombineDirectiveTokens(nodes);
+
+  const out: MarkdownInlineNode[] = [];
+  for (const node of recombined) {
+    if (node.type !== 'text') {
+      out.push(node);
+      continue;
+    }
+    out.push(...splitTextOnIcons(node.value, node.position));
+  }
+  return out;
+}
+
+/**
+ * When the user types `{[fa-solid:user]}`, remark's directive plugin
+ * sees `:user` and emits a `textDirective` node. The result is a
+ * three-node sequence `text("…{[fa-solid") + textDirective("user") +
+ * text("]}…")`. This helper detects that shape and stitches the three
+ * back into one text node so downstream icon detection works on the
+ * authored token.
+ */
+function recombineDirectiveTokens(nodes: MarkdownInlineNode[]): MarkdownInlineNode[] {
+  const out: MarkdownInlineNode[] = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const cur = nodes[i];
+    const next = nodes[i + 1];
+    const after = nodes[i + 2];
+    if (
+      cur?.type === 'text' &&
+      next?.type === 'textDirective' &&
+      after?.type === 'text' &&
+      /\{\[[a-zA-Z0-9_-]+$/.test(cur.value) &&
+      /^\]\}/.test(after.value)
+    ) {
+      const directive = next as unknown as { name?: string };
+      const directiveName = directive.name ?? '';
+      const merged: MarkdownInlineNode = {
+        type: 'text',
+        value: cur.value + ':' + directiveName + after.value,
+        ...(cur.position ? { position: cur.position } : {}),
+      };
+      out.push(merged);
+      i += 2;
+      continue;
+    }
+    out.push(cur);
+  }
+  return out;
+}
+
+const ICON_TOKEN_RE = /\{\[([a-zA-Z0-9_:-]+)\]\}/g;
+
+function splitTextOnIcons(value: string, position?: MarkdownSourcePosition): MarkdownInlineNode[] {
+  if (!value) return [];
+  ICON_TOKEN_RE.lastIndex = 0;
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+  const out: MarkdownInlineNode[] = [];
+  while ((match = ICON_TOKEN_RE.exec(value)) !== null) {
+    const token = match[1];
+    const icon = resolveIcon(token);
+    if (!icon) continue; // leave the literal `{[…]}` in place
+    if (match.index > lastIndex) {
+      out.push({
+        type: 'text',
+        value: value.slice(lastIndex, match.index),
+        ...(position ? { position } : {}),
+      });
+    }
+    const iconNode: MarkdownInlineIcon = {
+      type: 'inlineIcon',
+      token,
+      family: icon.family,
+      name: icon.name,
+      ...(position ? { position } : {}),
+    };
+    out.push(iconNode);
+    lastIndex = match.index + match[0].length;
+  }
+  if (lastIndex === 0) {
+    // No matches — return the original text node unchanged.
+    return [{ type: 'text', value, ...(position ? { position } : {}) }];
+  }
+  if (lastIndex < value.length) {
+    out.push({
+      type: 'text',
+      value: value.slice(lastIndex),
+      ...(position ? { position } : {}),
+    });
+  }
+  return out;
 }
 
 /**
@@ -318,12 +442,18 @@ function convertBlockNode(node: MdastNode, parseHtml: boolean): MarkdownBlockNod
 
   switch (node.type) {
     case 'heading': {
-      const headingChildren = convertInlineChildren(node.children ?? [], parseHtml);
+      // Defer icon splitting so `extractTemplateAnnotation` sees the
+      // trailing `{[name]}` as plain text and can decide whether it's
+      // a template annotation. Anything that's NOT the template still
+      // needs to become an icon node, so we run `splitInlineIcons` on
+      // what's left after the template extraction.
+      const headingChildren = convertInlineChildren(node.children ?? [], parseHtml, false);
       const annotation = extractTemplateAnnotation(headingChildren);
+      const finalChildren = splitInlineIcons(headingChildren);
       const result: MarkdownHeading = {
         type: 'heading',
         depth: (node.depth ?? 1) as 1 | 2 | 3 | 4 | 5 | 6,
-        children: headingChildren,
+        children: finalChildren,
         ...posField(pos),
       };
       if (annotation) {
@@ -967,6 +1097,16 @@ function inlineToMdast(node: MarkdownInlineNode): MdastNode {
         ...mdastPosField(node.position),
       };
 
+    case 'inlineIcon':
+      // Serialize back to the authored token so source round-trips
+      // byte-stable. The token already carries the qualified form when
+      // required (the parser preserved it verbatim).
+      return {
+        type: 'text',
+        value: `{[${node.token}]}`,
+        ...mdastPosField(node.position),
+      };
+
     default:
       return { type: 'text', value: '' };
   }

package/src/markdown/index.ts

@@ -108,4 +108,7 @@ export {
   countNodes,
   createDocument,
   parseFrontmatter,
+  setFrontmatterValues,
+  inferDocumentTitle,
+  readFrontmatterThemeId,
 } from './utils.js';

package/src/markdown/types.ts

@@ -453,6 +453,22 @@ export interface MarkdownInlineMath extends MarkdownNodeBase {
   value: string;
 }
 
+/**
+ * Inline FontAwesome icon. Authored as `{[name]}` (bare) or
+ * `{[fa-<family>:name]}` (qualified) in markdown source. The parser
+ * resolves the token against the FA Free catalog and emits this node;
+ * unknown / ambiguous tokens stay as literal text.
+ */
+export interface MarkdownInlineIcon extends MarkdownNodeBase {
+  type: 'inlineIcon';
+  /** Token exactly as authored — e.g. `github` or `fa-solid:user`. */
+  token: string;
+  /** Resolved icon family. */
+  family: 'brands' | 'solid' | 'regular';
+  /** Resolved icon name (without the `fa-` prefix). */
+  name: string;
+}
+
 /**
  * A footnote reference [^id]. GFM extension.
  */
@@ -518,7 +534,7 @@ export interface MarkdownTextDirective extends MarkdownNodeBase {
  */
 export interface MarkdownMention extends MarkdownNodeBase {
   type: 'mention';
-  /** Namespace for the mentioned entity (e.g. `"gezel"`, `"user"`). */
+  /** Namespace for the mentioned entity (e.g. `"user"`). */
   targetKind: string;
   /** Stable identifier within the namespace. */
   targetId: string;
@@ -563,7 +579,8 @@ export type MarkdownInlineNode =
   | MarkdownLinkReference
   | MarkdownImageReference
   | MarkdownTextDirective
-  | MarkdownMention;
+  | MarkdownMention
+  | MarkdownInlineIcon;
 
 /**
  * Any node in the markdown tree. Includes structural nodes (listItem,

package/src/markdown/utils.ts

@@ -157,6 +157,109 @@ export function parseFrontmatter(yaml: string): Record<string, unknown> | null {
   return Object.keys(result).length > 0 ? result : null;
 }
 
+const FRONTMATTER_BLOCK_RE = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n)?/;
+
+/** Quote a frontmatter scalar so it round-trips cleanly through `parseFrontmatter`. */
+function formatFrontmatterValue(value: string | number | boolean): string {
+  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  // Quote when needed: leading/trailing whitespace, leading punctuation that
+  // could trigger YAML modes, or values that look like reserved literals.
+  const needsQuote =
+    /^\s|\s$/.test(value) ||
+    /^[!&*?|>%@`]/.test(value) ||
+    /[:#]/.test(value) ||
+    value === '' ||
+    value === 'true' ||
+    value === 'false' ||
+    /^-?\d+(\.\d+)?$/.test(value);
+  if (!needsQuote) return value;
+  // Prefer double quotes; escape any embedded double-quote / backslash.
+  const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return `"${escaped}"`;
+}
+
+/**
+ * Update a markdown source string's YAML frontmatter block, applying the
+ * given key/value updates. A `null` or `undefined` value removes the key.
+ * If no frontmatter block exists and any non-null update is supplied, a
+ * new block is prepended; if every update is a removal and no block
+ * exists, the source is returned unchanged.
+ *
+ * Existing key order is preserved; new keys are appended in the order
+ * they appear in `updates`. The simple parser used here handles plain
+ * `key: value` pairs only — comments, multi-line scalars, and nested
+ * structures are left untouched (we only rewrite lines whose key matches
+ * one in `updates`).
+ *
+ * @param source - The markdown source string.
+ * @param updates - Map of key → new value (or null/undefined to remove).
+ * @returns The updated markdown source string.
+ */
+export function setFrontmatterValues(
+  source: string,
+  updates: Record<string, string | number | boolean | null | undefined>,
+): string {
+  const updateKeys = Object.keys(updates);
+  if (updateKeys.length === 0) return source;
+
+  const match = source.match(FRONTMATTER_BLOCK_RE);
+  const handled = new Set<string>();
+
+  // Existing frontmatter block — rewrite line-by-line, preserving order.
+  if (match) {
+    const inner = match[1];
+    const lines = inner.split(/\r?\n/);
+    const newLines: string[] = [];
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) {
+        newLines.push(line);
+        continue;
+      }
+      const colonIdx = trimmed.indexOf(':');
+      if (colonIdx < 1) {
+        newLines.push(line);
+        continue;
+      }
+      const key = trimmed.slice(0, colonIdx).trim();
+      if (!Object.prototype.hasOwnProperty.call(updates, key)) {
+        newLines.push(line);
+        continue;
+      }
+      handled.add(key);
+      const next = updates[key];
+      if (next === null || next === undefined) continue; // remove
+      newLines.push(`${key}: ${formatFrontmatterValue(next)}`);
+    }
+
+    // Append any keys that weren't already present.
+    for (const key of updateKeys) {
+      if (handled.has(key)) continue;
+      const next = updates[key];
+      if (next === null || next === undefined) continue;
+      newLines.push(`${key}: ${formatFrontmatterValue(next)}`);
+    }
+
+    // If every line got removed, drop the block entirely.
+    const nonEmpty = newLines.filter((l) => l.trim().length > 0);
+    const rest = source.slice(match[0].length);
+    if (nonEmpty.length === 0) return rest;
+    return `---\n${newLines.join('\n')}\n---\n${rest}`;
+  }
+
+  // No existing block — only create one if there's at least one non-null
+  // value to write.
+  const fresh: string[] = [];
+  for (const key of updateKeys) {
+    const next = updates[key];
+    if (next === null || next === undefined) continue;
+    fresh.push(`${key}: ${formatFrontmatterValue(next)}`);
+  }
+  if (fresh.length === 0) return source;
+  return `---\n${fresh.join('\n')}\n---\n${source}`;
+}
+
 /**
  * Create a minimal MarkdownDocument from a list of block nodes.
  * Convenience function for programmatic document construction.
@@ -167,3 +270,59 @@ export function createDocument(...children: MarkdownDocument['children']): Markd
     children,
   };
 }
+
+/**
+ * Infer a human-readable title for a markdown document.
+ *
+ * Resolution order:
+ *   1. `title:` value in YAML frontmatter (when present and non-empty)
+ *   2. Text of the first heading found, walking top-level depth (H1, then
+ *      H2, etc.) — the shallowest heading wins regardless of source order
+ *
+ * Returns `undefined` when no usable title is found.
+ */
+export function inferDocumentTitle(doc: MarkdownDocument): string | undefined {
+  const fmTitle = doc.frontmatter?.title;
+  if (typeof fmTitle === 'string') {
+    const trimmed = fmTitle.trim();
+    if (trimmed) return trimmed;
+  }
+
+  let best: { depth: number; text: string } | null = null;
+  for (const node of doc.children) {
+    if (node.type !== 'heading') continue;
+    const text = extractPlainText(node).trim();
+    if (!text) continue;
+    if (best === null || node.depth < best.depth) {
+      best = { depth: node.depth, text };
+      if (best.depth === 1) break;
+    }
+  }
+
+  return best?.text;
+}
+
+/**
+ * Read a theme id from a markdown document's frontmatter.
+ *
+ * Checks the editor's canonical `squisq-theme` key first, then the
+ * shorter legacy aliases (`themeId`, `theme`). Returns `undefined`
+ * when none of them carry a non-empty string. Centralizing the lookup
+ * keeps the export pipelines (DOCX, PPTX, HTML, plain-HTML bundle) in
+ * sync with whatever the editor writes — adding a new frontmatter
+ * spelling later is a one-file change.
+ */
+export function readFrontmatterThemeId(
+  frontmatter: Record<string, unknown> | undefined,
+): string | undefined {
+  if (!frontmatter) return undefined;
+  const keys = ['squisq-theme', 'themeId', 'theme'] as const;
+  for (const key of keys) {
+    const raw = frontmatter[key];
+    if (typeof raw === 'string') {
+      const trimmed = raw.trim();
+      if (trimmed) return trimmed;
+    }
+  }
+  return undefined;
+}