@gentbajko/slopify 2.4.0 → 2.5.0

package/dist/slices/notifications/settings.js

@@ -0,0 +1,34 @@
+import { readSetting, writeSetting } from "../settings/repo.js";
+import { notificationUrlProblem } from "./rules.js";
+// Its own row in the key/value `settings` table. Backups leave it out
+// (`slices/storage/portable.ts`): an ntfy topic in the URL is as good as a password.
+export const notificationUrlKey = "notificationUrl";
+export function readNotificationUrl(db) {
+    const stored = readSetting(db, notificationUrlKey);
+    if (stored === undefined)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(stored);
+    }
+    catch {
+        return null;
+    }
+    // A hand-edited row that no longer passes the rules is treated as not set rather than
+    // POSTed to.
+    return typeof value === "string" && value !== "" && notificationUrlProblem(value) === undefined
+        ? value
+        : null;
+}
+export function saveNotificationUrl(db, raw) {
+    const problem = notificationUrlProblem(raw);
+    if (problem !== undefined)
+        return { ok: false, message: problem };
+    const url = raw.trim();
+    if (url === "") {
+        db.prepare("DELETE FROM settings WHERE key = ?").run(notificationUrlKey);
+        return { ok: true, url: null };
+    }
+    writeSetting(db, notificationUrlKey, JSON.stringify(url));
+    return { ok: true, url };
+}

package/dist/slices/play-drafts/convert.js

@@ -4,6 +4,14 @@ import { runDraftSchema } from "../admission/schema.js";
 import { draftDocumentThemeOf } from "../document/model.js";
 import { defaultShorts, shortsExtrasOf, shortsSettingsProblems, } from "../shorts/model.js";
 import { defaultSubtitles } from "../subtitles/model.js";
+// Said where the control is, since the music sits in a closed disclosure on the Export rail.
+const musicMessages = {
+    uploading: "The shorts' background music is still uploading, so the run can't start yet. Wait for it to finish, or remove it under Outputs → Export → More shorts options → Background music.",
+    missing: "The shorts' background music file is no longer available (it was not uploaded again after the draft was copied, or the upload failed). Choose the file again under Outputs → Export → More shorts options → Background music, or remove it.",
+};
+function pickMusic(id) {
+    return id === undefined ? {} : { shortsMusic: id };
+}
 export function toAdmissionDraft(input) {
     const { form } = input.document;
     const fields = [];
@@ -49,15 +57,18 @@ export function toAdmissionDraft(input) {
         });
         return undefined;
     };
-    const file = (ref, kind, field) => {
+    const file = (ref, kind, field, messages = {
+        uploading: "This file is still uploading. Wait for it to finish.",
+        missing: "That upload is no longer available. Choose the file again.",
+    }) => {
         const attachment = input.attachments.find((item) => item.id === ref?.attachmentId && item.kind === kind && item.name === ref.name);
         if (attachment?.state === "ready" && attachment.stagedFileId !== null)
             return attachment.stagedFileId;
         fields.push({
             field,
             message: attachment?.state === "copying" || attachment?.state === "pending"
-                ? "This file is still uploading. Wait for it to finish."
-                : "That upload is no longer available. Choose the file again.",
+                ? messages.uploading
+                : messages.missing,
         });
         return undefined;
     };
@@ -119,6 +130,19 @@ export function toAdmissionDraft(input) {
                     : form.audio
             : undefined,
         images: form.images,
+        // The establishing image belongs to generated images; Off, or images not generated,
+        // leaves it out, which is what every draft saved before it was.
+        ...(sources.images === "generate" &&
+            form.reference !== undefined &&
+            form.reference.source !== "off"
+            ? {
+                reference: {
+                    source: form.reference.source,
+                    ...(form.reference.source === "prompt" ? { prompt: form.reference.prompt } : {}),
+                    thumbnail: form.reference.thumbnail,
+                },
+            }
+            : {}),
         articlePrompt: sources.article === "generate" ? form.articlePrompt : undefined,
         ...(sources.audio === "generate" && form.narrationPrompt?.trim()
             ? { narrationPrompt: form.narrationPrompt }
@@ -154,12 +178,20 @@ export function toAdmissionDraft(input) {
             thumbnail: sources.thumbnail === "provide"
                 ? file(form.provided.thumbnail, "thumbnail", "provided.thumbnail")
                 : undefined,
+            reference: sources.images === "generate" && form.reference?.source === "provide"
+                ? file(form.provided.reference ?? null, "reference", "provided.reference")
+                : undefined,
             images: sources.images === "provide"
                 ? form.provided.images.flatMap((ref, index) => {
                     const id = file(ref, "images", `provided.images.${index}`);
                     return id === undefined ? [] : [id];
                 })
                 : [],
+            // Optional, so only a file that was attached is checked; with Shorts off it is kept on
+            // the draft for when Shorts is turned back on, and never reaches the run.
+            ...(shortsOn && form.provided.shortsMusic
+                ? pickMusic(file(form.provided.shortsMusic, "audio", "shorts.music", musicMessages))
+                : {}),
         },
         chunking: {
             mode: chunkMode,

package/dist/slices/play-drafts/repo.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { fingerprint } from "../../kernel/runner/work.js";
+import { draftAttachmentKinds } from "./schema.js";
 const rowSchema = z.object({
     id: z.string(),
     schema_version: z.number(),
@@ -21,7 +22,7 @@ const attachmentSchema = z.object({
     id: z.string(),
     draft_id: z.string(),
     staged_file_id: z.string().nullable(),
-    kind: z.enum(["audio", "images", "thumbnail"]),
+    kind: z.enum(draftAttachmentKinds),
     original_filename: z.string(),
     status: z.enum(["pending", "ready", "reattach"]),
     error: z.string().nullable(),
@@ -52,6 +53,11 @@ export function attachmentRefs(document) {
         ...(p.audio === null ? [] : [{ ...p.audio, kind: "audio" }]),
         ...p.images.map((file) => ({ ...file, kind: "images" })),
         ...(p.thumbnail === null ? [] : [{ ...p.thumbnail, kind: "thumbnail" }]),
+        ...(p.reference === undefined || p.reference === null
+            ? []
+            : [{ ...p.reference, kind: "reference" }]),
+        // The shorts' music is staged like narration audio, so it is an audio attachment.
+        ...(p.shortsMusic == null ? [] : [{ ...p.shortsMusic, kind: "audio" }]),
     ];
 }
 export function requestHash(value) {

package/dist/slices/play-drafts/review-inputs.js

@@ -110,7 +110,9 @@ export function resolveReviewInputs(deps, view, font) {
     const activeIds = new Set(runs.flatMap((run) => [
         run.draft.provided.audio,
         run.draft.provided.thumbnail,
+        run.draft.provided.reference,
         ...(run.draft.provided.images ?? []),
+        run.draft.provided.shortsMusic,
     ]));
     const attachmentIdentity = fresh.value.attachments.flatMap((file) => file.stagedFileId !== null && activeIds.has(file.stagedFileId)
         ? [{ id: file.id, stagedFileId: file.stagedFileId, bytes: file.bytes }]

package/dist/slices/play-drafts/schema.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { formats, stageKinds } from "../../kernel/pipeline.js";
 import { thinkingModes } from "../../kernel/ports/llm.js";
-import { motionStyles, stageSources } from "../admission/model.js";
+import { motionStyles, referenceSources, stageSources } from "../admission/model.js";
 import { defaultEdgeSilenceSeconds, defaultImageSeconds, defaultMotionStyle, defaultZoomPercent, } from "../admission/rules.js";
 import { runDraftSchema, videoEditSchema } from "../admission/schema.js";
 import { checkpointRowSchema, checkpointStageSchema } from "../checkpoints/schema.js";
@@ -15,6 +15,8 @@ const values = z.record(text, text).readonly();
 const provider = z
     .object({ provider: text, model: text, thinking: z.enum(thinkingModes).optional() })
     .strict();
+// What a draft's uploads are for: a stage's files, or the Images stage's establishing image.
+export const draftAttachmentKinds = ["audio", "images", "thumbnail", "reference"];
 const file = z.object({ attachmentId: id, name: text }).strict().readonly();
 export const playDraftFormSchema = z
     .object({
@@ -45,6 +47,17 @@ export const playDraftFormSchema = z
     })
         .readonly(),
     images: provider.readonly(),
+    // Absent on drafts and templates saved before the establishing image: Off. The prompt is
+    // an image prompt's name, "" when none is picked.
+    reference: z
+        .object({
+        source: z.enum(["off", ...referenceSources]),
+        prompt: text,
+        thumbnail: z.boolean(),
+    })
+        .strict()
+        .readonly()
+        .optional(),
     articlePrompt: text,
     narrationPrompt: text.optional(),
     // Absent on drafts and templates saved before the YouTube description: off, built-in prompt.
@@ -105,6 +118,11 @@ export const playDraftFormSchema = z
         audio: file.nullable(),
         thumbnail: file.nullable(),
         images: z.array(file).readonly(),
+        // The uploaded establishing image; absent on drafts saved before it.
+        reference: file.nullable().optional(),
+        // The Shorts step's background music, uploaded as an audio attachment. Absent on
+        // drafts and templates saved before Play offered it: no music.
+        shortsMusic: file.nullable().optional(),
     })
         .strict()
         .readonly(),
@@ -150,7 +168,7 @@ export const discardDraftInputSchema = z
 export const draftAttachmentSchema = z
     .object({
     id,
-    kind: z.enum(["audio", "images", "thumbnail"]),
+    kind: z.enum(draftAttachmentKinds),
     name: text,
     state: z.enum(["pending", "copying", "ready", "reattach"]),
     stagedFileId: text.nullable(),

package/dist/slices/play-drafts/service.js

@@ -208,6 +208,12 @@ export function forkDraft(deps, input) {
                     audio: p.audio === null ? null : rewrite(p.audio),
                     thumbnail: p.thumbnail === null ? null : rewrite(p.thumbnail),
                     images: p.images.map(rewrite),
+                    ...(p.reference === undefined
+                        ? {}
+                        : { reference: p.reference === null ? null : rewrite(p.reference) }),
+                    ...(p.shortsMusic === undefined
+                        ? {}
+                        : { shortsMusic: p.shortsMusic === null ? null : rewrite(p.shortsMusic) }),
                 },
             },
         };

package/dist/slices/play-drafts/uploads.js

@@ -29,7 +29,8 @@ export async function uploadDraftAttachment(deps, input) {
         return refuse("conflict");
     const storage = { ...deps, emit: () => undefined };
     const result = await stageUpload(storage, {
-        stageKind: attachment.kind,
+        // The establishing image is the Images stage's upload.
+        stageKind: attachment.kind === "reference" ? "images" : attachment.kind,
         originalFilename: attachment.original_filename,
         content: input.content,
         onAllocated(file) {

package/dist/slices/project-templates/from-project.js

@@ -103,6 +103,10 @@ function documentFromProject(deps, revision) {
     // and a snapshot holds one prompt per kind and name.
     if (!prompts.some((prompt) => prompt.kind === "image" && prompt.name === config.shorts?.imagePrompt))
         addPrompt("image", config.shorts?.imagePrompt, "shortsImage");
+    // The establishing image's prompt, the same way.
+    if (config.reference?.source === "prompt" &&
+        !prompts.some((prompt) => prompt.kind === "image" && prompt.name === config.reference?.prompt))
+        addPrompt("image", config.reference.prompt, "referencePrompt");
     for (const category of ["intro", "outro"]) {
         const choice = config[category];
         const body = revision.content.promptTemplates[category] ?? config.rendered[category];
@@ -125,9 +129,16 @@ function documentFromProject(deps, revision) {
             : "",
         audio: config.sources.audio === "provide" ? attachment("Audio from project") : null,
         thumbnail: config.sources.thumbnail === "provide" ? attachment("Thumbnail from project") : null,
+        ...(config.reference?.source === "provide"
+            ? { reference: attachment("Establishing image from project") }
+            : {}),
         images: config.sources.images === "provide"
             ? (definitions.length ? definitions : (config.provided.images ?? [])).map((_, index) => attachment(`Image ${index + 1}`))
             : [],
+        // Named like the project's other files, to be attached again on Play.
+        ...(config.shorts?.enabled === true && revision.content.shortsMusic !== undefined
+            ? { shortsMusic: attachment("Music from project") }
+            : {}),
     };
     return {
         schemaVersion: 1,
@@ -147,6 +158,15 @@ function documentFromProject(deps, revision) {
             llm: config.llm ?? { provider: "", model: "" },
             audio: config.audio ?? { provider: "", model: "", voice: "" },
             images: config.images ?? { provider: "", model: "" },
+            ...(config.reference === undefined
+                ? {}
+                : {
+                    reference: {
+                        source: config.reference.source,
+                        prompt: config.reference.prompt ?? "",
+                        thumbnail: config.reference.thumbnail !== false,
+                    },
+                }),
             articlePrompt: config.articlePrompt ?? "",
             ...(config.narrationPrompt === undefined ? {} : { narrationPrompt: config.narrationPrompt }),
             ...(config.youtubeDescription === true ? { youtubeDescription: true } : {}),

package/dist/slices/project-templates/setup.js

@@ -10,6 +10,10 @@ export function templateSetup(deps, input) {
         { kind: "thumbnail", name: input.form.thumbnailPrompt },
         { kind: "shorts", name: input.form.shorts?.prompt ?? "" },
         { kind: "image", name: input.form.shorts?.imagePrompt ?? "" },
+        {
+            kind: "image",
+            name: input.form.reference?.source === "prompt" ? input.form.reference.prompt : "",
+        },
     ];
     for (const choice of choices) {
         if (choice.name === "")
@@ -53,6 +57,13 @@ export function freshTemplateDraft(deps, document, source) {
                 audio: provided.audio === null ? null : fresh(provided.audio),
                 thumbnail: provided.thumbnail === null ? null : fresh(provided.thumbnail),
                 images: provided.images.map(fresh),
+                ...(provided.reference === undefined
+                    ? {}
+                    : { reference: provided.reference === null ? null : fresh(provided.reference) }),
+                // Like the images: the name is kept and the file is attached again on Play.
+                ...(provided.shortsMusic === undefined
+                    ? {}
+                    : { shortsMusic: provided.shortsMusic === null ? null : fresh(provided.shortsMusic) }),
             },
         },
     };

package/dist/slices/rebuild/preview-details.js

@@ -46,9 +46,19 @@ export function previewDetails(deps, view, allRecipes, selected) {
             return [
                 {
                     key: row.key,
-                    label: index < 0 ? "Thumbnail image" : `Image ${index + 1}`,
+                    label: row.key === "reference:image"
+                        ? "Establishing image"
+                        : index < 0
+                            ? "Thumbnail image"
+                            : `Image ${index + 1}`,
                     text: input.prompt,
-                    settings: [input.provider, input.model, input.aspect].join(" · "),
+                    settings: [
+                        input.provider,
+                        input.model,
+                        ...(input.thinking === undefined ? [] : [`effort ${input.thinking}`]),
+                        input.aspect,
+                        ...(input.reference === undefined ? [] : ["drawn from the establishing image"]),
+                    ].join(" · "),
                 },
             ];
         }
@@ -142,6 +152,12 @@ function inputChanges(parent, view) {
         : `${String(after.shorts.minSeconds)}-${String(after.shorts.maxSeconds)}`);
     add("Shorts prompt", before.shorts?.prompt, after.shorts?.prompt);
     add("Shorts image prompt", before.shorts?.imagePrompt, after.shorts?.imagePrompt);
+    add("Establishing image", referenceLabel(before), referenceLabel(after));
+    add("Thumbnail drawn from the establishing image", before.reference === undefined
+        ? undefined
+        : before.reference.thumbnail === false
+            ? "Off"
+            : "On", after.reference === undefined ? undefined : after.reference.thumbnail === false ? "Off" : "On");
     add("Title on the shorts", before.shorts === undefined ? undefined : before.shorts.titleOnScreen === true ? "On" : "Off", after.shorts === undefined ? undefined : after.shorts.titleOnScreen === true ? "On" : "Off");
     add("Shorts speed", before.shorts === undefined ? undefined : `${shortsSpeedOf(before.shorts).toFixed(2)}×`, after.shorts === undefined ? undefined : `${shortsSpeedOf(after.shorts).toFixed(2)}×`);
     add("Shorts music", old.shortsMusic === undefined ? "None" : "Uploaded file", next.shortsMusic === undefined
@@ -191,3 +207,9 @@ function inputChanges(parent, view) {
     add("Manual captions", old.subtitleCues?.cues, next.subtitleCues?.cues);
     return changes;
 }
+function referenceLabel(config) {
+    const reference = config.reference;
+    if (reference === undefined)
+        return "Off";
+    return reference.source === "provide" ? "Uploaded image" : `Prompt: ${reference.prompt ?? ""}`;
+}

package/dist/slices/rebuild/recipe-build.js

@@ -1,7 +1,9 @@
+import { referenceForThumbnail } from "../admission/rules.js";
 import { audioRecipes } from "./recipe-audio.js";
 import { documentRecipes } from "./recipe-document.js";
 import { editPlan } from "./recipe-edit.js";
 import { exportRecipes } from "./recipe-exports.js";
+import { imageReference, referenceRecipe } from "./recipe-reference.js";
 import { shortsRecipes } from "./recipe-shorts.js";
 import { textRecipes } from "./recipe-text.js";
 import { thumbnailRecipes, visualAssets, visualRecipes } from "./recipe-visual.js";
@@ -11,16 +13,20 @@ export function buildRecipes(context) {
     const audio = audioRecipes(context, text);
     const exports = exportRecipes(context, audio);
     const captions = exports.find((value) => value.key === "subtitles:files");
-    const thumbnail = thumbnailRecipes(context, text.recipes);
+    // The establishing image, when it is on: every other image is drawn from it.
+    const reference = referenceRecipe(context);
+    const drawnFrom = imageReference(context, reference);
+    const thumbnail = thumbnailRecipes(context, text.recipes, referenceForThumbnail(context.config) ? drawnFrom : undefined);
     const youtube = youtubeRecipes(context, exports);
     return [
         ...text.recipes,
         ...audio.recipes,
         ...exports,
         ...youtube,
-        ...shortsRecipes(context, exports),
+        ...(reference === undefined ? [] : [reference]),
+        ...shortsRecipes(context, exports, drawnFrom),
         ...thumbnail,
         ...documentRecipes(context, text, thumbnail),
-        ...visualAssets(context, visualRecipes(context.config, context.content, audio.mediaFingerprint, captions?.fingerprint ?? null, (images) => editPlan(context, exports, youtube, images))),
+        ...visualAssets(context, visualRecipes(context.config, context.content, audio.mediaFingerprint, captions?.fingerprint ?? null, (images) => editPlan(context, exports, youtube, images), drawnFrom)),
     ];
 }

package/dist/slices/rebuild/recipe-input-schema.js

@@ -23,7 +23,9 @@ export const recipeInputSchema = z.discriminatedUnion("kind", [
             .object({
             budget: z.number().finite().optional(),
             level: z.enum(["minimal", "low", "medium", "high"]).optional(),
-            effort: z.enum(["none", "minimal", "low", "medium", "high", "xhigh"]).optional(),
+            effort: z
+                .enum(["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"])
+                .optional(),
         })
             .strict()
             .nullable(),
@@ -67,6 +69,11 @@ export const recipeInputSchema = z.discriminatedUnion("kind", [
         prompt: z.string(),
         aspect: z.enum(["16:9", "9:16"]),
         animate: z.object({ image: z.string(), seconds: z.number() }).strict().optional(),
+        thinking: z.enum(thinkingModes).optional(),
+        reference: z
+            .object({ fingerprint: z.string(), assetId: z.string().nullable() })
+            .strict()
+            .optional(),
     })
         .strict(),
     z

package/dist/slices/rebuild/recipe-legacy.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { referenceKey } from "../admission/model.js";
 import { buildRecipes } from "./recipe-build.js";
 export function baselineFingerprints(project, outputs, pieces, content, stages = []) {
     const recipes = buildRecipes({
@@ -34,6 +35,8 @@ export function legacyOutputWorkKey(output, config) {
             return `image:${output.id}`;
         case "thumbnail":
             return "thumbnail:image";
+        case "reference":
+            return referenceKey;
         case "notes":
             return "research:notes";
         case "article_md":

package/dist/slices/rebuild/recipe-reference.js

@@ -0,0 +1,44 @@
+import { referenceKey } from "../admission/model.js";
+import { usesReference } from "../admission/rules.js";
+import { recipe, selectedAsset, } from "./recipe-model.js";
+import { renderedPrompt } from "./recipe-text.js";
+// The establishing image (`RunDraft.reference`): one step of the Images stage, made before
+// every other image of the run and never part of the video. Made from its library prompt, whose
+// keywords are filled like every other image prompt's, or the file the user uploaded.
+export const referencePromptKey = "referencePrompt";
+// The image provider's choice as an image request carries it: the effort only when one is set,
+// so a request made without one keeps the fingerprint it always had.
+export function imageChoice(config) {
+    return {
+        provider: config.images?.provider ?? "",
+        model: config.images?.model ?? "",
+        ...(config.images?.thinking === undefined ? {} : { thinking: config.images.thinking }),
+    };
+}
+export function referenceRecipe(context) {
+    const { config, content } = context;
+    if (!usesReference(config) || config.reference === undefined)
+        return undefined;
+    if (config.reference.source === "provide")
+        return recipe(context, referenceKey, "images", {
+            kind: "provided",
+            version: 1,
+            assetId: content.provided.reference ?? null,
+            semantic: "reference",
+        }, [], { unresolved: content.provided.reference === undefined });
+    const prompt = renderedPrompt(context, referencePromptKey);
+    return recipe(context, referenceKey, "images", { kind: "image", version: 1, ...imageChoice(config), aspect: config.format, prompt }, [], { unresolved: prompt.trim() === "" });
+}
+// Which image the others are drawn from: the step's fingerprint, so making it again or
+// changing it marks every image drawn from it outdated, and the asset it made.
+export function imageReference(context, reference) {
+    return reference === undefined
+        ? undefined
+        : {
+            key: reference.key,
+            input: {
+                fingerprint: reference.fingerprint,
+                assetId: selectedAsset(context, reference.key, reference.fingerprint),
+            },
+        };
+}

package/dist/slices/rebuild/recipe-shorts.js

@@ -5,6 +5,7 @@ import { effectiveClips, pickedShortsOf } from "../shorts/clips.js";
 import { defaultShortsImagePrompt, musicVolumeOf, shortImageCount, shortsSpeedOf, } from "../shorts/model.js";
 import { imagePromptMessages } from "../shorts/prompts.js";
 import { recipe, resourceIdentity, selectedReference, } from "./recipe-model.js";
+import { imageChoice } from "./recipe-reference.js";
 import { llmInput, renderedPrompt } from "./recipe-text.js";
 // The Shorts step unfolds as its answers land, the way research's chapters unfold from the
 // plan. `shorts:pick` reads the word timing, so it waits for `subtitles:timing` and runs
@@ -19,7 +20,9 @@ import { llmInput, renderedPrompt } from "./recipe-text.js";
 // can be made again alone.
 export const shortsPickKey = "shorts:pick";
 export const shortsFutureKey = "shorts:future";
-export function shortsRecipes(context, exports) {
+export function shortsRecipes(context, exports, 
+// The establishing image the shorts' images are drawn from, when it is on.
+reference) {
     const { config } = context;
     const shorts = config.shorts;
     const timing = exports.find((value) => value.key === "subtitles:timing");
@@ -67,6 +70,10 @@ export function shortsRecipes(context, exports) {
                     shorts.maxSeconds,
                     config.llm?.provider ?? "",
                     config.llm?.model ?? "",
+                    // Only what is in use, so shorts planned before these existed keep their
+                    // fingerprint; the estimate reads the fields above by position.
+                    ...(config.images?.thinking === undefined ? [] : [config.images.thinking]),
+                    ...(reference === undefined ? [] : [reference.input.fingerprint]),
                 ],
             }, [pick.key], { tokenKey: shortsPickKey }),
         ];
@@ -94,11 +101,11 @@ export function shortsRecipes(context, exports) {
         const stills = written.map((prompt, index) => recipe(context, `${prefix}:image:${String(index + 1)}`, "video", {
             kind: "image",
             version: 1,
-            provider: images.provider,
-            model: images.model,
+            ...imageChoice(config),
             prompt,
             aspect: "9:16",
-        }, [prompts.key], { token }));
+            ...(reference === undefined ? {} : { reference: reference.input }),
+        }, [prompts.key, ...(reference === undefined ? [] : [reference.key])], { token }));
         recipes.push(...stills);
         const extras = renderExtras(context, clip);
         recipes.push(recipe(context, `${prefix}:render`, "video", {

package/dist/slices/rebuild/recipe-validation.js

@@ -1,4 +1,4 @@
-import { narrationPreparationFields, shortsFields, usesNarrationPreparation, usesShorts, usesYoutubeDescription, videoEditFields, youtubeDescriptionFields, } from "../admission/rules.js";
+import { narrationPreparationFields, shortsFields, usesNarrationPreparation, usesReference, usesShorts, usesYoutubeDescription, videoEditFields, youtubeDescriptionFields, } from "../admission/rules.js";
 import { detectSlots, render } from "../admission/substitute.js";
 import { usesAnimation } from "../video/edit-settings.js";
 export function validateRecipeInputs(config, content) {
@@ -93,6 +93,20 @@ export function validateRecipeInputs(config, content) {
             raw: content.promptTemplates.thumbnailPrompt ?? null,
             literal: config.rendered.thumbnailPrompt,
         });
+    // The establishing image: its prompt is checked like the thumbnail's, an upload must be there.
+    if (usesReference(config) && config.reference?.source === "prompt")
+        prompts.push({
+            field: "rendered.referencePrompt",
+            raw: content.promptTemplates.referencePrompt ?? null,
+            literal: config.rendered.referencePrompt,
+        });
+    if (usesReference(config) &&
+        config.reference?.source === "provide" &&
+        content.provided.reference === undefined)
+        fields.push({
+            field: "content.provided.reference",
+            message: "Upload the establishing image, choose From a prompt instead, or set Establishing image to Off.",
+        });
     if (config.sources.images !== "off")
         for (const key of content.imageOrder) {
             const image = content.imageDefinitions[key];

package/dist/slices/rebuild/recipe-visual.js

@@ -1,9 +1,12 @@
 import { render } from "../admission/substitute.js";
 import { recipe, resourceIdentity, } from "./recipe-model.js";
+import { imageChoice } from "./recipe-reference.js";
 import { matchingText, renderedPrompt } from "./recipe-text.js";
 export function visualRecipes(config, content, audioFingerprint, captionFingerprint, 
 // What the Video stage's edit settings add (`recipe-edit.ts`), from the images planned here.
-edit) {
+edit, 
+// The establishing image the generated images are drawn from, when it is on.
+reference) {
     const recipes = [];
     const imageKeys = config.sources.images === "off" ? [] : content.imageOrder;
     for (const key of imageKeys) {
@@ -19,11 +22,11 @@ edit) {
             : {
                 kind: "image",
                 version: 1,
-                provider: config.images?.provider ?? "",
-                model: config.images?.model ?? "",
+                ...imageChoice(config),
                 aspect: config.format,
                 prompt: prompt ?? "",
-            }, [], { unresolved: image.source === "provide" ? image.assetId === null : !prompt?.trim() }));
+                ...(reference === undefined ? {} : { reference: reference.input }),
+            }, image.source === "provide" || reference === undefined ? [] : [reference.key], { unresolved: image.source === "provide" ? image.assetId === null : !prompt?.trim() }));
     }
     if (config.sources.video !== "off") {
         const edited = edit?.([...recipes]) ?? { recipes: [], values: [], dependsOn: [] };
@@ -73,7 +76,9 @@ edit) {
     }
     return recipes;
 }
-export function thumbnailRecipes(context, textRecipes) {
+export function thumbnailRecipes(context, textRecipes, 
+// The establishing image, when it is on and the thumbnail is drawn from it too.
+reference) {
     const { config, content } = context;
     if (config.sources.thumbnail === "off")
         return [];
@@ -101,16 +106,23 @@ export function thumbnailRecipes(context, textRecipes) {
                     config.images?.provider ?? null,
                     config.images?.model ?? null,
                     config.format,
+                    // Only what is in use, so a thumbnail made before these existed keeps its
+                    // fingerprint.
+                    ...(config.images?.thinking === undefined ? [] : [config.images.thinking]),
+                    ...(reference === undefined ? [] : [reference.input.fingerprint]),
                 ],
             }
             : {
                 kind: "image",
                 version: 1,
-                provider: config.images?.provider ?? "",
-                model: config.images?.model ?? "",
+                ...imageChoice(config),
                 aspect: config.format,
                 prompt,
-            }, promptRecipe === undefined ? [] : [promptRecipe.key]),
+                ...(reference === undefined ? {} : { reference: reference.input }),
+            }, [
+            ...(promptRecipe === undefined ? [] : [promptRecipe.key]),
+            ...(reference === undefined ? [] : [reference.key]),
+        ]),
     ];
 }
 export function visualAssets(context, recipes) {

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

@@ -12,7 +12,14 @@ export async function revisionAction(deps, projectId, action) {
     const config = view.revision.config;
     const content = view.revision.content;
     const image = action.kind === "delete-image" || action.kind === "regenerate-image"
-        ? view.outputs.find((row) => row.selected && row.output.id === action.outputId && row.output.role === "image")
+        ? view.outputs.find((row) => row.selected &&
+            row.output.id === action.outputId &&
+            (row.output.role === "image" ||
+                // A generated establishing image is made again like any image; it is never deleted
+                // on its own (Edit project sets it Off), and an uploaded one has nothing to redo.
+                (action.kind === "regenerate-image" &&
+                    row.output.role === "reference" &&
+                    config.reference?.source === "prompt")))
         : undefined;
     if ((action.kind === "delete-image" || action.kind === "regenerate-image") && image === undefined)
         return { ok: false, reason: "unknown-image" };
@@ -64,7 +71,7 @@ function keyStage(key) {
     const prefix = key.split(":")[0];
     if (prefix === "entry" || prefix === "article")
         return "article";
-    if (prefix === "image")
+    if (prefix === "image" || prefix === "reference")
         return "images";
     if (prefix === "audio")
         return "audio";