Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Add the h3 shot tag taxonomy and compile it into the prompt

Bitti0406dc83cb55
diff --git a/src/lib/project.ts b/src/lib/project.ts
index c824e42..8608d6e 100644
--- a/src/lib/project.ts
+++ b/src/lib/project.ts
@@ -1,4 +1,5 @@
import { z } from "zod";
+import { normalizeShotTagSelection, shotTagClauses, SHOT_TAG_ID_PATTERN, type ShotTagSelection } from "./shot-tags";
export const PROJECT_FILE_NAME = "polstudio.json";
/** What the settings file used to be called, newest first. Both are still
@@ -177,6 +178,18 @@ export const projectReferenceSchema = z.object({
}
});
+/* The tags a shot was built from. Ids only — the words they compile into live
+ in src/lib/shot-tags.ts, so a term can be reworded without rewriting anyone's
+ project file, and a file written by a newer build keeps ids this build has no
+ term for instead of losing the user's choices on the next save.
+
+ Both layers validate SHAPE, not vocabulary, and they validate the same shape:
+ `is_shot_tag_id` in src-tauri/src/lib.rs is this regex. Were only one side to
+ know the taxonomy, the other would happily persist a tag it then refused to
+ read back. */
+export const shotTagIdSchema = z.string().regex(SHOT_TAG_ID_PATTERN, "Shot tag ids are lowercase letters, digits, and hyphens.");
+export const shotTagSelectionSchema = z.record(shotTagIdSchema, z.array(shotTagIdSchema));
+
export const generationJobSchema = z.object({
id: idSchema,
title: z.string().min(1),
@@ -192,6 +205,10 @@ export const generationJobSchema = z.object({
// change. Never treat it as the authoritative prompt.
compiledPrompt: z.string().min(1),
referenceIds: z.array(idSchema).default([]),
+ // `.nullish()` because Rust holds it as an Option — see the note on
+ // projectAssetSchema.durationMs. Every project written before shot tags
+ // existed has no key here at all, and must keep opening.
+ shotTags: shotTagSelectionSchema.nullish(),
// The one that broke the desktop app outright: createDraftGenerationJob never
// sets clipId, so EVERY project has a job without it. See the note on
// projectAssetSchema.durationMs.
@@ -423,9 +440,50 @@ export function usableImageReferences(references: ProjectReference[]): ProjectRe
.filter(isVisualReference);
}
-export function compileMiniMaxH3Prompt(creativeBrief: string, references: ProjectReference[] = []): string {
+/* Who wrote each piece of the compiled prompt.
+
+ - "brief" is the user's own prose, character for character.
+ - "tag" is a term they picked from the H3 vocabulary in shot-tags.ts.
+ - "frame" is everything PolStudio adds: field names, the [Shot N] marker,
+ punctuation it inserted, and the two default sound lines.
+
+ The preview in the generator renders these, and `compileMiniMaxH3Prompt` is
+ nothing but their values concatenated — so what the user is shown cannot
+ drift from what is sent, and their words stay visibly theirs. */
+export type PromptSegmentKind = "frame" | "brief" | "tag";
+export interface PromptSegment { kind: PromptSegmentKind; value: string }
+
+const frame = (value: string): PromptSegment => ({ kind: "frame", value });
+const own = (value: string): PromptSegment => ({ kind: "brief", value });
+const tagged = (value: string): PromptSegment => ({ kind: "tag", value });
+
+const capitalize = (value: string): string => value.charAt(0).toUpperCase() + value.slice(1);
+
+/** The stop `endSentence` would add, as its own segment — it is punctuation
+ * PolStudio inserted, not something the user typed. */
+const addedStop = (text: string): PromptSegment[] => (endSentence(text) === text ? [] : [frame(".")]);
+
+export function compileMiniMaxH3Prompt(
+ creativeBrief: string,
+ references: ProjectReference[] = [],
+ shotTags: ShotTagSelection | null = null,
+): string {
+ return compileMiniMaxH3PromptSegments(creativeBrief, references, shotTags).map((segment) => segment.value).join("");
+}
+
+export function compileMiniMaxH3PromptSegments(
+ creativeBrief: string,
+ references: ProjectReference[] = [],
+ shotTags: ShotTagSelection | null = null,
+): PromptSegment[] {
const brief = creativeBrief.trim();
- const style = deriveH3Style(brief);
+ const tags = shotTagClauses(shotTags);
+ // A chosen style REPLACES the guess made from the user's words; without one
+ // the guess stands, and it is marked as PolStudio's own doing.
+ const style = tags.style ?? deriveH3Style(brief);
+ const styleSegment = tags.style ? tagged(style) : frame(style);
+ // Sentences the tags contribute after the description, already terminated.
+ const tail = tags.clauses.length === 0 ? [] : [frame(` ${tags.clauses.join(" ")}`)];
// Same filter pair as `usableImageReferences`, in the same order — see the
// <Picture N> / reference_paths lockstep note on that function. An
// audio-only-tagged reference is dropped here (ref guide §2.1), so a project
@@ -433,12 +491,24 @@ export function compileMiniMaxH3Prompt(creativeBrief: string, references: Projec
const usable = references.filter(isReferenceUsable).filter(isVisualReference);
if (usable.length === 0) {
- // T2VA — base guide §2.2 field list and order.
+ // T2VA — base guide §2.2 field list and order. With no tags at all this is
+ // byte-identical to what it has always produced, down to the brief keeping
+ // whatever terminal punctuation the user gave it.
return [
- `integrated_multimodal_description: [Shot 1] ${style}, ${brief}`,
- `overall_soundscape: ${DEFAULT_SOUNDSCAPE}`,
- `non_diegetic_music: ${DEFAULT_MUSIC}`,
- ].join("\n\n");
+ frame("integrated_multimodal_description: [Shot 1] "),
+ styleSegment,
+ frame(", "),
+ // §4.1 order inside the shot: size, angle and lens sit in front of the
+ // subject and its action.
+ ...(tags.framing.length > 0 ? [tagged(tags.framing.join(", ")), frame(", ")] : []),
+ own(brief),
+ // Only terminated when something follows it — otherwise the shape of an
+ // untagged prompt would change for every existing project.
+ ...(tags.clauses.length > 0 ? addedStop(brief) : []),
+ ...tail,
+ frame(`\n\noverall_soundscape: ${DEFAULT_SOUNDSCAPE}`),
+ frame(`\n\nnon_diegetic_music: ${DEFAULT_MUSIC}`),
+ ].filter((segment) => segment.value.length > 0);
}
const images = usableImageReferences(references);
@@ -459,12 +529,16 @@ export function compileMiniMaxH3Prompt(creativeBrief: string, references: Projec
// present an app-generated string to the model as the user's own words.
// An image with no definition still belongs in the prompt — the picture is
// real payload — so it is cited without any claim about what it contains.
- const definitions = usable.map((reference, index) => {
- const detail = endSentence(referenceDefinition(reference).replace(/\s+/g, " "));
+ const definitions = usable.flatMap((reference, index): PromptSegment[] => {
+ const detail = referenceDefinition(reference).replace(/\s+/g, " ");
const picture = pictureNumber.get(reference.id);
const label = referenceLabel(reference, index);
- if (!picture) return `${label}: ${detail}`;
- return `${label} is the content shown in <Picture ${picture}>.${detail ? ` ${detail}` : ""}`;
+ const lead = index === 0 ? "" : "\n";
+ if (!picture) return [frame(`${lead}${label}: `), own(detail), ...addedStop(detail)];
+ return [
+ frame(`${lead}${label} is the content shown in <Picture ${picture}>.`),
+ ...(detail ? [frame(" "), own(detail), ...addedStop(detail)] : []),
+ ];
});
const labels = usable.map((reference, index) => referenceLabel(reference, index));
@@ -475,7 +549,12 @@ export function compileMiniMaxH3Prompt(creativeBrief: string, references: Projec
// §3: task-type prefix. Every reference here provides generation guidance
// without acting as a concrete frame or an edited source video, which is
// exactly `reference generation`. The summary reuses existing labels only.
- const summary = `[reference generation] ${endSentence(brief)} ${labelList} ${labels.length === 1 ? "provides" : "provide"} generation guidance for the single shot described below.`;
+ const summary: PromptSegment[] = [
+ frame("[reference generation] "),
+ own(brief),
+ ...addedStop(brief),
+ frame(` ${labelList} ${labels.length === 1 ? "provides" : "provide"} generation guidance for the single shot described below.`),
+ ];
// §4.1: one line per label using the fixed marker vocabulary. Their defined
// role is carried through unchanged, so fully_preserved is the honest marker.
@@ -488,27 +567,40 @@ export function compileMiniMaxH3Prompt(creativeBrief: string, references: Projec
// §5.2: in full-reference mode the style opening comes BEFORE [Shot 1], not
// after it. §5.3: cite each <Subject N> where it appears in the shot.
- const detailed = [
- `The target video is in a ${midSentenceStyle(style)} style.`,
- `[Shot 1] ${endSentence(brief)} The shot features ${labelList}, matching the definitions above.`,
- ].join("\n");
+ const detailed: PromptSegment[] = [
+ frame("The target video is in a "),
+ tags.style ? tagged(midSentenceStyle(style)) : frame(midSentenceStyle(style)),
+ frame(" style.\n[Shot 1] "),
+ // Framing leads the sentence here, so it takes the capital.
+ ...(tags.framing.length > 0 ? [tagged(capitalize(tags.framing.join(", "))), frame(", ")] : []),
+ own(brief),
+ ...addedStop(brief),
+ frame(` The shot features ${labelList}, matching the definitions above.`),
+ ...tail,
+ ];
return [
- `subject_definitions:\n${definitions.join("\n")}`,
- `summary:\n${summary}`,
- `retention_analysis:\n${retention.join("\n")}`,
- `detailed_description:\n${detailed}`,
- `overall_soundscape:\n${DEFAULT_SOUNDSCAPE}`,
- `non_diegetic_music:\n${DEFAULT_MUSIC}`,
- ].join("\n\n");
+ frame("subject_definitions:\n"),
+ ...definitions,
+ frame("\n\nsummary:\n"),
+ ...summary,
+ frame(`\n\nretention_analysis:\n${retention.join("\n")}`),
+ frame("\n\ndetailed_description:\n"),
+ ...detailed,
+ frame(`\n\noverall_soundscape:\n${DEFAULT_SOUNDSCAPE}`),
+ frame(`\n\nnon_diegetic_music:\n${DEFAULT_MUSIC}`),
+ ].filter((segment) => segment.value.length > 0);
}
export function createDraftGenerationJob(
creativeBrief: string,
- options: { id?: string; title?: string; referenceIds?: string[]; references?: ProjectReference[]; now?: string } = {},
+ options: { id?: string; title?: string; referenceIds?: string[]; references?: ProjectReference[]; shotTags?: ShotTagSelection | null; now?: string } = {},
): GenerationJob {
const brief = creativeBrief.trim();
const now = options.now ?? new Date().toISOString();
+ // Omitted rather than written as null when nothing is tagged, so a shot built
+ // from prose alone still writes exactly the file it always did.
+ const shotTags = normalizeShotTagSelection(options.shotTags);
return generationJobSchema.parse({
id: options.id ?? crypto.randomUUID(),
title: options.title ?? brief.split(/\s+/).slice(0, 6).join(" "),
@@ -523,8 +615,9 @@ export function createDraftGenerationJob(
// value is stale the moment the brief or the bound references change (a
// project created with reference images keeps a T2VA snapshot here while
// the job later holds bound image references). Do not read it as current.
- compiledPrompt: compileMiniMaxH3Prompt(brief, options.references ?? []),
+ compiledPrompt: compileMiniMaxH3Prompt(brief, options.references ?? [], shotTags),
referenceIds: options.referenceIds ?? [],
+ ...(shotTags ? { shotTags } : {}),
createdAt: now,
updatedAt: now,
});
diff --git a/src/lib/shot-tags.ts b/src/lib/shot-tags.ts
new file mode 100644
index 0000000..d779523
--- /dev/null
+++ b/src/lib/shot-tags.ts
@@ -0,0 +1,381 @@
+/* ---------------------------------------------------------------------------
+ The MiniMax H3 shot vocabulary, in one place.
+
+ Every string a tag can contribute to a compiled prompt lives here and
+ NOWHERE else. The rule this file exists to enforce is that the words handed
+ to the engine are the guide's own terms — "push in", "medium close-up",
+ "low-key lighting" — never a synonym this app invented on the user's behalf.
+ If a term is not in the guide it does not belong in `term`.
+
+ Two vocabularies, deliberately separate on every option:
+
+ - `label` is what the picker shows. It may be friendlier than the guide.
+ - `term` is what is compiled into the prompt. It is the guide's wording,
+ written mid-sentence (lowercase unless the guide capitalises it), because
+ the compiler splices it into a sentence and capitalises the lead itself.
+
+ The ids are persisted in `pols.json`, so they are stable forever: rename a
+ `label` freely, never an `id`. Both validators constrain ids to
+ `SHOT_TAG_ID_PATTERN` (src/lib/project.ts and src-tauri/src/lib.rs), so a new
+ id has to keep that shape.
+ --------------------------------------------------------------------------- */
+
+/** One choosable term. */
+export interface ShotTagOption {
+ /** Persisted in the project file. Never change one. */
+ id: string;
+ /** What the picker shows. */
+ label: string;
+ /** The guide's own wording, as it is spliced into the prompt. */
+ term: string;
+}
+
+export type ShotTagGroupId =
+ | "visualStyle"
+ | "shotSize"
+ | "cameraAngle"
+ | "lens"
+ | "cameraMovement"
+ | "cameraSpeed"
+ | "cameraAmplitude"
+ | "lighting"
+ | "timeOfDay"
+ | "mood"
+ | "motionPace";
+
+export interface ShotTagGroup {
+ id: ShotTagGroupId;
+ /** Picker heading. */
+ label: string;
+ /** One line saying what this group does to the prompt. Shown in the UI so
+ * nobody has to guess which part of the sentence a tag lands in. */
+ help: string;
+ /** Whether more than one option may be held at once. */
+ multiple: boolean;
+ /** Only offered once a camera movement is chosen — "slow speed" on its own
+ * describes nothing, and the compiler drops it (see `shotTagClauses`). */
+ requiresMovement?: boolean;
+ options: readonly ShotTagOption[];
+}
+
+/** Group id -> chosen option ids. Persisted verbatim; see `generationJobSchema`. */
+export type ShotTagSelection = Record<string, string[]>;
+
+/** Ids both validators accept. Kept in lockstep with `is_shot_tag_id` in
+ * src-tauri/src/lib.rs — a shape neither layer has to guess about. */
+export const SHOT_TAG_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/* The canonical H3 style names. These are the SAME seven strings
+ `deriveH3Style` can produce, and `MID_SENTENCE_STYLES` in project.ts already
+ knows how to spell each of them mid-sentence — so choosing one here can
+ simply replace the guess made from the user's words. */
+const VISUAL_STYLES: readonly ShotTagOption[] = [
+ { id: "live-action-cinematic", label: "Live action, cinematic", term: "Live-action, cinematic" },
+ { id: "live-action-documentary", label: "Live action, documentary", term: "Live-action, documentary" },
+ { id: "vintage-film", label: "Vintage film", term: "Vintage film" },
+ { id: "animated-2d", label: "2D animation", term: "2D-animated" },
+ { id: "cg-3d", label: "3D CG", term: "3D CG" },
+ { id: "claymation", label: "Claymation", term: "Claymation" },
+ { id: "watercolor", label: "Watercolor", term: "Watercolor" },
+];
+
+export const SHOT_TAG_GROUPS: readonly ShotTagGroup[] = [
+ {
+ id: "visualStyle",
+ label: "Look",
+ help: "Opens the shot. Choosing one replaces the style PolStudio would otherwise guess from your words.",
+ multiple: false,
+ options: VISUAL_STYLES,
+ },
+ {
+ id: "shotSize",
+ label: "Shot size",
+ help: "How much of the subject is in frame. Sits in front of your description.",
+ multiple: false,
+ options: [
+ { id: "extreme-wide", label: "Extreme wide", term: "extreme wide shot" },
+ { id: "wide", label: "Wide", term: "wide shot" },
+ { id: "full", label: "Full", term: "full shot" },
+ { id: "medium-full", label: "Medium full", term: "medium full shot" },
+ { id: "medium", label: "Medium", term: "medium shot" },
+ { id: "medium-close-up", label: "Medium close-up", term: "medium close-up" },
+ { id: "close-up", label: "Close-up", term: "close-up" },
+ { id: "extreme-close-up", label: "Extreme close-up", term: "extreme close-up" },
+ ],
+ },
+ {
+ id: "cameraAngle",
+ label: "Camera angle",
+ help: "Where the camera sits relative to the subject.",
+ multiple: false,
+ options: [
+ { id: "eye-level", label: "Eye level", term: "eye-level angle" },
+ { id: "low-angle", label: "Low angle", term: "low angle" },
+ { id: "high-angle", label: "High angle", term: "high angle" },
+ { id: "overhead", label: "Overhead", term: "overhead angle" },
+ { id: "dutch-angle", label: "Dutch angle", term: "dutch angle" },
+ { id: "over-the-shoulder", label: "Over the shoulder", term: "over-the-shoulder angle" },
+ { id: "point-of-view", label: "Point of view", term: "point-of-view shot" },
+ ],
+ },
+ {
+ id: "lens",
+ label: "Lens",
+ help: "The optics the shot is described as being taken on.",
+ multiple: false,
+ options: [
+ { id: "wide-angle-lens", label: "Wide angle", term: "wide-angle lens" },
+ { id: "standard-lens", label: "Standard", term: "standard lens" },
+ { id: "telephoto-lens", label: "Telephoto", term: "telephoto lens" },
+ { id: "macro-lens", label: "Macro", term: "macro lens" },
+ { id: "fisheye-lens", label: "Fisheye", term: "fisheye lens" },
+ { id: "anamorphic-lens", label: "Anamorphic", term: "anamorphic lens" },
+ ],
+ },
+ {
+ id: "cameraMovement",
+ label: "Camera movement",
+ help: "What the camera does during the shot. Written as its own clause after your description.",
+ multiple: true,
+ options: [
+ { id: "static-shot", label: "Static", term: "static shot" },
+ { id: "push-in", label: "Push in", term: "push in" },
+ { id: "pull-out", label: "Pull out", term: "pull out" },
+ { id: "pan-left", label: "Pan left", term: "pan left" },
+ { id: "pan-right", label: "Pan right", term: "pan right" },
+ { id: "tilt-up", label: "Tilt up", term: "tilt up" },
+ { id: "tilt-down", label: "Tilt down", term: "tilt down" },
+ { id: "truck-left", label: "Truck left", term: "truck left" },
+ { id: "truck-right", label: "Truck right", term: "truck right" },
+ { id: "pedestal-up", label: "Pedestal up", term: "pedestal up" },
+ { id: "pedestal-down", label: "Pedestal down", term: "pedestal down" },
+ { id: "zoom-in", label: "Zoom in", term: "zoom in" },
+ { id: "zoom-out", label: "Zoom out", term: "zoom out" },
+ { id: "tracking-shot", label: "Tracking", term: "tracking shot" },
+ { id: "arc-shot", label: "Arc", term: "arc shot" },
+ { id: "crane-up", label: "Crane up", term: "crane up" },
+ { id: "crane-down", label: "Crane down", term: "crane down" },
+ { id: "handheld", label: "Handheld", term: "handheld" },
+ { id: "whip-pan", label: "Whip pan", term: "whip pan" },
+ { id: "rack-focus", label: "Rack focus", term: "rack focus" },
+ ],
+ },
+ /* The guide asks for a movement to be qualified by HOW FAR and HOW FAST, not
+ just named, so both get their own control rather than being buried in an
+ adjective the user has to remember to type. Neither is offered — or
+ compiled — without a movement to qualify. */
+ {
+ id: "cameraSpeed",
+ label: "Movement speed",
+ help: "How fast the camera moves. Only used once a movement is chosen.",
+ multiple: false,
+ requiresMovement: true,
+ options: [
+ { id: "slow", label: "Slow", term: "slow speed" },
+ { id: "steady", label: "Steady", term: "steady speed" },
+ { id: "fast", label: "Fast", term: "fast speed" },
+ ],
+ },
+ {
+ id: "cameraAmplitude",
+ label: "Movement amplitude",
+ help: "How far the camera travels. Only used once a movement is chosen.",
+ multiple: false,
+ requiresMovement: true,
+ options: [
+ { id: "small", label: "Small", term: "small amplitude" },
+ { id: "moderate", label: "Moderate", term: "moderate amplitude" },
+ { id: "large", label: "Large", term: "large amplitude" },
+ ],
+ },
+ {
+ id: "lighting",
+ label: "Lighting",
+ help: "How the scene is lit.",
+ multiple: true,
+ options: [
+ { id: "soft-light", label: "Soft light", term: "soft light" },
+ { id: "hard-light", label: "Hard light", term: "hard light" },
+ { id: "natural-light", label: "Natural light", term: "natural light" },
+ { id: "practical-light", label: "Practical light", term: "practical light" },
+ { id: "backlight", label: "Backlight", term: "backlight" },
+ { id: "rim-light", label: "Rim light", term: "rim light" },
+ { id: "side-light", label: "Side light", term: "side light" },
+ { id: "top-light", label: "Top light", term: "top light" },
+ { id: "high-key", label: "High key", term: "high-key lighting" },
+ { id: "low-key", label: "Low key", term: "low-key lighting" },
+ { id: "silhouette", label: "Silhouette", term: "silhouette lighting" },
+ { id: "volumetric-light", label: "Volumetric", term: "volumetric light" },
+ { id: "firelight", label: "Firelight", term: "firelight" },
+ { id: "moonlight", label: "Moonlight", term: "moonlight" },
+ { id: "neon-light", label: "Neon", term: "neon light" },
+ ],
+ },
+ {
+ id: "timeOfDay",
+ label: "Time of day",
+ help: "When the shot happens.",
+ multiple: false,
+ options: [
+ { id: "dawn", label: "Dawn", term: "dawn" },
+ { id: "sunrise", label: "Sunrise", term: "sunrise" },
+ { id: "morning", label: "Morning", term: "morning" },
+ { id: "midday", label: "Midday", term: "midday" },
+ { id: "afternoon", label: "Afternoon", term: "afternoon" },
+ { id: "golden-hour", label: "Golden hour", term: "golden hour" },
+ { id: "sunset", label: "Sunset", term: "sunset" },
+ { id: "dusk", label: "Dusk", term: "dusk" },
+ { id: "blue-hour", label: "Blue hour", term: "blue hour" },
+ { id: "night", label: "Night", term: "night" },
+ ],
+ },
+ {
+ id: "mood",
+ label: "Mood",
+ help: "The feeling of the shot.",
+ multiple: true,
+ options: [
+ { id: "intimate", label: "Intimate", term: "intimate" },
+ { id: "calm", label: "Calm", term: "calm" },
+ { id: "tense", label: "Tense", term: "tense" },
+ { id: "ominous", label: "Ominous", term: "ominous" },
+ { id: "melancholic", label: "Melancholic", term: "melancholic" },
+ { id: "nostalgic", label: "Nostalgic", term: "nostalgic" },
+ { id: "joyful", label: "Joyful", term: "joyful" },
+ { id: "playful", label: "Playful", term: "playful" },
+ { id: "mysterious", label: "Mysterious", term: "mysterious" },
+ { id: "epic", label: "Epic", term: "epic" },
+ { id: "dreamlike", label: "Dreamlike", term: "dreamlike" },
+ { id: "solemn", label: "Solemn", term: "solemn" },
+ ],
+ },
+ {
+ id: "motionPace",
+ label: "Motion",
+ help: "How fast the action itself runs.",
+ multiple: false,
+ options: [
+ { id: "slow-motion", label: "Slow motion", term: "slow motion" },
+ { id: "real-time", label: "Real time", term: "real time" },
+ { id: "fast-motion", label: "Fast motion", term: "fast motion" },
+ { id: "time-lapse", label: "Time-lapse", term: "time-lapse" },
+ ],
+ },
+];
+
+const GROUPS_BY_ID: ReadonlyMap<string, ShotTagGroup> = new Map(SHOT_TAG_GROUPS.map((group) => [group.id, group]));
+
+export function shotTagGroup(id: string): ShotTagGroup | undefined {
+ return GROUPS_BY_ID.get(id);
+}
+
+/** The terms chosen in one group, in the group's own option order.
+ * Order comes from the taxonomy, not from the order boxes were ticked, so the
+ * same set of tags always compiles to the same bytes. Ids this build does not
+ * know are skipped rather than guessed at — see `normalizeShotTagSelection`
+ * for why they are still KEPT in the file. */
+export function shotTagTerms(selection: ShotTagSelection | null | undefined, groupId: ShotTagGroupId): string[] {
+ const group = GROUPS_BY_ID.get(groupId);
+ const chosen = selection?.[groupId];
+ if (!group || !chosen || chosen.length === 0) return [];
+ return group.options.filter((option) => chosen.includes(option.id)).map((option) => option.term);
+}
+
+/** Every option the user has chosen, across all groups, for counting and for
+ * listing back what is set. Unknown ids are left out — they cannot be shown
+ * as a term because this build has no term for them. */
+export function selectedShotTagOptions(selection: ShotTagSelection | null | undefined): Array<{ group: ShotTagGroup; option: ShotTagOption }> {
+ if (!selection) return [];
+ return SHOT_TAG_GROUPS.flatMap((group) => {
+ const chosen = selection[group.id] ?? [];
+ return group.options.filter((option) => chosen.includes(option.id)).map((option) => ({ group, option }));
+ });
+}
+
+export function countShotTags(selection: ShotTagSelection | null | undefined): number {
+ return selectedShotTagOptions(selection).length;
+}
+
+/** Tidies a selection for storage: drops empty groups, drops repeats, and
+ * returns `null` when nothing is left so the field is omitted from the file
+ * rather than written as an empty object.
+ *
+ * It deliberately does NOT drop ids this build doesn't recognise. A project
+ * written by a newer build would otherwise lose the user's choices the first
+ * time an older build re-saved it. `validate_and_normalize_config` in
+ * src-tauri/src/lib.rs performs exactly these three steps, in this order, so
+ * the file is byte-identical whichever layer wrote it last. */
+export function normalizeShotTagSelection(selection: ShotTagSelection | null | undefined): ShotTagSelection | null {
+ if (!selection) return null;
+ const normalized: ShotTagSelection = {};
+ for (const groupId of Object.keys(selection).sort()) {
+ const kept: string[] = [];
+ for (const optionId of selection[groupId] ?? []) {
+ if (!kept.includes(optionId)) kept.push(optionId);
+ }
+ if (kept.length > 0) normalized[groupId] = kept;
+ }
+ return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+/** Ticks or unticks one option, respecting the group's cardinality.
+ * Returns a NEW selection; never mutates the one passed in. */
+export function toggleShotTag(selection: ShotTagSelection | null | undefined, groupId: string, optionId: string): ShotTagSelection {
+ const current = { ...(selection ?? {}) };
+ const chosen = current[groupId] ?? [];
+ const group = GROUPS_BY_ID.get(groupId);
+ if (chosen.includes(optionId)) current[groupId] = chosen.filter((id) => id !== optionId);
+ else current[groupId] = group?.multiple ? [...chosen, optionId] : [optionId];
+ return normalizeShotTagSelection(current) ?? {};
+}
+
+/** Whether a movement has been chosen, which is what makes speed and amplitude
+ * meaningful. Both the picker and the compiler ask this same question, so a
+ * control the UI greys out is exactly the one the prompt would ignore. */
+export function hasCameraMovement(selection: ShotTagSelection | null | undefined): boolean {
+ return shotTagTerms(selection, "cameraMovement").length > 0;
+}
+
+/** What the tags contribute to one `[Shot N]`, split by where it lands. */
+export interface ShotTagClauses {
+ /** Canonical H3 style name, or null to keep deriving it from the user's words. */
+ style: string | null;
+ /** Framing terms, in guide order, that precede the user's description. */
+ framing: string[];
+ /** Whole sentences that follow the user's description, already terminated. */
+ clauses: string[];
+}
+
+const list = (terms: string[]): string => terms.join(", ");
+
+/** Guide order inside a shot: size, then angle, then lens, then the subject and
+ * its action (the user's own words), then the camera's move, then light, time,
+ * mood and the pace of the action. */
+export function shotTagClauses(selection: ShotTagSelection | null | undefined): ShotTagClauses {
+ const style = shotTagTerms(selection, "visualStyle")[0] ?? null;
+ const framing = [
+ ...shotTagTerms(selection, "shotSize"),
+ ...shotTagTerms(selection, "cameraAngle"),
+ ...shotTagTerms(selection, "lens"),
+ ];
+
+ const clauses: string[] = [];
+ const movement = shotTagTerms(selection, "cameraMovement");
+ if (movement.length > 0) {
+ // Speed and amplitude qualify the movement, so they ride in the same
+ // clause. Without a movement they say nothing and are left out entirely —
+ // the picker disables them for the same reason.
+ const qualifiers = [...shotTagTerms(selection, "cameraSpeed"), ...shotTagTerms(selection, "cameraAmplitude")];
+ clauses.push(`Camera movement: ${list([...movement, ...qualifiers])}.`);
+ }
+ const lighting = shotTagTerms(selection, "lighting");
+ if (lighting.length > 0) clauses.push(`Lighting: ${list(lighting)}.`);
+ const timeOfDay = shotTagTerms(selection, "timeOfDay");
+ if (timeOfDay.length > 0) clauses.push(`Time of day: ${list(timeOfDay)}.`);
+ const mood = shotTagTerms(selection, "mood");
+ if (mood.length > 0) clauses.push(`Mood: ${list(mood)}.`);
+ const pace = shotTagTerms(selection, "motionPace");
+ if (pace.length > 0) clauses.push(`Motion: ${list(pace)}.`);
+
+ return { style, framing, clauses };
+}