@nodaro/shared 3.30.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 (36) hide show
  1. package/dist/index.cjs +733 -93
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +501 -36
  4. package/dist/index.d.ts +501 -36
  5. package/dist/index.js +673 -94
  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__/presentation-utils.test.ts +14 -0
  15. package/src/__tests__/producer-types.test.ts +15 -0
  16. package/src/__tests__/seedance-draft.test.ts +74 -0
  17. package/src/__tests__/ugc-clip-saved-list.test.ts +19 -0
  18. package/src/__tests__/ugc-node-wires.test.ts +600 -0
  19. package/src/__tests__/ugc-run-state.test.ts +80 -3
  20. package/src/__tests__/workflow-export-strip.test.ts +14 -0
  21. package/src/entity-image-handle.ts +48 -1
  22. package/src/index.ts +8 -1
  23. package/src/json-kinds.ts +9 -0
  24. package/src/model-catalog.ts +61 -2
  25. package/src/model-constants.ts +3 -0
  26. package/src/node-preset-export.ts +2 -2
  27. package/src/node-preset-extract.ts +6 -4
  28. package/src/node-run-routes.ts +76 -0
  29. package/src/node-runtime-keys.ts +42 -1
  30. package/src/presentation-utils.ts +3 -0
  31. package/src/producer-types.ts +10 -0
  32. package/src/seedance-draft.ts +64 -0
  33. package/src/social-post.ts +13 -0
  34. package/src/ugc-node-wires.ts +623 -0
  35. package/src/ugc-run-state.ts +60 -5
  36. 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
  })
@@ -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
+ })
@@ -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
package/src/index.ts CHANGED
@@ -316,6 +316,7 @@ export {
316
316
  export type { NormalizedImageGen, PricedVideoSelection } from "./credit-identifiers.js"
317
317
 
318
318
  export * from "./credit-estimators/index.js"
319
+ export * from "./seedance-draft.js"
319
320
  export { extractVideoDurationFromNode, editPlanSourceDurationSec } from "./video-duration.js"
320
321
 
321
322
  export {
@@ -659,10 +660,13 @@ export {
659
660
 
660
661
  export {
661
662
  SOCIAL_POST_NODE_TYPES,
663
+ SOCIAL_POST_NODE_PLATFORM,
662
664
  INSTAGRAM_CAROUSEL_MIN_ITEMS,
663
665
  INSTAGRAM_CAROUSEL_MAX_ITEMS,
664
666
  } from "./social-post.js"
665
667
 
668
+ export { NODE_RUN_ROUTES, NODE_TYPES_WITHOUT_RUN_ROUTE, nodeRunRoute } from "./node-run-routes.js"
669
+
666
670
  export type {
667
671
  CommunityEntityType,
668
672
  CommunitySort,
@@ -1306,6 +1310,7 @@ export {
1306
1310
  getCreditRange,
1307
1311
  hasFeature,
1308
1312
  modelsWithFeature,
1313
+ modelTakesSeed,
1309
1314
  durationsByMode,
1310
1315
  resolutionOptionsByKind,
1311
1316
  aspectRatioOptionsByKind,
@@ -1652,7 +1657,7 @@ export {
1652
1657
  export type { VoiceChangerModel } from "./voice-changer-models.js"
1653
1658
 
1654
1659
  // --- Node presets ---
1655
- 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"
1656
1661
 
1657
1662
  // --- Execution node state (wire contract) ---
1658
1663
  export {
@@ -1836,3 +1841,5 @@ export * from "./telegram-channel.js"
1836
1841
  export * from "./ugc-run-state.js"
1837
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).
1838
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"
package/src/json-kinds.ts CHANGED
@@ -28,6 +28,7 @@
28
28
  * expects a Transcript, an `edl` pip an EDL.
29
29
  */
30
30
  import { RENDER_JSON_HANDLE, RENDER_NODE_TYPES, type RenderNodeDescriptor } from "./render-nodes.js"
31
+ import { UGC_PRIMARY_HANDLE } from "./ugc-node-wires.js"
31
32
 
32
33
  /** The two JSON shapes the platform's handle vocabulary tells apart. */
33
34
  export type JsonKind = "transcript" | "edl"
@@ -83,6 +84,14 @@ const JSON_OUTPUT_KINDS: Readonly<Record<string, JsonOutputs>> = Object.freeze({
83
84
  "competitor-read": { primary: "json", pips: { json: "other" } },
84
85
  // Describe to Picker: the picker values read off an image.
85
86
  "describe-to-picker": { primary: "picker-json", pips: { "picker-json": "other" } },
87
+ // The UGC video nodes: their own versioned JSON (a creator record, a plan, the
88
+ // clip tickets, the sized plan), and UGC Cards' layer plan and caption plan.
89
+ // Their text pips (category, transcript, report) are not JSON pips. The pip an
90
+ // edge with no `sourceHandle` reads is the UGC wires' own (UGC_PRIMARY_HANDLE).
91
+ "ugc-creator": { primary: UGC_PRIMARY_HANDLE["ugc-creator"], pips: { creator: "other" } },
92
+ "ugc-script": { primary: UGC_PRIMARY_HANDLE["ugc-script"], pips: { plan: "other" } },
93
+ "ugc-clips": { primary: UGC_PRIMARY_HANDLE["ugc-clips"], pips: { clips: "other", "plan-out": "other" } },
94
+ "ugc-cards": { primary: UGC_PRIMARY_HANDLE["ugc-cards"], pips: { layerPlan: "other", captionPlan: "other" } },
86
95
  })
87
96
 
88
97
  /** The input pips whose kind is fixed by the handle vocabulary. */
@@ -28,6 +28,7 @@
28
28
  * `docs/choosing-models.md` guide. CI (`gen:skills:check`) fails on drift.
29
29
  */
30
30
 
31
+ import { isSeedanceDraftCapable, SEEDANCE_DRAFT_RESOLUTION } from "./seedance-draft.js"
31
32
  import { isFlux2Model } from "./flux2-pricing.js"
32
33
  import { isAutoVideoDuration } from "./video-duration-auto.js"
33
34
 
@@ -237,6 +238,15 @@ export interface ModelCatalogEntry {
237
238
  * the longest clip and settled on the delivered one.
238
239
  */
239
240
  autoDuration?: boolean
241
+ /**
242
+ * The model takes NO seed: its provider schema has none, so a seed the
243
+ * request carries is dropped before the provider call and repeat runs vary.
244
+ * Absent means a seed is forwarded as usual. Read through
245
+ * {@link modelTakesSeed} — the editor hides its Seed field off it and clears
246
+ * a stale `data.seed` when the provider switches. Pinned to the KIE configs'
247
+ * `omitSeed` in both directions by `seed-capability-parity.test.ts`.
248
+ */
249
+ noSeed?: boolean
240
250
  pricing: readonly PriceVariant[]
241
251
  /** Editorial highlight — "best in tier". Surfaces in MCP output as a ⭐. */
242
252
  featured?: boolean
@@ -1776,6 +1786,8 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
1776
1786
  defaultDuration: 8,
1777
1787
  autoDuration: true,
1778
1788
  resolutions: ["480p", "720p", "1080p"],
1789
+ // KIE refuses a seed on Seedance 2.5 (422) — the provider config omits it.
1790
+ noSeed: true,
1779
1791
  pricing: [
1780
1792
  { identifier: "seedance-2-5", credits: 1260, note: "default 8s 720p — see :Ns:res variants for exact" },
1781
1793
  { identifier: "seedance-2-5:8s:480p", credits: 560, note: "8s 480p" },
@@ -2093,6 +2105,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
2093
2105
  durations: [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
2094
2106
  defaultDuration: 5,
2095
2107
  resolutions: ["720p", "1080p"],
2108
+ noSeed: true, // HappyHorse 1.1 dropped `seed` from its schema
2096
2109
  pricing: [
2097
2110
  { identifier: "happyhorse", credits: 282, note: "5s 720p default — per-second: ~5.7 cr/s @720p, ~7.3 cr/s @1080p" },
2098
2111
  ],
@@ -2109,6 +2122,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
2109
2122
  durations: [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
2110
2123
  defaultDuration: 5,
2111
2124
  resolutions: ["720p", "1080p"],
2125
+ noSeed: true, // HappyHorse 1.1 dropped `seed` from its schema
2112
2126
  pricing: [
2113
2127
  { identifier: "happyhorse-i2v", credits: 282, note: "5s 720p default — per-second: ~5.7 cr/s @720p, ~7.3 cr/s @1080p" },
2114
2128
  ],
@@ -2127,6 +2141,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
2127
2141
  defaultDuration: 5,
2128
2142
  resolutions: ["720p", "1080p"],
2129
2143
  features: ["reference-image"],
2144
+ noSeed: true, // HappyHorse 1.1 dropped `seed` from its schema
2130
2145
  pricing: [
2131
2146
  { identifier: "happyhorse-ref2v", credits: 282, note: "5s 720p default — per-second: ~5.7 cr/s @720p, ~7.3 cr/s @1080p" },
2132
2147
  ],
@@ -2292,6 +2307,27 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
2292
2307
  useCases: ["upscale", "high-res"],
2293
2308
  pricing: [{ identifier: "veo-4k", credits: 380 }],
2294
2309
  },
2310
+ // Seedance 2.5 Draft finalize (seedance-draft.ts): re-renders a Seedance 2.5
2311
+ // DRAFT as the same take at 1080p. Priced per output second of the draft; a
2312
+ // draft made with a reference VIDEO bills its `-ref` rate on input + output
2313
+ // seconds. Only works on a completed Seedance 2.5 draft.
2314
+ "seedance-2-5-hd": {
2315
+ id: "seedance-2-5-hd",
2316
+ kind: "video",
2317
+ modes: ["video-upscale"] as const,
2318
+ family: "Bytedance",
2319
+ label: "Seedance 2.5 HD (from draft)",
2320
+ series: "Seedance",
2321
+ description: "Finalize a Seedance 2.5 draft: the same take, frame for frame, re-rendered at 1080p.",
2322
+ useCases: ["upscale", "high-res"],
2323
+ pricing: [
2324
+ { identifier: "seedance-2-5-hd", credits: 3160, note: "default 8s — see :Ns variants for exact" },
2325
+ { identifier: "seedance-2-5-hd:4s", credits: 1580, note: "4s draft" },
2326
+ { identifier: "seedance-2-5-hd:8s", credits: 3160, note: "8s draft" },
2327
+ { identifier: "seedance-2-5-hd:30s", credits: 11850, note: "30s draft (max)" },
2328
+ { identifier: "seedance-2-5-hd:8s-ref", credits: 1900, note: "per-second rate of a draft made with a reference video; billed on input + output seconds" },
2329
+ ],
2330
+ },
2295
2331
  "topaz-video": {
2296
2332
  id: "topaz-video",
2297
2333
  kind: "video",
@@ -3685,7 +3721,7 @@ export interface NormalizedVideoRequest {
3685
3721
  */
3686
3722
  export function normalizeVideoRequestParams(
3687
3723
  modelId: string,
3688
- input: { aspectRatio?: string; resolution?: string },
3724
+ input: { aspectRatio?: string; resolution?: string; draft?: boolean },
3689
3725
  ): NormalizedVideoRequest {
3690
3726
  const m = MODEL_CATALOG[modelId]
3691
3727
  // Seeded from the COERCED tokens, never the raw input: this function's own
@@ -3694,8 +3730,21 @@ export function normalizeVideoRequestParams(
3694
3730
  // `1080` or `[]` verbatim would break that promise at exactly the sites that
3695
3731
  // must agree on one value.
3696
3732
  const aspect = readOptionToken(input.aspectRatio)
3697
- const res = readOptionToken(input.resolution)
3733
+ const requestedRes = readOptionToken(input.resolution)
3734
+ // Seedance Draft renders at 480p only (the provider rejects anything else),
3735
+ // so a draft is PRICED and SENT at 480p whatever resolution came with it — an
3736
+ // agent, an import or a FieldMapping can pair `draft` with 720p, and the
3737
+ // reservation must not follow the stale value. An omitted resolution is a
3738
+ // fill, not a correction, so it reports nothing.
3739
+ const draft = input.draft === true && isSeedanceDraftCapable(modelId)
3740
+ const res = draft ? SEEDANCE_DRAFT_RESOLUTION : requestedRes
3698
3741
  const out: NormalizedVideoRequest = { aspectRatio: aspect, resolution: res, adjustments: [] }
3742
+ if (draft && requestedRes !== undefined && requestedRes.toLowerCase() !== SEEDANCE_DRAFT_RESOLUTION) {
3743
+ out.adjustments.push({
3744
+ field: "resolution", from: requestedRes, to: SEEDANCE_DRAFT_RESOLUTION,
3745
+ reason: `A Seedance draft renders at ${SEEDANCE_DRAFT_RESOLUTION} only — using "${SEEDANCE_DRAFT_RESOLUTION}" instead of "${requestedRes}". Finalize the draft to get the same take at 1080p.`,
3746
+ })
3747
+ }
3699
3748
  if (!m) return out
3700
3749
 
3701
3750
  if (m.aspectRatios?.length && aspect && !PASSTHROUGH_ASPECT_TOKENS.has(aspect.toLowerCase())) {
@@ -3829,6 +3878,16 @@ export function hasFeature(modelId: string, feature: string): boolean {
3829
3878
  return MODEL_CATALOG[modelId]?.features?.includes(feature) ?? false
3830
3879
  }
3831
3880
 
3881
+ /**
3882
+ * Whether a seed on this model does anything — false only for a catalog entry
3883
+ * that declares `noSeed`. An unknown or missing id answers true, so a surface
3884
+ * never hides a Seed field for a model it knows nothing about.
3885
+ */
3886
+ export function modelTakesSeed(modelId: string | undefined): boolean {
3887
+ if (!modelId) return true
3888
+ return MODEL_CATALOG[modelId]?.noSeed !== true
3889
+ }
3890
+
3832
3891
  /**
3833
3892
  * All ids in the catalog whose `features` includes the given flag. Used by
3834
3893
  * frontend to build PROVIDERS_WITH_END_FRAME / PROVIDERS_WITH_REFERENCES
@@ -1107,6 +1107,9 @@ export const VIDEO_UPSCALE_PROVIDERS = [
1107
1107
  "topaz",
1108
1108
  "veo-1080p",
1109
1109
  "veo-4k",
1110
+ // Seedance 2.5 Draft finalize: re-renders a Seedance 2.5 DRAFT (by its task
1111
+ // id) as the same take at 1080p. See seedance-draft.ts.
1112
+ "seedance-2-5-hd",
1110
1113
  ] as const
1111
1114
  export type VideoUpscaleProvider = typeof VIDEO_UPSCALE_PROVIDERS[number]
1112
1115
 
@@ -39,7 +39,7 @@ export function buildNodePresetExport(
39
39
  kind: NODE_PRESET_EXPORT_KIND,
40
40
  version: 1,
41
41
  exportedAt: exportedAtIso,
42
- presets: presets.map((p) => ({ ...p, data: extractPresetData(p.data) })),
42
+ presets: presets.map((p) => ({ ...p, data: extractPresetData(p.data, p.nodeType) })),
43
43
  }
44
44
  }
45
45
 
@@ -51,6 +51,6 @@ export function parseNodePresetExport(input: unknown): NodePresetExport {
51
51
  const parsed = envelopeSchema.parse(input)
52
52
  return {
53
53
  ...parsed,
54
- presets: parsed.presets.map((p) => ({ ...p, data: extractPresetData(p.data) })),
54
+ presets: parsed.presets.map((p) => ({ ...p, data: extractPresetData(p.data, p.nodeType) })),
55
55
  }
56
56
  }
@@ -1,4 +1,4 @@
1
- import { EXECUTION_DATA_KEYS } from "./node-runtime-keys.js"
1
+ import { isExecutionDataKey } from "./node-runtime-keys.js"
2
2
  import { COMPOSER_PLAN_FIELDS } from "./model-constants.js"
3
3
  import { PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY } from "./prompt-affixes.js"
4
4
 
@@ -172,15 +172,17 @@ export const PRESET_EXCLUDED_KEYS: ReadonlySet<string> = new Set([
172
172
 
173
173
  /**
174
174
  * Capture a node's reusable configuration from its `data`: a shallow copy minus runtime/result
175
- * state (EXECUTION_DATA_KEYS) and graph/identity fields (PRESET_EXCLUDED_KEYS). Pure; never mutates
176
- * the input. Node-type-agnostic — the node type is stored alongside the result by the caller.
175
+ * state (`isExecutionDataKey`: the global keys, plus the node type's own when `nodeType` is given)
176
+ * and graph/identity fields (PRESET_EXCLUDED_KEYS). Pure; never mutates the input. The node type is
177
+ * stored alongside the result by the caller.
177
178
  */
178
179
  export function extractPresetData(
179
180
  data: Readonly<Record<string, unknown>>,
181
+ nodeType?: string,
180
182
  ): Record<string, unknown> {
181
183
  const out: Record<string, unknown> = {}
182
184
  for (const key of Object.keys(data)) {
183
- if (EXECUTION_DATA_KEYS.has(key)) continue
185
+ if (isExecutionDataKey(key, nodeType)) continue
184
186
  if (PRESET_EXCLUDED_KEYS.has(key)) continue
185
187
  out[key] = data[key]
186
188
  }
@@ -0,0 +1,76 @@
1
+ /**
2
+ * The REST route that runs one node type on its own: `POST /v1/<type>` by
3
+ * convention, or the route listed here.
4
+ *
5
+ * Part of the public API contract: `@nodaro/sdk`'s `nodes.run(type)` posts to
6
+ * the route this resolves, and the platform's workflow engine calls the same
7
+ * routes for the node types it runs over HTTP, so the two cannot disagree.
8
+ */
9
+ import { SOCIAL_POST_NODE_TYPES } from "./social-post.js"
10
+
11
+ const SOCIAL_PUBLISH_ROUTE = "/v1/social/publish"
12
+
13
+ /** Node types whose run route is NOT `POST /v1/<type>`. */
14
+ export const NODE_RUN_ROUTES: Readonly<Record<string, string>> = Object.freeze({
15
+ "generate-3d-scene": "/v1/3d-scene/generate",
16
+ "edit-3d-scene": "/v1/3d-scene/edit",
17
+ "ai-writer": "/v1/ai-writer/generate",
18
+ "llm-chat": "/v1/llm-chat/generate",
19
+ "video-composer": "/v1/scene-graph/generate",
20
+ "after-effects": "/v1/after-effects/generate",
21
+ "lottie-overlay": "/v1/lottie-overlay/generate",
22
+ "3d-title": "/v1/3d-title/generate",
23
+ "motion-graphics": "/v1/motion-graphics/generate",
24
+ "image-to-text": "/v1/image-to-text/describe",
25
+ "telegram-channel-feed": "/v1/telegram-channel/fetch",
26
+ "suno-generate": "/v1/suno/generate",
27
+ "suno-cover": "/v1/suno/cover",
28
+ "suno-extend": "/v1/suno/extend",
29
+ "suno-lyrics": "/v1/suno/lyrics",
30
+ "suno-separate": "/v1/suno/separate",
31
+ "suno-music-video": "/v1/suno/music-video",
32
+ "suno-mashup": "/v1/suno/mashup",
33
+ "suno-replace-section": "/v1/suno/replace-section",
34
+ "suno-style-boost": "/v1/suno/style-boost",
35
+ "suno-add-instrumental": "/v1/suno/add-instrumental",
36
+ "suno-add-vocals": "/v1/suno/add-vocals",
37
+ "suno-convert-wav": "/v1/suno/convert-wav",
38
+ "suno-upload-extend": "/v1/suno/upload-extend",
39
+ "suno-voice": "/v1/suno/voice/generate",
40
+ // The UGC nodes' routes, served by the Nodaro Cloud plugin.
41
+ "ugc-creator": "/v1/ugc/creator",
42
+ "ugc-script": "/v1/ugc/script",
43
+ "ugc-clips": "/v1/ugc/clips",
44
+ "ugc-clip": "/v1/ugc/clip",
45
+ "ugc-cards": "/v1/ugc/cards",
46
+ // Every social post node publishes through the one route; the body's
47
+ // `platform` says where (SOCIAL_POST_NODE_PLATFORM).
48
+ ...Object.fromEntries([...SOCIAL_POST_NODE_TYPES].map((type) => [type, SOCIAL_PUBLISH_ROUTE])),
49
+ })
50
+
51
+ /**
52
+ * Node types with no route that runs them on their own, each with what to run
53
+ * instead. They run inside the editor or a workflow, or through a sibling
54
+ * route that takes a differently shaped body.
55
+ */
56
+ export const NODE_TYPES_WITHOUT_RUN_ROUTE: Readonly<Record<string, string>> = Object.freeze({
57
+ "modify-image": 'run "image-to-image" instead (or "edit-image" for the nano-banana-edit provider)',
58
+ "upscale-image": 'run "edit-image" with an upscale provider instead (e.g. provider "recraft-upscale")',
59
+ "remove-background": 'run "edit-image" with provider "recraft-remove-bg" instead',
60
+ "image-to-video": 'run "generate-video" with a start frame instead',
61
+ composite: "it runs only as part of a workflow (client.workflows.run)",
62
+ "manual-edit": "it opens the in-browser editor and runs only inside a workflow",
63
+ "paint-mask": "it is painted in the editor and never runs; use its mask output inside a workflow",
64
+ scene: "it is run by the pipeline orchestrator (client.pipelines)",
65
+ "generative-pipeline": "it is run by the pipeline orchestrator (client.pipelines)",
66
+ })
67
+
68
+ /**
69
+ * The route that runs `type` on its own, or null when it has none (see
70
+ * {@link NODE_TYPES_WITHOUT_RUN_ROUTE} for what to run instead).
71
+ */
72
+ export function nodeRunRoute(type: string): string | null {
73
+ if (Object.prototype.hasOwnProperty.call(NODE_TYPES_WITHOUT_RUN_ROUTE, type)) return null
74
+ if (Object.prototype.hasOwnProperty.call(NODE_RUN_ROUTES, type)) return NODE_RUN_ROUTES[type]!
75
+ return `/v1/${encodeURIComponent(type)}`
76
+ }
@@ -9,7 +9,9 @@
9
9
  * - the node-preset extractor (presets must never capture runtime state)
10
10
  * - the backend defensive strip on preset writes
11
11
  *
12
- * When adding a new runtime/result field to a node's data, add its key here.
12
+ * When adding a new runtime/result field to a node's data, add its key here — or, when it is a
13
+ * generic name only one node type writes as a result, to that type's row of
14
+ * NODE_TYPE_EXECUTION_DATA_KEYS (read through `isExecutionDataKey` / `executionDataKeysOf`).
13
15
  */
14
16
  export const EXECUTION_DATA_KEYS: ReadonlySet<string> = new Set([
15
17
  "executionStatus",
@@ -150,8 +152,47 @@ export const EXECUTION_DATA_KEYS: ReadonlySet<string> = new Set([
150
152
  "resultsRunEndedAt",
151
153
  // A trigger's last run values (also in TRANSIENT_RUNTIME_KEYS: never saved).
152
154
  "__triggerData",
155
+ // A fan-out's notes rows, every fan-out's (row-aligned with __listResults):
156
+ // a row's warnings and length. A RESULT: persisted.
157
+ "__listResultMeta",
153
158
  ])
154
159
 
160
+ /**
161
+ * Run results a node type writes under a GENERIC name — `quote`, `durationSec`,
162
+ * `candidates` — that are execution data on THAT type only. Another node may
163
+ * keep a setting under the same name; filing these globally would misfile it
164
+ * (out of undo, presets, templates and the copilot's view). Same lifecycle as
165
+ * the global results: persisted, and a run writing them is never an undo step.
166
+ *
167
+ * UGC video (Nodaro Cloud): the outputs a node hands on (`ugcOutputs`), UGC
168
+ * Creator's options of a draw and their note, UGC Clips' quote, and UGC Clip's
169
+ * warnings, length and Re-render marks (`rerenderPending`: the clips pressed for
170
+ * Re-render that no run has rendered yet — run bookkeeping; the press itself,
171
+ * `rerender`, is a choice).
172
+ */
173
+ export const NODE_TYPE_EXECUTION_DATA_KEYS: Readonly<Record<string, readonly string[]>> = {
174
+ "ugc-creator": ["ugcOutputs", "candidates", "optionFailed"],
175
+ "ugc-script": ["ugcOutputs"],
176
+ "ugc-clips": ["ugcOutputs", "quote"],
177
+ "ugc-clip": ["ugcOutputs", "clipWarnings", "durationSec", "rerenderPending"],
178
+ "ugc-cards": ["ugcOutputs"],
179
+ }
180
+
181
+ /** Is `key` execution data (run state or a run's result) on a node of `type`: global, or that type's own? */
182
+ export function isExecutionDataKey(key: string, type: string | null | undefined): boolean {
183
+ if (EXECUTION_DATA_KEYS.has(key)) return true
184
+ return typeof type === "string" && Object.hasOwn(NODE_TYPE_EXECUTION_DATA_KEYS, type) && NODE_TYPE_EXECUTION_DATA_KEYS[type]!.includes(key)
185
+ }
186
+
187
+ const EXECUTION_DATA_KEYS_BY_TYPE = new Map<string, ReadonlySet<string>>(
188
+ Object.entries(NODE_TYPE_EXECUTION_DATA_KEYS).map(([type, keys]) => [type, new Set([...EXECUTION_DATA_KEYS, ...keys])]),
189
+ )
190
+
191
+ /** Every execution-data key on a node of `type`, as one set: the global ones, plus the type's own. */
192
+ export function executionDataKeysOf(type: string | null | undefined): ReadonlySet<string> {
193
+ return (typeof type === "string" ? EXECUTION_DATA_KEYS_BY_TYPE.get(type) : undefined) ?? EXECUTION_DATA_KEYS
194
+ }
195
+
155
196
  /**
156
197
  * The PURE RUN-STATE subset of EXECUTION_DATA_KEYS: per-tick values (status
157
198
  * flips, job ids, progress counters, fan-out bookkeeping) that must NEITHER
@@ -172,6 +172,9 @@ const AUDIO_OUTPUT_TYPES = new Set([
172
172
  const TEXT_OUTPUT_TYPES = new Set([
173
173
  "generate-script", "ai-writer", "llm-chat", "transcribe", "image-to-text", "qa-check",
174
174
  "text-prompt",
175
+ // UGC Cards' output card is its Notes: a run hands it on as the node's text
176
+ // (`output.text`, `generatedText` on the canvas).
177
+ "ugc-cards",
175
178
  ])
176
179
 
177
180
  // ---------------------------------------------------------------------------
@@ -14,6 +14,7 @@
14
14
  * a connection from a node type that the backend would happily route at
15
15
  * execution time (the prior drift bug, see issue 1 of the Task 4.1 review).
16
16
  */
17
+ import { UGC_PRIMARY_HANDLE } from "./ugc-node-wires.js"
17
18
 
18
19
  /**
19
20
  * Source node types whose primary output is a video URL.
@@ -104,6 +105,9 @@ export const VIDEO_PRODUCER_TYPES: ReadonlySet<string> = new Set([
104
105
  // Video Overlay: timed image layers over a video in one local FFmpeg pass
105
106
  // (the base audio copied) — emits a video URL on `video-out`.
106
107
  "video-overlay",
108
+ // UGC Clip: renders one clip of a UGC video from its ticket — emits a video
109
+ // URL on `video-out` (one per fan-out iteration).
110
+ "ugc-clip",
107
111
  ])
108
112
 
109
113
  /**
@@ -312,6 +316,12 @@ export const FAN_OUT_EACH_HANDLES: Readonly<Record<string, { readonly each: read
312
316
  // every clip (the master clock, renamed), so that handle stays one value
313
317
  // (decided 2026-10-04).
314
318
  "camera-switch": { each: ["edl"], primary: "edl" },
319
+ // UGC Clips: one ticket per clip on `clips` (each); `plan-out` and
320
+ // `transcript` carry one value. Not a FAN_OUT_EACH_TYPES member — every
321
+ // handle of such a member would fan out. Its one run writes the tickets as
322
+ // its list (`listResults`, the editor's `__listResults`). The pip an edge
323
+ // with no handle reads is the UGC wires' own (UGC_PRIMARY_HANDLE).
324
+ "ugc-clips": { each: ["clips"], primary: UGC_PRIMARY_HANDLE["ugc-clips"]! },
315
325
  }
316
326
 
317
327
  /**