@nodaro/shared 2.11.0 → 2.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.11.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__/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/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/video-analysis.ts

@@ -88,6 +88,21 @@ export type VideoAnalysisVisualEffect = (typeof VIDEO_ANALYSIS_VISUAL_EFFECTS)[n
 export const VIDEO_ANALYSIS_TRANSITIONS = ["cut", "fade", "dissolve", "wipe", "whip"] as const
 export type VideoAnalysisTransition = (typeof VIDEO_ANALYSIS_TRANSITIONS)[number]
 
+/**
+ * What burned-in text IS (2026-08-28, recast shot craft). Decides render-vs-omit
+ * downstream: a `subtitle` is a transcription of the piece's own speech — a
+ * recreation re-speaks it and must not render it — while a `title`, `caption`,
+ * `lower-third` or `logo` is picture content. Absent when a scene carries no
+ * text. A new KEY on the scene: strip-mode readers drop it harmlessly.
+ */
+export const VIDEO_ANALYSIS_TEXT_KINDS = ["title", "caption", "lower-third", "subtitle", "logo", "other"] as const
+export type VideoAnalysisTextKind = (typeof VIDEO_ANALYSIS_TEXT_KINDS)[number]
+
+/** How the CLIP opens (clip-level, not per scene — a window's first scene is
+ *  not the clip's). Absent ⇒ a hard open. Only `fade` today. */
+export const VIDEO_ANALYSIS_CLIP_TRANSITIONS_IN = ["fade"] as const
+export type VideoAnalysisClipTransitionIn = (typeof VIDEO_ANALYSIS_CLIP_TRANSITIONS_IN)[number]
+
 /**
  * Time manipulation — slow motion, ramps, timelapse, freeze, reverse.
  *
@@ -302,6 +317,8 @@ const windowSceneBase = z.object({
    * earlier scene's speech means the shot is replayed footage under a voice-over.
    */
   onScreenText: z.string().optional(),
+  /** What the on-screen text IS. Meaningful only when `onScreenText` is non-empty. */
+  onScreenTextKind: z.enum(VIDEO_ANALYSIS_TEXT_KINDS).optional(),
   /** Effects on this shot's PICTURE. Absent ⇒ a clean image. */
   effects: z.array(z.enum(VIDEO_ANALYSIS_VISUAL_EFFECTS)).optional(),
   transitionOut: z.enum(VIDEO_ANALYSIS_TRANSITIONS).optional(),
@@ -323,6 +340,8 @@ export const windowAnalysisSchema = z.object({
   /** The clip-level look as read from THIS window. Merge folds the windows
    *  field-by-field (first non-empty wins), like `language`. */
   look: clipLookSchema.optional(),
+  /** The clip opens with a fade-in. Folded from window 0 only. */
+  transitionIn: z.enum(VIDEO_ANALYSIS_CLIP_TRANSITIONS_IN).optional(),
   slots: z.array(entitySlotSchema),
   scenes: z.array(windowSceneSchema),
 })
@@ -349,6 +368,8 @@ export const videoAnalysisResultSchema = z.object({
    *  rather than a member: `meta` is probed fact (ffprobe dimensions, probed
    *  duration), while this is the model's reading of the photography. */
   look: clipLookSchema.optional(),
+  /** The clip opens with a fade-in. Folded from window 0 only. */
+  transitionIn: z.enum(VIDEO_ANALYSIS_CLIP_TRANSITIONS_IN).optional(),
   slots: z.array(entitySlotSchema),
   scenes: z.array(analyzedSceneSchema).min(1),
   /** CAST VARIATIONS (§4 cap handling): looks the analyzer's merge FOLDED into