@gentbajko/slopify 2.0.2 → 2.0.3

package/dist/slices/rebuild/runtime-narration-text.js

@@ -9,7 +9,7 @@ export function joinedNarration(parts) {
 export function narrationTextParts(view, plan, segment) {
     const concat = plan.recipes.find((row) => row.key === (segment === "body" ? "audio:body:concat" : `audio:${segment}`));
     if (concat === undefined)
-        throw new Error(`The saved ${segment} narration is missing.`);
+        throw new Error(`Slopify hit an internal error (the ${segment} narration is missing from the project plan). Retry stage; if it happens again, use Download diagnostics in Settings and report it.`);
     return concat.dependsOn.map((key) => {
         const recipe = plan.recipes.find((row) => row.key === key);
         const selected = view.pieces.find((row) => row.key === key &&
@@ -18,7 +18,7 @@ export function narrationTextParts(view, plan, segment) {
             row.piece.state === "done" &&
             row.fingerprint === recipe?.fingerprint);
         if (selected === undefined || recipe === undefined)
-            throw new Error("The saved narration transcript is incomplete.");
+            throw new Error("Some narration chunks aren't finished, so the full narration text isn't available. Let the Narration stage finish (Resume, or Retry stage on it), or regenerate the missing chunk in Edit project → Narration.");
         const input = recipe.input;
         if (input.kind === "provided" &&
             Array.isArray(input.semantic) &&
@@ -29,13 +29,13 @@ export function narrationTextParts(view, plan, segment) {
                 requestText: null,
             };
         if (input.kind !== "tts")
-            throw new Error("The narration source has not resolved.");
+            throw new Error("Slopify hit an internal error (a narration chunk's text was never worked out). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
         const payload = z
             .object({ text: z.string().optional(), spokenText: z.string().optional() })
             .parse(JSON.parse(selected.piece.payload ?? "{}"));
         if (input.spokenText !== undefined &&
             (payload.spokenText !== input.spokenText || payload.text !== input.text))
-            throw new Error("Prepared narration is missing its exact clean transcript.");
+            throw new Error("A narration chunk's audio no longer matches its prepared text. Regenerate that chunk in Edit project → Narration, then Retry stage.");
         return {
             logicalKey: input.logicalKey,
             spokenText: input.spokenText === undefined ? (payload.text ?? input.text) : (payload.spokenText ?? ""),
@@ -45,7 +45,7 @@ export function narrationTextParts(view, plan, segment) {
 }
 export async function publishNarrationText(deps, context, piece) {
     if (piece.input.kind !== "local")
-        throw new Error("Expected a narration-file recipe.");
+        throw new Error("Slopify hit an internal error (the narration text file step was set up wrongly). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
     const { segment } = z
         .object({ segment: z.enum(["body", "intro", "outro"]) })
         .parse(piece.input.values);
@@ -54,10 +54,10 @@ export async function publishNarrationText(deps, context, piece) {
         .prepare("SELECT recipe_context FROM revision_work WHERE id=?")
         .get(context.work.workId);
     if (view === undefined)
-        throw new Error("The pinned narration revision is missing.");
+        throw new Error("Slopify hit an internal error (the project version being narrated is missing). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
     const plan = executionPlan(deps, view, savedCatalogue(row?.recipe_context));
     if (!plan.recipes.some((recipe) => recipe.key === piece.key && recipe.fingerprint === piece.fingerprint))
-        throw new Error("Narration text no longer matches the admitted inputs.");
+        throw new Error("Slopify hit an internal error (the narration text no longer matches the project's saved inputs). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
     const parts = narrationTextParts(view, plan, segment);
     const outputs = preparedTexts(deps, context, piece, [
         ["narration_txt", `${segment}-narration.txt`, joinedNarration(parts)],
@@ -73,3 +73,42 @@ export async function publishNarrationText(deps, context, piece) {
     }));
     await publishResult(deps, context, piece, outputs, { segment });
 }
+// The narration's chunks in the order they are spoken, each with its clean text. A chunk is
+// sent as one or more parts; the Narration editor numbers these chunks, so anything that
+// names "chunk N" to a person counts from this list.
+export function narrationChunks(parts) {
+    const chunks = [];
+    for (const part of parts) {
+        const last = chunks.at(-1);
+        if (last?.key === part.logicalKey)
+            chunks[chunks.length - 1] = {
+                key: last.key,
+                spokenText: `${last.spokenText}${part.spokenText}`,
+            };
+        else
+            chunks.push({ key: part.logicalKey, spokenText: part.spokenText });
+    }
+    return chunks;
+}
+// The current chunk keys of each narration segment, in spoken order, for the Narration
+// editor. Undefined when the revision has no admitted work to read a plan from, or its
+// narration is not complete yet; the editor then keeps its own listing.
+export function narrationChunkOrder(deps, projectId, revisionId) {
+    const row = deps.db
+        .prepare("SELECT recipe_context FROM revision_work WHERE project_id=? AND revision_id=? AND recipe_context IS NOT NULL LIMIT 1")
+        .get(projectId, revisionId);
+    const view = executionView(deps, projectId, revisionId);
+    if (row === undefined || view === undefined)
+        return undefined;
+    const plan = executionPlan(deps, view, savedCatalogue(row.recipe_context));
+    const order = {};
+    for (const segment of ["intro", "body", "outro"]) {
+        try {
+            order[segment] = narrationChunks(narrationTextParts(view, plan, segment)).map((chunk) => chunk.key);
+        }
+        catch {
+            // A segment that is off, or not narrated yet, has no chunks to order.
+        }
+    }
+    return order;
+}

package/dist/slices/rebuild/runtime-piece-label.js

@@ -0,0 +1,62 @@
+import { executionPlan, executionView, savedCatalogue } from "./runtime-plan.js";
+// What a failed step is called on screen, so its error says which image, chunk or topic to
+// fix. Worked out only after a failure: numbering a narration chunk means building the plan.
+// Undefined for steps that name their own place (captions, export) or have no single one.
+export function pieceLabel(deps, context, piece) {
+    const { key } = piece;
+    if (key === "thumbnail:image" || key.startsWith("thumbnail:"))
+        return "Thumbnail";
+    if (key === "article:body")
+        return "Article";
+    if (key === "entry:intro:text")
+        return "Intro text";
+    if (key === "entry:outro:text")
+        return "Outro text";
+    if (key === "research:planner")
+        return "Research plan";
+    if (key === "research:notes")
+        return "Research notes";
+    const topic = /^research:chapter:(\d+)$/.exec(key);
+    if (topic !== null)
+        return `Research topic ${topic[1] ?? ""}`;
+    const view = () => executionView(deps, context.work.projectId, context.work.revisionId);
+    if (key.startsWith("image:")) {
+        const at = view()?.revision.content.imageOrder.indexOf(key.slice("image:".length)) ?? -1;
+        return at === -1 ? "An image" : `Image ${String(at + 1)}`;
+    }
+    const narration = /^(?:narration:prepare:(?:intro|body|outro):)?audio:(intro|body|outro)(?::(.+))?$/.exec(key);
+    if (narration === null)
+        return undefined;
+    const segment = narration[1] ?? "body";
+    const prefix = segment === "body" ? "Narration" : `${segment === "intro" ? "Intro" : "Outro"} narration`;
+    if (narration[2] === undefined || narration[2] === "concat" || narration[2] === "future")
+        return prefix;
+    return narrationChunk(deps, context, segment, key, prefix) ?? prefix;
+}
+function narrationChunk(deps, context, segment, key, prefix) {
+    const row = deps.db
+        .prepare("SELECT recipe_context FROM revision_work WHERE id=?")
+        .get(context.work.workId);
+    const view = executionView(deps, context.work.projectId, context.work.revisionId);
+    if (row?.recipe_context === null || row === undefined || view === undefined)
+        return undefined;
+    const plan = executionPlan(deps, view, savedCatalogue(row.recipe_context));
+    const concat = plan.recipes.find((recipe) => recipe.key === (segment === "body" ? "audio:body:concat" : `audio:${segment}`));
+    if (concat === undefined)
+        return undefined;
+    // Parts are `<chunk>:<n>`; the chunk is everything before the last colon.
+    const chunkOf = (part) => part.slice(0, part.lastIndexOf(":"));
+    const chunks = [...new Set(concat.dependsOn.map(chunkOf))];
+    const preparing = key.startsWith("narration:prepare:");
+    const chunk = preparing ? key.slice(key.indexOf("audio:")) : chunkOf(key);
+    const at = chunks.indexOf(chunk);
+    if (at === -1)
+        return undefined;
+    const label = `${prefix} chunk ${String(at + 1)} of ${String(chunks.length)}`;
+    if (preparing)
+        return `${label} (preparing its text)`;
+    const parts = concat.dependsOn.filter((part) => chunkOf(part) === chunk);
+    return parts.length > 1
+        ? `${label}, part ${String(parts.indexOf(key) + 1)} of ${String(parts.length)}`
+        : label;
+}

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

@@ -117,13 +117,15 @@ export async function executeProviderRecipe(deps, context, providers, piece) {
         });
         return "done";
     }
-    throw new Error("Expected an exact provider recipe.");
+    throw new Error("Slopify hit an internal error (this step has no provider request to run). Use Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
 }
 function checkAnswer(piece, answer) {
     if (answer.text.trim() === "")
-        return "The provider answered with nothing.";
+        return "The AI model sent back an empty answer. Use Retry stage; if it keeps happening, choose another model in the Providers section of Edit project.";
     if (piece.key === "research:planner")
-        return chaptersFrom(answer.text).length === 0 ? "The planner named no chapters." : undefined;
+        return chaptersFrom(answer.text).length === 0
+            ? "The AI model's research plan listed no chapters, so research could not go on. Use Retry stage; if it keeps happening, choose another model in the Providers section of Edit project."
+            : undefined;
     if (piece.key === "research:notes" || piece.key.startsWith("research:chapter:"))
         return sourcedAnswer(piece.key, answer.text);
     return undefined;
@@ -175,7 +177,7 @@ async function publishText(deps, context, piece, answer) {
             : [];
         const title = titles[Number(piece.key.split(":").at(-1)) - 1];
         if (typeof title !== "string")
-            throw new Error("Research chapter has no pinned title.");
+            throw new Error("Slopify hit an internal error (a research chapter has no title in the research plan). Use Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
         const asset = writeAsset(deps, context.work.projectId, `research-${piece.key.split(":").at(-1)}.md`, Buffer.from(answer.text));
         await publishResult(deps, context, piece, [], { title, notes: answer.text }, asset);
         return;

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

@@ -29,7 +29,7 @@ export function preparedResult(deps, context, piece, role, asset, durationMs = n
 export function preparedText(deps, context, piece, role, filename, text) {
     const output = preparedTexts(deps, context, piece, [[role, filename, text]])[0];
     if (output === undefined)
-        throw new Error("The text output was not prepared.");
+        throw new Error("Slopify hit an internal error (a text file could not be prepared). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
     return output;
 }
 export function preparedTexts(deps, context, piece, texts) {
@@ -168,10 +168,10 @@ export function retainPartialArticle(deps, context, piece, text) {
             if (authority === undefined)
                 return;
             if (authority.key !== piece.key || authority.fingerprint !== piece.fingerprint)
-                throw new Error("Partial article differs from its durable piece authority.");
+                throw new Error("Slopify hit an internal error (a partly written article doesn't match its saved step). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
             const revision = revisionById(deps.db, context.work.projectId, context.work.revisionId);
             if (revision === undefined)
-                throw new Error("Partial article origin disappeared.");
+                throw new Error("Slopify hit an internal error (the project version for a partly written article is missing). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
             insertAsset(deps.db, result.asset);
             insertManifestOutput(deps.db, revision, {
                 slot: `article:partial:${piece.id}`,

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

@@ -1,5 +1,6 @@
 import { executeExportRecipe } from "./runtime-export.js";
 import { executeLocalRecipe } from "./runtime-local.js";
+import { pieceLabel } from "./runtime-piece-label.js";
 import { executeProviderRecipe } from "./runtime-provider.js";
 import { executeSubtitleRecipe } from "./runtime-subtitles.js";
 import { workPieces } from "./work-records.js";
@@ -25,7 +26,16 @@ export async function runRevisionInvocation(deps, context, providers) {
             deps.db
                 .prepare("UPDATE revision_work_pieces SET state=? WHERE id=? AND work_id=? AND state!='done'")
                 .run(context.signal.aborted ? "pending" : "failed", piece.id, context.work.workId);
-            throw error;
+            if (context.signal.aborted || !(error instanceof Error))
+                throw error;
+            let label;
+            try {
+                label = pieceLabel(deps, context, piece);
+            }
+            catch {
+                // The error itself matters more than its label.
+            }
+            throw label === undefined ? error : new Error(`${label}: ${error.message}`, { cause: error });
         }
     }
     deps.db

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

@@ -1,12 +1,14 @@
 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 { 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({
     key: z.string(),
@@ -39,14 +41,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 need narration audio, but this project has none. Turn captions off in Edit project → Subtitles, 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 +58,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 && kind !== "gap") {
+            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 +74,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 +88,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 +100,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 +113,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 +127,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 +204,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/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,5 @@ function stageForKey(key) {
         return "thumbnail";
     if (prefix === "export" || prefix === "subtitles" || prefix === "video")
         return "video";
-    throw new Error("Unknown revision work key.");
+    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/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 = [