@nodaro/shared 3.21.0 → 3.24.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 (84) hide show
  1. package/dist/index.cjs +2291 -195
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +1929 -75
  4. package/dist/index.d.ts +1929 -75
  5. package/dist/index.js +2123 -196
  6. package/dist/index.js.map +1 -1
  7. package/package.json +1 -1
  8. package/src/__tests__/add-captions-plan.test.ts +33 -0
  9. package/src/__tests__/caption-plan-parse.test.ts +23 -0
  10. package/src/__tests__/caption-segment-schema.test.ts +30 -0
  11. package/src/__tests__/collections.test.ts +253 -0
  12. package/src/__tests__/dialogue-capabilities.test.ts +157 -0
  13. package/src/__tests__/edit-plan-review.test.ts +70 -0
  14. package/src/__tests__/edl-clocks.test.ts +97 -0
  15. package/src/__tests__/edl.test.ts +34 -0
  16. package/src/__tests__/execution-outcome.test.ts +44 -0
  17. package/src/__tests__/fan-out-meta.test.ts +23 -0
  18. package/src/__tests__/fan-out-rows.test.ts +36 -0
  19. package/src/__tests__/fan-out-url-item.test.ts +44 -0
  20. package/src/__tests__/fixtures/speaker-tracks.fixtures.json +622 -0
  21. package/src/__tests__/input-field-extra-keys.test.ts +34 -0
  22. package/src/__tests__/list-consumers-fan-in.test.ts +40 -0
  23. package/src/__tests__/model-tree.test.ts +7 -0
  24. package/src/__tests__/node-pass-through.test.ts +23 -0
  25. package/src/__tests__/node-runtime-keys.test.ts +1 -0
  26. package/src/__tests__/picker-restrictions.test.ts +36 -0
  27. package/src/__tests__/preview-gate.test.ts +305 -0
  28. package/src/__tests__/render-basis.test.ts +176 -0
  29. package/src/__tests__/render-nodes.test.ts +73 -0
  30. package/src/__tests__/render-output.test.ts +392 -0
  31. package/src/__tests__/run-continuation.test.ts +32 -0
  32. package/src/__tests__/speaker-tracks.test.ts +474 -0
  33. package/src/__tests__/speech-pricing.test.ts +69 -0
  34. package/src/__tests__/telegram-channel.test.ts +91 -0
  35. package/src/__tests__/tts-capabilities.test.ts +81 -4
  36. package/src/__tests__/tts-neighbour-text.test.ts +19 -0
  37. package/src/__tests__/ugc-call-body.test.ts +38 -0
  38. package/src/__tests__/ugc-run-state.test.ts +68 -0
  39. package/src/__tests__/video-character-refs.test.ts +213 -0
  40. package/src/__tests__/video-overlay-layer-plan.test.ts +94 -0
  41. package/src/add-captions-plan.ts +50 -0
  42. package/src/caption-plan.ts +45 -0
  43. package/src/caption-segment-schema.ts +82 -0
  44. package/src/collections.ts +482 -0
  45. package/src/competitors.ts +77 -0
  46. package/src/credit-estimators/index.ts +9 -0
  47. package/src/credit-estimators/speech.ts +51 -0
  48. package/src/dialogue-capabilities.ts +48 -0
  49. package/src/edit-plan-contract.ts +20 -9
  50. package/src/edit-plan-review.ts +40 -1
  51. package/src/edl.ts +27 -1
  52. package/src/execution-outcome.ts +41 -0
  53. package/src/fan-out-meta.ts +23 -0
  54. package/src/fan-out-rows.ts +74 -5
  55. package/src/gemini-omni-voices.ts +59 -0
  56. package/src/handle-aliases.ts +298 -0
  57. package/src/i18n/camera-motions.pt-BR.ts +14 -14
  58. package/src/i18n/transitions.pt-BR.ts +13 -13
  59. package/src/index.ts +180 -1
  60. package/src/model-catalog.ts +122 -13
  61. package/src/model-constants.ts +24 -4
  62. package/src/model-tree.ts +5 -1
  63. package/src/node-execution-state.ts +13 -0
  64. package/src/node-mappable-fields.ts +7 -1
  65. package/src/node-pass-through.ts +37 -0
  66. package/src/node-runtime-keys.ts +14 -0
  67. package/src/picker-restrictions.ts +49 -0
  68. package/src/presentation-types.ts +26 -2
  69. package/src/presentation-utils.ts +25 -7
  70. package/src/preview-gate.ts +279 -0
  71. package/src/producer-types.ts +58 -0
  72. package/src/render-final.ts +20 -0
  73. package/src/render-nodes.ts +92 -0
  74. package/src/render-output.ts +565 -0
  75. package/src/run-continuation.ts +39 -0
  76. package/src/speaker-tracks.ts +638 -0
  77. package/src/telegram-channel.ts +140 -0
  78. package/src/transcribe-preflight.ts +8 -4
  79. package/src/tts-capabilities.ts +19 -5
  80. package/src/tts-neighbour-text.ts +46 -0
  81. package/src/ugc-call-body.ts +86 -0
  82. package/src/ugc-run-state.ts +64 -0
  83. package/src/video-character-refs.ts +233 -0
  84. package/src/video-overlay.ts +78 -21
@@ -0,0 +1,37 @@
1
+ /**
2
+ * When a public video node outputs its input unchanged — no job, no charge —
3
+ * because there is nothing for it to do (spec R14). One rule for both engines:
4
+ * the orchestrator asks before any reservation, the canvas block before its API
5
+ * call. The API routes keep their limits (Combine Videos still needs two URLs;
6
+ * an empty overlay request is still `no_layers`).
7
+ */
8
+ export type PassThroughWarning = "no_layers" | "no_captions" | "single_input"
9
+ export interface PassThrough { readonly videoUrl: string; readonly warning: PassThroughWarning }
10
+
11
+ const present = (u: string | null | undefined): u is string => typeof u === "string" && u.length > 0
12
+
13
+ /** Exactly one resolved video → that video, unchanged. */
14
+ export function combineVideosPassThrough(videoUrls: ReadonlyArray<string | null | undefined>): PassThrough | null {
15
+ const urls = videoUrls.filter(present)
16
+ return urls.length === 1 ? { videoUrl: urls[0]!, warning: "single_input" } : null
17
+ }
18
+
19
+ /** A wired layer plan that resolved to nothing, with no handle layer either → the base video. */
20
+ export function videoOverlayPassThrough(input: {
21
+ readonly videoUrl: string | null | undefined
22
+ readonly planWired: boolean
23
+ readonly layerCount: number
24
+ }): PassThrough | null {
25
+ if (!input.planWired || input.layerCount > 0 || !present(input.videoUrl)) return null
26
+ return { videoUrl: input.videoUrl, warning: "no_layers" }
27
+ }
28
+
29
+ /** A wired caption plan whose styling produced no segment → the input video. */
30
+ export function captionPlanPassThrough(input: {
31
+ readonly videoUrl: string | null | undefined
32
+ readonly planWired: boolean
33
+ readonly segmentCount: number
34
+ }): PassThrough | null {
35
+ if (!input.planWired || input.segmentCount > 0 || !present(input.videoUrl)) return null
36
+ return { videoUrl: input.videoUrl, warning: "no_captions" }
37
+ }
@@ -48,9 +48,16 @@ export const EXECUTION_DATA_KEYS: ReadonlySet<string> = new Set([
48
48
  // Row-aligned twin of __listResults (Extract Field, List output) — read only
49
49
  // by the fan-out so two lists cut from one array pair by row.
50
50
  "__alignedListResults",
51
+ // A render's fan-out row stamps, row-aligned with __listResults: each row's
52
+ // take identity, and the clip every row was sent for (a failed row too).
53
+ "__listResultStamps",
51
54
  // List fan-out window flag (abandon-guard exemption). Set/cleared by
52
55
  // executeNodeForList — purely execution-related, never user-edited.
53
56
  "__listRunning",
57
+ // Why the last server run skipped this node (`empty_input`): a chip on the
58
+ // card for the run that just ended, never a saved result — also in
59
+ // TRANSIENT_RUNTIME_KEYS below.
60
+ "__runSkipReason",
54
61
  // One token per paid run still out on this node that no executor mark
55
62
  // covers (the editor's `withRunInFlight`, around each paid call outside the
56
63
  // executors). Purely execution-related, never user-edited; also in
@@ -117,6 +124,12 @@ export const EXECUTION_DATA_KEYS: ReadonlySet<string> = new Set([
117
124
  "searchResults",
118
125
  "pickedIds",
119
126
  "searchWarnings",
127
+ // Save to Collection: how the last run ended for this node (inserted /
128
+ // duplicate / replayed) and how many old records the cap evicted. RESULTS of
129
+ // a run — Clear results wipes them, and a template, a preset or a run-only
130
+ // patch never carries them as configuration.
131
+ "lastOutcome",
132
+ "lastEvicted",
120
133
  // When the editor's "Clear results" last emptied this node (ISO time). Not a
121
134
  // result and not config: bookkeeping that tells the load-time recovery lanes
122
135
  // "this node is empty ON PURPOSE" — without it, every reload reads an empty
@@ -163,6 +176,7 @@ export const TRANSIENT_RUNTIME_KEYS: ReadonlySet<string> = new Set([
163
176
  "__listTotal",
164
177
  "__listCompleted",
165
178
  "__listRunning",
179
+ "__runSkipReason",
166
180
  // A paid run still out, held by the editor tab that started it. Never
167
181
  // saved, so a reload, which has no such run, starts without one.
168
182
  "__runsInFlight",
@@ -0,0 +1,49 @@
1
+ import { canonicalExposedFieldKey } from "./exposed-field-keys.js"
2
+ import { INPUT_FIELD_MAP } from "./presentation-utils.js"
3
+
4
+ /** What an app's picker card may restrict (stored in `presentationSettings.cardMeta[nodeId]`). */
5
+ export interface PickerCardRestrictions {
6
+ readonly pickerAllowedValues?: readonly string[]
7
+ readonly pickerAllowedValuesByField?: Readonly<Record<string, readonly string[]>>
8
+ }
9
+
10
+ // Every submitted value is checked, whatever its type — a number or object where a
11
+ // catalog id belongs must be refused, not skipped. An unset / cleared pick ("" , null)
12
+ // is no selection and passes (the node falls back to its default).
13
+ const valuesOf = (v: unknown): string[] =>
14
+ (Array.isArray(v) ? v : [v]).filter((x) => x !== undefined && x !== null && x !== "").map(String)
15
+
16
+ /**
17
+ * The first submitted picker value an app's card restrictions forbid, as the
18
+ * runner's 400 text; null when all pass. Runs on every app run — `run_app`,
19
+ * the SDK and a hand-built body included — so a restriction is never UI-only.
20
+ * A submitted key is read through `canonicalExposedFieldKey`, so a legacy
21
+ * spelling cannot slip past a restriction written against the current field.
22
+ */
23
+ export function findRestrictedPickerValue(input: {
24
+ readonly cardMeta: Readonly<Record<string, PickerCardRestrictions | undefined>> | undefined
25
+ readonly nodes: ReadonlyArray<{ readonly id: string; readonly type?: string }>
26
+ readonly inputValues: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined
27
+ }): string | null {
28
+ if (!input.cardMeta || !input.inputValues) return null
29
+ for (const node of input.nodes) {
30
+ const meta = input.cardMeta[node.id]
31
+ const submitted = input.inputValues[node.id]
32
+ if (!meta || !submitted) continue
33
+ const rules: Array<[string, readonly string[]]> = []
34
+ const rep = node.type ? INPUT_FIELD_MAP[node.type]?.key : undefined
35
+ if (rep && meta.pickerAllowedValues && meta.pickerAllowedValues.length > 0) rules.push([rep, meta.pickerAllowedValues])
36
+ for (const [field, allowed] of Object.entries(meta.pickerAllowedValuesByField ?? {})) {
37
+ if (allowed.length > 0) rules.push([field, allowed])
38
+ }
39
+ for (const [field, allowed] of rules) {
40
+ for (const [key, raw] of Object.entries(submitted)) {
41
+ if (canonicalExposedFieldKey(node.type, key) !== field) continue
42
+ for (const value of valuesOf(raw)) {
43
+ if (!allowed.includes(value)) return `Invalid value for ${field}: ${value}. Allowed: ${allowed.join(", ")}`
44
+ }
45
+ }
46
+ }
47
+ }
48
+ return null
49
+ }
@@ -16,8 +16,32 @@ export interface ExposableOutput {
16
16
  }
17
17
 
18
18
  export type PresentationItem =
19
- | { type: "node"; nodeId: string }
20
- | { type: "field"; id: string; nodeId: string; field: string; allowedValues?: Array<string | number | boolean> }
19
+ | {
20
+ type: "node"
21
+ nodeId: string
22
+ /**
23
+ * For a node exposed whole whose input is text (a Text node): the most
24
+ * characters the app user may enter — the same limit a `field` item carries
25
+ * (a whole number, at least 1; ignored on a node that is not a text input).
26
+ * Enforced when the app runs, and it caps the price a speech node fed by
27
+ * this input is advertised at.
28
+ */
29
+ maxLength?: number
30
+ }
31
+ | {
32
+ type: "field"
33
+ id: string
34
+ nodeId: string
35
+ field: string
36
+ allowedValues?: Array<string | number | boolean>
37
+ /**
38
+ * For a text input: the most characters the app user may enter (a whole
39
+ * number, at least 1). Enforced when the app runs, and it caps the price a
40
+ * speech node fed by this input is advertised at — without it, an exposed
41
+ * speech text is priced at the model's per-request cap.
42
+ */
43
+ maxLength?: number
44
+ }
21
45
  | { type: "output"; id: string; nodeId: string; outputKey: string }
22
46
  | { type: "richtext"; id: string; content: string }
23
47
  | { type: "group"; id: string; title: string; items: PresentationItem[]; showTitle?: boolean; showBackground?: boolean }
@@ -7,6 +7,7 @@ import type { GenericNode, GenericEdge } from "./types.js"
7
7
  import type { PresentationItem } from "./presentation-types.js"
8
8
  import { AUDIO_PRODUCER_TYPES, VIDEO_PRODUCER_TYPES } from "./producer-types.js"
9
9
  import { canonicalizeOverrideKeys } from "./exposed-field-keys.js"
10
+ import { RENDER_NODE_TYPE_IDS } from "./render-nodes.js"
10
11
 
11
12
  // ---------------------------------------------------------------------------
12
13
  // Node type sets
@@ -146,13 +147,14 @@ const VIDEO_OUTPUT_TYPES = new Set([
146
147
  "upload-video",
147
148
  "lip-sync", "motion-transfer", "video-upscale", "add-captions",
148
149
  "social-media-format",
149
- // apply-edl renders an EDL into video OR audio. Its medium is decided at run
150
- // time (DYNAMIC_PRODUCER_TYPES), so getOutputType would answer "data" and a
151
- // published app would render the cut as a JSON blob. Declaring it here — as
152
- // the voice-changer/dubbing precedent does for their default medium — makes
153
- // the classifier answer "video" (the common case; an audio-only cut still
154
- // plays in a video element). Asserted in producer-types.test.ts.
155
- "apply-edl",
150
+ // A render (Apply EDL) renders an EDL into video OR audio. Its medium is
151
+ // decided at run time (DYNAMIC_PRODUCER_TYPES), so getOutputType would answer
152
+ // "data" and a published app would render the cut as a JSON blob. Declaring
153
+ // every render here — as the voice-changer/dubbing precedent does for their
154
+ // default medium — makes the classifier answer "video" (the common case; an
155
+ // audio-only cut still plays in a video element). Asserted in
156
+ // producer-types.test.ts.
157
+ ...RENDER_NODE_TYPE_IDS,
156
158
  ])
157
159
 
158
160
  const AUDIO_OUTPUT_TYPES = new Set([
@@ -394,6 +396,22 @@ export const INPUT_FIELD_MAP: Record<string, InputFieldSchema> = {
394
396
  "instrumentation": { key: "production", type: "select" },
395
397
  "voice-character": { key: "timbre", type: "select" },
396
398
  "voice-delivery": { key: "archetype", type: "select" },
399
+ // --- UGC (Cloud) ---
400
+ "ugc-creator": { key: "source", type: "select" },
401
+ }
402
+
403
+ /**
404
+ * Extra API-settable keys for node types whose card writes more than one field
405
+ * (INPUT_FIELD_MAP is one key per node type). Read by extract-app-inputs and the
406
+ * app runner; every key here must be in UGC_OVERRIDABLE_FIELDS for a UGC type.
407
+ */
408
+ export const INPUT_FIELD_EXTRA_KEYS: Readonly<Record<string, readonly InputFieldSchema[]>> = {
409
+ "ugc-creator": [{ key: "gender", type: "select" }, { key: "photoUrl", type: "image-url" }],
410
+ }
411
+
412
+ /** The extra override fields of a node type (none for most types). */
413
+ export function getInputFieldExtraKeys(nodeType: string): readonly InputFieldSchema[] {
414
+ return Object.hasOwn(INPUT_FIELD_EXTRA_KEYS, nodeType) ? INPUT_FIELD_EXTRA_KEYS[nodeType]! : []
397
415
  }
398
416
 
399
417
  /** Get the overridable field schema for an input node type. */
@@ -0,0 +1,279 @@
1
+ /**
2
+ * The preview stop rule (Track A, decided 2026-10-04): a run stops at a
3
+ * Preview render, and nothing downstream of it runs until Render final.
4
+ *
5
+ * It starts at a render node (`PREVIEW_RENDER_NODE_TYPES`) in either of two
6
+ * cases:
7
+ * - the render EXECUTES in this run and its effective quality, after the
8
+ * run's input overrides (`withRunOverrides`), is `proxy`;
9
+ * - the render sits OUTSIDE the run and an item its saved output would hand
10
+ * a consumer is a stamped Preview — decided per wire, exactly as the input
11
+ * resolvers read it: an `each` wire reads the latest batch, any other wire
12
+ * the selected result (`SavedRenderStampReader`).
13
+ *
14
+ * Everything forward of a start — through every way one node feeds another
15
+ * (`buildFeedMaps`: edges, teleports, Group membership, field mappings) — is
16
+ * GATED: never executed, never counted, never billed. A forward closure, not
17
+ * router gating, so a Combine Videos fed by the render AND an intro upload
18
+ * stops too. The invariant: no node ever consumes a preview. The render's own
19
+ * run stays allowed — a start render is gated only when it is itself
20
+ * downstream of another preview.
21
+ *
22
+ * One rule for both engines, the editor's estimates and its chip, and SDK users.
23
+ */
24
+ import { buildFeedMaps } from "./trigger-feeds.js"
25
+ import { defaultEdgeOutputMode } from "./producer-types.js"
26
+ import { mergeNodeInputOverrides } from "./presentation-utils.js"
27
+ import { RENDER_NODE_TYPE_IDS } from "./render-nodes.js"
28
+
29
+ /** Render nodes a run can stop at: every render in the registry (SV18). */
30
+ export const PREVIEW_RENDER_NODE_TYPES: ReadonlySet<string> = new Set(RENDER_NODE_TYPE_IDS)
31
+
32
+ /**
33
+ * Stable refusal code: a run with nobody to review it (a trigger, an API or
34
+ * MCP call, a present link, an app run) holds a Preview render. Set the
35
+ * render to Final, or run with a Final override on it.
36
+ */
37
+ export const PREVIEW_REVIEW_REQUIRED = "preview_review_required"
38
+
39
+ /**
40
+ * Stable refusal code: a sub-workflow or a component holds a Preview render.
41
+ * A nested graph has no Render final path, so this refusal is permanent.
42
+ */
43
+ export const PREVIEW_RENDER_NESTED = "preview_render_nested"
44
+
45
+ /** A node as the stop rule reads it (either engine's graph, or a saved one). */
46
+ export interface PreviewGateNode {
47
+ readonly id: string
48
+ readonly type?: string | null
49
+ readonly data?: unknown
50
+ readonly parentId?: string | null
51
+ }
52
+
53
+ /** A wire as the stop rule reads it. `data.outputMode` is the wire's mode. */
54
+ export interface PreviewGateEdge {
55
+ readonly source: string
56
+ readonly target: string
57
+ readonly sourceHandle?: string | null
58
+ readonly targetHandle?: string | null
59
+ readonly data?: unknown
60
+ }
61
+
62
+ /** What a saved render result says about itself: `"proxy"` is a Preview. */
63
+ export interface SavedRenderQualityStamp {
64
+ readonly quality?: string
65
+ }
66
+
67
+ /**
68
+ * How the rule reads a saved render: the result a scalar wire receives
69
+ * (`output`) and the rows an `each` wire iterates (`batch`, the LATEST batch
70
+ * only — `undefined` when the render has none, and the wire then reads the one
71
+ * result). The saved-output reader both engines use plugs in here.
72
+ */
73
+ export interface SavedRenderStampReader {
74
+ output(data: Readonly<Record<string, unknown>>): SavedRenderQualityStamp | undefined
75
+ batch(data: Readonly<Record<string, unknown>>): ReadonlyArray<SavedRenderQualityStamp | null> | undefined
76
+ }
77
+
78
+ /** A reader that sees no stamps: every saved render reads as unstamped. */
79
+ export const NO_SAVED_RENDER_STAMPS: SavedRenderStampReader = {
80
+ output: () => undefined,
81
+ batch: () => undefined,
82
+ }
83
+
84
+ /**
85
+ * The production reader. No render result carries a `quality` stamp until the
86
+ * results themselves are stamped, so today it reads none and the saved-preview
87
+ * half of the rule is inert; the stamped-result reader replaces it here, the
88
+ * one place every caller takes it from.
89
+ */
90
+ export const SAVED_RENDER_STAMPS: SavedRenderStampReader = NO_SAVED_RENDER_STAMPS
91
+
92
+ /** One run's view: which nodes execute, and how saved renders are read. */
93
+ export interface PreviewGateRun {
94
+ /** Does this node execute in this run? Default: every node that is not frozen (`data.skipped`). */
95
+ readonly executes?: (nodeId: string) => boolean
96
+ /** Default: `SAVED_RENDER_STAMPS`. */
97
+ readonly savedRenders?: SavedRenderStampReader
98
+ }
99
+
100
+ export interface PreviewStops {
101
+ /** Render nodes that execute in this run at Preview quality. */
102
+ readonly previewRenderIds: readonly string[]
103
+ /** Render nodes outside the run whose saved output hands a Preview on. */
104
+ readonly savedPreviewRenderIds: readonly string[]
105
+ /** Every node that would consume a preview: never executed in this run. */
106
+ readonly gatedNodeIds: ReadonlySet<string>
107
+ }
108
+
109
+ type Data = Readonly<Record<string, unknown>>
110
+
111
+ const dataOf = (n: PreviewGateNode): Data =>
112
+ (n.data && typeof n.data === "object" ? n.data : {}) as Data
113
+
114
+ const isPreviewStamp = (stamp: SavedRenderQualityStamp | null | undefined): boolean => stamp?.quality === "proxy"
115
+
116
+ /** A render node set to Preview: its quality (after any run overrides) is `proxy`. */
117
+ export function rendersAsPreview(node: PreviewGateNode): boolean {
118
+ return PREVIEW_RENDER_NODE_TYPES.has(node.type ?? "") && dataOf(node).quality === "proxy"
119
+ }
120
+
121
+ const TELEPORT_TYPES: ReadonlySet<string> = new Set(["teleport-send", "teleport-receive"])
122
+ const isTeleport = (n: PreviewGateNode | undefined): boolean => TELEPORT_TYPES.has(n?.type ?? "")
123
+
124
+ const outputModeOf = (edge: PreviewGateEdge): string | undefined => {
125
+ const mode = edge.data && typeof edge.data === "object" ? (edge.data as { outputMode?: unknown }).outputMode : undefined
126
+ return typeof mode === "string" ? mode : undefined
127
+ }
128
+
129
+ /**
130
+ * Does a consumer's wire read the render's latest batch, as the resolvers
131
+ * decide it? The consumer-side wire's own mode, else the default for the real
132
+ * source (the render) on the render-side handle. Through a teleport pair the
133
+ * consumer's wire is the one leaving the last teleport, and the render-side
134
+ * handle is the one on the render → teleport wire.
135
+ */
136
+ function readsEach(render: PreviewGateNode, consumerEdge: PreviewGateEdge, renderHandle: string | null | undefined): boolean {
137
+ return (outputModeOf(consumerEdge) ?? defaultEdgeOutputMode(render.type, renderHandle)) === "each"
138
+ }
139
+
140
+ /**
141
+ * The consumers a saved render hands a Preview to (empty when it hands none).
142
+ * A teleport pair is transparent, exactly as the input resolvers walk it: the
143
+ * nodes reached through it are decided per consumer wire, so a teleport fanning
144
+ * out to an `each` and a scalar consumer stops only the one reading a Preview.
145
+ */
146
+ function savedPreviewConsumers(
147
+ render: PreviewGateNode,
148
+ children: ReadonlyMap<string, readonly string[]>,
149
+ nodeById: ReadonlyMap<string, PreviewGateNode>,
150
+ edges: readonly PreviewGateEdge[],
151
+ reader: SavedRenderStampReader,
152
+ ): string[] {
153
+ const data = dataOf(render)
154
+ const scalarIsPreview = isPreviewStamp(reader.output(data))
155
+ const batch = reader.batch(data)
156
+ const eachIsPreview = batch ? batch.some(isPreviewStamp) : scalarIsPreview
157
+ const out = new Set<string>()
158
+ const visited = new Set<string>([render.id])
159
+ // (node a Preview may reach, the render-side handle it travels on)
160
+ const walk = (from: string, renderHandle: string | null | undefined, isRender: boolean): void => {
161
+ const wires = edges.filter((e) => e.source === from)
162
+ for (const child of children.get(from) ?? []) {
163
+ const wiresToChild = wires.filter((e) => e.target === child)
164
+ if (isTeleport(nodeById.get(child))) {
165
+ if (visited.has(child)) continue
166
+ visited.add(child)
167
+ // Leaving the render, the wire into the teleport names the handle;
168
+ // past it the handle is the one already carried.
169
+ if (isRender && wiresToChild.length > 0) for (const w of wiresToChild) walk(child, w.sourceHandle, false)
170
+ else walk(child, renderHandle, false)
171
+ continue
172
+ }
173
+ // A child fed with no wire (Group membership, a field mapping) reads the
174
+ // render's one result, as a scalar wire does.
175
+ const preview =
176
+ wiresToChild.length === 0
177
+ ? scalarIsPreview
178
+ : wiresToChild.some((e) =>
179
+ readsEach(render, e, isRender ? e.sourceHandle : renderHandle) ? eachIsPreview : scalarIsPreview,
180
+ )
181
+ if (preview) out.add(child)
182
+ }
183
+ }
184
+ walk(render.id, undefined, true)
185
+ return [...out]
186
+ }
187
+
188
+ /** The stop rule: where this run stops, and everything it does not run. */
189
+ export function previewStops(
190
+ nodes: readonly PreviewGateNode[],
191
+ edges: readonly PreviewGateEdge[],
192
+ run: PreviewGateRun = {},
193
+ ): PreviewStops {
194
+ const nodeById = new Map(nodes.map((n) => [n.id, n]))
195
+ const executes =
196
+ run.executes ?? ((id: string) => { const n = nodeById.get(id); return !!n && dataOf(n).skipped !== true })
197
+ const reader = run.savedRenders ?? SAVED_RENDER_STAMPS
198
+ const { children } = buildFeedMaps(nodes, edges)
199
+ const previewRenderIds: string[] = []
200
+ const savedPreviewRenderIds: string[] = []
201
+ const seeds: string[] = []
202
+ for (const n of nodes) {
203
+ if (!PREVIEW_RENDER_NODE_TYPES.has(n.type ?? "")) continue
204
+ const kids = children.get(n.id) ?? []
205
+ if (executes(n.id)) {
206
+ if (!rendersAsPreview(n)) continue
207
+ previewRenderIds.push(n.id)
208
+ seeds.push(...kids)
209
+ } else {
210
+ const consumers = savedPreviewConsumers(n, children, nodeById, edges, reader)
211
+ if (consumers.length === 0) continue
212
+ savedPreviewRenderIds.push(n.id)
213
+ seeds.push(...consumers)
214
+ }
215
+ }
216
+ const gated = new Set<string>()
217
+ const queue = [...seeds]
218
+ while (queue.length > 0) {
219
+ const id = queue.shift()!
220
+ if (gated.has(id)) continue
221
+ gated.add(id)
222
+ for (const next of children.get(id) ?? []) if (!gated.has(next)) queue.push(next)
223
+ }
224
+ return { previewRenderIds, savedPreviewRenderIds, gatedNodeIds: gated }
225
+ }
226
+
227
+ /** The nodes this run does not execute because they would consume a preview. */
228
+ export function previewGatedNodeIds(
229
+ nodes: readonly PreviewGateNode[],
230
+ edges: readonly PreviewGateEdge[],
231
+ run?: PreviewGateRun,
232
+ ): Set<string> {
233
+ return new Set(previewStops(nodes, edges, run).gatedNodeIds)
234
+ }
235
+
236
+ /** Does this run hold anything a reviewer would have to review: a Preview
237
+ * render it executes, or a saved Preview it hands on? */
238
+ export function holdsPreviewRender(
239
+ nodes: readonly PreviewGateNode[],
240
+ edges: readonly PreviewGateEdge[],
241
+ run?: PreviewGateRun,
242
+ ): boolean {
243
+ const stops = previewStops(nodes, edges, run)
244
+ return stops.previewRenderIds.length > 0 || stops.savedPreviewRenderIds.length > 0
245
+ }
246
+
247
+ /**
248
+ * The fields a run's input override clears from the node it overrides, so a
249
+ * fresh input wins over a cached result. The server's merge and
250
+ * `withRunOverrides` both clear exactly these.
251
+ */
252
+ export const RUN_OVERRIDE_CLEARED_FIELDS = [
253
+ "generatedResults",
254
+ "activeResultIndex",
255
+ "generatedImageUrl",
256
+ "generatedVideoUrl",
257
+ "generatedAudioUrl",
258
+ "generatedText",
259
+ ] as const
260
+
261
+ /**
262
+ * The graph a run executes once its input overrides (`{ [nodeId]: fields }`)
263
+ * are merged: the same shallow merge as the server's, clearing the overridden
264
+ * node's saved results. Never mutates; a node with no override is returned as
265
+ * is. Render final is a run with `{ [renderId]: { quality: "final" } }`.
266
+ */
267
+ export function withRunOverrides<N extends PreviewGateNode>(
268
+ nodes: readonly N[],
269
+ overrides: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
270
+ ): N[] {
271
+ if (!overrides) return [...nodes]
272
+ return nodes.map((n) => {
273
+ const fields = overrides[n.id]
274
+ if (!fields) return n
275
+ const merged = mergeNodeInputOverrides(n.type ?? undefined, { ...dataOf(n) }, { ...fields })
276
+ for (const key of RUN_OVERRIDE_CLEARED_FIELDS) delete merged[key]
277
+ return { ...n, data: merged }
278
+ })
279
+ }
@@ -207,6 +207,44 @@ export const AUDIO_PRODUCER_TYPES: ReadonlySet<string> = new Set([
207
207
  "extract-audio",
208
208
  ])
209
209
 
210
+ /**
211
+ * Source node types whose output is an IMAGE URL — what feeds a References
212
+ * input. ONE set for the canvas validators (`frontend/src/lib/
213
+ * generate-image-handles.ts` re-exports it), the backend's Generate Image
214
+ * handle migration and the MCP edge normalizer (`llm-chat`'s legacy `in`):
215
+ * they used to keep separate copies, and the backend's lagged by eight types.
216
+ */
217
+ export const IMAGE_PRODUCER_TYPES: ReadonlySet<string> = new Set([
218
+ "upload-image", "generate-image", "edit-image", "image-to-image", "modify-image", "upscale-image", "remove-background",
219
+ // extract-frame produces a single still image extracted from a video source.
220
+ "extract-frame",
221
+ // generate-mask emits the source image AND a mask PNG; its `image` source
222
+ // pip is the passthrough (the same image as the input).
223
+ "generate-mask",
224
+ // paint-mask emits the hand-painted mask PNG (a plain image at runtime).
225
+ // Membership is what makes mask targets accept it — mask is an advisory
226
+ // color, not a gated type.
227
+ "paint-mask",
228
+ // reference-sheet's `sheet` is one composited image and `panels` carries
229
+ // clean reference images; both resolve to image URLs at runtime.
230
+ "reference-sheet",
231
+ // reference-board's `image` pip emits a real generated board image.
232
+ "reference-board",
233
+ // image-collage composites N images → ONE image.
234
+ "image-collage",
235
+ // image-overlay places layers on a base → ONE image.
236
+ "image-overlay",
237
+ // 3D Render Pro's `stills` handle carries one PNG per shot of the exported
238
+ // composition (spread into referenceImageUrls like reference-sheet
239
+ // `panels`). A validator sees only the source NODE type, so this also makes
240
+ // its `video` pip droppable on an image input — the handle-blind trade
241
+ // reference-sheet and split-media already make; the input resolvers route
242
+ // by handle, so only `stills` becomes an image at runtime. Deliberately NOT
243
+ // in IMAGE_SOURCE_TYPES on either engine: that set types the node's PRIMARY
244
+ // asset, and 3D Render Pro's is the MP4.
245
+ "pro-3d-render",
246
+ ])
247
+
210
248
  /**
211
249
  * Source node types whose primary output is a LIST that, by default, fans out
212
250
  * one downstream execution per element when an edge leaves them WITHOUT an
@@ -264,6 +302,14 @@ export const FAN_OUT_EACH_HANDLES: Readonly<Record<string, { readonly each: read
264
302
  "camera-switch": { each: ["edl"], primary: "edl" },
265
303
  }
266
304
 
305
+ /**
306
+ * Fan-out nodes whose iterations must ALL succeed: one failed item fails the
307
+ * node (today's rule tolerates a partial list). UGC Clip — a missing clip
308
+ * silently drops a beat from the script (spec R17). Already-started items
309
+ * finish and settle; their jobs are reused on the next run.
310
+ */
311
+ export const FAN_OUT_ALL_OR_NOTHING_TYPES: ReadonlySet<string> = new Set(["ugc-clip"])
312
+
267
313
  /**
268
314
  * Nodes whose saved list is the list their last run PRODUCED — `__listResults`
269
315
  * (Extract Field's JSON value on `generatedJson`) — and never a history in
@@ -325,6 +371,18 @@ export const FAN_IN_TARGETS: Readonly<Record<string, "*" | readonly string[]>> =
325
371
  // input: a list (or a writer that ran once per item) arrives as one
326
372
  // message, never as a burst of sends to the owner's chat.
327
373
  "telegram-account-send": ["in"],
374
+ // The list operators — they READ the whole list wired into them (their
375
+ // executors collect every upstream item themselves) and emit a list. Run
376
+ // once per item by an "each" wire (a Split Text, a List, a node that ran per
377
+ // item), every iteration saw the same whole list and answered with its
378
+ // first match: a Filter List fed 11 stories handed 11 copies of story one
379
+ // downstream, and every paid stage after it ran 11 times on it
380
+ // (2026-10-06). A list operator is never fanned out, on any wire.
381
+ "filter-list": "*",
382
+ deduplicate: "*",
383
+ "merge-lists": "*",
384
+ "sort-list": "*",
385
+ selector: "*",
328
386
  }
329
387
 
330
388
  export function isFanInNodeType(nodeType: string | undefined | null): boolean {
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Render final for agents (`renderFinal: { renderNodeId }` on
3
+ * `POST /v1/workflows/:id/run`, the SDK's `workflows.renderFinal`, MCP
4
+ * `render_final`; decided 2026-10-06). The server derives the nodes the run
5
+ * executes and the render's one-shot Final override from the saved graph.
6
+ *
7
+ * The stable codes a Render final request is refused with when the node it
8
+ * names cannot be rendered. A client branches on the code, never on the text.
9
+ */
10
+
11
+ /** The workflow has no node with that id. */
12
+ export const RENDER_FINAL_NODE_NOT_FOUND = "render_final_node_not_found"
13
+
14
+ /** The node is not a render a Render final can run (an Apply EDL render). */
15
+ export const RENDER_FINAL_NOT_A_RENDER = "render_final_not_a_render"
16
+
17
+ /** Every Render final refusal code. */
18
+ export const RENDER_FINAL_CODES = [RENDER_FINAL_NODE_NOT_FOUND, RENDER_FINAL_NOT_A_RENDER] as const
19
+
20
+ export type RenderFinalCode = (typeof RENDER_FINAL_CODES)[number]