@nodaro/shared 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,14 +39,13 @@
   },
   "dependencies": {
     "fast-json-patch": "^3.1.1",
-    "zod": "^3.24.2"
+    "zod": "^4.4.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.2",
     "tsup": "^8.5.0",
     "typescript": "^5.7.3",
-    "vitest": "^4.1.2",
-    "zod-to-json-schema": "^3.25.2"
+    "vitest": "^4.1.2"
   },
   "engines": {
     "node": ">=22"

package/src/__tests__/character-mention-slug.test.ts

@@ -136,12 +136,53 @@ describe("parseCharacterMentionToken", () => {
     })
   })
 
-  it("4-part: @kira:1:smile:invalid — invalid mode rejects the entire token", () => {
-    expect(parseCharacterMentionToken("@kira:1:smile:invalid")).toBeNull()
+  // Variant + Role Separation: the 4th segment is no longer mode-only. A
+  // non-mode slug parses as a per-mention ROLE (curated or custom) that
+  // COEXISTS with the variant — the variant picks the image, the role picks
+  // the phrase. The `role` key is OMITTED (not null) for every other shape so
+  // pre-existing parses stay byte-identical.
+  it("4-part: @kira:1:walking:clothes — variant + non-mode ROLE coexist", () => {
+    expect(parseCharacterMentionToken("@kira:1:walking:clothes")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: "walking",
+      usageMode: null,
+      role: "clothes",
+    })
+  })
+
+  it("4-part: @kira:1:smile:invalid — a custom 4th-segment slug parses as a role (was rejected)", () => {
+    expect(parseCharacterMentionToken("@kira:1:smile:invalid")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: "smile",
+      usageMode: null,
+      role: "invalid",
+    })
+  })
+
+  it("4-part role + lock sentinel compose: @kira:1:walking:clothes~lock", () => {
+    expect(parseCharacterMentionToken("@kira:1:walking:clothes~lock")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: "walking",
+      usageMode: null,
+      role: "clothes",
+      lock: true,
+    })
+  })
+
+  it("4-part mode still routes to usageMode, NOT role (back-compat)", () => {
+    const parsed = parseCharacterMentionToken("@kira:1:smile:face")
+    expect(parsed?.usageMode).toBe("face")
+    expect(parsed && "role" in parsed).toBe(false)
   })
 
-  it("4-part: @kira:1:smile:smile — variant-shaped 4th segment still rejects (must be a mode)", () => {
-    expect(parseCharacterMentionToken("@kira:1:smile:smile")).toBeNull()
+  it("findCharacterMentionTokens surfaces the 4-part role token", () => {
+    const tokens = findCharacterMentionTokens("a shot of @kira:1:walking:clothes at dawn", ["kira"])
+    expect(tokens).toHaveLength(1)
+    expect(tokens[0].variantSlug).toBe("walking")
+    expect(tokens[0].role).toBe("clothes")
   })
 
   it("rejects 5-part tokens", () => {
@@ -191,9 +232,13 @@ describe("findCharacterMentionTokens", () => {
   it("does not parse a dash-form as a variant token", () => {
     expect(findCharacterMentionTokens("@kira-smile waves", ["kira"])).toEqual([])
   })
-  it("4-part with invalid mode is dropped (matches regex but parser rejects)", () => {
-    // The regex matches structurally but `parseCharacterMentionToken` rejects
-    // the 4th segment as an invalid mode, so the token is filtered out.
-    expect(findCharacterMentionTokens("@kira:1:smile:bogus waves", ["kira"])).toEqual([])
+  it("4-part with a non-mode 4th segment parses as variant + ROLE (Variant + Role Separation)", () => {
+    // Previously this was rejected outright; now the non-mode segment is a
+    // per-mention role coexisting with the variant.
+    const tokens = findCharacterMentionTokens("@kira:1:smile:bogus waves", ["kira"])
+    expect(tokens).toHaveLength(1)
+    expect(tokens[0].variantSlug).toBe("smile")
+    expect(tokens[0].role).toBe("bogus")
+    expect(tokens[0].usageMode).toBeNull()
   })
 })

package/src/__tests__/character-picker-display-order.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest"
+import {
+  CHARACTER_PICKER_DISPLAY_ORDER,
+  characterBucketDisplayRank,
+  characterMentionableAssetArrays,
+  sortCharacterEntriesForDisplay,
+} from "../character-variant-assets"
+import { CHARACTER_ATTACH_COLUMNS } from "../entity-asset-types"
+
+describe("CHARACTER_PICKER_DISPLAY_ORDER", () => {
+  it("covers exactly the keys of characterMentionableAssetArrays (drift guard)", () => {
+    // If a new bucket is added to the data record without a display rank (or
+    // vice versa), pickers would silently drop/misplace it. Fail loudly here.
+    const dataKeys = Object.keys(characterMentionableAssetArrays({})).sort()
+    const displayKeys = [...CHARACTER_PICKER_DISPLAY_ORDER].sort()
+    expect(displayKeys).toEqual(dataKeys)
+  })
+
+  it("pins boards first, sheets second", () => {
+    expect(CHARACTER_PICKER_DISPLAY_ORDER[0]).toBe("boards")
+    expect(CHARACTER_PICKER_DISPLAY_ORDER[1]).toBe("sheets")
+  })
+})
+
+describe("characterBucketDisplayRank", () => {
+  it("ranks canonical (no bucket) before boards, boards before variant buckets", () => {
+    expect(characterBucketDisplayRank(undefined)).toBeLessThan(characterBucketDisplayRank("boards"))
+    expect(characterBucketDisplayRank("boards")).toBeLessThan(characterBucketDisplayRank("expressions"))
+  })
+
+  it("puts unknown buckets last", () => {
+    expect(characterBucketDisplayRank("someFutureBucket")).toBeGreaterThan(
+      characterBucketDisplayRank("detailCloseups"),
+    )
+  })
+})
+
+describe("sortCharacterEntriesForDisplay", () => {
+  it("reorders within a character run (boards first) and keeps non-character items in place", () => {
+    const items = [
+      { characterSlug: undefined, url: "upload1" },
+      { characterSlug: "kira", bucket: undefined, url: "canonical" },
+      { characterSlug: "kira", bucket: "expressions", url: "smile" },
+      { characterSlug: "kira", bucket: "boards", url: "board1" },
+      { characterSlug: undefined, url: "upload2" },
+      { characterSlug: "bob", bucket: "poses", url: "bobpose" },
+      { characterSlug: "bob", bucket: "boards", url: "bobboard" },
+    ]
+    const sorted = sortCharacterEntriesForDisplay(items)
+    expect(sorted.map((i) => i.url)).toEqual([
+      "upload1", "canonical", "board1", "smile", "upload2", "bobboard", "bobpose",
+    ])
+  })
+
+  it("is stable within the same bucket", () => {
+    const items = [
+      { characterSlug: "kira", bucket: "boards", url: "b1" },
+      { characterSlug: "kira", bucket: "boards", url: "b2" },
+    ]
+    expect(sortCharacterEntriesForDisplay(items).map((i) => i.url)).toEqual(["b1", "b2"])
+  })
+})
+
+describe("CHARACTER_ATTACH_COLUMNS", () => {
+  it("includes boards (worker auto-attach whitelist, mirrors migration 250)", () => {
+    expect(CHARACTER_ATTACH_COLUMNS).toContain("boards")
+  })
+})

package/src/__tests__/entity-image-handle.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest"
-import { resolveEffectiveSourceType, ENTITY_IMAGE_HANDLE_TYPES } from "../entity-image-handle.js"
+import { resolveEffectiveSourceType, ENTITY_IMAGE_HANDLE_TYPES, sourceRefKey } from "../entity-image-handle.js"
 
 const ENTITY_REF_HANDLE: Record<string, string> = {
   character: "characterRef",
@@ -41,3 +41,24 @@ describe("resolveEffectiveSourceType (entity image handle → upload-image)", ()
     )
   })
 })
+
+describe("sourceRefKey (handle-scoped ref key — prevents node-id collision)", () => {
+  it("scopes an entity's image handle to `${id}::image`", () => {
+    for (const entity of ENTITY_IMAGE_HANDLE_TYPES) {
+      expect(sourceRefKey("n1", "image", entity)).toBe("n1::image")
+    }
+  })
+
+  it("keeps the bare node id for the identity handle so the two refs stay distinct", () => {
+    expect(sourceRefKey("n1", "characterRef", "character")).toBe("n1")
+    // Identity vs image handle of the SAME node → distinct keys (the fix).
+    expect(sourceRefKey("n1", "characterRef", "character"))
+      .not.toBe(sourceRefKey("n1", "image", "character"))
+  })
+
+  it("leaves non-entity image producers and the no-handle case on the bare node id", () => {
+    expect(sourceRefKey("n1", "image", "generate-image")).toBe("n1")
+    expect(sourceRefKey("n1", "image", "upload-image")).toBe("n1")
+    expect(sourceRefKey("n1", undefined, "character")).toBe("n1")
+  })
+})

package/src/__tests__/location-mention-slug.test.ts

@@ -89,10 +89,39 @@ describe("parseLocationMentionToken", () => {
       expect(parseLocationMentionToken("@oldlibrary:1:weather:style")).toBeNull()
     })
 
-    it("returns null for 4-part with unknown 4th-segment mode", () => {
+    it("4-part with a non-mode 4th segment parses as bucket/variant + ROLE (Variant + Role Separation)", () => {
+      // Previously rejected; now the non-mode segment is a per-mention role
+      // that coexists with the variant — the variant picks the image, the
+      // role picks the phrase.
       expect(
-        parseLocationMentionToken("@oldlibrary:1:weather/rain:face"),
-      ).toBeNull()
+        parseLocationMentionToken("@oldlibrary:1:weather/rain:lighting"),
+      ).toEqual({
+        locationSlug: "oldlibrary",
+        imageIndex: 1,
+        bucket: "weather",
+        variant: "rain",
+        usageMode: null,
+        role: "lighting",
+      })
+    })
+
+    it("4-part custom role slug coexists with the variant", () => {
+      expect(
+        parseLocationMentionToken("@oldlibrary:1:weather/rain:cozy-corner"),
+      ).toEqual({
+        locationSlug: "oldlibrary",
+        imageIndex: 1,
+        bucket: "weather",
+        variant: "rain",
+        usageMode: null,
+        role: "cozy-corner",
+      })
+    })
+
+    it("4-part MODE still routes to usageMode, not role (back-compat)", () => {
+      const parsed = parseLocationMentionToken("@oldlibrary:1:weather/rain:style")
+      expect(parsed?.usageMode).toBe("style")
+      expect(parsed && "role" in parsed).toBe(false)
     })
 
     it("3-part with a bare non-mode slug parses as a custom ROLE (parser gate removed, F2)", () => {

package/src/__tests__/pipeline-chat.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest"
-import { default as zodToJsonSchema } from "zod-to-json-schema"
+import { z } from "zod"
 import { ChatTurnResponseSchema, STAGE_PATCH_SCHEMA } from "../pipeline-chat.js"
 import { PIPELINE_STAGE_NAMES } from "../pipeline-events.js"
 
@@ -61,7 +61,7 @@ describe("ChatTurnResponseSchema", () => {
   })
 
   it("produces JSON Schema with root type:object (Anthropic-valid)", () => {
-    const js = zodToJsonSchema(ChatTurnResponseSchema, { target: "jsonSchema7" })
+    const js = z.toJSONSchema(ChatTurnResponseSchema, { target: "draft-7", unrepresentable: "any", io: "input" })
     expect((js as { type?: string }).type).toBe("object")
   })
 

package/src/__tests__/reference-roles.test.ts

@@ -8,10 +8,19 @@ describe("reference-roles registry", () => {
     for (const source of Object.keys(DEFAULT_LABEL_BY_SOURCE) as Array<keyof typeof DEFAULT_LABEL_BY_SOURCE>) {
       const presets = REFERENCE_ROLE_PRESETS[source]
       expect(presets, source).toBeTruthy()
-      expect(presets, source).toContain(defaultRoleForSource(source))
+      const def = defaultRoleForSource(source)
+      // Media sources (manual / wired-image) default to ref-only = the empty
+      // label (a bare {image:N} token). Empty is not a preset role.
+      if (def === "") continue
+      expect(presets, source).toContain(def)
     }
   })
 
+  it("media sources default to ref-only (empty label)", () => {
+    expect(DEFAULT_LABEL_BY_SOURCE["manual"]).toBe("")
+    expect(DEFAULT_LABEL_BY_SOURCE["wired-image"]).toBe("")
+  })
+
   it("defaultRoleForSource mirrors DEFAULT_LABEL_BY_SOURCE", () => {
     expect(defaultRoleForSource("wired-character")).toBe("person")
     expect(defaultRoleForSource("wired-location")).toBe("background")
@@ -34,3 +43,14 @@ describe("reference-roles registry", () => {
     expect(roleToPhrase("hoodie", "reference image B")).toBe("the hoodie from reference image B")
   })
 })
+
+describe("ref-only role", () => {
+  it("renders as the bare binding (no descriptive phrase)", () => {
+    expect(roleToPhrase("ref-only", "reference image A")).toBe("reference image A")
+    expect(roleToPhrase("ref-only", "@image_3")).toBe("@image_3")
+  })
+  it("is a curated preset for character and location (honored by the preset-gated resolvers)", () => {
+    expect(REFERENCE_ROLE_PRESETS["wired-character"]).toContain("ref-only")
+    expect(REFERENCE_ROLE_PRESETS["wired-location"]).toContain("ref-only")
+  })
+})

package/src/character-mention-slug.ts

@@ -31,6 +31,16 @@ export interface CharacterMentionTokenInfo {
    * other 4-part token.
    */
   readonly usageMode: UsageMode | null
+  /**
+   * Per-mention ROLE from a NON-MODE 4th segment (Variant + Role Separation) —
+   * coexists with a real variant: the variant picks the IMAGE, the role picks
+   * the PHRASE (`@kira:1:walking:clothes` → walking image, "the clothes from
+   * …"). Curated or custom slug, stored verbatim. OMITTED (undefined, not
+   * null) for every other shape — 2/3-part tokens and mode-bearing 4-part
+   * tokens keep their pre-existing parse byte-identically. Mirrors
+   * `LocationMentionTokenInfo.role`.
+   */
+  readonly role?: string
   /**
    * Additive per-mention identity-lock sentinel (Unified Reference Roles,
    * Task 4 + F4). Tri-state: `true` (trailing `~lock`, force lock ON) |
@@ -55,9 +65,11 @@ export interface CharacterMentionTokenInfo {
  *  - `@kira:1:smile`        → variant smile, default mode
  *  - `@kira:1:face`         → canonical, mode "face"  (mode is detected by
  *                              checking the 3rd segment against `USAGE_MODES`)
- *  - `@kira:1:smile:face`   → variant smile, mode "face"
- *  - `@kira:1:smile:bogus`  → null (4-part rejected when last segment is not
- *                              a valid usage mode — keeps the format strict)
+ *  - `@kira:1:smile:face`    → variant smile, mode "face"
+ *  - `@kira:1:walking:clothes` → variant walking, ROLE "clothes" (Variant +
+ *                              Role Separation: a non-mode 4th segment is a
+ *                              per-mention role — curated or custom — that
+ *                              coexists with the variant)
  *
  * Format change: as of the index-in-slug update, the index segment is required.
  * Bare `@kira` is not a mention; the autocomplete always inserts at least
@@ -71,7 +83,7 @@ export interface CharacterMentionTokenInfo {
 export function parseCharacterMentionToken(
   text: string,
   _knownCharacterSlugs?: readonly string[],
-): { characterSlug: string; imageIndex: number; variantSlug: string | null; usageMode: UsageMode | null; lock?: boolean } | null {
+): { characterSlug: string; imageIndex: number; variantSlug: string | null; usageMode: UsageMode | null; role?: string; lock?: boolean } | null {
   if (!text.startsWith("@")) return null
   let rest = text.slice(1)
   if (rest.length === 0 || !/^[a-z]/.test(rest)) return null
@@ -123,13 +135,19 @@ export function parseCharacterMentionToken(
     return { characterSlug, imageIndex, variantSlug: third, usageMode: null, ...lockField }
   }
 
-  // 4-part: kira:1:smile:mode — variant + mode override. Both segments must
-  // satisfy their respective shape; an unknown mode kills the token entirely
-  // (callers fall back to literal text, matching unknown-character behavior).
+  // 4-part: kira:1:variant:X — variant + a 4th segment that is EITHER a
+  // usage-mode override (today's shape, routed to `usageMode` byte-identically)
+  // OR — Variant + Role Separation — any other slug, parsed as a per-mention
+  // ROLE that coexists with the variant (the variant picks the image, the role
+  // picks the phrase). The `role` key is emitted ONLY on the non-mode branch so
+  // mode-bearing tokens keep their exact pre-existing shape.
   if (parts.length === 4) {
     if (!/^[a-z][a-z0-9-]*$/.test(third)) return null
-    if (!isUsageMode(fourth)) return null
-    return { characterSlug, imageIndex, variantSlug: third, usageMode: fourth, ...lockField }
+    if (!/^[a-z][a-z0-9-]*$/.test(fourth)) return null
+    if (isUsageMode(fourth)) {
+      return { characterSlug, imageIndex, variantSlug: third, usageMode: fourth, ...lockField }
+    }
+    return { characterSlug, imageIndex, variantSlug: third, usageMode: null, role: fourth, ...lockField }
   }
 
   return null

package/src/character-variant-assets.ts

@@ -119,3 +119,64 @@ export function characterMentionableAssetArrays(
     boards: characterBoardItems(data),
   }
 }
+
+/**
+ * DISPLAY order for character asset groups in picker menus (swap-picker,
+ * `@` autocomplete) — boards first (the highest-value identity reference),
+ * then sheets, then the variant buckets in data order.
+ *
+ * DISPLAY ONLY. The data-record key order of
+ * {@link characterMentionableAssetArrays} is payload-numbering-bearing
+ * (`{image:N}` / `@name:N` are positional) and MUST NOT change; menus sort
+ * their rendered rows by this rank instead. The guard test asserts this
+ * list's key set stays identical to the data record's.
+ */
+export const CHARACTER_PICKER_DISPLAY_ORDER: readonly string[] = [
+  "boards",
+  "sheets",
+  ...CHARACTER_VARIANT_ASSET_BUCKETS,
+]
+
+/**
+ * Display rank for a character entry's asset bucket. Canonical entries
+ * (no bucket — the portrait row) lead, then buckets per
+ * {@link CHARACTER_PICKER_DISPLAY_ORDER}; unknown buckets sink to the end.
+ */
+export function characterBucketDisplayRank(bucket: string | undefined): number {
+  if (bucket === undefined) return -1
+  const i = CHARACTER_PICKER_DISPLAY_ORDER.indexOf(bucket)
+  return i === -1 ? CHARACTER_PICKER_DISPLAY_ORDER.length : i
+}
+
+/**
+ * Sort picker entries for display: within each CONTIGUOUS run of entries
+ * sharing a `characterSlug`, order by {@link characterBucketDisplayRank}
+ * (stable within a rank); entries without a slug — and run boundaries —
+ * stay exactly where they are. Runs (not a global sort) because the flat
+ * reference list interleaves characters with uploads/wired images whose
+ * positions are meaningful.
+ */
+export function sortCharacterEntriesForDisplay<
+  T extends { readonly characterSlug?: string; readonly bucket?: string },
+>(items: readonly T[]): T[] {
+  const out: T[] = []
+  let i = 0
+  while (i < items.length) {
+    const slug = items[i].characterSlug
+    if (!slug) {
+      out.push(items[i])
+      i++
+      continue
+    }
+    let j = i
+    while (j < items.length && items[j].characterSlug === slug) j++
+    const run = items.slice(i, j)
+    const ranked = run
+      .map((it, k) => ({ it, k, r: characterBucketDisplayRank(it.bucket) }))
+      .sort((a, b) => a.r - b.r || a.k - b.k)
+      .map((x) => x.it)
+    out.push(...ranked)
+    i = j
+  }
+  return out
+}

package/src/entity-asset-types.ts

@@ -68,6 +68,9 @@ export const CHARACTER_ATTACH_COLUMNS = [
   "sheets",
   "detail_closeups",
   "outfit_variations",
+  // Named composite reference boards (migration 250) — identity-collage
+  // sheets auto-attached by the ffmpeg image-collage worker.
+  "boards",
 ] as const
 export type CharacterAttachColumn = (typeof CHARACTER_ATTACH_COLUMNS)[number]
 

package/src/entity-image-handle.ts

@@ -34,3 +34,25 @@ export function resolveEffectiveSourceType(
   }
   return rawSourceType ?? ""
 }
+
+/**
+ * The ref-assembly map key (and `ConnectedReference.id`) for a wired source.
+ *
+ * An entity's `image` handle emits a plain image that is DISTINCT from the
+ * entity's identity `*Ref` handle, yet both edges carry the SAME source node
+ * id. Every ref-assembly map that keyed by the bare node id therefore had the
+ * two edges collide — silently dropping one (identity → a literal `@abi:N`
+ * token + lost character, or the plain image → missing from the picker),
+ * non-deterministically by edge order. Scoping the entity-`image`-handle ref to
+ * `${nodeId}::image` keeps the two refs distinct so BOTH survive. Every other
+ * (type, handle) keeps the bare node id, so nothing else changes.
+ */
+export function sourceRefKey(
+  nodeId: string,
+  sourceHandleId: string | undefined | null,
+  rawSourceType: string | undefined | null,
+): string {
+  return sourceHandleId === "image" && ENTITY_IMAGE_HANDLE_TYPES.has(rawSourceType ?? "")
+    ? `${nodeId}::image`
+    : nodeId
+}

package/src/index.ts

@@ -706,6 +706,9 @@ export {
   characterSheetRefItems,
   characterBoardItems,
   characterMentionableAssetArrays,
+  CHARACTER_PICKER_DISPLAY_ORDER,
+  characterBucketDisplayRank,
+  sortCharacterEntriesForDisplay,
 } from "./character-variant-assets.js"
 export type {
   CharacterVariantAssetBucket,

package/src/location-mention-slug.ts

@@ -107,11 +107,13 @@ export interface LocationMentionTokenInfo {
   readonly usageMode: LocationUsageMode | null
   /** Bare-slug ROLE (Unified Reference Roles, Phase D + F2) — any slash-less,
    *  non-mode 3rd segment (`background`, `empty-background`, `as-is`, … or a
-   *  CUSTOM slug), stored verbatim in slug form. Absent (undefined) for canonical /
-   *  bucket-variant / mode tokens. The hybrid resolver + role pill map it back to
-   *  the phrase key via `normalizeRoleSlug` (custom slugs pass through). Optional so
-   *  canonical/variant/mode tokens stay shape-identical to the pre-Phase-D parser
-   *  output. */
+   *  CUSTOM slug), stored verbatim in slug form — OR (Variant + Role
+   *  Separation) a non-mode 4th segment coexisting with a bucket/variant
+   *  (`@lib:1:weather/rain:lighting` → rain image, lighting phrase). Absent
+   *  (undefined) for canonical / bare-variant / mode tokens. The hybrid
+   *  resolver + role pill map it back to the phrase key via `normalizeRoleSlug`
+   *  (custom slugs pass through). Optional so those tokens stay
+   *  shape-identical to the pre-Phase-D parser output. */
   readonly role?: string
   /**
    * Additive per-mention identity-lock sentinel (Unified Reference Roles,
@@ -235,7 +237,11 @@ export function parseLocationMentionToken(
     }
   }
 
-  // 4-part: @oldlibrary:1:bucket/variant:mode.
+  // 4-part: @oldlibrary:1:bucket/variant:X — X is EITHER a mode override
+  // (today's shape, byte-identical) OR — Variant + Role Separation — any other
+  // slug, parsed as a per-mention ROLE coexisting with the bucket/variant (the
+  // variant picks the image, the role picks the phrase). The `role` key is
+  // emitted only on the non-mode branch, mirroring the character parser.
   if (parts.length === 4) {
     if (!third.includes("/")) return null
     const slashAt = third.indexOf("/")
@@ -243,8 +249,11 @@ export function parseLocationMentionToken(
     const variant = third.slice(slashAt + 1)
     if (!/^[a-z][a-z0-9-]*$/.test(bucket)) return null
     if (!/^[a-z][a-z0-9-]*$/.test(variant)) return null
-    if (!isLocationUsageMode(fourth)) return null
-    return { locationSlug, imageIndex, bucket, variant, usageMode: fourth, ...lockField }
+    if (!/^[a-z][a-z0-9-]*$/.test(fourth)) return null
+    if (isLocationUsageMode(fourth)) {
+      return { locationSlug, imageIndex, bucket, variant, usageMode: fourth, ...lockField }
+    }
+    return { locationSlug, imageIndex, bucket, variant, usageMode: null, role: fourth, ...lockField }
   }
 
   return null

package/src/model-catalog.ts

@@ -187,6 +187,10 @@ const VIDEO_RATIOS_HVS345 = ["16:9", "9:16", "1:1", "4:3", "3:4"] as const
 // (docs.kie.ai/market/bytedance/seedance-2). Kept separate from HVS so the
 // wider set can't leak to models that don't support it.
 const VIDEO_RATIOS_SEEDANCE_2 = ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "adaptive"] as const
+// HappyHorse 1.1 (t2v + ref2v) — the model's full 9-ratio set incl. 4:5/5:4
+// portrait-social and 21:9/9:21 cinematic (docs.kie.ai/market/happyhorse-1-1).
+// Kept separate so the wider set can't leak to models that don't support it.
+const VIDEO_RATIOS_HAPPYHORSE_11 = ["16:9", "9:16", "1:1", "4:3", "3:4", "4:5", "5:4", "21:9", "9:21"] as const
 
 // =============================================================================
 // IMAGE MODELS
@@ -1377,21 +1381,22 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "wan-2.7-t2v", credits: 19, note: "5s 720p default" },
     ],
   },
-  // ── HappyHorse ──
+  // ── HappyHorse (1.1 — ids kept version-less; repointed in place when KIE
+  // delisted 1.0, same param surface, so saved workflows keep working) ──
   "happyhorse": {
     id: "happyhorse",
     kind: "video",
     modes: ["t2v"] as const,
     family: "HappyHorse",
-    label: "HappyHorse",
+    label: "HappyHorse 1.1",
     series: "HappyHorse",
-    description: "HappyHorse text-to-video — 3–15s at 720p/1080p.",
+    description: "HappyHorse 1.1 text-to-video — 3–15s at 720p/1080p, 9 aspect ratios incl. 21:9/9:21, per-second pricing.",
     useCases: ["motion", "creative"],
-    aspectRatios: VIDEO_RATIOS_HVS345,
+    aspectRatios: VIDEO_RATIOS_HAPPYHORSE_11,
     durations: [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
     resolutions: ["720p", "1080p"],
     pricing: [
-      { identifier: "happyhorse", credits: 13, note: "5s 720p default" },
+      { identifier: "happyhorse", credits: 29, note: "5s 720p default — per-second: ~5.7 cr/s @720p, ~7.3 cr/s @1080p" },
     ],
   },
   "happyhorse-i2v": {
@@ -1399,14 +1404,14 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     kind: "video",
     modes: ["i2v"] as const,
     family: "HappyHorse",
-    label: "HappyHorse I2V",
+    label: "HappyHorse 1.1 I2V",
     series: "HappyHorse",
-    description: "HappyHorse image-to-video — 3–15s at 720p/1080p, aspect ratio inferred from input image.",
+    description: "HappyHorse 1.1 image-to-video — 3–15s at 720p/1080p, aspect ratio inferred from input image, per-second pricing.",
     useCases: ["motion", "creative"],
     durations: [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
     resolutions: ["720p", "1080p"],
     pricing: [
-      { identifier: "happyhorse-i2v", credits: 13, note: "5s 720p default" },
+      { identifier: "happyhorse-i2v", credits: 29, note: "5s 720p default — per-second: ~5.7 cr/s @720p, ~7.3 cr/s @1080p" },
     ],
   },
   "happyhorse-ref2v": {
@@ -1414,16 +1419,16 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     kind: "video",
     modes: ["i2v"] as const,
     family: "HappyHorse",
-    label: "HappyHorse Ref2V",
+    label: "HappyHorse 1.1 Ref2V",
     series: "HappyHorse",
-    description: "HappyHorse reference-to-video — 1–9 reference images, 3–15s at 720p/1080p.",
+    description: "HappyHorse 1.1 reference-to-video — 1–9 reference images, 3–15s at 720p/1080p, per-second pricing.",
     useCases: ["motion", "reference"],
-    aspectRatios: VIDEO_RATIOS_HVS345,
+    aspectRatios: VIDEO_RATIOS_HAPPYHORSE_11,
     durations: [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
     resolutions: ["720p", "1080p"],
     features: ["reference-image"],
     pricing: [
-      { identifier: "happyhorse-ref2v", credits: 15, note: "5s 720p default" },
+      { identifier: "happyhorse-ref2v", credits: 29, note: "5s 720p default — per-second: ~5.7 cr/s @720p, ~7.3 cr/s @1080p" },
     ],
   },
   "happyhorse-edit": {
@@ -1437,7 +1442,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     useCases: ["v2v", "restyle"],
     resolutions: ["720p", "1080p"],
     pricing: [
-      { identifier: "happyhorse-edit", credits: 20, note: "720p default" },
+      { identifier: "happyhorse-edit", credits: 35, note: "720p default (5s-equivalent flat rate)" },
     ],
   },
   // ── Bytedance video lite/pro ──