@wildshard/sdk 0.0.0 → 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 +14 -4
  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 +371 -4
  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,247 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- Scaffolding owns only a fresh author directory.
2
+ import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- Resolve files beneath the new project root.
4
+ import { resolve } from 'node:path';
5
+ import { encodeCanonicalJson } from './immutable';
6
+ import { authorCard } from './authorManifest';
7
+ import { writeHandwrittenSource } from './handwritten';
8
+
9
+ /**
10
+ * SA39 (J319): generators may install any npm package, so a dependency's install scripts run only when listed here.
11
+ * pnpm 10 runs none by default. `allowBuilds` is the list our pinned pnpm 10.34.9 reads and `pnpm approve-builds` writes;
12
+ * pnpm 10.21 ignores it and so runs none at all. Nothing a new shard installs needs a script today: the list starts empty.
13
+ * The pnpm pin itself is in the `package.json` SA16 writes. Proved by hand (SA39 receipt): an unlisted postinstall
14
+ * never ran and `pnpm ignored-builds` named it; `esbuild: true` let esbuild's run.
15
+ */
16
+ export const INSTALL_SCRIPT_POLICY = `packages:
17
+ - .
18
+
19
+ # Install scripts (SA39): a dependency runs its preinstall, install or postinstall
20
+ # script only when it is listed \`true\` below. Wildshard's own packages need none.
21
+ # pnpm skips any other package's script and names it after \`pnpm install\`; allow
22
+ # one with \`pnpm approve-builds\` (or \`name: true\` here) only if you trust it.
23
+ # pnpm 10.34 or later reads this list; pnpm 10.0 to 10.33 runs no script at all;
24
+ # pnpm 9, npm and yarn run every script, so install with pnpm 10.34 or later.
25
+ allowBuilds: {}
26
+ `;
27
+
28
+ /** Write the project's pnpm install-script allowlist. */
29
+ function writeInstallScriptPolicy(project: string): void {
30
+ writeFileSync(resolve(project, 'pnpm-workspace.yaml'), INSTALL_SCRIPT_POLICY);
31
+ }
32
+
33
+ /** SA13 (J314): the author's manual at the package root, shipped by `files`; `new` copies it into every project. */
34
+ export const GUIDE_SOURCE: string = resolve(import.meta.dirname, '../../GUIDE.md');
35
+
36
+ /** SA14, SA27 (J314 Q6): the core `wildshard` skill and its three siblings, at the package's `skills/`, shipped by `files`. */
37
+ export const SKILLS = ['wildshard', 'wildshard-mockup-to-model', 'wildshard-goldens', 'wildshard-upgrade'] as const;
38
+ export type SkillName = (typeof SKILLS)[number];
39
+ /** A skill's file in the installed sdk. */
40
+ export const skillSource = (name: SkillName): string => resolve(import.meta.dirname, `../../skills/${name}/SKILL.md`);
41
+ /** Where a project keeps a skill: Claude Code lists project skills from `.claude/skills/<name>/SKILL.md`. */
42
+ export const skillFile = (name: SkillName): string => `.claude/skills/${name}/SKILL.md`;
43
+ /** The core `wildshard` skill (SA14). */
44
+ export const SKILL_SOURCE: string = skillSource('wildshard');
45
+ export const SKILL_FILE: string = skillFile('wildshard');
46
+
47
+ /** Copy the installed sdk's GUIDE.md and the four `wildshard` skills into the project, byte for byte. */
48
+ function writeGuide(project: string): void {
49
+ cpSync(GUIDE_SOURCE, resolve(project, 'GUIDE.md'));
50
+ for (const name of SKILLS) {
51
+ mkdirSync(resolve(project, `.claude/skills/${name}`), { recursive: true });
52
+ cpSync(skillSource(name), resolve(project, skillFile(name)));
53
+ }
54
+ }
55
+
56
+ /** SA16 (J314, J317): `new --template <name>`. `sdk` is Mossgate (sharddev's `_template`); `blender` is shard-format's
57
+ * hand-written `blender-template` (`corpus/handwritten`): a shard file folder held by hand, no sdk at runtime, no three. */
58
+ export const TEMPLATES = ['sdk', 'blender'] as const;
59
+ export type TemplateName = (typeof TEMPLATES)[number];
60
+ /** The template `new` makes with no flag. */
61
+ export const DEFAULT_TEMPLATE: TemplateName = 'sdk';
62
+ /** J317: a repo with one shard keeps its shard source at `src/`. */
63
+ export const SHARD_SOURCE_FOLDER = 'src';
64
+
65
+ /** The template named by `--template`, or a refusal that names both, thrown before anything is written. */
66
+ export function templateNamed(name: string): TemplateName {
67
+ const found = TEMPLATES.find(template => template === name);
68
+ if (found === undefined) throw new Error(`new: unknown template ${name}: use --template sdk or --template blender`);
69
+ return found;
70
+ }
71
+
72
+ function assertTarget(project: string, slug: string): void {
73
+ if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(slug) || existsSync(project)) throw new Error('new requires a fresh directory and kebab-case slug');
74
+ }
75
+
76
+ /** The installed sdk's own package.json: its version and the exact specs it pins for engine, shard-format and three. */
77
+ const SDK_PACKAGE: string = resolve(import.meta.dirname, '../../package.json');
78
+ interface SdkPackage { readonly version: string; readonly node: string; readonly dependencies: Readonly<Record<string, string>> }
79
+ function sdkPackage(): SdkPackage {
80
+ const parsed: unknown = JSON.parse(readFileSync(SDK_PACKAGE, 'utf8'));
81
+ if (typeof parsed !== 'object' || parsed === null || !('version' in parsed) || typeof parsed.version !== 'string'
82
+ || !('dependencies' in parsed) || typeof parsed.dependencies !== 'object' || parsed.dependencies === null) throw new Error('new: the installed @wildshard/sdk has no package.json version');
83
+ const dependencies: Record<string, string> = {};
84
+ for (const [name, spec] of Object.entries(parsed.dependencies)) if (typeof spec === 'string') dependencies[name] = spec;
85
+ const node = 'engines' in parsed && typeof parsed.engines === 'object' && parsed.engines !== null && 'node' in parsed.engines && typeof parsed.engines.node === 'string' ? parsed.engines.node : undefined;
86
+ if (node === undefined) throw new Error('new: the installed @wildshard/sdk names no Node engine');
87
+ return { version: parsed.version, node, dependencies };
88
+ }
89
+ /** What a shard repo lists besides the sdk (grill Q12, Q13): shard-format, `three` (sdk's peer), and engine until
90
+ * SHARD-COMPAT's engine zero. Each is pinned exactly as the installed sdk pins it, so the repo installs one copy. */
91
+ export const REPO_DEPENDENCIES = ['@wildshard/engine', '@wildshard/format', 'three'] as const;
92
+
93
+ /** What a hand-written repo lists (J314): no code imports anything, so only the CLI (`@wildshard/sdk`, for `wildshard
94
+ * check` and `upload`) and shard-format (`shard-format pack` and `validate`), as dev dependencies; no engine, no three. */
95
+ export const HANDWRITTEN_DEPENDENCIES = ['@wildshard/format'] as const;
96
+
97
+ /** A new repo's package.json: the shard's slug, SA39's pnpm pin, and each Wildshard package pinned exactly. */
98
+ export function repoPackageJson(slug: string, template: TemplateName = DEFAULT_TEMPLATE): string {
99
+ const sdk = sdkPackage(), dependencies: Record<string, string> = { '@wildshard/sdk': sdk.version };
100
+ for (const name of template === 'blender' ? HANDWRITTEN_DEPENDENCIES : REPO_DEPENDENCIES) {
101
+ const spec = sdk.dependencies[name];
102
+ if (spec === undefined) throw new Error(`new: the installed @wildshard/sdk does not pin ${name}`);
103
+ dependencies[name] = spec;
104
+ }
105
+ const sorted = Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b)));
106
+ // `version` is what `wildshard upload` sends (provenance.ts reads the nearest package.json).
107
+ return `${JSON.stringify({ name: slug, version: '0.0.1', private: true, type: 'module', packageManager: 'pnpm@10.34.9',
108
+ engines: { node: sdk.node }, scripts: { check: 'wildshard check .' }, [template === 'blender' ? 'devDependencies' : 'dependencies']: sorted }, null, 2)}\n`;
109
+ }
110
+
111
+ const TSCONFIG = `${JSON.stringify({
112
+ // The author build bundles src/ (extensionless relative imports), as sharddev's own tsconfig does.
113
+ compilerOptions: { target: 'esnext', module: 'esnext', moduleResolution: 'bundler', strict: true, noEmit: true, skipLibCheck: true,
114
+ resolveJsonModule: true, allowImportingTsExtensions: true },
115
+ include: ['src/**/*.ts'],
116
+ }, null, 2)}\n`;
117
+ const GITIGNORE = `node_modules/
118
+ # Build output: the built folder and <slug>.shardfile. Never commit it.
119
+ public/shardfiles/
120
+ public/assets/*/map/
121
+ tmp/
122
+ .DS_Store
123
+ `;
124
+ // Exact versions for every package an author adds, and refuse a Node older than the sdk's.
125
+ const NPMRC = `save-exact=true
126
+ engine-strict=true
127
+ `;
128
+
129
+ const HANDWRITTEN_LAYOUT = `- \`src/\` is the shard source, written by hand: a shard file folder.
130
+ \`shard.json\` is its index, \`sections/\` the JSON you edit, \`blobs/\` the
131
+ baked files (Blender models, textures, scripts) named by their hash, and
132
+ \`mounts/\` what the boot reads first. \`wildshard check .\`
133
+ runs \`shard-format pack\`, which settles every hash and size the sections
134
+ measure, and validates the whole folder. A changed blob is a new file under
135
+ its new hash, with every row that names it updated.
136
+ - \`package.json\` pins \`@wildshard/sdk\` (the CLI) and shard-format exactly;
137
+ nothing here imports code, so no engine and no three.js. Its \`version\` is
138
+ the version \`wildshard upload\` sends.`;
139
+
140
+ function repoReadme(slug: string, template: TemplateName, empty: boolean): string {
141
+ const handwritten = template === 'blender' && !empty;
142
+ const world = empty ? 'a bare shard source (`--empty`)' : template === 'sdk' ? 'the reference world, Mossgate (Template 1)' : 'the hand-written Blender template (`blender-template`)';
143
+ const files = empty ? '`data/`, `generators/`,\n `behaviour/` and `assets/`' : '`data/`,\n `generators/`, `behaviour/`, `assets/` and `manifest.json` (the card)';
144
+ const layout = handwritten ? HANDWRITTEN_LAYOUT : `- \`src/\` is the shard source: \`shard.config.ts\` (the build entry), ${files}.
145
+ - \`package.json\` pins \`@wildshard/sdk\`, shard-format, engine and \`three\`
146
+ exactly; its \`version\` is the version \`wildshard upload\` sends.`;
147
+ return `# ${slug}
148
+
149
+ A Wildshard **shard source**, started by \`wildshard new\` from ${world}.
150
+ \`wildshard check .\` builds it into one **shard file**, and \`wildshard upload\`
151
+ sends that file to a channel.
152
+
153
+ Start with \`GUIDE.md\`, the author's manual: section 1 is the loop (new, dev,
154
+ check, hero, upload), section 2 this layout. The \`wildshard\` skill in
155
+ \`.claude/skills/\` gives an agent the same loop; its siblings there make a
156
+ model from a picture (\`wildshard-mockup-to-model\`), refresh the hero and
157
+ proof tape (\`wildshard-goldens\`) and move to a newer sdk
158
+ (\`wildshard-upgrade\`).
159
+
160
+ \`\`\`sh
161
+ pnpm install
162
+ pnpm exec wildshard check .
163
+ \`\`\`
164
+
165
+ Until \`@wildshard/sdk\` is on npm, \`pnpm install\` cannot fetch it: run the CLI
166
+ from a sharddev checkout instead (\`GUIDE.md\`, "Running \`wildshard\` today").
167
+
168
+ ${layout}
169
+ - \`public/shardfiles/\` is build output. Never edit or commit it.
170
+ `;
171
+ }
172
+
173
+ /** Write the repo files around a shard source at `src/`: package.json, tsconfig, ignores, README, guide and skill. */
174
+ function writeRepoFiles(project: string, slug: string, template: TemplateName, empty: boolean): void {
175
+ writeFileSync(resolve(project, 'package.json'), repoPackageJson(slug, empty ? DEFAULT_TEMPLATE : template));
176
+ // A hand-written repo holds no TypeScript to check.
177
+ if (template !== 'blender' || empty) writeFileSync(resolve(project, 'tsconfig.json'), TSCONFIG);
178
+ writeFileSync(resolve(project, '.gitignore'), GITIGNORE);
179
+ writeFileSync(resolve(project, '.npmrc'), NPMRC);
180
+ writeFileSync(resolve(project, 'README.md'), repoReadme(slug, template, empty));
181
+ writeInstallScriptPolicy(project);
182
+ writeGuide(project);
183
+ }
184
+
185
+ /** Copy the shipped teaching world into `source`; generation and gameplay remain authored there. */
186
+ function writeReferenceSource(source: string, slug: string): void {
187
+ // The trusted CLI bundle defines dirname as its installed source directory.
188
+ const template = resolve(import.meta.dirname, '../shards/_template');
189
+ cpSync(template, source, { recursive: true, errorOnExist: true, force: false,
190
+ filter: from => !/\.(?:test|spec)\.[cm]?[jt]sx?$/u.test(from) && from !== resolve(template, 'card') && from !== resolve(template, 'hero.json')
191
+ // The template's README is sharddev's own notes; the repo gets a README of its own (SA16).
192
+ && from !== resolve(template, 'README.md')
193
+ // A checkout's built Template output (gitignored, under public/) is Template's; build output goes to the repo root.
194
+ && from !== resolve(template, 'public') });
195
+ const card: unknown = JSON.parse(readFileSync(resolve(source, 'manifest.json'), 'utf8'));
196
+ if (typeof card !== 'object' || card === null || Array.isArray(card)) throw new Error('Reference project manifest is missing');
197
+ // The template's card is Mossgate's own in-engine hero (template/card/): a new project wears a generated card until its
198
+ // author captures one, never another shard's art.
199
+ const art = authorCard(slug, 1);
200
+ // UP5 (2026-11-13): the boot loads `shardfile`; Template's path booted a file this project never builds and hung.
201
+ const manifest = encodeCanonicalJson({ ...card, slug, name: slug, status: 'experimental', card: { thumb: art, portrait: art, landscape: art }, shardfile: `/shardfiles/${slug}/shard.json` }).replaceAll('/assets/_template/', `/assets/${slug}/`);
202
+ writeFileSync(resolve(source, 'manifest.json'), manifest);
203
+ writeFileSync(resolve(source, 'data/card.json'), manifest);
204
+ writeFileSync(resolve(source, 'data/identity.json'), encodeCanonicalJson({ slug, name: slug, author: 'Local author' }));
205
+ writeFileSync(resolve(source, 'shard.config.ts'), `import { generate as reference } from './generators/generate';\nimport { BUILD_OPTIONS } from './generators/buildOptions';\nimport identity from './data/identity.json' with { type: 'json' };\nimport type { GeneratedProject, ProjectGenerationContext } from '@wildshard/sdk/projectGeneration';\n\n/** Author this world's data and generators; the identity belongs to this project. */\nexport async function generate(context: ProjectGenerationContext): Promise<GeneratedProject> {\n const product = await reference(context);\n return { ...product, shard: { ...product.shard, identity: { ...product.shard.identity, ...identity } } };\n}\n\n// oxlint-disable-next-line import/no-default-export -- The author CLI loads this documented generation entry.\nexport default generate;\nexport const buildOptions: typeof BUILD_OPTIONS = { ...BUILD_OPTIONS };\n`);
206
+ }
207
+
208
+ /** Write the runtime-free bare shard source (`new --empty`) into `source`. */
209
+ function writeEmptySource(source: string, slug: string): void {
210
+ for (const folder of ['generators', 'data', 'behaviour', 'assets']) mkdirSync(resolve(source, folder), { recursive: true });
211
+ const identity = encodeCanonicalJson({ slug, name: slug, author: 'Local author', revision: 1, seed: 1 }).trim();
212
+ writeFileSync(resolve(source, 'data/card.ts'), `/** Build-time identity; add authored level metadata here as the world grows. */\nexport const IDENTITY = ${identity};\n`);
213
+ writeFileSync(resolve(source, 'data/world.ts'), `import { emptyShardfile } from '@wildshard/sdk/author';\nimport { IDENTITY } from './card';\n\n/** Build-only declaration; the CLI emits its platform sections as JSON. */\nexport const WORLD = emptyShardfile(IDENTITY);\n`);
214
+ writeFileSync(resolve(source, 'generators/product.ts'), `import { WORLD } from '../data/world';\n\n// oxlint-disable-next-line import/no-default-export -- The documented build entry imports this declaration.\nexport default WORLD;\n`);
215
+ writeFileSync(resolve(source, 'generators/output.ts'), `import type { ProjectOutput } from '@wildshard/sdk/projectOutput';\n\n/** Build-only named blobs and platform sections, read automatically by the CLI. */\nexport const output = {} satisfies ProjectOutput;\n`);
216
+ writeFileSync(resolve(source, 'shard.config.ts'), `import product from './generators/product';\n\n// oxlint-disable-next-line import/no-default-export -- The author CLI loads this build entry.\nexport default product;\n`);
217
+ }
218
+
219
+ /** The bare shard source alone at `source`, with no repo around it (sdk API; tests build it in place). */
220
+ export function writeEmptyShardSource(source: string, slug: string): void {
221
+ assertTarget(source, slug);
222
+ writeEmptySource(source, slug);
223
+ }
224
+
225
+ /** `wildshard new <dir> [slug] [--template sdk|blender] [--empty]`: a whole single-shard repo, its shard source at `src/`. */
226
+ export function writeShardRepo(project: string, slug: string, options: { readonly template?: TemplateName; readonly empty?: boolean } = {}): void {
227
+ const template = options.template ?? DEFAULT_TEMPLATE;
228
+ assertTarget(project, slug);
229
+ mkdirSync(project, { recursive: true });
230
+ const source = resolve(project, SHARD_SOURCE_FOLDER);
231
+ try {
232
+ if (options.empty === true) writeEmptySource(source, slug);
233
+ else if (template === 'blender') writeHandwrittenSource(source, slug);
234
+ else writeReferenceSource(source, slug);
235
+ writeRepoFiles(project, slug, template, options.empty === true);
236
+ } catch (error) {
237
+ // A refused `new` leaves no half-written repo, so running it again names the real cause, not `new-target`.
238
+ rmSync(project, { recursive: true, force: true });
239
+ throw error;
240
+ }
241
+ }
242
+
243
+ /** `new <dir>`: the reference world as a whole repo. */
244
+ export function writeReferenceProject(project: string, slug: string): void { writeShardRepo(project, slug); }
245
+
246
+ /** `new <dir> --empty`: the bare shard source as a whole repo. */
247
+ export function writeNewProject(project: string, slug: string): void { writeShardRepo(project, slug, { empty: true }); }
@@ -0,0 +1,54 @@
1
+ /** Build-only noise; exact equality tests fence the runtime implementation. */
2
+ // 2D simplex noise (Stefan Gustavson's reference implementation, seeded permutation).
3
+ import { Rng } from './random';
4
+
5
+ const F2 = 0.5 * (Math.sqrt(3) - 1);
6
+ const G2 = (3 - Math.sqrt(3)) / 6;
7
+ const grad3: readonly (readonly [number, number])[] = [[1, 1], [-1, 1], [1, -1], [-1, -1], [1, 0], [-1, 0], [0, 1], [0, -1]];
8
+ const G_NONE: readonly [number, number] = [0, 0]; // never hit: `% 8` keeps the index in range; satisfies noUncheckedIndexedAccess
9
+
10
+ export class Noise2D {
11
+ private perm = new Uint8Array(512);
12
+ constructor(seed: number) {
13
+ const rng = new Rng(seed);
14
+ const p = new Uint8Array(256);
15
+ for (let i = 0; i < 256; i++) p[i] = i;
16
+ for (let i = 255; i > 0; i--) { const j = Math.floor(rng.next() * (i + 1)); [p[i], p[j]] = [p[j] ?? 0, p[i] ?? 0]; }
17
+ for (let i = 0; i < 512; i++) this.perm[i] = p[i & 255] ?? 0;
18
+ }
19
+ /** returns roughly [-1, 1] */
20
+ get(xin: number, yin: number): number {
21
+ const perm = this.perm;
22
+ const s = (xin + yin) * F2;
23
+ const i = Math.floor(xin + s), j = Math.floor(yin + s);
24
+ const t = (i + j) * G2;
25
+ const x0 = xin - (i - t), y0 = yin - (j - t);
26
+ const i1 = x0 > y0 ? 1 : 0, j1 = x0 > y0 ? 0 : 1;
27
+ const x1 = x0 - i1 + G2, y1 = y0 - j1 + G2;
28
+ const x2 = x0 - 1 + 2 * G2, y2 = y0 - 1 + 2 * G2;
29
+ const ii = i & 255, jj = j & 255;
30
+ let n = 0;
31
+ let t0 = 0.5 - x0 * x0 - y0 * y0;
32
+ if (t0 > 0) { const g = grad3[(perm[ii + (perm[jj] ?? 0)] ?? 0) % 8] ?? G_NONE; t0 *= t0; n += t0 * t0 * (g[0] * x0 + g[1] * y0); }
33
+ let t1 = 0.5 - x1 * x1 - y1 * y1;
34
+ if (t1 > 0) { const g = grad3[(perm[ii + i1 + (perm[jj + j1] ?? 0)] ?? 0) % 8] ?? G_NONE; t1 *= t1; n += t1 * t1 * (g[0] * x1 + g[1] * y1); }
35
+ let t2 = 0.5 - x2 * x2 - y2 * y2;
36
+ if (t2 > 0) { const g = grad3[(perm[ii + 1 + (perm[jj + 1] ?? 0)] ?? 0) % 8] ?? G_NONE; t2 *= t2; n += t2 * t2 * (g[0] * x2 + g[1] * y2); }
37
+ return 70 * n;
38
+ }
39
+ fbm(x: number, y: number, octaves = 5, lacunarity = 2, gain = 0.5): number {
40
+ let a = 1, f = 1, sum = 0, norm = 0;
41
+ for (let o = 0; o < octaves; o++) { sum += a * this.get(x * f, y * f); norm += a; a *= gain; f *= lacunarity; }
42
+ return sum / norm;
43
+ }
44
+ /** ridged multifractal, [0,1] */
45
+ ridged(x: number, y: number, octaves = 4): number {
46
+ let a = 1, f = 1, sum = 0, norm = 0;
47
+ for (let o = 0; o < octaves; o++) { const n = 1 - Math.abs(this.get(x * f, y * f)); sum += a * n * n; norm += a; a *= 0.5; f *= 2.1; }
48
+ return sum / norm;
49
+ }
50
+ }
51
+
52
+ export const smoothstep = (a: number, b: number, x: number): number => { const t = Math.min(1, Math.max(0, (x - a) / (b - a))); return t * t * (3 - 2 * t); };
53
+ export const clamp = (x: number, a: number, b: number): number => Math.min(b, Math.max(a, x));
54
+ export const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
@@ -0,0 +1,188 @@
1
+ import { ktx2DeviceCosts } from '@wildshard/format/ktx2Cost';
2
+ import { HEADLESS_CONTEXT_SECTIONS } from '@wildshard/engine/host/headlessSections';
3
+ import {publishedSourceResidency} from '@wildshard/format/sourceResidency';
4
+ import {postStackCost} from '@wildshard/format/postStack';
5
+ /** Author-only format-2 emission and on-disk inventory validation. */
6
+ // oxlint-disable-next-line import/no-nodejs-modules -- The author CLI owns its explicit product output directory.
7
+ import { existsSync, lstatSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
8
+ // oxlint-disable-next-line import/no-nodejs-modules -- Product paths are validated relative paths, never URLs.
9
+ import { dirname, resolve } from 'node:path';
10
+ import { parseOutputIndex, parseOutputSection, type OutputFile, type OutputIndex } from '@wildshard/format/outputIndex';
11
+ import { outputSectionPayloads, OUTPUT_SECTIONS } from '@wildshard/format/outputFields';
12
+ import { decisionScriptsFromSections, scriptAdmissionRows, type ScriptAdmissionRows } from '@wildshard/format/scriptContract';
13
+ import type { DecisionScripts } from '@wildshard/format/decisionScripts';
14
+ import { structuralGridEvidence } from '@wildshard/format/gridReadiness';
15
+ import { offlineMemoryAdmission } from '@wildshard/format/product';
16
+ import { validationRevision, validationSourceBytes } from '@wildshard/format/validationReceipt';
17
+ import { preflightDeclaredCosts } from '@wildshard/format/assetAdmission';
18
+ import { admitProduct, readmitted, rememberAdmitted } from './productOutput';
19
+ import { performanceTargetIssues } from './reportCard';
20
+ import { encodeCanonicalJson, hashImmutableBytes } from './immutable';
21
+ import { assetHandles, hashAssetBytes, immutableAsset, verifyAssetBytes, type ImmutableAsset } from './assetHandle';
22
+ import { readBoundedFile } from './sourceReader';
23
+ import { validateRuntimeImports } from './runtimeImports';
24
+ import type { ServerBlob } from './blobs';
25
+ import { COOK_DATA_PATH, cookMountPath } from '@wildshard/format/cookData';
26
+ import type { CookInput } from './cookInput';
27
+ import { validateDefinedJson, type EmittedSections } from './sections';
28
+ import { parseDiscoveryValues, type DiscoveryValues } from '@wildshard/format/discoveryValues';
29
+ import { checkWorldTargets, outputBlobExtension as blobExtension, outputBlobKind as blobKind, readCanonicalJson as readJson, validateShardfileProduct, type ProductFiles, type ValidatedProduct } from '@wildshard/format/productValidation';
30
+
31
+ const encoder = new TextEncoder();
32
+ function jsonBytes(value: unknown): Uint8Array { return encoder.encode(encodeCanonicalJson(value)); }
33
+ function put(destination: string, path: string, bytes: Uint8Array): void { const target = resolve(destination,path); mkdirSync(dirname(target),{recursive:true});writeFileSync(target,bytes); }
34
+ /** Optional build-only extensions. Runtime bytes themselves are written by the P3 copier. */
35
+ export interface OutputProductOptions {
36
+ /** Build metadata only; discovery inlines these admitted values after the product is built. */
37
+ readonly discovery?: DiscoveryValues;
38
+ readonly platform?: EmittedSections;
39
+ readonly namedFiles?: readonly OutputFile[];
40
+ /** J91: server-class files. They enter the index's `admission.server`, never `files`. */
41
+ readonly server?: readonly ServerBlob[];
42
+ readonly runtime?: { readonly files: readonly NonNullable<OutputIndex['runtime']>['files'][number][]; readonly lines: number };
43
+ /** C0 (J137): the files and hints that let this product stand alone (`cook.json`). */
44
+ readonly cook?: CookInput;
45
+ }
46
+ /** C0: the mounts' bytes and their `cook.json` join the product's emitted files. */
47
+ function cookRow(input: CookInput | undefined, emitted: Map<string,Uint8Array>, files: readonly {readonly path:string;readonly hash:string}[]): NonNullable<OutputIndex['cook']> | undefined {
48
+ if (input === undefined) return undefined;
49
+ // A mount with the bytes of a listed blob names that blob: a shardfile holds a file once, however many URLs serve it.
50
+ const blobs = new Map(files.map(file=>[file.hash,file.path]));
51
+ const mounts = input.mounts.map(({url,bytes}) => { const hash=hashAssetBytes(bytes),blob=blobs.get(hash),path=blob??cookMountPath(url);if(blob===undefined)emitted.set(path,bytes);return {url,path,hash,bytes:bytes.length}; });
52
+ const {packs,fence} = input, bytes = jsonBytes({version:1,mounts,...(packs===undefined?{}:{packs}),...(fence===undefined?{}:{fence})});
53
+ emitted.set(COOK_DATA_PATH,bytes);
54
+ return {path:COOK_DATA_PATH,hash:hashAssetBytes(bytes),bytes:bytes.length};
55
+ }
56
+ /** Read the named canonical platform payloads, each only after checking its emitted hash and size. */
57
+ export function outputPlatformPayloads(platform: EmittedSections | undefined, names: readonly string[] = HEADLESS_CONTEXT_SECTIONS): ReadonlyMap<string, unknown> {
58
+ const payloads = new Map<string, unknown>();
59
+ for (const entry of platform?.sections ?? []) {
60
+ if (!names.includes(entry.name)) continue;
61
+ if (payloads.has(entry.name)) throw new Error(`Duplicate ${entry.name} section`);
62
+ const bytes = platform?.files.get(entry.path);
63
+ if (bytes === undefined || bytes.length !== entry.bytes || hashAssetBytes(bytes) !== entry.hash) throw new Error(`${entry.name} section hash or size mismatch`);
64
+ payloads.set(entry.name, readJson(bytes));
65
+ }
66
+ return payloads;
67
+ }
68
+ /** Read the canonical platform decision payload only after checking its emitted hash and size. */
69
+ export function outputDecisionScripts(platform?: EmittedSections): DecisionScripts {
70
+ return decisionScriptsFromSections(outputPlatformPayloads(platform, ['sim/scripts']));
71
+ }
72
+ /** Exact contracts for both generic actor decisions and population-owned directors. */
73
+ export function outputScriptAdmissionRows(platform?: EmittedSections): ScriptAdmissionRows {
74
+ return scriptAdmissionRows(outputPlatformPayloads(platform, ['sim/scripts', 'actors/spawn-scripts', 'actors/return-scripts', 'view/modules']));
75
+ }
76
+ /** Split an admitted product without changing host values or any immutable asset byte. */
77
+ export function writeOutputProduct(input: unknown, assets: ReadonlyMap<string,Uint8Array>, destination: string, options: OutputProductOptions = {}): OutputIndex {
78
+ if (Object.hasOwn(options, 'custom')) throw new Error('Custom output extensions are retired');
79
+ // the product buildProject admitted a moment ago is not admitted twice in memory (readmitted); the written folder always is
80
+ const scripts = outputScriptAdmissionRows(options.platform), source = readmitted(input,assets,'warn',scripts) ?? admitProduct(input,assets,'warn',scripts);
81
+ const targetEntry = options.platform?.sections.find(row => row.name === 'world/targets');
82
+ if (targetEntry !== undefined) {
83
+ const bytes = options.platform?.files.get(targetEntry.path);
84
+ if (bytes === undefined || bytes.length !== targetEntry.bytes || hashAssetBytes(bytes) !== targetEntry.hash) throw new Error('World target section hash or size mismatch');
85
+ checkWorldTargets(source, readJson(bytes));
86
+ }
87
+ for(const issue of performanceTargetIssues(source,'warn'))console.warn(`Output budget report-only (G453): ${issue.metric}: ${issue.actual} exceeds ${issue.limit}`);
88
+ source.files.sort((a,b)=>a.hash.localeCompare(b.hash));
89
+ source.tiles.sort((a,b)=>a.lod-b.lod||a.x-b.x||a.z-b.z);
90
+ const sections: OutputIndex['sections'] = [], schemas: OutputIndex['schemas'] = [], files: OutputIndex['files'] = [];
91
+ const emitted = new Map<string,Uint8Array>();
92
+ for (const [name,value] of outputSectionPayloads(source)) {
93
+ const mapping = OUTPUT_SECTIONS.find(row => row.name === name); if (mapping === undefined) throw new Error('Missing platform section mapping');
94
+ parseOutputSection(name,value);
95
+ const bytes = jsonBytes(value), path = `sections/${name}.json`;emitted.set(path,bytes);
96
+ sections.push({name,path,schema:`wildshard:${name}@1`,hash:hashAssetBytes(bytes),bytes:bytes.length});
97
+ }
98
+ for (const {name,path,schema,hash,bytes} of options.platform?.sections ?? []) sections.push({name,path,schema,hash,bytes});
99
+ for (const [path,bytes] of options.platform?.files ?? []) {
100
+ if (emitted.has(path)) throw new Error('Duplicate platform output path');
101
+ emitted.set(path,bytes);
102
+ if (path.startsWith('schemas/')) schemas.push({path,hash:hashAssetBytes(bytes),bytes:bytes.length});
103
+ }
104
+ for (const blob of options.server ?? []) {
105
+ if (emitted.has(blob.file.path)) throw new Error('Duplicate server output path');
106
+ emitted.set(blob.file.path,blob.bytes);
107
+ }
108
+ const declarations = new Map(source.files.map(file => [file.hash,file]));
109
+ const names=new Map<string,OutputFile>();
110
+ for(const file of options.namedFiles??[]){if(names.has(file.hash))throw new Error('Duplicate named blob reference');names.set(file.hash,file);}
111
+ for (const [reference,bytes] of assets) {
112
+ const commons = reference.startsWith('commons:'), hash = commons ? reference.slice(8) : reference;
113
+ if(commons&&declarations.has(hash))continue;
114
+ const declaration = declarations.get(hash), pinned = source.requires.commonsCosts[hash];
115
+ if (!commons && declaration === undefined) throw new Error('Unlisted output asset');
116
+ if (commons && (pinned === undefined || !source.requires.commons.includes(hash))) throw new Error('Unlisted output commons asset');
117
+ const kind = blobKind(commons ? 'commons' : declaration?.kind ?? '',bytes), path = `blobs/${kind}/${hash}.${blobExtension(kind,bytes)}`;
118
+ if (emitted.has(path)) throw new Error('Output asset path collision');
119
+ emitted.set(path,bytes);
120
+ files.push({hash,kind,path,compressed:bytes.length,decoded:declaration?.decoded ?? pinned?.decoded ?? 0,gpu:declaration?.gpu ?? pinned?.gpu ?? 0,triangles:declaration?.triangles ?? pinned?.triangles ?? 0,draws:declaration?.draws ?? pinned?.draws ?? 0,dependencies:commons ? [] : declaration?.dependencies ?? [],critical:commons ? false : declaration?.critical ?? false,...(commons ? {commons:true as const} : {})});
121
+ }
122
+ for(const file of files){const named=names.get(file.hash);if(named!==undefined){const {name,jsonSchema,tier,variantOf,...metadata}=named;if(encodeCanonicalJson(metadata)!==encodeCanonicalJson(file))throw new Error('Named blob differs from its admitted declaration');if(name!==undefined)file.name=name;if(tier!==undefined)file.tier=tier;if(variantOf!==undefined)file.variantOf=variantOf;if(jsonSchema!==undefined)file.jsonSchema=jsonSchema;names.delete(file.hash);}}
123
+ if(names.size>0)throw new Error('Unadmitted named blob');
124
+ const ktx2Costs: NonNullable<OutputIndex['ktx2Costs']> = {};
125
+ for (const file of files) if (file.kind==='ktx2' && file.commons!==true) {
126
+ const bytes=emitted.get(file.path);if(bytes===undefined)throw new Error('Missing KTX2 cost bytes');
127
+ ktx2Costs[file.hash]=ktx2DeviceCosts(bytes);
128
+ }
129
+ const cook=cookRow(options.cook,emitted,files);
130
+ const {spawns:_spawns,...runtime} = source.runtime ?? {};
131
+ const index = parseOutputIndex({format:'wildshard.shardfile',formatVersion:2,sdk:'0.2',version:source.version,identity:source.identity,requires:source.requires,
132
+ build:{sourceHash:hashImmutableBytes(jsonBytes(source)),validator:validationRevision() ?? 'source'},admission:{budgets:source.budgets,serverBudget:source.serverBudget,authorCaps:source.authorCaps,critical:source.critical,library:source.library,...(source.late===undefined?{}:{late:source.late}),...(options.cook?.audioWaiver===undefined?{}:{audioWaiver:options.cook.audioWaiver}),...(options.server===undefined||options.server.length===0?{}:{server:options.server.map(blob=>blob.file).sort((a,b)=>a.name.localeCompare(b.name))})},
133
+ ...(Object.keys(ktx2Costs).length===0?{}:{ktx2Costs}),
134
+ sections:sections.sort((a,b)=>a.name.localeCompare(b.name)),schemas:schemas.sort((a,b)=>a.path.localeCompare(b.path)),files:files.sort((a,b)=>a.hash.localeCompare(b.hash)||a.path.localeCompare(b.path)),...(cook===undefined?{}:{cook}),runtime:source.runtime === null ? null : {...runtime,trust:'first-party',files:options.runtime?.files ?? [],lines:options.runtime?.lines ?? 0}});
135
+ // A writer owns this product directory, never a source folder. Preserve only the
136
+ // already-copied runtime files; refuse unrelated leftovers in validation below.
137
+ mkdirSync(destination,{recursive:true});
138
+ // S5: engine cooks packs from the raw upload, so a product holds none; clear any an older writer left here
139
+ rmSync(resolve(destination,'blobs/pack'),{recursive:true,force:true});
140
+ for (const [path,bytes] of emitted) put(destination,path,bytes);
141
+ put(destination,'shard.json',jsonBytes(index));
142
+ const published=validateOutputProduct(destination,assetHandles(emitted.values()));
143
+ const cost = preflightDeclaredCosts(source,offlineMemoryAdmission('warn')).worst;
144
+ const discovery = options.discovery === undefined ? undefined : parseDiscoveryValues(options.discovery);
145
+ put(destination,'validation.json',jsonBytes({revision:index.build.validator,sourceHash:hashImmutableBytes(validationSourceBytes(source)),indexHash:hashImmutableBytes(jsonBytes(index)),worst:cost,residentBytes:publishedSourceResidency(published.shard),postCost:postStackCost(published.shard,hash=>published.assets.get(hash)).cost,gridReady:structuralGridEvidence(source),
146
+ ...(discovery === undefined ? {} : { discovery: { hash: hashImmutableBytes(jsonBytes(discovery)), values: discovery } }) }));
147
+ return index;
148
+ }
149
+ /** The product folder as format validation reads it: bounded reads of regular files only, never through a symlink. */
150
+ function productFolder(destination: string): ProductFiles {
151
+ return {
152
+ read: (path: string, maxBytes: number): Uint8Array => {
153
+ let target = destination;
154
+ for (const part of path.split('/')) { target = resolve(target, part); if (lstatSync(target).isSymbolicLink()) throw new Error('Output symlinks refuse'); }
155
+ if (!lstatSync(target).isFile()) throw new Error('Output inventory needs regular files');
156
+ return readBoundedFile(resolve(destination, path), maxBytes);
157
+ },
158
+ paths: (): string[] => {
159
+ const found: string[] = [];
160
+ const walk = (folder: string): void => {
161
+ for (const name of readdirSync(resolve(destination, folder))) {
162
+ const path = folder === '' ? name : `${folder}/${name}`;
163
+ if (lstatSync(resolve(destination, path)).isDirectory()) walk(path); else found.push(path);
164
+ }
165
+ };
166
+ walk(''); return found;
167
+ },
168
+ };
169
+ }
170
+ /** Validate a written product folder: P1-F3's format half (`@wildshard/format/productValidation`), with the author's
171
+ * Ajv schema check, runtime import check and verified-asset snapshots. Executing script bytes is not part of it. */
172
+ export function validateOutputProduct(destination: string, prior?: ReadonlyMap<string, ImmutableAsset>): ValidatedProduct {
173
+ const verified = new Map(prior);
174
+ const checked = validateShardfileProduct(productFolder(destination), {
175
+ hash: hashAssetBytes,
176
+ verify: (bytes, expected, whole) => {
177
+ if (!verifyAssetBytes(bytes, expected, verified.get(expected))) return false;
178
+ if (whole) verified.set(expected, immutableAsset(bytes));
179
+ return true;
180
+ },
181
+ definedJson: (schemaBytes, bytes, name) => { validateDefinedJson(schemaBytes, bytes, name); },
182
+ runtimeImports: (path, source) => { validateRuntimeImports(destination, path, source); },
183
+ });
184
+ rememberAdmitted(checked.shard, checked.assets, 'warn', checked.scripts);
185
+ return checked;
186
+ }
187
+ /** Clear only a caller-owned generated product before a fresh emission. */
188
+ export function clearOutputProduct(destination: string): void { if(existsSync(destination))rmSync(destination,{recursive:true,force:true}); }
@@ -0,0 +1,66 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- The author build owns the generated runtime copy.
2
+ import { existsSync, lstatSync, readdirSync, realpathSync, rmSync } from 'node:fs';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- Runtime inventory paths are local project-relative paths.
4
+ import { dirname, relative, resolve, sep } from 'node:path';
5
+ import { parseSync } from 'vite';
6
+ import { runtimeMirrorIssues, type RuntimeMirror } from './runtimeMirrors';
7
+ import type { OutputIndex } from '@wildshard/format/outputIndex';
8
+
9
+ export interface RuntimeCopyFile { readonly path: string; readonly hash: string; readonly bytes: number; readonly lines: number }
10
+ export interface RuntimeCopy { readonly files: readonly RuntimeCopyFile[]; readonly lines: number }
11
+
12
+ /** Validate declared constant mirrors without a custom runtime registry. */
13
+ export function validateRuntimeData(mirrors: readonly RuntimeMirror[], copiedConstants: Readonly<Record<string, unknown>> | undefined): void {
14
+ if (mirrors.length > 0 && copiedConstants === undefined) throw new Error('Declared mirrors require runtime/const.ts');
15
+ const issues = runtimeMirrorIssues(mirrors, copiedConstants ?? {});
16
+ if (issues.length > 0) throw new Error(issues.join('\n'));
17
+ }
18
+
19
+ /** Client-plan products contain no copied executable runtime. Platform data
20
+ * and registered named files retain their original output-owner validation. */
21
+ export function proveRuntimeData(_destination: string, index: OutputIndex, mirrors: readonly RuntimeMirror[]): void {
22
+ if (index.runtime !== null && index.runtime.files.length > 0) throw new Error('Runtime proof requires a client-plan output with no copied TypeScript');
23
+ if (index.schemas.length > 0 || index.sections.some(row => row.name.startsWith('custom/'))) throw new Error('Custom runtime registries are retired');
24
+ validateRuntimeData(mirrors, undefined);
25
+ }
26
+
27
+ /** Parser comment ranges preserve strings, regexes and template literal text.
28
+ * Only nonblank lines after comment removal count; byte output is never edited. */
29
+ export function runtimeCodeLines(source: string, path = 'runtime/index.ts'): number {
30
+ const parsed = parseSync(path, source);
31
+ if (parsed.errors.length > 0) throw new Error(`Invalid runtime TypeScript: ${path}`);
32
+ const chunks: string[] = []; let cursor = 0;
33
+ for (const { start, end } of parsed.comments) {
34
+ chunks.push(source.slice(cursor, start), source.slice(start, end).replaceAll(/[^\n]/gu, ' ')); cursor = end;
35
+ }
36
+ chunks.push(source.slice(cursor));
37
+ return chunks.join('').split('\n').filter(line => line.trim()).length;
38
+ }
39
+
40
+ /** A client-plan product ships no runtime TypeScript (LD9 retired the copied-runtime entry): runtime/ may hold only
41
+ * declaration files (`.d.ts`), never executable source, and the owned destination/runtime directory is cleared so no
42
+ * earlier copy can linger. Symlinks and non-TypeScript files are refused before anything is deleted. */
43
+ export function writeRuntimeFiles(project: string, destination: string): RuntimeCopy {
44
+ const root = realpathSync(project), target = resolve(destination);
45
+ if (target === root || target.startsWith(`${root}${sep}`) || root.startsWith(`${target}${sep}`)) throw new Error('Runtime output must be separate from its author project');
46
+ const runtime = resolve(root, 'runtime'), output = resolve(target, 'runtime');
47
+ const walk = (folder: string): void => {
48
+ if (lstatSync(folder).isSymbolicLink()) throw new Error('Runtime cannot contain symlinks');
49
+ for (const item of readdirSync(folder, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
50
+ const file = resolve(folder, item.name), path = relative(root, file).split(sep).join('/');
51
+ if (item.isSymbolicLink()) throw new Error(`Runtime cannot contain symlinks: ${path}`);
52
+ if (item.isDirectory()) { walk(file); continue; }
53
+ if (!item.isFile() || !/^(?:[a-zA-Z0-9_-][a-zA-Z0-9_.-]*\/)*[a-zA-Z0-9_-][a-zA-Z0-9_.-]*\.ts$/u.test(path)) throw new Error(`Runtime accepts TypeScript files only: ${path}`);
54
+ if (path === 'runtime/sections.ts' || path.endsWith('/productSections.d.ts')) throw new Error(`Custom runtime registries are retired: ${path}`);
55
+ if (!path.endsWith('.d.ts')) throw new Error(`Client-plan runtime cannot contain executable source: ${path}`);
56
+ }
57
+ };
58
+ if (existsSync(runtime)) walk(runtime);
59
+ // Reject symlinked output ancestors before deleting anything.
60
+ for (let folder = output; ; folder = dirname(folder)) {
61
+ if (existsSync(folder) && lstatSync(folder).isSymbolicLink()) throw new Error('Runtime output cannot contain symlinks');
62
+ if (folder === dirname(folder)) break;
63
+ }
64
+ if (existsSync(output)) rmSync(output, { recursive: true });
65
+ return { files: [], lines: 0 };
66
+ }
@@ -0,0 +1,18 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- Only canonical checkout paths can receive the old-six offline warning policy.
2
+ import { existsSync, realpathSync } from 'node:fs';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- Author identities and symlink spellings do not confer checkout provenance.
4
+ import { resolve } from 'node:path';
5
+ import type { Shardfile } from '@wildshard/engine/host/shardfile';
6
+
7
+ const legacy = new Set(['driftwood-isle', 'pine-hollow', 'nalati-grasslands', 'far-reach', 'sunscar-dunes', 'nine-dragon-stack']);
8
+ /** Offline policy is selected by trusted checkout provenance, never by author slug or a product flag. */
9
+ export function projectPerformancePolicy(project: string | undefined, source: Pick<Shardfile,'identity'>): 'warn' | 'refuse' {
10
+ if (project === undefined || !legacy.has(source.identity.slug)) return 'refuse';
11
+ const root = process.cwd(); // P4: a first-party shard repo is the checkout, and it holds the shard at this path.
12
+ if (!existsSync(resolve(root, 'AGENTS.md'))) return 'refuse';
13
+ // SA16 (J317): a single-shard repo holds it at src/ (SA24 moves the six there), a multi-shard repo at src/shards/<slug>/.
14
+ const canonical = existsSync(resolve(root, 'src/shard.config.ts')) ? resolve(root, 'src') : resolve(root, 'src/shards', source.identity.slug);
15
+ if (!existsSync(project) || !existsSync(canonical)) return 'refuse';
16
+ const actual = realpathSync(project), products = [resolve(root, 'public/shardfiles', source.identity.slug),resolve(root,'out',source.identity.slug)];
17
+ return actual === realpathSync(canonical) || products.some(product => existsSync(product) && actual === realpathSync(product)) ? 'warn' : 'refuse';
18
+ }
@@ -0,0 +1,34 @@
1
+ import { phasedBossFight as platformFight, type PhasedBossBody as PlatformBody, type PhasedBossFight as PlatformFight, type PhasedBossPorts as PlatformPorts,
2
+ type PhasedBossRow as PlatformRow, type BossViewBinding as PlatformViews, type BossViewCall as PlatformViewCall, type PhasedBossState as PlatformState,
3
+ type RoamingBossBody as MobileBody, type RoamingBossRow as MobileRow, type RoamingBossPorts as MobilePorts, type RoamingBossFight as MobileFight } from '@wildshard/engine/game/plugin/bossPhase';
4
+
5
+ /** A phased boss fight's row (SHARD-PLATFORM SF27): modes, phases, attack rows, adds, hazards and the declared view names. */
6
+ export type PhasedBossRow = PlatformRow;
7
+ /** The body a phased boss fight drives (the engine's animal, structurally). */
8
+ export type PhasedBossBody = PlatformBody;
9
+ /** What a phased boss fight is lent: arena, bodies, player, hit resolvers, rng, feed and the view bindings. */
10
+ export type PhasedBossPorts<A extends PlatformBody> = PlatformPorts<A>;
11
+ /** A phased boss fight: its `BossScript`, the body's brain, its bodies and its continuation. */
12
+ export type PhasedBossFight<A extends PlatformBody> = PlatformFight<A>;
13
+ /** A phased boss fight's continuation (its modes, clocks, hazards). */
14
+ export type PhasedBossState = PlatformState;
15
+ /** The shard's bindings for a fight's declared views: name → function of numbers. */
16
+ export type BossViewBinding = PlatformViews;
17
+ /** A declared view call as data: `[name, ...numbers]`. */
18
+ export type BossViewCall = PlatformViewCall;
19
+ /**
20
+ * A phased boss fight from its row (SF27): a declared state machine of modes with timed beats, strike rows, invulnerability
21
+ * windows, adds and arena hazards, view-free; the shard binds the named views and lends its arena.
22
+ */
23
+ export function phasedBossFight<B extends MobileBody,L,R,K extends string,A extends string,Q extends string>(row: MobileRow<K,A,Q>,ports: MobilePorts<B,L,R,K,A,Q>): MobileFight<B,L,R>;
24
+ /** Run the fixed-arena phase, combo and hazard policy. */
25
+ export function phasedBossFight<B extends PlatformBody>(row: PlatformRow, ports: PlatformPorts<B>): PlatformFight<B>;
26
+ export function phasedBossFight<B extends PlatformBody,C extends MobileBody,L,R,K extends string,A extends string,Q extends string>(row: PlatformRow|MobileRow<K,A,Q>,ports: PlatformPorts<B>|MobilePorts<C,L,R,K,A,Q>): PlatformFight<B>|MobileFight<C,L,R> {
27
+ if('kind' in row && 'random' in ports)return platformFight(row,ports);
28
+ if('kind' in row || 'random' in ports)throw new Error('Phased boss row/host policy mismatch');
29
+ return platformFight(row,ports);
30
+ }
31
+ /** A roaming phased encounter: stance modes, strike clocks, lane chains, falling hazards and mobile adds as data. */
32
+ export type RoamingBossRow<K extends string,A extends string,Q extends string> = MobileRow<K,A,Q>;
33
+ /** Exact roaming policy continuation and BossScript on the host's actual bodies and lane schema. */
34
+ export type RoamingBossFight<B extends MobileBody,L,R> = MobileFight<B,L,R>;