@nodaro/shared 3.21.0 → 3.23.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 +2284 -195
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +1915 -75
  4. package/dist/index.d.ts +1915 -75
  5. package/dist/index.js +2117 -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 +462 -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 +295 -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 +179 -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,51 @@
1
+ /**
2
+ * Length-based speech pricing — the shape of the price, not its value.
3
+ *
4
+ * A speech request (Text to Speech, Text to Dialogue, and the voiced-video
5
+ * add-on) is priced per STARTED 100 characters of the text actually sent,
6
+ * with a minimum number of units per request. The amount of one unit is a
7
+ * `model_pricing` row per model — `<model id>:per-100-chars`, admin-editable
8
+ * — and never lives here. A client that reads that row (GET /v1/models,
9
+ * credits.model-costs) computes exactly what the server reserves with
10
+ * `speechCredits(chars, row)`.
11
+ *
12
+ * Why 100 and not 1,000: the per-request error is at most one unit, and a
13
+ * whole number of units times a charged unit price never under-quotes the
14
+ * charge (the same property the per-second video rows rely on).
15
+ *
16
+ * Decided 2026-10-06. Every name here is a published contract.
17
+ */
18
+ import { canonicalTtsProvider } from "../tts-capabilities.js"
19
+
20
+ /** Characters per price unit. */
21
+ export const SPEECH_PRICE_UNIT_CHARS = 100
22
+
23
+ /** The minimum units a request is priced at, however short its text. */
24
+ export const SPEECH_FLOOR_UNITS = 8
25
+
26
+ /** Appended to a speech model's id to name its per-unit price row. */
27
+ export const SPEECH_UNIT_CREDIT_SUFFIX = ":per-100-chars"
28
+
29
+ /**
30
+ * The price-row id of one unit for the model a request runs as. The legacy
31
+ * `elevenlabs` alias prices on turbo's row, as it runs on turbo; any other id
32
+ * (including the dialogue model) is used as given.
33
+ */
34
+ export function speechUnitCreditId(modelId: string): string {
35
+ return `${canonicalTtsProvider(modelId)}${SPEECH_UNIT_CREDIT_SUFFIX}`
36
+ }
37
+
38
+ /**
39
+ * Units a text of `chars` characters is priced at: every started 100, and
40
+ * never fewer than the floor. A count that is not a finite non-negative
41
+ * number (node data written straight into workflow JSON) is the floor.
42
+ */
43
+ export function speechPriceUnits(chars: number): number {
44
+ const started = Number.isFinite(chars) && chars > 0 ? Math.ceil(chars / SPEECH_PRICE_UNIT_CHARS) : 0
45
+ return Math.max(SPEECH_FLOOR_UNITS, started)
46
+ }
47
+
48
+ /** Base credits for `chars` characters at `perUnitCredits` per unit (the model's `:per-100-chars` row). */
49
+ export function speechCredits(chars: number, perUnitCredits: number): number {
50
+ return speechPriceUnits(chars) * perUnitCredits
51
+ }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Capability lookups for the DIALOGUE lane (`/v1/text-to-dialogue`, the Text to
3
+ * Dialogue node, the voiced-video multi-speaker track).
4
+ *
5
+ * The dialogue models carry a `tts` sheet in `MODEL_CATALOG` like the
6
+ * text-to-speech models, but each lane answers only for its own models: the
7
+ * text-to-speech lookups (`tts-capabilities.ts`) treat a dialogue id as unknown,
8
+ * and these treat a text-to-speech id as unknown. An unknown id here runs as
9
+ * {@link DEFAULT_DIALOGUE_PROVIDER} (v3 dialogue) — not as the text-to-speech
10
+ * fallback (turbo), which has no dialogue form.
11
+ */
12
+ import { MODEL_CATALOG, type TtsCapabilities, type TtsSettingLever } from "./model-catalog.js"
13
+ import { DEFAULT_DIALOGUE_PROVIDER, type DialogueProvider } from "./model-constants.js"
14
+
15
+ /** The sheet of a dialogue model, or `undefined` when the id is not one. Own properties only; a non-string is unknown. */
16
+ export function findDialogueCapabilities(provider: unknown): TtsCapabilities | undefined {
17
+ if (typeof provider !== "string" || !provider) return undefined
18
+ if (!Object.hasOwn(MODEL_CATALOG, provider)) return undefined
19
+ const entry = MODEL_CATALOG[provider]!
20
+ return entry.modes.includes("dialogue") ? entry.tts : undefined
21
+ }
22
+
23
+ /** The dialogue model a request naming `provider` runs on (and is billed as). */
24
+ export function dialogueProviderOf(provider: unknown): DialogueProvider {
25
+ return findDialogueCapabilities(provider) ? (provider as DialogueProvider) : DEFAULT_DIALOGUE_PROVIDER
26
+ }
27
+
28
+ /** The sheet a dialogue request runs under. */
29
+ export function getDialogueCapabilities(provider: unknown): TtsCapabilities {
30
+ return MODEL_CATALOG[dialogueProviderOf(provider)]!.tts!
31
+ }
32
+
33
+ /** The dialogue model honours this voice-setting lever. */
34
+ export function dialogueHasLever(provider: unknown, lever: TtsSettingLever): boolean {
35
+ return getDialogueCapabilities(provider).levers.includes(lever)
36
+ }
37
+
38
+ /** The dialogue model answers `/v1/text-to-dialogue/with-timestamps` (character timings + per-line voice segments). */
39
+ export function dialogueSupportsTimestamps(provider: unknown): boolean {
40
+ return getDialogueCapabilities(provider).timestamps
41
+ }
42
+
43
+ /** `value` is a stability this platform accepts for the dialogue model: one of its steps, or any finite 0–1 when it has none. */
44
+ export function dialogueStabilityAccepted(provider: unknown, value: number): boolean {
45
+ if (!Number.isFinite(value) || value < 0 || value > 1) return false
46
+ const steps = getDialogueCapabilities(provider).stabilitySteps
47
+ return steps ? steps.includes(value) : true
48
+ }
@@ -15,13 +15,15 @@ import { EDL_VERSION } from "./edl.js"
15
15
  // is shared. Mirrors the plugin's own (D13-local) pricing.ts scheme.
16
16
  // ─────────────────────────────────────────────────────────────────────────
17
17
 
18
- export type EditPlanMode = "tighten" | "clips" | "chapters"
18
+ /** `trailer` (Track D1): one short teaser EDL built from the strongest moments,
19
+ * priced like `clips` (the per-minute rate plus the clips flat). */
20
+ export type EditPlanMode = "tighten" | "clips" | "chapters" | "trailer"
19
21
  export type EditPlanTier = "economy" | "standard" | "premium"
20
- export const EDIT_PLAN_MODES: readonly EditPlanMode[] = ["tighten", "clips", "chapters"]
22
+ export const EDIT_PLAN_MODES: readonly EditPlanMode[] = ["tighten", "clips", "chapters", "trailer"]
21
23
  export const EDIT_PLAN_TIERS: readonly EditPlanTier[] = ["economy", "standard", "premium"]
22
24
  /** The coarse duration ladder (MINUTES) a probed source duration rounds UP to;
23
- * the composite credit id carries the bucket. 3 modes × 3 tiers × 6 buckets =
24
- * 54 composites (+ the bare `edit-plan`). */
25
+ * the composite credit id carries the bucket. 4 modes × 3 tiers × 6 buckets =
26
+ * 72 composites (+ the bare `edit-plan`). */
25
27
  export const EDIT_PLAN_BUCKET_MINUTES: readonly number[] = [15, 30, 60, 90, 120, 180]
26
28
  /** Hard duration cap (design §7.4). */
27
29
  export const EDIT_PLAN_MAX_MINUTES = 180
@@ -57,9 +59,18 @@ export function buildEditPlanCreditId(mode: EditPlanMode, tier: EditPlanTier, du
57
59
  return `edit-plan:${mode}:${tier}:${editPlanBucketMinutes(durationSec)}m`
58
60
  }
59
61
 
60
- /** Narrow an arbitrary value to a known edit-plan mode, defaulting to "tighten". */
62
+ /** Narrow an arbitrary value to a known edit-plan mode, defaulting to "tighten".
63
+ * For display and estimates only: anything that DISPATCHES a plan must use
64
+ * {@link parseEditPlanMode} and refuse an unknown mode, or that mode is planned
65
+ * (and charged) as tighten. */
61
66
  export function asEditPlanMode(v: unknown): EditPlanMode {
62
- return v === "clips" || v === "chapters" ? v : "tighten"
67
+ return parseEditPlanMode(v) ?? "tighten"
68
+ }
69
+
70
+ /** The strict sibling of {@link asEditPlanMode}: the mode when `v` is exactly a
71
+ * known edit-plan mode, otherwise `undefined` — never a substitute. */
72
+ export function parseEditPlanMode(v: unknown): EditPlanMode | undefined {
73
+ return typeof v === "string" && (EDIT_PLAN_MODES as readonly string[]).includes(v) ? (v as EditPlanMode) : undefined
63
74
  }
64
75
 
65
76
  /** Narrow an arbitrary value to a known edit-plan tier, defaulting to "standard". */
@@ -70,13 +81,13 @@ export function asEditPlanTier(v: unknown): EditPlanTier {
70
81
  /**
71
82
  * Unwrap an `edit-plan` job's `output_data` into the value stored on the node's
72
83
  * `data.generatedJson`, which every output extractor then reads. This is the ONE
73
- * place the three modes are normalized (the same rule on both engines and every
84
+ * place the modes are normalized (the same rule on both engines and every
74
85
  * result-application site, so audit-dag parity can't drift):
75
86
  * - `clips` → the BARE `Edl[]` (T5: the `list` fan-out reads `Array.isArray`
76
87
  * on `generatedJson`; each element becomes one JSON-stringified
77
88
  * item a downstream `edl` input `normalizeEdl`-parses).
78
89
  * - `chapters` → the `{ version, chapters }` object.
79
- * - `tighten` → the `Edl` object at top level.
90
+ * - `tighten` / `trailer` → the `Edl` object at top level.
80
91
  *
81
92
  * The cloud relay object-spreads `output_data` and adds `viaNodaroCloud: true`;
82
93
  * that key (and any other bookkeeping) is stripped here. The unwrap lives HERE —
@@ -90,7 +101,7 @@ export function unwrapEditPlanOutput(outputData: unknown): unknown {
90
101
  if (Array.isArray(o.clips)) return o.clips
91
102
  // chapters: { version, chapters: [...] } → the object, minus bookkeeping.
92
103
  if (Array.isArray(o.chapters)) return { version: EDL_VERSION, chapters: o.chapters }
93
- // tighten: the Edl object at top level → drop the relay's viaNodaroCloud.
104
+ // tighten / trailer: the Edl object at top level → drop the relay's viaNodaroCloud.
94
105
  const { viaNodaroCloud: _viaNodaroCloud, ...rest } = o
95
106
  return rest
96
107
  }
@@ -160,6 +160,18 @@ function fnv1a64(text: string): string {
160
160
  return hi.toString(16).padStart(8, "0") + lo.toString(16).padStart(8, "0")
161
161
  }
162
162
 
163
+ /**
164
+ * The basis of every plan object already hashed. Hashing walks the whole plan
165
+ * (about 20 ms on a large one), and both engines read the same saved plan
166
+ * object many times: each review edit is a new `editedEdl` object over an
167
+ * unchanged plan, and a run reads a seeded plan at every wire. Keyed by the
168
+ * plan OBJECT, so it relies on a plan never being mutated in place: the editor
169
+ * never mutates node data (a new plan is a new object), and the server reads
170
+ * `generatedJson` as stored. A copy of a plan is another object and is hashed
171
+ * on its own.
172
+ */
173
+ const basisByPlan = new WeakMap<object, string>()
174
+
163
175
  /**
164
176
  * The fingerprint of an Edit Plan's stored output (`data.generatedJson`, as
165
177
  * unwrapped): FNV-1a-64 of the UTF-8 bytes of its key-sorted JSON, as 16
@@ -167,7 +179,12 @@ function fnv1a64(text: string): string {
167
179
  * it; any change to a value, or to array order, changes it.
168
180
  */
169
181
  export function editPlanBasis(plan: unknown): string {
170
- return fnv1a64(canonicalJson(plan) ?? "")
182
+ if (typeof plan !== "object" || plan === null) return fnv1a64(canonicalJson(plan) ?? "")
183
+ const cached = basisByPlan.get(plan)
184
+ if (cached !== undefined) return cached
185
+ const basis = fnv1a64(canonicalJson(plan) ?? "")
186
+ basisByPlan.set(plan, basis)
187
+ return basis
171
188
  }
172
189
 
173
190
  // ─────────────────────────────────────────────────────────────────────────
@@ -306,6 +323,28 @@ export function editPlanSavedOutput(data: Readonly<Record<string, unknown>>): Ed
306
323
  return output
307
324
  }
308
325
 
326
+ /**
327
+ * What a result writer writes when a plan lands on an Edit Plan node: the plan
328
+ * itself, and `editedEdl: undefined` ONLY when the plan is not the one the
329
+ * person's review was made on (its `editPlanBasis` differs from
330
+ * `editedEdl.basis`; an edit that names no plan counts as different). The same
331
+ * plan landing again, for example a reopen while the run is still live after
332
+ * the plan finished, keeps the review (decided 2026-10-05). On a keep the patch
333
+ * does not name `editedEdl` at all, so a merging write leaves the review as it
334
+ * is. Pass the review the node holds now.
335
+ *
336
+ * The one place a review is cleared: `frontend/src/lib/__tests__/
337
+ * edit-plan-saved-output-sites.test.ts` fails on a clearing write anywhere else.
338
+ */
339
+ export function editPlanResultPatch(
340
+ plan: unknown,
341
+ editedEdl: unknown,
342
+ ): { readonly generatedJson: unknown; readonly editedEdl?: undefined } {
343
+ const basis = isRecord(editedEdl) ? editedEdl.basis : undefined
344
+ const madeOnThisPlan = typeof basis === "string" && basis.length > 0 && basis === editPlanBasis(plan)
345
+ return madeOnThisPlan ? { generatedJson: plan } : { generatedJson: plan, editedEdl: undefined }
346
+ }
347
+
309
348
  /**
310
349
  * Check a review edit before it is saved. The envelope (version, kind), the
311
350
  * basis, then the plan's shape and one decision per clip, and, for a Tighten edit,
package/src/edl.ts CHANGED
@@ -280,7 +280,12 @@ export function edlDurationMs(edl: Edl): number {
280
280
  /** The output-clock start time of each segment (index-aligned to
281
281
  * `edl.segments`), accounting for D17 overlap: the transition INTO segment k
282
282
  * pulls its duration back from the boundary. `outputStart(0) = 0`;
283
- * `outputStart(n) + dur(n) === edlDurationMs`. */
283
+ * `outputStart(n) + dur(n) === edlDurationMs`. The one output clock every
284
+ * remap reads — a player seeking a rendered cut reads it too. */
285
+ export function edlSegmentOutputStarts(edl: Edl): number[] {
286
+ return segmentOutputStarts(edl)
287
+ }
288
+
284
289
  function segmentOutputStarts(edl: Edl): number[] {
285
290
  const starts: number[] = []
286
291
  let cursor = 0
@@ -473,6 +478,27 @@ export function remapMsThroughEdl(edl: Edl, sourceMs: number, sourceId?: string)
473
478
  return null
474
479
  }
475
480
 
481
+ /**
482
+ * The inverse of `remapMsThroughEdl`: the master-clock instant the rendered
483
+ * output plays at `outputMs`, or `null` before the start, at or past the end,
484
+ * and for a non-finite time. Inside a crossfade both segments play; the
485
+ * INCOMING one (the later segment) is the one named, since the cut has moved
486
+ * to it. On an EDL that never revisits master time (a Tighten cut),
487
+ * `remapMsThroughEdl(edl, outputMsToMasterMs(edl, t)) === t` for every output
488
+ * instant `t`; an EDL that re-reads a span maps two output instants to one
489
+ * master instant, and the remap names the first.
490
+ */
491
+ export function outputMsToMasterMs(edl: Edl, outputMs: number): number | null {
492
+ if (!Number.isFinite(outputMs) || outputMs < 0) return null
493
+ const starts = segmentOutputStarts(edl)
494
+ for (let i = edl.segments.length - 1; i >= 0; i--) {
495
+ const seg = edl.segments[i]
496
+ const dur = Math.max(0, seg.outMs - seg.inMs)
497
+ if (outputMs >= starts[i] && outputMs < starts[i] + dur) return Math.round(seg.inMs + (outputMs - starts[i]))
498
+ }
499
+ return null
500
+ }
501
+
476
502
  /**
477
503
  * Remap a transcript onto the rendered output: drop words that fall entirely
478
504
  * in removed material, clip a word that straddles a cut to its kept part, and
@@ -0,0 +1,41 @@
1
+ import type { NodeSkipReason } from "./node-execution-state.js"
2
+
3
+ /**
4
+ * How a COMPLETED run ended, derived on read from its node states — never a
5
+ * column: the orchestrator, the boot sweep and the reconcile cron all write
6
+ * `completed`, and a column only one of them set would read "succeeded" for
7
+ * the runs the others closed. Every surface that shows a run (the editor's
8
+ * run bar and Executions tab, a published app, Present, the REST / SDK
9
+ * execution shapes, MCP `get_app_run` / `diagnose_run`) asks this one rule.
10
+ */
11
+ export type ExecutionOutcome = "succeeded" | "nothing_new"
12
+
13
+ interface SkipStateLike {
14
+ readonly status?: unknown
15
+ readonly skipReason?: unknown
16
+ }
17
+
18
+ const EMPTY_INPUT: NodeSkipReason = "empty_input"
19
+
20
+ /** The nodes a run skipped for want of input: nothing upstream produced any text in this run. */
21
+ export function countEmptyInputSkips(nodeStates: Readonly<Record<string, SkipStateLike>> | null | undefined): number {
22
+ let count = 0
23
+ for (const state of Object.values(nodeStates ?? {})) {
24
+ if (state && state.status === "skipped" && state.skipReason === EMPTY_INPUT) count += 1
25
+ }
26
+ return count
27
+ }
28
+
29
+ /**
30
+ * `nothing_new` when a completed run skipped at least one node for want of
31
+ * input (a feed that found no new posts, a writer with nothing to write);
32
+ * `succeeded` for any other completed run; undefined for a run that has not
33
+ * completed — a failed or cancelled run has no outcome, it has a status.
34
+ */
35
+ export function executionOutcome(
36
+ status: unknown,
37
+ nodeStates: Readonly<Record<string, SkipStateLike>> | null | undefined,
38
+ ): ExecutionOutcome | undefined {
39
+ if (status !== "completed") return undefined
40
+ return countEmptyInputSkips(nodeStates) > 0 ? "nothing_new" : "succeeded"
41
+ }
@@ -0,0 +1,23 @@
1
+ /** One fan-out item's notes: its warnings and its real length (UGC Clip). */
2
+ export interface FanOutItemMeta { readonly warnings: readonly string[]; readonly durationSec: number | null }
3
+ /** One row of UGC Cards' `notes` input. */
4
+ export interface ClipNote { readonly clip: number; readonly warnings: readonly string[]; readonly durationSec?: number }
5
+
6
+ export function fanOutItemMeta(output: { clipWarnings?: unknown; durationSec?: unknown } | null | undefined): FanOutItemMeta {
7
+ const w = output?.clipWarnings
8
+ const d = output?.durationSec
9
+ return {
10
+ warnings: Array.isArray(w) ? w.filter((x): x is string => typeof x === "string") : [],
11
+ durationSec: typeof d === "number" && Number.isFinite(d) && d > 0 ? d : null,
12
+ }
13
+ }
14
+
15
+ /** Row-aligned meta (or one single output) → the notes UGC Cards reads, clip numbers from 1. */
16
+ export function clipNotesFrom(meta: ReadonlyArray<FanOutItemMeta | null | undefined> | undefined, single?: FanOutItemMeta): ClipNote[] {
17
+ const rows = meta && meta.length > 0 ? meta : single ? [single] : []
18
+ return rows.map((m, i) => ({
19
+ clip: i + 1,
20
+ warnings: m?.warnings ?? [],
21
+ ...(typeof m?.durationSec === "number" ? { durationSec: m.durationSec } : {}),
22
+ }))
23
+ }
@@ -17,6 +17,7 @@
17
17
  */
18
18
  import { evaluateJsonPath, stringifyPathResults } from "./json-path.js"
19
19
  import { expandItemsWithRepeat } from "./repeat-types.js"
20
+ import { isDefaultSelectorConfig, resolveIndex, selectListItems, type SelectorFields } from "./selector.js"
20
21
 
21
22
  /**
22
23
  * The text LANES the input resolvers route somewhere OTHER than the prompt slot
@@ -45,6 +46,8 @@ export const NON_PROMPT_TEXT_LANES: Readonly<Record<string, "*" | readonly strin
45
46
  silence: ["edit-plan"],
46
47
  offsets: ["edit-plan"],
47
48
  qrText: ["image-overlay"],
49
+ layerPlan: ["video-overlay"],
50
+ captionPlan: ["add-captions"],
48
51
  transition: ["slideshow"],
49
52
  // Content Recipe's `link` carries the post's address (inputs.sourceLink), not
50
53
  // the material it analyzes — a list of links fanned through it must not be
@@ -77,6 +80,48 @@ export function compactWithRows(aligned: readonly string[]): { items: string[];
77
80
  return { items, rowIndices }
78
81
  }
79
82
 
83
+ /** What a wire reads off a list with holes when it reads ONE value (`pickHeldRow`). */
84
+ export type HeldRowPick =
85
+ /** This read is not one the holes change: the engine's own rule stands. */
86
+ | { readonly kind: "unaffected" }
87
+ /** The wire carries this value. */
88
+ | { readonly kind: "value"; readonly value: string }
89
+ /** The wire carries nothing (no scalar fallback). */
90
+ | { readonly kind: "none" }
91
+
92
+ /**
93
+ * One value off a ROW-ALIGNED list whose empty rows mean "nothing here" (an
94
+ * Edit Plan's clips as a person's review leaves them: the plan's rows, "" at
95
+ * every dropped clip), for a wire that does not iterate it.
96
+ *
97
+ * Without this, both engines fall back to the source's scalar output (the
98
+ * FIRST kept row of the whole list) whenever the wire's own pick is empty, so
99
+ * a wire could carry a row it never selected:
100
+ * - an Each wire with a range / list selector, outside its fan-out (the
101
+ * selection holds one kept row, or none, so nothing fans out): the first
102
+ * kept row OF THE SELECTION, or nothing when it holds none;
103
+ * - an item pick (`item` / `item:N`), in a fan-out or not: the picked row, or
104
+ * nothing when it is empty.
105
+ * Every other read is `unaffected`: a default Each wire (its scalar IS the
106
+ * first kept row), Selected (`last`), Bundle (`all`), an Each wire inside its
107
+ * fan-out (the iteration reads its own row, and an empty row runs nothing),
108
+ * and an empty list. Both engines call this, so they cannot disagree.
109
+ */
110
+ export function pickHeldRow(
111
+ rows: readonly string[],
112
+ edge: (SelectorFields & { outputMode?: string; itemIndex?: string }) | undefined,
113
+ iterating: boolean,
114
+ ): HeldRowPick {
115
+ if (rows.length === 0) return { kind: "unaffected" }
116
+ const mode = edge?.outputMode ?? "each"
117
+ const held = (row: string | undefined): HeldRowPick => (isBlank(row) ? { kind: "none" } : { kind: "value", value: row! })
118
+ if (mode === "item") return held(rows[resolveIndex(edge?.itemIndex ?? "1", rows.length)])
119
+ if (mode.startsWith("item:")) return held(rows[parseInt(mode.slice(5), 10)])
120
+ if (mode !== "each" || iterating || isDefaultSelectorConfig(edge)) return { kind: "unaffected" }
121
+ const kept = compactWithRows(selectListItems([...rows], edge)).items
122
+ return kept.length > 0 ? { kind: "value", value: kept[0]! } : { kind: "none" }
123
+ }
124
+
80
125
  /**
81
126
  * One column of a manual List table, row-aligned: a row is dropped only when
82
127
  * EVERY cell of it is blank (the trailing empty row the editor keeps), and an
@@ -126,7 +171,7 @@ export function resolveListFanOut<C extends FanOutCandidate>(
126
171
  const held = (c: C) => compactWithRows(c.aligned).items.length
127
172
  const primary = candidates.reduce((best, c) => (held(c) > held(best) ? c : best))
128
173
  const space = candidates.filter((c) => c.aligned.length === primary.aligned.length)
129
- const feedsPrompt = (c: C) => fanOutTextFeedsPrompt(nodeType, c.targetHandle) && isTextList(c.aligned)
174
+ const feedsPrompt = (c: C) => fanOutTextFeedsPrompt(nodeType, c.targetHandle) && isTextList(c.aligned, nodeType, c.targetHandle)
130
175
  const driver = feedsPrompt(primary) ? primary : (space.find(feedsPrompt) ?? primary)
131
176
  const rowIndices: number[] = []
132
177
  for (let row = 0; row < primary.aligned.length; row++) {
@@ -145,14 +190,38 @@ export function resolveListFanOut<C extends FanOutCandidate>(
145
190
  * the backend worker and the in-browser executor cannot disagree on it.
146
191
  */
147
192
  export function isFanOutUrlItem(item: string): boolean {
148
- return item.startsWith("http") || /\.(png|jpg|jpeg|webp|gif|mp4|mov|webm|mp3|wav|ogg)(\?|$)/i.test(item)
193
+ const s = item.trim()
194
+ // A media link is ONE address. JSON (`{…}` / `[…]`) and a sentence that merely
195
+ // contains an image address are text: a scraped post's JSON with a
196
+ // `.jpg?token=` inside it used to be read as a picture and dropped from the
197
+ // prompt (review finding H3, 2026-10-06).
198
+ if (s.length === 0 || /\s/.test(s) || s.startsWith("{") || s.startsWith("[")) return false
199
+ return s.startsWith("http") || /\.(png|jpg|jpeg|webp|gif|mp4|mov|webm|mp3|wav|ogg)(\?|$)/i.test(s)
200
+ }
201
+
202
+ /**
203
+ * Lanes where an item that LOOKS like a media link is still the item itself —
204
+ * a record's link is what a Save to Collection stores, not a picture to show
205
+ * it. Data-driven so a new consumer declares its lane here, never a name check
206
+ * in either engine.
207
+ */
208
+ const URL_ITEM_IS_TEXT_LANES: Readonly<Record<string, readonly string[]>> = {
209
+ "collection-write": ["in"],
210
+ }
211
+
212
+ /** Does a fan-out item that looks like a link stay TEXT on this lane (the item, not a media input)? */
213
+ export function fanOutUrlItemIsText(nodeType: string | null | undefined, targetHandle: string | null | undefined): boolean {
214
+ const lanes = URL_ITEM_IS_TEXT_LANES[nodeType ?? ""]
215
+ return lanes !== undefined && lanes.includes(targetHandle ?? "")
149
216
  }
150
217
 
151
- /** A media list never supplies a prompt override, whatever handle it is wired to.
218
+ /** A media list never supplies a prompt override, whatever handle it is wired to —
219
+ * except on a lane where a link IS the item (`fanOutUrlItemIsText`).
152
220
  * The FIRST value decides — a column is one kind of thing; this is not a scan. */
153
- function isTextList(aligned: readonly string[]): boolean {
221
+ function isTextList(aligned: readonly string[], nodeType?: string | null, targetHandle?: string | null): boolean {
154
222
  const first = aligned.find((v) => !isBlank(v))
155
- return first !== undefined && !isFanOutUrlItem(first)
223
+ if (first === undefined) return false
224
+ return !isFanOutUrlItem(first) || fanOutUrlItemIsText(nodeType, targetHandle)
156
225
  }
157
226
 
158
227
  /** What a fan-out source resolved to. */
@@ -0,0 +1,59 @@
1
+ /**
2
+ * The 30 preset voices Gemini Omni's audio-persona endpoint accepts, with the
3
+ * style labels its documentation gives each one. DATA, so the API docs, the MCP
4
+ * tool text and any client picker list them from one place instead of copying a
5
+ * table that drifts.
6
+ *
7
+ * A preset is the BASE voice; a persona is that voice plus a free-text
8
+ * description (timbre, pace, emotion) and an example line. Pinning a persona to a
9
+ * character is what keeps one voice across separate clips.
10
+ */
11
+ export interface GeminiOmniVoicePreset {
12
+ id: string
13
+ gender: "female" | "male" | "genderless"
14
+ /** The documented character of the voice ("soft", "raspy", "intellectual"…). */
15
+ style: string
16
+ /** The documented pitch band ("low", "mid-low", "mid", "mid-high", "high"; "younger" for fenrir). */
17
+ pitch: string
18
+ }
19
+
20
+ export const GEMINI_OMNI_VOICE_PRESETS = [
21
+ { id: "achernar", gender: "female", style: "soft", pitch: "high" },
22
+ { id: "achird", gender: "male", style: "friendly", pitch: "mid" },
23
+ { id: "algenib", gender: "male", style: "raspy", pitch: "low" },
24
+ { id: "algieba", gender: "male", style: "easygoing", pitch: "mid-low" },
25
+ { id: "alnilam", gender: "male", style: "steady", pitch: "mid-low" },
26
+ { id: "aoede", gender: "female", style: "brisk", pitch: "mid" },
27
+ { id: "autonoe", gender: "female", style: "bright", pitch: "mid" },
28
+ { id: "callirrhoe", gender: "female", style: "easygoing", pitch: "mid" },
29
+ { id: "charon", gender: "male", style: "intellectual", pitch: "low" },
30
+ { id: "despina", gender: "female", style: "smooth", pitch: "mid" },
31
+ { id: "enceladus", gender: "male", style: "breathy", pitch: "low" },
32
+ { id: "erinome", gender: "female", style: "clear", pitch: "mid" },
33
+ { id: "fenrir", gender: "male", style: "lively", pitch: "younger" },
34
+ { id: "gacrux", gender: "female", style: "mature", pitch: "mid" },
35
+ { id: "iapetus", gender: "male", style: "clear", pitch: "mid-low" },
36
+ { id: "kore", gender: "female", style: "capable", pitch: "mid" },
37
+ { id: "laomedeia", gender: "female", style: "cheerful", pitch: "mid-high" },
38
+ { id: "leda", gender: "female", style: "young", pitch: "mid-high" },
39
+ { id: "orus", gender: "male", style: "steady", pitch: "mid-low" },
40
+ { id: "puck", gender: "male", style: "cheerful", pitch: "mid" },
41
+ { id: "pulcherrima", gender: "genderless", style: "forward", pitch: "mid-high" },
42
+ { id: "rasalgethi", gender: "male", style: "intellectual", pitch: "mid" },
43
+ { id: "sadachbia", gender: "male", style: "vivid", pitch: "low" },
44
+ { id: "sadaltager", gender: "male", style: "knowledgeable", pitch: "mid" },
45
+ { id: "schedar", gender: "male", style: "smooth", pitch: "mid-low" },
46
+ { id: "sulafat", gender: "female", style: "warm", pitch: "mid" },
47
+ { id: "umbriel", gender: "male", style: "smooth", pitch: "low" },
48
+ { id: "vindemiatrix", gender: "female", style: "gentle", pitch: "mid" },
49
+ { id: "zephyr", gender: "female", style: "bright", pitch: "mid-high" },
50
+ { id: "zubenelgenubi", gender: "male", style: "casual", pitch: "mid-low" },
51
+ ] as const satisfies readonly GeminiOmniVoicePreset[]
52
+
53
+ export type GeminiOmniVoicePresetId = (typeof GEMINI_OMNI_VOICE_PRESETS)[number]["id"]
54
+
55
+ /** The preset ids as a non-empty tuple — what `z.enum(...)` takes. */
56
+ export const GEMINI_OMNI_VOICE_PRESET_IDS = GEMINI_OMNI_VOICE_PRESETS.map((v) => v.id) as unknown as readonly [
57
+ GeminiOmniVoicePresetId,
58
+ ...GeminiOmniVoicePresetId[],
59
+ ]