@nodaro/shared 1.4.1

package/src/__tests__/model-constants.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from "vitest"
+import {
+  VIDEO_MODEL_CAPS,
+  modelsForInputMode,
+  preferredInputModeForModel,
+  seedance2AudioLimitSec,
+  findSeedance2AudioOverLimit,
+} from "../model-constants.js"
+
+describe("seedance2AudioLimitSec", () => {
+  it("returns the verified 15.2s cap for seedance-2-fast (KIE r2v)", () => {
+    expect(seedance2AudioLimitSec("seedance-2-fast")).toBe(15.2)
+  })
+
+  it("returns null for providers without a verified cap (no false rejects)", () => {
+    expect(seedance2AudioLimitSec("seedance-2")).toBeNull() // non-fast limit unverified
+    expect(seedance2AudioLimitSec("minimax")).toBeNull()
+    expect(seedance2AudioLimitSec(undefined)).toBeNull()
+  })
+})
+
+describe("findSeedance2AudioOverLimit", () => {
+  it("flags the first reference audio over the cap", () => {
+    expect(findSeedance2AudioOverLimit("seedance-2-fast", [10, 16, 12])).toBe(16)
+  })
+
+  it("allows audio at or under the cap", () => {
+    expect(findSeedance2AudioOverLimit("seedance-2-fast", [10, 15.2])).toBeNull()
+    expect(findSeedance2AudioOverLimit("seedance-2-fast", [15.2])).toBeNull()
+  })
+
+  it("never rejects for providers without an enforced cap", () => {
+    expect(findSeedance2AudioOverLimit("seedance-2", [99])).toBeNull()
+    expect(findSeedance2AudioOverLimit("minimax", [99])).toBeNull()
+  })
+
+  it("ignores non-finite durations (probe failures) but still catches a real overage", () => {
+    expect(findSeedance2AudioOverLimit("seedance-2-fast", [NaN, 20])).toBe(20)
+    expect(findSeedance2AudioOverLimit("seedance-2-fast", [NaN])).toBeNull()
+  })
+})
+
+describe("modelsForInputMode", () => {
+  it("returns kling for first_frame", () => {
+    expect(modelsForInputMode("first_frame")).toContain("kling")
+  })
+
+  it("returns only kling-3-omni for multi_shot", () => {
+    const models = modelsForInputMode("multi_shot")
+    expect(models).toContain("kling-3-omni")
+    expect(models).not.toContain("veo3.1")
+    expect(models).not.toContain("hailuo-2.3-pro")
+  })
+
+  it("returns veo3.1 and seedance-2 for video_continuation", () => {
+    const models = modelsForInputMode("video_continuation")
+    expect(models).toContain("veo3.1")
+    expect(models).toContain("seedance-2")
+    expect(models).not.toContain("hailuo-2.3-pro")
+  })
+
+  it("returns the interpolation models (rife, topaz-apollo) for frame_interpolation", () => {
+    // Phase 1C registered RIFE + Topaz Apollo for Method 8 frame interpolation.
+    const models = modelsForInputMode("frame_interpolation")
+    expect(models).toContain("rife")
+    expect(models).toContain("topaz-apollo")
+  })
+})
+
+describe("preferredInputModeForModel", () => {
+  it("prefers ref_images for a multi-ref model (seedance-2)", () => {
+    expect(preferredInputModeForModel("seedance-2")).toBe("ref_images")
+  })
+
+  it("prefers ref_images for kling-3-omni", () => {
+    expect(preferredInputModeForModel("kling-3-omni")).toBe("ref_images")
+  })
+
+  it("falls back to first_frame for a keyframe-only model (kling-turbo)", () => {
+    expect(preferredInputModeForModel("kling-turbo")).toBe("first_frame")
+  })
+
+  it("never auto-selects first_last_frame even when the model supports it (minimax)", () => {
+    // minimax declares first_frame + first_last_frame; the animate stage does
+    // not implement paired keyframes yet, so first_frame must win.
+    expect(VIDEO_MODEL_CAPS["minimax"]!.inputModes).toContain("first_last_frame")
+    expect(preferredInputModeForModel("minimax")).toBe("first_frame")
+  })
+
+  it("returns undefined for an unregistered model so the caller keeps its default", () => {
+    expect(preferredInputModeForModel("seedance-2-fast")).toBeUndefined()
+    expect(preferredInputModeForModel("veo3")).toBeUndefined()
+  })
+
+  it("returns undefined for undefined input", () => {
+    expect(preferredInputModeForModel(undefined)).toBeUndefined()
+  })
+})
+
+describe("VIDEO_MODEL_CAPS shape", () => {
+  it("every model has a non-empty inputModes array", () => {
+    for (const [model, caps] of Object.entries(VIDEO_MODEL_CAPS)) {
+      expect(caps.inputModes.length, `${model} has empty inputModes`).toBeGreaterThan(0)
+    }
+  })
+
+  it("multi_shot models declare maxShotsPerCall", () => {
+    for (const [model, caps] of Object.entries(VIDEO_MODEL_CAPS)) {
+      if (caps.inputModes.includes("multi_shot")) {
+        expect(caps.maxShotsPerCall, `${model} multi_shot must declare maxShotsPerCall`).toBeDefined()
+      }
+    }
+  })
+
+  it("video_continuation models declare supportsVideoExtension: true", () => {
+    for (const [model, caps] of Object.entries(VIDEO_MODEL_CAPS)) {
+      if (caps.inputModes.includes("video_continuation")) {
+        expect(caps.supportsVideoExtension, `${model} video_continuation requires supportsVideoExtension`).toBe(true)
+      }
+    }
+  })
+})

package/src/__tests__/model-tree.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest"
+import { MODEL_CATALOG } from "../model-catalog.js"
+import { modelToNodeTarget, buildModelTree, searchModelVariants } from "../model-tree.js"
+
+describe("modelToNodeTarget", () => {
+  it("maps an enum image model to generate-image with a provider preset", () => {
+    expect(modelToNodeTarget("nano-banana")).toEqual({ nodeType: "generate-image", field: "provider", value: "nano-banana" })
+  })
+  it("maps suno ids to suno-generate via the model field with the catalog dataValue", () => {
+    expect(modelToNodeTarget("suno")).toEqual({ nodeType: "suno-generate", field: "model", value: "V4" })
+    expect(modelToNodeTarget("suno-v5")).toEqual({ nodeType: "suno-generate", field: "model", value: "V5" })
+    expect(modelToNodeTarget("suno-v5_5")).toEqual({ nodeType: "suno-generate", field: "model", value: "V5_5" })
+  })
+  // `elevenlabs-dubbing` is a single-provider utility whose id is NOT in any
+  // provider-enum array, so it exercises the modes fallback → bare node, no preset.
+  it("maps a single-provider utility to its node with no preset field", () => {
+    expect(modelToNodeTarget("elevenlabs-dubbing")).toEqual({ nodeType: "dubbing" })
+  })
+  // `gemini-omni-video` IS a valid provider-enum value (member of both
+  // IMAGE_TO_VIDEO_PROVIDERS and TEXT_TO_VIDEO_PROVIDERS), so it resolves via the
+  // ENUM_TARGETS path to a provider preset — not the modes fallback (that path is
+  // exercised by `elevenlabs-dubbing` above).
+  it("returns a provider preset for an enum video model (gemini-omni-video is enum-valid)", () => {
+    expect(modelToNodeTarget("gemini-omni-video")).toEqual({ nodeType: "generate-video", field: "provider", value: "gemini-omni-video" })
+  })
+  it("returns null when there is no node (voice-clone) or unknown id", () => {
+    expect(modelToNodeTarget("voice-clone")).toBeNull()
+    expect(modelToNodeTarget("totally-unknown")).toBeNull()
+  })
+  it("never targets suno-generate without a model value (every music model carries dataValue)", () => {
+    const bare = Object.values(MODEL_CATALOG)
+      .filter((m) => {
+        const t = modelToNodeTarget(m.id)
+        return t?.nodeType === "suno-generate" && t.value == null
+      })
+      .map((m) => m.id)
+    expect(bare).toEqual([])
+  })
+})
+
+describe("buildModelTree", () => {
+  const tree = buildModelTree()
+  const withSeries = (Object.values(MODEL_CATALOG) as Array<{ series?: string }>).filter((m) => m.series)
+  it("covers nearly every series-annotated model and renders no empty folder", () => {
+    const variants = tree.reduce((n, l) => n + l.models.length, 0)
+    expect(variants).toBeGreaterThanOrEqual(withSeries.length - 1)
+    for (const line of tree) expect(line.models.length).toBeGreaterThan(0)
+  })
+  it("series completeness: every node-creatable model declares a series", () => {
+    const missing = (Object.values(MODEL_CATALOG) as Array<{ id: string; series?: string }>)
+      .filter((m) => modelToNodeTarget(m.id) && (!m.series || !m.series.trim()))
+      .map((m) => m.id)
+    expect(missing).toEqual([])
+  })
+  it("keeps ElevenLabs as one line and Flux Kontext inside Flux", () => {
+    expect(tree.filter((l) => l.series === "ElevenLabs")).toHaveLength(1)
+    const flux = tree.find((l) => l.series === "Flux")
+    expect(flux?.models.some((m) => m.label.toLowerCase().includes("kontext"))).toBe(true)
+    expect(tree.some((l) => l.series.toLowerCase().includes("kontext"))).toBe(false)
+  })
+})
+
+describe("searchModelVariants", () => {
+  const treeIds = new Set(buildModelTree().flatMap((l) => l.models).map((m) => m.id))
+
+  it("returns [] for a blank query", () => {
+    expect(searchModelVariants("")).toEqual([])
+    expect(searchModelVariants("   ")).toEqual([])
+  })
+  it("matches by label or id, case-insensitive", () => {
+    const hits = searchModelVariants("FLUX")
+    expect(hits.length).toBeGreaterThan(0)
+    expect(hits.every((m) => m.label.toLowerCase().includes("flux") || m.id.toLowerCase().includes("flux"))).toBe(true)
+  })
+  it("narrows to a single kind when given one", () => {
+    const broad = searchModelVariants("a")
+    const imageOnly = searchModelVariants("a", "image")
+    expect(broad.length).toBeGreaterThan(0)
+    expect(imageOnly.length).toBeGreaterThan(0)
+    expect(imageOnly.every((m) => m.kind === "image")).toBe(true)
+    expect(imageOnly.length).toBeLessThanOrEqual(broad.length)
+  })
+  it("only returns node-creatable variants (subset of buildModelTree)", () => {
+    expect(searchModelVariants("a").every((m) => treeIds.has(m.id))).toBe(true)
+  })
+})

package/src/__tests__/no-internal-imports.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest"
+import { readFileSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+
+/**
+ * License-boundary guard: @nodaro/shared is published under Apache-2.0 and
+ * bundles everything it imports — an import from @nodaro/prompts
+ * (Nodaro SUL) would republish proprietary creative/prompt IP under Apache.
+ * Source files must never cross this boundary (tests excluded: not bundled).
+ */
+function walk(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const p = join(dir, name)
+    if (statSync(p).isDirectory()) return name === "__tests__" ? [] : walk(p)
+    return p.endsWith(".ts") ? [p] : []
+  })
+}
+
+describe("Apache boundary", () => {
+  it("no shared source file imports @nodaro/prompts", () => {
+    const offenders = walk(join(__dirname, ".."))
+      .filter((f) => /from\s+["']@nodaro\/prompts["']/.test(readFileSync(f, "utf8")))
+    expect(offenders).toEqual([])
+  })
+})

package/src/__tests__/node-default-mappings.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from "vitest"
+import {
+  NODE_DEFAULT_TYPES,
+  mapQuality,
+  mapAspectRatio,
+  supportedDefaultDimensions,
+  deriveLinkedFields,
+  validateProviderForNodeType,
+  getTargetField,
+  getValidValues,
+} from "../node-default-mappings.js"
+
+describe("supportedDefaultDimensions", () => {
+  it("image gen has both quality and aspect", () => {
+    expect(supportedDefaultDimensions("generate-image")).toEqual({
+      quality: true,
+      aspectRatio: true,
+    })
+  })
+
+  it("video gen has both quality and aspect", () => {
+    expect(supportedDefaultDimensions("text-to-video")).toEqual({
+      quality: true,
+      aspectRatio: true,
+    })
+  })
+
+  it("LLM nodes have neither", () => {
+    expect(supportedDefaultDimensions("ai-writer")).toEqual({
+      quality: false,
+      aspectRatio: false,
+    })
+  })
+
+  it("audio nodes have neither", () => {
+    expect(supportedDefaultDimensions("text-to-speech")).toEqual({
+      quality: false,
+      aspectRatio: false,
+    })
+    expect(supportedDefaultDimensions("voice-design")).toEqual({
+      quality: false,
+      aspectRatio: false,
+    })
+  })
+
+  it("lip-sync has neither", () => {
+    expect(supportedDefaultDimensions("lip-sync")).toEqual({
+      quality: false,
+      aspectRatio: false,
+    })
+  })
+})
+
+describe("mapQuality", () => {
+  it("maps nano-banana-pro 3 levels onto resolution", () => {
+    expect(mapQuality("nano-banana-pro", "low")).toEqual({ field: "resolution", value: "1K" })
+    expect(mapQuality("nano-banana-pro", "mid")).toEqual({ field: "resolution", value: "2K" })
+    expect(mapQuality("nano-banana-pro", "high")).toEqual({ field: "resolution", value: "4K" })
+  })
+
+  it("collapses gpt-image low to medium on the quality field", () => {
+    expect(mapQuality("gpt-image", "low")).toEqual({ field: "quality", value: "medium" })
+    expect(mapQuality("gpt-image", "mid")).toEqual({ field: "quality", value: "medium" })
+    expect(mapQuality("gpt-image", "high")).toEqual({ field: "quality", value: "high" })
+  })
+
+  it("flux caps at 2K on the resolution field", () => {
+    expect(mapQuality("flux", "low")).toEqual({ field: "resolution", value: "1K" })
+    expect(mapQuality("flux", "mid")).toEqual({ field: "resolution", value: "2K" })
+    expect(mapQuality("flux", "high")).toEqual({ field: "resolution", value: "2K" })
+  })
+
+  it("gpt-image-2 maps to resolution (NOT quality) — its config panel uses 1K/2K/4K", () => {
+    expect(mapQuality("gpt-image-2", "low")).toEqual({ field: "resolution", value: "1K" })
+    expect(mapQuality("gpt-image-2", "mid")).toEqual({ field: "resolution", value: "2K" })
+    expect(mapQuality("gpt-image-2", "high")).toEqual({ field: "resolution", value: "4K" })
+  })
+
+  it("seedream uses basic/high on the quality field", () => {
+    expect(mapQuality("seedream", "low")).toEqual({ field: "quality", value: "basic" })
+    expect(mapQuality("seedream", "mid")).toEqual({ field: "quality", value: "basic" })
+    expect(mapQuality("seedream", "high")).toEqual({ field: "quality", value: "high" })
+  })
+
+  it("returns undefined for providers not in the map", () => {
+    expect(mapQuality("not-a-real-provider", "high")).toBeUndefined()
+  })
+})
+
+describe("mapAspectRatio", () => {
+  it("auto returns undefined (caller omits the field)", () => {
+    expect(mapAspectRatio("nano-banana-pro", "auto")).toBeUndefined()
+  })
+
+  it("16:9 passes through for known providers", () => {
+    expect(mapAspectRatio("nano-banana-pro", "16:9")).toBe("16:9")
+    expect(mapAspectRatio("kling", "16:9")).toBe("16:9")
+  })
+
+  it("returns the same value even for unknown providers (no fallback yet)", () => {
+    expect(mapAspectRatio("unknown", "1:1")).toBe("1:1")
+  })
+})
+
+describe("deriveLinkedFields", () => {
+  it("derives model for generate-image with nano-banana-pro", () => {
+    expect(deriveLinkedFields("generate-image", "nano-banana-pro")).toEqual({
+      model: "gemini-2.5-flash-image",
+    })
+  })
+
+  it("returns empty for unmapped providers", () => {
+    expect(deriveLinkedFields("generate-image", "flux")).toEqual({})
+  })
+
+  it("returns empty for nodes without linked fields", () => {
+    expect(deriveLinkedFields("ai-writer", "claude-sonnet-4.6")).toEqual({})
+    expect(deriveLinkedFields("text-to-video", "kling")).toEqual({})
+  })
+})
+
+describe("validateProviderForNodeType", () => {
+  it("accepts valid image gen provider", () => {
+    expect(validateProviderForNodeType("generate-image", "nano-banana-pro")).toBeNull()
+    expect(validateProviderForNodeType("generate-image", "flux")).toBeNull()
+  })
+
+  it("rejects invalid image gen provider", () => {
+    expect(validateProviderForNodeType("generate-image", "fake-provider")).toMatch(/not valid/)
+  })
+
+  it("accepts valid LLM model", () => {
+    expect(validateProviderForNodeType("ai-writer", "claude-sonnet-4.6")).toBeNull()
+  })
+
+  it("rejects invalid LLM model", () => {
+    expect(validateProviderForNodeType("ai-writer", "fake-model")).toMatch(/not valid/)
+  })
+
+  it("accepts both suno and minimax for music", () => {
+    expect(validateProviderForNodeType("generate-music", "suno")).toBeNull()
+    expect(validateProviderForNodeType("generate-music", "minimax")).toBeNull()
+  })
+})
+
+describe("getTargetField", () => {
+  it("image/video/audio/lip-sync use provider field", () => {
+    expect(getTargetField("generate-image")).toBe("provider")
+    expect(getTargetField("text-to-video")).toBe("provider")
+    expect(getTargetField("text-to-speech")).toBe("provider")
+    expect(getTargetField("lip-sync")).toBe("provider")
+  })
+
+  it("LLM nodes and voice-design use model field", () => {
+    expect(getTargetField("ai-writer")).toBe("model")
+    expect(getTargetField("voice-design")).toBe("model")
+  })
+})
+
+describe("registry coverage", () => {
+  it("every NODE_DEFAULT_TYPE has a registry entry", () => {
+    for (const t of NODE_DEFAULT_TYPES) {
+      expect(getValidValues(t).length).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe("llm-chat (merged Generate Text node)", () => {
+  it("llm-chat is a model-field node mirroring ai-writer", () => {
+    expect(getTargetField("llm-chat")).toBe("model")
+    expect(validateProviderForNodeType("llm-chat", "claude-sonnet-4.6")).toBeNull()
+    expect(validateProviderForNodeType("llm-chat", "fake-model")).toMatch(/not valid/)
+    expect(deriveLinkedFields("llm-chat", "claude-sonnet-4.6")).toEqual({})
+  })
+})

package/src/__tests__/node-mappable-fields.test.ts

@@ -0,0 +1,7 @@
+import { describe, it, expect } from "vitest"
+import { NODE_MAPPABLE_FIELDS } from "../node-mappable-fields.js"
+describe("NODE_MAPPABLE_FIELDS creature", () => {
+  it("maps creature to its name + description (mirrors object)", () => {
+    expect(NODE_MAPPABLE_FIELDS["creature"]).toEqual(["creatureName", "description"])
+  })
+})

package/src/__tests__/node-preset-export.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest"
+import {
+  buildNodePresetExport,
+  parseNodePresetExport,
+  NODE_PRESET_EXPORT_KIND,
+} from "../node-preset-export.js"
+
+describe("node preset export/import", () => {
+  it("builds a versioned envelope", () => {
+    const env = buildNodePresetExport(
+      [{ nodeType: "generate-image", name: "X", data: { prompt: "a" } }],
+      "2026-06-05T00:00:00.000Z",
+    )
+    expect(env.kind).toBe(NODE_PRESET_EXPORT_KIND)
+    expect(env.version).toBe(1)
+    expect(env.exportedAt).toBe("2026-06-05T00:00:00.000Z")
+    expect(env.presets).toHaveLength(1)
+  })
+
+  it("parses a valid envelope and strips runtime keys from data", () => {
+    const parsed = parseNodePresetExport({
+      kind: NODE_PRESET_EXPORT_KIND,
+      version: 1,
+      exportedAt: "2026-06-05T00:00:00.000Z",
+      presets: [
+        { nodeType: "generate-image", name: "X", data: { prompt: "a", generatedResults: [1] } },
+      ],
+    })
+    expect(parsed.presets[0].data).toEqual({ prompt: "a" }) // runtime key stripped
+  })
+
+  it("rejects wrong kind / version / shape", () => {
+    expect(() => parseNodePresetExport({ kind: "nope", version: 1, presets: [] })).toThrow()
+    expect(() =>
+      parseNodePresetExport({ kind: NODE_PRESET_EXPORT_KIND, version: 2, presets: [] }),
+    ).toThrow()
+    expect(() => parseNodePresetExport(null)).toThrow()
+    expect(() =>
+      parseNodePresetExport({
+        kind: NODE_PRESET_EXPORT_KIND,
+        version: 1,
+        presets: [{ name: "no type", data: {} }],
+      }),
+    ).toThrow()
+  })
+})

package/src/__tests__/node-preset-extract.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from "vitest"
+import { EXECUTION_DATA_KEYS } from "../node-runtime-keys.js"
+import {
+  extractPresetData,
+  PRESET_EXCLUDED_KEYS,
+  PRESET_APPLY_CLEAR_KEYS,
+  presetDataMatches,
+} from "../node-preset-extract.js"
+
+describe("EXECUTION_DATA_KEYS", () => {
+  it("is non-empty and contains known result keys", () => {
+    expect(EXECUTION_DATA_KEYS.size).toBeGreaterThan(20)
+    for (const k of ["generatedResults", "currentJobId", "executionStatus", "activeResultIndex"]) {
+      expect(EXECUTION_DATA_KEYS.has(k)).toBe(true)
+    }
+  })
+})
+
+describe("extractPresetData", () => {
+  it("keeps config fields, drops runtime + label + fieldMappings", () => {
+    const out = extractPresetData({
+      label: "My Node",
+      prompt: "a cat",
+      provider: "nano-banana",
+      aspectRatio: "16:9",
+      negativePrompt: "",
+      seed: 0,
+      expandPrompt: false,
+      fieldMappings: { prompt: "node_3" },
+      generatedResults: [{ url: "x" }],
+      currentJobId: "job_1",
+      executionStatus: "completed",
+      activeResultIndex: 2,
+    })
+    expect(out).toEqual({
+      prompt: "a cat",
+      provider: "nano-banana",
+      aspectRatio: "16:9",
+      negativePrompt: "",
+      seed: 0,
+      expandPrompt: false,
+    })
+  })
+
+  it("preserves empty/false/zero values so apply reproduces saved state", () => {
+    const out = extractPresetData({ a: "", b: false, c: 0, d: null })
+    expect(out).toEqual({ a: "", b: false, c: 0, d: null })
+  })
+
+  it("excludes every EXECUTION_DATA_KEYS member", () => {
+    const input: Record<string, unknown> = { keep: 1 }
+    for (const k of EXECUTION_DATA_KEYS) input[k] = "runtime"
+    const out = extractPresetData(input)
+    expect(out).toEqual({ keep: 1 })
+  })
+
+  it("does not mutate its input", () => {
+    const input = { prompt: "x", label: "y" }
+    extractPresetData(input)
+    expect(input).toEqual({ prompt: "x", label: "y" })
+  })
+
+  it("PRESET_EXCLUDED_KEYS contains label, fieldMappings, and __activePresetId", () => {
+    expect(PRESET_EXCLUDED_KEYS.has("label")).toBe(true)
+    expect(PRESET_EXCLUDED_KEYS.has("fieldMappings")).toBe(true)
+    expect(PRESET_EXCLUDED_KEYS.has("__activePresetId")).toBe(true)
+  })
+
+  it("excludes the UI-only __promptFinalView field (per-field final-view toggle state)", () => {
+    expect(PRESET_EXCLUDED_KEYS.has("__promptFinalView")).toBe(true)
+    const out = extractPresetData({ prompt: "x", __promptFinalView: ["prompt"] })
+    expect(out).toEqual({ prompt: "x" })
+  })
+
+  it("drops graph-topology + DB-reference fields but keeps manual reference urls", () => {
+    const out = extractPresetData({
+      prompt: "a",
+      // manual, self-contained inputs — KEEP
+      referenceImageUrl: "https://r2/x.png",
+      referenceImageUrls: [{ id: "t1", url: "https://r2/y.png" }],
+      // graph wiring / DB references / identity — DROP
+      referenceImageOrder: ["t1"],
+      referenceOrder: ["t1"],
+      connectedMediaOrder: ["n2"],
+      connectedRefImageOrder: ["n3"],
+      characterDefinitionIds: ["char-1"],
+      suppressedCanonicalCharacterIds: ["char-2"],
+      suppressedCanonicalLocationIds: ["loc-1"],
+      identityMeta: [{ imageIndex: 0, label: "x" }],
+      extraRefs: [{ url: "https://r2/z.png", characterSlug: "@bob" }],
+    })
+    expect(out).toEqual({
+      prompt: "a",
+      referenceImageUrl: "https://r2/x.png",
+      referenceImageUrls: [{ id: "t1", url: "https://r2/y.png" }],
+    })
+  })
+
+  it("drops structural identifiers (router routes, sub-workflow ports, teleport channel)", () => {
+    const out = extractPresetData({
+      mode: "radio", // router non-structural config — KEEP
+      routes: [{ id: "default_a", name: "Route A", active: true }],
+      routeId: "r1",
+      routeIds: ["r1", "r2"],
+      ports: [{ id: "p1", name: "Input", mediaType: "any" }],
+      inputPorts: [{ id: "p2" }],
+      outputPorts: [{ id: "p3" }],
+      channel: "A",
+      channelColor: "#f59e0b",
+    })
+    expect(out).toEqual({ mode: "radio" })
+  })
+
+  it("drops generated composer-plan state (motionPlan + lottieUrl) but keeps the prompt", () => {
+    const out = extractPresetData({
+      motionPrompt: "x",
+      engine: "lottie",
+      motionPlan: { layers: [{ ind: 1 }], slots: {} },
+      lottieUrl: "https://r2.example/lottie/abc.json",
+    })
+    expect(out).toEqual({ motionPrompt: "x", engine: "lottie" })
+  })
+
+  it("excludes every generated composer-plan field for all composer node types", () => {
+    const input: Record<string, unknown> = { keep: 1 }
+    // every plan field (sceneGraph/effectPlan/overlayPlan/titlePlan/motionPlan/compositePlan) + lottieUrl
+    for (const k of PRESET_APPLY_CLEAR_KEYS) input[k] = "generated"
+    expect(extractPresetData(input)).toEqual({ keep: 1 })
+  })
+})
+
+describe("PRESET_EXCLUDED_KEYS ⊇ PRESET_APPLY_CLEAR_KEYS", () => {
+  it("every clear-on-apply key is also capture-excluded (one source covers save + import + override)", () => {
+    for (const k of PRESET_APPLY_CLEAR_KEYS) {
+      expect(PRESET_EXCLUDED_KEYS.has(k), `${k} must be capture-excluded`).toBe(true)
+    }
+  })
+})
+
+describe("presetDataMatches", () => {
+  it("true when every preset key matches the node value (extra node keys ignored)", () => {
+    expect(
+      presetDataMatches(
+        { prompt: "a", provider: "flux", seed: 5, __activePresetId: "x" },
+        { prompt: "a", provider: "flux" },
+      ),
+    ).toBe(true)
+  })
+
+  it("false when a preset-defined key differs", () => {
+    expect(presetDataMatches({ prompt: "b", provider: "flux" }, { prompt: "a", provider: "flux" })).toBe(false)
+  })
+
+  it("false when a preset key is missing on the node", () => {
+    expect(presetDataMatches({ prompt: "a" }, { prompt: "a", provider: "flux" })).toBe(false)
+  })
+
+  it("deep-compares nested arrays/objects", () => {
+    expect(presetDataMatches({ refs: [{ url: "u" }] }, { refs: [{ url: "u" }] })).toBe(true)
+    expect(presetDataMatches({ refs: [{ url: "u" }] }, { refs: [{ url: "v" }] })).toBe(false)
+  })
+
+  it("empty preset data matches anything", () => {
+    expect(presetDataMatches({ prompt: "a" }, {})).toBe(true)
+  })
+})