blendops 0.0.0-stage → 1.0.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 (484) hide show
  1. package/CHANGELOG.md +62 -0
  2. package/LICENSE +21 -0
  3. package/README.md +189 -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 +72 -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/examples/glb-web-handoff/README.md +174 -0
  136. package/docs/examples/glb-web-handoff/r3f-glb-viewer.tsx +320 -0
  137. package/docs/examples/glb-web-handoff/threejs-glb-viewer.mjs +709 -0
  138. package/docs/knowledge-and-recipe-catalog.md +236 -0
  139. package/docs/recipes/README.md +27 -0
  140. package/docs/recipes/cyberpunk-shoe-hero.md +97 -0
  141. package/docs/workflows/README.md +14 -0
  142. package/docs/workflows/full-non-blender-user-workflow.md +210 -0
  143. package/docs/workflows/product-hero-workflow.md +92 -0
  144. package/laws/README.md +32 -0
  145. package/laws/evidence-before-done.md +37 -0
  146. package/laws/no-arbitrary-python-interface.md +32 -0
  147. package/laws/non-blender-user-language.md +32 -0
  148. package/laws/official-runtime-only.md +78 -0
  149. package/package.json +99 -4
  150. package/packs/README.md +11 -0
  151. package/packs/product-hero-v0/PACK.md +114 -0
  152. package/registry/catalog-index.json +21344 -0
  153. package/registry/compatibility-matrix.json +533 -0
  154. package/registry/contract-context-fields.json +391 -0
  155. package/registry/knowledge-catalog.json +4648 -0
  156. package/registry/knowledge-sources.json +438 -0
  157. package/registry/recipe-catalog.json +2565 -0
  158. package/registry/runtime-capability-policy.json +525 -0
  159. package/registry/runtime-operations.json +4468 -0
  160. package/registry/skills.json +10231 -0
  161. package/registry/workflow-graph.json +7390 -0
  162. package/schemas/adapter-compatibility-matrix.schema.json +166 -0
  163. package/schemas/contract-context-fields.schema.json +147 -0
  164. package/schemas/execution-plan.schema.json +325 -0
  165. package/schemas/glb-web-handoff-manifest.schema.json +744 -0
  166. package/schemas/knowledge-record.schema.json +460 -0
  167. package/schemas/knowledge-source-registry.schema.json +268 -0
  168. package/schemas/operation-execution-ledger.schema.json +348 -0
  169. package/schemas/recipe-record.schema.json +469 -0
  170. package/schemas/runtime-capability-policy.schema.json +184 -0
  171. package/schemas/runtime-evidence-packet.schema.json +211 -0
  172. package/schemas/runtime-operations.schema.json +535 -0
  173. package/schemas/runtime-qualification-report.schema.json +540 -0
  174. package/schemas/runtime-session.schema.json +350 -0
  175. package/schemas/scene-spec.schema.json +624 -0
  176. package/schemas/skill-contract.schema.json +402 -0
  177. package/schemas/skill-eval.schema.json +509 -0
  178. package/scripts/build-knowledge-catalog.mjs +2376 -0
  179. package/scripts/compile-scene-plan.mjs +1945 -0
  180. package/scripts/export-claude-skills.mjs +634 -0
  181. package/scripts/generate-glb-handoff-report.mjs +2376 -0
  182. package/scripts/inspect-glb.mjs +1627 -0
  183. package/scripts/install-skills.mjs +5369 -0
  184. package/scripts/runtime-orchestrator.mjs +7652 -0
  185. package/scripts/validate-capability-policy.mjs +531 -0
  186. package/scripts/validate-evidence-packet.mjs +256 -0
  187. package/skills/README.md +315 -0
  188. package/skills/_template/SKILL.md +296 -0
  189. package/skills/acceptance-criteria-builder/EVAL.md +25 -0
  190. package/skills/acceptance-criteria-builder/SKILL.md +257 -0
  191. package/skills/acceptance-criteria-builder/contract.json +205 -0
  192. package/skills/acceptance-criteria-builder/references/brief-to-criteria-mapper.md +22 -0
  193. package/skills/acceptance-criteria-builder/references/checklist-patterns.md +22 -0
  194. package/skills/acceptance-criteria-builder/references/evidence-hook-rules.md +19 -0
  195. package/skills/asset-discovery/EVAL.md +81 -0
  196. package/skills/asset-discovery/SKILL.md +252 -0
  197. package/skills/asset-discovery/contract.json +291 -0
  198. package/skills/asset-discovery/references/asset-strategy-decision-tree.md +40 -0
  199. package/skills/asset-discovery/references/budget-reconciliation-patterns.md +54 -0
  200. package/skills/asset-discovery/references/license-confidence-table.md +41 -0
  201. package/skills/asset-fallback-strategy/EVAL.md +34 -0
  202. package/skills/asset-fallback-strategy/SKILL.md +248 -0
  203. package/skills/asset-fallback-strategy/contract.json +190 -0
  204. package/skills/asset-fallback-strategy/references/drop-with-caveat-rules.md +36 -0
  205. package/skills/asset-fallback-strategy/references/fallback-option-types.md +55 -0
  206. package/skills/asset-fallback-strategy/references/scoring-rubric.md +61 -0
  207. package/skills/asset-library-plan/EVAL.md +28 -0
  208. package/skills/asset-library-plan/SKILL.md +263 -0
  209. package/skills/asset-library-plan/contract.json +177 -0
  210. package/skills/asset-library-plan/references/folder-structure-rules.md +63 -0
  211. package/skills/asset-library-plan/references/metadata-schema.md +62 -0
  212. package/skills/asset-library-plan/references/naming-rules.md +51 -0
  213. package/skills/asset-license-checker/EVAL.md +33 -0
  214. package/skills/asset-license-checker/SKILL.md +245 -0
  215. package/skills/asset-license-checker/contract.json +172 -0
  216. package/skills/asset-license-checker/references/attribution-rendering-patterns.md +48 -0
  217. package/skills/asset-license-checker/references/common-license-mapping.md +39 -0
  218. package/skills/asset-license-checker/references/license-source-rules.md +38 -0
  219. package/skills/asset-style-check/EVAL.md +26 -0
  220. package/skills/asset-style-check/SKILL.md +238 -0
  221. package/skills/asset-style-check/contract.json +251 -0
  222. package/skills/asset-style-check/references/drift-classification.md +40 -0
  223. package/skills/asset-style-check/references/intentional-mixed-style.md +39 -0
  224. package/skills/asset-style-check/references/style-axes.md +46 -0
  225. package/skills/blender-brainstorming/EVAL.md +79 -0
  226. package/skills/blender-brainstorming/SKILL.md +228 -0
  227. package/skills/blender-brainstorming/contract.json +115 -0
  228. package/skills/blender-brainstorming/references/alternative-scoping-templates.md +43 -0
  229. package/skills/blender-brainstorming/references/clarification-patterns.md +29 -0
  230. package/skills/blender-brainstorming/references/intent-summary-style-guide.md +25 -0
  231. package/skills/blender-recipe-decomposer/EVAL.md +35 -0
  232. package/skills/blender-recipe-decomposer/SKILL.md +258 -0
  233. package/skills/blender-recipe-decomposer/contract.json +152 -0
  234. package/skills/blender-recipe-decomposer/references/dependency-patterns.md +53 -0
  235. package/skills/blender-recipe-decomposer/references/recipe-grouping-rules.md +58 -0
  236. package/skills/blender-recipe-decomposer/references/recipe-naming-rules.md +44 -0
  237. package/skills/blender-troubleshooting/EVAL.md +78 -0
  238. package/skills/blender-troubleshooting/SKILL.md +263 -0
  239. package/skills/blender-troubleshooting/contract.json +352 -0
  240. package/skills/blender-troubleshooting/references/common-symptom-playbooks.md +51 -0
  241. package/skills/blender-troubleshooting/references/divergence-routing-table.md +23 -0
  242. package/skills/blender-troubleshooting/references/four-phase-template.md +51 -0
  243. package/skills/blendops-help/EVAL.md +67 -0
  244. package/skills/blendops-help/SKILL.md +312 -0
  245. package/skills/blendops-help/contract.json +229 -0
  246. package/skills/blendops-help/references/lifecycle-phases.md +91 -0
  247. package/skills/blendops-help/references/quick-start-prompts.md +65 -0
  248. package/skills/blendops-help/references/routing-decision-tree.md +57 -0
  249. package/skills/bridge-conflicts/EVAL.md +83 -0
  250. package/skills/bridge-conflicts/SKILL.md +246 -0
  251. package/skills/bridge-conflicts/contract.json +145 -0
  252. package/skills/bridge-conflicts/references/bridge-state-matrix-template.md +82 -0
  253. package/skills/bridge-conflicts/references/conflict-playbooks.md +99 -0
  254. package/skills/bridge-conflicts/references/do-not-reminders.md +42 -0
  255. package/skills/camera-composition/EVAL.md +32 -0
  256. package/skills/camera-composition/SKILL.md +196 -0
  257. package/skills/camera-composition/contract.json +180 -0
  258. package/skills/camera-composition/references/camera-presets.md +30 -0
  259. package/skills/camera-composition/references/camera-rubric.md +24 -0
  260. package/skills/camera-composition/references/hero-composition-patterns.md +24 -0
  261. package/skills/camera-composition/references/web-layout-negative-space.md +25 -0
  262. package/skills/character-portrait/EVAL.md +42 -0
  263. package/skills/character-portrait/SKILL.md +245 -0
  264. package/skills/character-portrait/contract.json +205 -0
  265. package/skills/character-portrait/references/portrait-framing-rules.md +39 -0
  266. package/skills/character-portrait/references/portrait-lighting-patterns.md +50 -0
  267. package/skills/character-portrait/references/style-consistency-rules.md +41 -0
  268. package/skills/cli-appendix-job-outline/EVAL.md +26 -0
  269. package/skills/cli-appendix-job-outline/SKILL.md +252 -0
  270. package/skills/cli-appendix-job-outline/contract.json +147 -0
  271. package/skills/cli-appendix-job-outline/references/flag-order-reminders.md +16 -0
  272. package/skills/cli-appendix-job-outline/references/job-type-matrix.md +13 -0
  273. package/skills/cli-appendix-job-outline/references/stateless-limitations.md +12 -0
  274. package/skills/color-management-decision/EVAL.md +28 -0
  275. package/skills/color-management-decision/SKILL.md +254 -0
  276. package/skills/color-management-decision/contract.json +162 -0
  277. package/skills/color-management-decision/references/look-comparison.md +44 -0
  278. package/skills/color-management-decision/references/per-channel-rules.md +49 -0
  279. package/skills/color-management-decision/references/pipeline-mapping.md +47 -0
  280. package/skills/composition-quality-checker/EVAL.md +38 -0
  281. package/skills/composition-quality-checker/SKILL.md +260 -0
  282. package/skills/composition-quality-checker/contract.json +221 -0
  283. package/skills/composition-quality-checker/references/aspect-ratio-rules.md +37 -0
  284. package/skills/composition-quality-checker/references/composition-rules.md +58 -0
  285. package/skills/composition-quality-checker/references/headroom-leadroom-rules.md +46 -0
  286. package/skills/cycles-vs-eevee-decision/EVAL.md +26 -0
  287. package/skills/cycles-vs-eevee-decision/SKILL.md +249 -0
  288. package/skills/cycles-vs-eevee-decision/contract.json +142 -0
  289. package/skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md +39 -0
  290. package/skills/cycles-vs-eevee-decision/references/gpu-device-rules.md +51 -0
  291. package/skills/cycles-vs-eevee-decision/references/samples-by-quality.md +53 -0
  292. package/skills/done-criteria/EVAL.md +33 -0
  293. package/skills/done-criteria/SKILL.md +225 -0
  294. package/skills/done-criteria/contract.json +199 -0
  295. package/skills/done-criteria/references/done-vs-perfect.md +56 -0
  296. package/skills/done-criteria/references/out-of-scope-patterns.md +50 -0
  297. package/skills/done-criteria/references/stop-condition-templates.md +39 -0
  298. package/skills/environment-shot/EVAL.md +44 -0
  299. package/skills/environment-shot/SKILL.md +237 -0
  300. package/skills/environment-shot/contract.json +162 -0
  301. package/skills/environment-shot/references/depth-layering-rules.md +49 -0
  302. package/skills/environment-shot/references/time-and-weather-rules.md +35 -0
  303. package/skills/environment-shot/references/wide-shot-camera-rules.md +51 -0
  304. package/skills/glb-animation-handoff/EVAL.md +39 -0
  305. package/skills/glb-animation-handoff/SKILL.md +271 -0
  306. package/skills/glb-animation-handoff/contract.json +247 -0
  307. package/skills/glb-animation-handoff/references/animation-types.md +36 -0
  308. package/skills/glb-animation-handoff/references/transition-rules.md +55 -0
  309. package/skills/glb-animation-handoff/references/web-stack-caveats.md +40 -0
  310. package/skills/glb-web-handoff/EVAL.md +33 -0
  311. package/skills/glb-web-handoff/SKILL.md +212 -0
  312. package/skills/glb-web-handoff/contract.json +171 -0
  313. package/skills/glb-web-handoff/references/artifact-status-language.md +26 -0
  314. package/skills/glb-web-handoff/references/glb-handoff-checklist.md +30 -0
  315. package/skills/glb-web-handoff/references/performance-caveats.md +26 -0
  316. package/skills/glb-web-handoff/references/threejs-r3f-handoff.md +28 -0
  317. package/skills/intent-to-3d-brief-writer/EVAL.md +82 -0
  318. package/skills/intent-to-3d-brief-writer/SKILL.md +238 -0
  319. package/skills/intent-to-3d-brief-writer/contract.json +195 -0
  320. package/skills/intent-to-3d-brief-writer/references/acceptance-criteria-patterns.md +46 -0
  321. package/skills/intent-to-3d-brief-writer/references/eight-slot-template.md +123 -0
  322. package/skills/intent-to-3d-brief-writer/references/mixed-audience-handling.md +39 -0
  323. package/skills/interior-scene/EVAL.md +44 -0
  324. package/skills/interior-scene/SKILL.md +261 -0
  325. package/skills/interior-scene/contract.json +277 -0
  326. package/skills/interior-scene/references/furniture-layout-rules.md +51 -0
  327. package/skills/interior-scene/references/interior-architecture-rules.md +47 -0
  328. package/skills/interior-scene/references/interior-camera-rules.md +47 -0
  329. package/skills/lighting-material-plan/EVAL.md +32 -0
  330. package/skills/lighting-material-plan/SKILL.md +194 -0
  331. package/skills/lighting-material-plan/contract.json +213 -0
  332. package/skills/lighting-material-plan/references/cyberpunk-lookdev.md +22 -0
  333. package/skills/lighting-material-plan/references/lighting-patterns.md +30 -0
  334. package/skills/lighting-material-plan/references/material-portability.md +25 -0
  335. package/skills/lighting-material-plan/references/reflective-floor-pattern.md +22 -0
  336. package/skills/lighting-material-plan/references/web-material-simplification.md +23 -0
  337. package/skills/lighting-quality-checker/EVAL.md +41 -0
  338. package/skills/lighting-quality-checker/SKILL.md +247 -0
  339. package/skills/lighting-quality-checker/contract.json +187 -0
  340. package/skills/lighting-quality-checker/references/hdri-balance-rules.md +48 -0
  341. package/skills/lighting-quality-checker/references/intensity-ranges.md +73 -0
  342. package/skills/lighting-quality-checker/references/shadow-softness-rules.md +38 -0
  343. package/skills/material-quality-checker/EVAL.md +40 -0
  344. package/skills/material-quality-checker/SKILL.md +261 -0
  345. package/skills/material-quality-checker/contract.json +244 -0
  346. package/skills/material-quality-checker/references/consumer-stack-rules.md +62 -0
  347. package/skills/material-quality-checker/references/pbr-sanity-rules.md +78 -0
  348. package/skills/material-quality-checker/references/texture-budget-rules.md +48 -0
  349. package/skills/mobile-glb-budget/EVAL.md +40 -0
  350. package/skills/mobile-glb-budget/SKILL.md +264 -0
  351. package/skills/mobile-glb-budget/contract.json +309 -0
  352. package/skills/mobile-glb-budget/references/budget-tiers.md +30 -0
  353. package/skills/mobile-glb-budget/references/degradation-plan.md +34 -0
  354. package/skills/mobile-glb-budget/references/violation-rules.md +43 -0
  355. package/skills/output-format-decision/EVAL.md +27 -0
  356. package/skills/output-format-decision/SKILL.md +222 -0
  357. package/skills/output-format-decision/contract.json +179 -0
  358. package/skills/output-format-decision/references/bit-depth-rules.md +56 -0
  359. package/skills/output-format-decision/references/compression-tradeoffs.md +62 -0
  360. package/skills/output-format-decision/references/format-decision-matrix.md +34 -0
  361. package/skills/pack-prerequisite-checker/EVAL.md +26 -0
  362. package/skills/pack-prerequisite-checker/SKILL.md +272 -0
  363. package/skills/pack-prerequisite-checker/contract.json +214 -0
  364. package/skills/pack-prerequisite-checker/references/blocked-start-playbook.md +21 -0
  365. package/skills/pack-prerequisite-checker/references/pack-readiness-template.md +38 -0
  366. package/skills/pack-prerequisite-checker/references/prerequisite-matrix.md +20 -0
  367. package/skills/path-one-host-outline/EVAL.md +26 -0
  368. package/skills/path-one-host-outline/SKILL.md +251 -0
  369. package/skills/path-one-host-outline/contract.json +167 -0
  370. package/skills/path-one-host-outline/references/connector-vs-manual-matrix.md +21 -0
  371. package/skills/path-one-host-outline/references/host-checklist-template.md +35 -0
  372. package/skills/path-one-host-outline/references/lab-addon-reminders.md +12 -0
  373. package/skills/plain-language-response/EVAL.md +33 -0
  374. package/skills/plain-language-response/SKILL.md +194 -0
  375. package/skills/plain-language-response/contract.json +242 -0
  376. package/skills/plain-language-response/references/caveat-language.md +25 -0
  377. package/skills/plain-language-response/references/plain-language-patterns.md +30 -0
  378. package/skills/plain-language-response/references/stakeholder-friendly-examples.md +30 -0
  379. package/skills/plain-language-response/references/status-summary-templates.md +50 -0
  380. package/skills/polycount-budget-checker/EVAL.md +40 -0
  381. package/skills/polycount-budget-checker/SKILL.md +251 -0
  382. package/skills/polycount-budget-checker/contract.json +196 -0
  383. package/skills/polycount-budget-checker/references/instance-counting-rules.md +39 -0
  384. package/skills/polycount-budget-checker/references/per-mesh-rules.md +43 -0
  385. package/skills/polycount-budget-checker/references/topology-hints.md +56 -0
  386. package/skills/pre-handoff-verification/EVAL.md +84 -0
  387. package/skills/pre-handoff-verification/SKILL.md +252 -0
  388. package/skills/pre-handoff-verification/contract.json +295 -0
  389. package/skills/pre-handoff-verification/references/downgrade-rules.md +39 -0
  390. package/skills/pre-handoff-verification/references/seven-point-checklist.md +46 -0
  391. package/skills/pre-handoff-verification/references/text-only-mode-handling.md +36 -0
  392. package/skills/preview-report/EVAL.md +39 -0
  393. package/skills/preview-report/SKILL.md +254 -0
  394. package/skills/preview-report/contract.json +141 -0
  395. package/skills/preview-report/references/handoff-recipients.md +41 -0
  396. package/skills/preview-report/references/report-schema.md +60 -0
  397. package/skills/preview-report/references/truth-label-rules.md +36 -0
  398. package/skills/product-grid-scene-planner/EVAL.md +42 -0
  399. package/skills/product-grid-scene-planner/SKILL.md +246 -0
  400. package/skills/product-grid-scene-planner/contract.json +257 -0
  401. package/skills/product-grid-scene-planner/references/grid-consistency-rules.md +53 -0
  402. package/skills/product-grid-scene-planner/references/grid-layout-rules.md +42 -0
  403. package/skills/product-grid-scene-planner/references/grid-output-naming-rules.md +52 -0
  404. package/skills/product-hero-scene-planner/EVAL.md +33 -0
  405. package/skills/product-hero-scene-planner/SKILL.md +227 -0
  406. package/skills/product-hero-scene-planner/contract.json +228 -0
  407. package/skills/product-hero-scene-planner/references/clarification-patterns.md +24 -0
  408. package/skills/product-hero-scene-planner/references/cyberpunk-shoe-example.md +28 -0
  409. package/skills/product-hero-scene-planner/references/product-hero-playbooks.md +22 -0
  410. package/skills/product-hero-scene-planner/references/scene-plan-schema.md +35 -0
  411. package/skills/r3f-component-plan/EVAL.md +43 -0
  412. package/skills/r3f-component-plan/SKILL.md +290 -0
  413. package/skills/r3f-component-plan/contract.json +171 -0
  414. package/skills/r3f-component-plan/references/component-shape-patterns.md +54 -0
  415. package/skills/r3f-component-plan/references/suspense-placement-rules.md +50 -0
  416. package/skills/r3f-component-plan/references/usegltf-caching-rules.md +53 -0
  417. package/skills/recipe-fit-assessor/EVAL.md +28 -0
  418. package/skills/recipe-fit-assessor/SKILL.md +266 -0
  419. package/skills/recipe-fit-assessor/contract.json +220 -0
  420. package/skills/recipe-fit-assessor/references/recipe-catalog.md +30 -0
  421. package/skills/recipe-fit-assessor/references/scope-gap-rules.md +27 -0
  422. package/skills/recipe-fit-assessor/references/workflow-recommendation-template.md +34 -0
  423. package/skills/render-export-evidence/EVAL.md +86 -0
  424. package/skills/render-export-evidence/SKILL.md +339 -0
  425. package/skills/render-export-evidence/contract.json +206 -0
  426. package/skills/render-export-evidence/references/attempted-vs-failed-rubric.md +75 -0
  427. package/skills/render-export-evidence/references/evidence-record-templates.md +143 -0
  428. package/skills/render-export-evidence/references/truth-label-decision-tree.md +57 -0
  429. package/skills/resolution-aspect-decision/EVAL.md +26 -0
  430. package/skills/resolution-aspect-decision/SKILL.md +246 -0
  431. package/skills/resolution-aspect-decision/contract.json +160 -0
  432. package/skills/resolution-aspect-decision/references/aspect-defaults.md +41 -0
  433. package/skills/resolution-aspect-decision/references/print-vs-screen-rules.md +58 -0
  434. package/skills/resolution-aspect-decision/references/resolution-defaults.md +64 -0
  435. package/skills/runtime-attempt-report/EVAL.md +26 -0
  436. package/skills/runtime-attempt-report/SKILL.md +268 -0
  437. package/skills/runtime-attempt-report/contract.json +176 -0
  438. package/skills/runtime-attempt-report/references/attempt-record-template.md +49 -0
  439. package/skills/runtime-attempt-report/references/triage-next-steps.md +15 -0
  440. package/skills/runtime-attempt-report/references/truth-label-blocks.md +27 -0
  441. package/skills/runtime-path-picker/EVAL.md +26 -0
  442. package/skills/runtime-path-picker/SKILL.md +268 -0
  443. package/skills/runtime-path-picker/contract.json +191 -0
  444. package/skills/runtime-path-picker/references/anti-patterns.md +14 -0
  445. package/skills/runtime-path-picker/references/decision-tree.md +29 -0
  446. package/skills/runtime-path-picker/references/path-constraints-table.md +18 -0
  447. package/skills/runtime-readiness/EVAL.md +33 -0
  448. package/skills/runtime-readiness/SKILL.md +218 -0
  449. package/skills/runtime-readiness/contract.json +190 -0
  450. package/skills/runtime-readiness/references/blocker-report-template.md +28 -0
  451. package/skills/runtime-readiness/references/evidence-examples.md +23 -0
  452. package/skills/runtime-readiness/references/readiness-matrix.md +46 -0
  453. package/skills/runtime-setup/EVAL.md +33 -0
  454. package/skills/runtime-setup/SKILL.md +209 -0
  455. package/skills/runtime-setup/contract.json +171 -0
  456. package/skills/runtime-setup/references/runtime-option-decision-tree.md +28 -0
  457. package/skills/runtime-setup/references/setup-summary-template.md +33 -0
  458. package/skills/runtime-setup/references/source-confidence-labels.md +23 -0
  459. package/skills/scene-readiness/EVAL.md +33 -0
  460. package/skills/scene-readiness/SKILL.md +195 -0
  461. package/skills/scene-readiness/contract.json +198 -0
  462. package/skills/scene-readiness/references/blocker-catalog.md +24 -0
  463. package/skills/scene-readiness/references/not-run-handling.md +22 -0
  464. package/skills/scene-readiness/references/quality-rubric.md +23 -0
  465. package/skills/scene-readiness/references/verdict-language.md +22 -0
  466. package/skills/scope-guard/EVAL.md +33 -0
  467. package/skills/scope-guard/SKILL.md +222 -0
  468. package/skills/scope-guard/contract.json +171 -0
  469. package/skills/scope-guard/references/options-language-template.md +51 -0
  470. package/skills/scope-guard/references/recurring-creep-patterns.md +55 -0
  471. package/skills/scope-guard/references/scope-addition-classification.md +55 -0
  472. package/skills/stage-gates/EVAL.md +40 -0
  473. package/skills/stage-gates/SKILL.md +257 -0
  474. package/skills/stage-gates/contract.json +490 -0
  475. package/skills/stage-gates/references/failed-gate-handling.md +42 -0
  476. package/skills/stage-gates/references/gate-template.md +46 -0
  477. package/skills/stage-gates/references/stage-decomposition-patterns.md +55 -0
  478. package/skills/workflow-stage-router/EVAL.md +25 -0
  479. package/skills/workflow-stage-router/SKILL.md +259 -0
  480. package/skills/workflow-stage-router/contract.json +150 -0
  481. package/skills/workflow-stage-router/references/milestone-model.md +20 -0
  482. package/skills/workflow-stage-router/references/routing-decision-tree.md +32 -0
  483. package/skills/workflow-stage-router/references/stage-handoff-template.md +37 -0
  484. package/skills.sh.json +102 -0
@@ -0,0 +1,709 @@
1
+ /**
2
+ * BlendOps — Reusable Three.js GLB Web Handoff Integration Module
3
+ *
4
+ * Provides a production-ready, deterministic Three.js GLB viewer harness and
5
+ * helper utilities aligned with `schemas/glb-web-handoff-manifest.schema.json`
6
+ * and `skills/glb-web-handoff/SKILL.md`.
7
+ *
8
+ * Truth-State Boundary:
9
+ * - This module is a consumer-side web integration harness for Three.js (`r150+`).
10
+ * - It does not run Blender or claim live Blender runtime execution (`Runtime status: Not Run`).
11
+ * - Structural GLB validity (`inspect-glb.mjs`) does not prove visual rendering quality (`Tier 3`).
12
+ */
13
+
14
+ export const DEFAULT_DECODER_PATHS = Object.freeze({
15
+ dracoGltfPath: '/decoders/draco/gltf/',
16
+ basisTranscoderPath: '/decoders/basis/',
17
+ });
18
+
19
+ export const SUPPORTED_COLOR_SPACES = Object.freeze(['srgb', 'srgb-linear', 'display-p3']);
20
+
21
+ /**
22
+ * Normalizes a BlendOps GLB web handoff manifest (or partial options) into a
23
+ * deterministic viewer configuration object.
24
+ *
25
+ * @param {object} [manifestOrOptions]
26
+ * @returns {object}
27
+ */
28
+ export function resolveViewerManifestConfig(manifestOrOptions = {}) {
29
+ const manifest = manifestOrOptions && typeof manifestOrOptions === 'object' ? manifestOrOptions : {};
30
+ const artifact = manifest.artifact && typeof manifest.artifact === 'object' ? manifest.artifact : {};
31
+ const compression = manifest.compression && typeof manifest.compression === 'object' ? manifest.compression : {};
32
+ const spatial = manifest.spatial && typeof manifest.spatial === 'object' ? manifest.spatial : {};
33
+ const viewer = manifest.viewer && typeof manifest.viewer === 'object' ? manifest.viewer : {};
34
+ const animations = manifest.animations && typeof manifest.animations === 'object' ? manifest.animations : {};
35
+
36
+ const assetUrl =
37
+ typeof manifest.assetUrl === 'string' && manifest.assetUrl.trim().length > 0
38
+ ? manifest.assetUrl.trim()
39
+ : `/models/${artifact.fileName || 'asset.glb'}`;
40
+
41
+ const requiresDraco = Boolean(compression.draco ?? manifest.requiresDraco);
42
+ const requiresMeshopt = Boolean(compression.meshopt ?? manifest.requiresMeshopt);
43
+ const requiresKtx2 = Boolean(compression.ktx2BasisU ?? manifest.requiresKtx2);
44
+ const requiresWebP = Boolean(compression.webp ?? manifest.requiresWebP);
45
+
46
+ const outputColorSpace = SUPPORTED_COLOR_SPACES.includes(viewer.outputColorSpace)
47
+ ? viewer.outputColorSpace
48
+ : 'srgb';
49
+
50
+ const toneMapping =
51
+ typeof viewer.toneMapping === 'string' && viewer.toneMapping.length > 0
52
+ ? viewer.toneMapping
53
+ : 'ACESFilmicToneMapping';
54
+
55
+ const clipNames = Array.isArray(animations.clips)
56
+ ? animations.clips.map((c) => (typeof c === 'string' ? c : c?.name)).filter(Boolean)
57
+ : [];
58
+
59
+ return {
60
+ assetUrl,
61
+ fileName: artifact.fileName || 'asset.glb',
62
+ sha256: artifact.sha256 || null,
63
+ byteSize: Number.isInteger(artifact.byteSize) ? artifact.byteSize : null,
64
+ coordinateSystem: spatial.coordinateSystem || '+Y up, +Z forward, -X right (glTF 2.0 meters)',
65
+ unitScaleMetersPerUnit:
66
+ typeof spatial.unitScaleMetersPerUnit === 'number' && spatial.unitScaleMetersPerUnit > 0
67
+ ? spatial.unitScaleMetersPerUnit
68
+ : 1.0,
69
+ originPlacement: spatial.originPlacement || 'unspecified',
70
+ estimatedBounds: spatial.estimatedBounds || {
71
+ available: false,
72
+ min: null,
73
+ max: null,
74
+ size: null,
75
+ center: null,
76
+ maxDimensionMeters: null,
77
+ },
78
+ hasNonIdentityRootScale: Boolean(spatial.hasNonIdentityRootScale),
79
+ hasNegativeScale: Boolean(spatial.hasNegativeScale),
80
+ requiresDraco,
81
+ requiresMeshopt,
82
+ requiresKtx2,
83
+ requiresWebP,
84
+ outputColorSpace,
85
+ toneMapping,
86
+ environmentPreset: viewer.environmentPreset || 'RoomEnvironment',
87
+ autoCenterCamera: viewer.autoCenterCamera !== false,
88
+ animationClips: clipNames,
89
+ defaultClip: clipNames[0] || null,
90
+ };
91
+ }
92
+
93
+ /**
94
+ * Determines which decoders must be attached to `GLTFLoader` for a given manifest
95
+ * or decoder flags.
96
+ *
97
+ * @param {object} configOrManifest
98
+ * @param {object} [decoderPaths]
99
+ * @returns {object}
100
+ */
101
+ export function resolveDecoderConfiguration(configOrManifest = {}, decoderPaths = {}) {
102
+ const cfg =
103
+ 'requiresDraco' in configOrManifest && 'assetUrl' in configOrManifest
104
+ ? configOrManifest
105
+ : resolveViewerManifestConfig(configOrManifest);
106
+
107
+ const dracoGltfPath = decoderPaths.dracoGltfPath || DEFAULT_DECODER_PATHS.dracoGltfPath;
108
+ const basisTranscoderPath =
109
+ decoderPaths.basisTranscoderPath || DEFAULT_DECODER_PATHS.basisTranscoderPath;
110
+
111
+ return {
112
+ requiresDraco: Boolean(cfg.requiresDraco),
113
+ requiresMeshopt: Boolean(cfg.requiresMeshopt),
114
+ requiresKtx2: Boolean(cfg.requiresKtx2),
115
+ requiresWebP: Boolean(cfg.requiresWebP),
116
+ dracoGltfPath,
117
+ basisTranscoderPath,
118
+ requiredAddons: [
119
+ 'three/addons/loaders/GLTFLoader.js',
120
+ ...(cfg.requiresDraco ? ['three/addons/loaders/DRACOLoader.js'] : []),
121
+ ...(cfg.requiresMeshopt ? ['three/addons/libs/meshopt_decoder.module.js'] : []),
122
+ ...(cfg.requiresKtx2 ? ['three/addons/loaders/KTX2Loader.js'] : []),
123
+ ],
124
+ };
125
+ }
126
+
127
+ /**
128
+ * Computes deterministic perspective camera framing parameters from a 3D bounding box
129
+ * (`min` and `max` [x, y, z] arrays) and field-of-view.
130
+ *
131
+ * @param {{ min: number[], max: number[] }} bounds
132
+ * @param {{ fovDeg?: number, paddingFactor?: number, aspect?: number }} [options]
133
+ * @returns {{ center: [number, number, number], size: [number, number, number], maxDim: number, distance: number, position: [number, number, number], near: number, far: number }}
134
+ */
135
+ export function computeCameraFramingParameters(bounds, options = {}) {
136
+ if (
137
+ !bounds ||
138
+ !Array.isArray(bounds.min) ||
139
+ !Array.isArray(bounds.max) ||
140
+ bounds.min.length < 3 ||
141
+ bounds.max.length < 3
142
+ ) {
143
+ throw new TypeError('computeCameraFramingParameters requires bounds.min and bounds.max [x, y, z] arrays');
144
+ }
145
+
146
+ const fovDeg = typeof options.fovDeg === 'number' && options.fovDeg > 0 ? options.fovDeg : 45;
147
+ const paddingFactor =
148
+ typeof options.paddingFactor === 'number' && options.paddingFactor > 0
149
+ ? options.paddingFactor
150
+ : 1.45;
151
+
152
+ const size = [
153
+ Math.max(0, Number(bounds.max[0]) - Number(bounds.min[0])),
154
+ Math.max(0, Number(bounds.max[1]) - Number(bounds.min[1])),
155
+ Math.max(0, Number(bounds.max[2]) - Number(bounds.min[2])),
156
+ ];
157
+ const center = [
158
+ (Number(bounds.min[0]) + Number(bounds.max[0])) / 2,
159
+ (Number(bounds.min[1]) + Number(bounds.max[1])) / 2,
160
+ (Number(bounds.min[2]) + Number(bounds.max[2])) / 2,
161
+ ];
162
+
163
+ const rawMaxDim = Math.max(size[0], size[1], size[2]);
164
+ const maxDim = Number.isFinite(rawMaxDim) && rawMaxDim > 0 ? rawMaxDim : 1.0;
165
+ const fovRad = (fovDeg * Math.PI) / 180;
166
+ const halfFovTan = Math.tan(fovRad / 2);
167
+ const distance = Math.max((maxDim / (2 * halfFovTan)) * paddingFactor, 0.25);
168
+
169
+ const position = [
170
+ Number((center[0] + distance * 0.65).toFixed(6)),
171
+ Number((center[1] + distance * 0.45).toFixed(6)),
172
+ Number((center[2] + distance).toFixed(6)),
173
+ ];
174
+
175
+ const near = Number(Math.max(maxDim / 1000, 0.001).toFixed(6));
176
+ const far = Number(Math.max(maxDim * 100, distance * 20, 100).toFixed(6));
177
+
178
+ return {
179
+ center: [
180
+ Number(center[0].toFixed(6)),
181
+ Number(center[1].toFixed(6)),
182
+ Number(center[2].toFixed(6)),
183
+ ],
184
+ size: [
185
+ Number(size[0].toFixed(6)),
186
+ Number(size[1].toFixed(6)),
187
+ Number(size[2].toFixed(6)),
188
+ ],
189
+ maxDim: Number(maxDim.toFixed(6)),
190
+ distance: Number(distance.toFixed(6)),
191
+ position,
192
+ near,
193
+ far,
194
+ };
195
+ }
196
+
197
+ /**
198
+ * Configures a Three.js `GLTFLoader` instance with optional Draco, Meshopt, and KTX2
199
+ * decoders based on the GLB web handoff manifest.
200
+ *
201
+ * @param {object} loader - Instance of `GLTFLoader`
202
+ * @param {object} options
203
+ * @param {object} [options.manifest] - BlendOps GLB handoff manifest
204
+ * @param {object} [options.renderer] - Instance of `THREE.WebGLRenderer` (required if KTX2 is enabled)
205
+ * @param {Function} [options.DRACOLoader] - `DRACOLoader` constructor
206
+ * @param {Function} [options.KTX2Loader] - `KTX2Loader` constructor
207
+ * @param {object} [options.MeshoptDecoder] - `MeshoptDecoder` object
208
+ * @param {object} [options.decoderPaths] - Custom paths for Draco/Basis transcoders
209
+ * @returns {{ decoderConfig: object, dracoLoader: object|null, ktx2Loader: object|null, disposeDecoders: () => void }}
210
+ */
211
+ export function configureGltfDecoders(loader, options = {}) {
212
+ if (!loader || typeof loader !== 'object') {
213
+ throw new TypeError('configureGltfDecoders requires a valid GLTFLoader instance');
214
+ }
215
+
216
+ const decoderConfig = resolveDecoderConfiguration(
217
+ options.manifest || options,
218
+ options.decoderPaths || {},
219
+ );
220
+
221
+ let dracoLoader = null;
222
+ let ktx2Loader = null;
223
+
224
+ if (decoderConfig.requiresDraco) {
225
+ if (typeof options.DRACOLoader !== 'function') {
226
+ throw new Error(
227
+ 'GLB requires KHR_draco_mesh_compression, but options.DRACOLoader constructor was not provided.',
228
+ );
229
+ }
230
+ if (typeof loader.setDRACOLoader !== 'function') {
231
+ throw new Error('Provided GLTFLoader does not support setDRACOLoader().');
232
+ }
233
+ dracoLoader = new options.DRACOLoader();
234
+ if (typeof dracoLoader.setDecoderPath === 'function') {
235
+ dracoLoader.setDecoderPath(decoderConfig.dracoGltfPath);
236
+ }
237
+ loader.setDRACOLoader(dracoLoader);
238
+ }
239
+
240
+ if (decoderConfig.requiresMeshopt) {
241
+ if (!options.MeshoptDecoder) {
242
+ throw new Error(
243
+ 'GLB requires EXT_meshopt_compression, but options.MeshoptDecoder was not provided.',
244
+ );
245
+ }
246
+ if (typeof loader.setMeshoptDecoder !== 'function') {
247
+ throw new Error('Provided GLTFLoader does not support setMeshoptDecoder().');
248
+ }
249
+ loader.setMeshoptDecoder(options.MeshoptDecoder);
250
+ }
251
+
252
+ if (decoderConfig.requiresKtx2) {
253
+ if (typeof options.KTX2Loader !== 'function') {
254
+ throw new Error(
255
+ 'GLB requires KHR_texture_basisu, but options.KTX2Loader constructor was not provided.',
256
+ );
257
+ }
258
+ if (!options.renderer) {
259
+ throw new Error(
260
+ 'GLB requires KHR_texture_basisu, which requires options.renderer (WebGLRenderer) for KTX2Loader.detectSupport(renderer).',
261
+ );
262
+ }
263
+ if (typeof loader.setKTX2Loader !== 'function') {
264
+ throw new Error('Provided GLTFLoader does not support setKTX2Loader().');
265
+ }
266
+ ktx2Loader = new options.KTX2Loader();
267
+ if (typeof ktx2Loader.setTranscoderPath === 'function') {
268
+ ktx2Loader.setTranscoderPath(decoderConfig.basisTranscoderPath);
269
+ }
270
+ if (typeof ktx2Loader.detectSupport === 'function') {
271
+ ktx2Loader.detectSupport(options.renderer);
272
+ }
273
+ loader.setKTX2Loader(ktx2Loader);
274
+ }
275
+
276
+ return {
277
+ decoderConfig,
278
+ dracoLoader,
279
+ ktx2Loader,
280
+ disposeDecoders() {
281
+ if (dracoLoader && typeof dracoLoader.dispose === 'function') {
282
+ dracoLoader.dispose();
283
+ }
284
+ if (ktx2Loader && typeof ktx2Loader.dispose === 'function') {
285
+ ktx2Loader.dispose();
286
+ }
287
+ },
288
+ };
289
+ }
290
+
291
+ /**
292
+ * Frames a Three.js `PerspectiveCamera` and optional `OrbitControls` around a loaded
293
+ * root `Object3D` or explicit bounding box.
294
+ *
295
+ * @param {object} params
296
+ * @param {object} params.camera - `THREE.PerspectiveCamera`
297
+ * @param {object} [params.controls] - `OrbitControls`
298
+ * @param {object} [params.rootObject] - Loaded `gltf.scene` (`THREE.Object3D`)
299
+ * @param {object} [params.THREE] - Three.js namespace (used if computing Box3 from `rootObject`)
300
+ * @param {{ min: number[], max: number[] }} [params.bounds] - Explicit bounds fallback
301
+ * @param {number} [params.paddingFactor]
302
+ * @returns {object} Computed framing parameters
303
+ */
304
+ export function frameCameraToBoundingBox({
305
+ camera,
306
+ controls = null,
307
+ rootObject = null,
308
+ THREE = null,
309
+ bounds = null,
310
+ paddingFactor = 1.45,
311
+ }) {
312
+ if (!camera || typeof camera !== 'object') {
313
+ throw new TypeError('frameCameraToBoundingBox requires a camera instance');
314
+ }
315
+
316
+ let resolvedBounds = bounds;
317
+ if (!resolvedBounds && rootObject && THREE && typeof THREE.Box3 === 'function') {
318
+ const box = new THREE.Box3().setFromObject(rootObject);
319
+ if (box.min && box.max) {
320
+ resolvedBounds = {
321
+ min: [box.min.x, box.min.y, box.min.z],
322
+ max: [box.max.x, box.max.y, box.max.z],
323
+ };
324
+ }
325
+ }
326
+
327
+ if (!resolvedBounds) {
328
+ resolvedBounds = {
329
+ min: [-0.5, 0, -0.5],
330
+ max: [0.5, 1.0, 0.5],
331
+ };
332
+ }
333
+
334
+ const framing = computeCameraFramingParameters(resolvedBounds, {
335
+ fovDeg: typeof camera.fov === 'number' ? camera.fov : 45,
336
+ paddingFactor,
337
+ });
338
+
339
+ if (camera.position && typeof camera.position.set === 'function') {
340
+ camera.position.set(framing.position[0], framing.position[1], framing.position[2]);
341
+ }
342
+ camera.near = framing.near;
343
+ camera.far = framing.far;
344
+ if (typeof camera.updateProjectionMatrix === 'function') {
345
+ camera.updateProjectionMatrix();
346
+ }
347
+
348
+ if (controls && controls.target && typeof controls.target.set === 'function') {
349
+ controls.target.set(framing.center[0], framing.center[1], framing.center[2]);
350
+ if (typeof controls.update === 'function') {
351
+ controls.update();
352
+ }
353
+ } else if (typeof camera.lookAt === 'function') {
354
+ camera.lookAt(framing.center[0], framing.center[1], framing.center[2]);
355
+ }
356
+
357
+ return framing;
358
+ }
359
+
360
+ /**
361
+ * Traverses a Three.js scene graph and deterministically disposes geometries,
362
+ * materials, and attached textures to prevent WebGL memory leaks on unmount.
363
+ *
364
+ * @param {object} rootObject - `THREE.Object3D` (e.g., `gltf.scene`)
365
+ * @returns {{ geometriesDisposed: number, materialsDisposed: number, texturesDisposed: number }}
366
+ */
367
+ export function disposeGltfScene(rootObject) {
368
+ const stats = {
369
+ geometriesDisposed: 0,
370
+ materialsDisposed: 0,
371
+ texturesDisposed: 0,
372
+ };
373
+
374
+ if (!rootObject || typeof rootObject.traverse !== 'function') {
375
+ return stats;
376
+ }
377
+
378
+ const disposedGeometries = new Set();
379
+ const disposedMaterials = new Set();
380
+ const disposedTextures = new Set();
381
+
382
+ function disposeMaterial(mat) {
383
+ if (!mat || typeof mat !== 'object' || disposedMaterials.has(mat)) return;
384
+ disposedMaterials.add(mat);
385
+
386
+ for (const value of Object.values(mat)) {
387
+ if (
388
+ value &&
389
+ typeof value === 'object' &&
390
+ (value.isTexture === true || typeof value.dispose === 'function') &&
391
+ value !== mat &&
392
+ !Array.isArray(value)
393
+ ) {
394
+ if (!disposedTextures.has(value) && typeof value.dispose === 'function') {
395
+ disposedTextures.add(value);
396
+ value.dispose();
397
+ stats.texturesDisposed += 1;
398
+ }
399
+ }
400
+ }
401
+
402
+ if (typeof mat.dispose === 'function') {
403
+ mat.dispose();
404
+ stats.materialsDisposed += 1;
405
+ }
406
+ }
407
+
408
+ rootObject.traverse((node) => {
409
+ if (!node || typeof node !== 'object') return;
410
+ if (node.geometry && !disposedGeometries.has(node.geometry)) {
411
+ disposedGeometries.add(node.geometry);
412
+ if (typeof node.geometry.dispose === 'function') {
413
+ node.geometry.dispose();
414
+ stats.geometriesDisposed += 1;
415
+ }
416
+ }
417
+ if (Array.isArray(node.material)) {
418
+ for (const m of node.material) disposeMaterial(m);
419
+ } else if (node.material) {
420
+ disposeMaterial(node.material);
421
+ }
422
+ });
423
+
424
+ return stats;
425
+ }
426
+
427
+ /**
428
+ * Extracts a clean animation summary from loaded `gltf.animations` clips.
429
+ *
430
+ * @param {Array<object>} animations
431
+ * @returns {Array<{ index: number, name: string, durationSeconds: number, trackCount: number }>}
432
+ */
433
+ export function extractAnimationClipSummary(animations = []) {
434
+ if (!Array.isArray(animations)) return [];
435
+ return animations.map((clip, idx) => ({
436
+ index: idx,
437
+ name: typeof clip?.name === 'string' && clip.name.length > 0 ? clip.name : `clip_${idx}`,
438
+ durationSeconds:
439
+ typeof clip?.duration === 'number' && Number.isFinite(clip.duration)
440
+ ? Number(clip.duration.toFixed(4))
441
+ : 0,
442
+ trackCount: Array.isArray(clip?.tracks) ? clip.tracks.length : 0,
443
+ }));
444
+ }
445
+
446
+ /**
447
+ * Creates a managed Three.js GLB viewer controller. Accepts injected Three.js
448
+ * classes via `options.threeModules` (for testing or custom builds) or dynamically
449
+ * imports `three` and its official `three/addons/*` modules in browser/bundler environments.
450
+ *
451
+ * @param {object} options
452
+ * @param {HTMLElement} options.container - DOM element to mount the canvas into
453
+ * @param {object} [options.manifest] - BlendOps GLB handoff manifest
454
+ * @param {string} [options.assetUrl] - Override URL for the `.glb` asset
455
+ * @param {object} [options.decoderPaths] - Custom decoder paths
456
+ * @param {object} [options.threeModules] - Optional dependency injection `{ THREE, GLTFLoader, DRACOLoader, KTX2Loader, OrbitControls, RoomEnvironment, MeshoptDecoder }`
457
+ * @param {(progress: { loaded: number, total: number, ratio: number | null }) => void} [options.onProgress]
458
+ * @param {(result: object) => void} [options.onLoad]
459
+ * @param {(error: Error) => void} [options.onError]
460
+ */
461
+ export async function createThreeGlbViewer(options = {}) {
462
+ if (!options || !options.container) {
463
+ throw new TypeError('createThreeGlbViewer requires options.container');
464
+ }
465
+
466
+ const config = resolveViewerManifestConfig({
467
+ ...(options.manifest || {}),
468
+ ...(options.assetUrl ? { assetUrl: options.assetUrl } : {}),
469
+ });
470
+
471
+ let modules = options.threeModules;
472
+ if (!modules || !modules.THREE || !modules.GLTFLoader) {
473
+ const [
474
+ THREE,
475
+ { GLTFLoader },
476
+ { OrbitControls },
477
+ { RoomEnvironment },
478
+ dracoMod,
479
+ ktx2Mod,
480
+ meshoptMod,
481
+ ] = await Promise.all([
482
+ import('three'),
483
+ import('three/addons/loaders/GLTFLoader.js'),
484
+ import('three/addons/controls/OrbitControls.js'),
485
+ import('three/addons/environments/RoomEnvironment.js'),
486
+ config.requiresDraco ? import('three/addons/loaders/DRACOLoader.js') : Promise.resolve({}),
487
+ config.requiresKtx2 ? import('three/addons/loaders/KTX2Loader.js') : Promise.resolve({}),
488
+ config.requiresMeshopt
489
+ ? import('three/addons/libs/meshopt_decoder.module.js')
490
+ : Promise.resolve({}),
491
+ ]);
492
+
493
+ modules = {
494
+ THREE,
495
+ GLTFLoader,
496
+ OrbitControls,
497
+ RoomEnvironment,
498
+ DRACOLoader: dracoMod.DRACOLoader,
499
+ KTX2Loader: ktx2Mod.KTX2Loader,
500
+ MeshoptDecoder: meshoptMod.MeshoptDecoder,
501
+ };
502
+ }
503
+
504
+ const { THREE, GLTFLoader, OrbitControls, RoomEnvironment } = modules;
505
+ const container = options.container;
506
+ const width = Math.max(container.clientWidth || 800, 1);
507
+ const height = Math.max(container.clientHeight || 600, 1);
508
+
509
+ const scene = new THREE.Scene();
510
+ const camera = new THREE.PerspectiveCamera(45, width / height, 0.01, 1000);
511
+ const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
512
+
513
+ if ('outputColorSpace' in renderer && THREE.SRGBColorSpace) {
514
+ renderer.outputColorSpace =
515
+ config.outputColorSpace === 'srgb-linear' && THREE.LinearSRGBColorSpace
516
+ ? THREE.LinearSRGBColorSpace
517
+ : THREE.SRGBColorSpace;
518
+ }
519
+ if ('toneMapping' in renderer && THREE.ACESFilmicToneMapping) {
520
+ renderer.toneMapping = THREE[config.toneMapping] ?? THREE.ACESFilmicToneMapping;
521
+ renderer.toneMappingExposure = 1.0;
522
+ }
523
+ if (typeof renderer.setSize === 'function') {
524
+ renderer.setSize(width, height);
525
+ }
526
+ if (renderer.domElement && typeof container.appendChild === 'function') {
527
+ container.appendChild(renderer.domElement);
528
+ }
529
+
530
+ let pmremGenerator = null;
531
+ let envRenderTarget = null;
532
+ if (typeof THREE.PMREMGenerator === 'function' && typeof RoomEnvironment === 'function') {
533
+ pmremGenerator = new THREE.PMREMGenerator(renderer);
534
+ const roomEnv = new RoomEnvironment();
535
+ envRenderTarget = pmremGenerator.fromScene(roomEnv, 0.04);
536
+ scene.environment = envRenderTarget.texture;
537
+ if (typeof roomEnv.dispose === 'function') {
538
+ roomEnv.dispose();
539
+ }
540
+ }
541
+
542
+ const controls =
543
+ typeof OrbitControls === 'function' ? new OrbitControls(camera, renderer.domElement) : null;
544
+ if (controls) {
545
+ controls.enableDamping = true;
546
+ controls.dampingFactor = 0.05;
547
+ }
548
+
549
+ const loader = new GLTFLoader();
550
+ const { decoderConfig, disposeDecoders } = configureGltfDecoders(loader, {
551
+ manifest: options.manifest || config,
552
+ renderer,
553
+ DRACOLoader: modules.DRACOLoader,
554
+ KTX2Loader: modules.KTX2Loader,
555
+ MeshoptDecoder: modules.MeshoptDecoder,
556
+ decoderPaths: options.decoderPaths,
557
+ });
558
+
559
+ let loadedRoot = null;
560
+ let mixer = null;
561
+ let disposed = false;
562
+
563
+ const loadAsset = (url = config.assetUrl) =>
564
+ new Promise((resolve, reject) => {
565
+ loader.load(
566
+ url,
567
+ (gltf) => {
568
+ if (disposed) return;
569
+ if (loadedRoot) {
570
+ scene.remove(loadedRoot);
571
+ disposeGltfScene(loadedRoot);
572
+ }
573
+ loadedRoot = gltf.scene;
574
+ scene.add(loadedRoot);
575
+
576
+ const framing = frameCameraToBoundingBox({
577
+ camera,
578
+ controls,
579
+ rootObject: loadedRoot,
580
+ THREE,
581
+ bounds: config.estimatedBounds?.available ? config.estimatedBounds : null,
582
+ });
583
+
584
+ const clipSummary = extractAnimationClipSummary(gltf.animations || []);
585
+ if (
586
+ Array.isArray(gltf.animations) &&
587
+ gltf.animations.length > 0 &&
588
+ typeof THREE.AnimationMixer === 'function'
589
+ ) {
590
+ mixer = new THREE.AnimationMixer(loadedRoot);
591
+ const defaultAction = mixer.clipAction(gltf.animations[0]);
592
+ if (defaultAction && typeof defaultAction.play === 'function') {
593
+ defaultAction.play();
594
+ }
595
+ }
596
+
597
+ const payload = {
598
+ gltf,
599
+ scene: loadedRoot,
600
+ framing,
601
+ animations: clipSummary,
602
+ decoderConfig,
603
+ config,
604
+ };
605
+ if (typeof options.onLoad === 'function') {
606
+ options.onLoad(payload);
607
+ }
608
+ resolve(payload);
609
+ },
610
+ (evt) => {
611
+ if (typeof options.onProgress === 'function') {
612
+ const loaded = Number(evt?.loaded || 0);
613
+ const total = Number(evt?.total || 0);
614
+ options.onProgress({
615
+ loaded,
616
+ total,
617
+ ratio: total > 0 ? Number((loaded / total).toFixed(4)) : null,
618
+ });
619
+ }
620
+ },
621
+ (err) => {
622
+ const wrapped =
623
+ err instanceof Error
624
+ ? err
625
+ : new Error(`Failed to load GLB asset "${url}": ${String(err)}`);
626
+ if (typeof options.onError === 'function') {
627
+ options.onError(wrapped);
628
+ }
629
+ reject(wrapped);
630
+ },
631
+ );
632
+ });
633
+
634
+ const resize = () => {
635
+ if (disposed) return;
636
+ const w = Math.max(container.clientWidth || 800, 1);
637
+ const h = Math.max(container.clientHeight || 600, 1);
638
+ camera.aspect = w / h;
639
+ if (typeof camera.updateProjectionMatrix === 'function') {
640
+ camera.updateProjectionMatrix();
641
+ }
642
+ if (typeof renderer.setSize === 'function') {
643
+ renderer.setSize(w, h);
644
+ }
645
+ };
646
+
647
+ const stepFrame = (deltaSeconds = 1 / 60) => {
648
+ if (disposed) return;
649
+ if (mixer && typeof mixer.update === 'function') {
650
+ mixer.update(deltaSeconds);
651
+ }
652
+ if (controls && typeof controls.update === 'function') {
653
+ controls.update();
654
+ }
655
+ if (typeof renderer.render === 'function') {
656
+ renderer.render(scene, camera);
657
+ }
658
+ };
659
+
660
+ const dispose = () => {
661
+ if (disposed) return { alreadyDisposed: true };
662
+ disposed = true;
663
+ if (mixer && typeof mixer.stopAllAction === 'function') {
664
+ mixer.stopAllAction();
665
+ }
666
+ const disposalStats = loadedRoot
667
+ ? disposeGltfScene(loadedRoot)
668
+ : { geometriesDisposed: 0, materialsDisposed: 0, texturesDisposed: 0 };
669
+ if (loadedRoot) {
670
+ scene.remove(loadedRoot);
671
+ loadedRoot = null;
672
+ }
673
+ disposeDecoders();
674
+ if (controls && typeof controls.dispose === 'function') {
675
+ controls.dispose();
676
+ }
677
+ if (envRenderTarget && typeof envRenderTarget.dispose === 'function') {
678
+ envRenderTarget.dispose();
679
+ }
680
+ if (pmremGenerator && typeof pmremGenerator.dispose === 'function') {
681
+ pmremGenerator.dispose();
682
+ }
683
+ if (typeof renderer.dispose === 'function') {
684
+ renderer.dispose();
685
+ }
686
+ if (
687
+ renderer.domElement &&
688
+ renderer.domElement.parentNode === container &&
689
+ typeof container.removeChild === 'function'
690
+ ) {
691
+ container.removeChild(renderer.domElement);
692
+ }
693
+ return { alreadyDisposed: false, ...disposalStats };
694
+ };
695
+
696
+ return {
697
+ config,
698
+ decoderConfig,
699
+ scene,
700
+ camera,
701
+ renderer,
702
+ controls,
703
+ loader,
704
+ loadAsset,
705
+ resize,
706
+ stepFrame,
707
+ dispose,
708
+ };
709
+ }