@nodaro/shared 2.10.0 → 2.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.10.0",
+  "version": "2.12.1",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/catalog-projection.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expectTypeOf } from "vitest"
+import type { ProjectedCatalog } from "../catalog-projection.js"
+
+describe("ProjectedCatalog wire shape (Apache boundary)", () => {
+  it("is tag-free and policy-free (the deferred CatalogPolicy never crosses the wire)", () => {
+    // @ts-expect-error — no `tags` field may exist on the projection shape
+    const _t: ProjectedCatalog["tags"] = undefined
+    // @ts-expect-error — no policy field may exist either
+    const _p: ProjectedCatalog["policy"] = undefined
+    void _t
+    void _p
+    expectTypeOf<ProjectedCatalog>().toHaveProperty("catalogId")
+  })
+})

package/src/__tests__/default-video-provider.test.ts

@@ -23,7 +23,7 @@ describe("DEFAULT_VIDEO_PROVIDER", () => {
   })
 
   it("nothing-specified request resolves to the cheapest seeded composite", () => {
-    const sel = applyDefaultVideoSelection({})
+    const sel = applyDefaultVideoSelection<number>({})
     const id = buildVideoCreditModelIdentifier(
       sel.provider, sel.duration, undefined, "image-to-video", undefined, undefined, false,
     )

package/src/__tests__/pack-sidecar-localization.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect, afterEach } from "vitest"
+import { registerCatalogSidecars, resetCatalogSidecars, resolveLabel, entryMatchesQuery } from "../index.js"
+
+afterEach(() => resetCatalogSidecars())
+
+describe("pack sidecars resolve through the shared localizer (G10)", () => {
+  it("resolveLabel returns a pack-registered localized label", () => {
+    // English fallback before registration
+    expect(resolveLabel("person", "attire-x", "Modest Suit", "he")).toBe("Modest Suit")
+    registerCatalogSidecars("person", { he: { "attire-x": { label: "חליפה צנועה" } } })
+    expect(resolveLabel("person", "attire-x", "Modest Suit", "he")).toBe("חליפה צנועה")
+  })
+  it("english locale ignores sidecars", () => {
+    registerCatalogSidecars("person", { he: { "attire-x": { label: "חליפה צנועה" } } })
+    expect(resolveLabel("person", "attire-x", "Modest Suit", "en")).toBe("Modest Suit")
+  })
+  it("search matches the localized pack label", () => {
+    registerCatalogSidecars("person", { he: { "attire-x": { label: "חליפה צנועה" } } })
+    expect(entryMatchesQuery("person", "attire-x", "Modest Suit", "d", "he", "חליפה")).toBe(true)
+  })
+})

package/src/__tests__/parameter-node-value.test.ts

@@ -1,8 +1,9 @@
-import { describe, it, expect } from "vitest"
+import { describe, it, expect, afterEach } from "vitest"
 import {
   PARAMETER_NODE_TYPES,
   getParameterValue,
 } from "../parameter-node-value.js"
+import { setRegisteredPersonPackFields } from "../index.js"
 
 describe("PARAMETER_NODE_TYPES", () => {
   it("includes the existing parameter node types", () => {
@@ -135,3 +136,19 @@ describe("parameter-node-value — furniture", () => {
     expect(getParameterValue({}, "furniture")).toBeUndefined()
   })
 })
+
+describe("getParameterValue person pack-dimension fallback (G4)", () => {
+  afterEach(() => setRegisteredPersonPackFields([]))
+
+  it("returns undefined for an unregistered pack field", () => {
+    expect(getParameterValue({ sectorAttire: "attire-modest-suit" }, "person")).toBeUndefined()
+  })
+  it("resolves a registered pack field when no base dimension is set", () => {
+    setRegisteredPersonPackFields(["sectorAttire"])
+    expect(getParameterValue({ sectorAttire: "attire-modest-suit" }, "person")).toBe("attire-modest-suit")
+  })
+  it("base dimensions still win over pack fields", () => {
+    setRegisteredPersonPackFields(["sectorAttire"])
+    expect(getParameterValue({ type: "man", sectorAttire: "attire-modest-suit" }, "person")).toBe("man")
+  })
+})

package/src/__tests__/resolve-pipeline-model.test.ts

@@ -28,8 +28,8 @@ describe("resolvePipelineModel", () => {
   })
 
   it("returns the global script_llm for the script_llm stage", () => {
-    const config: Partial<PipelineConfig> = { script_llm: "claude-opus-4-6" }
-    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-6")
+    const config: Partial<PipelineConfig> = { script_llm: "claude-opus-4-7" }
+    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-7")
   })
 
   it("per-stage override beats the matching global field", () => {
@@ -52,12 +52,12 @@ describe("resolvePipelineModel", () => {
       stage_models: {
         scene_keyframes_image: "gpt-image",
         shots_video: "veo3",
-        script_llm: "claude-opus-4-6",
+        script_llm: "claude-opus-4-7",
       },
     }
     expect(resolvePipelineModel(config, "scene_keyframes_image")).toBe("gpt-image")
     expect(resolvePipelineModel(config, "shots_video")).toBe("veo3")
-    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-6")
+    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-7")
     // Entity image stages keep the global pick.
     expect(resolvePipelineModel(config, "characters_image")).toBe("flux")
   })

package/src/__tests__/video-analysis-shot-craft.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest"
+import {
+  VIDEO_ANALYSIS_TEXT_KINDS, VIDEO_ANALYSIS_CLIP_TRANSITIONS_IN, VIDEO_ANALYSIS_TRANSITIONS,
+  windowAnalysisSchema, videoAnalysisResultSchema,
+} from "../video-analysis.js"
+
+const scene = { startSec: 0, endSec: 4, label: "hook", shotType: "Wide", camera: "static", visual: "{slot:a} waits", audio: [] }
+const slot = { slotId: "a", label: "A", source: "wired-character", role: "person", description: "d" }
+
+describe("shot-craft fields (keys only)", () => {
+  it("adds a text-kind vocabulary and a clip transition-in vocabulary without widening the transition enum", () => {
+    expect(VIDEO_ANALYSIS_TEXT_KINDS).toEqual(["title", "caption", "lower-third", "subtitle", "logo", "other"])
+    expect(VIDEO_ANALYSIS_CLIP_TRANSITIONS_IN).toEqual(["fade"])
+    expect(VIDEO_ANALYSIS_TRANSITIONS).toEqual(["cut", "fade", "dissolve", "wipe", "whip"])
+  })
+  it("window and result accept transitionIn at the CLIP level and onScreenTextKind on a scene", () => {
+    const w = windowAnalysisSchema.parse({ transitionIn: "fade", slots: [slot], scenes: [{ ...scene, onScreenText: "HELLO", onScreenTextKind: "title", transitionOut: "cut" }] })
+    expect(w.transitionIn).toBe("fade")
+    expect(w.scenes[0]!.onScreenTextKind).toBe("title")
+    const r = videoAnalysisResultSchema.parse({
+      meta: { durationSec: 4, width: 16, height: 9, aspectRatio: "16:9" }, transitionIn: "fade", slots: [slot],
+      scenes: [{ ...scene, sceneNumber: 1, visualResolved: "A waits", slotRefs: ["a"], onScreenTextKind: "subtitle", onScreenText: "hi" }],
+    })
+    expect(r.transitionIn).toBe("fade")
+  })
+  it("a pre-change result still parses, and an unknown key is stripped (readers never break)", () => {
+    const r = videoAnalysisResultSchema.parse({
+      meta: { durationSec: 4, width: 16, height: 9, aspectRatio: "16:9" }, slots: [slot],
+      scenes: [{ ...scene, sceneNumber: 1, visualResolved: "A waits", slotRefs: ["a"], futureKey: 1 }],
+    })
+    expect(r.transitionIn).toBeUndefined()
+    expect((r.scenes[0] as Record<string, unknown>).futureKey).toBeUndefined()
+  })
+  it("rejects a value outside the vocabularies", () => {
+    expect(() => windowAnalysisSchema.parse({ transitionIn: "wipe", slots: [], scenes: [] })).toThrow()
+    expect(() => windowAnalysisSchema.parse({ slots: [], scenes: [{ ...scene, onScreenTextKind: "banner" }] })).toThrow()
+  })
+})

package/src/animals.ts

@@ -30,6 +30,16 @@ export interface Animal {
   readonly label: string
   readonly subcategory: AnimalSubcategory
   readonly description: string
+  /**
+   * Optional authored compact term — the short phrase a professional would
+   * write in a prompt, as opposed to the user-facing `label` (see the `term`
+   * convention in `@nodaro/prompts`'s `term.ts`). Authored ONLY where the
+   * lowercased label is not that phrase — a UI compound naming two things at
+   * once ("Airship / Dirigible" -> "airship", "Plasma Sword / Lightsaber" ->
+   * "plasma sword"). Everywhere else the lowercased label IS the term for a
+   * concrete object ("golden retriever", "katana"), so nothing is authored.
+   */
+  readonly term?: string
 }
 
 export const ANIMALS: ReadonlyArray<Animal> = [

package/src/catalog-projection.ts

@@ -0,0 +1,48 @@
+/**
+ * Tag-free, policy-free wire shape for the `GET /v1/catalogs` projection — the
+ * server-driven, pack-composed catalog view thin clients render their own
+ * pickers from. This is the ONLY catalog-related type in `@nodaro/shared`
+ * (Apache): catalog DATA stays in `@nodaro/prompts` (FSL), and the deferred
+ * `CatalogPolicy` (tags / deny-by-tag / per-read-kind filter) is deliberately
+ * NOT represented here — nothing tag- or policy-shaped may cross this boundary.
+ */
+export interface ProjectedCatalogOption {
+  id: string
+  label: string
+  description?: string
+  category?: string
+  /** The prompt fragment this id injects downstream. Present only when detail="full". */
+  promptHint?: string
+  /**
+   * Short professional term injected by compact hint mode; `label` is for
+   * display. Present at BOTH detail levels — a thin client renders `label`
+   * and injects `term`. Empty for a no-op ("auto"/"none") entry that injects
+   * nothing.
+   */
+  term?: string
+  icon?: string
+}
+
+export interface ProjectedCatalogDimension {
+  field: string
+  label: string
+  options: ProjectedCatalogOption[]
+}
+
+export interface ProjectedCatalog {
+  nodeType: string
+  label: string
+  catalogId: string
+  kind: "single" | "multi"
+  /** single only — the node-data field the chosen id writes to. */
+  valueField?: string
+  defaultValue?: string
+  categoryOrder?: readonly string[]
+  categoryLabels?: Readonly<Record<string, string>>
+  detail: "compact" | "full"
+  /** single-dim catalogs. */
+  options?: ProjectedCatalogOption[]
+  /** multi-dim catalogs. */
+  fields?: readonly string[]
+  dimensions?: ProjectedCatalogDimension[]
+}

package/src/entity-node-fields.ts

@@ -0,0 +1,147 @@
+/**
+ * Which DB columns of a saved entity land on its canvas node, per kind.
+ *
+ * Four surfaces copy an entity row onto a node: the browser's load-time
+ * hydrator, the browser's library picker, the backend's run-time hydration, and
+ * (indirectly) anything that reads a node expecting those fields to be there.
+ * They used to be four hand-written lists, and they drifted exactly as you would
+ * expect — the load-time hydrator covers `character` and nothing else, so an
+ * object node bound by an agent stays media-less until someone rebinds it by
+ * hand.
+ *
+ * This is the field NAMES only — the structural vocabulary. Merge behaviour
+ * (defaults, `prev` fallbacks, type narrowing) stays with each caller, because
+ * a browser node and a server row disagree about nulls and it is not worth
+ * pretending otherwise.
+ */
+
+/**
+ * Every entity kind, in the order surfaces present them.
+ *
+ * The list is the invariant: `Record<EntityNodeKind, …>` makes the compiler
+ * find every table below, every per-kind UI row in the `@` picker, and the
+ * picker’s kind→query map. What the compiler cannot see — that the MCP read
+ * tools for a kind exist and are reachable — is pinned by a test instead.
+ *
+ * Tool names are derivable from it too: `list_<kind>s` / `get_<kind>`.
+ */
+export const ENTITY_NODE_KINDS = ["character", "object", "creature", "location"] as const
+
+export type EntityNodeKind = (typeof ENTITY_NODE_KINDS)[number]
+
+/** The `data.*DbId` field that binds each entity node to its row. */
+export const ENTITY_DB_ID_FIELD: Record<EntityNodeKind, string> = {
+  character: "characterDbId",
+  object: "objectDbId",
+  creature: "creatureDbId",
+  location: "locationDbId",
+}
+
+/** The `data.*Name` field each kind stores its display name under. */
+export const ENTITY_NAME_FIELD: Record<EntityNodeKind, string> = {
+  character: "characterName",
+  object: "objectName",
+  creature: "creatureName",
+  location: "locationName",
+}
+
+/** Postgres table per kind. */
+export const ENTITY_TABLE: Record<EntityNodeKind, string> = {
+  character: "characters",
+  object: "objects",
+  creature: "creatures",
+  location: "locations",
+}
+
+/**
+ * `{name,url}[]` buckets per kind, as `[db_column, nodeField]`.
+ *
+ * These are what a generation actually consumes — the variant a prompt
+ * `@mentions`, the extra references a user attaches. A node missing them is not
+ * visibly broken; it just quietly generates the wrong picture.
+ */
+export const ENTITY_BUCKET_FIELDS: Record<EntityNodeKind, ReadonlyArray<readonly [string, string]>> = {
+  character: [
+    ["expressions", "expressions"],
+    ["poses", "poses"],
+    ["motions", "motions"],
+    ["angles", "angles"],
+    ["body_angles", "bodyAngles"],
+    ["lighting_variations", "lightingVariations"],
+    ["outfit_variations", "outfitVariations"],
+    ["detail_closeups", "detailCloseups"],
+    ["sheets", "sheets"],
+  ],
+  object: [
+    ["angles", "angles"],
+    ["materials", "materials"],
+    ["variations", "variations"],
+    ["motion_clips", "motionClips"],
+    ["detail_closeups", "detailCloseups"],
+    ["sheets", "sheets"],
+  ],
+  creature: [
+    ["angles", "angles"],
+    ["poses", "poses"],
+    ["variations", "variations"],
+    ["motion_clips", "motionClips"],
+    ["detail_closeups", "detailCloseups"],
+    ["sheets", "sheets"],
+  ],
+  location: [
+    ["time_of_day", "timeOfDay"],
+    ["weather", "weather"],
+    ["angles", "angles"],
+    ["lighting", "lighting"],
+    ["seasons", "seasons"],
+    ["atmosphere_motions", "atmosphereMotions"],
+    ["detail_closeups", "detailCloseups"],
+    ["sheets", "sheets"],
+  ],
+}
+
+/**
+ * Scalars every kind shares, as `[db_column, nodeField]`.
+ *
+ * `source_image_url` is the load-bearing one: the run engine reads
+ * `defaultAssetUrl || sourceImageUrl` and SKIPS the reference entirely when
+ * both are empty — no error, no warning, just a generation of the wrong
+ * person. A node with an id but no image is the shape an agent produces.
+ */
+export const ENTITY_SCALAR_FIELDS: ReadonlyArray<readonly [string, string]> = [
+  ["name", "__name"], // routed to the kind's own name field by the caller
+  ["description", "description"],
+  ["canonical_description", "canonicalDescription"],
+  ["source_image_url", "sourceImageUrl"],
+]
+
+/**
+ * Scalars only SOME kinds have.
+ *
+ * `style_lock` looks shared and is not: characters never grew the column,
+ * because a character's likeness is the lock. Selecting it from `characters`
+ * anyway is a PostgREST error, which the run-time hydrator swallows by design
+ * — so the whole kind would quietly stop hydrating and every test that mocks
+ * the database would still pass. That is why the column lists are checked
+ * against the migrations by `entity-hydration-columns.test.ts`.
+ */
+export const ENTITY_KIND_SCALAR_FIELDS: Record<EntityNodeKind, ReadonlyArray<readonly [string, string]>> = {
+  character: [],
+  object: [["style_lock", "styleLock"]],
+  creature: [["style_lock", "styleLock"]],
+  location: [["style_lock", "styleLock"]],
+}
+
+/** Every DB column a full hydration of `kind` reads. */
+export function entityHydrationColumns(kind: EntityNodeKind): string[] {
+  return [
+    "id",
+    ...entityScalarFields(kind).map(([column]) => column),
+    ...ENTITY_BUCKET_FIELDS[kind].map(([column]) => column),
+  ]
+}
+
+/** Every scalar `kind` actually has, shared plus its own. */
+export function entityScalarFields(kind: EntityNodeKind): ReadonlyArray<readonly [string, string]> {
+  return [...ENTITY_SCALAR_FIELDS, ...ENTITY_KIND_SCALAR_FIELDS[kind]]
+}

package/src/furniture.ts

@@ -26,6 +26,16 @@ export interface Furniture {
   readonly label: string
   readonly subcategory: FurnitureSubcategory
   readonly description: string
+  /**
+   * Optional authored compact term — the short phrase a professional would
+   * write in a prompt, as opposed to the user-facing `label` (see the `term`
+   * convention in `@nodaro/prompts`'s `term.ts`). Authored ONLY where the
+   * lowercased label is not that phrase — a UI compound naming two things at
+   * once ("Airship / Dirigible" -> "airship", "Plasma Sword / Lightsaber" ->
+   * "plasma sword"). Everywhere else the lowercased label IS the term for a
+   * concrete object ("golden retriever", "katana"), so nothing is authored.
+   */
+  readonly term?: string
 }
 
 export const FURNITURE: ReadonlyArray<Furniture> = [

package/src/i18n/framing.ar.ts

@@ -18,7 +18,6 @@ const map: LocaleCatalogMap = {
   "macro": { label: "ماكرو", description: "تفصيل قريب جدا لموضوع صغير" },
   "full-shot": { label: "لقطة كاملة", description: "الجسم بالكامل من الرأس إلى القدم في الإطار" },
   "cowboy-shot": { label: "لقطة Cowboy", description: "من منتصف الفخذ فأعلى، تأطير غربي كلاسيكي" },
-  "head-to-knees": { label: "من الرأس للركبتين", description: "من الرأس نزولا للركبتين" },
   "head-to-hip": { label: "من الرأس للخصر", description: "من الرأس نزولا للوركين" },
   "half-body": { label: "نصف جسم", description: "بورتريه نظيف من الخصر فأعلى" },
 

package/src/i18n/framing.de.ts

@@ -18,7 +18,6 @@ const map: LocaleCatalogMap = {
   "macro": { label: "Makro", description: "Extremes Nahdetail eines kleinen Motivs" },
   "full-shot": { label: "Ganzkörper-Aufnahme", description: "Ganzer Körper von Kopf bis Fuß im Bild" },
   "cowboy-shot": { label: "Cowboy Shot", description: "Ab Mitte Oberschenkel, klassische Western-Einstellung" },
-  "head-to-knees": { label: "Kopf bis Knie", description: "Vom Kopf bis zu den Knien" },
   "head-to-hip": { label: "Kopf bis Hüfte", description: "Vom Kopf bis zur Hüftlinie" },
   "half-body": { label: "Halbporträt", description: "Sauberes Porträt ab der Hüfte aufwärts" },
   "eye-level": { label: "Augenhöhe", description: "Kamera auf Augenhöhe des Motivs" },

package/src/i18n/framing.es.ts

@@ -18,7 +18,6 @@ const map: LocaleCatalogMap = {
   "macro": { label: "Macro", description: "Detalle extremamente cercano de un sujeto pequeño" },
   "full-shot": { label: "Plano Entero", description: "Cuerpo entero de cabeza a pies en el cuadro" },
   "cowboy-shot": { label: "Plano Vaquero", description: "Desde mitad del muslo hacia arriba, encuadre clásico del Oeste" },
-  "head-to-knees": { label: "De Cabeza a Rodillas", description: "Desde la cabeza hasta las rodillas" },
   "head-to-hip": { label: "De Cabeza a Cadera", description: "Desde la cabeza hasta las caderas" },
   "half-body": { label: "Medio Cuerpo", description: "Retrato limpio de cintura para arriba" },
 

package/src/i18n/framing.fr.ts

@@ -19,7 +19,6 @@ const map: LocaleCatalogMap = {
   "macro": { description: "Détail extrêmement rapproché d'un petit sujet" },
   "full-shot": { label: "Plan en pied", description: "Corps entier de la tête aux pieds dans le cadre" },
   "cowboy-shot": { description: "Du milieu des cuisses, cadrage western classique" },
-  "head-to-knees": { label: "De la tête aux genoux", description: "De la tête jusqu'aux genoux" },
   "head-to-hip": { label: "De la tête à la hanche", description: "De la tête jusqu'aux hanches" },
   "half-body": { label: "Demi-corps", description: "Portrait propre à partir de la taille" },
   // Angle

package/src/i18n/framing.he.ts

@@ -18,7 +18,6 @@ const map: LocaleCatalogMap = {
   "macro": { label: "Macro", description: "פרט קרוב קיצוני של סובייקט קטן" },
   "full-shot": { label: "Full Shot", description: "כל הגוף מראש עד רגליים בפריים" },
   "cowboy-shot": { label: "Cowboy Shot", description: "מאמצע הירך ומעלה, מסגור Western קלאסי" },
-  "head-to-knees": { label: "ראש עד ברכיים", description: "מהראש למטה עד הברכיים" },
   "head-to-hip": { label: "ראש עד מותן", description: "מהראש למטה עד המותניים" },
   "half-body": { label: "חצי גוף", description: "פורטרט נקי מהמותניים ומעלה" },
 

package/src/i18n/framing.hi.ts

@@ -19,7 +19,6 @@ const map: LocaleCatalogMap = {
   "macro": { label: "Macro", description: "छोटे subject का अत्यधिक नज़दीकी detail" },
   "full-shot": { label: "Full Shot", description: "Frame में सिर-से-पैर तक पूरा बदन" },
   "cowboy-shot": { label: "Cowboy Shot", description: "जाँघ के बीच से ऊपर, क्लासिक Western framing" },
-  "head-to-knees": { label: "सिर से घुटनों तक", description: "सिर से लेकर घुटनों तक" },
   "head-to-hip": { label: "सिर से कूल्हे तक", description: "सिर से लेकर कूल्हे तक" },
   "half-body": { label: "आधा बदन", description: "साफ़ कमर-से-ऊपर portrait" },
 

package/src/i18n/framing.ja.ts

@@ -19,7 +19,6 @@ const map: LocaleCatalogMap = {
   "macro": { label: "マクロ", description: "小さな被写体の極端な拡大" },
   "full-shot": { label: "フルショット", description: "頭からつま先まで全身がフレーム内に収まる" },
   "cowboy-shot": { label: "カウボーイショット", description: "太もも中央から上、クラシックな西部劇のフレーミング" },
-  "head-to-knees": { label: "頭から膝まで", description: "頭から膝までを写す" },
   "head-to-hip": { label: "頭から腰まで", description: "頭から腰までを写す" },
   "half-body": { label: "ハーフボディ", description: "クリーンな腰上のポートレート" },
 

package/src/i18n/framing.ko.ts

@@ -19,7 +19,6 @@ const map: LocaleCatalogMap = {
   "macro": { label: "매크로", description: "작은 피사체의 극단적인 클로즈 디테일입니다" },
   "full-shot": { label: "풀 샷", description: "머리부터 발끝까지 전신이 프레임에 들어갑니다" },
   "cowboy-shot": { label: "카우보이 샷", description: "허벅지 중간부터 위로, 클래식한 서부극 프레이밍입니다" },
-  "head-to-knees": { label: "머리부터 무릎까지", description: "머리부터 무릎까지의 프레이밍입니다" },
   "head-to-hip": { label: "머리부터 엉덩이까지", description: "머리부터 엉덩이까지의 프레이밍입니다" },
   "half-body": { label: "반신", description: "허리 위의 깔끔한 인물 사진입니다" },
 

package/src/i18n/framing.pt-BR.ts

@@ -19,7 +19,6 @@ const map: LocaleCatalogMap = {
   "macro": { description: "Detalhe extremo de um pequeno sujeito" },
   "full-shot": { label: "Plano Inteiro", description: "Corpo inteiro da cabeça aos pés no quadro" },
   "cowboy-shot": { description: "Da metade da coxa para cima, enquadramento clássico de Western" },
-  "head-to-knees": { label: "Da Cabeça aos Joelhos", description: "Da cabeça até os joelhos" },
   "head-to-hip": { label: "Da Cabeça ao Quadril", description: "Da cabeça até o quadril" },
   "half-body": { label: "Meio Corpo", description: "Retrato limpo da cintura para cima" },
 

package/src/i18n/framing.ru.ts

@@ -19,7 +19,6 @@ const map: LocaleCatalogMap = {
   "macro": { label: "Макро", description: "Сверхблизкая деталь маленького объекта" },
   "full-shot": { label: "Полный план", description: "Всё тело с головы до пят в кадре" },
   "cowboy-shot": { label: "Ковбойский план", description: "От середины бедра, классическое вестерн-кадрирование" },
-  "head-to-knees": { label: "Голова до колен", description: "От головы до колен" },
   "head-to-hip": { label: "Голова до бёдер", description: "От головы до бёдер" },
   "half-body": { label: "Поясной портрет", description: "Чистый поясной портрет" },
 

package/src/i18n/framing.zh-CN.ts

@@ -19,7 +19,6 @@ const map: LocaleCatalogMap = {
   "macro":             { label: "微距",           description: "对小型主体的极近距细节" },
   "full-shot":         { label: "全身镜头",       description: "全身入画" },
   "cowboy-shot":       { label: "牛仔镜头",       description: "大腿中部以上,经典西部片取景" },
-  "head-to-knees":     { label: "头到膝盖",       description: "从头部到膝盖" },
   "head-to-hip":       { label: "头到髋",         description: "从头部到髋部" },
   "half-body":         { label: "半身像",         description: "干净的腰部以上人像" },
 

package/src/i18n/index.ts

@@ -30,6 +30,33 @@ function cacheKey(catalog: I18nCatalogId, locale: LocaleId): string {
   return `${catalog}:${locale}`
 }
 
+/**
+ * Pack-sidecar overlay: localized strings contributed by registered catalog
+ * packs (e.g. an extension pack's `sidecars.he`), keyed `<catalog>:<locale>`.
+ * Consulted by `getLocalizedEntry` when the file sidecar lacks an id. Empty on
+ * mainline. Populated by `@nodaro/prompts` at pack registration — the content
+ * (the translated strings) lives in the pack (the deployment overlay), never
+ * in this Apache package.
+ */
+const packSidecars = new Map<string, LocaleCatalogMap>()
+
+export function registerCatalogSidecars(
+  catalog: string,
+  sidecars: Partial<Record<LocaleId, LocaleCatalogMap>> | undefined,
+): void {
+  if (!sidecars) return
+  for (const locale of Object.keys(sidecars) as LocaleId[]) {
+    const map = sidecars[locale]
+    if (!map) continue
+    const key = `${catalog}:${locale}`
+    packSidecars.set(key, { ...(packSidecars.get(key) ?? {}), ...map })
+  }
+}
+
+export function resetCatalogSidecars(): void {
+  packSidecars.clear()
+}
+
 /**
  * Lazy-load a sidecar catalog. Returns `null` if the locale is `en` (no
  * sidecar — English lives in the canonical catalog file) or if no sidecar
@@ -82,9 +109,12 @@ export function getLocalizedEntry(
   locale: LocaleId,
 ): LocalizedEntry | undefined {
   if (locale === "en") return undefined
-  const map = cache.get(cacheKey(catalog, locale))
-  if (!map) return undefined
-  return map[id]
+  const key = cacheKey(catalog, locale)
+  const fromFile = cache.get(key)?.[id]
+  if (fromFile) return fromFile
+  // Fall back to a pack-registered sidecar overlay (G10). File sidecars win;
+  // pack sidecars cover ids the deployment overlay added. Empty on mainline.
+  return packSidecars.get(key)?.[id]
 }
 
 /**

package/src/i18n/transitions.ar.ts

@@ -7,12 +7,15 @@ const map: LocaleCatalogMap = {
   "cross-dissolve": { label: "تلاشٍ متقاطع", description: "مزج تدريجي بين اللقطتين" },
   "fade-to-black": { label: "تلاشٍ إلى الأسود", description: "تظلم تدريجي ثم تظهر اللقطة التالية" },
   "fade-to-white": { label: "تلاشٍ إلى الأبيض", description: "توهج حتى الأبيض ثم تظهر اللقطة" },
+  "snap-to-black": { label: "قطع فوري إلى السواد", description: "قطع فوري إلى سواد كامل للحظة، ثم تدخل اللقطة التالية" },
   "match-cut": { label: "قطع متطابق", description: "تطابق الشكل أو الحركة بين اللقطتين" },
   "smash-cut": { label: "قطع مفاجئ", description: "قطع مفاجئ صارخ بين لقطتين متباينتين" },
   "iris": { label: "انتقال القزحية", description: "دائرة تنغلق ثم تنفتح على اللقطة الجديدة" },
   "wipe": { label: "مسح خطي", description: "خط يجتاح الإطار ليكشف اللقطة الجديدة" },
   "roll-transition": { label: "دوران", description: "الإطار يدور 90-180 درجة للانتقال" },
   "seamless-match": { label: "تطابق سلس", description: "قطع خفي يُموَّه بتطابق الحركة واللون" },
+  "whip-pan": { label: "بان سريع", description: "الكاميرا تنعطف جانبًا بسرعة مع ضبابية، واللقطة التالية تتابع الاتجاه نفسه" },
+  "jump-cut": { label: "قطع قافز", description: "الإطار نفسه، والزمن يقفز إلى الأمام" },
 
   // ── Time ──
   "fast-forward-day-night": { label: "تسريع (نهار ← ليل)", description: "مرور الزمن من النهار إلى الليل في نفس المشهد" },
@@ -62,6 +65,8 @@ const map: LocaleCatalogMap = {
   "zoom-into-mouth": { label: "تكبير في الفم", description: "الكاميرا تدخل الفم لتظهر في عالم جديد" },
   "push-through-glass": { label: "اختراق الزجاج", description: "الكاميرا تخترق لوح زجاج لعالم آخر" },
   "soul-jump": { label: "قفزة الروح", description: "روح شفافة تخرج وتدخل جسداً جديداً" },
+  "mask-transition": { label: "انتقال بالقناع", description: "جسم في المقدمة يحجب الإطار، والكاميرا تعبر العتمة إلى المشهد الجديد" },
+  "zoom-through": { label: "تقريب عبر التفصيل", description: "الكاميرا تكبّر تفصيلاً واحدًا حتى ينكشف المشهد الجديد داخله" },
 
   // ── Physics ──
   "explosion-blast": { label: "موجة انفجار", description: "انفجار يجتاح الإطار ويكشف المشهد الجديد" },
@@ -73,6 +78,7 @@ const map: LocaleCatalogMap = {
   "vehicle-explosion": { label: "انفجار مركبة", description: "مركبة تنفجر واللهب يغطي الإطار ثم يُكشف المشهد" },
   "jump-match": { label: "قفزة متطابقة", description: "الشخص يقفز وعند الهبوط يكون في مشهد جديد" },
   "hand-swipe": { label: "مسح اليد", description: "يد تمر أمام العدسة ويتغير المشهد" },
+  "action-relay": { label: "قطع على الحركة", description: "الشخصية تغادر الإطار وسط حركة وتكملها في المشهد الجديد" },
 
   // ── Light ──
   "white-flash": { label: "وميض أبيض", description: "الإطار يتوهج أبيض ثم يظهر المشهد الجديد" },

package/src/i18n/transitions.de.ts

@@ -7,12 +7,15 @@ const map: LocaleCatalogMap = {
   "cross-dissolve":         { label: "Überblendung",             description: "Allmähliche Mischung zwischen den Einstellungen" },
   "fade-to-black":          { label: "Abblende auf Schwarz",     description: "Dunkelt auf Schwarz ab, zweite Einstellung erscheint" },
   "fade-to-white":          { label: "Abblende auf Weiß",        description: "Erstrahlt in Weiß, zweite Einstellung erscheint" },
+  "snap-to-black":          { label: "Harter Schnitt auf Schwarz", description: "Sofortiger Schnitt auf volles Schwarz für einen Moment, dann die nächste Einstellung" },
   "match-cut":              { label: "Match Cut",                description: "Form- oder Bewegungsübereinstimmung zwischen Einstellungen" },
   "smash-cut":              { label: "Smash Cut",                description: "Abrupter Schnitt zwischen kontrastierenden Einstellungen" },
   "iris":                   { label: "Irisblende",               description: "Iris schließt und öffnet sich zur zweiten Einstellung" },
   "wipe":                   { label: "Wischblende",              description: "Linearer Wisch ersetzt die erste Einstellung" },
   "roll-transition":        { label: "Drehübergang",             description: "Bild dreht 90-180°, zweite Einstellung am Ende" },
   "seamless-match":         { label: "Nahtloser Schnitt",        description: "Versteckter Schnitt durch angeglichene Bewegung und Farbe" },
+  "whip-pan":               { label: "Whip Pan",                 description: "Die Kamera reißt seitwärts in Bewegungsunschärfe, die zweite Einstellung folgt derselben Richtung" },
+  "jump-cut":               { label: "Jump Cut",                 description: "Gleiche Einstellung, die Zeit springt vorwärts" },
 
   // ── Time ──
   "fast-forward-day-night": { label: "Zeitraffer Tag → Nacht",  description: "Zeitraffer von Tag zu Nacht in derselben Szene" },
@@ -62,6 +65,8 @@ const map: LocaleCatalogMap = {
   "zoom-into-mouth":        { label: "Zoom in den Mund",        description: "Die Kamera tritt durch den geöffneten Mund in die neue Welt" },
   "push-through-glass":     { label: "Durch das Glas",          description: "Die Kamera durchquert das Glas in die neue Welt" },
   "soul-jump":              { label: "Seelensprung",            description: "Eine transluzente Seele verlässt den Körper und betritt den neuen" },
+  "mask-transition":        { label: "Maskenübergang",          description: "Ein Objekt im Vordergrund verdunkelt das Bild, die Kamera fährt hindurch" },
+  "zoom-through":           { label: "Zoom Hindurch",           description: "Die Kamera vergrößert ein Detail, bis die neue Szene darin entsteht" },
 
   // ── Physics ──
   "explosion-blast":        { label: "Explosionsdruckwelle",    description: "Die Explosion fegt den Rahmen frei, neue Szene erscheint" },
@@ -73,6 +78,7 @@ const map: LocaleCatalogMap = {
   "vehicle-explosion":      { label: "Fahrzeugexplosion",       description: "Das Fahrzeug explodiert im Vordergrund, die Szene wechselt" },
   "jump-match":             { label: "Sprung-Schnitt",          description: "Das Sujet springt, die Landung verbindet mit der neuen Szene" },
   "hand-swipe":             { label: "Hand-Wisch",              description: "Eine Hand wischt über das Objektiv, die Szene wechselt dahinter" },
+  "action-relay":           { label: "Schnitt auf Bewegung",    description: "Das Sujet verlässt das Bild in einer Bewegung und setzt sie in der neuen Szene fort" },
 
   // ── Light ──
   "white-flash":            { label: "Weißblitz",               description: "Der Rahmen erstrahlt in reinem Weiß" },