@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
@@ -56,9 +56,9 @@ export type VideoOverlayOutputAspect = (typeof VIDEO_OVERLAY_OUTPUT_ASPECTS)[num
56
56
  /**
57
57
  * Reserved input id for a JSON layer plan. Payload: `VideoOverlayLayer[]` — the
58
58
  * same shape as the node's `layers[]`, a `preset` tag allowed and expanded at
59
- * the boundary. v1 renders NO pip for it: it is not in the node's inputs nor
60
- * any handle registry; both input resolvers route an edge on it into
61
- * `inputs.layerPlan`, which v1 ignores.
59
+ * the boundary. It has a pip on the node; both input resolvers route an edge on
60
+ * it into `inputs.layerPlan`, which `assembleVideoOverlayRequest` reads (plan
61
+ * layers first, then the handle layers).
62
62
  */
63
63
  export const VIDEO_OVERLAY_LAYER_PLAN_HANDLE = "layerPlan"
64
64
  /** Box and look bounds. */
@@ -87,7 +87,7 @@ export const VIDEO_OVERLAY_WARNING_CODES = ["clipped", "skipped", "animated_firs
87
87
  export type VideoOverlayWarningCode = (typeof VIDEO_OVERLAY_WARNING_CODES)[number]
88
88
  export const VIDEO_OVERLAY_ERROR_CODES = [
89
89
  "no_layers", "too_many_layers", "incomplete_box", "layer_without_image",
90
- "time_out_of_range", "end_before_start", "fit_without_aspect", "field_out_of_bounds",
90
+ "time_out_of_range", "end_before_start", "fit_without_aspect", "field_out_of_bounds", "invalid_layer_plan",
91
91
  ] as const
92
92
  export type VideoOverlayErrorCode = (typeof VIDEO_OVERLAY_ERROR_CODES)[number]
93
93
 
@@ -111,6 +111,8 @@ export interface VideoOverlayLayer {
111
111
  imageUrl?: string
112
112
  /** 1-based canvas slot (overlay = 1 … overlay12 = 12; 13 and up handle-less), stamped by both engine assemblies. Messages prefer it. */
113
113
  slot?: number
114
+ /** 1-based entry of a wired layer plan, stamped by the assembly. Messages prefer it. */
115
+ planLayer?: number
114
116
  /** Seconds, 0..3600, stored ms-precise; rendered on the base's frame grid (±1 frame). */
115
117
  start: number
116
118
  /** Seconds, 0..3600, > start; absent = until the video ends. */
@@ -158,12 +160,16 @@ export interface VideoOverlayRequest {
158
160
  /** A request whose layers went through `expandVideoOverlayPresets`. */
159
161
  export interface ExpandedVideoOverlayRequest extends Omit<VideoOverlayRequest, "layers"> {
160
162
  layers: VideoOverlayLayer[]
163
+ /** Set by the assembly when a wired layer plan could not be read; `validateVideoOverlayRequest` reports it first. */
164
+ planError?: "invalid_layer_plan"
161
165
  }
162
166
 
163
167
  /** `output_data.warnings[]`: `layer` = 0-based index of the request's layers (absent for a render-wide warning such as `audio_reencoded`), `slot` when known. */
164
168
  export interface VideoOverlayWarning {
165
169
  readonly layer?: number
166
170
  readonly slot?: number
171
+ /** Set instead of `slot` when the layer came from the layer plan. */
172
+ readonly planLayer?: number
167
173
  readonly code: VideoOverlayWarningCode
168
174
  readonly detail: string
169
175
  }
@@ -418,10 +424,14 @@ export interface VideoOverlayOrderable {
418
424
  readonly zIndex?: number | null
419
425
  /** 1-based canvas slot (stamped by both engine assemblies). */
420
426
  readonly slot?: number | null
427
+ /** 1-based layer-plan entry. Plan layers sit BELOW every slot layer (handle layers draw above the plan), unless they set a `zIndex`. */
428
+ readonly planLayer?: number | null
421
429
  /** 0-based index in the request's `layers[]` (the worker's graph layers carry it). */
422
430
  readonly index?: number | null
423
431
  }
424
432
 
433
+ /** A plan layer's default position sits this far below layer 1's (slot 1 = 0), so the whole plan renders under the slot layers. */
434
+ const PLAN_LAYER_Z_BASE = 1000
425
435
  const isSlot = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v >= 1
426
436
  const isIndex = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v >= 0
427
437
 
@@ -438,7 +448,7 @@ const isIndex = (v: unknown): v is number => typeof v === "number" && Number.isI
438
448
  export function videoOverlayRenderOrder(layers: ReadonlyArray<VideoOverlayOrderable | null | undefined>): number[] {
439
449
  return layers
440
450
  .map((l, i) => {
441
- const own = isSlot(l?.slot) ? l.slot - 1 : isIndex(l?.index) ? l.index : i
451
+ const own = isSlot(l?.planLayer) ? l.planLayer - 1 - PLAN_LAYER_Z_BASE : isSlot(l?.slot) ? l.slot - 1 : isIndex(l?.index) ? l.index : i
442
452
  return { i, z: typeof l?.zIndex === "number" && Number.isFinite(l.zIndex) ? l.zIndex : own }
443
453
  })
444
454
  .sort((a, b) => a.z - b.z || a.i - b.i)
@@ -540,6 +550,7 @@ export interface VideoOverlayIssue {
540
550
  /** 0-based index into the validated `layers[]`. */
541
551
  readonly layer?: number
542
552
  readonly slot?: number
553
+ readonly planLayer?: number
543
554
  readonly params: Readonly<Record<string, string | number>>
544
555
  }
545
556
  export type VideoOverlayValidation = { readonly ok: true } | VideoOverlayIssue
@@ -549,6 +560,8 @@ export interface VideoOverlayValidationInput {
549
560
  readonly outputAspect?: string | null
550
561
  readonly baseFit?: string | null
551
562
  readonly backgroundColor?: string | null
563
+ /** From `assembleVideoOverlayRequest`: the wired layer plan was unreadable. */
564
+ readonly planError?: "invalid_layer_plan"
552
565
  }
553
566
 
554
567
  const inTimeRange = (v: unknown): v is number =>
@@ -614,6 +627,7 @@ export function hasDrawableVideoOverlayBox(layer: unknown): boolean {
614
627
  * FIRST failure, as a code.
615
628
  */
616
629
  export function validateVideoOverlayRequest(body: VideoOverlayValidationInput): VideoOverlayValidation {
630
+ if (body.planError) return { ok: false, code: "invalid_layer_plan", params: {} }
617
631
  const layers = Array.isArray(body.layers) ? body.layers : []
618
632
  if (layers.length === 0) return { ok: false, code: "no_layers", params: {} }
619
633
  if (layers.length > VIDEO_OVERLAY_MAX_LAYERS) {
@@ -626,6 +640,7 @@ export function validateVideoOverlayRequest(body: VideoOverlayValidationInput):
626
640
  code,
627
641
  layer: i,
628
642
  ...(typeof l.slot === "number" ? { slot: l.slot } : {}),
643
+ ...(typeof l.planLayer === "number" ? { planLayer: l.planLayer } : {}),
629
644
  params,
630
645
  })
631
646
  const boxFields = VIDEO_OVERLAY_BOX_FIELDS.filter((f) => l[f] !== undefined && l[f] !== null)
@@ -654,20 +669,41 @@ const MESSAGES: { readonly [C in VideoOverlayErrorCode]: (p: Readonly<Record<str
654
669
  end_before_start: (p) => `end (${p.end} s) must be after start (${p.start} s)`,
655
670
  fit_without_aspect: () => "baseFit and backgroundColor need an outputAspect",
656
671
  field_out_of_bounds: (p) => `${p.field} is out of range (allowed: ${p.allowed})`,
672
+ invalid_layer_plan: () => "the layer plan must be a list of layers",
657
673
  }
658
674
 
659
- /** `Layer <slot>` when the layer came from the canvas, else `layers[<index>]`; "" for a request-wide failure. */
660
- export function videoOverlayLayerLabel(ref: { readonly layer?: number; readonly slot?: number }): string {
675
+ const PLAN_LAYER_WITHOUT_IMAGE = "no image — set imageUrl on this layer in the plan."
676
+
677
+ /** `Plan layer <n>` for a layer-plan entry, `Layer <slot>` when the layer came from the canvas, else `layers[<index>]`; "" for a request-wide failure. */
678
+ export function videoOverlayLayerLabel(ref: { readonly layer?: number; readonly slot?: number; readonly planLayer?: number }): string {
679
+ if (typeof ref.planLayer === "number") return `Plan layer ${ref.planLayer}`
661
680
  return typeof ref.slot === "number" ? `Layer ${ref.slot}` : typeof ref.layer === "number" ? `layers[${ref.layer}]` : ""
662
681
  }
663
682
 
664
683
  /** The ONE English rendering of a verdict — the route's 400 text and the worker's error message. */
665
684
  export function formatVideoOverlayError(issue: VideoOverlayIssue): string {
666
685
  const label = videoOverlayLayerLabel(issue)
667
- const text = MESSAGES[issue.code](issue.params)
686
+ // A plan layer has no handle to connect — its image can only come from its own imageUrl.
687
+ const text = issue.code === "layer_without_image" && typeof issue.planLayer === "number" ? PLAN_LAYER_WITHOUT_IMAGE : MESSAGES[issue.code](issue.params)
668
688
  return label ? `${label}: ${text}` : text
669
689
  }
670
690
 
691
+ /** The wired `layerPlan` value (a JSON string or an array) → its layers, or `invalid_layer_plan`. */
692
+ export function parseVideoOverlayLayerPlan(raw: unknown): { layers: VideoOverlayLayerInput[] } | { error: "invalid_layer_plan" } {
693
+ let value: unknown = raw
694
+ if (typeof raw === "string") {
695
+ try {
696
+ value = JSON.parse(raw)
697
+ } catch {
698
+ return { error: "invalid_layer_plan" }
699
+ }
700
+ }
701
+ if (!Array.isArray(value) || !value.every((l) => l !== null && typeof l === "object" && !Array.isArray(l))) {
702
+ return { error: "invalid_layer_plan" }
703
+ }
704
+ return { layers: value as VideoOverlayLayerInput[] }
705
+ }
706
+
671
707
  /** The node-data fields the assembly reads. */
672
708
  export interface VideoOverlayNodeFields {
673
709
  readonly layers?: ReadonlyArray<VideoOverlayLayerInput | null | undefined> | null
@@ -692,11 +728,19 @@ export interface VideoOverlayNodeFields {
692
728
  * (The canvas never builds that request: its two aspect writers clear both
693
729
  * fields with the aspect.) A value the route's schema would reject — an
694
730
  * unknown aspect or fit, a colour that is not `#rrggbb` — is dropped here.
731
+ *
732
+ * A wired layer plan (`planLayers`, a JSON string or an array) contributes its
733
+ * layers FIRST, then the slot layers: plan layers carry `planLayer` (1-based)
734
+ * and never a `slot`, and a plan layer's image is only its own `imageUrl` —
735
+ * never the index-aligned handle's (R18). An unreadable plan sets `planError`,
736
+ * which the validator reports before anything else.
695
737
  */
696
738
  export function assembleVideoOverlayRequest(input: {
697
739
  readonly videoUrl: string
698
740
  readonly data: VideoOverlayNodeFields
699
741
  readonly wiredImageUrls: ReadonlyArray<string | null | undefined>
742
+ /** The wired `layerPlan` value (string or array); absent when nothing is wired. */
743
+ readonly planLayers?: unknown
700
744
  }): ExpandedVideoOverlayRequest {
701
745
  const stored = Array.isArray(input.data.layers) ? input.data.layers : []
702
746
  const wired = input.wiredImageUrls.slice(0, VIDEO_OVERLAY_HANDLE_IDS.length)
@@ -718,13 +762,19 @@ export function assembleVideoOverlayRequest(input: {
718
762
  const baseFit = isFit(input.data.baseFit) ? input.data.baseFit : undefined
719
763
  const backgroundColor =
720
764
  typeof input.data.backgroundColor === "string" && HEX6.test(input.data.backgroundColor) ? input.data.backgroundColor : undefined
721
- return {
722
- videoUrl: input.videoUrl,
723
- layers,
765
+ const rest = {
724
766
  ...(outputAspect ? { outputAspect } : {}),
725
767
  ...(baseFit ? { baseFit } : {}),
726
768
  ...(backgroundColor ? { backgroundColor } : {}),
727
769
  }
770
+ if (input.planLayers === undefined) return { videoUrl: input.videoUrl, layers, ...rest }
771
+ const plan = parseVideoOverlayLayerPlan(input.planLayers)
772
+ if ("error" in plan) return { videoUrl: input.videoUrl, layers, ...rest, planError: plan.error }
773
+ const planned = expandVideoOverlayPresets(plan.layers).map((l, i) => {
774
+ const { slot: _slot, ...own } = l
775
+ return { ...own, planLayer: i + 1 }
776
+ })
777
+ return { videoUrl: input.videoUrl, layers: [...planned, ...layers], ...rest }
728
778
  }
729
779
 
730
780
  /**
@@ -757,6 +807,8 @@ export interface VideoOverlayComposition {
757
807
  readonly sources: ReadonlyArray<string | null | undefined>
758
808
  /** The node's stored settings — never the expanded request. */
759
809
  readonly data: VideoOverlayNodeFields
810
+ /** The wired `layerPlan` value (string or array); absent when nothing is wired. */
811
+ readonly planLayers?: unknown
760
812
  }
761
813
 
762
814
  /**
@@ -799,14 +851,19 @@ export const VIDEO_OVERLAY_MAX_COMPOSITION_KEY_LENGTH = 65_536
799
851
  export function videoOverlayCompositionKey(c: VideoOverlayComposition): string {
800
852
  const sources = c.sources.map((s) => (typeof s === "string" && s.length > 0 ? s : null))
801
853
  while (sources.length > 0 && sources[sources.length - 1] === null) sources.pop()
802
- return JSON.stringify(
803
- canonicalValue([
804
- c.baseUrl || null,
805
- sources,
806
- Array.isArray(c.data.layers) ? c.data.layers : [],
807
- c.data.outputAspect ?? null,
808
- c.data.baseFit ?? null,
809
- c.data.backgroundColor ?? null,
810
- ]),
811
- )
854
+ const parts: unknown[] = [
855
+ c.baseUrl || null,
856
+ sources,
857
+ Array.isArray(c.data.layers) ? c.data.layers : [],
858
+ c.data.outputAspect ?? null,
859
+ c.data.baseFit ?? null,
860
+ c.data.backgroundColor ?? null,
861
+ ]
862
+ // Appended only when a plan is wired, so a node with no plan keeps today's key.
863
+ // The PARSED plan is hashed: a JSON string and its array give one key.
864
+ if (c.planLayers !== undefined) {
865
+ const plan = parseVideoOverlayLayerPlan(c.planLayers)
866
+ parts.push("error" in plan ? "invalid" : plan.layers)
867
+ }
868
+ return JSON.stringify(canonicalValue(parts))
812
869
  }