videobook 0.0.0-stage → 0.2.0

package/dist/forget-asset.js

@@ -0,0 +1,216 @@
+import { markDescendantsStale } from "./notebook-action-catalog.js";
+import { mutateNotebook } from "./notebook-mutations.js";
+import { removeArtifactFromTimeline } from "./tools/delete-asset.js";
+const CELL_INPUT_ARTIFACT_KEYS = [
+    "firstFrameArtifactId",
+    "lastFrameArtifactId",
+    "providerArtifactId",
+];
+function isString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function inputVersionIds(inputs) {
+    return Array.isArray(inputs.outputVersionArtifactIds)
+        ? inputs.outputVersionArtifactIds.filter(isString)
+        : [];
+}
+function cellHoldsArtifact(cell, artifactId) {
+    const inputs = cell.inputs ?? {};
+    return cell.outputArtifactId === artifactId
+        || (cell.references ?? []).some((reference) => reference.targetId === artifactId)
+        || (cell.pinnedResults ?? []).some((pinned) => pinned.artifactId === artifactId)
+        || CELL_INPUT_ARTIFACT_KEYS.some((key) => inputs[key] === artifactId)
+        || inputVersionIds(inputs).includes(artifactId);
+}
+function detachedInputs(cell, artifactId) {
+    const inputs = { ...(cell.inputs ?? {}) };
+    for (const key of CELL_INPUT_ARTIFACT_KEYS) {
+        if (inputs[key] === artifactId)
+            delete inputs[key];
+    }
+    if (Array.isArray(inputs.outputVersionArtifactIds)) {
+        inputs.outputVersionArtifactIds = inputVersionIds(inputs)
+            .filter((id) => id !== artifactId);
+    }
+    if (cell.outputArtifactId === artifactId)
+        inputs.state = "ready";
+    return inputs;
+}
+function detachedCell(cell, artifactId) {
+    const references = (cell.references ?? [])
+        .filter((reference) => reference.targetId !== artifactId);
+    const pinnedResults = (cell.pinnedResults ?? [])
+        .filter((pinned) => pinned.artifactId !== artifactId);
+    return {
+        ...cell,
+        ...(cell.outputArtifactId === artifactId ? { outputArtifactId: undefined } : {}),
+        inputs: detachedInputs(cell, artifactId),
+        ...(cell.references ? { references } : {}),
+        ...(cell.pinnedResults ? { pinnedResults } : {}),
+    };
+}
+/** A cleared cell reads as never run, so a re-run refills it. */
+function detachedExecution(document, cellIds) {
+    const execution = { ...(document.execution ?? {}) };
+    for (const cellId of cellIds) {
+        const current = execution[cellId];
+        if (!current || typeof current !== "object")
+            continue;
+        execution[cellId] = {
+            ...current,
+            status: "ready",
+            stale: false,
+            outputArtifactId: undefined,
+            providerArtifactId: undefined,
+            error: undefined,
+        };
+    }
+    return execution;
+}
+function detachedDocument(document, artifactId) {
+    const cellIds = document.cells
+        .filter((cell) => cellHoldsArtifact(cell, artifactId))
+        .map((cell) => cell.id);
+    if (cellIds.length === 0)
+        return { document, cellIds };
+    const detached = {
+        ...document,
+        cells: document.cells.map((cell) => cellIds.includes(cell.id) ? detachedCell(cell, artifactId) : cell),
+        execution: detachedExecution(document, cellIds),
+    };
+    return {
+        document: cellIds.reduce((next, cellId) => markDescendantsStale(next, cellId), detached),
+        cellIds,
+    };
+}
+async function detachFromNotebooks(engine, artifactId) {
+    let cleared = 0;
+    for (const notebook of engine.notebooks.list()) {
+        if (!notebook.cells.some((cell) => cellHoldsArtifact(cell, artifactId))) {
+            continue;
+        }
+        let cellIds = [];
+        const result = await mutateNotebook(engine, notebook.id, "forget_asset", (document) => {
+            const detached = detachedDocument(document, artifactId);
+            cellIds = detached.cellIds;
+            return detached.document;
+        }, { artifactId }, { artifactId });
+        if (!result.ok)
+            throw new Error(result.error.message);
+        cleared += cellIds.length;
+    }
+    return cleared;
+}
+function referencesOf(details) {
+    const references = details?.references;
+    if (!Array.isArray(references))
+        return [];
+    return references.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return [];
+        const row = entry;
+        return isString(row.kind) && isString(row.id)
+            ? [{ kind: row.kind, id: row.id }]
+            : [];
+    });
+}
+function remainingForgetReferences(engine, artifactId) {
+    const references = engine.artifacts.deletionReferences(artifactId, { deleteOwnedMedia: true });
+    if (!references.ok)
+        throw new Error(references.error.message);
+    const clearable = new Set(engine.sequences.getPrimary().clips
+        .filter((clip) => clip.source.artifactId === artifactId).map((clip) => `sequenceClip:${clip.clipId}`));
+    for (const notebook of engine.notebooks.list()) {
+        for (const cell of notebook.cells) {
+            const cellId = `${notebook.id}/${cell.id}`;
+            if (cell.outputArtifactId === artifactId)
+                clearable.add(`cell.outputArtifact:${cellId}`);
+            for (const reference of cell.references ?? []) {
+                if (reference.targetId === artifactId)
+                    clearable.add(`cell.reference:${cellId}/${reference.id}`);
+            }
+            for (const result of cell.pinnedResults ?? []) {
+                if (result.artifactId === artifactId)
+                    clearable.add(`pinnedSearchResult:${cellId}/${result.id}`);
+            }
+        }
+    }
+    return references.value.filter((reference) => !clearable.has(`${reference.kind}:${reference.id}`));
+}
+function inUseOutcome(artifactId, label, references, clearedCells = 0) {
+    return { status: "in_use", artifactId, label, references, clearedCells,
+        forgottenObjects: 0, sharedObjects: 0, reclaimedBytes: 0 };
+}
+/**
+ * Deletes an artifact and destroys the bytes behind it.
+ *
+ * `engine.artifacts.delete` clears the catalog rows and the workspace copy,
+ * but the content objects survive — that is what makes a duplicate import
+ * free and an old revision restorable. Forgetting finishes the job through
+ * `storage.deleteObject`, which is left unforced on purpose: an object another
+ * artifact still references is kept, so forgetting one copy of shared bytes
+ * never blanks the other.
+ */
+export async function forgetAsset(engine, input) {
+    const artifact = engine.artifacts.get(input.assetId);
+    if (!artifact.ok)
+        throw new Error(artifact.error.message);
+    const artifactId = artifact.value.artifactId;
+    const label = artifact.value.label ?? null;
+    if (input.clearReferences) {
+        const blockers = remainingForgetReferences(engine, artifactId);
+        if (blockers.length > 0)
+            return inUseOutcome(artifactId, label, blockers);
+        const timeline = await removeArtifactFromTimeline(engine, artifactId, { dryRun: true });
+        if (timeline.error)
+            throw new Error(timeline.error);
+    }
+    const manifest = await engine.files.manifest(artifactId, { includeDotfiles: true });
+    const hashes = [...new Set(manifest.ok ? manifest.value.files.map((file) => file.objectHash) : [])];
+    const clearedCells = input.clearReferences
+        ? await detachFromNotebooks(engine, artifactId)
+        : 0;
+    if (input.clearReferences) {
+        const timeline = await removeArtifactFromTimeline(engine, artifactId);
+        if (timeline.error)
+            throw new Error(timeline.error);
+    }
+    const deleted = await engine.artifacts.delete(artifactId, {
+        deleteOwnedMedia: true,
+    });
+    if (!deleted.ok) {
+        if (deleted.error.code !== "IN_USE")
+            throw new Error(deleted.error.message);
+        return inUseOutcome(artifactId, label, referencesOf(deleted.error.details), clearedCells);
+    }
+    let forgottenObjects = 0;
+    let sharedObjects = 0;
+    let reclaimedBytes = 0;
+    for (const hash of hashes) {
+        const result = await engine.storage.deleteObject(hash);
+        if (result.ok) {
+            forgottenObjects += 1;
+            if (result.value.deletedLocal)
+                reclaimedBytes += result.value.sizeBytes;
+            continue;
+        }
+        // Bytes another artifact stores, or an object row that never existed.
+        if (result.error.code === "IN_USE") {
+            sharedObjects += 1;
+            continue;
+        }
+        if (result.error.code === "NOT_FOUND")
+            continue;
+        throw new Error(result.error.message);
+    }
+    return {
+        status: "forgotten",
+        artifactId,
+        label,
+        references: [],
+        clearedCells,
+        forgottenObjects,
+        sharedObjects,
+        reclaimedBytes,
+    };
+}

package/dist/frame-utils.js

@@ -0,0 +1,27 @@
+export function sampleEvenly(items, maxSamples) {
+    if (maxSamples <= 0)
+        return [];
+    if (items.length <= maxSamples)
+        return items;
+    if (maxSamples === 1)
+        return [items[0]];
+    const sampleStep = (items.length - 1) / (maxSamples - 1);
+    return Array.from({ length: maxSamples }, (_, index) => items[Math.round(index * sampleStep)]);
+}
+function calculateFrameSampleCount(durationSeconds) {
+    const sampleIntervalSeconds = durationSeconds <= 10 ? 2 : 5;
+    const sampleCount = Math.floor(durationSeconds / sampleIntervalSeconds);
+    return Math.max(3, Math.min(30, sampleCount));
+}
+export function formatTimestamp(t) {
+    return t.toFixed(2);
+}
+export function generateTimestamps(durationSeconds) {
+    if (!Number.isFinite(durationSeconds) || durationSeconds <= 0)
+        return [];
+    const sampleCount = calculateFrameSampleCount(durationSeconds);
+    const endMarginSeconds = Math.min(0.1, durationSeconds / sampleCount);
+    const lastTimestampSeconds = durationSeconds - endMarginSeconds;
+    const sampleStepSeconds = lastTimestampSeconds / (sampleCount - 1);
+    return Array.from({ length: sampleCount }, (_, index) => sampleStepSeconds * index);
+}

package/dist/generation-credit-error.js

@@ -0,0 +1,11 @@
+export function isGenerationCreditError(error) {
+    if (!error)
+        return false;
+    const message = error.toLowerCase().replaceAll(/[_-]+/g, " ");
+    return /\b(?:out of|insufficient|not enough|no(?: remaining| more| available)?) credits?\b/.test(message)
+        || /\bcredits? (?:balance )?(?:is |are )?(?:insufficient|exhausted|depleted|too low)\b/.test(message)
+        || /\b(?:insufficient|not enough|low|exhausted) (?:account |credit )?balance\b/.test(message)
+        || /\b(?:account |credit )?balance (?:is )?(?:insufficient|too low|exhausted)\b/.test(message)
+        || /\binsufficient quota\b/.test(message)
+        || /\b(?:exceeds? (?:your|the) (?:remaining |available )?credits?|credits? (?:left|remaining).{0,100}(?:required|requested|needed))\b/.test(message);
+}

package/dist/generation-input-mentions.js

@@ -0,0 +1,117 @@
+// Generation prompts name their media by input slot, never by grid square:
+// "@image1" is the first connected image input, whatever square it sits in, so
+// moving cells around the grid leaves the prompt untouched. The numbering is
+// the order the server hands media to the provider (image_refs, video_refs,
+// audio_refs), so "@image2" in the prompt and "reference image 2" in the
+// payload always mean the same asset. Frame inputs ride their own params and
+// get their own tokens.
+//
+// Pure and dependency-free: the client imports it for the autocomplete menu
+// and the input cards, the server for prompt resolution.
+const FRAME_TOKENS = {
+    first_frame: "firstframe",
+    last_frame: "lastframe",
+};
+// Inputs that feed a dedicated provider param and cannot be named inline.
+const UNNAMED_TARGET_INPUTS = new Set(["replace_audio"]);
+const KIND_ORDER = ["image", "video", "audio"];
+function generationInputMediaKind(cellType) {
+    if (cellType === "image" || cellType === "generate_image")
+        return "image";
+    if (cellType === "audio"
+        || cellType === "extract_audio"
+        || cellType === "generate_audio")
+        return "audio";
+    if (cellType === "video"
+        || cellType === "split_video"
+        || cellType === "generate_video"
+        || cellType === "concat"
+        || cellType === "splice")
+        return "video";
+    return null;
+}
+function numberedKindSlotIndex(targetInput, kind) {
+    if (targetInput === kind)
+        return 1;
+    const prefix = `${kind}_`;
+    if (!targetInput.startsWith(prefix))
+        return null;
+    const suffix = targetInput.slice(prefix.length);
+    if (!/^\d+$/.test(suffix))
+        return null;
+    return Number(suffix);
+}
+/** Stable sort by numbered slot ("image", "image_2", …); unnumbered last. */
+export function sortByKindSlot(entries, kind) {
+    return [...entries].sort((left, right) => {
+        const leftIndex = numberedKindSlotIndex(left.targetInput, kind)
+            ?? Number.MAX_SAFE_INTEGER;
+        const rightIndex = numberedKindSlotIndex(right.targetInput, kind)
+            ?? Number.MAX_SAFE_INTEGER;
+        return leftIndex - rightIndex;
+    });
+}
+function connectedInputs(cellId, cells, edges) {
+    const cellsById = new Map(cells.map((cell) => [cell.id, cell]));
+    return edges.flatMap((edge) => {
+        if (edge.target !== cellId)
+            return [];
+        const source = cellsById.get(edge.source);
+        const kind = source ? generationInputMediaKind(source.type) : null;
+        return kind
+            ? [{ kind, sourceCellId: edge.source, targetInput: edge.targetInput }]
+            : [];
+    });
+}
+function frameMentions(inputs) {
+    return Object.entries(FRAME_TOKENS).flatMap(([targetInput, token]) => {
+        const input = inputs.find((candidate) => candidate.kind === "image" && candidate.targetInput === targetInput);
+        return input ? [{ ...input, token }] : [];
+    });
+}
+function numberedMentions(inputs, kind, modeId) {
+    const named = inputs.filter((input) => input.kind === kind
+        && !(modeId !== "r2v" && kind === "image" && input.targetInput in FRAME_TOKENS)
+        && !UNNAMED_TARGET_INPUTS.has(input.targetInput));
+    return sortByKindSlot(named, kind).map((input, index) => ({
+        ...input,
+        token: `${kind}${index + 1}`,
+    }));
+}
+/** Every prompt-nameable input of a generation cell, in provider order. */
+export function generationInputMentions(cellId, cells, edges, modeId) {
+    const configuredMode = cells.find((cell) => cell.id === cellId)?.inputs?.generationMode;
+    const effectiveMode = modeId ?? configuredMode;
+    const inputs = connectedInputs(cellId, cells, edges);
+    return [
+        ...(effectiveMode === "r2v" ? [] : frameMentions(inputs)),
+        ...KIND_ORDER.flatMap((kind) => numberedMentions(inputs, kind, typeof effectiveMode === "string" ? effectiveMode : undefined)),
+    ];
+}
+export function remapGenerationInputPrompt(prompt, previous, next) {
+    const used = new Set([...previous, ...next].map((mention) => mention.token));
+    const replacements = new Map(previous.map((before) => {
+        const after = next.find((candidate) => candidate.sourceCellId === before.sourceCellId
+            && candidate.targetInput === before.targetInput)
+            ?? next.find((candidate) => candidate.targetInput === before.targetInput);
+        if (after)
+            return [before.token, after.token];
+        if (!next.some((candidate) => candidate.token === before.token))
+            return [before.token, before.token];
+        let index = 1;
+        while (used.has(`${before.kind}${index}`))
+            index += 1;
+        const missing = `${before.kind}${index}`;
+        used.add(missing);
+        return [before.token, missing];
+    }));
+    return prompt.replace(/@((?:image|video|audio)\d+|firstframe|lastframe)(?![\w-])/giu, (match, token) => {
+        const replacement = replacements.get(token.toLowerCase());
+        return replacement && replacement !== token.toLowerCase() ? `@${replacement}` : match;
+    });
+}
+/** "@image1"-style tokens in a prompt, lower-cased and without the "@". */
+export function scanGenerationInputTokens(prompt) {
+    return [...prompt.matchAll(/@((?:image|video|audio)\d+|firstframe|lastframe)(?![\w-])/giu)]
+        .map((match) => match[1].toLowerCase());
+}

package/dist/generation-input-policy.js

@@ -0,0 +1,68 @@
+export function generationModeInputTarget(modeId, kind, target) {
+    return modeId === "r2v" && kind === "image"
+        && (target === "first_frame" || target === "last_frame")
+        ? "image"
+        : target;
+}
+function modeInputs(mode, inputs) {
+    const normalized = inputs.map((input) => ({
+        ...input,
+        target: generationModeInputTarget(mode.id, input.kind, input.target),
+    }));
+    if (mode.id !== "i2v" || mode.slots.some((slot) => slot.targets.includes("image"))) {
+        return normalized;
+    }
+    const available = mode.slots.flatMap((slot) => slot.targets)
+        .filter((target) => target === "first_frame" || target === "last_frame")
+        .filter((target) => !inputs.some((input) => input.target === target));
+    let index = 0;
+    return normalized.map((input) => {
+        if (input.kind !== "image" || input.target !== "image")
+            return input;
+        const target = available[index++];
+        return target ? { ...input, target } : input;
+    });
+}
+function inputLabel(target) {
+    if (target === "replace_audio")
+        return "replacement audio";
+    if (target === "first_frame")
+        return "first frame";
+    if (target === "last_frame")
+        return "last frame";
+    return `${target} reference`;
+}
+export function generationModeInputError(mode, inputs) {
+    const name = mode.id === "default" || mode.id === "text" ? "this model" : mode.id.toUpperCase();
+    const subject = name === "this model" ? "This model" : name;
+    const counts = new Map(mode.slots.map((slot) => [slot.field, 0]));
+    const sorted = modeInputs(mode, inputs).sort((left, right) => Number(right.target !== right.kind) - Number(left.target !== left.kind));
+    for (const input of sorted) {
+        const matching = mode.slots.filter((slot) => slot.kind === input.kind && slot.targets.includes(input.target));
+        if (matching.length === 0) {
+            return `${subject} does not accept ${inputLabel(input.target)} inputs. Change the type or remove that input.`;
+        }
+        const available = matching.filter((slot) => slot.max === null || (counts.get(slot.field) ?? 0) < slot.max)
+            .sort((left, right) => {
+            const leftRequired = Number((counts.get(left.field) ?? 0) < left.min);
+            const rightRequired = Number((counts.get(right.field) ?? 0) < right.min);
+            return rightRequired - leftRequired || left.targets.length - right.targets.length;
+        });
+        const slot = available[0];
+        if (!slot) {
+            const maximum = matching.reduce((total, candidate) => total + (candidate.max ?? 0), 0);
+            return `${subject} accepts at most ${maximum} ${inputLabel(input.target)} input${maximum === 1 ? "" : "s"}. Remove an input or change the model.`;
+        }
+        counts.set(slot.field, (counts.get(slot.field) ?? 0) + 1);
+    }
+    const missing = mode.slots.find((slot) => (counts.get(slot.field) ?? 0) < slot.min);
+    if (missing) {
+        return `Add at least ${missing.min} ${inputLabel(missing.targets[0] ?? missing.kind)} input${missing.min === 1 ? "" : "s"} for ${name}.`;
+    }
+    const group = mode.requiredGroups.find((fields) => !fields.some((field) => (counts.get(field) ?? 0) > 0));
+    if (!group)
+        return null;
+    const labels = [...new Set(mode.slots.filter((slot) => group.includes(slot.field))
+            .flatMap((slot) => slot.targets).map(inputLabel))];
+    return `Add at least one ${labels.join(" or ")} input for ${name}.`;
+}

package/dist/generation-reference-mentions.js

@@ -0,0 +1,97 @@
+import { normalizeNotebookReference, replaceNotebookMentions, stripNotebookMentions, } from "videobook-engine/notebook-mentions";
+function refMentionEntries(refs) {
+    return refs
+        .map((raw, index) => ({
+        ref: normalizeNotebookReference(raw),
+        index,
+    }))
+        .filter((e) => e.ref !== "")
+        .sort((a, b) => b.ref.length - a.ref.length);
+}
+/** Remove "@<ref>" mentions that have no inline marker form (reference video
+ *  clips, first frames) — the asset still rides its body param. */
+export function stripRefMentions(prompt, refs) {
+    return stripNotebookMentions(prompt, refMentionEntries(refs).map(({ ref }) => ref));
+}
+/** Replace "@<ref>" mentions with natural-language noun phrases for Kie
+ *  happyhorse/video-edit and other free-form prompt models with no inline
+ *  marker syntax (the "[Image N]" form belongs to happyhorse 1.1 t2v/i2v/ref
+ *  only). The prompt is a free-form instruction; media rides separate URL
+ *  fields. Rewrite confirmed @<video-ref> → "the source video", each
+ *  @<image-ref> → "reference image N" (1-based in imageRefs), and each
+ *  @<audio-ref> → "reference audio N". Unlisted mentions stay literal. */
+export function replaceHappyHorseAssetMentions(prompt, videoRef, imageRefs, audioRefs = []) {
+    const replacements = [];
+    if (videoRef) {
+        const video = normalizeNotebookReference(videoRef);
+        if (video) {
+            replacements.push({ reference: video, replacement: "the source video" });
+        }
+    }
+    for (const { ref, index } of refMentionEntries(imageRefs)) {
+        replacements.push({
+            reference: ref,
+            replacement: `reference image ${index + 1}`,
+        });
+    }
+    for (const { ref, index } of refMentionEntries(audioRefs)) {
+        replacements.push({
+            reference: ref,
+            replacement: `reference audio ${index + 1}`,
+        });
+    }
+    return replaceNotebookMentions(prompt, replacements);
+}
+/** HappyHorse 1.1 reference-to-video: rewrite confirmed @<image-ref> mentions
+ *  to positional `[Image N]` markers matching the reference_image[] order. */
+export function rewriteImageRefMentionsToBrackets(prompt, imageRefs) {
+    return replaceNotebookMentions(prompt, refMentionEntries(imageRefs).map(({ ref, index }) => ({
+        reference: ref,
+        replacement: `[Image ${index + 1}]`,
+    })));
+}
+/** Seedance r2v: rewrite confirmed asset @refs to `@ImageN` / `@VideoN` /
+ *  `@AudioN` (1-based, matching upload order in each modality array). */
+export function rewriteSeedanceAssetMentions(prompt, refs) {
+    const replacements = [];
+    for (const { ref, index } of refMentionEntries(refs.imageRefs ?? [])) {
+        replacements.push({ reference: ref, replacement: `@Image${index + 1}` });
+    }
+    for (const { ref, index } of refMentionEntries(refs.videoRefs ?? [])) {
+        replacements.push({ reference: ref, replacement: `@Video${index + 1}` });
+    }
+    for (const { ref, index } of refMentionEntries(refs.audioRefs ?? [])) {
+        replacements.push({ reference: ref, replacement: `@Audio${index + 1}` });
+    }
+    return replaceNotebookMentions(prompt, replacements);
+}
+export function rewriteViduReferenceMentions(prompt, imageRefs, audioRefs) {
+    return replaceNotebookMentions(prompt, [
+        ...refMentionEntries(imageRefs).map(({ ref, index }) => ({
+            reference: ref,
+            replacement: `[@reference_image_${index + 1}]`,
+        })),
+        ...refMentionEntries(audioRefs).map(({ ref, index }) => ({
+            reference: ref,
+            replacement: `[reference_audio_${index + 1}]`,
+        })),
+    ]);
+}
+/** Free-form multi-ref natural rewrite when the provider has no inline marker
+ *  syntax: videos → "reference video N" (or "the source video" for a single
+ *  source clip), images → "reference image N", audio → "reference audio N". */
+export function replaceNaturalAssetMentions(prompt, refs) {
+    let out = prompt;
+    if (refs.sourceVideoRef) {
+        out = replaceHappyHorseAssetMentions(out, refs.sourceVideoRef, [], []);
+    }
+    const multiVideos = refs.videoRefs ?? [];
+    out = replaceNotebookMentions(out, refMentionEntries(multiVideos).map(({ ref, index }) => ({
+        reference: ref,
+        replacement: multiVideos.length === 1
+            ? "the source video"
+            : `reference video ${index + 1}`,
+    })));
+    out = replaceHappyHorseAssetMentions(out, null, refs.imageRefs ?? [], refs.audioRefs ?? []);
+    return out;
+}

package/dist/goal-characters.js

@@ -0,0 +1,49 @@
+import { resolveNotebookCellArtifactId } from "videobook-engine";
+import { notebookGridTag } from "videobook-engine/notebook-grid";
+import { replaceNotebookMentions, scanNotebookMentions } from "videobook-engine/notebook-mentions";
+import { resolveNotebookPromptReferences } from "./notebook-reference-resolver.js";
+const GOAL_CHARACTER_HELP = "Mention the reference images in the brief, for example /goal @a1 @a2 as ...";
+export function resolveGoalCharacters(engine, document, brief) {
+    if (scanNotebookMentions(brief).length === 0)
+        throw new Error(GOAL_CHARACTER_HELP);
+    const resolved = resolveNotebookPromptReferences({ engine, document, prompt: brief, requireMedia: true });
+    if (resolved.unresolved.length > 0)
+        throw new Error(resolved.unresolved[0].message);
+    const characters = new Map();
+    for (const reference of resolved.resolved) {
+        const artifact = engine.artifacts.get(reference.artifactId);
+        const cell = document.cells.find(candidate => candidate.id === reference.cellId);
+        if (!artifact.ok || artifact.value.kind !== "image" || !cell || !["image", "generate_image"].includes(cell.type)) {
+            throw new Error(`${reference.mention} is not an image`);
+        }
+        if (!characters.has(reference.artifactId))
+            characters.set(reference.artifactId, {
+                artifactId: reference.artifactId, cellId: cell.id, address: notebookGridTag(cell.slot),
+                label: artifact.value.label || cell.label || `Character ${characters.size + 1}`,
+            });
+    }
+    if (characters.size === 0)
+        throw new Error(GOAL_CHARACTER_HELP);
+    if (characters.size > 8)
+        throw new Error("A goal supports 1–8 reference images");
+    return [...characters.values()];
+}
+export function currentGoalCharacters(document, characters) {
+    return characters.map(character => {
+        const cell = document.cells.find(candidate => candidate.id === character.cellId);
+        if (!cell || resolveNotebookCellArtifactId(document, cell) !== character.artifactId) {
+            throw new Error(`Reference image ${character.address} changed or was removed. Start a new /goal.`);
+        }
+        return { ...character, address: notebookGridTag(cell.slot) };
+    });
+}
+export function goalPlannerBrief(brief, characters, document) {
+    const aliases = document?.cells.flatMap(cell => {
+        const index = characters.findIndex(character => character.artifactId === resolveNotebookCellArtifactId(document, cell));
+        return index < 0 ? [] : [{ reference: notebookGridTag(cell.slot), replacement: `Character ${index + 1}` }];
+    }) ?? [];
+    return replaceNotebookMentions(brief, [...characters.flatMap((character, index) => [
+            { reference: character.address.slice(1), replacement: `Character ${index + 1}` },
+            { reference: character.artifactId, replacement: `Character ${index + 1}` },
+        ]), ...aliases]).replace(/(Character \d)(?=Character \d)/gu, "$1 ");
+}