@bendyline/squisq 2.0.1 → 2.2.0

package/src/doc/materializeBlockLayers.ts

@@ -1,304 +0,0 @@
-/**
- * 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

@@ -1,120 +0,0 @@
-/**
- * Media-annotation extraction.
- *
- * Lifts standalone body-level media annotations — `{[audio …]}` / `{[video …]}`
- * — out of a block's markdown contents into typed {@link MediaClip}s. A block
- * can hold several clips (unlike the single heading annotation). An annotation
- * flagged `anchor=document` (or `span=document`) becomes a document-spanning
- * clip instead. The annotation grammar is the shared one used for heading
- * annotations, so quoting/escaping behave identically.
- */
-
-import { parseTimeSeconds } from '../markdown/annotationCoercion.js';
-import type { MarkdownBlockNode } from '../markdown/types.js';
-import type { MediaClip } from '../schemas/Media.js';
-import { parseStandaloneAnnotation, type ParsedAnnotation } from './standaloneAnnotation.js';
-
-/** Annotation template names that produce a timed media clip. */
-const MEDIA_TEMPLATES = new Set(['audio', 'video', 'media']);
-
-/**
- * Whether a standalone-annotation template name is a media name
- * (`audio`/`video`/`media`). The standalone template-block extractor uses
- * this to leave media annotations to {@link extractMediaFromContents}.
- */
-export function isMediaAnnotationName(name: string | undefined): boolean {
-  return name != null && MEDIA_TEMPLATES.has(name);
-}
-
-function time(raw: string | undefined): number | null {
-  if (raw == null) return null;
-  return parseTimeSeconds(raw);
-}
-
-/** Build a {@link MediaClip} from a parsed media annotation, or null if invalid. */
-function toMediaClip(parsed: ParsedAnnotation, id: string): MediaClip | null {
-  const { template, params } = parsed;
-  if (!template || !MEDIA_TEMPLATES.has(template)) return null;
-  const src = params.src;
-  if (!src) return null;
-
-  const kind: MediaClip['kind'] = template === 'video' ? 'video' : 'audio';
-  const anchor: MediaClip['anchor'] =
-    params.anchor === 'document' || params.span === 'document' ? 'document' : 'block';
-  // `startAt` is canonical; `startTime` is accepted as an alias (it is the
-  // heading-attribute spelling, so authors reach for it here too).
-  const clip: MediaClip = {
-    id,
-    src,
-    kind,
-    startAt: time(params.startAt ?? params.startTime) ?? 0,
-    anchor,
-  };
-
-  const clipStart = time(params.clipStart);
-  const clipEnd = time(params.clipEnd);
-  if (clipStart != null) clip.clipStart = clipStart;
-  if (clipEnd != null) clip.clipEnd = clipEnd;
-  // `spillover` or `spillover=true` → true; absent/`false` → omitted.
-  if (params.spillover === 'true' || params.spillover === '') clip.spillover = true;
-
-  return clip;
-}
-
-export interface MediaExtraction {
-  /** Block-anchored clips (anchor='block'). */
-  media: MediaClip[];
-  /** Document-spanning clips (anchor='document'). */
-  documentMedia: MediaClip[];
-  /** Contents with the lifted media-annotation paragraphs removed. */
-  remaining: MarkdownBlockNode[];
-}
-
-/**
- * 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);
-    const clip = parsed ? toMediaClip(parsed, '') : null;
-    if (parsed && clip) {
-      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

@@ -1,56 +0,0 @@
-/**
- * Doc-scoped theme resolution.
- *
- * 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 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. Inline custom themes ship with the doc, exactly like custom
- * templates; host-level themes can be supplied through an explicit registry.
- */
-
-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';
-
-/**
- * The minimal shape `resolveThemeForDoc` needs. Satisfied by both the squisq
- * `Doc` (typed `customThemes` + `themeId`) and a `MarkdownDocument` (raw
- * `frontmatter` carrying the encoded payload).
- */
-export interface ThemeResolvable {
-  themeId?: string;
-  customThemes?: Theme[];
-  frontmatter?: Record<string, unknown>;
-}
-
-/**
- * Resolve the Theme a document should render with.
- *
- * @param doc - the document (may carry inline custom themes plus a `themeId`
- *   / `squisq-theme` frontmatter selector).
- * @param explicitId - an id that overrides the doc's own selection (e.g. the
- *   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 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
-  // frontmatter payload (the shape exports see on a MarkdownDocument).
-  const inline = doc?.customThemes ?? readCustomThemesFromFrontmatter(doc?.frontmatter);
-  const custom = id ? inline?.find((t) => t.id === id) : undefined;
-  if (custom) return custom;
-  return resolveTheme(id, registry);
-}

package/src/doc/standaloneAnnotation.ts

@@ -1,58 +0,0 @@
-/**
- * Standalone-paragraph annotation parser.
- *
- * A paragraph whose entire trimmed text is exactly a `{[…]}` annotation
- * (nothing before or after) is a *standalone annotation*. Two features share
- * this shape:
- *
- * - **Media annotations** (`{[audio …]}` / `{[video …]}`) — lifted into typed
- *   {@link import('../schemas/Media.js').MediaClip}s by `mediaAnnotations.ts`.
- * - **Standalone template blocks** (`{[quote]}`, `{[statHighlight …]}`, …) —
- *   turned into heading-less {@link import('../schemas/Doc.js').Block}s by
- *   `annotationBlocks.ts`.
- *
- * Both call the single parser here so the annotation grammar (quoting,
- * escaping, first-token-is-template) stays identical to the heading form.
- */
-
-import {
-  matchTrailingTemplateAnnotation,
-  tokenizeAttrTokens,
-  splitKeyValueToken,
-} from '../markdown/attrTokens.js';
-import type { MarkdownBlockNode } from '../markdown/types.js';
-
-/** The template name + params parsed out of a standalone `{[…]}` paragraph. */
-export interface ParsedAnnotation {
-  /** First bare token, when the annotation leads with one (e.g. `quote`). */
-  template?: string;
-  /** Remaining `key=value` tokens, unquoted/unescaped. */
-  params: Record<string, string>;
-}
-
-/**
- * Parse a paragraph node that is *exactly* a `{[…]}` annotation (nothing
- * before or after). Returns the template + params, or null when the node
- * isn't a standalone annotation (not a paragraph, more than one child, a
- * non-text child such as a resolved inline icon, or trailing text).
- */
-export function parseStandaloneAnnotation(node: MarkdownBlockNode): ParsedAnnotation | null {
-  if (node.type !== 'paragraph') return null;
-  const children = node.children ?? [];
-  if (children.length !== 1 || children[0].type !== 'text') return null;
-  const text = children[0].value.trim();
-  const match = matchTrailingTemplateAnnotation(text);
-  // index 0 means the whole (trimmed) paragraph is the annotation.
-  if (!match || match.index !== 0) return null;
-
-  const tokens = tokenizeAttrTokens(match.inner.trim());
-  const firstIsParam = tokens.length > 0 && tokens[0].indexOf('=') > 0;
-  const template = firstIsParam || tokens.length === 0 ? undefined : tokens[0];
-  const startIdx = firstIsParam ? 0 : 1;
-  const params: Record<string, string> = {};
-  for (let i = startIdx; i < tokens.length; i++) {
-    const kv = splitKeyValueToken(tokens[i]);
-    if (kv) params[kv.key] = kv.value;
-  }
-  return { template, params };
-}