@wildshard/sdk 0.0.1 → 0.2.3

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 (687) hide show
  1. package/GUIDE.md +790 -0
  2. package/README.md +13 -5
  3. package/bin/wildshard.mjs +38 -0
  4. package/lint/declaration-config.d.mts +2 -0
  5. package/lint/declaration-config.mjs +19 -0
  6. package/lint/engine-plugin.d.mts +2 -0
  7. package/lint/engine-plugin.mjs +40 -0
  8. package/lint/host-callbacks.d.mts +6 -0
  9. package/lint/host-callbacks.mjs +123 -0
  10. package/lint/host-files.d.mts +1 -0
  11. package/lint/host-files.mjs +7 -0
  12. package/lint/layer-exports.d.mts +2 -0
  13. package/lint/layer-exports.mjs +21 -0
  14. package/lint/legacy-line-basis.json +995 -0
  15. package/lint/nine-tiling-baseline.json +35 -0
  16. package/lint/ratchet.json +11 -0
  17. package/lint/runtime-files.d.mts +12 -0
  18. package/lint/runtime-files.json +16 -0
  19. package/lint/runtime-files.mjs +69 -0
  20. package/lint/runtime-performance.d.mts +6 -0
  21. package/lint/runtime-performance.mjs +184 -0
  22. package/lint/sdk-plugin.d.mts +4 -0
  23. package/lint/sdk-plugin.mjs +134 -0
  24. package/lint/shardfile-boundaries.d.mts +10 -0
  25. package/lint/shardfile-boundaries.mjs +122 -0
  26. package/lint/tile-bake-debt.json +556 -0
  27. package/package.json +365 -3
  28. package/scripts/agent-parity.mjs +1524 -0
  29. package/scripts/agent-sync.mjs +518 -0
  30. package/scripts/apfs-clone.mjs +67 -0
  31. package/scripts/assert-store-layout.mjs +23 -0
  32. package/scripts/astc6-phone-cap.d.mts +3 -0
  33. package/scripts/astc6-phone-cap.mjs +137 -0
  34. package/scripts/audit-assets.d.mts +10 -0
  35. package/scripts/audit-assets.mjs +151 -0
  36. package/scripts/bake/coatFiles.d.mts +6 -0
  37. package/scripts/bake/coatFiles.mjs +37 -0
  38. package/scripts/bake/environment.d.mts +2 -0
  39. package/scripts/bake/environment.mjs +58 -0
  40. package/scripts/bake/far-proxies.mjs +45 -0
  41. package/scripts/bake/keyed-sky.d.mts +4 -0
  42. package/scripts/bake/keyed-sky.mjs +34 -0
  43. package/scripts/bake/movers.mjs +56 -0
  44. package/scripts/bake/nativeWorld.d.mts +6 -0
  45. package/scripts/bake/nativeWorld.mjs +43 -0
  46. package/scripts/bake/navmeshGround.ts +22 -0
  47. package/scripts/bake/near-placeholder.mjs +331 -0
  48. package/scripts/bake/placeholderShards.mjs +41 -0
  49. package/scripts/bake/skins.mjs +15 -0
  50. package/scripts/bake/template-skins.mjs +33 -0
  51. package/scripts/bake/viewmodelBytes.ts +26 -0
  52. package/scripts/bake/viewmodelPage.ts +11 -0
  53. package/scripts/bake/worldHost.d.mts +35 -0
  54. package/scripts/bake/worldHost.mjs +110 -0
  55. package/scripts/bake-astc6.cache.json +80 -0
  56. package/scripts/bake-astc6.far-reach.cache.json +23 -0
  57. package/scripts/bake-astc6.list.json +111 -0
  58. package/scripts/bake-astc6.mjs +279 -0
  59. package/scripts/bake-astc6.nalati-grasslands.cache.json +42 -0
  60. package/scripts/bake-catalogue.mjs +44 -0
  61. package/scripts/bake-check.mjs +54 -0
  62. package/scripts/bake-chunk.mjs +124 -0
  63. package/scripts/bake-cloud-field.mjs +24 -0
  64. package/scripts/bake-coats.mjs +110 -0
  65. package/scripts/bake-data-maps.d.mts +24 -0
  66. package/scripts/bake-data-maps.mjs +72 -0
  67. package/scripts/bake-entry-programs.mjs +117 -0
  68. package/scripts/bake-geometry.mjs +106 -0
  69. package/scripts/bake-hybrid-tiles.mjs +28 -0
  70. package/scripts/bake-ktx2.cache.json +276 -0
  71. package/scripts/bake-ktx2.list.json +365 -0
  72. package/scripts/bake-ktx2.mjs +477 -0
  73. package/scripts/bake-map-glb.mjs +127 -0
  74. package/scripts/bake-map-rest.d.mts +7 -0
  75. package/scripts/bake-map-rest.mjs +50 -0
  76. package/scripts/bake-maps.mjs +200 -0
  77. package/scripts/bake-navmesh.mjs +259 -0
  78. package/scripts/bake-packs.mjs +129 -0
  79. package/scripts/bake-pickups.mjs +102 -0
  80. package/scripts/bake-query-terrain.mjs +64 -0
  81. package/scripts/bake-recurve-pool.mjs +16 -0
  82. package/scripts/bake-section-schemas.d.mts +3 -0
  83. package/scripts/bake-template-shardfile.mjs +32 -0
  84. package/scripts/bake-textures.mjs +80 -0
  85. package/scripts/bake-viewmodel-sets.json +45 -0
  86. package/scripts/bake-viewmodel-sets.mjs +137 -0
  87. package/scripts/bake-voxel-ao.mjs +119 -0
  88. package/scripts/bake-water-ripples.mjs +25 -0
  89. package/scripts/blender/README.md +129 -0
  90. package/scripts/blender/build.sh +166 -0
  91. package/scripts/blender/lib/export-scene.mjs +129 -0
  92. package/scripts/blender/lib/glb-digest.mjs +188 -0
  93. package/scripts/blender/lib/glb.py +68 -0
  94. package/scripts/blender/lib/save_blend.py +17 -0
  95. package/scripts/blender/lib/world_fixture.py +55 -0
  96. package/scripts/blender/targets.json +591 -0
  97. package/scripts/build-sdk.mjs +95 -0
  98. package/scripts/build-shardfiles.d.mts +7 -0
  99. package/scripts/build-shardfiles.mjs +206 -0
  100. package/scripts/capture-hero.mjs +137 -0
  101. package/scripts/check-lift-review.mjs +23 -0
  102. package/scripts/chromium-keychain-check.mjs +139 -0
  103. package/scripts/chromium-keychain.d.mts +1 -0
  104. package/scripts/chromium-keychain.mjs +5 -0
  105. package/scripts/compile-script.d.mts +3 -0
  106. package/scripts/compile-script.mjs +8 -0
  107. package/scripts/creature-color.mjs +255 -0
  108. package/scripts/decide/calibrate.py +127 -0
  109. package/scripts/decide/calibration/2026-10-03/labels-s1.tsv +281 -0
  110. package/scripts/decide/calibration/2026-10-03/labels-s2.tsv +97 -0
  111. package/scripts/decide/calibration/2026-10-03/labels-s3.tsv +48 -0
  112. package/scripts/decide/calibration/2026-10-03/labels-s3b.tsv +26 -0
  113. package/scripts/decide/calibration/2026-10-03/res-capture-status-v1.jsonl +376 -0
  114. package/scripts/decide/calibration/2026-10-03/res-text-garbled-strings.jsonl +48 -0
  115. package/scripts/decide/calibration/2026-10-03/res-text-garbled-v1.jsonl +73 -0
  116. package/scripts/decide/decide.py +262 -0
  117. package/scripts/decide/decide.sh +50 -0
  118. package/scripts/decide/layer-purity-pilot.mjs +41 -0
  119. package/scripts/decide/sets/capture-status.json +46 -0
  120. package/scripts/decide/sets/layer-purity.json +28 -0
  121. package/scripts/decide/sets/text-garbled.json +17 -0
  122. package/scripts/decide/test_decide.py +37 -0
  123. package/scripts/docs.mjs +15 -0
  124. package/scripts/entry-reads/crawl.ts +152 -0
  125. package/scripts/entry-reads/tsconfig.json +25 -0
  126. package/scripts/gen-format-schema.d.mts +2 -0
  127. package/scripts/gen-format-schema.mjs +21 -0
  128. package/scripts/gen-host-catalogue.d.mts +14 -0
  129. package/scripts/gen-host-catalogue.mjs +108 -0
  130. package/scripts/gen-shard-layout-doc.d.mts +4 -0
  131. package/scripts/gen-shard-layout-doc.mjs +55 -0
  132. package/scripts/gen-shards.d.mts +17 -0
  133. package/scripts/gen-shards.mjs +311 -0
  134. package/scripts/goldens/capture-inputs.d.mts +4 -0
  135. package/scripts/goldens/capture-inputs.mjs +34 -0
  136. package/scripts/goldens/colour_shift.py +27 -0
  137. package/scripts/goldens/native-residency.d.mts +10 -0
  138. package/scripts/goldens/native-residency.mjs +104 -0
  139. package/scripts/goldens/plot-inputs.d.mts +12 -0
  140. package/scripts/goldens/plot-inputs.mjs +46 -0
  141. package/scripts/gpu-texmem.mjs +98 -0
  142. package/scripts/horizon-matte/config.py +24 -0
  143. package/scripts/horizon-matte/encode.py +91 -0
  144. package/scripts/horizon-matte/key.py +141 -0
  145. package/scripts/horizon-matte/mkjobs.py +33 -0
  146. package/scripts/horizon-matte/mkjobs_day2.py +11 -0
  147. package/scripts/horizon-matte/overlap.py +80 -0
  148. package/scripts/horizon-matte/run_codex.py +57 -0
  149. package/scripts/horizon-matte/stitch.py +133 -0
  150. package/scripts/img2mesh/CC0.md +105 -0
  151. package/scripts/img2mesh/README.md +209 -0
  152. package/scripts/img2mesh/ab_board.py +102 -0
  153. package/scripts/img2mesh/birds/birds.json +255 -0
  154. package/scripts/img2mesh/birds/birds_atlas.py +150 -0
  155. package/scripts/img2mesh/birds/birds_fix_preview.mjs +103 -0
  156. package/scripts/img2mesh/birds/birds_fix_render.py +75 -0
  157. package/scripts/img2mesh/birds/birds_pack.py +110 -0
  158. package/scripts/img2mesh/birds/birds_phone_b.py +112 -0
  159. package/scripts/img2mesh/birds/birds_post.py +550 -0
  160. package/scripts/img2mesh/birds/birds_render.py +125 -0
  161. package/scripts/img2mesh/birds/birds_sheet.py +33 -0
  162. package/scripts/img2mesh/birds/birds_view.py +60 -0
  163. package/scripts/img2mesh/board.py +100 -0
  164. package/scripts/img2mesh/build_cc0.sh +52 -0
  165. package/scripts/img2mesh/build_driftwood.sh +12 -0
  166. package/scripts/img2mesh/build_faces.sh +53 -0
  167. package/scripts/img2mesh/build_props.py +81 -0
  168. package/scripts/img2mesh/cc0_export.py +186 -0
  169. package/scripts/img2mesh/driftwood_post.py +571 -0
  170. package/scripts/img2mesh/e304_faces.sh +67 -0
  171. package/scripts/img2mesh/face_remaster.py +911 -0
  172. package/scripts/img2mesh/face_views.py +95 -0
  173. package/scripts/img2mesh/faces-e304.json +9 -0
  174. package/scripts/img2mesh/faces.json +30 -0
  175. package/scripts/img2mesh/head_cut.py +100 -0
  176. package/scripts/img2mesh/hi3d_paint.py +94 -0
  177. package/scripts/img2mesh/hi3d_refine.py +161 -0
  178. package/scripts/img2mesh/hunyuan_cpu_rasterizer.sh +42 -0
  179. package/scripts/img2mesh/pine_hollow_phone.sh +13 -0
  180. package/scripts/img2mesh/props/coral-arch.json +32 -0
  181. package/scripts/img2mesh/props/ember-furnace.json +30 -0
  182. package/scripts/img2mesh/props/night-market-gate.json +10 -0
  183. package/scripts/img2mesh/render_still.py +86 -0
  184. package/scripts/img2mesh/rig_strip.mjs +46 -0
  185. package/scripts/img2mesh/rig_transfer.mjs +104 -0
  186. package/scripts/img2mesh/split_sheet.py +48 -0
  187. package/scripts/img2mesh/trellis_batch.py +110 -0
  188. package/scripts/img2mesh/versus_board.py +114 -0
  189. package/scripts/import-bundle.d.mts +2 -0
  190. package/scripts/import-bundle.mjs +20 -0
  191. package/scripts/ktx2-ab-board.py +133 -0
  192. package/scripts/ktx2-ab.mjs +111 -0
  193. package/scripts/ktx2-settings.mjs +18 -0
  194. package/scripts/land.d.mts +14 -0
  195. package/scripts/land.mjs +809 -0
  196. package/scripts/lint-dispatch.mjs +14 -0
  197. package/scripts/map-bake-frames.d.mts +4 -0
  198. package/scripts/map-bake-frames.mjs +23 -0
  199. package/scripts/map-geometry.d.mts +9 -0
  200. package/scripts/map-geometry.mjs +29 -0
  201. package/scripts/map-world.mjs +162 -0
  202. package/scripts/mockup-local.sh +46 -0
  203. package/scripts/music/export-midi.mjs +68 -0
  204. package/scripts/music/gen/analyze.py +308 -0
  205. package/scripts/music/gen/audio_jobs.py +46 -0
  206. package/scripts/music/gen/briefs.json +51 -0
  207. package/scripts/music/gen/build_page.py +334 -0
  208. package/scripts/music/gen/folk.json +3187 -0
  209. package/scripts/music/gen/gen_ace_step.py +156 -0
  210. package/scripts/music/gen/gen_heartmula.py +187 -0
  211. package/scripts/music/gen/gen_minimax.py +143 -0
  212. package/scripts/music/gen/gen_sao.py +122 -0
  213. package/scripts/music/gen/gen_sao_small.py +104 -0
  214. package/scripts/music/gen/gen_sfx.py +98 -0
  215. package/scripts/music/gen/gen_sfx_ezaudio.py +112 -0
  216. package/scripts/music/gen/gen_sfx_moss.py +112 -0
  217. package/scripts/music/gen/models.json +61 -0
  218. package/scripts/music/gen/nalati-jobs.json +104 -0
  219. package/scripts/music/gen/nalati-score-build.json +119 -0
  220. package/scripts/music/gen/nalati-score.json +3448 -0
  221. package/scripts/music/gen/ob7-fit-decisions.json +38 -0
  222. package/scripts/music/gen/ob7-score-jobs.json +152 -0
  223. package/scripts/music/gen/ob7-sfx-jobs.json +897 -0
  224. package/scripts/music/gen/ob7_build.py +469 -0
  225. package/scripts/music/gen/ob7_generate.py +67 -0
  226. package/scripts/music/gen/ob7_run.sh +42 -0
  227. package/scripts/music/gen/orchestral.json +3187 -0
  228. package/scripts/music/gen/own_score.py +486 -0
  229. package/scripts/music/gen/ph-jobs.json +27 -0
  230. package/scripts/music/gen/ph_page.py +222 -0
  231. package/scripts/music/gen/piano.json +3175 -0
  232. package/scripts/music/gen/rank_v3.py +248 -0
  233. package/scripts/music/gen/sfx-best.json +2486 -0
  234. package/scripts/music/gen/sfx-ezaudio.json +4082 -0
  235. package/scripts/music/gen/sfx-jobs.json +57 -0
  236. package/scripts/music/gen/sfx-minimax-jobs.json +16 -0
  237. package/scripts/music/gen/sfx-minimax.json +289 -0
  238. package/scripts/music/gen/sfx-moss.json +4082 -0
  239. package/scripts/music/gen/sfx-nalati-b3-jobs.json +17 -0
  240. package/scripts/music/gen/sfx-nalati-jobs.json +338 -0
  241. package/scripts/music/gen/sfx-nalati.json +11202 -0
  242. package/scripts/music/gen/sfx-nd-jobs.json +57 -0
  243. package/scripts/music/gen/sfx-nd-moss.json +2097 -0
  244. package/scripts/music/gen/sfx-nd-sa3-medium.json +2097 -0
  245. package/scripts/music/gen/sfx-nd-summary.json +38 -0
  246. package/scripts/music/gen/sfx-peaks.json +7 -0
  247. package/scripts/music/gen/sfx-ph-jobs.json +169 -0
  248. package/scripts/music/gen/sfx-ph-moss.json +6564 -0
  249. package/scripts/music/gen/sfx-ph-sa3-medium.json +7239 -0
  250. package/scripts/music/gen/sfx-ph-summary.json +63 -0
  251. package/scripts/music/gen/sfx-sa3-medium.json +4082 -0
  252. package/scripts/music/gen/sfx-sa3.json +4082 -0
  253. package/scripts/music/gen/sfx-summary.json +107 -0
  254. package/scripts/music/gen/sfx_build.py +332 -0
  255. package/scripts/music/gen/sfx_merge.py +255 -0
  256. package/scripts/music/gen/sfx_minimax.py +61 -0
  257. package/scripts/music/gen/sfx_nalati.py +331 -0
  258. package/scripts/music/gen/sfx_sprite.py +424 -0
  259. package/scripts/music/gen/stems.py +539 -0
  260. package/scripts/music/gen/test_loop_meter.py +29 -0
  261. package/scripts/music/gen/test_ob7_provenance.py +77 -0
  262. package/scripts/music/gen/v3-folk-build.json +148 -0
  263. package/scripts/music/gen/v3-folk.json +1818 -0
  264. package/scripts/music/gen/v3-jobs.json +145 -0
  265. package/scripts/music/gen/v3-orchestral-build.json +148 -0
  266. package/scripts/music/gen/v3-orchestral.json +1813 -0
  267. package/scripts/music/gen/v3-ph-folk-build.json +94 -0
  268. package/scripts/music/gen/v3-ph-folk.json +1806 -0
  269. package/scripts/music/gen/v3-ph-orchestral-build.json +94 -0
  270. package/scripts/music/gen/v3-ph-orchestral.json +1824 -0
  271. package/scripts/music/gen/v3-ph-piano-build.json +94 -0
  272. package/scripts/music/gen/v3-ph-piano.json +1818 -0
  273. package/scripts/music/gen/v3-piano-build.json +148 -0
  274. package/scripts/music/gen/v3-piano.json +1813 -0
  275. package/scripts/music/wildshard-theme.mid +0 -0
  276. package/scripts/music/wildshard-trailer30.mid +0 -0
  277. package/scripts/named-blob-output.d.mts +8 -0
  278. package/scripts/named-blob-output.mjs +48 -0
  279. package/scripts/pack-all.mjs +15 -0
  280. package/scripts/pid-lock.d.mts +1 -0
  281. package/scripts/pid-lock.mjs +63 -0
  282. package/scripts/practice/bake_dummy.py +53 -0
  283. package/scripts/practice/build_dummies.sh +43 -0
  284. package/scripts/practice/dummy_parts.py +568 -0
  285. package/scripts/practice/dummy_rig_gate.py +139 -0
  286. package/scripts/practice/gate_sheet.py +36 -0
  287. package/scripts/practice/generate_dummy_unimate.py +132 -0
  288. package/scripts/practice/pack_dummy.mjs +59 -0
  289. package/scripts/practice/repair_dummy_weights.mjs +68 -0
  290. package/scripts/practice/rig_dummy.py +828 -0
  291. package/scripts/practice/verify_unimate_skin.mjs +356 -0
  292. package/scripts/preparation-seed.mjs +15 -0
  293. package/scripts/prepare-basis-tool.mjs +6 -0
  294. package/scripts/prepare-product.d.mts +14 -0
  295. package/scripts/prepare-product.mjs +101 -0
  296. package/scripts/product-build-tools.d.mts +3 -0
  297. package/scripts/product-build-tools.json +3 -0
  298. package/scripts/product-build-tools.mjs +31 -0
  299. package/scripts/publish-public.mjs +7 -0
  300. package/scripts/push-tables.d.mts +1 -0
  301. package/scripts/push-tables.mjs +28 -0
  302. package/scripts/record-shard-mounts.mjs +133 -0
  303. package/scripts/sdk-externals.d.mts +2 -0
  304. package/scripts/sdk-externals.mjs +2 -0
  305. package/scripts/section-inventory.ts +209 -0
  306. package/scripts/select-candidate.mjs +15 -0
  307. package/scripts/shard-build-pool.d.mts +4 -0
  308. package/scripts/shard-build-pool.mjs +53 -0
  309. package/scripts/shard-line-baseline.json +17 -0
  310. package/scripts/shard-milestones.d.mts +15 -0
  311. package/scripts/shard-milestones.mjs +105 -0
  312. package/scripts/shard-output-report.d.mts +9 -0
  313. package/scripts/shard-output-report.mjs +85 -0
  314. package/scripts/shard-platform-cli.mjs +93 -0
  315. package/scripts/shard-progress.mjs +212 -0
  316. package/scripts/shard-timelapse.py +102 -0
  317. package/scripts/shardfile-cold-boot.mjs +79 -0
  318. package/scripts/shardfile-vite.d.mts +4 -0
  319. package/scripts/shardfile-vite.mjs +20 -0
  320. package/scripts/simplify-models.mjs +24 -0
  321. package/scripts/site-facts.mjs +88 -0
  322. package/scripts/test-template-gate.mjs +44 -0
  323. package/scripts/test_golden_compare.py +68 -0
  324. package/scripts/tex-tiers.cache.json +181 -0
  325. package/scripts/tex-tiers.mjs +240 -0
  326. package/scripts/texmem-probe.mjs +184 -0
  327. package/scripts/unused-assets.mjs +173 -0
  328. package/scripts/vite-tmp.d.mts +23 -0
  329. package/scripts/vite-tmp.mjs +157 -0
  330. package/scripts/wave-line-baselines.json +32 -0
  331. package/scripts/wildshard.d.mts +4 -0
  332. package/scripts/wildshard.mjs +105 -0
  333. package/scripts/witness-checkpoints.d.mts +10 -0
  334. package/scripts/witness-checkpoints.mjs +84 -0
  335. package/scripts/witness-generation.d.mts +10 -0
  336. package/scripts/witness-generation.mjs +45 -0
  337. package/scripts/witness-manifests.d.mts +8 -0
  338. package/scripts/witness-manifests.mjs +157 -0
  339. package/scripts/worktree-ignore.d.mts +4 -0
  340. package/scripts/worktree-ignore.mjs +36 -0
  341. package/scripts/worktree-reap.mjs +214 -0
  342. package/scripts/worktree.mjs +396 -0
  343. package/scripts/worldclaw/capture-front.sh +28 -0
  344. package/scripts/worldclaw/design-template.md +62 -0
  345. package/scripts/worldclaw/spec-map.py +92 -0
  346. package/scripts/worldclaw/spec.ts +96 -0
  347. package/skills/wildshard/SKILL.md +50 -0
  348. package/skills/wildshard-goldens/SKILL.md +54 -0
  349. package/skills/wildshard-mockup-to-model/SKILL.md +56 -0
  350. package/skills/wildshard-upgrade/SKILL.md +46 -0
  351. package/src/.oxfmtrc.json +50 -0
  352. package/src/.oxlintrc.json +173 -0
  353. package/src/cli/account/account.ts +199 -0
  354. package/src/cli/account/command.ts +193 -0
  355. package/src/cli/account/key.ts +154 -0
  356. package/src/cli/args.ts +97 -0
  357. package/src/cli/audio/audio.ts +24 -0
  358. package/src/cli/bin.mjs +8 -0
  359. package/src/cli/delete/delete.ts +258 -0
  360. package/src/cli/help.ts +196 -0
  361. package/src/cli/hero/adopt.ts +103 -0
  362. package/src/cli/hero/hero.ts +112 -0
  363. package/src/cli/hero/stamp.ts +298 -0
  364. package/src/cli/main.ts +292 -0
  365. package/src/cli/report.ts +16 -0
  366. package/src/cli/shardfile/command.ts +50 -0
  367. package/src/cli/shardfile/shardfile.ts +192 -0
  368. package/src/cli/upload/api.ts +246 -0
  369. package/src/cli/upload/compress.ts +55 -0
  370. package/src/cli/upload/hero.ts +62 -0
  371. package/src/cli/upload/placement.ts +115 -0
  372. package/src/cli/upload/provenance.ts +192 -0
  373. package/src/cli/upload/signature.ts +30 -0
  374. package/src/cli/upload/upload.ts +269 -0
  375. package/src/cli/upload/validate.ts +74 -0
  376. package/src/cli/upload/wire.ts +147 -0
  377. package/src/cli/version.ts +63 -0
  378. package/src/commons/bake/portableMath.ts +187 -0
  379. package/src/commons/catalogue.ts +10 -0
  380. package/src/commons/courseProgram.ts +32 -0
  381. package/src/commons/practiceCourse.ts +16 -0
  382. package/src/commons/scripts/abi.as +14 -0
  383. package/src/commons/scripts/bridge.as +14 -0
  384. package/src/commons/scripts/course.as +63 -0
  385. package/src/scripts/ask-new.sh +29 -0
  386. package/src/scripts/asks.mjs +141 -0
  387. package/src/scripts/herdr-prompt.sh +34 -0
  388. package/src/scripts/herdr-question-open.sh +67 -0
  389. package/src/scripts/md-wrap.mjs +229 -0
  390. package/src/server/app.ts +19 -0
  391. package/src/server/serve.ts +49 -0
  392. package/src/sharddev/admission.ts +7 -0
  393. package/src/sharddev/arenaView.ts +15 -0
  394. package/src/sharddev/as/groupBankV2.ts +36 -0
  395. package/src/sharddev/as/groupStepV2.ts +13 -0
  396. package/src/sharddev/as/ws.ts +30 -0
  397. package/src/sharddev/as/wsV2.ts +180 -0
  398. package/src/sharddev/assemblyscriptCompiler.d.mts +5 -0
  399. package/src/sharddev/assemblyscriptCompiler.mjs +14 -0
  400. package/src/sharddev/assetHandle.ts +84 -0
  401. package/src/sharddev/assetOwner.ts +70 -0
  402. package/src/sharddev/assetScope.ts +30 -0
  403. package/src/sharddev/assets.ts +21 -0
  404. package/src/sharddev/audio.ts +9 -0
  405. package/src/sharddev/audioEncode.ts +211 -0
  406. package/src/sharddev/author.ts +3 -0
  407. package/src/sharddev/authorError.ts +28 -0
  408. package/src/sharddev/authorManifest.ts +39 -0
  409. package/src/sharddev/bake/annulus.ts +19 -0
  410. package/src/sharddev/bake/assemblyscriptMemo.ts +76 -0
  411. package/src/sharddev/bake/assemblyscriptMemoPort.ts +4 -0
  412. package/src/sharddev/bake/authoredWorld.ts +201 -0
  413. package/src/sharddev/bake/basisEncoder.ts +95 -0
  414. package/src/sharddev/bake/basisGlb.ts +85 -0
  415. package/src/sharddev/bake/basisTool.ts +74 -0
  416. package/src/sharddev/bake/basisToolInputs.ts +476 -0
  417. package/src/sharddev/bake/byteCodec.ts +33 -0
  418. package/src/sharddev/bake/canvasAtlas.ts +406 -0
  419. package/src/sharddev/bake/coarseCopy.ts +59 -0
  420. package/src/sharddev/bake/colliders.ts +87 -0
  421. package/src/sharddev/bake/compactGlb.ts +224 -0
  422. package/src/sharddev/bake/compileScript.ts +119 -0
  423. package/src/sharddev/bake/compileScriptV2.ts +75 -0
  424. package/src/sharddev/bake/contactRows.ts +84 -0
  425. package/src/sharddev/bake/creaturePlacement.ts +117 -0
  426. package/src/sharddev/bake/export.ts +67 -0
  427. package/src/sharddev/bake/facetedGeometry.ts +379 -0
  428. package/src/sharddev/bake/farImpostor.ts +120 -0
  429. package/src/sharddev/bake/forest.ts +100 -0
  430. package/src/sharddev/bake/format-hook.mjs +2 -0
  431. package/src/sharddev/bake/generatorGlb.ts +23 -0
  432. package/src/sharddev/bake/geometryBounds.ts +77 -0
  433. package/src/sharddev/bake/geometryError.ts +48 -0
  434. package/src/sharddev/bake/glb.ts +355 -0
  435. package/src/sharddev/bake/glbCompression.ts +143 -0
  436. package/src/sharddev/bake/gltfSource.ts +59 -0
  437. package/src/sharddev/bake/groundMap.ts +142 -0
  438. package/src/sharddev/bake/image.ts +20 -0
  439. package/src/sharddev/bake/isleMap.ts +64 -0
  440. package/src/sharddev/bake/json.mjs +84 -0
  441. package/src/sharddev/bake/keyedSky.ts +47 -0
  442. package/src/sharddev/bake/keyedSkyMemo.ts +39 -0
  443. package/src/sharddev/bake/kinds.ts +137 -0
  444. package/src/sharddev/bake/lightSources.ts +31 -0
  445. package/src/sharddev/bake/mapAssembly.ts +84 -0
  446. package/src/sharddev/bake/mapRaster.ts +173 -0
  447. package/src/sharddev/bake/mapRest.ts +57 -0
  448. package/src/sharddev/bake/mapScenes.ts +234 -0
  449. package/src/sharddev/bake/materialGraph.ts +32 -0
  450. package/src/sharddev/bake/meadow.ts +27 -0
  451. package/src/sharddev/bake/meshoptChoiceMemo.ts +34 -0
  452. package/src/sharddev/bake/nativeInteractionFacts.ts +5 -0
  453. package/src/sharddev/bake/nativeLattice.ts +178 -0
  454. package/src/sharddev/bake/nativeRaster.ts +106 -0
  455. package/src/sharddev/bake/nativeTerrainField.ts +11 -0
  456. package/src/sharddev/bake/navigation-json.mjs +38 -0
  457. package/src/sharddev/bake/navigation.ts +113 -0
  458. package/src/sharddev/bake/navigationAsset.ts +18 -0
  459. package/src/sharddev/bake/nearPlaceholder.ts +206 -0
  460. package/src/sharddev/bake/normalizeRig.ts +80 -0
  461. package/src/sharddev/bake/phoneAstc.ts +93 -0
  462. package/src/sharddev/bake/placeholders.ts +581 -0
  463. package/src/sharddev/bake/placement.ts +80 -0
  464. package/src/sharddev/bake/portableBytes.ts +18 -0
  465. package/src/sharddev/bake/portableBytesMemo.ts +50 -0
  466. package/src/sharddev/bake/practiceCourse.ts +49 -0
  467. package/src/sharddev/bake/primitives.ts +96 -0
  468. package/src/sharddev/bake/props.ts +443 -0
  469. package/src/sharddev/bake/questPlacement.ts +98 -0
  470. package/src/sharddev/bake/rawTexture.ts +26 -0
  471. package/src/sharddev/bake/riderArms.ts +97 -0
  472. package/src/sharddev/bake/rig.ts +95 -0
  473. package/src/sharddev/bake/riggedHullRecipes.ts +40 -0
  474. package/src/sharddev/bake/signPlacements.ts +25 -0
  475. package/src/sharddev/bake/simplifier.ts +52 -0
  476. package/src/sharddev/bake/skinned.ts +312 -0
  477. package/src/sharddev/bake/slabChunks.ts +149 -0
  478. package/src/sharddev/bake/slabs.ts +263 -0
  479. package/src/sharddev/bake/source-loader.mjs +55 -0
  480. package/src/sharddev/bake/sourceMetadata.ts +54 -0
  481. package/src/sharddev/bake/species.ts +368 -0
  482. package/src/sharddev/bake/specimenCatalogue.ts +47 -0
  483. package/src/sharddev/bake/splatGround.ts +141 -0
  484. package/src/sharddev/bake/staticMaterials.ts +171 -0
  485. package/src/sharddev/bake/terrain.ts +195 -0
  486. package/src/sharddev/bake/texture.ts +33 -0
  487. package/src/sharddev/bake/textureWasm.ts +81 -0
  488. package/src/sharddev/bake/tileEncoder.ts +11 -0
  489. package/src/sharddev/bake/tileGrid.ts +62 -0
  490. package/src/sharddev/bake/v2Finite.ts +160 -0
  491. package/src/sharddev/bake/v2Fuel.ts +71 -0
  492. package/src/sharddev/bake/wholePartition.ts +74 -0
  493. package/src/sharddev/bake/wholePieceJoin.ts +147 -0
  494. package/src/sharddev/bake/world.ts +173 -0
  495. package/src/sharddev/bake/worldCollision.ts +128 -0
  496. package/src/sharddev/bake/worldGeometry.ts +237 -0
  497. package/src/sharddev/bake/worldGlb.ts +123 -0
  498. package/src/sharddev/bake/worldImage.ts +12 -0
  499. package/src/sharddev/bake/worldLod.ts +128 -0
  500. package/src/sharddev/bake/worldRows.ts +102 -0
  501. package/src/sharddev/bake/worldTextureMemo.ts +63 -0
  502. package/src/sharddev/bake/zstdBytesMemo.ts +52 -0
  503. package/src/sharddev/bake.ts +193 -0
  504. package/src/sharddev/bakePublication.ts +31 -0
  505. package/src/sharddev/behaviourSource.ts +94 -0
  506. package/src/sharddev/bin/wildshard.mjs +7 -0
  507. package/src/sharddev/blobBytes.ts +65 -0
  508. package/src/sharddev/blobs.ts +138 -0
  509. package/src/sharddev/bootInventory.ts +129 -0
  510. package/src/sharddev/bossProfiles.ts +18 -0
  511. package/src/sharddev/buildBehaviour.ts +77 -0
  512. package/src/sharddev/buildCacheMetrics.ts +17 -0
  513. package/src/sharddev/buildDecisionScripts.ts +122 -0
  514. package/src/sharddev/check.ts +117 -0
  515. package/src/sharddev/checkProject.ts +126 -0
  516. package/src/sharddev/cli.ts +191 -0
  517. package/src/sharddev/clientChannels.ts +169 -0
  518. package/src/sharddev/clientScripts.ts +10 -0
  519. package/src/sharddev/commons.ts +77 -0
  520. package/src/sharddev/commonsCosts.ts +11 -0
  521. package/src/sharddev/compileMovers.ts +11 -0
  522. package/src/sharddev/configBoundary.ts +6 -0
  523. package/src/sharddev/cookInput.ts +40 -0
  524. package/src/sharddev/crowds.ts +6 -0
  525. package/src/sharddev/decisionBindingMap.ts +11 -0
  526. package/src/sharddev/decisionScriptBindings.ts +117 -0
  527. package/src/sharddev/decisionScripts.ts +28 -0
  528. package/src/sharddev/decisionSource.ts +51 -0
  529. package/src/sharddev/dev.ts +113 -0
  530. package/src/sharddev/director.ts +26 -0
  531. package/src/sharddev/directorAbi.ts +77 -0
  532. package/src/sharddev/discoveryDocument.ts +97 -0
  533. package/src/sharddev/draft.ts +11 -0
  534. package/src/sharddev/eliteEntryRows.ts +29 -0
  535. package/src/sharddev/entries.ts +76 -0
  536. package/src/sharddev/entryReads.ts +73 -0
  537. package/src/sharddev/executeBundle.ts +55 -0
  538. package/src/sharddev/finds.ts +5 -0
  539. package/src/sharddev/formatJsonSchema.ts +3 -0
  540. package/src/sharddev/generationCache.ts +257 -0
  541. package/src/sharddev/generationRecipe.ts +94 -0
  542. package/src/sharddev/handwritten.ts +110 -0
  543. package/src/sharddev/immutable.ts +14 -0
  544. package/src/sharddev/interactions.ts +38 -0
  545. package/src/sharddev/kit/bakedGeometry.ts +16 -0
  546. package/src/sharddev/kit/geometryPack.ts +110 -0
  547. package/src/sharddev/ledger.ts +13 -0
  548. package/src/sharddev/looks/tileField.ts +67 -0
  549. package/src/sharddev/materialGraphFiles.ts +57 -0
  550. package/src/sharddev/materials.ts +574 -0
  551. package/src/sharddev/measure.ts +18 -0
  552. package/src/sharddev/modes.ts +115 -0
  553. package/src/sharddev/moverPrograms.ts +213 -0
  554. package/src/sharddev/movers.ts +75 -0
  555. package/src/sharddev/nativePopulationRows.ts +46 -0
  556. package/src/sharddev/newProject.ts +247 -0
  557. package/src/sharddev/noise.ts +54 -0
  558. package/src/sharddev/outputProduct.ts +188 -0
  559. package/src/sharddev/outputRuntime.ts +66 -0
  560. package/src/sharddev/performancePolicy.ts +18 -0
  561. package/src/sharddev/phasedBoss.ts +34 -0
  562. package/src/sharddev/physics.ts +194 -0
  563. package/src/sharddev/platformSections.ts +42 -0
  564. package/src/sharddev/plumbing.ts +8 -0
  565. package/src/sharddev/productOutput.ts +128 -0
  566. package/src/sharddev/project.ts +337 -0
  567. package/src/sharddev/projectCompilerIdentity.ts +94 -0
  568. package/src/sharddev/projectDecisions.ts +66 -0
  569. package/src/sharddev/projectEntryProof.ts +32 -0
  570. package/src/sharddev/projectGeneration.ts +219 -0
  571. package/src/sharddev/projectInputFiles.ts +47 -0
  572. package/src/sharddev/projectManifest.ts +108 -0
  573. package/src/sharddev/projectMap.ts +35 -0
  574. package/src/sharddev/projectOutput.ts +242 -0
  575. package/src/sharddev/projectPolicy.ts +17 -0
  576. package/src/sharddev/projectSections.ts +27 -0
  577. package/src/sharddev/questGraph.ts +25 -0
  578. package/src/sharddev/quests.ts +65 -0
  579. package/src/sharddev/random.ts +61 -0
  580. package/src/sharddev/refusals.ts +234 -0
  581. package/src/sharddev/reportCard.ts +13 -0
  582. package/src/sharddev/returnProjectionV2.ts +81 -0
  583. package/src/sharddev/rows.ts +192 -0
  584. package/src/sharddev/runtimeImports.ts +38 -0
  585. package/src/sharddev/runtimeMirrors.ts +39 -0
  586. package/src/sharddev/runtimePerformance.ts +38 -0
  587. package/src/sharddev/scene.ts +321 -0
  588. package/src/sharddev/sceneAnimation.ts +54 -0
  589. package/src/sharddev/sceneAudio.ts +64 -0
  590. package/src/sharddev/sceneDeclarations.ts +100 -0
  591. package/src/sharddev/sceneGraph.ts +139 -0
  592. package/src/sharddev/sceneTransform.ts +12 -0
  593. package/src/sharddev/schemaValidation.ts +61 -0
  594. package/src/sharddev/sections.ts +47 -0
  595. package/src/sharddev/shardSource.ts +59 -0
  596. package/src/sharddev/sourceReader.ts +26 -0
  597. package/src/sharddev/spawns.ts +38 -0
  598. package/src/sharddev/species/clips.ts +24 -0
  599. package/src/sharddev/species.ts +29 -0
  600. package/src/sharddev/speciesBrains.ts +19 -0
  601. package/src/sharddev/synth.ts +66 -0
  602. package/src/sharddev/test/compileDualScriptV2.ts +71 -0
  603. package/src/sharddev/test/compileSimV2.ts +21 -0
  604. package/src/sharddev/test/diskScriptScenario.ts +86 -0
  605. package/src/sharddev/test/scriptScenario.ts +249 -0
  606. package/src/sharddev/test/scriptSource.ts +12 -0
  607. package/src/sharddev/version.ts +4 -0
  608. package/src/sharddev/weapons/bowProfile.ts +20 -0
  609. package/src/sharddev/weapons/firearmRows.ts +11 -0
  610. package/src/sharddev/weapons/meleeProfile.ts +71 -0
  611. package/src/sharddev/weapons/thrownProfile.ts +10 -0
  612. package/src/sharddev/worldScenes.ts +308 -0
  613. package/src/sharddev/worldSource.ts +82 -0
  614. package/src/shards/_template/README.md +78 -0
  615. package/src/shards/_template/assets/2bf489fdb15f1734ddb4c4f32d500ec6da85c765ec7a4eb28dc6781160e7ec8c +0 -0
  616. package/src/shards/_template/assets/97ec4d8f75f5fa6239ee919444d6dc19fd35896bb305930c1f050ac6e0e0e6a6 +1 -0
  617. package/src/shards/_template/assets/a6a587a31327f936b1b04c05ade818c73fc8964260918662db43539465e27586 +0 -0
  618. package/src/shards/_template/assets/b4fbde0422e125b498c3dc8b9a5cc2516c8598f09e9d0e5f6b639b32f98179e6 +0 -0
  619. package/src/shards/_template/assets/bfa4dfc9c18979f904557ee8deab0058b8a399be10266f5fb1578b403f482fd4 +1 -0
  620. package/src/shards/_template/assets/ef3b7ff4fd22715771cb7d68a3977a903c5e7c3dc293542687d04b3ef3ace2cb +0 -0
  621. package/src/shards/_template/assets/f2db05998615ce1cb79ea96be32c168842eb6a2b34ec01feb86d36404603ee54 +0 -0
  622. package/src/shards/_template/assets/fef98ebb7fce6f66b26e78ac699e5c90f9bdcfaf8cabeb2b58125347eea8b4ab +0 -0
  623. package/src/shards/_template/behaviour/boss.as +39 -0
  624. package/src/shards/_template/behaviour/door.as +32 -0
  625. package/src/shards/_template/behaviour/hooks.json +129 -0
  626. package/src/shards/_template/behaviour/idle.as +75 -0
  627. package/src/shards/_template/behaviour/items.as +22 -0
  628. package/src/shards/_template/card/landscape.jpg +0 -0
  629. package/src/shards/_template/card/portrait.jpg +0 -0
  630. package/src/shards/_template/card/thumb.jpg +0 -0
  631. package/src/shards/_template/data/audio.json +45 -0
  632. package/src/shards/_template/data/bossDecision.json +83 -0
  633. package/src/shards/_template/data/budgets.json +70 -0
  634. package/src/shards/_template/data/card.json +281 -0
  635. package/src/shards/_template/data/clientScripts.json +987 -0
  636. package/src/shards/_template/data/creatures.json +65 -0
  637. package/src/shards/_template/data/director.json +39 -0
  638. package/src/shards/_template/data/encounters.json +96 -0
  639. package/src/shards/_template/data/items.json +172 -0
  640. package/src/shards/_template/data/layout.json +66 -0
  641. package/src/shards/_template/data/ledger.json +32 -0
  642. package/src/shards/_template/data/look.json +521 -0
  643. package/src/shards/_template/data/map.json +64 -0
  644. package/src/shards/_template/data/moves.json +16 -0
  645. package/src/shards/_template/data/placeholder.json +8 -0
  646. package/src/shards/_template/data/plumbing.json +32 -0
  647. package/src/shards/_template/data/quests.json +223 -0
  648. package/src/shards/_template/data/rows.json +423 -0
  649. package/src/shards/_template/data/skins.json +66 -0
  650. package/src/shards/_template/data/spawn.json +6 -0
  651. package/src/shards/_template/data/targets.json +150 -0
  652. package/src/shards/_template/data/text.json +12 -0
  653. package/src/shards/_template/data/ui.json +33 -0
  654. package/src/shards/_template/data/water.json +13 -0
  655. package/src/shards/_template/generators/behaviour.ts +34 -0
  656. package/src/shards/_template/generators/boss.ts +29 -0
  657. package/src/shards/_template/generators/buildOptions.ts +2 -0
  658. package/src/shards/_template/generators/cell.ts +224 -0
  659. package/src/shards/_template/generators/districts.ts +215 -0
  660. package/src/shards/_template/generators/farLook.ts +15 -0
  661. package/src/shards/_template/generators/generate.ts +27 -0
  662. package/src/shards/_template/generators/ground.ts +15 -0
  663. package/src/shards/_template/generators/kit.ts +69 -0
  664. package/src/shards/_template/generators/landscape.ts +59 -0
  665. package/src/shards/_template/generators/landscapeNoise.ts +62 -0
  666. package/src/shards/_template/generators/mapInputs.ts +10 -0
  667. package/src/shards/_template/generators/product.ts +100 -0
  668. package/src/shards/_template/generators/productOutput.ts +18 -0
  669. package/src/shards/_template/generators/props.ts +9 -0
  670. package/src/shards/_template/generators/templatePropsSource.ts +58 -0
  671. package/src/shards/_template/generators/terrain.ts +17 -0
  672. package/src/shards/_template/generators/world.ts +630 -0
  673. package/src/shards/_template/hero.json +10 -0
  674. package/src/shards/_template/look/entry-reads.json +20 -0
  675. package/src/shards/_template/manifest.json +281 -0
  676. package/src/shards/_template/shard.config.ts +10 -0
  677. package/src/shared/health.ts +10 -0
  678. package/src/tools/build-web.ts +59 -0
  679. package/src/tsconfig.json +30 -0
  680. package/src/web/app.tsx +53 -0
  681. package/src/web/index.html +12 -0
  682. package/src/web/main.tsx +10 -0
  683. package/src/web/tsconfig.json +13 -0
  684. package/tsconfig.author.json +23 -0
  685. package/tsconfig.commons.json +21 -0
  686. package/tsconfig.json +47 -0
  687. package/tsconfig.sharddev.json +20 -0
@@ -0,0 +1,191 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- The author CLI accepts filesystem project/output paths.
2
+ import { basename, dirname, resolve } from 'node:path';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- `prove` tells a project from a built product by its config file.
4
+ import { existsSync } from 'node:fs';
5
+ import { buildProject, readProjectAssets, validateProject } from './project';
6
+ import { ShardfileSchema, type Shardfile } from '@wildshard/engine/host/shardfile';
7
+ import { devProject } from './dev';
8
+ import { proveAuthorSimulation, measureSimulation, validateSimulation } from '@wildshard/engine/host/headless';
9
+ import { performanceReport, performanceReportLines, type PerformanceObservations } from './reportCard';
10
+ import { projectPerformancePolicy } from './performancePolicy';
11
+ import { readBoundedFile } from './sourceReader';
12
+ import { STILL_IMAGE_LIMITS } from '@wildshard/format/stillImage';
13
+ import { assetOverdraw } from './assets';
14
+ // oxlint-disable-next-line import/no-nodejs-modules -- The CLI releases its author server on termination.
15
+ import process from 'node:process';
16
+ import { buildBehaviourProject } from './buildBehaviour';
17
+ import { synthProject } from './synth';
18
+ import { formatJsonSchemas, schemaAt, schemaDeclaration } from '@wildshard/engine/host/formatJsonSchema';
19
+ import { decisionModuleContracts } from '@wildshard/format/scriptContract';
20
+ import { outputScriptAdmissionRows, validateOutputProduct } from './outputProduct';
21
+ import { locatedError } from './authorError';
22
+ import type { ProjectManifestSource } from './projectManifest';
23
+ import { templateNamed, writeShardRepo } from './newProject';
24
+ import { findShardSource, isHandwrittenSource, isRepoSource, shardOutputRoot } from './shardSource';
25
+ import { checkProject, readProofTape } from './checkProject';
26
+ import { checkLines } from './check';
27
+ import { refusalHint, refusalNote, type RefusalStep } from './refusals';
28
+
29
+ const unmeasured: PerformanceObservations = { scripts: { p95Micros: 0, maxMicros: 0, samples: 0 }, fuel: { p95: 0, max: 0, samples: 0 } };
30
+ function printReport(shard: Shardfile, observed: PerformanceObservations, policy: 'warn' | 'refuse'): void {
31
+ const report = performanceReport(shard, observed, policy);
32
+ for (const line of performanceReportLines(report)) console.info(line);
33
+ if (observed.scripts.samples > 0) console.info('script CPU estimate: 60 warm-up ticks; minimum p95 of three 60-tick windows; raw maxima and all fuel retained');
34
+ if (!report.pass) throw new Error('Performance report refused this shard');
35
+ }
36
+ async function admitBuild(shard: Shardfile, assets: ReadonlyMap<string, Uint8Array>, policy: 'warn' | 'refuse', sections: ReadonlyMap<string, unknown>): Promise<void> {
37
+ // Native hybrids need their trusted recipes for a meaningful proof; never invent a fake native measurement.
38
+ if (shard.runtime !== null) { printReport(shard, unmeasured, policy); return; }
39
+ printReport(shard, await measureSimulation(shard, assets, undefined, sections), policy);
40
+ }
41
+ /** SA3: writes a built folder's shard file (hero check against `source`, format and audio checks) and returns its path;
42
+ * scripts/wildshard.mjs gives it. `draftWarning: false` leaves the draft warning (J198) to the caller. */
43
+ export type ShardfileWriter = (folder: string, source: string, options?: { readonly draftWarning?: boolean }) => Promise<string>;
44
+ /** A refusal from the shard file step, named by its own rules (SA3), not build's source rules. */
45
+ class ShardfileRefusalError extends Error { override readonly name = 'ShardfileRefusalError'; }
46
+ async function writeShardfileOf(options: CliOptions, folder: string, source: string): Promise<void> {
47
+ try { await options.writeShardfile?.(folder, source); }
48
+ catch (error) { throw new ShardfileRefusalError(error instanceof Error ? error.message : String(error), { cause: error }); }
49
+ }
50
+ /** The verbs whose first operand is a shard source (or, for validate and prove, a built folder). */
51
+ const SOURCE_VERBS: ReadonlySet<string> = new Set(['check', 'synth', 'build', 'dev', 'validate', 'prove']);
52
+ interface CliOptions { readonly decisionLegacyLines?: number; readonly manifest?: ProjectManifestSource; readonly writeShardfile?: ShardfileWriter }
53
+ async function runCommand(given: readonly string[], options: CliOptions): Promise<void> {
54
+ // SA16 (J317): a verb given a repo finds its shard source at `src/` or its one `src/shards/<slug>/`.
55
+ const args = SOURCE_VERBS.has(given[0] ?? '') && given[1] !== undefined && !given[1].startsWith('--') ? [given[0] ?? '', findShardSource(given[1]), ...given.slice(2)] : given;
56
+ const [command, input, output, buildFlag] = args;
57
+ if (command === 'schema') {
58
+ if (buildFlag !== undefined) throw new Error('usage: wildshard schema [list|shardfile|root] [JSON-pointer]');
59
+ if (input === undefined || input === 'list') {
60
+ if (output !== undefined) throw new Error('schema list accepts no pointer');
61
+ console.info(JSON.stringify(['shardfile', ...Object.keys(formatJsonSchemas())], null, 2)); return;
62
+ }
63
+ const document = input === 'shardfile' ? schemaDeclaration(ShardfileSchema) : formatJsonSchemas()[input];
64
+ if (document === undefined) throw new Error(`Unknown schema root: ${input}`);
65
+ // Whole root sections accept their authored spelling; deeper paths retain RFC 6901 semantics.
66
+ const pointer = input === 'shardfile' && output !== undefined && /^\/[a-z][A-Za-z0-9]*$/u.test(output)
67
+ ? `/properties${output}` : output;
68
+ console.info(JSON.stringify(schemaAt(document, pointer), null, 2)); return;
69
+ }
70
+ if (command === 'check') {
71
+ const rest = args.slice(1), json = rest.includes('--json'), positional = rest.filter(value => !value.startsWith('--'));
72
+ if (positional.length === 0 || positional.length > 2 || rest.some(value => value.startsWith('--') && value !== '--json') || rest.filter(value => value === '--json').length > 1) throw new Error('usage: wildshard check <source> [folder] [--json]');
73
+ // --json: stdout carries the verdict document alone; everything the steps print goes to stderr.
74
+ // (scripts/wildshard.mjs moves log and debug for the whole run; the steps here log with info and warn.)
75
+ const saved = { info: console.info, warn: console.warn }, toError = console.error.bind(console);
76
+ if (json) Object.assign(console, { info: toError, warn: toError });
77
+ let result;
78
+ try { result = await checkProject(findShardSource(positional[0] ?? ''), positional[1], options); } finally { Object.assign(console, saved); }
79
+ process.stdout.write(json ? `${JSON.stringify(result, null, 2)}\n` : `${checkLines(result).join('\n')}\n`);
80
+ if (result.verdict === 'fail') process.exitCode = 1;
81
+ return;
82
+ }
83
+ if (input === undefined) throw new Error('usage: wildshard new <dir> | check <source> [folder] [--json] | synth <source> | build <source> [folder] [--shardfile-only|--folder-only] [--no-placeholders] [--output=<slug>] | build <source> --behaviour-only | validate <source|shard.json> | dev <source> [port] (wildshard --help lists them all)');
84
+ // SA16 (J314): a hand-written src/ (--template blender) has no shard.config.ts to build, synth or serve; check settles it.
85
+ if ((command === 'build' || command === 'synth' || command === 'dev') && isRepoSource(resolve(input)) && isHandwrittenSource(resolve(input))) throw new Error(`${command}: ${input} is a hand-written shard file (--template blender): run wildshard check on the repo, which settles and builds it`);
86
+ if (command === 'synth') {
87
+ if (output !== undefined) throw new Error('usage: wildshard synth <source>');
88
+ const result = await synthProject(resolve(input));
89
+ console.info(`synthesized ${result.path} (${result.hash})`); return;
90
+ }
91
+ if (command === 'new') {
92
+ // SA16: `--template <name>` (or `--template=<name>`) picks the template; a flag only, never a prompt; default sdk.
93
+ const newArguments = args.slice(2), names: string[] = [], templates: string[] = [];
94
+ let empty = 0, unknown = false;
95
+ for (let index = 0; index < newArguments.length; index += 1) {
96
+ const value = newArguments[index] ?? '';
97
+ if (value === '--empty') empty += 1;
98
+ else if (value === '--template') { const name = newArguments[index + 1]; if (name === undefined || name.startsWith('--')) unknown = true; else templates.push(name); index += 1; }
99
+ else if (value.startsWith('--template=')) templates.push(value.slice('--template='.length));
100
+ else if (value.startsWith('--')) unknown = true;
101
+ else names.push(value);
102
+ }
103
+ if (input.startsWith('--') || names.length > 1 || unknown || empty > 1 || templates.length > 1) throw new Error('usage: wildshard new <dir> [slug] [--template sdk|blender] [--empty]');
104
+ // An unknown template refuses here, before anything is written.
105
+ const template = templateNamed(templates[0] ?? 'sdk');
106
+ const slug = names[0] ?? input.split('/').reverse().find((part) => part !== '') ?? '';
107
+ writeShardRepo(resolve(input), slug, { template, empty: empty === 1 });
108
+ return;
109
+ }
110
+ if (command === 'dev') {
111
+ const port = output === undefined ? 0 : Number(output);
112
+ if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('dev port must be 0..65535');
113
+ const server = await devProject(resolve(input), { port, ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }) });
114
+ const close = (): void => { void server.close(); }; process.once('SIGINT', close); process.once('SIGTERM', close);
115
+ console.info(`wildshard dev: ${server.url}`); return;
116
+ }
117
+ if (command === 'build') {
118
+ if (output === '--behaviour-only' && (buildFlag === undefined || buildFlag === '--check')) {
119
+ const files = await buildBehaviourProject(resolve(input), { check: buildFlag === '--check' });
120
+ console.info(`built ${files.length} native behaviour outputs`); return;
121
+ }
122
+ // A flag straight after the project is a flag, not the output folder.
123
+ const folder = output?.startsWith('--') === true ? undefined : output;
124
+ const flags = args.slice(folder === undefined ? 2 : 3), mapSourceHash = flags.find(flag => flag.startsWith('--generated-map-tiles-hash='))?.slice(27), mapPath = flags.find(flag => flag.startsWith('--map='))?.slice(6), tilesHash = flags.find(flag => flag.startsWith('--map-tiles-hash='))?.slice(17), selected = flags.find(flag => flag.startsWith('--output='))?.slice(9);
125
+ // SA3: --shardfile-only skips the client; --folder-only also skips the shard file, for build-shards, whose folders are
126
+ // cached and prepared before anything tars them. --product-only keeps its old meaning: --folder-only.
127
+ const folderOnly = flags.includes('--folder-only') || flags.includes('--product-only'), noClient = folderOnly || flags.includes('--shardfile-only');
128
+ const unknownFlag = flags.find(flag => flag !== '--shardfile-only' && flag !== '--folder-only' && flag !== '--product-only' && flag !== '--no-placeholders' && flag !== '--format=2' && flag !== '--copy-runtime' && !flag.startsWith('--map=') && !flag.startsWith('--map-tiles-hash=') && !flag.startsWith('--output=') && !flag.startsWith('--generated-map-tiles-hash='));
129
+ if (unknownFlag !== undefined) throw new Error(`unknown build flag: ${unknownFlag}`);
130
+ if (flags.filter(flag => flag.startsWith('--output=')).length > 1 || flags.length !== new Set(flags).size || flags.filter(flag => flag.startsWith('--map=')).length > 1 || flags.filter(flag => flag.startsWith('--map-tiles-hash=')).length > 1 || flags.filter(flag => flag.startsWith('--generated-map-tiles-hash=')).length > 1 || mapSourceHash !== undefined && mapPath !== undefined || ((mapPath === undefined) !== (tilesHash === undefined))) throw new Error('unknown or incomplete build map flag');
131
+ const map = mapPath === undefined || tilesHash === undefined ? undefined : { bytes: readBoundedFile(resolve(mapPath), STILL_IMAGE_LIMITS.bytes), tilesHash };
132
+ const shard = await buildProject(resolve(input), folder === undefined ? undefined : resolve(folder), { outputFormat:2, ...(selected === undefined ? {} : { output: selected }), ...(options.decisionLegacyLines === undefined ? {} : { decisionLegacyLines: options.decisionLegacyLines }), ...(options.manifest === undefined ? {} : { manifest: options.manifest }), copyRuntime: flags.includes('--copy-runtime'), ...(noClient ? { client: null } : {}), ...(map === undefined ? {} : { map }), ...(mapSourceHash === undefined ? {} : { mapSourceHash }), placeholders: !flags.includes('--no-placeholders'), admit: admitBuild }); console.info(`built ${shard.identity.slug} v${shard.version}`);
133
+ if (!folderOnly) await writeShardfileOf(options, folder === undefined ? resolve(shardOutputRoot(resolve(input)), 'public/shardfiles', shard.identity.slug) : resolve(folder), resolve(input));
134
+ return;
135
+ }
136
+ if (command === 'prove') {
137
+ if (input.endsWith('.json') && basename(input) !== 'shard.json') throw new Error('prove requires a format-2 shard.json or shard source');
138
+ if (output === undefined || buildFlag !== undefined) throw new Error('usage: wildshard prove <source|shard.json> <proof.json>');
139
+ const built = input.endsWith('.json') || !existsSync(resolve(input, 'shard.config.ts'));
140
+ const { shard, assets } = built
141
+ ? validateOutputProduct(resolve(input.endsWith('.json') ? dirname(input) : input))
142
+ : await readProjectAssets(resolve(input), undefined, options.manifest, options);
143
+ const plan = readProofTape(resolve(output));
144
+ console.info(JSON.stringify(await proveAuthorSimulation(shard, assets, plan), null, 2)); return;
145
+ }
146
+ if (command === 'validate') {
147
+ if (input.endsWith('.json') && basename(input) !== 'shard.json') throw new Error('validate requires a format-2 shard.json or shard source');
148
+ const folder=resolve(input.endsWith('.json') ? dirname(input) : input);
149
+ if (input.endsWith('.json') || existsSync(resolve(folder, 'shard.json'))) {
150
+ // P1-F3 (a): format validation, @wildshard/format/productValidation alone (schema, inventory, hashes, budgets, admission rows).
151
+ const checked = validateOutputProduct(folder);
152
+ // P1-F3 (b): execution proof. G491: validation.json contains static build evidence, never authority
153
+ // for current script CPU. Execute the admitted bytes again on this host.
154
+ await admitBuild(checked.shard, checked.assets, checked.shard.runtime === null ? 'refuse' : 'warn', checked.sections);
155
+ console.info(`validated ${checked.shard.identity.slug}: format 2 inventory, byte kinds and section schemas`); return;
156
+ }
157
+ const { shard, assets, output: extensions } = await readProjectAssets(resolve(input), undefined, options.manifest, options);
158
+ const scripts = outputScriptAdmissionRows(extensions.platform), contracts = decisionModuleContracts(scripts, shard.files);
159
+ const project = resolve(input), policy = projectPerformancePolicy(project, shard);
160
+ validateProject(shard, assets, project, scripts);
161
+ let layers = 0, blended = 0, masked = 0;
162
+ const kinds = new Map(shard.files.map((file) => [file.hash, file.kind]));
163
+ for (const [hash, bytes] of assets) {
164
+ const kind = kinds.get(hash) ?? 'commons';
165
+ const estimate = assetOverdraw(kind, bytes, kind === 'wasm' ? contracts.get(hash) ?? { abi: 0 } : undefined); layers += estimate.layers; blended += estimate.blendedLayers; masked += estimate.maskedLayers;
166
+ }
167
+ console.info(`advisory asset raster layers: ${layers.toFixed(2)} total, ${blended.toFixed(2)} blended, ${masked.toFixed(2)} alpha-tested (primitive bounds; before culling/occlusion, not measured screen overdraw)`);
168
+ if (shard.runtime !== null) { printReport(shard, unmeasured, policy); console.info(`validated ${shard.identity.slug} v${shard.version}: native execution/entries UNMEASURED (trusted browser proof required)`); return; }
169
+ const proof = await validateSimulation(shard, assets);
170
+ printReport(shard, proof, policy);
171
+ console.info(`validated ${shard.identity.slug} v${shard.version}: ${proof.ticks} sim ticks, ${proof.lanes} edge lanes, ${proof.steps} capsule steps`);
172
+ console.info(`advisory tick timing (${proof.timing.samples} samples): median ${proof.timing.medianMicros.toFixed(1)} us, max ${proof.timing.maxMicros.toFixed(1)} us, declared ${shard.serverBudget.tickMicros} us`);
173
+ if (proof.timing.medianMicros > shard.serverBudget.tickMicros) console.warn('advisory: measured tick median exceeds the declared runtime budget; host load is not an admission refusal');
174
+ return;
175
+ }
176
+ throw new Error('unknown wildshard command');
177
+ }
178
+ /** The step a verb's refusal comes from (SA21): `dev` and `synth` build. */
179
+ const STEPS: Readonly<Record<string, RefusalStep>> = { new: 'new', validate: 'validate', prove: 'prove' };
180
+ /** The refusal with its rule, fix and GUIDE.md link on a second line; the first line stays the refusing code's words. */
181
+ function authorRefusal(command: string | undefined, error: unknown): unknown {
182
+ const located = locatedError(error);
183
+ const message = located instanceof Error ? located.message : String(located);
184
+ const step = error instanceof ShardfileRefusalError ? 'shardfile' : command !== undefined && Object.hasOwn(STEPS, command) ? STEPS[command] : undefined;
185
+ const hint = refusalHint(refusalNote(step ?? 'build', message));
186
+ return new Error(`${message}\n ${hint}`, { cause: error });
187
+ }
188
+ /** Run the author CLI; returns only after validation/build completes. */
189
+ export async function runCli(args: readonly string[], options: CliOptions = {}): Promise<void> {
190
+ try { await runCommand(args, options); } catch (error) { throw authorRefusal(args[0], error); }
191
+ }
@@ -0,0 +1,169 @@
1
+ import * as v from 'valibot';
2
+ import { CLIENT_CHANNEL_LIMITS, NumericPoseSchema, NumericPoseInputSchema, ClientChannelsSchema, parseClientChannelInputs, parseClientChannels, type ClientChannelProgram, type ClientChannelProperty } from '@wildshard/format/clientChannels';
3
+
4
+ type Node = ClientChannelProgram['nodes'][number];
5
+ type Unary = Extract<Node, { a: number }>['op'];
6
+ type Binary = Exclude<Extract<Node, { b: number }>['op'], 'hypot3'>;
7
+ /** Readable authoring of bounded straight-line visual expressions; build output is ordinary format data. */
8
+ export class ClientChannels {
9
+ private readonly nodes: Node[] = [];
10
+ private readonly reads: string[] = [];
11
+ private readonly locals: NonNullable<ClientChannelProgram['locals']> = [];
12
+ private readonly bindings: NonNullable<ClientChannelProgram['bindings']> = [];
13
+ private readonly connectorRows: NonNullable<ClientChannelProgram['connectors']> = [];
14
+ private geometryRow: ClientChannelProgram['geometry'];
15
+ private promptRow: ClientChannelProgram['prompt'];
16
+ private moverId: string | undefined;
17
+ private readonly channels: ClientChannelProgram['channels'] = [];
18
+ private readonly id: string;
19
+ constructor(id: string) { this.id = id; }
20
+ private append(node: Node): number { const at = this.nodes.length; this.nodes.push(node); return at; }
21
+ /** Literal scalar, retained exactly as authored. */
22
+ constant(value: number): number { return this.append({ op: 'constant', value }); }
23
+ /** Continuous presentation time or the caller's original frame interval. */
24
+ clock(value: 'time' | 'delta'): number { return this.append({ op: 'clock', value }); }
25
+ /** Name an explicitly copied numeric observation; there is no state object or write port. */
26
+ read(name: string): number {
27
+ let index = this.reads.indexOf(name); if (index < 0) { index = this.reads.length; this.reads.push(name); }
28
+ return this.append({ op: 'read', index });
29
+ }
30
+ /** Read a private previous-frame scalar, initially a literal or a copied first-frame observation. */
31
+ local(initial: number | { readonly read: string }): number {
32
+ let seed: NonNullable<ClientChannelProgram['locals']>[number]['initial'];
33
+ if (typeof initial === 'number') seed = { op: 'constant', value: initial };
34
+ else {
35
+ let index = this.reads.indexOf(initial.read);
36
+ if (index < 0) { index = this.reads.length; this.reads.push(initial.read); }
37
+ seed = { op: 'read', index };
38
+ }
39
+ const index = this.locals.length, at = this.append({ op: 'local', index });
40
+ this.locals.push({ initial: seed, next: at });
41
+ return at;
42
+ }
43
+ /** Commit a finite node to this private slot after every frame calculation succeeds. */
44
+ retain(local: number, next: number): void {
45
+ const node = this.nodes[local];
46
+ if (node?.op !== 'local') throw new Error('Expected a private client slot');
47
+ const slot = this.locals[node.index];
48
+ if (slot === undefined) throw new Error('Missing private client slot');
49
+ slot.next = next;
50
+ }
51
+ /** One admitted unary arithmetic/trigonometric operation. */
52
+ unary(op: Exclude<Unary, Binary | 'hypot3' | 'sample'>, a: number): number { return this.append({ op, a }); }
53
+ /** One admitted binary arithmetic/trigonometric operation, preserving operand order. */
54
+ binary(op: Binary, a: number, b: number): number { return this.append({ op, a, b }); }
55
+ /** The original three-axis Math.hypot operation, without nested binary rounding. */
56
+ hypot3(a: number, b: number, c: number): number { return this.append({ op: 'hypot3', a, b, c }); }
57
+ /** Sample bounded ordered keys, retaining the original linear or smoothstep arithmetic. */
58
+ sample(a: number, keys: readonly (readonly [number, number])[], interpolation: 'linear' | 'smoothstep'): number {
59
+ return this.append({ op: 'sample', a, keys: keys.map(key => [key[0], key[1]]), interpolation });
60
+ }
61
+ /** Bind a declared fast kernel to private geometry, retaining the caller's original scalar arithmetic. */
62
+ deformTube(row: NonNullable<ClientChannelProgram['geometry']>): void { this.geometryRow = structuredClone(row); }
63
+ /** Declare bounded exact connector poses on borrowed private objects or existing instance slots. */
64
+ connector(row: NonNullable<ClientChannelProgram['connectors']>[number]): void { this.connectorRows.push(structuredClone(row)); }
65
+ /** Declare a normal input prompt; channel evaluation never dispatches its separate trusted action. */
66
+ prompt(row: NonNullable<ClientChannelProgram['prompt']>): void { this.promptRow = structuredClone(row); }
67
+ /** Select already evaluated scalar nodes without a call, loop or side effect. */
68
+ select(test: number, yes: number, no: number): number { return this.append({ op: 'select', test, yes, no }); }
69
+ /** Bind a scalar result to one private visual property. */
70
+ output(property: ClientChannelProperty, value: number): void { this.channels.push({ property, value }); }
71
+ /** Bind a visual channel to a named private scene object; rotations may specify their original Euler order. */
72
+ bind(property: NonNullable<ClientChannelProgram['bindings']>[number]['property'], target: string,
73
+ order?: NonNullable<ClientChannelProgram['bindings']>[number]['order']): void {
74
+ this.bindings.push({ property, target, ...(order === undefined ? {} : { order }) });
75
+ }
76
+ /** Observe a declared mover's copied pose/fields; this source has no additional clock or private recurrence. */
77
+ fromMover(id: string): void { this.moverId = id; }
78
+ /** Validate and detach the authored program. */
79
+ build(): ClientChannelProgram {
80
+ const result = parseClientChannels([{ id: this.id, reads: this.reads, nodes: this.nodes, channels: this.channels, ...(this.geometryRow === undefined ? {} : { geometry: this.geometryRow }), ...(this.connectorRows.length === 0 ? {} : { connectors: this.connectorRows }), ...(this.locals.length === 0 ? {} : { locals: this.locals }), ...(this.bindings.length === 0 ? {} : { bindings: this.bindings }), ...(this.moverId === undefined ? {} : { mover: this.moverId }), ...(this.promptRow === undefined ? {} : { prompt: this.promptRow }) }])[0];
81
+ if (result === undefined) throw new Error('Missing client channel program'); return result;
82
+ }
83
+ }
84
+
85
+ /** One numeric output of a group: a private root's field (`[field]` or `[field, axis]`) and the expression that fills it,
86
+ * reading owner fields by path (`read(owner, path)` declares the input binding). */
87
+ export interface NumericChannelOutput {
88
+ readonly target: string;
89
+ readonly path: readonly [string] | readonly [string, string];
90
+ readonly expr: (b: ClientChannels, read: (owner: string, path: readonly (string | number)[]) => number) => number;
91
+ }
92
+ const NUMERIC_PROPERTIES: readonly ClientChannelProperty[] = ['x', 'y', 'z', 'yaw', 'pitch', 'roll', 'scaleX', 'scaleY', 'scaleZ', 'value', 'turn', 'visible'];
93
+ /** A numeric group's outputs as programs of at most twelve channels each (`<prefix>.<n>`), every read a declared owner
94
+ * path: build-time authoring for `@wildshard/engine/game/plugin/channelPrograms` (a sky's frame, a weather's look). */
95
+ export function numericChannelPrograms(prefix: string, group: string, outputs: readonly NumericChannelOutput[]): ClientChannelProgram[] {
96
+ const programs: ClientChannelProgram[] = [];
97
+ for (let at = 0; at < outputs.length; at += NUMERIC_PROPERTIES.length) {
98
+ const b = new ClientChannels(`${prefix}.${String(programs.length)}`), inputs = new Map<string, { input: string; owner: string; path: (string | number)[] }>();
99
+ const read = (owner: string, path: readonly (string | number)[]): number => {
100
+ const input = [owner, ...path].join('.');
101
+ inputs.set(input, { input, owner, path: [...path] });
102
+ return b.read(input);
103
+ };
104
+ const rows = outputs.slice(at, at + NUMERIC_PROPERTIES.length).map((out, i) => {
105
+ const property = NUMERIC_PROPERTIES[i];
106
+ if (property === undefined) throw new Error('numeric channel property overflow');
107
+ b.output(property, out.expr(b, read));
108
+ return { property, target: out.target, path: [...out.path] };
109
+ });
110
+ const program = parseClientChannels([{ ...b.build(), numeric: { group, outputs: rows, inputs: [...inputs.values()], restoreOnly: [] } }])[0];
111
+ if (program === undefined) throw new Error('Missing numeric channel program');
112
+ programs.push(program);
113
+ }
114
+ return programs;
115
+ }
116
+
117
+ /** Compile creature-only borrowed observations into finite pose inputs. The
118
+ * authoring paths never cross the admitted wire; the original node and read
119
+ * order, numeric names and output arithmetic stay byte-for-byte unchanged. */
120
+ export function creaturePoseRows(input: unknown): v.InferOutput<typeof NumericPoseSchema> {
121
+ const source = v.parse(v.looseObject({ programs: ClientChannelsSchema, scalars: NumericPoseSchema.entries.scalars }), input);
122
+ const programs = source.programs.map(program => {
123
+ const numeric = program.numeric;
124
+ if (numeric === undefined) throw new Error('Creature authoring requires numeric inputs');
125
+ const inputs = parseClientChannelInputs(numeric.inputs).map(row => {
126
+ const [first, second] = row.path;
127
+ let value: unknown;
128
+ if (row.owner === 'frame' && row.path.length === 1) value = { kind: 'frame', field: first };
129
+ else if (row.owner === 'frame' && row.path.length === 2 && (first === 'mem' || first === 'dims') && typeof second === 'string')
130
+ value = { kind: 'scalar', record: first === 'mem' ? 'memory' : 'dimensions', name: second };
131
+ else if (row.owner === 'scalars' && row.path.length === 1) value = { kind: 'scalar', record: 'declared', name: first };
132
+ else if (row.owner === 'look' && row.path.length === 1) value = { kind: 'look', axis: first };
133
+ else if ((row.owner.startsWith('joint.') || row.owner.startsWith('read.joint.')) && row.path.length === 2)
134
+ value = { kind: 'joint', joint: row.owner.slice(row.owner.startsWith('read.') ? 11 : 6), transform: first, axis: second };
135
+ else throw new Error(`Unsupported creature input: ${row.owner}`);
136
+ if (typeof value !== 'object' || value === null) throw new Error('Missing creature input');
137
+ return v.parse(NumericPoseInputSchema, { ...value, input: row.input });
138
+ });
139
+ return { ...program, numeric: { ...numeric, inputs } };
140
+ });
141
+ return v.parse(NumericPoseSchema, { ...source, programs });
142
+ }
143
+
144
+ /** The defining channel bounds used by bounded source recipe packers. */
145
+ export function clientChannelLimits(): typeof CLIENT_CHANNEL_LIMITS { return CLIENT_CHANNEL_LIMITS; }
146
+
147
+ /** Offline smoothing and floor observations used to author creature channels. */
148
+ export interface CreatureSurfaceFrame {
149
+ smooth: { input: string; output: string; rate: number; initial: number | null }[];
150
+ floor: { field: string; lift: string; death: string; delay: number; rate: number };
151
+ look: [number, number, number];
152
+ group: string;
153
+ }
154
+ /** Admit the complete ordered frame inputs before compiling channel expressions.
155
+ * Defaults stay caller-owned; this only validates them and the observation-bank
156
+ * ceiling. No animation state or frame owner is constructed. */
157
+ export function creatureSurfaceFrame(input: unknown, defaults: unknown, observationPrograms: unknown): CreatureSurfaceFrame {
158
+ const number = v.pipe(v.number(), v.finite());
159
+ const key = v.pipe(v.string(), v.minLength(1), v.maxLength(96),
160
+ v.check(value => !['__proto__', 'prototype', 'constructor'].includes(value)));
161
+ const frame = v.parse(v.object({
162
+ smooth: v.pipe(v.array(v.object({ input: key, output: key, rate: number, initial: v.nullable(number) })), v.maxLength(16)),
163
+ floor: v.object({ field: key, lift: key, death: key, delay: number, rate: number }),
164
+ look: v.tuple([number, number, number]), group: key,
165
+ }), input);
166
+ v.parse(v.record(key, number), defaults);
167
+ v.parse(v.pipe(v.array(v.unknown()), v.maxLength(32)), observationPrograms);
168
+ return frame;
169
+ }
@@ -0,0 +1,10 @@
1
+ import * as v from 'valibot';
2
+ import { ClientScriptsSchema as schema, parseClientScripts as parse, clientScriptViewCost as viewCost, type ShardClientScripts as Data } from '@wildshard/format/clientScripts';
3
+ /** Strict presentation-only module/target declarations, with bounded pose and particle recipes. */
4
+ export const ClientScriptsSchema: v.SchemaWithPipe<readonly [typeof schema]> = v.pipe(schema);
5
+ /** Data-only author contract for isolated client scripts. */
6
+ export type ShardClientScripts = Data;
7
+ /** Parse bounded visual commands and copied state-read selections. */
8
+ export function parseClientScripts(input: unknown): Data { return parse(input); }
9
+ /** Exact bounded particle-pool resident cost to include in the authored library budget. */
10
+ export function clientScriptViewCost(data: Data): ReturnType<typeof viewCost> { return viewCost(data); }
@@ -0,0 +1,77 @@
1
+ import * as v from 'valibot';
2
+ import { assetCost, type AssetCost } from './assets';
3
+ import { encodeCanonicalJson } from './immutable';
4
+ import { ownAssetBytes } from './assetOwner';
5
+ import { SHARDFILE_ADMISSION_LIMITS as limits } from './admission';
6
+ import type { CommonsCosts } from './commonsCosts';
7
+
8
+ const id = v.pipe(v.string(), v.minLength(1), v.maxLength(128), v.regex(/^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)*$/u));
9
+ const version = v.pipe(v.string(), v.maxLength(32), v.regex(/^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)$/u));
10
+ const kind: v.PicklistSchema<["binary", "glb", "ktx2", "audio"], undefined> = v.picklist(['binary', 'glb', 'ktx2', 'audio']);
11
+ const metadata = v.strictObject({ id, kind, credit: v.pipe(v.string(), v.minLength(1), v.maxLength(4096)), licence: v.pipe(v.string(), v.minLength(1), v.maxLength(128)) });
12
+
13
+ /** One build-time pack input; only its copied bytes and validated metadata enter a product. */
14
+ export interface CommonsAsset {
15
+ id: string; kind: v.InferOutput<typeof kind>; bytes: Uint8Array; credit: string; licence: string;
16
+ }
17
+ /** A pinned author-tool pack; runtime code never imports or executes it. */
18
+ export interface CommonsPack { id: string; version: string; entries: readonly CommonsAsset[] }
19
+ /** Actual byte-derived cost and provenance of a stable catalogue entry. */
20
+ export interface CommonsEntry {
21
+ id: string; pack: string; packVersion: string; hash: string; kind: CommonsAsset['kind'];
22
+ wire: number; cost: AssetCost; credit: string; licence: string;
23
+ }
24
+ /** Version zero catalogue data, independent of package installation paths and build time. */
25
+ export interface CommonsCatalogue { format: 'wildshard.commons'; version: 0; entries: readonly CommonsEntry[] }
26
+ /** Owned build output; aliases with identical bytes share one hash-named asset. */
27
+ export interface BuiltCommons { catalogue: CommonsCatalogue; json: string; assets: ReadonlyMap<string, Uint8Array> }
28
+
29
+ /** Compile bounded packs deterministically, deriving costs from actual bytes instead of declared numbers. */
30
+ export function buildCommons(packs: readonly CommonsPack[]): BuiltCommons {
31
+ if (packs.length > limits.files) throw new Error('Commons packs exceed admission cap');
32
+ const entries: CommonsEntry[] = [], assets = new Map<string, Uint8Array>(), hashes = new Map<string, CommonsAsset['kind']>(), ids = new Set<string>(), packIds = new Set<string>();
33
+ let wire = 0;
34
+ for (const pack of packs) {
35
+ v.parse(id, pack.id); v.parse(version, pack.version);
36
+ if (packIds.has(pack.id)) throw new Error('Duplicate commons pack'); packIds.add(pack.id);
37
+ if (entries.length + pack.entries.length > limits.files) throw new Error('Commons entries exceed admission cap');
38
+ for (const input of pack.entries) {
39
+ const row = v.parse(metadata, { id: input.id, kind: input.kind, credit: input.credit, licence: input.licence });
40
+ const key = `${pack.id}/${row.id}`; v.parse(id, key);
41
+ if (ids.has(key)) throw new Error('Duplicate commons entry'); ids.add(key);
42
+ if (input.bytes.byteLength > limits.wireBytes) throw new Error('Commons wire exceeds admission cap');
43
+ const owned = ownAssetBytes(input.bytes), hash = owned.hash, previous = hashes.get(hash);
44
+ if (previous !== undefined && previous !== row.kind) throw new Error('Commons hash has conflicting kinds');
45
+ if (!assets.has(hash)) {
46
+ wire += input.bytes.byteLength; if (wire > limits.wireBytes) throw new Error('Commons total wire exceeds admission cap');
47
+ assets.set(hash, owned.bytes); hashes.set(hash, row.kind);
48
+ }
49
+ const bytes = assets.get(hash); if (bytes === undefined) throw new Error('Missing owned commons bytes');
50
+ entries.push({ id: key, pack: pack.id, packVersion: pack.version, hash, kind: row.kind, wire: bytes.byteLength, cost: assetCost(row.kind, bytes), credit: row.credit, licence: row.licence });
51
+ }
52
+ }
53
+ entries.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
54
+ const catalogue: CommonsCatalogue = { format: 'wildshard.commons', version: 0, entries };
55
+ return { catalogue, json: encodeCanonicalJson(catalogue), assets: new Map([...assets].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) };
56
+ }
57
+
58
+ /** Emit unique manifest requirements from selected pinned bytes, never copied author cost declarations. */
59
+ export function commonsRequirements(built: BuiltCommons, entryIds: readonly string[]): { commons: string[]; commonsWire: Record<string, number>; commonsCosts: CommonsCosts } {
60
+ if (entryIds.length > limits.files) throw new Error('Commons selection exceeds admission cap');
61
+ const entries = new Map(built.catalogue.entries.map(entry => [entry.id, entry])), selected = new Map<string, { wire: number; cost: AssetCost }>();
62
+ for (const entryId of entryIds) {
63
+ const entry = entries.get(entryId); if (entry === undefined) throw new Error(`Unknown commons entry: ${entryId}`);
64
+ if (selected.has(entry.hash)) continue;
65
+ if (selected.size >= limits.commons) throw new Error('Commons hashes exceed admission cap');
66
+ const bytes = built.assets.get(entry.hash);
67
+ if (bytes === undefined || ownAssetBytes(bytes).hash !== entry.hash) throw new Error('Pinned commons bytes differ from catalogue hash');
68
+ selected.set(entry.hash, { wire: bytes.length, cost: assetCost(entry.kind, bytes) });
69
+ }
70
+ const commons = [...selected.keys()].sort();
71
+ const commonsWire: Record<string, number> = {}, commonsCosts: CommonsCosts = {};
72
+ for (const hash of commons) {
73
+ const entry = selected.get(hash); if (entry === undefined) throw new Error('Missing pinned commons selection');
74
+ commonsWire[hash] = entry.wire; commonsCosts[hash] = entry.cost;
75
+ }
76
+ return { commons, commonsWire, commonsCosts };
77
+ }
@@ -0,0 +1,11 @@
1
+ import * as v from 'valibot';
2
+ import { CommonsCostSchema as costSchema, CommonsCostsSchema as costsSchema, assertCommonsCosts as assertCosts, type CommonsCosts as Costs } from '@wildshard/format/commonsCosts';
3
+
4
+ /** Pinned commons bytes declare exact decoded/GPU bytes and triangle/draw counts as nonnegative safe integers. */
5
+ export const CommonsCostSchema: v.SchemaWithPipe<readonly [typeof costSchema]> = v.pipe(costSchema);
6
+ /** Bounded hash-addressed metadata for at most 1024 distinct required commons assets. */
7
+ export const CommonsCostsSchema: v.SchemaWithPipe<readonly [typeof costsSchema]> = v.pipe(costsSchema);
8
+ /** Parsed exact residency and geometry costs keyed by the pinned commons content hash. */
9
+ export type CommonsCosts = Costs;
10
+ /** Refuse missing, extra or malformed cost rows before reading any immutable asset. */
11
+ export function assertCommonsCosts(commons: readonly string[], input: unknown): Costs { return assertCosts(commons, input); }
@@ -0,0 +1,11 @@
1
+ import { compileScript } from './bake/compileScript';
2
+ import { moverProgram } from './moverPrograms';
3
+ import { hashImmutableBytes } from './immutable';
4
+ import { MOVER_DRIVER_MODULES } from '@wildshard/format/moverMotion';
5
+
6
+ /** Compile and meter a fixed row driver; refuse any accidental change to its admitted continuation ABI. */
7
+ export async function compileMoverDriver(kind: 'ride' | 'hinge' | 'waves' | 'clip'): Promise<Uint8Array> {
8
+ const program = moverProgram(kind), bytes = await compileScript(program.source, { maximumPages: 1, sources: program.sources });
9
+ if (hashImmutableBytes(bytes) !== MOVER_DRIVER_MODULES[kind]) throw new Error('Fixed mover driver ABI changed');
10
+ return bytes;
11
+ }
@@ -0,0 +1,6 @@
1
+ /** Diagnose executable file/compiler dependencies before a bundled declaration is evaluated as a data URL. */
2
+ export function assertConfigBoundary(imports: readonly string[]): void {
3
+ const generatorImports = imports.filter(name =>
4
+ /^(?:node:)?fs(?:\/promises)?$/u.test(name) || name === 'node:module' || name === 'binaryen' || name.startsWith('assemblyscript'));
5
+ if (generatorImports.length > 0) throw new Error(`shard.config.ts must use injected build capabilities for file access (${generatorImports.join(', ')}). Read declared inputs through ctx.cached; script compiler dependencies require a separate build adapter.`);
6
+ }
@@ -0,0 +1,40 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- The author build reads the shard's folder and public/.
2
+ import { existsSync, readFileSync } from 'node:fs';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- The author build reads the shard's folder and public/.
4
+ import { resolve } from 'node:path';
5
+ import * as v from 'valibot';
6
+ import { AudioWaiverSchema, type AudioWaiver } from '@wildshard/format/audioWaiver';
7
+
8
+ /** C0 (J137): what a product carries so it stands alone. The list is the shard's `mounts.json`, per output
9
+ * (`scripts/record-shard-mounts.mjs`); the bytes stay in `public/` until the shard's own repo holds them (P5). */
10
+ export interface CookInput {
11
+ readonly mounts: readonly {readonly url: string; readonly bytes: Uint8Array}[];
12
+ readonly packs?: 'fence';
13
+ readonly fence?: readonly string[];
14
+ /** AUDIO AU5: this output's row of the source's `audio-waiver.json`, carried to `admission.audioWaiver`. */
15
+ readonly audioWaiver?: AudioWaiver;
16
+ }
17
+
18
+ const MountsSchema = v.strictObject({version: v.literal(1), outputs: v.record(v.string(), v.array(v.string()))});
19
+ const FenceReadsSchema = v.strictObject({version: v.literal(1), files: v.array(v.string())});
20
+ const PacksSetSchema = v.strictObject({version: v.literal(1), set: v.literal('fence')});
21
+ /** AUDIO AU5: a dated waiver per output slug for a shard over the audio budget's red line (meta AUDIO-PLAN). */
22
+ const AudioWaiversSchema = v.strictObject({version: v.literal(1), waivers: v.pipe(v.array(AudioWaiverSchema), v.check(rows => new Set(rows.map(row => row.shard)).size === rows.length, 'one audio waiver per shard'))});
23
+
24
+ /** The waiver row naming `slug` in the shard source's `audio-waiver.json`, if any. */
25
+ function readAudioWaiver(file: unknown, slug: string): AudioWaiver | undefined {
26
+ return file === undefined ? undefined : new Map(v.parse(AudioWaiversSchema, file).waivers.map(row => [row.shard, row] as const)).get(slug);
27
+ }
28
+
29
+ /** Read a project's cook input for one output, or nothing for a project with none. D5: the fence and packs lists are
30
+ * optional author data; a listed mount missing from `public/` refuses, because that file is what the shard stands on. */
31
+ export function readCookInput(project: string, slug: string): CookInput | undefined {
32
+ const json = (name: string): unknown => { const file = resolve(project, name); return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined; };
33
+ const list = json('mounts.json'), fence = json('fence-reads.json'), packs = json('packs-set.json'), audioWaiver = readAudioWaiver(json('audio-waiver.json'), slug);
34
+ const urls = list === undefined ? [] : v.parse(MountsSchema, list).outputs[slug] ?? [];
35
+ const publicRoot = resolve(project, '../../../public');
36
+ const mounts = urls.map(url => ({url, bytes: readFileSync(resolve(publicRoot, url.slice(1)))}));
37
+ const set = packs === undefined ? undefined : v.parse(PacksSetSchema, packs).set;
38
+ if (mounts.length === 0 && fence === undefined && set === undefined && audioWaiver === undefined) return undefined;
39
+ return {mounts, ...(set === undefined ? {} : {packs: set}), ...(fence === undefined ? {} : {fence: v.parse(FenceReadsSchema, fence).files}), ...(audioWaiver === undefined ? {} : {audioWaiver})};
40
+ }
@@ -0,0 +1,6 @@
1
+ import { parseFlock } from '@wildshard/format/crowds';
2
+
3
+ /** Stable ordered flock declaration with seeded placement and trusted native terrain/view/prey recipes. */
4
+ export type FlockData = ReturnType<typeof parseFlock>;
5
+ /** Admit finite crowd tuning before any world construction, setup draws or callback registration. */
6
+ export function flock(data: unknown): FlockData { return parseFlock(data); }
@@ -0,0 +1,11 @@
1
+ import { decisionBindingMap as resolveBindings, type DecisionRegistries as Registries, type DecisionBindingMap as BindingMap } from '@wildshard/format/decisionBindings';
2
+ import type { DecisionScriptRow } from '@wildshard/format/decisionScripts';
3
+
4
+ /** Authoritative registries shared with the production resolver. */
5
+ export type DecisionRegistries = Registries;
6
+ /** Generated labels and numeric constants use the format's defining map. */
7
+ export type DecisionBindingMap = BindingMap;
8
+ /** SDK compatibility entry; allocation and refusal live in the renderer-free format. */
9
+ export function decisionBindingMap(row: DecisionScriptRow, registries: DecisionRegistries): DecisionBindingMap {
10
+ return resolveBindings(row, registries);
11
+ }