@nodaro/shared 1.13.1 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.13.1",
+  "version": "1.15.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__/gvp-supported-providers.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest"
+import { GVP_SUPPORTED_PROVIDERS, isGvpSupportedProvider, isSeedance2Provider } from "../model-constants.js"
+
+/**
+ * Generate/Edit Video Pro provider-selection guard (2026-07-21): the pro
+ * nodes offer ONLY these SKUs. The list is intentionally narrower than the
+ * SEEDANCE_2_PROVIDERS capability family (mini is a Seedance-2 variant for
+ * capability gating but is NOT offered by the pro engine). If a new SKU is
+ * blessed for the pro nodes, update this pin together with the docs pages
+ * (docs/nodes/ai-video/generate-video-pro.md, edit-video-pro.md).
+ */
+describe("GVP_SUPPORTED_PROVIDERS", () => {
+  it("is exactly the blessed pro SKUs", () => {
+    expect([...GVP_SUPPORTED_PROVIDERS]).toEqual(["seedance-2", "seedance-2-fast"])
+  })
+
+  it("is a strict subset of the Seedance-2 capability family", () => {
+    for (const p of GVP_SUPPORTED_PROVIDERS) {
+      expect(isSeedance2Provider(p)).toBe(true)
+    }
+    // mini stays in the family (capabilities) but out of pro selection
+    expect(isSeedance2Provider("seedance-2-mini")).toBe(true)
+    expect(isGvpSupportedProvider("seedance-2-mini")).toBe(false)
+  })
+
+  it("predicate matches the list and rejects outsiders", () => {
+    for (const p of GVP_SUPPORTED_PROVIDERS) expect(isGvpSupportedProvider(p)).toBe(true)
+    expect(isGvpSupportedProvider("veo3")).toBe(false)
+    expect(isGvpSupportedProvider(undefined)).toBe(false)
+  })
+})

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

@@ -3,6 +3,9 @@ import {
   windowAnalysisSchema, videoAnalysisResultSchema,
   deriveSlotRefs, rewriteSlotTokens, unwrapUnresolvedTokens,
   renderAnalyzedScene, isOversizedScene, aspectRatioFromDims,
+  entitySlotSchema, analyzedSceneSchema,
+  rewriteSceneBindings, dropUnknownBindings,
+  VIDEO_ANALYSIS_MAX_VARIATIONS, VIDEO_ANALYSIS_VARIATION_SLUGS, VIDEO_ANALYSIS_DEFAULT_VARIATION,
   type EntitySlot,
 } from "../video-analysis.js"
 
@@ -48,6 +51,103 @@ describe("token helpers", () => {
   })
 })
 
+const dreamVariation = {
+  variationId: "dream",
+  label: "Dream self",
+  description: "tan man, mustache — flowing white robe, barefoot, hair loose (dream sequences)",
+  refImageUrl: "https://cdn.example/frames/hero-dream.jpg",
+}
+
+describe("appearance variations (cast-variations spec §4)", () => {
+  it("entitySlotSchema round-trips variations[] including refImageUrl", () => {
+    const parsed = entitySlotSchema.parse({ ...slot, variations: [dreamVariation] })
+    expect(parsed.variations).toEqual([dreamVariation])
+  })
+  it("absent variations stays absent (no [] materialization)", () => {
+    const parsed = entitySlotSchema.parse(slot)
+    expect("variations" in parsed && parsed.variations !== undefined).toBe(false)
+  })
+  it(`rejects more than VIDEO_ANALYSIS_MAX_VARIATIONS (${4}) — window layer rejects, merge folds`, () => {
+    expect(VIDEO_ANALYSIS_MAX_VARIATIONS).toBe(4)
+    const five = ["dream", "flashback", "disguise", "era", "alt-1"].map((id) => ({ ...dreamVariation, variationId: id }))
+    expect(entitySlotSchema.safeParse({ ...slot, variations: five }).success).toBe(false)
+  })
+  it("rejects the reserved 'default' variationId inside variations[] (D9)", () => {
+    expect(VIDEO_ANALYSIS_DEFAULT_VARIATION).toBe("default")
+    expect(entitySlotSchema.safeParse({ ...slot, variations: [{ ...dreamVariation, variationId: "default" }] }).success).toBe(false)
+  })
+  it("rejects a malformed variationId (slug charset only; vocabulary is doctrine-enforced)", () => {
+    expect(entitySlotSchema.safeParse({ ...slot, variations: [{ ...dreamVariation, variationId: "Dream Look" }] }).success).toBe(false)
+    expect(VIDEO_ANALYSIS_VARIATION_SLUGS).toContain("dream")
+    expect(VIDEO_ANALYSIS_VARIATION_SLUGS).toContain("alt-2")
+  })
+  it("windowAnalysisSchema scenes round-trip slotVariations; absent stays absent", () => {
+    const bound = { ...baseScene, slotVariations: { hero: "dream" } }
+    const parsed = windowAnalysisSchema.parse({ slots: [{ ...slot, variations: [dreamVariation] }], scenes: [bound, baseScene] })
+    expect(parsed.scenes[0].slotVariations).toEqual({ hero: "dream" })
+    expect(parsed.scenes[1].slotVariations).toBeUndefined()
+  })
+  it("analyzedSceneSchema inherits slotVariations from the same base", () => {
+    const parsed = analyzedSceneSchema.parse({
+      ...baseScene, sceneNumber: 1, visualResolved: "a man juggles", slotRefs: ["hero"], slotVariations: { hero: "dream" },
+    })
+    expect(parsed.slotVariations).toEqual({ hero: "dream" })
+  })
+  it("videoAnalysisResultSchema full-document round-trip with both fields", () => {
+    const meta = { durationSec: 10, width: 1920, height: 1080, aspectRatio: "16:9" }
+    const doc = {
+      meta,
+      slots: [{ ...slot, variations: [dreamVariation] }],
+      scenes: [{ ...baseScene, sceneNumber: 1, visualResolved: "a man juggles", slotRefs: ["hero"], slotVariations: { hero: "dream" } }],
+    }
+    expect(videoAnalysisResultSchema.parse(doc)).toEqual(doc)
+  })
+})
+
+describe("variationFolds (cast-variations §4/§6 — review F5)", () => {
+  const meta = { durationSec: 10, width: 1920, height: 1080, aspectRatio: "16:9" }
+  const doc = {
+    meta,
+    slots: [slot],
+    scenes: [{ ...baseScene, sceneNumber: 1, visualResolved: "a man juggles", slotRefs: ["hero"] }],
+  }
+  it("videoAnalysisResultSchema round-trips variationFolds — strip-mode consumers keep the §6 fold note", () => {
+    const withFolds = { ...doc, variationFolds: [{ slotId: "hero", variationId: "era", label: "Era" }] }
+    expect(videoAnalysisResultSchema.parse(withFolds)).toEqual(withFolds)
+  })
+  it("absent variationFolds stays absent (no [] materialization)", () => {
+    const parsed = videoAnalysisResultSchema.parse(doc)
+    expect("variationFolds" in parsed && parsed.variationFolds !== undefined).toBe(false)
+  })
+})
+
+describe("binding rewrite helpers (merge consumes — spec §4)", () => {
+  it("rewriteSceneBindings renames slot keys and per-slot variation values", () => {
+    expect(rewriteSceneBindings({ "man-2": "dream", other: "era" }, { "man-2": "hero" }, { hero: { dream: "flashback" } }))
+      .toEqual({ hero: "flashback", other: "era" })
+  })
+  it("rewriteSceneBindings passes undefined through", () => {
+    expect(rewriteSceneBindings(undefined, { a: "b" })).toBeUndefined()
+  })
+  it("dropUnknownBindings drops unknown (slot, variation) pairs and reports them", () => {
+    const valid = new Map([["hero", new Set(["dream"])]])
+    const r = dropUnknownBindings({ hero: "dream", hero2: "dream", other: "ghost" }, valid)
+    expect(r.kept).toEqual({ hero: "dream" })
+    expect(r.dropped).toEqual([{ slotId: "hero2", variationId: "dream" }, { slotId: "other", variationId: "ghost" }])
+  })
+  it("dropUnknownBindings treats 'default' as always valid for a known slot", () => {
+    const valid = new Map([["hero", new Set<string>()]])
+    const r = dropUnknownBindings({ hero: "default" }, valid)
+    expect(r.kept).toEqual({ hero: "default" })
+    expect(r.dropped).toEqual([])
+  })
+  it("dropUnknownBindings returns kept: undefined when nothing survives (no {} materialization)", () => {
+    const r = dropUnknownBindings({ ghost: "dream" }, new Map())
+    expect(r.kept).toBeUndefined()
+    expect(r.dropped).toEqual([{ slotId: "ghost", variationId: "dream" }])
+  })
+})
+
 describe("misc", () => {
   it("isOversizedScene flags > 8s only", () => {
     expect(isOversizedScene(0, 8)).toBe(false)

package/src/index.ts

@@ -106,6 +106,8 @@ export {
   VIDEO_GEN_COLLAPSED_T2V_IDS,
   resolveVideoProviderForMode,
   isSeedance2Provider,
+  GVP_SUPPORTED_PROVIDERS,
+  isGvpSupportedProvider,
   defaultVideoAspectRatio,
   CHARACTER_MOTION_PROVIDERS,
   LOCATION_ATMOSPHERE_PROVIDERS,

package/src/model-constants.ts

@@ -1124,6 +1124,22 @@ export function isSeedance2Provider(provider: string | undefined): boolean {
   return !!provider && SEEDANCE_2_PROVIDERS.has(provider)
 }
 
+/**
+ * Generate/Edit Video Pro SUPPORT subset — the only SKUs the pro multi-segment
+ * engine currently offers (mini withdrawn from selection, 2026-07-21).
+ * Deliberately distinct from SEEDANCE_2_PROVIDERS: the family set gates
+ * CAPABILITIES (ref limits, i2v params, adaptive aspect) and must keep every
+ * variant; this list gates which SKUs the pro nodes offer in selection. The
+ * pro plugin routes stay tolerant of the full family so previously-saved
+ * workflows keep running — the editor fail-safe snaps stale selections to a
+ * supported SKU instead.
+ */
+export const GVP_SUPPORTED_PROVIDERS = ["seedance-2", "seedance-2-fast"] as const
+
+export function isGvpSupportedProvider(provider: string | undefined): boolean {
+  return !!provider && (GVP_SUPPORTED_PROVIDERS as readonly string[]).includes(provider)
+}
+
 /**
  * Default aspect ratio for a video provider when the node carries no explicit
  * `aspectRatio`. Seedance 2.x defaults to `"adaptive"` (output matches the

package/src/social-post.ts

@@ -6,7 +6,11 @@
  * on Instagram's carousel item limits.
  */
 
-/** Node types that publish to a social platform via POST /v1/social/publish. */
+/** Node types that publish to a social platform via POST /v1/social/publish.
+ *  The 7 per-platform nodes hardcode their platform via `node.type`;
+ *  `publish-social` is the UNIFIED node whose platform is derived from the
+ *  chosen connection (`data.platform`) instead. All shared-set-driven routing
+ *  (carousel accumulation, caption, refMap gate) covers it automatically. */
 export const SOCIAL_POST_NODE_TYPES = new Set([
   "instagram-post",
   "tiktok-post",
@@ -15,6 +19,7 @@ export const SOCIAL_POST_NODE_TYPES = new Set([
   "x-post",
   "facebook-post",
   "telegram-post",
+  "publish-social",
 ])
 
 /** Instagram carousel limits per Meta Graph API.

package/src/video-analysis.ts

@@ -25,12 +25,46 @@ export type VideoAnalysisEntitySource = (typeof VIDEO_ANALYSIS_ENTITY_SOURCES)[n
 /** Matches {slot:<id>} tokens. Distinct from NODE_REF_PATTERN / {image:N} grammars. */
 export const SLOT_TOKEN_RE = /\{slot:([a-z0-9-]+)\}/g
 
+/**
+ * Appearance variations (cast-variations spec, 2026-07-24): a slot's canonical
+ * `description` IS its default look; `variations` enumerates NON-default looks
+ * only (dream vs reality, flashback, disguise…). `"default"` is a reserved
+ * variationId — used in scene bindings / ledger keys / routing for unbound
+ * scenes, never inside `variations[]`. The closed slug vocabulary is
+ * doctrine-enforced (the schema pins only the id charset, like `role`);
+ * `alt-1`/`alt-2` are the escape hatches.
+ */
+export const VIDEO_ANALYSIS_VARIATION_SLUGS = ["dream", "flashback", "disguise", "costume", "transformation", "era", "alt-1", "alt-2"] as const
+/** Max NON-default looks per slot. The window layer REJECTS past the cap (schema-forced retry); the cross-window merge FOLDS at the cap. */
+export const VIDEO_ANALYSIS_MAX_VARIATIONS = 4
+export const VIDEO_ANALYSIS_DEFAULT_VARIATION = "default"
+
+export const slotVariationSchema = z.object({
+  variationId: z.string().min(1).regex(/^[a-z0-9-]+$/)
+    .refine((id) => id !== VIDEO_ANALYSIS_DEFAULT_VARIATION, { message: `"${VIDEO_ANALYSIS_DEFAULT_VARIATION}" is reserved for the slot's canonical look` }),
+  label: z.string().min(1),
+  /** Full STANDALONE casting-sheet look restating the slot's invariant identity
+   *  core (face, build, age) — the manifest substitutes it wholesale, so a
+   *  wardrobe-only delta would silently delete identity from the prompt. */
+  description: z.string().min(1),
+  /** Per-variation identity reference (auto-cast frame or user sheet). In the
+   *  schema from day one: every strip-mode round-trip must carry it. */
+  refImageUrl: z.string().url().optional(),
+})
+export type SlotVariation = z.infer<typeof slotVariationSchema>
+
 export const entitySlotSchema = z.object({
   slotId: z.string().min(1).regex(/^[a-z0-9-]+$/),
   label: z.string().min(1),
   source: z.enum(VIDEO_ANALYSIS_ENTITY_SOURCES),
   role: z.string().min(1),
   description: z.string().min(1),
+  /** Auto-cast visual reference — a hosted frame from the analyzed footage
+   *  where this entity is clearly visible. Optional/additive: producers may
+   *  omit it; consumers use it as an identity reference for recreation. */
+  refImageUrl: z.string().url().optional(),
+  /** NON-default looks only; present only when at least one exists. */
+  variations: z.array(slotVariationSchema).max(VIDEO_ANALYSIS_MAX_VARIATIONS).optional(),
 })
 export type EntitySlot = z.infer<typeof entitySlotSchema>
 
@@ -57,6 +91,11 @@ const windowSceneBase = z.object({
   transitionOut: z.enum(["cut", "fade", "wipe", "whip"]).optional(),
   // Array of concurrent layers (music + speech + sfx together); [] = silence.
   audio: z.array(audioLayerSchema),
+  /** slotId → variationId for slots wearing a NON-default look in this scene
+   *  (only slots referenced in the scene; absent key ⇒ the default look).
+   *  Rides windowSceneBase so BOTH the window layer and analyzedSceneSchema
+   *  inherit it — the out-of-band binding channel (no in-text markers, D6). */
+  slotVariations: z.record(z.string(), z.string()).optional(),
 })
 // .strip() (default) drops model-emitted oversized/slotRefs — validator-computed only.
 const windowSceneSchema = windowSceneBase.refine((s) => s.endSec > s.startSec, { message: "endSec must be > startSec" })
@@ -89,6 +128,16 @@ export const videoAnalysisResultSchema = z.object({
   }),
   slots: z.array(entitySlotSchema),
   scenes: z.array(analyzedSceneSchema).min(1),
+  /** CAST VARIATIONS (§4 cap handling): looks the analyzer's merge FOLDED into
+   *  the default at VIDEO_ANALYSIS_MAX_VARIATIONS — recorded, never silent. In
+   *  the wire schema so strip-mode consumers (the recast client's validated
+   *  blueprint view) keep it: the §6 "folded into default look" note is the
+   *  user's only pre-pay defense against a wrong split. */
+  variationFolds: z.array(z.object({
+    slotId: z.string(),
+    variationId: z.string(),
+    label: z.string(),
+  })).optional(),
 })
 export type VideoAnalysisResult = z.infer<typeof videoAnalysisResultSchema>
 
@@ -113,6 +162,46 @@ export function unwrapUnresolvedTokens(text: string, validIds: Set<string>): { t
   return { text: out, unresolved }
 }
 
+/**
+ * Rewrite a scene's `slotVariations` after cross-window slot/variation
+ * unification: slot keys map through `slotRenames`, then each variation value
+ * maps through `variationRenames[<new slotId>]`. Absent renames pass through.
+ */
+export function rewriteSceneBindings(
+  sv: Record<string, string> | undefined,
+  slotRenames: Record<string, string>,
+  variationRenames?: Record<string, Record<string, string>>,
+): Record<string, string> | undefined {
+  if (!sv) return undefined
+  const out: Record<string, string> = {}
+  for (const [slotId, variationId] of Object.entries(sv)) {
+    const newSlot = slotRenames[slotId] ?? slotId
+    out[newSlot] = variationRenames?.[newSlot]?.[variationId] ?? variationId
+  }
+  return out
+}
+
+/**
+ * Drop bindings whose (slotId, variationId) no longer exists after a merge —
+ * the unwrap-rule mirror: never persist a dangling binding, and report what
+ * was dropped so the caller can warn. `"default"` is always valid for a known
+ * slot. `kept` is undefined when nothing survives (no `{}` materialization).
+ */
+export function dropUnknownBindings(
+  sv: Record<string, string> | undefined,
+  validBySlot: Map<string, Set<string>>,
+): { kept?: Record<string, string>; dropped: Array<{ slotId: string; variationId: string }> } {
+  if (!sv) return { dropped: [] }
+  const kept: Record<string, string> = {}
+  const dropped: Array<{ slotId: string; variationId: string }> = []
+  for (const [slotId, variationId] of Object.entries(sv)) {
+    const valid = validBySlot.get(slotId)
+    if (valid && (variationId === VIDEO_ANALYSIS_DEFAULT_VARIATION || valid.has(variationId))) kept[slotId] = variationId
+    else dropped.push({ slotId, variationId })
+  }
+  return { kept: Object.keys(kept).length > 0 ? kept : undefined, dropped }
+}
+
 /** Substitute {slot:x}: castMap binding wins, else the slot's description, else literal id. */
 export function renderAnalyzedScene(scene: { visual: string }, slots: EntitySlot[], castMap?: Record<string, string>): string {
   const byId = new Map(slots.map((s) => [s.slotId, s]))