@bendyline/squisq 1.5.1 → 2.0.0

package/src/doc/asciiTimeline/wrappedFlow.ts

@@ -0,0 +1,427 @@
+/**
+ * Conservative parser for two-or-more-lane flow art whose last edge wraps
+ * around the right margin. This dialect is common in AI-authored architecture
+ * notes and sequence sketches:
+ *
+ *   CLIENT                 KERNEL
+ *   ──────                 ──────
+ *   input ──► command ────► validate
+ *                            ├─ invalid → rejected ─┐
+ *   surfaced ◄─────────────────────────────────────┘
+ *
+ * It is intentionally strict. Every nonblank row must be a heading,
+ * underline, connector-only row, parenthetical continuation, or prose joined
+ * by an explicit arrow. Accepted art is converted to the ordinary timeline
+ * model, after which the canonical timeline renderer owns the authored form.
+ */
+
+import type {
+  AsciiTimeline,
+  AsciiTimelineEvent,
+  AsciiTimelineLink,
+  AsciiTimelineTrack,
+} from './types.js';
+
+interface TextSegment {
+  text: string;
+  start: number;
+  end: number;
+  trackIndex: number;
+}
+
+interface TrackBand {
+  id: string;
+  label: string;
+  row: number;
+  start: number;
+  end: number;
+}
+
+interface EventDraft {
+  id: string;
+  label: string;
+  description?: string;
+  trackIndex: number;
+  order: number;
+}
+
+interface LinkDraft {
+  source: string;
+  target: string;
+  label?: string;
+}
+
+interface PendingDescription {
+  eventId: string;
+  text: string;
+}
+
+const UNDERLINE_RE = /[─━═-]{6,}/gu;
+const FLOW_CHAR_RE = /[─━═│|►◄→←┌┐└┘├┤]/u;
+const ARROW_RE = /[►◄→←]/u;
+const LEFT_ARROW_RE = /[◄←]/u;
+const RIGHT_ARROW_RE = /[►→]/u;
+const CONNECTOR_ONLY_RE = /^[\s─━═│|►◄→←┌┐└┘├┤]+$/u;
+const HEADER_RE = /^[A-Z][A-Z0-9 _/-]*(?:\s+\([^)]*\))?$/u;
+
+/** Parse the wrapped-flow dialect, or return null without claiming the art. */
+export function parseWrappedFlowTimeline(text: string): AsciiTimeline | null {
+  const lines = text.replace(/\r\n?/g, '\n').split('\n');
+  const header = findHeader(lines);
+  if (!header || header.tracks.length < 2) return null;
+
+  const drafts: EventDraft[] = [];
+  const links: LinkDraft[] = [];
+  const usedIds = new Set<string>();
+  const lastByTrack = new Map<number, string>();
+  let pendingDescription: PendingDescription | null = null;
+  let activeBranchRoot: string | null = null;
+  let wrapSource: string | null = null;
+  let arrowCount = 0;
+  let hasLeftArrow = false;
+  let hasRightArrow = false;
+  let hasWrapTop = false;
+  let hasWrapBottom = false;
+
+  const addEvent = (segment: TextSegment): EventDraft => {
+    const label = normalizeText(segment.text);
+    const id = uniqueId(label, usedIds);
+    const draft: EventDraft = {
+      id,
+      label,
+      trackIndex: segment.trackIndex,
+      order: drafts.length,
+    };
+    drafts.push(draft);
+    return draft;
+  };
+  const addLink = (source: string | undefined, target: string | undefined, label?: string) => {
+    if (!source || !target || source === target) return;
+    if (
+      links.some((link) => link.source === source && link.target === target && link.label === label)
+    ) {
+      return;
+    }
+    links.push({ source, target, ...(label ? { label } : {}) });
+  };
+
+  for (let row = header.underlineRow + 1; row < lines.length; row++) {
+    const original = lines[row];
+    if (!original.trim()) continue;
+    if (CONNECTOR_ONLY_RE.test(original)) {
+      hasWrapTop ||= original.includes('┐');
+      hasWrapBottom ||= original.includes('┘');
+      continue;
+    }
+
+    const trimmed = original.trim();
+    if (trimmed.startsWith('(') && !ARROW_RE.test(original)) {
+      const trackIndex = trackIndexAt(header.tracks, firstContentColumn(original));
+      const eventId = lastByTrack.get(trackIndex);
+      if (!eventId) return null;
+      pendingDescription = {
+        eventId,
+        text: normalizeText(original.replace(/[│|]+\s*$/u, '')),
+      };
+      continue;
+    }
+
+    let line = original;
+    let continuationTarget: string | null = null;
+    if (pendingDescription) {
+      const firstArrow = firstArrowColumn(line);
+      if (firstArrow < 0) return null;
+      const continuation = normalizeText(Array.from(line).slice(0, firstArrow).join(''));
+      const event = drafts.find((candidate) => candidate.id === pendingDescription?.eventId);
+      if (!event) return null;
+      event.description = normalizeText(`${pendingDescription.text} ${continuation}`);
+      continuationTarget = event.id;
+      line = `${' '.repeat(firstArrow)}${Array.from(line).slice(firstArrow).join('')}`;
+      pendingDescription = null;
+    }
+
+    const segments = extractSegments(line, header.tracks);
+    if (segments.length === 0) return null;
+    if (segments.some((segment) => !/[\p{L}\p{N}]/u.test(segment.text))) return null;
+
+    const previousByTrack = new Map(lastByTrack);
+    const events = segments.map(addEvent);
+    const directions: Array<'left' | 'right' | null> = [];
+    for (let index = 0; index < segments.length - 1; index++) {
+      const between = Array.from(line)
+        .slice(segments[index].end + 1, segments[index + 1].start)
+        .join('');
+      const direction = LEFT_ARROW_RE.test(between)
+        ? 'left'
+        : RIGHT_ARROW_RE.test(between)
+          ? 'right'
+          : null;
+      directions.push(direction);
+      if (direction) arrowCount++;
+      hasLeftArrow ||= direction === 'left';
+      hasRightArrow ||= direction === 'right';
+      if (direction === 'left') addLink(events[index + 1].id, events[index].id);
+      if (direction === 'right') addLink(events[index].id, events[index + 1].id);
+    }
+
+    const leadingBranch = /^[\s│|]*[├└]/u.exec(original)?.[0] ?? '';
+    if (leadingBranch) {
+      if (!activeBranchRoot) {
+        activeBranchRoot = previousByTrack.get(events[0].trackIndex) ?? null;
+      }
+      addLink(activeBranchRoot ?? undefined, events[0].id);
+      if (leadingBranch.includes('└')) activeBranchRoot = null;
+    } else {
+      activeBranchRoot = null;
+    }
+
+    const allLeft = directions.length > 0 && directions.every((direction) => direction === 'left');
+    const ordered = allLeft ? [...events].reverse() : events;
+    const first = ordered[0];
+    if (!leadingBranch && !original.includes('┘')) {
+      addLink(previousByTrack.get(first.trackIndex), first.id);
+    }
+    if (continuationTarget) addLink(ordered[ordered.length - 1]?.id, continuationTarget);
+
+    for (const event of ordered) lastByTrack.set(event.trackIndex, event.id);
+
+    if (original.includes('┐')) {
+      hasWrapTop = true;
+      wrapSource = events[events.length - 1]?.id ?? null;
+    }
+    if (original.includes('┘')) {
+      hasWrapBottom = true;
+      const target = allLeft ? events[0]?.id : events[events.length - 1]?.id;
+      addLink(wrapSource ?? undefined, target);
+    }
+  }
+
+  if (pendingDescription || drafts.length < 6) return null;
+  if (arrowCount < 4 || !hasLeftArrow || !hasRightArrow || !hasWrapTop || !hasWrapBottom) {
+    return null;
+  }
+  if (!hasCrossTrackLink(drafts, links)) return null;
+
+  const columns = assignColumns(drafts, links);
+  const endColumn = Math.max(10, ...columns.values());
+  const tracks: AsciiTimelineTrack[] = header.tracks.map((band, trackIndex) => {
+    const trackEvents = drafts
+      .filter((event) => event.trackIndex === trackIndex)
+      .sort(
+        (left, right) =>
+          (columns.get(left.id) ?? 0) - (columns.get(right.id) ?? 0) || left.order - right.order,
+      );
+    let previousColumn = -1;
+    const events: AsciiTimelineEvent[] = trackEvents.map((event, index) => {
+      const ideal = columns.get(event.id) ?? index * 10;
+      const column = Math.max(previousColumn + 1, ideal);
+      previousColumn = column;
+      return {
+        id: event.id,
+        label: event.label,
+        ...(event.description ? { description: event.description } : {}),
+        column,
+        side: index % 2 === 0 ? 'above' : 'below',
+        marker: 'filled',
+      };
+    });
+    return {
+      id: band.id,
+      label: band.label,
+      row: band.row,
+      startColumn: 0,
+      endColumn,
+      events,
+    };
+  });
+  const width = Math.max(0, ...lines.map((line) => Array.from(line).length));
+  links.sort(
+    (left, right) =>
+      left.source.localeCompare(right.source) ||
+      left.target.localeCompare(right.target) ||
+      (left.label ?? '').localeCompare(right.label ?? ''),
+  );
+  return {
+    tracks,
+    links: links satisfies AsciiTimelineLink[],
+    width,
+    height: lines.length,
+    style: 'unicode',
+    warnings: [],
+  };
+}
+
+/** High-confidence predicate used by the editor's lossless rewrite gate. */
+export function isWrappedFlowTimelineSource(text: string): boolean {
+  return parseWrappedFlowTimeline(text) !== null;
+}
+
+function findHeader(
+  lines: readonly string[],
+): { tracks: TrackBand[]; underlineRow: number } | null {
+  for (let row = 1; row < Math.min(lines.length, 5); row++) {
+    const runs = Array.from(lines[row].matchAll(UNDERLINE_RE)).map((match) => ({
+      start: match.index,
+      end: (match.index ?? 0) + Array.from(match[0]).length - 1,
+    }));
+    if (runs.length < 2) continue;
+    const headings = splitHeader(lines[row - 1]);
+    if (
+      headings.length !== runs.length ||
+      headings.some((heading) => !HEADER_RE.test(heading.text))
+    ) {
+      continue;
+    }
+    const tracks = runs.map((run, index): TrackBand => {
+      const heading = headings[index];
+      const base = heading.text.replace(/\s+\([^)]*\)\s*$/u, '').trim();
+      return {
+        id: safeId(base),
+        label: heading.text,
+        row: row - 1,
+        start: run.start,
+        end: run.end,
+      };
+    });
+    return { tracks, underlineRow: row };
+  }
+  return null;
+}
+
+function splitHeader(line: string): Array<{ text: string; start: number; end: number }> {
+  const chars = Array.from(line);
+  const segments: Array<{ text: string; start: number; end: number }> = [];
+  let start = -1;
+  let spaces = 0;
+  for (let index = 0; index <= chars.length; index++) {
+    const char = chars[index];
+    if (char === ' ') {
+      spaces++;
+      if (start >= 0 && spaces >= 3) {
+        const end = index - spaces;
+        const text = chars
+          .slice(start, end + 1)
+          .join('')
+          .trim();
+        if (text) segments.push({ text, start, end });
+        start = -1;
+      }
+      continue;
+    }
+    spaces = 0;
+    if (char !== undefined && start < 0) start = index;
+    if (char === undefined && start >= 0) {
+      const text = chars.slice(start).join('').trim();
+      if (text) segments.push({ text, start, end: chars.length - 1 });
+    }
+  }
+  return segments;
+}
+
+function extractSegments(line: string, tracks: readonly TrackBand[]): TextSegment[] {
+  const chars = Array.from(line);
+  const segments: TextSegment[] = [];
+  let start = -1;
+  for (let index = 0; index <= chars.length; index++) {
+    const structural = index === chars.length || FLOW_CHAR_RE.test(chars[index] ?? '');
+    if (!structural && start < 0) start = index;
+    if (!structural || start < 0) continue;
+    const raw = chars.slice(start, index).join('');
+    const leading = raw.length - raw.trimStart().length;
+    const text = normalizeText(raw);
+    if (text) {
+      const segmentStart = start + leading;
+      const segmentEnd = segmentStart + Array.from(text).length - 1;
+      segments.push({
+        text,
+        start: segmentStart,
+        end: segmentEnd,
+        trackIndex: trackIndexAt(tracks, segmentStart),
+      });
+    }
+    start = -1;
+  }
+  return segments;
+}
+
+function trackIndexAt(tracks: readonly TrackBand[], column: number): number {
+  for (let index = 1; index < tracks.length; index++) {
+    if (column < tracks[index].start) return index - 1;
+  }
+  return tracks.length - 1;
+}
+
+function firstContentColumn(line: string): number {
+  const chars = Array.from(line);
+  const index = chars.findIndex((char) => /[\p{L}\p{N}(]/u.test(char));
+  return Math.max(0, index);
+}
+
+function firstArrowColumn(line: string): number {
+  return Array.from(line).findIndex((char) => ARROW_RE.test(char));
+}
+
+function normalizeText(value: string): string {
+  return value
+    .normalize('NFC')
+    .replace(/^[\s:]+|[\s:]+$/gu, '')
+    .replace(/\s+/gu, ' ')
+    .trim();
+}
+
+function safeId(value: string): string {
+  return (
+    value
+      .normalize('NFC')
+      .toLowerCase()
+      .replace(/[^a-z0-9_.~-]+/gu, '-')
+      .replace(/^-+|-+$/gu, '') || 'event'
+  );
+}
+
+function uniqueId(label: string, used: Set<string>): string {
+  const base = safeId(label);
+  if (!used.has(base)) {
+    used.add(base);
+    return base;
+  }
+  let suffix = 2;
+  while (used.has(`${base}-${suffix}`)) suffix++;
+  const id = `${base}-${suffix}`;
+  used.add(id);
+  return id;
+}
+
+function hasCrossTrackLink(events: readonly EventDraft[], links: readonly LinkDraft[]): boolean {
+  const trackById = new Map(events.map((event) => [event.id, event.trackIndex]));
+  return links.some((link) => trackById.get(link.source) !== trackById.get(link.target));
+}
+
+function assignColumns(
+  events: readonly EventDraft[],
+  links: readonly LinkDraft[],
+): Map<string, number> {
+  const outgoing = new Map<string, string[]>();
+  const indegree = new Map(events.map((event) => [event.id, 0]));
+  for (const link of links) {
+    outgoing.set(link.source, [...(outgoing.get(link.source) ?? []), link.target]);
+    indegree.set(link.target, (indegree.get(link.target) ?? 0) + 1);
+  }
+  const ranks = new Map(events.map((event) => [event.id, 0]));
+  const queue = events.filter((event) => indegree.get(event.id) === 0).map((event) => event.id);
+  let visited = 0;
+  while (queue.length > 0) {
+    const source = queue.shift() as string;
+    visited++;
+    for (const target of outgoing.get(source) ?? []) {
+      ranks.set(target, Math.max(ranks.get(target) ?? 0, (ranks.get(source) ?? 0) + 1));
+      const next = (indegree.get(target) ?? 1) - 1;
+      indegree.set(target, next);
+      if (next === 0) queue.push(target);
+    }
+  }
+  if (visited < events.length) {
+    for (const event of events) ranks.set(event.id, event.order);
+  }
+  return new Map(Array.from(ranks, ([id, rank]) => [id, rank * 10]));
+}

package/src/doc/audioMapping.ts

@@ -14,8 +14,10 @@
  */
 
 import type { Doc, Block, AudioSegment, AudioTimingData } from '../schemas/Doc.js';
+import { resolveMediaSchedule } from '../schemas/Media.js';
 import type { ContentContainer } from '../storage/ContentContainer.js';
 import { extractPlainText } from '../markdown/utils.js';
+import { applyNarrationTiming } from './applyNarrationTiming.js';
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
@@ -115,12 +117,9 @@ function flattenForAudio(blocks: Block[]): Block[] {
 /**
  * Info about a narration audio file found in the container.
  *
- * Originally limited to MP3, this now also covers WebM/MP4/Ogg/M4A
- * audio files that the browser recorder writes into `audio/`. The type
- * name is retained for backwards compatibility with the surrounding
- * matching logic; the data shape is identical regardless of codec.
+ * Covers MP3/WebM/MP4/Ogg/M4A audio files, including browser-recorder output.
  */
-interface Mp3Info {
+interface NarrationAudioInfo {
   /** Path in the container (e.g., "audio/narration-2026.webm"). */
   path: string;
   /** Filename without path (e.g., "narration-2026.webm"). */
@@ -189,10 +188,10 @@ function parseConsolidatedTiming(data: ArrayBuffer): Record<string, AudioTimingD
  * Checks for a consolidated timing.json first, then falls back to
  * per-file `.timing.json` sidecars.
  */
-async function discoverMp3s(container: ContentContainer): Promise<Mp3Info[]> {
+async function discoverNarrationAudio(container: ContentContainer): Promise<NarrationAudioInfo[]> {
   const files = await container.listFiles();
   const audioFiles = files.filter((f) => isNarrationAudioPath(f.path));
-  const results: Mp3Info[] = [];
+  const results: NarrationAudioInfo[] = [];
 
   // Try to load consolidated timing.json
   let consolidatedSections: Record<string, AudioTimingData> | null = null;
@@ -237,22 +236,22 @@ async function discoverMp3s(container: ContentContainer): Promise<Mp3Info[]> {
  */
 function resolveFromAnnotations(
   blocks: Block[],
-  mp3s: Mp3Info[],
-): Array<{ block: Block; mp3: Mp3Info }> {
-  const matches: Array<{ block: Block; mp3: Mp3Info }> = [];
+  audioFiles: NarrationAudioInfo[],
+): Array<{ block: Block; audio: NarrationAudioInfo }> {
+  const matches: Array<{ block: Block; audio: NarrationAudioInfo }> = [];
   const flat = flattenForAudio(blocks);
 
   for (const block of flat) {
     const audioRef = block.templateOverrides?.audio;
     if (!audioRef) continue;
 
-    // Find the MP3 by filename (exact or suffix match)
-    const mp3 = mp3s.find(
+    // Find the narration file by filename (exact or suffix match).
+    const audio = audioFiles.find(
       (m) => m.filename === audioRef || m.path === audioRef || m.path.endsWith(`/${audioRef}`),
     );
 
-    if (mp3) {
-      matches.push({ block, mp3 });
+    if (audio) {
+      matches.push({ block, audio });
     }
   }
 
@@ -266,27 +265,27 @@ const MIN_CONTENT_SIMILARITY = 0.35;
 const MIN_FILENAME_SIMILARITY = 0.5;
 
 /**
- * Auto-match MP3 files to blocks by content similarity.
+ * Auto-match narration files to blocks by content similarity.
  * Uses timing.json sourceText when available, falls back to filename matching.
  */
 function autoMatchBlocks(
   blocks: Block[],
-  mp3s: Mp3Info[],
-): Array<{ block: Block; mp3: Mp3Info; score: number }> {
+  audioFiles: NarrationAudioInfo[],
+): Array<{ block: Block; audio: NarrationAudioInfo; score: number }> {
   const flat = flattenForAudio(blocks);
-  if (flat.length === 0 || mp3s.length === 0) return [];
+  if (flat.length === 0 || audioFiles.length === 0) return [];
 
-  // Score all (mp3, block) pairs
+  // Score all (audio, block) pairs.
   const scoredPairs: Array<{
     block: Block;
     blockIndex: number;
-    mp3: Mp3Info;
-    mp3Index: number;
+    audio: NarrationAudioInfo;
+    audioIndex: number;
     score: number;
   }> = [];
 
-  for (let mi = 0; mi < mp3s.length; mi++) {
-    const mp3 = mp3s[mi];
+  for (let audioIndex = 0; audioIndex < audioFiles.length; audioIndex++) {
+    const audio = audioFiles[audioIndex];
 
     for (let bi = 0; bi < flat.length; bi++) {
       const block = flat[bi];
@@ -296,14 +295,14 @@ function autoMatchBlocks(
       let score = 0;
 
       // Primary: content similarity via timing.json sourceText
-      if (mp3.timing?.sourceText) {
-        score = scoreTextSimilarity(mp3.timing.sourceText, blockText);
+      if (audio.timing?.sourceText) {
+        score = scoreTextSimilarity(audio.timing.sourceText, blockText);
       }
 
       // Fallback: filename-based matching
       if (score < MIN_CONTENT_SIMILARITY && block.title) {
         const titleSlug = slugify(block.title);
-        const fileSlug = slugify(stripAudioExtension(mp3.filename));
+        const fileSlug = slugify(stripAudioExtension(audio.filename));
         // Check if the title slug appears in the filename slug
         if (fileSlug.includes(titleSlug) && titleSlug.length >= 3) {
           score = Math.max(score, MIN_FILENAME_SIMILARITY + 0.1);
@@ -311,22 +310,22 @@ function autoMatchBlocks(
       }
 
       if (score >= MIN_CONTENT_SIMILARITY) {
-        scoredPairs.push({ block, blockIndex: bi, mp3, mp3Index: mi, score });
+        scoredPairs.push({ block, blockIndex: bi, audio, audioIndex, score });
       }
     }
   }
 
-  // Greedy assignment: highest score first, each mp3 and block used at most once
+  // Greedy assignment: highest score first, each audio file and block at most once.
   scoredPairs.sort((a, b) => b.score - a.score);
   const usedBlocks = new Set<number>();
-  const usedMp3s = new Set<number>();
-  const matches: Array<{ block: Block; mp3: Mp3Info; score: number }> = [];
+  const usedAudio = new Set<number>();
+  const matches: Array<{ block: Block; audio: NarrationAudioInfo; score: number }> = [];
 
   for (const pair of scoredPairs) {
-    if (usedBlocks.has(pair.blockIndex) || usedMp3s.has(pair.mp3Index)) continue;
+    if (usedBlocks.has(pair.blockIndex) || usedAudio.has(pair.audioIndex)) continue;
     usedBlocks.add(pair.blockIndex);
-    usedMp3s.add(pair.mp3Index);
-    matches.push({ block: pair.block, mp3: pair.mp3, score: pair.score });
+    usedAudio.add(pair.audioIndex);
+    matches.push({ block: pair.block, audio: pair.audio, score: pair.score });
   }
 
   return matches;
@@ -344,22 +343,35 @@ function autoMatchBlocks(
  * assigned to the correct `audioSegment` indices.
  *
  * @param doc - The source Doc (not mutated).
- * @param container - ContentContainer with MP3 and timing files.
+ * @param container - ContentContainer with narration and timing files.
  * @returns New Doc with audio segments resolved, or original doc if no matches.
  */
 export async function resolveAudioMapping(doc: Doc, container: ContentContainer): Promise<Doc> {
-  // Discover MP3 files and their timing data
-  const mp3s = await discoverMp3s(container);
-  if (mp3s.length === 0) return doc;
+  // Step 0: a document-anchored narration take (preamble `{[audio src=…
+  // anchor=document]}` + v3 timing sidecar) re-times the block timeline
+  // to the recorded voice. See applyNarrationTiming for precedence.
+  const narration = await applyNarrationTiming(doc, container);
+  doc = narration.doc;
+
+  const audioFiles = await discoverNarrationAudio(container);
+
+  // Files already playing through the media schedule (documentMedia /
+  // block clips) must not ALSO be auto-mapped into audio.segments —
+  // that would play the narration twice.
+  const scheduledSrcs = new Set(resolveMediaSchedule(doc).map((clip) => clip.src));
+  const available = audioFiles.filter((f) => !scheduledSrcs.has(f.path));
+  if (available.length === 0) return doc;
 
   // Try annotations first
-  let matches = resolveFromAnnotations(doc.blocks, mp3s);
+  let matches = resolveFromAnnotations(doc.blocks, available);
 
-  // Fall back to auto-matching if no annotations found
-  if (matches.length === 0) {
-    matches = autoMatchBlocks(doc.blocks, mp3s).map((m) => ({
+  // Fall back to auto-matching if no annotations found. When narration
+  // timing was applied, content auto-matching is skipped — the take owns
+  // the timeline, and fuzzy matches against other files would fight it.
+  if (matches.length === 0 && !narration.applied) {
+    matches = autoMatchBlocks(doc.blocks, available).map((m) => ({
       block: m.block,
-      mp3: m.mp3,
+      audio: m.audio,
     }));
   }
 
@@ -377,11 +389,11 @@ export async function resolveAudioMapping(doc: Doc, container: ContentContainer)
   let startTime = 0;
 
   for (let i = 0; i < matches.length; i++) {
-    const { block, mp3 } = matches[i];
-    const duration = mp3.timing?.duration ?? 30; // Fallback duration if no timing
+    const { block, audio } = matches[i];
+    const duration = audio.timing?.duration ?? 30; // Fallback duration if no timing
 
     segments.push({
-      src: mp3.path,
+      src: audio.path,
       name: block.title ?? block.id,
       duration,
       startTime,
@@ -397,7 +409,9 @@ export async function resolveAudioMapping(doc: Doc, container: ContentContainer)
   return {
     ...doc,
     blocks: newBlocks,
-    duration: startTime,
+    // A narration take owns the overall duration; explicit per-block
+    // segments only ever extend it.
+    duration: narration.applied ? Math.max(doc.duration, startTime) : startTime,
     audio: { segments },
   };
 }