@nodaro/shared 3.27.0 → 3.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/dist/index.cjs +1050 -105
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +801 -46
  4. package/dist/index.d.ts +801 -46
  5. package/dist/index.js +950 -106
  6. package/dist/index.js.map +1 -1
  7. package/package.json +1 -1
  8. package/src/__tests__/entity-image-handle.test.ts +61 -1
  9. package/src/__tests__/json-kinds.test.ts +10 -0
  10. package/src/__tests__/model-seed-capability.test.ts +34 -0
  11. package/src/__tests__/node-preset-extract.test.ts +8 -0
  12. package/src/__tests__/node-run-routes.test.ts +63 -0
  13. package/src/__tests__/node-runtime-keys.test.ts +61 -0
  14. package/src/__tests__/pitch-tempo-pricing.test.ts +62 -0
  15. package/src/__tests__/presentation-utils.test.ts +14 -0
  16. package/src/__tests__/producer-types.test.ts +15 -0
  17. package/src/__tests__/render-nodes.test.ts +38 -4
  18. package/src/__tests__/seedance-draft.test.ts +74 -0
  19. package/src/__tests__/ugc-clip-saved-list.test.ts +19 -0
  20. package/src/__tests__/ugc-node-wires.test.ts +600 -0
  21. package/src/__tests__/ugc-run-state.test.ts +80 -3
  22. package/src/__tests__/video-depth.test.ts +146 -0
  23. package/src/__tests__/video-mask.test.ts +77 -0
  24. package/src/__tests__/workflow-export-strip.test.ts +14 -0
  25. package/src/credit-estimators/index.ts +10 -0
  26. package/src/credit-estimators/pitch-tempo.ts +68 -0
  27. package/src/credit-identifiers.ts +32 -7
  28. package/src/entity-image-handle.ts +48 -1
  29. package/src/fan-out-rows.ts +2 -0
  30. package/src/index.ts +15 -1
  31. package/src/json-kinds.ts +9 -0
  32. package/src/mask-composite.ts +108 -0
  33. package/src/model-catalog.ts +101 -2
  34. package/src/model-constants.ts +3 -0
  35. package/src/model-tree.ts +2 -0
  36. package/src/node-mappable-fields.ts +2 -0
  37. package/src/node-preset-export.ts +2 -2
  38. package/src/node-preset-extract.ts +6 -4
  39. package/src/node-run-routes.ts +76 -0
  40. package/src/node-runtime-keys.ts +42 -1
  41. package/src/presentation-utils.ts +6 -2
  42. package/src/producer-types.ts +19 -0
  43. package/src/render-nodes.ts +14 -5
  44. package/src/seedance-draft.ts +64 -0
  45. package/src/social-post.ts +13 -0
  46. package/src/ugc-node-wires.ts +623 -0
  47. package/src/ugc-run-state.ts +60 -5
  48. package/src/video-depth.ts +151 -0
  49. package/src/video-mask.ts +96 -0
  50. package/src/workflow-export.ts +3 -1
@@ -1,6 +1,9 @@
1
1
  import { describe, expect, it } from "vitest"
2
2
  import { LEGACY_EXPOSED_FIELD_KEYS } from "../exposed-field-keys.js"
3
- import { UGC_NODE_RUN_STATE_KEYS, UGC_NODE_TYPES, UGC_OVERRIDABLE_FIELDS, findUgcLockedFields, stripUgcRunState } from "../ugc-run-state.js"
3
+ import {
4
+ UGC_CREATOR_CANDIDATES_KEY, UGC_NODE_RUN_STATE_KEYS, UGC_NODE_TYPES, UGC_OVERRIDABLE_FIELDS, UGC_PICK_FIRST_MESSAGE, findUgcLockedFields, stripUgcRunState, ugcPickPending,
5
+ ugcRunWaitsForPick,
6
+ } from "../ugc-run-state.js"
4
7
 
5
8
  describe("UGC run state", () => {
6
9
  it("covers exactly the five UGC types", () => {
@@ -22,10 +25,10 @@ describe("UGC run state", () => {
22
25
 
23
26
  it("strips every run-state key and turns keepResult off, leaving choices and other nodes alone", () => {
24
27
  const nodes = [
25
- { id: "c", type: "ugc-creator", data: { source: "photo", gender: "man", keepResult: true, result: { v: 1 } } },
28
+ { id: "c", type: "ugc-creator", data: { source: "photo", gender: "man", photoUrl: "https://cdn.example/me.png", keepResult: true, result: { v: 1 } } },
26
29
  { id: "s", type: "ugc-script", data: { targetDurationSec: 20, keepResult: true, result: { v: 1 } } },
27
30
  { id: "l", type: "ugc-clips", data: { voiceId: "v", quote: { lines: [] }, result: {}, __listResults: ["{}"], ugcOutputs: { "plan-out": "{}" } } },
28
- { id: "k", type: "ugc-clip", data: { rerender: { "2": 1 }, warnings: ["x"], __listResults: ["u"], __listResultMeta: [], clipWarnings: [], durationSec: 9 } },
31
+ { id: "k", type: "ugc-clip", data: { rerender: { "2": 1 }, rerenderPending: { "2": true }, warnings: ["x"], __listResults: ["u"], __listResultMeta: [], clipWarnings: [], durationSec: 9 } },
29
32
  { id: "d", type: "ugc-cards", data: { result: { report: "No issues." } } },
30
33
  { id: "t", type: "text-prompt", data: { text: "keep", result: "keep" } },
31
34
  ]
@@ -42,6 +45,37 @@ describe("UGC run state", () => {
42
45
  expect(out[5]).toBe(nodes[5]) // other nodes are returned as they are
43
46
  })
44
47
 
48
+ it("never ships the author's own photo: a UGC Creator's photo goes, its source stays — a My photo run's image (that photo) too", () => {
49
+ const photo = "https://cdn.example/me.png"
50
+ // What a My photo run writes onto the creator: its image IS the photo (the creator wire names it).
51
+ const [creator] = stripUgcRunState([
52
+ {
53
+ id: "c",
54
+ type: "ugc-creator",
55
+ data: {
56
+ source: "photo",
57
+ gender: "woman",
58
+ photoUrl: photo,
59
+ generatedImageUrl: photo,
60
+ ugcOutputs: { creator: '{"v":1}', image: photo },
61
+ result: { v: 1, identityImages: [photo] },
62
+ executionStatus: "completed",
63
+ resultsRunId: "exec-1",
64
+ resultsRunEndedAt: "2026-10-09T09:00:40.000Z",
65
+ },
66
+ },
67
+ ])
68
+ expect(JSON.stringify(creator)).not.toContain(photo)
69
+ expect(creator!.data).not.toHaveProperty("generatedImageUrl")
70
+ expect(creator!.data).toMatchObject({ source: "photo", gender: "woman", keepResult: false })
71
+ })
72
+
73
+ it("no published creator carries the author's last image, whatever its source", () => {
74
+ expect(UGC_NODE_RUN_STATE_KEYS["ugc-creator"]).toContain("generatedImageUrl")
75
+ const [creator] = stripUgcRunState([{ id: "c", type: "ugc-creator", data: { source: "sampled", gender: "man", generatedImageUrl: "https://cdn.example/drawn.png" } }])
76
+ expect(creator!.data).toEqual({ source: "sampled", gender: "man", keepResult: false })
77
+ })
78
+
45
79
  it("leaves a UGC node with no data object alone", () => {
46
80
  const node = { id: "x", type: "ugc-clip" }
47
81
  expect(stripUgcRunState([node])).toEqual([node])
@@ -65,4 +99,47 @@ describe("UGC run state", () => {
65
99
  expect(findUgcLockedFields(null, { t: { text: "x" } })).toEqual([])
66
100
  expect(findUgcLockedFields([{ id: "c", type: "ugc-creator" }], undefined)).toEqual([])
67
101
  })
102
+
103
+ it("a creator's candidates are run state: stripped at publish and locked against a run's overrides", () => {
104
+ const nodes = [{ id: "c", type: "ugc-creator", data: { source: "sampled", gender: "woman", keepResult: false, candidates: [{ imageUrl: "https://cdn.example/a.png", record: { v: 1 } }] } }]
105
+ expect(UGC_NODE_RUN_STATE_KEYS["ugc-creator"]).toContain(UGC_CREATOR_CANDIDATES_KEY)
106
+ expect(stripUgcRunState(nodes)[0]!.data).toEqual({ source: "sampled", gender: "woman", keepResult: false })
107
+ expect(findUgcLockedFields(nodes, { c: { candidates: [] } })).toEqual([{ nodeId: "c", nodeType: "ugc-creator", field: "candidates" }])
108
+ })
109
+ })
110
+
111
+ describe("Pick a creator first", () => {
112
+ const option = { imageUrl: "https://cdn.example/a.png", record: { v: 1 } }
113
+ const creator = (candidates?: unknown) => ({ id: "c", type: "ugc-creator", data: { source: "sampled", ...(candidates ? { candidates } : {}) } })
114
+ it("options waiting: one or more stored on the node", () => {
115
+ expect(ugcPickPending(creator([option, option]).data)).toBe(true)
116
+ expect(ugcPickPending(creator([option]).data)).toBe(true)
117
+ expect(ugcPickPending(creator([]).data)).toBe(false)
118
+ expect(ugcPickPending(creator().data)).toBe(false)
119
+ })
120
+ it("a run that executes a creator with options waiting is refused; its own re-draw is not; other nodes never are", () => {
121
+ expect(ugcRunWaitsForPick([creator([option, option])])).toBe(true)
122
+ expect(ugcRunWaitsForPick([creator([option, option])], { redrawId: "c" })).toBe(false)
123
+ expect(ugcRunWaitsForPick([creator()])).toBe(false)
124
+ expect(ugcRunWaitsForPick([{ id: "x", type: "ugc-clips", data: { candidates: [option] } }])).toBe(false)
125
+ expect(UGC_PICK_FIRST_MESSAGE).toBe("Pick a creator first.")
126
+ })
127
+ it("the note of the last draw is run state", () => {
128
+ expect(UGC_NODE_RUN_STATE_KEYS["ugc-creator"]).toContain("optionFailed")
129
+ })
130
+ it("reads options only from a data object, and only a list counts", () => {
131
+ for (const data of [undefined, null, "candidates", [option], { candidates: { 0: option } }, { candidates: "x" }]) {
132
+ expect(ugcPickPending(data), JSON.stringify(data)).toBe(false)
133
+ }
134
+ expect(ugcRunWaitsForPick([])).toBe(false)
135
+ expect(ugcRunWaitsForPick([{ id: "c", type: null, data: { candidates: [option] } }, { id: "d" }])).toBe(false)
136
+ })
137
+ it("a second creator waiting is refused even while the first is re-drawn", () => {
138
+ const other = { ...creator([option]), id: "c2" }
139
+ expect(ugcRunWaitsForPick([creator([option, option]), other], { redrawId: "c" })).toBe(true)
140
+ })
141
+ it("the note of the last draw is stripped at publish", () => {
142
+ const nodes = [{ id: "c", type: "ugc-creator", data: { source: "sampled", gender: "woman", keepResult: false, optionFailed: true } }]
143
+ expect(stripUgcRunState(nodes)[0]!.data).toEqual({ source: "sampled", gender: "woman", keepResult: false })
144
+ })
68
145
  })
@@ -0,0 +1,146 @@
1
+ // packages/shared/src/__tests__/video-depth.test.ts
2
+ import { describe, expect, it } from "vitest"
3
+ import {
4
+ VIDEO_DEPTH_PROVIDERS,
5
+ FAL_VIDEO_DEPTH_PROVIDERS,
6
+ REPLICATE_VIDEO_DEPTH_PROVIDERS,
7
+ videoDepthLevers,
8
+ checkVideoDepthLength,
9
+ videoDepthCreditId,
10
+ videoDepthColormaps,
11
+ resolveVideoDepthColormap,
12
+ videoDepthNeedsGrayscalePass,
13
+ VIDEO_DEPTH_COLORMAPS,
14
+ VIDEO_DEPTH_LIMITS,
15
+ VIDEO_DEPTH_BUCKETS,
16
+ resolveVideoDepthProvider,
17
+ resolveVideoDepthModelSize,
18
+ } from "../video-depth.js"
19
+
20
+ describe("video-depth providers", () => {
21
+ it("partitions every provider into exactly one serving lane", () => {
22
+ for (const p of VIDEO_DEPTH_PROVIDERS) {
23
+ const lanes = [FAL_VIDEO_DEPTH_PROVIDERS.has(p), REPLICATE_VIDEO_DEPTH_PROVIDERS.has(p)].filter(Boolean)
24
+ expect(lanes).toHaveLength(1)
25
+ }
26
+ })
27
+ it("fal has all three levers, Replicate only colormap, unknown none", () => {
28
+ expect([...videoDepthLevers("video-depth-anything")].sort()).toEqual(["colormap", "resolution", "sideBySide"])
29
+ expect([...videoDepthLevers("depth-anything-frames")]).toEqual(["colormap"])
30
+ expect(videoDepthLevers("nope").size).toBe(0)
31
+ })
32
+ })
33
+
34
+ describe("videoDepthColormaps", () => {
35
+ it("fal offers all five in order, Replicate grayscale + inferno, unknown none", () => {
36
+ expect(videoDepthColormaps("video-depth-anything")).toEqual([...VIDEO_DEPTH_COLORMAPS])
37
+ expect(videoDepthColormaps("depth-anything-frames")).toEqual(["grayscale", "inferno"])
38
+ expect(videoDepthColormaps("nope")).toEqual([])
39
+ })
40
+ })
41
+
42
+ describe("resolveVideoDepthColormap", () => {
43
+ it("keeps a colormap the provider offers", () => {
44
+ expect(resolveVideoDepthColormap("video-depth-anything", "turbo")).toBe("turbo")
45
+ expect(resolveVideoDepthColormap("depth-anything-frames", "inferno")).toBe("inferno")
46
+ })
47
+ it("coerces an unsupported, missing or garbage value to grayscale", () => {
48
+ expect(resolveVideoDepthColormap("depth-anything-frames", "turbo")).toBe("grayscale")
49
+ expect(resolveVideoDepthColormap("depth-anything-frames", undefined)).toBe("grayscale")
50
+ expect(resolveVideoDepthColormap("video-depth-anything", 42)).toBe("grayscale")
51
+ })
52
+ it("returns undefined for a provider with no colormap lever", () => {
53
+ expect(resolveVideoDepthColormap("nope", "turbo")).toBeUndefined()
54
+ })
55
+ })
56
+
57
+ describe("videoDepthNeedsGrayscalePass", () => {
58
+ it("Replicate needs the pass unless inferno is chosen", () => {
59
+ expect(videoDepthNeedsGrayscalePass("depth-anything-frames", undefined)).toBe(true)
60
+ expect(videoDepthNeedsGrayscalePass("depth-anything-frames", "grayscale")).toBe(true)
61
+ expect(videoDepthNeedsGrayscalePass("depth-anything-frames", "inferno")).toBe(false)
62
+ })
63
+ it("fal never needs the pass", () => {
64
+ expect(videoDepthNeedsGrayscalePass("video-depth-anything", "grayscale")).toBe(false)
65
+ })
66
+ })
67
+
68
+ describe("checkVideoDepthLength", () => {
69
+ it("fal: exactly 2400 frames passes, 2401 rejects", () => {
70
+ expect(checkVideoDepthLength("video-depth-anything", { durationSec: 100, fps: 24 })).toEqual({ ok: true })
71
+ const r = checkVideoDepthLength("video-depth-anything", { durationSec: 100.01, fps: 24 })
72
+ expect(r.ok).toBe(false)
73
+ if (!r.ok) expect(r.message).toMatch(/2,401 frames.*2,400.*100 s at 24 fps/)
74
+ })
75
+ it("fal: unknown fps assumes 30 (80 s cap)", () => {
76
+ expect(checkVideoDepthLength("video-depth-anything", { durationSec: 80 })).toEqual({ ok: true })
77
+ const r = checkVideoDepthLength("video-depth-anything", { durationSec: 80.1 })
78
+ expect(r.ok).toBe(false)
79
+ if (!r.ok) expect(r.message).toMatch(/assumed 30 fps/)
80
+ })
81
+ it("fal: also capped at 300 s (the top price bucket), whatever the frame count", () => {
82
+ expect(VIDEO_DEPTH_LIMITS.FAL_MAX_SECONDS).toBe(300)
83
+ // 5 fps × 480 s = 2,400 frames: within the frame limit, over the seconds cap.
84
+ const long = checkVideoDepthLength("video-depth-anything", { durationSec: 480, fps: 5 })
85
+ expect(long.ok).toBe(false)
86
+ if (!long.ok) expect(long.message).toBe("Video is 480 s. This provider accepts at most 300 s. Trim the clip and run again.")
87
+ // 8 fps × 300 s = 2,400 frames: both limits met exactly.
88
+ expect(checkVideoDepthLength("video-depth-anything", { durationSec: 300, fps: 8 })).toEqual({ ok: true })
89
+ const over = checkVideoDepthLength("video-depth-anything", { durationSec: 300.5, fps: 1 })
90
+ expect(over.ok).toBe(false)
91
+ if (!over.ok) expect(over.message).toMatch(/^Video is 301 s\. This provider accepts at most 300 s\./)
92
+ })
93
+ it("replicate: seconds cap", () => {
94
+ expect(checkVideoDepthLength("depth-anything-frames", { durationSec: VIDEO_DEPTH_LIMITS.REPLICATE_MAX_SECONDS })).toEqual({ ok: true })
95
+ expect(checkVideoDepthLength("depth-anything-frames", { durationSec: 80.5 }).ok).toBe(false)
96
+ })
97
+ })
98
+
99
+ describe("videoDepthCreditId", () => {
100
+ it("buckets by duration, boundaries inclusive", () => {
101
+ expect(videoDepthCreditId("video-depth-anything", 5)).toBe("video-depth-anything:15s")
102
+ expect(videoDepthCreditId("video-depth-anything", 15)).toBe("video-depth-anything:15s")
103
+ expect(videoDepthCreditId("video-depth-anything", 15.01)).toBe("video-depth-anything:30s")
104
+ expect(videoDepthCreditId("depth-anything-frames", 61)).toBe("depth-anything-frames:120s")
105
+ expect(videoDepthCreditId("video-depth-anything", 299)).toBe("video-depth-anything:300s")
106
+ })
107
+ it("unknown, non-positive or over-cap duration prices the provider's highest REACHABLE bucket", () => {
108
+ // fal: capped at 300 s → the 300 s row.
109
+ expect(videoDepthCreditId("video-depth-anything", undefined)).toBe("video-depth-anything:300s")
110
+ expect(videoDepthCreditId("video-depth-anything", 0)).toBe("video-depth-anything:300s")
111
+ expect(videoDepthCreditId("video-depth-anything", 900)).toBe("video-depth-anything:300s")
112
+ // Replicate: capped at 80 s → the 120 s row; a longer clip is refused, so the 300 s row is unreachable.
113
+ expect(videoDepthCreditId("depth-anything-frames", undefined)).toBe("depth-anything-frames:120s")
114
+ expect(videoDepthCreditId("depth-anything-frames", -1)).toBe("depth-anything-frames:120s")
115
+ expect(videoDepthCreditId("depth-anything-frames", Number.NaN)).toBe("depth-anything-frames:120s")
116
+ expect(videoDepthCreditId("depth-anything-frames", 200)).toBe("depth-anything-frames:120s")
117
+ expect(videoDepthCreditId("depth-anything-frames", 80)).toBe("depth-anything-frames:120s")
118
+ })
119
+ it("derives each reachable ceiling from the limits: the smallest bucket at or above the provider's longest clip", () => {
120
+ const ceilingFor = (maxSec: number) => VIDEO_DEPTH_BUCKETS.find((b) => b >= maxSec)
121
+ expect(videoDepthCreditId("depth-anything-frames", undefined)).toBe(`depth-anything-frames:${ceilingFor(VIDEO_DEPTH_LIMITS.REPLICATE_MAX_SECONDS)}s`)
122
+ expect(videoDepthCreditId("video-depth-anything", undefined)).toBe(`video-depth-anything:${ceilingFor(VIDEO_DEPTH_LIMITS.FAL_MAX_SECONDS)}s`)
123
+ })
124
+ })
125
+
126
+ // Raw workflow JSON can carry any value; every layer that dispatches, denies or
127
+ // prices a run reads the SAME resolved provider, so none of them can drift.
128
+ describe("resolveVideoDepthProvider", () => {
129
+ it("keeps a known provider, resolves missing/unknown/non-string to the default", () => {
130
+ expect(resolveVideoDepthProvider("depth-anything-frames")).toBe("depth-anything-frames")
131
+ expect(resolveVideoDepthProvider("video-depth-anything")).toBe("video-depth-anything")
132
+ for (const raw of [undefined, null, "", "nope", "constructor", 42]) {
133
+ expect(resolveVideoDepthProvider(raw), String(raw)).toBe("video-depth-anything")
134
+ }
135
+ })
136
+ })
137
+
138
+ describe("resolveVideoDepthModelSize", () => {
139
+ it("keeps a known size, resolves anything else to large", () => {
140
+ expect(resolveVideoDepthModelSize("small")).toBe("small")
141
+ expect(resolveVideoDepthModelSize("base")).toBe("base")
142
+ for (const raw of [undefined, "huge", "constructor", 1]) {
143
+ expect(resolveVideoDepthModelSize(raw), String(raw)).toBe("large")
144
+ }
145
+ })
146
+ })
@@ -0,0 +1,77 @@
1
+ import { describe, it, expect } from "vitest"
2
+ import { readFileSync } from "node:fs"
3
+ import { resolve } from "node:path"
4
+ import {
5
+ VIDEO_MASK_LIMITS,
6
+ VIDEO_MASK_PROVIDERS,
7
+ resolveVideoMaskProvider,
8
+ videoMaskBilledSeconds,
9
+ videoMaskCreditId,
10
+ videoMaskCreditIds,
11
+ } from "../video-mask.js"
12
+ import { maskCompositeUnits } from "../mask-composite.js"
13
+
14
+ /** The priced length a run uses: billed seconds rounded up (lib/video-mask-length.ts). */
15
+ const rowFor = (sec: number, fps?: number) => videoMaskCreditId(Math.ceil(videoMaskBilledSeconds(sec, fps)))
16
+
17
+ describe("Video Mask pricing", () => {
18
+ // Repeated verbatim in docs/nodes/ai-video/video-mask.md → Worked examples.
19
+ it.each([
20
+ [4, 30, "sam-3.1-video:5s"],
21
+ [12, 24, "sam-3.1-video:15s"],
22
+ [10, 60, "sam-3.1-video:30s"],
23
+ [45, 30, "sam-3.1-video:60s"],
24
+ [100, 30, "sam-3.1-video:120s"],
25
+ ])("%s s at %s fps → %s", (sec, fps, row) => {
26
+ expect(rowFor(sec, fps)).toBe(row)
27
+ })
28
+
29
+ it("prices SAM 3 on its own rows (4 min at 30 fps → sam-3-video:240s)", () => {
30
+ expect(videoMaskCreditId(240, "sam-3")).toBe("sam-3-video:240s")
31
+ })
32
+
33
+ it("prices a clip at or under 30 fps at its own length, a faster one proportionally longer", () => {
34
+ expect(videoMaskBilledSeconds(10, 24)).toBe(10)
35
+ expect(videoMaskBilledSeconds(10, 30)).toBe(10)
36
+ expect(videoMaskBilledSeconds(10, 60)).toBe(20)
37
+ expect(videoMaskBilledSeconds(10, undefined)).toBe(10)
38
+ })
39
+
40
+ it("quotes an unknown length at the longest row and clamps past the cap", () => {
41
+ expect(videoMaskCreditId(undefined)).toBe("sam-3.1-video:300s")
42
+ expect(videoMaskCreditId(0)).toBe("sam-3.1-video:300s")
43
+ expect(videoMaskCreditId(500)).toBe("sam-3.1-video:300s")
44
+ expect(videoMaskCreditId(5)).toBe("sam-3.1-video:5s")
45
+ expect(videoMaskCreditId(5.01)).toBe("sam-3.1-video:10s")
46
+ expect(videoMaskCreditId(61)).toBe("sam-3.1-video:90s")
47
+ })
48
+
49
+ it("the last row covers exactly the longest clip a run accepts", () => {
50
+ for (const provider of VIDEO_MASK_PROVIDERS) {
51
+ expect(videoMaskCreditIds(provider).at(-1)).toBe(`${provider}-video:${VIDEO_MASK_LIMITS.MAX_BILLED_SEC}s`)
52
+ }
53
+ })
54
+
55
+ it("the doc's price table names every row", () => {
56
+ const doc = readFileSync(resolve(__dirname, "../../../../docs/nodes/ai-video/video-mask.md"), "utf8")
57
+ for (const provider of VIDEO_MASK_PROVIDERS) for (const id of videoMaskCreditIds(provider)) expect(doc).toContain(`\`${id}\``)
58
+ })
59
+
60
+ it("narrows unknown providers to the default", () => {
61
+ expect(resolveVideoMaskProvider("sam-3")).toBe("sam-3")
62
+ expect(resolveVideoMaskProvider("sam-3.1")).toBe("sam-3.1")
63
+ expect(resolveVideoMaskProvider("sam-9")).toBe("sam-3.1")
64
+ expect(resolveVideoMaskProvider(undefined)).toBe("sam-3.1")
65
+ })
66
+ })
67
+
68
+ describe("Mask Composite units", () => {
69
+ // Repeated in docs/nodes/processing-video/mask-composite.md (at the 10-credit row).
70
+ it.each([[3, 1], [5, 1], [10, 2], [10.0000001, 2], [61, 13], [300, 60]])("%s s → %s unit(s)", (sec, units) => {
71
+ expect(maskCompositeUnits(sec)).toBe(units)
72
+ })
73
+ it("an unknown length counts the 300 s cap (an upper bound); past the cap clamps", () => {
74
+ expect(maskCompositeUnits(undefined)).toBe(60)
75
+ expect(maskCompositeUnits(900)).toBe(60)
76
+ })
77
+ })
@@ -139,3 +139,17 @@ describe("stripExportContent — template export hygiene", () => {
139
139
  expect((outSub.data as Record<string, unknown>).referencedWorkflowId).toBeUndefined()
140
140
  })
141
141
  })
142
+
143
+ describe("stripExportContent — a type's own run results under generic names", () => {
144
+ it("strips UGC Clips' quote and UGC Clip's length from those types, and never another node's setting of the same name", () => {
145
+ const nodes: GenericNode[] = [
146
+ { id: "c", type: "ugc-clips", data: { label: "Clips", quote: { expected: 1 }, voiceId: "v" } },
147
+ { id: "k", type: "ugc-clip", data: { label: "Clip", durationSec: 7, clipWarnings: ["w"], rerenderPending: { 1: true }, rerender: { 1: 1 } } },
148
+ { id: "x", type: "some-future-node", data: { label: "Other", quote: "a quote to show", durationSec: 12 } },
149
+ ]
150
+ const [clips, clip, other] = stripExportContent(nodes)
151
+ expect(clips.data).toEqual({ label: "Clips", voiceId: "v" })
152
+ expect(clip.data).toEqual({ label: "Clip", rerender: { 1: 1 } })
153
+ expect(other.data).toEqual({ label: "Other", quote: "a quote to show", durationSec: 12 })
154
+ })
155
+ })
@@ -50,3 +50,13 @@ export {
50
50
  speechPriceUnits,
51
51
  speechCredits,
52
52
  } from "./speech.js"
53
+
54
+ export {
55
+ PITCH_TEMPO_PRICING,
56
+ PITCH_TEMPO_LIMITS,
57
+ pitchTempoStartedMinutes,
58
+ pitchTempoCreditId,
59
+ parsePitchTempoCreditId,
60
+ pitchTempoBaseCredits,
61
+ semitonesToPitchRatio,
62
+ } from "./pitch-tempo.js"
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Pitch & Tempo pricing — per STARTED minute of the input media (decided
3
+ * 2026-10-12), at least one minute, at most 30.
4
+ *
5
+ * One `model_pricing` row, `pitch-tempo`, holds the credits per minute; a run
6
+ * reserves `pitch-tempo:<N>m` (N = started minutes), which billing prices as
7
+ * that row × N — never a row of its own, so a retune of the rate row moves the
8
+ * route, the workflow run, the node's Run button and every estimate together.
9
+ * The same id is built by the route (from the probed length), the workflow run
10
+ * (the same probe) and the editor (the upstream length it knows).
11
+ *
12
+ * Worked examples at the row's listed rate of 20 (repeated in
13
+ * docs/nodes/processing-audio/pitch-tempo.md):
14
+ * 0:45 → 20, 1:00 → 20, 1:01 → 40, 3:10 → 80, 30:00 → 600.
15
+ */
16
+
17
+ export const PITCH_TEMPO_PRICING = {
18
+ /** The rate row: credits per started minute. Never reserved by itself. */
19
+ RATE_CREDIT_ID: "pitch-tempo",
20
+ /** The longest input a run accepts, in seconds (the route refuses longer). */
21
+ MAX_DURATION_SEC: 1800,
22
+ /** The most minutes a `pitch-tempo:<N>m` id can carry. */
23
+ MAX_MINUTES: 30,
24
+ /** The rate row's launch value (admin-retunable in /admin/models). */
25
+ CREDITS_PER_MINUTE_DEFAULT: 20,
26
+ } as const
27
+
28
+ /** The control ranges every surface validates against. */
29
+ export const PITCH_TEMPO_LIMITS = {
30
+ SEMITONES_MIN: -12,
31
+ SEMITONES_MAX: 12,
32
+ TEMPO_MIN: 0.5,
33
+ TEMPO_MAX: 2,
34
+ } as const
35
+
36
+ /**
37
+ * Started minutes of an input of `durationSec` seconds: ceil(sec / 60), at
38
+ * least 1, at most 30. An unknown or non-positive length counts as one minute
39
+ * (what the editor quotes before it knows the length; a run always measures).
40
+ */
41
+ export function pitchTempoStartedMinutes(durationSec: number | null | undefined): number {
42
+ if (typeof durationSec !== "number" || !Number.isFinite(durationSec) || durationSec <= 0) return 1
43
+ return Math.min(PITCH_TEMPO_PRICING.MAX_MINUTES, Math.max(1, Math.ceil(durationSec / 60)))
44
+ }
45
+
46
+ /** `pitch-tempo:<N>m` — the id a run on an input of `durationSec` seconds reserves. */
47
+ export function pitchTempoCreditId(durationSec: number | null | undefined): string {
48
+ return `pitch-tempo:${pitchTempoStartedMinutes(durationSec)}m`
49
+ }
50
+
51
+ /** The minutes of a `pitch-tempo:<N>m` id (1 ≤ N ≤ 30), or `undefined` for any other id. */
52
+ export function parsePitchTempoCreditId(id: string): { minutes: number } | undefined {
53
+ const m = /^pitch-tempo:(\d+)m$/.exec(id)
54
+ if (!m) return undefined
55
+ const minutes = Number(m[1])
56
+ if (!Number.isInteger(minutes) || minutes < 1 || minutes > PITCH_TEMPO_PRICING.MAX_MINUTES) return undefined
57
+ return { minutes }
58
+ }
59
+
60
+ /** rate × minutes, rounded up, at least 1 credit — what a `pitch-tempo:<N>m` id costs. */
61
+ export function pitchTempoBaseCredits(ratePerMinute: number, minutes: number): number {
62
+ return Math.max(1, Math.ceil(ratePerMinute * minutes))
63
+ }
64
+
65
+ /** The frequency ratio for a shift of `semitones` (12 = one octave up = ×2). */
66
+ export function semitonesToPitchRatio(semitones: number): number {
67
+ return 2 ** (semitones / 12)
68
+ }
@@ -718,14 +718,39 @@ export function applyEdlCreditId(quality: unknown): "apply-edl" | "apply-edl:pro
718
718
  }
719
719
 
720
720
  /**
721
- * The credit id of a Speaker View render (decided 2026-09-23, F4): a Preview
722
- * (`quality` "proxy") reserves on `speaker-view:proxy`, anything else on
723
- * `speaker-view`. The job is always named `speaker-view`; only its credit id
724
- * follows the quality, as Apply EDL's does. Ids only — no price is published
725
- * here, and none is set yet.
721
+ * Speaker View's price tiers (decided 2026-10-10, C4): a render is priced by
722
+ * how many speakers it composites at once. `standard` — at most two tiles on
723
+ * any segment and no zoom; `complex` — three to six tiles, or any zoom. Which
724
+ * tier a render is in is the render rule's to say (the app's
725
+ * `@nodaro/render-rules`), never this vocabulary's.
726
726
  */
727
- export function speakerViewCreditId(quality: unknown): "speaker-view" | "speaker-view:proxy" {
728
- return quality === "proxy" ? "speaker-view:proxy" : "speaker-view"
727
+ export const SPEAKER_VIEW_PRICE_TIERS = ["standard", "complex"] as const
728
+ export type SpeakerViewPriceTier = (typeof SPEAKER_VIEW_PRICE_TIERS)[number]
729
+
730
+ export type SpeakerViewCreditId = "speaker-view" | "speaker-view:proxy" | "speaker-view:complex" | "speaker-view:complex:proxy"
731
+
732
+ /** Every id `speakerViewCreditId` can name. */
733
+ export const SPEAKER_VIEW_CREDIT_IDS: readonly SpeakerViewCreditId[] = Object.freeze([
734
+ "speaker-view",
735
+ "speaker-view:proxy",
736
+ "speaker-view:complex",
737
+ "speaker-view:complex:proxy",
738
+ ] as const)
739
+
740
+ /**
741
+ * The credit id of a Speaker View render (F4, decided 2026-09-23; tiers
742
+ * decided 2026-10-10): a Preview (`quality` "proxy") reserves on its own row,
743
+ * anything else on the final's, and each in its price tier — `standard` on
744
+ * `speaker-view` / `speaker-view:proxy`, `complex` on `speaker-view:complex` /
745
+ * `speaker-view:complex:proxy`. A tier that is not exactly `standard` (absent
746
+ * included) names the `complex` row: a caller that cannot tell quotes high,
747
+ * never low. The job is always named `speaker-view`; only its credit id
748
+ * follows the quality and the tier.
749
+ */
750
+ export function speakerViewCreditId(quality: unknown, tier?: unknown): SpeakerViewCreditId {
751
+ const proxy = quality === "proxy"
752
+ if (tier === "standard") return proxy ? "speaker-view:proxy" : "speaker-view"
753
+ return proxy ? "speaker-view:complex:proxy" : "speaker-view:complex"
729
754
  }
730
755
 
731
756
  /**
@@ -63,6 +63,50 @@ const SCRAPER_HANDLE_EFFECTIVE_TYPE: Readonly<Record<string, string>> = {
63
63
  }
64
64
  const SCRAPER_SOURCE_TYPES = new Set(["meta-ads-scrape", "instagram-scrape"])
65
65
 
66
+ /**
67
+ * Output pips that emit a plain medium although their node is no producer of
68
+ * it: node type → pip → the canonical single-media producer the pip behaves
69
+ * as. A row here is NOT an identity remap (`ENTITY_IMAGE_HANDLE_TYPES`, which
70
+ * the identity gates and `sourceRefKey` read) and adds the node to no producer
71
+ * set: only a wire leaving THIS pip is that producer, so the node's other pips
72
+ * (UGC Creator's `creator` record) stay what they are. A frontend guard holds
73
+ * every row to a declared output drawn in that medium's colour.
74
+ *
75
+ * Both engines' input resolvers route a wire leaving one of these pips as the
76
+ * producer it names, and the editor's validators judge it the same way. A
77
+ * UGC wire input (a pip that reads one output of one UGC node) still judges
78
+ * the RAW node and pip, so a text pip keeps feeding the UGC input made for it.
79
+ */
80
+ export const OUTPUT_PIP_EFFECTIVE_TYPES: Readonly<Record<string, Readonly<Record<string, string>>>> = Object.freeze({
81
+ // UGC Creator's `image`: the creator's first image, for any image input.
82
+ "ugc-creator": Object.freeze({ image: "upload-image" }),
83
+ // The UGC nodes' plain-text pips — the script's product category, the clips'
84
+ // transcript, the cards' Notes — are one text each (`combine-text`: one
85
+ // string, not a list): they reach text and prompt inputs, never a JSON input.
86
+ "ugc-script": Object.freeze({ category: "combine-text" }),
87
+ "ugc-clips": Object.freeze({ transcript: "combine-text" }),
88
+ "ugc-cards": Object.freeze({ report: "combine-text" }),
89
+ })
90
+
91
+ const own = <T>(table: Readonly<Record<string, T>>, key: string): T | undefined =>
92
+ Object.hasOwn(table, key) ? table[key] : undefined
93
+
94
+ /**
95
+ * The source type a legacy-handle classifier judges an edge by: the raw node
96
+ * type, unless the edge leaves an `OUTPUT_PIP_EFFECTIVE_TYPES` pip. Only that
97
+ * table: the entity, aggregate and scraper remaps of `resolveEffectiveSourceType`
98
+ * keep the classifiers' rewiring of existing graphs as it was. Read by the
99
+ * editor's load-time pass and the server's write-time normalizer alike.
100
+ */
101
+ export function outputPipSourceType(
102
+ rawSourceType: string | undefined | null,
103
+ sourceHandleId: string | undefined | null,
104
+ ): string {
105
+ const type = rawSourceType ?? ""
106
+ const pips = own(OUTPUT_PIP_EFFECTIVE_TYPES, type)
107
+ return (pips && typeof sourceHandleId === "string" ? own(pips, sourceHandleId) : undefined) ?? type
108
+ }
109
+
66
110
  /**
67
111
  * The effective output TYPE a given source handle emits. Returns the raw node
68
112
  * type for every `(type, handle)` pair EXCEPT:
@@ -71,7 +115,8 @@ const SCRAPER_SOURCE_TYPES = new Set(["meta-ads-scrape", "instagram-scrape"])
71
115
  * lane's media type (see AGGREGATE_LANE_EFFECTIVE_TYPE);
72
116
  * - a Meta Ads `text` / `image` / `video` handle → the plain producer of
73
117
  * that type (see META_ADS_HANDLE_EFFECTIVE_TYPE); its `json` handle keeps
74
- * the raw type.
118
+ * the raw type;
119
+ * - an `OUTPUT_PIP_EFFECTIVE_TYPES` pip → the producer its row names.
75
120
  * Pure — safe for both frontend and backend.
76
121
  */
77
122
  export function resolveEffectiveSourceType(
@@ -81,6 +126,8 @@ export function resolveEffectiveSourceType(
81
126
  if (sourceHandleId === "image" && ENTITY_IMAGE_HANDLE_TYPES.has(rawSourceType ?? "")) {
82
127
  return "upload-image"
83
128
  }
129
+ const pipType = outputPipSourceType(rawSourceType, sourceHandleId)
130
+ if (pipType !== (rawSourceType ?? "")) return pipType
84
131
  if (AGGREGATE_LANE_SOURCE_TYPES.has(rawSourceType ?? "")) {
85
132
  const effective = AGGREGATE_LANE_EFFECTIVE_TYPE[sourceHandleId ?? ""]
86
133
  if (effective) return effective
@@ -43,6 +43,8 @@ export const NON_PROMPT_TEXT_LANES: Readonly<Record<string, "*" | readonly strin
43
43
  script: ["ai-avatar"],
44
44
  transcript: ["add-captions", "apply-edl", "edit-plan", "camera-switch", "speaker-view", "speaker-frames"],
45
45
  edl: ["apply-edl", "camera-switch", "speaker-view"],
46
+ // Speaker View's face tracks (Speaker Frames' descriptor): framing data, never a prompt.
47
+ tracks: ["speaker-view"],
46
48
  silence: ["edit-plan"],
47
49
  offsets: ["edit-plan"],
48
50
  qrText: ["image-overlay"],
package/src/index.ts CHANGED
@@ -304,6 +304,10 @@ export {
304
304
  speedRampCreditId,
305
305
  applyEdlCreditId,
306
306
  speakerViewCreditId,
307
+ SPEAKER_VIEW_CREDIT_IDS,
308
+ SPEAKER_VIEW_PRICE_TIERS,
309
+ type SpeakerViewPriceTier,
310
+ type SpeakerViewCreditId,
307
311
  sunoCreditType,
308
312
  SUNO_VERSION_CREDIT_KEYS,
309
313
  SUNO_VERSION_PRICED_OPERATIONS,
@@ -312,6 +316,7 @@ export {
312
316
  export type { NormalizedImageGen, PricedVideoSelection } from "./credit-identifiers.js"
313
317
 
314
318
  export * from "./credit-estimators/index.js"
319
+ export * from "./seedance-draft.js"
315
320
  export { extractVideoDurationFromNode, editPlanSourceDurationSec } from "./video-duration.js"
316
321
 
317
322
  export {
@@ -550,6 +555,7 @@ export {
550
555
  buildLipSyncCreditId,
551
556
  } from "./lip-sync-pricing.js"
552
557
  export type { LipSyncDurationBucket } from "./lip-sync-pricing.js"
558
+ export * from "./video-depth.js"
553
559
 
554
560
  export { isFlux2Model, FLUX2_RES_MP } from "./flux2-pricing.js"
555
561
  export type { Flux2Model } from "./flux2-pricing.js"
@@ -654,10 +660,13 @@ export {
654
660
 
655
661
  export {
656
662
  SOCIAL_POST_NODE_TYPES,
663
+ SOCIAL_POST_NODE_PLATFORM,
657
664
  INSTAGRAM_CAROUSEL_MIN_ITEMS,
658
665
  INSTAGRAM_CAROUSEL_MAX_ITEMS,
659
666
  } from "./social-post.js"
660
667
 
668
+ export { NODE_RUN_ROUTES, NODE_TYPES_WITHOUT_RUN_ROUTE, nodeRunRoute } from "./node-run-routes.js"
669
+
661
670
  export type {
662
671
  CommunityEntityType,
663
672
  CommunitySort,
@@ -1301,6 +1310,7 @@ export {
1301
1310
  getCreditRange,
1302
1311
  hasFeature,
1303
1312
  modelsWithFeature,
1313
+ modelTakesSeed,
1304
1314
  durationsByMode,
1305
1315
  resolutionOptionsByKind,
1306
1316
  aspectRatioOptionsByKind,
@@ -1647,7 +1657,7 @@ export {
1647
1657
  export type { VoiceChangerModel } from "./voice-changer-models.js"
1648
1658
 
1649
1659
  // --- Node presets ---
1650
- export { EXECUTION_DATA_KEYS, TRANSIENT_RUNTIME_KEYS, stripTransientRuntimeData } from "./node-runtime-keys.js"
1660
+ export { EXECUTION_DATA_KEYS, NODE_TYPE_EXECUTION_DATA_KEYS, TRANSIENT_RUNTIME_KEYS, executionDataKeysOf, isExecutionDataKey, stripTransientRuntimeData } from "./node-runtime-keys.js"
1651
1661
 
1652
1662
  // --- Execution node state (wire contract) ---
1653
1663
  export {
@@ -1703,6 +1713,8 @@ export * from "./audio-fx-presets.js"
1703
1713
  export * from "./supported-fonts.js"
1704
1714
  export * from "./image-overlay-layers.js"
1705
1715
  export * from "./video-overlay.js"
1716
+ export * from "./video-mask.js"
1717
+ export * from "./mask-composite.js"
1706
1718
  export * from "./image-overlay-shapes.js"
1707
1719
  export * from "./image-overlay-platforms.js"
1708
1720
  // --- Shot-sequence visual elements (text/shape/image; shared with backend Zod validation) ---
@@ -1829,3 +1841,5 @@ export * from "./telegram-channel.js"
1829
1841
  export * from "./ugc-run-state.js"
1830
1842
  // UGC builder call → the REST body of the public route it dispatches to (the canvas and the app run the builder's calls through it).
1831
1843
  export * from "./ugc-call-body.js"
1844
+ // UGC node wires: every UGC node's request body and outputs, one implementation for the orchestrator and the editor.
1845
+ export * from "./ugc-node-wires.js"