@nodaro/prompts 1.12.0 → 1.14.0

package/src/picker-analyzer-registry.ts

@@ -454,10 +454,46 @@ export interface MultiPickerAnalyzerSpec {
   readonly schema: z.ZodType<Record<string, unknown>, unknown>
   readonly toolName: string
   readonly legend: string
+  /** Compact bullet list of the pickers NOT wired into this spec (PICKER_TYPES
+   *  minus `types`), keyed by picker-type key so the LLM can ATTRIBUTE a gap to
+   *  the right picker even when it was not wired. Names + dimension labels only,
+   *  never catalog ids. Empty string when every picker is already wired. */
+  readonly otherPickersLegend: string
 }
 
 const MULTI_CACHE = new Map<string, MultiPickerAnalyzerSpec>()
 
+/** Title-case a picker-type key for display, e.g. "person" → "Person",
+ *  "exposure-settings" → "Exposure Settings". */
+function pickerDisplayName(type: string): string {
+  return type
+    .split("-")
+    .map((w) => (w.length > 0 ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(" ")
+}
+
+/** One compact bullet per non-wired picker so the LLM can attribute a gap to a
+ *  picker it wasn't handed. Flat pickers show their registry `label` (one axis);
+ *  discriminated pickers show a title-cased name plus their dimension labels.
+ *  Never lists catalog ids. Empty string when every PICKER_TYPES member is
+ *  wired. */
+function buildOtherPickersLegend(sorted: ReadonlyArray<PickerType>): string {
+  const otherTypes = PICKER_TYPES.filter((t) => !sorted.includes(t))
+  if (otherTypes.length === 0) return ""
+  const lines = otherTypes.map((type) => {
+    const descriptor = PICKER_ANALYZER_REGISTRY[type as PickerType] as PickerAnalyzerDescriptor
+    if (descriptor.kind === "flat") {
+      return `- ${type}: ${descriptor.label}`
+    }
+    const dims = descriptor.order
+      .map((k) => descriptor.labels[k])
+      .filter(Boolean)
+      .join(", ")
+    return `- ${type}: ${pickerDisplayName(type)}${dims ? ` — ${dims}` : ""}`
+  })
+  return `Non-wired pickers — use one of these keys in a gap's \`picker\` when an attribute belongs to it:\n${lines.join("\n")}`
+}
+
 /** Build ONE forced-tool schema spanning the given pickers (each section
  *  optional so an omitted picker doesn't trigger a validation retry) plus the
  *  capped `gaps` sidecar. Memoized by the sorted picker-set key. */
@@ -479,6 +515,7 @@ export function buildMultiPickerAnalyzerSpec(types: ReadonlyArray<PickerType>):
     schema: z.object(shape).strict() as unknown as MultiPickerAnalyzerSpec["schema"],
     toolName: "emit_pickers",
     legend: legendParts.join("\n\n"),
+    otherPickersLegend: buildOtherPickersLegend(sorted),
   }
   MULTI_CACHE.set(key, result)
   return result

package/src/prompt-builder.ts

@@ -7,6 +7,13 @@
 import { resolveTemplate, applyTemplate } from "./prompt-templates.js"
 import { NATIVE_NEGATIVE_PROMPT_MODELS, MODELS_WITH_REFERENCE_IMAGE_SUPPORT, imageReferenceLimit, getMaxImagePromptChars, getMaxNegativePromptChars } from "@nodaro/shared"
 import { getStylePromptHint } from "./style.js"
+import {
+  STYLE_SECTION_GAP,
+  STYLE_SECTION_HEADER,
+  endsInsideStyleSection,
+  insertBeforeStyleSection,
+  splitStyleSection,
+} from "./prompt-style-section.js"
 import { findCharacterMentionTokens, type CharacterMentionTokenInfo } from "@nodaro/shared"
 import { usageModeDirective, DEFAULT_USAGE_MODE, type UsageMode } from "@nodaro/shared"
 import { roleToPhrase, defaultRoleForSource, REFERENCE_ROLE_PRESETS, normalizeRoleSlug, resolveDefaultRole } from "@nodaro/shared"
@@ -2025,6 +2032,32 @@ function reconcileBodySegments(body: string, bodySegments: readonly PromptSegmen
   return [{ text: body, origin: "user" }]
 }
 
+/**
+ * The `Style:` / `Avoid:` control lines with the separator each one needs.
+ *
+ * They are self-labeling and stay at the very END of the prompt, which makes
+ * them the only text that can still land under an open `[style]` header — the
+ * section has no terminator, so a blank line is what closes its scope. `Avoid:`
+ * reads the body WITH `Style:` already on it, so once the first control line has
+ * closed the section the second rejoins on a single newline, exactly as before.
+ *
+ * Derived from the body they are appended to, because the cap's tail cut moves
+ * that boundary. The cut can only NARROW the separator — the section is the last
+ * block, so a cut either drops it entirely or lands inside it — which is what
+ * lets the caller reserve on the pre-cut body and re-derive afterwards.
+ */
+function controlSuffixes(
+  body: string,
+  styleLine: string,
+  avoidLine: string,
+): { styleSuffix: string; avoidSuffix: string } {
+  const separator = (text: string): string =>
+    endsInsideStyleSection(text) ? STYLE_SECTION_GAP : "\n"
+  const styleSuffix = styleLine ? `${separator(body)}${styleLine}` : ""
+  const avoidSuffix = avoidLine ? `${separator(body + styleSuffix)}${avoidLine}` : ""
+  return { styleSuffix, avoidSuffix }
+}
+
 /**
  * Build the final image generation prompt from config.
  * Handles character description wrapping, style appending, negative prompt routing,
@@ -2585,8 +2618,9 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
           ...extrasRendered.elementDirectives,
         ]
         const lockBlock = allLockLines.length > 0 ? `${allLockLines.join("\n")}\n\n` : ""
-        const trailingBlock = trailingLines.length > 0 ? `\n${trailingLines.join("\n")}` : ""
-        promptForNext = `${lockBlock}${promptForNext}${trailingBlock}`
+        // Scene content, so it extends the BODY: appended flat it would land
+        // under a `[style]` header the composer left open.
+        promptForNext = `${lockBlock}${insertBeforeStyleSection(promptForNext, trailingLines)}`
       }
 
       // Mutate the config locals (NOT the original passed config).
@@ -2731,8 +2765,10 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
         ...locCanon.phrases, ...objCanon.phrases,
         ...locCanon.elementDirectives, ...objCanon.elementDirectives,
       ]
-      const canonTrailingBlock = canonTrailingLines.length > 0 ? `\n${canonTrailingLines.join("\n")}` : ""
-      const composedScene = `${canonLockBlock}${scene}${canonTrailingBlock}`
+      // Role phrases and element injections are scene content → they extend the
+      // BODY, ahead of the `[style]` section (which has no terminator, so a flat
+      // append would read as one more look clause).
+      const composedScene = `${canonLockBlock}${insertBeforeStyleSection(scene, canonTrailingLines)}`
       prompt = config.referenceLockSnippet
         ? `${config.referenceLockSnippet}\n${composedScene}`
         : composedScene
@@ -2776,24 +2812,20 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
     }
 
     const styleText = style?.trim()
-    const styleSuffix = styleText ? `\nStyle: ${getStylePromptHint(styleText) || styleText}` : ""
+    const styleLine = styleText ? `Style: ${getStylePromptHint(styleText) || styleText}` : ""
 
     const negPrompt = negativePrompt?.trim()
     let nativeNegativePrompt: string | undefined
-    let avoidSuffix = ""
+    let avoidLine = ""
     if (negPrompt) {
       if (NATIVE_NEGATIVE_PROMPT_MODELS.has(provider)) {
         // Clamp native negatives to the provider's verified cap (e.g. ideogram /
         // qwen = 500) so an over-long negative can't trigger a provider reject.
         nativeNegativePrompt = negPrompt.slice(0, getMaxNegativePromptChars(provider))
       } else {
-        avoidSuffix = `\nAvoid: ${negPrompt}`
+        avoidLine = `Avoid: ${negPrompt}`
       }
     }
-    if (marks) {
-      marks.styleSuffix = styleSuffix
-      marks.avoidSuffix = avoidSuffix
-    }
 
     // Cap the assembled prompt at the PROVIDER's max (default IMAGE_PROMPT_MAX =
     // 5000, what the image routes already accept) — never the old hardcoded
@@ -2804,11 +2836,19 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
     // The cut is ORDER-BLIND — record how much it removed so a cap-aware caller
     // (`assembleImageInput`) can shed its own lowest-value text and re-assemble.
     const maxLen = getMaxImagePromptChars(provider)
-    const reserved = styleSuffix.length + avoidSuffix.length
+    // Reserved on the PRE-cut body; the cut can only NARROW the separator (see
+    // `controlSuffixes`), so the re-derived suffixes always fit the reservation.
+    const preCut = controlSuffixes(prompt, styleLine, avoidLine)
+    const reserved = preCut.styleSuffix.length + preCut.avoidSuffix.length
     if (prompt.length + reserved > maxLen) {
       if (marks) marks.overflowChars += prompt.length + reserved - maxLen
       prompt = prompt.slice(0, Math.max(0, maxLen - reserved - 3)) + "..."
     }
+    const { styleSuffix, avoidSuffix } = controlSuffixes(prompt, styleLine, avoidLine)
+    if (marks) {
+      marks.styleSuffix = styleSuffix
+      marks.avoidSuffix = avoidSuffix
+    }
     // Body span = everything after the captured directive prefix, taken from the
     // possibly-truncated body so the segment join still reconstructs (empty in the
     // Phase-0 consolidation branch → collapses via the fallback, the documented
@@ -2878,37 +2918,38 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
       })
     })
 
-  // Assemble prompt
+  // Assemble prompt. The wrapper template composes the BODY only — a `[style]`
+  // section is lifted off first and re-attached after, so a description can
+  // never land under its header (and a user-overridden template, which may put
+  // the descriptions anywhere, still only ever rearranges the body).
   let prompt = config.prompt
   if (charDescs.length > 0) {
     const wrapperTemplate = resolveTemplate("generate-image-wrapper", userTemplates, flowTemplates)
-    prompt = applyTemplate(wrapperTemplate, {
-      userPrompt: prompt,
+    const { body, section } = splitStyleSection(prompt)
+    const wrapped = applyTemplate(wrapperTemplate, {
+      userPrompt: body,
       assetDescriptions: charDescs.join(" "),
     })
+    prompt = section.length > 0 ? `${wrapped}${STYLE_SECTION_GAP}${section}` : wrapped
   }
 
   // Append style — if the inline `style` is a known STYLES catalog id, inject
   // the richer promptHint; otherwise fall back to the raw text (covers custom
   // free-text styles that don't match a preset).
   const styleText = style?.trim()
-  const styleSuffix = styleText ? `\nStyle: ${getStylePromptHint(styleText) || styleText}` : ""
+  const styleLine = styleText ? `Style: ${getStylePromptHint(styleText) || styleText}` : ""
 
   // Handle negative prompt: native support vs prompt-appended
   const negPrompt = negativePrompt?.trim()
   let nativeNegativePrompt: string | undefined
-  let avoidSuffix = ""
+  let avoidLine = ""
   if (negPrompt) {
     if (NATIVE_NEGATIVE_PROMPT_MODELS.has(provider)) {
       nativeNegativePrompt = negPrompt.slice(0, getMaxNegativePromptChars(provider))
     } else {
-      avoidSuffix = `\nAvoid: ${negPrompt}`
+      avoidLine = `Avoid: ${negPrompt}`
     }
   }
-  if (marks) {
-    marks.styleSuffix = styleSuffix
-    marks.avoidSuffix = avoidSuffix
-  }
 
   // Cap at the provider max (default IMAGE_PROMPT_MAX = 5000), reserving the
   // style/avoid suffixes so a long body never severs the appended control text
@@ -2916,11 +2957,17 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
   // BODY, THEN append the suffixes. Same order-blind cut as the
   // connectedReferences path above → same `overflowChars` bookkeeping.
   const maxLen = getMaxImagePromptChars(provider)
-  const reserved = styleSuffix.length + avoidSuffix.length
+  const preCut = controlSuffixes(prompt, styleLine, avoidLine)
+  const reserved = preCut.styleSuffix.length + preCut.avoidSuffix.length
   if (prompt.length + reserved > maxLen) {
     if (marks) marks.overflowChars += prompt.length + reserved - maxLen
     prompt = prompt.slice(0, Math.max(0, maxLen - reserved - 3)) + "..."
   }
+  const { styleSuffix, avoidSuffix } = controlSuffixes(prompt, styleLine, avoidLine)
+  if (marks) {
+    marks.styleSuffix = styleSuffix
+    marks.avoidSuffix = avoidSuffix
+  }
   // Legacy path has no directive prefix; the body is the char-desc-wrapped
   // (possibly-truncated) prompt right before the style/avoid suffixes.
   if (marks) marks.bodyBeforeSuffixes = prompt
@@ -3394,15 +3441,25 @@ function capitalizeLineInitial(line: string): string {
 
 /** Render the user prompt as the hybrid scene: each `{image:N:label}` token
  *  expanded to its uniform lettered phrase, each line's first letter
- *  capitalized. No per-role special-casing — the label drives the phrase. */
+ *  capitalized. No per-role special-casing — the label drives the phrase.
+ *
+ *  The capitalizer STOPS at the `[style]` section and everything after it: the
+ *  header would become `[Style]:`, and every catalog clause under it would gain
+ *  a capital it was not written with. The header line is matched EXACTLY — the
+ *  composer never indents it, and the whitespace collapses on this path are
+ *  horizontal-only (`[^\S\r\n]`), so nothing can pad it before this runs. */
 function buildHybridScene(
   prompt: string,
   refs: readonly ConnectedReference[],
   finalIndexByUrl: ReadonlyMap<string, number>,
 ): string {
-  return prompt
-    .split("\n")
-    .map((line) => capitalizeLineInitial(expandImageRefTokensHybrid(line, refs, finalIndexByUrl)))
+  const lines = prompt.split("\n")
+  const sectionAt = lines.indexOf(STYLE_SECTION_HEADER)
+  return lines
+    .map((line, i) => {
+      const expanded = expandImageRefTokensHybrid(line, refs, finalIndexByUrl)
+      return sectionAt >= 0 && i >= sectionAt ? expanded : capitalizeLineInitial(expanded)
+    })
     .join("\n")
 }
 

package/src/prompt-hint-join.ts

@@ -10,6 +10,15 @@
  * ("prompt. hint", not "prompt . hint"), and drop a blank body so the result
  * never starts with ". ".
  *
+ * WHAT THIS JOIN COVERS NOW: the prompt BODY only. A LOOK clause no longer
+ * reaches this function from either composer — it lifts into the trailing
+ * `[style]` section (`prompt-style-section.ts`), which is `". "`-joined WITHIN a
+ * line but hung off the body by a blank line. So "every folded clause is one
+ * `". "` further along the same string" stopped being true for a look-carrying
+ * call, deliberately; `composeSectionedPrompt` is the whole-prompt shape and
+ * this is the piece of it that assembles the body. The zero-hint no-op branch is
+ * untouched and still the thing the routes' `composed !== prompt` guard reads.
+ *
  * Never mutates its inputs.
  */
 

package/src/prompt-style-section.ts

@@ -0,0 +1,256 @@
+/**
+ * THE `[style]` SECTION — the trailing block an assembled prompt carries when a
+ * run selects any LOOK dimension, shared by the image (`assembleImageInput`)
+ * and video (`composeVideoPromptText`) composers so the two surfaces render one
+ * shape.
+ *
+ *     <body>
+ *
+ *     [style]:
+ *     <film line>
+ *     <scene line>
+ *
+ * WHY THE LOOK CLAUSES MOVED: folded inline, a broad direction buried the shot
+ * — a dozen grade/lighting/era sentences between the user's prose and the
+ * structured fields, all in the same register, with nothing telling the model
+ * which sentences describe the ACTION and which describe the LOOK. The section
+ * says it structurally instead.
+ *
+ * WHAT STAYS IN THE BODY: the user's prose, the subject fold, the whole MOTION
+ * family, and the structured fragment last. Camera motion is part of the shot
+ * prose, not the look — so the body/section boundary IS the registry's `family`
+ * column, the same column the video verbosity policy splits on. Coupling them
+ * is deliberate: one row cannot be shot-prose for the verbosity policy and look
+ * for the section.
+ *
+ * THE SECTION HAS NO TERMINATOR, so "after the section" is not a shape a caller
+ * can reach by appending: every assembler downstream of the composer (both
+ * reference resolvers, the legacy character-description wrapper, `Style:` /
+ * `Avoid:`) joins its text with a single `\n`, which lands it UNDER the header.
+ * Two helpers below are how they stay out — `insertBeforeStyleSection` for body
+ * content, `endsInsideStyleSection` for the self-labeling control lines that
+ * must stay last. A terminator instead would dangle whenever nothing follows,
+ * and would break the byte parity below.
+ *
+ * THE ZERO-CLAUSE CONTRACT (load-bearing): with no look clause — none selected,
+ * all shed, or all deduped away — there is NO header and NO extra newline, and
+ * the output is byte-identical to the plain hint join. That keeps the
+ * verbatim-and-untrimmed no-op alive (zero hints AND zero section → the user's
+ * prompt back byte-for-byte, `undefined` included), which is what the routes'
+ * `composed !== prompt` guard reads to decide whether to pin
+ * `input_data.userPrompt`.
+ *
+ * NO INDENTATION ANYWHERE: the video reference resolver collapses 2+ horizontal
+ * spaces unanchored, so an indented section line would come back flattened. The
+ * section is written flush-left rather than relying on that collapse to be
+ * harmless.
+ */
+import { joinPromptHints, PROMPT_HINT_SEPARATOR } from "./prompt-hint-join.js"
+import {
+  renderDirectionHintClauses,
+  type DirectionFamily,
+  type DirectionFields,
+  type DirectionHintMode,
+  type DirectionStyleGroup,
+} from "./direction-registry.js"
+
+/**
+ * The section header, verbatim. Lowercase and bracketed so it reads as
+ * structure rather than as a sentence — and so it can be found again by
+ * `buildImagePrompt`'s hybrid line-capitalizer, which must stop here
+ * (`[Style]:` would be a different token, and capitalized clause lines would
+ * corrupt the lowercase catalog wording).
+ */
+export const STYLE_SECTION_HEADER = "[style]:"
+
+/** The blank line between the body and the section. Omitted for an empty body. */
+export const STYLE_SECTION_GAP = "\n\n"
+
+/** The section's opening bytes — the gap, the header and the newline before its
+ *  first clause line (the section is never emitted without one). */
+const STYLE_SECTION_OPENING = `${STYLE_SECTION_GAP}${STYLE_SECTION_HEADER}\n`
+
+/**
+ * Split a composed prompt into the BODY and the `[style]` section it ends with
+ * (`section: ""` when it carries none, the body then being the whole string;
+ * the section comes back WITHOUT the gap).
+ *
+ * Matched from the RIGHT: the composer always emits the section last, and a
+ * user's own prose is free to contain the same characters. A blank body drops
+ * the gap with it, so the section-only form is matched on its own.
+ */
+export function splitStyleSection(prompt: string): { body: string; section: string } {
+  const at = prompt.lastIndexOf(STYLE_SECTION_OPENING)
+  if (at >= 0) {
+    return { body: prompt.slice(0, at), section: prompt.slice(at + STYLE_SECTION_GAP.length) }
+  }
+  return prompt.startsWith(`${STYLE_SECTION_HEADER}\n`)
+    ? { body: "", section: prompt }
+    : { body: prompt, section: "" }
+}
+
+/**
+ * Extend a composed prompt's BODY with more lines, AHEAD of the `[style]`
+ * section — what every assembler downstream of the composer needs, because the
+ * section has no terminator: a plain append lands under the header and reads as
+ * one more look clause. Reference bindings, element directives and character
+ * descriptions are scene content that belongs with the prose, and leaving the
+ * look clauses last is where a look tail was measured to cost nothing.
+ *
+ * With no section this IS the plain `"\n"` join every caller emitted before —
+ * the byte-parity path, down to the leading newline an empty prompt produces.
+ */
+export function insertBeforeStyleSection(prompt: string, lines: readonly string[]): string {
+  if (lines.length === 0) return prompt
+  const block = lines.join("\n")
+  const { body, section } = splitStyleSection(prompt)
+  if (section.length === 0) return `${prompt}\n${block}`
+  return `${body.length > 0 ? `${body}\n${block}` : block}${STYLE_SECTION_GAP}${section}`
+}
+
+/**
+ * True when `prompt` ends INSIDE the section — its last `\n\n`-delimited block
+ * opens with the header. What the self-labeling control lines (`Style:`,
+ * `Avoid:`) read: they stay at the END of the prompt by design, so a blank line
+ * of their own is the only thing that can close the header's scope ahead of
+ * them.
+ */
+export function endsInsideStyleSection(prompt: string): boolean {
+  const at = prompt.lastIndexOf(STYLE_SECTION_GAP)
+  const lastBlock = at >= 0 ? prompt.slice(at + STYLE_SECTION_GAP.length) : prompt
+  return lastBlock.startsWith(`${STYLE_SECTION_HEADER}\n`)
+}
+
+/** Where a rendered clause reads in the assembled prompt. */
+export type PromptClauseSlot = "body" | "film" | "scene"
+
+/** A rendered clause plus the line it belongs on. */
+export interface SlottedPromptClause {
+  readonly text: string
+  readonly slot: PromptClauseSlot
+}
+
+/**
+ * The slot a direction row's clause takes: motion stays in the body, the five
+ * `styleGroup: "film"` rows lead the section, every other look row follows on
+ * the scene line.
+ */
+export function styleSlotFor(
+  row: { readonly family: DirectionFamily; readonly styleGroup?: DirectionStyleGroup },
+): PromptClauseSlot {
+  if (row.family === "motion") return "body"
+  return row.styleGroup === "film" ? "film" : "scene"
+}
+
+/**
+ * The SUBJECT channel's clauses: always body. Who is in the shot is the noun
+ * phrase the look modifies, not part of the look.
+ */
+export function asBodyClauses(texts: readonly string[]): SlottedPromptClause[] {
+  return texts.map((text) => ({ text, slot: "body" as const }))
+}
+
+/**
+ * Fold a direction bag and tag each clause with its slot, in registry table
+ * order. The ORDER is the fold/survival order, not the string order — the
+ * composers slice this list from the tail when a cap forces a shed, and only
+ * then hand the surviving prefix to `composeSectionedPrompt`.
+ */
+export function partitionStyleClauses(
+  direction: DirectionFields | undefined,
+  opts: { surface: "image" | "video"; mode?: DirectionHintMode },
+): SlottedPromptClause[] {
+  return renderDirectionHintClauses(direction, opts).map((clause) => ({
+    text: clause.text,
+    slot: styleSlotFor(clause),
+  }))
+}
+
+/**
+ * The section block for a set of clauses — `""` when none of them is a look
+ * clause. Each line is omitted entirely when its half of the split is empty, so
+ * a scene-only fold never emits a blank film line.
+ */
+export function styleSectionFromClauses(clauses: readonly SlottedPromptClause[]): string {
+  const line = (slot: PromptClauseSlot) =>
+    clauses
+      .filter((c) => c.slot === slot)
+      .map((c) => c.text)
+      .join(PROMPT_HINT_SEPARATOR)
+  const lines = [line("film"), line("scene")].filter((l) => l.length > 0)
+  return lines.length === 0 ? "" : `${STYLE_SECTION_HEADER}\n${lines.join("\n")}`
+}
+
+/**
+ * The section for a raw direction bag — the entry point a client renders its
+ * preview through, so the preview and the server emit the same bytes.
+ */
+export function renderStyleSection(
+  direction: DirectionFields | undefined,
+  opts: { surface: "image" | "video"; mode?: DirectionHintMode },
+): string {
+  return styleSectionFromClauses(partitionStyleClauses(direction, opts))
+}
+
+/**
+ * The assembled prompt for a set of clauses: body clauses `". "`-joined onto the
+ * user's prompt, the structured fragment last in the body, then the section.
+ *
+ * TRIMMING follows `joinPromptHints`: the prompt is trimmed whenever ANYTHING
+ * folded — a section counts, so a look-only fold trims too, or the blank line
+ * would inherit the prompt's trailing whitespace. With nothing folded at all the
+ * prompt is returned VERBATIM AND UNTRIMMED (`undefined` passes straight
+ * through), which is the byte-parity contract every existing caller rests on.
+ *
+ * A blank body drops the gap with it, so the result never opens on a newline —
+ * the same reason `joinPromptHints` filters a blank prompt out of its join.
+ */
+export function composeSectionedPrompt<T extends string | undefined>(
+  userPrompt: T,
+  clauses: readonly SlottedPromptClause[],
+  structuredFragment: string,
+): string | T {
+  const bodyHints = [
+    ...clauses.filter((c) => c.slot === "body").map((c) => c.text),
+    structuredFragment,
+  ].filter((p) => p.length > 0)
+  const section = styleSectionFromClauses(clauses)
+  if (section.length === 0) {
+    return bodyHints.length === 0 ? userPrompt : joinPromptHints(userPrompt ?? "", bodyHints)
+  }
+  const body =
+    bodyHints.length > 0 ? joinPromptHints(userPrompt ?? "", bodyHints) : (userPrompt ?? "").trim()
+  return body.length > 0 ? `${body}${STYLE_SECTION_GAP}${section}` : section
+}
+
+/**
+ * What each clause costs the assembled prompt, as the EXACT composed-length
+ * delta of adding it to the prefix below it. Feeds `keepableDirectionHints`,
+ * which walks the list tail-first.
+ *
+ * Exact deltas rather than "clause + separator" because the section's own bytes
+ * are not evenly distributed: the FIRST look clause carries the whole
+ * `"\n\n[style]:\n"` header (11 characters that only come back when the section
+ * disappears), the second look clause of a line carries a `". "`, the first of
+ * the scene line carries a `"\n"`. Flat costs would under-price the header, so
+ * the walk would cover a deficit with more clauses than it needs and over-shed
+ * — visible as a fold that drops two clauses where one would have fit. The
+ * deltas do not change between shed iterations (the walk only ever shortens the
+ * prefix), so they are computed once, before the loop.
+ */
+export function sectionedClauseCosts(
+  userPrompt: string | undefined,
+  clauses: readonly SlottedPromptClause[],
+  structuredFragment: string,
+): number[] {
+  const lengthAt = (kept: number) =>
+    composeSectionedPrompt(userPrompt, clauses.slice(0, kept), structuredFragment)?.length ?? 0
+  const costs: number[] = []
+  let below = lengthAt(0)
+  for (let i = 0; i < clauses.length; i++) {
+    const at = lengthAt(i + 1)
+    costs.push(at - below)
+    below = at
+  }
+  return costs
+}

package/src/prompt-wizard-categories.ts

@@ -256,6 +256,9 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "ltx-2.3-pro":  "Lightricks LTX 2.3 Pro — text/image/audio→video, 6–10s, up to 4K",
     "ltx-2.3-fast": "Lightricks LTX 2.3 Fast — text/image→video, 6–20s, up to 4K",
     "gemini-omni-video": "Google Gemini Omni — multimodal video with native audio, 4–10s, up to 4K.",
+    "gemini-omni-flash": "Google Gemini Omni Flash — faster, cheaper Omni tier; multimodal video with native audio, 4–10s, up to 4K.",
+    "wan-3": "Wan 3.0 — multimodal refs (10 images / 5 videos / 5 audio) or first+last frame, native audio, 2–30s, 480p/720p/1080p",
+    "wan-3-prime": "Wan 3.0 Prime — high-speed Wan 3.0 tier; same surface, faster turnaround at a higher rate",
     "grok-imagine-video-1.5": "Grok Imagine 1.5 — image-to-video only; requires an input image",
   },
   "image-to-video": {
@@ -289,6 +292,9 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "ltx-2.3-pro":  "Lightricks LTX 2.3 Pro — start/end frame i2v + audio→video, 6–10s, up to 4K",
     "ltx-2.3-fast": "Lightricks LTX 2.3 Fast — start/end frame i2v, 6–20s, up to 4K",
     "gemini-omni-video": "Google Gemini Omni — multimodal video with native audio, 4–10s, up to 4K.",
+    "gemini-omni-flash": "Google Gemini Omni Flash — faster, cheaper Omni tier; multimodal video with native audio, 4–10s, up to 4K.",
+    "wan-3": "Wan 3.0 — multimodal refs (10 images / 5 videos / 5 audio) or first+last frame, native audio, 2–30s, 480p/720p/1080p",
+    "wan-3-prime": "Wan 3.0 Prime — high-speed Wan 3.0 tier; same surface, faster turnaround at a higher rate",
     "grok-imagine-video-1.5": "Grok Imagine 1.5 — stylized animation, 1–15s, 480p/720p (image required)",
   },
   "video-to-video": {

package/src/provider-prompt-doctrine.ts

@@ -239,8 +239,8 @@ KIE VEO API docs (docs.kie.ai/veo3-api/generate-veo-3-video). Captured 2026-08-0
 }
 
 const GEMINI_OMNI_DOCTRINE: ProviderPromptDoctrine = {
-  providers: ["gemini-omni-video"],
-  heading: "Gemini Omni Video (gemini-omni-video)",
+  providers: ["gemini-omni-video", "gemini-omni-flash"],
+  heading: "Gemini Omni (gemini-omni-video, gemini-omni-flash)",
   tips: [
     "Multimodal Google video with native audio: text-to-video, image-to-video, and video-edit through the same prompt surface. 4/6/8/10s; 720p/1080p or 4K tier.",
     "Structure like the platform default: subject → action → scene → lighting → camera → style. Quote dialogue lines to have them spoken; describe SFX/ambience plainly in the prompt.",
@@ -262,6 +262,7 @@ subject → action → scene/environment → lighting → camera movement → st
 
 **Duration & tiers**
 - 4 / 6 / 8 / 10 seconds. 720p/1080p tier or the pricier 4K tier — pick 4K only when the deliverable needs it (nearly 2× the credits).
+- gemini-omni-flash is the faster/cheaper tier with the identical request surface — same 4/6/8/10s, same 720p/1080p and 4K tiers, same video-edit path. Everything above applies verbatim.
 
 Source: KIE gemini-omni-video market contract (parameters + live behavior probed for the
 aspect-ratio hard-reject, see providers/kie/video.ts). Captured 2026-08-09.`,
@@ -334,6 +335,53 @@ Source: Alibaba Cloud Model Studio — "Text-to-video / image-to-video prompt gu
 (alibabacloud.com/help/en/model-studio/text-to-video-prompt). Captured 2026-08-09.`,
 }
 
+// Wan 3.0 is a SEPARATE doctrine from WAN_DOCTRINE on purpose: Wan 2.x binds
+// references as "Image 1" / "Video 1" (capitalised, WITH a space) while the Wan
+// 3.0 contract uses "Image1" / "Video1" / "Audio1" (no space), and 3.0's surface
+// (adaptive aspect, boolean audio, 30s, mutually-exclusive frame vs reference
+// modes) is different. Folding them together would ship a token format the model
+// does not use. There is no published Wan 3.0 prompt guide, so the body below is
+// KIE contract facts only — no invented vendor style claims.
+const WAN_3_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["wan-3", "wan-3-prime"],
+  heading: "Wan 3.0 (wan-3, wan-3-prime)",
+  tips: [
+    "Two INPUT MODES, exclusive on the wire: first/last frame, OR reference mode (images + videos + audio). With any reference wired the platform folds the frame into the references and names it in the prompt.",
+    "References bind by ordinal token in array order: Image1, Image2, Video1, Audio1 — no space, unlike Wan 2.x's \"Image 1\". Name every wired asset or it may be ignored.",
+    "Reference caps: 10 images / 5 videos / 5 audio clips; each video and each audio clip 1-15s, with ≤15s combined per array. With reference videos, input seconds + output duration ≤ 30.",
+    "2-30 seconds (default 5); 480p/720p/1080p; aspect adaptive (default, matches the input media) or 16:9 / 4:3 / 1:1 / 3:4 / 9:16. Prompt cap 20,000 chars — excess is truncated silently.",
+    "`audio` is a boolean, ON by default: the clip comes back with an ambient/SFX track. Cue the sound you want in the prompt, or state the exclusion (\"no music\") — it is not a dialogue guarantee.",
+    "wan-3-prime is the HIGH-SPEED tier: identical surface and limits, faster turnaround at a higher per-second rate. It is not a quality upgrade — choose it for latency, not for looks.",
+  ],
+  doctrine: `Prompt structure (no public Wan 3.0 prompt guide exists — the KIE API contract is the
+doctrine source, like MiniMax H3 and HappyHorse; platform-standard structure applies):
+subject → action → scene/environment → lighting → camera movement → style → constraints.
+
+**Modes (mutually exclusive at the provider)**
+- Frame mode: first_frame_url, optionally with last_frame_url, and NO references — the frames anchor the shot exactly, so describe MOTION and camera, not the still.
+- Reference mode: image / video / audio reference arrays. The provider CANNOT take these together with the first/last frame parameters, so when both are wired the platform folds — the frame is appended to the reference images (after the caller's own, ordinals unchanged) and bound in the prompt as the opening/closing frame. Write for reference mode whenever a reference is attached.
+- Text-only runs are supported and are the model's default mode.
+
+**Reference binding**
+- Assets bind by ORDINAL TOKEN in array order: Image1, Image2, …, Video1, …, Audio1, …. Note the format has NO space — Wan 2.x's "Image 1" is a different generation and does not apply here.
+- Write the binding into the prompt explicitly ("Image1 walks into the room described in Image2"); an unnamed reference may simply be ignored.
+- Caps: up to 10 images, 5 videos, 5 audio clips. Each video and each audio clip must be 1-15s with ≤15s combined per array. Audio should not be the only media input — pair it with an image or a video.
+
+**Duration, resolution, aspect**
+- 2-30 seconds (provider default 5). With reference videos there is an extra ceiling: input video duration + output duration ≤ 30 seconds.
+- 480p / 720p / 1080p. Aspect "adaptive" (the default — the model selects the ratio from the input media and intent) or 16:9 / 4:3 / 1:1 / 3:4 / 9:16. There is no 21:9.
+- Prompts accept Chinese and English, up to 20,000 characters; anything beyond is truncated silently, so front-load the load-bearing content.
+
+**Audio**
+- The "audio" boolean defaults ON and produces an ambient/SFX track with the clip. Describe the soundscape you want plainly ("rain on glass, distant traffic"), or state the exclusion, or turn the toggle off. The contract documents no lip-synced dialogue guarantee — plan spoken lines as a separate TTS + lip-sync pass.
+
+**Tiers**
+- wan-3 and wan-3-prime take identical inputs. Prime trades a higher per-second rate for faster turnaround; it is not documented as a quality tier.
+
+Source: KIE Wan 3.0 market contract (docs.kie.ai/market/wan/3-0-video,
+docs.kie.ai/market/wan/3-0-video-prime). Captured 2026-09-01.`,
+}
+
 const HAPPYHORSE_DOCTRINE: ProviderPromptDoctrine = {
   providers: ["happyhorse", "happyhorse-i2v", "happyhorse-ref2v", "happyhorse-edit"],
   heading: "HappyHorse 1.1 (happyhorse, happyhorse-i2v, happyhorse-ref2v)",
@@ -391,6 +439,7 @@ export const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[] = [
   GEMINI_OMNI_DOCTRINE,
   GROK_IMAGINE_DOCTRINE,
   WAN_DOCTRINE,
+  WAN_3_DOCTRINE,
   HAPPYHORSE_DOCTRINE,
   RUNWAY_KIE_DOCTRINE,
 ]

package/src/setting.ts

@@ -85,6 +85,7 @@ export const SETTINGS: ReadonlyArray<Setting> = [
   { id: "parking-lot",     label: "Parking Lot",          category: "urban",       description: "Suburban parking lot at dusk",           promptHint: "set in an empty suburban parking lot at dusk with sodium-vapor lamps casting orange pools, scattered shopping carts and painted lane lines" },
   { id: "penthouse",       label: "Penthouse",            category: "urban",       description: "Luxury penthouse with skyline view",     promptHint: "set in a luxury penthouse interior with panoramic skyline views, marble floors, modernist furniture and low warm ambient light" },
   { id: "gas-station",     label: "Gas Station",          category: "urban",       description: "Lonely highway gas station at night",    promptHint: "set at a lonely highway gas station at night with a fluorescent canopy, bug-swarmed sodium lamps and cracked asphalt" },
+  { id: "open-air-market", label: "Open-Air Market",      category: "urban",       description: "Bustling market of vendor stalls under canopies", term: "open-air market", promptHint: "set in a bustling open-air market — rows of vendor stalls under thatched and canvas canopies, produce piled high, warm dusty light and crowds moving between the stalls" },
 
   // -------------------- Nature --------------------
   { id: "forest",          label: "Forest Clearing",      category: "nature",      description: "Sunlit mossy clearing",                  promptHint: "set in a sunlit forest clearing with moss-covered stones, dappled light through tall trees and a soft carpet of fallen leaves" },