@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,35 @@
1
+ {
2
+ "version": 1,
3
+ "product": "nine-dragon-stack",
4
+ "ring": "cell",
5
+ "chunks": {
6
+ "bytes": 4000000
7
+ },
8
+ "tileDebt": {
9
+ "0/3/2": {
10
+ "resident": 19453408,
11
+ "triangles": 65741,
12
+ "draws": 12
13
+ },
14
+ "0/3/3": {
15
+ "resident": 61867808,
16
+ "triangles": 240585,
17
+ "draws": 34
18
+ },
19
+ "0/3/4": {
20
+ "resident": 18616828,
21
+ "triangles": 64072,
22
+ "draws": 13
23
+ },
24
+ "0/4/3": {
25
+ "resident": 24180888,
26
+ "triangles": 146216,
27
+ "draws": 31
28
+ },
29
+ "0/4/4": {
30
+ "resident": 27771836,
31
+ "triangles": 129914,
32
+ "draws": 24
33
+ }
34
+ }
35
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "budgets": {},
3
+ "wildshard/sdk-no-facade": {
4
+ "src/sharddev/kit/bakedGeometry.ts": 7,
5
+ "src/sharddev/phasedBoss.ts": 9,
6
+ "src/sharddev/species/clips.ts": 11,
7
+ "src/sharddev/speciesBrains.ts": 3,
8
+ "src/sharddev/weapons/bowProfile.ts": 1,
9
+ "src/sharddev/weapons/meleeProfile.ts": 2
10
+ }
11
+ }
@@ -0,0 +1,12 @@
1
+ export const RUNTIME_FILE_DEFAULT: 128;
2
+ export const RUNTIME_FILES_LIST: 'lint/runtime-files.json';
3
+ export interface RuntimeFilesRaise { slug: string; from: number; to: number; why: string }
4
+ export interface RuntimeFilesPolicy { about: string; default: 128; ceilings: Record<string, number>; raises: RuntimeFilesRaise[] }
5
+ /** Shape failures of a runtime-files policy, as messages. */
6
+ export function runtimeFilesShape(policy: unknown): string[];
7
+ /** The runtime/ source-file ceiling of a slug; the 128 default for any slug without a line. */
8
+ export function runtimeFileCeiling(policy: unknown, slug: string): number;
9
+ /** Read the checked-in policy of a checkout. */
10
+ export function readRuntimeFiles(root: string): unknown;
11
+ /** Shrink-only comparison of a candidate policy with its predecessor (undefined when new). */
12
+ export function compareRuntimeFiles(before: unknown, after: unknown): string[];
@@ -0,0 +1,16 @@
1
+ {
2
+ "about": "Per-shard ceilings on runtime/ source files (lint/runtime-files.mjs). Shrink-only: lower a ceiling as files leave runtime/; a rise needs a new raises line {slug, from, to, why}. Any slug without a line keeps the 128 default.",
3
+ "ceilings": {
4
+ "driftwood-isle": 128,
5
+ "pine-hollow": 148
6
+ },
7
+ "default": 128,
8
+ "raises": [
9
+ {
10
+ "from": 128,
11
+ "slug": "pine-hollow",
12
+ "to": 152,
13
+ "why": "W2 seed (coordinator, 2026-10-16, flagged for Jake): 127 today (126 + runtime/sections.ts) plus the 25 client files of progress/shard-platform/w2a-o268/README.md still to move under G450 (5)"
14
+ }
15
+ ]
16
+ }
@@ -0,0 +1,69 @@
1
+ // SHARD-PLATFORM W2 (coordinator call, flagged for Jake): a custom runtime/ holds at most 128 source files, except a
2
+ // first-party shard listed in lint/runtime-files.json, whose checked-in ceiling may be higher while W2 moves its client
3
+ // play folders into runtime/ wholesale (G450 (5)). That ceiling is shrink-only: it falls as W3 converts sim and data out,
4
+ // and it rises only with a new `raises` line naming the slug, the old and new ceiling and why. Third-party projects, the
5
+ // Template and any slug without a line keep the 128 default. The author CLI reads the ceiling only for trusted checkout
6
+ // provenance (src/sharddev/performancePolicy.ts 'warn'); every other project refuses above 128.
7
+ import { readFileSync } from 'node:fs';
8
+ import { resolve } from 'node:path';
9
+
10
+ export const RUNTIME_FILE_DEFAULT = 128;
11
+ export const RUNTIME_FILES_LIST = 'lint/runtime-files.json';
12
+
13
+ const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
14
+ const count = (value) => Number.isSafeInteger(value) && value >= 0;
15
+
16
+ /** Shape failures of a runtime-files policy, as messages. @param {unknown} policy */
17
+ export function runtimeFilesShape(policy) {
18
+ if (!object(policy)) return ['runtime-files policy must be an object'];
19
+ const failures = [];
20
+ if (Object.keys(policy).sort().join(',') !== 'about,ceilings,default,raises') failures.push('runtime-files policy needs exactly about, ceilings, default, raises');
21
+ if (policy.default !== RUNTIME_FILE_DEFAULT) failures.push(`runtime-files default must stay ${RUNTIME_FILE_DEFAULT}`);
22
+ if (typeof policy.about !== 'string' || policy.about.trim() === '') failures.push('runtime-files policy needs an about line');
23
+ if (!object(policy.ceilings) || Object.values(policy.ceilings).some(value => !count(value))) failures.push('runtime-files ceilings must be whole file counts');
24
+ if (!Array.isArray(policy.raises) || policy.raises.some(raise => !object(raise) || Object.keys(raise).sort().join(',') !== 'from,slug,to,why'
25
+ || typeof raise.slug !== 'string' || !count(raise.from) || !count(raise.to) || raise.to <= raise.from || typeof raise.why !== 'string' || raise.why.trim() === '')) {
26
+ failures.push('runtime-files raises must be {slug, from, to, why} lines with to above from');
27
+ }
28
+ return failures;
29
+ }
30
+
31
+ /** The runtime/ source-file ceiling of a slug; the default for any slug without a line. @param {unknown} policy @param {string} slug */
32
+ export function runtimeFileCeiling(policy, slug) {
33
+ const failures = runtimeFilesShape(policy);
34
+ if (failures.length > 0) throw new Error(failures.join('; '));
35
+ const ceilings = /** @type {{ ceilings: Record<string, number> }} */ (policy).ceilings;
36
+ return Object.hasOwn(ceilings, slug) ? ceilings[slug] : RUNTIME_FILE_DEFAULT;
37
+ }
38
+
39
+ /** Read the checked-in policy of a checkout. @param {string} root */
40
+ export function readRuntimeFiles(root) {
41
+ return /** @type {unknown} */ (JSON.parse(readFileSync(resolve(root, RUNTIME_FILES_LIST), 'utf8')));
42
+ }
43
+
44
+ /** Shrink-only: compare a candidate policy with its predecessor (undefined when the list is new). A ceiling may fall or
45
+ * drop freely; a rise (a slug above its old ceiling, or a new slug above the default) needs a new `raises` line whose
46
+ * from/to match it exactly. Raise lines are history: none may be removed or edited.
47
+ * @param {unknown} before @param {unknown} after @returns {string[]} */
48
+ export function compareRuntimeFiles(before, after) {
49
+ const failures = runtimeFilesShape(after);
50
+ if (failures.length > 0) return failures;
51
+ const next = /** @type {{ ceilings: Record<string, number>, raises: {slug: string, from: number, to: number, why: string}[] }} */ (after);
52
+ const previous = before === undefined ? { ceilings: {}, raises: [] } : /** @type {typeof next} */ (before);
53
+ if (before !== undefined && runtimeFilesShape(before).length > 0) return ['runtime-files predecessor is malformed'];
54
+ const line = (/** @type {{slug: string, from: number, to: number, why: string}} */ raise) => JSON.stringify([raise.slug, raise.from, raise.to, raise.why]);
55
+ const kept = new Set(next.raises.map(line));
56
+ for (const raise of previous.raises) if (!kept.has(line(raise))) failures.push(`runtime-files raise line removed or edited: ${raise.slug} ${raise.from} -> ${raise.to}`);
57
+ const old = new Set(previous.raises.map(line));
58
+ const fresh = next.raises.filter(raise => !old.has(line(raise)));
59
+ const used = new Set();
60
+ for (const [slug, ceiling] of Object.entries(next.ceilings)) {
61
+ const was = Object.hasOwn(previous.ceilings, slug) ? previous.ceilings[slug] : RUNTIME_FILE_DEFAULT;
62
+ if (ceiling <= was) continue;
63
+ const raise = fresh.find(item => item.slug === slug && item.from === was && item.to === ceiling);
64
+ if (raise === undefined) failures.push(`runtime-files: ${slug} ceiling rises ${was} -> ${ceiling} without a raises line {slug, from: ${was}, to: ${ceiling}, why}`);
65
+ else used.add(raise);
66
+ }
67
+ for (const raise of fresh) if (!used.has(raise)) failures.push(`runtime-files: raise line ${raise.slug} ${raise.from} -> ${raise.to} matches no ceiling change`);
68
+ return failures;
69
+ }
@@ -0,0 +1,6 @@
1
+ export interface RuntimePerformanceIssue { kind: string; start: number; end: number; line: number; site: string; message: string }
2
+ export interface RuntimePerformanceDebt { count: number; row: string }
3
+ export function runtimePerformanceSites(source: string, filename?: string, supplied?: object | null): RuntimePerformanceIssue[];
4
+ export function runtimePerformanceViolations(source: string, filename: string, baseline?: Readonly<Record<string, RuntimePerformanceDebt>>, supplied?: object | null): RuntimePerformanceIssue[];
5
+ /** Exact frozen bytes retain their historical debt without granting it to the live primary. */
6
+ export function frozenRuntimePerformanceViolations(source: string, filename: string, primary: string, digest: string, baseline: Readonly<Record<string, RuntimePerformanceDebt>>, supplied?: object | null): RuntimePerformanceIssue[];
@@ -0,0 +1,184 @@
1
+ // SF62: one syntax-only pass. No TypeScript program or renderer is created by this guard.
2
+ import { parseSync } from 'vite';
3
+ import { createHash } from 'node:crypto';
4
+
5
+ const FUNCTIONS = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
6
+ const HOT = /^(?:update|tick|think|step|frame|advance|run|render|onTick|onUpdate)/u;
7
+ const SCHEDULERS = new Set(['system', 'onUpdate', 'onInput', 'onLate', 'onFixed', 'onStep', 'watchFrames']);
8
+ const ALLOCATING = new Set(['clone', 'map', 'flatMap', 'filter', 'slice', 'concat', 'split', 'match', 'matchAll', 'replace', 'replaceAll', 'toArray', 'toSorted', 'toReversed', 'keys', 'values', 'entries', 'from', 'of']);
9
+ const RAW = new Set(['renderer', 'rootScene', 'scene', 'getContext', 'WebGLRenderer', 'WebGLRenderingContext', 'WebGL2RenderingContext', 'Scene']);
10
+ const DOM = new Set(['window', 'document', 'createElement', 'querySelector', 'querySelectorAll', 'getElementById', 'innerHTML', 'outerHTML', 'appendChild']);
11
+ const ASYNC = new Set(['fetch', 'setTimeout', 'setInterval', 'requestAnimationFrame', 'timeout', 'interval', 'raf']);
12
+ const unwrap = node => {
13
+ let value = node;
14
+ while (['TSAsExpression', 'TSSatisfiesExpression', 'ParenthesizedExpression', 'TSNonNullExpression', 'ChainExpression'].includes(value?.type)) value = value.expression;
15
+ return value;
16
+ };
17
+ // Oxlint's supplied AST uses ranges; standalone parses expose start/end.
18
+ // Read either representation without modifying or retaining the caller's AST.
19
+ const startOf = node => node.start ?? node.range[0];
20
+ const endOf = node => node.end ?? node.range[1];
21
+ // Each analysis has several whole-file and function-body passes. Index the
22
+ // immutable parse once; subtree intervals preserve the original preorder.
23
+ const indexedWalk = program => {
24
+ const rows = [], ranges = new Map();
25
+ const index = (node, parent = null) => {
26
+ if (!node || typeof node.type !== 'string') return;
27
+ const start = rows.length;
28
+ rows.push({ node, parent });
29
+ for (const key of Object.keys(node)) {
30
+ if (key === 'parent') continue;
31
+ const value = node[key];
32
+ if (Array.isArray(value)) { for (const item of value) index(item, node); }
33
+ else index(value, node);
34
+ }
35
+ ranges.set(node, { start, end: rows.length });
36
+ };
37
+ index(program);
38
+ return (node, visit) => {
39
+ const range = ranges.get(node);
40
+ if (range === undefined) return;
41
+ for (let i = range.start; i < range.end; i++) {
42
+ const row = rows[i];
43
+ visit(row.node, i === range.start ? null : row.parent);
44
+ }
45
+ };
46
+ };
47
+
48
+ /** Exact source-site identities survive line moves, but never allow new code or another copy of a violation. */
49
+ export function runtimePerformanceSites(source, filename = 'runtime.ts', supplied = null) {
50
+ const parsed = supplied === null ? parseSync(filename, source) : null;
51
+ const issues = [], constants = new Map(), funcs = [], parents = new Map();
52
+ if (parsed !== null && parsed.errors.length > 0) return [{ kind: 'syntax', start: 0, end: source.length, line: 1, site: 'syntax', message: 'Runtime source must parse before it can be checked' }];
53
+ const program = supplied ?? parsed.program;
54
+ const walk = indexedWalk(program);
55
+ const ambiguous = new Set();
56
+ walk(program, (node, parent) => {
57
+ parents.set(node, parent);
58
+ if (node.type === 'VariableDeclarator' && node.id.type === 'Identifier') {
59
+ if (constants.has(node.id.name) || parent?.kind !== 'const') ambiguous.add(node.id.name);
60
+ constants.set(node.id.name, node.init);
61
+ }
62
+ if (FUNCTIONS.has(node.type)) for (const param of node.params) if (param.type === 'Identifier') ambiguous.add(param.name);
63
+ });
64
+ const constant = (raw, seen = new Set()) => {
65
+ const node = unwrap(raw); if (!node) return undefined;
66
+ if (node.type === 'Literal') return node.value;
67
+ if (node.type === 'Identifier' && !seen.has(node.name) && !ambiguous.has(node.name)) { const next = new Set(seen); next.add(node.name); return constant(constants.get(node.name), next); }
68
+ if (node.type === 'UnaryExpression' && node.operator === '-') { const value = constant(node.argument, seen); return typeof value === 'number' ? -value : undefined; }
69
+ return undefined;
70
+ };
71
+ const name = raw => {
72
+ const node = unwrap(raw); if (!node) return null;
73
+ if (node.type === 'Identifier') return node.name;
74
+ if (node.type === 'MemberExpression') return node.computed ? constant(node.property) : node.property.name;
75
+ return null;
76
+ };
77
+ walk(program, node => {
78
+ if (!FUNCTIONS.has(node.type)) return;
79
+ const parent = parents.get(node), grand = parents.get(parent);
80
+ const id = node.id?.name ?? (parent?.type === 'VariableDeclarator' ? name(parent.id) : ['Property', 'MethodDefinition', 'PropertyDefinition'].includes(parent?.type) ? name(parent.key) ?? constant(parent.key) : null);
81
+ const call = parent?.type === 'CallExpression' ? parent : grand?.type === 'CallExpression' ? grand : null;
82
+ const scheduled = call !== null && SCHEDULERS.has(name(call.callee));
83
+ funcs.push({ node, id, hot: scheduled || (typeof id === 'string' && HOT.test(id)), calls: new Set() });
84
+ });
85
+ const alias = (id, seen = new Set()) => {
86
+ if (seen.has(id)) return id; seen.add(id);
87
+ const initial = unwrap(constants.get(id)); return initial?.type === 'Identifier' ? alias(initial.name, seen) : id;
88
+ };
89
+ walk(program, node => { if (node.type === 'Property' && HOT.test(name(node.key) ?? constant(node.key) ?? '')) for (const fn of funcs) if (fn.id !== null && alias(name(node.value)) === fn.id) fn.hot = true; });
90
+ walk(program, node => { if (node.type === 'CallExpression' && SCHEDULERS.has(name(node.callee))) for (const arg of node.arguments) for (const fn of funcs) if (fn.id !== null && alias(name(arg)) === fn.id) fn.hot = true; });
91
+ for (const fn of funcs) walk(fn.node.body, node => { if (node.type === 'CallExpression') fn.calls.add(alias(name(node.callee))); });
92
+ // Local helpers called by a frame callback are hot too; aliasing a local helper does not hide its body.
93
+ // Preserve every same-named candidate, including nested/shadowed helpers.
94
+ // Index that conservative graph once instead of rescanning all functions in
95
+ // every propagation round and again at every recursive reachability step.
96
+ const named = new Map(), edges = new Map();
97
+ for (const fn of funcs) if (fn.id !== null) {
98
+ const group = named.get(fn.id) ?? [];
99
+ group.push(fn); named.set(fn.id, group);
100
+ }
101
+ for (const fn of funcs) {
102
+ const targets = new Set();
103
+ for (const called of fn.calls) for (const target of named.get(called) ?? []) targets.add(target);
104
+ edges.set(fn, targets);
105
+ }
106
+ const pending = funcs.filter(fn => fn.hot);
107
+ for (let index = 0; index < pending.length; index++) for (const target of edges.get(pending[index])) if (!target.hot) {
108
+ target.hot = true; pending.push(target);
109
+ }
110
+ const inside = node => funcs.some(fn => fn.hot && startOf(node) >= startOf(fn.node.body) && endOf(node) <= endOf(fn.node.body));
111
+ const issue = (node, kind, message) => {
112
+ const start = startOf(node), end = endOf(node);
113
+ const text = source.slice(start, end).replaceAll(/\s+/gu, ' ').trim();
114
+ const site = createHash('sha256').update(`${kind}:${text}`).digest('hex');
115
+ issues.push({ kind, start, end, line: source.slice(0, start).split('\n').length, site, message });
116
+ };
117
+ const bound = raw => {
118
+ const node = unwrap(raw), value = constant(node);
119
+ if (Number.isSafeInteger(value)) return true;
120
+ return node?.type === 'CallExpression' && name(node.callee) === 'min' && name(node.callee.object) === 'Math' && node.arguments.some(arg => Number.isSafeInteger(constant(arg)));
121
+ };
122
+ const bounded = node => {
123
+ if (['WhileStatement', 'DoWhileStatement'].includes(node.type)) return constant(node.test) === false;
124
+ if (node.type === 'ForOfStatement') { const right = unwrap(node.right); return right?.type === 'ArrayExpression' && right.elements.every(item => item !== null && constant(item) !== undefined); }
125
+ if (node.type !== 'ForStatement') return false;
126
+ const init = node.init?.declarations?.[0], id = init?.id?.name, test = unwrap(node.test), update = unwrap(node.update);
127
+ if (!id || !bound(init.init) || test?.type !== 'BinaryExpression' || name(test.left) !== id || !bound(test.right)) return false;
128
+ const ascending = ['<', '<='].includes(test.operator), descending = ['>', '>='].includes(test.operator);
129
+ const progress = update?.type === 'UpdateExpression' && name(update.argument) === id && ((ascending && update.operator === '++') || (descending && update.operator === '--'));
130
+ if (!progress) return false;
131
+ let changed = false;
132
+ walk(node.body, body => { if ((body.type === 'AssignmentExpression' && name(body.left) === id) || (body.type === 'UpdateExpression' && name(body.argument) === id)) changed = true; });
133
+ return !changed;
134
+ };
135
+ walk(program, (node, parent) => {
136
+ // Type-only imports/declarations do not acquire a runtime renderer or DOM handle.
137
+ let ancestor = node;
138
+ while (ancestor) { if (ancestor.type.startsWith('TS') && !['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'TSInstantiationExpression'].includes(ancestor.type)) return; ancestor = parents.get(ancestor); }
139
+ if (parent?.importKind === 'type' || parents.get(parent)?.importKind === 'type') return;
140
+ const member = node.type === 'MemberExpression' ? name(node) : null;
141
+ const identifier = node.type === 'Identifier' && !(parent?.type === 'MemberExpression' && parent.property === node && !parent.computed) && !(parent?.type === 'Property' && parent.key === node && !parent.computed && parents.get(parent)?.type !== 'ObjectPattern') ? node.name : null;
142
+ const access = member ?? identifier;
143
+ if (RAW.has(access)) issue(node, 'raw-render', 'Runtime must use engine tiles, recipes and registry instead of raw scene/renderer/WebGL');
144
+ if (DOM.has(access)) issue(node, 'dom', 'Runtime cannot access DOM; use the owned platform UI ports');
145
+ if (ASYNC.has(access)) issue(node, 'async', 'Runtime uses fixed-step state, not timers or fetch');
146
+ if (['ForStatement', 'ForOfStatement', 'ForInStatement', 'WhileStatement', 'DoWhileStatement'].includes(node.type) && !bounded(node)) issue(node, 'unbounded-loop', 'Runtime loops require a statically finite counter or literal collection');
147
+ if (!inside(node)) return;
148
+ if (['NewExpression', 'ArrayExpression', 'ObjectExpression', 'ArrowFunctionExpression', 'FunctionExpression'].includes(node.type)) issue(node, 'frame-allocation', 'Reuse state and buffers instead of allocating inside frame callbacks');
149
+ if (node.type === 'TemplateLiteral' && node.expressions.length > 0) issue(node, 'frame-allocation', 'Move dynamic strings out of the frame loop');
150
+ if (node.type === 'CallExpression' && ALLOCATING.has(name(node.callee))) issue(node, 'frame-allocation', 'Allocating collection/string methods belong outside frame callbacks');
151
+ if (node.type === 'BinaryExpression' && node.operator === '+' && (typeof constant(node.left) === 'string' || typeof constant(node.right) === 'string') && !(constant(node.left) !== undefined && constant(node.right) !== undefined)) issue(node, 'frame-allocation', 'Move dynamic strings out of the frame loop');
152
+ });
153
+ // Recursive helpers have no finite runtime bound. Include mutual recursion, not just direct self calls.
154
+ const reaches = (from, to, seen = new Set()) => {
155
+ if (seen.has(from)) return false; seen.add(from);
156
+ for (const target of edges.get(from)) if (target === to || reaches(target, to, seen)) return true;
157
+ return false;
158
+ };
159
+ for (const fn of funcs) if (fn.hot && reaches(fn, fn)) issue(fn.node, 'unbounded-loop', 'Recursive frame helpers have no statically finite bound');
160
+ return issues.sort((a, b) => a.start - b.start || a.kind.localeCompare(b.kind));
161
+ }
162
+
163
+ /** Existing transition debt is exact by path, syntax hash and multiplicity; outside projects receive no allowance. */
164
+ export function runtimePerformanceViolations(source, filename, baseline = {}, supplied = null) {
165
+ const counts = new Map();
166
+ return runtimePerformanceSites(source, filename, supplied).filter(issue => {
167
+ const key = `${filename}:${issue.kind}:${issue.site}`, count = (counts.get(key) ?? 0) + 1; counts.set(key, count);
168
+ return count > (baseline[key]?.count ?? 0);
169
+ });
170
+ }
171
+
172
+ /** Frozen files retain only exact historical site debt; changed bytes gain no historical allowance. */
173
+ const frozenIndexes = new Map();
174
+ export function frozenRuntimePerformanceViolations(source, filename, primary, digest, baseline, supplied = null) {
175
+ if (createHash('sha256').update(source).digest('hex') !== digest) return runtimePerformanceViolations(source, filename, {}, supplied);
176
+ let sites = frozenIndexes.get(digest);
177
+ if (sites === undefined) { sites = runtimePerformanceSites(source, filename, supplied); frozenIndexes.set(digest, sites); }
178
+ const counts = new Map();
179
+ return sites.filter(issue => {
180
+ const suffix = `:${issue.kind}:${issue.site}`, key = filename + suffix;
181
+ const count = (counts.get(key) ?? 0) + 1; counts.set(key, count);
182
+ return count > (baseline[key]?.count ?? baseline[primary + suffix]?.count ?? 0);
183
+ }).map(issue => ({ kind: issue.kind, start: issue.start, end: issue.end, line: issue.line, site: issue.site, message: issue.message }));
184
+ }
@@ -0,0 +1,4 @@
1
+ /** Why `source` may not be imported from `filename` under a shard's author folders, or null when it may. */
2
+ export function generatorImportViolation(filename: string, source: string | null, required?: boolean): string | null;
3
+ declare const plugin: { readonly meta: { readonly name: string }; readonly rules: Readonly<Record<string, object>> };
4
+ export default plugin;
@@ -0,0 +1,134 @@
1
+ // The SDK's own authoring lint rules, loaded beside engine's plugin by `.oxlintrc.author.json` (here as
2
+ // `./lint/sdk-plugin.mjs`, in a shard repo from `node_modules/@wildshard/sdk/lint/sdk-plugin.mjs`, or the old
3
+ // `@wildshard/sharddev` folder until SHARD-COMPAT SA7b).
4
+ // SHARD-AUTHORING SA6: `generator-imports` moved here from engine's plugin so the rule an author runs comes with the SDK
5
+ // pin, not the engine pin.
6
+ // SHARD-AUTHORING SA38 (J319): generators are arbitrary Node code, so in `generators/` the rule is a denylist of
7
+ // Wildshard cheats (the engine, sdk paths outside its exports, another shard's source, a second three); any npm
8
+ // package, valibot and node:* pass. data/, quests/ and shard.config.ts keep the authoring allowlist, minus the engine.
9
+ import { readFileSync } from 'node:fs';
10
+ import { isBuiltin } from 'node:module';
11
+ import { dirname, isAbsolute, resolve } from 'node:path';
12
+ import { fileURLToPath } from 'node:url';
13
+
14
+ const RULE = 'generator-imports';
15
+ // Not visible to a lint, left for later: `#` subpath imports and tsconfig `paths` aliases (they name no package), and
16
+ // `createRequire(...)(...)` calls.
17
+ // The authoring surface for data/, quests/ and shard.config.ts (DS0.3, J170): three; the SDK and commons; the shard
18
+ // format and valibot, the language the format's schemas are written in; and Node's built-ins.
19
+ const AUTHOR_PACKAGE = /^(?:three|valibot|@wildshard\/(?:format|shard-format|sdk|sharddev|commons))(?:\/|$)/u;
20
+ const SDK_PACKAGE = /^@wildshard\/(?:sdk|sharddev)(?:\/(.*))?$/u;
21
+ // Another shard's repo package (`@wildshard/shard-dunes`); the shard format is not a shard.
22
+ const SHARD_PACKAGE = /^@wildshard\/shard-(?!format(?:\/|$))[^/]+/u;
23
+
24
+ // The pinned sdk's public subpaths: the exports of the package.json this file ships in.
25
+ const SDK_EXPORTS = Object.keys(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).exports ?? {});
26
+ const sdkExports = (subpath) => SDK_EXPORTS.some((key) => {
27
+ const star = key.indexOf('*');
28
+ return star === -1 ? key === subpath
29
+ : subpath.length >= key.length && subpath.startsWith(key.slice(0, star)) && subpath.endsWith(key.slice(star + 1));
30
+ });
31
+
32
+ const ENGINE = `${RULE}: shard source may not import @wildshard/engine (any subpath, host included); import the sdk or `
33
+ + 'format export instead, e.g. @wildshard/sdk/immutable or @wildshard/format/shardSchema';
34
+ const secondThree = (source) => `${RULE}: ${source} loads a second copy of three beside the shard's peer three; `
35
+ + "import from 'three' (or 'three/addons/...')";
36
+ const otherShard = (name) => `${RULE}: this import reaches into another shard's source (${name}); copy what the shard `
37
+ + 'needs into its own folder, or ask for it in @wildshard/sdk';
38
+ const notExported = (source) => `${RULE}: ${source} is not in the sdk's package.json exports; import one of the `
39
+ + 'listed exports (node_modules/@wildshard/sdk/package.json "exports")';
40
+
41
+ /** The Wildshard cheats, refused in every author folder: null when `source` is none of them. */
42
+ function cheat(source, local, required) {
43
+ if (/^@wildshard\/engine(?:\/|$)/u.test(source)) return ENGINE;
44
+ // three's ESM build is the one copy; its sources, its build files by name and a require() of three (the CJS build)
45
+ // are each a second copy. Still open: an aliased three (`npm:three@x` under another name) and `three/webgpu`.
46
+ if (/^three\/(?:src|build)(?:\/|$)/u.test(source) || (required && /^three(?:\/|$)/u.test(source))) return secondThree(source);
47
+ const shard = SHARD_PACKAGE.exec(source);
48
+ if (shard !== null) return otherShard(shard[0]);
49
+ const sdk = SDK_PACKAGE.exec(source);
50
+ if (sdk !== null) {
51
+ if (/^runtime(?:\/|$)/u.test(sdk[1] ?? '')) {
52
+ return `${RULE}: trusted SDK runtime code is not an authoring import; import an exported sdk subpath instead`;
53
+ }
54
+ if (/(?:^|\/)\.\.?(?:\/|$)/u.test(sdk[1] ?? '')) return notExported(source);
55
+ return sdkExports(sdk[1] === undefined ? '.' : `./${sdk[1]}`) ? null : notExported(source);
56
+ }
57
+ // A path into installed packages: the part after the last node_modules names the package.
58
+ const at = local.lastIndexOf('/node_modules/');
59
+ const installed = at === -1 ? null : /^\/node_modules\/((?:@[^/]+\/)?[^/]+)/u.exec(local.slice(at))?.[1];
60
+ if (installed === '@wildshard/engine') return ENGINE;
61
+ if (installed === 'three') return secondThree(source);
62
+ if (installed !== undefined && installed !== null && SHARD_PACKAGE.test(installed)) return otherShard(installed);
63
+ // The sdk's own source, by path (this repo's src/sharddev, or an installed copy).
64
+ if (installed === '@wildshard/sdk' || installed === '@wildshard/sharddev' || /\/src\/sharddev(?:\/|$)/u.test(local)) {
65
+ return `${RULE}: ${source} reaches @wildshard/sdk files by path; import the package by name through one of its `
66
+ + 'package.json exports';
67
+ }
68
+ return null;
69
+ }
70
+
71
+ /** Why `source` may not be imported from `filename` under a shard's author folders, or null when it may. */
72
+ export function generatorImportViolation(filename, rawSource, required = false) {
73
+ // The last src/shards/ in the path names the shard, so a checkout under some other src/shards/ still matches.
74
+ const path = resolve(filename).replaceAll('\\', '/'), match = /^.*\/src\/shards\/([^/]+)\/(.+)$/u.exec(path);
75
+ if (match === null || !(/^(?:generators|data|quests)\//u.test(match[2]) || match[2] === 'shard.config.ts')) return null;
76
+ if (typeof rawSource !== 'string') return null;
77
+ const source = rawSource.startsWith('file:') ? fileURLToPath(rawSource) : rawSource;
78
+ if (source === '<computed>') return `${RULE}: author imports require a literal module path; write the path as a string`;
79
+ const root = path.slice(0, path.length - match[2].length);
80
+ const local = source.startsWith('.') || isAbsolute(source) ? resolve(dirname(filename), source).replaceAll('\\', '/') : '';
81
+ const denied = cheat(source, local, required);
82
+ if (denied !== null) return denied;
83
+ const own = local !== '' && local.startsWith(root);
84
+ const other = local === '' || own ? null : /^.*\/src\/shards\/([^/]+)\//u.exec(local);
85
+ if (other) return otherShard(other[1]);
86
+ if (match[2].startsWith('generators/')) return null;
87
+ // Test runners and Node fixture tools never become producer imports.
88
+ if (path.endsWith('.test.ts') && local === '' && !source.startsWith('@wildshard/')) return null;
89
+ if (own || AUTHOR_PACKAGE.test(source) || isBuiltin(source)) return null;
90
+ return `${RULE}: data, quests and shard.config.ts import only three, the sdk, commons, the shard format, valibot, `
91
+ + 'node:* or their own shard files; move this import into generators/';
92
+ }
93
+
94
+ const unwrap = (node) => {
95
+ let x = node;
96
+ while (x && ['ChainExpression', 'TSNonNullExpression', 'TSAsExpression', 'TSSatisfiesExpression', 'ParenthesizedExpression'].includes(x.type)) x = x.expression;
97
+ return x;
98
+ };
99
+ // A template literal or a '+' chain resolves by its leading string; anything else is not a literal path.
100
+ const importPrefix = (node) => {
101
+ const x = unwrap(node);
102
+ if (x?.type === 'BinaryExpression' && x.operator === '+') return importPrefix(x.left);
103
+ if (x?.type === 'Literal' && typeof x.value === 'string') return x.value;
104
+ return x?.type === 'TemplateLiteral' ? x.quasis[0]?.value.cooked ?? null : null;
105
+ };
106
+ const computedSpecifier = (node) => {
107
+ const x = unwrap(node);
108
+ return (x?.type === 'TemplateLiteral' && x.expressions.length > 0) || (x?.type === 'BinaryExpression' && x.operator === '+');
109
+ };
110
+
111
+ const generatorImports = {
112
+ meta: { type: 'problem', docs: { description: 'Generators import anything but Wildshard cheats (J319); data and quests stay on the authoring surface (DS0.3, J170)' }, schema: [] },
113
+ create(context) {
114
+ const check = (node, specifier, required = false) => {
115
+ const prefix = importPrefix(specifier), source = computedSpecifier(specifier) || prefix === null ? '<computed>' : prefix;
116
+ const reason = generatorImportViolation(context.filename, source, required);
117
+ if (reason !== null) context.report({ node, message: `${reason} (import: ${source})` });
118
+ };
119
+ return {
120
+ ImportDeclaration(node) { check(node, node.source); },
121
+ ExportNamedDeclaration(node) { if (node.source) check(node, node.source); },
122
+ ExportAllDeclaration(node) { check(node, node.source); },
123
+ ImportExpression(node) { check(node, node.source); },
124
+ TSImportType(node) { check(node, node.source ?? node.argument); },
125
+ TSExternalModuleReference(node) { check(node, node.expression); },
126
+ CallExpression(node) {
127
+ if (node.callee.type === 'Identifier' && node.callee.name === 'require') check(node, node.arguments[0], true);
128
+ },
129
+ };
130
+ },
131
+ };
132
+
133
+ const plugin = { meta: { name: 'wildshard-sdk' }, rules: { 'generator-imports': generatorImports } };
134
+ export default plugin; // oxlint loads a JS plugin from its default export
@@ -0,0 +1,10 @@
1
+ export interface ShardfileBoundaryIssue {
2
+ rule: 'runtime-standalone' | 'no-build-time-import' | 'no-runtime-in-build';
3
+ message: string;
4
+ start: number;
5
+ end: number;
6
+ }
7
+ /** Parse source using the same visitors as oxlint; no migration allowance is applied. */
8
+ export function shardfileBoundaryViolations(root: string, file: string, source: string): ShardfileBoundaryIssue[];
9
+ /** Adapter for ESLint-compatible AST dispatch. */
10
+ export function shardfileBoundaryVisitors(root: string, file: string, rule: ShardfileBoundaryIssue['rule'], report: (node: { start: number; end: number }, message: string) => void): Record<string, (node: object) => void>;
@@ -0,0 +1,122 @@
1
+ // G450 / shardfile design §3.3. Shared by oxlint and the verbatim runtime copier.
2
+ import { existsSync, readFileSync } from 'node:fs';
3
+ import { dirname, relative, resolve } from 'node:path';
4
+ import { parseSync } from 'vite';
5
+
6
+ const BUILD = /^(?:data|generators|bake|behaviour|assets|blender)(?:\/|$)|^shard\.config(?:\.[cm]?[jt]s)?$/u;
7
+ const PLAY = /^(?:runtime|world|look|models|weapons|quest|quests|combat|species|creatures|npc|loadout|ride|vm|grapple|life|compendium|boot|debug|dev|playground|explore|audio|loot|onboarding)(?:\/|$)/u;
8
+ const shard = path => /^src\/shards\/([^/]+)\/(.+)$/u.exec(path);
9
+ const text = node => node?.type === 'Literal' && typeof node.value === 'string' ? node.value
10
+ : node?.type === 'TemplateLiteral' && node.expressions.length === 0 ? node.quasis[0]?.value.cooked ?? null : null;
11
+ const prefix = node => text(node) ?? (node?.type === 'TemplateLiteral' ? node.quasis[0]?.value.cooked
12
+ : node?.type === 'BinaryExpression' && node.operator === '+' ? prefix(node.left) : null);
13
+ const member = (node, name) => node?.type === 'MemberExpression' && (node.computed ? text(node.property) : node.property?.name) === name;
14
+ const importMeta = node => node?.type === 'MetaProperty' && node.meta.name === 'import' && node.property.name === 'meta';
15
+ const packages = new Map();
16
+
17
+ function publicPackage(root, source) {
18
+ if (source === 'three' || source.startsWith('three/') || source === 'valibot') return true;
19
+ const pkg = /^@wildshard\/(engine|game|sdk|sharddev|format)(?:\/(.+))?$/u.exec(source);
20
+ if (pkg === null) return false;
21
+ const file = resolve(root, 'src', pkg[1], 'package.json');
22
+ if (!packages.has(file)) packages.set(file, existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')).exports ?? {} : {});
23
+ const sub = pkg.at(2);
24
+ return Object.hasOwn(packages.get(file), sub === undefined ? '.' : `./${sub}`);
25
+ }
26
+
27
+ function target(root, file, source) {
28
+ const clean = source.replace(/[?#].*$/u, '');
29
+ if (clean.startsWith('.')) return relative(root, resolve(root, dirname(file), clean)).replaceAll('\\', '/');
30
+ if (clean.startsWith('/src/')) return clean.slice(1);
31
+ if (clean.startsWith('src/')) return clean;
32
+ const absolute = relative(root, clean).replaceAll('\\', '/');
33
+ return absolute.startsWith('src/') ? absolute : null;
34
+ }
35
+
36
+ function violation(root, file, source, computed, glob, rule) {
37
+ const own = shard(file), dest = source === null ? null : target(root, file, source);
38
+ const other = dest === null ? null : shard(dest);
39
+ const build = own !== null && BUILD.test(own[2]);
40
+ if (rule === 'runtime-standalone') {
41
+ if (own === null || !own[2].startsWith('runtime/')) return null;
42
+ if (computed || source === null) return 'runtime/ imports must have a statically closed path';
43
+ if (/[?#]/u.test(source)) return 'runtime/ cannot import assets, JSON, ?raw or ?url; read the admitted product instead';
44
+ if (/\.[^/]+$/u.test(source) && !/\.[cm]?[jt]sx?$/u.test(source)) return `runtime/ cannot import JSON or assets: ${source}; read the admitted product instead`;
45
+ if (dest === null) return publicPackage(root, source) ? null : `runtime/ imports only its own files and public engine/game/SDK/format, three or valibot modules: ${source}`;
46
+ if (!dest.startsWith(`src/shards/${own[1]}/runtime/`)) return `runtime/ is standalone: ${source} leaves its own runtime/; read a built section or move play code into runtime/`;
47
+ if (/\.[^/]+$/u.test(dest) && !/\.[cm]?tsx?$/u.test(dest) || glob && !/\.[cm]?tsx?$/u.test(dest)) return `runtime/ cannot import JSON or assets: ${source}; read the admitted product instead`;
48
+ return null;
49
+ }
50
+ if (rule === 'no-build-time-import') {
51
+ if (!file.startsWith('src/') || file.startsWith('src/commons/') || /^src\/sharddev\/(?:cli|bake)\//u.test(file)) return null;
52
+ if (other === null || !BUILD.test(other[2])) {
53
+ return computed && dest?.startsWith('src/shards/') && !build ? `Play code cannot compute a path into shard build-time folders: ${source}` : null;
54
+ }
55
+ if (build && own[1] === other[1]) return null;
56
+ return `Play code cannot import build-time code: ${source}; read it from the built shard's sections or blobs`;
57
+ }
58
+ if (!build || other === null) return null;
59
+ if (PLAY.test(other[2]) || (!BUILD.test(other[2]) && /\.[cm]?[jt]sx?$/u.test(other[2]))) return `Build-time code cannot import play code: ${source}; move shared facts into data/ and read the output at runtime`;
60
+ // Extensionless imports of legacy root play modules (plugin, roster, layout, etc.).
61
+ if (!BUILD.test(other[2]) && !other[2].includes('/') && !/\./u.test(other[2])) return `Build-time code cannot import legacy play code: ${source}; declare build facts in data/`;
62
+ return null;
63
+ }
64
+
65
+ /** Same AST visitors for the linter and copier. Type-only, lazy and resource imports are all boundaries. */
66
+ export function shardfileBoundaryVisitors(root, file, rule, report) {
67
+ const own = shard(file);
68
+ if (rule === 'runtime-standalone' && !own?.[2].startsWith('runtime/')) return {};
69
+ if (rule === 'no-runtime-in-build' && (own === null || !BUILD.test(own[2]))) return {};
70
+ const check = (node, raw, glob = false) => {
71
+ const source = prefix(raw) ?? null;
72
+ const reason = violation(root, file, source, text(raw) === null, glob, rule);
73
+ if (reason !== null) report(node, reason);
74
+ };
75
+ return {
76
+ ImportDeclaration(node) { check(node, node.source); },
77
+ ExportNamedDeclaration(node) { if (node.source) check(node, node.source); },
78
+ ExportAllDeclaration(node) { check(node, node.source); },
79
+ ImportExpression(node) { check(node, node.source); },
80
+ TSImportType(node) { check(node, node.source); },
81
+ TSExternalModuleReference(node) { check(node, node.expression); },
82
+ CallExpression(node) {
83
+ if (node.callee.type === 'Identifier' && node.callee.name === 'require') check(node, node.arguments[0]);
84
+ if ((member(node.callee, 'glob') || member(node.callee, 'globEager')) && importMeta(node.callee.object)) {
85
+ const raw = node.arguments[0], patterns = raw?.type === 'ArrayExpression' ? raw.elements : [raw];
86
+ if (rule === 'runtime-standalone' && shard(file)?.[2].startsWith('runtime/') && node.arguments[1]?.type === 'ObjectExpression'
87
+ && node.arguments[1].properties.some(property => ['query', 'as'].includes(property.key?.name ?? text(property.key)))) {
88
+ report(node, 'runtime/ globs cannot transform modules into assets with query/as');
89
+ }
90
+ for (const pattern of patterns) {
91
+ // Negative glob patterns only remove files; positive patterns must prove the boundary.
92
+ if (!(text(pattern) ?? '').startsWith('!')) check(node, pattern, true);
93
+ }
94
+ }
95
+ },
96
+ NewExpression(node) {
97
+ if (node.callee.type === 'Identifier' && node.callee.name === 'URL' && member(node.arguments[1], 'url') && importMeta(node.arguments[1].object)) check(node, node.arguments[0]);
98
+ },
99
+ };
100
+ }
101
+
102
+ /** Raw violations, without migration allowances. `file` is the source-relative src/shards/... path.
103
+ * @returns {{rule: string, message: string, start: number, end: number}[]} */
104
+ export function shardfileBoundaryViolations(root, file, source) {
105
+ const parsed = parseSync(file, source);
106
+ if (parsed.errors.length > 0) throw new Error(`Cannot check shard imports: ${file}: ${parsed.errors[0].message}`);
107
+ const found = [];
108
+ for (const rule of ['runtime-standalone', 'no-build-time-import', 'no-runtime-in-build']) {
109
+ const visitors = shardfileBoundaryVisitors(root, file, rule, (node, message) => found.push({ rule, message, start: node.start, end: node.end }));
110
+ const walk = node => {
111
+ if (node === null || typeof node !== 'object') return;
112
+ if (node.type !== undefined) visitors[node.type]?.(node);
113
+ for (const [key, value] of Object.entries(node)) {
114
+ if (key === 'parent' || key === 'comments') continue;
115
+ if (Array.isArray(value)) { for (const child of value) walk(child); }
116
+ else if (value !== null && typeof value === 'object') walk(value);
117
+ }
118
+ };
119
+ walk(parsed.program);
120
+ }
121
+ return found;
122
+ }