@nodaro/prompts 1.0.1 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",

package/src/__tests__/ref-only-references.test.ts

@@ -0,0 +1,63 @@
+// End-to-end coverage for the "ref-only" reference role: a mention or node
+// default of `ref-only` injects ONLY the bare reference pointer — `reference
+// image A` on image nodes, `@image_1` on video nodes — with no "the {role}
+// from …" wrapper. Character is preset-gated (ref-only must be a curated
+// preset); location honors the token role verbatim. Both route through the one
+// `roleToPhrase` chokepoint.
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import { resolveVideoReferenceCore } from "../video-reference-resolver.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const kira = (over: Partial<ConnectedReference> = {}): ConnectedReference => ({
+  id: "k", defaultName: "Kira", source: "wired-character", url: "u-kira", characterSlug: "kira", ...over,
+})
+const library: ConnectedReference = {
+  id: "l", defaultName: "Old Library", source: "wired-location",
+  url: "https://cdn/library.png", locationSlug: "old-library",
+}
+
+describe("ref-only character (image)", () => {
+  it("mention '@kira:1:ref-only' → bare 'reference image A'", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro", prompt: "@kira:1:ref-only in the rain",
+      connectedReferences: [kira()], referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("reference image A in the rain")
+    expect(out.prompt).not.toContain("the person from reference image A")
+  })
+  it("node defaultRole 'ref-only' (unmentioned canonical) → no 'the person from …'", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro", prompt: "a portrait",
+      connectedReferences: [kira({ defaultRole: "ref-only" })], referenceFormat: "hybrid",
+    })
+    expect(out.prompt).not.toContain("the person from reference image A")
+  })
+})
+
+describe("ref-only character (video)", () => {
+  it("mention '@kira:1:ref-only' → bare '@image_1'", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1:ref-only walks in", wiredCharRefs: [kira()], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("@image_1 walks in")
+    expect(out.prompt).not.toContain("the person from @image_1")
+  })
+  it("node defaultRole 'ref-only' (unmentioned canonical) → no 'the person from @image_1'", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a slow dolly", wiredCharRefs: [kira({ defaultRole: "ref-only" })], hybridRoles: true,
+    })
+    expect(out.prompt).not.toContain("the person from @image_1")
+  })
+})
+
+describe("ref-only location (image)", () => {
+  it("mention '@old-library:1:ref-only' → bare 'reference image A'", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro", prompt: "@old-library:1:ref-only at night",
+      connectedReferences: [library], referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("reference image A at night")
+    expect(out.prompt).not.toContain("the background from reference image A")
+  })
+})

package/src/__tests__/variant-role-separation.test.ts

@@ -0,0 +1,92 @@
+// Variant + Role Separation: a mention's VARIANT picks the image, its ROLE
+// picks the phrase — independently (`@kira:1:walking:clothes` → the walking
+// image attached, "the clothes from …" injected). Covers the character
+// resolvers on BOTH bindings (image letters, video @image_N), the location
+// image resolver, ref-only composition, and the mode-in-seg4 back-compat.
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import { resolveVideoReferenceCore } from "../video-reference-resolver.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const kira = (over: Partial<ConnectedReference> = {}): ConnectedReference => ({
+  id: "k", defaultName: "Kira", source: "wired-character", url: "u-kira", characterSlug: "kira", ...over,
+})
+const kiraWalking = kira({ id: "kw", variantSlug: "walking", url: "u-walk" })
+
+const library: ConnectedReference = {
+  id: "l", defaultName: "Old Library", source: "wired-location",
+  url: "u-lib", locationSlug: "oldlibrary",
+}
+const libraryRain: ConnectedReference = {
+  ...library, id: "lr", url: "u-rain",
+  locationVariantBucket: "weather", locationVariantSlug: "rain",
+}
+
+describe("character variant + role (image)", () => {
+  it("@kira:1:walking:clothes → walking image attached, 'the clothes from reference image A'", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro", prompt: "@kira:1:walking:clothes in the rain",
+      connectedReferences: [kira(), kiraWalking], referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the clothes from reference image A in the rain")
+    expect(out.referenceImageUrls).toContain("u-walk")
+  })
+
+  it("@kira:1:walking:ref-only → walking image attached, bare 'reference image A'", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro", prompt: "@kira:1:walking:ref-only in the rain",
+      connectedReferences: [kira(), kiraWalking], referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("reference image A in the rain")
+    expect(out.prompt).not.toContain("from reference image A")
+    expect(out.referenceImageUrls).toContain("u-walk")
+  })
+
+  it("a CUSTOM 4th-segment role survives verbatim", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro", prompt: "@kira:1:walking:earrings at dawn",
+      connectedReferences: [kira(), kiraWalking], referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the earrings from reference image A at dawn")
+  })
+
+  it("back-compat: @kira:1:walking:pose (mode in seg4) is unchanged", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro", prompt: "@kira:1:walking:pose at dawn",
+      connectedReferences: [kira(), kiraWalking], referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the pose from reference image A at dawn")
+    expect(out.referenceImageUrls).toContain("u-walk")
+  })
+})
+
+describe("character variant + role (video)", () => {
+  it("@kira:1:walking:clothes → 'the clothes from @image_1', walking image attached", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1:walking:clothes walks in",
+      wiredCharRefs: [kira(), kiraWalking], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the clothes from @image_1 walks in")
+    expect(out.additionalUrls).toContain("u-walk")
+  })
+
+  it("@kira:1:walking:ref-only → bare '@image_1'", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1:walking:ref-only walks in",
+      wiredCharRefs: [kira(), kiraWalking], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("@image_1 walks in")
+    expect(out.prompt).not.toContain("from @image_1")
+  })
+})
+
+describe("location variant + role (image)", () => {
+  it("@oldlibrary:1:weather/rain:lighting → rain image attached, 'the lighting from reference image A'", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro", prompt: "@oldlibrary:1:weather/rain:lighting a chase",
+      connectedReferences: [library, libraryRain], referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the lighting from reference image A a chase")
+    expect(out.referenceImageUrls).toContain("u-rain")
+  })
+})

package/src/__tests__/video-reference-resolver.test.ts

@@ -156,8 +156,7 @@ describe("REF_BINDING", () => {
 // into `@image_N`-style subject bindings (Task 2.3). Positional, 1-based against
 // the corresponding count. Out-of-range / missing count → drop to the bare label
 // (legacy `stripVideoImageTokens` strip behavior). Label-less in-range token →
-// "the subject in @kind_N" so the binding still lands. Purely additive in 2.3 —
-// defined + exported + tested here, NOT yet called by the core (that is Task 2.4).
+// the bare "@kind_N" (the ref-only default) so the binding lands with no wrapper.
 describe("resolveReferenceTokens", () => {
   const counts = { image: 4, video: 0, audio: 0 }
   it("resolves repeated labels distinctly by slot", () => {
@@ -168,8 +167,10 @@ describe("resolveReferenceTokens", () => {
   it("drops out-of-range tokens to bare label", () => {
     expect(resolveReferenceTokens("a {image:9:ghost} here", counts)).toBe("a ghost here")
   })
-  it("handles a label-less token", () => {
-    expect(resolveReferenceTokens("{image:1}", counts)).toBe("the subject in @image_1")
+  it("resolves a label-less token to the bare kind ordinal (ref-only)", () => {
+    expect(resolveReferenceTokens("{image:1}", counts)).toBe("@image_1")
+    expect(resolveReferenceTokens("{video:1}", { image: 0, video: 1, audio: 0 })).toBe("@video_1")
+    expect(resolveReferenceTokens("{audio:1}", { image: 0, video: 0, audio: 1 })).toBe("@audio_1")
   })
   it("resolves video + audio tokens against their own counts", () => {
     expect(resolveReferenceTokens("dance like {video:1:clip} to {audio:1:song}", { image: 0, video: 1, audio: 1 }))

package/src/picker-analyzer-registry.ts

@@ -188,7 +188,7 @@ export function buildPickerAnalyzerSpec(pickerType: PickerType): PickerAnalyzerS
  *  (multi). `.strict()` blocks unknown keys. Mirrors the field cardinality. */
 export function buildPickerZodSchema(
   spec: PickerAnalyzerSpec,
-): z.ZodType<Record<string, string | string[]>, z.ZodTypeDef, unknown> {
+): z.ZodType<Record<string, string | string[]>, unknown> {
   const shape: Record<string, z.ZodTypeAny> = {}
   for (const d of spec.dimensions) {
     const ids = d.entryIds as unknown as [string, ...string[]]
@@ -196,16 +196,12 @@ export function buildPickerZodSchema(
     shape[d.dimension] = d.limit > 1 ? z.array(enumZ).max(d.limit).optional() : enumZ.optional()
   }
   // dynamic shape → Zod can't infer the narrowed output type; runtime-validated by picker-analyzer-registry.test.ts
-  return z.object(shape).strict() as unknown as z.ZodType<
-    Record<string, string | string[]>,
-    z.ZodTypeDef,
-    unknown
-  >
+  return z.object(shape).strict() as unknown as z.ZodType<Record<string, string | string[]>, unknown>
 }
 
 export interface PickerAnalyzer {
   readonly spec: PickerAnalyzerSpec
-  readonly schema: z.ZodType<Record<string, string | string[]>, z.ZodTypeDef, unknown>
+  readonly schema: z.ZodType<Record<string, string | string[]>, unknown>
   readonly legend: string
 }
 
@@ -265,7 +261,7 @@ export interface PickerGaps {
 }
 
 export interface MultiPickerAnalyzerSpec {
-  readonly schema: z.ZodType<Record<string, unknown>, z.ZodTypeDef, unknown>
+  readonly schema: z.ZodType<Record<string, unknown>, unknown>
   readonly toolName: string
   readonly legend: string
 }

package/src/prompt-builder.ts

@@ -289,6 +289,12 @@ function resolveCharacterMentionsHybrid(
     mentionedCharacterSlugs.add(t.characterSlug)
     refByUrl.set(match.url, match)
     if (t.lock !== undefined) lockOverrideByUrl.set(match.url, t.lock)
+    // Variant + Role Separation: an explicit 4th-segment ROLE
+    // (`@kira:1:walking:clothes`) wins outright and coexists with the variant —
+    // the variant picked the image (variantMatch above), the role picks the
+    // phrase. Used VERBATIM (curated or custom), mirroring the seg3 custom-role
+    // relaxation below.
+    const explicitRole = (t.role ?? "").trim()
     const segment = (t.usageMode ?? t.variantSlug ?? "").trim()
     // Custom roles survive VERBATIM (Unified Reference Roles, Phase D). A
     // non-empty segment is the role when it is a curated preset (face/pose/style
@@ -299,10 +305,11 @@ function resolveCharacterMentionsHybrid(
     // face-pose/emotion/name/none) fall back to the NODE default: the character
     // node's `defaultRole` (hybrid dropdown pick, verbatim) → its
     // `defaultUsageMode`-derived role → the source default ("person") — via
-    // `resolveDefaultRole` (Character Node Role+Lock). Precedence: per-mention
-    // token role → node defaultRole → defaultUsageMode-derived → source default.
-    const role =
-      segment && (presets.includes(segment) || (t.usageMode == null && !variantMatch))
+    // `resolveDefaultRole` (Character Node Role+Lock). Precedence: seg4 role →
+    // seg3 token role → node defaultRole → defaultUsageMode-derived → source default.
+    const role = explicitRole
+      ? explicitRole
+      : segment && (presets.includes(segment) || (t.usageMode == null && !variantMatch))
         ? segment
         : resolveDefaultRole(match.defaultRole, match.defaultUsageMode, "wired-character")
     matched.push({ token: t.token, offset: t.offset, url: match.url, role })

package/src/prompt-wizard-categories.ts

@@ -245,7 +245,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "bytedance-pro": "Higher quality ByteDance",
     "runway-kie": "Runway via KIE, strong cinematic quality",
     "wan-2.7-t2v": "Wan 2.7 T2V — 2–15s, 720p/1080p",
-    "happyhorse":   "HappyHorse T2V — 3–15s, 720p/1080p",
+    "happyhorse":   "HappyHorse 1.1 T2V — 3–15s, 720p/1080p, 9 aspect ratios incl. 21:9/9:21",
     "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.",
@@ -275,8 +275,8 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "grok-i2v": "General purpose animation",
     "runway-kie": "Cinematic image animation",
     "wan-2.7-i2v":    "Wan 2.7 I2V — 2–15s, 720p/1080p, start+end frame",
-    "happyhorse-i2v":  "HappyHorse I2V — 3–15s, 720p/1080p",
-    "happyhorse-ref2v": "HappyHorse Ref2V — multi-ref image to video, 3–15s",
+    "happyhorse-i2v":  "HappyHorse 1.1 I2V — 3–15s, 720p/1080p",
+    "happyhorse-ref2v": "HappyHorse 1.1 Ref2V — multi-ref image to video (1–9 refs), 3–15s",
     "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.",

package/src/video-reference-resolver.ts

@@ -88,8 +88,8 @@ const REFERENCE_TOKEN_RE = /\{(image|video|audio):(\d+)(?::([a-zA-Z0-9_ -]+))?\}
  *     `stripVideoImageTokens` strip behavior: drop the token, keep the label text.
  *   - in range, label present → `REF_BINDING[kind](label, N)`
  *     (e.g. `the person from @image_2`).
- *   - in range, no label → `the subject in @${kind}_${N}` so the binding still
- *     lands even when the author didn't name the subject.
+ *   - in range, no label → the bare `@${kind}_${N}` (the ref-only default): the
+ *     binding lands with no descriptive wrapper.
  *
  * Runs of 2+ HORIZONTAL whitespace (left behind by a dropped label-less token)
  * collapse to one space, the result is trimmed, and an empty result becomes
@@ -115,7 +115,7 @@ export function resolveReferenceTokens(
         const n = parseInt(nStr, 10)
         if (n < 1 || n > counts[kind]) return label ?? ""
         if (label) return REF_BINDING[kind](label, n)
-        return `the subject in @${kind}_${n}`
+        return `@${kind}_${n}`
       })
       // Horizontal whitespace only — preserve `\n` / `\n\n` block separators.
       .replace(/[^\S\r\n]{2,}/g, " ")
@@ -309,6 +309,10 @@ function resolveVideoCharacterMentionsHybrid(
     mentionedCharacterSlugs.add(t.characterSlug)
     refByUrl.set(match.url, match)
     if (t.lock !== undefined) lockOverrideByUrl.set(match.url, t.lock)
+    // Variant + Role Separation: an explicit 4th-segment ROLE
+    // (`@kira:1:walking:clothes`) wins outright and coexists with the variant —
+    // used VERBATIM, in lock-step with the image-side resolver.
+    const explicitRole = (t.role ?? "").trim()
     const segment = (t.usageMode ?? t.variantSlug ?? "").trim()
     // Custom roles survive VERBATIM — the SAME relaxation as the image-side
     // `resolveCharacterMentionsHybrid` (Unified Reference Roles, Phase D), kept
@@ -317,9 +321,11 @@ function resolveVideoCharacterMentionsHybrid(
     // a real variant URL → role; a real variant slug or a directive-only usage
     // mode → the NODE default (`defaultRole` verbatim → `defaultUsageMode`-derived
     // → "person", via `resolveDefaultRole` — Character Node Role+Lock), mirroring
-    // the image-side mention fallback.
-    const role =
-      segment && (presets.includes(segment) || (t.usageMode == null && !variantMatch))
+    // the image-side mention fallback. Precedence: seg4 role → seg3 token role →
+    // node default chain.
+    const role = explicitRole
+      ? explicitRole
+      : segment && (presets.includes(segment) || (t.usageMode == null && !variantMatch))
         ? segment
         : resolveDefaultRole(match.defaultRole, match.defaultUsageMode, "wired-character")
     matched.push({ token: t.token, offset: t.offset, url: match.url, role })