@nodaro/prompts 1.20.0 → 1.23.0

package/src/__tests__/fixtures/parameter-hint-golden.json

@@ -658,17 +658,17 @@
       "expected": "the subject lets the jaw fall open under its own weight until the mouth hangs wide and slack, the lips loose and the tongue still, holding it open while the rest of the face stays blank"
     },
     {
-      "key": "character-motion/id:rise-after-knockdown",
+      "key": "character-motion/id:sprint-start",
       "note": "single-dim catalog id",
       "node": {
         "id": "n1",
         "type": "character-motion",
         "data": {
-          "characterMotion": "rise-after-knockdown"
+          "characterMotion": "sprint-start"
         }
       },
       "ctx": null,
-      "expected": "the subject pushes up from the ground onto one knee, plants a hand and rises to standing, shakes the head clear and raises both fists back into guard"
+      "expected": "the subject crouches in starting blocks with fingertips on the line, raises the pelvis into the set position, then drives forward off the front foot in a low lean and accelerates into full stride"
     },
     {
       "key": "character-motion/multi-pick",
@@ -2970,19 +2970,19 @@
     },
     {
       "key": "transition/timing",
-      "note": "transition with position + duration + intensity, no ctx",
+      "note": "transition with position + duration + intensity, no ctx (a non-instant row, so the duration clause is emitted)",
       "node": {
         "id": "n1",
         "type": "transition",
         "data": {
-          "transition": "none",
+          "transition": "cross-dissolve",
           "position": "middle",
           "duration": "short",
           "intensity": "dynamic"
         }
       },
       "ctx": null,
-      "expected": "no transition, hard cut, instantaneous switch from first shot to second shot, the transition occurs in the middle of the clip, lasting approximately 1 second, with dynamic energy and assertive flourish"
+      "expected": "smooth cross-dissolve transition where the first shot gradually fades out as the second shot fades in, the transition occurs in the middle of the clip, lasting approximately 1 second, with dynamic energy and assertive flourish"
     },
     {
       "key": "transition/timing-auto",
@@ -3000,6 +3000,22 @@
       "ctx": null,
       "expected": "no transition, hard cut, instantaneous switch from first shot to second shot"
     },
+    {
+      "key": "transition/timing-instant",
+      "note": "an INSTANT transition (a cut) with position + duration + intensity — the duration clause is dropped",
+      "node": {
+        "id": "n1",
+        "type": "transition",
+        "data": {
+          "transition": "none",
+          "position": "middle",
+          "duration": "short",
+          "intensity": "dynamic"
+        }
+      },
+      "ctx": null,
+      "expected": "no transition, hard cut, instantaneous switch from first shot to second shot, the transition occurs in the middle of the clip, with dynamic energy and assertive flourish"
+    },
     {
       "key": "transition/with-ctx",
       "note": "transition composing startState + endState clauses",

package/src/__tests__/frame-delivery.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest"
+import { planFrameDelivery } from "../frame-delivery.js"
+
+const START = "https://cdn.example/start.png"
+const END = "https://cdn.example/end.png"
+
+describe("planFrameDelivery", () => {
+  it("keeps a frame as a frame on a model whose frame mode measured fine", () => {
+    const plan = planFrameDelivery({
+      provider: "seedance-2-5", supportsReferenceImages: true, startFrameUrl: START, prompt: "a walk",
+    })
+    expect(plan).toEqual({ delivery: "frame", referenceImageUrls: [], promptSuffix: "" })
+  })
+
+  it("moves the frame into the reference list on the Seedance 2.0 family", () => {
+    const plan = planFrameDelivery({
+      provider: "seedance-2-fast", supportsReferenceImages: true, startFrameUrl: START,
+    })
+    expect(plan.delivery).toBe("reference")
+    expect(plan.referenceImageUrls).toEqual([START])
+    expect(plan.promptSuffix).toBe("Use @image_1 as the opening (first) frame of the video.")
+  })
+
+  it("appends frames after the user's own images so their ordinals hold", () => {
+    const plan = planFrameDelivery({
+      provider: "seedance-2-fast",
+      supportsReferenceImages: true,
+      startFrameUrl: START,
+      endFrameUrl: END,
+      userReferenceUrls: ["https://cdn.example/a.png", "https://cdn.example/b.png"],
+    })
+    expect(plan.referenceImageUrls).toEqual(["https://cdn.example/a.png", "https://cdn.example/b.png", START, END])
+    expect(plan.promptSuffix).toContain("@image_3 as the opening (first) frame")
+    expect(plan.promptSuffix).toContain("@image_4 as the closing (last) frame")
+  })
+
+  it("adds no second opening sentence when the prompt already binds one", () => {
+    const plan = planFrameDelivery({
+      provider: "seedance-2-fast",
+      supportsReferenceImages: true,
+      startFrameUrl: START,
+      prompt: "Use @image_1 as the first frame, it is the last keyframe of @video_1",
+    })
+    expect(plan.delivery).toBe("reference")
+    expect(plan.promptSuffix).toBe("")
+  })
+
+  it("honours an explicit choice in both directions", () => {
+    expect(planFrameDelivery({
+      provider: "seedance-2-fast", requested: "frame", supportsReferenceImages: true, startFrameUrl: START,
+    }).delivery).toBe("frame")
+    expect(planFrameDelivery({
+      provider: "veo3.1", requested: "reference", supportsReferenceImages: true, startFrameUrl: START,
+    }).delivery).toBe("reference")
+  })
+
+  it("refuses, with a reason, on a model that takes no reference images", () => {
+    const plan = planFrameDelivery({
+      provider: "wan-i2v", requested: "reference", supportsReferenceImages: false, startFrameUrl: START,
+    })
+    expect(plan).toMatchObject({ delivery: "frame", refusedReason: "no-reference-support" })
+  })
+
+  it("refuses rather than displace a user's reference image at the cap", () => {
+    const refs = Array.from({ length: 9 }, (_, i) => `https://cdn.example/ref-${i}.png`)
+    const plan = planFrameDelivery({
+      provider: "seedance-2-fast", supportsReferenceImages: true, startFrameUrl: START, userReferenceUrls: refs,
+    })
+    expect(plan).toMatchObject({ delivery: "frame", refusedReason: "image-cap" })
+    expect(plan.referenceImageUrls).toEqual(refs)
+  })
+
+  it("is a no-op when no frame is wired", () => {
+    const plan = planFrameDelivery({ provider: "seedance-2-fast", supportsReferenceImages: true })
+    expect(plan).toEqual({ delivery: "frame", referenceImageUrls: [], promptSuffix: "" })
+  })
+
+  it("plans the same shape whether it is asked with urls or with stand-ins", () => {
+    // The config panel knows a frame is wired before it knows its url, so it
+    // passes placeholders. Ordering and sentences must not depend on the string.
+    const real = planFrameDelivery({
+      provider: "seedance-2-mini", supportsReferenceImages: true, startFrameUrl: START, endFrameUrl: END,
+      userReferenceUrls: ["https://cdn.example/a.png"],
+    })
+    const preview = planFrameDelivery({
+      provider: "seedance-2-mini", supportsReferenceImages: true, startFrameUrl: "frame:start", endFrameUrl: "frame:end",
+      userReferenceUrls: ["ref:0"],
+    })
+    expect(preview.delivery).toBe(real.delivery)
+    expect(preview.promptSuffix).toBe(real.promptSuffix)
+    expect(preview.referenceImageUrls).toHaveLength(real.referenceImageUrls.length)
+  })
+})

package/src/__tests__/graph-composed-unwired-identity.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from "vitest"
+
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+import { getPickerCatalog, type PickerOption } from "../picker-catalogs.js"
+import { composeTransitionHintFromConnections } from "../transitions.js"
+import { composeCharacterFxHintFromConnections } from "../character-fx.js"
+import type { HintEdgeLike, HintGraphContext, HintNodeLike } from "@nodaro/shared"
+
+/**
+ * THE BOUND ON "compose transition and character-fx from the graph on every
+ * path", as a proof rather than a claim.
+ *
+ * Transition and character-fx joined `EXECUTION_GRAPH_COMPOSED_PARAMETER_TYPES`
+ * (@nodaro/shared) and `LABEL_REF_GRAPH_COMPOSED_PARAMETER_TYPES` (backend
+ * `services/workflow-engine/label-ref-hint-context.ts`), so every executor now
+ * hands them the graph. That deliberately changes the prompt of a workflow that
+ * WIRES them — signed off, and the new text is the text the picker's own
+ * injection preview has always shown.
+ *
+ * What was signed off with it is the BOUND: a picker with nothing wired to its
+ * own composing handles (`startState` / `endState` for transition, `target` for
+ * character-fx) must emit BYTE-IDENTICAL text with and without the graph, so a
+ * workflow that wires nothing cannot move at all. This file walks every entry
+ * of both catalogs, in both hint modes, under two unwired graph shapes, and
+ * asserts that equality — then proves it is not vacuous with wired positive
+ * controls that MUST differ.
+ *
+ * Why two unwired shapes: "unwired" in a real workflow does not mean an
+ * isolated node. The picker is normally wired INTO a consumer (an outgoing
+ * `cinematography` edge) while nothing feeds its own handles — the walker in
+ * `resolveParameterHint` only ever looks at edges whose TARGET is the picker,
+ * and this pins that.
+ */
+
+const MODES = ["full", "compact"] as const
+
+/** The two pickers this change admitted, with the data field each reads. */
+const SUBJECTS = [
+  { type: "transition", valueField: "transition" },
+  { type: "character-fx", valueField: "characterFx" },
+] as const
+
+function optionsFor(type: string): readonly PickerOption[] {
+  const catalog = getPickerCatalog(type)
+  if (!catalog?.options?.length) throw new Error(`no registered picker catalog options for ${type}`)
+  return catalog.options
+}
+
+function pickerNode(type: string, valueField: string, id: string, mode: string): HintNodeLike {
+  return { id: "picker", type, data: { [valueField]: id, hintMode: mode } }
+}
+
+/** Nothing at all around the picker. */
+function isolated(node: HintNodeLike): HintGraphContext {
+  return { nodes: [node], edges: [] }
+}
+
+/** The realistic unwired shape: the picker FEEDS a consumer, but nothing feeds it. */
+function wiredIntoConsumer(node: HintNodeLike): HintGraphContext {
+  const consumer: HintNodeLike = { id: "consumer", type: "generate-video", data: { prompt: "a man walks forward" } }
+  const edges: HintEdgeLike[] = [
+    { source: node.id, target: consumer.id, sourceHandle: null, targetHandle: "cinematography" },
+  ]
+  return { nodes: [node, consumer], edges }
+}
+
+const UNWIRED_SHAPES = [
+  { name: "isolated (no edges at all)", build: isolated },
+  { name: "wired INTO a consumer, nothing wired into it", build: wiredIntoConsumer },
+] as const
+
+describe("unwired transition / character-fx pickers are byte-identical with and without the graph", () => {
+  for (const { type, valueField } of SUBJECTS) {
+    for (const { name, build } of UNWIRED_SHAPES) {
+      it(`${type}: every catalog entry × both hint modes, ${name}`, () => {
+        const options = optionsFor(type)
+        const differences: string[] = []
+        let compared = 0
+
+        for (const option of options) {
+          for (const mode of MODES) {
+            const node = pickerNode(type, valueField, option.id, mode)
+            const withoutGraph = getParameterPromptHint(node)
+            const withGraph = getParameterPromptHint(node, build(node))
+            compared += 1
+            if (withGraph !== withoutGraph) {
+              differences.push(`${type}/${option.id}/${mode}: ${JSON.stringify(withoutGraph)} -> ${JSON.stringify(withGraph)}`)
+            }
+          }
+        }
+
+        // Non-vacuity of the WALK itself: a catalog that somehow arrived empty
+        // would pass a zero-difference assertion trivially.
+        expect(compared).toBe(options.length * MODES.length)
+        expect(compared).toBeGreaterThan(20)
+        expect(differences).toEqual([])
+      })
+    }
+  }
+
+  it("the catalogs really do carry injecting entries (the comparison is over real text, not all empty strings)", () => {
+    // `auto` / `none` inject "" by design and are legitimately compared; this
+    // asserts they are not ALL of it, so the identity above is meaningful.
+    for (const { type, valueField } of SUBJECTS) {
+      const injecting = optionsFor(type).filter(
+        (o) => getParameterPromptHint(pickerNode(type, valueField, o.id, "full")).trim().length > 0,
+      )
+      expect(injecting.length, type).toBeGreaterThan(20)
+    }
+  })
+})
+
+describe("positive control — a WIRED picker must differ (or the bound above proves nothing)", () => {
+  /** A tone node: free text, so its fragment is identical in both hint modes,
+   *  which keeps the control honest without re-deriving inherited-mode text. */
+  const tone = (id: string, text: string): HintNodeLike => ({ id, type: "tone", data: { tone: text } })
+
+  it("transition: a startState + endState wire changes the text, in both modes", () => {
+    const id = optionsFor("transition").find(
+      (o) => getParameterPromptHint(pickerNode("transition", "transition", o.id, "full")).trim().length > 0,
+    )!.id
+    const start = tone("start", "warm golden morning light")
+    const end = tone("end", "cold blue dusk")
+
+    for (const mode of MODES) {
+      const node = pickerNode("transition", "transition", id, mode)
+      const ctx: HintGraphContext = {
+        nodes: [node, start, end],
+        edges: [
+          { source: "start", target: node.id, sourceHandle: null, targetHandle: "startState" },
+          { source: "end", target: node.id, sourceHandle: null, targetHandle: "endState" },
+        ],
+      }
+      const composed = getParameterPromptHint(node, ctx)
+      expect(composed).not.toBe(getParameterPromptHint(node))
+      // Derived from the catalog composer, never a hand-written sentence.
+      expect(composed).toBe(
+        composeTransitionHintFromConnections(
+          id,
+          [getParameterPromptHint(start)],
+          [getParameterPromptHint(end)],
+          undefined,
+          mode,
+        ),
+      )
+    }
+  })
+
+  it("character-fx: a target ref wire changes the text, in both modes", () => {
+    const id = optionsFor("character-fx").find(
+      (o) => getParameterPromptHint(pickerNode("character-fx", "characterFx", o.id, "full")).trim().length > 0,
+    )!.id
+    const mira: HintNodeLike = { id: "mira", type: "character", data: { characterName: "Mira" } }
+
+    for (const mode of MODES) {
+      const node = pickerNode("character-fx", "characterFx", id, mode)
+      const ctx: HintGraphContext = {
+        nodes: [node, mira],
+        edges: [{ source: "mira", target: node.id, sourceHandle: null, targetHandle: "target" }],
+      }
+      const composed = getParameterPromptHint(node, ctx)
+      expect(composed).not.toBe(getParameterPromptHint(node))
+      expect(composed).toBe(composeCharacterFxHintFromConnections(id, ["Mira"], undefined, mode))
+    }
+  })
+})

package/src/__tests__/node-prompt-fields.test.ts

@@ -16,10 +16,10 @@ describe("nodeSupportsPromptAffixes", () => {
     expect(nodeSupportsPromptAffixes("not-a-node")).toBe(false)
     expect(nodeSupportsPromptAffixes(undefined)).toBe(false)
   })
-  it("PROMPT_AFFIX_NODE_TYPES is exactly the registry minus opt-outs (40 types)", () => {
+  it("PROMPT_AFFIX_NODE_TYPES is exactly the registry minus opt-outs (41 types)", () => {
     const expected = Object.entries(NODE_PROMPT_FIELDS).filter(([, s]) => s.affixes !== false).map(([t]) => t)
     expect([...PROMPT_AFFIX_NODE_TYPES].sort()).toEqual(expected.sort())
-    expect(PROMPT_AFFIX_NODE_TYPES.size).toBe(40)
+    expect(PROMPT_AFFIX_NODE_TYPES.size).toBe(41)
   })
   it("getPromptFields still resolves", () => expect(getPromptFields("generate-image")?.prompt).toBe("prompt"))
 })

package/src/__tests__/parameter-prompt-hint.test.ts

@@ -330,8 +330,14 @@ describe("getParameterPromptHint — character-motion minor-age floor", () => {
   const ADULT = { age: "age-30s" }
   const motion = { id: "n1", type: "character-motion", data: { characterMotion: ["wave-hello", "kiss-partner"] } }
   const wave = (target: string) => getCharacterMotionPromptHint("wave-hello").replace(/\bthe subject\b/g, target)
-  const kiss = (target: string, partner: string) =>
-    getCharacterMotionPromptHint("kiss-partner").replace(/\bthe subject\b/g, target).replace(/\bthe partner\b/g, partner)
+  // kiss-partner names the partner twice. A wired name repeats; the unwired
+  // fallback is introduced once and referred back to after that.
+  const kiss = (target: string, ...partner: readonly string[]) => {
+    let i = 0
+    return getCharacterMotionPromptHint("kiss-partner")
+      .replace(/\bthe subject\b/g, target)
+      .replace(/\bthe partner\b/g, () => partner[Math.min(i++, partner.length - 1)]!)
+  }
 
   it("a minor wired to target drops the adult-only move and keeps the neutral one", () => {
     const out = getParameterPromptHint(motion, {
@@ -347,7 +353,7 @@ describe("getParameterPromptHint — character-motion minor-age floor", () => {
       nodes: [{ id: "c1", type: "character", data: { characterName: "Mira", person: ADULT } }],
       edges: [{ source: "c1", target: "n1", targetHandle: "target" }],
     })
-    expect(out).toBe(`${wave("Mira")}, then ${kiss("Mira", "another person")}`)
+    expect(out).toBe(`${wave("Mira")}, then ${kiss("Mira", "another person", "that same person")}`)
     expect(out).toMatch(/kiss/)
   })
 

package/src/__tests__/transitions-instant.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest"
+import {
+  TRANSITIONS,
+  TRANSITION_DURATIONS,
+  composeTransitionHintFromConnections,
+  isInstantTransition,
+} from "../transitions.js"
+import { getPickerCatalog } from "../picker-catalogs.js"
+
+/**
+ * F5 (transition QA, 2026-09-22): a duration clause on a cut ("match cut, …,
+ * lasting approximately 1 second") made the video model render a 1.75 s
+ * dissolve. Rows whose mechanism IS a cut carry `instant: true`, and the
+ * composer drops the duration lever for them.
+ */
+const INSTANT_IDS = [
+  "none",
+  "snap-to-black",
+  "match-cut",
+  "smash-cut",
+  "seamless-match",
+  "jump-cut",
+  "jump-match",
+  "action-relay",
+]
+
+const DURATION_HINTS = TRANSITION_DURATIONS.map((d) => d.promptHint).filter((h) => h.length > 0)
+
+describe("instant transitions — the catalog marker", () => {
+  it("marks exactly the cut rows", () => {
+    expect(TRANSITIONS.filter((t) => t.instant).map((t) => t.id).sort()).toEqual([...INSTANT_IDS].sort())
+  })
+
+  it("isInstantTransition answers per id, and false for unknown / auto / empty", () => {
+    for (const id of INSTANT_IDS) expect(isInstantTransition(id)).toBe(true)
+    expect(isInstantTransition("cross-dissolve")).toBe(false)
+    expect(isInstantTransition("whip-pan")).toBe(false)
+    expect(isInstantTransition("freeze-frame-jump")).toBe(false)
+    expect(isInstantTransition("auto")).toBe(false)
+    expect(isInstantTransition("nonexistent")).toBe(false)
+    expect(isInstantTransition("")).toBe(false)
+    expect(isInstantTransition(undefined)).toBe(false)
+    expect(isInstantTransition(null)).toBe(false)
+    expect(isInstantTransition([])).toBe(false)
+  })
+
+  it("a multi-pick is instant only when every id is", () => {
+    expect(isInstantTransition(["match-cut", "smash-cut"])).toBe(true)
+    expect(isInstantTransition(["match-cut", "cross-dissolve"])).toBe(false)
+  })
+})
+
+describe("instant transitions — the composer drops the duration lever", () => {
+  for (const mode of ["full", "compact"] as const) {
+    it(`${mode}: no duration clause on any instant row, for every duration`, () => {
+      for (const id of INSTANT_IDS) {
+        for (const d of TRANSITION_DURATIONS) {
+          const r = composeTransitionHintFromConnections(id, [], [], { duration: d.id }, mode)
+          for (const hint of DURATION_HINTS) expect(r).not.toContain(hint)
+        }
+      }
+    })
+
+    it(`${mode}: position and intensity still apply to a cut`, () => {
+      const r = composeTransitionHintFromConnections(
+        "match-cut", [], [], { position: "middle", duration: "short", intensity: "natural" }, mode,
+      )
+      expect(r).toContain("the transition occurs in the middle of the clip")
+      expect(r).toContain("with natural unhurried timing")
+      expect(r).not.toContain("lasting approximately")
+    })
+  }
+
+  it("compact match cut reads term + position + intensity only", () => {
+    expect(
+      composeTransitionHintFromConnections(
+        "match-cut", [], [], { position: "middle", duration: "short", intensity: "natural" }, "compact",
+      ),
+    ).toBe("match cut, the transition occurs in the middle of the clip, with natural unhurried timing")
+  })
+
+  it("a non-instant row keeps its duration", () => {
+    const r = composeTransitionHintFromConnections("cross-dissolve", [], [], { duration: "short" })
+    expect(r).toContain("lasting approximately 1 second")
+  })
+
+  it("a mixed pick keeps its duration — the non-cut still has a length", () => {
+    const r = composeTransitionHintFromConnections(["match-cut", "ink-splash"], [], [], { duration: "short" })
+    expect(r).toContain("lasting approximately 1 second")
+  })
+
+  it("a no-op 'auto' beside a cut does not make the pick non-instant", () => {
+    const r = composeTransitionHintFromConnections(["auto", "smash-cut"], [], [], { duration: "long" })
+    expect(r).not.toContain("lasting approximately")
+  })
+})
+
+describe("instant transitions — on the wire catalog", () => {
+  it("the transition picker options carry instant: true on exactly the cut rows", () => {
+    const options = getPickerCatalog("transition")?.options ?? []
+    expect(options.length).toBe(TRANSITIONS.length)
+    expect(options.filter((o) => o.instant === true).map((o) => o.id).sort()).toEqual([...INSTANT_IDS].sort())
+    // Absent (not `false`) everywhere else, so a non-transition catalog's shape is unchanged.
+    for (const o of options) if (!INSTANT_IDS.includes(o.id)) expect(o).not.toHaveProperty("instant")
+  })
+
+  it("no other catalog grows the field", () => {
+    const camera = getPickerCatalog("camera-motion")?.options ?? []
+    expect(camera.length).toBeGreaterThan(0)
+    for (const o of camera) expect(o).not.toHaveProperty("instant")
+  })
+})

package/src/ad-creative-analysis.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-ad creative analysis — the "expert competitor ad analyst" pass the
+ * social scraper nodes (Meta Ads first; TikTok / Instagram / LinkedIn next)
+ * can run on every ad they return. Node-agnostic on purpose: the input is
+ * "one creative + its copy + a little context", never a Meta-shaped ad.
+ *
+ * The model answers in a fixed JSON shape (the schema lives with the backend
+ * call site); this file owns the WORDS — what each field means and how to
+ * judge it — so the prompt can be tuned without touching the wire contract.
+ */
+
+/** The fields the analysis returns, in the order a reader wants them. */
+export const AD_CREATIVE_ANALYSIS_FIELDS = [
+  "assetType",
+  "format",
+  "visualHooks",
+  "audiences",
+  "graphicIdentity",
+  "copywritingHooks",
+  "usps",
+  "cta",
+  "summary",
+] as const
+export type AdCreativeAnalysisField = (typeof AD_CREATIVE_ANALYSIS_FIELDS)[number]
+
+export const AD_CREATIVE_ANALYSIS_SYSTEM_PROMPT = `You are an expert competitor ad analyst. You look at a competitor's ad — its creative (image or video poster frame) and its copy — and extract the relevant ad information into a structured summary a marketing team can act on.
+
+Judge from what is actually in the creative and copy; never invent claims that are not visible or written. Be concrete and specific (name the objects, colors, people, layouts, words), not generic ("eye-catching visuals"). Write in the language of the ad copy when it is not English, otherwise in English.
+
+Fill every field:
+- assetType: "static" (a still image), "motion" (a video — you see its poster frame), "carousel" (several creatives in one ad), or "unknown".
+- format: the placement the creative is built for — e.g. "in-feed", "story / reel (9:16)", "square feed", "banner / web", judged from its shape and framing.
+- visualHooks: the key visuals and visual angles used to stop the scroll (product close-up, before/after, face + eye contact, big number, screenshot, meme style, UGC selfie, text-on-image…). 2–6 short items.
+- audiences: who the ad represents or addresses (age band, gender, life situation, profession, interest, geography, pain point). 1–5 short items.
+- graphicIdentity: the graphic components — color palette, typography style, logo placement, layout system, illustration vs photo, brand consistency cues. One or two sentences.
+- copywritingHooks: the copywriting angles used in the visual text and in the body (curiosity, urgency, social proof, question, offer, fear of missing out, authority, humor…). 1–6 short items, each naming the angle and quoting or paraphrasing the line that carries it.
+- usps: the unique selling points the ad claims (price, speed, exclusivity, guarantee, results, features). 1–5 short items.
+- cta: the call to action — the button label and/or the closing line that tells the viewer what to do.
+- summary: two to four sentences: what the ad sells, to whom, with what hook, and why it likely works (or does not).`
+
+/**
+ * The organic-content twin of the ad prompt — for scraped social POSTS
+ * (Instagram / TikTok / LinkedIn), not paid ads. SAME output fields (so one
+ * schema and one UI serve both), read for organic content: hooks, audience,
+ * the value/benefit the post conveys (`usps`), and its ask (`cta` — "link in
+ * bio", "follow", a comment prompt, or none).
+ */
+export const POST_CONTENT_ANALYSIS_SYSTEM_PROMPT = `You are an expert social-media content analyst. You look at a single organic post — its creative (image or video cover frame) and its caption — and extract what a marketing team can learn from it into a structured summary.
+
+Judge from what is actually in the creative and caption; never invent claims that are not visible or written. Be concrete and specific (name the objects, colors, people, layouts, words), not generic ("engaging content"). Write in the language of the caption when it is not English, otherwise in English.
+
+Fill every field:
+- assetType: "static" (a still image), "motion" (a video / reel — you see its cover frame), "carousel" (a multi-image post), or "unknown".
+- format: the format the post is built for — e.g. "reel (9:16)", "square feed photo", "carousel", "portrait (4:5)", judged from its shape and framing.
+- visualHooks: the key visuals and visual angles used to stop the scroll (product close-up, before/after, face + eye contact, big text overlay, meme style, UGC selfie, trend/format…). 2–6 short items.
+- audiences: who the post represents or speaks to (age band, gender, life situation, profession, interest, geography, community). 1–5 short items.
+- graphicIdentity: the graphic components — color palette, typography style, logo / handle placement, layout, illustration vs photo, brand consistency cues. One or two sentences.
+- copywritingHooks: the caption / content angles (curiosity, storytelling, question, trend, humor, social proof, education, behind-the-scenes…). 1–6 short items, each naming the angle and quoting or paraphrasing the line that carries it.
+- usps: the value or benefit the post conveys to the viewer (entertainment, education, inspiration, a product benefit, a deal). 1–5 short items.
+- cta: the ask — the caption's call to action ("link in bio", "shop now", "follow", "comment below"), or "none" if the post makes none.
+- summary: two to four sentences: what the post is about, who it speaks to, with what hook, and why it likely performs (or does not).`
+
+export interface AdCreativeAnalysisInput {
+  /** Who is advertising (the Page / account name). */
+  readonly advertiser?: string
+  readonly headline?: string
+  readonly body?: string
+  readonly ctaLabel?: string
+  /** Where the ad points (the landing domain is enough). */
+  readonly landing?: string
+  /** Placements the ad ran on (Facebook, Instagram, TikTok…). */
+  readonly platforms?: readonly string[]
+  /** Creative shape already classified by the caller ("vertical", "square", "horizontal"). */
+  readonly creativeFormat?: string
+  /** "1 video, 2 images" — what the ad carries beyond the one frame the model sees. */
+  readonly mediaSummary?: string
+  /** The user's optional focus ("we sell running shoes — compare against our positioning"). */
+  readonly focus?: string
+}
+
+/**
+ * The user turn's text. The creative itself travels as a separate image
+ * block; this is everything else the analyst should know, one labelled
+ * line per fact, blanks left out.
+ */
+export function buildAdCreativeAnalysisUserText(input: AdCreativeAnalysisInput): string {
+  const lines: string[] = []
+  if (input.advertiser) lines.push(`Account / advertiser: ${input.advertiser}`)
+  if (input.headline) lines.push(`Headline: ${input.headline}`)
+  if (input.body) lines.push(`Body copy:\n${input.body}`)
+  if (input.ctaLabel) lines.push(`CTA button: ${input.ctaLabel}`)
+  if (input.landing) lines.push(`Landing: ${input.landing}`)
+  if (input.platforms && input.platforms.length > 0) lines.push(`Placements: ${input.platforms.join(", ")}`)
+  if (input.creativeFormat) lines.push(`Creative shape: ${input.creativeFormat}`)
+  if (input.mediaSummary) lines.push(`Media: ${input.mediaSummary}`)
+  lines.push("The attached image is the ad's creative (for a video, its poster frame).")
+  if (input.focus) lines.push(`\nAnalyst focus from the user: ${input.focus}`)
+  return lines.join("\n")
+}

package/src/catalog-packs.ts

@@ -125,8 +125,13 @@ function applyExtend(c: PickerCatalog, pack: CatalogPack): PickerCatalog {
 
 function applyDeny(c: PickerCatalog, denyIds: readonly string[]): PickerCatalog {
   const deny = new Set(denyIds)
-  if (c.kind === "single") return { ...c, options: (c.options ?? []).filter((o) => !deny.has(o.id)) }
-  return { ...c, dimensions: (c.dimensions ?? []).map((d) => ({ ...d, options: d.options.filter((o) => !deny.has(o.id)) })) }
+  // Single-value catalogs can also declare auxiliary dimensions (e.g.
+  // transition duration or motion speed). Those are curated too.
+  return {
+    ...c,
+    options: c.options?.filter((o) => !deny.has(o.id)),
+    dimensions: c.dimensions?.map((d) => ({ ...d, options: d.options.filter((o) => !deny.has(o.id)) })),
+  }
 }
 
 export function composePickerCatalogs(
@@ -145,6 +150,12 @@ export function composePickerCatalogs(
       else if (pack.mode === "extend") out = applyExtend(out, pack)
       else if (pack.mode === "deny") out = applyDeny(out, pack.denyIds ?? [])
     }
+    if (activePacks.some((p) => p.catalogId === c.catalogId) && out.defaultValue) {
+      const options = [...(out.options ?? []), ...(out.dimensions ?? []).flatMap((d) => d.options)]
+      if (!options.some((o) => o.id === out.defaultValue)) {
+        out = { ...out, defaultValue: out.options?.[0]?.id }
+      }
+    }
     return out
   })
 }