@nodaro/shared 3.31.0 → 3.33.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 (378) hide show
  1. package/README.md +17 -0
  2. package/dist/chunk-23FJQTEA.js +1604 -0
  3. package/dist/chunk-23FJQTEA.js.map +1 -0
  4. package/dist/chunk-2NIQO2J3.cjs +54 -0
  5. package/dist/chunk-2NIQO2J3.cjs.map +1 -0
  6. package/dist/chunk-2NQLSLSN.cjs +19 -0
  7. package/dist/chunk-2NQLSLSN.cjs.map +1 -0
  8. package/dist/chunk-2OJIVO7R.cjs +32 -0
  9. package/dist/chunk-2OJIVO7R.cjs.map +1 -0
  10. package/dist/chunk-2RF4Z7KG.cjs +803 -0
  11. package/dist/chunk-2RF4Z7KG.cjs.map +1 -0
  12. package/dist/chunk-3RYKIUAE.js +86 -0
  13. package/dist/chunk-3RYKIUAE.js.map +1 -0
  14. package/dist/chunk-44I73CQS.cjs +194 -0
  15. package/dist/chunk-44I73CQS.cjs.map +1 -0
  16. package/dist/chunk-5PC6JBGJ.cjs +1419 -0
  17. package/dist/chunk-5PC6JBGJ.cjs.map +1 -0
  18. package/dist/chunk-5RU2HCW2.js +30 -0
  19. package/dist/chunk-5RU2HCW2.js.map +1 -0
  20. package/dist/chunk-5RYLK3MQ.js +267 -0
  21. package/dist/chunk-5RYLK3MQ.js.map +1 -0
  22. package/dist/chunk-5THUHJ3E.js +46 -0
  23. package/dist/chunk-5THUHJ3E.js.map +1 -0
  24. package/dist/chunk-6DAWSVX2.cjs +103 -0
  25. package/dist/chunk-6DAWSVX2.cjs.map +1 -0
  26. package/dist/chunk-6WZ2VN7V.js +920 -0
  27. package/dist/chunk-6WZ2VN7V.js.map +1 -0
  28. package/dist/chunk-7G7G42KS.js +86 -0
  29. package/dist/chunk-7G7G42KS.js.map +1 -0
  30. package/dist/chunk-7Z5LUTGU.js +1567 -0
  31. package/dist/chunk-7Z5LUTGU.js.map +1 -0
  32. package/dist/chunk-AINCI23X.js +2171 -0
  33. package/dist/chunk-AINCI23X.js.map +1 -0
  34. package/dist/chunk-BG5D5CZ6.js +1922 -0
  35. package/dist/chunk-BG5D5CZ6.js.map +1 -0
  36. package/dist/chunk-CK3GK34R.js +1381 -0
  37. package/dist/chunk-CK3GK34R.js.map +1 -0
  38. package/dist/chunk-CUH22J4D.js +17 -0
  39. package/dist/chunk-CUH22J4D.js.map +1 -0
  40. package/dist/chunk-D26ENTN2.cjs +1770 -0
  41. package/dist/chunk-D26ENTN2.cjs.map +1 -0
  42. package/dist/chunk-D6GNRSCV.cjs +2017 -0
  43. package/dist/chunk-D6GNRSCV.cjs.map +1 -0
  44. package/dist/chunk-FBV5DF6D.js +95 -0
  45. package/dist/chunk-FBV5DF6D.js.map +1 -0
  46. package/dist/chunk-FG4E7MTG.cjs +4 -0
  47. package/dist/chunk-FG4E7MTG.cjs.map +1 -0
  48. package/dist/chunk-FT5CF6IA.js +42 -0
  49. package/dist/chunk-FT5CF6IA.js.map +1 -0
  50. package/dist/chunk-G6IIVKMO.js +26 -0
  51. package/dist/chunk-G6IIVKMO.js.map +1 -0
  52. package/dist/chunk-HC7VKIV5.cjs +430 -0
  53. package/dist/chunk-HC7VKIV5.cjs.map +1 -0
  54. package/dist/chunk-HGC5JNVA.cjs +1503 -0
  55. package/dist/chunk-HGC5JNVA.cjs.map +1 -0
  56. package/dist/chunk-HKFMXNVQ.cjs +1273 -0
  57. package/dist/chunk-HKFMXNVQ.cjs.map +1 -0
  58. package/dist/chunk-HRXEZ3SX.cjs +526 -0
  59. package/dist/chunk-HRXEZ3SX.cjs.map +1 -0
  60. package/dist/chunk-HSHCCBIV.js +255 -0
  61. package/dist/chunk-HSHCCBIV.js.map +1 -0
  62. package/dist/chunk-HUR6ZJ7S.cjs +159 -0
  63. package/dist/chunk-HUR6ZJ7S.cjs.map +1 -0
  64. package/dist/chunk-J7BMO73N.cjs +114 -0
  65. package/dist/chunk-J7BMO73N.cjs.map +1 -0
  66. package/dist/chunk-JFS3NWZ5.cjs +1714 -0
  67. package/dist/chunk-JFS3NWZ5.cjs.map +1 -0
  68. package/dist/chunk-JL4C5VJ7.cjs +488 -0
  69. package/dist/chunk-JL4C5VJ7.cjs.map +1 -0
  70. package/dist/chunk-JSGIEF6Z.cjs +1087 -0
  71. package/dist/chunk-JSGIEF6Z.cjs.map +1 -0
  72. package/dist/chunk-JWA5SGCS.js +203 -0
  73. package/dist/chunk-JWA5SGCS.js.map +1 -0
  74. package/dist/chunk-K3LLGRK7.cjs +3545 -0
  75. package/dist/chunk-K3LLGRK7.cjs.map +1 -0
  76. package/dist/chunk-KU6S7IYV.cjs +210 -0
  77. package/dist/chunk-KU6S7IYV.cjs.map +1 -0
  78. package/dist/chunk-M36G6SRP.js +447 -0
  79. package/dist/chunk-M36G6SRP.js.map +1 -0
  80. package/dist/chunk-M7GQBRZU.cjs +1963 -0
  81. package/dist/chunk-M7GQBRZU.cjs.map +1 -0
  82. package/dist/chunk-MRXGWL42.cjs +4 -0
  83. package/dist/chunk-MRXGWL42.cjs.map +1 -0
  84. package/dist/chunk-NEJ2PV4C.cjs +211 -0
  85. package/dist/chunk-NEJ2PV4C.cjs.map +1 -0
  86. package/dist/chunk-OTATNBMD.js +141 -0
  87. package/dist/chunk-OTATNBMD.js.map +1 -0
  88. package/dist/chunk-OZSACQ2V.js +471 -0
  89. package/dist/chunk-OZSACQ2V.js.map +1 -0
  90. package/dist/chunk-PHZ23DP3.js +1782 -0
  91. package/dist/chunk-PHZ23DP3.js.map +1 -0
  92. package/dist/chunk-PQHS255G.js +1369 -0
  93. package/dist/chunk-PQHS255G.js.map +1 -0
  94. package/dist/chunk-PRYE7AZQ.cjs +1227 -0
  95. package/dist/chunk-PRYE7AZQ.cjs.map +1 -0
  96. package/dist/chunk-PVJBAPYJ.js +404 -0
  97. package/dist/chunk-PVJBAPYJ.js.map +1 -0
  98. package/dist/chunk-PXFQVLBX.js +776 -0
  99. package/dist/chunk-PXFQVLBX.js.map +1 -0
  100. package/dist/chunk-QA3MVQ32.js +21 -0
  101. package/dist/chunk-QA3MVQ32.js.map +1 -0
  102. package/dist/chunk-QJRP44ZO.js +769 -0
  103. package/dist/chunk-QJRP44ZO.js.map +1 -0
  104. package/dist/chunk-SAW5OK36.cjs +54 -0
  105. package/dist/chunk-SAW5OK36.cjs.map +1 -0
  106. package/dist/chunk-SES6GDBQ.cjs +624 -0
  107. package/dist/chunk-SES6GDBQ.cjs.map +1 -0
  108. package/dist/chunk-SFW3UB2P.js +31 -0
  109. package/dist/chunk-SFW3UB2P.js.map +1 -0
  110. package/dist/chunk-TNPDV7I4.cjs +2346 -0
  111. package/dist/chunk-TNPDV7I4.cjs.map +1 -0
  112. package/dist/chunk-TU33KYKW.cjs +25 -0
  113. package/dist/chunk-TU33KYKW.cjs.map +1 -0
  114. package/dist/chunk-TZBIY5C3.js +187 -0
  115. package/dist/chunk-TZBIY5C3.js.map +1 -0
  116. package/dist/chunk-TZE673G6.js +3 -0
  117. package/dist/chunk-TZE673G6.js.map +1 -0
  118. package/dist/chunk-UCFWI6D4.js +29 -0
  119. package/dist/chunk-UCFWI6D4.js.map +1 -0
  120. package/dist/chunk-UTQSSKSG.js +1164 -0
  121. package/dist/chunk-UTQSSKSG.js.map +1 -0
  122. package/dist/chunk-VA42637J.cjs +287 -0
  123. package/dist/chunk-VA42637J.cjs.map +1 -0
  124. package/dist/chunk-VNQRI2RO.cjs +1047 -0
  125. package/dist/chunk-VNQRI2RO.cjs.map +1 -0
  126. package/dist/chunk-VXPLKQWY.cjs +821 -0
  127. package/dist/chunk-VXPLKQWY.cjs.map +1 -0
  128. package/dist/chunk-WD6HJRBG.cjs +197 -0
  129. package/dist/chunk-WD6HJRBG.cjs.map +1 -0
  130. package/dist/chunk-WDIBOWAA.js +1054 -0
  131. package/dist/chunk-WDIBOWAA.js.map +1 -0
  132. package/dist/chunk-WKOIGLQX.cjs +38 -0
  133. package/dist/chunk-WKOIGLQX.cjs.map +1 -0
  134. package/dist/chunk-WNVQ3SMB.cjs +96 -0
  135. package/dist/chunk-WNVQ3SMB.cjs.map +1 -0
  136. package/dist/chunk-WRSWH7US.cjs +285 -0
  137. package/dist/chunk-WRSWH7US.cjs.map +1 -0
  138. package/dist/chunk-XGFTL5XY.js +181 -0
  139. package/dist/chunk-XGFTL5XY.js.map +1 -0
  140. package/dist/chunk-XNISPHTZ.js +1039 -0
  141. package/dist/chunk-XNISPHTZ.js.map +1 -0
  142. package/dist/chunk-Y2PM3FFL.js +3 -0
  143. package/dist/chunk-Y2PM3FFL.js.map +1 -0
  144. package/dist/chunk-YBPBK5KI.js +1030 -0
  145. package/dist/chunk-YBPBK5KI.js.map +1 -0
  146. package/dist/chunk-YWNYGYI7.cjs +31 -0
  147. package/dist/chunk-YWNYGYI7.cjs.map +1 -0
  148. package/dist/chunk-YYV35XOS.js +122 -0
  149. package/dist/chunk-YYV35XOS.js.map +1 -0
  150. package/dist/chunk-Z2OL5AJD.cjs +133 -0
  151. package/dist/chunk-Z2OL5AJD.cjs.map +1 -0
  152. package/dist/chunk-ZDFHA2EC.js +572 -0
  153. package/dist/chunk-ZDFHA2EC.js.map +1 -0
  154. package/dist/chunk-ZL7UM6PU.cjs +34 -0
  155. package/dist/chunk-ZL7UM6PU.cjs.map +1 -0
  156. package/dist/chunk-ZNZDQAXN.js +175 -0
  157. package/dist/chunk-ZNZDQAXN.js.map +1 -0
  158. package/dist/chunk-ZO5PBBFX.js +3497 -0
  159. package/dist/chunk-ZO5PBBFX.js.map +1 -0
  160. package/dist/chunk-ZRL2UFTH.cjs +1073 -0
  161. package/dist/chunk-ZRL2UFTH.cjs.map +1 -0
  162. package/dist/entries/apps.cjs +155 -0
  163. package/dist/entries/apps.cjs.map +1 -0
  164. package/dist/entries/apps.d.cts +292 -0
  165. package/dist/entries/apps.d.ts +292 -0
  166. package/dist/entries/apps.js +10 -0
  167. package/dist/entries/apps.js.map +1 -0
  168. package/dist/entries/captions.cjs +124 -0
  169. package/dist/entries/captions.cjs.map +1 -0
  170. package/dist/entries/captions.d.cts +354 -0
  171. package/dist/entries/captions.d.ts +354 -0
  172. package/dist/entries/captions.js +3 -0
  173. package/dist/entries/captions.js.map +1 -0
  174. package/dist/entries/catalogs.cjs +165 -0
  175. package/dist/entries/catalogs.cjs.map +1 -0
  176. package/dist/entries/catalogs.d.cts +385 -0
  177. package/dist/entries/catalogs.d.ts +385 -0
  178. package/dist/entries/catalogs.js +4 -0
  179. package/dist/entries/catalogs.js.map +1 -0
  180. package/dist/entries/credits.cjs +596 -0
  181. package/dist/entries/credits.cjs.map +1 -0
  182. package/dist/entries/credits.d.cts +1460 -0
  183. package/dist/entries/credits.d.ts +1460 -0
  184. package/dist/entries/credits.js +11 -0
  185. package/dist/entries/credits.js.map +1 -0
  186. package/dist/entries/edl.cjs +409 -0
  187. package/dist/entries/edl.cjs.map +1 -0
  188. package/dist/entries/edl.d.cts +1199 -0
  189. package/dist/entries/edl.d.ts +1199 -0
  190. package/dist/entries/edl.js +4 -0
  191. package/dist/entries/edl.js.map +1 -0
  192. package/dist/entries/entities.cjs +530 -0
  193. package/dist/entries/entities.cjs.map +1 -0
  194. package/dist/entries/entities.d.cts +1371 -0
  195. package/dist/entries/entities.d.ts +1371 -0
  196. package/dist/entries/entities.js +5 -0
  197. package/dist/entries/entities.js.map +1 -0
  198. package/dist/entries/i18n.cjs +48 -0
  199. package/dist/entries/i18n.cjs.map +1 -0
  200. package/dist/entries/i18n.d.cts +69 -0
  201. package/dist/entries/i18n.d.ts +69 -0
  202. package/dist/entries/i18n.js +3 -0
  203. package/dist/entries/i18n.js.map +1 -0
  204. package/dist/entries/llm-models.cjs +177 -0
  205. package/dist/entries/llm-models.cjs.map +1 -0
  206. package/dist/entries/llm-models.d.cts +435 -0
  207. package/dist/entries/llm-models.d.ts +435 -0
  208. package/dist/entries/llm-models.js +4 -0
  209. package/dist/entries/llm-models.js.map +1 -0
  210. package/dist/entries/media.cjs +335 -0
  211. package/dist/entries/media.cjs.map +1 -0
  212. package/dist/entries/media.d.cts +518 -0
  213. package/dist/entries/media.d.ts +518 -0
  214. package/dist/entries/media.js +6 -0
  215. package/dist/entries/media.js.map +1 -0
  216. package/dist/entries/model-catalog.cjs +259 -0
  217. package/dist/entries/model-catalog.cjs.map +1 -0
  218. package/dist/entries/model-catalog.d.cts +202 -0
  219. package/dist/entries/model-catalog.d.ts +202 -0
  220. package/dist/entries/model-catalog.js +6 -0
  221. package/dist/entries/model-catalog.js.map +1 -0
  222. package/dist/entries/models.cjs +833 -0
  223. package/dist/entries/models.cjs.map +1 -0
  224. package/dist/entries/models.d.cts +287 -0
  225. package/dist/entries/models.d.ts +287 -0
  226. package/dist/entries/models.js +8 -0
  227. package/dist/entries/models.js.map +1 -0
  228. package/dist/entries/nodes.cjs +789 -0
  229. package/dist/entries/nodes.cjs.map +1 -0
  230. package/dist/entries/nodes.d.cts +1600 -0
  231. package/dist/entries/nodes.d.ts +1600 -0
  232. package/dist/entries/nodes.js +16 -0
  233. package/dist/entries/nodes.js.map +1 -0
  234. package/dist/entries/organizations.cjs +80 -0
  235. package/dist/entries/organizations.cjs.map +1 -0
  236. package/dist/entries/organizations.d.cts +466 -0
  237. package/dist/entries/organizations.d.ts +466 -0
  238. package/dist/entries/organizations.js +3 -0
  239. package/dist/entries/organizations.js.map +1 -0
  240. package/dist/entries/pipeline.cjs +594 -0
  241. package/dist/entries/pipeline.cjs.map +1 -0
  242. package/dist/entries/pipeline.d.cts +2617 -0
  243. package/dist/entries/pipeline.d.ts +2617 -0
  244. package/dist/entries/pipeline.js +5 -0
  245. package/dist/entries/pipeline.js.map +1 -0
  246. package/dist/entries/scene3d.cjs +704 -0
  247. package/dist/entries/scene3d.cjs.map +1 -0
  248. package/dist/entries/scene3d.d.cts +4284 -0
  249. package/dist/entries/scene3d.d.ts +4284 -0
  250. package/dist/entries/scene3d.js +3 -0
  251. package/dist/entries/scene3d.js.map +1 -0
  252. package/dist/entries/social.cjs +714 -0
  253. package/dist/entries/social.cjs.map +1 -0
  254. package/dist/entries/social.d.cts +1366 -0
  255. package/dist/entries/social.d.ts +1366 -0
  256. package/dist/entries/social.js +5 -0
  257. package/dist/entries/social.js.map +1 -0
  258. package/dist/entries/types.cjs +13 -0
  259. package/dist/entries/types.cjs.map +1 -0
  260. package/dist/entries/types.d.cts +162 -0
  261. package/dist/entries/types.d.ts +162 -0
  262. package/dist/entries/types.js +4 -0
  263. package/dist/entries/types.js.map +1 -0
  264. package/dist/entries/ugc.cjs +279 -0
  265. package/dist/entries/ugc.cjs.map +1 -0
  266. package/dist/entries/ugc.d.cts +575 -0
  267. package/dist/entries/ugc.d.ts +575 -0
  268. package/dist/entries/ugc.js +6 -0
  269. package/dist/entries/ugc.js.map +1 -0
  270. package/dist/entries/video.cjs +549 -0
  271. package/dist/entries/video.cjs.map +1 -0
  272. package/dist/entries/video.d.cts +1791 -0
  273. package/dist/entries/video.d.ts +1791 -0
  274. package/dist/entries/video.js +8 -0
  275. package/dist/entries/video.js.map +1 -0
  276. package/dist/entries/workflow.cjs +574 -0
  277. package/dist/entries/workflow.cjs.map +1 -0
  278. package/dist/entries/workflow.d.cts +1743 -0
  279. package/dist/entries/workflow.d.ts +1743 -0
  280. package/dist/entries/workflow.js +5 -0
  281. package/dist/entries/workflow.js.map +1 -0
  282. package/dist/fan-out-meta-Bu6VyXcZ.d.cts +19 -0
  283. package/dist/fan-out-meta-Bu6VyXcZ.d.ts +19 -0
  284. package/dist/gemini-omni-voices-zeRXxSbZ.d.cts +174 -0
  285. package/dist/gemini-omni-voices-zeRXxSbZ.d.ts +174 -0
  286. package/dist/image-overlay-layers-CyBfRhxJ.d.cts +208 -0
  287. package/dist/image-overlay-layers-CyBfRhxJ.d.ts +208 -0
  288. package/dist/index.cjs +7747 -27084
  289. package/dist/index.cjs.map +1 -1
  290. package/dist/index.d.cts +32 -24198
  291. package/dist/index.d.ts +32 -24198
  292. package/dist/index.js +40 -25220
  293. package/dist/index.js.map +1 -1
  294. package/dist/model-catalog-V-ZNzRSd.d.cts +651 -0
  295. package/dist/model-catalog-V-ZNzRSd.d.ts +651 -0
  296. package/dist/presentation-types-0ENOCjoj.d.cts +61 -0
  297. package/dist/presentation-types-0ENOCjoj.d.ts +61 -0
  298. package/dist/presentation-utils-D0kxsWf9.d.cts +92 -0
  299. package/dist/presentation-utils-pZwlEAzo.d.ts +92 -0
  300. package/dist/scene-node-types-C3kl_zyK.d.cts +1949 -0
  301. package/dist/scene-node-types-C3kl_zyK.d.ts +1949 -0
  302. package/dist/supported-fonts-CRoF1gOy.d.cts +16 -0
  303. package/dist/supported-fonts-CRoF1gOy.d.ts +16 -0
  304. package/dist/types-BRlFPEru.d.cts +511 -0
  305. package/dist/types-BRlFPEru.d.ts +511 -0
  306. package/dist/types-DffyGSy5.d.cts +67 -0
  307. package/dist/types-DffyGSy5.d.ts +67 -0
  308. package/package.json +102 -1
  309. package/src/__tests__/add-captions-plan.test.ts +6 -2
  310. package/src/__tests__/caption-edge-dash.test.ts +23 -0
  311. package/src/__tests__/fixtures/root-exports.baseline.json +4625 -0
  312. package/src/__tests__/input-field-extra-keys.test.ts +1 -0
  313. package/src/__tests__/model-makers.test.ts +76 -0
  314. package/src/__tests__/no-internal-imports.test.ts +1 -1
  315. package/src/__tests__/node-aspect-ratio.test.ts +25 -0
  316. package/src/__tests__/node-runtime-keys.test.ts +9 -0
  317. package/src/__tests__/package-entries.test.ts +50 -0
  318. package/src/__tests__/pitch-tempo-pricing.test.ts +21 -0
  319. package/src/__tests__/presentation-utils.test.ts +15 -0
  320. package/src/__tests__/preview-gate-use-case.test.ts +151 -0
  321. package/src/__tests__/private-host.test.ts +53 -0
  322. package/src/__tests__/run-continuation.test.ts +7 -1
  323. package/src/__tests__/site-capture-node.test.ts +58 -0
  324. package/src/__tests__/ugc-lane-wires.test.ts +228 -0
  325. package/src/__tests__/ugc-node-wires.test.ts +9 -3
  326. package/src/__tests__/ugc-run-state.test.ts +5 -4
  327. package/src/__tests__/video-analysis-catalog-sync.test.ts +1 -1
  328. package/src/__tests__/video-analysis-pricing.test.ts +6 -6
  329. package/src/__tests__/voice-changer-pro-quote.test.ts +79 -0
  330. package/src/add-captions-plan.ts +9 -3
  331. package/src/caption-edge-dash.ts +33 -0
  332. package/src/component-types.ts +9 -0
  333. package/src/credit-estimators/index.ts +22 -1
  334. package/src/credit-estimators/pitch-tempo.ts +15 -1
  335. package/src/credit-estimators/speech.ts +72 -4
  336. package/src/credit-estimators/unit-quote.ts +52 -0
  337. package/src/credit-estimators/video-sfx.ts +15 -0
  338. package/src/credit-estimators/voice-changer-pro-quote.ts +138 -0
  339. package/src/credit-identifiers.ts +62 -17
  340. package/src/entity-image-handle.ts +2 -0
  341. package/src/entries/apps.ts +63 -0
  342. package/src/entries/captions.ts +34 -0
  343. package/src/entries/catalogs.ts +65 -0
  344. package/src/entries/credits.ts +105 -0
  345. package/src/entries/edl.ts +42 -0
  346. package/src/entries/entities.ts +144 -0
  347. package/src/entries/i18n.ts +31 -0
  348. package/src/entries/llm-models.ts +63 -0
  349. package/src/entries/media.ts +36 -0
  350. package/src/entries/model-catalog.ts +95 -0
  351. package/src/entries/models.ts +266 -0
  352. package/src/entries/nodes.ts +245 -0
  353. package/src/entries/organizations.ts +9 -0
  354. package/src/entries/pipeline.ts +43 -0
  355. package/src/entries/scene3d.ts +27 -0
  356. package/src/entries/social.ts +297 -0
  357. package/src/entries/types.ts +26 -0
  358. package/src/entries/ugc.ts +14 -0
  359. package/src/entries/video.ts +59 -0
  360. package/src/entries/workflow.ts +172 -0
  361. package/src/fan-out-rows.ts +2 -0
  362. package/src/index.ts +25 -1845
  363. package/src/json-kinds.ts +4 -0
  364. package/src/model-catalog.ts +243 -34
  365. package/src/node-mappable-fields.ts +1 -0
  366. package/src/node-run-routes.ts +2 -0
  367. package/src/node-runtime-keys.ts +8 -0
  368. package/src/normalize-node-params.ts +30 -0
  369. package/src/presentation-utils.ts +12 -0
  370. package/src/preview-gate.ts +92 -14
  371. package/src/private-host.ts +89 -59
  372. package/src/producer-types.ts +16 -2
  373. package/src/run-continuation.ts +21 -0
  374. package/src/site-capture-node.ts +82 -0
  375. package/src/ugc-lane-wires.ts +246 -0
  376. package/src/ugc-node-wires.ts +37 -7
  377. package/src/ugc-run-state.ts +5 -3
  378. package/src/video-analysis-pricing.ts +31 -29
@@ -0,0 +1,1371 @@
1
+ import { o as GenericNode, G as GenericEdge, B as UsageMode, k as ConnectedReference, R as ReferenceSource } from '../types-BRlFPEru.js';
2
+ export { C as CHARACTER_ASSET_TYPES, a as CHARACTER_ASSET_VARIANTS, b as CHARACTER_ATTACH_COLUMNS, c as CHARACTER_REFERENCE_PHOTO_KINDS, d as CHARACTER_STYLES, e as CREATURE_ATTACH_COLUMNS, f as CharacterAssetType, g as CharacterAttachColumn, i as CharacterReferencePhoto, j as CharacterReferencePhotoKind, l as CreatureAttachColumn, m as DEFAULT_USAGE_MODE, E as EntityStyle, L as LOCATION_ASSET_TYPES, q as LOCATION_ASSET_VARIANTS, r as LOCATION_ATTACH_COLUMNS, s as LOCATION_REFERENCE_PHOTO_KINDS, t as LOCATION_REFERENCE_PHOTO_KIND_LABELS, u as LocationAssetType, v as LocationAttachColumn, w as LocationReferencePhotoKind, O as OBJECT_ASSET_TYPES, x as OBJECT_ASSET_VARIANTS, y as OBJECT_ATTACH_COLUMNS, z as ObjectAssetType, A as ObjectAttachColumn, P as PLACEHOLDER_CHARACTER_NAME, U as USAGE_MODES, F as isUsageMode, H as locationReferencePhotoKindLabel, J as usageModeDirective, K as usageModeIncludesName, M as usageModeLabel } from '../types-BRlFPEru.js';
3
+
4
+ /**
5
+ * Featured entity starter catalog (the "Featured" tab of each
6
+ * entity Library).
7
+ *
8
+ * These are app-provided starter presets: a curated visual description per
9
+ * archetype that the user can drop into an entity's Generate field as a
10
+ * head-start, instead of writing one from scratch. They are intentionally
11
+ * ASSETLESS — they seed generation (the user still generates the image with
12
+ * their chosen model + style), so no hosted sample images are required. The
13
+ * "Mine" tab (reuse an already-saved image) and "+ New" (Upload / write your
14
+ * own) cover the other two on-ramps.
15
+ */
16
+ interface FeaturedEntity {
17
+ /** Stable id (unique within its type). */
18
+ id: string;
19
+ /** Short name shown on the chip. */
20
+ label: string;
21
+ /** Curated visual description dropped into the Generate field. */
22
+ description: string;
23
+ }
24
+ declare const FEATURED_ENTITIES: Record<string, readonly FeaturedEntity[]>;
25
+ /** Featured presets for an entity type ("character" | "location" | "object"). */
26
+ declare function getFeaturedEntities(type: string): readonly FeaturedEntity[];
27
+
28
+ /**
29
+ * Ancestor reference image collection — traverses upstream nodes to find
30
+ * image-producing ancestors, with passthrough for text/logic nodes.
31
+ * Shared between frontend and backend via a callback for extracting image URLs.
32
+ */
33
+
34
+ declare const IMAGE_REF_TYPES: Set<string>;
35
+ declare const PASSTHROUGH_TYPES: Set<string>;
36
+ /**
37
+ * Collect reference image URLs from upstream ancestor nodes.
38
+ * @param getImageUrl - Callback to extract an image URL from a node. Frontend uses
39
+ * extractNodeOutput(), backend uses nodeStates[id]?.output?.imageUrl.
40
+ */
41
+ declare function collectAncestorRefs<N extends GenericNode, E extends GenericEdge>(nodeId: string, nodes: N[], edges: E[], getImageUrl: (node: N) => string | undefined, visited?: Set<string>): string[];
42
+
43
+ /**
44
+ * Shared helper for materializing user-attached "extra reference images" into
45
+ * `ConnectedReference` entries.
46
+ *
47
+ * Used by both:
48
+ * - frontend `execute-node.ts` (single-node Run + DAG executor path) and
49
+ * - backend `payload-builder.ts` (orchestrator path)
50
+ * so single-node frontend runs and orchestrator-driven runs produce identical
51
+ * `referenceImageUrls` + assembled prompts. See `frontend/src/types/nodes.ts`
52
+ * for the `ExtraRef` interface and `packages/shared/src/prompt-builder.ts`
53
+ * for the directive emission contract (`buildExtraRefDirectives`).
54
+ *
55
+ * Field mapping:
56
+ * - manual upload → source = "manual", description = ref.description
57
+ * - char-variant → source = "wired-character", characterSlug + variantSlug
58
+ * preserved, description = ref.description (used as the
59
+ * bullet's per-image description in directives — overrides
60
+ * `variantDescription` from the character node).
61
+ *
62
+ * Usage-mode resolution: per-ref `usageMode` override → upstream character
63
+ * node's `defaultUsageMode` → global "identical". The resolved mode is stored
64
+ * in `defaultUsageMode` on the resulting `ConnectedReference` so the existing
65
+ * directive emission (`buildExtraRefDirectives`, `buildCanonicalFallback`,
66
+ * `resolveCharacterMentions`) reads it uniformly.
67
+ *
68
+ * Character-node lookup: takes a `lookupCharacterNode` callback so each caller
69
+ * can provide its own (frontend uses Zustand store + edges, backend uses
70
+ * `PayloadBuildContext.nodes` + edges). The callback should return the
71
+ * character node whose name slugifies to `characterSlug`, or undefined if
72
+ * no such character is wired upstream.
73
+ */
74
+
75
+ /** Shape of an extra-ref entry on node data. Matches `ExtraRef` in the
76
+ * frontend `types/nodes.ts`; duplicated here as a structural interface so
77
+ * the backend (which sees node data as `Record<string, unknown>`) can pass
78
+ * raw JSON through `expandExtraRefsToConnectedReferences`. */
79
+ interface ExtraRefInput {
80
+ /**
81
+ * Stable id of this extra reference, when the row has one. What a
82
+ * `{ref:<id>}` token in the prompt names; passed through to the shared video
83
+ * resolver's slot map by both the canvas and the orchestrator. Absent → the
84
+ * row still numbers normally but cannot be addressed by id.
85
+ */
86
+ readonly id?: string;
87
+ readonly url?: string;
88
+ readonly description?: string;
89
+ readonly characterSlug?: string;
90
+ readonly variantSlug?: string;
91
+ readonly variantDisplayName?: string;
92
+ readonly usageMode?: UsageMode;
93
+ }
94
+ /** Hook that returns extra metadata for the upstream Character node backing
95
+ * a given character slug, if any. Used to resolve `defaultUsageMode` and
96
+ * `characterCanonicalDescription`. */
97
+ interface ExtraRefCharacterContext {
98
+ readonly defaultUsageMode?: UsageMode;
99
+ readonly canonicalDescription?: string | null;
100
+ readonly displayName?: string;
101
+ /** Character node's hybrid `defaultRole` — stamped onto the extra's
102
+ * `ConnectedReference.defaultRole` (only when the extra carries no per-ref
103
+ * `usageMode` override, which would take precedence). */
104
+ readonly defaultRole?: string;
105
+ /** Character node's `identityLock`, mapped to the per-reference lock shape
106
+ * (`characterLockToRefLock`) — stamped onto the extra's
107
+ * `ConnectedReference.identityLock`. */
108
+ readonly identityLock?: {
109
+ enabled: boolean;
110
+ text?: string;
111
+ };
112
+ }
113
+ /**
114
+ * Convert a list of `ExtraRef` entries into `ConnectedReference` entries that
115
+ * append to the consumer node's existing `connectedReferences` list. The
116
+ * resulting entries carry `isExtraRef: true` so the shared prompt-builder
117
+ * routes them through the dedicated extra-ref directive emission (which
118
+ * handles "Image N is the same subject as Image M, …" pairing).
119
+ *
120
+ * `lookupCharacterContext(slug)` is called for character-sourced extras to
121
+ * resolve the upstream character node's `defaultUsageMode` and canonical
122
+ * description. Returning `undefined` is safe — the helper falls back to the
123
+ * per-ref `usageMode` override or the global default.
124
+ */
125
+ declare function expandExtraRefsToConnectedReferences(extras: ReadonlyArray<ExtraRefInput> | undefined, lookupCharacterContext?: (slug: string) => ExtraRefCharacterContext | undefined): ConnectedReference[];
126
+
127
+ /**
128
+ * Surround continuation — the shared WIRE CONTRACT.
129
+ *
130
+ * The Location 360° "look-around" builds each ring view (45°, 90°, …) as an
131
+ * image-to-image continuation of the previous one.
132
+ *
133
+ * This module owns only what the route Zod schema, the SDK input type, and the
134
+ * worker all need to agree on: the direction enum and the carried-fraction
135
+ * defaults. The fill prompt lives in `@nodaro/prompts` (never published) and
136
+ * the compositing/harmonization engine is private.
137
+ */
138
+ /**
139
+ * The camera move a continuation represents: `right` / `left` pan the view
140
+ * horizontally, `up` / `down` tilt it vertically.
141
+ */
142
+ declare const SURROUND_DIRECTIONS: readonly ["right", "left", "up", "down"];
143
+ type SurroundDirection = (typeof SURROUND_DIRECTIONS)[number];
144
+ /** Default carried fraction for a horizontal pan. */
145
+ declare const DEFAULT_CARRIED_FRACTION = 0.5;
146
+ /** Default carried fraction for a vertical tilt. */
147
+ declare const TILT_CARRIED_FRACTION = 0.12;
148
+ /** True for the vertical tilt directions (up/down), false for the pans. */
149
+ declare function isTiltDirection(direction: SurroundDirection): boolean;
150
+ /** The carried fraction the platform uses when the caller doesn't pin one. */
151
+ declare function defaultCarriedFraction(direction: SurroundDirection): number;
152
+
153
+ declare const OBJECT_ASPECT_OPTIONS: readonly ["1:1", "3:4", "16:9", "9:16", "4:3"];
154
+ type ObjectAspectRatio = (typeof OBJECT_ASPECT_OPTIONS)[number];
155
+ /**
156
+ * The asset categories with distinct natural framing. For objects, all bucket
157
+ * defaults are currently `"1:1"`, but the per-asset-type table is kept (vs a
158
+ * single flat constant) so future tuning (e.g., wider framing for motion clips
159
+ * with camera-orbit moves) can be added without touching the resolver.
160
+ */
161
+ type ObjectAssetTypeForAspect = "angles" | "materials" | "variations" | "motion" | "custom";
162
+ declare const OBJECT_ASPECT_DEFAULTS: Record<ObjectAssetTypeForAspect, ObjectAspectRatio>;
163
+ declare function isObjectAspectRatio(s: string): s is ObjectAspectRatio;
164
+ interface ResolveObjectAspectOptions {
165
+ /** Explicit `aspectRatio` on the request body — highest precedence. */
166
+ readonly explicit?: string | null;
167
+ /**
168
+ * The object node's `defaultAssetAspectRatio` — set per-canvas-node via the
169
+ * 5-pill toggle on the object node (Phase E). Flows through the API as
170
+ * `objectNodeAspectRatio`.
171
+ */
172
+ readonly nodeOverride?: string | null;
173
+ /** What's being generated. Drives the default when nothing else is set. */
174
+ readonly assetType: ObjectAssetTypeForAspect;
175
+ }
176
+ /**
177
+ * Resolve the final aspect ratio for an object generation request.
178
+ *
179
+ * Precedence: explicit > node override > per-asset-type default. The two
180
+ * "soft" inputs are tolerated as raw strings and only honored when they parse
181
+ * to a value in OBJECT_ASPECT_OPTIONS — anything else falls through to the
182
+ * next layer (so a stale enum value doesn't poison the generation).
183
+ */
184
+ declare function resolveObjectAspectRatio(opts: ResolveObjectAspectOptions): ObjectAspectRatio;
185
+
186
+ /**
187
+ * Slugify a name (character or variant) for use in @-mention tokens.
188
+ * Lowercase, strip non-alphanumeric, collapse runs of dashes.
189
+ */
190
+ declare function characterMentionSlug(name: string): string;
191
+ interface CharacterMentionTokenInfo {
192
+ readonly token: string;
193
+ readonly characterSlug: string;
194
+ /**
195
+ * 1-based positional index assigned at insertion time by the autocomplete.
196
+ * Lets the user wire a literal-text mention (`@kira:1`) to a final-prompt
197
+ * identity directive (`Image 1 (person) — match exactly…`) so the order in
198
+ * the typed prompt matches the order in the assembled directive block.
199
+ */
200
+ readonly imageIndex: number;
201
+ readonly variantSlug: string | null;
202
+ /**
203
+ * Optional per-mention usage-mode override (e.g. `:face`, `:style`). When
204
+ * `null`, the assembled directive falls back to the source character node's
205
+ * `defaultUsageMode`, then to the global `"identical"` default. Always one
206
+ * of the entries in `USAGE_MODES` when non-null — the parser rejects any
207
+ * other 4-part token.
208
+ */
209
+ readonly usageMode: UsageMode | null;
210
+ /**
211
+ * Per-mention ROLE from a NON-MODE 4th segment (Variant + Role Separation) —
212
+ * coexists with a real variant: the variant picks the IMAGE, the role picks
213
+ * the PHRASE (`@kira:1:walking:clothes` → walking image, "the clothes from
214
+ * …"). Curated or custom slug, stored verbatim. OMITTED (undefined, not
215
+ * null) for every other shape — 2/3-part tokens and mode-bearing 4-part
216
+ * tokens keep their pre-existing parse byte-identically. Mirrors
217
+ * `LocationMentionTokenInfo.role`.
218
+ */
219
+ readonly role?: string;
220
+ /**
221
+ * Additive per-mention identity-lock sentinel (Unified Reference Roles,
222
+ * Task 4 + F4). Tri-state: `true` (trailing `~lock`, force lock ON) |
223
+ * `false` (trailing `~nolock`, force lock OFF — suppresses a ref-level
224
+ * `identityLock.enabled = true`) | ABSENT/undefined (neither sentinel —
225
+ * inherit the ref/source default; byte-identical to the pre-Task-4 shape).
226
+ * Only ACTED UPON by the HYBRID resolvers; the LEGACY resolvers ignore it
227
+ * entirely, so both `~lock` and `~nolock` are inert on the legacy path.
228
+ */
229
+ readonly lock?: boolean;
230
+ readonly offset: number;
231
+ }
232
+ /**
233
+ * Parse a single `@<character>:<index>(:<variant>)?(:<usageMode>)?` token.
234
+ *
235
+ * Supported shapes (each segment after `:` may contain internal dashes, so
236
+ * `@young-kira:1:soft-smile` parses unambiguously as character + index +
237
+ * variant):
238
+ *
239
+ * - `@kira:1` → canonical, default mode
240
+ * - `@kira:1:smile` → variant smile, default mode
241
+ * - `@kira:1:face` → canonical, mode "face" (mode is detected by
242
+ * checking the 3rd segment against `USAGE_MODES`)
243
+ * - `@kira:1:smile:face` → variant smile, mode "face"
244
+ * - `@kira:1:walking:clothes` → variant walking, ROLE "clothes" (Variant +
245
+ * Role Separation: a non-mode 4th segment is a
246
+ * per-mention role — curated or custom — that
247
+ * coexists with the variant)
248
+ *
249
+ * Format change: as of the index-in-slug update, the index segment is required.
250
+ * Bare `@kira` is not a mention; the autocomplete always inserts at least
251
+ * `@kira:N`.
252
+ *
253
+ * `knownCharacterSlugs` is no longer needed for parsing (the structure is
254
+ * unambiguous given the closed `USAGE_MODES` enum) — it remains accepted for
255
+ * API compatibility but ignored here. `findCharacterMentionTokens` still uses
256
+ * it to filter unknown characters.
257
+ */
258
+ declare function parseCharacterMentionToken(text: string, _knownCharacterSlugs?: readonly string[]): {
259
+ characterSlug: string;
260
+ imageIndex: number;
261
+ variantSlug: string | null;
262
+ usageMode: UsageMode | null;
263
+ role?: string;
264
+ lock?: boolean;
265
+ } | null;
266
+ /** Find all @-mentions in a prompt that match a known character slug. */
267
+ declare function findCharacterMentionTokens(prompt: string, knownCharacterSlugs: readonly string[]): CharacterMentionTokenInfo[];
268
+
269
+ /**
270
+ * Single source of truth for a character's `{name, url}[]` variant-asset buckets
271
+ * — the image/video variants that are expandable into connected references and
272
+ * therefore selectable in the reference picker AND `@`-mentionable in prompts.
273
+ *
274
+ * Historically the expansion list was hardcoded (6 copies across frontend
275
+ * `connected-references.ts` / `connected-refs-builder.ts` / `execute-node.ts` and
276
+ * backend `payload-builder.ts`), so when wardrobe (`outfitVariations`) and detail
277
+ * close-ups (`detailCloseups`) were added — same `{name,url}[]` shape, written by
278
+ * studio.nodaro.ai — they were silently dropped from the picker and `@` list.
279
+ * Drive every expansion site off this constant so a new bucket can't drift again.
280
+ *
281
+ * NOT included (different shapes, handled elsewhere):
282
+ * - `sheets` (`ReferenceSheet[]` — composited multi-panel boards)
283
+ * - `referenceVideosByVariant` (`Record<variant, url[]>` — per-emotion video refs)
284
+ */
285
+ declare const CHARACTER_VARIANT_ASSET_BUCKETS: readonly ["expressions", "poses", "motions", "angles", "bodyAngles", "lightingVariations", "outfitVariations", "detailCloseups"];
286
+ type CharacterVariantAssetBucket = (typeof CHARACTER_VARIANT_ASSET_BUCKETS)[number];
287
+ interface CharacterVariantAssetItem {
288
+ readonly name: string;
289
+ readonly url: string;
290
+ readonly description?: string;
291
+ }
292
+ /**
293
+ * Build the `{ bucket: items[] }` map for every variant-asset bucket from a
294
+ * character node's data. Missing / non-array buckets coerce to `[]`. One helper
295
+ * for all six expansion sites so the bucket set is defined exactly once.
296
+ */
297
+ declare function characterVariantAssetArrays(data: Record<string, unknown> | null | undefined): Record<CharacterVariantAssetBucket, readonly CharacterVariantAssetItem[]>;
298
+ /**
299
+ * Map a character's composite reference `sheets` (ReferenceSheet[] — a different
300
+ * shape, with a composite board `url` + `type`/`skin`) into mentionable
301
+ * `{name,url}` items so they too can be picked / `@`-mentioned. Each sheet → one
302
+ * item named `"<type> <skin>"` (e.g. "turnaround studio"). Drops url-less sheets.
303
+ */
304
+ declare function characterSheetRefItems(sheets: unknown): CharacterVariantAssetItem[];
305
+ /**
306
+ * Resolve a character's named reference boards from BOTH the `boards` column AND
307
+ * the LEGACY `selected_asset_by_variant` shim (`studioBoard` / `studioBoard:<name>`)
308
+ * — mirroring studio.nodaro.ai's read (entity-boards.ts), which merges both since
309
+ * pre-column boards still live in the shim. Column wins on duplicate name; the
310
+ * unnamed legacy board is named "board". Drops url-less entries.
311
+ */
312
+ declare function characterBoardItems(data: Record<string, unknown> | null | undefined): CharacterVariantAssetItem[];
313
+ /**
314
+ * The COMPLETE set of mentionable character asset arrays: the `{name,url}[]`
315
+ * variant buckets + derived `sheets` and `boards` buckets. This is what the
316
+ * connected-reference / `@`-mention expansion sites iterate, so every
317
+ * studio-produced asset (variants, composite sheets, AND boards — incl. legacy
318
+ * shim boards) surfaces in the reference picker and `@` list.
319
+ */
320
+ declare function characterMentionableAssetArrays(data: Record<string, unknown> | null | undefined): Record<string, readonly CharacterVariantAssetItem[]>;
321
+ /**
322
+ * DISPLAY order for character asset groups in picker menus (swap-picker,
323
+ * `@` autocomplete) — boards first (the highest-value identity reference),
324
+ * then sheets, then the variant buckets in data order.
325
+ *
326
+ * DISPLAY ONLY. The data-record key order of
327
+ * {@link characterMentionableAssetArrays} is payload-numbering-bearing
328
+ * (`{image:N}` / `@name:N` are positional) and MUST NOT change; menus sort
329
+ * their rendered rows by this rank instead. The guard test asserts this
330
+ * list's key set stays identical to the data record's.
331
+ */
332
+ declare const CHARACTER_PICKER_DISPLAY_ORDER: readonly string[];
333
+ /**
334
+ * Display rank for a character entry's asset bucket. Canonical entries
335
+ * (no bucket — the portrait row) lead, then buckets per
336
+ * {@link CHARACTER_PICKER_DISPLAY_ORDER}; unknown buckets sink to the end.
337
+ */
338
+ declare function characterBucketDisplayRank(bucket: string | undefined): number;
339
+ /**
340
+ * Sort picker entries for display: within each CONTIGUOUS run of entries
341
+ * sharing a `characterSlug`, order by {@link characterBucketDisplayRank}
342
+ * (stable within a rank); entries without a slug — and run boundaries —
343
+ * stay exactly where they are. Runs (not a global sort) because the flat
344
+ * reference list interleaves characters with uploads/wired images whose
345
+ * positions are meaningful.
346
+ */
347
+ declare function sortCharacterEntriesForDisplay<T extends {
348
+ readonly characterSlug?: string;
349
+ readonly bucket?: string;
350
+ }>(items: readonly T[]): T[];
351
+
352
+ /**
353
+ * Location `@-mention` parser. Mirrors `character-mention-slug.ts` shape but
354
+ * with two key differences:
355
+ *
356
+ * 1. **Bucketed variants:** the 3rd segment can be `bucket/variant` (slash-
357
+ * separated, e.g. `weather/rain` or `lighting/cinematic`) in addition
358
+ * to a bare usage-mode keyword. Locations carry their variants split
359
+ * across 5 buckets (timeOfDay / weather / seasons / angles / lighting)
360
+ * plus motion clips; the bucket prefix disambiguates which array to
361
+ * pull from when two buckets happen to share a variant name.
362
+ *
363
+ * 2. **Smaller usage-mode set:** locations support 4 modes ("identical",
364
+ * "style", "layout", "none") — a strict subset of the 8 character modes.
365
+ * The character modes "face" / "face-pose" / "pose" / "emotion" / "name"
366
+ * don't apply to scenes.
367
+ *
368
+ * The mention resolver (Phase 2 #2 follow-up) uses the parsed token to look
369
+ * up the variant URL by walking the upstream Location node's `node.data`:
370
+ * timeOfDay / weather / seasons / angles / lighting / atmosphereMotions
371
+ * arrays, each `{name, url}`. Slug match is case-insensitive via the same
372
+ * slugify helper used by character variants.
373
+ *
374
+ * Format reference (the parser accepts these shapes; everything else returns
375
+ * null and the token falls through to literal-text in the final prompt):
376
+ *
377
+ * @oldlibrary:1 — canonical, default mode
378
+ * @oldlibrary:1:weather/rain — rain variant from weather bucket
379
+ * @oldlibrary:1:layout — canonical, mode "layout"
380
+ * @oldlibrary:1:weather/rain:style — variant + mode override
381
+ * @oldlibrary:1:weather/rain:bogus — null (4th segment must be a known
382
+ * location usage mode)
383
+ */
384
+ /** Modes that apply to scenes/locations. Subset of character `USAGE_MODES`. */
385
+ declare const LOCATION_USAGE_MODES: readonly ["identical", "style", "layout", "none"];
386
+ type LocationUsageMode = (typeof LOCATION_USAGE_MODES)[number];
387
+ /** Default mode when neither the slug nor the location node specifies one. */
388
+ declare const DEFAULT_LOCATION_USAGE_MODE: LocationUsageMode;
389
+ /** Type guard — narrows an arbitrary string to `LocationUsageMode`. */
390
+ declare function isLocationUsageMode(s: string): s is LocationUsageMode;
391
+ /**
392
+ * Human-readable label for the location usage-mode dropdown / badge UI.
393
+ * Mirrors `usageModeLabel` for character modes but with location-specific
394
+ * phrasing — locations don't have face/pose semantics, so the labels speak
395
+ * about the scene as a whole (framing, layout, mood) instead of subject
396
+ * features. Used by the location pill's mode menu (slice 4) and the
397
+ * hierarchical drill in the `@`-autocomplete.
398
+ *
399
+ * Phrasing decisions:
400
+ * - "Match exactly" — strongest possible directive; the scene should
401
+ * reproduce the reference verbatim. Equivalent in role to character
402
+ * "Identical".
403
+ * - "Style / mood only" — atmospheric transfer (lighting, color grade,
404
+ * mood) without locking the framing. Maps to character "Style only".
405
+ * - "Layout / framing only" — keep the spatial composition (where things
406
+ * are, where the camera sits) without copying the textures or palette.
407
+ * No character-side equivalent.
408
+ * - "No textual bias" — visual reference only, no top-level header
409
+ * mention. Maps to character "None".
410
+ */
411
+ declare function locationUsageModeLabel(mode: LocationUsageMode): string;
412
+ /**
413
+ * Slugify a location name for use in @-mention tokens. Same algorithm as
414
+ * `characterMentionSlug` — lowercase, strip non-alphanumeric, collapse runs.
415
+ * Kept as a separate export to make the call site's intent explicit and to
416
+ * allow future divergence (e.g., locations may need to preserve digits at
417
+ * the start, characters may not).
418
+ */
419
+ declare function locationMentionSlug(name: string): string;
420
+ interface LocationMentionTokenInfo {
421
+ readonly token: string;
422
+ readonly locationSlug: string;
423
+ readonly imageIndex: number;
424
+ /** "weather", "lighting", etc. — null when the mention targets the canonical
425
+ * main image. */
426
+ readonly bucket: string | null;
427
+ /** Variant name within the bucket (e.g. "rain"). null for canonical. */
428
+ readonly variant: string | null;
429
+ /** Per-mention mode override; null falls back to the location node's default
430
+ * (or the global "identical" default). */
431
+ readonly usageMode: LocationUsageMode | null;
432
+ /** Bare-slug ROLE (Unified Reference Roles, Phase D + F2) — any slash-less,
433
+ * non-mode 3rd segment (`background`, `empty-background`, `as-is`, … or a
434
+ * CUSTOM slug), stored verbatim in slug form — OR (Variant + Role
435
+ * Separation) a non-mode 4th segment coexisting with a bucket/variant
436
+ * (`@lib:1:weather/rain:lighting` → rain image, lighting phrase). Absent
437
+ * (undefined) for canonical / bare-variant / mode tokens. The hybrid
438
+ * resolver + role pill map it back to the phrase key via `normalizeRoleSlug`
439
+ * (custom slugs pass through). Optional so those tokens stay
440
+ * shape-identical to the pre-Phase-D parser output. */
441
+ readonly role?: string;
442
+ /**
443
+ * Additive per-mention identity-lock sentinel (Unified Reference Roles,
444
+ * Task 4 + F4). Tri-state: `true` (`~lock`, force ON) | `false` (`~nolock`,
445
+ * force OFF — suppresses a ref-level `identityLock.enabled = true`) |
446
+ * ABSENT/undefined (neither — inherit the ref default; byte-identical to the
447
+ * pre-Task-4 shape). Only ACTED UPON by the HYBRID resolver; the LEGACY
448
+ * resolver ignores it, so both sentinels are inert on the legacy path.
449
+ */
450
+ readonly lock?: boolean;
451
+ /** Byte offset into the source prompt — used to splice the token out at
452
+ * resolve time. */
453
+ readonly offset: number;
454
+ }
455
+ /**
456
+ * Parse a single `@<location>:<index>(:<bucket>/<variant>|<mode>)?(:<mode>)?`
457
+ * token. Returns null when the token doesn't match any supported shape
458
+ * (caller falls back to literal text).
459
+ *
460
+ * Disambiguation at the 3rd segment: presence of `/` indicates a
461
+ * bucket/variant pair; absence indicates a bare mode keyword. The 4th
462
+ * segment is always a mode override (and must be a valid `LocationUsageMode`).
463
+ */
464
+ declare function parseLocationMentionToken(text: string): {
465
+ locationSlug: string;
466
+ imageIndex: number;
467
+ bucket: string | null;
468
+ variant: string | null;
469
+ usageMode: LocationUsageMode | null;
470
+ /** Bare-slug role (slug form). Present for ANY bare, non-mode 3rd segment
471
+ * (preset OR custom, F2); OMITTED (undefined) for every other shape so
472
+ * canonical/variant/mode results stay byte-identical to the pre-Phase-D parser. */
473
+ role?: string;
474
+ /** Additive per-mention identity-lock sentinel (Task 4 + F4). Tri-state:
475
+ * `true` (`~lock`) | `false` (`~nolock`) | OMITTED (neither — byte-identical). */
476
+ lock?: boolean;
477
+ } | null;
478
+ /**
479
+ * Find all location @-mentions in a prompt that match a known location slug.
480
+ *
481
+ * The regex captures every `@<slug>:<index>(:<segment>)?(:<segment>)?` shape
482
+ * where each segment is either `[a-z][a-z0-9-]*` (the character format —
483
+ * shared with characters) or `[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*` (the
484
+ * bucket/variant format — location-only). `knownLocationSlugs` filters to
485
+ * only the user's wired locations so `@kira:1:smile` doesn't accidentally
486
+ * trip the location parser.
487
+ */
488
+ declare function findLocationMentionTokens(prompt: string, knownLocationSlugs: readonly string[]): LocationMentionTokenInfo[];
489
+
490
+ /**
491
+ * Named-image `@-mention` parser — `@<name-slug>:<index>[:<role>]`.
492
+ *
493
+ * The media analog of `character-mention-slug.ts` / `location-mention-slug.ts`,
494
+ * for a wired image (`wired-image` / `manual` reference) addressed by the slug of
495
+ * its NAME: an upload node's label on the canvas, or the name a thin client puts
496
+ * on the reference. The grammar is the SHORT one — 2 or 3 segments, no buckets, no
497
+ * variants, no usage-mode enum — because a media reference has no variant array to
498
+ * select from and no identity mode to override. Every valid 3rd segment is a ROLE.
499
+ * It is not unique to media: `entity-mention-slug.ts` (creatures/objects) speaks
500
+ * the identical grammar off the shared core noted below.
501
+ *
502
+ * @town:3 — bare mention; renders the reference's binding
503
+ * ("reference image C") at the typed position
504
+ * @town:3:background — role phrase ("the background from reference image C")
505
+ * @town:3:my-custom-role — custom roles pass through verbatim
506
+ * @town:3~lock — additive identity-lock sentinel (also `~nolock`)
507
+ * @town:1:a:b — NULL. A 4-part token is never an image mention.
508
+ *
509
+ * GRAMMAR CORE. The slug shape, the parser and the finder (including BOTH
510
+ * collision guards) live in `mention-token-grammar.ts` and are shared verbatim
511
+ * with `entity-mention-slug.ts` (creatures/objects), which speaks the identical
512
+ * 2-or-3-segment grammar. This module is the MEDIA view of that core: the
513
+ * per-kind field names, and the part that genuinely differs — WHICH refs
514
+ * contribute a slug.
515
+ *
516
+ * NO WIRE FIELD. Unlike `characterSlug` / `locationSlug`, there is no `imageSlug`
517
+ * on `ConnectedReference`: the slug is DERIVED from `defaultName` at resolve time
518
+ * (`knownImageSlugsFromRefs`), so a client cannot drift from the grammar and the
519
+ * reference schema is untouched.
520
+ *
521
+ * NO LEGACY RESOLVER. Only the hybrid reference format resolves these tokens;
522
+ * under the legacy format an `@name:N` token stays literal text and the
523
+ * reference auto-attaches exactly as it does today.
524
+ */
525
+
526
+ /**
527
+ * Slugify an image reference's display name for `@`-mention tokens. Byte-
528
+ * identical algorithm to `characterMentionSlug` / `locationMentionSlug`; kept as
529
+ * a separate export to make the call site's intent explicit.
530
+ */
531
+ declare function imageMentionSlug(name: string): string;
532
+ interface ImageMentionTokenInfo {
533
+ /** The matched token text, verbatim — spliced out of the prompt at resolve time. */
534
+ readonly token: string;
535
+ readonly imageSlug: string;
536
+ /**
537
+ * 1-based correlation index assigned at insertion by the autocomplete
538
+ * (`nextMentionIndex` = max(existing N) + 1, unified across characters,
539
+ * locations and images). The hybrid resolver binds by its own numbering walk,
540
+ * so the index is CORRELATION ONLY — it is never echoed into the prompt.
541
+ */
542
+ readonly imageIndex: number;
543
+ /**
544
+ * Per-mention ROLE from the 3rd segment (`@town:3:background`) — curated
545
+ * (`REFERENCE_ROLE_PRESETS["wired-image"]`) or custom, stored VERBATIM. Media
546
+ * role presets are all single-word, so this never needs `normalizeRoleSlug`
547
+ * (the location-only remapping for multi-word presets). OMITTED (undefined,
548
+ * never null) for 2-part tokens, so those stay shape-identical to a parser
549
+ * with no role support.
550
+ */
551
+ readonly role?: string;
552
+ /**
553
+ * Additive `~lock` / `~nolock` sentinel. Tri-state: `true` (force ON) |
554
+ * `false` (force OFF, suppressing a ref-level `identityLock.enabled`) |
555
+ * ABSENT/undefined (inherit the ref default). Honored only by the hybrid
556
+ * resolver — there is no legacy image resolver to make it inert on.
557
+ */
558
+ readonly lock?: boolean;
559
+ /** Byte offset into the source prompt — used to splice the token out. */
560
+ readonly offset: number;
561
+ }
562
+ /**
563
+ * Parse a single `@<name-slug>:<index>[:<role>]` token. Returns null when the
564
+ * token doesn't match a supported shape (the caller falls back to literal text).
565
+ *
566
+ * Segment count is 2 or 3 — NOT 2–4 like the character/location parsers. A media
567
+ * reference has no variant/bucket slot, so there is nothing for a 4th segment to
568
+ * mean, and claiming one would let this parser swallow a character token.
569
+ *
570
+ * Delegates to the shared `parseMentionToken` and renames its kind-neutral
571
+ * `slug` / `index` to this module's `imageSlug` / `imageIndex`. The optional
572
+ * `role` / `lock` keys are re-emitted CONDITIONALLY so the documented shape rule
573
+ * survives the rename: a 2-part token has no `role` key at all.
574
+ */
575
+ declare function parseImageMentionToken(text: string): {
576
+ imageSlug: string;
577
+ imageIndex: number;
578
+ /** Present ONLY for a 3-part token; omitted otherwise (shape rule). */
579
+ role?: string;
580
+ /** Present ONLY when a sentinel was found; omitted otherwise (shape rule). */
581
+ lock?: boolean;
582
+ } | null;
583
+ /**
584
+ * Find every image `@-mention` in a prompt whose slug is a known image slug.
585
+ *
586
+ * `knownImageSlugs` (from `knownImageSlugsFromRefs`) is what keeps this parser
587
+ * off the other grammars' tokens — every finder matches the same `@slug:N…`
588
+ * surface and only the known-slug set separates them.
589
+ */
590
+ declare function findImageMentionTokens(prompt: string, knownImageSlugs: readonly string[]): ImageMentionTokenInfo[];
591
+ /**
592
+ * The mention slug a single reference contributes, or `null` when the ref
593
+ * cannot carry a mention at all — the SINGLE gate, so every view of "which
594
+ * refs are mentionable" is the same view.
595
+ *
596
+ * Shared by `knownImageSlugsFromRefs` (the finder's known-slug set) and the
597
+ * prompt-builder's hybrid resolver (its slug → ref lookup map). Those two must
598
+ * admit exactly the same refs: a slug the finder accepts but the resolver drops
599
+ * would splice a token with nothing to bind, and a ref the resolver keys under
600
+ * a slug no token can match is dead weight. Emptiness is NOT the gate (see
601
+ * `MENTION_SLUG_PATTERN`).
602
+ */
603
+ declare function imageMentionSlugForRef(r: ConnectedReference): string | null;
604
+ /**
605
+ * The known-image-slug set for a reference list — the SINGLE source of truth for
606
+ * the derivation, shared by `buildImagePrompt`'s Phase 0 and the backend
607
+ * orchestrator's structured-branch gate so the two can never disagree about
608
+ * whether a prompt carries a resolvable image mention.
609
+ *
610
+ * Only MEDIA refs (`wired-image` / `manual`) with a URL participate — the other
611
+ * sources have their own mention grammars: characters, locations, and — since the
612
+ * creature/object leg — wired entities via `knownEntitySlugsFromRefs`.
613
+ *
614
+ * `isExtraRef` refs are EXCLUDED: an extra renders through the extras path with
615
+ * its own body line, so letting a mention also bind one would double-emit prose.
616
+ *
617
+ * Grammar-invalid slugs are DROPPED (see `MENTION_SLUG_PATTERN`) — a ref named
618
+ * "3D Render" slugs to the non-empty but unparseable `"3d-render"`, and admitting
619
+ * it would put a slug in the set that no token can ever match.
620
+ *
621
+ * All four of those gates live in `imageMentionSlugForRef`, which the hybrid
622
+ * resolver's own lookup map uses too — one predicate, so the two views cannot
623
+ * drift apart.
624
+ */
625
+ declare function knownImageSlugsFromRefs(refs: readonly ConnectedReference[]): string[];
626
+
627
+ /**
628
+ * Wired-entity `@-mention` parser — `@<name-slug>:<index>[:<role>][~lock|~nolock]`
629
+ * for `wired-creature` and `wired-object` references.
630
+ *
631
+ * THE BUG THIS KILLS. Before this leg, creatures and objects were the only wired
632
+ * sources with NO mention grammar. A user writing "Nessie rises from the lake"
633
+ * with a creature node wired in got the creature's NAME as plain prose while its
634
+ * binding dangled as a trailing "the creature from reference image D" line after
635
+ * the style hints — two disconnected halves of one intent, which is exactly the
636
+ * failure mode mentions exist to remove. With a mention, the binding renders
637
+ * INLINE at the typed position and the trailing canonical fallback for that ref
638
+ * is suppressed.
639
+ *
640
+ * @nessie:4 — bare mention; the source-default role phrase
641
+ * ("the creature from reference image D")
642
+ * @nessie:4:markings — role phrase ("the markings from reference image D")
643
+ * @chair:2:material — objects use the `wired-object` presets
644
+ * @nessie:4:my-custom-role — custom roles pass through verbatim
645
+ * @nessie:4~lock — additive identity-lock sentinel (also `~nolock`)
646
+ * @nessie:4:a:b — NULL. A 4-part token is never an entity mention.
647
+ *
648
+ * GRAMMAR CORE. Identical grammar to the named-image mention, so the slug shape,
649
+ * the parser and the finder (with BOTH collision guards — the 4-part trailing
650
+ * reject and the location slash guard) are the SHARED `mention-token-grammar.ts`,
651
+ * not a second hand-copied edition. This module is the ENTITY view of that core:
652
+ * the field names, and the part that genuinely differs — WHICH refs contribute a
653
+ * slug.
654
+ *
655
+ * PRECEDENCE, across all five kinds:
656
+ *
657
+ * character → location → image → creature → object
658
+ *
659
+ * Enforced by RESOLUTION ORDER in `buildImagePrompt`'s Phase 0, not by anything
660
+ * in this file: each pass splices its matched tokens out of the prompt before the
661
+ * next pass runs its finder, so a slug claimed by an earlier kind never reaches a
662
+ * later pass. A name shared by a character and a creature resolves as the
663
+ * CHARACTER, and the creature token never fires. The creature-before-object half
664
+ * of the tail is enforced inside the single entity pass, whose slug → ref map is
665
+ * built creature-first (see `resolveEntityMentionsHybrid`).
666
+ *
667
+ * NO WIRE FIELD, matching the image grammar and unlike `characterSlug` /
668
+ * `locationSlug`: the slug is DERIVED from `defaultName` at resolve time
669
+ * (`knownEntitySlugsFromRefs`), so a client cannot drift from the grammar and the
670
+ * reference schema is untouched.
671
+ *
672
+ * NO LEGACY RESOLVER — the image-grammar precedent. Only the hybrid reference
673
+ * format resolves these tokens; under the legacy format an `@name:N` token stays
674
+ * literal text and the entity auto-attaches with its trailing canonical phrase
675
+ * exactly as it does today. Legacy assembly has no inline role-phrase machinery
676
+ * at all (its object/creature rendering is the numbered-directive block), so
677
+ * there is no clean seam to add one and no consumer asking for it.
678
+ */
679
+
680
+ /**
681
+ * Slugify a wired entity's display name for `@`-mention tokens. Byte-identical
682
+ * algorithm to `characterMentionSlug` / `imageMentionSlug`; kept as a separate
683
+ * export to make the call site's intent explicit.
684
+ */
685
+ declare function entityMentionSlug(name: string): string;
686
+ interface EntityMentionTokenInfo {
687
+ /** The matched token text, verbatim — spliced out of the prompt at resolve time. */
688
+ readonly token: string;
689
+ readonly entitySlug: string;
690
+ /**
691
+ * 1-based correlation index assigned at insertion by the autocomplete
692
+ * (`nextMentionIndex` = max(existing N) + 1, unified across every mention
693
+ * kind). The hybrid resolver binds by its own numbering walk, so the index is
694
+ * CORRELATION ONLY — it is never echoed into the prompt.
695
+ */
696
+ readonly entityIndex: number;
697
+ /**
698
+ * Per-mention ROLE from the 3rd segment (`@nessie:4:markings`) — curated
699
+ * (`REFERENCE_ROLE_PRESETS["wired-creature"]` / `["wired-object"]`) or custom,
700
+ * stored VERBATIM. Both preset lists are entirely single-word, so this never
701
+ * needs `normalizeRoleSlug` (the location-only remapping for multi-word
702
+ * presets). OMITTED (undefined, never null) for 2-part tokens.
703
+ */
704
+ readonly role?: string;
705
+ /**
706
+ * Additive `~lock` / `~nolock` sentinel. Tri-state: `true` (force ON) |
707
+ * `false` (force OFF, suppressing a ref-level `identityLock.enabled`) |
708
+ * ABSENT/undefined (inherit the ref default). Honored only by the hybrid
709
+ * resolver — there is no legacy entity resolver to make it inert on.
710
+ */
711
+ readonly lock?: boolean;
712
+ /** Byte offset into the source prompt — used to splice the token out. */
713
+ readonly offset: number;
714
+ }
715
+ /**
716
+ * Parse a single `@<name-slug>:<index>[:<role>]` token. Returns null when the
717
+ * token doesn't match a supported shape (the caller falls back to literal text).
718
+ *
719
+ * Segment count is 2 or 3 — NOT 2–4 like the character/location parsers. A wired
720
+ * creature or object has no variant/bucket slot, so there is nothing for a 4th
721
+ * segment to mean, and claiming one would let this parser swallow a character
722
+ * token.
723
+ */
724
+ declare function parseEntityMentionToken(text: string): {
725
+ entitySlug: string;
726
+ entityIndex: number;
727
+ /** Present ONLY for a 3-part token; omitted otherwise (shape rule). */
728
+ role?: string;
729
+ /** Present ONLY when a sentinel was found; omitted otherwise (shape rule). */
730
+ lock?: boolean;
731
+ } | null;
732
+ /**
733
+ * Find every entity `@-mention` in a prompt whose slug is a known entity slug.
734
+ *
735
+ * `knownEntitySlugs` (from `knownEntitySlugsFromRefs`) is what keeps this parser
736
+ * off the other grammars' tokens — every finder matches the same `@slug:N…`
737
+ * surface and only the known-slug set separates them. Cross-kind precedence is
738
+ * additionally enforced by pass ORDER at the resolver (see the module header).
739
+ */
740
+ declare function findEntityMentionTokens(prompt: string, knownEntitySlugs: readonly string[]): EntityMentionTokenInfo[];
741
+ /**
742
+ * The mention slug a single reference contributes, or `null` when the ref cannot
743
+ * carry an entity mention at all — the SINGLE gate, so every view of "which refs
744
+ * are entity-mentionable" is the same view.
745
+ *
746
+ * Shared by `knownEntitySlugsFromRefs` (the finder's known-slug set) and the
747
+ * prompt-builder's hybrid resolver (its slug → ref lookup map). Those two must
748
+ * admit exactly the same refs: a slug the finder accepts but the resolver drops
749
+ * would splice a token with nothing to bind, and a ref the resolver keys under a
750
+ * slug no token can match is dead weight. Emptiness is NOT the gate (see
751
+ * `MENTION_SLUG_PATTERN`) — a creature named "3-Eyed Raven" slugs to the truthy
752
+ * but unparseable `"3-eyed-raven"`.
753
+ *
754
+ * `isExtraRef` refs are EXCLUDED, mirroring `imageMentionSlugForRef`: an extra
755
+ * renders through the extras path with its own body line, so letting a mention
756
+ * also bind one would double-emit prose.
757
+ */
758
+ declare function entityMentionSlugForRef(r: ConnectedReference): string | null;
759
+ /**
760
+ * The known-entity-slug set for a reference list — the SINGLE source of truth for
761
+ * the derivation, shared by `buildImagePrompt`'s Phase 0 and the backend
762
+ * orchestrator's structured-branch gate so the two can never disagree about
763
+ * whether a prompt carries a resolvable entity mention.
764
+ *
765
+ * UNFILTERED, exactly like `knownImageSlugsFromRefs` and the character/location
766
+ * slug sets: every mentionable creature/object contributes its slug regardless of
767
+ * what any OTHER kind may also claim. Cross-kind precedence is a property of the
768
+ * resolver's pass order (character → location → image → creature → object), NOT
769
+ * of this set — subtracting the earlier kinds' slugs here would put the
770
+ * precedence rule in two places and let them drift.
771
+ *
772
+ * Creature and object share ONE set (and one resolver pass): the grammar, the
773
+ * gate and the rendering are identical, and `defaultRoleForSource(r.source)`
774
+ * already tells the two apart at phrase time. Their relative precedence is
775
+ * settled where a tie can actually occur — the resolver's slug → ref map, built
776
+ * creature-first.
777
+ */
778
+ declare function knownEntitySlugsFromRefs(refs: readonly ConnectedReference[]): string[];
779
+
780
+ /**
781
+ * A bound entity (a wired Character or Location) ready to convert into a
782
+ * `ConnectedReference`. The minimal identity an app captures when a user binds
783
+ * an entity — the SLUG (and thus the resolver match) is DERIVED from `name`
784
+ * here, so callers can't drift from Nodaro's mention resolver. Apps own their
785
+ * own binding UX (chips, pickers); this is just the contract mapping.
786
+ */
787
+ interface EntityReferenceInput {
788
+ /** The entity row id. */
789
+ readonly id: string;
790
+ readonly kind: "character" | "location" | "creature" | "image";
791
+ /** Display name — the slug is derived from this. */
792
+ readonly name: string;
793
+ /** Resolved thumbnail/source URL; null/undefined → "" (placeholder-safe). */
794
+ readonly url?: string | null;
795
+ /** Variant slug (e.g. "smile", "rain"); undefined = canonical/default. */
796
+ readonly variant?: string;
797
+ /** Optional free-text descriptor (creature bindings: species/appearance) —
798
+ * folded into the auto-generated directive subject by the prompt builder. */
799
+ readonly description?: string | null;
800
+ }
801
+ /**
802
+ * Map ONE bound entity to its `ConnectedReference`. character → `wired-character`
803
+ * (slug via `characterMentionSlug`), location → `wired-location` (slug via
804
+ * `locationMentionSlug`), creature → `wired-creature` (no mention-slug machinery
805
+ * — like `wired-object`, a bound creature AUTO-ATTACHES and gets a canonical-style
806
+ * creature/animal-subject directive with zero typing; `{image:N:creature}` tokens
807
+ * also resolve against it), image → `wired-image` (a plain media reference; it
808
+ * AUTO-ATTACHES, and an `@<name-slug>:<index>[:<role>]` mention re-seats it at the
809
+ * position it was typed). Canonical-description fields are null here (a binding
810
+ * captures only name+variant; the picker/full-row path supplies descriptions).
811
+ */
812
+ declare function toConnectedReference(entity: EntityReferenceInput): ConnectedReference;
813
+ /** Batch form — `entities.map(toConnectedReference)`. */
814
+ declare function toConnectedReferences(entities: readonly EntityReferenceInput[]): ConnectedReference[];
815
+
816
+ declare const CHARACTER_ASPECT_OPTIONS: readonly ["1:1", "3:4", "16:9", "9:16"];
817
+ type CharacterAspectRatio = (typeof CHARACTER_ASPECT_OPTIONS)[number];
818
+ /**
819
+ * The asset categories with distinct natural framing. Aliases:
820
+ * - `angles` is the legacy single-surface key (now head-and-shoulders by
821
+ * default). Use `headAngles` for clarity in new code.
822
+ * - `bodyAngles` is the new full-body column added in migration 118.
823
+ */
824
+ type CharacterAssetTypeForAspect = "portrait" | "expressions" | "poses" | "angles" | "headAngles" | "bodyAngles" | "lighting" | "motions";
825
+ declare const CHARACTER_ASPECT_DEFAULTS: Record<CharacterAssetTypeForAspect, CharacterAspectRatio>;
826
+ declare function isCharacterAspectRatio(s: string): s is CharacterAspectRatio;
827
+ interface ResolveCharacterAspectOptions {
828
+ /** Explicit `aspectRatio` on the request body — highest precedence. */
829
+ readonly explicit?: string | null;
830
+ /**
831
+ * The character node's `defaultAssetAspectRatio` — set per-canvas-node via
832
+ * the 4-pill toggle on the character node. Flows through the API as
833
+ * `characterNodeAspectRatio`.
834
+ */
835
+ readonly nodeOverride?: string | null;
836
+ /** What's being generated. Drives the default when nothing else is set. */
837
+ readonly assetType: CharacterAssetTypeForAspect;
838
+ }
839
+ /**
840
+ * Resolve the final aspect ratio for a character generation request.
841
+ *
842
+ * Precedence: explicit > node override > per-asset-type default. The two
843
+ * "soft" inputs are tolerated as raw strings and only honored when they
844
+ * parse to a value in `CHARACTER_ASPECT_OPTIONS` — anything else falls
845
+ * through to the next layer (so a stale enum value doesn't poison the
846
+ * generation).
847
+ */
848
+ declare function resolveCharacterAspectRatio(opts: ResolveCharacterAspectOptions): CharacterAspectRatio;
849
+
850
+ type EntityStudioKind = "location" | "creature" | "object";
851
+ /** Provider "W:H" ratio strings (same vocabulary as the character table). */
852
+ declare const ENTITY_ASPECT_DEFAULTS: Record<EntityStudioKind, Record<string, string>>;
853
+ /**
854
+ * Resolve the provider aspect string for an entity asset generation.
855
+ * Precedence: explicit > node override > per-asset-type default > "1:1".
856
+ * The two "soft" inputs are honored only when they parse as a "W:H" ratio, so a
857
+ * stale value falls through instead of poisoning the request.
858
+ */
859
+ declare function resolveEntityAspect(opts: {
860
+ entity: EntityStudioKind;
861
+ assetType: string;
862
+ explicit?: string | null;
863
+ nodeOverride?: string | null;
864
+ }): string;
865
+ /**
866
+ * "9:16" → 0.5625 (width / height) for a CSS `aspect-ratio` fallback value.
867
+ * Anything that isn't a "W:H" ratio (or has a zero term) → 1 (square).
868
+ */
869
+ declare function aspectRatioToNumber(ratio: string): number;
870
+
871
+ type EntityKind = "character" | "object" | "location";
872
+ declare const SHEET_TYPES: readonly ["turnaround", "variation-board", "detail", "full-reference"];
873
+ type SheetType = (typeof SHEET_TYPES)[number];
874
+ declare const SHEET_SKINS: readonly ["studio", "cinematic", "blueprint", "illustrated"];
875
+ type SheetSkin = (typeof SHEET_SKINS)[number];
876
+ declare const SHEET_ASPECTS: readonly ["landscape", "square", "story"];
877
+ type SheetAspect = (typeof SHEET_ASPECTS)[number];
878
+ /** Studio sheet presets (character only). Declared here so SheetFlavour can carry
879
+ * it without a cycle (`presets.ts` re-exports it alongside the registry). */
880
+ type SheetPresetId = "studio-main" | "studio-extended";
881
+ declare const OUTPUT_FORMATS: readonly ["still", "motion"];
882
+ type OutputFormat = (typeof OUTPUT_FORMATS)[number];
883
+ declare const SECTION_KINDS: readonly ["header", "head-turnaround", "body-turnaround", "turnaround", "coverage", "expression-board", "pose-board", "material-board", "variation-board", "environment-board", "detail-board", "wardrobe-board", "palette", "scale", "notes"];
884
+ type SectionKind = (typeof SECTION_KINDS)[number];
885
+ declare const SHEET_BACKGROUNDS: readonly ["grey", "white", "transparent", "in-context"];
886
+ type SheetBackground = (typeof SHEET_BACKGROUNDS)[number];
887
+ /** A board entry is either a catalog preset (by variant) or a user-authored custom panel. */
888
+ interface PresetEntry {
889
+ kind: "preset";
890
+ variant: string;
891
+ }
892
+ interface CustomEntry {
893
+ kind: "custom";
894
+ label: string;
895
+ prompt: string;
896
+ }
897
+ type SheetEntry = PresetEntry | CustomEntry;
898
+ /** One band in the sheet. `board` disambiguates kinds that map to several buckets (environment-board). */
899
+ interface SheetSection {
900
+ kind: SectionKind;
901
+ board?: string;
902
+ subtitle?: string;
903
+ panelCount?: number;
904
+ entries?: SheetEntry[];
905
+ }
906
+ interface SheetFlavour {
907
+ outputFormat: OutputFormat;
908
+ withText: boolean;
909
+ showLabels: boolean;
910
+ aspect: SheetAspect;
911
+ background: SheetBackground;
912
+ sections?: SheetSection[];
913
+ presetId?: SheetPresetId;
914
+ }
915
+ /** A single panel the planner says must exist (reused or generated). */
916
+ interface PanelRequest {
917
+ section: SectionKind;
918
+ board: string;
919
+ variant: string;
920
+ label: string;
921
+ custom: boolean;
922
+ prompt?: string;
923
+ }
924
+ interface Swatch {
925
+ hex: string;
926
+ label: string;
927
+ }
928
+ interface PanelSource {
929
+ board: string;
930
+ variant: string;
931
+ assetId?: string;
932
+ url: string;
933
+ }
934
+ interface SheetTextData {
935
+ title?: string;
936
+ metadata?: Record<string, string>;
937
+ notes?: string;
938
+ sectionLabels?: Record<string, string>;
939
+ }
940
+ interface ReferenceSheet {
941
+ id: string;
942
+ type: SheetType;
943
+ skin: SheetSkin;
944
+ flavour: SheetFlavour;
945
+ source: "studio" | "node";
946
+ url: string;
947
+ panelUrls: string[];
948
+ panelSources: PanelSource[];
949
+ sectionsSnapshot: SheetSection[];
950
+ metadataSnapshot: SheetTextData;
951
+ paletteSnapshot: Swatch[];
952
+ sourceImageUrlAtGen: string;
953
+ createdAt: string;
954
+ }
955
+ /** Hard ceilings (also re-asserted in the route Zod schema, Plan 04). */
956
+ declare const MAX_PANELS_PER_SHEET = 24;
957
+ declare const MAX_CUSTOM_ENTRIES_PER_BOARD = 12;
958
+
959
+ /** Starter presets for the NEW close-up bucket (per entity). Custom entries override. */
960
+ declare const DETAIL_VARIANTS: Record<EntityKind, readonly string[]>;
961
+ /** Starter presets for the NEW wardrobe bucket (character only). Custom entries override. */
962
+ declare const WARDROBE_VARIANTS: readonly ["base look", "alternate look", "sporty"];
963
+ /** Logical board → ordered canonical variants, per entity. Character/object/location
964
+ * pull from the SoT lists; detail/wardrobe are the new buckets. */
965
+ declare const BOARD_VARIANTS: Record<EntityKind, Record<string, readonly string[]>>;
966
+ /** Section kinds that NEVER produce panels (chrome/text bands). The single
967
+ * source of truth for "structural" — the planner uses this to decide whether a
968
+ * section with no resolvable board is intentionally panel-less (these) or a
969
+ * misconfiguration (e.g. `environment-board` with no explicit `board`, which
970
+ * must throw, not silently yield zero panels). */
971
+ declare const STRUCTURAL_SECTIONS: Set<"notes" | "scale" | "coverage" | "turnaround" | "variation-board" | "header" | "head-turnaround" | "body-turnaround" | "expression-board" | "pose-board" | "material-board" | "environment-board" | "detail-board" | "wardrobe-board" | "palette">;
972
+ /** Default board for each board-typed section kind. `null` = no default board.
973
+ * For the four structural kinds (`STRUCTURAL_SECTIONS`) that means "no panels".
974
+ * For `environment-board` it means "ambiguous (3 buckets) — the section MUST
975
+ * carry an explicit `board`" (the planner throws if it doesn't). */
976
+ declare const SECTION_BOARD: Record<SectionKind, string | null>;
977
+ /** Sections each entity supports (catalog gate for the config picker, Plan 06). */
978
+ declare const ENTITY_SECTIONS: Record<EntityKind, readonly SectionKind[]>;
979
+ /** Preset section stacks per (entity, type). `full-reference` is the rich poster
980
+ * (YUVAL order for character); other types are single-board presets. */
981
+ declare const DEFAULT_SECTIONS: Record<EntityKind, Record<SheetType, readonly SheetSection[]>>;
982
+ /** Default number of panels drawn from a board when the section doesn't specify. */
983
+ declare const DEFAULT_PANEL_COUNT = 4;
984
+ /** Logical board key → real entity DB column (headAngles→angles,
985
+ * lighting→lighting_variations, timeOfDay→time_of_day, etc.). The worker uses
986
+ * this to find a panel's asset in the entity's JSONB buckets. */
987
+ declare const BOARD_TO_COLUMN: Record<EntityKind, Record<string, string>>;
988
+ /** Flat per-entity DB column holding motion clips ({name,url} videos). Unlike
989
+ * still panels (per-board columns via BOARD_TO_COLUMN), all of an entity's motion
990
+ * clips live in ONE column, looked up by name===variant. Used by the motion
991
+ * reference sheet to find the clip for each planned panel. */
992
+ declare const MOTION_COLUMN: Record<EntityKind, string>;
993
+ /** Logical board → the `generate-*-asset` `assetType` to use. Standard boards map
994
+ * to their own assetType; detail/wardrobe have no dedicated assetType so they go
995
+ * through `custom` (with a built userPrompt). */
996
+ declare const BOARD_TO_ASSET_TYPE: Record<EntityKind, Record<string, string>>;
997
+
998
+ /**
999
+ * Pure: given an entity kind, an ordered section list, and the flavour, return the
1000
+ * ordered panels the sheet needs. Reuse-vs-generate and pricing happen later
1001
+ * (Plan 04) — this only says WHAT panels must exist. Throws on bad config so the
1002
+ * route can 400 before any paid work.
1003
+ */
1004
+ declare function planSheetPanels(entityKind: EntityKind, sections: readonly SheetSection[], _flavour: SheetFlavour): PanelRequest[];
1005
+
1006
+ /** Build the `userPrompt` for a detail/wardrobe panel generated via the
1007
+ * `custom` assetType (these boards have no dedicated backend assetType). */
1008
+ declare function buildPanelPrompt(entityKind: EntityKind, board: string, variant: string, name: string): string;
1009
+
1010
+ /**
1011
+ * The section stack to actually compose for a sheet. The Studio "Sheet" tab
1012
+ * sends an explicit, user-chosen stack in `flavour.sections`; the canvas node,
1013
+ * workflow runs, and API/MCP callers send only `type`, so fall back to the
1014
+ * default stack for (entityKind, type). Always returns a fresh, mutable clone so
1015
+ * neither the caller nor the shared `DEFAULT_SECTIONS` constant is mutated.
1016
+ *
1017
+ * Single source of truth for "type → sections" — without this fallback a node
1018
+ * sheet composes with zero bands (a blank image). Every (entityKind, type) has a
1019
+ * non-empty default stack (guarded by the catalog invariant test).
1020
+ */
1021
+ declare function resolveSheetSections(entityKind: EntityKind, type: SheetType, sections?: readonly SheetSection[]): SheetSection[];
1022
+ /** A `generate-*-asset` request for one missing panel. */
1023
+ interface PanelGenRequest {
1024
+ assetType: string;
1025
+ variant: string;
1026
+ attachToColumn: string;
1027
+ attachName: string;
1028
+ userPrompt?: string;
1029
+ }
1030
+ interface SheetGenerationPlan {
1031
+ presentUrls: string[];
1032
+ missing: PanelGenRequest[];
1033
+ }
1034
+ /** Find the bucket item whose `name` equals `variant` and which carries a
1035
+ * non-empty `url` (single source of truth — the same predicate the still + motion
1036
+ * panel resolvers use to locate a planned panel in an entity's buckets). */
1037
+ declare function matchVariant(items: ReadonlyArray<{
1038
+ name?: string;
1039
+ url?: string;
1040
+ }>, variant: string): {
1041
+ name?: string;
1042
+ url?: string;
1043
+ } | undefined;
1044
+ /** Pure: given the entity's current buckets (keyed by DB column), split the
1045
+ * planned panels into already-present URLs and the generate-requests needed for
1046
+ * the rest. The surface fires each request, awaits, then calls the compose API. */
1047
+ declare function planSheetGeneration(entityKind: EntityKind, sections: readonly SheetSection[], flavour: SheetFlavour, bucketsByColumn: Record<string, ReadonlyArray<{
1048
+ name?: string;
1049
+ url?: string;
1050
+ }> | undefined>, name: string): SheetGenerationPlan;
1051
+
1052
+ /** The credit identifier for a sheet by output format (single source of truth —
1053
+ * mirrors resolveCinematicCreditId). Used by the route guard, the orchestrator
1054
+ * payload-builder, and the node's credit display. */
1055
+ declare function referenceSheetCreditId(flavour: {
1056
+ outputFormat?: OutputFormat | string;
1057
+ } | undefined): string;
1058
+
1059
+ /** Build ordered preset entries from a variant list (a curated board subset). */
1060
+ declare const presetEntries: (vs: readonly string[]) => SheetEntry[];
1061
+ interface SheetPreset {
1062
+ id: SheetPresetId;
1063
+ label: string;
1064
+ description: string;
1065
+ /** Carrier for the route's required `type` enum; the layout comes from `baseSections`. */
1066
+ type: SheetType;
1067
+ baseSections: SheetSection[];
1068
+ skin: SheetSkin;
1069
+ aspect: SheetAspect;
1070
+ }
1071
+ /**
1072
+ * Studio sheet presets (character only). Each bundles a curated head+body
1073
+ * turnaround (via `entries`) + a default skin/aspect + a carrier `type`. The
1074
+ * à-la-carte boards below layer optional extra bands on top.
1075
+ *
1076
+ * `studio-main` is the clean screenshot format (head: front, profiles, back-of-
1077
+ * head; body: front, side, back). `studio-extended` adds above/below + 3/4
1078
+ * angles for fuller coverage.
1079
+ */
1080
+ declare const SHEET_PRESETS: readonly SheetPreset[];
1081
+ declare const PRESET_LABELS: Record<SheetPresetId, string>;
1082
+ interface AlaCarteBoard {
1083
+ id: string;
1084
+ label: string;
1085
+ /** UI hint: panels this board adds (the board's default slice). Free boards are 0. */
1086
+ panelCount: number;
1087
+ section: SheetSection;
1088
+ }
1089
+ /** Optional boards layered on a base preset. No `entries` → the planner uses the
1090
+ * board's default slice (`min(4, board length)`). Palette is structural (free). */
1091
+ declare const ALA_CARTE_BOARDS: readonly AlaCarteBoard[];
1092
+
1093
+ interface SheetCostEstimate {
1094
+ present: number;
1095
+ missing: PanelGenRequest[];
1096
+ prepareCost: number;
1097
+ assemblyCost: number;
1098
+ total: number;
1099
+ /** True when the plan exceeds MAX_PANELS_PER_SHEET (planSheetPanels throws). */
1100
+ overflow: boolean;
1101
+ }
1102
+ /**
1103
+ * Pure cost estimate for a sheet plan. Wraps `planSheetGeneration` so a
1104
+ * MAX_PANELS overflow (which throws in the planner) becomes `overflow:true`
1105
+ * instead of crashing the caller's render. `perPanelCost`/`assemblyCost` are
1106
+ * injected by the UI (constants from the adapter) so the shared layer stays
1107
+ * pricing-agnostic.
1108
+ */
1109
+ declare function estimateSheetCost(entityKind: EntityKind, sections: readonly SheetSection[], flavour: SheetFlavour, buckets: Record<string, ReadonlyArray<{
1110
+ name?: string;
1111
+ url?: string;
1112
+ }> | undefined>, name: string, perPanelCost: number, assemblyCost: number): SheetCostEstimate;
1113
+
1114
+ /** Gen providers for the board: strict subset of IMAGE_GEN_PROVIDERS that
1115
+ * renders legible in-image text + accepts reference conditioning. */
1116
+ declare const REFERENCE_BOARD_PROVIDERS: readonly ["nano-banana-pro", "gpt-image-2", "gpt-image-2-5-flare", "gpt-image-2-5-sunburst"];
1117
+ type ReferenceBoardProvider = (typeof REFERENCE_BOARD_PROVIDERS)[number];
1118
+ type BoardEntityKind = "character" | "location" | "object";
1119
+ interface BoardTemplate {
1120
+ /** "<entityKind>/<slug>" */
1121
+ readonly id: string;
1122
+ readonly entityKind: BoardEntityKind;
1123
+ readonly label: string;
1124
+ readonly build: (ctx: BoardPromptContext) => string;
1125
+ }
1126
+ /** Optional metadata the resolver supplies from a connected entity. All
1127
+ * optional — the prompt degrades gracefully (omits labels) when absent. */
1128
+ interface BoardPromptContext {
1129
+ readonly name?: string;
1130
+ readonly description?: string;
1131
+ }
1132
+ declare const REFERENCE_BOARD_TEMPLATES: readonly BoardTemplate[];
1133
+ declare function listBoardTemplates(kind: BoardEntityKind): BoardTemplate[];
1134
+ declare function buildBoardPrompt(templateId: string, ctx: BoardPromptContext): string;
1135
+
1136
+ /**
1137
+ * Entity node types that expose a plain `image` source handle (emitting the
1138
+ * portrait URL) in addition to their identity `*Ref` handle. When a wire leaves
1139
+ * the `image` handle, the entity is treated as a plain image PRODUCER
1140
+ * (substituted to "upload-image") so it reaches image inputs and lists exactly
1141
+ * like generate-image / upload-image, while the `*Ref` handle stays identity.
1142
+ *
1143
+ * SINGLE SOURCE OF TRUTH — consumed by:
1144
+ * - frontend connection validation (drop validator, drag-glow, popover),
1145
+ * - frontend run assemblers (execute-node, video-prompt-assembly),
1146
+ * - frontend config-panel reference preview builders,
1147
+ * - backend payload-builder identity-injection guards.
1148
+ * Add future per-handle output-type remaps HERE so every surface inherits them.
1149
+ */
1150
+ declare const ENTITY_IMAGE_HANDLE_TYPES: ReadonlySet<string>;
1151
+ /**
1152
+ * Aggregate node types (Group / Collect) whose source handles are typed LANES
1153
+ * — `out-text` / `out-image` / `out-video` / `out-audio` — each emitting that
1154
+ * media type. Like an entity's `image` handle, a wire leaving a lane is a plain
1155
+ * producer of that lane's type, so it must reach the typed inputs of every
1156
+ * consumer (Image Collage, Combine Videos, Merge Lists, prompts, …) exactly as
1157
+ * an upload node of that type would. Neither node type is in any producer set
1158
+ * itself: the NODE emits nothing, its LANES do.
1159
+ */
1160
+ declare const AGGREGATE_LANE_SOURCE_TYPES: ReadonlySet<string>;
1161
+ /**
1162
+ * Output pips that emit a plain medium although their node is no producer of
1163
+ * it: node type → pip → the canonical single-media producer the pip behaves
1164
+ * as. A row here is NOT an identity remap (`ENTITY_IMAGE_HANDLE_TYPES`, which
1165
+ * the identity gates and `sourceRefKey` read) and adds the node to no producer
1166
+ * set: only a wire leaving THIS pip is that producer, so the node's other pips
1167
+ * (UGC Creator's `creator` record) stay what they are. A frontend guard holds
1168
+ * every row to a declared output drawn in that medium's colour.
1169
+ *
1170
+ * Both engines' input resolvers route a wire leaving one of these pips as the
1171
+ * producer it names, and the editor's validators judge it the same way. A
1172
+ * UGC wire input (a pip that reads one output of one UGC node) still judges
1173
+ * the RAW node and pip, so a text pip keeps feeding the UGC input made for it.
1174
+ */
1175
+ declare const OUTPUT_PIP_EFFECTIVE_TYPES: Readonly<Record<string, Readonly<Record<string, string>>>>;
1176
+ /**
1177
+ * The source type a legacy-handle classifier judges an edge by: the raw node
1178
+ * type, unless the edge leaves an `OUTPUT_PIP_EFFECTIVE_TYPES` pip. Only that
1179
+ * table: the entity, aggregate and scraper remaps of `resolveEffectiveSourceType`
1180
+ * keep the classifiers' rewiring of existing graphs as it was. Read by the
1181
+ * editor's load-time pass and the server's write-time normalizer alike.
1182
+ */
1183
+ declare function outputPipSourceType(rawSourceType: string | undefined | null, sourceHandleId: string | undefined | null): string;
1184
+ /**
1185
+ * The effective output TYPE a given source handle emits. Returns the raw node
1186
+ * type for every `(type, handle)` pair EXCEPT:
1187
+ * - an entity `image` handle → `"upload-image"` (a plain image producer);
1188
+ * - an aggregate (group / collect) lane handle → the plain producer of that
1189
+ * lane's media type (see AGGREGATE_LANE_EFFECTIVE_TYPE);
1190
+ * - a Meta Ads `text` / `image` / `video` handle → the plain producer of
1191
+ * that type (see META_ADS_HANDLE_EFFECTIVE_TYPE); its `json` handle keeps
1192
+ * the raw type;
1193
+ * - an `OUTPUT_PIP_EFFECTIVE_TYPES` pip → the producer its row names.
1194
+ * Pure — safe for both frontend and backend.
1195
+ */
1196
+ declare function resolveEffectiveSourceType(rawSourceType: string | undefined | null, sourceHandleId: string | undefined | null): string;
1197
+ /**
1198
+ * The ref-assembly map key (and `ConnectedReference.id`) for a wired source.
1199
+ *
1200
+ * An entity's `image` handle emits a plain image that is DISTINCT from the
1201
+ * entity's identity `*Ref` handle, yet both edges carry the SAME source node
1202
+ * id. Every ref-assembly map that keyed by the bare node id therefore had the
1203
+ * two edges collide — silently dropping one (identity → a literal `@abi:N`
1204
+ * token + lost character, or the plain image → missing from the picker),
1205
+ * non-deterministically by edge order. Scoping the entity-`image`-handle ref to
1206
+ * `${nodeId}::image` keeps the two refs distinct so BOTH survive. Every other
1207
+ * (type, handle) keeps the bare node id, so nothing else changes.
1208
+ */
1209
+ declare function sourceRefKey(nodeId: string, sourceHandleId: string | undefined | null, rawSourceType: string | undefined | null): string;
1210
+
1211
+ /**
1212
+ * Per-source ORDERED preset role ids (most-useful first) for the editor's role
1213
+ * menu. The single source of truth for the curated vocabulary — every menu and
1214
+ * the resolver read from here. `Custom…` (free-form) is added by the UI, not
1215
+ * listed here. Each list MUST contain the source's `DEFAULT_LABEL_BY_SOURCE`
1216
+ * value (guarded by reference-roles.test.ts).
1217
+ */
1218
+ declare const REFERENCE_ROLE_PRESETS: Record<ReferenceSource, readonly string[]>;
1219
+ /** Canonical default role for a source — the value the editor pre-fills and the
1220
+ * resolver falls back to. Aliased to `DEFAULT_LABEL_BY_SOURCE` so the two never
1221
+ * drift. */
1222
+ declare function defaultRoleForSource(source: ReferenceSource): string;
1223
+ /**
1224
+ * Render the inline reference phrase. `binding` is the caller-formatted slot
1225
+ * string: `"reference image A"` (image, lettered) or `"@image_3"` (video).
1226
+ * Most roles are nouns and slot into the default template; the two non-noun
1227
+ * specials get a hand-tuned phrasing so the prompt reads naturally.
1228
+ */
1229
+ declare function roleToPhrase(role: string, binding: string): string;
1230
+ /**
1231
+ * Map a location role SLUG — as it appears in a `@location:N:<slug>` mention
1232
+ * token (lowercase, dash-joined, no spaces) — back to its canonical phrase key
1233
+ * so `roleToPhrase` matches the non-noun specials. Only the multi-word
1234
+ * `wired-location` presets need remapping (`empty-background` → `empty
1235
+ * background`); single-token roles and `as-is` (whose phrase key keeps the
1236
+ * hyphen) and free-form custom slugs pass through unchanged.
1237
+ *
1238
+ * Data-driven from `REFERENCE_ROLE_PRESETS["wired-location"]` (the single source
1239
+ * of truth for the location vocabulary): a preset whose space→dash slug equals
1240
+ * `slug` maps back to the preset's phrase form, so a future multi-word preset is
1241
+ * handled with no extra wiring. Mention tokens are slug-form (the grammar
1242
+ * segment is `[a-z][a-z0-9-]*`), so the role is stored verbatim on the token and
1243
+ * normalized HERE at the consumption points — the location mention resolver
1244
+ * (before `roleToPhrase`) and the location role pill (display label). The
1245
+ * character side never needs this: character role slugs are single tokens that
1246
+ * already equal their phrase key.
1247
+ */
1248
+ declare function normalizeRoleSlug(slug: string): string;
1249
+ /**
1250
+ * Role for a FIRST-SIGHT character extra-ref in HYBRID assembly. The `segment`
1251
+ * is the role when it is a curated preset for `source`; otherwise the source
1252
+ * default. This mirrors the segment→role preset gate the mention-hybrid paths
1253
+ * use, minus their custom-role-survival relaxation (an extra has no parsed
1254
+ * `usageMode == null` signal to tell a role from a variant pick).
1255
+ *
1256
+ * Shared by BOTH the image (`renderExtraRefsHybrid` in `prompt-builder.ts`) and
1257
+ * video (`resolveVideoReferenceCore` extras first-sight in
1258
+ * `video-reference-resolver.ts`) resolvers — and, as of the Reference Roles
1259
+ * deferred-follow-up, they share the HELPER **and** its INPUT, so they are
1260
+ * fully converged:
1261
+ * - image passes the COALESCED `defaultUsageMode`
1262
+ * (`usageMode` → char-node default → "identical", folded by
1263
+ * `expandExtraRefsToConnectedReferences`).
1264
+ * - video passes its COALESCED `effectiveMode`
1265
+ * (`ex.usageMode` → char-node default (`lookupCharacterBySlug`) →
1266
+ * "identical") — the identical resolution chain, already computed for the
1267
+ * legacy directive path.
1268
+ * Both are always defined for a real character extra, so no `variantSlug`
1269
+ * fallback is needed on either side. A character whose node default is
1270
+ * Face/Pose/Style now resolves an un-overridden extra to that default on BOTH
1271
+ * image and video (and consistently with the video legacy path). The single
1272
+ * source of truth for the coalescing is the per-ref override → char-node
1273
+ * default → "identical" chain, applied at both call sites.
1274
+ */
1275
+ declare function firstSightExtraRole(segment: string | null | undefined, source: ReferenceSource): string;
1276
+ /**
1277
+ * The effective default role for a wired entity, given the node's explicit
1278
+ * hybrid `defaultRole` and its legacy `defaultUsageMode`. Single source of truth
1279
+ * for the node-default precedence, read at every hybrid resolver site (image +
1280
+ * video × extras / canonical / mention):
1281
+ *
1282
+ * 1. `defaultRole` (the hybrid dropdown pick) — used VERBATIM when non-blank,
1283
+ * so a Custom role like `earrings` survives (mirrors the pill's Custom
1284
+ * relaxation) and beats any legacy `defaultUsageMode`.
1285
+ * 2. else `firstSightExtraRole(defaultUsageMode, source)` — the back-compat
1286
+ * mapping (`face`/`pose`/`style` pass through; every other usage mode, and
1287
+ * an absent one, collapse to the source default, e.g. `"person"`).
1288
+ *
1289
+ * A per-mention token role (the pill / autocomplete) still wins over this at the
1290
+ * mention call sites; this is only the NODE-level fallback.
1291
+ */
1292
+ declare function resolveDefaultRole(defaultRole: string | null | undefined, defaultUsageMode: string | null | undefined, source: ReferenceSource): string;
1293
+ /**
1294
+ * Sanitize a free-form Custom role into a character-variant-slug-safe token.
1295
+ * Hoisted to shared (was `config-panels/prompt-editor/character-ref-roles.ts`)
1296
+ * so BOTH the mention pill and the character node's role dropdown share one
1297
+ * source of truth. Grammar is `[a-z][a-z0-9-]*` (the `variantSlug` token slot):
1298
+ * lower-case, dash-join whitespace, drop out-of-grammar chars, force a leading
1299
+ * letter, cap at 32, collapse dash runs, drop a trailing dash — keeping the
1300
+ * emitted role re-parseable and matching `characterMentionSlug`'s slugification.
1301
+ */
1302
+ declare function sanitizeRole(raw: string): string;
1303
+
1304
+ /**
1305
+ * Which DB columns of a saved entity land on its canvas node, per kind.
1306
+ *
1307
+ * Four surfaces copy an entity row onto a node: the browser's load-time
1308
+ * hydrator, the browser's library picker, the backend's run-time hydration, and
1309
+ * (indirectly) anything that reads a node expecting those fields to be there.
1310
+ * They used to be four hand-written lists, and they drifted exactly as you would
1311
+ * expect — the load-time hydrator covers `character` and nothing else, so an
1312
+ * object node bound by an agent stays media-less until someone rebinds it by
1313
+ * hand.
1314
+ *
1315
+ * This is the field NAMES only — the structural vocabulary. Merge behaviour
1316
+ * (defaults, `prev` fallbacks, type narrowing) stays with each caller, because
1317
+ * a browser node and a server row disagree about nulls and it is not worth
1318
+ * pretending otherwise.
1319
+ */
1320
+ /**
1321
+ * Every entity kind, in the order surfaces present them.
1322
+ *
1323
+ * The list is the invariant: `Record<EntityNodeKind, …>` makes the compiler
1324
+ * find every table below, every per-kind UI row in the `@` picker, and the
1325
+ * picker’s kind→query map. What the compiler cannot see — that the MCP read
1326
+ * tools for a kind exist and are reachable — is pinned by a test instead.
1327
+ *
1328
+ * Tool names are derivable from it too: `list_<kind>s` / `get_<kind>`.
1329
+ */
1330
+ declare const ENTITY_NODE_KINDS: readonly ["character", "object", "creature", "location"];
1331
+ type EntityNodeKind = (typeof ENTITY_NODE_KINDS)[number];
1332
+ /** The `data.*DbId` field that binds each entity node to its row. */
1333
+ declare const ENTITY_DB_ID_FIELD: Record<EntityNodeKind, string>;
1334
+ /** The `data.*Name` field each kind stores its display name under. */
1335
+ declare const ENTITY_NAME_FIELD: Record<EntityNodeKind, string>;
1336
+ /** Postgres table per kind. */
1337
+ declare const ENTITY_TABLE: Record<EntityNodeKind, string>;
1338
+ /**
1339
+ * `{name,url}[]` buckets per kind, as `[db_column, nodeField]`.
1340
+ *
1341
+ * These are what a generation actually consumes — the variant a prompt
1342
+ * `@mentions`, the extra references a user attaches. A node missing them is not
1343
+ * visibly broken; it just quietly generates the wrong picture.
1344
+ */
1345
+ declare const ENTITY_BUCKET_FIELDS: Record<EntityNodeKind, ReadonlyArray<readonly [string, string]>>;
1346
+ /**
1347
+ * Scalars every kind shares, as `[db_column, nodeField]`.
1348
+ *
1349
+ * `source_image_url` is the load-bearing one: the run engine reads
1350
+ * `defaultAssetUrl || sourceImageUrl` and SKIPS the reference entirely when
1351
+ * both are empty — no error, no warning, just a generation of the wrong
1352
+ * person. A node with an id but no image is the shape an agent produces.
1353
+ */
1354
+ declare const ENTITY_SCALAR_FIELDS: ReadonlyArray<readonly [string, string]>;
1355
+ /**
1356
+ * Scalars only SOME kinds have.
1357
+ *
1358
+ * `style_lock` looks shared and is not: characters never grew the column,
1359
+ * because a character's likeness is the lock. Selecting it from `characters`
1360
+ * anyway is a PostgREST error, which the run-time hydrator swallows by design
1361
+ * — so the whole kind would quietly stop hydrating and every test that mocks
1362
+ * the database would still pass. That is why the column lists are checked
1363
+ * against the migrations by `entity-hydration-columns.test.ts`.
1364
+ */
1365
+ declare const ENTITY_KIND_SCALAR_FIELDS: Record<EntityNodeKind, ReadonlyArray<readonly [string, string]>>;
1366
+ /** Every DB column a full hydration of `kind` reads. */
1367
+ declare function entityHydrationColumns(kind: EntityNodeKind): string[];
1368
+ /** Every scalar `kind` actually has, shared plus its own. */
1369
+ declare function entityScalarFields(kind: EntityNodeKind): ReadonlyArray<readonly [string, string]>;
1370
+
1371
+ export { AGGREGATE_LANE_SOURCE_TYPES, ALA_CARTE_BOARDS, type AlaCarteBoard, BOARD_TO_ASSET_TYPE, BOARD_TO_COLUMN, BOARD_VARIANTS, type BoardEntityKind, type BoardPromptContext, type BoardTemplate, CHARACTER_ASPECT_DEFAULTS, CHARACTER_ASPECT_OPTIONS, CHARACTER_PICKER_DISPLAY_ORDER, CHARACTER_VARIANT_ASSET_BUCKETS, type CharacterAspectRatio, type CharacterAssetTypeForAspect, type CharacterMentionTokenInfo, type CharacterVariantAssetBucket, type CharacterVariantAssetItem, type CustomEntry, DEFAULT_CARRIED_FRACTION, DEFAULT_LOCATION_USAGE_MODE, DEFAULT_PANEL_COUNT, DEFAULT_SECTIONS, DETAIL_VARIANTS, ENTITY_ASPECT_DEFAULTS, ENTITY_BUCKET_FIELDS, ENTITY_DB_ID_FIELD, ENTITY_IMAGE_HANDLE_TYPES, ENTITY_KIND_SCALAR_FIELDS, ENTITY_NAME_FIELD, ENTITY_NODE_KINDS, ENTITY_SCALAR_FIELDS, ENTITY_SECTIONS, ENTITY_TABLE, type EntityKind, type EntityMentionTokenInfo, type EntityNodeKind, type EntityReferenceInput, type EntityStudioKind, type ExtraRefCharacterContext, type ExtraRefInput, FEATURED_ENTITIES, type FeaturedEntity, IMAGE_REF_TYPES, type ImageMentionTokenInfo, LOCATION_USAGE_MODES, type LocationMentionTokenInfo, type LocationUsageMode, MAX_CUSTOM_ENTRIES_PER_BOARD, MAX_PANELS_PER_SHEET, MOTION_COLUMN, OBJECT_ASPECT_DEFAULTS, OBJECT_ASPECT_OPTIONS, OUTPUT_FORMATS, OUTPUT_PIP_EFFECTIVE_TYPES, type ObjectAspectRatio, type ObjectAssetTypeForAspect, type OutputFormat, PASSTHROUGH_TYPES, PRESET_LABELS, type PanelGenRequest, type PanelRequest, type PanelSource, type PresetEntry, REFERENCE_BOARD_PROVIDERS, REFERENCE_BOARD_TEMPLATES, REFERENCE_ROLE_PRESETS, type ReferenceBoardProvider, type ReferenceSheet, type ResolveCharacterAspectOptions, type ResolveObjectAspectOptions, SECTION_BOARD, SECTION_KINDS, SHEET_ASPECTS, SHEET_BACKGROUNDS, SHEET_PRESETS, SHEET_SKINS, SHEET_TYPES, STRUCTURAL_SECTIONS, SURROUND_DIRECTIONS, type SectionKind, type SheetAspect, type SheetBackground, type SheetCostEstimate, type SheetEntry, type SheetFlavour, type SheetGenerationPlan, type SheetPreset, type SheetPresetId, type SheetSection, type SheetSkin, type SheetTextData, type SheetType, type SurroundDirection, type Swatch, TILT_CARRIED_FRACTION, UsageMode, WARDROBE_VARIANTS, aspectRatioToNumber, buildBoardPrompt, buildPanelPrompt, characterBoardItems, characterBucketDisplayRank, characterMentionSlug, characterMentionableAssetArrays, characterSheetRefItems, characterVariantAssetArrays, collectAncestorRefs, defaultCarriedFraction, defaultRoleForSource, entityHydrationColumns, entityMentionSlug, entityMentionSlugForRef, entityScalarFields, estimateSheetCost, expandExtraRefsToConnectedReferences, findCharacterMentionTokens, findEntityMentionTokens, findImageMentionTokens, findLocationMentionTokens, firstSightExtraRole, getFeaturedEntities, imageMentionSlug, imageMentionSlugForRef, isCharacterAspectRatio, isLocationUsageMode, isObjectAspectRatio, isTiltDirection, knownEntitySlugsFromRefs, knownImageSlugsFromRefs, listBoardTemplates, locationMentionSlug, locationUsageModeLabel, matchVariant, normalizeRoleSlug, outputPipSourceType, parseCharacterMentionToken, parseEntityMentionToken, parseImageMentionToken, parseLocationMentionToken, planSheetGeneration, planSheetPanels, presetEntries, referenceSheetCreditId, resolveCharacterAspectRatio, resolveDefaultRole, resolveEffectiveSourceType, resolveEntityAspect, resolveObjectAspectRatio, resolveSheetSections, roleToPhrase, sanitizeRole, sortCharacterEntriesForDisplay, sourceRefKey, toConnectedReference, toConnectedReferences };