@nodaro/shared 3.60.1 → 3.62.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 (261) hide show
  1. package/dist/{chunk-5Y42RIGY.cjs → chunk-2D5LQFV4.cjs} +18 -332
  2. package/dist/chunk-2D5LQFV4.cjs.map +1 -0
  3. package/dist/{chunk-5G23AJBU.cjs → chunk-2HZGDZZN.cjs} +6 -6
  4. package/dist/{chunk-5G23AJBU.cjs.map → chunk-2HZGDZZN.cjs.map} +1 -1
  5. package/dist/{chunk-DS2TOM32.js → chunk-2QKF7M2Z.js} +28 -4
  6. package/dist/chunk-2QKF7M2Z.js.map +1 -0
  7. package/dist/{chunk-CIOXUPCJ.cjs → chunk-2W745U4A.cjs} +228 -355
  8. package/dist/chunk-2W745U4A.cjs.map +1 -0
  9. package/dist/{chunk-LN3EVFRS.js → chunk-3OYO3XCC.js} +70 -6
  10. package/dist/chunk-3OYO3XCC.js.map +1 -0
  11. package/dist/{chunk-5HK5Z5OB.cjs → chunk-4ZEFP2FQ.cjs} +4 -4
  12. package/dist/{chunk-5HK5Z5OB.cjs.map → chunk-4ZEFP2FQ.cjs.map} +1 -1
  13. package/dist/{chunk-KOLC7AF2.js → chunk-5YYN5X57.js} +398 -38
  14. package/dist/chunk-5YYN5X57.js.map +1 -0
  15. package/dist/{chunk-RRPPXZ36.cjs → chunk-6CSXMWL4.cjs} +4 -4
  16. package/dist/{chunk-RRPPXZ36.cjs.map → chunk-6CSXMWL4.cjs.map} +1 -1
  17. package/dist/{chunk-M3SXUUWC.cjs → chunk-6FQBKI2A.cjs} +4 -11
  18. package/dist/chunk-6FQBKI2A.cjs.map +1 -0
  19. package/dist/{chunk-G4XWVWRI.js → chunk-6G7NN4S4.js} +5 -4
  20. package/dist/chunk-6G7NN4S4.js.map +1 -0
  21. package/dist/{chunk-HOKWJXHA.cjs → chunk-A2PX5IRC.cjs} +31 -4
  22. package/dist/chunk-A2PX5IRC.cjs.map +1 -0
  23. package/dist/{chunk-W4M7TNXG.cjs → chunk-AFYTX4AI.cjs} +52 -43
  24. package/dist/chunk-AFYTX4AI.cjs.map +1 -0
  25. package/dist/chunk-ALRXY4QH.cjs +13 -0
  26. package/dist/chunk-ALRXY4QH.cjs.map +1 -0
  27. package/dist/chunk-AOJ6B7K4.cjs +351 -0
  28. package/dist/chunk-AOJ6B7K4.cjs.map +1 -0
  29. package/dist/{chunk-KJZVQIN4.js → chunk-C7POAYFE.js} +3 -3
  30. package/dist/{chunk-KJZVQIN4.js.map → chunk-C7POAYFE.js.map} +1 -1
  31. package/dist/{chunk-6Q6SI7AG.js → chunk-CC4V2B7S.js} +3 -3
  32. package/dist/{chunk-6Q6SI7AG.js.map → chunk-CC4V2B7S.js.map} +1 -1
  33. package/dist/{chunk-GNPJ2JLE.cjs → chunk-CIPPPT7E.cjs} +6 -6
  34. package/dist/{chunk-GNPJ2JLE.cjs.map → chunk-CIPPPT7E.cjs.map} +1 -1
  35. package/dist/{chunk-6XVHYD5R.js → chunk-CLAKSLXF.js} +4 -9
  36. package/dist/chunk-CLAKSLXF.js.map +1 -0
  37. package/dist/chunk-CTANEPMY.js +61 -0
  38. package/dist/chunk-CTANEPMY.js.map +1 -0
  39. package/dist/{chunk-WGKAOUEQ.cjs → chunk-D34K455O.cjs} +3 -2
  40. package/dist/chunk-D34K455O.cjs.map +1 -0
  41. package/dist/chunk-E2HZTGYX.js +331 -0
  42. package/dist/chunk-E2HZTGYX.js.map +1 -0
  43. package/dist/{chunk-SKFJIFEV.cjs → chunk-G3KVK7OU.cjs} +21 -21
  44. package/dist/{chunk-SKFJIFEV.cjs.map → chunk-G3KVK7OU.cjs.map} +1 -1
  45. package/dist/chunk-G4U3HW6W.js +453 -0
  46. package/dist/chunk-G4U3HW6W.js.map +1 -0
  47. package/dist/{chunk-EN2YI5TV.js → chunk-GSFB537T.js} +3 -3
  48. package/dist/{chunk-EN2YI5TV.js.map → chunk-GSFB537T.js.map} +1 -1
  49. package/dist/chunk-HRY7KGAE.cjs +506 -0
  50. package/dist/chunk-HRY7KGAE.cjs.map +1 -0
  51. package/dist/{chunk-6AJOTEVC.js → chunk-I2RQB7VG.js} +3 -3
  52. package/dist/{chunk-6AJOTEVC.js.map → chunk-I2RQB7VG.js.map} +1 -1
  53. package/dist/chunk-IDTKF5EX.cjs +48 -0
  54. package/dist/chunk-IDTKF5EX.cjs.map +1 -0
  55. package/dist/{chunk-DQIJPDHC.cjs → chunk-IWWVPR3W.cjs} +88 -11
  56. package/dist/chunk-IWWVPR3W.cjs.map +1 -0
  57. package/dist/{chunk-URLDVK67.js → chunk-JJNNM23P.js} +3 -3
  58. package/dist/{chunk-URLDVK67.js.map → chunk-JJNNM23P.js.map} +1 -1
  59. package/dist/{chunk-YHVEZVAO.js → chunk-JZGZ26YB.js} +6 -306
  60. package/dist/chunk-JZGZ26YB.js.map +1 -0
  61. package/dist/{chunk-XROE3CAS.cjs → chunk-KHH54GRP.cjs} +120 -79
  62. package/dist/chunk-KHH54GRP.cjs.map +1 -0
  63. package/dist/{chunk-AXT7YNOR.cjs → chunk-KJSRPHJ2.cjs} +48 -47
  64. package/dist/chunk-KJSRPHJ2.cjs.map +1 -0
  65. package/dist/{chunk-FVVD6XY2.js → chunk-KL6GAYTT.js} +13 -4
  66. package/dist/chunk-KL6GAYTT.js.map +1 -0
  67. package/dist/{chunk-AFQFGZN7.cjs → chunk-KYMHFVAZ.cjs} +8 -6
  68. package/dist/chunk-KYMHFVAZ.cjs.map +1 -0
  69. package/dist/{chunk-A6HRY3WF.cjs → chunk-MYJQELFN.cjs} +420 -37
  70. package/dist/chunk-MYJQELFN.cjs.map +1 -0
  71. package/dist/chunk-N5HH46JF.cjs +68 -0
  72. package/dist/chunk-N5HH46JF.cjs.map +1 -0
  73. package/dist/{chunk-BXNPO3PL.cjs → chunk-N7OUQK7E.cjs} +8 -8
  74. package/dist/{chunk-BXNPO3PL.cjs.map → chunk-N7OUQK7E.cjs.map} +1 -1
  75. package/dist/{chunk-JKZVRKN3.js → chunk-NGKKNSK6.js} +31 -8
  76. package/dist/chunk-NGKKNSK6.js.map +1 -0
  77. package/dist/{chunk-SWVGHAYO.js → chunk-O7RZRUMZ.js} +110 -74
  78. package/dist/chunk-O7RZRUMZ.js.map +1 -0
  79. package/dist/{chunk-SCYBGTX6.js → chunk-PTD6EDUU.js} +3 -3
  80. package/dist/{chunk-SCYBGTX6.js.map → chunk-PTD6EDUU.js.map} +1 -1
  81. package/dist/{chunk-BDXXOEBZ.cjs → chunk-QWYFHQYK.cjs} +79 -54
  82. package/dist/chunk-QWYFHQYK.cjs.map +1 -0
  83. package/dist/{chunk-VB2ARGQ6.js → chunk-RGNHHIMN.js} +3 -3
  84. package/dist/chunk-RGNHHIMN.js.map +1 -0
  85. package/dist/{chunk-AZGONXWV.js → chunk-S24ZBUB4.js} +194 -299
  86. package/dist/chunk-S24ZBUB4.js.map +1 -0
  87. package/dist/{chunk-IV6IDECY.js → chunk-S5TMRJMX.js} +4 -4
  88. package/dist/{chunk-IV6IDECY.js.map → chunk-S5TMRJMX.js.map} +1 -1
  89. package/dist/chunk-SMOO5FAH.js +10 -0
  90. package/dist/chunk-SMOO5FAH.js.map +1 -0
  91. package/dist/{chunk-HYBACFYW.js → chunk-SYWR5G3T.js} +16 -7
  92. package/dist/chunk-SYWR5G3T.js.map +1 -0
  93. package/dist/{chunk-GWBQ3GPO.cjs → chunk-TRVWMKNE.cjs} +343 -53
  94. package/dist/chunk-TRVWMKNE.cjs.map +1 -0
  95. package/dist/{chunk-G6GMY5BC.js → chunk-UDDVDQMF.js} +298 -36
  96. package/dist/chunk-UDDVDQMF.js.map +1 -0
  97. package/dist/{chunk-PONP5J5E.cjs → chunk-V24EPI5N.cjs} +13 -3
  98. package/dist/chunk-V24EPI5N.cjs.map +1 -0
  99. package/dist/{chunk-HDHLZK7C.cjs → chunk-VACPZPUA.cjs} +5 -5
  100. package/dist/{chunk-HDHLZK7C.cjs.map → chunk-VACPZPUA.cjs.map} +1 -1
  101. package/dist/{chunk-ICDLYU4I.js → chunk-Y6X7UJSD.js} +10 -9
  102. package/dist/chunk-Y6X7UJSD.js.map +1 -0
  103. package/dist/chunk-YCXRSWCQ.js +42 -0
  104. package/dist/chunk-YCXRSWCQ.js.map +1 -0
  105. package/dist/entries/apps.cjs +44 -44
  106. package/dist/entries/apps.js +9 -9
  107. package/dist/entries/credits.cjs +217 -152
  108. package/dist/entries/credits.d.cts +112 -6
  109. package/dist/entries/credits.d.ts +112 -6
  110. package/dist/entries/credits.js +13 -8
  111. package/dist/entries/entities.cjs +188 -143
  112. package/dist/entries/entities.d.cts +122 -1
  113. package/dist/entries/entities.d.ts +122 -1
  114. package/dist/entries/entities.js +2 -1
  115. package/dist/entries/llm-models.d.cts +2 -1
  116. package/dist/entries/llm-models.d.ts +2 -1
  117. package/dist/entries/media.cjs +92 -87
  118. package/dist/entries/media.d.cts +11 -1
  119. package/dist/entries/media.d.ts +11 -1
  120. package/dist/entries/media.js +3 -2
  121. package/dist/entries/model-catalog.cjs +207 -99
  122. package/dist/entries/model-catalog.d.cts +90 -4
  123. package/dist/entries/model-catalog.d.ts +90 -4
  124. package/dist/entries/model-catalog.js +5 -5
  125. package/dist/entries/models.cjs +407 -294
  126. package/dist/entries/models.d.cts +4 -3
  127. package/dist/entries/models.d.ts +4 -3
  128. package/dist/entries/models.js +6 -5
  129. package/dist/entries/nodes.cjs +241 -233
  130. package/dist/entries/nodes.d.cts +15 -2
  131. package/dist/entries/nodes.d.ts +15 -2
  132. package/dist/entries/nodes.js +10 -10
  133. package/dist/entries/pipeline.cjs +152 -152
  134. package/dist/entries/pipeline.d.cts +2 -1
  135. package/dist/entries/pipeline.d.ts +2 -1
  136. package/dist/entries/pipeline.js +3 -3
  137. package/dist/entries/ugc.cjs +71 -71
  138. package/dist/entries/ugc.js +4 -4
  139. package/dist/entries/video.cjs +308 -204
  140. package/dist/entries/video.d.cts +480 -98
  141. package/dist/entries/video.d.ts +480 -98
  142. package/dist/entries/video.js +8 -4
  143. package/dist/entries/workflow.cjs +111 -99
  144. package/dist/entries/workflow.d.cts +29 -2
  145. package/dist/entries/workflow.d.ts +29 -2
  146. package/dist/entries/workflow.js +2 -2
  147. package/dist/{gpt-image-2-6-BeZdT-pW.d.cts → gpt-image-2-6-jIRQBRag.d.cts} +6 -0
  148. package/dist/{gpt-image-2-6-BeZdT-pW.d.ts → gpt-image-2-6-jIRQBRag.d.ts} +6 -0
  149. package/dist/index.cjs +2321 -1870
  150. package/dist/index.d.cts +10 -10
  151. package/dist/index.d.ts +10 -10
  152. package/dist/index.js +26 -23
  153. package/dist/{model-catalog-D6Es7VG-.d.cts → model-catalog-CCEcv08q.d.cts} +179 -14
  154. package/dist/{model-catalog-D6Es7VG-.d.ts → model-catalog-CCEcv08q.d.ts} +179 -14
  155. package/dist/{model-constants-22k3fjp1.d.cts → model-constants-B88p6XR0.d.ts} +305 -20
  156. package/dist/{model-constants-22k3fjp1.d.ts → model-constants-Cf3zaITt.d.cts} +305 -20
  157. package/package.json +1 -1
  158. package/src/__tests__/extend-providers.test.ts +114 -0
  159. package/src/__tests__/fixtures/mask-composite-quote-parity.json +118 -0
  160. package/src/__tests__/fixtures/root-exports.baseline.json +68 -0
  161. package/src/__tests__/gpt-image-2-6-formats.test.ts +4 -1
  162. package/src/__tests__/gpt-image-2-6.test.ts +7 -0
  163. package/src/__tests__/grok-video-15-catalog.test.ts +189 -0
  164. package/src/__tests__/gvp-supported-providers.test.ts +5 -2
  165. package/src/__tests__/image-mask-mode.test.ts +34 -1
  166. package/src/__tests__/mask-edit-follows-source.test.ts +150 -0
  167. package/src/__tests__/minimax-h3-image.test.ts +140 -0
  168. package/src/__tests__/model-makers.test.ts +49 -11
  169. package/src/__tests__/model-tree.test.ts +13 -0
  170. package/src/__tests__/retired-video-provider.test.ts +15 -5
  171. package/src/__tests__/seedance-25-catalog-modes.test.ts +1 -1
  172. package/src/__tests__/seedance-task-type.test.ts +178 -0
  173. package/src/__tests__/seedream-5-5.test.ts +117 -0
  174. package/src/__tests__/unit-contract-compose.test.ts +27 -1
  175. package/src/__tests__/unit-contracts.test.ts +20 -6
  176. package/src/__tests__/upscale-factors.test.ts +107 -0
  177. package/src/__tests__/video-character-refs.test.ts +20 -2
  178. package/src/__tests__/video-collapse-parity.test.ts +19 -0
  179. package/src/__tests__/video-overlay-geometry.test.ts +68 -0
  180. package/src/__tests__/video-overlay-layer-plan.test.ts +3 -4
  181. package/src/__tests__/video-overlay-layouts.test.ts +529 -0
  182. package/src/__tests__/video-overlay-pricing.test.ts +61 -0
  183. package/src/__tests__/video-overlay-validate.test.ts +128 -0
  184. package/src/__tests__/video-overlay-wired-kind.test.ts +207 -0
  185. package/src/__tests__/video-overlay.test.ts +280 -194
  186. package/src/__tests__/video-ref-limits.test.ts +2 -1
  187. package/src/__tests__/video-reference-only.test.ts +6 -2
  188. package/src/__tests__/video-start-frame-only.test.ts +98 -0
  189. package/src/__tests__/wired-character-names.test.ts +220 -0
  190. package/src/credit-estimators/index.ts +8 -0
  191. package/src/credit-estimators/video-overlay.ts +70 -0
  192. package/src/credit-identifiers.ts +102 -5
  193. package/src/entity-image-url.ts +21 -0
  194. package/src/entries/credits.ts +14 -0
  195. package/src/entries/entities.ts +14 -0
  196. package/src/entries/model-catalog.ts +39 -1
  197. package/src/entries/models.ts +34 -0
  198. package/src/entries/nodes.ts +2 -0
  199. package/src/entries/video.ts +6 -0
  200. package/src/entries/workflow.ts +1 -0
  201. package/src/generated/unit-contracts.ts +8 -1
  202. package/src/gpt-image-2-6.ts +6 -0
  203. package/src/input-image-pricing.ts +76 -0
  204. package/src/mask-composite.ts +11 -0
  205. package/src/minimax-h3-image.ts +61 -0
  206. package/src/model-catalog.ts +512 -48
  207. package/src/model-constants.ts +602 -34
  208. package/src/node-default-mappings.ts +12 -2
  209. package/src/node-execution-state.ts +4 -1
  210. package/src/producer-types.ts +23 -1
  211. package/src/seedance-task-type.ts +37 -0
  212. package/src/seedream-5-5.ts +45 -0
  213. package/src/unit-contract-compose.ts +4 -1
  214. package/src/upscale-factors.ts +111 -0
  215. package/src/video-character-refs.ts +7 -4
  216. package/src/video-overlay-geometry.ts +99 -0
  217. package/src/video-overlay-input.ts +25 -0
  218. package/src/video-overlay-layout-ids.ts +48 -0
  219. package/src/video-overlay-layouts.ts +315 -0
  220. package/src/video-overlay-validate.ts +223 -0
  221. package/src/video-overlay-video-layers.ts +304 -0
  222. package/src/video-overlay.ts +165 -297
  223. package/src/video-ui-defaults.ts +8 -6
  224. package/src/wired-character-names.ts +202 -0
  225. package/src/wired-image-size.ts +55 -0
  226. package/dist/chunk-5Y42RIGY.cjs.map +0 -1
  227. package/dist/chunk-6XVHYD5R.js.map +0 -1
  228. package/dist/chunk-A6HRY3WF.cjs.map +0 -1
  229. package/dist/chunk-AFQFGZN7.cjs.map +0 -1
  230. package/dist/chunk-AXT7YNOR.cjs.map +0 -1
  231. package/dist/chunk-AZGONXWV.js.map +0 -1
  232. package/dist/chunk-BDXXOEBZ.cjs.map +0 -1
  233. package/dist/chunk-CIOXUPCJ.cjs.map +0 -1
  234. package/dist/chunk-DQIJPDHC.cjs.map +0 -1
  235. package/dist/chunk-DS2TOM32.js.map +0 -1
  236. package/dist/chunk-FVVD6XY2.js.map +0 -1
  237. package/dist/chunk-G4XWVWRI.js.map +0 -1
  238. package/dist/chunk-G6GMY5BC.js.map +0 -1
  239. package/dist/chunk-G7ZYZQKO.cjs +0 -27
  240. package/dist/chunk-G7ZYZQKO.cjs.map +0 -1
  241. package/dist/chunk-GWBQ3GPO.cjs.map +0 -1
  242. package/dist/chunk-HNEF2N5C.cjs +0 -19
  243. package/dist/chunk-HNEF2N5C.cjs.map +0 -1
  244. package/dist/chunk-HOKWJXHA.cjs.map +0 -1
  245. package/dist/chunk-HYBACFYW.js.map +0 -1
  246. package/dist/chunk-ICDLYU4I.js.map +0 -1
  247. package/dist/chunk-JKZVRKN3.js.map +0 -1
  248. package/dist/chunk-KOLC7AF2.js.map +0 -1
  249. package/dist/chunk-LN3EVFRS.js.map +0 -1
  250. package/dist/chunk-M3SXUUWC.cjs.map +0 -1
  251. package/dist/chunk-MHY47BLL.js +0 -23
  252. package/dist/chunk-MHY47BLL.js.map +0 -1
  253. package/dist/chunk-PONP5J5E.cjs.map +0 -1
  254. package/dist/chunk-SWVGHAYO.js.map +0 -1
  255. package/dist/chunk-VB2ARGQ6.js.map +0 -1
  256. package/dist/chunk-VYQ25YQF.js +0 -17
  257. package/dist/chunk-VYQ25YQF.js.map +0 -1
  258. package/dist/chunk-W4M7TNXG.cjs.map +0 -1
  259. package/dist/chunk-WGKAOUEQ.cjs.map +0 -1
  260. package/dist/chunk-XROE3CAS.cjs.map +0 -1
  261. package/dist/chunk-YHVEZVAO.js.map +0 -1
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Video Overlay — timed image layers over a video. The wire contract of the
2
+ * Video Overlay — timed image and video layers over a video. The wire contract of the
3
3
  * `video-overlay` node, `POST /v1/video-overlay`, the `overlay_images` MCP
4
4
  * verb, `client.media.videoOverlay` and `nodaro media video-overlay`, defined
5
5
  * ONCE:
@@ -12,8 +12,8 @@
12
12
  * never switch on the tag;
13
13
  * - `expandVideoOverlayLayer` / `expandVideoOverlayPresets`: the one
14
14
  * normaliser every write boundary calls;
15
- * - `resolveVideoOverlayGeometry`: the one placement function the canvas
16
- * preview and the ffmpeg worker both call;
15
+ * - `resolveVideoOverlayGeometry` (in `video-overlay-geometry.ts`): the one
16
+ * placement function the canvas preview and the ffmpeg worker both call;
17
17
  * - `assembleVideoOverlayRequest`: the one node-data → request assembly both
18
18
  * workflow engines call;
19
19
  * - `videoOverlayCompositionKey` (+ `videoOverlaySlotSources`): the freshness
@@ -22,14 +22,18 @@
22
22
  * `VIDEO_OVERLAY_MAX_COMPOSITION_KEY_LENGTH`) and the DAG payload compute
23
23
  * it with this one function, and the node compares it against the key of
24
24
  * its current settings;
25
- * - `validateVideoOverlayRequest`: what a schema cannot express, at every
26
- * engine entry. It returns a CODE, never English: `formatVideoOverlayError`
27
- * renders the route / worker text, the canvas renders the code through its
28
- * dictionaries.
25
+ * - `validateVideoOverlayRequest` (in `video-overlay-validate.ts`): what a
26
+ * schema cannot express, at every engine entry. It returns a CODE, never
27
+ * English: `formatVideoOverlayError` renders the route / worker text, the
28
+ * canvas renders the code through its dictionaries.
29
+ * The geometry and validator siblings import from this file; it imports
30
+ * nothing from them.
29
31
  * Wire contract only — no prompt content, no I/O.
30
32
  */
31
- import { OVERLAY_ANCHORS, type OverlayAnchor } from "./image-overlay-layers.js"
32
- import { ASPECT_RATIO_DIMENSIONS } from "./model-constants.js"
33
+ import type { OverlayAnchor } from "./image-overlay-layers.js"
34
+ import { asLayer, isFit, nonEmpty, storedLayout } from "./video-overlay-input.js"
35
+ import { isVideoOverlayVideoLayer, withoutEmptyVideoOverlaySources, withoutImpliedVideoOverlayAnimate, withoutVideoOverlaySound } from "./video-overlay-video-layers.js"
36
+ import type { VideoOverlayLayoutId } from "./video-overlay-layout-ids.js"
33
37
 
34
38
  /** Engine + MCP contract: layers per request. */
35
39
  export const VIDEO_OVERLAY_MAX_LAYERS = 20
@@ -72,6 +76,22 @@ export const VIDEO_OVERLAY_BOUNDS = {
72
76
  } as const
73
77
  /** Σ downloaded layer bytes per job. */
74
78
  export const VIDEO_OVERLAY_MAX_TOTAL_LAYER_BYTES = 100 * 1024 * 1024
79
+ /** A video layer's `sound.volume` (1 = as recorded). */
80
+ export const VIDEO_OVERLAY_VOLUME_BOUNDS = [0, 1] as const
81
+ /**
82
+ * Video layers per request. Measured on the pinned ffmpeg: a 60 s base with
83
+ * two video layers renders well inside the 10-minute limit (three times its
84
+ * slowest render), and three video layers do not at 60 s.
85
+ */
86
+ export const VIDEO_OVERLAY_MAX_VIDEO_LAYERS = 2
87
+ /**
88
+ * The longest base video, seconds, for a run with a video layer — the
89
+ * longest base for which one and two video layers both render within the
90
+ * 10-minute limit with room for three times the slowest measured render.
91
+ */
92
+ export const VIDEO_OVERLAY_VIDEO_MAX_BASE_SEC = 60
93
+ /** One video layer's file, bytes. */
94
+ export const VIDEO_OVERLAY_MAX_LAYER_VIDEO_BYTES = 200 * 1024 * 1024
75
95
  /** Fade + scale ramp, seconds each way (clamped to half of a short layer). */
76
96
  export const VIDEO_OVERLAY_ANIMATION_SEC = 0.15
77
97
  /** The scale a layer grows from and shrinks back to during the ramp. */
@@ -83,11 +103,13 @@ export const VIDEO_OVERLAY_BADGE_INSET = 4
83
103
  export const VIDEO_OVERLAY_DEFAULT_BACKGROUND = "#000000"
84
104
  /** The six box fields — exactly what a preset writes. */
85
105
  export const VIDEO_OVERLAY_BOX_FIELDS = ["anchor", "x", "y", "width", "height", "fit"] as const
86
- export const VIDEO_OVERLAY_WARNING_CODES = ["clipped", "skipped", "animated_first_frame", "audio_reencoded"] as const
106
+ export const VIDEO_OVERLAY_WARNING_CODES = ["clipped", "skipped", "animated_first_frame", "audio_reencoded", "layer_no_audio"] as const
87
107
  export type VideoOverlayWarningCode = (typeof VIDEO_OVERLAY_WARNING_CODES)[number]
88
108
  export const VIDEO_OVERLAY_ERROR_CODES = [
89
109
  "no_layers", "too_many_layers", "incomplete_box", "layer_without_image",
90
110
  "time_out_of_range", "end_before_start", "fit_without_aspect", "field_out_of_bounds", "invalid_layer_plan",
111
+ "layer_two_sources", "too_many_video_layers", "sound_without_video",
112
+ "base_box_needs_aspect", "layout_needs_aspect", "layout_needs_video_layer", "layout_conflicts_base_box",
91
113
  ] as const
92
114
  export type VideoOverlayErrorCode = (typeof VIDEO_OVERLAY_ERROR_CODES)[number]
93
115
 
@@ -99,6 +121,14 @@ export interface VideoOverlayBox {
99
121
  readonly height?: number
100
122
  readonly fit: VideoOverlayFit
101
123
  }
124
+ /** A box as a writer may send it (the base box from workflow JSON): every field optional; `null` means absent. */
125
+ export type VideoOverlayBoxInput = { readonly [K in keyof VideoOverlayBox]?: VideoOverlayBox[K] | null }
126
+
127
+ /** A video layer's sound, mixed with the base's during the layer's window. Absent = the layer is silent. */
128
+ export interface VideoOverlaySound {
129
+ /** 0..1 (`VIDEO_OVERLAY_VOLUME_BOUNDS`). */
130
+ readonly volume: number
131
+ }
102
132
 
103
133
  /** A layer as stored and enqueued — complete: every box and look field present. */
104
134
  export interface VideoOverlayLayer {
@@ -109,6 +139,14 @@ export interface VideoOverlayLayer {
109
139
  * and the run-time merge is still `wired ?? imageUrl` everywhere.
110
140
  */
111
141
  imageUrl?: string
142
+ /**
143
+ * The layer's video, instead of `imageUrl` — never both. Cleared by wiring
144
+ * exactly as `imageUrl` is; a wired handle's source is a video when the
145
+ * assembly is told so (`wiredVideoSlots`).
146
+ */
147
+ videoUrl?: string
148
+ /** A video layer only. */
149
+ sound?: VideoOverlaySound
112
150
  /** 1-based canvas slot (overlay = 1 … overlay12 = 12; 13 and up handle-less), stamped by both engine assemblies. Messages prefer it. */
113
151
  slot?: number
114
152
  /** 1-based entry of a wired layer plan, stamped by the assembly. Messages prefer it. */
@@ -128,12 +166,12 @@ export interface VideoOverlayLayer {
128
166
  y: number
129
167
  /** % of the output canvas width (1..100). */
130
168
  width: number
131
- /** % of the output canvas height (1..100); absent = follows the image's aspect. */
169
+ /** % of the output canvas height (1..100); absent = follows the image's (or video's) aspect. */
132
170
  height?: number
133
171
  fit: VideoOverlayFit
134
172
  /** 0..1 */
135
173
  opacity: number
136
- /** Fade + slight scale in and out, 0.15 s each way. */
174
+ /** Fade + slight scale in and out, 0.15 s each way. Default on for an image, off for a video. */
137
175
  animate: boolean
138
176
  /** Integer 0..100; absent = its position (slot − 1: layer 1 lowest). */
139
177
  zIndex?: number
@@ -142,24 +180,50 @@ export interface VideoOverlayLayer {
142
180
  /** A layer as a WRITER may send it (workflow JSON, a template, the canvas): every field optional; `null` means absent. */
143
181
  export type VideoOverlayLayerInput = { [K in keyof VideoOverlayLayer]?: VideoOverlayLayer[K] | null }
144
182
 
145
- /** A layer on the REST / SDK wire: image and start required; the box may be a preset, explicit fields, or nothing (→ the corner-badge default). */
146
- export type VideoOverlayLayerSpec = { imageUrl: string; start: number } & Partial<Omit<VideoOverlayLayer, "imageUrl" | "start">>
183
+ /**
184
+ * A layer on the REST / SDK wire: exactly one of `imageUrl` / `videoUrl`, and
185
+ * `start`, required; the box may be a preset, explicit fields, or nothing
186
+ * (→ the corner-badge default).
187
+ */
188
+ export type VideoOverlayLayerSpec = { start: number } & Partial<Omit<VideoOverlayLayer, "imageUrl" | "videoUrl" | "start">> &
189
+ ({ imageUrl: string; videoUrl?: never } | { videoUrl: string; imageUrl?: never })
190
+
191
+ /**
192
+ * A base box on the REST / SDK wire: `anchor` and `width` required; `x` and
193
+ * `y` default to 0 and `fit` to contain (`expandVideoOverlayLayout`), and no
194
+ * `height` follows the base's own aspect.
195
+ */
196
+ export type VideoOverlayBaseBoxSpec = Pick<VideoOverlayBox, "anchor" | "width"> & Partial<Omit<VideoOverlayBox, "anchor" | "width">>
147
197
 
148
198
  /** The `POST /v1/video-overlay` body. */
149
199
  export interface VideoOverlayRequest {
150
200
  videoUrl: string
151
- /** 1..20 */
201
+ /** 1..20, at most `VIDEO_OVERLAY_MAX_VIDEO_LAYERS` (2) of them videos. */
152
202
  layers: VideoOverlayLayerSpec[]
153
203
  outputAspect?: VideoOverlayOutputAspect
154
204
  /** Only with `outputAspect`; default cover. */
155
205
  baseFit?: VideoOverlayFit
156
206
  /** `#rrggbb`, only with `outputAspect` (drawn under `contain`); default `#000000`. */
157
207
  backgroundColor?: string
208
+ /** Where the base sits, in a layer's box vocabulary; only with `outputAspect`. Overrides `baseFit`; uncovered canvas shows `backgroundColor`. Refused with a stack layout. */
209
+ baseBox?: VideoOverlayBaseBoxSpec
210
+ /**
211
+ * A named layout that writes the boxes (`expandVideoOverlayLayout`): an
212
+ * explicit `baseBox` wins over `video-bottom` / `video-top`; a stack places
213
+ * the base itself and takes none; `pip` replaces the first video layer's box.
214
+ */
215
+ layout?: VideoOverlayLayoutId
158
216
  }
159
217
 
160
218
  /** A request whose layers went through `expandVideoOverlayPresets`. */
161
- export interface ExpandedVideoOverlayRequest extends Omit<VideoOverlayRequest, "layers"> {
219
+ export interface ExpandedVideoOverlayRequest extends Omit<VideoOverlayRequest, "layers" | "baseBox"> {
162
220
  layers: VideoOverlayLayer[]
221
+ /**
222
+ * The base box as stored or sent, its `null` fields dropped — any field may
223
+ * be absent. The validator refuses one without an anchor and a width; the
224
+ * worker fills the rest (`expandVideoOverlayLayout`) after it.
225
+ */
226
+ baseBox?: Partial<VideoOverlayBox>
163
227
  /** Set by the assembly when a wired layer plan could not be read; `validateVideoOverlayRequest` reports it first. */
164
228
  planError?: "invalid_layer_plan"
165
229
  }
@@ -223,20 +287,6 @@ export function isVideoOverlayCorner(v: unknown): v is VideoOverlayCorner {
223
287
  export function isVideoOverlayOutputAspect(v: unknown): v is VideoOverlayOutputAspect {
224
288
  return typeof v === "string" && (VIDEO_OVERLAY_OUTPUT_ASPECTS as readonly string[]).includes(v)
225
289
  }
226
- function isFit(v: unknown): v is VideoOverlayFit {
227
- return v === "contain" || v === "cover"
228
- }
229
-
230
- /**
231
- * A `layers[]` entry as a layer, or null when it is not a plain object. Layer
232
- * arrays reach this module from untrusted workflow JSON (the MCP write sites
233
- * type nodes as `record<string, unknown>`), so a bare string / number / array
234
- * entry is read as an ABSENT layer — never spread, never `in`-probed.
235
- */
236
- function asLayer(v: unknown): VideoOverlayLayerInput | null {
237
- return v !== null && typeof v === "object" && !Array.isArray(v) ? (v as VideoOverlayLayerInput) : null
238
- }
239
-
240
290
  /** 1-based slot of a layer handle id (`overlay` → 1 … `overlay12` → 12); 0 for anything else. */
241
291
  export function videoOverlaySlotOfHandle(handle: string | null | undefined): number {
242
292
  return (VIDEO_OVERLAY_HANDLE_IDS as readonly string[]).indexOf(handle ?? "") + 1
@@ -248,7 +298,8 @@ export function videoOverlayPresetBox(preset: VideoOverlayPresetId, corner?: Vid
248
298
  : VIDEO_OVERLAY_PRESETS[preset]
249
299
  }
250
300
 
251
- const TRAILING_DEFAULTS = { x: 0, y: 0, fit: "contain", opacity: 1, animate: true } as const
301
+ /** Filled when absent; `animate` too, by the layer's kind (on for an image, off for a video). */
302
+ const TRAILING_DEFAULTS = { x: 0, y: 0, fit: "contain", opacity: 1 } as const
252
303
 
253
304
  function usable(key: string, value: unknown): boolean {
254
305
  if (value === null || value === undefined) return false
@@ -283,27 +334,33 @@ function sameShallow(a: Readonly<Record<string, unknown>>, b: unknown): boolean
283
334
  * fields, the layer's own fields winning (D8): `{}` → the full default.
284
335
  * - no `preset` + a PARTIAL box (not anchor AND width) → returned untouched;
285
336
  * the validator answers `incomplete_box`.
286
- * Trailing defaults x 0, y 0, fit contain, opacity 1, animate true are filled
287
- * here and nowhere else. `null` reads as absent. Returned BY REFERENCE when
288
- * nothing changes; idempotent, tag included.
337
+ * Trailing defaults x 0, y 0, fit contain, opacity 1, and animate (true for an
338
+ * image, false for a video layer — in every branch, the default layer's included)
339
+ * are filled here and nowhere else. A VIDEO layer with a preset and no `start`
340
+ * starts at 0, like the default layer; an image one is left to the validator
341
+ * (`time_out_of_range`), as it always was. `null` reads as absent. Returned BY
342
+ * REFERENCE when nothing changes; idempotent, tag included.
289
343
  */
290
344
  export function expandVideoOverlayLayer(raw: VideoOverlayLayerInput | null | undefined): VideoOverlayLayer {
291
345
  const obj = asLayer(raw)
292
346
  const layer = obj ? clean(obj) : {}
347
+ const animateDefault = !isVideoOverlayVideoLayer(layer)
293
348
  const present = VIDEO_OVERLAY_BOX_FIELDS.filter((f) => layer[f] !== undefined)
294
349
  let out: Record<string, unknown>
295
350
  if (isVideoOverlayPresetId(layer.preset)) {
296
351
  const box = videoOverlayPresetBox(layer.preset, layer.corner)
297
- out = { ...box, ...layer }
352
+ // A video layer tagged with a preset starts at 0 when it names no start (as the default layer does); an image layer is left for the validator, as before.
353
+ out = { ...box, ...(animateDefault || layer.start !== undefined ? {} : { start: 0 }), ...layer }
298
354
  if (present.some((f) => layer[f] !== box[f])) delete out.preset
299
355
  } else if (present.length === 0) {
300
- out = { ...DEFAULT_VIDEO_OVERLAY_LAYER, ...videoOverlayPresetBox("corner-badge", layer.corner), ...layer }
356
+ out = { ...DEFAULT_VIDEO_OVERLAY_LAYER, animate: animateDefault, ...videoOverlayPresetBox("corner-badge", layer.corner), ...layer }
301
357
  } else if (layer.anchor === undefined || layer.width === undefined) {
302
358
  return raw as VideoOverlayLayer
303
359
  } else {
304
360
  out = { ...layer }
305
361
  }
306
362
  for (const [k, v] of Object.entries(TRAILING_DEFAULTS)) if (out[k] === undefined) out[k] = v
363
+ if (out.animate === undefined) out.animate = animateDefault
307
364
  return sameShallow(out, raw) ? (raw as VideoOverlayLayer) : (out as unknown as VideoOverlayLayer)
308
365
  }
309
366
 
@@ -343,10 +400,11 @@ export function toCustomVideoOverlayLayer(layer: VideoOverlayLayerInput | null |
343
400
  }
344
401
 
345
402
  /**
346
- * D10 — delete `imageUrl` from every layer whose canvas handle is wired
347
- * (`wiredSlots`: 1-based). Pure over `layers` (the route has no edges, so this
348
- * is a sibling of the expansion, not part of it). Slots 13 and up have no handle
349
- * and are never touched. The input array by reference when nothing changes.
403
+ * D10 — delete `imageUrl` AND `videoUrl` from every layer whose canvas handle
404
+ * is wired (`wiredSlots`: 1-based): the wire is the layer's source, whichever
405
+ * kind it is. Pure over `layers` (the route has no edges, so this is a sibling
406
+ * of the expansion, not part of it). Slots 13 and up have no handle and are
407
+ * never touched. The input array by reference when nothing changes.
350
408
  */
351
409
  export function clearWiredVideoOverlayImageUrls<T extends VideoOverlayLayerInput | null | undefined>(
352
410
  layers: readonly T[],
@@ -356,9 +414,9 @@ export function clearWiredVideoOverlayImageUrls<T extends VideoOverlayLayerInput
356
414
  for (const slot of wiredSlots) {
357
415
  if (!Number.isInteger(slot) || slot < 1 || slot > VIDEO_OVERLAY_HANDLE_IDS.length) continue
358
416
  const layer = layers[slot - 1]
359
- if (!asLayer(layer) || !("imageUrl" in (layer as object))) continue
417
+ if (!asLayer(layer) || !("imageUrl" in (layer as object) || "videoUrl" in (layer as object))) continue
360
418
  out ??= [...layers]
361
- const { imageUrl: _cleared, ...rest } = layer as VideoOverlayLayerInput
419
+ const { imageUrl: _image, videoUrl: _video, ...rest } = layer as VideoOverlayLayerInput
362
420
  out[slot - 1] = rest as T
363
421
  }
364
422
  return out ?? layers
@@ -404,11 +462,14 @@ export function normalizeVideoOverlayNodes<T extends NodeLike>(nodes: readonly T
404
462
  }
405
463
  const cleared = clearWiredVideoOverlayImageUrls(layers, wired)
406
464
  let layersChanged = cleared !== layers
407
- const next = cleared.map((l) => {
465
+ const next = cleared.map((l, i) => {
408
466
  // null / missing stays as stored; a non-object entry is left untouched so
409
467
  // the validator sees it (it reads as an absent layer everywhere).
410
468
  if (!asLayer(l)) return l
411
- const e = expandVideoOverlayLayer(l)
469
+ // A wired slot's fade default follows its wire's kind, read at the run:
470
+ // only a fade it was written with is stored.
471
+ const expanded = expandVideoOverlayLayer(l)
472
+ const e = wired.has(i + 1) ? withoutImpliedVideoOverlayAnimate(expanded, l) : expanded
412
473
  if (e !== l) layersChanged = true
413
474
  return e
414
475
  })
@@ -455,239 +516,6 @@ export function videoOverlayRenderOrder(layers: ReadonlyArray<VideoOverlayOrdera
455
516
  .map((e) => e.i)
456
517
  }
457
518
 
458
- export interface VideoOverlayRect {
459
- readonly left: number
460
- readonly top: number
461
- readonly width: number
462
- readonly height: number
463
- }
464
- export interface VideoOverlayCanvas {
465
- readonly w: number
466
- readonly h: number
467
- }
468
- export interface VideoOverlayGeometry {
469
- readonly box: VideoOverlayRect
470
- readonly drawn: VideoOverlayRect
471
- }
472
-
473
- const evenFloor = (n: number): number => Math.max(2, Math.floor(n / 2) * 2)
474
-
475
- /**
476
- * The output canvas: `ASPECT_RATIO_DIMENSIONS[outputAspect]` when a target
477
- * aspect is set; otherwise the base's DISPLAY size (rotation already applied by
478
- * the caller's probe) with the sample aspect ratio resolved and both sides
479
- * rounded down to even — `trunc(iw*sar/2)*2 × trunc(ih/2)*2`, what the ffmpeg
480
- * base chain produces. null when neither is known.
481
- */
482
- export function videoOverlayCanvas(
483
- display: { readonly width: number; readonly height: number; readonly sar?: number } | null | undefined,
484
- outputAspect?: string | null,
485
- ): VideoOverlayCanvas | null {
486
- if (isVideoOverlayOutputAspect(outputAspect)) {
487
- const d = ASPECT_RATIO_DIMENSIONS[outputAspect]!
488
- return { w: d.width, h: d.height }
489
- }
490
- if (!display || !(display.width > 0) || !(display.height > 0)) return null
491
- const sar = typeof display.sar === "number" && Number.isFinite(display.sar) && display.sar > 0 ? display.sar : 1
492
- return { w: evenFloor(display.width * sar), h: evenFloor(display.height) }
493
- }
494
-
495
- function anchorFactors(anchor: OverlayAnchor): readonly [number, number] {
496
- const h = anchor.endsWith("left") ? 0 : anchor.endsWith("right") ? 1 : 0.5
497
- const v = anchor.startsWith("top") ? 0 : anchor.startsWith("bottom") ? 1 : 0.5
498
- return [h, v]
499
- }
500
-
501
- /**
502
- * Spec §3.4. `width%` → px of the canvas width; height follows the image's
503
- * aspect unless `height%` is set; nine anchors; x/y are additive offsets in %
504
- * of the canvas. An aspect-following box taller than the canvas is fitted
505
- * inside it (both sides scaled, aspect kept) — so `drawn` never exceeds the
506
- * canvas, which is what bounds the sharp pre-fit at one canvas of RGBA. `fit`:
507
- * contain → the image scaled inside the box, centred; cover → the box itself.
508
- * The only post-processing is rounding `drawn` DOWN to even, floored at 2 × 2.
509
- * Differences from Image Overlay's copies (on purpose): no 8192 edge shrink,
510
- * the canvas clamp, the even rounding.
511
- */
512
- export function resolveVideoOverlayGeometry(
513
- canvas: VideoOverlayCanvas,
514
- layer: Pick<VideoOverlayLayer, "anchor" | "x" | "y" | "width" | "height" | "fit">,
515
- imageAspect: number,
516
- ): VideoOverlayGeometry {
517
- const aspect = Number.isFinite(imageAspect) && imageAspect > 0 ? imageAspect : 1
518
- let bw = Math.max(1, Math.round((layer.width / 100) * canvas.w))
519
- let bh = layer.height !== undefined ? Math.max(1, Math.round((layer.height / 100) * canvas.h)) : Math.max(1, Math.round(bw / aspect))
520
- if (layer.height === undefined && bh > canvas.h) {
521
- bw = Math.max(1, Math.round(bw * (canvas.h / bh)))
522
- bh = canvas.h
523
- }
524
- const [ax, ay] = anchorFactors(layer.anchor)
525
- const left = Math.round(ax * (canvas.w - bw) + (layer.x / 100) * canvas.w)
526
- const top = Math.round(ay * (canvas.h - bh) + (layer.y / 100) * canvas.h)
527
- let dw: number
528
- let dh: number
529
- if (layer.fit === "cover") {
530
- dw = bw
531
- dh = bh
532
- } else if (bw / bh > aspect) {
533
- dh = bh
534
- dw = bh * aspect
535
- } else {
536
- dw = bw
537
- dh = bw / aspect
538
- }
539
- const width = evenFloor(dw)
540
- const height = evenFloor(dh)
541
- return {
542
- box: { left, top, width: bw, height: bh },
543
- drawn: { left: left + Math.floor((bw - width) / 2), top: top + Math.floor((bh - height) / 2), width, height },
544
- }
545
- }
546
-
547
- export interface VideoOverlayIssue {
548
- readonly ok: false
549
- readonly code: VideoOverlayErrorCode
550
- /** 0-based index into the validated `layers[]`. */
551
- readonly layer?: number
552
- readonly slot?: number
553
- readonly planLayer?: number
554
- readonly params: Readonly<Record<string, string | number>>
555
- }
556
- export type VideoOverlayValidation = { readonly ok: true } | VideoOverlayIssue
557
-
558
- export interface VideoOverlayValidationInput {
559
- readonly layers?: ReadonlyArray<VideoOverlayLayerInput | null | undefined> | null
560
- readonly outputAspect?: string | null
561
- readonly baseFit?: string | null
562
- readonly backgroundColor?: string | null
563
- /** From `assembleVideoOverlayRequest`: the wired layer plan was unreadable. */
564
- readonly planError?: "invalid_layer_plan"
565
- }
566
-
567
- const inTimeRange = (v: unknown): v is number =>
568
- typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= VIDEO_OVERLAY_MAX_TIME_SEC
569
-
570
- type BoundedField = keyof typeof VIDEO_OVERLAY_BOUNDS
571
- const BOUNDED_FIELDS = Object.keys(VIDEO_OVERLAY_BOUNDS) as BoundedField[]
572
-
573
- /**
574
- * The first present (non-null) box / look field outside its domain, with the
575
- * domain as a symbolic `allowed` string; null when every present field is in
576
- * range. Only PRESENT fields are checked, so the verdict is the same before and
577
- * after the expansion (it fills in-range defaults only). This is what keeps a
578
- * JSON-written layer (MCP `update_workflow_json`, copilot, templates) from
579
- * reaching the geometry with an unbounded box — `drawn ≤ canvas` (§3.4) holds
580
- * only for boxes inside these bounds.
581
- */
582
- function outOfBounds(l: VideoOverlayLayerInput): { field: string; allowed: string } | null {
583
- for (const f of BOUNDED_FIELDS) {
584
- const v = l[f]
585
- if (v === undefined || v === null) continue
586
- const [min, max] = VIDEO_OVERLAY_BOUNDS[f]
587
- const integer = f === "zIndex"
588
- if (typeof v !== "number" || !Number.isFinite(v) || v < min || v > max || (integer && !Number.isInteger(v))) {
589
- return { field: f, allowed: `${integer ? "integers " : ""}${min}..${max}` }
590
- }
591
- }
592
- if (l.anchor != null && !(OVERLAY_ANCHORS as readonly unknown[]).includes(l.anchor)) {
593
- return { field: "anchor", allowed: OVERLAY_ANCHORS.join(", ") }
594
- }
595
- if (l.fit != null && !isFit(l.fit)) return { field: "fit", allowed: VIDEO_OVERLAY_FITS.join(", ") }
596
- if (l.animate != null && typeof l.animate !== "boolean") return { field: "animate", allowed: "true, false" }
597
- return null
598
- }
599
-
600
- /**
601
- * Can `resolveVideoOverlayGeometry` place this layer? True when its box is what
602
- * the validator's box checks require: `anchor` one of the nine anchors, `width`
603
- * a finite number, and every present box / look field in range
604
- * (`VIDEO_OVERLAY_BOUNDS`, enums). A partial box saved from workflow JSON
605
- * (`{ imageUrl, start, width }`, `anchor: null`) is stored as written — the
606
- * expansion leaves it for the validator's `incomplete_box` — so any reader
607
- * that DRAWS a stored layer (the canvas stage) must skip one that fails this;
608
- * the geometry would throw on it.
609
- */
610
- export function hasDrawableVideoOverlayBox(layer: unknown): boolean {
611
- const l = asLayer(layer)
612
- if (!l) return false
613
- if (!(OVERLAY_ANCHORS as readonly unknown[]).includes(l.anchor)) return false
614
- if (typeof l.width !== "number" || !Number.isFinite(l.width)) return false
615
- return outOfBounds(l) === null
616
- }
617
-
618
- /**
619
- * Spec §3.5 — what a schema cannot express, and what the DAG path skips. Run
620
- * at every engine entry: the route (`.superRefine`, before the expansion), the
621
- * canvas single-node run, payload-builder and the worker (after it) — the
622
- * verdict is the same on either side of the expansion (no code reads an
623
- * expanded field). Also refuses a PRESENT box / look field outside
624
- * `VIDEO_OVERLAY_BOUNDS` or its enum / type (`field_out_of_bounds`, spec §4.4's
625
- * "out-of-bounds box/opacity/zIndex" row — on the DAG path this validator is
626
- * the only check). A non-object `layers[]` entry reads as an empty layer. The
627
- * FIRST failure, as a code.
628
- */
629
- export function validateVideoOverlayRequest(body: VideoOverlayValidationInput): VideoOverlayValidation {
630
- if (body.planError) return { ok: false, code: "invalid_layer_plan", params: {} }
631
- const layers = Array.isArray(body.layers) ? body.layers : []
632
- if (layers.length === 0) return { ok: false, code: "no_layers", params: {} }
633
- if (layers.length > VIDEO_OVERLAY_MAX_LAYERS) {
634
- return { ok: false, code: "too_many_layers", params: { max: VIDEO_OVERLAY_MAX_LAYERS, count: layers.length } }
635
- }
636
- for (let i = 0; i < layers.length; i++) {
637
- const l: VideoOverlayLayerInput = asLayer(layers[i]) ?? {}
638
- const at = (code: VideoOverlayErrorCode, params: Record<string, string | number> = {}): VideoOverlayIssue => ({
639
- ok: false,
640
- code,
641
- layer: i,
642
- ...(typeof l.slot === "number" ? { slot: l.slot } : {}),
643
- ...(typeof l.planLayer === "number" ? { planLayer: l.planLayer } : {}),
644
- params,
645
- })
646
- const boxFields = VIDEO_OVERLAY_BOX_FIELDS.filter((f) => l[f] !== undefined && l[f] !== null)
647
- if (!isVideoOverlayPresetId(l.preset) && boxFields.length > 0 && (l.anchor == null || l.width == null)) return at("incomplete_box")
648
- const bad = outOfBounds(l)
649
- if (bad) return at("field_out_of_bounds", bad)
650
- if (typeof l.imageUrl !== "string" || l.imageUrl.length === 0) return at("layer_without_image")
651
- if (!inTimeRange(l.start)) return at("time_out_of_range", { field: "start", max: VIDEO_OVERLAY_MAX_TIME_SEC })
652
- if (l.end !== undefined && l.end !== null) {
653
- if (!inTimeRange(l.end)) return at("time_out_of_range", { field: "end", max: VIDEO_OVERLAY_MAX_TIME_SEC })
654
- if (!(l.end > l.start)) return at("end_before_start", { start: l.start, end: l.end })
655
- }
656
- }
657
- if (!isVideoOverlayOutputAspect(body.outputAspect) && (body.baseFit != null || body.backgroundColor != null)) {
658
- return { ok: false, code: "fit_without_aspect", params: {} }
659
- }
660
- return { ok: true }
661
- }
662
-
663
- const MESSAGES: { readonly [C in VideoOverlayErrorCode]: (p: Readonly<Record<string, string | number>>) => string } = {
664
- no_layers: () => "At least 1 layer is required",
665
- too_many_layers: (p) => `At most ${p.max} layers (got ${p.count})`,
666
- incomplete_box: () => "anchor and width are required without a preset",
667
- layer_without_image: () => "no image — connect one to the layer's handle or set imageUrl",
668
- time_out_of_range: (p) => `${p.field} must be between 0 and ${p.max} s`,
669
- end_before_start: (p) => `end (${p.end} s) must be after start (${p.start} s)`,
670
- fit_without_aspect: () => "baseFit and backgroundColor need an outputAspect",
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",
673
- }
674
-
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}`
680
- return typeof ref.slot === "number" ? `Layer ${ref.slot}` : typeof ref.layer === "number" ? `layers[${ref.layer}]` : ""
681
- }
682
-
683
- /** The ONE English rendering of a verdict — the route's 400 text and the worker's error message. */
684
- export function formatVideoOverlayError(issue: VideoOverlayIssue): string {
685
- const label = videoOverlayLayerLabel(issue)
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)
688
- return label ? `${label}: ${text}` : text
689
- }
690
-
691
519
  /** The wired `layerPlan` value (a JSON string or an array) → its layers, or `invalid_layer_plan`. */
692
520
  export function parseVideoOverlayLayerPlan(raw: unknown): { layers: VideoOverlayLayerInput[] } | { error: "invalid_layer_plan" } {
693
521
  let value: unknown = raw
@@ -704,12 +532,18 @@ export function parseVideoOverlayLayerPlan(raw: unknown): { layers: VideoOverlay
704
532
  return { layers: value as VideoOverlayLayerInput[] }
705
533
  }
706
534
 
535
+ /** A stored base box without its `null` fields (by reference when it has none); a non-object as stored, for the validator. */
536
+ const storedBaseBox = (box: VideoOverlayBoxInput): Partial<VideoOverlayBox> => (asLayer(box) ? clean(box as VideoOverlayLayerInput) : box) as Partial<VideoOverlayBox>
537
+
707
538
  /** The node-data fields the assembly reads. */
708
539
  export interface VideoOverlayNodeFields {
709
540
  readonly layers?: ReadonlyArray<VideoOverlayLayerInput | null | undefined> | null
710
541
  readonly outputAspect?: string | null
711
542
  readonly baseFit?: string | null
712
543
  readonly backgroundColor?: string | null
544
+ /** As written, like the fields above: the validator, not the type, refuses a malformed box or an unknown layout. */
545
+ readonly baseBox?: VideoOverlayBoxInput | null
546
+ readonly layout?: string | null
713
547
  }
714
548
 
715
549
  /**
@@ -717,8 +551,12 @@ export interface VideoOverlayNodeFields {
717
551
  * payload-builder (so both engines refuse identically). Per slot i over
718
552
  * max(wired handles (≤ 12), stored layers) — every stored slot, so more than
719
553
  * 20 layers that render reach the validator's `too_many_layers` instead of
720
- * being dropped: the image is the wired handle's,
721
- * else the layer's own `imageUrl`; a slot with neither is dropped; a slot with
554
+ * being dropped: the source is the wired handle's — a `videoUrl` when its slot
555
+ * is in `wiredVideoSlots`, else an `imageUrl` (a stored `sound` skipped, so a
556
+ * wire read as an image at the run never refuses it), replacing both stored
557
+ * sources — else the layer's own `imageUrl` / `videoUrl` as stored (both stored reach
558
+ * the validator's `layer_two_sources`; an empty-string one is dropped —
559
+ * `withoutEmptyVideoOverlaySources`, plan layers too); a slot with neither is dropped; a slot with
722
560
  * no settings is the default layer (D2 — a `null` / missing / `{}` entry);
723
561
  * `slot = i + 1` is stamped; the layer is expanded. `baseFit` /
724
562
  * `backgroundColor` ride as stored, WITH or WITHOUT an `outputAspect`: the
@@ -728,6 +566,12 @@ export interface VideoOverlayNodeFields {
728
566
  * (The canvas never builds that request: its two aspect writers clear both
729
567
  * fields with the aspect.) A value the route's schema would reject — an
730
568
  * unknown aspect or fit, a colour that is not `#rrggbb` — is dropped here.
569
+ * `baseBox` and `layout` ride AS STORED (a `""` layout reads as absent, like
570
+ * `null`; a box's `null` fields are dropped, as a layer's are by its
571
+ * expansion — every reader treats them as absent, and the REST route's schema
572
+ * takes no `null`, so the canvas run's request stays one the route accepts): a
573
+ * malformed box or an unknown layout reaches the validator, which refuses it
574
+ * on both engines.
731
575
  *
732
576
  * A wired layer plan (`planLayers`, a JSON string or an array) contributes its
733
577
  * layers FIRST, then the slot layers: plan layers carry `planLayer` (1-based)
@@ -738,7 +582,10 @@ export interface VideoOverlayNodeFields {
738
582
  export function assembleVideoOverlayRequest(input: {
739
583
  readonly videoUrl: string
740
584
  readonly data: VideoOverlayNodeFields
585
+ /** Each wired handle's source, by slot (images and videos alike). */
741
586
  readonly wiredImageUrls: ReadonlyArray<string | null | undefined>
587
+ /** 1-based slots whose wired source is a video (`videoOverlayWiredLayerKind`); absent = every wire is an image. */
588
+ readonly wiredVideoSlots?: ReadonlySet<number>
742
589
  /** The wired `layerPlan` value (string or array); absent when nothing is wired. */
743
590
  readonly planLayers?: unknown
744
591
  }): ExpandedVideoOverlayRequest {
@@ -751,12 +598,19 @@ export function assembleVideoOverlayRequest(input: {
751
598
  const slots = Math.max(wired.length, stored.length)
752
599
  const layers: VideoOverlayLayer[] = []
753
600
  for (let i = 0; i < slots; i++) {
754
- const raw = asLayer(stored[i])
601
+ const own = asLayer(stored[i])
602
+ const raw = own && withoutEmptyVideoOverlaySources(own)
755
603
  const wiredUrl = wired[i]
756
- const own = raw?.imageUrl
757
- const image = typeof wiredUrl === "string" && wiredUrl.length > 0 ? wiredUrl : typeof own === "string" && own.length > 0 ? own : undefined
758
- if (!image) continue
759
- layers.push(expandVideoOverlayLayer({ ...(raw ?? {}), imageUrl: image, slot: i + 1 }))
604
+ if (nonEmpty(wiredUrl)) {
605
+ // The wire is the source: the other kind's stored field goes, its own kind's is replaced.
606
+ const video = input.wiredVideoSlots?.has(i + 1) === true
607
+ const [kind, other] = video ? (["videoUrl", "imageUrl"] as const) : (["imageUrl", "videoUrl"] as const)
608
+ const { [other]: _replaced, ...keep } = raw ?? {}
609
+ // An image wire skips a stored sound (`withoutVideoOverlaySound`); the expansion fills the fade default by the wire's kind.
610
+ layers.push(expandVideoOverlayLayer({ ...(video ? keep : withoutVideoOverlaySound(keep)), [kind]: wiredUrl, slot: i + 1 }))
611
+ } else if (nonEmpty(raw?.imageUrl) || nonEmpty(raw?.videoUrl)) {
612
+ layers.push(expandVideoOverlayLayer({ ...raw, slot: i + 1 }))
613
+ }
760
614
  }
761
615
  const outputAspect = isVideoOverlayOutputAspect(input.data.outputAspect) ? input.data.outputAspect : undefined
762
616
  const baseFit = isFit(input.data.baseFit) ? input.data.baseFit : undefined
@@ -766,11 +620,13 @@ export function assembleVideoOverlayRequest(input: {
766
620
  ...(outputAspect ? { outputAspect } : {}),
767
621
  ...(baseFit ? { baseFit } : {}),
768
622
  ...(backgroundColor ? { backgroundColor } : {}),
623
+ ...(input.data.baseBox != null ? { baseBox: storedBaseBox(input.data.baseBox) } : {}),
624
+ ...(storedLayout(input.data.layout) !== undefined ? { layout: input.data.layout as VideoOverlayLayoutId } : {}),
769
625
  }
770
626
  if (input.planLayers === undefined) return { videoUrl: input.videoUrl, layers, ...rest }
771
627
  const plan = parseVideoOverlayLayerPlan(input.planLayers)
772
628
  if ("error" in plan) return { videoUrl: input.videoUrl, layers, ...rest, planError: plan.error }
773
- const planned = expandVideoOverlayPresets(plan.layers).map((l, i) => {
629
+ const planned = expandVideoOverlayPresets(plan.layers.map(withoutEmptyVideoOverlaySources)).map((l, i) => {
774
630
  const { slot: _slot, ...own } = l
775
631
  return { ...own, planLayer: i + 1 }
776
632
  })
@@ -778,12 +634,13 @@ export function assembleVideoOverlayRequest(input: {
778
634
  }
779
635
 
780
636
  /**
781
- * Slot i's image: the wired handle's, else the layer's own `imageUrl` — the
782
- * one source rule the stage, the panel, the canvas executor and the DAG
783
- * payload share (the render's merge is the same `wired ?? imageUrl`, spec
784
- * §3.5). Every stored slot, past 20 too: the limit is the layer COUNT, not
785
- * the slot (layers 1–4 removed from a 24-layer node leave 20 at slots 5–24).
786
- * Only the wired list is capped, at the 12 handles.
637
+ * Slot i's source: the wired handle's, else the layer's own `imageUrl`, else
638
+ * its own `videoUrl` — the one source rule the stage, the panel, the canvas
639
+ * executor and the DAG payload share (the render's merge is the same
640
+ * `wired ?? imageUrl ?? videoUrl`, spec §3.5). Every stored slot, past 20 too:
641
+ * the limit is the layer COUNT, not the slot (layers 1–4 removed from a
642
+ * 24-layer node leave 20 at slots 5–24). Only the wired list is capped, at the
643
+ * 12 handles.
787
644
  */
788
645
  export function videoOverlaySlotSources(
789
646
  layers: ReadonlyArray<VideoOverlayLayerInput | null | undefined> | null | undefined,
@@ -793,9 +650,9 @@ export function videoOverlaySlotSources(
793
650
  const wired = wiredImageUrls.slice(0, VIDEO_OVERLAY_HANDLE_IDS.length)
794
651
  return Array.from({ length: Math.max(stored.length, wired.length) }, (_, i) => {
795
652
  const w = wired[i]
796
- if (typeof w === "string" && w.length > 0) return w
797
- const own = asLayer(stored[i])?.imageUrl
798
- return typeof own === "string" && own.length > 0 ? own : undefined
653
+ if (nonEmpty(w)) return w
654
+ const own = asLayer(stored[i])
655
+ return nonEmpty(own?.imageUrl) ? own.imageUrl : nonEmpty(own?.videoUrl) ? own.videoUrl : undefined
799
656
  })
800
657
  }
801
658
 
@@ -803,12 +660,14 @@ export function videoOverlaySlotSources(
803
660
  export interface VideoOverlayComposition {
804
661
  /** The resolved base video URL. */
805
662
  readonly baseUrl?: string | null
806
- /** The image each slot draws, by slot index (`videoOverlaySlotSources`). */
663
+ /** The image or video each slot draws, by slot index (`videoOverlaySlotSources`). */
807
664
  readonly sources: ReadonlyArray<string | null | undefined>
808
665
  /** The node's stored settings — never the expanded request. */
809
666
  readonly data: VideoOverlayNodeFields
810
667
  /** The wired `layerPlan` value (string or array); absent when nothing is wired. */
811
668
  readonly planLayers?: unknown
669
+ /** The 1-based slots whose wired source is a video (the assembly's `wiredVideoSlots`); absent or empty = every wire is an image. */
670
+ readonly videoSlots?: Iterable<number> | null
812
671
  }
813
672
 
814
673
  /**
@@ -842,8 +701,9 @@ export const VIDEO_OVERLAY_MAX_COMPOSITION_KEY_LENGTH = 65_536
842
701
 
843
702
  /**
844
703
  * The composition key a run stamps on its result (`resultCompositionKey`): the
845
- * base, every slot's image, the layers, the output aspect, the fit and the pad
846
- * colour. A later change to any of them marks the result "Result (old)".
704
+ * base, every slot's image, the layers, the output aspect, the fit, the pad
705
+ * colour, the base box, the layout and which wired slots are videos. A later
706
+ * change to any of them marks the result "Result (old)".
847
707
  * Canonical — independent of object key order, of absent vs undefined vs null
848
708
  * fields, and of trailing empty slots — so the canvas (the node and its
849
709
  * single-node Run) and the DAG payload give one key for one composition.
@@ -865,5 +725,13 @@ export function videoOverlayCompositionKey(c: VideoOverlayComposition): string {
865
725
  const plan = parseVideoOverlayLayerPlan(c.planLayers)
866
726
  parts.push("error" in plan ? "invalid" : plan.layers)
867
727
  }
728
+ // Likewise only when set, as ONE object — never confused with the plan (an array or "invalid").
729
+ const layout = storedLayout(c.data.layout)
730
+ if (c.data.baseBox != null || layout !== undefined) parts.push({ baseBox: c.data.baseBox, layout })
731
+ // A wired slot's kind can change while its URL does not (an extension-less
732
+ // link, a List column's type); only when a wire is a video, so an
733
+ // image-only node keeps its key.
734
+ const videoSlots = [...new Set(c.videoSlots ?? [])].sort((a, b) => a - b)
735
+ if (videoSlots.length > 0) parts.push({ videoSlots })
868
736
  return JSON.stringify(canonicalValue(parts))
869
737
  }