@nodaro/shared 1.4.2 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.4.2",
+  "version": "1.6.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/pipeline-state-types.ts

@@ -148,7 +148,7 @@ export const StageAwaitingSubGateEventSchema = z.object({
   pipelineId: z.string().uuid(),
   stageName: z.enum(["animate_audio_edit", "scene_images"]),
   subGate: SubGateNameSchema,
-  payload: z.record(z.unknown()).optional(),
+  payload: z.record(z.string(), z.unknown()).optional(),
 })
 export type StageAwaitingSubGateEvent = z.infer<typeof StageAwaitingSubGateEventSchema>
 

package/src/reduce-strategy-registry.ts

@@ -1,4 +1,4 @@
-import { z, type ZodType, type ZodTypeDef } from "zod"
+import { z, type ZodType } from "zod"
 // Reuse the canonical `OutputType` from presentation-utils so a single union
 // is the source of truth across the package. Re-exporting it here would
 // collide with the explicit named re-export in `index.ts`.
@@ -13,7 +13,7 @@ export type ReduceStrategy<TConfig = unknown> = {
   readonly label: string
   readonly description: string
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  readonly configSchema: ZodType<TConfig, ZodTypeDef, any>
+  readonly configSchema: ZodType<TConfig, any>
   readonly defaultConfig: TConfig
   readonly outputType: OutputType
   readonly creditCostKey: string

package/src/reference-roles.ts

@@ -9,9 +9,9 @@ import { DEFAULT_LABEL_BY_SOURCE, type ReferenceSource } from "./types.js"
  * value (guarded by reference-roles.test.ts).
  */
 export const REFERENCE_ROLE_PRESETS: Record<ReferenceSource, readonly string[]> = {
-  "wired-character": ["person", "face", "clothes", "hair", "pose", "expression", "style"],
+  "wired-character": ["ref-only", "person", "face", "clothes", "hair", "pose", "expression", "style"],
   "wired-face": ["face", "person", "expression", "style"],
-  "wired-location": ["background", "atmosphere", "as-is", "empty background", "layout", "lighting", "style"],
+  "wired-location": ["ref-only", "background", "atmosphere", "as-is", "empty background", "layout", "lighting", "style"],
   "wired-object": ["object", "shape", "material", "color", "texture", "style"],
   "wired-creature": ["creature", "anatomy", "markings", "pose", "color", "style"],
   "wired-image": ["object", "person", "face", "clothes", "background", "style", "pose", "texture"],
@@ -35,6 +35,10 @@ export function roleToPhrase(role: string, binding: string): string {
   const r = role.trim()
   if (!r) return binding
   switch (r) {
+    case "ref-only":
+      // Bare reference pointer — no descriptive phrase. The label-less/default
+      // state for media refs; an explicit pick for character/location assets.
+      return binding
     case "as-is":
       return `${binding}, used as-is`
     case "empty background":

package/src/scene-node-types.ts

@@ -89,7 +89,7 @@ export const ShotSpecSchema = z.object({
   camera_path_directive: z
     .object({
       path_kind: z.enum(["orbit", "dolly", "crane", "arc", "reveal"]),
-      parameters: z.record(z.unknown()).optional(),
+      parameters: z.record(z.string(), z.unknown()).optional(),
     })
     .optional(),
 

package/src/types.ts

@@ -82,6 +82,13 @@ export interface ConnectedReference {
   readonly characterSlug?: string
   /** Variant slug (e.g. "smile"). undefined = canonical/default. */
   readonly variantSlug?: string
+  /**
+   * Which character asset bucket this entry came from ("boards", "sheets",
+   * "expressions", …); undefined = the canonical portrait entry. DISPLAY
+   * metadata only — menus use it to rank rows (boards first) via
+   * `sortCharacterEntriesForDisplay`; it never affects payload numbering.
+   */
+  readonly bucket?: string
   /** Character's canonical_description. Set on every entry from the same character (used for dedup). */
   readonly characterCanonicalDescription?: string | null
   /**
@@ -205,8 +212,11 @@ export interface ConnectedReference {
 
 /** Default label per source — used by `@` autocomplete and inventory fallback. */
 export const DEFAULT_LABEL_BY_SOURCE: Record<ReferenceSource, string> = {
-  "manual": "object",
-  "wired-image": "object",
+  // Media references default to "ref-only" — the empty label, i.e. a bare
+  // {image:N} token that injects only "reference image A" (image) / "@image_N"
+  // (video) with no descriptive role phrase. Pick a role on the pill to change.
+  "manual": "",
+  "wired-image": "",
   "wired-character": "person",
   "wired-face": "face",
   "wired-object": "object",