@gentbajko/slopify 2.0.2 → 2.1.0

package/dist/slices/rebuild/runtime-subtitles.js

@@ -1,14 +1,19 @@
 import { readFileSync } from "node:fs";
 import { z } from "zod";
 import { subtitleModelDir } from "../../kernel/paths.js";
+import { SubtitleMismatch } from "../../kernel/ports/subtitles.js";
 import { resolveFont } from "../fonts/index.js";
 import { validateCues } from "../revisions/rules.js";
 import { discardPreparedAssets, writeAsset } from "../storage/assets.js";
 import { outputPath } from "../storage/layout.js";
 import { captionCues, serializeAss, serializeSrt, serializeVtt } from "../subtitles/captions.js";
+import { spoken } from "../video/plan.js";
 import { exportSnapshot, retainedOutput, revisionAudio, revisionTranscript, } from "./runtime-export-inputs.js";
+import { narrationChunks, narrationTextParts, } from "./runtime-narration-text.js";
 import { preparedResult, preparedText, publishResult } from "./runtime-publication.js";
-const wordsSchema = z.object({
+// The saved `subtitles.json`: every word at its time in the final video. The YouTube
+// description reads it too (`runtime-youtube.ts`).
+export const wordsSchema = z.object({
     key: z.string(),
     words: z.array(z.object({
         text: z.string(),
@@ -39,14 +44,15 @@ export async function executeSubtitleRecipe(deps, context, piece) {
         return cues(deps, context, piece, snapshot);
     if (piece.key === "subtitles:files")
         return files(deps, context, piece, snapshot);
-    throw new Error("Unknown subtitle recipe.");
+    throw new Error("Slopify hit an internal error (unknown kind of caption step). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
 }
 async function timing(deps, context, piece, snapshot) {
     const audio = await revisionAudio(deps, context, snapshot.view);
     if (audio.length === 0)
-        throw new Error("Subtitles need narration audio.");
-    if (deps.alignSubtitles === undefined)
-        throw new Error("Local subtitle alignment is unavailable in this build.");
+        throw new Error("Captions and the YouTube description need narration audio, but this project has none. Turn captions and the YouTube description off in Edit project, or turn narration on, then Retry stage.");
+    const alignSubtitles = deps.alignSubtitles;
+    if (alignSubtitles === undefined)
+        throw new Error("Slopify hit an internal error (the caption timing tool is missing from this build). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
     if (!context.maySubmit(piece.id))
         return "held";
     const words = [];
@@ -55,10 +61,11 @@ async function timing(deps, context, piece, snapshot) {
     const total = audio.reduce((sum, segment) => sum + segment.seconds, 0);
     for (const segment of audio) {
         context.signal.throwIfAborted();
-        if (segment.path !== null && segment.kind !== "gap") {
-            const aligned = await deps.alignSubtitles({
-                audioPath: segment.path,
-                text: revisionTranscript(deps, snapshot, segment.kind),
+        const { path, kind } = segment;
+        if (path !== null && spoken(kind)) {
+            const aligned = await located(snapshot, kind, () => alignSubtitles({
+                audioPath: path,
+                text: revisionTranscript(deps, snapshot, kind),
                 cacheDir: subtitleModelDir(deps.paths.dataDir),
                 ffmpeg: deps.ffmpeg,
                 signal: context.signal,
@@ -70,10 +77,10 @@ async function timing(deps, context, piece, snapshot) {
                     current: Math.round((100 * (offset + segment.seconds * (maximum > 0 ? current / maximum : 0))) / total),
                     total: 100,
                 }),
-            });
+            }));
             for (const word of aligned) {
                 if (word.end > segment.seconds + 0.1)
-                    throw new Error("Subtitle timing exceeds the narration duration.");
+                    throw new Error("Caption timing came out longer than the narration audio. Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
                 words.push({
                     ...word,
                     start: word.start + offset,
@@ -84,7 +91,7 @@ async function timing(deps, context, piece, snapshot) {
         offset += segment.seconds;
     }
     if (captionCues(words).length === 0)
-        throw new Error("No spoken words could be aligned. Check that the English article matches the audio.");
+        throw new Error("None of the narration could be matched to the article text, so captions can't be timed. Captions only work for English narration; if you uploaded your own audio, make sure it reads the article text, then Retry stage.");
     context.signal.throwIfAborted();
     const output = preparedText(deps, context, piece, "subtitle_words", "subtitles.json", JSON.stringify({ key: piece.logicalFingerprint ?? piece.fingerprint, words, omissions }));
     await publishResult(deps, context, piece, [output], { words, omissions }, output.asset);
@@ -96,7 +103,7 @@ async function cues(deps, context, piece, snapshot) {
     let value;
     if (manual !== undefined) {
         if (plan.work.find((one) => one.key === piece.key)?.disposition === "review")
-            throw new Error("Review the saved captions against the current narration before rebuilding.");
+            throw new Error("Your edited captions were written for an older version of the narration. Review them in Edit project → Captions and save, then Retry stage.");
         const audio = await revisionAudio(deps, context, view);
         const errors = validateCues(manual.cues, audio.reduce((sum, segment) => sum + segment.seconds, 0));
         if (errors.length > 0)
@@ -109,7 +116,7 @@ async function cues(deps, context, piece, snapshot) {
             one.state === "ready" &&
             one.workKey === "subtitles:timing");
         if (output === undefined)
-            throw new Error("The revision has no aligned subtitle timing.");
+            throw new Error("Caption timing is missing. Use Re-run section on Video, then Retry stage.");
         const timed = wordsSchema.parse(JSON.parse(readFileSync(outputPath(deps.paths, context.work.projectId, output.output.path), "utf8")));
         value = { cues: [...captionCues(timed.words)], omissions: timed.omissions };
     }
@@ -123,10 +130,10 @@ async function files(deps, context, piece, snapshot) {
     const { view } = snapshot;
     const config = view.revision.config.subtitles;
     if (config === undefined || config.mode === "off")
-        throw new Error("The admitted revision has no subtitles.");
+        throw new Error("Slopify hit an internal error (captions are off for this version of the project). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
     const row = view.pieces.find((one) => one.key === "subtitles:cues" && one.selected && one.available && one.piece.state === "done");
     if (row?.piece.payload === null || row?.piece.payload === undefined)
-        throw new Error("The revision has no prepared captions.");
+        throw new Error("The captions haven't been prepared yet. Use Re-run section on Video, then Retry stage.");
     const value = cuesSchema.parse(JSON.parse(row.piece.payload));
     const previous = view.outputs.find((one) => one.output.role === "subtitle_font" && one.selected && one.available);
     const previousFiles = view.pieces.find((one) => one.key === "subtitles:files" &&
@@ -200,3 +207,62 @@ async function files(deps, context, piece, snapshot) {
         discardPreparedAssets(deps, prepared.map((one) => one.asset));
     }
 }
+// A mismatch names the place to fix: the time in the narration, the chunk that holds it (as
+// the Narration editor numbers them) and what was expected against what was heard. The
+// usual cause is a TTS request that skipped or reworded a sentence.
+async function located(snapshot, segment, align) {
+    try {
+        return await align();
+    }
+    catch (error) {
+        if (!(error instanceof SubtitleMismatch))
+            throw error;
+        throw new Error(mismatchMessage(snapshot, segment, error), { cause: error });
+    }
+}
+export function mismatchMessage(snapshot, segment, mismatch) {
+    let chunks = [];
+    try {
+        chunks = narrationChunks(narrationTextParts(snapshot.view, snapshot.plan, segment));
+    }
+    catch {
+        // Without a readable plan the message still gives the time and the words.
+    }
+    return describeMismatch(chunks, segment, mismatch);
+}
+export function describeMismatch(chunks, segment, mismatch) {
+    const probe = comparable(mismatch.expected).split(" ").slice(0, 6).join(" ");
+    const at = probe === ""
+        ? chunks.length - 1
+        : chunks.findIndex((chunk) => comparable(chunk.spokenText).includes(probe));
+    const chunk = at === -1 ? undefined : chunks[at];
+    const where = chunk === undefined
+        ? `${clock(mismatch.at)} into the ${segment} narration`
+        : `${clock(mismatch.at)} into the ${segment} narration, in narration chunk ${String(at + 1)} of ${String(chunks.length)} (it starts "${opening(chunk.spokenText)}")`;
+    const expected = mismatch.expected === "" ? "the end of the text" : `"${mismatch.expected}…"`;
+    const heard = mismatch.heard === "" ? "no more speech" : `"${mismatch.heard.toLowerCase()}…"`;
+    const fix = chunk === undefined
+        ? "Check that part of the narration, regenerate it in Edit project → Narration, then Resume."
+        : `In Edit project → Narration, regenerate narration chunk ${String(at + 1)}, then Resume.`;
+    return `Subtitles stopped matching the audio at ${where}. The text expected ${expected} but the audio has ${heard} The recording there probably skips or changes words. ${fix}`;
+}
+function comparable(text) {
+    return text
+        .toUpperCase()
+        .replace(/&/g, " AND ")
+        .replace(/[^A-Z0-9' ]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function opening(text) {
+    return text.trim().split(/\s+/).slice(0, 6).join(" ");
+}
+function clock(seconds) {
+    const whole = Math.floor(seconds);
+    const hours = Math.floor(whole / 3600);
+    const minutes = Math.floor((whole % 3600) / 60);
+    const rest = String(whole % 60).padStart(2, "0");
+    return hours > 0
+        ? `${String(hours)}:${String(minutes).padStart(2, "0")}:${rest}`
+        : `${String(minutes)}:${rest}`;
+}

package/dist/slices/rebuild/runtime-youtube.js

@@ -0,0 +1,84 @@
+import { readFileSync } from "node:fs";
+import { outputPath } from "../storage/layout.js";
+import { assembleDescription, checkDescriptionAnswer, descriptionMessages, tagsText, } from "../youtube/answer.js";
+import { defaultDescriptionPrompt } from "../youtube/model.js";
+import { transcriptPassages, transcriptText } from "../youtube/transcript.js";
+import { exportSnapshot, revisionAudio } from "./runtime-export-inputs.js";
+import { savedCatalogue } from "./runtime-plan.js";
+import { preparedTexts, publishResult } from "./runtime-publication.js";
+import { wordsSchema } from "./runtime-subtitles.js";
+// Writes the YouTube description and tags from the saved word timing: the transcript's
+// passages carry their start in the final video, so the chapters the model picks are real
+// times. An answer that breaks YouTube's chapter or tag rules is a failed attempt, which the
+// provider wrapper asks again while attempts remain.
+export async function executeYoutubeRecipe(deps, context, providers, piece) {
+    if (deps.db
+        .prepare("SELECT state FROM revision_work_pieces WHERE id=? AND work_id=?")
+        .get(piece.id, context.work.workId)?.state === "done")
+        return "done";
+    if (!context.maySubmit(piece.id))
+        return "held";
+    context.signal.throwIfAborted();
+    const input = piece.input;
+    if (input.kind !== "local" || input.operation !== "youtube-description-v1")
+        throw new Error("Slopify hit an internal error (the YouTube description step was set up wrongly). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
+    const { view } = exportSnapshot(deps, context, piece);
+    const config = view.revision.config;
+    const llm = config.llm;
+    if (llm === undefined || llm.provider.trim() === "" || llm.model.trim() === "")
+        throw new Error("The YouTube description needs an AI text model, and none is chosen. Choose one in Edit project → Providers, then Retry stage.");
+    const timing = view.outputs.find((row) => row.selected &&
+        row.available &&
+        row.state === "ready" &&
+        row.workKey === "subtitles:timing" &&
+        row.output.role === "subtitle_words");
+    if (timing === undefined)
+        throw new Error("The narration's word timing, which the YouTube description's chapters come from, is missing. Use Re-run section on Video, then Retry stage.");
+    const { words } = wordsSchema.parse(JSON.parse(readFileSync(outputPath(deps.paths, context.work.projectId, timing.output.path), "utf8")));
+    const passages = transcriptPassages(words);
+    if (passages.length === 0)
+        throw new Error("The narration's word timing holds no words, so there is nothing to write the YouTube description from. Use Re-run section on Video, then Retry stage.");
+    // The same timeline the timing walked: silence at the start, intro, gaps, body, outro and
+    // silence at the end.
+    const audio = await revisionAudio(deps, context, view);
+    const durationSeconds = audio.reduce((sum, segment) => sum + segment.seconds, 0);
+    const saved = Array.isArray(input.values) ? input.values[4] : undefined;
+    const instruction = typeof saved === "string" && saved.trim() !== "" ? saved : defaultDescriptionPrompt;
+    const messages = descriptionMessages({
+        instruction,
+        title: config.title,
+        durationSeconds,
+        transcript: transcriptText(passages),
+    });
+    const row = deps.db
+        .prepare("SELECT recipe_context FROM revision_work WHERE id=?")
+        .get(context.work.workId);
+    const model = savedCatalogue(row?.recipe_context).llm.find((one) => one.provider === llm.provider && one.id === llm.model);
+    if (!context.maySubmit(piece.id))
+        return "held";
+    const answer = await providers.forPiece(piece.id).llm({
+        provider: llm.provider,
+        model: llm.model,
+        ...(llm.thinking === undefined ? {} : { thinking: llm.thinking }),
+        thinkingConfig: llm.thinking === undefined ? null : (model?.llm.thinking?.[llm.thinking] ?? null),
+        messages,
+        webSearch: false,
+        previewLabel: piece.key,
+        check: (value) => {
+            const checked = checkDescriptionAnswer(value.text, durationSeconds);
+            return checked.ok ? undefined : checked.reason;
+        },
+    });
+    if (!answer.ok)
+        return "held";
+    const checked = checkDescriptionAnswer(answer.value.text, durationSeconds);
+    if (!checked.ok)
+        throw new Error(checked.reason);
+    const description = assembleDescription(checked.value);
+    const tags = tagsText(checked.value.tags);
+    await publishResult(deps, context, piece, preparedTexts(deps, context, piece, [
+        ["youtube_description", "description.txt", description],
+        ["youtube_tags", "tags.txt", tags],
+    ]), { description, tags: checked.value.tags, chapters: checked.value.chapters, durationSeconds });
+    return "done";
+}

package/dist/slices/rebuild/transition-repo.js

@@ -15,14 +15,14 @@ export function transitionRevisionWork(deps, input) {
     transact(db, () => {
         const current = currentRevisionId(db, input.projectId);
         if (current !== input.baseRevisionId && current !== input.revisionId)
-            throw new Error("Work transition requires the current head.");
+            throw new Error("The project was changed while this was being saved. Try again.");
         const base = revisionById(db, input.projectId, input.baseRevisionId);
         const next = revisionById(db, input.projectId, input.revisionId);
         if (base === undefined || next === undefined)
-            throw new Error("Work transition requires owned revisions.");
+            throw new Error("Slopify hit an internal error (a project version to switch between is missing). Try again; if it happens again, use Download diagnostics in Settings and report it.");
         if (JSON.stringify(Object.entries(input.fingerprints).sort()) !==
             JSON.stringify(Object.entries(next.fingerprints).sort()))
-            throw new Error("Desired work differs from revision fingerprints.");
+            throw new Error("Slopify hit an internal error (the planned steps don't match the saved project version). Try again; if it happens again, use Download diagnostics in Settings and report it.");
         const reserved = db
             .prepare(`SELECT r.* FROM revision_work_reservations r JOIN revision_work w ON w.id=r.work_id WHERE r.project_id=? AND r.revision_id=? AND w.state IN ('pending','running','done')`)
             .all(input.projectId, input.baseRevisionId)
@@ -57,13 +57,13 @@ export function transitionRevisionWork(deps, input) {
                 continue;
             const exact = input.recipes?.find((row) => row.key === key);
             if (exact !== undefined && exact.fingerprint !== fp)
-                throw new Error("Recipe differs from desired fingerprint.");
+                throw new Error("Slopify hit an internal error (a planned step doesn't match the saved project version). Try again; if it happens again, use Download diagnostics in Settings and report it.");
             const kind = exact?.stage ?? stageForKey(key);
             const stage = db
                 .prepare("SELECT id FROM stages WHERE project_id=? AND kind=?")
                 .get(input.projectId, kind);
             if (stage === undefined)
-                throw new Error("Desired work has no project stage.");
+                throw new Error("Slopify hit an internal error (a planned step has no matching stage). Try again; if it happens again, use Download diagnostics in Settings and report it.");
             const workId = deps.ids.next();
             const pieceId = deps.ids.next();
             db.prepare(`INSERT INTO revision_work(id,project_id,revision_id,stage_id,kind,fingerprint,state,dispatch_state,created_at) VALUES (?,?,?,?,?,?,'pending','held',?)`).run(workId, input.projectId, input.revisionId, z.string().parse(stage.id), kind, fp, deps.clock.now().toISOString());
@@ -104,5 +104,7 @@ function stageForKey(key) {
         return "thumbnail";
     if (prefix === "export" || prefix === "subtitles" || prefix === "video")
         return "video";
-    throw new Error("Unknown revision work key.");
+    if (prefix === "document")
+        return "document";
+    throw new Error("Slopify hit an internal error (unknown kind of step). Try again; if it happens again, use Download diagnostics in Settings and report it.");
 }

package/dist/slices/reruns/cascade.js

@@ -14,9 +14,9 @@ function staleStages(input) {
             return withDependents([action.stage], input);
         case "article-edit": {
             // An article edit re-runs audio, LLM-mode intro/outro text, the LLM-written
-            // thumbnail and the video, leaving prompt-based images untouched. The video comes
-            // along as a dependent of the audio, so it is never named here.
-            const roots = ["audio"];
+            // thumbnail, the document and the video, leaving prompt-based images untouched. The
+            // video comes along as a dependent of the audio, so it is never named here.
+            const roots = ["audio", "document"];
             if (input.thumbnailSource === "prompt_by_llm") {
                 roots.push("thumbnail");
             }
@@ -64,6 +64,8 @@ function withDependents(roots, input) {
     }
     return found;
 }
+// A stage with no row is not part of the run (a project from before the Document stage
+// may lack one), so it is stepped over like a skipped one.
 function stateOf(stages, kind) {
-    return stages.find((stage) => stage.kind === kind)?.state ?? "pending";
+    return stages.find((stage) => stage.kind === kind)?.state ?? "skipped";
 }

package/dist/slices/reruns/index.js

@@ -204,7 +204,7 @@ function clearStage(deps, stage, outputs) {
 // runs the returned cleanup only after commit. Finished narration is left intact.
 export function clearUnfinishedAudio(deps, projectId) {
     if (currentRevisionId(deps.db, projectId) !== undefined)
-        throw new Error("Versioned narration must be edited through revisions.");
+        throw new Error("Slopify hit an internal error (narration was changed the old way on a project that uses versions). Try again; if it happens again, use Download diagnostics in Settings and report it.");
     const stage = stagesOf(deps.db, projectId).find((one) => one.kind === "audio");
     if (stage === undefined ||
         stage.state === "done" ||

package/dist/slices/research/run.js

@@ -10,7 +10,7 @@ import { chaptersFrom, plannerMessages, subAgentMessages } from "./planner.js";
 import { sourcedAnswer, synthesisMessages } from "./synthesis.js";
 // A model that cannot ground on the web fails the stage immediately, with no fallback to
 // what the model already knows.
-export const webResearchUnsupported = "web research unsupported by this model";
+export const webResearchUnsupported = "The chosen AI model can't search the web, which research needs. Choose a model with web search in Edit project → Providers, or turn research off, then Retry stage.";
 // What a chapter piece carries between runs: its title, and its notes once a sub-agent
 // has answered. That is the whole of the resume.
 const chapterPayload = z.object({ title: z.string(), notes: z.string().optional() });
@@ -18,14 +18,14 @@ export async function runResearch(deps, context, providers) {
     const { projectId } = context.stage;
     const project = projectById(deps.db, projectId);
     if (project === undefined) {
-        throw new Error(`project ${projectId} has no row`);
+        throw new Error("This project no longer exists; it may have been deleted while it was running.");
     }
     const choice = project.config.llm;
     const articlePrompt = project.config.rendered.article;
     if (choice === undefined || articlePrompt === undefined) {
         // Admission refuses a run whose research is Generate without both, so
         // reaching here is a bug in admission rather than something the user did.
-        throw new Error("the run has no LLM provider or no rendered article prompt");
+        throw new Error("No AI model or article prompt is set for research. Choose a model in Edit project → Providers and check Edit project → Prompts, then Retry stage.");
     }
     const brief = { articlePrompt, values: project.config.values };
     try {
@@ -62,7 +62,7 @@ async function research(deps, context, providers, choice, brief) {
         messages: synthesisMessages(brief, findings),
         documents: researchDocuments(findings),
         previewLabel: "Writing research notes",
-        check: (given) => sourcedAnswer("the synthesis", given.text),
+        check: (given) => sourcedAnswer("the research summary", given.text),
     });
     if (!answer.ok)
         return "held";
@@ -110,7 +110,9 @@ async function plan(deps, context, providers, choice, brief, add) {
         messages: plannerMessages(brief),
         previewLabel: "Planning research",
         // An empty answer, or one with no chapter in it, is a failed attempt.
-        check: (given) => chaptersFrom(given.text).length === 0 ? "the planner named no chapters" : undefined,
+        check: (given) => chaptersFrom(given.text).length === 0
+            ? "The AI model didn't return any research topics. Retry stage; if it keeps happening, choose a different model in Edit project → Providers."
+            : undefined,
     });
     if (!answer.ok)
         return answer;
@@ -156,7 +158,7 @@ async function researchChapters(deps, context, providers, choice, brief, chapter
                 // Grounding is asked for explicitly, so a model without it says so
                 // instead of answering from what it already knows.
                 webSearch: true,
-                check: (given) => sourcedAnswer(`the researcher on "${kept.title}"`, given.text),
+                check: (given) => sourcedAnswer(`the research topic "${kept.title}"`, given.text),
             });
             if (!answer.ok) {
                 setPiece(deps.db, piece.id, "pending", piece.payload);
@@ -215,7 +217,7 @@ function section(label, messages) {
 }
 function payloadOf(piece) {
     if (piece.payload === null) {
-        throw new Error(`chapter ${piece.id} has no payload`);
+        throw new Error("Slopify hit an internal error (a saved research topic is empty). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
     }
     return chapterPayload.parse(JSON.parse(piece.payload));
 }

package/dist/slices/research/synthesis.js

@@ -41,7 +41,9 @@ export function endsWithSources(text) {
 // but cannot be used is a failed attempt, so the wrapper retries it.
 export function sourcedAnswer(who, text) {
     if (text.trim() === "") {
-        return `${who} answered with nothing`;
+        return `The AI model returned an empty answer for ${who}. Retry stage; if it keeps happening, choose a different model in Edit project → Providers.`;
     }
-    return endsWithSources(text) ? undefined : `${who} answered with no Sources list`;
+    return endsWithSources(text)
+        ? undefined
+        : `The AI model's answer for ${who} had no sources. Research needs web sources: Retry stage, or choose a model with web search in Edit project → Providers.`;
 }

package/dist/slices/revisions/mutation-assets.js

@@ -34,11 +34,14 @@ export function validateUploads(deps, edit) {
             (to.kind === "image" && edit.config.sources.images === "off"))
             fields.push({
                 field,
-                message: "Enable the corresponding provided or generated content before importing this file.",
+                message: "This section is off or not set to use your own file. Change the section's setting first, then add the file.",
             });
         const destination = JSON.stringify(to);
         if (staged.has(upload.stagedFileId) || destinations.has(destination))
-            fields.push({ field, message: "Each upload and destination must be unique." });
+            fields.push({
+                field,
+                message: "The same file or place is used twice. Remove the duplicate.",
+            });
         staged.add(upload.stagedFileId);
         destinations.add(destination);
         const file = stagedFileById(deps.db, upload.stagedFileId);
@@ -47,11 +50,20 @@ export function validateUploads(deps, edit) {
             file.state !== "staged" ||
             file.stageKind !== kind ||
             !statSync(stagingPath(deps.paths, file.path), { throwIfNoEntry: false })?.isFile())
-            fields.push({ field, message: "Choose a completed upload for this stage." });
+            fields.push({
+                field,
+                message: "This upload is missing or has not finished. Upload the file again.",
+            });
         if (to.kind === "image" && edit.content.imageDefinitions[to.imageKey] === undefined)
-            fields.push({ field, message: "Choose an image in this revision." });
+            fields.push({
+                field,
+                message: "This image is no longer in the project. Reload the page and choose again.",
+            });
         if (to.kind === "narration" && !to.key.startsWith("audio:"))
-            fields.push({ field, message: "Choose a narration segment." });
+            fields.push({
+                field,
+                message: "Choose which part of the narration this audio file replaces.",
+            });
     }
     return fields;
 }
@@ -81,7 +93,10 @@ export function validateAssetReferences(deps, projectId, content, prepared) {
             deps.db
                 .prepare("SELECT 1 FROM project_assets WHERE project_id=? AND id=?")
                 .get(projectId, id) === undefined)
-            fields.push({ field, message: "Choose an asset belonging to this project." });
+            fields.push({
+                field,
+                message: "This file does not belong to this project. Reload the page and choose again.",
+            });
         if (!prepared.some((row) => row.id === id) &&
             deps.db
                 .prepare("SELECT 1 FROM revision_outputs WHERE project_id=? AND asset_id=? AND json_extract(descriptor,'$.stageKind')=? AND json_extract(descriptor,'$.role') IN (SELECT value FROM json_each(?))")
@@ -95,7 +110,10 @@ export function validateAssetReferences(deps, projectId, content, prepared) {
                 deps.db
                     .prepare("SELECT 1 FROM project_revisions r, json_each(r.content, '$.narrationOverrides') o WHERE r.project_id=? AND json_extract(o.value,'$.kind')='asset' AND json_extract(o.value,'$.assetId')=? LIMIT 1")
                     .get(projectId, id) !== undefined))
-            fields.push({ field, message: "Choose an asset for this content stage." });
+            fields.push({
+                field,
+                message: "This file cannot be used in this section. Choose a file of the right kind.",
+            });
     }
     return fields;
 }
@@ -144,5 +162,5 @@ export function validateReplacementAvailability(deps, base, edit) {
         previous.has(id) ||
         statSync(outputPath(deps.paths, base.revision.projectId, assetPath(deps, base.revision.projectId, id)), { throwIfNoEntry: false })?.isFile()
         ? []
-        : [{ field: "content", message: "The replacement asset is missing. Upload it again." }]);
+        : [{ field: "content", message: "The replacement file is missing. Upload it again." }]);
 }

package/dist/slices/revisions/mutation-cues.js

@@ -34,7 +34,7 @@ export function validateProposedCues(base, edit, plan, prepared, durations) {
     const fail = () => [
         {
             field: "content.subtitleCues",
-            message: "Save captions against the current, complete narration timeline.",
+            message: "The narration changed or is not finished, so these captions no longer line up. Reload the page and edit the captions again once narration is complete.",
         },
     ];
     const candidates = [
@@ -82,7 +82,9 @@ export function validateProposedCues(base, edit, plan, prepared, durations) {
     if (parts.some((one) => one === undefined))
         return fail();
     const seconds = parts.reduce((sum, one) => sum + (one ?? 0), 0) / 1000 +
-        Math.max(0, keys.length - 1) * plan.config.silenceGapSeconds;
+        Math.max(0, keys.length - 1) * plan.config.silenceGapSeconds +
+        // The lead-in and the tail are part of the timeline the cues are timed against.
+        2 * plan.config.edgeSilenceSeconds;
     return validateCues(cues.cues, seconds);
 }
 export function measuredOutputs(deps, base, durations) {

package/dist/slices/revisions/projection.js

@@ -1,12 +1,13 @@
 import { z } from "zod";
 import { stageKinds } from "../../kernel/pipeline.js";
 import { insertPiece } from "../../kernel/runner/piece-repo.js";
+import { sourceOf } from "../admission/model.js";
 import { recipeInputSchema } from "../rebuild/recipe-input-schema.js";
 import { insertOutput } from "../storage/repo.js";
 import { insertManifestOutput, insertManifestPiece, outputsForRevision, piecesForRevision, selectOutputRecord, selectPieceRecord, } from "./repo.js";
 export function ensureRevisionStages(deps, revision) {
     for (const kind of stageKinds) {
-        const source = revision.config.sources[kind];
+        const source = sourceOf(revision.config.sources, kind);
         deps.db
             .prepare("INSERT INTO stages(id,project_id,kind,source,state) VALUES (?,?,?,?,?) ON CONFLICT(project_id,kind) DO UPDATE SET source=excluded.source")
             .run(deps.ids.next(), revision.projectId, kind, source, source === "off" ? "skipped" : "pending");

package/dist/slices/revisions/rules.js

@@ -51,16 +51,25 @@ export function validateCues(cues, duration) {
     for (const [index, cue] of cues.entries()) {
         const field = `content.subtitleCues.cues.${index}`;
         if (seen.has(cue.id))
-            fields.push({ field: `${field}.id`, message: "Caption IDs must be unique." });
+            fields.push({
+                field: `${field}.id`,
+                message: "Two captions have the same ID. Reload the page and edit the captions again.",
+            });
         seen.add(cue.id);
         if (cue.text.trim() === "")
-            fields.push({ field: `${field}.text`, message: "Caption text is required." });
+            fields.push({
+                field: `${field}.text`,
+                message: "Enter the caption text, or delete this caption.",
+            });
         if (!Number.isFinite(cue.start) || cue.start < end)
-            fields.push({ field: `${field}.start`, message: "Start must follow the previous caption." });
+            fields.push({
+                field: `${field}.start`,
+                message: "This caption must start after the previous one ends.",
+            });
         if (!Number.isFinite(cue.end) || cue.end <= cue.start || cue.end > duration)
             fields.push({
                 field: `${field}.end`,
-                message: "End must follow start and fit the narration.",
+                message: "This caption must end after it starts and before the narration ends.",
             });
         end = cue.end;
     }
@@ -75,7 +84,7 @@ export function validateTemplateIntent(base, edit) {
                 base.revision.config.rendered[key] === edit.config.rendered[key])
                 fields.push({
                     field: `content.promptTemplates.${key}`,
-                    message: "Choose the raw template or explicitly keep the current prompt before changing keywords.",
+                    message: "This prompt was edited by hand, so new keywords will not change it. Switch it back to its template, or choose to keep your edited prompt, first.",
                 });
         }
         for (const [key, image] of Object.entries(base.revision.content.imageDefinitions)) {
@@ -87,7 +96,7 @@ export function validateTemplateIntent(base, edit) {
                 next.prompt === image.prompt)
                 fields.push({
                     field: `content.imageDefinitions.${key}.templateKey`,
-                    message: "Choose the raw template or explicitly keep the current image prompt before changing keywords.",
+                    message: "This image prompt was edited by hand, so new keywords will not change it. Switch it back to its template, or choose to keep your edited prompt, first.",
                 });
         }
     }
@@ -99,7 +108,7 @@ export function validateTemplateIntent(base, edit) {
                 isDeepStrictEqual(base.revision.content.imageDefinitions[key], image)))
             fields.push({
                 field: `content.imageDefinitions.${key}.templateKey`,
-                message: "The linked raw image template is missing.",
+                message: "The prompt template this image uses is missing. Choose another image prompt.",
             });
     return fields;
 }
@@ -132,13 +141,13 @@ export function validateNarrationIntent(base, edit) {
         if (!isDeepStrictEqual(value, base.revision.content.narrationOverrides[key]) && !keys.has(key))
             fields.push({
                 field: `content.narrationOverrides.${key}`,
-                message: "Choose an active narration group or entry.",
+                message: "This narration part no longer exists. Reload the page and choose again.",
             });
     for (const [index, upload] of (edit.uploads ?? []).entries())
         if (upload.destination.kind === "narration" && !keys.has(upload.destination.key))
             fields.push({
                 field: `uploads.${index}.destination.key`,
-                message: "Choose an active narration group or entry.",
+                message: "This narration part no longer exists. Reload the page and choose again.",
             });
     return fields;
 }

package/dist/slices/revisions/schema.js

@@ -20,7 +20,7 @@ const cue = z
     .strict()
     .refine((value) => value.end > value.start, {
     path: ["end"],
-    message: "End must be after start.",
+    message: "The end time must be after the start time.",
 });
 export const revisionContentSchema = z
     .object({