@bendyline/squisq 1.5.1 → 2.0.0

package/src/__tests__/treeviewPipeline.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown, stringifyMarkdown } from '../markdown/index';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { docToMarkdown } from '../doc/docToMarkdown';
+import { materializeLayers } from './materializeTestUtils';
+import { profileBlockContents, recommendTemplatesForBlock } from '../recommend/templates';
+import type { Block, Layer } from '../schemas/Doc';
+import type { TreeTemplateItem } from '../schemas/BlockTemplates';
+
+const TREE_ART = ['src/', '├── index.ts', '├── components/', '│   └── App.tsx', '└── utils/'].join(
+  '\n',
+);
+const fenced = (art: string, lang = ''): string => '```' + lang + '\n' + art + '\n```';
+const AUTO_DOC = ['# Project', '', '## Layout', '', fenced(TREE_ART), ''].join('\n');
+
+function convert(md: string, options?: Parameters<typeof markdownToDoc>[1]) {
+  return markdownToDoc(parseMarkdown(md), { generateCoverBlock: false, ...options });
+}
+function findBlock(doc: { blocks: Block[] }, title: string): Block | undefined {
+  const walk = (blocks: Block[]): Block | undefined => {
+    for (const b of blocks) {
+      if (b.title === title) return b;
+      const inner = b.children ? walk(b.children) : undefined;
+      if (inner) return inner;
+    }
+    return undefined;
+  };
+  return walk(doc.blocks);
+}
+
+describe('auto-template conversion of tree fences', () => {
+  it('converts a heading with a lone tree fence into an ephemeral tree block', () => {
+    const block = findBlock(convert(AUTO_DOC), 'Layout');
+    expect(block?.template).toBe('tree');
+    expect(block?.autoTemplate).toBe(true);
+    const items = block?.templateData?.items as TreeTemplateItem[];
+    expect(items?.map((i) => i.label)).toEqual(['src/']);
+    expect(items?.[0].children.map((c) => c.label)).toEqual(['index.ts', 'components/', 'utils/']);
+    expect(block?.templateData?.title).toBe('Layout');
+  });
+
+  it('round-trips losslessly: fence byte-identical, no annotation injected', () => {
+    const output = stringifyMarkdown(docToMarkdown(convert(AUTO_DOC)));
+    expect(output).toContain(TREE_ART);
+    expect(output).not.toContain('{[tree');
+  });
+
+  it('respects the autoTemplates kill switch', () => {
+    expect(findBlock(convert(AUTO_DOC, { autoTemplates: false }), 'Layout')?.template).not.toBe(
+      'tree',
+    );
+  });
+
+  it('respects the frontmatter kill switch', () => {
+    const md = `---\nsquisq-auto-templates: false\n---\n\n${AUTO_DOC}`;
+    expect(findBlock(convert(md), 'Layout')?.template).not.toBe('tree');
+  });
+
+  it('does not convert a real-language fence', () => {
+    const md = ['## Layout', '', fenced(TREE_ART, 'bash'), ''].join('\n');
+    expect(findBlock(convert(md), 'Layout')?.template).not.toBe('tree');
+  });
+
+  it('does not convert when a table competes with the fence', () => {
+    const md = [
+      '## Layout',
+      '',
+      '| a | b |',
+      '|---|---|',
+      '| 1 | 2 |',
+      '',
+      fenced(TREE_ART),
+      '',
+    ].join('\n');
+    expect(findBlock(convert(md), 'Layout')?.template).not.toBe('tree');
+  });
+
+  it('does not steal a box-diagram fence (mutual exclusion)', () => {
+    const diagram = [
+      '┌────────┐',
+      '│ Alpha  │',
+      '└───┬────┘',
+      '    ▼',
+      '┌────────┐',
+      '│ Beta   │',
+      '└────────┘',
+    ].join('\n');
+    const block = findBlock(convert(['## Arch', '', fenced(diagram), ''].join('\n')), 'Arch');
+    expect(block?.template).toBe('diagram');
+  });
+});
+
+describe('explicit `tree`-tagged fence (survives flatten → round-trip)', () => {
+  // A flattened tree loses its connector lines, so an untagged fence would no
+  // longer auto-detect. The `tree` fence LANGUAGE is the durable "block tag"
+  // (it round-trips through markdown ↔ Tiptap as `class="language-tree"`),
+  // and explicit-lang detection accepts the flat art.
+  const FLAT_ART = ['README.md', 'index.ts', 'package.json'].join('\n');
+  const FLAT_DOC = ['# Project', '', '## Files', '', fenced(FLAT_ART, 'tree'), ''].join('\n');
+
+  it('a bare flat fence does NOT become a tree', () => {
+    const md = ['## Files', '', fenced(FLAT_ART), ''].join('\n');
+    expect(findBlock(convert(md), 'Files')?.template).not.toBe('tree');
+  });
+
+  it('a `tree`-tagged flat fence DOES become a tree', () => {
+    const block = findBlock(convert(FLAT_DOC), 'Files');
+    expect(block?.template).toBe('tree');
+    expect(block?.autoTemplate).toBe(true);
+    const items = block?.templateData?.items as TreeTemplateItem[];
+    expect(items?.map((i) => i.label)).toEqual(['README.md', 'index.ts', 'package.json']);
+  });
+
+  it('round-trips losslessly: fence + `tree` lang preserved, no annotation injected', () => {
+    const output = stringifyMarkdown(docToMarkdown(convert(FLAT_DOC)));
+    expect(output).toContain('```tree');
+    expect(output).toContain(FLAT_ART);
+    expect(output).not.toContain('{[tree');
+    // Re-importing the output keeps it a tree — the identity is sticky.
+    expect(findBlock(convert(output), 'Files')?.template).toBe('tree');
+  });
+
+  it('profiles a `tree`-tagged flat fence as hasTree', () => {
+    const md = parseMarkdown(fenced(FLAT_ART, 'tree'));
+    const profile = profileBlockContents(md.children as Parameters<typeof profileBlockContents>[0]);
+    expect(profile.hasTree).toBe(true);
+  });
+});
+
+describe('explicit {[tree]} annotation', () => {
+  it('derives items even with autoTemplates off', () => {
+    const md = ['## Files {[tree]}', '', fenced(TREE_ART), ''].join('\n');
+    const block = findBlock(convert(md, { autoTemplates: false }), 'Files');
+    expect(block?.template).toBe('tree');
+    expect((block?.templateData?.items as TreeTemplateItem[])?.length).toBe(1);
+  });
+
+  it('converts a nested markdown list under an explicit annotation', () => {
+    const md = ['## Files {[tree]}', '', '- src/', '  - index.ts', '  - utils/', ''].join('\n');
+    const block = findBlock(convert(md, { autoTemplates: false }), 'Files');
+    const items = block?.templateData?.items as TreeTemplateItem[];
+    expect(items?.[0].label).toBe('src/');
+    expect(items?.[0].children.map((c) => c.label)).toEqual(['index.ts', 'utils/']);
+  });
+
+  it('records a diagnostic when the body does not parse as a tree', () => {
+    const md = ['## Files {[tree]}', '', 'just prose, no hierarchy at all', ''].join('\n');
+    const doc = convert(md);
+    expect(doc.diagnostics?.some((d) => d.code === 'tree-parse')).toBe(true);
+  });
+});
+
+describe('rendering a derived tree through materializeBlockLayers', () => {
+  it('emits a single tree layer with the item hierarchy', () => {
+    const block = findBlock(convert(AUTO_DOC), 'Layout') as Block;
+    const layers = materializeLayers(block, {});
+    const treeLayer = layers.find((l: Layer) => l.type === 'tree');
+    expect(treeLayer).toBeDefined();
+    if (treeLayer?.type === 'tree') {
+      expect(treeLayer.content.items[0].label).toBe('src/');
+      expect(treeLayer.content.items[0].isDir).toBe(true);
+    }
+  });
+});
+
+describe('duration/caption hygiene', () => {
+  it('excludes the consumed tree fence from captions', () => {
+    const doc = convert(AUTO_DOC);
+    const captionText = (doc.captions?.phrases ?? []).map((p) => p.text).join(' ');
+    expect(captionText).not.toContain('├──');
+    expect(captionText).not.toContain('index.ts');
+  });
+});
+
+describe('template picker recommendation', () => {
+  it('surfaces tree for a tree-fence profile', () => {
+    const md = parseMarkdown(fenced(TREE_ART));
+    const profile = profileBlockContents(md.children as Parameters<typeof profileBlockContents>[0]);
+    expect(profile.hasTree).toBe(true);
+    const { recommended } = recommendTemplatesForBlock(profile, ['tree', 'list', 'title']);
+    expect(recommended).toContain('tree');
+  });
+});

package/src/__tests__/treeviewRender.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import {
+  parseTree,
+  renderTree,
+  treeFromTemplateData,
+  treeToTemplateData,
+  type Tree,
+} from '../doc/treeview/index.js';
+import { TREE_FIXTURES } from './fixtures/treeviewFixtures.js';
+
+function semantic(t: Tree): string[] {
+  const out: string[] = [];
+  const walk = (nodes: Tree['roots'], depth: number): void => {
+    for (const n of nodes) {
+      out.push(`${depth}:${n.label}${n.comment ? ` #${n.comment}` : ''}`);
+      walk(n.children, depth + 1);
+    }
+  };
+  walk(t.roots, 0);
+  return out;
+}
+
+describe('renderTree — output', () => {
+  it('renders a clean Unicode tree with connectors', () => {
+    const t = parseTree(['a/', '├── b', '└── c/', '    └── d'].join('\n'));
+    expect(renderTree(t)).toBe(['a/', '├── b', '└── c/', '    └── d'].join('\n'));
+  });
+
+  it('renders ASCII vocabulary for ascii-style trees', () => {
+    const t = parseTree(['a/', '|-- b', '`-- c'].join('\n'));
+    const out = renderTree(t);
+    expect(out).toContain('|-- b');
+    expect(out).toContain('`-- c');
+    expect(out).not.toMatch(/[├└│─]/u);
+  });
+
+  it('honours a style override', () => {
+    const t = parseTree(['a/', '├── b', '└── c'].join('\n'));
+    expect(renderTree(t, { style: 'ascii' })).toContain('|-- b');
+  });
+
+  it('renders trailing comments', () => {
+    const t = parseTree(['p/', '└── a.ts # note'].join('\n'));
+    expect(renderTree(t)).toContain('a.ts  # note');
+  });
+
+  it('roots carry no connector; children do', () => {
+    const t = parseTree(['root/', '└── only'].join('\n'));
+    const lines = renderTree(t).split('\n');
+    expect(lines[0]).toBe('root/');
+    expect(lines[1]).toBe('└── only');
+  });
+});
+
+describe('renderTree ↔ parseTree fixpoint', () => {
+  for (const fx of TREE_FIXTURES) {
+    it(`fixpoint + byte-idempotence: ${fx.name}`, () => {
+      const d1 = parseTree(fx.art);
+      const t1 = renderTree(d1);
+      const d2 = parseTree(t1);
+      expect(semantic(d2)).toEqual(semantic(d1));
+      const t2 = renderTree(d2);
+      const t3 = renderTree(parseTree(t2));
+      expect(t2).toBe(t1);
+      expect(t3).toBe(t1);
+    });
+  }
+
+  it('anti-churn: a structural edit only changes locally, then is stable', () => {
+    const t = parseTree(['a/', '├── b', '└── c'].join('\n'));
+    // Rename one node (structure-only edit) via the template-data round-trip.
+    const { items } = treeToTemplateData(t);
+    items[0].children[0].label = 'renamed';
+    const edited = treeFromTemplateData(items);
+    const r1 = renderTree(edited);
+    expect(r1).toContain('renamed');
+    expect(renderTree(parseTree(r1))).toBe(r1);
+  });
+});
+
+describe('templateData mapping round-trip', () => {
+  for (const fx of TREE_FIXTURES) {
+    it(`grid → items → grid preserves semantics: ${fx.name}`, () => {
+      const t = parseTree(fx.art);
+      const back = treeFromTemplateData(treeToTemplateData(t).items, { style: t.style });
+      expect(semantic(back)).toEqual(semantic(t));
+      // And renders identically.
+      expect(renderTree(back)).toBe(renderTree(t));
+    });
+  }
+});

package/src/__tests__/versions.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, beforeEach } from 'vitest';
 import { MemoryContentContainer } from '../storage/ContentContainer';
+import { scopeContainer } from '../storage/ScopedContentContainer';
 import {
   DocumentVersionManager,
   VERSIONS_PREFIX,
@@ -111,6 +112,49 @@ describe('saveVersion', () => {
     expect(result.version?.path).toBe(`${VERSIONS_PREFIX}index.20260430T152030Z.md`);
     expect(result.version?.basename).toBe('index');
     expect(await readUtf8(container, result.version!.path)).toBe('# hello');
+    expect(await readUtf8(container, '.gitignore')).toBe('.versions/\n');
+  });
+
+  it('writes the ignore rule at the root of a scoped *_files sidecar', async () => {
+    const parent = new MemoryContentContainer();
+    const sidecar = scopeContainer(parent, 'notes_files');
+    const now = new Date(Date.UTC(2026, 3, 30, 15, 20, 30));
+
+    const result = await saveVersion(sidecar, {
+      basename: 'notes',
+      content: '# hello',
+      now,
+    });
+
+    expect(result.saved).toBe(true);
+    expect(await readUtf8(parent, 'notes_files/.gitignore')).toBe('.versions/\n');
+    expect(await parent.exists(`notes_files/${result.version!.path}`)).toBe(true);
+  });
+
+  it('preserves existing .gitignore rules and does not duplicate the versions rule', async () => {
+    await container.writeDocument('# hello', 'index.md');
+    await container.writeFile(
+      '.gitignore',
+      new TextEncoder().encode('generated/\r\n'),
+      'text/plain',
+    );
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)) });
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 31)) });
+
+    expect(await readUtf8(container, '.gitignore')).toBe('generated/\r\n.versions/\r\n');
+  });
+
+  it('backfills .gitignore when an existing snapshot is unchanged', async () => {
+    await container.writeDocument('# hello', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)) });
+    await container.removeFile('.gitignore');
+
+    const result = await saveVersion(container, {
+      now: new Date(Date.UTC(2026, 3, 30, 15, 20, 31)),
+    });
+
+    expect(result.reason).toBe('unchanged');
+    expect(await readUtf8(container, '.gitignore')).toBe('.versions/\n');
   });
 
   it('returns unchanged on identical second save', async () => {

package/src/doc/applyNarrationTiming.ts

@@ -0,0 +1,244 @@
+/**
+ * Apply narration timing from a document-anchored take to a Doc's block
+ * timeline.
+ *
+ * When a doc carries a document-spanning narration clip (a preamble
+ * `{[audio src=… anchor=document]}` → `doc.documentMedia`) whose
+ * `.timing.json` sidecar has per-block ranges (v3, written by the
+ * teleprompter's aligner), the blocks are re-timed so playback and
+ * exports advance in sync with the recorded voice. Runs as step 0 of
+ * `resolveAudioMapping`, so every surface that resolves audio gets it.
+ *
+ * Precedence: author-pinned `duration=`/`startTime=` heading attrs win
+ * over narration ranges (a conflicting pin gets an `info` diagnostic);
+ * narration ranges win over per-block audio-segment mapping and
+ * reading-time estimates.
+ */
+
+import type { Block, Doc, DocDiagnostic } from '../schemas/Doc.js';
+import type { MediaClip } from '../schemas/Media.js';
+import type { ContentContainer } from '../storage/ContentContainer.js';
+import { estimateTimeFromText } from '../timing/narrationTiming.js';
+import { buildNarrationScript } from '../narration/script.js';
+import {
+  parseNarrationTimingJson,
+  type NarrationTimingBlock,
+  type NarrationTimingJsonV3,
+} from '../narration/sidecar.js';
+import { flattenRenderableBlocks, getBlockBodyText, getPinnedBlockMeta } from './markdownToDoc.js';
+import { scoreTextSimilarity } from './audioMapping.js';
+
+export interface NarrationResolution {
+  doc: Doc;
+  /** False → the doc is returned unchanged (no clip / no sidecar / no match). */
+  applied: boolean;
+  /** The narration media path, for callers that bundle assets. */
+  clipSrc?: string;
+}
+
+/** Minimum similarity for the fuzzy block-matching rung. */
+const MIN_BLOCK_SIMILARITY = 0.5;
+/** Minimum whole-script similarity for the v1 proportional fallback. */
+const MIN_V1_SCRIPT_SIMILARITY = 0.8;
+/** Pins that disagree with the narration range by more than this get a diagnostic. */
+const PIN_CONFLICT_TOLERANCE_SEC = 1;
+
+interface BlockRangeSec {
+  startSec: number;
+  endSec: number;
+}
+
+/** Spoken text of a block, mirroring the narration script builder. */
+function blockSpokenText(block: Block): string {
+  const title = block.title ? block.title.trim() : '';
+  const body = getBlockBodyText(block);
+  if (title && body) return `${title}\n${body}`;
+  return title || body;
+}
+
+/**
+ * Match sidecar block ranges to doc blocks with a deterministic ladder:
+ * exact blockId → text similarity (greedy best-first, ≥ 0.5) →
+ * in-order zip when the leftover counts agree. Unmatchable sidecar
+ * blocks are dropped.
+ */
+function matchSidecarBlocks(
+  flat: Block[],
+  timing: NarrationTimingJsonV3,
+): Map<string, BlockRangeSec> {
+  const ranges = new Map<string, BlockRangeSec>();
+  const remainingBlocks = new Set(flat.map((b) => b.id));
+  const remainingSidecar: NarrationTimingBlock[] = [];
+
+  const byId = new Map(flat.map((b) => [b.id, b]));
+  for (const entry of timing.blocks) {
+    if (entry.blockId && byId.has(entry.blockId) && remainingBlocks.has(entry.blockId)) {
+      ranges.set(entry.blockId, { startSec: entry.startSec, endSec: entry.endSec });
+      remainingBlocks.delete(entry.blockId);
+    } else {
+      remainingSidecar.push(entry);
+    }
+  }
+
+  // Fuzzy rung: greedy best pair first, each side used once.
+  if (remainingSidecar.length > 0 && remainingBlocks.size > 0) {
+    const candidates: Array<{ score: number; entry: NarrationTimingBlock; blockId: string }> = [];
+    for (const entry of remainingSidecar) {
+      const slice = timing.sourceText.slice(entry.charStart, entry.charEnd);
+      for (const block of flat) {
+        if (!remainingBlocks.has(block.id)) continue;
+        const score = scoreTextSimilarity(slice, blockSpokenText(block));
+        if (score >= MIN_BLOCK_SIMILARITY) candidates.push({ score, entry, blockId: block.id });
+      }
+    }
+    candidates.sort((a, b) => b.score - a.score || a.entry.blockIndex - b.entry.blockIndex);
+    const usedEntries = new Set<NarrationTimingBlock>();
+    for (const candidate of candidates) {
+      if (usedEntries.has(candidate.entry) || !remainingBlocks.has(candidate.blockId)) continue;
+      ranges.set(candidate.blockId, {
+        startSec: candidate.entry.startSec,
+        endSec: candidate.entry.endSec,
+      });
+      usedEntries.add(candidate.entry);
+      remainingBlocks.delete(candidate.blockId);
+    }
+    // Order rung: leftover counts equal → zip in document/sidecar order.
+    const leftoverEntries = remainingSidecar.filter((e) => !usedEntries.has(e));
+    if (leftoverEntries.length > 0 && leftoverEntries.length === remainingBlocks.size) {
+      const leftoverBlocks = flat.filter((b) => remainingBlocks.has(b.id));
+      leftoverEntries.sort((a, b) => a.blockIndex - b.blockIndex);
+      leftoverBlocks.forEach((block, i) => {
+        const entry = leftoverEntries[i];
+        ranges.set(block.id, { startSec: entry.startSec, endSec: entry.endSec });
+      });
+    }
+  }
+
+  return ranges;
+}
+
+/**
+ * v1 fallback: no block ranges in the sidecar. If the take's source
+ * text still narrates this doc (whole-script similarity ≥ 0.8), derive
+ * per-block ranges by spoken-word proportion.
+ */
+function proportionalRanges(
+  doc: Doc,
+  timing: NarrationTimingJsonV3,
+): Map<string, BlockRangeSec> | null {
+  const script = buildNarrationScript(doc);
+  if (script.blocks.length === 0) return null;
+  if (scoreTextSimilarity(script.sourceText, timing.sourceText) < MIN_V1_SCRIPT_SIMILARITY) {
+    return null;
+  }
+  const ranges = new Map<string, BlockRangeSec>();
+  const starts = script.blocks.map((range) =>
+    estimateTimeFromText(script.sourceText, range.charStart, timing.duration),
+  );
+  script.blocks.forEach((range, i) => {
+    ranges.set(range.blockId, {
+      startSec: starts[i],
+      endSec: i + 1 < starts.length ? starts[i + 1] : timing.duration,
+    });
+  });
+  return ranges;
+}
+
+interface RetimeContext {
+  clipStart: number;
+  ranges: Map<string, BlockRangeSec>;
+  diagnostics: DocDiagnostic[];
+  /** Timeline cursor (doc seconds) for unmatched blocks. */
+  cursor: number;
+}
+
+/** Recursively clone blocks, applying narration ranges to matched, unpinned blocks. */
+function retimeBlocks(blocks: Block[], ctx: RetimeContext): Block[] {
+  return blocks.map((block) => {
+    const range = ctx.ranges.get(block.id);
+    const pinned = getPinnedBlockMeta(block);
+    const next: Block = { ...block };
+
+    if (range && pinned.duration == null && pinned.startTime == null) {
+      next.startTime = ctx.clipStart + range.startSec;
+      next.duration = Math.max(0, range.endSec - range.startSec);
+      ctx.cursor = Math.max(ctx.cursor, next.startTime + next.duration);
+    } else if (range) {
+      // Author pins win; surface real disagreement as an info diagnostic.
+      const pinnedStart = pinned.startTime ?? block.startTime;
+      const pinnedDuration = pinned.duration ?? block.duration;
+      const narrStart = ctx.clipStart + range.startSec;
+      const narrDuration = Math.max(0, range.endSec - range.startSec);
+      if (
+        Math.abs(pinnedStart - narrStart) > PIN_CONFLICT_TOLERANCE_SEC ||
+        Math.abs(pinnedDuration - narrDuration) > PIN_CONFLICT_TOLERANCE_SEC
+      ) {
+        ctx.diagnostics.push({
+          severity: 'info',
+          code: 'narration-pin-conflict',
+          message:
+            `Block timing is pinned (duration=/startTime=) but the recorded narration says ` +
+            `~${narrDuration.toFixed(1)}s starting at ~${narrStart.toFixed(1)}s. The pin wins; ` +
+            `remove it to follow the narration.`,
+          blockId: block.id,
+        });
+      }
+      ctx.cursor = Math.max(ctx.cursor, pinnedStart + pinnedDuration);
+    } else {
+      // No narration range (block added after the take, or unmatched):
+      // keep its duration but place it at the running cursor so the
+      // timeline stays monotonic.
+      next.startTime = ctx.cursor;
+      ctx.cursor += next.duration;
+    }
+
+    if (block.children && block.children.length > 0) {
+      next.children = retimeBlocks(block.children, ctx);
+    }
+    return next;
+  });
+}
+
+/**
+ * Find the doc's document-anchored narration clip, load its timing
+ * sidecar, and re-time the blocks from its ranges. Pure with respect to
+ * the input doc — returns a new Doc (or the original when nothing
+ * applies).
+ */
+export async function applyNarrationTiming(
+  doc: Doc,
+  container: ContentContainer,
+): Promise<NarrationResolution> {
+  const clips: MediaClip[] = (doc.documentMedia ?? []).filter((c) => c.anchor === 'document');
+  for (const clip of clips) {
+    if (!clip.src) continue;
+    const sidecarData = await container.readFile(`${clip.src}.timing.json`);
+    if (!sidecarData) continue;
+    const timing = parseNarrationTimingJson(sidecarData);
+    if (!timing) continue;
+
+    const flat = flattenRenderableBlocks(doc.blocks);
+    const ranges =
+      timing.blocks.length > 0 ? matchSidecarBlocks(flat, timing) : proportionalRanges(doc, timing);
+    if (!ranges || ranges.size === 0) continue;
+
+    const ctx: RetimeContext = {
+      clipStart: clip.startAt,
+      ranges,
+      diagnostics: [],
+      cursor: 0,
+    };
+    const blocks = retimeBlocks(doc.blocks, ctx);
+    const duration = Math.max(clip.startAt + timing.duration, ctx.cursor);
+    const retimed: Doc = {
+      ...doc,
+      blocks,
+      duration,
+      ...(ctx.diagnostics.length > 0
+        ? { diagnostics: [...(doc.diagnostics ?? []), ...ctx.diagnostics] }
+        : {}),
+    };
+    return { doc: retimed, applied: true, clipSrc: clip.src };
+  }
+  return { doc, applied: false };
+}