create-threenative 0.2.3 → 0.2.5

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 (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -0,0 +1,705 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { createHash, randomUUID } from "node:crypto";
4
+ import { open, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
5
+ import path from "node:path";
6
+
7
+ const DEFAULT_MODEL = "meta/muse-image";
8
+ const DEFAULT_ENDPOINT = "https://openrouter.ai/api/v1/chat/completions";
9
+ const MAX_IMAGE_BYTES = 32 * 1024 * 1024;
10
+ const DEFAULT_TIMEOUT_MS = 120_000;
11
+ const SCHEMA_VERSION = 1;
12
+ let activeController;
13
+
14
+ class InputError extends Error {
15
+ constructor(message) {
16
+ super(message);
17
+ this.name = "InputError";
18
+ }
19
+ }
20
+
21
+ class ProviderError extends Error {
22
+ constructor(message, metadata = {}) {
23
+ super(message);
24
+ this.name = "ProviderError";
25
+ Object.assign(this, metadata);
26
+ }
27
+ }
28
+
29
+ function fail(message) {
30
+ throw new InputError(message);
31
+ }
32
+
33
+ function sha256(bytes) {
34
+ return createHash("sha256").update(bytes).digest("hex");
35
+ }
36
+
37
+ function safeRelative(root, candidate, label) {
38
+ const resolved = path.resolve(candidate);
39
+ const relative = path.relative(root, resolved);
40
+ if (
41
+ relative === "" ||
42
+ relative === ".." ||
43
+ relative.startsWith(`..${path.sep}`) ||
44
+ path.isAbsolute(relative)
45
+ ) {
46
+ fail(`${label} escapes the declared artifact root`);
47
+ }
48
+ return resolved;
49
+ }
50
+
51
+ async function assertExistingPathInside(root, candidate, label) {
52
+ const resolved = safeRelative(root, candidate, label);
53
+ const existing = await realpath(resolved).catch(() => undefined);
54
+ if (existing !== undefined) safeRelative(root, existing, label);
55
+ else {
56
+ const parent = await realpath(path.dirname(resolved)).catch(() => undefined);
57
+ if (parent !== undefined && parent !== root) safeRelative(root, parent, label);
58
+ }
59
+ return resolved;
60
+ }
61
+
62
+ function projectRelative(projectRoot, file) {
63
+ const relative = path.relative(projectRoot, file);
64
+ if (
65
+ relative === "" ||
66
+ relative === ".." ||
67
+ relative.startsWith(`..${path.sep}`) ||
68
+ path.isAbsolute(relative)
69
+ ) {
70
+ fail("artifact path is outside projectRoot");
71
+ }
72
+ return relative.split(path.sep).join("/");
73
+ }
74
+
75
+ function parseArgs(argv) {
76
+ const values = {};
77
+ const flags = new Set([
78
+ "record",
79
+ "request-id",
80
+ "prompt-file",
81
+ "out",
82
+ "model",
83
+ "reference",
84
+ "timeout-ms",
85
+ ]);
86
+ for (let index = 0; index < argv.length; index += 1) {
87
+ const argument = argv[index];
88
+ if (argument === "--help") return { help: true };
89
+ if (!argument?.startsWith("--")) fail(`unexpected argument '${argument ?? ""}'`);
90
+ const name = argument.slice(2);
91
+ if (!flags.has(name)) fail(`unknown option '--${name}'`);
92
+ const value = argv[index + 1];
93
+ if (value === undefined || value.startsWith("--")) fail(`option '--${name}' needs a value`);
94
+ values[name] = value;
95
+ index += 1;
96
+ }
97
+ for (const name of ["record", "request-id", "prompt-file", "out"]) {
98
+ if (values[name] === undefined || values[name] === "")
99
+ fail(`missing required option '--${name}'`);
100
+ }
101
+ const timeout =
102
+ values["timeout-ms"] === undefined ? DEFAULT_TIMEOUT_MS : Number(values["timeout-ms"]);
103
+ if (!Number.isInteger(timeout) || timeout < 1 || timeout > DEFAULT_TIMEOUT_MS)
104
+ fail("timeout-ms must be an integer from 1 to 120000");
105
+ return { ...values, timeoutMs: timeout, model: values.model ?? DEFAULT_MODEL };
106
+ }
107
+
108
+ function printHelp() {
109
+ console.log(
110
+ "Usage: node scripts/reference.mjs --record RUN.json --request-id ID --prompt-file PROMPT.txt --out IMAGE [--model MODEL] [--reference IMAGE]",
111
+ );
112
+ }
113
+
114
+ function imageInfo(bytes) {
115
+ if (bytes.length < 12) return undefined;
116
+ const png = bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
117
+ if (png) {
118
+ if (
119
+ bytes.length < 33 ||
120
+ bytes.toString("ascii", 12, 16) !== "IHDR" ||
121
+ bytes.toString("ascii", bytes.length - 8, bytes.length - 4) !== "IEND"
122
+ )
123
+ return undefined;
124
+ const width = bytes.readUInt32BE(16);
125
+ const height = bytes.readUInt32BE(20);
126
+ return width > 0 && height > 0
127
+ ? { mime: "image/png", width, height, extension: ".png" }
128
+ : undefined;
129
+ }
130
+ if (
131
+ bytes.subarray(0, 6).toString("ascii") === "GIF87a" ||
132
+ bytes.subarray(0, 6).toString("ascii") === "GIF89a"
133
+ ) {
134
+ const width = bytes.readUInt16LE(6);
135
+ const height = bytes.readUInt16LE(8);
136
+ return width > 0 && height > 0
137
+ ? { mime: "image/gif", width, height, extension: ".gif" }
138
+ : undefined;
139
+ }
140
+ if (
141
+ bytes.subarray(0, 4).toString("ascii") === "RIFF" &&
142
+ bytes.subarray(8, 12).toString("ascii") === "WEBP"
143
+ ) {
144
+ return { mime: "image/webp", width: undefined, height: undefined, extension: ".webp" };
145
+ }
146
+ if (bytes[0] === 0xff && bytes[1] === 0xd8) {
147
+ let offset = 2;
148
+ while (offset + 9 < bytes.length) {
149
+ if (bytes[offset] !== 0xff) {
150
+ offset += 1;
151
+ continue;
152
+ }
153
+ const marker = bytes[offset + 1];
154
+ offset += 2;
155
+ if (marker === 0xd8 || marker === 0xd9) continue;
156
+ if (offset + 2 > bytes.length) return undefined;
157
+ const length = bytes.readUInt16BE(offset);
158
+ if (length < 2 || offset + length > bytes.length) return undefined;
159
+ if (
160
+ (marker >= 0xc0 && marker <= 0xc3) ||
161
+ (marker >= 0xc5 && marker <= 0xc7) ||
162
+ (marker >= 0xc9 && marker <= 0xcb) ||
163
+ (marker >= 0xcd && marker <= 0xcf)
164
+ ) {
165
+ const height = bytes.readUInt16BE(offset + 3);
166
+ const width = bytes.readUInt16BE(offset + 5);
167
+ return width > 0 && height > 0
168
+ ? { mime: "image/jpeg", width, height, extension: ".jpg" }
169
+ : undefined;
170
+ }
171
+ offset += length;
172
+ }
173
+ }
174
+ return undefined;
175
+ }
176
+
177
+ function validateImage(bytes, expectedExtension) {
178
+ if (bytes.length === 0 || bytes.length > MAX_IMAGE_BYTES)
179
+ fail(`image payload must be between 1 byte and ${MAX_IMAGE_BYTES} bytes`);
180
+ const info = imageInfo(bytes);
181
+ if (info === undefined) fail("provider response is not a supported raster image");
182
+ if (
183
+ expectedExtension !== undefined &&
184
+ ![info.extension, info.extension === ".jpg" ? ".jpeg" : info.extension].includes(
185
+ expectedExtension.toLowerCase(),
186
+ )
187
+ ) {
188
+ fail(`image MIME '${info.mime}' does not match output extension '${expectedExtension}'`);
189
+ }
190
+ return info;
191
+ }
192
+
193
+ function outputExtension(file) {
194
+ const extension = path.extname(file).toLowerCase();
195
+ if (![".png", ".jpg", ".jpeg", ".webp", ".gif"].includes(extension))
196
+ fail("output must use .png, .jpg, .jpeg, .webp or .gif");
197
+ return extension;
198
+ }
199
+
200
+ async function atomicWriteJson(file, value) {
201
+ const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
202
+ const handle = await open(temporary, "wx");
203
+ try {
204
+ await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
205
+ await handle.sync();
206
+ } finally {
207
+ await handle.close();
208
+ }
209
+ await rename(temporary, file);
210
+ }
211
+
212
+ async function atomicWriteBytes(file, bytes) {
213
+ const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
214
+ const handle = await open(temporary, "wx");
215
+ try {
216
+ await handle.writeFile(bytes);
217
+ await handle.sync();
218
+ } finally {
219
+ await handle.close();
220
+ }
221
+ await rename(temporary, file);
222
+ }
223
+
224
+ async function acquireLock(recordFile) {
225
+ const lockFile = `${recordFile}.lock`;
226
+ for (let attempt = 0; attempt < 2; attempt += 1) {
227
+ try {
228
+ const handle = await open(lockFile, "wx");
229
+ await handle.writeFile(
230
+ `${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`,
231
+ "utf8",
232
+ );
233
+ await handle.close();
234
+ return async () => rm(lockFile, { force: true });
235
+ } catch (error) {
236
+ if (error?.code !== "EEXIST") throw error;
237
+ const owner = JSON.parse(await readFile(lockFile, "utf8").catch(() => "{}"));
238
+ const pid = Number(owner.pid);
239
+ let live = false;
240
+ if (Number.isInteger(pid) && pid > 0) {
241
+ try {
242
+ process.kill(pid, 0);
243
+ live = true;
244
+ } catch {
245
+ live = false;
246
+ }
247
+ }
248
+ if (live)
249
+ throw new ProviderError("run is locked by another writer", { category: "lock-busy" });
250
+ await rm(lockFile, { force: true });
251
+ }
252
+ }
253
+ throw new ProviderError("could not acquire run lock", { category: "lock-busy" });
254
+ }
255
+
256
+ function ensureRecord(record) {
257
+ if (
258
+ !record ||
259
+ record.schemaVersion !== SCHEMA_VERSION ||
260
+ typeof record.runId !== "string" ||
261
+ typeof record.projectRoot !== "string"
262
+ )
263
+ fail("record schemaVersion, runId and projectRoot are required");
264
+ if (!path.isAbsolute(record.projectRoot)) fail("record projectRoot must be absolute");
265
+ if (
266
+ !record.limits ||
267
+ !Number.isInteger(record.limits.maxImageRequests) ||
268
+ record.limits.maxImageRequests < 1
269
+ )
270
+ fail("record limits.maxImageRequests is required");
271
+ if (!record.limits.deadlineAt || Number.isNaN(Date.parse(record.limits.deadlineAt)))
272
+ fail("record limits.deadlineAt is required");
273
+ record.requests ??= {};
274
+ for (const key of ["pending", "completed", "unknown", "failed"]) record.requests[key] ??= [];
275
+ if (!Array.isArray(record.rounds)) record.rounds = [];
276
+ if (!Array.isArray(record.decisionHistory)) record.decisionHistory = [];
277
+ const ids = new Set();
278
+ for (const key of ["pending", "completed", "unknown", "failed"]) {
279
+ for (const request of record.requests[key]) {
280
+ if (typeof request?.requestId !== "string" || ids.has(request.requestId))
281
+ fail("record request ledger contains a duplicate or malformed request ID");
282
+ ids.add(request.requestId);
283
+ }
284
+ }
285
+ return record;
286
+ }
287
+
288
+ async function readRecord(recordFile) {
289
+ let value;
290
+ try {
291
+ value = JSON.parse(await readFile(recordFile, "utf8"));
292
+ } catch (error) {
293
+ fail(`cannot read record: ${error instanceof Error ? error.message : "invalid JSON"}`);
294
+ }
295
+ return ensureRecord(value);
296
+ }
297
+
298
+ function recordRoot(record, recordFile) {
299
+ const projectRoot = path.resolve(record.projectRoot);
300
+ const artifactRoot = path.resolve(
301
+ projectRoot,
302
+ record.artifactRoot ?? path.relative(projectRoot, path.dirname(recordFile)),
303
+ );
304
+ if (artifactRoot !== projectRoot) safeRelative(projectRoot, artifactRoot, "artifactRoot");
305
+ return { projectRoot, artifactRoot };
306
+ }
307
+
308
+ function requestCount(record) {
309
+ return (
310
+ record.requests.completed.length +
311
+ record.requests.pending.length +
312
+ record.requests.unknown.length
313
+ );
314
+ }
315
+
316
+ function findRequest(record, requestId) {
317
+ for (const key of ["completed", "pending", "unknown", "failed"]) {
318
+ const found = record.requests[key].find((entry) => entry.requestId === requestId);
319
+ if (found !== undefined) return { key, entry: found };
320
+ }
321
+ return undefined;
322
+ }
323
+
324
+ function removeRequest(record, requestId, key) {
325
+ const index = record.requests[key].findIndex((entry) => entry.requestId === requestId);
326
+ if (index >= 0) return record.requests[key].splice(index, 1)[0];
327
+ return undefined;
328
+ }
329
+
330
+ function dataUri(value) {
331
+ if (typeof value !== "string" || !value.startsWith("data:")) return undefined;
332
+ const match = /^data:(image\/(?:png|jpeg|jpg|webp|gif));base64,([A-Za-z0-9+/=\s]+)$/u.exec(value);
333
+ if (match === null) return undefined;
334
+ return {
335
+ mime: match[1] === "image/jpg" ? "image/jpeg" : match[1],
336
+ bytes: Buffer.from(match[2].replace(/\s+/gu, ""), "base64"),
337
+ };
338
+ }
339
+
340
+ function findImagePayload(value, seen = new Set()) {
341
+ if (value === null || value === undefined || seen.has(value)) return undefined;
342
+ if (typeof value === "string") return dataUri(value);
343
+ if (typeof value !== "object") return undefined;
344
+ seen.add(value);
345
+ if (typeof value.b64_json === "string") {
346
+ const mime = typeof value.mime_type === "string" ? value.mime_type : "image/png";
347
+ return { mime, bytes: Buffer.from(value.b64_json, "base64") };
348
+ }
349
+ if (typeof value.base64 === "string") {
350
+ const mime = typeof value.mime === "string" ? value.mime : "image/png";
351
+ return { mime, bytes: Buffer.from(value.base64, "base64") };
352
+ }
353
+ if (typeof value.url === "string") return dataUri(value.url);
354
+ if (value.image_url !== undefined) return findImagePayload(value.image_url, seen);
355
+ if (Array.isArray(value)) {
356
+ for (const child of value) {
357
+ const found = findImagePayload(child, seen);
358
+ if (found !== undefined) return found;
359
+ }
360
+ } else {
361
+ for (const child of Object.values(value)) {
362
+ const found = findImagePayload(child, seen);
363
+ if (found !== undefined) return found;
364
+ }
365
+ }
366
+ return undefined;
367
+ }
368
+
369
+ function hasImageModality(architecture, key) {
370
+ return Array.isArray(architecture?.[key])
371
+ ? architecture[key].some((modality) => typeof modality === "string" && modality === "image")
372
+ : false;
373
+ }
374
+
375
+ function capabilitySupportsImages(value, needsInput) {
376
+ if (!Array.isArray(value?.data)) return false;
377
+ return value.data.some((endpoint) => {
378
+ const architecture = endpoint?.architecture;
379
+ return (
380
+ hasImageModality(architecture, "output_modalities") &&
381
+ (!needsInput || hasImageModality(architecture, "input_modalities"))
382
+ );
383
+ });
384
+ }
385
+
386
+ function capabilityEndpoint(apiEndpoint, model) {
387
+ if (process.env.NODE_ENV === "test" && process.env.TN_REFERENCE_CAPABILITIES_ENDPOINT)
388
+ return process.env.TN_REFERENCE_CAPABILITIES_ENDPOINT;
389
+ const endpoint = new URL(apiEndpoint);
390
+ endpoint.pathname = `/api/v1/models/${encodeURIComponent(model)}/endpoints`;
391
+ endpoint.search = "";
392
+ return endpoint.toString();
393
+ }
394
+
395
+ async function fetchJson(url, options, timeoutMs) {
396
+ activeController = new AbortController();
397
+ const timer = setTimeout(() => activeController.abort(), timeoutMs);
398
+ try {
399
+ const response = await fetch(url, { ...options, signal: activeController.signal });
400
+ const text = await response.text();
401
+ let body;
402
+ try {
403
+ body = text === "" ? {} : JSON.parse(text);
404
+ } catch {
405
+ throw new ProviderError("provider returned non-JSON output", {
406
+ category: "invalid-response",
407
+ status: response.status,
408
+ });
409
+ }
410
+ return { response, body };
411
+ } catch (error) {
412
+ if (error instanceof ProviderError) throw error;
413
+ if (error?.name === "AbortError")
414
+ throw new ProviderError("provider request timed out or was cancelled", {
415
+ category: "timeout",
416
+ });
417
+ throw new ProviderError("provider request failed", { category: "network" });
418
+ } finally {
419
+ clearTimeout(timer);
420
+ activeController = undefined;
421
+ }
422
+ }
423
+
424
+ async function discoverCapabilities(endpoint, model, needsInput, timeoutMs) {
425
+ const { response, body } = await fetchJson(
426
+ capabilityEndpoint(endpoint, model),
427
+ {
428
+ headers: {
429
+ // biome-ignore lint/style/useNamingConvention: HTTP header uses the exact wire spelling.
430
+ Accept: "application/json",
431
+ },
432
+ },
433
+ timeoutMs,
434
+ );
435
+ if (!response.ok)
436
+ throw new ProviderError("model capability discovery failed", {
437
+ category: "capability",
438
+ status: response.status,
439
+ retryAfter: response.headers.get("retry-after") ?? undefined,
440
+ });
441
+ if (!capabilitySupportsImages(body, needsInput))
442
+ throw new ProviderError(
443
+ "selected model does not advertise the required image input/output support",
444
+ { category: "capability" },
445
+ );
446
+ return body;
447
+ }
448
+
449
+ function requestBody(model, prompt, reference) {
450
+ const content = [{ type: "text", text: prompt }];
451
+ if (reference !== undefined)
452
+ content.unshift({
453
+ type: "image_url",
454
+ // biome-ignore lint/style/useNamingConvention: provider payload uses the exact API field name.
455
+ image_url: {
456
+ url: `data:${reference.info.mime};base64,${reference.bytes.toString("base64")}`,
457
+ },
458
+ });
459
+ return { model, messages: [{ role: "user", content }], modalities: ["image"] };
460
+ }
461
+
462
+ function providerMessage(status) {
463
+ if (status === 400) return "provider rejected the request";
464
+ if (status === 401 || status === 403) return "provider credentials were rejected";
465
+ if (status === 402) return "provider reported insufficient credit";
466
+ if (status === 404) return "provider route or model was not found";
467
+ if (status === 429) return "provider rate-limited the request";
468
+ if (status >= 500) return "provider returned a server error";
469
+ return "provider returned an error";
470
+ }
471
+
472
+ async function generate(options, recordFile, record, roots) {
473
+ const promptFile = await assertExistingPathInside(
474
+ roots.artifactRoot,
475
+ path.resolve(process.cwd(), options["prompt-file"]),
476
+ "prompt file",
477
+ );
478
+ const outFile = await assertExistingPathInside(
479
+ roots.artifactRoot,
480
+ path.resolve(process.cwd(), options.out),
481
+ "output file",
482
+ );
483
+ const referenceFile =
484
+ options.reference === undefined
485
+ ? undefined
486
+ : await assertExistingPathInside(
487
+ roots.artifactRoot,
488
+ path.resolve(process.cwd(), options.reference),
489
+ "reference image",
490
+ );
491
+ const prompt = await readFile(promptFile, "utf8");
492
+ if (prompt.trim() === "") fail("prompt file is empty");
493
+ const referenceBytes = referenceFile === undefined ? undefined : await readFile(referenceFile);
494
+ const referenceInfo = referenceBytes === undefined ? undefined : validateImage(referenceBytes);
495
+ const extension = outputExtension(outFile);
496
+ if (!process.env.OPENROUTER_API_KEY) fail("OPENROUTER_API_KEY is required for generated targets");
497
+ if (Date.now() >= Date.parse(record.limits.deadlineAt))
498
+ throw new ProviderError("run deadline has expired", { category: "deadline" });
499
+ if (requestCount(record) >= record.limits.maxImageRequests)
500
+ throw new ProviderError("image request allowance is exhausted", { category: "budget" });
501
+
502
+ const requestId = options["request-id"];
503
+ const previous = findRequest(record, requestId);
504
+ if (previous?.key === "completed") {
505
+ const artifact = previous.entry.artifact;
506
+ if (!artifact?.path || !artifact.sha256)
507
+ throw new ProviderError("completed request receipt is malformed", { category: "receipt" });
508
+ const artifactFile = path.resolve(roots.projectRoot, artifact.path);
509
+ await assertExistingPathInside(roots.projectRoot, artifactFile, "completed artifact");
510
+ const bytes = await readFile(artifactFile).catch(() => {
511
+ throw new ProviderError("completed artifact is missing", { category: "receipt" });
512
+ });
513
+ if (sha256(bytes) !== artifact.sha256)
514
+ throw new ProviderError("completed artifact hash does not match its receipt", {
515
+ category: "receipt",
516
+ });
517
+ console.log(
518
+ JSON.stringify({
519
+ action: "reused",
520
+ requestId,
521
+ model: previous.entry.model,
522
+ output: artifact.path,
523
+ sha256: artifact.sha256,
524
+ }),
525
+ );
526
+ return;
527
+ }
528
+ if (previous !== undefined)
529
+ throw new ProviderError(
530
+ "request ID has a pending, unknown or failed receipt and will not be sent again",
531
+ { category: previous.key === "failed" ? "request-failed" : "request-not-replayable" },
532
+ );
533
+ if (
534
+ await stat(outFile)
535
+ .then(() => true)
536
+ .catch(() => false)
537
+ )
538
+ fail("output path already exists; locked targets are never overwritten");
539
+
540
+ const pending = {
541
+ requestId,
542
+ model: options.model,
543
+ promptSha256: sha256(prompt),
544
+ referenceSha256: referenceBytes === undefined ? undefined : sha256(referenceBytes),
545
+ outputPath: projectRelative(roots.projectRoot, outFile),
546
+ startedAt: new Date().toISOString(),
547
+ };
548
+ record.requests.pending.push(pending);
549
+ await atomicWriteJson(recordFile, record);
550
+ let posted = false;
551
+ const endpoint =
552
+ process.env.NODE_ENV === "test" && process.env.TN_REFERENCE_ENDPOINT
553
+ ? process.env.TN_REFERENCE_ENDPOINT
554
+ : DEFAULT_ENDPOINT;
555
+ try {
556
+ const capabilities = await discoverCapabilities(
557
+ endpoint,
558
+ options.model,
559
+ referenceBytes !== undefined,
560
+ options.timeoutMs,
561
+ );
562
+ record.providerCapabilities = {
563
+ model: options.model,
564
+ checkedAt: new Date().toISOString(),
565
+ imageInputOutput: true,
566
+ response: capabilities,
567
+ };
568
+ await atomicWriteJson(recordFile, record);
569
+ const result = await fetchJson(
570
+ endpoint,
571
+ {
572
+ method: "POST",
573
+ headers: {
574
+ // biome-ignore lint/style/useNamingConvention: HTTP header uses the exact wire spelling.
575
+ Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
576
+ "Content-Type": "application/json",
577
+ // biome-ignore lint/style/useNamingConvention: HTTP header uses the exact wire spelling.
578
+ Accept: "application/json",
579
+ },
580
+ body: JSON.stringify(
581
+ requestBody(
582
+ options.model,
583
+ prompt,
584
+ referenceBytes === undefined
585
+ ? undefined
586
+ : { bytes: referenceBytes, info: referenceInfo },
587
+ ),
588
+ ),
589
+ },
590
+ options.timeoutMs,
591
+ );
592
+ posted = true;
593
+ if (!result.response.ok)
594
+ throw new ProviderError(providerMessage(result.response.status), {
595
+ category: `http-${result.response.status}`,
596
+ status: result.response.status,
597
+ retryAfter: result.response.headers.get("retry-after") ?? undefined,
598
+ });
599
+ if (process.env.NODE_ENV === "test" && process.env.TN_REFERENCE_ABORT_AFTER_POST === "1")
600
+ throw new ProviderError("test cancellation after provider dispatch", {
601
+ category: "cancelled",
602
+ });
603
+ const image = findImagePayload(result.body);
604
+ if (image === undefined)
605
+ throw new ProviderError("provider returned no inline raster image", {
606
+ category: "invalid-image",
607
+ });
608
+ const info = validateImage(image.bytes, extension);
609
+ if (image.mime !== info.mime && !(image.mime === "image/jpg" && info.mime === "image/jpeg"))
610
+ throw new ProviderError("provider MIME does not match decoded image bytes", {
611
+ category: "invalid-image",
612
+ });
613
+ await atomicWriteBytes(outFile, image.bytes);
614
+ const artifact = {
615
+ path: projectRelative(roots.projectRoot, outFile),
616
+ sha256: sha256(image.bytes),
617
+ bytes: image.bytes.length,
618
+ mime: info.mime,
619
+ width: info.width,
620
+ height: info.height,
621
+ };
622
+ const receipt = removeRequest(record, requestId, "pending");
623
+ record.requests.completed.push({
624
+ ...receipt,
625
+ completedAt: new Date().toISOString(),
626
+ artifact,
627
+ usage: result.body.usage ?? result.body.cost ?? "unknown",
628
+ });
629
+ await atomicWriteJson(recordFile, record);
630
+ console.log(
631
+ JSON.stringify({
632
+ action: "generated",
633
+ requestId,
634
+ model: options.model,
635
+ output: artifact.path,
636
+ sha256: artifact.sha256,
637
+ bytes: artifact.bytes,
638
+ mime: artifact.mime,
639
+ width: artifact.width,
640
+ height: artifact.height,
641
+ usage: result.body.usage ?? result.body.cost ?? "unknown",
642
+ }),
643
+ );
644
+ } catch (error) {
645
+ const safeError =
646
+ error instanceof ProviderError
647
+ ? error
648
+ : new ProviderError("provider operation failed", { category: "provider" });
649
+ const receipt = removeRequest(record, requestId, "pending");
650
+ if (receipt !== undefined) {
651
+ const destination =
652
+ posted ||
653
+ safeError.category === "timeout" ||
654
+ safeError.category === "network" ||
655
+ safeError.category === "cancelled" ||
656
+ String(safeError.category).startsWith("http-") ||
657
+ safeError.category === "invalid-image"
658
+ ? "unknown"
659
+ : "failed";
660
+ record.requests[destination].push({
661
+ ...receipt,
662
+ finishedAt: new Date().toISOString(),
663
+ category: safeError.category,
664
+ status: safeError.status,
665
+ retryAfter: safeError.retryAfter,
666
+ });
667
+ await atomicWriteJson(recordFile, record);
668
+ }
669
+ throw safeError;
670
+ }
671
+ }
672
+
673
+ async function main() {
674
+ const options = parseArgs(process.argv.slice(2));
675
+ if (options.help) {
676
+ printHelp();
677
+ return;
678
+ }
679
+ const recordFile = path.resolve(process.cwd(), options.record);
680
+ const record = await readRecord(recordFile);
681
+ const roots = recordRoot(record, recordFile);
682
+ const release = await acquireLock(recordFile);
683
+ try {
684
+ await generate(options, recordFile, record, roots);
685
+ } finally {
686
+ await release();
687
+ }
688
+ }
689
+
690
+ process.on("SIGINT", () => activeController?.abort());
691
+ process.on("SIGTERM", () => activeController?.abort());
692
+ main().catch((error) => {
693
+ const category = error instanceof InputError ? "invalid-input" : (error.category ?? "provider");
694
+ const exitCode = error instanceof InputError ? 2 : 1;
695
+ console.log(
696
+ JSON.stringify({
697
+ action: "failed",
698
+ category,
699
+ status: error.status,
700
+ retryAfter: error.retryAfter,
701
+ message: error.message,
702
+ }),
703
+ );
704
+ process.exitCode = exitCode;
705
+ });