@woosh/meep-engine 3.22.0 → 3.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (267) hide show
  1. package/package.json +1 -1
  2. package/src/core/geom/3d/hash-grid/PointHashGrid3.d.ts +118 -0
  3. package/src/core/geom/3d/hash-grid/PointHashGrid3.d.ts.map +1 -0
  4. package/src/core/geom/3d/hash-grid/PointHashGrid3.js +283 -0
  5. package/src/core/geom/3d/shape/BoxShape3D.d.ts.map +1 -1
  6. package/src/core/geom/3d/shape/BoxShape3D.js +6 -17
  7. package/src/core/geom/3d/shape/CapsuleShape3D.d.ts.map +1 -1
  8. package/src/core/geom/3d/shape/CapsuleShape3D.js +3 -14
  9. package/src/core/geom/3d/shape/CylinderShape3D.d.ts.map +1 -1
  10. package/src/core/geom/3d/shape/CylinderShape3D.js +3 -21
  11. package/src/core/geom/3d/shape/PlaneShape3D.d.ts +105 -0
  12. package/src/core/geom/3d/shape/PlaneShape3D.d.ts.map +1 -0
  13. package/src/core/geom/3d/shape/PlaneShape3D.js +251 -0
  14. package/src/core/geom/3d/shape/SphereShape3D.js +3 -3
  15. package/src/core/geom/3d/shape/json/shape_to_type.d.ts.map +1 -1
  16. package/src/core/geom/3d/shape/json/shape_to_type.js +3 -0
  17. package/src/core/geom/3d/shape/json/type_adapters.d.ts +14 -0
  18. package/src/core/geom/3d/shape/json/type_adapters.d.ts.map +1 -1
  19. package/src/core/geom/3d/shape/json/type_adapters.js +15 -0
  20. package/src/core/geom/3d/shape/sdf/sdf3_box.d.ts +51 -0
  21. package/src/core/geom/3d/shape/sdf/sdf3_box.d.ts.map +1 -0
  22. package/src/core/geom/3d/shape/sdf/sdf3_box.js +113 -0
  23. package/src/core/geom/3d/shape/sdf/sdf3_capsule.d.ts +46 -0
  24. package/src/core/geom/3d/shape/sdf/sdf3_capsule.d.ts.map +1 -0
  25. package/src/core/geom/3d/shape/sdf/sdf3_capsule.js +82 -0
  26. package/src/core/geom/3d/shape/sdf/sdf3_cylinder.d.ts +60 -0
  27. package/src/core/geom/3d/shape/sdf/sdf3_cylinder.d.ts.map +1 -0
  28. package/src/core/geom/3d/shape/sdf/sdf3_cylinder.js +126 -0
  29. package/src/core/geom/3d/shape/sdf/sdf3_degenerate_normal.d.ts +50 -0
  30. package/src/core/geom/3d/shape/sdf/sdf3_degenerate_normal.d.ts.map +1 -0
  31. package/src/core/geom/3d/shape/sdf/sdf3_degenerate_normal.js +53 -0
  32. package/src/core/geom/3d/shape/sdf/sdf3_plane.d.ts +52 -0
  33. package/src/core/geom/3d/shape/sdf/sdf3_plane.d.ts.map +1 -0
  34. package/src/core/geom/3d/shape/sdf/sdf3_plane.js +61 -0
  35. package/src/core/geom/3d/shape/sdf/sdf3_sphere.d.ts +41 -0
  36. package/src/core/geom/3d/shape/sdf/sdf3_sphere.d.ts.map +1 -0
  37. package/src/core/geom/3d/shape/sdf/sdf3_sphere.js +71 -0
  38. package/src/core/process/ConcurrencyGate.d.ts +103 -0
  39. package/src/core/process/ConcurrencyGate.d.ts.map +1 -0
  40. package/src/core/process/ConcurrencyGate.js +207 -0
  41. package/src/engine/asset/AssetManager.d.ts +10 -0
  42. package/src/engine/asset/AssetManager.d.ts.map +1 -1
  43. package/src/engine/asset/AssetManager.js +10 -0
  44. package/src/engine/graphics/CONTEXT_LOSS_RECOVERY_PLAN.md +30 -13
  45. package/src/engine/graphics3/pose/collect_entity_playbacks.d.ts +26 -0
  46. package/src/engine/graphics3/pose/collect_entity_playbacks.d.ts.map +1 -0
  47. package/src/engine/graphics3/pose/collect_entity_playbacks.js +40 -0
  48. package/src/engine/graphics3/pose/query_entity_node_world_pose.d.ts.map +1 -1
  49. package/src/engine/graphics3/pose/query_entity_node_world_pose.js +74 -101
  50. package/src/engine/physics/cloth/MEASUREMENTS.md +1287 -4
  51. package/src/engine/physics/cloth/PLAN.md +1967 -1581
  52. package/src/engine/physics/cloth/build/ClothProxy.d.ts +147 -0
  53. package/src/engine/physics/cloth/build/ClothProxy.d.ts.map +1 -0
  54. package/src/engine/physics/cloth/build/ClothProxy.js +207 -0
  55. package/src/engine/physics/cloth/build/cloth_proxy_from_joints.d.ts +70 -0
  56. package/src/engine/physics/cloth/build/cloth_proxy_from_joints.d.ts.map +1 -0
  57. package/src/engine/physics/cloth/build/cloth_proxy_from_joints.js +256 -0
  58. package/src/engine/physics/cloth/collider/ClothColliderIndex.d.ts +176 -0
  59. package/src/engine/physics/cloth/collider/ClothColliderIndex.d.ts.map +1 -0
  60. package/src/engine/physics/cloth/collider/ClothColliderIndex.js +435 -0
  61. package/src/engine/physics/cloth/collider/ClothColliderKind.d.ts +12 -0
  62. package/src/engine/physics/cloth/collider/ClothColliderKind.d.ts.map +1 -0
  63. package/src/engine/physics/cloth/collider/ClothColliderKind.js +38 -0
  64. package/src/engine/physics/cloth/collider/ClothColliderRecord.d.ts +120 -0
  65. package/src/engine/physics/cloth/collider/ClothColliderRecord.d.ts.map +1 -0
  66. package/src/engine/physics/cloth/collider/ClothColliderRecord.js +137 -0
  67. package/src/engine/physics/cloth/collider/cloth_collider_bounds.d.ts +25 -0
  68. package/src/engine/physics/cloth/collider/cloth_collider_bounds.d.ts.map +1 -0
  69. package/src/engine/physics/cloth/collider/cloth_collider_bounds.js +190 -0
  70. package/src/engine/physics/cloth/collider/cloth_collider_pack.d.ts +44 -0
  71. package/src/engine/physics/cloth/collider/cloth_collider_pack.d.ts.map +1 -0
  72. package/src/engine/physics/cloth/collider/cloth_collider_pack.js +173 -0
  73. package/src/engine/physics/cloth/collider/cloth_collider_sdf.d.ts +94 -0
  74. package/src/engine/physics/cloth/collider/cloth_collider_sdf.d.ts.map +1 -0
  75. package/src/engine/physics/cloth/collider/cloth_collider_sdf.js +275 -0
  76. package/src/engine/physics/cloth/ecs/ClothCollider.d.ts +126 -0
  77. package/src/engine/physics/cloth/ecs/ClothCollider.d.ts.map +1 -0
  78. package/src/engine/physics/cloth/ecs/ClothCollider.js +199 -0
  79. package/src/engine/physics/cloth/ecs/ClothColliderFlags.d.ts +9 -0
  80. package/src/engine/physics/cloth/ecs/ClothColliderFlags.d.ts.map +1 -0
  81. package/src/engine/physics/cloth/ecs/ClothColliderFlags.js +32 -0
  82. package/src/engine/physics/cloth/ecs/ClothColliderSystem.d.ts +114 -0
  83. package/src/engine/physics/cloth/ecs/ClothColliderSystem.d.ts.map +1 -0
  84. package/src/engine/physics/cloth/ecs/ClothColliderSystem.js +243 -0
  85. package/src/engine/physics/cloth/ecs/ClothDynamicsFlags.js +66 -57
  86. package/src/engine/physics/cloth/ecs/ClothInstance.d.ts +109 -1
  87. package/src/engine/physics/cloth/ecs/ClothInstance.d.ts.map +1 -1
  88. package/src/engine/physics/cloth/ecs/ClothInstance.js +479 -363
  89. package/src/engine/physics/cloth/ecs/ClothRig.d.ts +95 -0
  90. package/src/engine/physics/cloth/ecs/ClothRig.d.ts.map +1 -0
  91. package/src/engine/physics/cloth/ecs/ClothRig.js +140 -0
  92. package/src/engine/physics/cloth/ecs/ClothSystem.d.ts +30 -1
  93. package/src/engine/physics/cloth/ecs/ClothSystem.d.ts.map +1 -1
  94. package/src/engine/physics/cloth/ecs/ClothSystem.js +1021 -773
  95. package/src/engine/physics/cloth/ecs/cloth_build_rows.d.ts +90 -0
  96. package/src/engine/physics/cloth/ecs/cloth_build_rows.d.ts.map +1 -0
  97. package/src/engine/physics/cloth/ecs/cloth_build_rows.js +374 -0
  98. package/src/engine/physics/cloth/ecs/cloth_dynamics_library.d.ts +32 -3
  99. package/src/engine/physics/cloth/ecs/cloth_dynamics_library.d.ts.map +1 -1
  100. package/src/engine/physics/cloth/ecs/cloth_dynamics_library.js +283 -254
  101. package/src/engine/physics/cloth/ecs/cloth_gather_colliders.d.ts +59 -0
  102. package/src/engine/physics/cloth/ecs/cloth_gather_colliders.d.ts.map +1 -0
  103. package/src/engine/physics/cloth/ecs/cloth_gather_colliders.js +328 -0
  104. package/src/engine/physics/cloth/ecs/cloth_reconstruct_pose.d.ts +13 -0
  105. package/src/engine/physics/cloth/ecs/cloth_reconstruct_pose.d.ts.map +1 -0
  106. package/src/engine/physics/cloth/ecs/cloth_reconstruct_pose.js +288 -0
  107. package/src/engine/physics/cloth/ecs/cloth_seed_rig.d.ts +58 -0
  108. package/src/engine/physics/cloth/ecs/cloth_seed_rig.d.ts.map +1 -0
  109. package/src/engine/physics/cloth/ecs/cloth_seed_rig.js +199 -0
  110. package/src/engine/physics/cloth/ecs/cloth_seed_subtree.d.ts +8 -63
  111. package/src/engine/physics/cloth/ecs/cloth_seed_subtree.d.ts.map +1 -1
  112. package/src/engine/physics/cloth/ecs/cloth_seed_subtree.js +317 -645
  113. package/src/engine/physics/cloth/ecs/cloth_write_back.d.ts +61 -0
  114. package/src/engine/physics/cloth/ecs/cloth_write_back.d.ts.map +1 -1
  115. package/src/engine/physics/cloth/ecs/cloth_write_back.js +212 -449
  116. package/src/engine/physics/cloth/ecs/cloth_write_back_rig.d.ts +49 -0
  117. package/src/engine/physics/cloth/ecs/cloth_write_back_rig.d.ts.map +1 -0
  118. package/src/engine/physics/cloth/ecs/cloth_write_back_rig.js +115 -0
  119. package/src/engine/physics/cloth/playground/README.md +155 -1
  120. package/src/engine/physics/cloth/playground/collide.html +178 -0
  121. package/src/engine/physics/cloth/playground/collide_build.d.ts +95 -0
  122. package/src/engine/physics/cloth/playground/collide_build.d.ts.map +1 -0
  123. package/src/engine/physics/cloth/playground/collide_build.js +315 -0
  124. package/src/engine/physics/cloth/playground/collide_main.d.ts +2 -0
  125. package/src/engine/physics/cloth/playground/collide_main.d.ts.map +1 -0
  126. package/src/engine/physics/cloth/playground/collide_main.js +720 -0
  127. package/src/engine/physics/cloth/playground/garment.html +182 -0
  128. package/src/engine/physics/cloth/playground/garment_build.d.ts +78 -0
  129. package/src/engine/physics/cloth/playground/garment_build.d.ts.map +1 -0
  130. package/src/engine/physics/cloth/playground/garment_build.js +359 -0
  131. package/src/engine/physics/cloth/playground/garment_main.d.ts +2 -0
  132. package/src/engine/physics/cloth/playground/garment_main.d.ts.map +1 -0
  133. package/src/engine/physics/cloth/playground/garment_main.js +633 -0
  134. package/src/engine/physics/cloth/solver/ClothState.d.ts +208 -5
  135. package/src/engine/physics/cloth/solver/ClothState.d.ts.map +1 -1
  136. package/src/engine/physics/cloth/solver/ClothState.js +302 -8
  137. package/src/engine/physics/cloth/solver/cloth_contact_find.d.ts +87 -0
  138. package/src/engine/physics/cloth/solver/cloth_contact_find.d.ts.map +1 -0
  139. package/src/engine/physics/cloth/solver/cloth_contact_find.js +343 -0
  140. package/src/engine/physics/cloth/solver/cloth_self_find.d.ts +112 -0
  141. package/src/engine/physics/cloth/solver/cloth_self_find.d.ts.map +1 -0
  142. package/src/engine/physics/cloth/solver/cloth_self_find.js +448 -0
  143. package/src/engine/physics/cloth/solver/cloth_solve_vertex.d.ts +4 -1
  144. package/src/engine/physics/cloth/solver/cloth_solve_vertex.d.ts.map +1 -1
  145. package/src/engine/physics/cloth/solver/cloth_solve_vertex.js +16 -1
  146. package/src/engine/physics/cloth/solver/cloth_solver_constants.d.ts +112 -5
  147. package/src/engine/physics/cloth/solver/cloth_solver_constants.d.ts.map +1 -1
  148. package/src/engine/physics/cloth/solver/cloth_solver_constants.js +117 -6
  149. package/src/engine/physics/cloth/solver/cloth_step.d.ts +40 -9
  150. package/src/engine/physics/cloth/solver/cloth_step.d.ts.map +1 -1
  151. package/src/engine/physics/cloth/solver/cloth_step.js +122 -10
  152. package/src/engine/physics/cloth/solver/constraint/cloth_backstop_row.d.ts +95 -0
  153. package/src/engine/physics/cloth/solver/constraint/cloth_backstop_row.d.ts.map +1 -0
  154. package/src/engine/physics/cloth/solver/constraint/cloth_backstop_row.js +285 -0
  155. package/src/engine/physics/cloth/solver/constraint/cloth_contact_row.d.ts +129 -0
  156. package/src/engine/physics/cloth/solver/constraint/cloth_contact_row.d.ts.map +1 -0
  157. package/src/engine/physics/cloth/solver/constraint/cloth_contact_row.js +501 -0
  158. package/src/engine/physics/cloth/solver/constraint/cloth_self_row.d.ts +75 -0
  159. package/src/engine/physics/cloth/solver/constraint/cloth_self_row.d.ts.map +1 -0
  160. package/src/engine/physics/cloth/solver/constraint/cloth_self_row.js +202 -0
  161. package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts +4 -4
  162. package/src/shade/playground/vgeo_viewer/README.md +18 -0
  163. package/src/shade/playground/vgeo_viewer/main.js +87 -50
  164. package/src/shade/renderer/buffer/table/GPUDatabase.d.ts.map +1 -1
  165. package/src/shade/renderer/buffer/table/GPUDatabase.js +191 -62
  166. package/src/shade/renderer/buffer/table/GPUTypedTable.d.ts +94 -2
  167. package/src/shade/renderer/buffer/table/GPUTypedTable.d.ts.map +1 -1
  168. package/src/shade/renderer/buffer/table/GPUTypedTable.js +414 -2
  169. package/src/shade/renderer/buffer/table/GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.d.ts +14 -0
  170. package/src/shade/renderer/buffer/table/GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.d.ts.map +1 -0
  171. package/src/shade/renderer/buffer/table/GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.js +13 -0
  172. package/src/shade/renderer/buffer/table/gpu_table_partial_upload_shader.d.ts +17 -0
  173. package/src/shade/renderer/buffer/table/gpu_table_partial_upload_shader.d.ts.map +1 -0
  174. package/src/shade/renderer/buffer/table/gpu_table_partial_upload_shader.js +116 -0
  175. package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.d.ts +9 -4
  176. package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.d.ts.map +1 -1
  177. package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js +843 -734
  178. package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.d.ts +12 -0
  179. package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.d.ts.map +1 -1
  180. package/src/shade/renderer/geometry/bvh/GPUGeometryMeshletsBVH.js +13 -0
  181. package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts +17 -0
  182. package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts.map +1 -1
  183. package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.js +185 -30
  184. package/src/shade/renderer/geometry/virtual/MICRON_COMPARISON_2026_08_20.md +17 -0
  185. package/src/shade/renderer/geometry/virtual/VGEO_FORMAT.md +141 -24
  186. package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md +204 -64
  187. package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_PLAN.md +110 -10
  188. package/src/shade/renderer/geometry/virtual/VK_LOD_CLUSTERS_COMPARISON_2026_08_20.md +19 -0
  189. package/src/shade/renderer/geometry/virtual/format/read/VGeoByteSource.d.ts +19 -6
  190. package/src/shade/renderer/geometry/virtual/format/read/VGeoByteSource.d.ts.map +1 -1
  191. package/src/shade/renderer/geometry/virtual/format/read/VGeoByteSource.js +26 -7
  192. package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.d.ts +173 -14
  193. package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.d.ts.map +1 -1
  194. package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.js +458 -51
  195. package/src/shade/renderer/geometry/virtual/format/read/VGeoReadOptions.d.ts +49 -13
  196. package/src/shade/renderer/geometry/virtual/format/read/VGeoReadOptions.d.ts.map +1 -1
  197. package/src/shade/renderer/geometry/virtual/format/read/VGeoReadOptions.js +52 -14
  198. package/src/shade/renderer/geometry/virtual/format/read/tool/VGEO_MAX_AUDIT_BYTES.d.ts +20 -0
  199. package/src/shade/renderer/geometry/virtual/format/read/tool/VGEO_MAX_AUDIT_BYTES.d.ts.map +1 -0
  200. package/src/shade/renderer/geometry/virtual/format/read/tool/VGEO_MAX_AUDIT_BYTES.js +19 -0
  201. package/src/shade/renderer/geometry/virtual/format/read/tool/vgeo_audit_container.d.ts +27 -0
  202. package/src/shade/renderer/geometry/virtual/format/read/tool/vgeo_audit_container.d.ts.map +1 -0
  203. package/src/shade/renderer/geometry/virtual/format/read/tool/vgeo_audit_container.js +48 -0
  204. package/src/shade/renderer/geometry/virtual/format/read/tool/vgeo_install_all_pages.d.ts +29 -0
  205. package/src/shade/renderer/geometry/virtual/format/read/tool/vgeo_install_all_pages.d.ts.map +1 -0
  206. package/src/shade/renderer/geometry/virtual/format/read/tool/vgeo_install_all_pages.js +60 -0
  207. package/src/shade/renderer/geometry/virtual/format/read/vgeo_fetch_byte_source.d.ts +8 -1
  208. package/src/shade/renderer/geometry/virtual/format/read/vgeo_fetch_byte_source.d.ts.map +1 -1
  209. package/src/shade/renderer/geometry/virtual/format/read/vgeo_fetch_byte_source.js +32 -2
  210. package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyManager.d.ts +258 -0
  211. package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyManager.d.ts.map +1 -0
  212. package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyManager.js +723 -0
  213. package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyOptions.d.ts +49 -0
  214. package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyOptions.d.ts.map +1 -0
  215. package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyOptions.js +50 -0
  216. package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts +1 -1
  217. package/src/shade/renderer/postprocess/nss/NSS.d.ts +1 -1
  218. package/src/shade/renderer/texture/bindless/GPUBindlessTextureManager.d.ts +3 -0
  219. package/src/shade/renderer/texture/bindless/GPUBindlessTextureManager.d.ts.map +1 -1
  220. package/src/shade/renderer/texture/bindless/GPUBindlessTextureManager.js +121 -21
  221. package/src/shade/renderer/texture/virtual/README.md +6 -4
  222. package/src/shade/renderer/texture/virtual/VirtualTextureManager.d.ts.map +1 -1
  223. package/src/shade/renderer/texture/virtual/VirtualTextureManager.js +7 -0
  224. package/src/shade/renderer/texture/virtual/source/VTSourceTiled.d.ts +3 -3
  225. package/src/shade/renderer/texture/virtual/source/VTSourceTiled.js +3 -3
  226. package/src/engine/ecs/system/SystemExecutionPhase.d.ts +0 -9
  227. package/src/engine/ecs/system/SystemExecutionPhase.d.ts.map +0 -1
  228. package/src/engine/graphics/texture/virtual/NOTES.md +0 -128
  229. package/src/engine/graphics/texture/virtual/VT_DEFAULT_PAGE_RESOLUTION.d.ts +0 -6
  230. package/src/engine/graphics/texture/virtual/VT_DEFAULT_PAGE_RESOLUTION.d.ts.map +0 -1
  231. package/src/engine/graphics/texture/virtual/VT_DEFAULT_PAGE_RESOLUTION.js +0 -5
  232. package/src/engine/graphics/texture/virtual/VirtualTextureTileLoader.d.ts +0 -49
  233. package/src/engine/graphics/texture/virtual/VirtualTextureTileLoader.d.ts.map +0 -1
  234. package/src/engine/graphics/texture/virtual/VirtualTextureTileLoader.js +0 -264
  235. package/src/engine/graphics/texture/virtual/VirtualTextureUsage.d.ts +0 -44
  236. package/src/engine/graphics/texture/virtual/VirtualTextureUsage.d.ts.map +0 -1
  237. package/src/engine/graphics/texture/virtual/VirtualTextureUsage.js +0 -228
  238. package/src/engine/graphics/texture/virtual/VirtualTextureUsageShader.d.ts +0 -3
  239. package/src/engine/graphics/texture/virtual/VirtualTextureUsageShader.d.ts.map +0 -1
  240. package/src/engine/graphics/texture/virtual/VirtualTextureUsageShader.js +0 -73
  241. package/src/engine/graphics/texture/virtual/debug/ResidencyDebugView.d.ts +0 -14
  242. package/src/engine/graphics/texture/virtual/debug/ResidencyDebugView.d.ts.map +0 -1
  243. package/src/engine/graphics/texture/virtual/debug/ResidencyDebugView.js +0 -85
  244. package/src/engine/graphics/texture/virtual/debug/UsageDebugView.d.ts +0 -12
  245. package/src/engine/graphics/texture/virtual/debug/UsageDebugView.d.ts.map +0 -1
  246. package/src/engine/graphics/texture/virtual/debug/UsageDebugView.js +0 -63
  247. package/src/engine/graphics/texture/virtual/debug/UsagePyramidDebugView.d.ts +0 -12
  248. package/src/engine/graphics/texture/virtual/debug/UsagePyramidDebugView.d.ts.map +0 -1
  249. package/src/engine/graphics/texture/virtual/debug/UsagePyramidDebugView.js +0 -243
  250. package/src/engine/graphics/texture/virtual/tile/VirtualTextureTile.d.ts +0 -30
  251. package/src/engine/graphics/texture/virtual/tile/VirtualTextureTile.d.ts.map +0 -1
  252. package/src/engine/graphics/texture/virtual/tile/VirtualTextureTile.js +0 -39
  253. package/src/engine/graphics/texture/virtual/tile/compose_finger_print.d.ts +0 -9
  254. package/src/engine/graphics/texture/virtual/tile/compose_finger_print.d.ts.map +0 -1
  255. package/src/engine/graphics/texture/virtual/tile/compose_finger_print.js +0 -24
  256. package/src/engine/graphics/texture/virtual/tile/compose_tile_address.d.ts +0 -9
  257. package/src/engine/graphics/texture/virtual/tile/compose_tile_address.d.ts.map +0 -1
  258. package/src/engine/graphics/texture/virtual/tile/compose_tile_address.js +0 -26
  259. package/src/engine/graphics/texture/virtual/tile/decompose_finger_print.d.ts +0 -11
  260. package/src/engine/graphics/texture/virtual/tile/decompose_finger_print.d.ts.map +0 -1
  261. package/src/engine/graphics/texture/virtual/tile/decompose_finger_print.js +0 -12
  262. package/src/engine/graphics/texture/virtual/tile/finger_print_to_tile_address.d.ts +0 -7
  263. package/src/engine/graphics/texture/virtual/tile/finger_print_to_tile_address.d.ts.map +0 -1
  264. package/src/engine/graphics/texture/virtual/tile/finger_print_to_tile_address.js +0 -16
  265. package/src/engine/graphics/texture/virtual/tile/tile_address_to_finger_print.d.ts +0 -7
  266. package/src/engine/graphics/texture/virtual/tile/tile_address_to_finger_print.d.ts.map +0 -1
  267. package/src/engine/graphics/texture/virtual/tile/tile_address_to_finger_print.js +0 -35
@@ -12,6 +12,12 @@
12
12
  * Reads are asynchronous because the interesting sources are. A source over bytes already in memory
13
13
  * resolves immediately and costs a microtask, which is the right price for not having two readers.
14
14
  *
15
+ * **Each read carries its own abort signal.** A page the camera stopped wanting is one request out
16
+ * of hundreds in flight, and cancelling it has to be possible without cancelling the rest — so the
17
+ * signal is a parameter of {@link read} rather than something baked into the source when it was
18
+ * built. A source over memory has nothing to abort and says so by checking the signal and refusing
19
+ * to start; one over the network passes it to `fetch` and the connection really does close.
20
+ *
15
21
  * Ranges are checked against the length the source declares, so a file that names bytes it does not
16
22
  * have fails here, naming the range, rather than somewhere downstream holding a short array.
17
23
  *
@@ -42,6 +48,11 @@ export class VGeoByteSource {
42
48
  * gigabyte asset costs whatever the traversal asks for and not a gigabyte of heap. That is the
43
49
  * one case where a debug tool and a runtime want exactly the same thing.
44
50
  *
51
+ * `Blob.arrayBuffer` takes no signal, so a cancelled read here is abandoned rather than
52
+ * stopped — the local read completes and its bytes are dropped. That is the honest behaviour for
53
+ * a source with no cancellation of its own, and it is why {@link read} checks the signal on both
54
+ * sides of the call rather than only before it.
55
+ *
45
56
  * @param {Blob} blob
46
57
  * @param {string} [name]
47
58
  * @returns {VGeoByteSource}
@@ -49,11 +60,12 @@ export class VGeoByteSource {
49
60
  static from_blob(blob: Blob, name?: string): VGeoByteSource;
50
61
  /**
51
62
  * @param {number} byte_length
52
- * @param {function(number, number): Promise<Uint8Array>} read given a byte offset and a byte
53
- * count, resolves with exactly that many bytes
63
+ * @param {function(number, number, AbortSignal=): Promise<Uint8Array>} read given a byte offset,
64
+ * a byte count and optionally a signal that says the caller stopped wanting the range,
65
+ * resolves with exactly that many bytes
54
66
  * @param {string} [name]
55
67
  */
56
- constructor(byte_length: number, read: (arg0: number, arg1: number) => Promise<Uint8Array>, name?: string);
68
+ constructor(byte_length: number, read: (arg0: number, arg1: number, arg2: AbortSignal | undefined) => Promise<Uint8Array>, name?: string);
57
69
  /**
58
70
  * How many bytes this source holds — the whole file, however little of it has been read.
59
71
  * @type {number}
@@ -84,11 +96,12 @@ export class VGeoByteSource {
84
96
  /**
85
97
  * @param {number} byte_offset
86
98
  * @param {number} byte_length
99
+ * @param {AbortSignal} [signal] aborting it abandons this read and no other
87
100
  * @returns {Promise<Uint8Array>} exactly that range
88
- * @throws {Error} if the range is not inside the source, or the reader answered with a different
89
- * number of bytes than it was asked for
101
+ * @throws {Error} if the range is not inside the source, the caller aborted it, or the reader
102
+ * answered with a different number of bytes than it was asked for
90
103
  */
91
- read(byte_offset: number, byte_length: number): Promise<Uint8Array>;
104
+ read(byte_offset: number, byte_length: number, signal?: AbortSignal): Promise<Uint8Array>;
92
105
  #private;
93
106
  }
94
107
  //# sourceMappingURL=VGeoByteSource.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"VGeoByteSource.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoByteSource.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAsGI;;;;;;;;;;OAUG;IACH,iBAJW,UAAU,GAAC,WAAW,SACtB,MAAM,GACJ,cAAc,CAU1B;IAED;;;;;;;;;;OAUG;IACH,uBAJW,IAAI,SACJ,MAAM,GACJ,cAAc,CAU1B;IA/GD;;;;;OAKG;IACH,yBALW,MAAM,eACG,MAAM,QAAE,MAAM,KAAG,QAAQ,UAAU,CAAC,SAE7C,MAAM,EAUhB;IA5CD;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,YAFU,MAAM,CAED;IA6Bf;;OAEG;IACH,mBAEC;IAED;;;;;OAKG;IACH,uBAGC;IAED;;;;;;OAMG;IACH,kBANW,MAAM,eACN,MAAM,GACJ,QAAQ,UAAU,CAAC,CAgC/B;;CA2CJ"}
1
+ {"version":3,"file":"VGeoByteSource.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoByteSource.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA8GI;;;;;;;;;;OAUG;IACH,iBAJW,UAAU,GAAC,WAAW,SACtB,MAAM,GACJ,cAAc,CAU1B;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAJW,IAAI,SACJ,MAAM,GACJ,cAAc,CAU1B;IA5HD;;;;;;OAMG;IACH,yBANW,MAAM,eACG,MAAM,QAAE,MAAM,QAAE,WAAW,iBAAI,QAAQ,UAAU,CAAC,SAG3D,MAAM,EAUhB;IA7CD;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,YAFU,MAAM,CAED;IA8Bf;;OAEG;IACH,mBAEC;IAED;;;;;OAKG;IACH,uBAGC;IAED;;;;;;;OAOG;IACH,kBAPW,MAAM,eACN,MAAM,WACN,WAAW,GACT,QAAQ,UAAU,CAAC,CAsC/B;;CAgDJ"}
@@ -14,6 +14,12 @@ import { assert } from "../../../../../../core/assert.js";
14
14
  * Reads are asynchronous because the interesting sources are. A source over bytes already in memory
15
15
  * resolves immediately and costs a microtask, which is the right price for not having two readers.
16
16
  *
17
+ * **Each read carries its own abort signal.** A page the camera stopped wanting is one request out
18
+ * of hundreds in flight, and cancelling it has to be possible without cancelling the rest — so the
19
+ * signal is a parameter of {@link read} rather than something baked into the source when it was
20
+ * built. A source over memory has nothing to abort and says so by checking the signal and refusing
21
+ * to start; one over the network passes it to `fetch` and the connection really does close.
22
+ *
17
23
  * Ranges are checked against the length the source declares, so a file that names bytes it does not
18
24
  * have fails here, naming the range, rather than somewhere downstream holding a short array.
19
25
  *
@@ -45,7 +51,7 @@ export class VGeoByteSource {
45
51
  bytes_read = 0;
46
52
 
47
53
  /**
48
- * @type {function(number, number): Promise<Uint8Array>}
54
+ * @type {function(number, number, AbortSignal=): Promise<Uint8Array>}
49
55
  */
50
56
  #read;
51
57
 
@@ -57,8 +63,9 @@ export class VGeoByteSource {
57
63
 
58
64
  /**
59
65
  * @param {number} byte_length
60
- * @param {function(number, number): Promise<Uint8Array>} read given a byte offset and a byte
61
- * count, resolves with exactly that many bytes
66
+ * @param {function(number, number, AbortSignal=): Promise<Uint8Array>} read given a byte offset,
67
+ * a byte count and optionally a signal that says the caller stopped wanting the range,
68
+ * resolves with exactly that many bytes
62
69
  * @param {string} [name]
63
70
  */
64
71
  constructor(byte_length, read, name = 'a byte source') {
@@ -92,11 +99,12 @@ export class VGeoByteSource {
92
99
  /**
93
100
  * @param {number} byte_offset
94
101
  * @param {number} byte_length
102
+ * @param {AbortSignal} [signal] aborting it abandons this read and no other
95
103
  * @returns {Promise<Uint8Array>} exactly that range
96
- * @throws {Error} if the range is not inside the source, or the reader answered with a different
97
- * number of bytes than it was asked for
104
+ * @throws {Error} if the range is not inside the source, the caller aborted it, or the reader
105
+ * answered with a different number of bytes than it was asked for
98
106
  */
99
- async read(byte_offset, byte_length) {
107
+ async read(byte_offset, byte_length, signal = undefined) {
100
108
  if (
101
109
  !Number.isInteger(byte_offset) || byte_offset < 0
102
110
  || !Number.isInteger(byte_length) || byte_length < 0
@@ -108,7 +116,13 @@ export class VGeoByteSource {
108
116
  );
109
117
  }
110
118
 
111
- const bytes = await this.#read(byte_offset, byte_length);
119
+ // Before the read rather than only after: a source over memory resolves in a microtask, and
120
+ // a caller that cancelled between queueing and here would otherwise still pay for it.
121
+ signal?.throwIfAborted();
122
+
123
+ const bytes = await this.#read(byte_offset, byte_length, signal);
124
+
125
+ signal?.throwIfAborted();
112
126
 
113
127
  if (bytes.byteLength !== byte_length) {
114
128
  // Checked rather than trusted: everything downstream indexes by the format's offsets,
@@ -154,6 +168,11 @@ export class VGeoByteSource {
154
168
  * gigabyte asset costs whatever the traversal asks for and not a gigabyte of heap. That is the
155
169
  * one case where a debug tool and a runtime want exactly the same thing.
156
170
  *
171
+ * `Blob.arrayBuffer` takes no signal, so a cancelled read here is abandoned rather than
172
+ * stopped — the local read completes and its bytes are dropped. That is the honest behaviour for
173
+ * a source with no cancellation of its own, and it is why {@link read} checks the signal on both
174
+ * sides of the call rather than only before it.
175
+ *
157
176
  * @param {Blob} blob
158
177
  * @param {string} [name]
159
178
  * @returns {VGeoByteSource}
@@ -23,11 +23,19 @@
23
23
  * in for one that did not, and draws both over the same surface. That is what activation is for, and
24
24
  * it is why installing a page does bookkeeping rather than only filling a map.
25
25
  *
26
+ * **Mechanics, not policy — and the line is deliberate.** Which page to fetch next, which to drop,
27
+ * how many bytes one asset may hold, how many requests may be in flight across a thousand of them:
28
+ * none of that is decided here, because none of it can be decided by one reader looking at one file.
29
+ * `VGeoResidencyManager` is where it is decided and readers register with one; §10's eviction bullet
30
+ * is the reason for the split rather than an apology for it. What *is* here is everything that is
31
+ * about the bytes — the fetch, the retries, the quarantine a page that will not arrive ends up in,
32
+ * and the accounting a budget owner spends against.
33
+ *
26
34
  * **Validation is not on this path.** The mandatory reject rules of §4 and §10 are applied
27
35
  * unconditionally by {@link vgeo_read_header} and {@link vgeo_read_page} — a file whose magic,
28
36
  * versions, encoding or codec this build does not understand is refused rather than misread. The
29
- * whole-file audit is {@link validate}, it reads every byte of the file, and it is off by default;
30
- * see {@link VGeoReadOptions.validate}.
37
+ * whole-file audit is `vgeo_audit_container` in `tool/`, it reads every byte of the file, and
38
+ * nothing on the runtime path can reach it.
31
39
  *
32
40
  * @author Alex Goldring
33
41
  * @copyright Company Named Limited (c) 2026
@@ -72,6 +80,16 @@ export class VGeoContainerReader {
72
80
  get resident_page_count(): number;
73
81
  /**
74
82
  * Decoded bytes currently held. The number a residency budget is spent against.
83
+ *
84
+ * It is exactly the decoded page images — the same number the directory's `decoded_size` column
85
+ * and every child-table entry promise *before* a page is fetched, which is what lets a budget
86
+ * owner admit a page rather than discover its cost after paying for it. It is deliberately not
87
+ * what the pages cost in the heap: the reader's own per-page bookkeeping — the `VGeoPage`, its
88
+ * cluster and child tables, the two activation arrays, the map entries — measured 6.4–11.9 KB
89
+ * per page on top of the image. That is 1.2% of a 544 KB page at the sizes design §5 targets and
90
+ * 294% of a 2 KB one, so a budget sized against very small pages has to allow for it and one
91
+ * sized against the design's page size is inside its own rounding.
92
+ *
75
93
  * @returns {number}
76
94
  */
77
95
  get resident_bytes(): number;
@@ -79,17 +97,60 @@ export class VGeoContainerReader {
79
97
  * @returns {number}
80
98
  */
81
99
  get pending_page_count(): number;
100
+ /**
101
+ * How many not-yet-resident pages the reverse-reference index is holding counters for.
102
+ *
103
+ * Diagnostic, and the number a leak in that index would show up in: an entry exists only while
104
+ * some resident, selectable cluster refers into a page that is not here, so this tracks the
105
+ * residency frontier and must not track how many pages a session has visited. See
106
+ * {@link #pending_refs} for what that was measured at.
107
+ *
108
+ * @returns {number}
109
+ */
110
+ get pending_reference_page_count(): number;
111
+ /**
112
+ * How many bytes of speculative head prefix are still held — zero once {@link release_head} has
113
+ * run, which is the normal state after the first read that falls outside the prefix.
114
+ *
115
+ * @returns {number}
116
+ */
117
+ get head_bytes(): number;
118
+ /**
119
+ * How many pages have failed their retries and will not be asked for again.
120
+ * @returns {number}
121
+ */
122
+ get quarantined_page_count(): number;
82
123
  /**
83
124
  * The root page, which is pinned for the life of the reader — §10 makes it the one page that is
84
125
  * never evictable, because every traversal starts by walking its parentless groups.
126
+ *
127
+ * What the pin costs is worth writing down, because "pinned for life, times a thousand assets"
128
+ * is the shape of a problem and this one is not: build invariant §11.7 puts exactly one root
129
+ * cluster in the file, and the assembler gives the root page the complete topmost level — so the
130
+ * root page *is* that one cluster. Measured on two torus builds, of 7.7K and 42K source
131
+ * triangles and 8 and 12 levels: 1,732 B and 1,472 B decoded. A thousand of them is under 2 MB,
132
+ * and no builder-side cap on root size is needed to keep it that way.
133
+ *
85
134
  * @returns {VGeoPage}
86
135
  */
87
136
  get root(): VGeoPage;
88
137
  /**
89
- * Every resident page, in page-index order.
138
+ * Every resident page, sorted by page index.
139
+ *
140
+ * A snapshot, and it costs one: an array of every resident page plus a sort of it — 0.29 ms per
141
+ * access measured at 20,000 resident pages. So this is for a tool, a panel or a test, and **not
142
+ * for anything that runs per frame**. {@link resident_pages} is the same set in arrival order
143
+ * and allocates nothing, which is what a per-frame sweep should read.
144
+ *
90
145
  * @returns {VGeoPage[]}
91
146
  */
92
147
  get pages(): VGeoPage[];
148
+ /**
149
+ * Every resident page, in arrival order, allocating nothing.
150
+ *
151
+ * @returns {IterableIterator<VGeoPage>}
152
+ */
153
+ resident_pages(): IterableIterator<VGeoPage>;
93
154
  /**
94
155
  * The page, if it is here.
95
156
  *
@@ -105,6 +166,19 @@ export class VGeoContainerReader {
105
166
  * @returns {boolean}
106
167
  */
107
168
  is_resident(page_index: number): boolean;
169
+ /**
170
+ * How many of a page's child pages are resident.
171
+ *
172
+ * §10's eviction rule is written in terms of this: within a residency tier, a page is evictable
173
+ * only while it has no resident child pages in that tier, checked against its own child table.
174
+ * `SAME_PAGE` references never pin and are in no child table by construction (§11.2), so the
175
+ * table is the whole answer. The *rule* is a policy and lives with the budget owner; this
176
+ * lookup is about one page's own bytes and lives here.
177
+ *
178
+ * @param {number} page_index
179
+ * @returns {number} zero for a page that is not resident, and for one no child of which is
180
+ */
181
+ resident_child_count(page_index: number): number;
108
182
  /**
109
183
  * Whether a group may be selected from — §10's activation invariant, and **not** the same
110
184
  * question as {@link is_resident}.
@@ -129,18 +203,80 @@ export class VGeoContainerReader {
129
203
  * @returns {boolean}
130
204
  */
131
205
  is_selectable(page_index: number, group: number): boolean;
206
+ /**
207
+ * Whether a page has failed its retries and been quarantined.
208
+ *
209
+ * @param {number} page_index
210
+ * @returns {boolean}
211
+ */
212
+ is_quarantined(page_index: number): boolean;
213
+ /**
214
+ * Why a page was quarantined, or `undefined` if it was not.
215
+ *
216
+ * §10 asks for the quarantine *and* for telemetry, because a page that stopped arriving is the
217
+ * difference between a coarse asset and a broken deployment, and on screen the two are the same
218
+ * picture.
219
+ *
220
+ * @param {number} page_index
221
+ * @returns {string|undefined}
222
+ */
223
+ quarantine_reason(page_index: number): string | undefined;
224
+ /**
225
+ * Every quarantined page and its reason.
226
+ * @returns {IterableIterator<[number, string]>}
227
+ */
228
+ quarantine(): IterableIterator<[number, string]>;
229
+ /**
230
+ * Let a quarantined page be asked for again.
231
+ *
232
+ * **When** is a policy and is not decided here. A frame checksum that failed at a
233
+ * content-addressed URL will fail again and lifting its quarantine buys nothing; a run of 503s
234
+ * from one edge node is a different thing, and a budget owner that has watched other pages of
235
+ * other assets arrive since has evidence this reader does not have. So the reader quarantines
236
+ * for its own lifetime and offers this, and `VGeoResidencyManager` is where the decision to use
237
+ * it lives.
238
+ *
239
+ * @param {number} [page_index] omit to lift every quarantine
240
+ * @returns {number} how many pages were released
241
+ */
242
+ clear_quarantine(page_index?: number): number;
132
243
  /**
133
244
  * Fetch and install one page, from the exact range something already resident named.
134
245
  *
135
246
  * Concurrent calls for the same page share one fetch; a page already resident is returned
136
- * without one.
247
+ * without one; a page in quarantine is refused without one.
137
248
  *
138
249
  * @param {number} page_index
139
250
  * @param {number} frame_offset absolute
140
251
  * @param {number} fetch_size
141
252
  * @returns {Promise<VGeoPage>}
253
+ * @throws {Error} asynchronously — when the page is already quarantined, when it fails every
254
+ * attempt and is quarantined by doing so, or when {@link cancel} abandoned it
142
255
  */
143
256
  install(page_index: number, frame_offset: number, fetch_size: number): Promise<VGeoPage>;
257
+ /**
258
+ * Abandon a fetch that is still in flight.
259
+ *
260
+ * **What a want that goes stale mid-flight should do, decided:** abort it while it can still be
261
+ * aborted, and install it once it cannot. The camera moved, nothing wants the page now, and the
262
+ * request is worth closing — but once the bytes have landed, refusing to install them is the one
263
+ * choice that pays for the fetch *and* throws the page away. So an abort that arrives too late
264
+ * does nothing, the page installs, and it enters residency untouched — which under LRU on
265
+ * last-touched (design §6) makes it the first candidate for eviction if the camera really is
266
+ * done with it, and free if it is not.
267
+ *
268
+ * The pending promise rejects, so a caller awaiting it sees the abort rather than a page. A
269
+ * cancelled page is **not** quarantined: nothing was wrong with it.
270
+ *
271
+ * @param {number} page_index
272
+ * @returns {boolean} whether there was a fetch to abandon
273
+ */
274
+ cancel(page_index: number): boolean;
275
+ /**
276
+ * Abandon every fetch in flight.
277
+ * @returns {number} how many were abandoned
278
+ */
279
+ cancel_all(): number;
144
280
  /**
145
281
  * Install the page a want names.
146
282
  *
@@ -155,18 +291,31 @@ export class VGeoContainerReader {
155
291
  * clamped cluster projected — so a caller that stops early has fetched the pages that would fix
156
292
  * the most visible coarseness, not an arbitrary prefix of the list.
157
293
  *
294
+ * **A page that will not arrive does not take the batch down.** One flaky edge node, or one
295
+ * corrupt frame out of a thousand assets' worth of pages, must cost exactly that page: it is
296
+ * retried, then quarantined, then skipped, and what comes back is what did install. *Which*
297
+ * pages failed is durable rather than a per-call return — see {@link quarantine} — because a
298
+ * failure that lived only in one call's result is one the next call would repeat.
299
+ *
300
+ * The concurrency bound here is this reader's own. A runtime holding many assets wants a bound
301
+ * across all of them and should install through `VGeoResidencyManager`, which admits every
302
+ * registered reader's fetches through one scheduler: eight readers calling this at the default
303
+ * were measured issuing 48 concurrent range requests.
304
+ *
158
305
  * @param {VGeoPageWant[]} wants
159
306
  * @param {number} [limit] most pages to install; the rest are left for the next traversal to
160
307
  * want again, which it will, from a cut taken with everything this call did install
308
+ * @param {AbortSignal} [signal] stops the batch taking new wants, and abandons what is in flight
161
309
  * @returns {Promise<VGeoPage[]>} the pages installed, in completion order
162
310
  */
163
- install_wants(wants: VGeoPageWant[], limit?: number): Promise<VGeoPage[]>;
311
+ install_wants(wants: VGeoPageWant[], limit?: number, signal?: AbortSignal): Promise<VGeoPage[]>;
164
312
  /**
165
313
  * Drop a page.
166
314
  *
167
315
  * The eviction *rule* — a page is evictable only while it has no resident child pages, and the
168
316
  * root is pinned (§10) — is a residency policy and belongs to whatever is managing the budget,
169
- * not here. What this does is the dropping.
317
+ * not here. What this does is the dropping; {@link resident_child_count} is the lookup the rule
318
+ * is written in terms of.
170
319
  *
171
320
  * @param {number} page_index
172
321
  * @returns {boolean} whether a page was there to drop
@@ -191,10 +340,9 @@ export class VGeoContainerReader {
191
340
  /**
192
341
  * Install every page the directory lists.
193
342
  *
194
- * The opposite of what this reader is for, and exactly what a tool wants when the question is
195
- * about the file rather than about a view of it — the pages no cut reaches are the ones a bug
196
- * hides in.
197
- *
343
+ * @deprecated it reads the whole file, and a renderer holding a reader must not be able to reach
344
+ * that from the reader. Call `vgeo_install_all_pages` in `tool/` instead, which is a tool
345
+ * and says so. Kept as a shim because the playground and the specs are what it is for.
198
346
  * @param {function(number, number): void} [on_progress] called with pages installed and total
199
347
  * @returns {Promise<void>}
200
348
  */
@@ -203,13 +351,24 @@ export class VGeoContainerReader {
203
351
  * The whole-file audit — every build invariant of §11, every checksum, and the directory against
204
352
  * what a frame scan reconstructs.
205
353
  *
206
- * **This reads the entire file**, which is the one thing the rest of this class exists to avoid,
207
- * and it is why it is a separate call and off by default. It answers a question about whoever
208
- * produced the file; nothing about reading one depends on it having been asked.
209
- *
354
+ * @deprecated it reads the entire file into one `ArrayBuffer`, which is the one thing the rest
355
+ * of this class exists to avoid and which a multi-GB asset does not survive. Call
356
+ * `vgeo_audit_container` in `tool/` instead, which refuses a file too large to audit this
357
+ * way rather than attempting it. Kept as a shim for the playground and the specs.
210
358
  * @returns {Promise<VGeoDefect[]>} empty is the only good answer
211
359
  */
212
360
  validate(): Promise<VGeoDefect[]>;
361
+ /**
362
+ * Drop the speculative head prefix.
363
+ *
364
+ * Nothing depends on it afterwards: the header and level table are parsed into {@link header}
365
+ * before anything else runs, the root page owns its own decoded bytes, and every later read
366
+ * names a range the source can serve. A page whose frame lay inside the prefix costs one request
367
+ * if it is wanted after this — the same request it would have cost had the prefix been smaller.
368
+ *
369
+ * @returns {number} bytes released
370
+ */
371
+ release_head(): number;
213
372
  #private;
214
373
  }
215
374
  import { VGeoReadOptions } from "./VGeoReadOptions.js";
@@ -1 +1 @@
1
- {"version":3,"file":"VGeoContainerReader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IAwJI;;;;;;;;OAQG;IACH,8CALW,eAAe,GACb,QAAQ,mBAAmB,CAAC,CAUxC;IA/ED;;;OAGG;IACH,8CAFW,eAAe,EAOzB;IAhGD;;OAEG;IACH,4BAAmB;IAEnB;;;;OAIG;IACH,WAFU,gBAAc,SAAS,CAEX;IAwFtB;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;;OAIG;IACH,qBAEC;IAED;;;OAGG;IACH,wBAEC;IAyFD;;;;;;;;OAQG;IACH,iBAHW,MAAM,GACJ,WAAS,SAAS,CAI9B;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAUnB;IAoOD;;;;;;;;;;OAUG;IACH,oBALW,MAAM,gBACN,MAAM,cACN,MAAM,GACJ,iBAAiB,CAqB7B;IAmCD;;;;;OAKG;IACH,kCAFa,iBAAiB,CAI7B;IAED;;;;;;;;;;;OAWG;IACH,qBALW,cAAc,UACd,MAAM,GAEJ,QAAQ,UAAU,CAAC,CA8B/B;IAED;;;;;;;;;OASG;IACH,kBAHW,MAAM,GACJ,OAAO,CAoDnB;IAED;;;;OAIG;IACH,aAFa,MAAM,CAYlB;IAED;;;;;;;;OAQG;IACH,kBAFa,sBAAsB,CAkBlC;IAED;;;;;;;;;OASG;IACH,uCAHoB,MAAM,QAAE,MAAM,KAAG,IAAI,GAC5B,QAAQ,IAAI,CAAC,CAgBzB;IAED;;;;;;;;;OASG;IACH,YAFa,QAAQ,YAAY,CAAC,CAUjC;;CA6EJ;gCA54B+B,sBAAsB"}
1
+ {"version":3,"file":"VGeoContainerReader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IAwPI;;;;;;;;OAQG;IACH,8CALW,eAAe,GACb,QAAQ,mBAAmB,CAAC,CAUxC;IAhJD;;;OAGG;IACH,8CAFW,eAAe,EAOzB;IA/HD;;OAEG;IACH,4BAAmB;IAEnB;;;;OAIG;IACH,WAFU,gBAAc,SAAS,CAEX;IAuHtB;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;;;;;;OAaG;IACH,6BAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,2CAEC;IAED;;;;;OAKG;IACH,yBAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;;;;;;;;;;;OAYG;IACH,qBAEC;IAED;;;;;;;;;OASG;IACH,wBAEC;IAED;;;;OAIG;IACH,kBAFa,0BAA0B,CAItC;IA0FD;;;;;;;;OAQG;IACH,iBAHW,MAAM,GACJ,WAAS,SAAS,CAI9B;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,iCAHW,MAAM,GACJ,MAAM,CAoBlB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAUnB;IAoOD;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;OASG;IACH,8BAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,cAFa,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAI9C;IAED;;;;;;;;;;;;OAYG;IACH,8BAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;;;;;;OAYG;IACH,oBAPW,MAAM,gBACN,MAAM,cACN,MAAM,GACJ,iBAAiB,CAoC7B;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,mBAHW,MAAM,GACJ,OAAO,CAYnB;IAED;;;OAGG;IACH,cAFa,MAAM,CAYlB;IA0ED;;;;;OAKG;IACH,kCAFa,iBAAiB,CAI7B;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,qBANW,cAAc,UACd,MAAM,WAEN,WAAW,GACT,QAAQ,UAAU,CAAC,CA+D/B;IAED;;;;;;;;;;OAUG;IACH,kBAHW,MAAM,GACJ,OAAO,CAoDnB;IAED;;;;OAIG;IACH,aAFa,MAAM,CAYlB;IAED;;;;;;;;OAQG;IACH,kBAFa,sBAAsB,CAkBlC;IAED;;;;;;;;OAQG;IACH,uCAHoB,MAAM,QAAE,MAAM,KAAG,IAAI,GAC5B,QAAQ,IAAI,CAAC,CAMzB;IAED;;;;;;;;;OASG;IACH,YAFa,QAAQ,YAAY,CAAC,CAYjC;IAiCD;;;;;;;;;OASG;IACH,gBAFa,MAAM,CAQlB;;CA8DJ;gCA9vC+B,sBAAsB"}