@bendyline/squisq 1.4.1 → 1.5.1

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/icons/index.ts

@@ -16,3 +16,11 @@ export {
   iconGlyph,
 } from './resolve.js';
 export type { IconSuggestion } from './resolve.js';
+export {
+  iconMarker,
+  hasIconMarker,
+  stripIconMarkers,
+  splitIconMarkers,
+  iconClass,
+} from './inlineIconMarker.js';
+export type { IconTextRun } from './inlineIconMarker.js';

package/src/icons/inlineIconMarker.ts

@@ -0,0 +1,73 @@
+/**
+ * Inline-icon markers for template text.
+ *
+ * Slide templates flatten rich markdown body content into strings before
+ * rendering. Inline icons need to survive that flattening step, so we encode
+ * them as sentinel-delimited text markers and let `TextLayer` turn them back
+ * into FontAwesome glyphs when rendering.
+ */
+
+import type { IconFamily } from './iconData.js';
+
+/**
+ * Private-Use-Area sentinel that brackets an encoded icon.
+ * Kept as an escape sequence so the source remains valid TypeScript text.
+ */
+const SENTINEL = '\uE000';
+
+/** Matches one encoded marker: `<sentinel><family>:<name><sentinel>`. */
+const MARKER_RE = new RegExp(`${SENTINEL}([a-z]+):([a-zA-Z0-9-]+)${SENTINEL}`, 'g');
+
+/** Encode a resolved icon (family + name) as an embeddable text marker. */
+export function iconMarker(family: IconFamily, name: string): string {
+  return `${SENTINEL}${family}:${name}${SENTINEL}`;
+}
+
+/** True when a string contains at least one encoded icon marker. */
+export function hasIconMarker(value: string): boolean {
+  return value.includes(SENTINEL);
+}
+
+/** Remove every icon marker, leaving a clean plain-text projection. */
+export function stripIconMarkers(value: string): string {
+  return value.replace(MARKER_RE, '');
+}
+
+/** A run of a marker-bearing string: literal text or a resolved icon. */
+export type IconTextRun =
+  | { type: 'text'; text: string }
+  | { type: 'icon'; family: IconFamily; name: string };
+
+/**
+ * Split a string into ordered text/icon runs. Text between markers is
+ * preserved verbatim, including whitespace; each marker becomes an icon run.
+ */
+export function splitIconMarkers(value: string): IconTextRun[] {
+  const runs: IconTextRun[] = [];
+  let lastIndex = 0;
+  MARKER_RE.lastIndex = 0;
+
+  let match: RegExpExecArray | null;
+  while ((match = MARKER_RE.exec(value)) !== null) {
+    if (match.index > lastIndex) {
+      runs.push({ type: 'text', text: value.slice(lastIndex, match.index) });
+    }
+    runs.push({
+      type: 'icon',
+      family: match[1] as IconFamily,
+      name: match[2],
+    });
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (lastIndex < value.length) {
+    runs.push({ type: 'text', text: value.slice(lastIndex) });
+  }
+
+  return runs;
+}
+
+/** FontAwesome CSS class for a resolved icon, e.g. `fa-solid fa-rocket`. */
+export function iconClass(family: IconFamily, name: string): string {
+  return `fa-${family} fa-${name}`;
+}

package/src/imageEdit/export.ts

@@ -15,7 +15,8 @@
 
 import type { ContentContainer } from '../storage/ContentContainer.js';
 import type { ImageEditCanvas, ImageEditDoc, ImageEditLayer } from '../schemas/ImageEditDoc.js';
-import type { Position } from '../schemas/Doc.js';
+import type { MarkerStyle, Position } from '../schemas/Doc.js';
+import { markerPath, shapePath } from '../doc/utils/shapeGeometry.js';
 
 /** Supported export formats. */
 export type ImageEditExportFormat = 'png' | 'jpeg' | 'webp';
@@ -78,7 +79,15 @@ export async function exportImageEditDoc(
 // SVG construction
 // ============================================
 
-async function buildSvgString(doc: ImageEditDoc, container: ContentContainer): Promise<string> {
+/**
+ * Build the standalone SVG string that mirrors the canvas + layers. Exposed
+ * for tests (the raster step needs a browser); shape/text/path layers don't
+ * touch `container`, only image layers do (to inline asset bytes).
+ */
+export async function buildSvgString(
+  doc: ImageEditDoc,
+  container: ContentContainer,
+): Promise<string> {
   const { width, height, background } = doc.canvas;
   const bgRect =
     background && background !== 'transparent'
@@ -145,6 +154,10 @@ async function renderLayerInner(
     return `<line x1="${x}" y1="${y}" x2="${x + w}" y2="${y + h}"${stroke}${strokeWidth}/>`;
   }
 
+  if (layer.type === 'path') {
+    return renderPathToSvg(layer, x, y, w, h);
+  }
+
   // text
   const c = layer.content;
   const style = c.style;
@@ -169,6 +182,76 @@ async function renderLayerInner(
   );
 }
 
+/**
+ * Serialize a `path` layer to SVG. Mirrors the runtime
+ * `react/src/layers/PathLayer.tsx`: when `shapeKind` is set, `d` is
+ * re-derived from the position box via `shapePath` (so named shapes scale);
+ * otherwise the stored absolute `d` is used. Start/end markers are emitted
+ * as `<marker>` defs scoped to the layer id, matching `markerPath` geometry.
+ */
+function renderPathToSvg(
+  layer: ImageEditLayer & { type: 'path' },
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): string {
+  const c = layer.content;
+  const d = c.shapeKind ? (shapePath(c.shapeKind, x, y, w, h) ?? c.d) : c.d;
+  const stroke = c.stroke ?? '#1e293b';
+  const strokeWidth = c.strokeWidth ?? 2;
+  const fill = c.fill ?? 'none';
+  const dash = c.dasharray ? ` stroke-dasharray="${escapeAttr(c.dasharray)}"` : '';
+
+  // Markers: explicit start/end win; otherwise derive from the legacy `arrow` flag.
+  const startStyle = effectiveExportMarker(c.startMarker, c.arrow, 'start');
+  const endStyle = effectiveExportMarker(c.endMarker, c.arrow, 'end');
+  const start = markerPath(startStyle, 'start');
+  const end = markerPath(endStyle, 'end');
+  const startId = `marker-start-${layer.id}`;
+  const endId = `marker-end-${layer.id}`;
+  const defs =
+    start || end
+      ? `<defs>${start ? markerDefSvg(startId, 'start', start, stroke) : ''}${
+          end ? markerDefSvg(endId, 'end', end, stroke) : ''
+        }</defs>`
+      : '';
+  const markerStart = start ? ` marker-start="url(#${startId})"` : '';
+  const markerEnd = end ? ` marker-end="url(#${endId})"` : '';
+
+  return (
+    defs +
+    `<path d="${escapeAttr(d)}" fill="${escapeAttr(fill)}"` +
+    ` stroke="${escapeAttr(stroke)}" stroke-width="${strokeWidth}"${dash}${markerStart}${markerEnd}/>`
+  );
+}
+
+function effectiveExportMarker(
+  explicit: MarkerStyle | undefined,
+  arrow: (ImageEditLayer & { type: 'path' })['content']['arrow'],
+  end: 'start' | 'end',
+): MarkerStyle {
+  if (explicit) return explicit;
+  return arrow === 'both' || arrow === end ? 'arrow' : 'none';
+}
+
+function markerDefSvg(
+  id: string,
+  dir: 'start' | 'end',
+  marker: { d: string; filled: boolean },
+  stroke: string,
+): string {
+  const refX = dir === 'end' ? 9 : 1;
+  const paint = marker.filled
+    ? `fill="${escapeAttr(stroke)}"`
+    : `fill="none" stroke="${escapeAttr(stroke)}" stroke-width="1.5"`;
+  return (
+    `<marker id="${escapeAttr(id)}" viewBox="0 0 10 10" refX="${refX}" refY="5"` +
+    ` markerWidth="4" markerHeight="4" orient="auto-start-reverse" markerUnits="strokeWidth">` +
+    `<path d="${escapeAttr(marker.d)}" ${paint}/></marker>`
+  );
+}
+
 function preserveAspectRatioFor(fit?: 'cover' | 'contain' | 'fill'): string {
   if (fit === 'cover') return 'xMidYMid slice';
   if (fit === 'fill') return 'none';

package/src/imageEdit/index.ts

@@ -66,6 +66,7 @@ export {
 // Export
 export {
   exportImageEditDoc,
+  buildSvgString,
   type ImageEditExportFormat,
   type ImageEditExportOptions,
 } from './export.js';

package/src/imageEdit/persistence.ts

@@ -59,4 +59,55 @@ function assertImageEditDoc(value: unknown, filename: string): asserts value is
   if (!Array.isArray(v.layers)) {
     throw new Error(`readImageEditDoc: ${filename} layers must be an array`);
   }
+  v.layers.forEach((layer, i) => assertLayer(layer, i, filename));
+}
+
+const VALID_LAYER_TYPES = new Set(['image', 'text', 'shape', 'path']);
+
+function assertLayer(value: unknown, index: number, filename: string): void {
+  const ctx = `${filename} layers[${index}]`;
+  if (!value || typeof value !== 'object') {
+    throw new Error(`readImageEditDoc: ${ctx} must be an object`);
+  }
+  const layer = value as Record<string, unknown>;
+
+  if (typeof layer['id'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} must have a string id`);
+  }
+  if (typeof layer['type'] !== 'string' || !VALID_LAYER_TYPES.has(layer['type'])) {
+    throw new Error(
+      `readImageEditDoc: ${ctx} type must be one of image|text|shape, got ${String(layer['type'])}`,
+    );
+  }
+
+  const pos = layer['position'];
+  if (
+    !pos ||
+    typeof pos !== 'object' ||
+    (typeof (pos as Record<string, unknown>)['x'] !== 'number' &&
+      typeof (pos as Record<string, unknown>)['x'] !== 'string') ||
+    (typeof (pos as Record<string, unknown>)['y'] !== 'number' &&
+      typeof (pos as Record<string, unknown>)['y'] !== 'string')
+  ) {
+    throw new Error(`readImageEditDoc: ${ctx} position must have numeric or string x and y`);
+  }
+
+  const content = layer['content'];
+  if (!content || typeof content !== 'object') {
+    throw new Error(`readImageEditDoc: ${ctx} content must be an object`);
+  }
+  const c = content as Record<string, unknown>;
+
+  if (layer['type'] === 'image' && typeof c['src'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} (image) content.src must be a string`);
+  }
+  if (layer['type'] === 'text' && typeof c['text'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} (text) content.text must be a string`);
+  }
+  if (layer['type'] === 'shape' && typeof c['shape'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} (shape) content.shape must be a string`);
+  }
+  if (layer['type'] === 'path' && typeof c['d'] !== 'string') {
+    throw new Error(`readImageEditDoc: ${ctx} (path) content.d must be a string`);
+  }
 }

package/src/index.ts

@@ -6,7 +6,9 @@ export * from './markdown/index.js';
 export * from './timing/index.js';
 export * from './random/index.js';
 export * from './generate/index.js';
+export * from './transform/index.js';
 export * from './versions/index.js';
 export * from './jsonForm/index.js';
 export * from './imageEdit/index.js';
+export * from './icons/index.js';
 export * from './recommend/index.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;
+}