@nodaro/shared 3.61.0 → 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 (254) hide show
  1. package/dist/{chunk-IVXSNW2B.cjs → chunk-2D5LQFV4.cjs} +18 -332
  2. package/dist/chunk-2D5LQFV4.cjs.map +1 -0
  3. package/dist/{chunk-XUJC6GHE.cjs → chunk-2HZGDZZN.cjs} +6 -6
  4. package/dist/{chunk-XUJC6GHE.cjs.map → chunk-2HZGDZZN.cjs.map} +1 -1
  5. package/dist/{chunk-43TGSZRJ.js → chunk-2QKF7M2Z.js} +3 -3
  6. package/dist/{chunk-43TGSZRJ.js.map → chunk-2QKF7M2Z.js.map} +1 -1
  7. package/dist/{chunk-7ARKVJTN.cjs → chunk-2W745U4A.cjs} +228 -355
  8. package/dist/chunk-2W745U4A.cjs.map +1 -0
  9. package/dist/{chunk-673E4KYC.js → chunk-3OYO3XCC.js} +70 -6
  10. package/dist/chunk-3OYO3XCC.js.map +1 -0
  11. package/dist/{chunk-FMXFHJWX.cjs → chunk-4ZEFP2FQ.cjs} +4 -4
  12. package/dist/{chunk-FMXFHJWX.cjs.map → chunk-4ZEFP2FQ.cjs.map} +1 -1
  13. package/dist/{chunk-A3FHTSLB.js → chunk-5YYN5X57.js} +302 -27
  14. package/dist/chunk-5YYN5X57.js.map +1 -0
  15. package/dist/{chunk-4KYLNTR7.cjs → chunk-6CSXMWL4.cjs} +4 -4
  16. package/dist/{chunk-4KYLNTR7.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-ZFJN23V4.cjs → chunk-A2PX5IRC.cjs} +4 -4
  22. package/dist/{chunk-ZFJN23V4.cjs.map → chunk-A2PX5IRC.cjs.map} +1 -1
  23. package/dist/{chunk-JHTT2V4A.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-ZDBPQBAA.js → chunk-C7POAYFE.js} +3 -3
  30. package/dist/{chunk-ZDBPQBAA.js.map → chunk-C7POAYFE.js.map} +1 -1
  31. package/dist/{chunk-B6BG3LV2.js → chunk-CC4V2B7S.js} +3 -3
  32. package/dist/{chunk-B6BG3LV2.js.map → chunk-CC4V2B7S.js.map} +1 -1
  33. package/dist/{chunk-XZKFZMRT.cjs → chunk-CIPPPT7E.cjs} +6 -6
  34. package/dist/{chunk-XZKFZMRT.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-RQ4F3AJH.cjs → chunk-G3KVK7OU.cjs} +21 -21
  44. package/dist/{chunk-RQ4F3AJH.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-IRQ3SPX7.js → chunk-GSFB537T.js} +3 -3
  48. package/dist/{chunk-IRQ3SPX7.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-VOWJCUMR.js → chunk-I2RQB7VG.js} +3 -3
  52. package/dist/{chunk-VOWJCUMR.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-5XRRENHD.cjs → chunk-IWWVPR3W.cjs} +88 -11
  56. package/dist/chunk-IWWVPR3W.cjs.map +1 -0
  57. package/dist/{chunk-SCMTN57Y.js → chunk-JJNNM23P.js} +3 -3
  58. package/dist/{chunk-SCMTN57Y.js.map → chunk-JJNNM23P.js.map} +1 -1
  59. package/dist/{chunk-ZZGQRRN7.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-NJVOJXBS.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-F5YEMSNK.cjs → chunk-MYJQELFN.cjs} +320 -26
  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-MQZRQ5LM.cjs → chunk-N7OUQK7E.cjs} +8 -8
  74. package/dist/{chunk-MQZRQ5LM.cjs.map → chunk-N7OUQK7E.cjs.map} +1 -1
  75. package/dist/{chunk-UARGJ5IZ.js → chunk-NGKKNSK6.js} +30 -7
  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-C77F4ZTL.js → chunk-PTD6EDUU.js} +3 -3
  80. package/dist/{chunk-C77F4ZTL.js.map → chunk-PTD6EDUU.js.map} +1 -1
  81. package/dist/{chunk-ZNM2LW3D.cjs → chunk-QWYFHQYK.cjs} +78 -53
  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-MOMFX32D.js → chunk-S24ZBUB4.js} +194 -299
  86. package/dist/chunk-S24ZBUB4.js.map +1 -0
  87. package/dist/{chunk-EWS2VFO4.js → chunk-S5TMRJMX.js} +4 -4
  88. package/dist/{chunk-EWS2VFO4.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-RUHKBEFF.js → chunk-SYWR5G3T.js} +16 -7
  92. package/dist/chunk-SYWR5G3T.js.map +1 -0
  93. package/dist/{chunk-FQXRYPCX.cjs → chunk-TRVWMKNE.cjs} +337 -52
  94. package/dist/chunk-TRVWMKNE.cjs.map +1 -0
  95. package/dist/{chunk-LLOIAGFB.js → chunk-UDDVDQMF.js} +292 -35
  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-5I4T4QR5.cjs → chunk-VACPZPUA.cjs} +5 -5
  100. package/dist/{chunk-5I4T4QR5.cjs.map → chunk-VACPZPUA.cjs.map} +1 -1
  101. package/dist/{chunk-HGI2VKIV.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 +105 -3
  109. package/dist/entries/credits.d.ts +105 -3
  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 +195 -103
  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 +102 -102
  144. package/dist/entries/workflow.d.cts +5 -4
  145. package/dist/entries/workflow.d.ts +5 -4
  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 +2309 -1886
  150. package/dist/index.d.cts +9 -9
  151. package/dist/index.d.ts +9 -9
  152. package/dist/index.js +26 -23
  153. package/dist/{model-catalog-BgSvskgY.d.cts → model-catalog-CCEcv08q.d.cts} +128 -14
  154. package/dist/{model-catalog-BgSvskgY.d.ts → model-catalog-CCEcv08q.d.ts} +128 -14
  155. package/dist/{model-constants-DHd9jwQ7.d.ts → model-constants-B88p6XR0.d.ts} +299 -19
  156. package/dist/{model-constants-DHd9jwQ7.d.cts → model-constants-Cf3zaITt.d.cts} +299 -19
  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__/grok-video-15-catalog.test.ts +189 -0
  163. package/src/__tests__/gvp-supported-providers.test.ts +5 -2
  164. package/src/__tests__/minimax-h3-image.test.ts +140 -0
  165. package/src/__tests__/model-makers.test.ts +49 -11
  166. package/src/__tests__/model-tree.test.ts +13 -0
  167. package/src/__tests__/retired-video-provider.test.ts +15 -5
  168. package/src/__tests__/seedance-25-catalog-modes.test.ts +1 -1
  169. package/src/__tests__/seedance-task-type.test.ts +178 -0
  170. package/src/__tests__/seedream-5-5.test.ts +117 -0
  171. package/src/__tests__/unit-contract-compose.test.ts +27 -1
  172. package/src/__tests__/unit-contracts.test.ts +20 -6
  173. package/src/__tests__/upscale-factors.test.ts +107 -0
  174. package/src/__tests__/video-character-refs.test.ts +20 -2
  175. package/src/__tests__/video-collapse-parity.test.ts +19 -0
  176. package/src/__tests__/video-overlay-geometry.test.ts +68 -0
  177. package/src/__tests__/video-overlay-layer-plan.test.ts +3 -4
  178. package/src/__tests__/video-overlay-layouts.test.ts +529 -0
  179. package/src/__tests__/video-overlay-pricing.test.ts +61 -0
  180. package/src/__tests__/video-overlay-validate.test.ts +128 -0
  181. package/src/__tests__/video-overlay-wired-kind.test.ts +207 -0
  182. package/src/__tests__/video-overlay.test.ts +280 -194
  183. package/src/__tests__/video-ref-limits.test.ts +2 -1
  184. package/src/__tests__/video-reference-only.test.ts +6 -2
  185. package/src/__tests__/video-start-frame-only.test.ts +98 -0
  186. package/src/__tests__/wired-character-names.test.ts +220 -0
  187. package/src/credit-estimators/index.ts +8 -0
  188. package/src/credit-estimators/video-overlay.ts +70 -0
  189. package/src/credit-identifiers.ts +94 -1
  190. package/src/entity-image-url.ts +21 -0
  191. package/src/entries/credits.ts +14 -0
  192. package/src/entries/entities.ts +14 -0
  193. package/src/entries/model-catalog.ts +35 -1
  194. package/src/entries/models.ts +34 -0
  195. package/src/entries/nodes.ts +2 -0
  196. package/src/entries/video.ts +6 -0
  197. package/src/generated/unit-contracts.ts +8 -1
  198. package/src/gpt-image-2-6.ts +6 -0
  199. package/src/input-image-pricing.ts +76 -0
  200. package/src/mask-composite.ts +11 -0
  201. package/src/minimax-h3-image.ts +61 -0
  202. package/src/model-catalog.ts +355 -37
  203. package/src/model-constants.ts +590 -32
  204. package/src/node-default-mappings.ts +12 -2
  205. package/src/node-execution-state.ts +4 -3
  206. package/src/producer-types.ts +23 -1
  207. package/src/seedance-task-type.ts +37 -0
  208. package/src/seedream-5-5.ts +45 -0
  209. package/src/unit-contract-compose.ts +4 -1
  210. package/src/upscale-factors.ts +111 -0
  211. package/src/video-character-refs.ts +7 -4
  212. package/src/video-overlay-geometry.ts +99 -0
  213. package/src/video-overlay-input.ts +25 -0
  214. package/src/video-overlay-layout-ids.ts +48 -0
  215. package/src/video-overlay-layouts.ts +315 -0
  216. package/src/video-overlay-validate.ts +223 -0
  217. package/src/video-overlay-video-layers.ts +304 -0
  218. package/src/video-overlay.ts +165 -297
  219. package/src/video-ui-defaults.ts +8 -6
  220. package/src/wired-character-names.ts +202 -0
  221. package/dist/chunk-5XRRENHD.cjs.map +0 -1
  222. package/dist/chunk-673E4KYC.js.map +0 -1
  223. package/dist/chunk-6XVHYD5R.js.map +0 -1
  224. package/dist/chunk-7ARKVJTN.cjs.map +0 -1
  225. package/dist/chunk-7WGKP3EU.js +0 -23
  226. package/dist/chunk-7WGKP3EU.js.map +0 -1
  227. package/dist/chunk-A3FHTSLB.js.map +0 -1
  228. package/dist/chunk-AFQFGZN7.cjs.map +0 -1
  229. package/dist/chunk-F5YEMSNK.cjs.map +0 -1
  230. package/dist/chunk-FQXRYPCX.cjs.map +0 -1
  231. package/dist/chunk-FVVD6XY2.js.map +0 -1
  232. package/dist/chunk-G4XWVWRI.js.map +0 -1
  233. package/dist/chunk-HGI2VKIV.js.map +0 -1
  234. package/dist/chunk-IVXSNW2B.cjs.map +0 -1
  235. package/dist/chunk-JHTT2V4A.cjs.map +0 -1
  236. package/dist/chunk-KHZAQGRP.js +0 -17
  237. package/dist/chunk-KHZAQGRP.js.map +0 -1
  238. package/dist/chunk-LLOIAGFB.js.map +0 -1
  239. package/dist/chunk-M3SXUUWC.cjs.map +0 -1
  240. package/dist/chunk-MOMFX32D.js.map +0 -1
  241. package/dist/chunk-NCOGGRRP.cjs +0 -27
  242. package/dist/chunk-NCOGGRRP.cjs.map +0 -1
  243. package/dist/chunk-NJVOJXBS.cjs.map +0 -1
  244. package/dist/chunk-PONP5J5E.cjs.map +0 -1
  245. package/dist/chunk-RUHKBEFF.js.map +0 -1
  246. package/dist/chunk-SWVGHAYO.js.map +0 -1
  247. package/dist/chunk-UARGJ5IZ.js.map +0 -1
  248. package/dist/chunk-VB2ARGQ6.js.map +0 -1
  249. package/dist/chunk-WGKAOUEQ.cjs.map +0 -1
  250. package/dist/chunk-XROE3CAS.cjs.map +0 -1
  251. package/dist/chunk-ZLDFPVVI.cjs +0 -19
  252. package/dist/chunk-ZLDFPVVI.cjs.map +0 -1
  253. package/dist/chunk-ZNM2LW3D.cjs.map +0 -1
  254. package/dist/chunk-ZZGQRRN7.js.map +0 -1
@@ -0,0 +1,315 @@
1
+ /**
2
+ * Video Overlay layouts and the placed base — the request-level normaliser
3
+ * (`expandVideoOverlayLayout`) and the geometry the canvas preview and the
4
+ * ffmpeg worker both call, so the preview and the render cannot disagree.
5
+ * A sibling of `video-overlay.ts`: it imports from there, nothing there imports
6
+ * from here, and the layout ids live in the dependency-free
7
+ * `video-overlay-layout-ids.ts`.
8
+ *
9
+ * - `video-bottom` / `video-top` write a base box; an explicit one wins.
10
+ * - `pip` writes the first video layer's box in its corner.
11
+ * - The two stacks write no box: their rects depend on the sources' shapes,
12
+ * known only after probing, so the worker and the preview call
13
+ * `resolveVideoOverlayStackRects` with them. A stack places the base
14
+ * itself, so the validator refuses one with a `baseBox` (`layout_conflicts_base_box`).
15
+ * `pip` and the two stacks turn the first video layer's fade off;
16
+ * `video-bottom` / `video-top` touch no layer. "First video layer" is the
17
+ * lowest one (`firstVideoLayerIndex`); image layers are left where they are.
18
+ * A probed video's aspect goes through `clampVideoOverlayAspect` before any of
19
+ * this geometry, and a video's rect through `evenVideoOverlayRect` after it —
20
+ * in the worker and the preview alike.
21
+ * Wire contract only — no I/O.
22
+ */
23
+ import {
24
+ VIDEO_OVERLAY_BOX_FIELDS,
25
+ expandVideoOverlayLayer,
26
+ isVideoOverlayCorner,
27
+ videoOverlayRenderOrder,
28
+ type VideoOverlayBox,
29
+ type VideoOverlayBoxInput,
30
+ type VideoOverlayCorner,
31
+ type VideoOverlayFit,
32
+ type VideoOverlayLayer,
33
+ type VideoOverlayLayerInput,
34
+ type VideoOverlayOrderable,
35
+ } from "./video-overlay.js"
36
+ import { resolveVideoOverlayGeometry, type VideoOverlayCanvas, type VideoOverlayRect } from "./video-overlay-geometry.js"
37
+ import { validateVideoOverlayRequest } from "./video-overlay-validate.js"
38
+ import { isVideoOverlayVideoLayer } from "./video-overlay-video-layers.js"
39
+
40
+ /** Picture in picture: the inset's width and its margin from the corner, % of the output canvas (Speaker View's inset). */
41
+ export const VIDEO_OVERLAY_PIP_WIDTH = 30
42
+ export const VIDEO_OVERLAY_PIP_INSET = 4
43
+
44
+ /** What a layout reads and writes — a request, an assembled request, or node data. */
45
+ export interface VideoOverlayLayoutFields {
46
+ readonly layout?: string | null
47
+ readonly baseBox?: VideoOverlayBoxInput | null
48
+ readonly layers?: ReadonlyArray<VideoOverlayLayerInput | null | undefined> | null
49
+ }
50
+
51
+ /** The base box each edge layout writes: the base whole, full width, flush on that edge. */
52
+ const EDGE_BASE_BOXES: { readonly [L in "video-bottom" | "video-top"]: VideoOverlayBox } = {
53
+ "video-bottom": { anchor: "bottom", x: 0, y: 0, width: 100, fit: "contain" },
54
+ "video-top": { anchor: "top", x: 0, y: 0, width: 100, fit: "contain" },
55
+ }
56
+
57
+ /** A base box's trailing defaults, as a layer's (`expandVideoOverlayLayer`). */
58
+ const BOX_DEFAULTS = { x: 0, y: 0, fit: "contain" } as const
59
+
60
+ /**
61
+ * The narrowest and widest aspect a probed video is placed at. A video's
62
+ * shape is only known from its probe, and nothing bounds a probe, so a stack
63
+ * of a 1:1000 sliver could otherwise place a rect off the canvas. Inside these
64
+ * bounds every stack, base and layer rect stays on it.
65
+ */
66
+ export const VIDEO_OVERLAY_ASPECT_BOUNDS = [1 / 8, 8] as const
67
+
68
+ /** Rounded down to even, floored at 2; the epsilon absorbs float error at an exact even size (960.0000 read as 959.9999). */
69
+ const evenFloor = (n: number): number => Math.max(2, Math.floor(n / 2 + 1e-9) * 2)
70
+ const usableAspect = (a: number): number => (Number.isFinite(a) && a > 0 ? a : 1)
71
+
72
+ /**
73
+ * A probed video's display aspect (width ÷ height), held inside
74
+ * `VIDEO_OVERLAY_ASPECT_BOUNDS`; one that is not a positive finite number
75
+ * reads as square, as in the layer geometry. The worker and the preview pass
76
+ * every video's aspect (the base's and each video layer's) through this before
77
+ * any placement, so they place the same rects.
78
+ */
79
+ export function clampVideoOverlayAspect(aspect: number): number {
80
+ const [min, max] = VIDEO_OVERLAY_ASPECT_BOUNDS
81
+ return Number.isFinite(aspect) && aspect > 0 ? Math.min(max, Math.max(min, aspect)) : 1
82
+ }
83
+
84
+ /** Rounded down to an even integer, negatives included (−61 → −62). */
85
+ const floorEven = (n: number): number => Math.floor(n / 2) * 2
86
+
87
+ /**
88
+ * A video's rect as the render draws it: left and top rounded DOWN to even,
89
+ * and the size down to even. ffmpeg's overlay on yuv420 clears the low bit of
90
+ * an odd x or y (a base placed at top 371 is drawn at 370), so this is where
91
+ * the picture lands anyway; the worker hands the graph these numbers and the
92
+ * preview draws them, so the two agree to the pixel. A stack's two rects move
93
+ * by the same pixel (its heights are even), so its join stays exact. Applied
94
+ * to the base's rect and to video layers only — an image layer's geometry is
95
+ * unchanged. By reference when the rect is already even.
96
+ */
97
+ export function evenVideoOverlayRect(rect: VideoOverlayRect): VideoOverlayRect {
98
+ const even = { left: floorEven(rect.left), top: floorEven(rect.top), width: evenFloor(rect.width), height: evenFloor(rect.height) }
99
+ return sameShallow(even, rect) ? rect : even
100
+ }
101
+
102
+ function sameShallow(a: object, b: object): boolean {
103
+ const ka = Object.keys(a)
104
+ return ka.length === Object.keys(b).length && ka.every((k) => (a as Record<string, unknown>)[k] === (b as Record<string, unknown>)[k])
105
+ }
106
+
107
+ /** The lowest video layer by `videoOverlayRenderOrder`, as its index in `layers`; -1 when there is none. */
108
+ export function firstVideoLayerIndex(
109
+ layers: ReadonlyArray<(VideoOverlayOrderable & { readonly videoUrl?: string | null }) | null | undefined> | null | undefined,
110
+ ): number {
111
+ if (!Array.isArray(layers)) return -1
112
+ return videoOverlayRenderOrder(layers).find((i) => isVideoOverlayVideoLayer(layers[i])) ?? -1
113
+ }
114
+
115
+ /**
116
+ * An explicit base box with `anchor` and `width` gets the layer's trailing
117
+ * defaults (x 0, y 0, fit contain) and loses its `null` fields; anything else
118
+ * (a partial box, a non-object) is returned untouched for the validator. By
119
+ * reference when nothing changes.
120
+ */
121
+ function expandBaseBox(raw: VideoOverlayBoxInput): VideoOverlayBoxInput {
122
+ if (typeof raw !== "object" || Array.isArray(raw) || raw.anchor == null || raw.width == null) return raw
123
+ const out: Record<string, unknown> = { ...BOX_DEFAULTS }
124
+ for (const [k, v] of Object.entries(raw)) if (v != null) out[k] = v
125
+ return sameShallow(out, raw) ? raw : (out as VideoOverlayBoxInput)
126
+ }
127
+
128
+ function pipBox(corner: VideoOverlayCorner): VideoOverlayBox {
129
+ const sx = corner.endsWith("left") ? 1 : -1
130
+ const sy = corner.startsWith("top") ? 1 : -1
131
+ return { anchor: corner, x: sx * VIDEO_OVERLAY_PIP_INSET, y: sy * VIDEO_OVERLAY_PIP_INSET, width: VIDEO_OVERLAY_PIP_WIDTH, fit: "contain" }
132
+ }
133
+
134
+ /**
135
+ * The validator's per-layer verdict on this layer alone (a one-layer request
136
+ * meets no request-level check). A layout never repairs a layer it refuses — a
137
+ * bad or partial box, a non-boolean `animate`, two sources, a bad time or
138
+ * volume — so the verdict is the same before and after the expansion, as
139
+ * `expandBaseBox` leaves a partial base box for the validator.
140
+ */
141
+ const acceptedAlone = (layer: VideoOverlayLayerInput): boolean => validateVideoOverlayRequest({ layers: [layer] }).ok
142
+
143
+ /**
144
+ * The first video layer under `pip` or a stack, the layouts that place it:
145
+ * `pip` replaces its box (as a preset click does: height and tag go), and each
146
+ * of them turns its fade off. A layer the validator would refuse is returned
147
+ * untouched.
148
+ */
149
+ function placeFirstVideoLayer(layout: string, layer: VideoOverlayLayerInput): VideoOverlayLayerInput {
150
+ if (!acceptedAlone(layer)) return layer
151
+ if (layout !== "pip") return layer.animate === false ? layer : { ...layer, animate: false }
152
+ const rest: Record<string, unknown> = { ...layer }
153
+ for (const f of VIDEO_OVERLAY_BOX_FIELDS) delete rest[f]
154
+ delete rest.preset
155
+ const corner = isVideoOverlayCorner(layer.corner) ? layer.corner : "bottom-right"
156
+ const next = expandVideoOverlayLayer({ ...rest, ...pipBox(corner), animate: false } as VideoOverlayLayerInput)
157
+ return sameShallow(next, layer) ? layer : next
158
+ }
159
+
160
+ /**
161
+ * The request-level normaliser: what a `layout` writes, and an explicit base
162
+ * box's defaults. Called at the write boundaries and by the worker after the
163
+ * validator. An explicit `baseBox` wins over `video-bottom` / `video-top`;
164
+ * `pip` places the first video layer; the stacks write no box. An unknown
165
+ * layout writes nothing (the validator refuses it), and neither does any
166
+ * layout to a first video layer the validator refuses, so the verdict is the
167
+ * same before and after. Never mutates; the request BY REFERENCE when nothing
168
+ * changes; idempotent.
169
+ */
170
+ export function expandVideoOverlayLayout<T extends VideoOverlayLayoutFields>(req: T): T & { readonly baseBox?: VideoOverlayBox } {
171
+ const { layout } = req
172
+ const baseBox =
173
+ req.baseBox != null ? expandBaseBox(req.baseBox) : layout === "video-bottom" || layout === "video-top" ? EDGE_BASE_BOXES[layout] : req.baseBox
174
+ let layers = req.layers
175
+ const first = layout === "pip" || layout === "stack-whole" || layout === "stack-filled" ? firstVideoLayerIndex(req.layers) : -1
176
+ if (first >= 0 && Array.isArray(req.layers)) {
177
+ const layer = req.layers[first] as VideoOverlayLayerInput
178
+ const placed = placeFirstVideoLayer(layout as string, layer)
179
+ if (placed !== layer) layers = req.layers.map((l, i) => (i === first ? placed : l))
180
+ }
181
+ if (baseBox === req.baseBox && layers === req.layers) return req as T & { readonly baseBox?: VideoOverlayBox }
182
+ // Only the changed fields: an unset one never becomes an `undefined` key.
183
+ return {
184
+ ...req,
185
+ ...(baseBox !== req.baseBox ? { baseBox } : {}),
186
+ ...(layers !== req.layers ? { layers } : {}),
187
+ } as T & { readonly baseBox?: VideoOverlayBox }
188
+ }
189
+
190
+ /**
191
+ * The two stacked rects, `top` for the base and `bottom` for the first video
192
+ * layer, in output pixels.
193
+ * - `stack-whole`: both whole, the same even width, touching, the pair centred
194
+ * with equal spare room above and below (±1 px). They shrink together only
195
+ * when both together are taller than the canvas. The join is pixel-exact.
196
+ * - `stack-filled`: the top half (rounded down to even) and the rest, full
197
+ * width; the aspects are not read — both are cropped (`cover`).
198
+ * An aspect that is not a positive finite number reads as square.
199
+ */
200
+ export function resolveVideoOverlayStackRects(
201
+ layout: "stack-whole" | "stack-filled",
202
+ canvas: VideoOverlayCanvas,
203
+ topAspect: number,
204
+ bottomAspect: number,
205
+ ): { top: VideoOverlayRect; bottom: VideoOverlayRect } {
206
+ if (layout === "stack-filled") {
207
+ const half = evenFloor(canvas.h / 2)
208
+ return {
209
+ top: { left: 0, top: 0, width: canvas.w, height: half },
210
+ bottom: { left: 0, top: half, width: canvas.w, height: canvas.h - half },
211
+ }
212
+ }
213
+ const a = usableAspect(topAspect)
214
+ const b = usableAspect(bottomAspect)
215
+ const total = canvas.w / a + canvas.w / b
216
+ const width = evenFloor(total > canvas.h ? (canvas.w * canvas.h) / total : canvas.w)
217
+ const th = evenFloor(width / a)
218
+ const bh = evenFloor(width / b)
219
+ const top = Math.floor((canvas.h - th - bh) / 2)
220
+ const left = Math.floor((canvas.w - width) / 2)
221
+ return {
222
+ top: { left, top, width, height: th },
223
+ bottom: { left, top: top + th, width, height: bh },
224
+ }
225
+ }
226
+
227
+ /** A picture placed on the output canvas: its even rect and how it fills it (contain = scaled to the rect, cover = cropped to it). */
228
+ export interface VideoOverlayPlacedRect {
229
+ readonly drawn: VideoOverlayRect
230
+ readonly fit: VideoOverlayFit
231
+ }
232
+
233
+ /** A video layer to place. */
234
+ export interface PlacedVideoOverlayVideoInput {
235
+ /** 0-based index in the request's layers[] (what `firstVideo` names). */
236
+ readonly index: number
237
+ readonly layer: Pick<VideoOverlayLayer, "anchor" | "x" | "y" | "width" | "height" | "fit">
238
+ /** Its display aspect (width ÷ height, rotation and sample aspect resolved); held inside the bounds here. */
239
+ readonly aspect: number
240
+ }
241
+
242
+ export interface VideoOverlayVideoPlacement {
243
+ /** Present when the base is placed (a stack or a base box); absent = the base as before (its own size, or `outputAspect` with `baseFit`). */
244
+ readonly basePlacement?: VideoOverlayPlacedRect
245
+ /** Each video layer's even drawn rect and fit, by request index. */
246
+ readonly layers: ReadonlyMap<number, VideoOverlayPlacedRect>
247
+ }
248
+
249
+ /**
250
+ * Where the base and every video layer draw, on the output canvas — the ONE
251
+ * placement the worker renders with and the canvas preview draws with. Every
252
+ * aspect goes through `clampVideoOverlayAspect` and every rect through
253
+ * `evenVideoOverlayRect` here, so neither caller can skip them.
254
+ * - A stack (`stack-whole` / `stack-filled`): both rects from
255
+ * `resolveVideoOverlayStackRects` with the base's and the first video
256
+ * layer's aspects; that layer's stored box is not read. `stack-filled` draws
257
+ * both `cover`, `stack-whole` both `contain`, whatever fit is stored.
258
+ * - Otherwise a base box (written by `video-bottom` / `video-top`, or explicit)
259
+ * places the base with `resolveVideoOverlayBaseRect` at its own fit.
260
+ * - Every other video layer: its box, `resolveVideoOverlayGeometry`, at its
261
+ * aspect (`pip` has already written its box).
262
+ * An image layer is not placed here: its geometry is unchanged. The caller
263
+ * passes a stack's first video layer among `videos` (the worker refuses a
264
+ * stack whose first video layer it does not keep). Pure.
265
+ */
266
+ export function placeVideoOverlayVideos(input: {
267
+ readonly canvas: VideoOverlayCanvas
268
+ readonly layout?: string | null
269
+ readonly baseBox?: VideoOverlayBox
270
+ readonly baseAspect: number
271
+ /** `firstVideoLayerIndex` of the request's layers: what a stack places under the base. */
272
+ readonly firstVideo: number
273
+ readonly videos: ReadonlyArray<PlacedVideoOverlayVideoInput>
274
+ }): VideoOverlayVideoPlacement {
275
+ const { canvas, layout } = input
276
+ const baseAspect = clampVideoOverlayAspect(input.baseAspect)
277
+ const layers = new Map<number, VideoOverlayPlacedRect>()
278
+ let basePlacement: VideoOverlayPlacedRect | undefined
279
+ if (layout === "stack-whole" || layout === "stack-filled") {
280
+ const first = input.videos.find((v) => v.index === input.firstVideo)
281
+ if (!first) throw new Error(`placeVideoOverlayVideos: the stacked layer ${input.firstVideo} was not kept`)
282
+ const rects = resolveVideoOverlayStackRects(layout, canvas, baseAspect, clampVideoOverlayAspect(first.aspect))
283
+ const fit: VideoOverlayFit = layout === "stack-filled" ? "cover" : "contain"
284
+ basePlacement = { drawn: evenVideoOverlayRect(rects.top), fit }
285
+ layers.set(first.index, { drawn: evenVideoOverlayRect(rects.bottom), fit })
286
+ } else if (input.baseBox) {
287
+ basePlacement = { drawn: evenVideoOverlayRect(resolveVideoOverlayBaseRect(canvas, input.baseBox, baseAspect)), fit: input.baseBox.fit }
288
+ }
289
+ for (const v of input.videos) {
290
+ if (layers.has(v.index)) continue
291
+ const { drawn } = resolveVideoOverlayGeometry(canvas, v.layer, clampVideoOverlayAspect(v.aspect))
292
+ layers.set(v.index, { drawn: evenVideoOverlayRect(drawn), fit: v.layer.fit })
293
+ }
294
+ return { ...(basePlacement ? { basePlacement } : {}), layers }
295
+ }
296
+
297
+ /**
298
+ * Where a placed base draws, in output pixels. Its SIZE is the layer
299
+ * geometry's drawn size (`resolveVideoOverlayGeometry`: the same clamp and even
300
+ * rounding as an image layer); it is then placed by that drawn size against the
301
+ * anchor, plus the x / y offsets — so a contained base sits flush on its
302
+ * anchored edge rather than centred in a box rounded to other numbers (a 16:9
303
+ * base at the bottom of 1080x1920 draws at y 1314–1920, with no strip under it).
304
+ */
305
+ export function resolveVideoOverlayBaseRect(canvas: VideoOverlayCanvas, box: VideoOverlayBox, baseAspect: number): VideoOverlayRect {
306
+ const { drawn } = resolveVideoOverlayGeometry(canvas, box, baseAspect)
307
+ const ax = box.anchor.endsWith("left") ? 0 : box.anchor.endsWith("right") ? 1 : 0.5
308
+ const ay = box.anchor.startsWith("top") ? 0 : box.anchor.startsWith("bottom") ? 1 : 0.5
309
+ return {
310
+ left: Math.round(ax * (canvas.w - drawn.width) + (box.x / 100) * canvas.w),
311
+ top: Math.round(ay * (canvas.h - drawn.height) + (box.y / 100) * canvas.h),
312
+ width: drawn.width,
313
+ height: drawn.height,
314
+ }
315
+ }
@@ -0,0 +1,223 @@
1
+ /**
2
+ * Video Overlay — the request validator: what a schema cannot express, run at
3
+ * every engine entry. It returns a CODE, never English: `formatVideoOverlayError`
4
+ * renders the route / worker text, the canvas renders the code through its
5
+ * dictionaries. A sibling of `video-overlay.ts`, which it imports from; nothing
6
+ * there imports this file.
7
+ * Wire contract only — no prompt content, no I/O.
8
+ */
9
+ import { OVERLAY_ANCHORS } from "./image-overlay-layers.js"
10
+ import {
11
+ VIDEO_OVERLAY_BOUNDS, VIDEO_OVERLAY_BOX_FIELDS, VIDEO_OVERLAY_FITS, VIDEO_OVERLAY_MAX_LAYERS, VIDEO_OVERLAY_MAX_TIME_SEC,
12
+ VIDEO_OVERLAY_MAX_VIDEO_LAYERS, VIDEO_OVERLAY_VOLUME_BOUNDS, isVideoOverlayOutputAspect, isVideoOverlayPresetId,
13
+ type VideoOverlayBoxInput, type VideoOverlayErrorCode, type VideoOverlayLayerInput,
14
+ } from "./video-overlay.js"
15
+ import { asLayer, isFit, nonEmpty, storedLayout } from "./video-overlay-input.js"
16
+ import { isVideoOverlayVideoLayer } from "./video-overlay-video-layers.js"
17
+ import {
18
+ VIDEO_OVERLAY_LAYOUT_IDS, isVideoOverlayLayoutId, videoOverlayLayoutNeedsAspect, videoOverlayLayoutNeedsVideoLayer, videoOverlayLayoutPlacesBase,
19
+ type VideoOverlayLayoutId,
20
+ } from "./video-overlay-layout-ids.js"
21
+
22
+ export interface VideoOverlayIssue {
23
+ readonly ok: false
24
+ readonly code: VideoOverlayErrorCode
25
+ /** 0-based index into the validated `layers[]`. */
26
+ readonly layer?: number
27
+ readonly slot?: number
28
+ readonly planLayer?: number
29
+ readonly params: Readonly<Record<string, string | number>>
30
+ }
31
+ export type VideoOverlayValidation = { readonly ok: true } | VideoOverlayIssue
32
+
33
+ export interface VideoOverlayValidationInput {
34
+ readonly layers?: ReadonlyArray<VideoOverlayLayerInput | null | undefined> | null
35
+ readonly outputAspect?: string | null
36
+ readonly baseFit?: string | null
37
+ readonly backgroundColor?: string | null
38
+ readonly baseBox?: VideoOverlayBoxInput | null
39
+ readonly layout?: string | null
40
+ /** From `assembleVideoOverlayRequest`: the wired layer plan was unreadable. */
41
+ readonly planError?: "invalid_layer_plan"
42
+ }
43
+
44
+ const inTimeRange = (v: unknown): v is number =>
45
+ typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= VIDEO_OVERLAY_MAX_TIME_SEC
46
+
47
+ type BoundedField = keyof typeof VIDEO_OVERLAY_BOUNDS
48
+ const BOUNDED_FIELDS = Object.keys(VIDEO_OVERLAY_BOUNDS) as BoundedField[]
49
+
50
+ /**
51
+ * The first present (non-null) box / look field outside its domain, with the
52
+ * domain as a symbolic `allowed` string; null when every present field is in
53
+ * range. Only PRESENT fields are checked, so the verdict is the same before and
54
+ * after the expansion (it fills in-range defaults only). This is what keeps a
55
+ * JSON-written layer (MCP `update_workflow_json`, copilot, templates) from
56
+ * reaching the geometry with an unbounded box — `drawn ≤ canvas` (§3.4) holds
57
+ * only for boxes inside these bounds.
58
+ */
59
+ function outOfBounds(l: VideoOverlayLayerInput): { field: string; allowed: string } | null {
60
+ for (const f of BOUNDED_FIELDS) {
61
+ const v = l[f]
62
+ if (v === undefined || v === null) continue
63
+ const [min, max] = VIDEO_OVERLAY_BOUNDS[f]
64
+ const integer = f === "zIndex"
65
+ if (typeof v !== "number" || !Number.isFinite(v) || v < min || v > max || (integer && !Number.isInteger(v))) {
66
+ return { field: f, allowed: `${integer ? "integers " : ""}${min}..${max}` }
67
+ }
68
+ }
69
+ if (l.anchor != null && !(OVERLAY_ANCHORS as readonly unknown[]).includes(l.anchor)) {
70
+ return { field: "anchor", allowed: OVERLAY_ANCHORS.join(", ") }
71
+ }
72
+ if (l.fit != null && !isFit(l.fit)) return { field: "fit", allowed: VIDEO_OVERLAY_FITS.join(", ") }
73
+ if (l.animate != null && typeof l.animate !== "boolean") return { field: "animate", allowed: "true, false" }
74
+ return null
75
+ }
76
+
77
+ /**
78
+ * A present `sound` that is not `{ volume }` with the volume inside
79
+ * `VIDEO_OVERLAY_VOLUME_BOUNDS`. Kept out of `outOfBounds`: a bad volume is
80
+ * refused, but it does not stop the stage from drawing the layer.
81
+ */
82
+ function soundOutOfBounds(sound: unknown): { field: string; allowed: string } | null {
83
+ if (sound === undefined || sound === null) return null
84
+ const [min, max] = VIDEO_OVERLAY_VOLUME_BOUNDS
85
+ const v = typeof sound === "object" && !Array.isArray(sound) ? (sound as { volume?: unknown }).volume : undefined
86
+ return typeof v === "number" && Number.isFinite(v) && v >= min && v <= max ? null : { field: "sound.volume", allowed: `${min}..${max}` }
87
+ }
88
+
89
+ /** A present base box under the layer rule: anchor and width (a non-object reads as an empty box), every present box field in range. */
90
+ function baseBoxIssue(raw: unknown): VideoOverlayIssue | null {
91
+ const own = asLayer(raw) ?? {}
92
+ const box = Object.fromEntries(VIDEO_OVERLAY_BOX_FIELDS.map((f) => [f, own[f]])) as VideoOverlayLayerInput
93
+ if (box.anchor == null || box.width == null) return { ok: false, code: "incomplete_box", params: { field: "baseBox" } }
94
+ const bad = outOfBounds(box)
95
+ return bad ? { ok: false, code: "field_out_of_bounds", params: { ...bad, field: `baseBox.${bad.field}` } } : null
96
+ }
97
+
98
+ /**
99
+ * Can `resolveVideoOverlayGeometry` place this layer? True when its box is what
100
+ * the validator's box checks require: `anchor` one of the nine anchors, `width`
101
+ * a finite number, and every present box / look field in range
102
+ * (`VIDEO_OVERLAY_BOUNDS`, enums). A partial box saved from workflow JSON
103
+ * (`{ imageUrl, start, width }`, `anchor: null`) is stored as written — the
104
+ * expansion leaves it for the validator's `incomplete_box` — so any reader
105
+ * that DRAWS a stored layer (the canvas stage) must skip one that fails this;
106
+ * the geometry would throw on it.
107
+ */
108
+ export function hasDrawableVideoOverlayBox(layer: unknown): boolean {
109
+ const l = asLayer(layer)
110
+ if (!l) return false
111
+ if (!(OVERLAY_ANCHORS as readonly unknown[]).includes(l.anchor)) return false
112
+ if (typeof l.width !== "number" || !Number.isFinite(l.width)) return false
113
+ return outOfBounds(l) === null
114
+ }
115
+
116
+ /**
117
+ * Spec §3.5 — what a schema cannot express, and what the DAG path skips. Run
118
+ * at every engine entry: the route (`.superRefine`, before the expansion), the
119
+ * canvas single-node run, payload-builder and the worker (after it) — the
120
+ * verdict is the same on either side of the expansion (no code reads an
121
+ * expanded field). Also refuses a PRESENT box / look field outside
122
+ * `VIDEO_OVERLAY_BOUNDS` or its enum / type (`field_out_of_bounds`, spec §4.4's
123
+ * "out-of-bounds box/opacity/zIndex" row — on the DAG path this validator is
124
+ * the only check). A layer carries an image or a video, never both
125
+ * (`layer_two_sources`), at most `VIDEO_OVERLAY_MAX_VIDEO_LAYERS` are videos,
126
+ * and only a video layer has `sound`. A non-object `layers[]` entry reads as
127
+ * an empty layer. A `layout` (`""` reads as absent) must be known, a stack
128
+ * takes no `baseBox` (`layout_conflicts_base_box`: it places the base
129
+ * itself); a `baseBox` follows the layer rule (`incomplete_box`,
130
+ * `field_out_of_bounds` as `baseBox.<field>`) and needs an `outputAspect`; a
131
+ * layout gets what it needs (an aspect, a video layer) — checked before
132
+ * `base_box_needs_aspect`, so writing a layout's base box does not change the
133
+ * verdict. The FIRST failure, as a code.
134
+ */
135
+ export function validateVideoOverlayRequest(body: VideoOverlayValidationInput): VideoOverlayValidation {
136
+ if (body.planError) return { ok: false, code: "invalid_layer_plan", params: {} }
137
+ const layers = Array.isArray(body.layers) ? body.layers : []
138
+ if (layers.length === 0) return { ok: false, code: "no_layers", params: {} }
139
+ if (layers.length > VIDEO_OVERLAY_MAX_LAYERS) {
140
+ return { ok: false, code: "too_many_layers", params: { max: VIDEO_OVERLAY_MAX_LAYERS, count: layers.length } }
141
+ }
142
+ const videoCount = layers.filter(isVideoOverlayVideoLayer).length
143
+ if (videoCount > VIDEO_OVERLAY_MAX_VIDEO_LAYERS) {
144
+ return { ok: false, code: "too_many_video_layers", params: { max: VIDEO_OVERLAY_MAX_VIDEO_LAYERS, count: videoCount } }
145
+ }
146
+ for (let i = 0; i < layers.length; i++) {
147
+ const l: VideoOverlayLayerInput = asLayer(layers[i]) ?? {}
148
+ const at = (code: VideoOverlayErrorCode, params: Record<string, string | number> = {}): VideoOverlayIssue => ({
149
+ ok: false,
150
+ code,
151
+ layer: i,
152
+ ...(typeof l.slot === "number" ? { slot: l.slot } : {}),
153
+ ...(typeof l.planLayer === "number" ? { planLayer: l.planLayer } : {}),
154
+ params,
155
+ })
156
+ const boxFields = VIDEO_OVERLAY_BOX_FIELDS.filter((f) => l[f] !== undefined && l[f] !== null)
157
+ if (!isVideoOverlayPresetId(l.preset) && boxFields.length > 0 && (l.anchor == null || l.width == null)) return at("incomplete_box")
158
+ const bad = outOfBounds(l) ?? soundOutOfBounds(l.sound)
159
+ if (bad) return at("field_out_of_bounds", bad)
160
+ const hasVideo = nonEmpty(l.videoUrl)
161
+ if (nonEmpty(l.imageUrl) && hasVideo) return at("layer_two_sources")
162
+ if (!nonEmpty(l.imageUrl) && !hasVideo) return at("layer_without_image")
163
+ if (l.sound != null && !hasVideo) return at("sound_without_video")
164
+ if (!inTimeRange(l.start)) return at("time_out_of_range", { field: "start", max: VIDEO_OVERLAY_MAX_TIME_SEC })
165
+ if (l.end !== undefined && l.end !== null) {
166
+ if (!inTimeRange(l.end)) return at("time_out_of_range", { field: "end", max: VIDEO_OVERLAY_MAX_TIME_SEC })
167
+ if (!(l.end > l.start)) return at("end_before_start", { start: l.start, end: l.end })
168
+ }
169
+ }
170
+ const hasAspect = isVideoOverlayOutputAspect(body.outputAspect)
171
+ if (!hasAspect && (body.baseFit != null || body.backgroundColor != null)) {
172
+ return { ok: false, code: "fit_without_aspect", params: {} }
173
+ }
174
+ const stored = storedLayout(body.layout)
175
+ if (stored !== undefined && !isVideoOverlayLayoutId(stored)) {
176
+ return { ok: false, code: "field_out_of_bounds", params: { field: "layout", allowed: VIDEO_OVERLAY_LAYOUT_IDS.join(", ") } }
177
+ }
178
+ const layout = stored as VideoOverlayLayoutId | undefined
179
+ if (layout && body.baseBox != null && videoOverlayLayoutPlacesBase(layout)) return { ok: false, code: "layout_conflicts_base_box", params: { layout } }
180
+ const boxIssue = body.baseBox != null ? baseBoxIssue(body.baseBox) : null
181
+ if (boxIssue) return boxIssue
182
+ if (layout && !hasAspect && videoOverlayLayoutNeedsAspect(layout)) return { ok: false, code: "layout_needs_aspect", params: { layout } }
183
+ if (layout && videoOverlayLayoutNeedsVideoLayer(layout) && !layers.some(isVideoOverlayVideoLayer)) {
184
+ return { ok: false, code: "layout_needs_video_layer", params: { layout } }
185
+ }
186
+ if (body.baseBox != null && !hasAspect) return { ok: false, code: "base_box_needs_aspect", params: {} }
187
+ return { ok: true }
188
+ }
189
+
190
+ const MESSAGES: { readonly [C in VideoOverlayErrorCode]: (p: Readonly<Record<string, string | number>>) => string } = {
191
+ no_layers: () => "At least 1 layer is required",
192
+ too_many_layers: (p) => `At most ${p.max} layers (got ${p.count})`,
193
+ incomplete_box: (p) => (p.field ? `${p.field} needs an anchor and a width` : "anchor and width are required without a preset"),
194
+ layer_without_image: () => "no image or video — connect one to the layer's handle or set imageUrl or videoUrl",
195
+ time_out_of_range: (p) => `${p.field} must be between 0 and ${p.max} s`,
196
+ end_before_start: (p) => `end (${p.end} s) must be after start (${p.start} s)`,
197
+ fit_without_aspect: () => "baseFit and backgroundColor need an outputAspect",
198
+ field_out_of_bounds: (p) => `${p.field} is out of range (allowed: ${p.allowed})`,
199
+ invalid_layer_plan: () => "the layer plan must be a list of layers",
200
+ layer_two_sources: () => "has both an image and a video — keep one (imageUrl or videoUrl)",
201
+ too_many_video_layers: (p) => `At most ${p.max} video layers (got ${p.count})`,
202
+ sound_without_video: () => "sound is only for a video layer — remove it or set videoUrl",
203
+ base_box_needs_aspect: () => "baseBox needs an outputAspect",
204
+ layout_needs_aspect: (p) => `layout ${p.layout} needs an outputAspect`,
205
+ layout_needs_video_layer: (p) => `layout ${p.layout} needs a video layer — set videoUrl on a layer or connect a video to a layer's handle`,
206
+ layout_conflicts_base_box: () => "A stack layout places the base itself — remove baseBox or choose Custom",
207
+ }
208
+
209
+ const PLAN_LAYER_WITHOUT_IMAGE = "no image or video — set imageUrl or videoUrl on this layer in the plan."
210
+
211
+ /** `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. */
212
+ export function videoOverlayLayerLabel(ref: { readonly layer?: number; readonly slot?: number; readonly planLayer?: number }): string {
213
+ if (typeof ref.planLayer === "number") return `Plan layer ${ref.planLayer}`
214
+ return typeof ref.slot === "number" ? `Layer ${ref.slot}` : typeof ref.layer === "number" ? `layers[${ref.layer}]` : ""
215
+ }
216
+
217
+ /** The ONE English rendering of a verdict — the route's 400 text and the worker's error message. */
218
+ export function formatVideoOverlayError(issue: VideoOverlayIssue): string {
219
+ const label = videoOverlayLayerLabel(issue)
220
+ // A plan layer has no handle to connect — its source can only come from its own imageUrl or videoUrl.
221
+ const text = issue.code === "layer_without_image" && typeof issue.planLayer === "number" ? PLAN_LAYER_WITHOUT_IMAGE : MESSAGES[issue.code](issue.params)
222
+ return label ? `${label}: ${text}` : text
223
+ }