@bendyline/squisq 1.5.1 → 2.0.0

package/src/doc/materializeBlockLayers.ts

@@ -0,0 +1,304 @@
+/**
+ * Canonical block-to-layer materialization contract.
+ *
+ * Timeline scheduling and UI components both delegate here so template
+ * lookup, custom templates, ownership, render style, persistent layers,
+ * failure policy, and diagnostics cannot drift by render mode.
+ */
+
+import type { Block, Layer } from '../schemas/Doc.js';
+import type {
+  DocBlock,
+  PersistentLayerConfig,
+  TemplateBlock,
+  TemplateContext,
+} from '../schemas/BlockTemplates.js';
+import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+import type { Theme } from '../schemas/Theme.js';
+import type { ViewportConfig } from '../schemas/Viewport.js';
+import { createTemplateContext, isTemplateBlock } from '../schemas/BlockTemplates.js';
+import { DEFAULT_THEME } from '../schemas/themeLibrary.js';
+import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
+import { cloneData } from '../internal/immutable.js';
+import { applyRenderStyleToLayers } from './utils/applyRenderStyle.js';
+import { coerceTemplateParams } from './templates/inputDescriptors.js';
+import { fallbackBlockLayers } from './templates/fallbackBlock.js';
+import { expandPersistentLayers, wrapWithPersistentLayers } from './templates/persistentLayers.js';
+import { resolveTemplateName } from './templates/templateNames.js';
+import {
+  buildRegistry,
+  templateRegistry,
+  type RuntimeTemplateRegistry,
+} from './templates/registry.js';
+
+/** Internal result from executing one template function. */
+type TemplateLayerMaterialization =
+  | { status: 'ok'; layers: Layer[] }
+  | { status: 'unknown-template'; layers: [] }
+  | { status: 'invalid-result'; layers: []; receivedType: string }
+  | { status: 'error'; layers: []; error: unknown };
+
+/** How a failed template render is represented in the returned layer graph. */
+export type LayerMaterializationFailureMode = 'fallback' | 'empty';
+
+/** A structured, inspectable explanation for a template render failure. */
+export type LayerMaterializationDiagnostic =
+  | {
+      code: 'unknown-template';
+      template: string;
+      message: string;
+    }
+  | {
+      code: 'invalid-template-result';
+      template: string;
+      message: string;
+      receivedType: string;
+    }
+  | {
+      code: 'template-error';
+      template: string;
+      message: string;
+      cause: unknown;
+    };
+
+/** Identifies which path produced a materialized layer graph. */
+export type LayerMaterializationSource = 'authored' | 'template' | 'fallback' | 'empty';
+
+/**
+ * Complete result from {@link materializeBlockLayers}. Failures are data, not
+ * console side effects: callers can display, report, or ignore the diagnostic.
+ */
+export interface BlockLayerMaterialization {
+  layers: Layer[];
+  source: LayerMaterializationSource;
+  diagnostic?: LayerMaterializationDiagnostic;
+}
+
+/**
+ * The single public context for turning a block into renderable layers.
+ *
+ * Theme persistent layers are inherited by default. Pass
+ * `persistentLayers: false` to opt out, or a config to replace the theme's
+ * persistent layers wholesale.
+ */
+export interface MaterializeBlockLayersOptions {
+  /** Theme used by templates and render-style post-processing. */
+  theme?: Theme;
+  /** Target viewport. Defaults to the landscape preset. */
+  viewport?: ViewportConfig;
+  /** Theme inheritance override for persistent layers. */
+  persistentLayers?: PersistentLayerConfig | false;
+  /** Zero-based position in the flattened render sequence. */
+  blockIndex?: number;
+  /** Number of blocks in the flattened render sequence. */
+  totalBlocks?: number;
+  /** Document-scoped custom templates; built-ins win name collisions. */
+  customTemplates?: readonly CustomTemplateDefinition[];
+  /** Failed templates render a visible fallback by default. */
+  failureMode?: LayerMaterializationFailureMode;
+}
+
+/** Pre-expanded scheduling cache; not part of the public materialization API. */
+export interface ExpandedPersistentLayerSet {
+  bottomLayers: Layer[];
+  topLayers: Layer[];
+}
+
+/** Internal dependencies and compatibility switches supplied by orchestrators. */
+export interface MaterializationRuntime {
+  registry: RuntimeTemplateRegistry;
+  templateContext?: TemplateContext;
+  applyRenderStyle?: boolean;
+  expandedPersistentLayers?: ExpandedPersistentLayerSet;
+}
+
+/**
+ * Turn any doc block into an owned, render-ready layer graph.
+ *
+ * This is the only recommended public materialization entry point.
+ */
+export function materializeBlockLayers(
+  block: DocBlock,
+  options: MaterializeBlockLayersOptions = {},
+): BlockLayerMaterialization {
+  const registry =
+    options.customTemplates && options.customTemplates.length > 0
+      ? buildRegistry(options.customTemplates)
+      : (templateRegistry as unknown as RuntimeTemplateRegistry);
+  return materializeBlockLayersWithRuntime(block, options, { registry });
+}
+
+/** Internal entry point for schedulers that cache registry and persistent expansion. */
+export function materializeBlockLayersWithRuntime(
+  block: DocBlock,
+  options: MaterializeBlockLayersOptions,
+  runtime: MaterializationRuntime,
+): BlockLayerMaterialization {
+  const theme = options.theme ?? DEFAULT_THEME;
+  const viewport = options.viewport ?? VIEWPORT_PRESETS.landscape;
+  const blockIndex = options.blockIndex ?? 0;
+  const totalBlocks = options.totalBlocks ?? 1;
+  const effectivePersistentLayers =
+    options.persistentLayers === false
+      ? undefined
+      : (options.persistentLayers ?? theme.persistentLayers);
+
+  const existingLayers = (block as Block).layers;
+  if (existingLayers && existingLayers.length > 0 && !isTemplateBlock(block)) {
+    return {
+      layers: injectPersistentLayers(
+        cloneData(existingLayers),
+        block,
+        theme,
+        effectivePersistentLayers,
+        runtime.expandedPersistentLayers,
+      ),
+      source: 'authored',
+    };
+  }
+
+  if (!isTemplateBlock(block)) {
+    return {
+      layers: injectPersistentLayers(
+        [],
+        block,
+        theme,
+        effectivePersistentLayers,
+        runtime.expandedPersistentLayers,
+      ),
+      source: 'empty',
+    };
+  }
+
+  const context = runtime.templateContext
+    ? cloneData(runtime.templateContext)
+    : createTemplateContext(theme, blockIndex, totalBlocks, viewport);
+  context.block = cloneData(block as Block);
+
+  const execution = executeTemplateMaterialization(block, context, runtime.registry);
+  if (execution.status === 'ok') {
+    const styledLayers =
+      runtime.applyRenderStyle !== false
+        ? applyRenderStyleToLayers(execution.layers, block as Block, theme)
+        : execution.layers;
+    return {
+      layers: injectPersistentLayers(
+        styledLayers,
+        block,
+        theme,
+        effectivePersistentLayers,
+        runtime.expandedPersistentLayers,
+      ),
+      source: 'template',
+    };
+  }
+
+  const diagnostic = toLayerMaterializationDiagnostic(block.template, execution);
+  if ((options.failureMode ?? 'fallback') === 'empty') {
+    return {
+      layers: injectPersistentLayers(
+        [],
+        block,
+        theme,
+        effectivePersistentLayers,
+        runtime.expandedPersistentLayers,
+      ),
+      source: 'empty',
+      diagnostic,
+    };
+  }
+
+  return {
+    layers: injectPersistentLayers(
+      fallbackBlockLayers(block, context, diagnostic.message),
+      block,
+      theme,
+      effectivePersistentLayers,
+      runtime.expandedPersistentLayers,
+    ),
+    source: 'fallback',
+    diagnostic,
+  };
+}
+
+function executeTemplateMaterialization(
+  templateBlock: TemplateBlock,
+  context: TemplateContext,
+  registry: RuntimeTemplateRegistry,
+): TemplateLayerMaterialization {
+  const safeTemplateBlock = cloneData(templateBlock);
+  const safeContext = cloneData(context);
+  const maybeChildren = (safeTemplateBlock as Block).children;
+  if ((!safeContext.children || safeContext.children.length === 0) && maybeChildren?.length) {
+    safeContext.children = maybeChildren;
+  }
+
+  const templateFn = registry[resolveTemplateName(safeTemplateBlock.template)];
+  if (!templateFn) return { status: 'unknown-template', layers: [] };
+
+  const { templateData, templateOverrides } = safeTemplateBlock as Block;
+  const input =
+    templateData || templateOverrides
+      ? ({
+          ...safeTemplateBlock,
+          ...templateData,
+          ...coerceTemplateParams(safeTemplateBlock.template, templateOverrides ?? {}).input,
+        } as TemplateBlock)
+      : safeTemplateBlock;
+
+  try {
+    const renderedLayers = templateFn(input, safeContext);
+    if (!Array.isArray(renderedLayers)) {
+      return {
+        status: 'invalid-result',
+        layers: [],
+        receivedType: typeof renderedLayers,
+      };
+    }
+    return { status: 'ok', layers: cloneData(renderedLayers) };
+  } catch (error: unknown) {
+    return { status: 'error', layers: [], error };
+  }
+}
+
+function toLayerMaterializationDiagnostic(
+  template: string,
+  execution: Exclude<TemplateLayerMaterialization, { status: 'ok' }>,
+): LayerMaterializationDiagnostic {
+  if (execution.status === 'unknown-template') {
+    return {
+      code: 'unknown-template',
+      template,
+      message: `Unknown template "${template}"`,
+    };
+  }
+  if (execution.status === 'invalid-result') {
+    return {
+      code: 'invalid-template-result',
+      template,
+      receivedType: execution.receivedType,
+      message: `Template "${template}" returned ${execution.receivedType}, not a layer array`,
+    };
+  }
+  return {
+    code: 'template-error',
+    template,
+    cause: execution.error,
+    message: `Template "${template}" failed`,
+  };
+}
+
+function injectPersistentLayers(
+  layers: Layer[],
+  block: DocBlock,
+  theme: Theme,
+  persistentLayers?: PersistentLayerConfig,
+  expanded?: ExpandedPersistentLayerSet,
+): Layer[] {
+  if (!persistentLayers) return layers;
+  const bottomLayers =
+    expanded?.bottomLayers ?? expandPersistentLayers(persistentLayers.bottomLayers, theme);
+  const topLayers =
+    expanded?.topLayers ?? expandPersistentLayers(persistentLayers.topLayers, theme);
+  return wrapWithPersistentLayers(layers, block as TemplateBlock, bottomLayers, topLayers);
+}

package/src/doc/mediaAnnotations.ts

@@ -73,15 +73,21 @@ export interface MediaExtraction {
 /**
  * Walk `contents`, lifting every standalone media annotation into a
  * {@link MediaClip}. `makeId(src, index)` produces stable clip ids.
+ * When `blockId` is given, each clip records its round-trip `origin` —
+ * the owning block, its position in the ORIGINAL contents array, and
+ * the annotation paragraph's exact text — so `docToMarkdown` can
+ * re-insert it byte-stably.
  */
 export function extractMediaFromContents(
   contents: MarkdownBlockNode[] | undefined,
   makeId: (src: string, index: number) => string,
+  blockId?: string,
 ): MediaExtraction {
   const media: MediaClip[] = [];
   const documentMedia: MediaClip[] = [];
   const remaining: MarkdownBlockNode[] = [];
   let index = 0;
+  let originalIndex = 0;
 
   for (const node of contents ?? []) {
     const parsed = parseStandaloneAnnotation(node);
@@ -90,10 +96,24 @@ export function extractMediaFromContents(
       clip.id = makeId(clip.src, index++);
       const line = node.position?.start.line;
       if (line != null) clip.sourceLine = line;
+      if (blockId !== undefined) {
+        // parseStandaloneAnnotation only matches a paragraph with exactly
+        // one text child, so this read is safe when `parsed` is non-null.
+        const rawText =
+          node.type === 'paragraph' && node.children?.[0]?.type === 'text'
+            ? node.children[0].value.trim()
+            : undefined;
+        clip.origin = {
+          blockId,
+          index: originalIndex,
+          ...(rawText !== undefined ? { raw: rawText } : {}),
+        };
+      }
       (clip.anchor === 'document' ? documentMedia : media).push(clip);
     } else {
       remaining.push(node);
     }
+    originalIndex++;
   }
 
   return { media, documentMedia, remaining };

package/src/doc/resolveDocTheme.ts

@@ -3,18 +3,18 @@
  *
  * The theme analog of how `buildRegistry` resolves custom templates: pure and
  * doc-scoped, with no global state. `resolveThemeForDoc` looks up the active
- * theme id in the doc's own custom themes first, then falls back to the
- * built-in / globally-registered themes via `resolveTheme`.
+ * theme id in the doc's own custom themes first, then falls back to an
+ * optional caller-owned registry, then built-ins via `resolveTheme`.
  *
  * It accepts either a squisq `Doc` (which carries a typed `customThemes`
  * array) or anything with raw `frontmatter` — notably a `MarkdownDocument`,
  * which is the shape every export pipeline pivots through. In the latter case
  * the inline themes are decoded from the `squisq-custom-themes` frontmatter
- * payload. Either way, resolution needs no `registerTheme` call — an inline
- * custom theme ships with the doc, exactly like custom templates.
+ * payload. Inline custom themes ship with the doc, exactly like custom
+ * templates; host-level themes can be supplied through an explicit registry.
  */
 
-import type { Theme } from '../schemas/Theme.js';
+import type { Theme, ThemeRegistry } from '../schemas/Theme.js';
 import { resolveTheme } from '../schemas/themeLibrary.js';
 import { readFrontmatterThemeId } from '../markdown/utils.js';
 import { readCustomThemesFromFrontmatter } from './customThemesFrontmatter.js';
@@ -39,11 +39,12 @@ export interface ThemeResolvable {
  *   editor's theme dropdown, or an export `--theme` option). When omitted, the
  *   doc's `themeId` / frontmatter theme id is used.
  * @returns the matching inline custom theme (doc-scoped) when present, else
- *   the built-in / registered theme for that id, else the default theme.
+ *   the caller-registry or built-in theme for that id, else the default theme.
  */
 export function resolveThemeForDoc(
   doc: ThemeResolvable | null | undefined,
   explicitId?: string,
+  registry?: ThemeRegistry,
 ): Theme {
   const id = explicitId ?? doc?.themeId ?? readFrontmatterThemeId(doc?.frontmatter);
   // Prefer the already-parsed list on a squisq Doc; otherwise decode the
@@ -51,5 +52,5 @@ export function resolveThemeForDoc(
   const inline = doc?.customThemes ?? readCustomThemesFromFrontmatter(doc?.frontmatter);
   const custom = id ? inline?.find((t) => t.id === id) : undefined;
   if (custom) return custom;
-  return resolveTheme(id);
+  return resolveTheme(id, registry);
 }

package/src/doc/templateInputs.ts

@@ -18,8 +18,24 @@
  *   preview surfaces use this so a half-authored block still renders.
  */
 
-import type { MarkdownBlockNode, MarkdownList, MarkdownTable } from '../markdown/types.js';
+import type {
+  MarkdownBlockNode,
+  MarkdownCodeBlock,
+  MarkdownList,
+  MarkdownTable,
+} from '../markdown/types.js';
 import { extractPlainText } from '../markdown/utils.js';
+import { matchNumberHighlight } from '../recommend/numberHighlight.js';
+import {
+  detectAsciiDiagram,
+  isEligibleAsciiFenceLang,
+  isExplicitDiagramLang,
+} from './asciiDiagram/detect.js';
+import { asciiDiagramToTemplateData } from './asciiDiagram/mapping.js';
+import { detectAsciiTimeline, isEligibleAsciiTimelineFenceLang } from './asciiTimeline/detect.js';
+import { asciiTimelineToTemplateData } from './asciiTimeline/mapping.js';
+import { detectTree, isEligibleTreeFenceLang, isExplicitTreeLang } from './treeview/detect.js';
+import { treeToTemplateData, treeFromMarkdownList, findFirstList } from './treeview/mapping.js';
 
 /** First image discovered in a block's body, with explicit dimensions when present. */
 export interface FirstImage {
@@ -153,6 +169,125 @@ export function extractBlockquoteText(contents?: MarkdownBlockNode[]): string {
   return '';
 }
 
+function firstParagraph(
+  contents: MarkdownBlockNode[] | undefined,
+): { node: Extract<MarkdownBlockNode, { type: 'paragraph' }>; index: number } | null {
+  if (!contents) return null;
+  const index = contents.findIndex((node) => node.type === 'paragraph');
+  if (index < 0) return null;
+  return {
+    node: contents[index] as Extract<MarkdownBlockNode, { type: 'paragraph' }>,
+    index,
+  };
+}
+
+/** A leading bold number is an explicit authoring signal for the hero stat. */
+function leadingStrongStat(
+  paragraph: Extract<MarkdownBlockNode, { type: 'paragraph' }>,
+): string | null {
+  for (const child of paragraph.children) {
+    if (child.type === 'text' && child.value.trim() === '') continue;
+    if (child.type !== 'strong') return null;
+    const text = extractPlainText(child).trim();
+    // Explicit bold authoring is intentionally broader than automatic stat
+    // recommendation: a small integer such as `**42**` is a valid hero when
+    // the author chose statHighlight. Anchor at the beginning so a bold phrase
+    // like `**Revenue grew 42%**` does not become oversized wholesale.
+    const match = text.match(/^(?:[$€£¥]\s*)?[+-]?\d+(?:[.,]\d+)*(?:\s?(?:[%‰x×]|[A-Za-z]+))?/);
+    return match?.[0].trim() || null;
+  }
+  return null;
+}
+
+function removeStatPhrase(text: string, start: number, end: number): string {
+  const before = text.slice(0, start).trim();
+  let after = text.slice(end);
+  // A dash/colon visually separates inline prose, but is redundant once the
+  // stat and description render on separate lines.
+  if (!before) after = after.replace(/^\s*(?:[-–—:]\s*)?/, '');
+  else after = after.trim();
+  return [before, after].filter(Boolean).join(' ').trim();
+}
+
+function bodyWithoutParagraphStat(
+  contents: MarkdownBlockNode[] | undefined,
+  paragraphIndex: number,
+  paragraphText: string,
+  start: number,
+  end: number,
+): string {
+  if (!contents) return '';
+  return contents
+    .map((node, index) =>
+      index === paragraphIndex
+        ? removeStatPhrase(paragraphText, start, end)
+        : extractPlainText(node).trim(),
+    )
+    .filter(Boolean)
+    .join('\n')
+    .trim();
+}
+
+/**
+ * Map Markdown-authored stat content onto the template's visual roles.
+ *
+ * A leading bold metric in the body is the strongest signal (`**42%** of
+ * teams`), followed by a stat-looking heading for backward compatibility,
+ * then an unformatted metric in the first body paragraph (used by automatic
+ * templates). Generic content retains the historical heading/body mapping.
+ */
+function deriveStatHighlightInputs(
+  headingText: string,
+  contents: MarkdownBlockNode[] | undefined,
+  bodyText: string,
+): Record<string, unknown> {
+  const paragraph = firstParagraph(contents);
+  if (paragraph) {
+    const paragraphText = extractPlainText(paragraph.node).trim();
+    const strongStat = leadingStrongStat(paragraph.node);
+    if (strongStat) {
+      const start = paragraphText.indexOf(strongStat);
+      const description = bodyWithoutParagraphStat(
+        contents,
+        paragraph.index,
+        paragraphText,
+        start,
+        start + strongStat.length,
+      );
+      return {
+        stat: strongStat,
+        description: description || headingText || strongStat,
+      };
+    }
+  }
+
+  const trimmedHeading = headingText.trim();
+  const headingStat = matchNumberHighlight(trimmedHeading);
+  if (headingStat && headingStat.index === 0 && headingStat.end === trimmedHeading.length) {
+    return { stat: headingText, description: bodyText || headingText };
+  }
+
+  if (paragraph) {
+    const paragraphText = extractPlainText(paragraph.node).trim();
+    const bodyStat = matchNumberHighlight(paragraphText);
+    if (bodyStat) {
+      const description = bodyWithoutParagraphStat(
+        contents,
+        paragraph.index,
+        paragraphText,
+        bodyStat.index,
+        bodyStat.end,
+      );
+      return {
+        stat: bodyStat.value,
+        description: description || headingText || bodyStat.value,
+      };
+    }
+  }
+
+  return { stat: headingText, description: bodyText || headingText };
+}
+
 export interface DeriveTemplateInputsOptions {
   /**
    * Return visible placeholder values instead of `null` when an essential
@@ -177,7 +312,7 @@ export function deriveTemplateInputs(
 
   switch (templateName) {
     case 'statHighlight':
-      return { stat: headingText, description: bodyText || headingText };
+      return deriveStatHighlightInputs(headingText, contents, bodyText);
     case 'quote': {
       const quote = extractBlockquoteText(contents) || bodyText || headingText;
       return { quote };
@@ -234,6 +369,54 @@ export function deriveTemplateInputs(
         body: bodyText,
       };
     }
+    case 'diagram': {
+      // Nodes/edges from an ASCII-art fence in the body (the fence itself
+      // stays in `contents`, untouched, so round-trips are lossless).
+      const fences = (contents ?? []).filter((n): n is MarkdownCodeBlock => n.type === 'code');
+      const fence =
+        fences.length === 1 && isEligibleAsciiFenceLang(fences[0].lang) ? fences[0] : undefined;
+      const detection = fence
+        ? detectAsciiDiagram(fence.value, { explicit: isExplicitDiagramLang(fence.lang) })
+        : undefined;
+      if (!detection?.isDiagram || !detection.diagram) return placeholders ? {} : null;
+      const { nodes, edges } = asciiDiagramToTemplateData(detection.diagram);
+      return { nodes, edges, ...(headingText ? { title: headingText } : {}) };
+    }
+    case 'timeline': {
+      // Tracks/events from a spatial ASCII timeline fence. Calling this case
+      // already implies author/template intent, so accept the detector's
+      // explicit one-event form even when the fence itself is untagged.
+      const fences = (contents ?? []).filter((n): n is MarkdownCodeBlock => n.type === 'code');
+      const fence =
+        fences.length === 1 && isEligibleAsciiTimelineFenceLang(fences[0].lang)
+          ? fences[0]
+          : undefined;
+      const detection = fence ? detectAsciiTimeline(fence.value, { explicit: true }) : undefined;
+      if (!detection?.isTimeline || !detection.timeline) return placeholders ? {} : null;
+      const { tracks, links } = asciiTimelineToTemplateData(detection.timeline);
+      return { tracks, links, ...(headingText ? { title: headingText } : {}) };
+    }
+    case 'tree': {
+      // Items from an ASCII tree fence, or a nested markdown bullet list when
+      // the author explicitly annotates a listed body. The fence/list stays
+      // in `contents`, so round-trips are lossless.
+      const fences = (contents ?? []).filter((n): n is MarkdownCodeBlock => n.type === 'code');
+      const fence =
+        fences.length === 1 && isEligibleTreeFenceLang(fences[0].lang) ? fences[0] : undefined;
+      if (fence) {
+        const detection = detectTree(fence.value, { explicit: isExplicitTreeLang(fence.lang) });
+        if (detection.isTree && detection.tree) {
+          const { items } = treeToTemplateData(detection.tree);
+          return { items, ...(headingText ? { title: headingText } : {}) };
+        }
+      }
+      const list = findFirstList(contents);
+      if (list) {
+        const { items } = treeToTemplateData(treeFromMarkdownList(list));
+        if (items.length > 0) return { items, ...(headingText ? { title: headingText } : {}) };
+      }
+      return placeholders ? {} : null;
+    }
     default:
       return placeholders ? {} : null;
   }

package/src/doc/templates/__tests__/customTemplateRegistry.test.ts

@@ -89,9 +89,7 @@ describe('expandDocBlocks with customTemplates', () => {
     expect(expanded[0].layers![0].position.width).toBe('90%');
   });
 
-  it('falls back to a no-layer block (with a warning) when the template is unknown', () => {
-    // Suppress the expected console.warn from `expandTemplateBlock`.
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  it('returns a visible fallback and structured diagnostic when the template is unknown', () => {
     const block: Block = {
       id: 'b1',
       startTime: 0,
@@ -100,11 +98,27 @@ describe('expandDocBlocks with customTemplates', () => {
       title: 'Y',
       template: 'nonexistent',
     };
-    const expanded = expandDocBlocks([block], { customTemplates: [heroDef] });
+    const diagnostics: string[] = [];
+    const expanded = expandDocBlocks([block], {
+      customTemplates: [heroDef],
+      onDiagnostic: (diagnostic) => diagnostics.push(diagnostic.code),
+    });
+    expect(expanded[0].layers?.some((layer) => layer.id === 'fallback-notice')).toBe(true);
+    expect(diagnostics).toEqual(['unknown-template']);
+  });
+
+  it('retains an explicit empty policy for hosts that do not want fallback UI', () => {
+    const block: Block = {
+      id: 'b1',
+      startTime: 0,
+      duration: 1,
+      audioSegment: 0,
+      template: 'nonexistent',
+    };
+    const expanded = expandDocBlocks([block], {
+      customTemplates: [heroDef],
+      failureMode: 'empty',
+    });
     expect(expanded[0].layers).toBeUndefined();
-    expect(warnSpy).toHaveBeenCalled();
-    warnSpy.mockRestore();
   });
 });
-
-import { vi } from 'vitest';