@nodaro/shared 2.12.2 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.12.2",
+  "version": "2.13.0",
   "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__/node-preset-extract.test.ts

@@ -4,6 +4,7 @@ import {
   extractPresetData,
   PRESET_EXCLUDED_KEYS,
   PRESET_APPLY_CLEAR_KEYS,
+  presetApplyClearKeys,
   presetDataMatches,
 } from "../node-preset-extract.js"
 
@@ -164,3 +165,61 @@ describe("presetDataMatches", () => {
     expect(presetDataMatches({ prompt: "a" }, {})).toBe(true)
   })
 })
+
+describe("presetApplyClearKeys", () => {
+  const staticKeys = [...PRESET_APPLY_CLEAR_KEYS]
+  const hasAffixes = (keys: readonly string[]) =>
+    keys.includes("promptPrefix") && keys.includes("promptSuffix")
+
+  it("always includes every static clear key, whatever the preset ships", () => {
+    for (const data of [
+      {},
+      { prompt: "a cat" },
+      { promptPrefix: "Cinematic 35mm still of" },
+      { promptSuffix: ", golden hour" },
+      { prompt: "a cat", promptPrefix: "PRE", promptSuffix: "POST" },
+      { provider: "flux", aspectRatio: "16:9" },
+    ]) {
+      const keys = presetApplyClearKeys(data)
+      for (const k of staticKeys) expect(keys, `${k} missing for ${JSON.stringify(data)}`).toContain(k)
+    }
+  })
+
+  it("owns no prompt content -> does NOT clear the affixes (settings-only preset)", () => {
+    expect(hasAffixes(presetApplyClearKeys({}))).toBe(false)
+    expect(hasAffixes(presetApplyClearKeys({ provider: "flux", seed: 3 }))).toBe(false)
+    // exactly the static set, nothing added
+    expect([...presetApplyClearKeys({ provider: "flux" })].sort()).toEqual([...staticKeys].sort())
+  })
+
+  it("ships `prompt` -> clears BOTH affixes (the stale-prefix hazard)", () => {
+    expect(hasAffixes(presetApplyClearKeys({ prompt: "a cat" }))).toBe(true)
+  })
+
+  it("ships an affix -> clears both affixes (the other one is then re-set by the spread)", () => {
+    expect(hasAffixes(presetApplyClearKeys({ promptPrefix: "PRE" }))).toBe(true)
+    expect(hasAffixes(presetApplyClearKeys({ promptSuffix: "POST" }))).toBe(true)
+  })
+
+  it("ships prompt AND affixes -> clears both affixes", () => {
+    expect(hasAffixes(presetApplyClearKeys({ prompt: "a cat", promptPrefix: "PRE", promptSuffix: "POST" }))).toBe(true)
+  })
+
+  it("never lists `prompt` itself — it is overwritten only when the preset ships it", () => {
+    for (const data of [{}, { prompt: "a cat" }, { promptPrefix: "PRE" }]) {
+      expect(presetApplyClearKeys(data)).not.toContain("prompt")
+    }
+  })
+
+  it("treats an explicit `undefined` value as NOT owning prompt content", () => {
+    expect(hasAffixes(presetApplyClearKeys({ prompt: undefined }))).toBe(false)
+    expect(hasAffixes(presetApplyClearKeys({ promptPrefix: undefined }))).toBe(false)
+  })
+
+  it("does not mutate PRESET_APPLY_CLEAR_KEYS", () => {
+    presetApplyClearKeys({ prompt: "a cat" })
+    expect([...PRESET_APPLY_CLEAR_KEYS].sort()).toEqual([...staticKeys].sort())
+    expect(PRESET_APPLY_CLEAR_KEYS).not.toContain("promptPrefix")
+    expect(PRESET_APPLY_CLEAR_KEYS).not.toContain("promptSuffix")
+  })
+})

package/src/__tests__/prompt-affixes.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest"
+import { PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY, readPromptAffixes } from "../prompt-affixes.js"
+
+describe("prompt-affixes keys", () => {
+  it("names the node-data keys", () => {
+    expect(PROMPT_PREFIX_KEY).toBe("promptPrefix")
+    expect(PROMPT_SUFFIX_KEY).toBe("promptSuffix")
+  })
+})
+
+describe("readPromptAffixes", () => {
+  it("returns both affixes when set", () =>
+    expect(readPromptAffixes({ promptPrefix: "PRE", promptSuffix: "POST" })).toEqual({ prefix: "PRE", suffix: "POST" }))
+  it("omits blank / non-string values", () =>
+    expect(readPromptAffixes({ promptPrefix: "   ", promptSuffix: 42 })).toEqual({}))
+  it("omits absent keys", () => expect(readPromptAffixes({ prompt: "x" })).toEqual({}))
+  it("keeps internal/trailing whitespace of a non-blank affix verbatim", () =>
+    expect(readPromptAffixes({ promptPrefix: "RULES:\n\n" })).toEqual({ prefix: "RULES:\n\n" }))
+})
+
+/**
+ * Presets capture the affixes for free: `extractPresetData` strips only
+ * PRESET_EXCLUDED_KEYS + EXECUTION_DATA_KEYS, and the affix keys are in
+ * neither. This test pins that contract so a future addition to either
+ * exclusion set can't silently drop pre/post text from saved presets.
+ */
+import { extractPresetData } from "../node-preset-extract.js"
+describe("presets capture prompt affixes", () => {
+  it("extractPresetData keeps promptPrefix/promptSuffix", () =>
+    expect(extractPresetData({ prompt: "p", promptPrefix: "PRE", promptSuffix: "POST", label: "x", executionStatus: "running" }))
+      .toEqual({ prompt: "p", promptPrefix: "PRE", promptSuffix: "POST" }))
+})

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

@@ -8,10 +8,16 @@ const scene = { startSec: 0, endSec: 4, label: "hook", shotType: "Wide", camera:
 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", () => {
+  it("adds a text-kind vocabulary and a clip transition-in vocabulary; the transition enum is v2 (rev 1.5)", () => {
     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"])
+    // Stage 1 shipped "keys only, no enum widened" (a lagging client rejects an
+    // unknown VALUE). Rev 1.5 (2026-08-30) widens it on purpose — sequenced
+    // behind the client bump — so this pin now tracks the v2 vocabulary.
+    expect(VIDEO_ANALYSIS_TRANSITIONS).toEqual([
+      "cut", "fade", "dissolve", "wipe", "whip",
+      "zoom", "slide", "white-flash", "digital-glitch", "morph", "match", "jump",
+    ])
   })
   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" }] })

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

@@ -275,6 +275,18 @@ describe("cinematography fields (angle / speed / onScreenText / look)", () => {
     }
   })
 
+  it("vocabulary v2 carries the twelve common edits, and the wire neutral is not a member", () => {
+    // rev 1.5 Appendix F: absent = nothing asserted; `none` is wire-local to the
+    // analyser's roll schema and must never reach the canonical enum.
+    expect([...VIDEO_ANALYSIS_TRANSITIONS]).toEqual([
+      "cut", "fade", "dissolve", "wipe", "whip",
+      "zoom", "slide", "white-flash", "digital-glitch", "morph", "match", "jump",
+    ])
+    expect(VIDEO_ANALYSIS_TRANSITIONS).not.toContain("none" as never)
+    expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, transitionOut: "none" }] }).success).toBe(false)
+    expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene }] }).success).toBe(true)
+  })
+
   it("marks the viewpoints where no face is visible — auto-cast reads this", () => {
     // A reference frame shot from behind cannot cast a face, however well framed.
     expect([...VIDEO_ANALYSIS_FACELESS_ANGLES].sort()).toEqual(["from-behind", "over-the-shoulder"])

package/src/catalog-projection.ts

@@ -44,5 +44,8 @@ export interface ProjectedCatalog {
   options?: ProjectedCatalogOption[]
   /** multi-dim catalogs. */
   fields?: readonly string[]
+  /** Per-field option lists. Multi-dim catalogs always carry these; a
+   *  single-dim catalog carries them when it has secondary parameter
+   *  fields beside its main picker (transition position/duration/intensity). */
   dimensions?: ProjectedCatalogDimension[]
 }

package/src/i18n/composition-effects.ar.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "بدون", description: "بدون تأثير تركيبي" },
   "bursting-through-frame": { label: "اختراق الإطار", description: "تمزق ورقي ثلاثي الأبعاد يكسر الإطار" },
   "breaking-out-of-frame": { label: "الخروج من الإطار", description: "طرف يمتد خارج حدود اللوحة" },
   "pixel-disintegration": { label: "تفكك بكسلي", description: "الموضوع يتحلل إلى جسيمات" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments": { label: "شظايا عائمة", description: "أجزاء من الجسم تنجرف بعيدا" },
   "silhouette-outline": { label: "ظل خارجي", description: "ظل أسود نقي على خلفية مسطحة" },
   "exploding-particles": { label: "جسيمات منفجرة", description: "الخط الخارجي يتطاير إلى جسيمات" },
-  "3x3-grid-collage": { label: "كولاج شبكة 3×3", description: "مونتاج تسع وضعيات على ورقة اتصال" },
 
   "matte-painting": { label: "رسم Matte", description: "خلفية مرسومة بـ Matte مدمجة مع Live Action" },
   "double-exposure": { label: "تعريض مزدوج", description: "تعريضان فوتوغرافيان متراكبان مدمجان" },

package/src/i18n/composition-effects.de.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "Keiner", description: "Kein Kompositionseffekt" },
   "bursting-through-frame": { label: "Durch den Rahmen brechen", description: "3D-Papierriss durchbricht den Rahmen" },
   "breaking-out-of-frame": { label: "Aus dem Rahmen ausbrechen", description: "Glied erstreckt sich über den Bildrand" },
   "pixel-disintegration": { label: "Pixel-Zerfall", description: "Motiv löst sich in Partikel auf" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments": { label: "Schwebende Fragmente", description: "Körper schwebt teilweise davon" },
   "silhouette-outline": { label: "Silhouetten-Umriss", description: "Saubere schwarze Silhouette auf flachem Hintergrund" },
   "exploding-particles": { label: "Explodierende Partikel", description: "Umriss zerstreut sich in Partikel" },
-  "3x3-grid-collage": { label: "3x3-Raster-Collage", description: "Kontaktbogen mit 9 Posen-Montage" },
   "matte-painting": { label: "Matte Painting", description: "Kompositiertes Matte-Painting-Hintergrund mit Live-Action verbunden" },
   "double-exposure": { label: "Doppelbelichtung", description: "Zwei geschichtete fotografische Belichtungen verschmolzen" },
   "multiple-exposure": { label: "Mehrfachbelichtung", description: "Drei oder mehr übereinander gestapelte Belichtungen" },

package/src/i18n/composition-effects.es.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "Ninguno", description: "Sin efecto de composición" },
   "bursting-through-frame": { label: "Atravesando el Marco", description: "Rasgado de papel 3D rompiendo el marco" },
   "breaking-out-of-frame": { label: "Rompiendo el Marco", description: "Extremidad se extiende más allá del borde del lienzo" },
   "pixel-disintegration": { label: "Desintegración de Píxeles", description: "Sujeto disolviéndose en partículas" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments": { label: "Fragmentos Flotantes", description: "Cuerpo derivando parcialmente" },
   "silhouette-outline": { label: "Silueta Contorno", description: "Silueta negra limpia sobre fondo plano" },
   "exploding-particles": { label: "Partículas Explotando", description: "Contorno disipándose en partículas" },
-  "3x3-grid-collage": { label: "Collage en Cuadrícula 3x3", description: "Montaje tipo hoja de contactos de 9 poses" },
 
   // -------------------- Round 2 --------------------
   "matte-painting": { label: "Matte Painting", description: "Fondo de matte painting compuesto y mezclado con acción real" },

package/src/i18n/composition-effects.fr.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "Aucun", description: "Aucun effet de composition" },
   "bursting-through-frame": { label: "Surgissant à travers le cadre", description: "Déchirure de papier 3D brisant le cadre" },
   "breaking-out-of-frame": { label: "Sortant du cadre", description: "Membre s'étendant au-delà de la bordure du tableau" },
   "pixel-disintegration": { label: "Désintégration en pixels", description: "Sujet se dissolvant en particules" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments": { label: "Fragments flottants", description: "Corps se dispersant partiellement" },
   "silhouette-outline": { label: "Silhouette en contour", description: "Silhouette noire nette sur fond uni" },
   "exploding-particles": { label: "Particules explosives", description: "Contour se dispersant en particules" },
-  "3x3-grid-collage": { label: "Collage en grille 3x3", description: "Montage planche-contact de 9 poses" },
   "matte-painting": { label: "Matte painting", description: "Fond peint en matte painting fondu avec prise de vue réelle" },
   "double-exposure": { label: "Double exposition", description: "Deux expositions photographiques superposées et fondues" },
   "multiple-exposure": { label: "Exposition multiple", description: "Trois expositions ou plus empilées" },

package/src/i18n/composition-effects.he.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "ללא", description: "ללא אפקט קומפוזיציה" },
   "bursting-through-frame": { label: "פורץ דרך הפריים", description: "קריעת נייר תלת-ממדית הפורצת את הפריים" },
   "breaking-out-of-frame": { label: "פורץ מחוץ לפריים", description: "גף נמתח מעבר לגבול הקנבס" },
   "pixel-disintegration": { label: "פירוק לפיקסלים", description: "סובייקט מתפרק לחלקיקים" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments": { label: "שברים מרחפים", description: "גוף נסחף חלקית" },
   "silhouette-outline": { label: "מתאר צללית", description: "צללית שחורה נקייה על רקע שטוח" },
   "exploding-particles": { label: "חלקיקים מתפוצצים", description: "מתאר מתפזר לחלקיקים" },
-  "3x3-grid-collage": { label: "קולאז' רשת 3x3", description: "מונטז' של 9 פוזות בסגנון contact sheet" },
   "matte-painting": { label: "Matte Painting", description: "רקע matte-painting מורכב מעורב עם צילום חי" },
   "double-exposure": { label: "חשיפה כפולה", description: "שתי חשיפות צילום שכבתיות מוזגות" },
   "multiple-exposure": { label: "חשיפה מרובה", description: "שלוש חשיפות או יותר מוערמות" },

package/src/i18n/composition-effects.hi.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "कोई नहीं", description: "कोई composition effect नहीं" },
   "bursting-through-frame": { label: "Frame से बाहर निकलता हुआ", description: "Frame को तोड़ता 3D paper-tear" },
   "breaking-out-of-frame": { label: "Frame से बाहर निकलना", description: "अंग canvas की सीमा से बाहर निकलता है" },
   "pixel-disintegration": { label: "Pixel Disintegration", description: "Subject कणों में घुलता हुआ" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments": { label: "तैरते टुकड़े", description: "बदन आंशिक रूप से दूर बहता हुआ" },
   "silhouette-outline": { label: "Silhouette की रेखा", description: "Flat BG पर साफ़ काला silhouette" },
   "exploding-particles": { label: "विस्फोटक कण", description: "रेखा कणों में बिखर रही है" },
-  "3x3-grid-collage": { label: "3x3 Grid Collage", description: "Contact-sheet 9-pose montage" },
 
   // -------------------- Round 2 --------------------
   "matte-painting": { label: "Matte Painting", description: "Live action के साथ blended composite matte-painted background" },

package/src/i18n/composition-effects.ja.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "なし", description: "構図エフェクトなし" },
   "bursting-through-frame": { label: "フレームを突き破る", description: "フレームを破る3D紙破り効果" },
   "breaking-out-of-frame": { label: "フレームから飛び出す", description: "手足がキャンバスの境界を越える" },
   "pixel-disintegration": { label: "ピクセル崩壊", description: "粒子に溶け込む被写体" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments": { label: "浮かぶ断片", description: "体が部分的に漂い去る" },
   "silhouette-outline": { label: "シルエットの輪郭", description: "フラットな背景上の真っ黒なシルエット" },
   "exploding-particles": { label: "爆発する粒子", description: "粒子に飛散する輪郭" },
-  "3x3-grid-collage": { label: "3×3グリッド・コラージュ", description: "コンタクトシート風の9ポーズモンタージュ" },
 
   // Additional composition effects
   "matte-painting": { label: "マットペインティング", description: "実写と合成されたマットペイントの背景" },

package/src/i18n/composition-effects.ko.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "없음", description: "구도 효과 없음" },
   "bursting-through-frame": { label: "프레임을 뚫고 나오기", description: "프레임을 찢고 나오는 3D 페이퍼-티어 효과입니다" },
   "breaking-out-of-frame": { label: "프레임 밖으로 나오기", description: "사지가 캔버스 경계 너머로 뻗어 나옵니다" },
   "pixel-disintegration": { label: "픽셀 디스인테그레이션", description: "피사체가 입자로 분해되어 흩어집니다" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments": { label: "플로팅 프래그먼츠", description: "몸이 부분적으로 떠다니며 흩어집니다" },
   "silhouette-outline": { label: "실루엣 아웃라인", description: "평면 배경 위의 깔끔한 검은 실루엣입니다" },
   "exploding-particles": { label: "익스플로딩 파티클", description: "윤곽이 입자로 흩뿌려집니다" },
-  "3x3-grid-collage": { label: "3x3 그리드 콜라주", description: "9 포즈 콘택트 시트 몽타주입니다" },
 
   // Additional composition effects
   "matte-painting": { label: "매트 페인팅", description: "라이브 액션과 합성된 매트 페인팅 배경입니다" },

package/src/i18n/composition-effects.pt-BR.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "Nenhum", description: "Sem efeito de composição" },
   "bursting-through-frame": { label: "Rompendo o Quadro", description: "Rasgo de papel 3D quebrando o quadro" },
   "breaking-out-of-frame": { label: "Saindo do Quadro", description: "Membro se estende além da borda do quadro" },
   "pixel-disintegration": { label: "Desintegração em Pixels", description: "Sujeito se dissolvendo em partículas" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments": { label: "Fragmentos Flutuando", description: "Corpo se afastando parcialmente em pedaços" },
   "silhouette-outline": { label: "Contorno em Silhueta", description: "Silhueta preta limpa sobre fundo plano" },
   "exploding-particles": { label: "Partículas Explodindo", description: "Contorno se desfazendo em partículas" },
-  "3x3-grid-collage": { label: "Colagem em Grade 3x3", description: "Folha-contato com 9 poses" },
   "matte-painting": { label: "Matte Painting", description: "Fundo composto em matte painting integrado a captação real" },
   "double-exposure": { label: "Dupla Exposição", description: "Duas exposições fotográficas sobrepostas e fundidas" },
   "multiple-exposure": { label: "Múltipla Exposição", description: "Três ou mais exposições empilhadas" },

package/src/i18n/composition-effects.ru.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "Нет", description: "Без композиционного эффекта" },
   "bursting-through-frame": {
     label: "Прорыв сквозь рамку",
     description: "3D-эффект разорванной бумаги, ломающий рамку",
@@ -53,10 +54,6 @@ const map: LocaleCatalogMap = {
     label: "Взрыв частиц",
     description: "Контур разлетается на частицы",
   },
-  "3x3-grid-collage": {
-    label: "Коллаж 3×3",
-    description: "Контактный лист из 9 поз",
-  },
   "matte-painting": {
     label: "Маттовая живопись",
     description: "Композитный нарисованный матовый фон, смешанный с живой съёмкой",

package/src/i18n/composition-effects.zh-CN.ts

@@ -1,6 +1,7 @@
 import type { LocaleCatalogMap } from "./types.js"
 
 const map: LocaleCatalogMap = {
+  "none": { label: "无", description: "无构图效果" },
   "bursting-through-frame":   { label: "撕纸破框",       description: "3D 撕纸效果冲破画框" },
   "breaking-out-of-frame":    { label: "破出画框",       description: "肢体伸出画布边缘" },
   "pixel-disintegration":     { label: "像素崩解",       description: "主体崩解为颗粒" },
@@ -14,7 +15,6 @@ const map: LocaleCatalogMap = {
   "floating-fragments":       { label: "漂浮碎片",       description: "身体部分飘散远去" },
   "silhouette-outline":       { label: "剪影轮廓",       description: "纯色背景上的干净黑剪影" },
   "exploding-particles":      { label: "粒子爆裂",       description: "轮廓向外炸成颗粒" },
-  "3x3-grid-collage":         { label: "3x3 网格拼贴",   description: "9 格姿势接触印样拼贴" },
   "matte-painting":           { label: "接景绘画",       description: "接景背景与实拍画面合成" },
   "double-exposure":          { label: "二次曝光",       description: "两层摄影曝光叠合" },
   "multiple-exposure":        { label: "多重曝光",       description: "三次或更多次曝光叠合" },

package/src/index.ts

@@ -912,7 +912,9 @@ export {
   describeNodeAdjustments,
 } from "./normalize-node-params.js"
 export type { NodeParamAdjustment, NormalizedNodes } from "./normalize-node-params.js"
-export { extractPresetData, PRESET_EXCLUDED_KEYS, PRESET_APPLY_CLEAR_KEYS, presetDataMatches } from "./node-preset-extract.js"
+export { extractPresetData, PRESET_EXCLUDED_KEYS, PRESET_APPLY_CLEAR_KEYS, presetApplyClearKeys, presetDataMatches } from "./node-preset-extract.js"
+export { PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY, readPromptAffixes } from "./prompt-affixes.js"
+export type { PromptAffixFields, PromptAffixes } from "./prompt-affixes.js"
 
 // --- Factory prompt-snippets (reusable inline prompt fragments) ---
 

package/src/node-preset-extract.ts

@@ -1,5 +1,6 @@
 import { EXECUTION_DATA_KEYS } from "./node-runtime-keys.js"
 import { COMPOSER_PLAN_FIELDS } from "./model-constants.js"
+import { PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY } from "./prompt-affixes.js"
 
 /**
  * Generated-plan state on composer nodes that a preset must NEITHER capture NOR
@@ -26,6 +27,43 @@ import { COMPOSER_PLAN_FIELDS } from "./model-constants.js"
  */
 export const PRESET_APPLY_CLEAR_KEYS: readonly string[] = [...COMPOSER_PLAN_FIELDS, "lottieUrl"]
 
+/**
+ * The three keys that carry a preset's PROMPT CONTENT: the prompt itself plus the pre/post text
+ * wrapped around it at run time. A preset "owns prompt content" iff its data defines any of them.
+ */
+const PROMPT_CONTENT_KEYS: readonly string[] = ["prompt", PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY]
+
+/**
+ * The keys applying THIS preset must clear on the node: always `PRESET_APPLY_CLEAR_KEYS`, plus
+ * `promptPrefix` / `promptSuffix` when the preset owns prompt content. The dropdown spreads
+ * `{ ...clearPatch, ...preset.data }`, so the preset's own affixes (if any) land back on top of
+ * the clear — the clear only decides what happens to the keys the preset does NOT set.
+ *
+ * The hazard this closes: with a STATIC clear set the affixes are named by no patch, so applying
+ * preset B (which ships only `prompt`) over a node carrying preset A's `promptPrefix` leaves A's
+ * prefix in place, silently wrapping B's prompt. The node then runs text no preset ever authored,
+ * and nothing in the UI attributes it — the prefix lives in a collapsed settings section.
+ *
+ * The rule is ASYMMETRIC on purpose, because the two directions have opposite promises:
+ *  - A preset that owns prompt content is authoring the whole prompt, affixes included, so any
+ *    leftover affix from a previous preset is stale — clear both.
+ *  - A settings-only preset (provider / aspect ratio / seed …) promises to touch nothing about the
+ *    prompt, so it leaves prompt AND affixes exactly as the user has them.
+ *  - `prompt` is NEVER cleared, only overwritten when the preset ships it. That is the feature's
+ *    core promise: apply a preset that ships only affixes and your typed prompt is kept, wrapped.
+ *
+ * Pure; `PRESET_APPLY_CLEAR_KEYS` itself stays a fixed set (it is also spread into
+ * `PRESET_EXCLUDED_KEYS`, and affixes must remain capture-INCLUDED for presets to ship them).
+ */
+export function presetApplyClearKeys(
+  presetData: Readonly<Record<string, unknown>>,
+): readonly string[] {
+  const ownsPromptContent = PROMPT_CONTENT_KEYS.some((k) => presetData[k] !== undefined)
+  return ownsPromptContent
+    ? [...PRESET_APPLY_CLEAR_KEYS, PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY]
+    : PRESET_APPLY_CLEAR_KEYS
+}
+
 /**
  * Config fields that are intentionally NOT part of a preset, because they are not portable
  * configuration — they identify the node on the canvas, wire it into one specific graph, or point

package/src/prompt-affixes.ts

@@ -0,0 +1,43 @@
+/**
+ * Prompt pre/post text ("affixes") — the PUBLIC node-data contract.
+ *
+ * Every AI prompt node may carry two optional strings that are wrapped around
+ * its run-time prompt: `promptPrefix` goes before, `promptSuffix` after. Both
+ * support `{Node Label}` references and plain-text snippets exactly like the
+ * main prompt. They are settings (edited in the node's config panel, captured
+ * by presets, settable through workflow JSON / `inputOverrides`), never shown
+ * on the node face or to published-app end users.
+ *
+ * Only the KEYS + TYPE live here (what the SDK/API contract needs). The wrap
+ * behaviour (`applyPromptAffixes`) lives in `@nodaro/prompts` next to
+ * `resolvePrompt` — see the spec's IP-placement note.
+ */
+export const PROMPT_PREFIX_KEY = "promptPrefix" as const
+export const PROMPT_SUFFIX_KEY = "promptSuffix" as const
+
+export interface PromptAffixFields {
+  /** Text placed BEFORE the node's prompt at run time. Supports {Node Label} refs. */
+  readonly promptPrefix?: string
+  /** Text placed AFTER the node's prompt at run time. Supports {Node Label} refs. */
+  readonly promptSuffix?: string
+}
+
+/** The affix pair read off node data (blank / non-string values are omitted). */
+export interface PromptAffixes {
+  readonly prefix?: string
+  readonly suffix?: string
+}
+
+function nonBlank(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim().length > 0 ? v : undefined
+}
+
+/** Read `{ prefix, suffix }` off a node's `data`. Never throws; unknown shapes → `{}`. */
+export function readPromptAffixes(data: Record<string, unknown>): PromptAffixes {
+  const prefix = nonBlank(data[PROMPT_PREFIX_KEY])
+  const suffix = nonBlank(data[PROMPT_SUFFIX_KEY])
+  return {
+    ...(prefix !== undefined ? { prefix } : {}),
+    ...(suffix !== undefined ? { suffix } : {}),
+  }
+}

package/src/video-analysis.ts

@@ -84,8 +84,20 @@ export type VideoAnalysisVisualEffect = (typeof VIDEO_ANALYSIS_VISUAL_EFFECTS)[n
  * `dissolve` (a cross-fade from one image to the other) is distinct from `fade`
  * (through black or white). Collapsing both onto `fade` — as this enum did — makes
  * a recreation render the wrong edit, and the two look nothing alike.
+ *
+ * ABSENT means NOTHING ASSERTED (since v2): the analyser emits a value only
+ * when it can see the device; an unknown or uncertain edit is left out so the
+ * video model chooses. `cut` is itself an assertion (an instant change between
+ * two clearly different shots), never a default.
  */
-export const VIDEO_ANALYSIS_TRANSITIONS = ["cut", "fade", "dissolve", "wipe", "whip"] as const
+export const VIDEO_ANALYSIS_TRANSITIONS = [
+  "cut", "fade", "dissolve", "wipe", "whip",
+  // v2 (2026-08-30, recast shot craft rev 1.5 Appendix F): the common edits a
+  // creator actually cuts with. `white-flash` / `digital-glitch` are spelled
+  // out because `flash` / `glitch` already name in-shot EFFECTS (the axis test
+  // below) — a device is the edit BETWEEN two shots, an effect is on one shot.
+  "zoom", "slide", "white-flash", "digital-glitch", "morph", "match", "jump",
+] as const
 export type VideoAnalysisTransition = (typeof VIDEO_ANALYSIS_TRANSITIONS)[number]
 
 /**