@bendyline/squisq 1.5.0 → 1.5.1

package/src/doc/validate.ts

@@ -28,8 +28,12 @@ import type {
 } from '../markdown/types.js';
 import { parseMarkdown } from '../markdown/parse.js';
 import { getChildren, extractPlainText } from '../markdown/utils.js';
-import { coerceAnnotationValues } from '../markdown/annotationCoercion.js';
+import { coerceAnnotationValues, KNOWN_BLOCK_META_KEYS } from '../markdown/annotationCoercion.js';
 import { markdownToDoc, flattenBlocks } from './markdownToDoc.js';
+import { parseStandaloneAnnotation } from './standaloneAnnotation.js';
+import { isDataFence, parseDataFence } from './structuredData.js';
+import { deriveTemplateInputs } from './templateInputs.js';
+import { lintTemplateParams } from './templates/inputDescriptors.js';
 import {
   templateRegistry,
   TEMPLATE_ALIASES,
@@ -38,6 +42,7 @@ import {
   normalizeShapeKind,
   SHAPE_NAMES,
 } from './templates/index.js';
+import { nearestName } from './utils/nearest.js';
 
 // ============================================
 // Options & result
@@ -64,6 +69,7 @@ export interface MarkdownValidationResult {
   diagnostics: DocDiagnostic[];
   errorCount: number;
   warningCount: number;
+  infoCount: number;
   /** The converted Doc (conversion diagnostics are included above). */
   doc: Doc;
 }
@@ -95,6 +101,9 @@ export function validateMarkdownDoc(
   const blocks = flattenBlocks(doc.blocks);
 
   const knownTemplates = collectKnownTemplates(doc, options);
+  // Custom template names are skipped by the input linter — they carry
+  // arbitrary author-defined inputs the built-in descriptors can't know about.
+  const customNames = new Set<string>(doc.customTemplates?.map((t) => t.name) ?? []);
 
   // Parent-aware walk: a `{[shape]}` annotation is only meaningful on the
   // direct child of a `{[drawing]}` block, so the template check needs each
@@ -102,6 +111,9 @@ export function validateMarkdownDoc(
   const visit = (block: Block, parent: Block | undefined): void => {
     checkTemplate(block, parent, knownTemplates, diagnostics);
     checkAttributeCoercion(block, parent, diagnostics);
+    checkConflictingAnnotationKeys(block, diagnostics);
+    checkTemplateInputs(block, parent, customNames, diagnostics);
+    checkPossibleDataFences(block, diagnostics);
     if (isDrawingBlock(block)) checkDrawingConnectors(block, diagnostics);
     for (const child of block.children ?? []) visit(child, block);
   };
@@ -122,6 +134,7 @@ export function validateMarkdownDoc(
     diagnostics,
     errorCount: diagnostics.filter((d) => d.severity === 'error').length,
     warningCount: diagnostics.filter((d) => d.severity === 'warning').length,
+    infoCount: diagnostics.filter((d) => d.severity === 'info').length,
     doc,
   };
 }
@@ -150,13 +163,19 @@ function checkTemplate(
   known: Set<string>,
   diagnostics: DocDiagnostic[],
 ): void {
-  const requested = block.sourceHeading?.templateAnnotation?.template;
+  // Heading blocks carry the requested name on the heading annotation;
+  // heading-less standalone blocks carry it on `sourceAnnotation` (raw,
+  // un-resolved) — read whichever is present.
+  const requested =
+    block.sourceHeading?.templateAnnotation?.template ?? block.sourceAnnotation?.template;
   if (!requested) return;
 
   // Inside a drawing, the annotation names a shape primitive, not a template.
   if (parent && isDrawingBlock(parent)) {
     if (isShapeName(requested)) return;
-    const suggestion = nearestName(requested, new Set(SHAPE_NAMES));
+    const suggestion = nearestName(requested, new Set(SHAPE_NAMES), {
+      map: resolveTemplateName,
+    });
     diagnostics.push({
       severity: 'warning',
       code: 'unknown-shape',
@@ -183,7 +202,7 @@ function checkTemplate(
 
   if (known.has(requested) || known.has(resolveTemplateName(requested))) return;
 
-  const suggestion = nearestName(requested, known);
+  const suggestion = nearestName(requested, known, { map: resolveTemplateName });
   diagnostics.push({
     severity: 'warning',
     code: 'unknown-template',
@@ -195,6 +214,60 @@ function checkTemplate(
   });
 }
 
+/**
+ * Lint a template block's `{[…]}` inputs against the built-in input
+ * descriptors: unknown keys (with a did-you-mean), values outside a closed
+ * enum / that fail coercion, and missing required inputs. All are warnings.
+ *
+ * Only built-in templates with descriptors are checked — shapes, drawing
+ * children, custom templates, and not-yet-described built-ins are skipped
+ * (`lintTemplateParams` returns `[]` for the latter). A `missing-input`
+ * finding is suppressed when the value is actually satisfiable from the
+ * block's own fields, structured data, or body derivation.
+ */
+function checkTemplateInputs(
+  block: Block,
+  parent: Block | undefined,
+  customNames: ReadonlySet<string>,
+  diagnostics: DocDiagnostic[],
+): void {
+  const requested = block.sourceHeading?.templateAnnotation?.template;
+  if (!requested) return;
+  // Inside a drawing, the annotation names a shape primitive, not a template.
+  if (parent && isDrawingBlock(parent)) return;
+  if (isShapeName(requested)) return;
+
+  const canonical = resolveTemplateName(requested);
+  if (customNames.has(requested) || customNames.has(canonical)) return;
+
+  const params = block.sourceHeading?.templateAnnotation?.params ?? {};
+  for (const finding of lintTemplateParams(canonical, params)) {
+    if (finding.kind === 'missing-input' && isInputSatisfiable(canonical, block, finding.key)) {
+      continue;
+    }
+    diagnostics.push({
+      severity: 'warning',
+      code: finding.kind,
+      message: `Block "${block.id}": ${finding.message}`,
+      blockId: block.id,
+      ...lineOf(block),
+    });
+  }
+}
+
+/**
+ * Whether a required template input is satisfiable even though it's absent
+ * from the `{[…]}` params: present in a structured-data fence, carried as a
+ * block-level field (e.g. `title` from the heading), or derivable from the
+ * heading + body (`deriveTemplateInputs` in strict mode).
+ */
+function isInputSatisfiable(canonical: string, block: Block, key: string): boolean {
+  if (block.templateData && key in block.templateData) return true;
+  if ((block as unknown as Record<string, unknown>)[key] != null) return true;
+  const derived = deriveTemplateInputs(canonical, block.title ?? '', block.contents);
+  return derived != null && key in derived;
+}
+
 /** Numeric geometry keys carried in a shape's `{[…]}` params. */
 const NUMERIC_SHAPE_KEYS = ['x', 'y', 'width', 'height', 'w', 'h', 'strokeWidth', 'borderRadius'];
 
@@ -240,6 +313,34 @@ function checkAttributeCoercion(
   }
 }
 
+/**
+ * A heading can carry the same block-meta key in both the Pandoc `{k=v}`
+ * block and the squiggly `{[tpl k=v]}` annotation. The Pandoc value wins
+ * (same precedence as `makeBlock` in markdownToDoc), which is easy to miss
+ * when the two disagree — surface an info diagnostic so the author knows
+ * which value is in effect.
+ */
+function checkConflictingAnnotationKeys(block: Block, diagnostics: DocDiagnostic[]): void {
+  const annotationParams = block.sourceHeading?.templateAnnotation?.params;
+  const pandocParams = block.sourceHeading?.attributes?.params;
+  if (!annotationParams || !pandocParams) return;
+
+  for (const key of Object.keys(KNOWN_BLOCK_META_KEYS)) {
+    const fromAnnotation = annotationParams[key];
+    const fromPandoc = pandocParams[key];
+    if (fromAnnotation == null || fromPandoc == null || fromAnnotation === fromPandoc) continue;
+    diagnostics.push({
+      severity: 'info',
+      code: 'conflicting-annotation-key',
+      message:
+        `"${key}" is set in both {[…]} (${fromAnnotation}) and {…} (${fromPandoc}) — ` +
+        `the {…} value wins.`,
+      blockId: block.id,
+      ...lineOf(block),
+    });
+  }
+}
+
 /**
  * A drawing's `line`/`arrow` connectors reference sibling shapes by id via
  * `from`/`to`; flag any that don't resolve (mirrors the `connectsTo`
@@ -269,6 +370,40 @@ function checkDrawingConnectors(block: Block, diagnostics: DocDiagnostic[]): voi
   }
 }
 
+/**
+ * A plain ```json / ```yaml fence (no `data` marker) inside a template-
+ * annotated block, whose content parses as a top-level object, is almost
+ * certainly meant as template input — surface an info nudge to add the
+ * `data` marker. Deliberately scoped to *annotated* blocks so ordinary code
+ * samples in prose sections never trigger it.
+ */
+function checkPossibleDataFences(block: Block, diagnostics: DocDiagnostic[]): void {
+  const annotated = !!(
+    block.sourceHeading?.templateAnnotation?.template || block.sourceAnnotation?.template
+  );
+  if (!annotated) return;
+
+  for (const node of block.contents ?? []) {
+    if (node.type !== 'code') continue;
+    const lang = node.lang?.toLowerCase();
+    if (lang !== 'json' && lang !== 'yaml' && lang !== 'yml') continue;
+    if (isDataFence(node)) continue; // already a data fence — nothing to nudge
+
+    const result = parseDataFence(node);
+    if (!result.data || Object.keys(result.data).length === 0) continue;
+
+    diagnostics.push({
+      severity: 'info',
+      code: 'possible-data-fence',
+      message:
+        `This ${lang} block renders as code — add "data" to the fence ` +
+        `(\`\`\`${lang} data) if it's meant as template input.`,
+      blockId: block.id,
+      ...(node.position ? { line: node.position.start.line } : lineOf(block)),
+    });
+  }
+}
+
 // ============================================
 // Unrecognized `{[…]}` text
 // ============================================
@@ -285,7 +420,7 @@ function checkUnrecognizedAnnotations(
   markdownDoc: MarkdownDocument,
   diagnostics: DocDiagnostic[],
 ): void {
-  const walk = (node: MarkdownNode, headingLine: number | undefined): void => {
+  const walk = (node: MarkdownNode, headingLine: number | undefined, topLevel: boolean): void => {
     if (node.type === 'heading') {
       const heading = node as MarkdownHeading;
       const text = extractPlainText(heading);
@@ -301,13 +436,22 @@ function checkUnrecognizedAnnotations(
       }
       return; // heading inline children already covered by extractPlainText
     }
+    // A *top-level* paragraph that is exactly a `{[templateName …]}` /
+    // `{[audio …]}` annotation is recognized (it becomes a standalone template
+    // block or a media clip) — don't flag it, and don't descend into its text.
+    // Nested paragraphs (inside a list / blockquote) are NOT extracted, so
+    // they still warn.
+    if (node.type === 'paragraph' && topLevel) {
+      const parsed = parseStandaloneAnnotation(node);
+      if (parsed && parsed.template != null) return;
+    }
     if (node.type === 'text' && ANNOTATION_LIKE_RE.test(node.value)) {
       diagnostics.push({
         severity: 'warning',
         code: 'unparsed-annotation',
         message:
-          `Body text contains "{[…]}" — template annotations are only recognized on ` +
-          `headings (or the token is not a known inline icon)`,
+          `Body text contains "{[…]}" — template annotations are recognized on headings ` +
+          `and as standalone paragraphs (or the token is not a known inline icon)`,
         ...(node.position
           ? { line: node.position.start.line }
           : headingLine != null
@@ -318,12 +462,12 @@ function checkUnrecognizedAnnotations(
     }
     if (node.type === 'code') return; // code blocks legitimately contain {[
     for (const child of getChildren(node)) {
-      walk(child, headingLine);
+      walk(child, headingLine, false);
     }
   };
 
   for (const child of markdownDoc.children) {
-    walk(child, child.position?.start.line);
+    walk(child, child.position?.start.line, true);
   }
 }
 
@@ -417,51 +561,6 @@ function walkHtmlImages(nodes: HtmlNode[], report: (src: string) => void): void
   }
 }
 
-// ============================================
-// Did-you-mean
-// ============================================
-
-/**
- * Nearest known name by edit distance. Returns undefined when nothing is
- * plausibly close (distance > 2 and > 40% of the input length).
- */
-function nearestName(input: string, candidates: Set<string>): string | undefined {
-  let best: string | undefined;
-  let bestDist = Infinity;
-  const lower = input.toLowerCase();
-  for (const candidate of candidates) {
-    const dist = levenshtein(lower, candidate.toLowerCase());
-    if (dist < bestDist) {
-      bestDist = dist;
-      best = candidate;
-    }
-  }
-  if (best && (bestDist <= 2 || bestDist <= Math.ceil(input.length * 0.4))) {
-    return resolveTemplateName(best);
-  }
-  return undefined;
-}
-
-function levenshtein(a: string, b: string): number {
-  if (a === b) return 0;
-  const m = a.length;
-  const n = b.length;
-  if (m === 0) return n;
-  if (n === 0) return m;
-  let prev = new Array<number>(n + 1);
-  let curr = new Array<number>(n + 1);
-  for (let j = 0; j <= n; j++) prev[j] = j;
-  for (let i = 1; i <= m; i++) {
-    curr[0] = i;
-    for (let j = 1; j <= n; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
-    }
-    [prev, curr] = [curr, prev];
-  }
-  return prev[n];
-}
-
 // ============================================
 // Helpers
 // ============================================

package/src/generate/contentExtractor.ts

@@ -147,12 +147,66 @@ const QUOTE_PATTERNS = [
   /(\w+(?:\s+\w+)?)\s+(?:said|stated|wrote|noted|observed|commented),?\s*"([^"]+)"/gi,
 ];
 
+// A single side of a comparison ("X" in "from X to Y"). Deliberately excludes
+// sentence/clause terminators (. ! ? ;) and newlines so a capture group can
+// never swallow text from an adjacent sentence. Without this, greedy `.{2,30}`
+// matches across a period — e.g. "…contradicted from witness to witness.
+// Robertson said…" yields right="witness. Robertson", producing a nonsensical
+// "witness → witness. Robertson" slide. Commas and colons are allowed (ranges
+// like "9:00 to 17:00", ratios); downstream label truncation trims commas.
+const COMPARISON_SIDE = '[^.!?;\\r\\n]{2,30}';
+
 const COMPARISON_PATTERNS = [
-  /from\s+(.{2,30})\s+to\s+(.{2,30})/gi,
-  /(.{2,30})\s+(?:vs\.?|versus)\s+(.{2,30})/gi,
-  /(.{2,30})\s+compared\s+to\s+(.{2,30})/gi,
+  new RegExp(`from\\s+(${COMPARISON_SIDE})\\s+to\\s+(${COMPARISON_SIDE})`, 'gi'),
+  new RegExp(`(${COMPARISON_SIDE})\\s+(?:vs\\.?|versus)\\s+(${COMPARISON_SIDE})`, 'gi'),
+  new RegExp(`(${COMPARISON_SIDE})\\s+compared\\s+to\\s+(${COMPARISON_SIDE})`, 'gi'),
 ];
 
+// Words whose trailing period is an abbreviation, not a sentence end. Used by
+// isSentenceBoundary() so names like "George W. Tibbetts" or "Quong Chong & Co."
+// don't get split into fragments. Matched only when the entire preceding word
+// equals one of these (case-insensitive), so "canal." / "taco." are unaffected.
+const SENTENCE_ABBREVIATIONS = new Set([
+  'mr',
+  'mrs',
+  'ms',
+  'dr',
+  'prof',
+  'st',
+  'mt',
+  'jr',
+  'sr',
+  'gen',
+  'col',
+  'capt',
+  'lt',
+  'sgt',
+  'rev',
+  'hon',
+  'sen',
+  'rep',
+  'gov',
+  'pres',
+  'vs',
+  'etc',
+  'inc',
+  'co',
+  'ltd',
+  'corp',
+  'al',
+  'fig',
+  'eg',
+  'ie',
+  'approx',
+  'dept',
+  'univ',
+  'assn',
+  'bros',
+  'ave',
+  'blvd',
+  'rd',
+]);
+
 const FACT_INDICATORS = [
   'largest',
   'smallest',
@@ -427,10 +481,38 @@ function extractComparisons(text: string): ExtractedElement[] {
       if (seen.has(position)) continue;
       seen.add(position);
 
-      const left = match[1].trim();
-      const right = match[2].trim();
+      // Trim a trailing clause introduced by a comma + space ("retired
+      // airliners, arranged in rows" → "retired airliners"). A greedy side
+      // match often swallows the words after the compared thing; the comma is a
+      // clause boundary, not part of the value. Numeric grouping commas
+      // ("4,000") survive because those are comma+digit, not comma+space.
+      const trimClause = (s: string) => s.replace(/,\s+.*$/, '').trim();
+      const left = trimClause(match[1].trim());
+      const right = trimClause(match[2].trim());
       if (left.length < 2 || left.length > 30) continue;
       if (right.length < 2 || right.length > 30) continue;
+      // Reject "from X to X"-style idioms — "from witness to witness",
+      // "from day to day", "from generation to generation". These mean "it
+      // varied", not "A versus B", and render as a pointless "X → X" card.
+      // The signature is a word repeated across the connector: the last word
+      // of the left side equals the first word of the right side. (Greedy
+      // matching may append trailing context to the right side, so a whole-
+      // string equality check is not enough.)
+      const wordsOf = (s: string) =>
+        s
+          .toLowerCase()
+          .split(/\s+/)
+          .map((w) => w.replace(/[^a-z0-9]+/g, ''))
+          .filter(Boolean);
+      const leftWords = wordsOf(left);
+      const rightWords = wordsOf(right);
+      if (
+        leftWords.length > 0 &&
+        rightWords.length > 0 &&
+        leftWords[leftWords.length - 1] === rightWords[0]
+      ) {
+        continue;
+      }
 
       const context = getSentenceContext(text, position, match[0].length);
 
@@ -447,46 +529,77 @@ function extractComparisons(text: string): ExtractedElement[] {
   return elements;
 }
 
+/**
+ * Whether the `. ! ?` at `index` is a real sentence terminator rather than a
+ * period inside an abbreviation ("George W. Tibbetts", "M. DeWitt", "Mr.",
+ * "U.S."), a single-letter initial, a decimal ("3.5"), or an ellipsis. Naive
+ * splitting on every period produces broken fragments — e.g. the standalone
+ * slide "They were met at George W" from "…at George W. Tibbetts' store…".
+ * Returns false for any non-terminator character so callers can scan freely.
+ */
+function isSentenceBoundary(text: string, index: number): boolean {
+  const ch = text[index];
+  if (ch === '!' || ch === '?') return true;
+  if (ch !== '.') return false;
+
+  // Ellipsis: defer the boundary to the final dot in a run of dots.
+  if (text[index + 1] === '.') return false;
+  // Decimal number: digit "." digit → "3.5".
+  if (/[0-9]/.test(text[index - 1] ?? '') && /[0-9]/.test(text[index + 1] ?? '')) return false;
+
+  // The run of letters immediately preceding the period.
+  let w = index - 1;
+  while (w >= 0 && /[A-Za-z]/.test(text[w])) w--;
+  const word = text.slice(w + 1, index);
+  if (word.length === 1) return false; // single-letter initial: "George W."
+  if (word && SENTENCE_ABBREVIATIONS.has(word.toLowerCase())) return false;
+
+  // A genuine sentence starts with an uppercase letter, digit, or opening
+  // quote/bracket. A lowercase continuation means the period was mid-sentence
+  // (an abbreviation we didn't enumerate).
+  let j = index + 1;
+  while (j < text.length && /\s/.test(text[j])) j++;
+  if (j >= text.length) return true; // end of text
+  return !/[a-z]/.test(text[j]);
+}
+
 /**
  * Iterate over sentence-like spans in the text, yielding trimmed text and
  * accurate start/end indices within the original string.
  *
- * Sentences are approximated as runs of non-[.!?] characters optionally
- * followed by [.!?] delimiters. Leading/trailing whitespace is excluded.
+ * Boundaries are detected by isSentenceBoundary() so abbreviations, initials,
+ * decimals, and ellipses do not split a sentence. Leading whitespace and
+ * trailing whitespace/terminators are excluded from each span.
  */
 function forEachSentenceSpan(
   text: string,
   callback: (trimmed: string, start: number, end: number) => void,
 ): void {
-  const sentenceRegex = /[^.!?]+[.!?]*/g;
-  let match: RegExpExecArray | null;
-
-  while ((match = sentenceRegex.exec(text)) !== null) {
-    const raw = match[0];
-    const rawStart = match.index;
-    const rawEnd = rawStart + raw.length;
-
-    // Compute leading whitespace to exclude
-    let leading = 0;
-    while (leading < raw.length && /\s/.test(raw[leading])) {
-      leading++;
-    }
-
-    // Compute trailing whitespace or sentence-ending punctuation to exclude
-    let trailing = 0;
-    while (trailing < raw.length - leading && /[\s.!?]/.test(raw[raw.length - 1 - trailing])) {
-      trailing++;
-    }
-
-    const start = rawStart + leading;
-    const end = rawEnd - trailing;
-    if (end <= start) continue;
-
+  const emit = (rawStart: number, rawEnd: number) => {
+    let start = rawStart;
+    while (start < rawEnd && /\s/.test(text[start])) start++;
+    let end = rawEnd;
+    while (end > start && /[\s.!?]/.test(text[end - 1])) end--;
+    if (end <= start) return;
     const trimmed = text.slice(start, end);
-    if (!trimmed) continue;
+    if (trimmed) callback(trimmed, start, end);
+  };
 
-    callback(trimmed, start, end);
+  let spanStart = 0;
+  let i = 0;
+  while (i < text.length) {
+    if (isSentenceBoundary(text, i)) {
+      // Consume any consecutive terminators ("?!", "…") as one boundary.
+      let end = i + 1;
+      while (end < text.length && /[.!?]/.test(text[end])) end++;
+      emit(spanStart, end);
+      spanStart = end;
+      i = end;
+    } else {
+      i++;
+    }
   }
+  if (spanStart < text.length) emit(spanStart, text.length);
 }
 
 function extractFacts(text: string): ExtractedElement[] {
@@ -621,11 +734,11 @@ function getSentenceContext(
   matchLength: number,
 ): { sentence: string; start: number; end: number } {
   let start = matchStart;
-  while (start > 0 && !/[.!?]/.test(text[start - 1])) start--;
+  while (start > 0 && !isSentenceBoundary(text, start - 1)) start--;
   while (start < matchStart && /\s/.test(text[start])) start++;
 
   let end = matchStart + matchLength;
-  while (end < text.length && !/[.!?]/.test(text[end])) end++;
+  while (end < text.length && !isSentenceBoundary(text, end)) end++;
   if (end < text.length) end++;
 
   return { sentence: text.slice(start, end).trim(), start, end };

package/src/generate/index.ts

@@ -16,6 +16,3 @@ export type {
 
 export { mapElementToBlock } from './templateMapper.js';
 export type { MapOptions } from './templateMapper.js';
-
-export { generateSlideshow } from './slideshowGenerator.js';
-export type { SlideshowDoc, SlideshowImage, SlideshowOptions } from './slideshowGenerator.js';

package/src/jsonForm/index.ts

@@ -20,3 +20,5 @@ export { evaluateWhen, resolveFlag } from './evaluateWhen.js';
 export { toPointer, pointerSegments, getByPointer, setByPointer, resolveRef } from './pointer.js';
 export { inferSchema } from './inferSchema.js';
 export type { InferSchemaOptions } from './inferSchema.js';
+export { buildJsonFormTokens, resolveJsonFormTheme } from './tokens.js';
+export type { BuildJsonFormTokensOptions } from './tokens.js';

package/src/jsonForm/tokens.ts

@@ -0,0 +1,78 @@
+/**
+ * Pure CSS-custom-property builder shared by `<JsonView>` (read-only, in
+ * `@bendyline/squisq-react`) and `<JsonEditor>` (editable, in
+ * `@bendyline/squisq-editor-react`).
+ *
+ * Both components derive an identical token bag from a Theme + resolved
+ * Surface; they differ only in the CSS-var prefix (`--squisq-json` vs
+ * `--squisq-jsonform`) so the viewer and editor can coexist on one page.
+ * This function is the single source of that derivation. It is pure and
+ * framework-free: it performs no `window` / `matchMedia` access — the
+ * surface must already be resolved to a concrete `SurfaceScheme` (or left
+ * `undefined` to skip surface application) by the calling React hook.
+ */
+
+import { applySurface, DEFAULT_THEME, resolveFontFamily } from '../schemas/index.js';
+import type { SurfaceScheme, Theme } from '../schemas/index.js';
+
+export interface BuildJsonFormTokensOptions {
+  /**
+   * CSS-var prefix WITHOUT the trailing dash, e.g. `--squisq-json` or
+   * `--squisq-jsonform`. Each token key is `${prefix}-${name}`.
+   */
+  prefix: string;
+}
+
+/**
+ * Build the CSS custom-property map for a JSON form/view surface.
+ *
+ * @param theme   The theme to render with (falls back to `DEFAULT_THEME`).
+ * @param surface Already-resolved concrete surface, or `undefined` to leave
+ *                the theme un-surfaced. (The `'auto'` → concrete resolution
+ *                is the React hook's job, so this stays pure.)
+ * @param options `{ prefix }` — the CSS-var namespace.
+ */
+export function buildJsonFormTokens(
+  theme: Theme | undefined,
+  surface: SurfaceScheme | undefined,
+  options: BuildJsonFormTokensOptions,
+): Record<string, string> {
+  const { prefix } = options;
+  const baseTheme = theme ?? DEFAULT_THEME;
+  const finalTheme = surface ? applySurface(baseTheme, surface) : baseTheme;
+
+  const titleFont = resolveFontFamily(finalTheme.typography.titleFont, 'system-ui, sans-serif');
+  const bodyFont = resolveFontFamily(finalTheme.typography.bodyFont, 'system-ui, sans-serif');
+  const monoFont = resolveFontFamily(
+    finalTheme.typography.monoFont,
+    'ui-monospace, Consolas, monospace',
+  );
+
+  return {
+    [`${prefix}-bg`]: finalTheme.colors.background,
+    [`${prefix}-text`]: finalTheme.colors.text,
+    [`${prefix}-muted`]: finalTheme.colors.textMuted,
+    [`${prefix}-primary`]: finalTheme.colors.primary,
+    [`${prefix}-accent`]: finalTheme.colors.secondary,
+    [`${prefix}-warning`]: finalTheme.colors.warning,
+    [`${prefix}-border`]: `color-mix(in srgb, ${finalTheme.colors.textMuted} 35%, transparent)`,
+    [`${prefix}-input-bg`]: finalTheme.colors.backgroundLight,
+    [`${prefix}-title-font`]: titleFont,
+    [`${prefix}-body-font`]: bodyFont,
+    [`${prefix}-mono-font`]: monoFont,
+    [`${prefix}-radius`]: `${finalTheme.style.borderRadius ?? 8}px`,
+  };
+}
+
+/**
+ * Resolve the effective theme after surface application — the companion to
+ * `buildJsonFormTokens` for callers that also need the `Theme` object (both
+ * hooks return it alongside the style bag).
+ */
+export function resolveJsonFormTheme(
+  theme: Theme | undefined,
+  surface: SurfaceScheme | undefined,
+): Theme {
+  const baseTheme = theme ?? DEFAULT_THEME;
+  return surface ? applySurface(baseTheme, surface) : baseTheme;
+}

package/src/markdown/annotationCoercion.ts

@@ -205,7 +205,7 @@ export function coerceAnnotationValues(params: Record<string, string>): CoerceRe
 // ============================================
 
 /** Parse a finite number from a string. Returns null on failure. */
-function parseNumber(raw: string): number | null {
+export function parseNumber(raw: string): number | null {
   if (raw.trim() === '') return null;
   const n = Number(raw);
   return Number.isFinite(n) ? n : null;

package/src/markdown/attrTokens.ts

@@ -220,3 +220,22 @@ export function quoteAttrValue(value: string): string {
   }
   return `"${value.replace(DQ_ESCAPE_RE, (ch) => `\\${ch}`)}"`;
 }
+
+/**
+ * Serialize a `{[templateName key=value …]}` template annotation. The inverse
+ * of {@link parseStandaloneAnnotation} / the tokenizer: emits the template
+ * name (when present) followed by each `key=value` pair in insertion order,
+ * quoting values via {@link quoteAttrValue}. Used to re-emit heading-less
+ * standalone annotation blocks in `docToMarkdown`.
+ */
+export function serializeAnnotation(
+  template: string | undefined,
+  params?: Record<string, string>,
+): string {
+  const parts: string[] = [];
+  if (template) parts.push(template);
+  for (const [key, value] of Object.entries(params ?? {})) {
+    parts.push(`${key}=${quoteAttrValue(value)}`);
+  }
+  return `{[${parts.join(' ')}]}`;
+}