blendops 0.0.0-stage → 1.1.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 (485) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/LICENSE +21 -0
  3. package/README.md +208 -2
  4. package/bin/blendops.mjs +4 -0
  5. package/bundles/claude-desktop-manual/BLENDOPS_SINGLE_FILE.md +78 -0
  6. package/bundles/claude-desktop-manual/IMPORT_STEPS.md +43 -0
  7. package/bundles/claude-desktop-manual/INSTALL_REPORT_TEMPLATE.md +13 -0
  8. package/bundles/claude-desktop-manual/README.md +70 -0
  9. package/bundles/claude-desktop-manual/SKILL.md +62 -0
  10. package/bundles/claude-desktop-manual/manifest.json +278 -0
  11. package/bundles/claude-desktop-manual/references/evidence-rules.md +13 -0
  12. package/bundles/claude-desktop-manual/references/install-boundary.md +13 -0
  13. package/bundles/claude-desktop-manual/references/laws/evidence-before-done.md +14 -0
  14. package/bundles/claude-desktop-manual/references/laws/no-arbitrary-python-interface.md +12 -0
  15. package/bundles/claude-desktop-manual/references/laws/non-blender-user-language.md +13 -0
  16. package/bundles/claude-desktop-manual/references/laws/official-runtime-only.md +20 -0
  17. package/bundles/claude-desktop-manual/references/packs/product-hero-v0.md +30 -0
  18. package/bundles/claude-desktop-manual/references/runtime-stacks.md +13 -0
  19. package/bundles/claude-desktop-manual/references/skill-map.md +36 -0
  20. package/bundles/claude-desktop-manual/references/skills/acceptance-criteria-builder.md +69 -0
  21. package/bundles/claude-desktop-manual/references/skills/asset-discovery.md +73 -0
  22. package/bundles/claude-desktop-manual/references/skills/asset-fallback-strategy.md +66 -0
  23. package/bundles/claude-desktop-manual/references/skills/asset-library-plan.md +69 -0
  24. package/bundles/claude-desktop-manual/references/skills/asset-license-checker.md +69 -0
  25. package/bundles/claude-desktop-manual/references/skills/asset-style-check.md +69 -0
  26. package/bundles/claude-desktop-manual/references/skills/blender-brainstorming.md +62 -0
  27. package/bundles/claude-desktop-manual/references/skills/blender-recipe-decomposer.md +66 -0
  28. package/bundles/claude-desktop-manual/references/skills/blender-troubleshooting.md +78 -0
  29. package/bundles/claude-desktop-manual/references/skills/blendops-help.md +82 -0
  30. package/bundles/claude-desktop-manual/references/skills/bridge-conflicts.md +68 -0
  31. package/bundles/claude-desktop-manual/references/skills/camera-composition.md +65 -0
  32. package/bundles/claude-desktop-manual/references/skills/character-portrait.md +68 -0
  33. package/bundles/claude-desktop-manual/references/skills/cli-appendix-job-outline.md +62 -0
  34. package/bundles/claude-desktop-manual/references/skills/color-management-decision.md +68 -0
  35. package/bundles/claude-desktop-manual/references/skills/composition-quality-checker.md +71 -0
  36. package/bundles/claude-desktop-manual/references/skills/cycles-vs-eevee-decision.md +65 -0
  37. package/bundles/claude-desktop-manual/references/skills/done-criteria.md +70 -0
  38. package/bundles/claude-desktop-manual/references/skills/environment-shot.md +65 -0
  39. package/bundles/claude-desktop-manual/references/skills/glb-animation-handoff.md +69 -0
  40. package/bundles/claude-desktop-manual/references/skills/glb-web-handoff.md +68 -0
  41. package/bundles/claude-desktop-manual/references/skills/intent-to-3d-brief-writer.md +68 -0
  42. package/bundles/claude-desktop-manual/references/skills/interior-scene.md +73 -0
  43. package/bundles/claude-desktop-manual/references/skills/lighting-material-plan.md +65 -0
  44. package/bundles/claude-desktop-manual/references/skills/lighting-quality-checker.md +70 -0
  45. package/bundles/claude-desktop-manual/references/skills/material-quality-checker.md +71 -0
  46. package/bundles/claude-desktop-manual/references/skills/mobile-glb-budget.md +73 -0
  47. package/bundles/claude-desktop-manual/references/skills/output-format-decision.md +63 -0
  48. package/bundles/claude-desktop-manual/references/skills/pack-prerequisite-checker.md +74 -0
  49. package/bundles/claude-desktop-manual/references/skills/path-one-host-outline.md +66 -0
  50. package/bundles/claude-desktop-manual/references/skills/plain-language-response.md +70 -0
  51. package/bundles/claude-desktop-manual/references/skills/polycount-budget-checker.md +71 -0
  52. package/bundles/claude-desktop-manual/references/skills/pre-handoff-verification.md +76 -0
  53. package/bundles/claude-desktop-manual/references/skills/preview-report.md +62 -0
  54. package/bundles/claude-desktop-manual/references/skills/product-grid-scene-planner.md +72 -0
  55. package/bundles/claude-desktop-manual/references/skills/product-hero-scene-planner.md +68 -0
  56. package/bundles/claude-desktop-manual/references/skills/r3f-component-plan.md +66 -0
  57. package/bundles/claude-desktop-manual/references/skills/recipe-fit-assessor.md +75 -0
  58. package/bundles/claude-desktop-manual/references/skills/render-export-evidence.md +70 -0
  59. package/bundles/claude-desktop-manual/references/skills/resolution-aspect-decision.md +65 -0
  60. package/bundles/claude-desktop-manual/references/skills/runtime-attempt-report.md +67 -0
  61. package/bundles/claude-desktop-manual/references/skills/runtime-path-picker.md +67 -0
  62. package/bundles/claude-desktop-manual/references/skills/runtime-readiness.md +63 -0
  63. package/bundles/claude-desktop-manual/references/skills/runtime-setup.md +63 -0
  64. package/bundles/claude-desktop-manual/references/skills/scene-readiness.md +65 -0
  65. package/bundles/claude-desktop-manual/references/skills/scope-guard.md +62 -0
  66. package/bundles/claude-desktop-manual/references/skills/stage-gates.md +91 -0
  67. package/bundles/claude-desktop-manual/references/skills/workflow-stage-router.md +67 -0
  68. package/bundles/generic-project-local/BLENDOPS.md +71 -0
  69. package/bundles/generic-project-local/INSTALL_REPORT_TEMPLATE.md +52 -0
  70. package/bundles/generic-project-local/README.md +73 -0
  71. package/bundles/generic-project-local/ROLLBACK.md +66 -0
  72. package/bundles/generic-project-local/manifest.json +66 -0
  73. package/bundles/skill-package/README.md +54 -0
  74. package/bundles/skill-package/blendops/LICENSE.txt +21 -0
  75. package/bundles/skill-package/blendops/SKILL.md +50 -0
  76. package/bundles/skill-package/blendops/agents/README.md +61 -0
  77. package/bundles/skill-package/blendops/agents/openai.yaml +4 -0
  78. package/bundles/skill-package/blendops/references/evidence-rules.md +17 -0
  79. package/bundles/skill-package/blendops/references/install-boundary.md +13 -0
  80. package/bundles/skill-package/blendops/references/law-evidence-before-done.md +12 -0
  81. package/bundles/skill-package/blendops/references/law-no-arbitrary-python-interface.md +7 -0
  82. package/bundles/skill-package/blendops/references/law-non-blender-user-language.md +8 -0
  83. package/bundles/skill-package/blendops/references/law-official-runtime-only.md +9 -0
  84. package/bundles/skill-package/blendops/references/pack-product-hero-v0.md +21 -0
  85. package/bundles/skill-package/blendops/references/runtime-stacks.md +13 -0
  86. package/bundles/skill-package/blendops/references/skill-acceptance-criteria-builder.md +51 -0
  87. package/bundles/skill-package/blendops/references/skill-asset-discovery.md +54 -0
  88. package/bundles/skill-package/blendops/references/skill-asset-fallback-strategy.md +48 -0
  89. package/bundles/skill-package/blendops/references/skill-asset-library-plan.md +51 -0
  90. package/bundles/skill-package/blendops/references/skill-asset-license-checker.md +51 -0
  91. package/bundles/skill-package/blendops/references/skill-asset-style-check.md +52 -0
  92. package/bundles/skill-package/blendops/references/skill-blender-brainstorming.md +43 -0
  93. package/bundles/skill-package/blendops/references/skill-blender-recipe-decomposer.md +48 -0
  94. package/bundles/skill-package/blendops/references/skill-blender-troubleshooting.md +59 -0
  95. package/bundles/skill-package/blendops/references/skill-blendops-help.md +62 -0
  96. package/bundles/skill-package/blendops/references/skill-bridge-conflicts.md +48 -0
  97. package/bundles/skill-package/blendops/references/skill-camera-composition.md +48 -0
  98. package/bundles/skill-package/blendops/references/skill-character-portrait.md +50 -0
  99. package/bundles/skill-package/blendops/references/skill-cli-appendix-job-outline.md +44 -0
  100. package/bundles/skill-package/blendops/references/skill-color-management-decision.md +50 -0
  101. package/bundles/skill-package/blendops/references/skill-composition-quality-checker.md +53 -0
  102. package/bundles/skill-package/blendops/references/skill-cycles-vs-eevee-decision.md +47 -0
  103. package/bundles/skill-package/blendops/references/skill-done-criteria.md +53 -0
  104. package/bundles/skill-package/blendops/references/skill-environment-shot.md +47 -0
  105. package/bundles/skill-package/blendops/references/skill-glb-animation-handoff.md +51 -0
  106. package/bundles/skill-package/blendops/references/skill-glb-web-handoff.md +51 -0
  107. package/bundles/skill-package/blendops/references/skill-intent-to-3d-brief-writer.md +50 -0
  108. package/bundles/skill-package/blendops/references/skill-interior-scene.md +54 -0
  109. package/bundles/skill-package/blendops/references/skill-lighting-material-plan.md +48 -0
  110. package/bundles/skill-package/blendops/references/skill-lighting-quality-checker.md +52 -0
  111. package/bundles/skill-package/blendops/references/skill-map.md +32 -0
  112. package/bundles/skill-package/blendops/references/skill-material-quality-checker.md +53 -0
  113. package/bundles/skill-package/blendops/references/skill-mobile-glb-budget.md +55 -0
  114. package/bundles/skill-package/blendops/references/skill-output-format-decision.md +46 -0
  115. package/bundles/skill-package/blendops/references/skill-pack-prerequisite-checker.md +56 -0
  116. package/bundles/skill-package/blendops/references/skill-path-one-host-outline.md +48 -0
  117. package/bundles/skill-package/blendops/references/skill-plain-language-response.md +53 -0
  118. package/bundles/skill-package/blendops/references/skill-polycount-budget-checker.md +53 -0
  119. package/bundles/skill-package/blendops/references/skill-pre-handoff-verification.md +57 -0
  120. package/bundles/skill-package/blendops/references/skill-preview-report.md +45 -0
  121. package/bundles/skill-package/blendops/references/skill-product-grid-scene-planner.md +54 -0
  122. package/bundles/skill-package/blendops/references/skill-product-hero-scene-planner.md +51 -0
  123. package/bundles/skill-package/blendops/references/skill-r3f-component-plan.md +48 -0
  124. package/bundles/skill-package/blendops/references/skill-recipe-fit-assessor.md +57 -0
  125. package/bundles/skill-package/blendops/references/skill-render-export-evidence.md +51 -0
  126. package/bundles/skill-package/blendops/references/skill-resolution-aspect-decision.md +48 -0
  127. package/bundles/skill-package/blendops/references/skill-runtime-attempt-report.md +49 -0
  128. package/bundles/skill-package/blendops/references/skill-runtime-path-picker.md +49 -0
  129. package/bundles/skill-package/blendops/references/skill-runtime-readiness.md +45 -0
  130. package/bundles/skill-package/blendops/references/skill-runtime-setup.md +45 -0
  131. package/bundles/skill-package/blendops/references/skill-scene-readiness.md +48 -0
  132. package/bundles/skill-package/blendops/references/skill-scope-guard.md +44 -0
  133. package/bundles/skill-package/blendops/references/skill-stage-gates.md +73 -0
  134. package/bundles/skill-package/blendops/references/skill-workflow-stage-router.md +49 -0
  135. package/docs/README.md +276 -0
  136. package/docs/examples/glb-web-handoff/README.md +174 -0
  137. package/docs/examples/glb-web-handoff/r3f-glb-viewer.tsx +320 -0
  138. package/docs/examples/glb-web-handoff/threejs-glb-viewer.mjs +709 -0
  139. package/docs/knowledge-and-recipe-catalog.md +236 -0
  140. package/docs/recipes/README.md +27 -0
  141. package/docs/recipes/cyberpunk-shoe-hero.md +97 -0
  142. package/docs/workflows/README.md +14 -0
  143. package/docs/workflows/full-non-blender-user-workflow.md +210 -0
  144. package/docs/workflows/product-hero-workflow.md +92 -0
  145. package/laws/README.md +32 -0
  146. package/laws/evidence-before-done.md +37 -0
  147. package/laws/no-arbitrary-python-interface.md +32 -0
  148. package/laws/non-blender-user-language.md +32 -0
  149. package/laws/official-runtime-only.md +78 -0
  150. package/package.json +103 -4
  151. package/packs/README.md +11 -0
  152. package/packs/product-hero-v0/PACK.md +114 -0
  153. package/registry/catalog-index.json +21344 -0
  154. package/registry/compatibility-matrix.json +533 -0
  155. package/registry/contract-context-fields.json +391 -0
  156. package/registry/knowledge-catalog.json +4648 -0
  157. package/registry/knowledge-sources.json +438 -0
  158. package/registry/recipe-catalog.json +2565 -0
  159. package/registry/runtime-capability-policy.json +525 -0
  160. package/registry/runtime-operations.json +4468 -0
  161. package/registry/skills.json +10231 -0
  162. package/registry/workflow-graph.json +7390 -0
  163. package/schemas/adapter-compatibility-matrix.schema.json +166 -0
  164. package/schemas/contract-context-fields.schema.json +147 -0
  165. package/schemas/execution-plan.schema.json +325 -0
  166. package/schemas/glb-web-handoff-manifest.schema.json +744 -0
  167. package/schemas/knowledge-record.schema.json +460 -0
  168. package/schemas/knowledge-source-registry.schema.json +268 -0
  169. package/schemas/operation-execution-ledger.schema.json +348 -0
  170. package/schemas/recipe-record.schema.json +469 -0
  171. package/schemas/runtime-capability-policy.schema.json +184 -0
  172. package/schemas/runtime-evidence-packet.schema.json +211 -0
  173. package/schemas/runtime-operations.schema.json +535 -0
  174. package/schemas/runtime-qualification-report.schema.json +540 -0
  175. package/schemas/runtime-session.schema.json +350 -0
  176. package/schemas/scene-spec.schema.json +624 -0
  177. package/schemas/skill-contract.schema.json +402 -0
  178. package/schemas/skill-eval.schema.json +509 -0
  179. package/scripts/build-knowledge-catalog.mjs +2376 -0
  180. package/scripts/compile-scene-plan.mjs +1945 -0
  181. package/scripts/export-claude-skills.mjs +634 -0
  182. package/scripts/generate-glb-handoff-report.mjs +2376 -0
  183. package/scripts/inspect-glb.mjs +1627 -0
  184. package/scripts/install-skills.mjs +5443 -0
  185. package/scripts/runtime-orchestrator.mjs +7713 -0
  186. package/scripts/validate-capability-policy.mjs +531 -0
  187. package/scripts/validate-evidence-packet.mjs +256 -0
  188. package/skills/README.md +315 -0
  189. package/skills/_template/SKILL.md +296 -0
  190. package/skills/acceptance-criteria-builder/EVAL.md +25 -0
  191. package/skills/acceptance-criteria-builder/SKILL.md +257 -0
  192. package/skills/acceptance-criteria-builder/contract.json +205 -0
  193. package/skills/acceptance-criteria-builder/references/brief-to-criteria-mapper.md +22 -0
  194. package/skills/acceptance-criteria-builder/references/checklist-patterns.md +22 -0
  195. package/skills/acceptance-criteria-builder/references/evidence-hook-rules.md +19 -0
  196. package/skills/asset-discovery/EVAL.md +81 -0
  197. package/skills/asset-discovery/SKILL.md +252 -0
  198. package/skills/asset-discovery/contract.json +291 -0
  199. package/skills/asset-discovery/references/asset-strategy-decision-tree.md +40 -0
  200. package/skills/asset-discovery/references/budget-reconciliation-patterns.md +54 -0
  201. package/skills/asset-discovery/references/license-confidence-table.md +41 -0
  202. package/skills/asset-fallback-strategy/EVAL.md +34 -0
  203. package/skills/asset-fallback-strategy/SKILL.md +248 -0
  204. package/skills/asset-fallback-strategy/contract.json +190 -0
  205. package/skills/asset-fallback-strategy/references/drop-with-caveat-rules.md +36 -0
  206. package/skills/asset-fallback-strategy/references/fallback-option-types.md +55 -0
  207. package/skills/asset-fallback-strategy/references/scoring-rubric.md +61 -0
  208. package/skills/asset-library-plan/EVAL.md +28 -0
  209. package/skills/asset-library-plan/SKILL.md +263 -0
  210. package/skills/asset-library-plan/contract.json +177 -0
  211. package/skills/asset-library-plan/references/folder-structure-rules.md +63 -0
  212. package/skills/asset-library-plan/references/metadata-schema.md +62 -0
  213. package/skills/asset-library-plan/references/naming-rules.md +51 -0
  214. package/skills/asset-license-checker/EVAL.md +33 -0
  215. package/skills/asset-license-checker/SKILL.md +245 -0
  216. package/skills/asset-license-checker/contract.json +172 -0
  217. package/skills/asset-license-checker/references/attribution-rendering-patterns.md +48 -0
  218. package/skills/asset-license-checker/references/common-license-mapping.md +39 -0
  219. package/skills/asset-license-checker/references/license-source-rules.md +38 -0
  220. package/skills/asset-style-check/EVAL.md +26 -0
  221. package/skills/asset-style-check/SKILL.md +238 -0
  222. package/skills/asset-style-check/contract.json +251 -0
  223. package/skills/asset-style-check/references/drift-classification.md +40 -0
  224. package/skills/asset-style-check/references/intentional-mixed-style.md +39 -0
  225. package/skills/asset-style-check/references/style-axes.md +46 -0
  226. package/skills/blender-brainstorming/EVAL.md +79 -0
  227. package/skills/blender-brainstorming/SKILL.md +228 -0
  228. package/skills/blender-brainstorming/contract.json +115 -0
  229. package/skills/blender-brainstorming/references/alternative-scoping-templates.md +43 -0
  230. package/skills/blender-brainstorming/references/clarification-patterns.md +29 -0
  231. package/skills/blender-brainstorming/references/intent-summary-style-guide.md +25 -0
  232. package/skills/blender-recipe-decomposer/EVAL.md +35 -0
  233. package/skills/blender-recipe-decomposer/SKILL.md +258 -0
  234. package/skills/blender-recipe-decomposer/contract.json +152 -0
  235. package/skills/blender-recipe-decomposer/references/dependency-patterns.md +53 -0
  236. package/skills/blender-recipe-decomposer/references/recipe-grouping-rules.md +58 -0
  237. package/skills/blender-recipe-decomposer/references/recipe-naming-rules.md +44 -0
  238. package/skills/blender-troubleshooting/EVAL.md +78 -0
  239. package/skills/blender-troubleshooting/SKILL.md +263 -0
  240. package/skills/blender-troubleshooting/contract.json +352 -0
  241. package/skills/blender-troubleshooting/references/common-symptom-playbooks.md +51 -0
  242. package/skills/blender-troubleshooting/references/divergence-routing-table.md +23 -0
  243. package/skills/blender-troubleshooting/references/four-phase-template.md +51 -0
  244. package/skills/blendops-help/EVAL.md +67 -0
  245. package/skills/blendops-help/SKILL.md +312 -0
  246. package/skills/blendops-help/contract.json +229 -0
  247. package/skills/blendops-help/references/lifecycle-phases.md +91 -0
  248. package/skills/blendops-help/references/quick-start-prompts.md +65 -0
  249. package/skills/blendops-help/references/routing-decision-tree.md +57 -0
  250. package/skills/bridge-conflicts/EVAL.md +83 -0
  251. package/skills/bridge-conflicts/SKILL.md +246 -0
  252. package/skills/bridge-conflicts/contract.json +145 -0
  253. package/skills/bridge-conflicts/references/bridge-state-matrix-template.md +82 -0
  254. package/skills/bridge-conflicts/references/conflict-playbooks.md +99 -0
  255. package/skills/bridge-conflicts/references/do-not-reminders.md +42 -0
  256. package/skills/camera-composition/EVAL.md +32 -0
  257. package/skills/camera-composition/SKILL.md +196 -0
  258. package/skills/camera-composition/contract.json +180 -0
  259. package/skills/camera-composition/references/camera-presets.md +30 -0
  260. package/skills/camera-composition/references/camera-rubric.md +24 -0
  261. package/skills/camera-composition/references/hero-composition-patterns.md +24 -0
  262. package/skills/camera-composition/references/web-layout-negative-space.md +25 -0
  263. package/skills/character-portrait/EVAL.md +42 -0
  264. package/skills/character-portrait/SKILL.md +245 -0
  265. package/skills/character-portrait/contract.json +205 -0
  266. package/skills/character-portrait/references/portrait-framing-rules.md +39 -0
  267. package/skills/character-portrait/references/portrait-lighting-patterns.md +50 -0
  268. package/skills/character-portrait/references/style-consistency-rules.md +41 -0
  269. package/skills/cli-appendix-job-outline/EVAL.md +26 -0
  270. package/skills/cli-appendix-job-outline/SKILL.md +252 -0
  271. package/skills/cli-appendix-job-outline/contract.json +147 -0
  272. package/skills/cli-appendix-job-outline/references/flag-order-reminders.md +16 -0
  273. package/skills/cli-appendix-job-outline/references/job-type-matrix.md +13 -0
  274. package/skills/cli-appendix-job-outline/references/stateless-limitations.md +12 -0
  275. package/skills/color-management-decision/EVAL.md +28 -0
  276. package/skills/color-management-decision/SKILL.md +254 -0
  277. package/skills/color-management-decision/contract.json +162 -0
  278. package/skills/color-management-decision/references/look-comparison.md +44 -0
  279. package/skills/color-management-decision/references/per-channel-rules.md +49 -0
  280. package/skills/color-management-decision/references/pipeline-mapping.md +47 -0
  281. package/skills/composition-quality-checker/EVAL.md +38 -0
  282. package/skills/composition-quality-checker/SKILL.md +260 -0
  283. package/skills/composition-quality-checker/contract.json +221 -0
  284. package/skills/composition-quality-checker/references/aspect-ratio-rules.md +37 -0
  285. package/skills/composition-quality-checker/references/composition-rules.md +58 -0
  286. package/skills/composition-quality-checker/references/headroom-leadroom-rules.md +46 -0
  287. package/skills/cycles-vs-eevee-decision/EVAL.md +26 -0
  288. package/skills/cycles-vs-eevee-decision/SKILL.md +249 -0
  289. package/skills/cycles-vs-eevee-decision/contract.json +142 -0
  290. package/skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md +39 -0
  291. package/skills/cycles-vs-eevee-decision/references/gpu-device-rules.md +51 -0
  292. package/skills/cycles-vs-eevee-decision/references/samples-by-quality.md +53 -0
  293. package/skills/done-criteria/EVAL.md +33 -0
  294. package/skills/done-criteria/SKILL.md +225 -0
  295. package/skills/done-criteria/contract.json +199 -0
  296. package/skills/done-criteria/references/done-vs-perfect.md +56 -0
  297. package/skills/done-criteria/references/out-of-scope-patterns.md +50 -0
  298. package/skills/done-criteria/references/stop-condition-templates.md +39 -0
  299. package/skills/environment-shot/EVAL.md +44 -0
  300. package/skills/environment-shot/SKILL.md +237 -0
  301. package/skills/environment-shot/contract.json +162 -0
  302. package/skills/environment-shot/references/depth-layering-rules.md +49 -0
  303. package/skills/environment-shot/references/time-and-weather-rules.md +35 -0
  304. package/skills/environment-shot/references/wide-shot-camera-rules.md +51 -0
  305. package/skills/glb-animation-handoff/EVAL.md +39 -0
  306. package/skills/glb-animation-handoff/SKILL.md +271 -0
  307. package/skills/glb-animation-handoff/contract.json +247 -0
  308. package/skills/glb-animation-handoff/references/animation-types.md +36 -0
  309. package/skills/glb-animation-handoff/references/transition-rules.md +55 -0
  310. package/skills/glb-animation-handoff/references/web-stack-caveats.md +40 -0
  311. package/skills/glb-web-handoff/EVAL.md +33 -0
  312. package/skills/glb-web-handoff/SKILL.md +212 -0
  313. package/skills/glb-web-handoff/contract.json +171 -0
  314. package/skills/glb-web-handoff/references/artifact-status-language.md +26 -0
  315. package/skills/glb-web-handoff/references/glb-handoff-checklist.md +30 -0
  316. package/skills/glb-web-handoff/references/performance-caveats.md +26 -0
  317. package/skills/glb-web-handoff/references/threejs-r3f-handoff.md +28 -0
  318. package/skills/intent-to-3d-brief-writer/EVAL.md +82 -0
  319. package/skills/intent-to-3d-brief-writer/SKILL.md +238 -0
  320. package/skills/intent-to-3d-brief-writer/contract.json +195 -0
  321. package/skills/intent-to-3d-brief-writer/references/acceptance-criteria-patterns.md +46 -0
  322. package/skills/intent-to-3d-brief-writer/references/eight-slot-template.md +123 -0
  323. package/skills/intent-to-3d-brief-writer/references/mixed-audience-handling.md +39 -0
  324. package/skills/interior-scene/EVAL.md +44 -0
  325. package/skills/interior-scene/SKILL.md +261 -0
  326. package/skills/interior-scene/contract.json +277 -0
  327. package/skills/interior-scene/references/furniture-layout-rules.md +51 -0
  328. package/skills/interior-scene/references/interior-architecture-rules.md +47 -0
  329. package/skills/interior-scene/references/interior-camera-rules.md +47 -0
  330. package/skills/lighting-material-plan/EVAL.md +32 -0
  331. package/skills/lighting-material-plan/SKILL.md +194 -0
  332. package/skills/lighting-material-plan/contract.json +213 -0
  333. package/skills/lighting-material-plan/references/cyberpunk-lookdev.md +22 -0
  334. package/skills/lighting-material-plan/references/lighting-patterns.md +30 -0
  335. package/skills/lighting-material-plan/references/material-portability.md +25 -0
  336. package/skills/lighting-material-plan/references/reflective-floor-pattern.md +22 -0
  337. package/skills/lighting-material-plan/references/web-material-simplification.md +23 -0
  338. package/skills/lighting-quality-checker/EVAL.md +41 -0
  339. package/skills/lighting-quality-checker/SKILL.md +247 -0
  340. package/skills/lighting-quality-checker/contract.json +187 -0
  341. package/skills/lighting-quality-checker/references/hdri-balance-rules.md +48 -0
  342. package/skills/lighting-quality-checker/references/intensity-ranges.md +73 -0
  343. package/skills/lighting-quality-checker/references/shadow-softness-rules.md +38 -0
  344. package/skills/material-quality-checker/EVAL.md +40 -0
  345. package/skills/material-quality-checker/SKILL.md +261 -0
  346. package/skills/material-quality-checker/contract.json +244 -0
  347. package/skills/material-quality-checker/references/consumer-stack-rules.md +62 -0
  348. package/skills/material-quality-checker/references/pbr-sanity-rules.md +78 -0
  349. package/skills/material-quality-checker/references/texture-budget-rules.md +48 -0
  350. package/skills/mobile-glb-budget/EVAL.md +40 -0
  351. package/skills/mobile-glb-budget/SKILL.md +264 -0
  352. package/skills/mobile-glb-budget/contract.json +309 -0
  353. package/skills/mobile-glb-budget/references/budget-tiers.md +30 -0
  354. package/skills/mobile-glb-budget/references/degradation-plan.md +34 -0
  355. package/skills/mobile-glb-budget/references/violation-rules.md +43 -0
  356. package/skills/output-format-decision/EVAL.md +27 -0
  357. package/skills/output-format-decision/SKILL.md +222 -0
  358. package/skills/output-format-decision/contract.json +179 -0
  359. package/skills/output-format-decision/references/bit-depth-rules.md +56 -0
  360. package/skills/output-format-decision/references/compression-tradeoffs.md +62 -0
  361. package/skills/output-format-decision/references/format-decision-matrix.md +34 -0
  362. package/skills/pack-prerequisite-checker/EVAL.md +26 -0
  363. package/skills/pack-prerequisite-checker/SKILL.md +272 -0
  364. package/skills/pack-prerequisite-checker/contract.json +214 -0
  365. package/skills/pack-prerequisite-checker/references/blocked-start-playbook.md +21 -0
  366. package/skills/pack-prerequisite-checker/references/pack-readiness-template.md +38 -0
  367. package/skills/pack-prerequisite-checker/references/prerequisite-matrix.md +20 -0
  368. package/skills/path-one-host-outline/EVAL.md +26 -0
  369. package/skills/path-one-host-outline/SKILL.md +251 -0
  370. package/skills/path-one-host-outline/contract.json +167 -0
  371. package/skills/path-one-host-outline/references/connector-vs-manual-matrix.md +21 -0
  372. package/skills/path-one-host-outline/references/host-checklist-template.md +35 -0
  373. package/skills/path-one-host-outline/references/lab-addon-reminders.md +12 -0
  374. package/skills/plain-language-response/EVAL.md +33 -0
  375. package/skills/plain-language-response/SKILL.md +194 -0
  376. package/skills/plain-language-response/contract.json +242 -0
  377. package/skills/plain-language-response/references/caveat-language.md +25 -0
  378. package/skills/plain-language-response/references/plain-language-patterns.md +30 -0
  379. package/skills/plain-language-response/references/stakeholder-friendly-examples.md +30 -0
  380. package/skills/plain-language-response/references/status-summary-templates.md +50 -0
  381. package/skills/polycount-budget-checker/EVAL.md +40 -0
  382. package/skills/polycount-budget-checker/SKILL.md +251 -0
  383. package/skills/polycount-budget-checker/contract.json +196 -0
  384. package/skills/polycount-budget-checker/references/instance-counting-rules.md +39 -0
  385. package/skills/polycount-budget-checker/references/per-mesh-rules.md +43 -0
  386. package/skills/polycount-budget-checker/references/topology-hints.md +56 -0
  387. package/skills/pre-handoff-verification/EVAL.md +84 -0
  388. package/skills/pre-handoff-verification/SKILL.md +252 -0
  389. package/skills/pre-handoff-verification/contract.json +295 -0
  390. package/skills/pre-handoff-verification/references/downgrade-rules.md +39 -0
  391. package/skills/pre-handoff-verification/references/seven-point-checklist.md +46 -0
  392. package/skills/pre-handoff-verification/references/text-only-mode-handling.md +36 -0
  393. package/skills/preview-report/EVAL.md +39 -0
  394. package/skills/preview-report/SKILL.md +254 -0
  395. package/skills/preview-report/contract.json +141 -0
  396. package/skills/preview-report/references/handoff-recipients.md +41 -0
  397. package/skills/preview-report/references/report-schema.md +60 -0
  398. package/skills/preview-report/references/truth-label-rules.md +36 -0
  399. package/skills/product-grid-scene-planner/EVAL.md +42 -0
  400. package/skills/product-grid-scene-planner/SKILL.md +246 -0
  401. package/skills/product-grid-scene-planner/contract.json +257 -0
  402. package/skills/product-grid-scene-planner/references/grid-consistency-rules.md +53 -0
  403. package/skills/product-grid-scene-planner/references/grid-layout-rules.md +42 -0
  404. package/skills/product-grid-scene-planner/references/grid-output-naming-rules.md +52 -0
  405. package/skills/product-hero-scene-planner/EVAL.md +33 -0
  406. package/skills/product-hero-scene-planner/SKILL.md +227 -0
  407. package/skills/product-hero-scene-planner/contract.json +228 -0
  408. package/skills/product-hero-scene-planner/references/clarification-patterns.md +24 -0
  409. package/skills/product-hero-scene-planner/references/cyberpunk-shoe-example.md +28 -0
  410. package/skills/product-hero-scene-planner/references/product-hero-playbooks.md +22 -0
  411. package/skills/product-hero-scene-planner/references/scene-plan-schema.md +35 -0
  412. package/skills/r3f-component-plan/EVAL.md +43 -0
  413. package/skills/r3f-component-plan/SKILL.md +290 -0
  414. package/skills/r3f-component-plan/contract.json +171 -0
  415. package/skills/r3f-component-plan/references/component-shape-patterns.md +54 -0
  416. package/skills/r3f-component-plan/references/suspense-placement-rules.md +50 -0
  417. package/skills/r3f-component-plan/references/usegltf-caching-rules.md +53 -0
  418. package/skills/recipe-fit-assessor/EVAL.md +28 -0
  419. package/skills/recipe-fit-assessor/SKILL.md +266 -0
  420. package/skills/recipe-fit-assessor/contract.json +220 -0
  421. package/skills/recipe-fit-assessor/references/recipe-catalog.md +30 -0
  422. package/skills/recipe-fit-assessor/references/scope-gap-rules.md +27 -0
  423. package/skills/recipe-fit-assessor/references/workflow-recommendation-template.md +34 -0
  424. package/skills/render-export-evidence/EVAL.md +86 -0
  425. package/skills/render-export-evidence/SKILL.md +339 -0
  426. package/skills/render-export-evidence/contract.json +206 -0
  427. package/skills/render-export-evidence/references/attempted-vs-failed-rubric.md +75 -0
  428. package/skills/render-export-evidence/references/evidence-record-templates.md +143 -0
  429. package/skills/render-export-evidence/references/truth-label-decision-tree.md +57 -0
  430. package/skills/resolution-aspect-decision/EVAL.md +26 -0
  431. package/skills/resolution-aspect-decision/SKILL.md +246 -0
  432. package/skills/resolution-aspect-decision/contract.json +160 -0
  433. package/skills/resolution-aspect-decision/references/aspect-defaults.md +41 -0
  434. package/skills/resolution-aspect-decision/references/print-vs-screen-rules.md +58 -0
  435. package/skills/resolution-aspect-decision/references/resolution-defaults.md +64 -0
  436. package/skills/runtime-attempt-report/EVAL.md +26 -0
  437. package/skills/runtime-attempt-report/SKILL.md +268 -0
  438. package/skills/runtime-attempt-report/contract.json +176 -0
  439. package/skills/runtime-attempt-report/references/attempt-record-template.md +49 -0
  440. package/skills/runtime-attempt-report/references/triage-next-steps.md +15 -0
  441. package/skills/runtime-attempt-report/references/truth-label-blocks.md +27 -0
  442. package/skills/runtime-path-picker/EVAL.md +26 -0
  443. package/skills/runtime-path-picker/SKILL.md +268 -0
  444. package/skills/runtime-path-picker/contract.json +191 -0
  445. package/skills/runtime-path-picker/references/anti-patterns.md +14 -0
  446. package/skills/runtime-path-picker/references/decision-tree.md +29 -0
  447. package/skills/runtime-path-picker/references/path-constraints-table.md +18 -0
  448. package/skills/runtime-readiness/EVAL.md +33 -0
  449. package/skills/runtime-readiness/SKILL.md +218 -0
  450. package/skills/runtime-readiness/contract.json +190 -0
  451. package/skills/runtime-readiness/references/blocker-report-template.md +28 -0
  452. package/skills/runtime-readiness/references/evidence-examples.md +23 -0
  453. package/skills/runtime-readiness/references/readiness-matrix.md +46 -0
  454. package/skills/runtime-setup/EVAL.md +33 -0
  455. package/skills/runtime-setup/SKILL.md +209 -0
  456. package/skills/runtime-setup/contract.json +171 -0
  457. package/skills/runtime-setup/references/runtime-option-decision-tree.md +28 -0
  458. package/skills/runtime-setup/references/setup-summary-template.md +33 -0
  459. package/skills/runtime-setup/references/source-confidence-labels.md +23 -0
  460. package/skills/scene-readiness/EVAL.md +33 -0
  461. package/skills/scene-readiness/SKILL.md +195 -0
  462. package/skills/scene-readiness/contract.json +198 -0
  463. package/skills/scene-readiness/references/blocker-catalog.md +24 -0
  464. package/skills/scene-readiness/references/not-run-handling.md +22 -0
  465. package/skills/scene-readiness/references/quality-rubric.md +23 -0
  466. package/skills/scene-readiness/references/verdict-language.md +22 -0
  467. package/skills/scope-guard/EVAL.md +33 -0
  468. package/skills/scope-guard/SKILL.md +222 -0
  469. package/skills/scope-guard/contract.json +171 -0
  470. package/skills/scope-guard/references/options-language-template.md +51 -0
  471. package/skills/scope-guard/references/recurring-creep-patterns.md +55 -0
  472. package/skills/scope-guard/references/scope-addition-classification.md +55 -0
  473. package/skills/stage-gates/EVAL.md +40 -0
  474. package/skills/stage-gates/SKILL.md +257 -0
  475. package/skills/stage-gates/contract.json +490 -0
  476. package/skills/stage-gates/references/failed-gate-handling.md +42 -0
  477. package/skills/stage-gates/references/gate-template.md +46 -0
  478. package/skills/stage-gates/references/stage-decomposition-patterns.md +55 -0
  479. package/skills/workflow-stage-router/EVAL.md +25 -0
  480. package/skills/workflow-stage-router/SKILL.md +259 -0
  481. package/skills/workflow-stage-router/contract.json +150 -0
  482. package/skills/workflow-stage-router/references/milestone-model.md +20 -0
  483. package/skills/workflow-stage-router/references/routing-decision-tree.md +32 -0
  484. package/skills/workflow-stage-router/references/stage-handoff-template.md +37 -0
  485. package/skills.sh.json +102 -0
@@ -0,0 +1,1627 @@
1
+ #!/usr/bin/env node
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import crypto from 'node:crypto';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ const __filename = fileURLToPath(import.meta.url);
8
+
9
+ export const GLB_MAGIC = 0x46546c67; // 'glTF' in ASCII little-endian
10
+ export const GLB_VERSION_2 = 2;
11
+ export const GLB_CHUNK_TYPE_JSON = 0x4e4f534a; // 'JSON' in ASCII little-endian
12
+ export const GLB_CHUNK_TYPE_BIN = 0x004e4942; // 'BIN\0' in ASCII little-endian
13
+
14
+ const COMPONENT_TYPE_BYTE_SIZES = Object.freeze({
15
+ 5120: 1, // BYTE
16
+ 5121: 1, // UNSIGNED_BYTE
17
+ 5122: 2, // SHORT
18
+ 5123: 2, // UNSIGNED_SHORT
19
+ 5125: 4, // UNSIGNED_INT
20
+ 5126: 4, // FLOAT
21
+ });
22
+
23
+ const ACCESSOR_TYPE_COMPONENT_COUNTS = Object.freeze({
24
+ SCALAR: 1,
25
+ VEC2: 2,
26
+ VEC3: 3,
27
+ VEC4: 4,
28
+ MAT2: 4,
29
+ MAT3: 9,
30
+ MAT4: 16,
31
+ });
32
+
33
+ const VALID_ALPHA_MODES = new Set(['OPAQUE', 'MASK', 'BLEND']);
34
+ const VALID_ANIMATION_PATHS = new Set(['translation', 'rotation', 'scale', 'weights']);
35
+ const VALID_INTERPOLATIONS = new Set(['LINEAR', 'STEP', 'CUBICSPLINE']);
36
+
37
+ export const CONTAINER_TRUTH_DISCLAIMER =
38
+ 'Container inspection verifies binary GLB 2.0 framing, JSON/BIN chunk alignment, buffer/accessor bounds, and structural metadata only. It does NOT replace full Khronos glTF 2.0 specification validation (gltf-validator), and it does NOT prove visual framing, lighting quality, material appearance, or live Blender runtime execution.';
39
+
40
+ /**
41
+ * Builds a deterministic, spec-compliant minimal GLB 2.0 buffer in memory
42
+ * for unit testing and static container validation without claiming a live Blender export.
43
+ */
44
+ export function buildMinimalValidGlbBuffer({
45
+ includeBinChunk = true,
46
+ includePositionBounds = true,
47
+ generator = 'blendops-synthetic-glb-fixture',
48
+ extras = { isSyntheticFixture: true },
49
+ customGltfPatch = null,
50
+ extraBinBytes = null,
51
+ } = {}) {
52
+ // 3 vertices (1 triangle), 3 floats per vertex = 36 bytes, padded to 4-byte boundary (36 is already a multiple of 4)
53
+ const vertexPositions = new Float32Array([
54
+ 0.0, 0.0, 0.0,
55
+ 1.0, 0.0, 0.0,
56
+ 0.0, 1.0, 0.0,
57
+ ]);
58
+ const baseBinPayload = Buffer.from(vertexPositions.buffer);
59
+ const binPayload = extraBinBytes
60
+ ? Buffer.concat([baseBinPayload, Buffer.from(extraBinBytes)])
61
+ : baseBinPayload;
62
+
63
+ const gltfJson = {
64
+ asset: {
65
+ version: '2.0',
66
+ generator,
67
+ },
68
+ extras,
69
+ scene: 0,
70
+ scenes: [{ name: 'SyntheticValidationScene', nodes: [0] }],
71
+ nodes: [{ name: 'SyntheticTriangleNode', mesh: 0 }],
72
+ meshes: [
73
+ {
74
+ name: 'SyntheticTriangleMesh',
75
+ primitives: [
76
+ {
77
+ attributes: { POSITION: 0 },
78
+ material: 0,
79
+ },
80
+ ],
81
+ },
82
+ ],
83
+ materials: [
84
+ {
85
+ name: 'SyntheticPBRMaterial',
86
+ pbrMetallicRoughness: {
87
+ baseColorFactor: [0.8, 0.8, 0.8, 1.0],
88
+ metallicFactor: 0.0,
89
+ roughnessFactor: 0.5,
90
+ },
91
+ },
92
+ ],
93
+ };
94
+
95
+ if (includeBinChunk) {
96
+ gltfJson.buffers = [{ byteLength: binPayload.byteLength }];
97
+ gltfJson.bufferViews = [
98
+ {
99
+ buffer: 0,
100
+ byteOffset: 0,
101
+ byteLength: baseBinPayload.byteLength,
102
+ target: 34962, // ARRAY_BUFFER
103
+ },
104
+ ];
105
+ const accessor = {
106
+ bufferView: 0,
107
+ byteOffset: 0,
108
+ componentType: 5126, // FLOAT
109
+ count: 3,
110
+ type: 'VEC3',
111
+ };
112
+ if (includePositionBounds) {
113
+ accessor.min = [0.0, 0.0, 0.0];
114
+ accessor.max = [1.0, 1.0, 0.0];
115
+ }
116
+ gltfJson.accessors = [accessor];
117
+ } else {
118
+ gltfJson.meshes = [];
119
+ gltfJson.nodes = [{ name: 'EmptyRootNode' }];
120
+ }
121
+
122
+ if (typeof customGltfPatch === 'function') {
123
+ customGltfPatch(gltfJson, { baseBinByteLength: baseBinPayload.byteLength, totalBinByteLength: binPayload.byteLength });
124
+ } else if (customGltfPatch && typeof customGltfPatch === 'object') {
125
+ Object.assign(gltfJson, customGltfPatch);
126
+ }
127
+
128
+ const rawJsonBytes = Buffer.from(JSON.stringify(gltfJson), 'utf8');
129
+ const jsonPadLen = (4 - (rawJsonBytes.length % 4)) % 4;
130
+ const jsonChunkData = Buffer.concat([rawJsonBytes, Buffer.alloc(jsonPadLen, 0x20)]); // pad with ASCII space 0x20
131
+
132
+ let binChunkFull = Buffer.alloc(0);
133
+ if (includeBinChunk) {
134
+ const binPadLen = (4 - (binPayload.length % 4)) % 4;
135
+ const binChunkData = Buffer.concat([binPayload, Buffer.alloc(binPadLen, 0x00)]);
136
+ const binHeader = Buffer.alloc(8);
137
+ binHeader.writeUInt32LE(binChunkData.length, 0);
138
+ binHeader.writeUInt32LE(GLB_CHUNK_TYPE_BIN, 4);
139
+ binChunkFull = Buffer.concat([binHeader, binChunkData]);
140
+ }
141
+
142
+ const totalLength = 12 + 8 + jsonChunkData.length + binChunkFull.length;
143
+ const header = Buffer.alloc(12);
144
+ header.writeUInt32LE(GLB_MAGIC, 0);
145
+ header.writeUInt32LE(GLB_VERSION_2, 4);
146
+ header.writeUInt32LE(totalLength, 8);
147
+
148
+ const jsonHeader = Buffer.alloc(8);
149
+ jsonHeader.writeUInt32LE(jsonChunkData.length, 0);
150
+ jsonHeader.writeUInt32LE(GLB_CHUNK_TYPE_JSON, 4);
151
+
152
+ return Buffer.concat([header, jsonHeader, jsonChunkData, binChunkFull]);
153
+ }
154
+
155
+ function collectUsedExtensionsInObject(node, foundSet = new Set()) {
156
+ if (!node || typeof node !== 'object') return foundSet;
157
+ if (Array.isArray(node)) {
158
+ for (const item of node) {
159
+ collectUsedExtensionsInObject(item, foundSet);
160
+ }
161
+ return foundSet;
162
+ }
163
+ if (node.extensions && typeof node.extensions === 'object' && !Array.isArray(node.extensions)) {
164
+ for (const extName of Object.keys(node.extensions)) {
165
+ if (typeof extName === 'string' && extName.length > 0) {
166
+ foundSet.add(extName);
167
+ }
168
+ }
169
+ }
170
+ for (const val of Object.values(node)) {
171
+ if (val && typeof val === 'object') {
172
+ collectUsedExtensionsInObject(val, foundSet);
173
+ }
174
+ }
175
+ return foundSet;
176
+ }
177
+
178
+ function isExternalUri(uri) {
179
+ if (typeof uri !== 'string' || uri.trim().length === 0) return false;
180
+ return !uri.trim().toLowerCase().startsWith('data:');
181
+ }
182
+
183
+ function hasUnsafeUriTraversal(uri) {
184
+ if (typeof uri !== 'string') return false;
185
+ if (uri.startsWith('data:')) return false;
186
+ const normalized = uri.replace(/\\/g, '/');
187
+ if (normalized.startsWith('/') || /^[a-zA-Z]:\//.test(normalized)) return true;
188
+ const parts = normalized.split('/');
189
+ return parts.includes('..');
190
+ }
191
+
192
+ function validateBuffersAndAccessors(gltf, hasBinChunk, binChunkLength, errors, warnings) {
193
+ const buffers = Array.isArray(gltf.buffers) ? gltf.buffers : [];
194
+ const bufferViews = Array.isArray(gltf.bufferViews) ? gltf.bufferViews : [];
195
+ const accessors = Array.isArray(gltf.accessors) ? gltf.accessors : [];
196
+ const meshes = Array.isArray(gltf.meshes) ? gltf.meshes : [];
197
+ const externalResources = [];
198
+
199
+ for (let i = 0; i < buffers.length; i += 1) {
200
+ const buf = buffers[i];
201
+ if (!buf || typeof buf !== 'object') {
202
+ errors.push(`buffers[${i}] must be an object`);
203
+ continue;
204
+ }
205
+ if (!Number.isInteger(buf.byteLength) || buf.byteLength < 1) {
206
+ errors.push(`buffers[${i}].byteLength must be a positive integer (received ${JSON.stringify(buf.byteLength)})`);
207
+ continue;
208
+ }
209
+ if (buf.uri !== undefined) {
210
+ if (typeof buf.uri !== 'string' || buf.uri.trim().length === 0) {
211
+ errors.push(`buffers[${i}].uri must be a non-empty string when present`);
212
+ } else {
213
+ const externalFile = isExternalUri(buf.uri);
214
+ externalResources.push({
215
+ kind: 'buffer',
216
+ index: i,
217
+ uri: buf.uri,
218
+ isExternalFile: externalFile,
219
+ });
220
+ if (externalFile) {
221
+ warnings.push(
222
+ `buffers[${i}] references an external URI ('${buf.uri}'); self-contained GLB 2.0 web delivery should embed binary data in Chunk 1 (BIN)`,
223
+ );
224
+ if (hasUnsafeUriTraversal(buf.uri)) {
225
+ errors.push(`buffers[${i}].uri ('${buf.uri}') contains unsafe path traversal or absolute path`);
226
+ }
227
+ }
228
+ }
229
+ } else if (i === 0) {
230
+ if (!hasBinChunk) {
231
+ errors.push(`buffers[0] declares an embedded GLB buffer (${buf.byteLength} bytes) but Chunk 1 (BIN) is missing`);
232
+ } else if (binChunkLength < buf.byteLength) {
233
+ errors.push(
234
+ `buffers[0].byteLength (${buf.byteLength}) exceeds Chunk 1 (BIN) byteLength (${binChunkLength})`,
235
+ );
236
+ }
237
+ } else {
238
+ errors.push(
239
+ `buffers[${i}] omits 'uri'; in GLB 2.0 only buffers[0] may omit 'uri' to reference the embedded BIN chunk`,
240
+ );
241
+ }
242
+ }
243
+
244
+ for (let i = 0; i < bufferViews.length; i += 1) {
245
+ const bv = bufferViews[i];
246
+ if (!bv || typeof bv !== 'object') {
247
+ errors.push(`bufferViews[${i}] must be an object`);
248
+ continue;
249
+ }
250
+ const bufIdx = bv.buffer;
251
+ const byteOffset = bv.byteOffset ?? 0;
252
+ const byteLength = bv.byteLength;
253
+ const byteStride = bv.byteStride;
254
+
255
+ if (!Number.isInteger(bufIdx) || bufIdx < 0 || bufIdx >= buffers.length) {
256
+ errors.push(`bufferViews[${i}].buffer (${JSON.stringify(bufIdx)}) does not reference a valid buffer index`);
257
+ continue;
258
+ }
259
+ if (!Number.isInteger(byteOffset) || byteOffset < 0) {
260
+ errors.push(`bufferViews[${i}].byteOffset must be a non-negative integer`);
261
+ continue;
262
+ }
263
+ if (!Number.isInteger(byteLength) || byteLength < 1) {
264
+ errors.push(`bufferViews[${i}].byteLength must be a positive integer`);
265
+ continue;
266
+ }
267
+ if (byteStride !== undefined) {
268
+ if (!Number.isInteger(byteStride) || byteStride < 4 || byteStride > 252 || byteStride % 4 !== 0) {
269
+ errors.push(
270
+ `bufferViews[${i}].byteStride (${JSON.stringify(byteStride)}) must be a multiple of 4 in the range [4, 252]`,
271
+ );
272
+ }
273
+ }
274
+ const targetBuf = buffers[bufIdx];
275
+ if (targetBuf && Number.isInteger(targetBuf.byteLength) && byteOffset + byteLength > targetBuf.byteLength) {
276
+ errors.push(
277
+ `bufferViews[${i}] span (byteOffset ${byteOffset} + byteLength ${byteLength} = ${byteOffset + byteLength}) exceeds buffers[${bufIdx}].byteLength (${targetBuf.byteLength})`,
278
+ );
279
+ }
280
+ }
281
+
282
+ for (let i = 0; i < accessors.length; i += 1) {
283
+ const acc = accessors[i];
284
+ if (!acc || typeof acc !== 'object') {
285
+ errors.push(`accessors[${i}] must be an object`);
286
+ continue;
287
+ }
288
+ const compBytes = COMPONENT_TYPE_BYTE_SIZES[acc.componentType];
289
+ const compCount = ACCESSOR_TYPE_COMPONENT_COUNTS[acc.type];
290
+ if (!compBytes) {
291
+ errors.push(`accessors[${i}].componentType (${JSON.stringify(acc.componentType)}) is not a valid glTF 2.0 componentType`);
292
+ }
293
+ if (!compCount) {
294
+ errors.push(`accessors[${i}].type (${JSON.stringify(acc.type)}) is not a valid glTF 2.0 accessor type`);
295
+ }
296
+ if (!Number.isInteger(acc.count) || acc.count < 1) {
297
+ errors.push(`accessors[${i}].count (${JSON.stringify(acc.count)}) must be an integer >= 1`);
298
+ }
299
+
300
+ if (acc.bufferView !== undefined) {
301
+ if (!Number.isInteger(acc.bufferView) || acc.bufferView < 0 || acc.bufferView >= bufferViews.length) {
302
+ errors.push(`accessors[${i}].bufferView (${JSON.stringify(acc.bufferView)}) does not reference a valid bufferView`);
303
+ } else if (compBytes && compCount && Number.isInteger(acc.count) && acc.count >= 1) {
304
+ const bv = bufferViews[acc.bufferView];
305
+ const accOffset = acc.byteOffset ?? 0;
306
+ if (!Number.isInteger(accOffset) || accOffset < 0) {
307
+ errors.push(`accessors[${i}].byteOffset must be a non-negative integer`);
308
+ } else if (bv && Number.isInteger(bv.byteLength)) {
309
+ const elementSize = compBytes * compCount;
310
+ const stride = bv.byteStride ?? elementSize;
311
+ if (bv.byteStride !== undefined && bv.byteStride < elementSize) {
312
+ errors.push(
313
+ `accessors[${i}] element size (${elementSize} bytes) exceeds bufferViews[${acc.bufferView}].byteStride (${bv.byteStride})`,
314
+ );
315
+ }
316
+ const requiredBytes = accOffset + (acc.count - 1) * stride + elementSize;
317
+ if (requiredBytes > bv.byteLength) {
318
+ errors.push(
319
+ `accessors[${i}] byte span (${requiredBytes} bytes) exceeds bufferViews[${acc.bufferView}].byteLength (${bv.byteLength})`,
320
+ );
321
+ }
322
+ }
323
+ }
324
+ }
325
+
326
+ if (acc.sparse && typeof acc.sparse === 'object') {
327
+ const sCount = acc.sparse.count;
328
+ if (!Number.isInteger(sCount) || sCount < 1 || (Number.isInteger(acc.count) && sCount > acc.count)) {
329
+ errors.push(`accessors[${i}].sparse.count (${JSON.stringify(sCount)}) must be in [1, accessors[${i}].count]`);
330
+ }
331
+ const idxBv = acc.sparse.indices?.bufferView;
332
+ if (!Number.isInteger(idxBv) || idxBv < 0 || idxBv >= bufferViews.length) {
333
+ errors.push(`accessors[${i}].sparse.indices.bufferView (${JSON.stringify(idxBv)}) is out of range`);
334
+ }
335
+ const valBv = acc.sparse.values?.bufferView;
336
+ if (!Number.isInteger(valBv) || valBv < 0 || valBv >= bufferViews.length) {
337
+ errors.push(`accessors[${i}].sparse.values.bufferView (${JSON.stringify(valBv)}) is out of range`);
338
+ }
339
+ }
340
+ }
341
+
342
+ // Inspect POSITION accessors referenced by mesh primitives for bounding-box completeness
343
+ const positionAccessorIndices = new Set();
344
+ for (let mIdx = 0; mIdx < meshes.length; mIdx += 1) {
345
+ const mesh = meshes[mIdx];
346
+ const prims = Array.isArray(mesh?.primitives) ? mesh.primitives : [];
347
+ for (let pIdx = 0; pIdx < prims.length; pIdx += 1) {
348
+ const prim = prims[pIdx];
349
+ const posIdx = prim?.attributes?.POSITION;
350
+ if (Number.isInteger(posIdx)) {
351
+ positionAccessorIndices.add(posIdx);
352
+ if (posIdx < 0 || posIdx >= accessors.length) {
353
+ errors.push(`meshes[${mIdx}].primitives[${pIdx}].attributes.POSITION (${posIdx}) is out of range`);
354
+ }
355
+ }
356
+ if (prim?.attributes && typeof prim.attributes === 'object') {
357
+ for (const [attrName, attrIdx] of Object.entries(prim.attributes)) {
358
+ if (!Number.isInteger(attrIdx) || attrIdx < 0 || attrIdx >= accessors.length) {
359
+ if (attrName !== 'POSITION') {
360
+ errors.push(`meshes[${mIdx}].primitives[${pIdx}].attributes.${attrName} (${JSON.stringify(attrIdx)}) is out of range`);
361
+ }
362
+ }
363
+ }
364
+ }
365
+ if (prim?.indices !== undefined) {
366
+ if (!Number.isInteger(prim.indices) || prim.indices < 0 || prim.indices >= accessors.length) {
367
+ errors.push(`meshes[${mIdx}].primitives[${pIdx}].indices (${JSON.stringify(prim.indices)}) is out of range`);
368
+ } else {
369
+ const idxAcc = accessors[prim.indices];
370
+ if (idxAcc && idxAcc.type !== 'SCALAR') {
371
+ errors.push(`meshes[${mIdx}].primitives[${pIdx}].indices accessor must have type 'SCALAR' (received '${idxAcc.type}')`);
372
+ }
373
+ }
374
+ }
375
+ }
376
+ }
377
+
378
+ let missingPositionBoundsCount = 0;
379
+ const globalMin = [Infinity, Infinity, Infinity];
380
+ const globalMax = [-Infinity, -Infinity, -Infinity];
381
+ let hasValidBounds = false;
382
+
383
+ for (const posIdx of positionAccessorIndices) {
384
+ const acc = accessors[posIdx];
385
+ if (!acc || typeof acc !== 'object') continue;
386
+ const validMin =
387
+ Array.isArray(acc.min) &&
388
+ acc.min.length === 3 &&
389
+ acc.min.every((v) => typeof v === 'number' && Number.isFinite(v));
390
+ const validMax =
391
+ Array.isArray(acc.max) &&
392
+ acc.max.length === 3 &&
393
+ acc.max.every((v) => typeof v === 'number' && Number.isFinite(v));
394
+
395
+ if (!validMin || !validMax) {
396
+ missingPositionBoundsCount += 1;
397
+ warnings.push(
398
+ `accessors[${posIdx}] (POSITION) is missing required 3-element numeric min/max bounding box arrays`,
399
+ );
400
+ } else {
401
+ for (let axis = 0; axis < 3; axis += 1) {
402
+ if (acc.min[axis] > acc.max[axis]) {
403
+ errors.push(
404
+ `accessors[${posIdx}] (POSITION) has inverted bounds on axis ${axis}: min (${acc.min[axis]}) > max (${acc.max[axis]})`,
405
+ );
406
+ }
407
+ globalMin[axis] = Math.min(globalMin[axis], acc.min[axis]);
408
+ globalMax[axis] = Math.max(globalMax[axis], acc.max[axis]);
409
+ }
410
+ hasValidBounds = true;
411
+ }
412
+ }
413
+
414
+ const dimensions = hasValidBounds
415
+ ? [
416
+ Number((globalMax[0] - globalMin[0]).toFixed(6)),
417
+ Number((globalMax[1] - globalMin[1]).toFixed(6)),
418
+ Number((globalMax[2] - globalMin[2]).toFixed(6)),
419
+ ]
420
+ : null;
421
+ const center = hasValidBounds
422
+ ? [
423
+ Number(((globalMin[0] + globalMax[0]) / 2).toFixed(6)),
424
+ Number(((globalMin[1] + globalMax[1]) / 2).toFixed(6)),
425
+ Number(((globalMin[2] + globalMax[2]) / 2).toFixed(6)),
426
+ ]
427
+ : null;
428
+
429
+ return {
430
+ bounds: {
431
+ positionAccessorCount: positionAccessorIndices.size,
432
+ missingPositionBoundsCount,
433
+ sceneBoundingBox: hasValidBounds
434
+ ? {
435
+ min: globalMin,
436
+ max: globalMax,
437
+ dimensions,
438
+ center,
439
+ }
440
+ : { min: null, max: null, dimensions: null, center: null },
441
+ },
442
+ externalBufferResources: externalResources,
443
+ };
444
+ }
445
+
446
+ function validateAndSummarizeSceneGraph(gltf, errors, warnings) {
447
+ const scenes = Array.isArray(gltf.scenes) ? gltf.scenes : [];
448
+ const nodes = Array.isArray(gltf.nodes) ? gltf.nodes : [];
449
+ const meshes = Array.isArray(gltf.meshes) ? gltf.meshes : [];
450
+ const skins = Array.isArray(gltf.skins) ? gltf.skins : [];
451
+ const cameras = Array.isArray(gltf.cameras) ? gltf.cameras : [];
452
+ const accessors = Array.isArray(gltf.accessors) ? gltf.accessors : [];
453
+ const materials = Array.isArray(gltf.materials) ? gltf.materials : [];
454
+ const textures = Array.isArray(gltf.textures) ? gltf.textures : [];
455
+ const images = Array.isArray(gltf.images) ? gltf.images : [];
456
+ const samplers = Array.isArray(gltf.samplers) ? gltf.samplers : [];
457
+ const bufferViews = Array.isArray(gltf.bufferViews) ? gltf.bufferViews : [];
458
+ const animations = Array.isArray(gltf.animations) ? gltf.animations : [];
459
+
460
+ let defaultSceneIndex = null;
461
+ if (gltf.scene !== undefined) {
462
+ if (!Number.isInteger(gltf.scene) || gltf.scene < 0 || gltf.scene >= scenes.length) {
463
+ errors.push(`gltf.scene (${JSON.stringify(gltf.scene)}) does not reference a valid scene index`);
464
+ } else {
465
+ defaultSceneIndex = gltf.scene;
466
+ }
467
+ } else if (scenes.length > 0) {
468
+ defaultSceneIndex = 0;
469
+ }
470
+
471
+ const sceneSummaries = [];
472
+ const rootNodeIndexSet = new Set();
473
+ for (let sIdx = 0; sIdx < scenes.length; sIdx += 1) {
474
+ const sc = scenes[sIdx];
475
+ if (!sc || typeof sc !== 'object') {
476
+ errors.push(`scenes[${sIdx}] must be an object`);
477
+ continue;
478
+ }
479
+ const rootNodes = Array.isArray(sc.nodes) ? sc.nodes : [];
480
+ const validRoots = [];
481
+ for (let r = 0; r < rootNodes.length; r += 1) {
482
+ const nIdx = rootNodes[r];
483
+ if (!Number.isInteger(nIdx) || nIdx < 0 || nIdx >= nodes.length) {
484
+ errors.push(`scenes[${sIdx}].nodes[${r}] (${JSON.stringify(nIdx)}) does not reference a valid node index`);
485
+ } else {
486
+ validRoots.push(nIdx);
487
+ rootNodeIndexSet.add(nIdx);
488
+ }
489
+ }
490
+ sceneSummaries.push({
491
+ index: sIdx,
492
+ name: typeof sc.name === 'string' ? sc.name : null,
493
+ rootNodeIndices: validRoots,
494
+ });
495
+ }
496
+
497
+ // Validate nodes, parent uniqueness, and cycles
498
+ const parentByNode = new Map();
499
+ for (let nIdx = 0; nIdx < nodes.length; nIdx += 1) {
500
+ const node = nodes[nIdx];
501
+ if (!node || typeof node !== 'object') {
502
+ errors.push(`nodes[${nIdx}] must be an object`);
503
+ continue;
504
+ }
505
+ if (node.mesh !== undefined) {
506
+ if (!Number.isInteger(node.mesh) || node.mesh < 0 || node.mesh >= meshes.length) {
507
+ errors.push(`nodes[${nIdx}].mesh (${JSON.stringify(node.mesh)}) does not reference a valid mesh index`);
508
+ }
509
+ }
510
+ if (node.skin !== undefined) {
511
+ if (!Number.isInteger(node.skin) || node.skin < 0 || node.skin >= skins.length) {
512
+ errors.push(`nodes[${nIdx}].skin (${JSON.stringify(node.skin)}) does not reference a valid skin index`);
513
+ }
514
+ }
515
+ if (node.camera !== undefined) {
516
+ if (!Number.isInteger(node.camera) || node.camera < 0 || node.camera >= cameras.length) {
517
+ errors.push(`nodes[${nIdx}].camera (${JSON.stringify(node.camera)}) does not reference a valid camera index`);
518
+ }
519
+ }
520
+ if (node.matrix !== undefined && (node.translation !== undefined || node.rotation !== undefined || node.scale !== undefined)) {
521
+ errors.push(
522
+ `nodes[${nIdx}] specifies both 'matrix' and TRS ('translation'/'rotation'/'scale') properties, violating glTF 2.0 node transform rules`,
523
+ );
524
+ }
525
+ if (Array.isArray(node.children)) {
526
+ for (let c = 0; c < node.children.length; c += 1) {
527
+ const childIdx = node.children[c];
528
+ if (!Number.isInteger(childIdx) || childIdx < 0 || childIdx >= nodes.length) {
529
+ errors.push(`nodes[${nIdx}].children[${c}] (${JSON.stringify(childIdx)}) is out of range`);
530
+ } else if (childIdx === nIdx) {
531
+ errors.push(`nodes[${nIdx}] lists itself as a child (cycle detected)`);
532
+ } else {
533
+ if (parentByNode.has(childIdx)) {
534
+ errors.push(
535
+ `nodes[${childIdx}] has multiple parents (nodes[${parentByNode.get(childIdx)}] and nodes[${nIdx}]); glTF 2.0 node hierarchy must be a strict tree`,
536
+ );
537
+ } else {
538
+ parentByNode.set(childIdx, nIdx);
539
+ }
540
+ }
541
+ }
542
+ }
543
+ }
544
+
545
+ // Cycle detection via DFS coloring (0 = unvisited, 1 = visiting, 2 = visited)
546
+ const visitState = new Uint8Array(nodes.length);
547
+ function dfsCycleCheck(u) {
548
+ visitState[u] = 1;
549
+ const children = Array.isArray(nodes[u]?.children) ? nodes[u].children : [];
550
+ for (const v of children) {
551
+ if (!Number.isInteger(v) || v < 0 || v >= nodes.length || v === u) continue;
552
+ if (visitState[v] === 1) {
553
+ errors.push(`Cycle detected in glTF node hierarchy involving nodes[${u}] -> nodes[${v}]`);
554
+ } else if (visitState[v] === 0) {
555
+ dfsCycleCheck(v);
556
+ }
557
+ }
558
+ visitState[u] = 2;
559
+ }
560
+ for (let nIdx = 0; nIdx < nodes.length; nIdx += 1) {
561
+ if (visitState[nIdx] === 0) {
562
+ dfsCycleCheck(nIdx);
563
+ }
564
+ }
565
+
566
+ // Root node transforms
567
+ const rootIndicesToInspect =
568
+ rootNodeIndexSet.size > 0
569
+ ? [...rootNodeIndexSet]
570
+ : nodes.map((_, idx) => idx).filter((idx) => !parentByNode.has(idx));
571
+
572
+ const rootNodeTransforms = [];
573
+ for (const rIdx of rootIndicesToInspect) {
574
+ const node = nodes[rIdx];
575
+ if (!node || typeof node !== 'object') continue;
576
+ const translation =
577
+ Array.isArray(node.translation) && node.translation.length === 3 && node.translation.every((n) => typeof n === 'number')
578
+ ? node.translation
579
+ : [0, 0, 0];
580
+ const rotation =
581
+ Array.isArray(node.rotation) && node.rotation.length === 4 && node.rotation.every((n) => typeof n === 'number')
582
+ ? node.rotation
583
+ : [0, 0, 0, 1];
584
+ const scale =
585
+ Array.isArray(node.scale) && node.scale.length === 3 && node.scale.every((n) => typeof n === 'number')
586
+ ? node.scale
587
+ : [1, 1, 1];
588
+ const hasNonIdentityScale = scale.some((s) => Math.abs(s - 1) > 1e-5);
589
+ const hasNegativeScale = scale.some((s) => s < 0);
590
+ if (hasNegativeScale) {
591
+ warnings.push(
592
+ `Root node nodes[${rIdx}] ('${node.name || 'unnamed'}') has negative scale [${scale.join(', ')}], which can invert triangle winding and normal shading in web viewers`,
593
+ );
594
+ } else if (hasNonIdentityScale) {
595
+ warnings.push(
596
+ `Root node nodes[${rIdx}] ('${node.name || 'unnamed'}') has unapplied scale [${scale.join(', ')}]; apply scale in Blender (1 unit = 1m) before export when possible`,
597
+ );
598
+ }
599
+ rootNodeTransforms.push({
600
+ nodeIndex: rIdx,
601
+ name: typeof node.name === 'string' ? node.name : null,
602
+ translation,
603
+ rotation,
604
+ scale,
605
+ hasNonIdentityScale,
606
+ hasNegativeScale,
607
+ });
608
+ }
609
+
610
+ // Summarize meshes & primitives
611
+ let totalVertices = 0;
612
+ let totalTrianglesEstimate = 0;
613
+ const meshSummaries = [];
614
+
615
+ for (let mIdx = 0; mIdx < meshes.length; mIdx += 1) {
616
+ const mesh = meshes[mIdx];
617
+ if (!mesh || typeof mesh !== 'object') {
618
+ errors.push(`meshes[${mIdx}] must be an object`);
619
+ continue;
620
+ }
621
+ const prims = Array.isArray(mesh.primitives) ? mesh.primitives : [];
622
+ let meshVerts = 0;
623
+ let meshTris = 0;
624
+ const attrSet = new Set();
625
+ const matIdxSet = new Set();
626
+ let maxMorphTargets = 0;
627
+
628
+ for (let pIdx = 0; pIdx < prims.length; pIdx += 1) {
629
+ const prim = prims[pIdx];
630
+ if (!prim || typeof prim !== 'object') {
631
+ errors.push(`meshes[${mIdx}].primitives[${pIdx}] must be an object`);
632
+ continue;
633
+ }
634
+ const attrs = prim.attributes && typeof prim.attributes === 'object' ? prim.attributes : {};
635
+ for (const attrKey of Object.keys(attrs)) {
636
+ attrSet.add(attrKey);
637
+ }
638
+ const posIdx = attrs.POSITION;
639
+ let primVertCount = 0;
640
+ if (Number.isInteger(posIdx) && posIdx >= 0 && posIdx < accessors.length) {
641
+ primVertCount = Number.isInteger(accessors[posIdx]?.count) ? accessors[posIdx].count : 0;
642
+ }
643
+ meshVerts += primVertCount;
644
+
645
+ const mode = prim.mode ?? 4; // 4 = TRIANGLES
646
+ let indexOrVertCount = primVertCount;
647
+ if (Number.isInteger(prim.indices) && prim.indices >= 0 && prim.indices < accessors.length) {
648
+ indexOrVertCount = Number.isInteger(accessors[prim.indices]?.count)
649
+ ? accessors[prim.indices].count
650
+ : primVertCount;
651
+ }
652
+ if (mode === 4) {
653
+ meshTris += Math.floor(indexOrVertCount / 3);
654
+ } else if (mode === 5 || mode === 6) {
655
+ meshTris += Math.max(0, indexOrVertCount - 2);
656
+ }
657
+
658
+ if (prim.material !== undefined) {
659
+ if (!Number.isInteger(prim.material) || prim.material < 0 || prim.material >= materials.length) {
660
+ errors.push(
661
+ `meshes[${mIdx}].primitives[${pIdx}].material (${JSON.stringify(prim.material)}) does not reference a valid material index`,
662
+ );
663
+ } else {
664
+ matIdxSet.add(prim.material);
665
+ }
666
+ }
667
+
668
+ if (Array.isArray(prim.targets)) {
669
+ maxMorphTargets = Math.max(maxMorphTargets, prim.targets.length);
670
+ }
671
+ }
672
+
673
+ totalVertices += meshVerts;
674
+ totalTrianglesEstimate += meshTris;
675
+
676
+ meshSummaries.push({
677
+ index: mIdx,
678
+ name: typeof mesh.name === 'string' ? mesh.name : null,
679
+ primitiveCount: prims.length,
680
+ vertexCount: meshVerts,
681
+ triangleEstimate: meshTris,
682
+ attributes: [...attrSet].sort(),
683
+ materialIndices: [...matIdxSet].sort((a, b) => a - b),
684
+ morphTargetCount: maxMorphTargets,
685
+ });
686
+ }
687
+
688
+ // Validate images & textures
689
+ const externalImageResources = [];
690
+ for (let iIdx = 0; iIdx < images.length; iIdx += 1) {
691
+ const img = images[iIdx];
692
+ if (!img || typeof img !== 'object') {
693
+ errors.push(`images[${iIdx}] must be an object`);
694
+ continue;
695
+ }
696
+ if (img.bufferView !== undefined) {
697
+ if (!Number.isInteger(img.bufferView) || img.bufferView < 0 || img.bufferView >= bufferViews.length) {
698
+ errors.push(`images[${iIdx}].bufferView (${JSON.stringify(img.bufferView)}) does not reference a valid bufferView`);
699
+ }
700
+ if (typeof img.mimeType !== 'string' || img.mimeType.trim().length === 0) {
701
+ errors.push(`images[${iIdx}] uses bufferView (${img.bufferView}) but omits required 'mimeType'`);
702
+ }
703
+ } else if (typeof img.uri === 'string' && img.uri.trim().length > 0) {
704
+ const externalFile = isExternalUri(img.uri);
705
+ externalImageResources.push({
706
+ kind: 'image',
707
+ index: iIdx,
708
+ uri: img.uri,
709
+ isExternalFile: externalFile,
710
+ });
711
+ if (externalFile) {
712
+ warnings.push(
713
+ `images[${iIdx}] references an external texture URI ('${img.uri}'); external URIs can fail with 404 or CORS errors in web viewers unless packed into the GLB`,
714
+ );
715
+ if (hasUnsafeUriTraversal(img.uri)) {
716
+ errors.push(`images[${iIdx}].uri ('${img.uri}') contains unsafe path traversal or absolute path`);
717
+ }
718
+ }
719
+ } else {
720
+ errors.push(`images[${iIdx}] must specify either 'bufferView' (+ 'mimeType') or 'uri'`);
721
+ }
722
+ }
723
+
724
+ const textureSummaries = [];
725
+ for (let tIdx = 0; tIdx < textures.length; tIdx += 1) {
726
+ const tex = textures[tIdx];
727
+ if (!tex || typeof tex !== 'object') {
728
+ errors.push(`textures[${tIdx}] must be an object`);
729
+ continue;
730
+ }
731
+ let sourceImgIdx = tex.source ?? null;
732
+ let isExtensionSource = false;
733
+ if (sourceImgIdx === null && tex.extensions && typeof tex.extensions === 'object') {
734
+ const basisuSource = tex.extensions.KHR_texture_basisu?.source;
735
+ const webpSource = tex.extensions.EXT_texture_webp?.source;
736
+ if (Number.isInteger(basisuSource)) {
737
+ sourceImgIdx = basisuSource;
738
+ isExtensionSource = true;
739
+ } else if (Number.isInteger(webpSource)) {
740
+ sourceImgIdx = webpSource;
741
+ isExtensionSource = true;
742
+ }
743
+ }
744
+ if (sourceImgIdx !== null) {
745
+ if (!Number.isInteger(sourceImgIdx) || sourceImgIdx < 0 || sourceImgIdx >= images.length) {
746
+ errors.push(`textures[${tIdx}] image source (${JSON.stringify(sourceImgIdx)}) does not reference a valid image index`);
747
+ }
748
+ } else {
749
+ warnings.push(`textures[${tIdx}] does not reference a source image index`);
750
+ }
751
+
752
+ if (tex.sampler !== undefined) {
753
+ if (!Number.isInteger(tex.sampler) || tex.sampler < 0 || tex.sampler >= samplers.length) {
754
+ errors.push(`textures[${tIdx}].sampler (${JSON.stringify(tex.sampler)}) does not reference a valid sampler index`);
755
+ }
756
+ }
757
+
758
+ const imgObj = Number.isInteger(sourceImgIdx) && sourceImgIdx >= 0 && sourceImgIdx < images.length ? images[sourceImgIdx] : null;
759
+ let storageKind = 'missing';
760
+ let mimeType = typeof imgObj?.mimeType === 'string' ? imgObj.mimeType : null;
761
+ let uri = typeof imgObj?.uri === 'string' ? imgObj.uri : null;
762
+ if (imgObj) {
763
+ if (imgObj.bufferView !== undefined) {
764
+ storageKind = isExtensionSource ? 'extensionSource' : 'bufferView';
765
+ } else if (typeof imgObj.uri === 'string') {
766
+ if (imgObj.uri.trim().toLowerCase().startsWith('data:')) {
767
+ storageKind = 'dataUri';
768
+ if (!mimeType) {
769
+ const m = imgObj.uri.match(/^data:([^;,]+)/i);
770
+ if (m) mimeType = m[1];
771
+ }
772
+ } else {
773
+ storageKind = 'externalUri';
774
+ }
775
+ }
776
+ }
777
+
778
+ textureSummaries.push({
779
+ index: tIdx,
780
+ name: typeof tex.name === 'string' ? tex.name : null,
781
+ sourceImageIndex: Number.isInteger(sourceImgIdx) ? sourceImgIdx : null,
782
+ samplerIndex: Number.isInteger(tex.sampler) ? tex.sampler : null,
783
+ mimeType,
784
+ storageKind,
785
+ uri: storageKind === 'externalUri' ? uri : null,
786
+ });
787
+ }
788
+
789
+ // Validate and summarize materials
790
+ const materialSummaries = [];
791
+ for (let matIdx = 0; matIdx < materials.length; matIdx += 1) {
792
+ const mat = materials[matIdx];
793
+ if (!mat || typeof mat !== 'object') {
794
+ errors.push(`materials[${matIdx}] must be an object`);
795
+ continue;
796
+ }
797
+ const alphaMode = mat.alphaMode ?? 'OPAQUE';
798
+ if (!VALID_ALPHA_MODES.has(alphaMode)) {
799
+ errors.push(`materials[${matIdx}].alphaMode ('${alphaMode}') must be one of OPAQUE, MASK, BLEND`);
800
+ }
801
+ const pbr = mat.pbrMetallicRoughness && typeof mat.pbrMetallicRoughness === 'object' ? mat.pbrMetallicRoughness : {};
802
+
803
+ const checkTexRef = (texInfo, label) => {
804
+ if (!texInfo || typeof texInfo !== 'object') return false;
805
+ if (!Number.isInteger(texInfo.index) || texInfo.index < 0 || texInfo.index >= textures.length) {
806
+ errors.push(`materials[${matIdx}].${label}.index (${JSON.stringify(texInfo.index)}) does not reference a valid texture`);
807
+ return false;
808
+ }
809
+ return true;
810
+ };
811
+
812
+ const hasBaseColorTexture = checkTexRef(pbr.baseColorTexture, 'pbrMetallicRoughness.baseColorTexture');
813
+ const hasMetallicRoughnessTexture = checkTexRef(
814
+ pbr.metallicRoughnessTexture,
815
+ 'pbrMetallicRoughness.metallicRoughnessTexture',
816
+ );
817
+ const hasNormalTexture = checkTexRef(mat.normalTexture, 'normalTexture');
818
+ const hasOcclusionTexture = checkTexRef(mat.occlusionTexture, 'occlusionTexture');
819
+ const hasEmissiveTexture = checkTexRef(mat.emissiveTexture, 'emissiveTexture');
820
+
821
+ const baseColorFactor =
822
+ Array.isArray(pbr.baseColorFactor) &&
823
+ pbr.baseColorFactor.length === 4 &&
824
+ pbr.baseColorFactor.every((n) => typeof n === 'number')
825
+ ? pbr.baseColorFactor
826
+ : [1, 1, 1, 1];
827
+ const metallicFactor =
828
+ typeof pbr.metallicFactor === 'number' && pbr.metallicFactor >= 0 && pbr.metallicFactor <= 1
829
+ ? pbr.metallicFactor
830
+ : 1;
831
+ const roughnessFactor =
832
+ typeof pbr.roughnessFactor === 'number' && pbr.roughnessFactor >= 0 && pbr.roughnessFactor <= 1
833
+ ? pbr.roughnessFactor
834
+ : 1;
835
+ const matExtensions =
836
+ mat.extensions && typeof mat.extensions === 'object' && !Array.isArray(mat.extensions)
837
+ ? Object.keys(mat.extensions).sort()
838
+ : [];
839
+
840
+ materialSummaries.push({
841
+ index: matIdx,
842
+ name: typeof mat.name === 'string' ? mat.name : null,
843
+ alphaMode: VALID_ALPHA_MODES.has(alphaMode) ? alphaMode : 'OPAQUE',
844
+ doubleSided: Boolean(mat.doubleSided),
845
+ unlit: matExtensions.includes('KHR_materials_unlit'),
846
+ hasBaseColorTexture,
847
+ hasMetallicRoughnessTexture,
848
+ hasNormalTexture,
849
+ hasOcclusionTexture,
850
+ hasEmissiveTexture,
851
+ baseColorFactor,
852
+ metallicFactor,
853
+ roughnessFactor,
854
+ extensions: matExtensions,
855
+ });
856
+ }
857
+
858
+ // Validate and summarize animations
859
+ const animationSummaries = [];
860
+ for (let aIdx = 0; aIdx < animations.length; aIdx += 1) {
861
+ const anim = animations[aIdx];
862
+ if (!anim || typeof anim !== 'object') {
863
+ errors.push(`animations[${aIdx}] must be an object`);
864
+ continue;
865
+ }
866
+ const animChannels = Array.isArray(anim.channels) ? anim.channels : [];
867
+ const animSamplers = Array.isArray(anim.samplers) ? anim.samplers : [];
868
+ const targetPathsSet = new Set();
869
+ const interpSet = new Set();
870
+ let maxDuration = null;
871
+
872
+ for (let sIdx = 0; sIdx < animSamplers.length; sIdx += 1) {
873
+ const samp = animSamplers[sIdx];
874
+ if (!samp || typeof samp !== 'object') {
875
+ errors.push(`animations[${aIdx}].samplers[${sIdx}] must be an object`);
876
+ continue;
877
+ }
878
+ const interp = samp.interpolation ?? 'LINEAR';
879
+ if (!VALID_INTERPOLATIONS.has(interp)) {
880
+ errors.push(`animations[${aIdx}].samplers[${sIdx}].interpolation ('${interp}') is invalid`);
881
+ } else {
882
+ interpSet.add(interp);
883
+ }
884
+ if (!Number.isInteger(samp.input) || samp.input < 0 || samp.input >= accessors.length) {
885
+ errors.push(`animations[${aIdx}].samplers[${sIdx}].input (${JSON.stringify(samp.input)}) does not reference a valid accessor`);
886
+ } else {
887
+ const inputAcc = accessors[samp.input];
888
+ if (Array.isArray(inputAcc?.max) && typeof inputAcc.max[0] === 'number' && Number.isFinite(inputAcc.max[0]) && inputAcc.max[0] >= 0) {
889
+ maxDuration = maxDuration === null ? inputAcc.max[0] : Math.max(maxDuration, inputAcc.max[0]);
890
+ }
891
+ }
892
+ if (!Number.isInteger(samp.output) || samp.output < 0 || samp.output >= accessors.length) {
893
+ errors.push(`animations[${aIdx}].samplers[${sIdx}].output (${JSON.stringify(samp.output)}) does not reference a valid accessor`);
894
+ }
895
+ }
896
+
897
+ for (let cIdx = 0; cIdx < animChannels.length; cIdx += 1) {
898
+ const ch = animChannels[cIdx];
899
+ if (!ch || typeof ch !== 'object') {
900
+ errors.push(`animations[${aIdx}].channels[${cIdx}] must be an object`);
901
+ continue;
902
+ }
903
+ if (!Number.isInteger(ch.sampler) || ch.sampler < 0 || ch.sampler >= animSamplers.length) {
904
+ errors.push(`animations[${aIdx}].channels[${cIdx}].sampler (${JSON.stringify(ch.sampler)}) does not reference a valid animation sampler`);
905
+ }
906
+ const target = ch.target;
907
+ if (!target || typeof target !== 'object') {
908
+ errors.push(`animations[${aIdx}].channels[${cIdx}].target must be an object`);
909
+ } else {
910
+ if (target.node !== undefined && (!Number.isInteger(target.node) || target.node < 0 || target.node >= nodes.length)) {
911
+ errors.push(`animations[${aIdx}].channels[${cIdx}].target.node (${JSON.stringify(target.node)}) does not reference a valid node`);
912
+ }
913
+ if (!VALID_ANIMATION_PATHS.has(target.path)) {
914
+ errors.push(`animations[${aIdx}].channels[${cIdx}].target.path ('${target.path}') must be translation, rotation, scale, or weights`);
915
+ } else {
916
+ targetPathsSet.add(target.path);
917
+ }
918
+ }
919
+ }
920
+
921
+ animationSummaries.push({
922
+ index: aIdx,
923
+ name: typeof anim.name === 'string' ? anim.name : null,
924
+ channelCount: animChannels.length,
925
+ samplerCount: animSamplers.length,
926
+ durationSeconds: maxDuration !== null ? Number(maxDuration.toFixed(6)) : null,
927
+ targetPaths: [...targetPathsSet].sort(),
928
+ interpolationModes: [...interpSet].sort(),
929
+ });
930
+ }
931
+
932
+ // Validate skins
933
+ for (let skIdx = 0; skIdx < skins.length; skIdx += 1) {
934
+ const skin = skins[skIdx];
935
+ if (!skin || typeof skin !== 'object') {
936
+ errors.push(`skins[${skIdx}] must be an object`);
937
+ continue;
938
+ }
939
+ if (!Array.isArray(skin.joints) || skin.joints.length === 0) {
940
+ errors.push(`skins[${skIdx}].joints must be a non-empty array of node indices`);
941
+ } else {
942
+ for (let j = 0; j < skin.joints.length; j += 1) {
943
+ const jNode = skin.joints[j];
944
+ if (!Number.isInteger(jNode) || jNode < 0 || jNode >= nodes.length) {
945
+ errors.push(`skins[${skIdx}].joints[${j}] (${JSON.stringify(jNode)}) does not reference a valid node index`);
946
+ }
947
+ }
948
+ }
949
+ if (skin.inverseBindMatrices !== undefined) {
950
+ if (!Number.isInteger(skin.inverseBindMatrices) || skin.inverseBindMatrices < 0 || skin.inverseBindMatrices >= accessors.length) {
951
+ errors.push(`skins[${skIdx}].inverseBindMatrices (${JSON.stringify(skin.inverseBindMatrices)}) does not reference a valid accessor`);
952
+ }
953
+ }
954
+ }
955
+
956
+ return {
957
+ defaultSceneIndex,
958
+ scenes: sceneSummaries,
959
+ meshes: meshSummaries,
960
+ materials: materialSummaries,
961
+ textures: textureSummaries,
962
+ animations: animationSummaries,
963
+ rootNodeTransforms,
964
+ totalVertices,
965
+ totalTrianglesEstimate,
966
+ externalImageResources,
967
+ };
968
+ }
969
+
970
+ export async function runKhronosGltfValidator(buffer, { validatorModuleLoader } = {}) {
971
+ try {
972
+ const loader =
973
+ validatorModuleLoader ||
974
+ (async () => {
975
+ return import('gltf-validator');
976
+ });
977
+ const mod = await loader();
978
+ const validateBytes = mod?.validateBytes || mod?.default?.validateBytes;
979
+ if (typeof validateBytes !== 'function') {
980
+ return {
981
+ requested: true,
982
+ status: 'error',
983
+ tool: 'gltf-validator',
984
+ message: 'Loaded gltf-validator module does not export validateBytes(Uint8Array)',
985
+ issues: null,
986
+ };
987
+ }
988
+ const report = await validateBytes(new Uint8Array(buffer));
989
+ const numErrors = report?.issues?.numErrors ?? 0;
990
+ const numWarnings = report?.issues?.numWarnings ?? 0;
991
+ return {
992
+ requested: true,
993
+ status: numErrors === 0 ? 'passed' : 'failed',
994
+ tool: 'gltf-validator',
995
+ toolVersion: report?.validatorVersion || null,
996
+ message:
997
+ numErrors === 0
998
+ ? `Khronos gltf-validator passed (0 errors, ${numWarnings} warnings)`
999
+ : `Khronos gltf-validator reported ${numErrors} error(s) and ${numWarnings} warning(s)`,
1000
+ issues: {
1001
+ numErrors,
1002
+ numWarnings,
1003
+ numInfos: report?.issues?.numInfos ?? 0,
1004
+ numHints: report?.issues?.numHints ?? 0,
1005
+ messages: Array.isArray(report?.issues?.messages) ? report.issues.messages : [],
1006
+ },
1007
+ };
1008
+ } catch (err) {
1009
+ const code = err?.code || '';
1010
+ const msg = err?.message || String(err);
1011
+ if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND' || /Cannot find package 'gltf-validator'/i.test(msg)) {
1012
+ return {
1013
+ requested: true,
1014
+ status: 'unavailable',
1015
+ tool: 'gltf-validator',
1016
+ message:
1017
+ 'Optional Khronos gltf-validator package is not installed in this environment; container-level GLB 2.0 inspection completed via built-in Node parser.',
1018
+ issues: null,
1019
+ };
1020
+ }
1021
+ return {
1022
+ requested: true,
1023
+ status: 'error',
1024
+ tool: 'gltf-validator',
1025
+ message: `Khronos gltf-validator execution failed: ${msg}`,
1026
+ issues: null,
1027
+ };
1028
+ }
1029
+ }
1030
+
1031
+ export function inspectGlbBuffer(buffer, { strictPositionBounds = false } = {}) {
1032
+ const errors = [];
1033
+ const warnings = [];
1034
+
1035
+ if (!Buffer.isBuffer(buffer)) {
1036
+ return {
1037
+ valid: false,
1038
+ errors: ['Input must be a Node.js Buffer'],
1039
+ warnings: [],
1040
+ byteSize: 0,
1041
+ sha256: null,
1042
+ header: null,
1043
+ chunks: null,
1044
+ counts: null,
1045
+ extensions: null,
1046
+ bounds: null,
1047
+ details: null,
1048
+ validationTiers: {
1049
+ containerStructural: {
1050
+ status: 'Failed',
1051
+ tool: 'scripts/inspect-glb.mjs',
1052
+ summary: 'Input is not a valid Node.js Buffer.',
1053
+ },
1054
+ gltfSpecification: {
1055
+ status: 'Not Run',
1056
+ tool: 'gltf-validator',
1057
+ summary: 'Khronos gltf-validator not executed.',
1058
+ },
1059
+ visualQuality: {
1060
+ status: 'Not Run',
1061
+ summary: 'Visual quality cannot be verified from binary container inspection.',
1062
+ },
1063
+ liveRuntime: {
1064
+ status: 'Not Run',
1065
+ summary: 'Live Blender runtime execution cannot be verified from a binary file.',
1066
+ },
1067
+ },
1068
+ truthBoundary: {
1069
+ verificationScope: 'container-structure-only',
1070
+ provesContainerIntegrity: false,
1071
+ provesVisualCorrectness: false,
1072
+ provesBlenderRuntimeExecution: false,
1073
+ disclaimer: CONTAINER_TRUTH_DISCLAIMER,
1074
+ },
1075
+ };
1076
+ }
1077
+
1078
+ const byteSize = buffer.byteLength;
1079
+ const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
1080
+
1081
+ if (byteSize === 0) {
1082
+ errors.push('GLB buffer is empty (0 bytes)');
1083
+ } else if (byteSize < 20) {
1084
+ errors.push(`GLB buffer is truncated (${byteSize} bytes; minimum GLB 2.0 header + JSON chunk header is 20 bytes)`);
1085
+ }
1086
+
1087
+ let magic = null;
1088
+ let version = null;
1089
+ let declaredByteLength = null;
1090
+
1091
+ if (byteSize >= 12) {
1092
+ magic = buffer.readUInt32LE(0);
1093
+ version = buffer.readUInt32LE(4);
1094
+ declaredByteLength = buffer.readUInt32LE(8);
1095
+
1096
+ if (magic !== GLB_MAGIC) {
1097
+ errors.push(
1098
+ `Invalid GLB magic header: expected 0x46546c67 ('glTF'), received 0x${magic.toString(16).padStart(8, '0')}`,
1099
+ );
1100
+ }
1101
+ if (version !== GLB_VERSION_2) {
1102
+ errors.push(`Unsupported GLB container version: expected 2, received ${version}`);
1103
+ }
1104
+ if (declaredByteLength !== byteSize) {
1105
+ errors.push(
1106
+ `GLB header declared length (${declaredByteLength} bytes) does not match actual file size (${byteSize} bytes)`,
1107
+ );
1108
+ }
1109
+ }
1110
+
1111
+ let jsonChunkLength = null;
1112
+ let jsonChunkType = null;
1113
+ let hasBinChunk = false;
1114
+ let binChunkLength = 0;
1115
+ let gltf = null;
1116
+
1117
+ if (byteSize >= 20 && errors.length === 0) {
1118
+ jsonChunkLength = buffer.readUInt32LE(12);
1119
+ jsonChunkType = buffer.readUInt32LE(16);
1120
+
1121
+ if (jsonChunkType !== GLB_CHUNK_TYPE_JSON) {
1122
+ errors.push(
1123
+ `Chunk 0 must have type JSON (0x4e4f534a), received 0x${jsonChunkType.toString(16).padStart(8, '0')}`,
1124
+ );
1125
+ }
1126
+ if (jsonChunkLength === 0) {
1127
+ errors.push('Chunk 0 (JSON) has 0 byte length');
1128
+ } else if (jsonChunkLength % 4 !== 0) {
1129
+ errors.push(`Chunk 0 (JSON) length (${jsonChunkLength}) violates 4-byte alignment requirement`);
1130
+ }
1131
+
1132
+ const jsonEnd = 20 + jsonChunkLength;
1133
+ if (jsonEnd > byteSize) {
1134
+ errors.push(
1135
+ `Chunk 0 (JSON) extends past end of file (offset 20 + length ${jsonChunkLength} = ${jsonEnd} > ${byteSize})`,
1136
+ );
1137
+ } else if (jsonChunkLength > 0 && jsonChunkType === GLB_CHUNK_TYPE_JSON) {
1138
+ const jsonBytes = buffer.subarray(20, jsonEnd);
1139
+
1140
+ // Verify trailing padding bytes after the closing '}' are spaces (0x20), not null bytes or garbage
1141
+ if (jsonBytes.includes(0x00)) {
1142
+ errors.push('Chunk 0 (JSON) contains forbidden NUL (0x00) padding bytes; glTF 2.0 requires ASCII space (0x20) padding');
1143
+ }
1144
+
1145
+ const jsonText = jsonBytes.toString('utf8');
1146
+ try {
1147
+ const parsed = JSON.parse(jsonText);
1148
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
1149
+ errors.push('Chunk 0 (JSON) root must be a JSON object');
1150
+ } else {
1151
+ gltf = parsed;
1152
+ }
1153
+ } catch (err) {
1154
+ errors.push(`Chunk 0 (JSON) contains malformed JSON: ${err.message}`);
1155
+ }
1156
+ }
1157
+
1158
+ // Inspect optional Chunk 1 (BIN)
1159
+ if (jsonEnd < byteSize) {
1160
+ const remaining = byteSize - jsonEnd;
1161
+ if (remaining < 8) {
1162
+ errors.push(`Truncated Chunk 1 header at offset ${jsonEnd} (${remaining} bytes remaining, need at least 8)`);
1163
+ } else {
1164
+ hasBinChunk = true;
1165
+ binChunkLength = buffer.readUInt32LE(jsonEnd);
1166
+ const binChunkType = buffer.readUInt32LE(jsonEnd + 4);
1167
+ if (binChunkType !== GLB_CHUNK_TYPE_BIN) {
1168
+ errors.push(
1169
+ `Chunk 1 must have type BIN\\0 (0x004e4942), received 0x${binChunkType.toString(16).padStart(8, '0')}`,
1170
+ );
1171
+ }
1172
+ if (binChunkLength % 4 !== 0) {
1173
+ errors.push(`Chunk 1 (BIN) length (${binChunkLength}) violates 4-byte alignment requirement`);
1174
+ }
1175
+ const binEnd = jsonEnd + 8 + binChunkLength;
1176
+ if (binEnd > byteSize) {
1177
+ errors.push(
1178
+ `Chunk 1 (BIN) extends past end of file (offset ${jsonEnd + 8} + length ${binChunkLength} = ${binEnd} > ${byteSize})`,
1179
+ );
1180
+ } else if (binEnd < byteSize) {
1181
+ errors.push(
1182
+ `Unexpected trailing bytes after Chunk 1 (BIN): expected EOF at ${binEnd}, found ${byteSize - binEnd} extra byte(s)`,
1183
+ );
1184
+ }
1185
+ }
1186
+ }
1187
+ }
1188
+
1189
+ let counts = null;
1190
+ let extensions = null;
1191
+ let bounds = null;
1192
+ let details = null;
1193
+
1194
+ if (gltf) {
1195
+ const assetVersion = gltf.asset?.version;
1196
+ if (typeof assetVersion !== 'string' || !/^2\.0$/.test(assetVersion)) {
1197
+ errors.push(
1198
+ `glTF asset.version must be "2.0" (received ${JSON.stringify(assetVersion)})`,
1199
+ );
1200
+ }
1201
+
1202
+ const meshes = Array.isArray(gltf.meshes) ? gltf.meshes : [];
1203
+ const primitiveCount = meshes.reduce(
1204
+ (sum, m) => sum + (Array.isArray(m?.primitives) ? m.primitives.length : 0),
1205
+ 0,
1206
+ );
1207
+
1208
+ const { bounds: computedBounds, externalBufferResources } = validateBuffersAndAccessors(
1209
+ gltf,
1210
+ hasBinChunk,
1211
+ binChunkLength,
1212
+ errors,
1213
+ warnings,
1214
+ );
1215
+ bounds = computedBounds;
1216
+
1217
+ const sceneSummary = validateAndSummarizeSceneGraph(gltf, errors, warnings);
1218
+
1219
+ counts = {
1220
+ scenes: Array.isArray(gltf.scenes) ? gltf.scenes.length : 0,
1221
+ nodes: Array.isArray(gltf.nodes) ? gltf.nodes.length : 0,
1222
+ meshes: meshes.length,
1223
+ primitives: primitiveCount,
1224
+ vertices: sceneSummary.totalVertices,
1225
+ trianglesEstimate: sceneSummary.totalTrianglesEstimate,
1226
+ materials: Array.isArray(gltf.materials) ? gltf.materials.length : 0,
1227
+ textures: Array.isArray(gltf.textures) ? gltf.textures.length : 0,
1228
+ images: Array.isArray(gltf.images) ? gltf.images.length : 0,
1229
+ samplers: Array.isArray(gltf.samplers) ? gltf.samplers.length : 0,
1230
+ animations: Array.isArray(gltf.animations) ? gltf.animations.length : 0,
1231
+ skins: Array.isArray(gltf.skins) ? gltf.skins.length : 0,
1232
+ accessors: Array.isArray(gltf.accessors) ? gltf.accessors.length : 0,
1233
+ bufferViews: Array.isArray(gltf.bufferViews) ? gltf.bufferViews.length : 0,
1234
+ buffers: Array.isArray(gltf.buffers) ? gltf.buffers.length : 0,
1235
+ };
1236
+
1237
+ const extensionsUsed = Array.isArray(gltf.extensionsUsed) ? [...new Set(gltf.extensionsUsed)] : [];
1238
+ const extensionsRequired = Array.isArray(gltf.extensionsRequired) ? [...new Set(gltf.extensionsRequired)] : [];
1239
+ const actuallyUsedExtensions = [...collectUsedExtensionsInObject(gltf)].sort();
1240
+ const undeclaredExtensionsFound = actuallyUsedExtensions.filter(
1241
+ (ext) => !extensionsUsed.includes(ext),
1242
+ );
1243
+
1244
+ for (const reqExt of extensionsRequired) {
1245
+ if (!extensionsUsed.includes(reqExt)) {
1246
+ errors.push(`extensionsRequired entry '${reqExt}' is missing from extensionsUsed`);
1247
+ }
1248
+ }
1249
+ for (const undeclaredExt of undeclaredExtensionsFound) {
1250
+ errors.push(
1251
+ `Extension '${undeclaredExt}' is used in the glTF JSON payload but is not declared in extensionsUsed`,
1252
+ );
1253
+ }
1254
+
1255
+ const allKnownExts = new Set([...extensionsUsed, ...extensionsRequired, ...actuallyUsedExtensions]);
1256
+ const dracoUsed = allKnownExts.has('KHR_draco_mesh_compression');
1257
+ const dracoRequired = extensionsRequired.includes('KHR_draco_mesh_compression');
1258
+ const meshoptUsed = allKnownExts.has('EXT_meshopt_compression');
1259
+ const meshoptRequired = extensionsRequired.includes('EXT_meshopt_compression');
1260
+ const ktx2Used = allKnownExts.has('KHR_texture_basisu');
1261
+ const ktx2Required = extensionsRequired.includes('KHR_texture_basisu');
1262
+ const webpUsed = allKnownExts.has('EXT_texture_webp');
1263
+ const webpRequired = extensionsRequired.includes('EXT_texture_webp');
1264
+
1265
+ extensions = {
1266
+ extensionsUsed,
1267
+ extensionsRequired,
1268
+ undeclaredExtensionsFound,
1269
+ compression: {
1270
+ draco: {
1271
+ used: dracoUsed,
1272
+ required: dracoRequired,
1273
+ decoderRequired: dracoUsed || dracoRequired,
1274
+ },
1275
+ meshopt: {
1276
+ used: meshoptUsed,
1277
+ required: meshoptRequired,
1278
+ decoderRequired: meshoptUsed || meshoptRequired,
1279
+ },
1280
+ ktx2BasisU: {
1281
+ used: ktx2Used,
1282
+ required: ktx2Required,
1283
+ transcoderRequired: ktx2Used || ktx2Required,
1284
+ },
1285
+ webp: {
1286
+ used: webpUsed,
1287
+ required: webpRequired,
1288
+ },
1289
+ },
1290
+ };
1291
+
1292
+ details = {
1293
+ defaultSceneIndex: sceneSummary.defaultSceneIndex,
1294
+ scenes: sceneSummary.scenes,
1295
+ meshes: sceneSummary.meshes,
1296
+ materials: sceneSummary.materials,
1297
+ textures: sceneSummary.textures,
1298
+ animations: sceneSummary.animations,
1299
+ rootNodeTransforms: sceneSummary.rootNodeTransforms,
1300
+ externalResources: [...externalBufferResources, ...sceneSummary.externalImageResources],
1301
+ extras: gltf.extras && typeof gltf.extras === 'object' ? gltf.extras : null,
1302
+ };
1303
+
1304
+ if (strictPositionBounds && bounds.missingPositionBoundsCount > 0) {
1305
+ errors.push(
1306
+ `${bounds.missingPositionBoundsCount} POSITION accessor(s) omit required min/max bounds under strictPositionBounds`,
1307
+ );
1308
+ }
1309
+ }
1310
+
1311
+ const valid = errors.length === 0;
1312
+ const structuralStatus = !valid ? 'Failed' : warnings.length > 0 ? 'Warn' : 'Passed';
1313
+
1314
+ return {
1315
+ valid,
1316
+ errors,
1317
+ warnings,
1318
+ byteSize,
1319
+ sha256,
1320
+ header:
1321
+ magic !== null
1322
+ ? {
1323
+ magic: magic === GLB_MAGIC ? 'glTF' : 'INVALID',
1324
+ magicHex: `0x${magic.toString(16).padStart(8, '0')}`,
1325
+ version,
1326
+ declaredByteLength,
1327
+ }
1328
+ : null,
1329
+ chunks:
1330
+ jsonChunkLength !== null
1331
+ ? {
1332
+ jsonChunkLength,
1333
+ hasBinChunk,
1334
+ binChunkLength,
1335
+ }
1336
+ : null,
1337
+ asset: gltf?.asset || null,
1338
+ counts,
1339
+ extensions,
1340
+ bounds,
1341
+ details,
1342
+ khronosValidator: {
1343
+ requested: false,
1344
+ status: 'not_run',
1345
+ tool: 'gltf-validator',
1346
+ message: 'Khronos gltf-validator not requested (pass --khronos to attempt validation)',
1347
+ issues: null,
1348
+ },
1349
+ validationTiers: {
1350
+ containerStructural: {
1351
+ status: structuralStatus,
1352
+ tool: 'scripts/inspect-glb.mjs',
1353
+ errorCount: errors.length,
1354
+ warningCount: warnings.length,
1355
+ summary: valid
1356
+ ? `Binary GLB 2.0 container structure passed (${warnings.length} warning(s)).`
1357
+ : `Binary GLB 2.0 container structure failed with ${errors.length} error(s).`,
1358
+ },
1359
+ gltfSpecification: {
1360
+ status: 'Not Run',
1361
+ tool: 'gltf-validator',
1362
+ summary:
1363
+ 'Upstream Khronos gltf-validator was not executed. Built-in inspection checks GLB 2.0 container structure and cross-references, not the full Khronos glTF 2.0 specification.',
1364
+ },
1365
+ visualQuality: {
1366
+ status: 'Not Run',
1367
+ summary:
1368
+ 'Visual framing, lighting balance, silhouette readability, and material appearance are not verifiable from binary container inspection.',
1369
+ },
1370
+ liveRuntime: {
1371
+ status: 'Not Run',
1372
+ summary:
1373
+ 'Live Blender runtime execution and current-run provenance are not established by static GLB file inspection.',
1374
+ },
1375
+ },
1376
+ truthBoundary: {
1377
+ verificationScope: 'container-structure-only',
1378
+ provesContainerIntegrity: valid,
1379
+ provesFullGltfSpecCompliance: false,
1380
+ provesVisualCorrectness: false,
1381
+ provesBlenderRuntimeExecution: false,
1382
+ disclaimer: CONTAINER_TRUTH_DISCLAIMER,
1383
+ },
1384
+ };
1385
+ }
1386
+
1387
+ export async function inspectGlbFile(
1388
+ filePath,
1389
+ { runKhronos = false, strictPositionBounds = false, validatorModuleLoader } = {},
1390
+ ) {
1391
+ const resolved = path.resolve(filePath);
1392
+ if (!fs.existsSync(resolved)) {
1393
+ return {
1394
+ valid: false,
1395
+ filePath: resolved,
1396
+ errors: [`GLB file does not exist: ${filePath}`],
1397
+ warnings: [],
1398
+ byteSize: 0,
1399
+ sha256: null,
1400
+ header: null,
1401
+ chunks: null,
1402
+ counts: null,
1403
+ extensions: null,
1404
+ bounds: null,
1405
+ details: null,
1406
+ khronosValidator: {
1407
+ requested: Boolean(runKhronos),
1408
+ status: 'not_run',
1409
+ tool: 'gltf-validator',
1410
+ message: 'Skipped because file does not exist',
1411
+ issues: null,
1412
+ },
1413
+ validationTiers: {
1414
+ containerStructural: {
1415
+ status: 'Failed',
1416
+ tool: 'scripts/inspect-glb.mjs',
1417
+ errorCount: 1,
1418
+ warningCount: 0,
1419
+ summary: `GLB file does not exist: ${filePath}`,
1420
+ },
1421
+ gltfSpecification: {
1422
+ status: 'Not Run',
1423
+ tool: 'gltf-validator',
1424
+ summary: 'Skipped because file does not exist.',
1425
+ },
1426
+ visualQuality: {
1427
+ status: 'Not Run',
1428
+ summary: 'Visual quality cannot be verified without a valid rendered artifact.',
1429
+ },
1430
+ liveRuntime: {
1431
+ status: 'Not Run',
1432
+ summary: 'Live Blender runtime execution was not run.',
1433
+ },
1434
+ },
1435
+ truthBoundary: {
1436
+ verificationScope: 'container-structure-only',
1437
+ provesContainerIntegrity: false,
1438
+ provesFullGltfSpecCompliance: false,
1439
+ provesVisualCorrectness: false,
1440
+ provesBlenderRuntimeExecution: false,
1441
+ disclaimer: CONTAINER_TRUTH_DISCLAIMER,
1442
+ },
1443
+ };
1444
+ }
1445
+
1446
+ let lstat;
1447
+ try {
1448
+ lstat = fs.lstatSync(resolved);
1449
+ } catch (err) {
1450
+ return {
1451
+ valid: false,
1452
+ filePath: resolved,
1453
+ errors: [`Unable to stat GLB path: ${err.message}`],
1454
+ warnings: [],
1455
+ byteSize: 0,
1456
+ sha256: null,
1457
+ header: null,
1458
+ chunks: null,
1459
+ counts: null,
1460
+ extensions: null,
1461
+ bounds: null,
1462
+ details: null,
1463
+ khronosValidator: {
1464
+ requested: Boolean(runKhronos),
1465
+ status: 'not_run',
1466
+ tool: 'gltf-validator',
1467
+ message: 'Skipped because path could not be stat-ed',
1468
+ issues: null,
1469
+ },
1470
+ validationTiers: {
1471
+ containerStructural: {
1472
+ status: 'Failed',
1473
+ tool: 'scripts/inspect-glb.mjs',
1474
+ errorCount: 1,
1475
+ warningCount: 0,
1476
+ summary: `Unable to stat GLB path: ${filePath}`,
1477
+ },
1478
+ gltfSpecification: {
1479
+ status: 'Not Run',
1480
+ tool: 'gltf-validator',
1481
+ summary: 'Skipped because path could not be stat-ed.',
1482
+ },
1483
+ visualQuality: {
1484
+ status: 'Not Run',
1485
+ summary: 'Visual quality cannot be verified.',
1486
+ },
1487
+ liveRuntime: {
1488
+ status: 'Not Run',
1489
+ summary: 'Live Blender runtime execution was not run.',
1490
+ },
1491
+ },
1492
+ truthBoundary: {
1493
+ verificationScope: 'container-structure-only',
1494
+ provesContainerIntegrity: false,
1495
+ provesFullGltfSpecCompliance: false,
1496
+ provesVisualCorrectness: false,
1497
+ provesBlenderRuntimeExecution: false,
1498
+ disclaimer: CONTAINER_TRUTH_DISCLAIMER,
1499
+ },
1500
+ };
1501
+ }
1502
+
1503
+ if (!lstat.isFile()) {
1504
+ return {
1505
+ valid: false,
1506
+ filePath: resolved,
1507
+ errors: [`Path is not a regular file: ${filePath}`],
1508
+ warnings: [],
1509
+ byteSize: 0,
1510
+ sha256: null,
1511
+ header: null,
1512
+ chunks: null,
1513
+ counts: null,
1514
+ extensions: null,
1515
+ bounds: null,
1516
+ details: null,
1517
+ khronosValidator: {
1518
+ requested: Boolean(runKhronos),
1519
+ status: 'not_run',
1520
+ tool: 'gltf-validator',
1521
+ message: 'Skipped because path is not a regular file',
1522
+ issues: null,
1523
+ },
1524
+ validationTiers: {
1525
+ containerStructural: {
1526
+ status: 'Failed',
1527
+ tool: 'scripts/inspect-glb.mjs',
1528
+ errorCount: 1,
1529
+ warningCount: 0,
1530
+ summary: `Path is not a regular file: ${filePath}`,
1531
+ },
1532
+ gltfSpecification: {
1533
+ status: 'Not Run',
1534
+ tool: 'gltf-validator',
1535
+ summary: 'Skipped because path is not a regular file.',
1536
+ },
1537
+ visualQuality: {
1538
+ status: 'Not Run',
1539
+ summary: 'Visual quality cannot be verified.',
1540
+ },
1541
+ liveRuntime: {
1542
+ status: 'Not Run',
1543
+ summary: 'Live Blender runtime execution was not run.',
1544
+ },
1545
+ },
1546
+ truthBoundary: {
1547
+ verificationScope: 'container-structure-only',
1548
+ provesContainerIntegrity: false,
1549
+ provesFullGltfSpecCompliance: false,
1550
+ provesVisualCorrectness: false,
1551
+ provesBlenderRuntimeExecution: false,
1552
+ disclaimer: CONTAINER_TRUTH_DISCLAIMER,
1553
+ },
1554
+ };
1555
+ }
1556
+
1557
+ const buffer = fs.readFileSync(resolved);
1558
+ const result = inspectGlbBuffer(buffer, { strictPositionBounds });
1559
+ result.filePath = resolved;
1560
+
1561
+ if (runKhronos) {
1562
+ const khronosRes = await runKhronosGltfValidator(buffer, { validatorModuleLoader });
1563
+ result.khronosValidator = khronosRes;
1564
+ if (khronosRes.status === 'passed') {
1565
+ result.validationTiers.gltfSpecification = {
1566
+ status: (khronosRes.issues?.numWarnings ?? 0) > 0 ? 'Warn' : 'Passed',
1567
+ tool: 'gltf-validator',
1568
+ summary: khronosRes.message,
1569
+ };
1570
+ result.truthBoundary.provesFullGltfSpecCompliance = true;
1571
+ } else if (khronosRes.status === 'unavailable') {
1572
+ result.validationTiers.gltfSpecification = {
1573
+ status: 'Unavailable',
1574
+ tool: 'gltf-validator',
1575
+ summary: khronosRes.message,
1576
+ };
1577
+ } else if (khronosRes.status === 'failed' || khronosRes.status === 'error') {
1578
+ result.valid = false;
1579
+ result.truthBoundary.provesContainerIntegrity = false;
1580
+ result.truthBoundary.provesFullGltfSpecCompliance = false;
1581
+ result.errors.push(khronosRes.message);
1582
+ result.validationTiers.gltfSpecification = {
1583
+ status: 'Failed',
1584
+ tool: 'gltf-validator',
1585
+ summary: khronosRes.message,
1586
+ };
1587
+ }
1588
+ }
1589
+
1590
+ return result;
1591
+ }
1592
+
1593
+ async function main() {
1594
+ const args = process.argv.slice(2);
1595
+ const runKhronos = args.includes('--khronos');
1596
+ const strictPositionBounds = args.includes('--strict-bounds');
1597
+ const selfTest = args.includes('--self-test');
1598
+ const positional = args.filter((a) => !a.startsWith('--'));
1599
+
1600
+ if (selfTest) {
1601
+ const buf = buildMinimalValidGlbBuffer();
1602
+ const res = inspectGlbBuffer(buf, { strictPositionBounds: true });
1603
+ if (runKhronos) {
1604
+ res.khronosValidator = await runKhronosGltfValidator(buf);
1605
+ }
1606
+ process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
1607
+ process.exitCode = res.valid ? 0 : 1;
1608
+ return;
1609
+ }
1610
+
1611
+ if (positional.length === 0) {
1612
+ process.stderr.write(
1613
+ 'Usage: node scripts/inspect-glb.mjs <path-to-file.glb> [--khronos] [--strict-bounds] | --self-test\n',
1614
+ );
1615
+ process.exitCode = 1;
1616
+ return;
1617
+ }
1618
+
1619
+ const targetFile = positional[0];
1620
+ const report = await inspectGlbFile(targetFile, { runKhronos, strictPositionBounds });
1621
+ process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
1622
+ process.exitCode = report.valid ? 0 : 1;
1623
+ }
1624
+
1625
+ if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
1626
+ main();
1627
+ }