@speclip/pi-talking-head 0.1.3 → 0.1.5

package/README.md

@@ -71,9 +71,55 @@ talking_head_get {
 
 只有调用这个工具时才会把这些证据放进当前会话上下文；安装 package 不会把整份转录常驻注入上下文。
 
-### 3. 文件名优先筛选 B-roll
+### 3. 先规划 B-roll 视觉连续性
 
-先为已经稳定的 A-roll 片段建立一个结构化需求，再扫描指定素材目录：
+在查找素材前，把最终 A-roll 和所有 B-roll 需求交给连续性规划工具：
+
+```js
+talking_head_broll_plan {
+  projectId: "launch-video",
+  aroll: [
+    { id: "hook", sourceStartMs: 50, sourceEndMs: 4120 },
+    { id: "answer", sourceStartMs: 4860, sourceEndMs: 13200 }
+  ],
+  needs: [
+    {
+      id: "product-a",
+      outputStartMs: 1000,
+      outputEndMs: 3000,
+      speechText: "第一步打开设置",
+      purpose: "demonstrate",
+      searchTerms: ["设置", "打开"],
+      reason: "展示第一步"
+    },
+    {
+      id: "product-b",
+      outputStartMs: 3300,
+      outputEndMs: 5200,
+      speechText: "第二步选择设备",
+      purpose: "demonstrate",
+      searchTerms: ["设备", "选择"],
+      reason: "展示第二步"
+    }
+  ],
+  cutCoverBeforeMs: 250,
+  cutCoverAfterMs: 500
+}
+```
+
+规划结果同时返回 `plan.coverage` 和 `continuityPlanReceipt`。`plan.coverage` 会列出 B-roll/A-roll 时长、B-roll 占比和最长连续 B-roll；凭证则把当前项目 revision、A-roll、规划后的 B-roll 区间和跳点审阅结果绑定在一起。后续 `talking_head_apply` 会重新计算并核对，不能跳过规划或把已经衔接的区间手动缩短。
+
+规划结果处理两类问题：
+
+- **B-roll 闪屏**：两个 B-roll 之间只露出不超过 500ms 的 A-roll 时，`plan.needs` 会把前一个需求延长到后一个需求的起点。后续分别选段后，两段 B-roll 会直接交接，不再闪回 A-roll。
+- **气口剪辑跳转**：A-roll 相邻片段的源时间不连续时，会生成 `jumpCuts`。工具检查建议遮盖区间是否已被 B-roll 连续覆盖；未覆盖项标为 `needs-broll`，Agent 应结合口播语义补充 `purpose: "mask-cut"` 的需求，再重新规划。
+- **A-roll 出镜预算**：B-roll 总覆盖最多占成片 50%，单次连续覆盖最多 8000ms。规划和最终应用都会独立校验；超限时应删除或缩短低价值需求，而不是继续遮盖 A-roll。
+
+规划只提供时间轴证据，不会假定每个剪辑点都必须加 B-roll。`needs-broll` 表示“值得检查”，不表示“必须遮盖”；是否添加仍需结合实际画面判断。
+
+### 4. 文件名优先筛选 B-roll
+
+使用 `plan.needs` 中已经调整过的完整区间，再扫描指定素材目录：
 
 ```js
 talking_head_broll_match {
@@ -85,15 +131,7 @@ talking_head_broll_match {
   maxDepth: 12,
   maxCandidates: 5,
   candidateOffset: 0,
-  need: {
-    id: "mouse-demo",
-    outputStartMs: 5200,
-    outputEndMs: 8200,
-    speechText: "电脑除了键盘，还需要鼠标",
-    purpose: "demonstrate",
-    searchTerms: ["鼠标", "操作"],
-    reason: "展示口播提到的具体对象和动作"
-  }
+  need: plan.needs[0]
 }
 ```
 
@@ -121,23 +159,24 @@ talking_head_broll_select {
 
 该工具会验证素材 SHA-256、manifest 分析范围、起始帧和覆盖片段尾部的证据时间戳，返回可直接交给 `talking_head_apply` 的完整 placement。placement 内含选择凭证；不要手写或删除其中字段。
 
-### 4. 写入人工确认后的时间线
+### 5. 写入人工确认后的时间线
 
 ```js
 talking_head_apply {
   projectId: "launch-video",
   expectedRevision: 1,
-  arroll: [
+  aroll: [
     { id: "hook", sourceStartMs: 50, sourceEndMs: 4120 },
     { id: "answer", sourceStartMs: 4860, sourceEndMs: 13200 }
   ],
-  broll: [selection.placement]
+  broll: [selectionA.placement, selectionB.placement],
+  continuityPlanReceipt
 }
 ```
 
-B-roll 使用成片时间轴定位，`assetStartMs` 来自联络表 manifest，并永远保留主口播音轨。`talking_head_apply` 会重新校验选择凭证、素材与 manifest 的 SHA-256；时间点被手改或素材被替换都会拒绝写入新修订。
+B-roll 使用成片时间轴定位，`assetStartMs` 来自联络表 manifest，并永远保留主口播音轨。`talking_head_apply` 会重新校验连续性规划凭证、选段凭证、素材与 manifest 的 SHA-256；规划区间或时间点被手改、素材被替换都会拒绝写入新修订。若两个 B-roll 之间仍存在不超过 500ms 的 A-roll，也会拒绝写入并要求重新规划。当前不支持 B-roll 相互重叠，因为未定义 z-order。
 
-### 5. 交给 pi-media 渲染
+### 6. 交给 pi-media 渲染
 
 先用同一个源文件创建 `pi-media` 项目，再把上一步的 `mediaOperation` 原样传入：
 
@@ -165,6 +204,7 @@ review { path: "out/launch-final.mp4" }
 | --- | --- |
 | `talking_head_create` | 从视频和词级转录建立 revision 1，分析句子、语气词、重复和停顿并生成默认 EDL |
 | `talking_head_get` | 读取指定 revision，分页返回整句与编辑候选，可选导出 pi-media EDL |
+| `talking_head_broll_plan` | 按 A-roll 优先预算规划 B-roll、衔接相邻片段并报告待审阅跳点 |
 | `talking_head_broll_match` | 只用文件名和目录名匹配本地 B-roll，返回受限 shortlist 与视觉升级建议 |
 | `talking_head_broll_select` | 用 pi-media 联络表 manifest 验证具体源时间段并生成 placement |
 | `talking_head_apply` | 写入新的不可变口播 revision，并返回 pi-media EDL |

package/extensions/talking-head/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { matchWorkspaceBrollAssets, selectBrollWindow } from "../../src/broll.ts";
+import { createBrollContinuityPlanReceipt, planBrollContinuity } from "../../src/continuity.ts";
 import { toMediaTimelineOperation } from "../../src/edl.ts";
 import {
 	applyTimeline,
@@ -23,7 +24,7 @@ const stableId = Type.String({
 	pattern: "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$",
 });
 
-const arrollSegment = Type.Object({
+const arollSegment = Type.Object({
 	id: stableId,
 	sourceStartMs: Type.Number({ minimum: 0 }),
 	sourceEndMs: Type.Number({ exclusiveMinimum: 0 }),
@@ -66,6 +67,34 @@ const brollNeed = Type.Object({
 	reason: Type.String({ minLength: 1, maxLength: 1_000 }),
 }, { additionalProperties: false });
 
+const arollJumpCut = Type.Object({
+	fromSegmentId: stableId,
+	toSegmentId: stableId,
+	outputTimeMs: Type.Number({ minimum: 0 }),
+	sourceDeltaMs: Type.Number(),
+	suggestedOutputStartMs: Type.Number({ minimum: 0 }),
+	suggestedOutputEndMs: Type.Number({ minimum: 0 }),
+	coveredByNeedIds: Type.Array(stableId, { maxItems: 500 }),
+	status: Type.Union([Type.Literal("covered"), Type.Literal("needs-broll")]),
+}, { additionalProperties: false });
+
+const continuityPlanReceipt = Type.Object({
+	schemaVersion: Type.Literal(1),
+	projectId: stableId,
+	revision: Type.Integer({ minimum: 1 }),
+	arollSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+	shortGapMs: Type.Integer({ minimum: 0, maximum: 2_000 }),
+	cutCoverBeforeMs: Type.Integer({ minimum: 0, maximum: 2_000 }),
+	cutCoverAfterMs: Type.Integer({ minimum: 0, maximum: 2_000 }),
+	needs: Type.Array(Type.Object({
+		id: stableId,
+		outputStartMs: Type.Number({ minimum: 0 }),
+		outputEndMs: Type.Number({ exclusiveMinimum: 0 }),
+	}, { additionalProperties: false }), { maxItems: 500 }),
+	jumpCuts: Type.Array(arollJumpCut, { maxItems: 999 }),
+	planSha256: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+}, { additionalProperties: false });
+
 export default function talkingHead(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "talking_head_create",
@@ -168,6 +197,43 @@ export default function talkingHead(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "talking_head_broll_plan",
+		label: "Plan B-roll visual continuity",
+		description: "Plan A-roll-first B-roll windows before asset matching. Keeps total B-roll at or below 50% and each continuous run at or below 8 seconds, bridges brief A-roll flashes, and reports source jump cuts for visual review.",
+		parameters: Type.Object({
+			projectId: stableId,
+			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+			aroll: Type.Array(arollSegment, { minItems: 1, maxItems: 1_000 }),
+			needs: Type.Array(brollNeed, { maxItems: 500 }),
+			cutCoverBeforeMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 2_000, default: 250 })),
+			cutCoverAfterMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 2_000, default: 500 })),
+		}, { additionalProperties: false }),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const { snapshot } = await getTalkingHeadProject(ctx.cwd, params.projectId, params.revision);
+			const plan = planBrollContinuity({
+				aroll: params.aroll,
+				needs: params.needs,
+				...(params.cutCoverBeforeMs === undefined ? {} : { cutCoverBeforeMs: params.cutCoverBeforeMs }),
+				...(params.cutCoverAfterMs === undefined ? {} : { cutCoverAfterMs: params.cutCoverAfterMs }),
+			});
+			return result({
+				projectId: params.projectId,
+				revision: snapshot.revision,
+				plan,
+				continuityPlanReceipt: createBrollContinuityPlanReceipt(
+					params.projectId,
+					snapshot.revision,
+					params.aroll,
+					plan,
+				),
+				nextStep: plan.jumpCuts.some((cut) => cut.status === "needs-broll")
+					? "Create purpose=mask-cut needs for uncovered jump cuts, then run this planner again before asset matching."
+					: "Use plan.needs for B-roll asset matching and source-window selection.",
+			});
+		},
+	});
+
 	pi.registerTool({
 		name: "talking_head_broll_match",
 		label: "Match local B-roll assets",
@@ -242,12 +308,13 @@ export default function talkingHead(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "talking_head_apply",
 		label: "Apply talking-head timeline",
-		description: "Create a new immutable talking-head revision from word-boundary A-roll ranges and optional B-roll placements. Returns a generic pi-media timeline operation ready for edit_apply.",
+		description: "Create a new immutable talking-head revision from word-boundary A-roll ranges and optional B-roll placements. B-roll requires the matching continuity plan receipt; coverage above 50%, continuous runs above 8 seconds, brief A-roll flashes, unplanned ranges, and overlaps are rejected. Returns a generic pi-media timeline operation ready for edit_apply.",
 		parameters: Type.Object({
 			projectId: stableId,
 			expectedRevision: Type.Integer({ minimum: 1 }),
-			aroll: Type.Array(arrollSegment, { minItems: 1, maxItems: 1_000 }),
+			aroll: Type.Array(arollSegment, { minItems: 1, maxItems: 1_000 }),
 			broll: Type.Array(brollPlacement, { maxItems: 500 }),
+			continuityPlanReceipt: Type.Optional(continuityPlanReceipt),
 		}, { additionalProperties: false }),
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const current = await getTalkingHeadProject(ctx.cwd, params.projectId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclip/pi-talking-head",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Pause-aware talking-head editing and B-roll planning for Pi, exported as generic pi-media EDLs",
   "type": "module",
   "license": "MIT",

package/prompts/edit-talking-head.md

@@ -2,6 +2,6 @@
 description: Tighten a talking-head video without destroying natural speech rhythm
 ---
 
-Use the `talking-head-edit` skill to review full-sentence context, word-level pauses, filler words, adjacent repetitions, and low-confidence delivery cues; stabilize A-roll, match B-roll by filename before escalating through paged contact-sheet batches, validate the selected manifest-backed source window, and export a generic pi-media EDL for this request: $@
+Use the `talking-head-edit` skill to review full-sentence context, word-level pauses, filler words, adjacent repetitions, and low-confidence delivery cues; stabilize A-roll, keep A-roll visible for at least half of the output, limit each continuous B-roll run to 8 seconds, bridge brief A-roll flashes, mask only visually objectionable jump cuts, match B-roll by filename before escalating through paged contact-sheet batches, validate the selected manifest-backed source window, and export a generic pi-media EDL for this request: $@
 
 Show the proposed rhythm before writing a new revision. Never overwrite the source or an existing render.

package/skills/talking-head-edit/SKILL.md

@@ -12,16 +12,17 @@ Use `pi-speech` for word evidence, this package for editorial decisions, and `pi
 3. Inspect bounded `talking_head_get` pages. Review the full sentence context, filler candidates, and repetition candidates together with pauses. Treat `safe` and every recommendation as evidence, not an instruction. Preserve pauses that carry emphasis, emotion, topic boundaries, or a deliberate breath.
 4. Never delete a filler token automatically. Decide whether `啊`, `额`, `嗯`, or a repeated token is a false start, a discourse marker, or intentional emphasis from its sentence context. A text-only delivery cue is low-confidence evidence; review audio and picture before relying on emotion or performance intent.
 5. Before changing the revision, summarize the proposed rhythm: what words and gaps will be removed, which pauses or fillers will remain, and why. Get the user's approval unless they explicitly delegated editorial judgment.
-6. Stabilize A-roll before B-roll. For every B-roll window, record the output range, complete spoken text, one purpose (`demonstrate`, `explain`, `evidence`, `establish`, `transition`, or `mask-cut`), 1-20 concise search terms, and a concrete reason.
-7. Call `talking_head_broll_match` before generating contact sheets. Follow its bounded result:
+6. Stabilize A-roll before B-roll. A-roll is the primary picture, not leftover filler: keep it visible for at least half of the final duration and reintroduce it within every 8 seconds of continuous B-roll. For every B-roll window, record the output range, complete spoken text, one purpose (`demonstrate`, `explain`, `evidence`, `establish`, `transition`, or `mask-cut`), 1-20 concise search terms, and a concrete reason.
+7. Call `talking_head_broll_plan` with the final proposed A-roll and all semantic B-roll needs before matching assets. Keep its `continuityPlanReceipt` unchanged. Use the returned `plan.needs` and inspect `plan.coverage`: the planner rejects total B-roll above 50% or any continuous run above 8000ms. It extends the previous B-roll across A-roll gaps of 500ms or less so neighboring B-roll clips hand off directly. Review every reported A-roll jump cut, but add `purpose: mask-cut` only when picture review shows a visually objectionable cut and the spoken context supports B-roll. Never cover every reported jump cut by default. If the budget is exceeded, remove or shorten lower-value needs instead of hiding more A-roll, then rerun the plan.
+8. Call `talking_head_broll_match` before generating contact sheets. Follow its bounded result:
    - `filename-direct`: probe and visually inspect only the selected asset to choose its source window. Do not call `media_contact_sheet` for unselected assets.
    - `filename-shortlist`: inspect only the returned shortlist and stop as soon as one asset satisfies the need. If none does and `nextCandidateOffset` is non-null, request that next page; do not repeat the first batch.
    - `visual-fallback`: use low-cost contact sheets on the bounded shortlist because filenames supplied no useful evidence. Exhaust that batch before requesting a non-null `nextCandidateOffset`.
    - If the scan is truncated, do not paginate it: narrow the asset directory and rescan so the candidate inventory is stable.
-8. After selecting one asset, call `media_probe`, then use `media_contact_sheet` only as densely as timing requires: one high-density pass for a short ambiguous clip, medium for a normal clip, or low over a long clip followed by high density over the narrowed range. Read `contact_sheet_manifest.json` timestamps instead of guessing times from the PNG. Verify a continuous source window at least as long as the output window, preferably with 500ms handles on both sides.
-9. Call `talking_head_broll_select` with the selected asset, manifest path, exact source start, and the manifest timestamps actually reviewed. Use its complete returned `placement`, including `selectionReceipt`; do not hand-author or omit selection fields.
-10. Call `talking_head_apply` using exact word-boundary A-roll ranges and the validated B-roll placement. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
-11. Create/read a `pi-media` project for the same source. Pass the returned `mediaOperation` unchanged to `edit_apply`, then `render` the exact new revision and call `review`.
+9. After selecting one asset, call `media_probe`, then use `media_contact_sheet` only as densely as timing requires: one high-density pass for a short ambiguous clip, medium for a normal clip, or low over a long clip followed by high density over the narrowed range. Read `contact_sheet_manifest.json` timestamps instead of guessing times from the PNG. Verify a continuous source window at least as long as the planned output window, preferably with 500ms handles on both sides.
+10. Call `talking_head_broll_select` with each planned need, selected asset, manifest path, exact source start, and the manifest timestamps actually reviewed. Use its complete returned `placement`, including `selectionReceipt`; do not shorten bridged output ranges or hand-author selection fields.
+11. Call `talking_head_apply` using the same planned A-roll, every validated B-roll placement, and the unchanged `continuityPlanReceipt`. The tool independently rejects B-roll above the 50%/8000ms A-roll-first budget, unplanned ranges, overlaps, and A-roll flashes of 500ms or less. Every B-roll window must have a concrete visual purpose in `reason`; keep `audio: keep-primary`.
+12. Create/read a `pi-media` project for the same source. Pass the returned `mediaOperation` unchanged to `edit_apply`, then `render` the exact new revision and call `review`.
 
 Never overwrite source media or outputs. If a revision conflict occurs, re-read both projects and reconcile intent. If the source, transcript, or B-roll hash changed, stop and ask whether to create a new project rather than silently adopting new bytes.
 

package/skills/talking-head-edit/references/cut-craft.md

@@ -23,6 +23,7 @@
 - Start with filename and directory metadata. Generate contact sheets only for the selected asset, a bounded ambiguous shortlist, or a bounded fallback batch whose names carry no meaning.
 - For a long selected asset, locate a broad range cheaply and then generate a denser contact sheet only for that range. Use manifest timestamps, not visual timestamp transcription.
 - Ensure the selected source window covers the complete spoken beat. Prefer extra source handles so a later timing adjustment does not require rescanning.
+- If neighboring B-roll windows expose 500ms or less of A-roll, plan a direct handoff by extending the previous B-roll need before source-window selection. Do not let a few frames of A-roll flash between overlays.
 - Cover visible jump cuts when appropriate, but do not hide continuity errors that change meaning.
 - Keep the primary voice track. B-roll audio replacement is outside the current contract.
 - Record the search query and editorial reason so a later agent can replace the asset without guessing intent.

package/src/continuity.ts

@@ -0,0 +1,432 @@
+import { createHash } from "node:crypto";
+import type {
+	ArollJumpCut,
+	ArollSegment,
+	BrollContinuityBridge,
+	BrollContinuityPlan,
+	BrollContinuityPlanReceipt,
+	BrollCoverageSummary,
+	BrollNeed,
+} from "./contracts.ts";
+import { timelineDuration } from "./transcript.ts";
+
+export const MAX_BROLL_COVERAGE_RATIO = 0.5;
+export const MAX_CONTINUOUS_BROLL_MS = 8_000;
+
+export interface PlanBrollContinuityInput {
+	aroll: ArollSegment[];
+	needs: BrollNeed[];
+	shortGapMs?: number;
+	cutCoverBeforeMs?: number;
+	cutCoverAfterMs?: number;
+}
+
+export interface BrollOutputWindow {
+	id: string;
+	outputStartMs: number;
+	outputEndMs: number;
+}
+
+export interface ShortArollFlashGap {
+	fromBrollId: string;
+	toBrollId: string;
+	startMs: number;
+	endMs: number;
+	durationMs: number;
+}
+
+export interface OverlappingBrollWindows {
+	underBrollId: string;
+	overBrollId: string;
+}
+
+function boundedMilliseconds(value: number | undefined, fallback: number, name: string, maximum: number): number {
+	const selected = value ?? fallback;
+	if (!Number.isInteger(selected) || selected < 0 || selected > maximum) {
+		throw new Error(`${name} must be an integer within 0-${maximum}`);
+	}
+	return selected;
+}
+
+export function findShortArollFlashGaps(
+	windows: BrollOutputWindow[],
+	shortGapMs = 500,
+): ShortArollFlashGap[] {
+	const threshold = boundedMilliseconds(shortGapMs, 500, "shortGapMs", 2_000);
+	const sorted = [...windows].sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| left.outputEndMs - right.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	const gaps: ShortArollFlashGap[] = [];
+	let frontier = sorted[0];
+	let coveredUntilMs = frontier?.outputEndMs ?? 0;
+	for (let index = 1; index < sorted.length; index += 1) {
+		const next = sorted[index]!;
+		if (next.outputStartMs <= coveredUntilMs) {
+			if (next.outputEndMs > coveredUntilMs) {
+				frontier = next;
+				coveredUntilMs = next.outputEndMs;
+			}
+			continue;
+		}
+		const durationMs = next.outputStartMs - coveredUntilMs;
+		if (durationMs > threshold) {
+			frontier = next;
+			coveredUntilMs = next.outputEndMs;
+			continue;
+		}
+		gaps.push({
+			fromBrollId: frontier!.id,
+			toBrollId: next.id,
+			startMs: coveredUntilMs,
+			endMs: next.outputStartMs,
+			durationMs,
+		});
+		frontier = next;
+		coveredUntilMs = next.outputEndMs;
+	}
+	return gaps;
+}
+
+export function findOverlappingBrollWindows(windows: BrollOutputWindow[]): OverlappingBrollWindows[] {
+	const sorted = [...windows].sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| right.outputEndMs - left.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	const overlaps: OverlappingBrollWindows[] = [];
+	let frontier = sorted[0];
+	for (let index = 1; index < sorted.length; index += 1) {
+		const next = sorted[index]!;
+		if (frontier && next.outputStartMs < frontier.outputEndMs) {
+			overlaps.push({ underBrollId: frontier.id, overBrollId: next.id });
+			if (next.outputEndMs > frontier.outputEndMs) frontier = next;
+			continue;
+		}
+		frontier = next;
+	}
+	return overlaps;
+}
+
+export function summarizeBrollCoverage(
+	windows: BrollOutputWindow[],
+	outputDurationMs: number,
+): BrollCoverageSummary {
+	if (!Number.isFinite(outputDurationMs) || outputDurationMs <= 0) {
+		throw new Error("outputDurationMs must be a positive finite number");
+	}
+	for (const window of windows) {
+		if (!Number.isFinite(window.outputStartMs) || !Number.isFinite(window.outputEndMs)
+			|| window.outputStartMs < 0 || window.outputEndMs <= window.outputStartMs
+			|| window.outputEndMs > outputDurationMs) {
+			throw new Error(`Invalid B-roll coverage window: ${window.id}`);
+		}
+	}
+	const sorted = [...windows].sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| left.outputEndMs - right.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	let brollDurationMs = 0;
+	let longestContinuousBrollMs = 0;
+	let runStartMs: number | undefined;
+	let runEndMs: number | undefined;
+	for (const window of sorted) {
+		if (runStartMs === undefined || runEndMs === undefined) {
+			runStartMs = window.outputStartMs;
+			runEndMs = window.outputEndMs;
+			continue;
+		}
+		if (window.outputStartMs <= runEndMs) {
+			runEndMs = Math.max(runEndMs, window.outputEndMs);
+			continue;
+		}
+		const durationMs = runEndMs - runStartMs;
+		brollDurationMs += durationMs;
+		longestContinuousBrollMs = Math.max(longestContinuousBrollMs, durationMs);
+		runStartMs = window.outputStartMs;
+		runEndMs = window.outputEndMs;
+	}
+	if (runStartMs !== undefined && runEndMs !== undefined) {
+		const durationMs = runEndMs - runStartMs;
+		brollDurationMs += durationMs;
+		longestContinuousBrollMs = Math.max(longestContinuousBrollMs, durationMs);
+	}
+	return {
+		brollDurationMs,
+		arollDurationMs: outputDurationMs - brollDurationMs,
+		brollCoverageRatio: Math.round((brollDurationMs / outputDurationMs) * 10_000) / 10_000,
+		longestContinuousBrollMs,
+		limits: {
+			maxBrollCoverageRatio: MAX_BROLL_COVERAGE_RATIO,
+			maxContinuousBrollMs: MAX_CONTINUOUS_BROLL_MS,
+		},
+	};
+}
+
+export function assertBrollCoverageBudget(
+	windows: BrollOutputWindow[],
+	outputDurationMs: number,
+): BrollCoverageSummary {
+	const coverage = summarizeBrollCoverage(windows, outputDurationMs);
+	if (coverage.brollDurationMs > outputDurationMs * MAX_BROLL_COVERAGE_RATIO) {
+		const percent = ((coverage.brollDurationMs / outputDurationMs) * 100).toFixed(1);
+		throw new Error(`B-roll coverage ${percent}% exceeds the 50% A-roll-first limit; remove or shorten lower-priority B-roll needs`);
+	}
+	if (coverage.longestContinuousBrollMs > MAX_CONTINUOUS_BROLL_MS) {
+		throw new Error(`continuous B-roll run ${coverage.longestContinuousBrollMs}ms exceeds the 8000ms limit; split it with a meaningful A-roll appearance`);
+	}
+	return coverage;
+}
+
+function validateSegments(aroll: ArollSegment[]): void {
+	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
+	const ids = new Set<string>();
+	for (const segment of aroll) {
+		if (ids.has(segment.id)) throw new Error(`Duplicate A-roll segment ID: ${segment.id}`);
+		ids.add(segment.id);
+		if (!Number.isFinite(segment.sourceStartMs) || !Number.isFinite(segment.sourceEndMs)
+			|| segment.sourceStartMs < 0 || segment.sourceEndMs <= segment.sourceStartMs) {
+			throw new Error(`Invalid A-roll segment range: ${segment.id}`);
+		}
+	}
+}
+
+function validateNeeds(needs: BrollNeed[], outputDurationMs: number): void {
+	if (needs.length > 500) throw new Error("B-roll plan must contain at most 500 needs");
+	const ids = new Set<string>();
+	for (const need of needs) {
+		if (ids.has(need.id)) throw new Error(`Duplicate B-roll need ID: ${need.id}`);
+		ids.add(need.id);
+		if (!Number.isFinite(need.outputStartMs) || !Number.isFinite(need.outputEndMs)
+			|| need.outputStartMs < 0 || need.outputEndMs <= need.outputStartMs
+			|| need.outputEndMs > outputDurationMs) {
+			throw new Error(`Invalid B-roll need output range: ${need.id}`);
+		}
+	}
+	const overlap = findOverlappingBrollWindows(needs)[0];
+	if (overlap) throw new Error(`B-roll needs ${overlap.underBrollId} and ${overlap.overBrollId} overlap; z-order is not supported`);
+}
+
+function bridgeShortGaps(needs: BrollNeed[], shortGapMs: number): {
+	needs: BrollNeed[];
+	bridges: BrollContinuityBridge[];
+} {
+	const sorted = structuredClone(needs).sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| left.outputEndMs - right.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	const bridges: BrollContinuityBridge[] = [];
+	let frontier = sorted[0];
+	let coveredUntilMs = frontier?.outputEndMs ?? 0;
+	for (let index = 1; index < sorted.length; index += 1) {
+		const next = sorted[index]!;
+		if (next.outputStartMs <= coveredUntilMs) {
+			if (next.outputEndMs > coveredUntilMs) {
+				frontier = next;
+				coveredUntilMs = next.outputEndMs;
+			}
+			continue;
+		}
+		const durationMs = next.outputStartMs - coveredUntilMs;
+		if (durationMs > shortGapMs) {
+			frontier = next;
+			coveredUntilMs = next.outputEndMs;
+			continue;
+		}
+		bridges.push({
+			fromNeedId: frontier!.id,
+			toNeedId: next.id,
+			gapStartMs: coveredUntilMs,
+			gapEndMs: next.outputStartMs,
+			durationMs,
+			strategy: "extend-previous-broll",
+		});
+		frontier!.outputEndMs = next.outputStartMs;
+		frontier = next;
+		coveredUntilMs = next.outputEndMs;
+	}
+	return { needs: sorted, bridges };
+}
+
+function coverageForRange(needs: BrollOutputWindow[], startMs: number, endMs: number): {
+	covered: boolean;
+	needIds: string[];
+} {
+	const overlapping = needs.filter((need) => need.outputEndMs > startMs && need.outputStartMs < endMs).sort((left, right) => (
+		left.outputStartMs - right.outputStartMs
+		|| left.outputEndMs - right.outputEndMs
+		|| (left.id < right.id ? -1 : left.id > right.id ? 1 : 0)
+	));
+	let cursor = startMs;
+	const needIds: string[] = [];
+	for (const need of overlapping) {
+		if (need.outputStartMs > cursor) return { covered: false, needIds };
+		needIds.push(need.id);
+		cursor = Math.max(cursor, need.outputEndMs);
+		if (cursor >= endMs) return { covered: true, needIds };
+	}
+	return { covered: false, needIds };
+}
+
+export function analyzeArollJumpCuts(
+	aroll: ArollSegment[],
+	needs: BrollOutputWindow[],
+	outputDurationMs: number,
+	cutCoverBeforeMs: number,
+	cutCoverAfterMs: number,
+): ArollJumpCut[] {
+	const jumpCuts: ArollJumpCut[] = [];
+	let outputTimeMs = 0;
+	for (let index = 0; index < aroll.length - 1; index += 1) {
+		const current = aroll[index]!;
+		const next = aroll[index + 1]!;
+		outputTimeMs += current.sourceEndMs - current.sourceStartMs;
+		const sourceDeltaMs = next.sourceStartMs - current.sourceEndMs;
+		if (sourceDeltaMs === 0) continue;
+		const suggestedOutputStartMs = Math.max(0, outputTimeMs - cutCoverBeforeMs);
+		const suggestedOutputEndMs = Math.min(outputDurationMs, outputTimeMs + cutCoverAfterMs);
+		const coverage = coverageForRange(needs, suggestedOutputStartMs, suggestedOutputEndMs);
+		jumpCuts.push({
+			fromSegmentId: current.id,
+			toSegmentId: next.id,
+			outputTimeMs,
+			sourceDeltaMs,
+			suggestedOutputStartMs,
+			suggestedOutputEndMs,
+			coveredByNeedIds: coverage.needIds,
+			status: coverage.covered ? "covered" : "needs-broll",
+		});
+	}
+	return jumpCuts;
+}
+
+export function planBrollContinuity(input: PlanBrollContinuityInput): BrollContinuityPlan {
+	validateSegments(input.aroll);
+	const outputDurationMs = timelineDuration(input.aroll);
+	validateNeeds(input.needs, outputDurationMs);
+	const shortGapMs = boundedMilliseconds(input.shortGapMs, 500, "shortGapMs", 2_000);
+	const cutCoverBeforeMs = boundedMilliseconds(input.cutCoverBeforeMs, 250, "cutCoverBeforeMs", 2_000);
+	const cutCoverAfterMs = boundedMilliseconds(input.cutCoverAfterMs, 500, "cutCoverAfterMs", 2_000);
+	if (cutCoverBeforeMs === 0 && cutCoverAfterMs === 0) {
+		throw new Error("cutCoverBeforeMs and cutCoverAfterMs cannot both be zero");
+	}
+	const bridged = bridgeShortGaps(input.needs, shortGapMs);
+	const coverage = assertBrollCoverageBudget(bridged.needs, outputDurationMs);
+	return {
+		outputDurationMs,
+		shortGapMs,
+		cutCoverBeforeMs,
+		cutCoverAfterMs,
+		needs: bridged.needs,
+		bridges: bridged.bridges,
+		coverage,
+		jumpCuts: analyzeArollJumpCuts(
+			input.aroll,
+			bridged.needs,
+			outputDurationMs,
+			cutCoverBeforeMs,
+			cutCoverAfterMs,
+		),
+	};
+}
+
+function planReceiptPayload(receipt: Omit<BrollContinuityPlanReceipt, "planSha256">): string {
+	return canonicalJson(receipt);
+}
+
+function canonicalJson(value: unknown): string {
+	if (value === null || typeof value !== "object") {
+		const serialized = JSON.stringify(value);
+		if (serialized === undefined) throw new Error("Cannot canonicalize an undefined value");
+		return serialized;
+	}
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	const object = value as Record<string, unknown>;
+	return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+}
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function arollSha256(aroll: ArollSegment[]): string {
+	return sha256(canonicalJson(aroll));
+}
+
+function plannedRanges(needs: BrollNeed[]): BrollContinuityPlanReceipt["needs"] {
+	return needs.map((need) => ({
+		id: need.id,
+		outputStartMs: need.outputStartMs,
+		outputEndMs: need.outputEndMs,
+	}));
+}
+
+export function createBrollContinuityPlanReceipt(
+	projectId: string,
+	revision: number,
+	aroll: ArollSegment[],
+	plan: BrollContinuityPlan,
+): BrollContinuityPlanReceipt {
+	const payload: Omit<BrollContinuityPlanReceipt, "planSha256"> = {
+		schemaVersion: 1,
+		projectId,
+		revision,
+		arollSha256: arollSha256(aroll),
+		shortGapMs: plan.shortGapMs,
+		cutCoverBeforeMs: plan.cutCoverBeforeMs,
+		cutCoverAfterMs: plan.cutCoverAfterMs,
+		needs: plannedRanges(plan.needs),
+		jumpCuts: structuredClone(plan.jumpCuts),
+	};
+	return { ...payload, planSha256: sha256(planReceiptPayload(payload)) };
+}
+
+export function verifyBrollContinuityPlanReceipt(
+	projectId: string,
+	revision: number,
+	aroll: ArollSegment[],
+	placements: BrollOutputWindow[],
+	receipt: BrollContinuityPlanReceipt,
+): void {
+	if (receipt.schemaVersion !== 1 || receipt.projectId !== projectId || receipt.revision !== revision) {
+		throw new Error("B-roll continuity receipt does not match the current project revision");
+	}
+	if (receipt.arollSha256 !== arollSha256(aroll)) {
+		throw new Error("B-roll continuity receipt does not match the planned A-roll");
+	}
+	const { planSha256, ...payload } = receipt;
+	if (planSha256 !== sha256(planReceiptPayload(payload))) {
+		throw new Error("B-roll continuity receipt hash is invalid");
+	}
+	const dummyNeeds: BrollNeed[] = receipt.needs.map((need) => ({
+		...need,
+		speechText: "continuity receipt",
+		purpose: "mask-cut",
+		searchTerms: ["continuity"],
+		reason: "continuity receipt verification",
+	}));
+	const recomputed = planBrollContinuity({
+		aroll,
+		needs: dummyNeeds,
+		shortGapMs: receipt.shortGapMs,
+		cutCoverBeforeMs: receipt.cutCoverBeforeMs,
+		cutCoverAfterMs: receipt.cutCoverAfterMs,
+	});
+	if (canonicalJson(plannedRanges(recomputed.needs)) !== canonicalJson(receipt.needs)
+		|| canonicalJson(recomputed.jumpCuts) !== canonicalJson(receipt.jumpCuts)) {
+		throw new Error("B-roll continuity receipt does not match the recomputed plan");
+	}
+	const actualRanges = [...placements].sort((left, right) => (
+		left.outputStartMs - right.outputStartMs || left.outputEndMs - right.outputEndMs
+	)).map((placement) => ({
+		id: placement.id,
+		outputStartMs: placement.outputStartMs,
+		outputEndMs: placement.outputEndMs,
+	}));
+	if (canonicalJson(actualRanges) !== canonicalJson(receipt.needs)) {
+		throw new Error("B-roll placements do not match the planned ranges");
+	}
+}

package/src/contracts.ts

@@ -165,6 +165,61 @@ export interface BrollWindowSelection {
 	placement: BrollPlacementInput;
 }
 
+export interface BrollContinuityBridge {
+	fromNeedId: string;
+	toNeedId: string;
+	gapStartMs: number;
+	gapEndMs: number;
+	durationMs: number;
+	strategy: "extend-previous-broll";
+}
+
+export interface ArollJumpCut {
+	fromSegmentId: string;
+	toSegmentId: string;
+	outputTimeMs: number;
+	sourceDeltaMs: number;
+	suggestedOutputStartMs: number;
+	suggestedOutputEndMs: number;
+	coveredByNeedIds: string[];
+	status: "covered" | "needs-broll";
+}
+
+export interface BrollCoverageSummary {
+	brollDurationMs: number;
+	arollDurationMs: number;
+	brollCoverageRatio: number;
+	longestContinuousBrollMs: number;
+	limits: {
+		maxBrollCoverageRatio: number;
+		maxContinuousBrollMs: number;
+	};
+}
+
+export interface BrollContinuityPlan {
+	outputDurationMs: number;
+	shortGapMs: number;
+	cutCoverBeforeMs: number;
+	cutCoverAfterMs: number;
+	needs: BrollNeed[];
+	bridges: BrollContinuityBridge[];
+	jumpCuts: ArollJumpCut[];
+	coverage: BrollCoverageSummary;
+}
+
+export interface BrollContinuityPlanReceipt {
+	schemaVersion: 1;
+	projectId: string;
+	revision: number;
+	arollSha256: string;
+	shortGapMs: number;
+	cutCoverBeforeMs: number;
+	cutCoverAfterMs: number;
+	needs: Array<{ id: string; outputStartMs: number; outputEndMs: number }>;
+	jumpCuts: ArollJumpCut[];
+	planSha256: string;
+}
+
 export interface TranscriptAnalysis {
 	schemaVersion: 2;
 	text: string;
@@ -209,6 +264,9 @@ export interface TalkingHeadSnapshot {
 	policy: TalkingHeadPolicy;
 	aroll: ArollSegment[];
 	broll: BrollPlacement[];
+	continuityPlanReceipt?: BrollContinuityPlanReceipt;
+	jumpCuts?: ArollJumpCut[];
+	brollCoverage?: BrollCoverageSummary;
 	outputDurationMs: number;
 }
 

package/src/project.ts

@@ -5,6 +5,7 @@ import type {
 	ArollSegment,
 	BrollPlacement,
 	BrollPlacementInput,
+	BrollContinuityPlanReceipt,
 	FillerCandidate,
 	PauseCandidate,
 	RepetitionCandidate,
@@ -17,6 +18,13 @@ import type {
 	WordTranscript,
 } from "./contracts.ts";
 import { verifyBrollPlacementSelection } from "./broll.ts";
+import {
+	analyzeArollJumpCuts,
+	assertBrollCoverageBudget,
+	findOverlappingBrollWindows,
+	findShortArollFlashGaps,
+	verifyBrollContinuityPlanReceipt,
+} from "./continuity.ts";
 import { analyzeTranscript, DEFAULT_POLICY, timelineDuration } from "./transcript.ts";
 import { resolveExistingWorkspaceFile, resolveWorkspacePath, snapshotFile, workspaceRelativePath } from "./workspace.ts";
 
@@ -34,6 +42,7 @@ export interface ApplyTimelineInput {
 	expectedRevision: number;
 	aroll: ArollSegment[];
 	broll: BrollPlacementInput[];
+	continuityPlanReceipt?: BrollContinuityPlanReceipt;
 }
 
 function assertProjectId(projectId: string): void {
@@ -78,8 +87,16 @@ async function validateTimeline(
 	cwd: string,
 	aroll: ArollSegment[],
 	broll: BrollPlacementInput[],
+	projectId: string,
+	revision: number,
+	continuityPlanReceipt: BrollContinuityPlanReceipt | undefined,
 	signal?: AbortSignal,
-): Promise<{ outputDurationMs: number; broll: BrollPlacement[] }> {
+): Promise<{
+	outputDurationMs: number;
+	broll: BrollPlacement[];
+	brollCoverage: ReturnType<typeof assertBrollCoverageBudget>;
+	jumpCuts: ReturnType<typeof analyzeArollJumpCuts>;
+}> {
 	if (aroll.length === 0 || aroll.length > 1_000) throw new Error("A-roll must contain 1-1000 segments");
 	uniqueIds(aroll, "A-roll segment");
 	for (const segment of aroll) {
@@ -91,9 +108,7 @@ async function validateTimeline(
 	const outputDurationMs = timelineDuration(aroll);
 	if (broll.length > 500) throw new Error("B-roll must contain at most 500 placements");
 	uniqueIds(broll, "B-roll placement");
-	const normalizedBroll: BrollPlacement[] = [];
 	for (const placement of broll) {
-		signal?.throwIfAborted();
 		if (!Number.isFinite(placement.outputStartMs) || !Number.isFinite(placement.outputEndMs)
 			|| placement.outputStartMs < 0 || placement.outputEndMs <= placement.outputStartMs) {
 			throw new Error(`Invalid B-roll output range: ${placement.id}`);
@@ -106,6 +121,25 @@ async function validateTimeline(
 		}
 		if (!placement.selectionReceipt) throw new Error(`B-roll selectionReceipt is required: ${placement.id}`);
 		if (placement.audio !== "keep-primary") throw new Error("B-roll audio must keep the primary A-roll audio");
+	}
+	const overlap = findOverlappingBrollWindows(broll)[0];
+	if (overlap) {
+		throw new Error(`B-roll placements ${overlap.underBrollId} and ${overlap.overBrollId} overlap; ambiguous z-order is not supported`);
+	}
+	const flashGap = findShortArollFlashGaps(broll, 500)[0];
+	if (flashGap) {
+		throw new Error(`B-roll placements ${flashGap.fromBrollId} and ${flashGap.toBrollId} leave a brief ${flashGap.durationMs}ms A-roll flash; run talking_head_broll_plan and reselect the bridged window`);
+	}
+	const brollCoverage = assertBrollCoverageBudget(broll, outputDurationMs);
+	if (broll.length > 0 && !continuityPlanReceipt) {
+		throw new Error("B-roll continuityPlanReceipt is required; run talking_head_broll_plan first");
+	}
+	if (continuityPlanReceipt) {
+		verifyBrollContinuityPlanReceipt(projectId, revision, aroll, broll, continuityPlanReceipt);
+	}
+	const normalizedBroll: BrollPlacement[] = [];
+	for (const placement of broll) {
+		signal?.throwIfAborted();
 		const asset = await verifyBrollPlacementSelection(cwd, placement, signal);
 		normalizedBroll.push({
 			...structuredClone(placement),
@@ -114,7 +148,14 @@ async function validateTimeline(
 			assetSha256: asset.sha256,
 		});
 	}
-	return { outputDurationMs, broll: normalizedBroll };
+	return {
+		outputDurationMs,
+		broll: normalizedBroll,
+		brollCoverage,
+		jumpCuts: continuityPlanReceipt
+			? structuredClone(continuityPlanReceipt.jumpCuts)
+			: analyzeArollJumpCuts(aroll, broll, outputDurationMs, 250, 500),
+	};
 }
 
 function summary(analysis: TranscriptAnalysis) {
@@ -181,6 +222,8 @@ export async function createTalkingHeadProject(cwd: string, input: CreateTalking
 		policy,
 		aroll: analysis.segments,
 		broll: [],
+		brollCoverage: assertBrollCoverageBudget([], analysis.outputDurationMs),
+		jumpCuts: analyzeArollJumpCuts(analysis.segments, [], analysis.outputDurationMs, 250, 500),
 		outputDurationMs: analysis.outputDurationMs,
 	};
 	try {
@@ -248,7 +291,15 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput, sign
 		await assertProjectSourcesUnchanged(cwd, project);
 		await assertSnapshotAssetsUnchanged(cwd, current);
 		assertWordSafeSegments(input.aroll, await getAnalysis(cwd, project));
-		const validated = await validateTimeline(cwd, input.aroll, input.broll, signal);
+		const validated = await validateTimeline(
+			cwd,
+			input.aroll,
+			input.broll,
+			input.projectId,
+			input.expectedRevision,
+			input.continuityPlanReceipt,
+			signal,
+		);
 		const revision = project.currentRevision + 1;
 		const now = new Date().toISOString();
 		const snapshot: TalkingHeadSnapshot = {
@@ -260,6 +311,11 @@ export async function applyTimeline(cwd: string, input: ApplyTimelineInput, sign
 			policy: current.policy,
 			aroll: structuredClone(input.aroll),
 			broll: validated.broll,
+			brollCoverage: validated.brollCoverage,
+			jumpCuts: validated.jumpCuts,
+			...(input.continuityPlanReceipt === undefined
+				? {}
+				: { continuityPlanReceipt: structuredClone(input.continuityPlanReceipt) }),
 			outputDurationMs: validated.outputDurationMs,
 		};
 		await writeJson(join(directory, "snapshots", `${revision}.json`), snapshot, true);