@bendyline/squisq 2.1.0 → 2.3.0

package/src/doc/customTemplatesFrontmatter.ts

@@ -1,273 +0,0 @@
-/**
- * Frontmatter serialization for user-defined custom templates (layouts).
- *
- * Custom template definitions live in the document's YAML frontmatter
- * under the key `squisq-custom-templates`. They're stored as a single
- * **compact JSON** object keyed by template name:
- *
- * ```yaml
- * squisq-custom-templates: {"hero":{"lb":"Hero Section","ly":[{"ty":"text",…}]}}
- * ```
- *
- * Squisq's frontmatter parser is line-based; a JSON object literal
- * round-trips through it verbatim (no leading quote to strip, single
- * line), so the value is written **unquoted** and stays human-readable
- * and diffable — important for a codebase edited by people and agents.
- *
- * The JSON is kept small by:
- *   - keying definitions by `name` (drops the `name` field + array wrapper),
- *   - omitting the viewport when it's the 1920×1080 default,
- *   - renaming well-known property names to two-letter codes via
- *     {@link LONG_TO_SHORT} (e.g. `fontSize` → `fz`).
- *
- * The rename is a generic, recursive, bijective pass: **any property not
- * in the map passes through unchanged**, so the format is lossless even
- * as the Layer schema grows — new fields are simply stored under their
- * full name until (optionally) added to the map.
- *
- * Back-compat: the reader still accepts the historical base64-of-JSON
- * payload and a structured array, so older documents load unchanged.
- * The first save migrates them to the compact form.
- *
- */
-
-import type { Layer } from '../schemas/Doc.js';
-import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
-import { FRONTMATTER_CUSTOM_TEMPLATES_KEY } from '../schemas/CustomTemplates.js';
-
-const DEFAULT_VIEWPORT = { width: 1920, height: 1080 };
-
-/** Re-export for callers that need the canonical key spelling. */
-export { FRONTMATTER_CUSTOM_TEMPLATES_KEY };
-
-// ─── Compact key codec ──────────────────────────────────────────────
-
-/**
- * Long → short property-name map. Values must be unique and must not
- * collide with any real key that passes through unmapped (those are
- * 1-char — `x`/`y`/`d`/`id`/`to` — or full words; the codes here are
- * 2-letter combos, so they never clash). A field literally named like a
- * code (e.g. a real `fz` key) would be the one corruption case — none
- * exist in the schema, and the round-trip test guards against it.
- */
-const LONG_TO_SHORT: Readonly<Record<string, string>> = {
-  // definition
-  label: 'lb',
-  description: 'ds',
-  viewport: 'vp',
-  layers: 'ly',
-  name: 'nm',
-  // layer
-  type: 'ty',
-  position: 'po',
-  content: 'ct',
-  animation: 'am',
-  // position
-  width: 'wd',
-  height: 'hg',
-  anchor: 'an',
-  // text
-  text: 'tx',
-  style: 'sy',
-  fontSize: 'fz',
-  fontFamily: 'ff',
-  fontWeight: 'fw',
-  color: 'cl',
-  textAlign: 'al',
-  verticalAlign: 'vl',
-  lineHeight: 'lh',
-  shadow: 'sd',
-  background: 'bg',
-  backgroundOpacity: 'bo',
-  backgroundGradient: 'bj',
-  borderColor: 'bc',
-  borderWidth: 'bw',
-  borderStyle: 'bs',
-  padding: 'pd',
-  maxLines: 'mx',
-  // shape / path
-  shape: 'sp',
-  fill: 'fl',
-  fillOpacity: 'fo',
-  gradient: 'gr',
-  stroke: 'sk',
-  strokeWidth: 'sw',
-  borderRadius: 'br',
-  shapeKind: 'kd',
-  dasharray: 'da',
-  arrow: 'ar',
-  startMarker: 'st',
-  endMarker: 'em',
-  // image
-  src: 'sc',
-  alt: 'at',
-  fit: 'ft',
-  credit: 'cr',
-  license: 'lc',
-  // gradient
-  from: 'fr',
-  angle: 'ag',
-};
-
-const SHORT_TO_LONG: Readonly<Record<string, string>> = Object.fromEntries(
-  Object.entries(LONG_TO_SHORT).map(([long, short]) => [short, long]),
-);
-
-/** Recursively rename an object's keys via `map`, leaving unmapped keys. */
-function renameKeys(value: unknown, map: Readonly<Record<string, string>>): unknown {
-  if (Array.isArray(value)) return value.map((v) => renameKeys(v, map));
-  if (value && typeof value === 'object') {
-    const out: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      out[map[k] ?? k] = renameKeys(v, map);
-    }
-    return out;
-  }
-  return value;
-}
-
-function isDefaultViewport(v: { width: number; height: number } | undefined): boolean {
-  return !v || (v.width === DEFAULT_VIEWPORT.width && v.height === DEFAULT_VIEWPORT.height);
-}
-
-/** UTF-8 safe `atob`. */
-function base64ToUtf8(b64: string): string {
-  if (typeof globalThis.atob === 'function') {
-    const binary = globalThis.atob(b64);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-    return new TextDecoder().decode(bytes);
-  }
-  return Buffer.from(b64, 'base64').toString('utf-8');
-}
-
-// ─── Definition list read / write ───────────────────────────────────
-
-/**
- * Read the `squisq-custom-templates` frontmatter key and decode it into
- * an array of CustomTemplateDefinitions. Returns undefined when the key
- * is absent or unparseable so callers can omit the field from the Doc.
- *
- * Accepts, in order: the compact JSON object (current), a base64-JSON
- * string (legacy), and an already-structured array/object (in case a
- * richer YAML parser delivers it). Malformed payloads return undefined
- * rather than failing the whole doc load.
- */
-export function readCustomTemplatesFromFrontmatter(
-  frontmatter: Record<string, unknown> | undefined,
-): CustomTemplateDefinition[] | undefined {
-  if (!frontmatter) return undefined;
-  const candidates = normalizeCandidates(frontmatter[FRONTMATTER_CUSTOM_TEMPLATES_KEY]);
-  if (!candidates) return undefined;
-  const out: CustomTemplateDefinition[] = [];
-  for (const entry of candidates) {
-    if (!entry || typeof entry !== 'object') continue;
-    const e = entry as Record<string, unknown>;
-    if (typeof e.name !== 'string' || typeof e.label !== 'string') continue;
-    if (!Array.isArray(e.layers)) continue;
-    const def: CustomTemplateDefinition = {
-      name: e.name,
-      label: e.label,
-      viewport: readViewport(e.viewport),
-      layers: e.layers as Layer[],
-    };
-    if (typeof e.description === 'string') def.description = e.description;
-    out.push(def);
-  }
-  return out.length > 0 ? out : undefined;
-}
-
-/**
- * Encode a list of custom template definitions into the compact JSON
- * object described in the module header. Returns undefined when the
- * input list is empty so callers can leave the key off the output.
- */
-export function writeCustomTemplatesToFrontmatter(
-  templates: readonly CustomTemplateDefinition[] | undefined,
-  options?: { pretty?: boolean },
-): string | undefined {
-  if (!templates || templates.length === 0) return undefined;
-  const map: Record<string, Record<string, unknown>> = {};
-  for (const def of templates) {
-    const entry: Record<string, unknown> = { lb: def.label };
-    if (def.description) entry.ds = def.description;
-    if (!isDefaultViewport(def.viewport)) entry.vp = def.viewport;
-    entry.ly = renameKeys(def.layers, LONG_TO_SHORT);
-    map[def.name] = entry;
-  }
-  // Pretty output is multi-line, so it rides out as a YAML literal block
-  // scalar (see `formatBlockScalar` / stringify's frontmatter path) and
-  // parses back via `JSON.parse`. Default stays compact (single line) so
-  // existing docs and snapshots are byte-unchanged. The compact key codec
-  // (LONG_TO_SHORT) is applied in both modes.
-  return JSON.stringify(map, null, options?.pretty ? 2 : undefined);
-}
-
-function readViewport(raw: unknown): { width: number; height: number } {
-  if (raw && typeof raw === 'object') {
-    const v = raw as Record<string, unknown>;
-    const w = typeof v.width === 'number' ? v.width : DEFAULT_VIEWPORT.width;
-    const h = typeof v.height === 'number' ? v.height : DEFAULT_VIEWPORT.height;
-    return { width: w, height: h };
-  }
-  return DEFAULT_VIEWPORT;
-}
-
-/**
- * Expand the compact, name-keyed map into full-keyed definition objects
- * that {@link readCustomTemplatesFromFrontmatter}'s validation loop
- * understands. The `name` comes from the map key.
- */
-function expandCompactMap(map: Record<string, unknown>): unknown[] {
-  return Object.entries(map).map(([name, raw]) => {
-    const e = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;
-    const def: Record<string, unknown> = {
-      name,
-      label: e.lb,
-      viewport: e.vp ?? { ...DEFAULT_VIEWPORT },
-      layers: renameKeys(e.ly ?? [], SHORT_TO_LONG),
-    };
-    if (typeof e.ds === 'string') def.description = e.ds;
-    return def;
-  });
-}
-
-/** Turn a parsed value into a list of full-keyed definition objects. */
-function fromParsed(parsed: unknown): unknown[] | null {
-  if (Array.isArray(parsed)) return parsed; // legacy structured array
-  if (parsed && typeof parsed === 'object')
-    return expandCompactMap(parsed as Record<string, unknown>);
-  return null;
-}
-
-function tryJson(s: string): unknown | undefined {
-  try {
-    return JSON.parse(s);
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Normalize any supported payload shape into a list of full-keyed
- * definition objects. Returns null when the value is none of them.
- */
-function normalizeCandidates(raw: unknown): unknown[] | null {
-  if (raw == null) return null;
-  if (Array.isArray(raw)) return raw;
-  if (typeof raw === 'object') return expandCompactMap(raw as Record<string, unknown>);
-  if (typeof raw !== 'string') return null;
-
-  // Current format: a JSON object/array literal stored verbatim.
-  const direct = tryJson(raw.trim());
-  if (direct !== undefined) return fromParsed(direct);
-
-  // Legacy format: base64-encoded JSON.
-  try {
-    const decoded = tryJson(base64ToUtf8(raw));
-    if (decoded !== undefined) return fromParsed(decoded);
-  } catch {
-    // not valid base64 either
-  }
-  return null;
-}

package/src/doc/customThemesFrontmatter.ts

@@ -1,95 +0,0 @@
-/**
- * Frontmatter serialization for user-defined custom themes.
- *
- * The theme analog of {@link ./customTemplatesFrontmatter.ts}. Custom Theme
- * definitions live in the document's YAML frontmatter under the key
- * `squisq-custom-themes`, stored as a single **compact JSON** object keyed
- * by theme id:
- *
- * ```yaml
- * squisq-custom-themes: {"my-brand":{"schemaVersion":"1","id":"my-brand",…}}
- * ```
- *
- * Squisq's frontmatter parser is line-based; a JSON object literal
- * round-trips through it verbatim (single line, no leading quote to strip),
- * so the value is written **unquoted** and stays human-readable and diffable
- * — the same mechanism the custom-templates codec relies on.
- *
- * Only one theme is *active* per doc (selected by id via the `squisq-theme`
- * frontmatter key / `Doc.themeId`), but the payload is a keyed map — parallel
- * to custom templates — so a doc can carry a small catalog and switch between
- * them, and `resolveThemeForDoc` can resolve any of them doc-scoped.
- *
- * Malformed entries are dropped (via `validateTheme`) rather than failing the
- * whole doc load, matching the tolerant behavior of the templates reader.
- */
-
-import type { Theme } from '../schemas/Theme.js';
-import { FRONTMATTER_CUSTOM_THEMES_KEY } from '../schemas/Theme.js';
-import { validateTheme } from '../schemas/themeValidator.js';
-
-/** Re-export for callers that need the canonical key spelling. */
-export { FRONTMATTER_CUSTOM_THEMES_KEY };
-
-/**
- * Normalize the raw frontmatter value into an array of candidate objects.
- * Accepts, in order: a JSON string (current, from the line-based parser),
- * an already-parsed object map (keyed by id), and an array (in case a richer
- * YAML parser delivers one). Returns undefined when absent/unparseable.
- */
-function normalizeCandidates(raw: unknown): unknown[] | undefined {
-  if (raw === undefined || raw === null) return undefined;
-  let value: unknown = raw;
-  if (typeof value === 'string') {
-    const trimmed = value.trim();
-    if (!trimmed) return undefined;
-    try {
-      value = JSON.parse(trimmed);
-    } catch {
-      return undefined;
-    }
-  }
-  if (Array.isArray(value)) return value;
-  if (value && typeof value === 'object') {
-    return Object.values(value as Record<string, unknown>);
-  }
-  return undefined;
-}
-
-/**
- * Read the custom themes inlined into a document's frontmatter. Returns
- * undefined when the key is absent or holds no valid theme, so callers can
- * omit the field from the Doc.
- */
-export function readCustomThemesFromFrontmatter(
-  frontmatter: Record<string, unknown> | undefined,
-): Theme[] | undefined {
-  if (!frontmatter) return undefined;
-  const candidates = normalizeCandidates(frontmatter[FRONTMATTER_CUSTOM_THEMES_KEY]);
-  if (!candidates) return undefined;
-  const out: Theme[] = [];
-  for (const entry of candidates) {
-    const result = validateTheme(entry);
-    if (result.valid && result.theme) out.push(result.theme);
-  }
-  return out.length > 0 ? out : undefined;
-}
-
-/**
- * Encode a list of custom themes into the compact JSON object described in
- * the module header (keyed by theme id). Returns undefined when the input is
- * empty so callers can leave the key off the output.
- */
-export function writeCustomThemesToFrontmatter(
-  themes: readonly Theme[] | undefined,
-  options?: { pretty?: boolean },
-): string | undefined {
-  if (!themes || themes.length === 0) return undefined;
-  const map: Record<string, Theme> = {};
-  for (const theme of themes) map[theme.id] = theme;
-  // Pretty output is multi-line, so it serializes as a YAML literal block
-  // scalar (see the markdown stringify frontmatter path) and reads back via
-  // `JSON.parse`. Default stays compact (single line) so existing docs and
-  // snapshots are byte-unchanged.
-  return JSON.stringify(map, null, options?.pretty ? 2 : undefined);
-}

package/src/doc/docToMarkdown.ts

@@ -1,284 +0,0 @@
-/**
- * Doc → Markdown Conversion
- *
- * Converts a Doc with a heading-driven Block hierarchy back into a
- * MarkdownDocument. This is the reverse of markdownToDoc() and enables
- * round-tripping: edit a Doc's block tree, then serialize back to markdown.
- *
- * **Algorithm:**
- * Walk the block tree depth-first. For each block:
- * 1. If it has a `sourceHeading`, emit that heading node
- * 2. Emit all nodes in `contents`
- * 3. Recurse into `children`
- *
- * @example
- * ```ts
- * import { markdownToDoc, docToMarkdown } from '@bendyline/squisq/doc';
- * import { parseMarkdown, stringifyMarkdown } from '@bendyline/squisq/markdown';
- *
- * const md = '# Hello\n\nWorld\n';
- * const doc = markdownToDoc(parseMarkdown(md));
- * const roundTripped = stringifyMarkdown(docToMarkdown(doc));
- * ```
- */
-
-import type { Doc, Block } from '../schemas/Doc.js';
-import type { MediaClip } from '../schemas/Media.js';
-import type {
-  MarkdownDocument,
-  MarkdownBlockNode,
-  MarkdownHeading,
-  MarkdownParagraph,
-} from '../markdown/types.js';
-import { serializeAnnotation } from '../markdown/attrTokens.js';
-import { flattenBlocks } from './markdownToDoc.js';
-import {
-  FRONTMATTER_CUSTOM_TEMPLATES_KEY,
-  writeCustomTemplatesToFrontmatter,
-} from './customTemplatesFrontmatter.js';
-import {
-  FRONTMATTER_CUSTOM_THEMES_KEY,
-  writeCustomThemesToFrontmatter,
-} from './customThemesFrontmatter.js';
-
-const TRANSITION_PARAM_KEYS = ['transition', 'transitionDuration', 'transitionDirection'] as const;
-
-/**
- * Convert a Doc with heading-driven blocks back to a MarkdownDocument.
- *
- * Walks the block tree depth-first, emitting heading nodes and contents
- * in document order. Blocks without a `sourceHeading` (preamble blocks)
- * emit only their contents.
- *
- * If a block has a `template` or `templateOverrides` that aren't already
- * reflected in the heading's `templateAnnotation`, the annotation is
- * injected so the round-trip preserves template assignments.
- *
- * @param doc - A Doc whose blocks may have `sourceHeading`, `contents`, and `children`
- * @returns A MarkdownDocument that can be stringified back to markdown
- */
-export function docToMarkdown(doc: Doc): MarkdownDocument {
-  const children: MarkdownBlockNode[] = [];
-
-  // Media clips were LIFTED out of block contents at parse time
-  // (`extractMediaFromContents`); re-insert their authoring annotations so
-  // the round-trip doesn't silently drop narration/clip references.
-  // Doc-anchored clips whose home block still exists ride back into that
-  // block's body; homeless ones (programmatic clips, or a preamble block
-  // that was dropped once emptied) emit at the document top — the
-  // canonical authored position.
-  const blockIds = new Set(flattenBlocks(doc.blocks).map((b) => b.id));
-  const docMediaByBlock = new Map<string, MediaClip[]>();
-  const homelessDocMedia: MediaClip[] = [];
-  for (const clip of doc.documentMedia ?? []) {
-    if (clip.origin && blockIds.has(clip.origin.blockId)) {
-      const list = docMediaByBlock.get(clip.origin.blockId) ?? [];
-      list.push(clip);
-      docMediaByBlock.set(clip.origin.blockId, list);
-    } else {
-      homelessDocMedia.push(clip);
-    }
-  }
-  for (const clip of homelessDocMedia) {
-    children.push(synthesizeMediaParagraph(clip));
-  }
-
-  function emitBlock(block: Block): void {
-    // Emit the heading node if present
-    if (block.sourceHeading) {
-      const heading = ensureAnnotation(block, block.sourceHeading);
-      children.push(heading);
-    } else if (block.standaloneAnnotation) {
-      // Heading-less standalone block: re-emit its `{[…]}` annotation as a
-      // paragraph before its contents. The serializer's quoting is paired
-      // with the tokenizer, and stringifyMarkdown un-escapes `{[…]}` spans,
-      // so the annotation round-trips.
-      children.push(synthesizeAnnotationParagraph(block));
-    }
-
-    // Emit body content, with this block's media annotations re-inserted
-    // at their original positions. `origin.index` refers to the ORIGINAL
-    // contents array (which included every annotation), so ascending
-    // insertion into the stripped contents reproduces the source order.
-    const clips = [...(block.media ?? []), ...(docMediaByBlock.get(block.id) ?? [])];
-    if (clips.length > 0) {
-      const contents = [...(block.contents ?? [])];
-      const anchored = clips
-        .filter((clip) => clip.origin)
-        .sort((a, b) => a.origin!.index - b.origin!.index);
-      for (const clip of anchored) {
-        contents.splice(
-          Math.min(clip.origin!.index, contents.length),
-          0,
-          synthesizeMediaParagraph(clip),
-        );
-      }
-      // Origin-less block clips (programmatic) sit right under the heading.
-      for (const clip of clips.filter((c) => !c.origin).reverse()) {
-        contents.unshift(synthesizeMediaParagraph(clip));
-      }
-      children.push(...contents);
-    } else if (block.contents) {
-      children.push(...block.contents);
-    }
-
-    // Recurse into children (sub-headings)
-    if (block.children) {
-      for (const child of block.children) {
-        emitBlock(child);
-      }
-    }
-  }
-
-  for (const block of doc.blocks) {
-    emitBlock(block);
-  }
-
-  // Merge `Doc.customTemplates` into the outgoing frontmatter so the
-  // markdown remains the source-of-truth: edits made via the editor's
-  // TemplateDesigner round-trip through `docToMarkdown` →
-  // `stringifyMarkdown` and are visible to anyone reading the file.
-  const customPayload = writeCustomTemplatesToFrontmatter(doc.customTemplates);
-  let frontmatter = doc.frontmatter;
-  if (customPayload) {
-    frontmatter = { ...(frontmatter ?? {}), [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: customPayload };
-  } else if (frontmatter && FRONTMATTER_CUSTOM_TEMPLATES_KEY in frontmatter) {
-    // The doc has no custom templates anymore — drop the stale
-    // frontmatter key so the markdown reflects the current state.
-    const { [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: _drop, ...rest } = frontmatter;
-    void _drop;
-    frontmatter = rest;
-  }
-
-  // Mirror the same round-trip for `Doc.customThemes` (the theme analog).
-  const customThemesPayload = writeCustomThemesToFrontmatter(doc.customThemes);
-  if (customThemesPayload) {
-    frontmatter = { ...(frontmatter ?? {}), [FRONTMATTER_CUSTOM_THEMES_KEY]: customThemesPayload };
-  } else if (frontmatter && FRONTMATTER_CUSTOM_THEMES_KEY in frontmatter) {
-    const { [FRONTMATTER_CUSTOM_THEMES_KEY]: _dropTheme, ...rest } = frontmatter;
-    void _dropTheme;
-    frontmatter = rest;
-  }
-
-  return {
-    type: 'document',
-    children,
-    ...(frontmatter && Object.keys(frontmatter).length > 0 ? { frontmatter } : {}),
-  };
-}
-
-/**
- * Build the synthesized annotation paragraph for a heading-less standalone
- * block: `{[templateName key=value …]}` from its `sourceAnnotation.template`
- * and current `templateOverrides` (edits round-trip through the latter).
- */
-function synthesizeAnnotationParagraph(block: Block): MarkdownParagraph {
-  const text = serializeAnnotation(block.sourceAnnotation?.template, block.templateOverrides);
-  return { type: 'paragraph', children: [{ type: 'text', value: text }] };
-}
-
-/**
- * Re-synthesize the authoring paragraph for a media clip. The extraction
- * kept the exact source text (`origin.raw`) — emit it verbatim so quoting,
- * param order, and `mm:ss` time forms stay byte-stable. Programmatic clips
- * (no raw) serialize canonically: src, anchor, then timing params.
- */
-function synthesizeMediaParagraph(clip: MediaClip): MarkdownParagraph {
-  if (clip.origin?.raw) {
-    return { type: 'paragraph', children: [{ type: 'text', value: clip.origin.raw }] };
-  }
-  const params: Record<string, string> = { src: clip.src };
-  if (clip.anchor === 'document') params.anchor = 'document';
-  if (clip.startAt) params.startAt = String(clip.startAt);
-  if (clip.clipStart != null) params.clipStart = String(clip.clipStart);
-  if (clip.clipEnd != null) params.clipEnd = String(clip.clipEnd);
-  if (clip.spillover) params.spillover = 'true';
-  return {
-    type: 'paragraph',
-    children: [{ type: 'text', value: serializeAnnotation(clip.kind, params) }],
-  };
-}
-
-/**
- * Ensure the heading's `templateAnnotation` reflects the block's
- * template and templateOverrides. Returns a (possibly cloned) heading.
- */
-function ensureAnnotation(block: Block, heading: MarkdownHeading): MarkdownHeading {
-  const { attributes, transitionParams } = ensureTransitionMetadata(block, heading);
-
-  // If the block has a non-default template or overrides, inject an annotation
-  const hasExplicitTemplate =
-    block.template && block.template !== 'sectionHeader' && block.autoTemplate !== true;
-  const hasOverrides = block.templateOverrides && Object.keys(block.templateOverrides).length > 0;
-
-  let templateAnnotation = heading.templateAnnotation;
-  if (!templateAnnotation && (hasExplicitTemplate || hasOverrides || transitionParams)) {
-    templateAnnotation = {
-      ...(hasExplicitTemplate ? { template: block.template ?? 'sectionHeader' } : {}),
-      ...(hasOverrides ? { params: block.templateOverrides } : {}),
-    };
-  }
-
-  if (transitionParams) {
-    templateAnnotation = {
-      ...(templateAnnotation ?? {}),
-      params: {
-        ...(templateAnnotation?.params ?? {}),
-        ...transitionParams,
-      },
-    };
-  }
-
-  if (attributes === heading.attributes && templateAnnotation === heading.templateAnnotation) {
-    return heading;
-  }
-
-  return { ...heading, children: [...heading.children], attributes, templateAnnotation };
-}
-
-function ensureTransitionMetadata(
-  block: Block,
-  heading: MarkdownHeading,
-): {
-  attributes: MarkdownHeading['attributes'];
-  transitionParams: Record<string, string> | undefined;
-} {
-  const transition = block.transition;
-  if (!transition) {
-    return { attributes: heading.attributes, transitionParams: undefined };
-  }
-
-  // The transition is written to the squisq-native `{[…]}` params for
-  // author-facing markdown, and to `attributes.blockMeta` for the in-memory
-  // Doc → MarkdownDocument → Doc path (which does not re-parse string params).
-  const attrs = removeTransitionParams(heading.attributes) ?? {};
-  const attributes = {
-    ...attrs,
-    blockMeta: {
-      ...(attrs.blockMeta ?? {}),
-      transition,
-    },
-  };
-  return {
-    attributes,
-    transitionParams: {
-      transition: transition.type,
-      ...(transition.duration !== undefined
-        ? { transitionDuration: String(transition.duration) }
-        : {}),
-      ...(transition.direction ? { transitionDirection: transition.direction } : {}),
-    },
-  };
-}
-
-function removeTransitionParams(
-  attrs: MarkdownHeading['attributes'],
-): MarkdownHeading['attributes'] {
-  if (!attrs?.params) return attrs;
-  const params = { ...attrs.params };
-  for (const key of TRANSITION_PARAM_KEYS) delete params[key];
-  return {
-    ...attrs,
-    ...(Object.keys(params).length > 0 ? { params } : { params: undefined }),
-  };
-}