@speclip/pi-subtitles 0.2.2 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@
 ## 能力边界
 
 - 输入：`pi-speech` 兼容的词级 JSON 转录，也兼容常见 `{ word, start, end }` 秒级结构。
-- A-roll 映射：按保留源片段压缩时间轴；字幕不会跨越剪辑点。
+- A-roll 映射：直接读取渲染回执，支持多源、回接、重复片段和实际帧/采样边界；生成、修订及导出均检查剪辑点。
 - 自动分段：结合标点、停顿、字数、时长和阅读速度生成初稿。
 - Agent 审阅：通过不可变 revision 修正 ASR 文本、标点和断句；横屏项目强制单行，审阅阶段也不能绕过。
 - 导出：标准 SRT；可选带横屏/竖屏安全区预设的 ASS；两者都不覆盖已有文件。
@@ -39,6 +39,24 @@ pi install npm:@speclip/pi-subtitles
 
 ### 1. 创建字幕项目
 
+A-roll 已渲染时，优先直接传官方回执和原始转录，不需要自行生成派生转录：
+
+```js
+subtitles_create {
+  projectId: "launch-captions",
+  renderReceiptPath: "analysis/render_receipt.json",
+  transcriptPath: "transcripts/launch.json",
+  layoutPreset: "landscape",
+  protectedPhrases: ["跷跷板"]
+}
+```
+
+回执必须含 `pi-media` 的 `timelineTiming`，工具核对成片和源文件哈希，按实际输出边界映射。回接和重复片段分别保留独立字词 ID；帧取整造成的字尾截短返回 `render-tail-clipped` 听校提示，真正跨原片剪点的词仍会报错。
+
+多个主素材用 `sourceTranscripts: [{ sourcePath, transcriptPath }]` 替代单个 `transcriptPath`，每个主素材恰好绑定一份转录。回执模式不能同时传 `sourceDurationMs` 或 `timelineSegments`。
+
+以下是兼容保留的旧输入方式；它没有经过渲染校验的跨插件时间轴绑定。
+
 无 A-roll 剪辑时，只传源时长：
 
 ```js
@@ -50,7 +68,7 @@ subtitles_create {
 }
 ```
 
-有 A-roll 剪辑时，必须传最终保留的源区间：
+旧模式有剪辑时，传按播放顺序排列的保留源区间，可回接、可重复：
 
 ```js
 subtitles_create {
@@ -89,6 +107,24 @@ subtitles_get {
 
 ### 3. 写入 Agent 审阅版本
 
+优先读取 `subtitles_get { projectId, view: "words", offset: 0, limit: 200 }` 的所有字词页，按稳定 ID 提交完整分组，让工具计算时间：
+
+```js
+subtitles_apply {
+  projectId: "launch-captions",
+  expectedRevision: 1,
+  changeReason: "按语义重新断句，保持全部字词",
+  groups: [
+    { startWordId: "a-001:word-0", endWordId: "a-001:word-8" }
+    // 继续列出全部保留字词，不能只提交一页
+  ]
+}
+```
+
+分组不得遗漏、重复、乱序或跨剪辑片段。可选 `text` 用于标点、空格或听校后的纠错；实质文字变化必须说明 `correctionReason`。工具按组内真实字词时间生成字幕，短字幕仅借用同片段内的静音。`protectedPhrases` 用于初稿的短语保护，原 ASR 多字词也优先保持整体。
+
+`groups` 与下方兼容的完整 `cues` 二选一。直接提交 `cues` 可精确改显示时间，但文字覆盖变化会产生 `text-changed` 提示。所有修订均校验非重叠、片段边界、视频末端和行长。
+
 ```js
 subtitles_apply {
   projectId: "launch-captions",
@@ -102,6 +138,8 @@ subtitles_apply {
 
 `cues` 必须是完整列表，不是某一页。时间必须递增、不重叠，且不能超过成片时长。`expectedRevision` 防止并发审阅互相覆盖；每次成功都会产生新的不可变快照。
 
+`subtitles_get` 同时返回 `findings` 和 `review`。阅读速度、短时显示等是审阅提示；不能用它们掩盖结构错误。`review.text`、`review.sync`、`review.visual` 分别记录听校、同步和视觉结果，可在修订时传 `{ status: "passed", evidence: "实际核对的音频/视频及范围" }`；未提供的项目会重置为 pending。结构通过不代表听校通过。
+
 ### 4. 导出标准轨道
 
 ```js
@@ -119,6 +157,25 @@ subtitles_export {
 
 本包的完成状态是“字幕轨道已生成并校验”，不是“字幕已经烧进视频”。最后应把轨道交给支持字幕的渲染器，并检查实际成片中的同步、遮挡、安全区、字体回退和漏字。
 
+### 5. 预览与烧录交接
+
+导出返回 `subtitleTrack: { sourcePath, format, mode: "burn-in", exportReceiptPath }`（回执模式才有 `exportReceiptPath`）。直接放入 `pi-media` 的 timeline `edit_apply`，保留其他编辑字段。渲染器核对轨道哈希和主音频时间轴指纹；B-roll/BGM 调整不改变该指纹，主素材、源区间、顺序或输出帧率改变则拒绝旧字幕。
+
+先用支持新接口的 `pi-media` 生成抽样证据：
+
+```js
+media_subtitle_preview {
+  videoPath: "deliverables/clean.mp4",
+  exportReceiptPath: ".subtitles/projects/launch-captions/exports/<exportId>.json",
+  sampleTimesSeconds: [5, 55, 77],
+  clip: { startSeconds: 54, durationSeconds: 4 }
+}
+```
+
+选择视频内 1–6 个时间点，短视频最长 15 秒。返回 PNG、可听短视频、字体选择日志和报告路径；视觉与同步状态保持 pending，由实际查看/听校后更新。最终视频仍需 `render` + `review`。字幕渲染环境需有 libass；可用 `PI_MEDIA_SUBTITLE_FFMPEG_BINARY` 指定二进制。
+
+内部保留精确毫秒，导出时 SRT 量化为毫秒、ASS 为厘秒，且时间不能越过镜头边界。格式精度导致零时长时明确失败，不静默输出坏字幕。
+
 ## 工作区数据
 
 项目状态保存在：
@@ -126,11 +183,12 @@ subtitles_export {
 ```text
 .subtitles/projects/<projectId>/
 ├── project.json
+├── words.json                 # 不可变字词映射、源字词位置、片段边界与诊断
 ├── snapshots/<revision>.json
 └── exports/<exportId>.json
 ```
 
-源转录与导出文件都不会被覆盖。源转录字节变化后，旧项目会拒绝继续导出，避免把新内容误配到旧时间轴。
+新字段均为可选字段，旧项目与原有四个工具仍兼容；升级不会原地改写旧项目。源转录与导出文件都不会被覆盖。源转录字节变化后，旧项目会拒绝继续导出，避免把新内容误配到旧时间轴。
 
 ## 开发
 

package/extensions/subtitles/index.ts

@@ -5,6 +5,7 @@ import {
 	createSubtitleProject,
 	exportSubtitleProject,
 	getSubtitleProject,
+	getProjectWords,
 } from "../../src/project.ts";
 
 function result(details: unknown) {
@@ -60,6 +61,8 @@ const assStyle = Type.Object({
 	marginV: Type.Optional(Type.Integer({ minimum: 0, maximum: 4_000 })),
 }, { additionalProperties: false });
 
+const reviewEvidence = Type.Object({ status: Type.Union([Type.Literal("pending"), Type.Literal("passed")]), evidence: Type.Optional(Type.String({ minLength: 1, maxLength: 2000 })) }, { additionalProperties: false });
+
 export default function subtitles(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "subtitles_create",
@@ -67,8 +70,11 @@ export default function subtitles(pi: ExtensionAPI): void {
 		description: "Create an immutable workspace subtitle project from a word-timestamp JSON transcript. Optionally remaps retained A-roll source segments onto the final edited timeline, then generates readable cue groups. Landscape is the default and strictly remains single-line.",
 		parameters: Type.Object({
 			projectId: Type.String({ minLength: 1, maxLength: 128, pattern: "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$" }),
-			transcriptPath: Type.String({ minLength: 1, description: "Existing workspace-relative word-timestamp JSON from pi-speech or a compatible ASR." }),
-			sourceDurationMs: Type.Number({ exclusiveMinimum: 0 }),
+			transcriptPath: Type.Optional(Type.String({ minLength: 1, description: "Existing workspace-relative word-timestamp JSON; single primary source only." })),
+				renderReceiptPath: Type.Optional(Type.String({ minLength: 1, description: "Exact pi-media render receipt with timelineTiming. Preferred after A-roll editing; mutually exclusive with sourceDurationMs/timelineSegments." })),
+				sourceTranscripts: Type.Optional(Type.Array(Type.Object({ sourcePath: Type.String({ minLength: 1 }), transcriptPath: Type.String({ minLength: 1 }) }, { additionalProperties: false }), { minItems: 1, maxItems: 1000 })),
+				protectedPhrases: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 80 }), { maxItems: 200 })),
+			sourceDurationMs: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
 			layoutPreset: Type.Optional(Type.Union([
 				Type.Literal("landscape"),
 				Type.Literal("portrait"),
@@ -76,7 +82,7 @@ export default function subtitles(pi: ExtensionAPI): void {
 			timelineSegments: Type.Optional(Type.Array(timelineSegment, {
 				minItems: 1,
 				maxItems: 1_000,
-				description: "Ordered retained A-roll source ranges. Omit only when the final timeline is identical to the source.",
+				description: "Legacy ranges in playback order, including reordered/repeated source ranges. Prefer renderReceiptPath for frame-accurate editing.",
 			})),
 			policy: Type.Optional(policy),
 		}, { additionalProperties: false }),
@@ -97,19 +103,25 @@ export default function subtitles(pi: ExtensionAPI): void {
 		parameters: Type.Object({
 			projectId: Type.String({ minLength: 1, maxLength: 128 }),
 			revision: Type.Optional(Type.Integer({ minimum: 1 })),
+				view: Type.Optional(Type.Union([Type.Literal("cues"), Type.Literal("words")], { description: "words returns stable occurrence IDs for complete word-group review." })),
 			offset: Type.Optional(Type.Integer({ minimum: 0, default: 0 })),
 			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 200, default: 100 })),
 		}, { additionalProperties: false }),
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			signal?.throwIfAborted();
 			const loaded = await getSubtitleProject(ctx.cwd, params.projectId, params.revision);
+			const mapped = params.view === "words" ? await getProjectWords(ctx.cwd, loaded.project) : undefined;
+			const items = mapped?.words ?? loaded.snapshot.cues;
 			const offset = params.offset ?? 0;
 			const limit = params.limit ?? 100;
 			return result({
 				project: loaded.project,
 				revision: loaded.snapshot.revision,
 				snapshotSha256: loaded.snapshot.snapshotSha256,
-				total: loaded.snapshot.cues.length,
+				total: items.length,
+					view: params.view ?? "cues",
+					review: loaded.snapshot.review,
+					findings: loaded.snapshot.findings,
 				offset,
 				limit,
 				hasMore: offset + limit < loaded.snapshot.cues.length,
@@ -121,11 +133,17 @@ export default function subtitles(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "subtitles_apply",
 		label: "Apply subtitle review",
-		description: "Create a new immutable subtitle revision from a complete Agent-reviewed cue list. Uses optimistic locking and requires a human-readable change reason.",
+		description: "Create a new immutable subtitle revision from complete word groups (preferred; automatic timing and coverage checks) or a full cue list. Uses optimistic locking and requires a human-readable change reason.",
 		parameters: Type.Object({
 			projectId: Type.String({ minLength: 1, maxLength: 128 }),
 			expectedRevision: Type.Integer({ minimum: 1 }),
-			cues: Type.Array(subtitleCue, { minItems: 1, maxItems: 10_000 }),
+			cues: Type.Optional(Type.Array(subtitleCue, { minItems: 1, maxItems: 10_000 })),
+				groups: Type.Optional(Type.Array(Type.Object({
+					startWordId: Type.String({ minLength: 1 }), endWordId: Type.String({ minLength: 1 }),
+					text: Type.Optional(Type.String({ minLength: 1, maxLength: 2000 })),
+					correctionReason: Type.Optional(Type.String({ minLength: 1, maxLength: 2000 })),
+				}, { additionalProperties: false }), { minItems: 1, maxItems: 10000, description: "Complete ordered word ranges; timing is computed by the tool. Mutually exclusive with cues." })),
+				review: Type.Optional(Type.Object({ text: Type.Optional(reviewEvidence), sync: Type.Optional(reviewEvidence), visual: Type.Optional(reviewEvidence) }, { additionalProperties: false })),
 			changeReason: Type.String({ minLength: 1, maxLength: 2_000 }),
 		}, { additionalProperties: false }),
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclip/pi-subtitles",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Agent-reviewed subtitle timing, layout, and standard track export for Pi",
   "type": "module",
   "license": "MIT",

package/prompts/add-subtitles.md

@@ -5,3 +5,5 @@ description: Add reviewed subtitles to an edited talking-head video
 Use the `add-subtitles` skill to map a word-level transcript onto the final A-roll timeline, inspect every generated cue page, preserve spoken meaning, apply only evidence-backed text or grouping corrections, and export an exact SRT plus optional ASS track for this request: $@
 
 Finish A-roll first. Do not time subtitles from B-roll assets, submit a partial cue page as a complete revision, overwrite existing tracks, or claim that the video contains subtitles until a renderer has applied and visually reviewed the exported track.
+
+Prefer renderReceiptPath with original transcripts, then word-ID groups for review. Let tools compute timing and validate coverage. Use media_subtitle_preview for sample images/font logs and a short audio/video clip, then hand the returned subtitleTrack to pi-media. Keep text, sync and visual review status separate.

package/skills/add-subtitles/SKILL.md

@@ -5,18 +5,17 @@ description: Build and review subtitles from word-level ASR timestamps after A-r
 
 # Add subtitles
 
-Use `pi-speech` for word timestamps and this package for final-timeline mapping, readable cue decisions, Agent review, and standard subtitle track export.
+Use `pi-speech` for word timestamps, `pi-subtitles` for timing and review, and `pi-media` for subtitle previews and final rendering.
 
-1. Finish the A-roll edit before creating subtitles. Obtain the exact source duration and the ordered retained A-roll source ranges. B-roll overlays do not change subtitle timing while the primary A-roll audio remains unchanged.
-2. Use a `pi-speech`-compatible JSON transcript with word-level `beginMs` and `endMs`. Do not derive cue timing from sentence text, a summary, or B-roll asset timestamps.
-3. Call `subtitles_create` once. Set `layoutPreset` to `landscape` or `portrait`; it defaults to `landscape`. Pass `timelineSegments` when A-roll has cuts; omit it only when the final timeline is identical to the source. Each retained range must end on a word-safe edit boundary. The tool rejects a word that straddles a cut.
-4. Treat the generated cues as a proposal. Read every page with `subtitles_get`; do not review only the first page. Check the words against the spoken audio, then check punctuation, semantic grouping, reading speed, line breaks, and whether a cue crosses an editorial thought boundary.
-5. Keep speech meaning intact. Correct ASR spelling or punctuation only with audio evidence. Do not delete content merely to make a line shorter. Preserve intentional fillers, emphasis, terminology, numbers, names, and sentence-ending tone.
-6. Prefer one complete idea per cue and natural boundaries at strong punctuation or acoustic pauses. Landscape captions are always one line and must be split into another timed cue when too long; never insert `\n`. Portrait captions may use at most two balanced lines. Avoid one-character orphan cues and rapid flashes. Do not force every cue to an identical duration; subtitle timing follows the actual delivery rhythm.
-7. If edits are needed, gather the complete cue list across all pages and call `subtitles_apply` with the current `expectedRevision` and a concrete `changeReason`. Never submit one paginated slice as if it were the full revision. If the revision changed, re-read and reconcile instead of overwriting another review.
-8. Call `subtitles_export` with the exact reviewed revision. SRT is the portable timing/text track. Request ASS for final burn-in: both layouts use `Source Han Sans SC Heavy`, white glyphs without a black outline, and a softened semi-transparent black shadow offset down and right. Do not replace `PlayRes` with the source video's 4K resolution. Verify that the renderer really resolves this font instead of silently falling back.
-9. Keep rendering explicit. This package does not burn subtitles into video and does not invent FFmpeg arguments. Hand the returned SRT or ASS artifact and provenance receipt to a renderer that supports subtitle tracks, then visually review the actual final video for safe-area placement, occlusion, glyph fallback, sync, and missing text.
+1. Finish A-roll and obtain the official render receipt containing `timelineTiming`. Use `subtitles_create` with `renderReceiptPath` and the ORIGINAL `transcriptPath`. For multiple primary sources, pass `sourceTranscripts: [{ sourcePath, transcriptPath }]` instead. Do not copy time ranges, recalculate frame rounding, manufacture a derived transcript, or change playback order to satisfy the subtitle tool. The receipt importer handles reordered and repeated clips, actual frame/sample boundaries and source provenance.
+2. Without an edited render receipt, the legacy `transcriptPath` + `sourceDurationMs` + optional `timelineSegments` input remains available. Ranges are in playback order. Do not combine these timing inputs with `renderReceiptPath`. Legacy projects have no verified renderer handoff binding.
+3. Choose `landscape` (default, one line) or `portrait` (up to two lines). Add `protectedPhrases` for known phrases that must not be split. These phrases must fit the layout; they do not correct transcription.
+4. Read ALL cue pages using `subtitles_get`, inspect `findings`, and check spoken words, terminology, punctuation and semantic grouping against audio. Automatic grouping and structural checks do not establish text accuracy or sync. A `render-tail-clipped` finding means actual rendering shortened a word; listen to that join. A real source cut through a word is an error requiring an edit correction.
+5. Prefer `subtitles_get` with `view: "words"` when regrouping. Read all pages, then submit the complete ordered `groups` list to `subtitles_apply`: each group contains `startWordId` and `endWordId`. The tool calculates timing, checks full word coverage, and extends short cues only within the same clip's available silence. Do not write Python to match text to timestamps. Word IDs identify clip occurrences, including repeated use of a source word.
+6. A group's optional `text` adjusts punctuation/spacing or corrects spoken text. Changes beyond punctuation/spacing require `correctionReason` supported by audio. Preserve meaning, fillers, emphasis, terms and numbers. Never delete words merely to make a shorter cue. The complete legacy `cues` input remains available for precise timing edits; its text-change findings require review. Never submit one page as a full revision. Use `expectedRevision` and a concrete `changeReason`; reconcile concurrent revisions.
+7. Review dimensions are separate: `review.text`, `review.sync`, `review.visual`. Each is `pending` or `passed`; `passed` requires concrete `evidence`. A new revision resets unspecified dimensions to pending. Do not report a pass if you cannot actually hear or view the relevant output. Structural validation runs automatically at creation, apply and export.
+8. Export the exact revision with `subtitles_export`, requesting ASS for styling and burn-in. Both layouts use Source Han Sans SC Heavy with white glyphs and a softened shadow. Keep canonical ASS PlayRes rather than changing it to the input resolution. The exporter quantizes SRT/ASS within edit and video boundaries, and rejects timing that would collapse at format precision.
+9. Call `media_subtitle_preview` with the clean `videoPath`, the returned `receipt.receiptPath` as `exportReceiptPath`, 1–6 `sampleTimesSeconds`, and optionally `clip: { startSeconds, durationSeconds }` (up to 15 seconds). Inspect images, actual font-resolution logs and the audio/video clip. Preview generation leaves sync/visual approval pending. If the runtime lacks libass, report the actionable configuration error instead of writing ad hoc FFmpeg scripts.
+10. For final burn-in, pass the exported `subtitleTrack` object unchanged into the existing pi-media timeline's `edit_apply`, preserving the other timeline fields. Its `exportReceiptPath` binds the track hash and primary timeline. B-roll overlays can change; A-roll source/range/order/frame-rate changes require remapping. Then `render` and `review` the precise edit revision and inspect/listen to the result. Independent tracks and sample previews are not a completed burned video.
 
-Never overwrite a transcript, subtitle track, or render. If the transcript hash changes, create a new subtitle project so timing decisions stay reproducible.
-
-Read [timing and layout](references/timing-and-layout.md) when reviewing dense, fast, bilingual, or unusually sparse speech.
+Never overwrite source transcripts, tracks or renders. Transcript or primary timeline changes require a new subtitle project. Read [timing and layout](references/timing-and-layout.md) for dense or bilingual speech.

package/skills/add-subtitles/references/timing-and-layout.md

@@ -5,9 +5,11 @@
 For a retained A-roll source range, final cue time is:
 
 ```text
-final_time = accumulated_retained_duration + source_word_time - range_source_start
+final_time = receipt.outputStartSeconds * 1000 + source_word_time - range_source_start
 ```
 
+Use actual receipt output frame/sample boundaries. Do not accumulate requested source durations after rendering, and do not stretch all words to fit frame rounding: pi-media pads or trims the tail without changing speech speed. Small rendered-tail truncations produce findings; real source-word cuts remain errors.
+
 A cut is also a subtitle boundary. Even when the two retained words become adjacent in the final video, a cue must not bridge across the edit because it can expose removed language or create misleading timing.
 
 ## Talking-head layout policy

package/src/contracts.ts

@@ -9,10 +9,43 @@ export interface TimelineSegment {
 	id: string;
 	sourceStartMs: number;
 	sourceEndMs: number;
+	sourcePath?: string;
+	outputStartMs?: number;
+	outputEndMs?: number;
 }
 
 export interface TimelineWord extends TranscriptWord {
 	timelineSegmentId?: string;
+	id?: string;
+	sourceWordIndex?: number;
+	sourceBeginMs?: number;
+	sourceEndMs?: number;
+	timelineSegmentEndMs?: number;
+}
+
+export interface SubtitleFinding {
+	code: string;
+	severity: "warning" | "info";
+	message: string;
+	cueId?: string;
+}
+
+export interface WordGroup {
+	startWordId: string;
+	endWordId: string;
+	text?: string;
+	correctionReason?: string;
+}
+
+export interface ReviewEvidence {
+	status: "pending" | "passed";
+	evidence?: string;
+}
+
+export interface SubtitleReview {
+	text?: ReviewEvidence;
+	sync?: ReviewEvidence;
+	visual?: ReviewEvidence;
 }
 
 export interface SubtitlePolicy {
@@ -76,6 +109,15 @@ export interface SubtitleProject {
 	transcript: FileRef;
 	timelineSegments: TimelineSegment[];
 	policy: SubtitlePolicy;
+	wordMap?: FileRef;
+	sources?: Array<{ source: FileRef; transcript: FileRef }>;
+	renderBinding?: {
+		receipt: FileRef;
+		video: FileRef;
+		projectId: string;
+		snapshotRevision: number;
+		primaryTimelineSha256: string;
+	};
 }
 
 export interface SubtitleSnapshot {
@@ -86,6 +128,9 @@ export interface SubtitleSnapshot {
 	createdAt: string;
 	changeReason: string;
 	cues: SubtitleCue[];
+	groups?: WordGroup[];
+	review?: SubtitleReview;
+	findings?: SubtitleFinding[];
 	snapshotSha256: string;
 }
 
@@ -97,6 +142,10 @@ export interface SubtitleExportReceipt {
 	createdAt: string;
 	snapshotSha256: string;
 	tracks: { srt: FileRef; ass?: FileRef };
+	primaryTimelineSha256?: string;
+	video?: FileRef;
+	review?: SubtitleReview;
+	structure?: "passed";
 	receiptPath: string;
 	receiptSha256: string;
 }

package/src/cues.ts

@@ -4,6 +4,7 @@ import type {
 	TimelineSegment,
 	TimelineWord,
 	TranscriptWord,
+	SubtitleFinding,
 } from "./contracts.ts";
 
 export const DEFAULT_SUBTITLE_POLICY: SubtitlePolicy = {
@@ -49,39 +50,54 @@ function validateWords(words: TranscriptWord[]): void {
 
 function validateTimeline(segments: TimelineSegment[]): void {
 	if (segments.length === 0) throw new Error("Timeline must retain at least one A-roll segment");
-	let previousEnd = -1;
+	let previousEnd = segments[0]?.outputStartMs ?? 0;
 	const ids = new Set<string>();
 	for (const segment of segments) {
 		if (!segment.id || ids.has(segment.id) || !finiteNonNegative(segment.sourceStartMs)
 			|| !finiteNonNegative(segment.sourceEndMs) || segment.sourceEndMs <= segment.sourceStartMs) {
 			throw new Error("Timeline contains an invalid or duplicate segment");
 		}
-		if (segment.sourceStartMs < previousEnd) throw new Error("Timeline source segments overlap or are out of order");
+		if ((segment.outputStartMs === undefined) !== (segment.outputEndMs === undefined)) throw new Error("Timeline output range must have both endpoints");
+		if (segment.outputStartMs !== undefined && (!finiteNonNegative(segment.outputStartMs)
+			|| !finiteNonNegative(segment.outputEndMs) || segment.outputEndMs <= segment.outputStartMs
+			|| Math.abs(segment.outputStartMs - previousEnd) > 0.001)) throw new Error("Timeline output ranges must be contiguous in playback order");
 		ids.add(segment.id);
-		previousEnd = segment.sourceEndMs;
+		previousEnd = segment.outputEndMs ?? previousEnd + segment.sourceEndMs - segment.sourceStartMs;
 	}
 }
 
-export function remapWordsToTimeline(words: TranscriptWord[], segments: TimelineSegment[]): TimelineWord[] {
+export function remapWordsToTimeline(words: TranscriptWord[], segments: TimelineSegment[], findings: SubtitleFinding[] = []): TimelineWord[] {
 	validateWords(words);
 	validateTimeline(segments);
 	const remapped: TimelineWord[] = [];
 	let outputOffsetMs = 0;
 	for (const segment of segments) {
-		for (const word of words) {
+		const outputStart = segment.outputStartMs ?? outputOffsetMs;
+		const outputEnd = segment.outputEndMs ?? outputStart + segment.sourceEndMs - segment.sourceStartMs;
+		for (const [wordIndex, word] of words.entries()) {
 			const overlaps = word.beginMs < segment.sourceEndMs && word.endMs > segment.sourceStartMs;
 			if (!overlaps) continue;
-			if (word.beginMs < segment.sourceStartMs || word.endMs > segment.sourceEndMs) {
-				throw new Error(`Word timestamp crosses A-roll edit boundary: ${word.text}`);
+			if (word.beginMs < segment.sourceStartMs - 0.001 || word.endMs > segment.sourceEndMs + 0.001) {
+				throw new Error(`Word timestamp crosses A-roll edit boundary: ${segment.id}, word ${wordIndex} (${word.text}), ${word.beginMs}–${word.endMs}ms`);
 			}
+			const beginMs = Math.max(outputStart, outputStart + word.beginMs - segment.sourceStartMs);
+			const rawEnd = outputStart + word.endMs - segment.sourceStartMs;
+			const endMs = Math.min(outputEnd, rawEnd);
+			if (endMs <= beginMs) throw new Error(`Rendered segment ${segment.id} removes word ${wordIndex} (${word.text}); adjust the edit boundary`);
+			if (rawEnd > outputEnd + 0.001) findings.push({ code: "render-tail-clipped", severity: "warning", message: `${segment.id}: ${word.text} shortened by ${rawEnd - outputEnd}ms by rendered timing; listen to the boundary` });
 			remapped.push({
 				...word,
-				beginMs: outputOffsetMs + word.beginMs - segment.sourceStartMs,
-				endMs: outputOffsetMs + word.endMs - segment.sourceStartMs,
+				id: `${segment.id}:word-${wordIndex}`,
+				sourceWordIndex: wordIndex,
+				sourceBeginMs: word.beginMs,
+				sourceEndMs: word.endMs,
+				beginMs,
+				endMs,
 				timelineSegmentId: segment.id,
+				timelineSegmentEndMs: outputEnd,
 			});
 		}
-		outputOffsetMs += segment.sourceEndMs - segment.sourceStartMs;
+		outputOffsetMs = outputEnd;
 	}
 	return remapped;
 }
@@ -105,12 +121,13 @@ function splitTiming(word: TimelineWord, policy: SubtitlePolicy): TimedToken[] {
 				punctuation: "",
 			}, policy);
 			if (nested[0] && start > 0) nested[0].spaceBefore = true;
+			if (nested.at(-1) && match === matches.at(-1)) nested.at(-1)!.text += word.punctuation;
 			return nested;
 		});
 	}
 	const asciiWord = isAsciiWord(text);
-	const mustSplit = [...text].length > policy.maxLineChars * policy.maxLines || durationMs > policy.maxDurationMs;
-	const units = asciiWord && !mustSplit ? [text] : [...text];
+	const mustSplit = visibleChars(text + word.punctuation) > policy.maxLineChars * policy.maxLines || durationMs > policy.maxDurationMs;
+	const units = !mustSplit ? [text] : [...text];
 	const stepMs = durationMs / units.length;
 	return units.map((unit, index) => ({
 		text: `${unit}${index === units.length - 1 ? word.punctuation : ""}`,
@@ -233,23 +250,45 @@ export function buildSubtitleCues(
 	words: TimelineWord[],
 	timelineEndMs: number,
 	policy: Partial<SubtitlePolicy> = {},
+	protectedPhrases: string[] = [],
 ): SubtitleCue[] {
 	if (!finiteNonNegative(timelineEndMs)) throw new Error("timelineEndMs must be non-negative");
 	validateWords(words);
 	const resolved = { ...DEFAULT_SUBTITLE_POLICY, ...policy };
+	if (protectedPhrases.some(p => !p.trim() || visibleChars(p) > resolved.maxLineChars * resolved.maxLines)) throw new Error("Protected phrase must fit the subtitle layout");
 	const groups: TimelineWord[][] = [];
 	for (const word of words) {
 		const previous = groups.at(-1);
 		if (!previous || previous[0]!.timelineSegmentId !== word.timelineSegmentId) groups.push([word]);
 		else previous.push(word);
 	}
-	const raw = groups.flatMap((group) => buildGroup(group.flatMap((word) => splitTiming(word, resolved)), resolved));
+	const raw = groups.flatMap((group) => buildGroup(protectPhrases(group, protectedPhrases).flatMap((word) => splitTiming(word, resolved)), resolved)
+		.map((cue) => ({ ...cue, segmentEnd: group[0]!.timelineSegmentEndMs ?? timelineEndMs })));
 	return raw.map((cue, index) => {
-		const nextStart = raw[index + 1]?.beginMs ?? Math.max(cue.endMs, timelineEndMs);
+		const nextStart = Math.min(raw[index + 1]?.beginMs ?? timelineEndMs, cue.segmentEnd, timelineEndMs);
 		return {
 			id: `cue-${String(index + 1).padStart(3, "0")}`,
-			...cue,
+			beginMs: cue.beginMs,
+			text: cue.text,
 			endMs: Math.max(cue.endMs, Math.min(cue.beginMs + resolved.minDurationMs, cue.beginMs + resolved.maxDurationMs, nextStart)),
 		};
 	});
 }
+
+function protectPhrases(words: TimelineWord[], phrases: string[]): TimelineWord[] {
+	const result: TimelineWord[] = [];
+	for (let i = 0; i < words.length; i++) {
+		let matchEnd = i;
+		for (const phrase of phrases) {
+			let text = "";
+			for (let end = i; end < words.length && text.length < phrase.length; end++) {
+				text += words[end]!.text;
+				if (text === phrase) matchEnd = Math.max(matchEnd, end);
+				if (words[end]!.punctuation) break;
+			}
+		}
+		result.push({ ...words[i]!, text: words.slice(i, matchEnd + 1).map(w => w.text).join(""), endMs: words[matchEnd]!.endMs, punctuation: words[matchEnd]!.punctuation });
+		i = matchEnd;
+	}
+	return result;
+}

package/src/export.ts

@@ -1,4 +1,5 @@
-import type { AssStyle, FileRef, SubtitleCue, SubtitleLayoutPreset } from "./contracts.ts";
+import type { AssStyle, FileRef, SubtitleCue, SubtitleLayoutPreset, SubtitleProject } from "./contracts.ts";
+import { segmentRanges, validateCues } from "./validation.ts";
 import { rm } from "node:fs/promises";
 import { resolveExistingWorkspaceFile, writeNewWorkspaceFile } from "./workspace.ts";
 
@@ -87,7 +88,7 @@ function assertCues(cues: SubtitleCue[]): void {
 }
 
 export function renderSrt(cues: SubtitleCue[]): string {
-	assertCues(cues);
+	cues = quantizeCues(cues, 1);
 	return `${cues.map((cue, index) => `${index + 1}\n${srtTime(cue.beginMs)} --> ${srtTime(cue.endMs)}\n${cue.text}`).join("\n\n")}\n`;
 }
 
@@ -96,7 +97,7 @@ function assText(value: string): string {
 }
 
 export function renderAss(cues: SubtitleCue[], style: Partial<AssStyle> = {}): string {
-	assertCues(cues);
+	cues = quantizeCues(cues, 10);
 	const resolved = { ...DEFAULT_ASS_STYLE, ...style };
 	const header = `[Script Info]\nScriptType: v4.00+\nPlayResX: ${resolved.playResX}\nPlayResY: ${resolved.playResY}\nWrapStyle: 2\nScaledBorderAndShadow: yes\n\n[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\nStyle: Default,${resolved.fontName},${resolved.fontSize},${resolved.primaryColour},${resolved.primaryColour},${resolved.outlineColour},${resolved.shadowColour},${resolved.bold ? -1 : 0},0,0,0,100,100,0,0,1,${resolved.outline},${resolved.shadow},${resolved.alignment},${resolved.marginL},${resolved.marginR},${resolved.marginV},1\n\n[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text`;
 	const blur = resolved.blur > 0 ? `{\\blur${resolved.blur}}` : "";
@@ -107,18 +108,36 @@ export function renderAss(cues: SubtitleCue[], style: Partial<AssStyle> = {}): s
 export async function exportSubtitleTracks(
 	cwd: string,
 	cues: SubtitleCue[],
-	input: { srtPath: string; assPath?: string; assStyle?: Partial<AssStyle> },
+	input: { srtPath: string; assPath?: string; assStyle?: Partial<AssStyle>; project?: SubtitleProject },
 ): Promise<{ srt: FileRef; ass?: FileRef }> {
 	assertCues(cues);
 	if (!input.srtPath.toLowerCase().endsWith(".srt")) throw new Error("srtPath must end in .srt");
 	if (input.assPath !== undefined && !input.assPath.toLowerCase().endsWith(".ass")) throw new Error("assPath must end in .ass");
-	const srt = await writeNewWorkspaceFile(cwd, input.srtPath, renderSrt(cues), "application/x-subrip; charset=utf-8");
+	const srtText = renderSrt(quantizeCues(cues, 1, input.project));
+	const assText = input.assPath ? renderAss(quantizeCues(cues, 10, input.project), input.assStyle) : undefined;
+	const srt = await writeNewWorkspaceFile(cwd, input.srtPath, srtText, "application/x-subrip; charset=utf-8");
 	if (!input.assPath) return { srt };
 	try {
-		const ass = await writeNewWorkspaceFile(cwd, input.assPath, renderAss(cues, input.assStyle), "text/x-ssa; charset=utf-8");
+		const ass = await writeNewWorkspaceFile(cwd, input.assPath, assText!, "text/x-ssa; charset=utf-8");
 		return { srt, ass };
 	} catch (error) {
 		await rm(await resolveExistingWorkspaceFile(cwd, srt.path), { force: true });
 		throw error;
 	}
 }
+
+export function quantizeCues(cues: SubtitleCue[], unitMs: number, project?: SubtitleProject): SubtitleCue[] {
+	assertCues(cues);
+	if (project) validateCues(cues, project);
+	const ranges = project ? segmentRanges(project.timelineSegments) : [];
+	const rounded = cues.map(c => {
+		const range = ranges.find(s => c.beginMs >= s.beginMs && c.endMs <= s.endMs);
+		return { ...c,
+			beginMs: Math.max(Math.round(c.beginMs / unitMs) * unitMs, range ? Math.ceil(range.beginMs / unitMs) * unitMs : 0),
+			endMs: Math.min(Math.round(c.endMs / unitMs) * unitMs, range ? Math.floor(range.endMs / unitMs) * unitMs : Infinity),
+		};
+	});
+	try { assertCues(rounded); } catch { throw new Error(`Subtitle timing cannot be represented at ${unitMs}ms precision without overlap or zero duration`); }
+	if (project) validateCues(rounded, project);
+	return rounded;
+}

package/src/project.ts

@@ -1,6 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { importRenderTimeline, parseTranscript } from "./timeline.ts";
+import type { SourceTranscriptInput } from "./timeline.ts";
+import { validateCues, validateReview, cuesFromGroups, textCoverageFinding } from "./validation.ts";
 import { buildSubtitleCues, DEFAULT_SUBTITLE_POLICY, remapWordsToTimeline } from "./cues.ts";
 import type {
 	AssStyle,
@@ -11,9 +14,12 @@ import type {
 	SubtitleLayoutPreset,
 	SubtitleSnapshot,
 	TimelineSegment,
-	TranscriptWord,
+	TimelineWord,
+	WordGroup,
+	SubtitleReview,
+	SubtitleFinding,
 } from "./contracts.ts";
-import { exportSubtitleTracks, renderSrt, resolveAssStyle } from "./export.ts";
+import { exportSubtitleTracks, resolveAssStyle } from "./export.ts";
 import {
 	readWorkspaceJson,
 	resolveExistingWorkspaceFile,
@@ -24,15 +30,13 @@ import {
 
 const PROJECT_ID = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/u;
 
-interface RawTranscript {
-	words?: unknown[];
-	sentences?: Array<{ words?: unknown[] }>;
-}
-
 export interface CreateSubtitleProjectInput {
 	projectId: string;
-	transcriptPath: string;
-	sourceDurationMs: number;
+	transcriptPath?: string;
+	sourceDurationMs?: number;
+	renderReceiptPath?: string;
+	sourceTranscripts?: SourceTranscriptInput[];
+	protectedPhrases?: string[];
 	layoutPreset?: SubtitleLayoutPreset;
 	timelineSegments?: TimelineSegment[];
 	policy?: Partial<SubtitlePolicy>;
@@ -41,7 +45,9 @@ export interface CreateSubtitleProjectInput {
 export interface ApplySubtitleRevisionInput {
 	projectId: string;
 	expectedRevision: number;
-	cues: SubtitleCue[];
+	cues?: SubtitleCue[];
+	groups?: WordGroup[];
+	review?: SubtitleReview;
 	changeReason: string;
 }
 
@@ -67,32 +73,6 @@ function projectRelative(projectId: string, path = ""): string {
 	return `.subtitles/projects/${projectId}${path ? `/${path}` : ""}`;
 }
 
-function normalizedWord(value: unknown): TranscriptWord | undefined {
-	if (!value || typeof value !== "object") return undefined;
-	const item = value as Record<string, unknown>;
-	const text = typeof item.text === "string" ? item.text : typeof item.word === "string" ? item.word : undefined;
-	const beginMs = typeof item.beginMs === "number" ? item.beginMs : typeof item.start === "number" ? item.start * 1_000 : undefined;
-	const endMs = typeof item.endMs === "number" ? item.endMs : typeof item.end === "number" ? item.end * 1_000 : undefined;
-	if (!text || beginMs === undefined || endMs === undefined) return undefined;
-	const trimmed = text.trim();
-	if (!trimmed || /^(?:<sil>|\[sil\])$/iu.test(trimmed)) return undefined;
-	return {
-		text: trimmed,
-		beginMs,
-		endMs,
-		punctuation: typeof item.punctuation === "string" ? item.punctuation : "",
-	};
-}
-
-function transcriptWords(transcript: RawTranscript): TranscriptWord[] {
-	const raw = Array.isArray(transcript.sentences)
-		? transcript.sentences.flatMap((sentence) => Array.isArray(sentence.words) ? sentence.words : [])
-		: Array.isArray(transcript.words) ? transcript.words : [];
-	const words = raw.map(normalizedWord).filter((word): word is TranscriptWord => word !== undefined);
-	if (words.length === 0) throw new Error("Transcript contains no usable word timestamps");
-	return words;
-}
-
 function validateSourceAndTimeline(sourceDurationMs: number, timelineSegments: TimelineSegment[]): void {
 	if (!Number.isFinite(sourceDurationMs) || sourceDurationMs <= 0) throw new Error("sourceDurationMs must be positive");
 	if (timelineSegments.some((segment) => segment.sourceEndMs > sourceDurationMs)) {
@@ -101,6 +81,8 @@ function validateSourceAndTimeline(sourceDurationMs: number, timelineSegments: T
 }
 
 function resolvedPolicy(layoutPreset: SubtitleLayoutPreset, input: Partial<SubtitlePolicy> | undefined): SubtitlePolicy {
+	if (layoutPreset !== "landscape" && layoutPreset !== "portrait") throw new Error("Invalid subtitle layout preset");
+	if (layoutPreset === "portrait" && input?.maxLines !== undefined && input.maxLines > 2) throw new Error("Portrait subtitles allow at most two lines");
 	if (layoutPreset === "landscape" && input?.maxLines !== undefined && input.maxLines !== 1) {
 		throw new Error("Landscape subtitles must use one line");
 	}
@@ -124,7 +106,7 @@ function timelineDuration(segments: TimelineSegment[]): number {
 	return segments.reduce((total, segment) => total + segment.sourceEndMs - segment.sourceStartMs, 0);
 }
 
-function snapshot(projectId: string, revision: number, parentRevision: number | null, cues: SubtitleCue[], changeReason: string): SubtitleSnapshot {
+function snapshot(projectId: string, revision: number, parentRevision: number | null, cues: SubtitleCue[], changeReason: string, extras: Pick<SubtitleSnapshot, "groups" | "review" | "findings"> = {}): SubtitleSnapshot {
 	const base = {
 		schemaVersion: 1 as const,
 		projectId,
@@ -133,6 +115,7 @@ function snapshot(projectId: string, revision: number, parentRevision: number |
 		createdAt: new Date().toISOString(),
 		changeReason,
 		cues,
+		...extras,
 	};
 	return { ...base, snapshotSha256: sha256Json(base) };
 }
@@ -151,15 +134,22 @@ async function writeInternalJson(cwd: string, relativePath: string, value: unkno
 
 export async function createSubtitleProject(cwd: string, input: CreateSubtitleProjectInput) {
 	assertProjectId(input.projectId);
-	const transcript = await snapshotExistingWorkspaceFile(cwd, input.transcriptPath, "application/json");
-	const rawTranscript = await readWorkspaceJson<RawTranscript>(cwd, input.transcriptPath, "word transcript");
-	const segments = input.timelineSegments ?? [{ id: "a-1", sourceStartMs: 0, sourceEndMs: input.sourceDurationMs }];
-	validateSourceAndTimeline(input.sourceDurationMs, segments);
-	const durationMs = timelineDuration(segments);
+	if (input.renderReceiptPath && (input.timelineSegments || input.sourceDurationMs !== undefined)) throw new Error("renderReceiptPath is mutually exclusive with legacy timelineSegments/sourceDurationMs");
+	const imported = input.renderReceiptPath ? await importRenderTimeline(cwd, input.renderReceiptPath, input.transcriptPath, input.sourceTranscripts) : undefined;
+	if (!imported && (!input.transcriptPath || input.sourceDurationMs === undefined || input.sourceTranscripts)) throw new Error("Legacy input requires transcriptPath and sourceDurationMs; sourceTranscripts requires renderReceiptPath");
+	const transcript = imported?.sources[0]!.transcript ?? await snapshotExistingWorkspaceFile(cwd, input.transcriptPath!, "application/json");
+	if (!imported && input.timelineSegments?.some(s => s.outputStartMs !== undefined || s.outputEndMs !== undefined || s.sourcePath !== undefined)) throw new Error("Explicit output timing requires a render receipt");
+	const segments = imported?.segments ?? input.timelineSegments ?? [{ id: "a-1", sourceStartMs: 0, sourceEndMs: input.sourceDurationMs! }];
+	if (!imported) validateSourceAndTimeline(input.sourceDurationMs!, segments);
+	const durationMs = imported?.durationMs ?? timelineDuration(segments);
+	const findings: SubtitleFinding[] = imported?.findings ?? [];
+	const words = imported?.words ?? remapWordsToTimeline(parseTranscript(await readWorkspaceJson(cwd, input.transcriptPath!, "word transcript")), segments, findings);
 	const layoutPreset = input.layoutPreset ?? "landscape";
 	const policy = resolvedPolicy(layoutPreset, input.policy);
-	const cues = buildSubtitleCues(remapWordsToTimeline(transcriptWords(rawTranscript), segments), durationMs, policy);
+	const cues = buildSubtitleCues(words, durationMs, policy, input.protectedPhrases);
 	if (cues.length === 0) throw new Error("Retained A-roll timeline contains no transcribed words");
+	const wordMapText = `${JSON.stringify({ words, findings }, null, 2)}\n`;
+	const wordMap = { path: projectRelative(input.projectId, "words.json"), bytes: Buffer.byteLength(wordMapText), sha256: createHash("sha256").update(wordMapText).digest("hex"), mimeType: "application/json" };
 	const now = new Date().toISOString();
 	const project: SubtitleProject = {
 		schemaVersion: 1,
@@ -168,13 +158,15 @@ export async function createSubtitleProject(cwd: string, input: CreateSubtitlePr
 		updatedAt: now,
 		currentRevision: 1,
 		layoutPreset,
-		sourceDurationMs: input.sourceDurationMs,
+		sourceDurationMs: input.sourceDurationMs ?? Math.max(...segments.map(s => s.sourceEndMs)),
 		timelineDurationMs: durationMs,
 		transcript,
 		timelineSegments: segments,
 		policy,
+		wordMap,
+		...(imported ? { sources: imported.sources, renderBinding: imported.binding } : {}),
 	};
-	const first = snapshot(input.projectId, 1, null, cues, "Initial subtitle generation from word timestamps");
+	const first = snapshot(input.projectId, 1, null, cues, "Initial subtitle generation from word timestamps", { review: validateReview(), findings: [...findings, ...validateCues(cues, project)] });
 	const projectsMarker = await resolveNewWorkspaceFile(cwd, ".subtitles/projects/.marker");
 	const projectsRoot = dirname(projectsMarker);
 	await mkdir(projectsRoot, { recursive: true });
@@ -182,6 +174,7 @@ export async function createSubtitleProject(cwd: string, input: CreateSubtitlePr
 	const temporary = join(projectsRoot, `.${input.projectId}.${randomUUID()}.tmp`);
 	await mkdir(join(temporary, "snapshots"), { recursive: true });
 	try {
+		await writeFile(join(temporary, "words.json"), wordMapText, { flag: "wx" });
 		await writeFile(join(temporary, "project.json"), `${JSON.stringify(project, null, 2)}\n`, { flag: "wx" });
 		await writeFile(join(temporary, "snapshots/1.json"), `${JSON.stringify(first, null, 2)}\n`, { flag: "wx" });
 		await rename(temporary, target);
@@ -210,20 +203,11 @@ export async function getSubtitleProject(cwd: string, projectId: string, revisio
 	return { project, snapshot: selectedSnapshot };
 }
 
-function visibleCharacters(value: string): number {
-	return [...value].filter((character) => !/\s/u.test(character) && !/\p{Cf}/u.test(character)).length;
-}
-
-function assertReviewedCues(cues: SubtitleCue[], project: SubtitleProject): void {
-	if (cues.length === 0 || cues.length > 10_000) throw new Error("cues must contain 1-10000 items");
-	renderSrt(cues);
-	if (cues.at(-1)!.endMs > project.timelineDurationMs) throw new Error("Subtitle cue exceeds the final timeline duration");
-	if (project.layoutPreset === "landscape") {
-		if (cues.some((cue) => /[\r\n]/u.test(cue.text))) throw new Error("Landscape subtitles must use one line");
-		if (cues.some((cue) => visibleCharacters(cue.text) > project.policy.maxLineChars)) {
-			throw new Error(`Landscape subtitle exceeds ${project.policy.maxLineChars} visible characters`);
-		}
-	}
+export async function getProjectWords(cwd: string, project: SubtitleProject): Promise<{ words: TimelineWord[]; findings: SubtitleFinding[] }> {
+	if (!project.wordMap) return { words: remapWordsToTimeline(parseTranscript(await readWorkspaceJson(cwd, project.transcript.path, "transcript")), project.timelineSegments), findings: [] };
+	const current = await snapshotExistingWorkspaceFile(cwd, project.wordMap.path, "application/json");
+	if (current.sha256 !== project.wordMap.sha256) throw new Error("Subtitle word map changed");
+	return await readWorkspaceJson(cwd, project.wordMap.path, "subtitle word map");
 }
 
 async function withProjectLock<T>(cwd: string, projectId: string, action: (directory: string) => Promise<T>): Promise<T> {
@@ -249,9 +233,13 @@ export async function applySubtitleRevision(cwd: string, input: ApplySubtitleRev
 		if (project.currentRevision !== input.expectedRevision) {
 			throw new Error(`Project ${input.projectId} expected revision ${input.expectedRevision} but current revision is ${project.currentRevision}`);
 		}
-		assertReviewedCues(input.cues, project);
+		if ((input.cues === undefined) === (input.groups === undefined)) throw new Error("Submit exactly one of cues or groups");
+		await assertTranscriptUnchanged(cwd, project);
+		const mapped = await getProjectWords(cwd, project);
+		const cues = input.groups ? cuesFromGroups(input.groups, mapped.words, project) : input.cues!;
+		const findings = [...mapped.findings, ...validateCues(cues, project), ...textCoverageFinding(cues, mapped.words)];
 		const revision = project.currentRevision + 1;
-		const nextSnapshot = snapshot(input.projectId, revision, project.currentRevision, input.cues, input.changeReason.trim());
+		const nextSnapshot = snapshot(input.projectId, revision, project.currentRevision, cues, input.changeReason.trim(), { ...(input.groups ? { groups: input.groups } : {}), review: validateReview(input.review), findings });
 		const snapshotPath = join(directory, `snapshots/${revision}.json`);
 		await writeFile(snapshotPath, `${JSON.stringify(nextSnapshot, null, 2)}\n`, { flag: "wx" });
 		const nextProject: SubtitleProject = { ...project, currentRevision: revision, updatedAt: new Date().toISOString() };
@@ -269,9 +257,10 @@ export async function applySubtitleRevision(cwd: string, input: ApplySubtitleRev
 }
 
 async function assertTranscriptUnchanged(cwd: string, project: SubtitleProject): Promise<void> {
-	const current = await snapshotExistingWorkspaceFile(cwd, project.transcript.path, project.transcript.mimeType);
-	if (current.sha256 !== project.transcript.sha256 || current.bytes !== project.transcript.bytes) {
-		throw new Error("Source transcript has changed since subtitle project creation");
+	const refs = project.sources?.map(s => s.transcript) ?? [project.transcript];
+	for (const ref of refs) {
+		const current = await snapshotExistingWorkspaceFile(cwd, ref.path, ref.mimeType);
+		if (current.sha256 !== ref.sha256 || current.bytes !== ref.bytes) throw new Error("Source transcript has changed since subtitle project creation");
 	}
 }
 
@@ -284,6 +273,15 @@ export async function exportSubtitleProject(cwd: string, input: {
 }) {
 	const { project, snapshot: selectedSnapshot } = await getSubtitleProject(cwd, input.projectId, input.revision);
 	await assertTranscriptUnchanged(cwd, project);
+	validateCues(selectedSnapshot.cues, project);
+	await getProjectWords(cwd, project);
+	if (project.renderBinding) {
+		const refs = [project.renderBinding.receipt, project.renderBinding.video, ...(project.sources ?? []).map(s => s.source)];
+		for (const ref of refs) {
+			const current = await snapshotExistingWorkspaceFile(cwd, ref.path, ref.mimeType);
+			if (current.sha256 !== ref.sha256 || current.bytes !== ref.bytes) throw new Error(`Subtitle render provenance changed: ${ref.path}`);
+		}
+	}
 	const resolvedAssStyle = input.assPath
 		? resolveAssStyle(project.layoutPreset ?? "landscape", input.assStyle)
 		: undefined;
@@ -291,6 +289,7 @@ export async function exportSubtitleProject(cwd: string, input: {
 		srtPath: input.srtPath,
 		...(input.assPath ? { assPath: input.assPath } : {}),
 		...(resolvedAssStyle ? { assStyle: resolvedAssStyle } : {}),
+		project,
 	});
 	const exportId = randomUUID();
 	const receiptPath = projectRelative(input.projectId, `exports/${exportId}.json`);
@@ -302,9 +301,15 @@ export async function exportSubtitleProject(cwd: string, input: {
 		createdAt: new Date().toISOString(),
 		snapshotSha256: selectedSnapshot.snapshotSha256,
 		tracks,
+		structure: "passed" as const,
+		review: selectedSnapshot.review ?? validateReview(),
+		...(project.renderBinding ? { primaryTimelineSha256: project.renderBinding.primaryTimelineSha256, video: project.renderBinding.video } : {}),
 		receiptPath,
 	};
 	const receipt: SubtitleExportReceipt = { ...base, receiptSha256: sha256Json(base) };
 	await writeInternalJson(cwd, receiptPath, receipt);
-	return { project, snapshot: selectedSnapshot, receipt };
+	return { project, snapshot: selectedSnapshot, receipt, subtitleTrack: {
+		sourcePath: (tracks.ass ?? tracks.srt).path, format: tracks.ass ? "ass" as const : "srt" as const, mode: "burn-in" as const,
+		...(project.renderBinding ? { exportReceiptPath: receiptPath } : {}),
+	} };
 }

package/src/timeline.ts

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+import type { FileRef, SubtitleFinding, TimelineSegment, TimelineWord, TranscriptWord } from './contracts.ts';
+import { remapWordsToTimeline } from './cues.ts';
+import { readWorkspaceJson, snapshotExistingWorkspaceFile } from './workspace.ts';
+
+export function parseTranscript(value: unknown): TranscriptWord[] {
+	const input = value as { words?: unknown[]; sentences?: Array<{ words?: unknown[] }> };
+	const raw = Array.isArray(input?.sentences) ? input.sentences.flatMap(s => s.words ?? []) : input?.words;
+	if (!Array.isArray(raw)) throw new Error('Transcript contains no usable word timestamps');
+	const words: TranscriptWord[] = [];
+	for (const [index, value] of raw.entries()) {
+		const w = value as Record<string, unknown>;
+		const text = typeof w?.text === 'string' ? w.text : w?.word;
+		if (typeof text === 'string' && /^(?:<sil>|\[sil\])$/iu.test(text.trim())) continue;
+		const beginMs = typeof w?.beginMs === 'number' ? w.beginMs : typeof w?.start === 'number' ? w.start * 1000 : NaN;
+		const endMs = typeof w?.endMs === 'number' ? w.endMs : typeof w?.end === 'number' ? w.end * 1000 : NaN;
+		if (typeof text !== 'string' || !text.trim() || !Number.isFinite(beginMs) || !Number.isFinite(endMs)) throw new Error(`Invalid transcript word ${index}; refusing to silently discard text`);
+		words.push({ text: text.trim(), beginMs, endMs, punctuation: typeof w.punctuation === 'string' ? w.punctuation : '' });
+	}
+	if (!words.length) throw new Error('Transcript contains no usable word timestamps');
+	return words;
+}
+
+export interface SourceTranscriptInput { sourcePath: string; transcriptPath: string }
+interface Timing {
+	policy: string; frameRate: number; sampleRate: number; totalFrames: number; totalSamples: number; outputDurationSeconds: number;
+	segments: Array<{ id: string; sourcePath: string; sourceStartSeconds: number; sourceEndSeconds: number; outputStartSeconds: number; outputEndSeconds: number; outputStartFrame: number; outputEndFrame: number; outputStartSample: number; outputEndSample: number; durationAdjustmentSeconds: number }>;
+}
+interface Receipt { primaryTimelineSha256?: string; path: string; bytes: number; sha256: string; projectId: string; snapshotRevision: number; sourceSha256s: string[]; timelineTiming: Timing }
+
+// Versioned, ordered tuple shared with pi-media. Excludes overlays, BGM, IDs and output file bytes.
+export function primaryTimelineHash(timing: Timing, sourceHashes: Map<string, string>): string {
+	return createHash('sha256').update(JSON.stringify(['primary-timeline-v1', timing.frameRate, timing.sampleRate,
+		timing.segments.map(s => [sourceHashes.get(s.sourcePath), s.sourceStartSeconds, s.sourceEndSeconds, s.outputStartSample, s.outputEndSample])])).digest('hex');
+}
+
+export async function importRenderTimeline(cwd: string, receiptPath: string, transcriptPath?: string, inputs?: SourceTranscriptInput[]) {
+	const receiptRef = await snapshotExistingWorkspaceFile(cwd, receiptPath, 'application/json');
+	const receipt = await readWorkspaceJson<Receipt>(cwd, receiptPath, 'render receipt');
+	const t = receipt.timelineTiming;
+	if (!t || t.policy !== 'cumulative-frame-rounding' || !Number.isFinite(t.frameRate) || t.frameRate < 1 || t.frameRate > 240 || t.sampleRate !== 48000
+		|| !Array.isArray(t.segments) || !t.segments.length || t.segments.length > 1000 || !Array.isArray(receipt.sourceSha256s)
+		|| !receipt.projectId || !Number.isInteger(receipt.snapshotRevision) || receipt.snapshotRevision < 1) throw new Error('Invalid or unsupported render timeline receipt');
+	let frames = 0, samples = 0, ideal = 0;
+	const ids = new Set<string>();
+	for (const s of t.segments) {
+		if (!s.id || ids.has(s.id) || !s.sourcePath || !Number.isFinite(s.sourceStartSeconds) || s.sourceStartSeconds < 0
+			|| !Number.isFinite(s.sourceEndSeconds) || s.sourceEndSeconds <= s.sourceStartSeconds) throw new Error('Invalid render segment');
+		ids.add(s.id);
+		ideal += s.sourceEndSeconds - s.sourceStartSeconds;
+		const endFrame = Math.round(ideal * t.frameRate + 1e-8), endSample = Math.round(endFrame / t.frameRate * t.sampleRate);
+		if (endFrame <= frames || s.outputStartFrame !== frames || s.outputEndFrame !== endFrame || s.outputStartSample !== samples || s.outputEndSample !== endSample
+			|| !Number.isFinite(s.outputStartSeconds) || Math.abs(s.outputStartSeconds - frames / t.frameRate) > 1e-9
+			|| !Number.isFinite(s.outputEndSeconds) || Math.abs(s.outputEndSeconds - endFrame / t.frameRate) > 1e-9
+			|| !Number.isFinite(s.durationAdjustmentSeconds) || Math.abs(s.durationAdjustmentSeconds - (endFrame - frames) / t.frameRate + s.sourceEndSeconds - s.sourceStartSeconds) > 1e-9) throw new Error(`Inconsistent render timing for ${s.id}`);
+		frames = endFrame; samples = endSample;
+	}
+	if (t.totalFrames !== frames || t.totalSamples !== samples || !Number.isFinite(t.outputDurationSeconds) || Math.abs(t.outputDurationSeconds - frames / t.frameRate) > 1e-9) throw new Error('Inconsistent render duration');
+	const video = await snapshotExistingWorkspaceFile(cwd, receipt.path, 'video/mp4');
+	if (video.sha256 !== receipt.sha256 || video.bytes !== receipt.bytes) throw new Error('Rendered video differs from its receipt');
+	const paths = [...new Set(t.segments.map(s => s.sourcePath))];
+	if (transcriptPath && inputs) throw new Error('Use transcriptPath or sourceTranscripts, not both');
+	if (transcriptPath && paths.length !== 1) throw new Error('Multi-source timeline requires sourceTranscripts for every primary source');
+	const bindings = inputs ?? (transcriptPath ? [{ sourcePath: paths[0]!, transcriptPath }] : []);
+	if (bindings.length !== paths.length || new Set(bindings.map(b => b.sourcePath)).size !== bindings.length || paths.some(p => !bindings.some(b => b.sourcePath === p))) throw new Error('sourceTranscripts must match every primary source exactly once');
+	const sources: Array<{ source: FileRef; transcript: FileRef }> = [];
+	const wordsByPath = new Map<string, TranscriptWord[]>(), sourceHashes = new Map<string, string>();
+	for (const b of bindings) {
+		const source = await snapshotExistingWorkspaceFile(cwd, b.sourcePath, 'application/octet-stream');
+		if (!receipt.sourceSha256s.includes(source.sha256)) throw new Error(`Source changed since render: ${b.sourcePath}`);
+		const transcript = await snapshotExistingWorkspaceFile(cwd, b.transcriptPath, 'application/json');
+		wordsByPath.set(b.sourcePath, parseTranscript(await readWorkspaceJson(cwd, b.transcriptPath, 'word transcript')));
+		sourceHashes.set(b.sourcePath, source.sha256); sources.push({ source, transcript });
+	}
+	const fingerprint = primaryTimelineHash(t, sourceHashes);
+	if (receipt.primaryTimelineSha256 && receipt.primaryTimelineSha256 !== fingerprint) throw new Error("Render primary timeline fingerprint differs from its sources");
+	const segments: TimelineSegment[] = t.segments.map(s => ({ id: s.id, sourcePath: s.sourcePath,
+		sourceStartMs: s.sourceStartSeconds * 1000, sourceEndMs: s.sourceEndSeconds * 1000,
+		outputStartMs: s.outputStartSeconds * 1000, outputEndMs: s.outputEndSeconds * 1000 }));
+	const findings: SubtitleFinding[] = [], words: TimelineWord[] = [];
+	for (const s of segments) words.push(...remapWordsToTimeline(wordsByPath.get(s.sourcePath!)!, [s], findings));
+	return { segments, words, sources, findings, durationMs: t.outputDurationSeconds * 1000,
+		binding: { receipt: receiptRef, video, projectId: receipt.projectId, snapshotRevision: receipt.snapshotRevision, primaryTimelineSha256: fingerprint } };
+}

package/src/validation.ts

@@ -0,0 +1,66 @@
+import type { SubtitleCue, SubtitleFinding, SubtitleProject, SubtitleReview, TimelineSegment, TimelineWord, WordGroup } from './contracts.ts';
+
+export function segmentRanges(segments: TimelineSegment[]) {
+	let offset = 0;
+	return segments.map(s => {
+		const beginMs = s.outputStartMs ?? offset;
+		const endMs = s.outputEndMs ?? beginMs + s.sourceEndMs - s.sourceStartMs;
+		offset = endMs;
+		return { id: s.id, beginMs, endMs };
+	});
+}
+export function visibleCharacters(text: string) { return [...text].filter(c => !/[\s\p{Cf}]/u.test(c)).length; }
+export function validateCues(cues: SubtitleCue[], project: SubtitleProject): SubtitleFinding[] {
+	if (!Array.isArray(cues) || !cues.length || cues.length > 10000) throw new Error('cues must contain 1-10000 items');
+	const ranges = segmentRanges(project.timelineSegments), findings: SubtitleFinding[] = [], ids = new Set<string>();
+	let previousEnd = 0;
+	for (const c of cues) {
+		if (!c.id || ids.has(c.id) || typeof c.text !== 'string' || !c.text.trim() || !Number.isFinite(c.beginMs) || !Number.isFinite(c.endMs)
+			|| c.beginMs < 0 || c.endMs <= c.beginMs || c.beginMs < previousEnd) throw new Error(`Invalid or overlapping subtitle cue: ${c.id}`);
+		ids.add(c.id); previousEnd = c.endMs;
+		if (c.endMs > project.timelineDurationMs) throw new Error(`Subtitle cue exceeds the final timeline duration: ${c.id}`);
+		if (!ranges.some(s => c.beginMs >= s.beginMs && c.endMs <= s.endMs)) throw new Error(`Subtitle cue crosses A-roll edit boundary: ${c.id}`);
+		if (project.layoutPreset === 'landscape' && /[\r\n]/u.test(c.text)) throw new Error('Landscape subtitles must use one line');
+		const lines = c.text.split(/\r?\n/u);
+		if (lines.length > project.policy.maxLines || lines.some(l => visibleCharacters(l) > project.policy.maxLineChars)) throw new Error(`Subtitle ${c.id} exceeds ${project.policy.maxLineChars} visible characters per line or line count`);
+		const duration = c.endMs - c.beginMs, count = visibleCharacters(c.text);
+		if (duration < project.policy.minDurationMs) findings.push({ code: 'short-cue', severity: 'warning', cueId: c.id, message: `${duration}ms; no safe room to extend` });
+		if (duration > project.policy.maxDurationMs) findings.push({ code: 'long-cue', severity: 'warning', cueId: c.id, message: `${duration}ms exceeds preferred duration` });
+		if (count / (duration / 1000) > project.policy.targetCps) findings.push({ code: 'fast-cue', severity: 'warning', cueId: c.id, message: `${(count * 1000 / duration).toFixed(2)} characters/second` });
+		if (count === 1) findings.push({ code: 'orphan-cue', severity: 'warning', cueId: c.id, message: 'Single-character cue requires semantic review' });
+	}
+	return findings;
+}
+export function validateReview(review: SubtitleReview = {}): SubtitleReview {
+	for (const entry of Object.values(review)) {
+		if (!entry || !['pending', 'passed'].includes(entry.status) || (entry.status === 'passed' && !entry.evidence?.trim())) throw new Error('Passed review requires concrete listening/visual evidence');
+	}
+	return { text: { status: 'pending' }, sync: { status: 'pending' }, visual: { status: 'pending' }, ...review };
+}
+function normalize(text: string) { return text.replace(/[\s\p{P}\p{Cf}]/gu, ''); }
+export function textCoverageFinding(cues: SubtitleCue[], words: TimelineWord[]): SubtitleFinding[] {
+	return normalize(cues.map(c => c.text).join('')) === normalize(words.map(w => w.text).join('')) ? []
+		: [{ code: 'text-changed', severity: 'warning', message: 'Reviewed text differs from ASR; verify corrections against audio. Use word groups for exact coverage checks.' }];
+}
+export function cuesFromGroups(groups: WordGroup[], words: TimelineWord[], project: SubtitleProject): SubtitleCue[] {
+	if (!groups.length || groups.length > 10000) throw new Error('groups must contain 1-10000 complete ranges');
+	const positions = new Map(words.map((w, i) => [w.id, i]));
+	let cursor = 0;
+	const cues = groups.map((g, i) => {
+		const start = positions.get(g.startWordId), end = positions.get(g.endWordId);
+		if (start === undefined || end === undefined || start !== cursor || end < start) throw new Error(`Group ${i + 1} has missing, duplicated, out-of-order or unknown words`);
+		const selected = words.slice(start, end + 1), first = selected[0]!, last = selected.at(-1)!;
+		if (selected.some(w => w.timelineSegmentId !== first.timelineSegmentId)) throw new Error(`Group ${i + 1} crosses A-roll edit boundary`);
+		let original = '';
+		for (const w of selected) original += `${original && /[A-Za-z0-9]$/u.test(original) && /^[A-Za-z0-9]/u.test(w.text) ? ' ' : ''}${w.text}${w.punctuation}`;
+		if (g.text !== undefined && normalize(g.text) !== normalize(original) && !g.correctionReason?.trim()) throw new Error(`Group ${i + 1}: text correction requires correctionReason based on audio`);
+		cursor = end + 1;
+		return { id: `cue-${String(i + 1).padStart(3, '0')}`, beginMs: first.beginMs, endMs: last.endMs, text: g.text ?? original };
+	});
+	if (cursor !== words.length) throw new Error('Groups omit trailing transcript words');
+	const ranges = segmentRanges(project.timelineSegments);
+	return cues.map((c, i) => {
+		const range = ranges.find(r => c.beginMs >= r.beginMs && c.endMs <= r.endMs)!;
+		return { ...c, endMs: Math.max(c.endMs, Math.min(c.beginMs + project.policy.minDurationMs, cues[i + 1]?.beginMs ?? project.timelineDurationMs, range.endMs)) };
+	});
+}