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.
- package/CHANGELOG.md +74 -0
- package/LICENSE +21 -0
- package/README.md +208 -2
- package/bin/blendops.mjs +4 -0
- package/bundles/claude-desktop-manual/BLENDOPS_SINGLE_FILE.md +78 -0
- package/bundles/claude-desktop-manual/IMPORT_STEPS.md +43 -0
- package/bundles/claude-desktop-manual/INSTALL_REPORT_TEMPLATE.md +13 -0
- package/bundles/claude-desktop-manual/README.md +70 -0
- package/bundles/claude-desktop-manual/SKILL.md +62 -0
- package/bundles/claude-desktop-manual/manifest.json +278 -0
- package/bundles/claude-desktop-manual/references/evidence-rules.md +13 -0
- package/bundles/claude-desktop-manual/references/install-boundary.md +13 -0
- package/bundles/claude-desktop-manual/references/laws/evidence-before-done.md +14 -0
- package/bundles/claude-desktop-manual/references/laws/no-arbitrary-python-interface.md +12 -0
- package/bundles/claude-desktop-manual/references/laws/non-blender-user-language.md +13 -0
- package/bundles/claude-desktop-manual/references/laws/official-runtime-only.md +20 -0
- package/bundles/claude-desktop-manual/references/packs/product-hero-v0.md +30 -0
- package/bundles/claude-desktop-manual/references/runtime-stacks.md +13 -0
- package/bundles/claude-desktop-manual/references/skill-map.md +36 -0
- package/bundles/claude-desktop-manual/references/skills/acceptance-criteria-builder.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/asset-discovery.md +73 -0
- package/bundles/claude-desktop-manual/references/skills/asset-fallback-strategy.md +66 -0
- package/bundles/claude-desktop-manual/references/skills/asset-library-plan.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/asset-license-checker.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/asset-style-check.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/blender-brainstorming.md +62 -0
- package/bundles/claude-desktop-manual/references/skills/blender-recipe-decomposer.md +66 -0
- package/bundles/claude-desktop-manual/references/skills/blender-troubleshooting.md +78 -0
- package/bundles/claude-desktop-manual/references/skills/blendops-help.md +82 -0
- package/bundles/claude-desktop-manual/references/skills/bridge-conflicts.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/camera-composition.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/character-portrait.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/cli-appendix-job-outline.md +62 -0
- package/bundles/claude-desktop-manual/references/skills/color-management-decision.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/composition-quality-checker.md +71 -0
- package/bundles/claude-desktop-manual/references/skills/cycles-vs-eevee-decision.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/done-criteria.md +70 -0
- package/bundles/claude-desktop-manual/references/skills/environment-shot.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/glb-animation-handoff.md +69 -0
- package/bundles/claude-desktop-manual/references/skills/glb-web-handoff.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/intent-to-3d-brief-writer.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/interior-scene.md +73 -0
- package/bundles/claude-desktop-manual/references/skills/lighting-material-plan.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/lighting-quality-checker.md +70 -0
- package/bundles/claude-desktop-manual/references/skills/material-quality-checker.md +71 -0
- package/bundles/claude-desktop-manual/references/skills/mobile-glb-budget.md +73 -0
- package/bundles/claude-desktop-manual/references/skills/output-format-decision.md +63 -0
- package/bundles/claude-desktop-manual/references/skills/pack-prerequisite-checker.md +74 -0
- package/bundles/claude-desktop-manual/references/skills/path-one-host-outline.md +66 -0
- package/bundles/claude-desktop-manual/references/skills/plain-language-response.md +70 -0
- package/bundles/claude-desktop-manual/references/skills/polycount-budget-checker.md +71 -0
- package/bundles/claude-desktop-manual/references/skills/pre-handoff-verification.md +76 -0
- package/bundles/claude-desktop-manual/references/skills/preview-report.md +62 -0
- package/bundles/claude-desktop-manual/references/skills/product-grid-scene-planner.md +72 -0
- package/bundles/claude-desktop-manual/references/skills/product-hero-scene-planner.md +68 -0
- package/bundles/claude-desktop-manual/references/skills/r3f-component-plan.md +66 -0
- package/bundles/claude-desktop-manual/references/skills/recipe-fit-assessor.md +75 -0
- package/bundles/claude-desktop-manual/references/skills/render-export-evidence.md +70 -0
- package/bundles/claude-desktop-manual/references/skills/resolution-aspect-decision.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/runtime-attempt-report.md +67 -0
- package/bundles/claude-desktop-manual/references/skills/runtime-path-picker.md +67 -0
- package/bundles/claude-desktop-manual/references/skills/runtime-readiness.md +63 -0
- package/bundles/claude-desktop-manual/references/skills/runtime-setup.md +63 -0
- package/bundles/claude-desktop-manual/references/skills/scene-readiness.md +65 -0
- package/bundles/claude-desktop-manual/references/skills/scope-guard.md +62 -0
- package/bundles/claude-desktop-manual/references/skills/stage-gates.md +91 -0
- package/bundles/claude-desktop-manual/references/skills/workflow-stage-router.md +67 -0
- package/bundles/generic-project-local/BLENDOPS.md +71 -0
- package/bundles/generic-project-local/INSTALL_REPORT_TEMPLATE.md +52 -0
- package/bundles/generic-project-local/README.md +73 -0
- package/bundles/generic-project-local/ROLLBACK.md +66 -0
- package/bundles/generic-project-local/manifest.json +66 -0
- package/bundles/skill-package/README.md +54 -0
- package/bundles/skill-package/blendops/LICENSE.txt +21 -0
- package/bundles/skill-package/blendops/SKILL.md +50 -0
- package/bundles/skill-package/blendops/agents/README.md +61 -0
- package/bundles/skill-package/blendops/agents/openai.yaml +4 -0
- package/bundles/skill-package/blendops/references/evidence-rules.md +17 -0
- package/bundles/skill-package/blendops/references/install-boundary.md +13 -0
- package/bundles/skill-package/blendops/references/law-evidence-before-done.md +12 -0
- package/bundles/skill-package/blendops/references/law-no-arbitrary-python-interface.md +7 -0
- package/bundles/skill-package/blendops/references/law-non-blender-user-language.md +8 -0
- package/bundles/skill-package/blendops/references/law-official-runtime-only.md +9 -0
- package/bundles/skill-package/blendops/references/pack-product-hero-v0.md +21 -0
- package/bundles/skill-package/blendops/references/runtime-stacks.md +13 -0
- package/bundles/skill-package/blendops/references/skill-acceptance-criteria-builder.md +51 -0
- package/bundles/skill-package/blendops/references/skill-asset-discovery.md +54 -0
- package/bundles/skill-package/blendops/references/skill-asset-fallback-strategy.md +48 -0
- package/bundles/skill-package/blendops/references/skill-asset-library-plan.md +51 -0
- package/bundles/skill-package/blendops/references/skill-asset-license-checker.md +51 -0
- package/bundles/skill-package/blendops/references/skill-asset-style-check.md +52 -0
- package/bundles/skill-package/blendops/references/skill-blender-brainstorming.md +43 -0
- package/bundles/skill-package/blendops/references/skill-blender-recipe-decomposer.md +48 -0
- package/bundles/skill-package/blendops/references/skill-blender-troubleshooting.md +59 -0
- package/bundles/skill-package/blendops/references/skill-blendops-help.md +62 -0
- package/bundles/skill-package/blendops/references/skill-bridge-conflicts.md +48 -0
- package/bundles/skill-package/blendops/references/skill-camera-composition.md +48 -0
- package/bundles/skill-package/blendops/references/skill-character-portrait.md +50 -0
- package/bundles/skill-package/blendops/references/skill-cli-appendix-job-outline.md +44 -0
- package/bundles/skill-package/blendops/references/skill-color-management-decision.md +50 -0
- package/bundles/skill-package/blendops/references/skill-composition-quality-checker.md +53 -0
- package/bundles/skill-package/blendops/references/skill-cycles-vs-eevee-decision.md +47 -0
- package/bundles/skill-package/blendops/references/skill-done-criteria.md +53 -0
- package/bundles/skill-package/blendops/references/skill-environment-shot.md +47 -0
- package/bundles/skill-package/blendops/references/skill-glb-animation-handoff.md +51 -0
- package/bundles/skill-package/blendops/references/skill-glb-web-handoff.md +51 -0
- package/bundles/skill-package/blendops/references/skill-intent-to-3d-brief-writer.md +50 -0
- package/bundles/skill-package/blendops/references/skill-interior-scene.md +54 -0
- package/bundles/skill-package/blendops/references/skill-lighting-material-plan.md +48 -0
- package/bundles/skill-package/blendops/references/skill-lighting-quality-checker.md +52 -0
- package/bundles/skill-package/blendops/references/skill-map.md +32 -0
- package/bundles/skill-package/blendops/references/skill-material-quality-checker.md +53 -0
- package/bundles/skill-package/blendops/references/skill-mobile-glb-budget.md +55 -0
- package/bundles/skill-package/blendops/references/skill-output-format-decision.md +46 -0
- package/bundles/skill-package/blendops/references/skill-pack-prerequisite-checker.md +56 -0
- package/bundles/skill-package/blendops/references/skill-path-one-host-outline.md +48 -0
- package/bundles/skill-package/blendops/references/skill-plain-language-response.md +53 -0
- package/bundles/skill-package/blendops/references/skill-polycount-budget-checker.md +53 -0
- package/bundles/skill-package/blendops/references/skill-pre-handoff-verification.md +57 -0
- package/bundles/skill-package/blendops/references/skill-preview-report.md +45 -0
- package/bundles/skill-package/blendops/references/skill-product-grid-scene-planner.md +54 -0
- package/bundles/skill-package/blendops/references/skill-product-hero-scene-planner.md +51 -0
- package/bundles/skill-package/blendops/references/skill-r3f-component-plan.md +48 -0
- package/bundles/skill-package/blendops/references/skill-recipe-fit-assessor.md +57 -0
- package/bundles/skill-package/blendops/references/skill-render-export-evidence.md +51 -0
- package/bundles/skill-package/blendops/references/skill-resolution-aspect-decision.md +48 -0
- package/bundles/skill-package/blendops/references/skill-runtime-attempt-report.md +49 -0
- package/bundles/skill-package/blendops/references/skill-runtime-path-picker.md +49 -0
- package/bundles/skill-package/blendops/references/skill-runtime-readiness.md +45 -0
- package/bundles/skill-package/blendops/references/skill-runtime-setup.md +45 -0
- package/bundles/skill-package/blendops/references/skill-scene-readiness.md +48 -0
- package/bundles/skill-package/blendops/references/skill-scope-guard.md +44 -0
- package/bundles/skill-package/blendops/references/skill-stage-gates.md +73 -0
- package/bundles/skill-package/blendops/references/skill-workflow-stage-router.md +49 -0
- package/docs/README.md +276 -0
- package/docs/examples/glb-web-handoff/README.md +174 -0
- package/docs/examples/glb-web-handoff/r3f-glb-viewer.tsx +320 -0
- package/docs/examples/glb-web-handoff/threejs-glb-viewer.mjs +709 -0
- package/docs/knowledge-and-recipe-catalog.md +236 -0
- package/docs/recipes/README.md +27 -0
- package/docs/recipes/cyberpunk-shoe-hero.md +97 -0
- package/docs/workflows/README.md +14 -0
- package/docs/workflows/full-non-blender-user-workflow.md +210 -0
- package/docs/workflows/product-hero-workflow.md +92 -0
- package/laws/README.md +32 -0
- package/laws/evidence-before-done.md +37 -0
- package/laws/no-arbitrary-python-interface.md +32 -0
- package/laws/non-blender-user-language.md +32 -0
- package/laws/official-runtime-only.md +78 -0
- package/package.json +103 -4
- package/packs/README.md +11 -0
- package/packs/product-hero-v0/PACK.md +114 -0
- package/registry/catalog-index.json +21344 -0
- package/registry/compatibility-matrix.json +533 -0
- package/registry/contract-context-fields.json +391 -0
- package/registry/knowledge-catalog.json +4648 -0
- package/registry/knowledge-sources.json +438 -0
- package/registry/recipe-catalog.json +2565 -0
- package/registry/runtime-capability-policy.json +525 -0
- package/registry/runtime-operations.json +4468 -0
- package/registry/skills.json +10231 -0
- package/registry/workflow-graph.json +7390 -0
- package/schemas/adapter-compatibility-matrix.schema.json +166 -0
- package/schemas/contract-context-fields.schema.json +147 -0
- package/schemas/execution-plan.schema.json +325 -0
- package/schemas/glb-web-handoff-manifest.schema.json +744 -0
- package/schemas/knowledge-record.schema.json +460 -0
- package/schemas/knowledge-source-registry.schema.json +268 -0
- package/schemas/operation-execution-ledger.schema.json +348 -0
- package/schemas/recipe-record.schema.json +469 -0
- package/schemas/runtime-capability-policy.schema.json +184 -0
- package/schemas/runtime-evidence-packet.schema.json +211 -0
- package/schemas/runtime-operations.schema.json +535 -0
- package/schemas/runtime-qualification-report.schema.json +540 -0
- package/schemas/runtime-session.schema.json +350 -0
- package/schemas/scene-spec.schema.json +624 -0
- package/schemas/skill-contract.schema.json +402 -0
- package/schemas/skill-eval.schema.json +509 -0
- package/scripts/build-knowledge-catalog.mjs +2376 -0
- package/scripts/compile-scene-plan.mjs +1945 -0
- package/scripts/export-claude-skills.mjs +634 -0
- package/scripts/generate-glb-handoff-report.mjs +2376 -0
- package/scripts/inspect-glb.mjs +1627 -0
- package/scripts/install-skills.mjs +5443 -0
- package/scripts/runtime-orchestrator.mjs +7713 -0
- package/scripts/validate-capability-policy.mjs +531 -0
- package/scripts/validate-evidence-packet.mjs +256 -0
- package/skills/README.md +315 -0
- package/skills/_template/SKILL.md +296 -0
- package/skills/acceptance-criteria-builder/EVAL.md +25 -0
- package/skills/acceptance-criteria-builder/SKILL.md +257 -0
- package/skills/acceptance-criteria-builder/contract.json +205 -0
- package/skills/acceptance-criteria-builder/references/brief-to-criteria-mapper.md +22 -0
- package/skills/acceptance-criteria-builder/references/checklist-patterns.md +22 -0
- package/skills/acceptance-criteria-builder/references/evidence-hook-rules.md +19 -0
- package/skills/asset-discovery/EVAL.md +81 -0
- package/skills/asset-discovery/SKILL.md +252 -0
- package/skills/asset-discovery/contract.json +291 -0
- package/skills/asset-discovery/references/asset-strategy-decision-tree.md +40 -0
- package/skills/asset-discovery/references/budget-reconciliation-patterns.md +54 -0
- package/skills/asset-discovery/references/license-confidence-table.md +41 -0
- package/skills/asset-fallback-strategy/EVAL.md +34 -0
- package/skills/asset-fallback-strategy/SKILL.md +248 -0
- package/skills/asset-fallback-strategy/contract.json +190 -0
- package/skills/asset-fallback-strategy/references/drop-with-caveat-rules.md +36 -0
- package/skills/asset-fallback-strategy/references/fallback-option-types.md +55 -0
- package/skills/asset-fallback-strategy/references/scoring-rubric.md +61 -0
- package/skills/asset-library-plan/EVAL.md +28 -0
- package/skills/asset-library-plan/SKILL.md +263 -0
- package/skills/asset-library-plan/contract.json +177 -0
- package/skills/asset-library-plan/references/folder-structure-rules.md +63 -0
- package/skills/asset-library-plan/references/metadata-schema.md +62 -0
- package/skills/asset-library-plan/references/naming-rules.md +51 -0
- package/skills/asset-license-checker/EVAL.md +33 -0
- package/skills/asset-license-checker/SKILL.md +245 -0
- package/skills/asset-license-checker/contract.json +172 -0
- package/skills/asset-license-checker/references/attribution-rendering-patterns.md +48 -0
- package/skills/asset-license-checker/references/common-license-mapping.md +39 -0
- package/skills/asset-license-checker/references/license-source-rules.md +38 -0
- package/skills/asset-style-check/EVAL.md +26 -0
- package/skills/asset-style-check/SKILL.md +238 -0
- package/skills/asset-style-check/contract.json +251 -0
- package/skills/asset-style-check/references/drift-classification.md +40 -0
- package/skills/asset-style-check/references/intentional-mixed-style.md +39 -0
- package/skills/asset-style-check/references/style-axes.md +46 -0
- package/skills/blender-brainstorming/EVAL.md +79 -0
- package/skills/blender-brainstorming/SKILL.md +228 -0
- package/skills/blender-brainstorming/contract.json +115 -0
- package/skills/blender-brainstorming/references/alternative-scoping-templates.md +43 -0
- package/skills/blender-brainstorming/references/clarification-patterns.md +29 -0
- package/skills/blender-brainstorming/references/intent-summary-style-guide.md +25 -0
- package/skills/blender-recipe-decomposer/EVAL.md +35 -0
- package/skills/blender-recipe-decomposer/SKILL.md +258 -0
- package/skills/blender-recipe-decomposer/contract.json +152 -0
- package/skills/blender-recipe-decomposer/references/dependency-patterns.md +53 -0
- package/skills/blender-recipe-decomposer/references/recipe-grouping-rules.md +58 -0
- package/skills/blender-recipe-decomposer/references/recipe-naming-rules.md +44 -0
- package/skills/blender-troubleshooting/EVAL.md +78 -0
- package/skills/blender-troubleshooting/SKILL.md +263 -0
- package/skills/blender-troubleshooting/contract.json +352 -0
- package/skills/blender-troubleshooting/references/common-symptom-playbooks.md +51 -0
- package/skills/blender-troubleshooting/references/divergence-routing-table.md +23 -0
- package/skills/blender-troubleshooting/references/four-phase-template.md +51 -0
- package/skills/blendops-help/EVAL.md +67 -0
- package/skills/blendops-help/SKILL.md +312 -0
- package/skills/blendops-help/contract.json +229 -0
- package/skills/blendops-help/references/lifecycle-phases.md +91 -0
- package/skills/blendops-help/references/quick-start-prompts.md +65 -0
- package/skills/blendops-help/references/routing-decision-tree.md +57 -0
- package/skills/bridge-conflicts/EVAL.md +83 -0
- package/skills/bridge-conflicts/SKILL.md +246 -0
- package/skills/bridge-conflicts/contract.json +145 -0
- package/skills/bridge-conflicts/references/bridge-state-matrix-template.md +82 -0
- package/skills/bridge-conflicts/references/conflict-playbooks.md +99 -0
- package/skills/bridge-conflicts/references/do-not-reminders.md +42 -0
- package/skills/camera-composition/EVAL.md +32 -0
- package/skills/camera-composition/SKILL.md +196 -0
- package/skills/camera-composition/contract.json +180 -0
- package/skills/camera-composition/references/camera-presets.md +30 -0
- package/skills/camera-composition/references/camera-rubric.md +24 -0
- package/skills/camera-composition/references/hero-composition-patterns.md +24 -0
- package/skills/camera-composition/references/web-layout-negative-space.md +25 -0
- package/skills/character-portrait/EVAL.md +42 -0
- package/skills/character-portrait/SKILL.md +245 -0
- package/skills/character-portrait/contract.json +205 -0
- package/skills/character-portrait/references/portrait-framing-rules.md +39 -0
- package/skills/character-portrait/references/portrait-lighting-patterns.md +50 -0
- package/skills/character-portrait/references/style-consistency-rules.md +41 -0
- package/skills/cli-appendix-job-outline/EVAL.md +26 -0
- package/skills/cli-appendix-job-outline/SKILL.md +252 -0
- package/skills/cli-appendix-job-outline/contract.json +147 -0
- package/skills/cli-appendix-job-outline/references/flag-order-reminders.md +16 -0
- package/skills/cli-appendix-job-outline/references/job-type-matrix.md +13 -0
- package/skills/cli-appendix-job-outline/references/stateless-limitations.md +12 -0
- package/skills/color-management-decision/EVAL.md +28 -0
- package/skills/color-management-decision/SKILL.md +254 -0
- package/skills/color-management-decision/contract.json +162 -0
- package/skills/color-management-decision/references/look-comparison.md +44 -0
- package/skills/color-management-decision/references/per-channel-rules.md +49 -0
- package/skills/color-management-decision/references/pipeline-mapping.md +47 -0
- package/skills/composition-quality-checker/EVAL.md +38 -0
- package/skills/composition-quality-checker/SKILL.md +260 -0
- package/skills/composition-quality-checker/contract.json +221 -0
- package/skills/composition-quality-checker/references/aspect-ratio-rules.md +37 -0
- package/skills/composition-quality-checker/references/composition-rules.md +58 -0
- package/skills/composition-quality-checker/references/headroom-leadroom-rules.md +46 -0
- package/skills/cycles-vs-eevee-decision/EVAL.md +26 -0
- package/skills/cycles-vs-eevee-decision/SKILL.md +249 -0
- package/skills/cycles-vs-eevee-decision/contract.json +142 -0
- package/skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md +39 -0
- package/skills/cycles-vs-eevee-decision/references/gpu-device-rules.md +51 -0
- package/skills/cycles-vs-eevee-decision/references/samples-by-quality.md +53 -0
- package/skills/done-criteria/EVAL.md +33 -0
- package/skills/done-criteria/SKILL.md +225 -0
- package/skills/done-criteria/contract.json +199 -0
- package/skills/done-criteria/references/done-vs-perfect.md +56 -0
- package/skills/done-criteria/references/out-of-scope-patterns.md +50 -0
- package/skills/done-criteria/references/stop-condition-templates.md +39 -0
- package/skills/environment-shot/EVAL.md +44 -0
- package/skills/environment-shot/SKILL.md +237 -0
- package/skills/environment-shot/contract.json +162 -0
- package/skills/environment-shot/references/depth-layering-rules.md +49 -0
- package/skills/environment-shot/references/time-and-weather-rules.md +35 -0
- package/skills/environment-shot/references/wide-shot-camera-rules.md +51 -0
- package/skills/glb-animation-handoff/EVAL.md +39 -0
- package/skills/glb-animation-handoff/SKILL.md +271 -0
- package/skills/glb-animation-handoff/contract.json +247 -0
- package/skills/glb-animation-handoff/references/animation-types.md +36 -0
- package/skills/glb-animation-handoff/references/transition-rules.md +55 -0
- package/skills/glb-animation-handoff/references/web-stack-caveats.md +40 -0
- package/skills/glb-web-handoff/EVAL.md +33 -0
- package/skills/glb-web-handoff/SKILL.md +212 -0
- package/skills/glb-web-handoff/contract.json +171 -0
- package/skills/glb-web-handoff/references/artifact-status-language.md +26 -0
- package/skills/glb-web-handoff/references/glb-handoff-checklist.md +30 -0
- package/skills/glb-web-handoff/references/performance-caveats.md +26 -0
- package/skills/glb-web-handoff/references/threejs-r3f-handoff.md +28 -0
- package/skills/intent-to-3d-brief-writer/EVAL.md +82 -0
- package/skills/intent-to-3d-brief-writer/SKILL.md +238 -0
- package/skills/intent-to-3d-brief-writer/contract.json +195 -0
- package/skills/intent-to-3d-brief-writer/references/acceptance-criteria-patterns.md +46 -0
- package/skills/intent-to-3d-brief-writer/references/eight-slot-template.md +123 -0
- package/skills/intent-to-3d-brief-writer/references/mixed-audience-handling.md +39 -0
- package/skills/interior-scene/EVAL.md +44 -0
- package/skills/interior-scene/SKILL.md +261 -0
- package/skills/interior-scene/contract.json +277 -0
- package/skills/interior-scene/references/furniture-layout-rules.md +51 -0
- package/skills/interior-scene/references/interior-architecture-rules.md +47 -0
- package/skills/interior-scene/references/interior-camera-rules.md +47 -0
- package/skills/lighting-material-plan/EVAL.md +32 -0
- package/skills/lighting-material-plan/SKILL.md +194 -0
- package/skills/lighting-material-plan/contract.json +213 -0
- package/skills/lighting-material-plan/references/cyberpunk-lookdev.md +22 -0
- package/skills/lighting-material-plan/references/lighting-patterns.md +30 -0
- package/skills/lighting-material-plan/references/material-portability.md +25 -0
- package/skills/lighting-material-plan/references/reflective-floor-pattern.md +22 -0
- package/skills/lighting-material-plan/references/web-material-simplification.md +23 -0
- package/skills/lighting-quality-checker/EVAL.md +41 -0
- package/skills/lighting-quality-checker/SKILL.md +247 -0
- package/skills/lighting-quality-checker/contract.json +187 -0
- package/skills/lighting-quality-checker/references/hdri-balance-rules.md +48 -0
- package/skills/lighting-quality-checker/references/intensity-ranges.md +73 -0
- package/skills/lighting-quality-checker/references/shadow-softness-rules.md +38 -0
- package/skills/material-quality-checker/EVAL.md +40 -0
- package/skills/material-quality-checker/SKILL.md +261 -0
- package/skills/material-quality-checker/contract.json +244 -0
- package/skills/material-quality-checker/references/consumer-stack-rules.md +62 -0
- package/skills/material-quality-checker/references/pbr-sanity-rules.md +78 -0
- package/skills/material-quality-checker/references/texture-budget-rules.md +48 -0
- package/skills/mobile-glb-budget/EVAL.md +40 -0
- package/skills/mobile-glb-budget/SKILL.md +264 -0
- package/skills/mobile-glb-budget/contract.json +309 -0
- package/skills/mobile-glb-budget/references/budget-tiers.md +30 -0
- package/skills/mobile-glb-budget/references/degradation-plan.md +34 -0
- package/skills/mobile-glb-budget/references/violation-rules.md +43 -0
- package/skills/output-format-decision/EVAL.md +27 -0
- package/skills/output-format-decision/SKILL.md +222 -0
- package/skills/output-format-decision/contract.json +179 -0
- package/skills/output-format-decision/references/bit-depth-rules.md +56 -0
- package/skills/output-format-decision/references/compression-tradeoffs.md +62 -0
- package/skills/output-format-decision/references/format-decision-matrix.md +34 -0
- package/skills/pack-prerequisite-checker/EVAL.md +26 -0
- package/skills/pack-prerequisite-checker/SKILL.md +272 -0
- package/skills/pack-prerequisite-checker/contract.json +214 -0
- package/skills/pack-prerequisite-checker/references/blocked-start-playbook.md +21 -0
- package/skills/pack-prerequisite-checker/references/pack-readiness-template.md +38 -0
- package/skills/pack-prerequisite-checker/references/prerequisite-matrix.md +20 -0
- package/skills/path-one-host-outline/EVAL.md +26 -0
- package/skills/path-one-host-outline/SKILL.md +251 -0
- package/skills/path-one-host-outline/contract.json +167 -0
- package/skills/path-one-host-outline/references/connector-vs-manual-matrix.md +21 -0
- package/skills/path-one-host-outline/references/host-checklist-template.md +35 -0
- package/skills/path-one-host-outline/references/lab-addon-reminders.md +12 -0
- package/skills/plain-language-response/EVAL.md +33 -0
- package/skills/plain-language-response/SKILL.md +194 -0
- package/skills/plain-language-response/contract.json +242 -0
- package/skills/plain-language-response/references/caveat-language.md +25 -0
- package/skills/plain-language-response/references/plain-language-patterns.md +30 -0
- package/skills/plain-language-response/references/stakeholder-friendly-examples.md +30 -0
- package/skills/plain-language-response/references/status-summary-templates.md +50 -0
- package/skills/polycount-budget-checker/EVAL.md +40 -0
- package/skills/polycount-budget-checker/SKILL.md +251 -0
- package/skills/polycount-budget-checker/contract.json +196 -0
- package/skills/polycount-budget-checker/references/instance-counting-rules.md +39 -0
- package/skills/polycount-budget-checker/references/per-mesh-rules.md +43 -0
- package/skills/polycount-budget-checker/references/topology-hints.md +56 -0
- package/skills/pre-handoff-verification/EVAL.md +84 -0
- package/skills/pre-handoff-verification/SKILL.md +252 -0
- package/skills/pre-handoff-verification/contract.json +295 -0
- package/skills/pre-handoff-verification/references/downgrade-rules.md +39 -0
- package/skills/pre-handoff-verification/references/seven-point-checklist.md +46 -0
- package/skills/pre-handoff-verification/references/text-only-mode-handling.md +36 -0
- package/skills/preview-report/EVAL.md +39 -0
- package/skills/preview-report/SKILL.md +254 -0
- package/skills/preview-report/contract.json +141 -0
- package/skills/preview-report/references/handoff-recipients.md +41 -0
- package/skills/preview-report/references/report-schema.md +60 -0
- package/skills/preview-report/references/truth-label-rules.md +36 -0
- package/skills/product-grid-scene-planner/EVAL.md +42 -0
- package/skills/product-grid-scene-planner/SKILL.md +246 -0
- package/skills/product-grid-scene-planner/contract.json +257 -0
- package/skills/product-grid-scene-planner/references/grid-consistency-rules.md +53 -0
- package/skills/product-grid-scene-planner/references/grid-layout-rules.md +42 -0
- package/skills/product-grid-scene-planner/references/grid-output-naming-rules.md +52 -0
- package/skills/product-hero-scene-planner/EVAL.md +33 -0
- package/skills/product-hero-scene-planner/SKILL.md +227 -0
- package/skills/product-hero-scene-planner/contract.json +228 -0
- package/skills/product-hero-scene-planner/references/clarification-patterns.md +24 -0
- package/skills/product-hero-scene-planner/references/cyberpunk-shoe-example.md +28 -0
- package/skills/product-hero-scene-planner/references/product-hero-playbooks.md +22 -0
- package/skills/product-hero-scene-planner/references/scene-plan-schema.md +35 -0
- package/skills/r3f-component-plan/EVAL.md +43 -0
- package/skills/r3f-component-plan/SKILL.md +290 -0
- package/skills/r3f-component-plan/contract.json +171 -0
- package/skills/r3f-component-plan/references/component-shape-patterns.md +54 -0
- package/skills/r3f-component-plan/references/suspense-placement-rules.md +50 -0
- package/skills/r3f-component-plan/references/usegltf-caching-rules.md +53 -0
- package/skills/recipe-fit-assessor/EVAL.md +28 -0
- package/skills/recipe-fit-assessor/SKILL.md +266 -0
- package/skills/recipe-fit-assessor/contract.json +220 -0
- package/skills/recipe-fit-assessor/references/recipe-catalog.md +30 -0
- package/skills/recipe-fit-assessor/references/scope-gap-rules.md +27 -0
- package/skills/recipe-fit-assessor/references/workflow-recommendation-template.md +34 -0
- package/skills/render-export-evidence/EVAL.md +86 -0
- package/skills/render-export-evidence/SKILL.md +339 -0
- package/skills/render-export-evidence/contract.json +206 -0
- package/skills/render-export-evidence/references/attempted-vs-failed-rubric.md +75 -0
- package/skills/render-export-evidence/references/evidence-record-templates.md +143 -0
- package/skills/render-export-evidence/references/truth-label-decision-tree.md +57 -0
- package/skills/resolution-aspect-decision/EVAL.md +26 -0
- package/skills/resolution-aspect-decision/SKILL.md +246 -0
- package/skills/resolution-aspect-decision/contract.json +160 -0
- package/skills/resolution-aspect-decision/references/aspect-defaults.md +41 -0
- package/skills/resolution-aspect-decision/references/print-vs-screen-rules.md +58 -0
- package/skills/resolution-aspect-decision/references/resolution-defaults.md +64 -0
- package/skills/runtime-attempt-report/EVAL.md +26 -0
- package/skills/runtime-attempt-report/SKILL.md +268 -0
- package/skills/runtime-attempt-report/contract.json +176 -0
- package/skills/runtime-attempt-report/references/attempt-record-template.md +49 -0
- package/skills/runtime-attempt-report/references/triage-next-steps.md +15 -0
- package/skills/runtime-attempt-report/references/truth-label-blocks.md +27 -0
- package/skills/runtime-path-picker/EVAL.md +26 -0
- package/skills/runtime-path-picker/SKILL.md +268 -0
- package/skills/runtime-path-picker/contract.json +191 -0
- package/skills/runtime-path-picker/references/anti-patterns.md +14 -0
- package/skills/runtime-path-picker/references/decision-tree.md +29 -0
- package/skills/runtime-path-picker/references/path-constraints-table.md +18 -0
- package/skills/runtime-readiness/EVAL.md +33 -0
- package/skills/runtime-readiness/SKILL.md +218 -0
- package/skills/runtime-readiness/contract.json +190 -0
- package/skills/runtime-readiness/references/blocker-report-template.md +28 -0
- package/skills/runtime-readiness/references/evidence-examples.md +23 -0
- package/skills/runtime-readiness/references/readiness-matrix.md +46 -0
- package/skills/runtime-setup/EVAL.md +33 -0
- package/skills/runtime-setup/SKILL.md +209 -0
- package/skills/runtime-setup/contract.json +171 -0
- package/skills/runtime-setup/references/runtime-option-decision-tree.md +28 -0
- package/skills/runtime-setup/references/setup-summary-template.md +33 -0
- package/skills/runtime-setup/references/source-confidence-labels.md +23 -0
- package/skills/scene-readiness/EVAL.md +33 -0
- package/skills/scene-readiness/SKILL.md +195 -0
- package/skills/scene-readiness/contract.json +198 -0
- package/skills/scene-readiness/references/blocker-catalog.md +24 -0
- package/skills/scene-readiness/references/not-run-handling.md +22 -0
- package/skills/scene-readiness/references/quality-rubric.md +23 -0
- package/skills/scene-readiness/references/verdict-language.md +22 -0
- package/skills/scope-guard/EVAL.md +33 -0
- package/skills/scope-guard/SKILL.md +222 -0
- package/skills/scope-guard/contract.json +171 -0
- package/skills/scope-guard/references/options-language-template.md +51 -0
- package/skills/scope-guard/references/recurring-creep-patterns.md +55 -0
- package/skills/scope-guard/references/scope-addition-classification.md +55 -0
- package/skills/stage-gates/EVAL.md +40 -0
- package/skills/stage-gates/SKILL.md +257 -0
- package/skills/stage-gates/contract.json +490 -0
- package/skills/stage-gates/references/failed-gate-handling.md +42 -0
- package/skills/stage-gates/references/gate-template.md +46 -0
- package/skills/stage-gates/references/stage-decomposition-patterns.md +55 -0
- package/skills/workflow-stage-router/EVAL.md +25 -0
- package/skills/workflow-stage-router/SKILL.md +259 -0
- package/skills/workflow-stage-router/contract.json +150 -0
- package/skills/workflow-stage-router/references/milestone-model.md +20 -0
- package/skills/workflow-stage-router/references/routing-decision-tree.md +32 -0
- package/skills/workflow-stage-router/references/stage-handoff-template.md +37 -0
- package/skills.sh.json +102 -0
|
@@ -0,0 +1,2376 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import fs from 'node:fs';
|
|
3
|
+
import os from 'node:os';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import crypto from 'node:crypto';
|
|
6
|
+
import { fileURLToPath } from 'node:url';
|
|
7
|
+
import {
|
|
8
|
+
inspectGlbBuffer,
|
|
9
|
+
inspectGlbFile,
|
|
10
|
+
buildMinimalValidGlbBuffer,
|
|
11
|
+
CONTAINER_TRUTH_DISCLAIMER,
|
|
12
|
+
} from './inspect-glb.mjs';
|
|
13
|
+
|
|
14
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
15
|
+
const __dirname = path.dirname(__filename);
|
|
16
|
+
export const DEFAULT_HANDOFF_MANIFEST_SCHEMA_PATH = path.resolve(
|
|
17
|
+
__dirname,
|
|
18
|
+
'..',
|
|
19
|
+
'schemas',
|
|
20
|
+
'glb-web-handoff-manifest.schema.json',
|
|
21
|
+
);
|
|
22
|
+
|
|
23
|
+
const PROTECTED_REPO_DIRS = new Set([
|
|
24
|
+
'.git',
|
|
25
|
+
'.github',
|
|
26
|
+
'.aistudio',
|
|
27
|
+
'bin',
|
|
28
|
+
'bundles',
|
|
29
|
+
'docs',
|
|
30
|
+
'evals',
|
|
31
|
+
'laws',
|
|
32
|
+
'node_modules',
|
|
33
|
+
'packs',
|
|
34
|
+
'registry',
|
|
35
|
+
'schemas',
|
|
36
|
+
'scripts',
|
|
37
|
+
'skill-reviews',
|
|
38
|
+
'skills',
|
|
39
|
+
]);
|
|
40
|
+
|
|
41
|
+
// Mid-mobile hero card planning ceilings from skills/mobile-glb-budget
|
|
42
|
+
export const DEFAULT_WEB_PERFORMANCE_BUDGET = Object.freeze({
|
|
43
|
+
tier: 'mid-mobile-hero-default',
|
|
44
|
+
maxFileSizeBytes: 5 * 1024 * 1024, // 5 MB
|
|
45
|
+
maxTriangles: 50000,
|
|
46
|
+
maxVertices: 65000,
|
|
47
|
+
maxMaterials: 6,
|
|
48
|
+
maxTextures: 8,
|
|
49
|
+
maxAnimationChannels: 50,
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
let cachedManifestValidator = null;
|
|
53
|
+
|
|
54
|
+
function matchesJsonSchemaType(val, expectedType) {
|
|
55
|
+
if (expectedType === 'null') return val === null;
|
|
56
|
+
if (expectedType === 'array') return Array.isArray(val);
|
|
57
|
+
if (expectedType === 'object') return typeof val === 'object' && val !== null && !Array.isArray(val);
|
|
58
|
+
if (expectedType === 'integer') return typeof val === 'number' && Number.isInteger(val);
|
|
59
|
+
if (expectedType === 'number') return typeof val === 'number' && Number.isFinite(val);
|
|
60
|
+
if (expectedType === 'boolean') return typeof val === 'boolean';
|
|
61
|
+
if (expectedType === 'string') return typeof val === 'string';
|
|
62
|
+
return true;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function validateAgainstSchemaNode(val, schemaNode, instancePath, outErrors) {
|
|
66
|
+
if (!schemaNode || typeof schemaNode !== 'object') return;
|
|
67
|
+
|
|
68
|
+
if (schemaNode.type !== undefined) {
|
|
69
|
+
const allowedTypes = Array.isArray(schemaNode.type) ? schemaNode.type : [schemaNode.type];
|
|
70
|
+
const matched = allowedTypes.some((t) => matchesJsonSchemaType(val, t));
|
|
71
|
+
if (!matched) {
|
|
72
|
+
outErrors.push({
|
|
73
|
+
instancePath,
|
|
74
|
+
message: `must be ${allowedTypes.join(' or ')}`,
|
|
75
|
+
});
|
|
76
|
+
return;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
if (schemaNode.const !== undefined && val !== schemaNode.const) {
|
|
81
|
+
outErrors.push({
|
|
82
|
+
instancePath,
|
|
83
|
+
message: `must be equal to constant ${JSON.stringify(schemaNode.const)}`,
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
if (Array.isArray(schemaNode.enum) && !schemaNode.enum.includes(val)) {
|
|
88
|
+
outErrors.push({
|
|
89
|
+
instancePath,
|
|
90
|
+
message: 'must be equal to one of the allowed values',
|
|
91
|
+
params: { allowedValues: schemaNode.enum },
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
if (typeof val === 'string') {
|
|
96
|
+
if (typeof schemaNode.minLength === 'number' && val.length < schemaNode.minLength) {
|
|
97
|
+
outErrors.push({
|
|
98
|
+
instancePath,
|
|
99
|
+
message: `must NOT have fewer than ${schemaNode.minLength} characters`,
|
|
100
|
+
});
|
|
101
|
+
}
|
|
102
|
+
if (typeof schemaNode.maxLength === 'number' && val.length > schemaNode.maxLength) {
|
|
103
|
+
outErrors.push({
|
|
104
|
+
instancePath,
|
|
105
|
+
message: `must NOT have more than ${schemaNode.maxLength} characters`,
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
if (typeof schemaNode.pattern === 'string') {
|
|
109
|
+
const re = new RegExp(schemaNode.pattern);
|
|
110
|
+
if (!re.test(val)) {
|
|
111
|
+
outErrors.push({
|
|
112
|
+
instancePath,
|
|
113
|
+
message: `must match pattern "${schemaNode.pattern}"`,
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
if (typeof val === 'number' && Number.isFinite(val)) {
|
|
120
|
+
if (typeof schemaNode.minimum === 'number' && val < schemaNode.minimum) {
|
|
121
|
+
outErrors.push({
|
|
122
|
+
instancePath,
|
|
123
|
+
message: `must be >= ${schemaNode.minimum}`,
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
if (typeof schemaNode.maximum === 'number' && val > schemaNode.maximum) {
|
|
127
|
+
outErrors.push({
|
|
128
|
+
instancePath,
|
|
129
|
+
message: `must be <= ${schemaNode.maximum}`,
|
|
130
|
+
});
|
|
131
|
+
}
|
|
132
|
+
if (typeof schemaNode.exclusiveMinimum === 'number' && val <= schemaNode.exclusiveMinimum) {
|
|
133
|
+
outErrors.push({
|
|
134
|
+
instancePath,
|
|
135
|
+
message: `must be > ${schemaNode.exclusiveMinimum}`,
|
|
136
|
+
});
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
if (Array.isArray(val)) {
|
|
141
|
+
if (typeof schemaNode.minItems === 'number' && val.length < schemaNode.minItems) {
|
|
142
|
+
outErrors.push({
|
|
143
|
+
instancePath,
|
|
144
|
+
message: `must NOT have fewer than ${schemaNode.minItems} items`,
|
|
145
|
+
});
|
|
146
|
+
}
|
|
147
|
+
if (typeof schemaNode.maxItems === 'number' && val.length > schemaNode.maxItems) {
|
|
148
|
+
outErrors.push({
|
|
149
|
+
instancePath,
|
|
150
|
+
message: `must NOT have more than ${schemaNode.maxItems} items`,
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
if (schemaNode.items && typeof schemaNode.items === 'object') {
|
|
154
|
+
for (let i = 0; i < val.length; i += 1) {
|
|
155
|
+
validateAgainstSchemaNode(val[i], schemaNode.items, `${instancePath}/${i}`, outErrors);
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
if (val && typeof val === 'object' && !Array.isArray(val)) {
|
|
161
|
+
const props = schemaNode.properties && typeof schemaNode.properties === 'object' ? schemaNode.properties : {};
|
|
162
|
+
if (Array.isArray(schemaNode.required)) {
|
|
163
|
+
for (const reqKey of schemaNode.required) {
|
|
164
|
+
if (!Object.prototype.hasOwnProperty.call(val, reqKey) || val[reqKey] === undefined) {
|
|
165
|
+
outErrors.push({
|
|
166
|
+
instancePath,
|
|
167
|
+
message: `must have required property '${reqKey}'`,
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
if (schemaNode.additionalProperties === false) {
|
|
173
|
+
for (const key of Object.keys(val)) {
|
|
174
|
+
if (!Object.prototype.hasOwnProperty.call(props, key)) {
|
|
175
|
+
outErrors.push({
|
|
176
|
+
instancePath,
|
|
177
|
+
message: `must NOT have additional properties ('${key}')`,
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
for (const [propKey, propSchema] of Object.entries(props)) {
|
|
183
|
+
if (Object.prototype.hasOwnProperty.call(val, propKey) && val[propKey] !== undefined) {
|
|
184
|
+
validateAgainstSchemaNode(val[propKey], propSchema, `${instancePath}/${propKey}`, outErrors);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
function getHandoffManifestSchemaValidator(schemaPath = DEFAULT_HANDOFF_MANIFEST_SCHEMA_PATH) {
|
|
191
|
+
if (cachedManifestValidator && cachedManifestValidator.schemaPath === schemaPath) {
|
|
192
|
+
return cachedManifestValidator.validate;
|
|
193
|
+
}
|
|
194
|
+
const raw = fs.readFileSync(schemaPath, 'utf8');
|
|
195
|
+
const schema = JSON.parse(raw);
|
|
196
|
+
const validate = (data) => {
|
|
197
|
+
const collected = [];
|
|
198
|
+
validateAgainstSchemaNode(data, schema, '', collected);
|
|
199
|
+
validate.errors = collected;
|
|
200
|
+
return collected.length === 0;
|
|
201
|
+
};
|
|
202
|
+
validate.errors = [];
|
|
203
|
+
cachedManifestValidator = { schemaPath, validate };
|
|
204
|
+
return validate;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
export function escapeHtml(value) {
|
|
208
|
+
return String(value ?? '')
|
|
209
|
+
.replace(/&/g, '&')
|
|
210
|
+
.replace(/</g, '<')
|
|
211
|
+
.replace(/>/g, '>')
|
|
212
|
+
.replace(/"/g, '"')
|
|
213
|
+
.replace(/'/g, ''');
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
function sanitizeSlug(raw, fallback = 'glb-artifact') {
|
|
217
|
+
if (typeof raw !== 'string' || raw.trim().length === 0) return fallback;
|
|
218
|
+
const cleaned = raw
|
|
219
|
+
.toLowerCase()
|
|
220
|
+
.replace(/\.(glb|gltf)$/i, '')
|
|
221
|
+
.replace(/[^a-z0-9]+/g, '-')
|
|
222
|
+
.replace(/^-+|-+$/g, '');
|
|
223
|
+
return cleaned.length >= 3 ? cleaned.slice(0, 80) : `${cleaned || fallback}-handoff`;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
export function validateGlbWebHandoffManifest(
|
|
227
|
+
manifest,
|
|
228
|
+
{ schemaPath = DEFAULT_HANDOFF_MANIFEST_SCHEMA_PATH } = {},
|
|
229
|
+
) {
|
|
230
|
+
const errors = [];
|
|
231
|
+
|
|
232
|
+
if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
|
|
233
|
+
return {
|
|
234
|
+
valid: false,
|
|
235
|
+
errors: ['GLB web handoff manifest root must be a JSON object'],
|
|
236
|
+
};
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
// Explicitly check truth-state taxonomy violations before schema messages so error reasons are crystal-clear
|
|
240
|
+
const ts = manifest.truthStates;
|
|
241
|
+
if (ts && typeof ts === 'object') {
|
|
242
|
+
if (ts.artifactStatus === 'Not Run') {
|
|
243
|
+
errors.push(
|
|
244
|
+
"Truth-state taxonomy violation: truthStates.artifactStatus cannot be 'Not Run' (default artifact state is 'Not Produced')",
|
|
245
|
+
);
|
|
246
|
+
}
|
|
247
|
+
if (ts.artifactStatus === 'Attempted') {
|
|
248
|
+
errors.push(
|
|
249
|
+
"Truth-state taxonomy violation: truthStates.artifactStatus cannot be 'Attempted' (use 'Not Produced' or 'Failed')",
|
|
250
|
+
);
|
|
251
|
+
}
|
|
252
|
+
if (ts.runtimeStatus === 'Not Produced') {
|
|
253
|
+
errors.push(
|
|
254
|
+
"Truth-state taxonomy violation: truthStates.runtimeStatus cannot be 'Not Produced' (default runtime state is 'Not Run')",
|
|
255
|
+
);
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
const validateSchema = getHandoffManifestSchemaValidator(schemaPath);
|
|
260
|
+
const schemaOk = validateSchema(manifest);
|
|
261
|
+
if (!schemaOk) {
|
|
262
|
+
for (const err of validateSchema.errors || []) {
|
|
263
|
+
const loc = err.instancePath || '/';
|
|
264
|
+
const allowed = Array.isArray(err.params?.allowedValues)
|
|
265
|
+
? ` [${err.params.allowedValues.join(', ')}]`
|
|
266
|
+
: '';
|
|
267
|
+
errors.push(`schema(${loc}): ${err.message}${allowed}`);
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
const art = manifest.artifact;
|
|
272
|
+
const extComp = manifest.extensionsAndCompression;
|
|
273
|
+
const valSummary = manifest.validationSummary;
|
|
274
|
+
|
|
275
|
+
if (!art || typeof art !== 'object' || !ts || typeof ts !== 'object') {
|
|
276
|
+
return { valid: false, errors };
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
const prov = art.provenance;
|
|
280
|
+
if (prov && typeof prov === 'object') {
|
|
281
|
+
if (prov.sourceKind === 'synthetic_fixture' && prov.isSyntheticFixture !== true) {
|
|
282
|
+
errors.push(
|
|
283
|
+
"Provenance contradiction: sourceKind 'synthetic_fixture' requires provenance.isSyntheticFixture === true",
|
|
284
|
+
);
|
|
285
|
+
}
|
|
286
|
+
if (prov.isSyntheticFixture === true) {
|
|
287
|
+
if (ts.runtimeStatus !== 'Not Run') {
|
|
288
|
+
errors.push(
|
|
289
|
+
`Synthetic fixture boundary violation: synthetic fixture cannot claim runtimeStatus '${ts.runtimeStatus}' (must be 'Not Run')`,
|
|
290
|
+
);
|
|
291
|
+
}
|
|
292
|
+
if (ts.artifactStatus !== 'Not Produced') {
|
|
293
|
+
errors.push(
|
|
294
|
+
`Synthetic fixture boundary violation: synthetic fixture cannot claim production artifactStatus '${ts.artifactStatus}' (must be 'Not Produced')`,
|
|
295
|
+
);
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
if (ts.runtimePath === 'none') {
|
|
301
|
+
if (ts.runtimeStatus !== 'Not Run') {
|
|
302
|
+
errors.push(
|
|
303
|
+
`When truthStates.runtimePath is 'none', runtimeStatus must be 'Not Run' (received '${ts.runtimeStatus}')`,
|
|
304
|
+
);
|
|
305
|
+
}
|
|
306
|
+
if (ts.artifactStatus !== 'Not Produced') {
|
|
307
|
+
errors.push(
|
|
308
|
+
`When truthStates.runtimePath is 'none', artifactStatus must be 'Not Produced' (received '${ts.artifactStatus}')`,
|
|
309
|
+
);
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
if (ts.runtimePath === 'path-2-community' && ts.releaseEligibility !== 'non-release') {
|
|
314
|
+
errors.push(
|
|
315
|
+
`Path 2 community runtime ('path-2-community') requires truthStates.releaseEligibility to be 'non-release' (received '${ts.releaseEligibility}')`,
|
|
316
|
+
);
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
if (ts.artifactStatus === 'Produced' || ts.artifactStatus === 'Verified') {
|
|
320
|
+
if (ts.runtimeStatus !== 'Produced' && ts.runtimeStatus !== 'Verified') {
|
|
321
|
+
errors.push(
|
|
322
|
+
`Evidence-before-done violation: artifactStatus '${ts.artifactStatus}' requires runtimeStatus 'Produced' or 'Verified' (received '${ts.runtimeStatus}')`,
|
|
323
|
+
);
|
|
324
|
+
}
|
|
325
|
+
if (!Number.isInteger(art.byteSize) || art.byteSize <= 0) {
|
|
326
|
+
errors.push(
|
|
327
|
+
`Evidence-before-done violation: artifactStatus '${ts.artifactStatus}' requires a positive integer artifact.byteSize`,
|
|
328
|
+
);
|
|
329
|
+
}
|
|
330
|
+
if (typeof art.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(art.sha256)) {
|
|
331
|
+
errors.push(
|
|
332
|
+
`Evidence-before-done violation: artifactStatus '${ts.artifactStatus}' requires a 64-character hex artifact.sha256`,
|
|
333
|
+
);
|
|
334
|
+
}
|
|
335
|
+
if (!prov || prov.currentRunProvenanceVerified !== true) {
|
|
336
|
+
errors.push(
|
|
337
|
+
`Evidence-before-done violation: artifactStatus '${ts.artifactStatus}' requires artifact.provenance.currentRunProvenanceVerified === true`,
|
|
338
|
+
);
|
|
339
|
+
}
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
if (ts.artifactStatus === 'Verified') {
|
|
343
|
+
if (ts.runtimeStatus !== 'Verified') {
|
|
344
|
+
errors.push(
|
|
345
|
+
`Evidence-before-done violation: artifactStatus 'Verified' requires runtimeStatus 'Verified' (received '${ts.runtimeStatus}')`,
|
|
346
|
+
);
|
|
347
|
+
}
|
|
348
|
+
if (valSummary?.tiers?.containerStructural?.status !== 'Passed') {
|
|
349
|
+
errors.push(
|
|
350
|
+
"Evidence-before-done violation: artifactStatus 'Verified' requires validationSummary.tiers.containerStructural.status === 'Passed'",
|
|
351
|
+
);
|
|
352
|
+
}
|
|
353
|
+
if (valSummary?.overallVerdict === 'Fail') {
|
|
354
|
+
errors.push(
|
|
355
|
+
"Contradictory manifest: artifactStatus 'Verified' cannot have validationSummary.overallVerdict === 'Fail'",
|
|
356
|
+
);
|
|
357
|
+
}
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
if (extComp && typeof extComp === 'object') {
|
|
361
|
+
const used = Array.isArray(extComp.extensionsUsed) ? extComp.extensionsUsed : [];
|
|
362
|
+
const req = Array.isArray(extComp.extensionsRequired) ? extComp.extensionsRequired : [];
|
|
363
|
+
for (const r of req) {
|
|
364
|
+
if (!used.includes(r)) {
|
|
365
|
+
errors.push(`Extension consistency error: extensionsRequired entry '${r}' is missing from extensionsUsed`);
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
const comp = extComp.compression;
|
|
369
|
+
if (comp && typeof comp === 'object') {
|
|
370
|
+
if ((used.includes('KHR_draco_mesh_compression') || req.includes('KHR_draco_mesh_compression')) &&
|
|
371
|
+
(!comp.draco?.used || !comp.draco?.decoderRequired)) {
|
|
372
|
+
errors.push(
|
|
373
|
+
'Extension consistency error: KHR_draco_mesh_compression is present but compression.draco.used / decoderRequired is false',
|
|
374
|
+
);
|
|
375
|
+
}
|
|
376
|
+
if ((used.includes('EXT_meshopt_compression') || req.includes('EXT_meshopt_compression')) &&
|
|
377
|
+
(!comp.meshopt?.used || !comp.meshopt?.decoderRequired)) {
|
|
378
|
+
errors.push(
|
|
379
|
+
'Extension consistency error: EXT_meshopt_compression is present but compression.meshopt.used / decoderRequired is false',
|
|
380
|
+
);
|
|
381
|
+
}
|
|
382
|
+
if ((used.includes('KHR_texture_basisu') || req.includes('KHR_texture_basisu')) &&
|
|
383
|
+
(!comp.ktx2BasisU?.used || !comp.ktx2BasisU?.transcoderRequired)) {
|
|
384
|
+
errors.push(
|
|
385
|
+
'Extension consistency error: KHR_texture_basisu is present but compression.ktx2BasisU.used / transcoderRequired is false',
|
|
386
|
+
);
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
if (valSummary && typeof valSummary === 'object') {
|
|
392
|
+
const structStatus = valSummary.tiers?.containerStructural?.status;
|
|
393
|
+
const errList = Array.isArray(valSummary.errors) ? valSummary.errors : [];
|
|
394
|
+
if ((structStatus === 'Failed' || errList.length > 0) && valSummary.overallVerdict !== 'Fail') {
|
|
395
|
+
errors.push(
|
|
396
|
+
`Verdict contradiction: containerStructural status is '${structStatus}' with ${errList.length} error(s), so overallVerdict must be 'Fail' (received '${valSummary.overallVerdict}')`,
|
|
397
|
+
);
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
return {
|
|
402
|
+
valid: errors.length === 0,
|
|
403
|
+
errors,
|
|
404
|
+
};
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
export function buildGlbWebHandoffManifestFromInspection(
|
|
408
|
+
inspection,
|
|
409
|
+
{
|
|
410
|
+
filename = 'artifact.glb',
|
|
411
|
+
targetViewerStack = 'threejs',
|
|
412
|
+
sourceKind = 'unverified',
|
|
413
|
+
isSyntheticFixture = false,
|
|
414
|
+
currentRunProvenanceVerified = false,
|
|
415
|
+
runtimePath = 'none',
|
|
416
|
+
runtimeStatus = 'Not Run',
|
|
417
|
+
artifactStatus = 'Not Produced',
|
|
418
|
+
unitScaleMetersPerUnit = 1.0,
|
|
419
|
+
forwardAxis = '+Z',
|
|
420
|
+
originPolicy = 'unverified',
|
|
421
|
+
performanceBudget = DEFAULT_WEB_PERFORMANCE_BUDGET,
|
|
422
|
+
} = {},
|
|
423
|
+
) {
|
|
424
|
+
const safeFilename = path.basename(filename || 'artifact.glb');
|
|
425
|
+
const effectiveIsSynthetic =
|
|
426
|
+
Boolean(isSyntheticFixture) ||
|
|
427
|
+
sourceKind === 'synthetic_fixture' ||
|
|
428
|
+
Boolean(inspection?.details?.extras?.isSyntheticFixture);
|
|
429
|
+
const effectiveSourceKind = effectiveIsSynthetic ? 'synthetic_fixture' : sourceKind;
|
|
430
|
+
|
|
431
|
+
// Enforce downgrade-only & synthetic fixture truth-state policy
|
|
432
|
+
const effectiveRuntimePath = effectiveIsSynthetic ? 'none' : runtimePath;
|
|
433
|
+
const effectiveRuntimeStatus =
|
|
434
|
+
effectiveIsSynthetic || effectiveRuntimePath === 'none' ? 'Not Run' : runtimeStatus;
|
|
435
|
+
const effectiveArtifactStatus =
|
|
436
|
+
effectiveIsSynthetic ||
|
|
437
|
+
effectiveRuntimePath === 'none' ||
|
|
438
|
+
!currentRunProvenanceVerified ||
|
|
439
|
+
!inspection?.valid
|
|
440
|
+
? inspection && !inspection.valid && runtimeStatus === 'Attempted'
|
|
441
|
+
? 'Failed'
|
|
442
|
+
: 'Not Produced'
|
|
443
|
+
: artifactStatus;
|
|
444
|
+
|
|
445
|
+
const releaseEligibility =
|
|
446
|
+
effectiveRuntimePath === 'path-2-community'
|
|
447
|
+
? 'non-release'
|
|
448
|
+
: effectiveRuntimePath === 'none'
|
|
449
|
+
? 'not-applicable'
|
|
450
|
+
: 'release-eligible';
|
|
451
|
+
|
|
452
|
+
const counts = inspection?.counts || {
|
|
453
|
+
scenes: 0,
|
|
454
|
+
nodes: 0,
|
|
455
|
+
meshes: 0,
|
|
456
|
+
primitives: 0,
|
|
457
|
+
vertices: 0,
|
|
458
|
+
trianglesEstimate: 0,
|
|
459
|
+
materials: 0,
|
|
460
|
+
textures: 0,
|
|
461
|
+
images: 0,
|
|
462
|
+
samplers: 0,
|
|
463
|
+
animations: 0,
|
|
464
|
+
skins: 0,
|
|
465
|
+
accessors: 0,
|
|
466
|
+
bufferViews: 0,
|
|
467
|
+
buffers: 0,
|
|
468
|
+
};
|
|
469
|
+
|
|
470
|
+
const ext = inspection?.extensions || {
|
|
471
|
+
extensionsUsed: [],
|
|
472
|
+
extensionsRequired: [],
|
|
473
|
+
undeclaredExtensionsFound: [],
|
|
474
|
+
compression: {
|
|
475
|
+
draco: { used: false, required: false, decoderRequired: false },
|
|
476
|
+
meshopt: { used: false, required: false, decoderRequired: false },
|
|
477
|
+
ktx2BasisU: { used: false, required: false, transcoderRequired: false },
|
|
478
|
+
webp: { used: false, required: false },
|
|
479
|
+
},
|
|
480
|
+
};
|
|
481
|
+
|
|
482
|
+
const details = inspection?.details || {
|
|
483
|
+
defaultSceneIndex: null,
|
|
484
|
+
scenes: [],
|
|
485
|
+
meshes: [],
|
|
486
|
+
materials: [],
|
|
487
|
+
textures: [],
|
|
488
|
+
animations: [],
|
|
489
|
+
rootNodeTransforms: [],
|
|
490
|
+
externalResources: [],
|
|
491
|
+
};
|
|
492
|
+
|
|
493
|
+
const perfWarnings = [];
|
|
494
|
+
const budget = { ...DEFAULT_WEB_PERFORMANCE_BUDGET, ...(performanceBudget || {}) };
|
|
495
|
+
if (typeof inspection?.byteSize === 'number' && inspection.byteSize > budget.maxFileSizeBytes) {
|
|
496
|
+
perfWarnings.push(
|
|
497
|
+
`File size (${inspection.byteSize} bytes) exceeds ${budget.tier} ceiling (${budget.maxFileSizeBytes} bytes); consider Draco/Meshopt geometry compression or KTX2 texture compression.`,
|
|
498
|
+
);
|
|
499
|
+
}
|
|
500
|
+
if (counts.trianglesEstimate > budget.maxTriangles) {
|
|
501
|
+
perfWarnings.push(
|
|
502
|
+
`Estimated triangle count (${counts.trianglesEstimate}) exceeds ${budget.tier} ceiling (${budget.maxTriangles} triangles).`,
|
|
503
|
+
);
|
|
504
|
+
}
|
|
505
|
+
if (counts.vertices > budget.maxVertices) {
|
|
506
|
+
perfWarnings.push(
|
|
507
|
+
`Vertex count (${counts.vertices}) exceeds ${budget.tier} ceiling (${budget.maxVertices} vertices).`,
|
|
508
|
+
);
|
|
509
|
+
}
|
|
510
|
+
if (counts.materials > budget.maxMaterials) {
|
|
511
|
+
perfWarnings.push(
|
|
512
|
+
`Distinct material count (${counts.materials}) exceeds ${budget.tier} ceiling (${budget.maxMaterials} materials); merge materials or texture atlases to reduce draw calls.`,
|
|
513
|
+
);
|
|
514
|
+
}
|
|
515
|
+
if (counts.textures > budget.maxTextures) {
|
|
516
|
+
perfWarnings.push(
|
|
517
|
+
`Texture count (${counts.textures}) exceeds ${budget.tier} ceiling (${budget.maxTextures} textures).`,
|
|
518
|
+
);
|
|
519
|
+
}
|
|
520
|
+
const totalAnimChannels = (details.animations || []).reduce((s, a) => s + (a.channelCount || 0), 0);
|
|
521
|
+
if (totalAnimChannels > budget.maxAnimationChannels) {
|
|
522
|
+
perfWarnings.push(
|
|
523
|
+
`Total animation channel count (${totalAnimChannels}) exceeds ${budget.tier} ceiling (${budget.maxAnimationChannels} channels).`,
|
|
524
|
+
);
|
|
525
|
+
}
|
|
526
|
+
|
|
527
|
+
const errors = Array.isArray(inspection?.errors) ? [...inspection.errors] : ['Invalid inspection input'];
|
|
528
|
+
const warnings = Array.isArray(inspection?.warnings) ? [...inspection.warnings] : [];
|
|
529
|
+
|
|
530
|
+
const unresolvedIssues = [];
|
|
531
|
+
const nextActions = [];
|
|
532
|
+
|
|
533
|
+
if (!inspection?.valid || errors.length > 0) {
|
|
534
|
+
unresolvedIssues.push(
|
|
535
|
+
`GLB structural container inspection failed with ${errors.length} error(s): ${errors[0]}`,
|
|
536
|
+
);
|
|
537
|
+
nextActions.push(
|
|
538
|
+
'Fix the reported GLB 2.0 structural errors in the exporter or re-export the asset before attempting web viewer integration.',
|
|
539
|
+
);
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
if (ext.compression.draco.decoderRequired) {
|
|
543
|
+
unresolvedIssues.push(
|
|
544
|
+
'Asset uses KHR_draco_mesh_compression; web viewers will fail to parse geometry unless DRACOLoader is configured with a reachable WASM/JS decoder path.',
|
|
545
|
+
);
|
|
546
|
+
nextActions.push(
|
|
547
|
+
'Configure DRACOLoader with a self-hosted or version-pinned Draco decoder path before loading the GLB.',
|
|
548
|
+
);
|
|
549
|
+
}
|
|
550
|
+
if (ext.compression.meshopt.decoderRequired) {
|
|
551
|
+
unresolvedIssues.push(
|
|
552
|
+
'Asset uses EXT_meshopt_compression; web viewers require MeshoptDecoder to be attached to GLTFLoader.',
|
|
553
|
+
);
|
|
554
|
+
nextActions.push('Attach MeshoptDecoder to GLTFLoader before loading the GLB.');
|
|
555
|
+
}
|
|
556
|
+
if (ext.compression.ktx2BasisU.transcoderRequired) {
|
|
557
|
+
unresolvedIssues.push(
|
|
558
|
+
'Asset uses KHR_texture_basisu (KTX2/BasisU GPU textures); web viewers require KTX2Loader with renderer.detectSupport(renderer).',
|
|
559
|
+
);
|
|
560
|
+
nextActions.push(
|
|
561
|
+
'Configure KTX2Loader with BasisU transcoder binaries and call ktx2Loader.detectSupport(renderer).',
|
|
562
|
+
);
|
|
563
|
+
}
|
|
564
|
+
|
|
565
|
+
const externalFiles = (details.externalResources || []).filter((r) => r.isExternalFile);
|
|
566
|
+
if (externalFiles.length > 0) {
|
|
567
|
+
unresolvedIssues.push(
|
|
568
|
+
`Asset references ${externalFiles.length} external resource URI(s) (${externalFiles.map((r) => r.uri).join(', ')}); missing companion files or CORS restrictions will break loading in web viewers.`,
|
|
569
|
+
);
|
|
570
|
+
nextActions.push(
|
|
571
|
+
'Re-export as a self-contained single-file GLB with all buffers and textures packed into the binary chunk, or verify all external URIs are co-hosted with CORS headers.',
|
|
572
|
+
);
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
if (effectiveIsSynthetic) {
|
|
576
|
+
unresolvedIssues.push(
|
|
577
|
+
'Artifact is a synthetic test fixture (isSyntheticFixture: true). It verifies container/pipeline tooling only and is not a production Blender asset.',
|
|
578
|
+
);
|
|
579
|
+
}
|
|
580
|
+
|
|
581
|
+
unresolvedIssues.push(
|
|
582
|
+
'Visual quality (framing, lighting response, silhouette, PBR material appearance) and live browser rendering are not proven by static GLB inspection.',
|
|
583
|
+
);
|
|
584
|
+
|
|
585
|
+
if (!currentRunProvenanceVerified) {
|
|
586
|
+
unresolvedIssues.push(
|
|
587
|
+
'Current-run Blender runtime provenance is unverified; Runtime status remains Not Run and Artifact status remains Not Produced.',
|
|
588
|
+
);
|
|
589
|
+
}
|
|
590
|
+
|
|
591
|
+
if (nextActions.length === 0) {
|
|
592
|
+
nextActions.push(
|
|
593
|
+
`Load '${safeFilename}' in the target ${targetViewerStack} viewer using the generated integration template and verify visual framing, lighting, and material response manually.`,
|
|
594
|
+
);
|
|
595
|
+
}
|
|
596
|
+
if (inspection?.khronosValidator?.status !== 'passed') {
|
|
597
|
+
nextActions.push(
|
|
598
|
+
'Optionally run the upstream Khronos gltf-validator for exhaustive glTF 2.0 specification verification.',
|
|
599
|
+
);
|
|
600
|
+
}
|
|
601
|
+
nextActions.push(
|
|
602
|
+
'Pass this handoff manifest and summary to plain-language-response when preparing the final plain-language delivery note.',
|
|
603
|
+
);
|
|
604
|
+
|
|
605
|
+
const overallVerdict =
|
|
606
|
+
!inspection?.valid || errors.length > 0
|
|
607
|
+
? 'Fail'
|
|
608
|
+
: warnings.length > 0 || perfWarnings.length > 0 || externalFiles.length > 0
|
|
609
|
+
? 'Warn'
|
|
610
|
+
: 'Pass';
|
|
611
|
+
|
|
612
|
+
const structTierStatus =
|
|
613
|
+
!inspection?.valid || errors.length > 0
|
|
614
|
+
? 'Failed'
|
|
615
|
+
: warnings.length > 0
|
|
616
|
+
? 'Warn'
|
|
617
|
+
: 'Passed';
|
|
618
|
+
|
|
619
|
+
const gltfSpecTier = inspection?.validationTiers?.gltfSpecification || {
|
|
620
|
+
status: 'Not Run',
|
|
621
|
+
tool: 'gltf-validator',
|
|
622
|
+
summary:
|
|
623
|
+
'Upstream Khronos gltf-validator was not executed; built-in inspection covers GLB 2.0 container structure and cross-references.',
|
|
624
|
+
};
|
|
625
|
+
|
|
626
|
+
const bbox = inspection?.bounds?.sceneBoundingBox || {
|
|
627
|
+
min: null,
|
|
628
|
+
max: null,
|
|
629
|
+
dimensions: null,
|
|
630
|
+
center: null,
|
|
631
|
+
};
|
|
632
|
+
|
|
633
|
+
const manifest = {
|
|
634
|
+
$schema: '../schemas/glb-web-handoff-manifest.schema.json',
|
|
635
|
+
schemaVersion: '1.0.0',
|
|
636
|
+
manifestId: sanitizeSlug(safeFilename),
|
|
637
|
+
skillId: 'glb-web-handoff',
|
|
638
|
+
artifact: {
|
|
639
|
+
filename: safeFilename,
|
|
640
|
+
format: 'GLB 2.0',
|
|
641
|
+
byteSize: typeof inspection?.byteSize === 'number' ? inspection.byteSize : null,
|
|
642
|
+
sha256: typeof inspection?.sha256 === 'string' ? inspection.sha256 : null,
|
|
643
|
+
gltfVersion: inspection?.asset?.version === '2.0' ? '2.0' : null,
|
|
644
|
+
generator: typeof inspection?.asset?.generator === 'string' ? inspection.asset.generator : null,
|
|
645
|
+
provenance: {
|
|
646
|
+
sourceKind: effectiveSourceKind,
|
|
647
|
+
isSyntheticFixture: effectiveIsSynthetic,
|
|
648
|
+
currentRunProvenanceVerified: Boolean(currentRunProvenanceVerified) && !effectiveIsSynthetic,
|
|
649
|
+
notes: effectiveIsSynthetic
|
|
650
|
+
? 'Synthetic GLB 2.0 test fixture generated in memory/disk for deterministic structural and handoff verification. Not a Blender export.'
|
|
651
|
+
: currentRunProvenanceVerified
|
|
652
|
+
? 'Artifact provenance linked to current recorded run.'
|
|
653
|
+
: 'Pre-existing or user-supplied GLB inspected statically; live Blender export provenance is not verified in this run.',
|
|
654
|
+
},
|
|
655
|
+
},
|
|
656
|
+
truthStates: {
|
|
657
|
+
runtimeStatus: effectiveRuntimeStatus,
|
|
658
|
+
runtimePath: effectiveRuntimePath,
|
|
659
|
+
artifactStatus: effectiveArtifactStatus,
|
|
660
|
+
releaseEligibility,
|
|
661
|
+
},
|
|
662
|
+
contents: {
|
|
663
|
+
counts,
|
|
664
|
+
defaultSceneIndex: details.defaultSceneIndex,
|
|
665
|
+
scenes: details.scenes,
|
|
666
|
+
meshes: details.meshes,
|
|
667
|
+
materials: details.materials,
|
|
668
|
+
textures: details.textures,
|
|
669
|
+
animations: details.animations,
|
|
670
|
+
},
|
|
671
|
+
extensionsAndCompression: {
|
|
672
|
+
extensionsUsed: ext.extensionsUsed,
|
|
673
|
+
extensionsRequired: ext.extensionsRequired,
|
|
674
|
+
undeclaredExtensionsFound: ext.undeclaredExtensionsFound,
|
|
675
|
+
compression: ext.compression,
|
|
676
|
+
externalResources: details.externalResources,
|
|
677
|
+
},
|
|
678
|
+
spatialAndTransformAssumptions: {
|
|
679
|
+
unitScaleMetersPerUnit: Number(unitScaleMetersPerUnit) > 0 ? Number(unitScaleMetersPerUnit) : 1.0,
|
|
680
|
+
coordinateSystem: {
|
|
681
|
+
upAxis: '+Y',
|
|
682
|
+
forwardAxis: forwardAxis === '-Z' ? '-Z' : '+Z',
|
|
683
|
+
handedness: 'right-handed',
|
|
684
|
+
sourceUpAxisConversionNote:
|
|
685
|
+
'glTF 2.0 specifies +Y up, +Z forward, and 1 unit = 1 meter. Blender scenes (Z-up) require +Y up conversion at export time; static binary inspection verifies node transforms and bounds but cannot prove semantic orientation.',
|
|
686
|
+
},
|
|
687
|
+
originPolicy,
|
|
688
|
+
sceneBoundingBox: {
|
|
689
|
+
min: bbox.min || null,
|
|
690
|
+
max: bbox.max || null,
|
|
691
|
+
dimensions: bbox.dimensions || null,
|
|
692
|
+
center: bbox.center || null,
|
|
693
|
+
},
|
|
694
|
+
rootNodeTransforms: details.rootNodeTransforms,
|
|
695
|
+
},
|
|
696
|
+
targetViewer: {
|
|
697
|
+
stack: ['threejs', 'react-three-fiber', 'model-viewer', 'babylonjs', 'generic-webgl'].includes(
|
|
698
|
+
targetViewerStack,
|
|
699
|
+
)
|
|
700
|
+
? targetViewerStack
|
|
701
|
+
: 'threejs',
|
|
702
|
+
dracoDecoderPath: ext.compression.draco.decoderRequired ? '/draco/' : null,
|
|
703
|
+
ktx2TranscoderPath: ext.compression.ktx2BasisU.transcoderRequired ? '/basis/' : null,
|
|
704
|
+
meshoptDecoderRequired: Boolean(ext.compression.meshopt.decoderRequired),
|
|
705
|
+
toneMappingAssumption:
|
|
706
|
+
'ACESFilmicToneMapping or AgX/Neutral tone mapping must be chosen explicitly by the web application; appearance varies by tone mapper and exposure.',
|
|
707
|
+
outputColorSpaceAssumption:
|
|
708
|
+
'THREE.SRGBColorSpace output encoding with sRGB baseColor/emissive textures and LinearSRGB data textures (normal, metallicRoughness, occlusion).',
|
|
709
|
+
environmentLightingAssumption:
|
|
710
|
+
'PBR metallic-roughness materials require an environment map (e.g. RoomEnvironment + PMREMGenerator or HDRI) to avoid appearing black or flat.',
|
|
711
|
+
},
|
|
712
|
+
validationSummary: {
|
|
713
|
+
overallVerdict,
|
|
714
|
+
tiers: {
|
|
715
|
+
containerStructural: {
|
|
716
|
+
status: structTierStatus,
|
|
717
|
+
tool: 'scripts/inspect-glb.mjs',
|
|
718
|
+
errorCount: errors.length,
|
|
719
|
+
warningCount: warnings.length,
|
|
720
|
+
summary:
|
|
721
|
+
structTierStatus === 'Failed'
|
|
722
|
+
? `GLB 2.0 container structural check failed with ${errors.length} error(s).`
|
|
723
|
+
: `GLB 2.0 container structural check passed (${warnings.length} warning(s)).`,
|
|
724
|
+
},
|
|
725
|
+
gltfSpecification: gltfSpecTier,
|
|
726
|
+
visualQuality: {
|
|
727
|
+
status: 'Not Run',
|
|
728
|
+
summary:
|
|
729
|
+
'Visual quality (framing, silhouette, lighting balance, material appearance) is not verified by binary inspection and requires rendered or live viewer inspection.',
|
|
730
|
+
},
|
|
731
|
+
liveRuntime: {
|
|
732
|
+
status: effectiveRuntimeStatus === 'Verified' ? 'Passed' : 'Not Run',
|
|
733
|
+
summary:
|
|
734
|
+
effectiveRuntimeStatus === 'Verified'
|
|
735
|
+
? 'Live runtime execution evidence verified.'
|
|
736
|
+
: 'Live Blender runtime execution was Not Run in this inspection pass.',
|
|
737
|
+
},
|
|
738
|
+
},
|
|
739
|
+
errors,
|
|
740
|
+
warnings,
|
|
741
|
+
performanceWarnings: perfWarnings,
|
|
742
|
+
},
|
|
743
|
+
unresolvedIssues,
|
|
744
|
+
nextActions,
|
|
745
|
+
};
|
|
746
|
+
|
|
747
|
+
return manifest;
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
export function buildWebIntegrationCodeSnippets(manifest) {
|
|
751
|
+
const filename = manifest?.artifact?.filename || 'model.glb';
|
|
752
|
+
const comp = manifest?.extensionsAndCompression?.compression || {};
|
|
753
|
+
const needsDraco = Boolean(comp.draco?.decoderRequired);
|
|
754
|
+
const needsMeshopt = Boolean(comp.meshopt?.decoderRequired);
|
|
755
|
+
const needsKtx2 = Boolean(comp.ktx2BasisU?.transcoderRequired);
|
|
756
|
+
const animations = Array.isArray(manifest?.contents?.animations) ? manifest.contents.animations : [];
|
|
757
|
+
const defaultClip = animations[0]?.name || null;
|
|
758
|
+
|
|
759
|
+
const threeImports = [
|
|
760
|
+
"import * as THREE from 'three';",
|
|
761
|
+
"import { OrbitControls } from 'three/addons/controls/OrbitControls.js';",
|
|
762
|
+
"import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';",
|
|
763
|
+
"import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';",
|
|
764
|
+
];
|
|
765
|
+
if (needsDraco) {
|
|
766
|
+
threeImports.push("import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';");
|
|
767
|
+
}
|
|
768
|
+
if (needsMeshopt) {
|
|
769
|
+
threeImports.push("import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';");
|
|
770
|
+
}
|
|
771
|
+
if (needsKtx2) {
|
|
772
|
+
threeImports.push("import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';");
|
|
773
|
+
}
|
|
774
|
+
|
|
775
|
+
const decoderSetupLines = [];
|
|
776
|
+
if (needsDraco) {
|
|
777
|
+
decoderSetupLines.push(
|
|
778
|
+
' const dracoLoader = new DRACOLoader();',
|
|
779
|
+
` dracoLoader.setDecoderPath(options.dracoDecoderPath || '${manifest?.targetViewer?.dracoDecoderPath || '/draco/'}');`,
|
|
780
|
+
' loader.setDRACOLoader(dracoLoader);',
|
|
781
|
+
);
|
|
782
|
+
}
|
|
783
|
+
if (needsMeshopt) {
|
|
784
|
+
decoderSetupLines.push(' loader.setMeshoptDecoder(MeshoptDecoder);');
|
|
785
|
+
}
|
|
786
|
+
if (needsKtx2) {
|
|
787
|
+
decoderSetupLines.push(
|
|
788
|
+
' const ktx2Loader = new KTX2Loader();',
|
|
789
|
+
` ktx2Loader.setTranscoderPath(options.ktx2TranscoderPath || '${manifest?.targetViewer?.ktx2TranscoderPath || '/basis/'}');`,
|
|
790
|
+
' ktx2Loader.detectSupport(renderer);',
|
|
791
|
+
' loader.setKTX2Loader(ktx2Loader);',
|
|
792
|
+
);
|
|
793
|
+
}
|
|
794
|
+
|
|
795
|
+
const decoderCleanupLines = [];
|
|
796
|
+
if (needsDraco) decoderCleanupLines.push(' dracoLoader.dispose();');
|
|
797
|
+
if (needsKtx2) decoderCleanupLines.push(' ktx2Loader.dispose();');
|
|
798
|
+
|
|
799
|
+
const threeJsCode = `${threeImports.join('\n')}
|
|
800
|
+
|
|
801
|
+
/**
|
|
802
|
+
* Mounts a GLB 2.0 asset into a container element with automatic bounding-box framing,
|
|
803
|
+
* studio PMREM lighting, OrbitControls, optional animation playback, and deterministic disposal.
|
|
804
|
+
*
|
|
805
|
+
* Truth boundary: Loading a GLB in Three.js verifies client-side runtime parsing only;
|
|
806
|
+
* visual framing and material fidelity must still be reviewed by a human operator.
|
|
807
|
+
*/
|
|
808
|
+
export function mountGlbViewer(container, options = {}) {
|
|
809
|
+
const assetUrl = options.assetUrl || './${filename}';
|
|
810
|
+
const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
|
|
811
|
+
renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
|
|
812
|
+
renderer.setSize(container.clientWidth || 800, container.clientHeight || 600);
|
|
813
|
+
renderer.outputColorSpace = THREE.SRGBColorSpace;
|
|
814
|
+
renderer.toneMapping = THREE.ACESFilmicToneMapping;
|
|
815
|
+
renderer.toneMappingExposure = 1.0;
|
|
816
|
+
container.appendChild(renderer.domElement);
|
|
817
|
+
|
|
818
|
+
const scene = new THREE.Scene();
|
|
819
|
+
const pmremGenerator = new THREE.PMREMGenerator(renderer);
|
|
820
|
+
const envTexture = pmremGenerator.fromScene(new RoomEnvironment(), 0.04).texture;
|
|
821
|
+
scene.environment = envTexture;
|
|
822
|
+
|
|
823
|
+
const camera = new THREE.PerspectiveCamera(
|
|
824
|
+
45,
|
|
825
|
+
(container.clientWidth || 800) / (container.clientHeight || 600),
|
|
826
|
+
0.01,
|
|
827
|
+
1000,
|
|
828
|
+
);
|
|
829
|
+
const controls = new OrbitControls(camera, renderer.domElement);
|
|
830
|
+
controls.enableDamping = true;
|
|
831
|
+
|
|
832
|
+
const loader = new GLTFLoader();
|
|
833
|
+
${decoderSetupLines.length > 0 ? decoderSetupLines.join('\n') : ' // No compression decoders required by this manifest.'}
|
|
834
|
+
|
|
835
|
+
let mixer = null;
|
|
836
|
+
let loadedRoot = null;
|
|
837
|
+
let frameId = null;
|
|
838
|
+
let disposed = false;
|
|
839
|
+
const clock = new THREE.Clock();
|
|
840
|
+
|
|
841
|
+
loader.load(
|
|
842
|
+
assetUrl,
|
|
843
|
+
(gltf) => {
|
|
844
|
+
if (disposed) return;
|
|
845
|
+
loadedRoot = gltf.scene;
|
|
846
|
+
scene.add(loadedRoot);
|
|
847
|
+
|
|
848
|
+
// Frame camera from measured scene bounding box
|
|
849
|
+
const box = new THREE.Box3().setFromObject(loadedRoot);
|
|
850
|
+
const size = box.getSize(new THREE.Vector3());
|
|
851
|
+
const center = box.getCenter(new THREE.Vector3());
|
|
852
|
+
const maxDim = Math.max(size.x, size.y, size.z, 0.1);
|
|
853
|
+
const fitDist = maxDim * 1.85;
|
|
854
|
+
|
|
855
|
+
camera.near = Math.max(maxDim / 100, 0.001);
|
|
856
|
+
camera.far = Math.max(maxDim * 100, 100);
|
|
857
|
+
camera.position.set(center.x + fitDist * 0.6, center.y + fitDist * 0.45, center.z + fitDist);
|
|
858
|
+
camera.updateProjectionMatrix();
|
|
859
|
+
controls.target.copy(center);
|
|
860
|
+
controls.update();
|
|
861
|
+
|
|
862
|
+
if (Array.isArray(gltf.animations) && gltf.animations.length > 0) {
|
|
863
|
+
mixer = new THREE.AnimationMixer(loadedRoot);
|
|
864
|
+
const clipName = options.clipName ?? ${defaultClip ? JSON.stringify(defaultClip) : 'null'};
|
|
865
|
+
const clip =
|
|
866
|
+
(clipName && THREE.AnimationClip.findByName(gltf.animations, clipName)) ||
|
|
867
|
+
gltf.animations[0];
|
|
868
|
+
if (clip) {
|
|
869
|
+
mixer.clipAction(clip).play();
|
|
870
|
+
}
|
|
871
|
+
}
|
|
872
|
+
if (typeof options.onLoaded === 'function') {
|
|
873
|
+
options.onLoaded({ gltf, bounds: { size, center } });
|
|
874
|
+
}
|
|
875
|
+
},
|
|
876
|
+
undefined,
|
|
877
|
+
(error) => {
|
|
878
|
+
if (typeof options.onError === 'function') {
|
|
879
|
+
options.onError(error);
|
|
880
|
+
}
|
|
881
|
+
},
|
|
882
|
+
);
|
|
883
|
+
|
|
884
|
+
function onResize() {
|
|
885
|
+
if (disposed) return;
|
|
886
|
+
const width = container.clientWidth || 800;
|
|
887
|
+
const height = container.clientHeight || 600;
|
|
888
|
+
camera.aspect = width / height;
|
|
889
|
+
camera.updateProjectionMatrix();
|
|
890
|
+
renderer.setSize(width, height);
|
|
891
|
+
}
|
|
892
|
+
window.addEventListener('resize', onResize);
|
|
893
|
+
|
|
894
|
+
function animate() {
|
|
895
|
+
if (disposed) return;
|
|
896
|
+
frameId = window.requestAnimationFrame(animate);
|
|
897
|
+
const delta = clock.getDelta();
|
|
898
|
+
if (mixer) mixer.update(delta);
|
|
899
|
+
controls.update();
|
|
900
|
+
renderer.render(scene, camera);
|
|
901
|
+
}
|
|
902
|
+
animate();
|
|
903
|
+
|
|
904
|
+
return {
|
|
905
|
+
dispose() {
|
|
906
|
+
disposed = true;
|
|
907
|
+
if (frameId !== null) window.cancelAnimationFrame(frameId);
|
|
908
|
+
window.removeEventListener('resize', onResize);
|
|
909
|
+
if (mixer && loadedRoot) mixer.uncacheRoot(loadedRoot);
|
|
910
|
+
if (loadedRoot) {
|
|
911
|
+
loadedRoot.traverse((obj) => {
|
|
912
|
+
if (obj.isMesh) {
|
|
913
|
+
obj.geometry?.dispose?.();
|
|
914
|
+
const mats = Array.isArray(obj.material) ? obj.material : [obj.material];
|
|
915
|
+
for (const m of mats) {
|
|
916
|
+
if (!m) continue;
|
|
917
|
+
for (const val of Object.values(m)) {
|
|
918
|
+
if (val && typeof val === 'object' && val.isTexture) {
|
|
919
|
+
val.dispose();
|
|
920
|
+
}
|
|
921
|
+
}
|
|
922
|
+
m.dispose?.();
|
|
923
|
+
}
|
|
924
|
+
}
|
|
925
|
+
});
|
|
926
|
+
}
|
|
927
|
+
controls.dispose();
|
|
928
|
+
envTexture.dispose();
|
|
929
|
+
pmremGenerator.dispose();
|
|
930
|
+
${decoderCleanupLines.join('\n')}
|
|
931
|
+
renderer.dispose();
|
|
932
|
+
renderer.domElement.remove();
|
|
933
|
+
},
|
|
934
|
+
};
|
|
935
|
+
}
|
|
936
|
+
`;
|
|
937
|
+
|
|
938
|
+
const r3fCode = `import React, { Suspense, useEffect } from 'react';
|
|
939
|
+
import { Canvas } from '@react-three/fiber';
|
|
940
|
+
import { Bounds, Environment, OrbitControls, useAnimations, useGLTF } from '@react-three/drei';
|
|
941
|
+
|
|
942
|
+
export interface GlbHandoffModelProps {
|
|
943
|
+
/** URL or path to the GLB 2.0 asset (never hardcode a synthetic fixture as a production asset) */
|
|
944
|
+
src: string;
|
|
945
|
+
/** Optional animation clip name (${animations.length > 0 ? animations.map((a) => `'${a.name || `clip_${a.index}`}'`).join(' | ') : 'string'}) */
|
|
946
|
+
clipName?: string;
|
|
947
|
+
/** Uniform scale multiplier (manifest assumes ${manifest?.spatialAndTransformAssumptions?.unitScaleMetersPerUnit ?? 1}m per unit, +Y up) */
|
|
948
|
+
scale?: number;
|
|
949
|
+
/** Optional Draco decoder path when KHR_draco_mesh_compression is used */
|
|
950
|
+
dracoDecoderPath?: string;
|
|
951
|
+
onLoaded?: (info: { sceneName: string | null; clipNames: string[] }) => void;
|
|
952
|
+
}
|
|
953
|
+
|
|
954
|
+
export function GlbHandoffModel({
|
|
955
|
+
src,
|
|
956
|
+
clipName = ${defaultClip ? JSON.stringify(defaultClip) : 'undefined'},
|
|
957
|
+
scale = 1,
|
|
958
|
+
dracoDecoderPath = ${needsDraco ? JSON.stringify(manifest?.targetViewer?.dracoDecoderPath || '/draco/') : 'undefined'},
|
|
959
|
+
onLoaded,
|
|
960
|
+
}: GlbHandoffModelProps) {
|
|
961
|
+
const gltf = useGLTF(src, dracoDecoderPath || false);
|
|
962
|
+
const { actions, names } = useAnimations(gltf.animations, gltf.scene);
|
|
963
|
+
|
|
964
|
+
useEffect(() => {
|
|
965
|
+
onLoaded?.({
|
|
966
|
+
sceneName: gltf.scene?.name || null,
|
|
967
|
+
clipNames: names,
|
|
968
|
+
});
|
|
969
|
+
}, [gltf.scene, names, onLoaded]);
|
|
970
|
+
|
|
971
|
+
useEffect(() => {
|
|
972
|
+
const targetClip = clipName && actions[clipName] ? clipName : names[0];
|
|
973
|
+
const action = targetClip ? actions[targetClip] : null;
|
|
974
|
+
if (action) {
|
|
975
|
+
action.reset().fadeIn(0.2).play();
|
|
976
|
+
return () => {
|
|
977
|
+
action.fadeOut(0.2);
|
|
978
|
+
};
|
|
979
|
+
}
|
|
980
|
+
return undefined;
|
|
981
|
+
}, [actions, clipName, names]);
|
|
982
|
+
|
|
983
|
+
return <primitive object={gltf.scene} scale={scale} />;
|
|
984
|
+
}
|
|
985
|
+
|
|
986
|
+
export interface GlbHandoffViewerCanvasProps extends GlbHandoffModelProps {
|
|
987
|
+
fallback?: React.ReactNode;
|
|
988
|
+
}
|
|
989
|
+
|
|
990
|
+
export function GlbHandoffViewerCanvas({
|
|
991
|
+
src = './${filename}',
|
|
992
|
+
clipName,
|
|
993
|
+
scale = 1,
|
|
994
|
+
dracoDecoderPath,
|
|
995
|
+
fallback = null,
|
|
996
|
+
onLoaded,
|
|
997
|
+
}: GlbHandoffViewerCanvasProps) {
|
|
998
|
+
return (
|
|
999
|
+
<Canvas
|
|
1000
|
+
camera={{ fov: 45, near: 0.01, far: 1000, position: [2.2, 1.6, 2.8] }}
|
|
1001
|
+
gl={{ antialias: true, powerPreference: 'high-performance' }}
|
|
1002
|
+
>
|
|
1003
|
+
<Suspense fallback={fallback}>
|
|
1004
|
+
<Environment preset="studio" />
|
|
1005
|
+
<Bounds fit clip observe margin={1.25}>
|
|
1006
|
+
<GlbHandoffModel
|
|
1007
|
+
src={src}
|
|
1008
|
+
clipName={clipName}
|
|
1009
|
+
scale={scale}
|
|
1010
|
+
dracoDecoderPath={dracoDecoderPath}
|
|
1011
|
+
onLoaded={onLoaded}
|
|
1012
|
+
/>
|
|
1013
|
+
</Bounds>
|
|
1014
|
+
<OrbitControls makeDefault enableDamping />
|
|
1015
|
+
</Suspense>
|
|
1016
|
+
</Canvas>
|
|
1017
|
+
);
|
|
1018
|
+
}
|
|
1019
|
+
`;
|
|
1020
|
+
|
|
1021
|
+
return {
|
|
1022
|
+
threejs: threeJsCode,
|
|
1023
|
+
reactThreeFiber: r3fCode,
|
|
1024
|
+
};
|
|
1025
|
+
}
|
|
1026
|
+
|
|
1027
|
+
export function formatGlbHandoffMarkdownSummary(manifest) {
|
|
1028
|
+
const art = manifest.artifact;
|
|
1029
|
+
const ts = manifest.truthStates;
|
|
1030
|
+
const counts = manifest.contents.counts;
|
|
1031
|
+
const ext = manifest.extensionsAndCompression;
|
|
1032
|
+
const spatial = manifest.spatialAndTransformAssumptions;
|
|
1033
|
+
const val = manifest.validationSummary;
|
|
1034
|
+
|
|
1035
|
+
const lines = [
|
|
1036
|
+
`## BlendOps GLB Web Handoff Report — \`${art.filename}\``,
|
|
1037
|
+
'',
|
|
1038
|
+
'### 1. Truth State & Provenance',
|
|
1039
|
+
`- **Overall handoff verdict:** \`${val.overallVerdict}\``,
|
|
1040
|
+
`- **Runtime status:** \`${ts.runtimeStatus}\` (path: \`${ts.runtimePath}\`)`,
|
|
1041
|
+
`- **Artifact status:** \`${ts.artifactStatus}\` (release eligibility: \`${ts.releaseEligibility}\`)`,
|
|
1042
|
+
`- **Artifact provenance:** \`${art.provenance.sourceKind}\` (\`isSyntheticFixture: ${art.provenance.isSyntheticFixture}\`, \`currentRunProvenanceVerified: ${art.provenance.currentRunProvenanceVerified}\`)`,
|
|
1043
|
+
`- **Provenance note:** ${art.provenance.notes}`,
|
|
1044
|
+
'',
|
|
1045
|
+
'### 2. 4-Tier Validation Summary',
|
|
1046
|
+
`- **Tier 1 — Container Structural Inspection (\`${val.tiers.containerStructural.tool}\`):** \`${val.tiers.containerStructural.status}\` — ${val.tiers.containerStructural.summary}`,
|
|
1047
|
+
`- **Tier 2 — Khronos glTF 2.0 Specification (\`${val.tiers.gltfSpecification.tool}\`):** \`${val.tiers.gltfSpecification.status}\` — ${val.tiers.gltfSpecification.summary}`,
|
|
1048
|
+
`- **Tier 3 — Visual Quality Validation:** \`${val.tiers.visualQuality.status}\` — ${val.tiers.visualQuality.summary}`,
|
|
1049
|
+
`- **Tier 4 — Live Blender Runtime Execution:** \`${val.tiers.liveRuntime.status}\` — ${val.tiers.liveRuntime.summary}`,
|
|
1050
|
+
'',
|
|
1051
|
+
'### 3. Artifact Contents & Geometry Inventory',
|
|
1052
|
+
`- **Format / Version:** \`${art.format}\` (glTF \`${art.gltfVersion || 'unknown'}\`, generator: \`${art.generator || 'unspecified'}\`)`,
|
|
1053
|
+
`- **File size:** \`${art.byteSize ?? 0} bytes\` (\`SHA-256: ${art.sha256 || 'none'}\`)`,
|
|
1054
|
+
`- **Scene graph counts:** \`${counts.scenes}\` scene(s), \`${counts.nodes}\` node(s), \`${counts.meshes}\` mesh(es), \`${counts.primitives}\` primitive(s)`,
|
|
1055
|
+
`- **Geometry budget:** \`${counts.vertices}\` vertices, \`~${counts.trianglesEstimate}\` estimated triangles`,
|
|
1056
|
+
`- **Surface & animation counts:** \`${counts.materials}\` material(s), \`${counts.textures}\` texture(s), \`${counts.images}\` image(s), \`${counts.animations}\` animation clip(s), \`${counts.skins}\` skin(s)`,
|
|
1057
|
+
'',
|
|
1058
|
+
'### 4. Extensions, Compression & External Dependencies',
|
|
1059
|
+
`- **Extensions used:** ${ext.extensionsUsed.length > 0 ? ext.extensionsUsed.map((e) => `\`${e}\``).join(', ') : 'none'}`,
|
|
1060
|
+
`- **Extensions required:** ${ext.extensionsRequired.length > 0 ? ext.extensionsRequired.map((e) => `\`${e}\``).join(', ') : 'none'}`,
|
|
1061
|
+
`- **Draco compression (\`KHR_draco_mesh_compression\`):** \`${ext.compression.draco.decoderRequired ? 'Decoder required' : 'Not used'}\``,
|
|
1062
|
+
`- **Meshopt compression (\`EXT_meshopt_compression\`):** \`${ext.compression.meshopt.decoderRequired ? 'Decoder required' : 'Not used'}\``,
|
|
1063
|
+
`- **KTX2 / BasisU textures (\`KHR_texture_basisu\`):** \`${ext.compression.ktx2BasisU.transcoderRequired ? 'Transcoder required' : 'Not used'}\``,
|
|
1064
|
+
`- **External URI references:** \`${ext.externalResources.filter((r) => r.isExternalFile).length}\``,
|
|
1065
|
+
'',
|
|
1066
|
+
'### 5. Spatial, Scale & Transform Assumptions',
|
|
1067
|
+
`- **Unit scale:** \`1 unit = ${spatial.unitScaleMetersPerUnit} meter(s)\``,
|
|
1068
|
+
`- **Coordinate system:** \`${spatial.coordinateSystem.upAxis}\` up, \`${spatial.coordinateSystem.forwardAxis}\` forward (\`${spatial.coordinateSystem.handedness}\`)`,
|
|
1069
|
+
`- **Origin policy:** \`${spatial.originPolicy}\``,
|
|
1070
|
+
`- **Measured bounding box:** ${spatial.sceneBoundingBox.dimensions ? `dimensions \`[${spatial.sceneBoundingBox.dimensions.join(', ')}]\`, center \`[${spatial.sceneBoundingBox.center.join(', ')}]\`` : 'unavailable'}`,
|
|
1071
|
+
`- **Target web viewer stack:** \`${manifest.targetViewer.stack}\``,
|
|
1072
|
+
'',
|
|
1073
|
+
];
|
|
1074
|
+
|
|
1075
|
+
if (val.errors.length > 0) {
|
|
1076
|
+
lines.push('### 6. Structural Errors');
|
|
1077
|
+
for (const err of val.errors) {
|
|
1078
|
+
lines.push(`- ${err}`);
|
|
1079
|
+
}
|
|
1080
|
+
lines.push('');
|
|
1081
|
+
}
|
|
1082
|
+
|
|
1083
|
+
if (val.warnings.length > 0 || val.performanceWarnings.length > 0) {
|
|
1084
|
+
lines.push('### 7. Compatibility & Performance Warnings');
|
|
1085
|
+
for (const w of [...val.warnings, ...val.performanceWarnings]) {
|
|
1086
|
+
lines.push(`- ${w}`);
|
|
1087
|
+
}
|
|
1088
|
+
lines.push('');
|
|
1089
|
+
}
|
|
1090
|
+
|
|
1091
|
+
lines.push('### 8. Unresolved Limitations & Caveats');
|
|
1092
|
+
for (const issue of manifest.unresolvedIssues) {
|
|
1093
|
+
lines.push(`- ${issue}`);
|
|
1094
|
+
}
|
|
1095
|
+
lines.push('');
|
|
1096
|
+
lines.push('### 9. Recommended Next Actions');
|
|
1097
|
+
for (const act of manifest.nextActions) {
|
|
1098
|
+
lines.push(`- ${act}`);
|
|
1099
|
+
}
|
|
1100
|
+
lines.push('');
|
|
1101
|
+
|
|
1102
|
+
return lines.join('\n');
|
|
1103
|
+
}
|
|
1104
|
+
|
|
1105
|
+
export function renderGlbHandoffHtmlReport(manifest, snippets) {
|
|
1106
|
+
const art = manifest.artifact;
|
|
1107
|
+
const ts = manifest.truthStates;
|
|
1108
|
+
const counts = manifest.contents.counts;
|
|
1109
|
+
const ext = manifest.extensionsAndCompression;
|
|
1110
|
+
const spatial = manifest.spatialAndTransformAssumptions;
|
|
1111
|
+
const val = manifest.validationSummary;
|
|
1112
|
+
|
|
1113
|
+
const verdictBadgeClass =
|
|
1114
|
+
val.overallVerdict === 'Pass'
|
|
1115
|
+
? 'badge-pass'
|
|
1116
|
+
: val.overallVerdict === 'Warn'
|
|
1117
|
+
? 'badge-warn'
|
|
1118
|
+
: 'badge-fail';
|
|
1119
|
+
|
|
1120
|
+
const meshRows =
|
|
1121
|
+
manifest.contents.meshes.length > 0
|
|
1122
|
+
? manifest.contents.meshes
|
|
1123
|
+
.map(
|
|
1124
|
+
(m) => `<tr>
|
|
1125
|
+
<td class="num">${m.index}</td>
|
|
1126
|
+
<td><code>${escapeHtml(m.name || `mesh_${m.index}`)}</code></td>
|
|
1127
|
+
<td class="num">${m.primitiveCount}</td>
|
|
1128
|
+
<td class="num">${m.vertexCount.toLocaleString('en-US')}</td>
|
|
1129
|
+
<td class="num">${m.triangleEstimate.toLocaleString('en-US')}</td>
|
|
1130
|
+
<td><code>${escapeHtml(m.attributes.join(', ') || 'none')}</code></td>
|
|
1131
|
+
<td class="num">${m.morphTargetCount}</td>
|
|
1132
|
+
</tr>`,
|
|
1133
|
+
)
|
|
1134
|
+
.join('\n')
|
|
1135
|
+
: '<tr><td colspan="7" class="empty-cell">No meshes declared in this GLB container.</td></tr>';
|
|
1136
|
+
|
|
1137
|
+
const materialRows =
|
|
1138
|
+
manifest.contents.materials.length > 0
|
|
1139
|
+
? manifest.contents.materials
|
|
1140
|
+
.map(
|
|
1141
|
+
(mat) => `<tr>
|
|
1142
|
+
<td class="num">${mat.index}</td>
|
|
1143
|
+
<td><code>${escapeHtml(mat.name || `material_${mat.index}`)}</code></td>
|
|
1144
|
+
<td><code>${escapeHtml(mat.alphaMode)}</code></td>
|
|
1145
|
+
<td>${mat.doubleSided ? 'Yes' : 'No'}</td>
|
|
1146
|
+
<td class="num">${mat.metallicFactor.toFixed(2)} / ${mat.roughnessFactor.toFixed(2)}</td>
|
|
1147
|
+
<td>${[
|
|
1148
|
+
mat.hasBaseColorTexture ? 'BaseColor' : null,
|
|
1149
|
+
mat.hasMetallicRoughnessTexture ? 'MetalRough' : null,
|
|
1150
|
+
mat.hasNormalTexture ? 'Normal' : null,
|
|
1151
|
+
mat.hasOcclusionTexture ? 'Occlusion' : null,
|
|
1152
|
+
mat.hasEmissiveTexture ? 'Emissive' : null,
|
|
1153
|
+
]
|
|
1154
|
+
.filter(Boolean)
|
|
1155
|
+
.join(', ') || 'Factors only'}</td>
|
|
1156
|
+
<td><code>${escapeHtml(mat.extensions.join(', ') || 'Standard PBR')}</code></td>
|
|
1157
|
+
</tr>`,
|
|
1158
|
+
)
|
|
1159
|
+
.join('\n')
|
|
1160
|
+
: '<tr><td colspan="7" class="empty-cell">No materials declared in this GLB container.</td></tr>';
|
|
1161
|
+
|
|
1162
|
+
const animationRows =
|
|
1163
|
+
manifest.contents.animations.length > 0
|
|
1164
|
+
? manifest.contents.animations
|
|
1165
|
+
.map(
|
|
1166
|
+
(anim) => `<tr>
|
|
1167
|
+
<td class="num">${anim.index}</td>
|
|
1168
|
+
<td><code>${escapeHtml(anim.name || `clip_${anim.index}`)}</code></td>
|
|
1169
|
+
<td class="num">${anim.channelCount}</td>
|
|
1170
|
+
<td class="num">${anim.samplerCount}</td>
|
|
1171
|
+
<td class="num">${anim.durationSeconds !== null ? `${anim.durationSeconds.toFixed(3)}s` : 'Unknown'}</td>
|
|
1172
|
+
<td><code>${escapeHtml(anim.targetPaths.join(', ') || 'none')}</code></td>
|
|
1173
|
+
<td><code>${escapeHtml(anim.interpolationModes.join(', ') || 'LINEAR')}</code></td>
|
|
1174
|
+
</tr>`,
|
|
1175
|
+
)
|
|
1176
|
+
.join('\n')
|
|
1177
|
+
: '<tr><td colspan="7" class="empty-cell">Static asset — 0 animation clips present.</td></tr>';
|
|
1178
|
+
|
|
1179
|
+
const embeddedManifestJson = JSON.stringify(manifest).replace(/</g, '\\u003c');
|
|
1180
|
+
|
|
1181
|
+
return `<!DOCTYPE html>
|
|
1182
|
+
<html lang="en">
|
|
1183
|
+
<head>
|
|
1184
|
+
<meta charset="utf-8" />
|
|
1185
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
1186
|
+
<title>BlendOps GLB Web Handoff Report — ${escapeHtml(art.filename)}</title>
|
|
1187
|
+
<style>
|
|
1188
|
+
:root {
|
|
1189
|
+
--bg: #0b0f19;
|
|
1190
|
+
--surface: #111827;
|
|
1191
|
+
--surface-elevated: #1e293b;
|
|
1192
|
+
--border: #263248;
|
|
1193
|
+
--text: #f8fafc;
|
|
1194
|
+
--text-muted: #94a3b8;
|
|
1195
|
+
--accent: #38bdf8;
|
|
1196
|
+
--pass-bg: rgba(22, 163, 74, 0.16);
|
|
1197
|
+
--pass-border: rgba(34, 197, 94, 0.45);
|
|
1198
|
+
--pass-text: #4ade80;
|
|
1199
|
+
--warn-bg: rgba(217, 119, 6, 0.16);
|
|
1200
|
+
--warn-border: rgba(245, 158, 11, 0.45);
|
|
1201
|
+
--warn-text: #fbbf24;
|
|
1202
|
+
--fail-bg: rgba(220, 38, 38, 0.16);
|
|
1203
|
+
--fail-border: rgba(248, 113, 113, 0.45);
|
|
1204
|
+
--fail-text: #f87171;
|
|
1205
|
+
--neutral-bg: rgba(148, 163, 184, 0.12);
|
|
1206
|
+
--neutral-border: rgba(148, 163, 184, 0.35);
|
|
1207
|
+
--neutral-text: #cbd5e1;
|
|
1208
|
+
--mono: "JetBrains Mono", "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
|
|
1209
|
+
--sans: "Plus Jakarta Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
|
|
1210
|
+
}
|
|
1211
|
+
* { box-sizing: border-box; }
|
|
1212
|
+
body {
|
|
1213
|
+
margin: 0;
|
|
1214
|
+
background: var(--bg);
|
|
1215
|
+
color: var(--text);
|
|
1216
|
+
font-family: var(--sans);
|
|
1217
|
+
font-size: 14px;
|
|
1218
|
+
line-height: 1.55;
|
|
1219
|
+
}
|
|
1220
|
+
.container {
|
|
1221
|
+
max-width: 1240px;
|
|
1222
|
+
margin: 0 auto;
|
|
1223
|
+
padding: 28px 24px 56px;
|
|
1224
|
+
}
|
|
1225
|
+
header.top-header {
|
|
1226
|
+
display: flex;
|
|
1227
|
+
flex-wrap: wrap;
|
|
1228
|
+
justify-content: space-between;
|
|
1229
|
+
align-items: flex-start;
|
|
1230
|
+
gap: 16px;
|
|
1231
|
+
padding-bottom: 20px;
|
|
1232
|
+
border-bottom: 1px solid var(--border);
|
|
1233
|
+
margin-bottom: 20px;
|
|
1234
|
+
}
|
|
1235
|
+
.eyebrow {
|
|
1236
|
+
font-family: var(--mono);
|
|
1237
|
+
font-size: 11px;
|
|
1238
|
+
letter-spacing: 0.08em;
|
|
1239
|
+
text-transform: uppercase;
|
|
1240
|
+
color: var(--accent);
|
|
1241
|
+
margin-bottom: 6px;
|
|
1242
|
+
}
|
|
1243
|
+
h1 {
|
|
1244
|
+
margin: 0;
|
|
1245
|
+
font-size: 24px;
|
|
1246
|
+
font-weight: 700;
|
|
1247
|
+
letter-spacing: -0.02em;
|
|
1248
|
+
}
|
|
1249
|
+
h2 {
|
|
1250
|
+
margin: 0 0 12px;
|
|
1251
|
+
font-size: 16px;
|
|
1252
|
+
font-weight: 600;
|
|
1253
|
+
letter-spacing: -0.01em;
|
|
1254
|
+
}
|
|
1255
|
+
.truth-banner {
|
|
1256
|
+
background: var(--surface);
|
|
1257
|
+
border: 1px solid var(--border);
|
|
1258
|
+
border-left: 4px solid var(--accent);
|
|
1259
|
+
border-radius: 6px;
|
|
1260
|
+
padding: 14px 16px;
|
|
1261
|
+
margin-bottom: 24px;
|
|
1262
|
+
color: var(--text-muted);
|
|
1263
|
+
font-size: 13px;
|
|
1264
|
+
}
|
|
1265
|
+
.truth-banner strong { color: var(--text); }
|
|
1266
|
+
.badge {
|
|
1267
|
+
display: inline-flex;
|
|
1268
|
+
align-items: center;
|
|
1269
|
+
padding: 3px 10px;
|
|
1270
|
+
border-radius: 4px;
|
|
1271
|
+
font-family: var(--mono);
|
|
1272
|
+
font-size: 12px;
|
|
1273
|
+
font-weight: 600;
|
|
1274
|
+
border: 1px solid transparent;
|
|
1275
|
+
}
|
|
1276
|
+
.badge-pass { background: var(--pass-bg); border-color: var(--pass-border); color: var(--pass-text); }
|
|
1277
|
+
.badge-warn { background: var(--warn-bg); border-color: var(--warn-border); color: var(--warn-text); }
|
|
1278
|
+
.badge-fail { background: var(--fail-bg); border-color: var(--fail-border); color: var(--fail-text); }
|
|
1279
|
+
.badge-neutral { background: var(--neutral-bg); border-color: var(--neutral-border); color: var(--neutral-text); }
|
|
1280
|
+
.grid-4 {
|
|
1281
|
+
display: grid;
|
|
1282
|
+
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
|
|
1283
|
+
gap: 14px;
|
|
1284
|
+
margin-bottom: 24px;
|
|
1285
|
+
}
|
|
1286
|
+
.grid-2 {
|
|
1287
|
+
display: grid;
|
|
1288
|
+
grid-template-columns: repeat(auto-fit, minmax(380px, 1fr));
|
|
1289
|
+
gap: 16px;
|
|
1290
|
+
margin-bottom: 24px;
|
|
1291
|
+
}
|
|
1292
|
+
.panel {
|
|
1293
|
+
background: var(--surface);
|
|
1294
|
+
border: 1px solid var(--border);
|
|
1295
|
+
border-radius: 6px;
|
|
1296
|
+
padding: 16px;
|
|
1297
|
+
margin-bottom: 20px;
|
|
1298
|
+
}
|
|
1299
|
+
.metric-label {
|
|
1300
|
+
font-size: 12px;
|
|
1301
|
+
color: var(--text-muted);
|
|
1302
|
+
margin-bottom: 4px;
|
|
1303
|
+
}
|
|
1304
|
+
.metric-value {
|
|
1305
|
+
font-family: var(--mono);
|
|
1306
|
+
font-size: 18px;
|
|
1307
|
+
font-weight: 700;
|
|
1308
|
+
font-variant-numeric: tabular-nums;
|
|
1309
|
+
}
|
|
1310
|
+
.metric-sub {
|
|
1311
|
+
font-size: 12px;
|
|
1312
|
+
color: var(--text-muted);
|
|
1313
|
+
margin-top: 6px;
|
|
1314
|
+
}
|
|
1315
|
+
table {
|
|
1316
|
+
width: 100%;
|
|
1317
|
+
border-collapse: collapse;
|
|
1318
|
+
font-size: 13px;
|
|
1319
|
+
}
|
|
1320
|
+
th, td {
|
|
1321
|
+
padding: 9px 10px;
|
|
1322
|
+
border-bottom: 1px solid var(--border);
|
|
1323
|
+
text-align: left;
|
|
1324
|
+
}
|
|
1325
|
+
th {
|
|
1326
|
+
color: var(--text-muted);
|
|
1327
|
+
font-weight: 600;
|
|
1328
|
+
font-size: 12px;
|
|
1329
|
+
text-transform: uppercase;
|
|
1330
|
+
letter-spacing: 0.04em;
|
|
1331
|
+
}
|
|
1332
|
+
td.num, th.num {
|
|
1333
|
+
text-align: right;
|
|
1334
|
+
font-family: var(--mono);
|
|
1335
|
+
font-variant-numeric: tabular-nums;
|
|
1336
|
+
}
|
|
1337
|
+
td.empty-cell {
|
|
1338
|
+
text-align: center;
|
|
1339
|
+
color: var(--text-muted);
|
|
1340
|
+
padding: 16px;
|
|
1341
|
+
}
|
|
1342
|
+
code, pre {
|
|
1343
|
+
font-family: var(--mono);
|
|
1344
|
+
font-variant-numeric: tabular-nums;
|
|
1345
|
+
}
|
|
1346
|
+
pre.code-block {
|
|
1347
|
+
background: #070a12;
|
|
1348
|
+
border: 1px solid var(--border);
|
|
1349
|
+
border-radius: 6px;
|
|
1350
|
+
padding: 14px;
|
|
1351
|
+
overflow-x: auto;
|
|
1352
|
+
font-size: 12px;
|
|
1353
|
+
line-height: 1.5;
|
|
1354
|
+
color: #e2e8f0;
|
|
1355
|
+
margin: 0;
|
|
1356
|
+
}
|
|
1357
|
+
ul.compact-list {
|
|
1358
|
+
margin: 0;
|
|
1359
|
+
padding-left: 18px;
|
|
1360
|
+
}
|
|
1361
|
+
ul.compact-list li {
|
|
1362
|
+
margin-bottom: 6px;
|
|
1363
|
+
}
|
|
1364
|
+
.preview-grid {
|
|
1365
|
+
display: grid;
|
|
1366
|
+
grid-template-columns: 1fr 340px;
|
|
1367
|
+
gap: 16px;
|
|
1368
|
+
align-items: stretch;
|
|
1369
|
+
}
|
|
1370
|
+
@media (max-width: 860px) {
|
|
1371
|
+
.preview-grid { grid-template-columns: 1fr; }
|
|
1372
|
+
}
|
|
1373
|
+
.canvas-stage {
|
|
1374
|
+
background: #070a12;
|
|
1375
|
+
border: 1px solid var(--border);
|
|
1376
|
+
border-radius: 6px;
|
|
1377
|
+
min-height: 300px;
|
|
1378
|
+
display: flex;
|
|
1379
|
+
flex-direction: column;
|
|
1380
|
+
justify-content: space-between;
|
|
1381
|
+
padding: 12px;
|
|
1382
|
+
}
|
|
1383
|
+
canvas#glbWireframeCanvas {
|
|
1384
|
+
width: 100%;
|
|
1385
|
+
height: 240px;
|
|
1386
|
+
display: block;
|
|
1387
|
+
}
|
|
1388
|
+
.file-drop-zone {
|
|
1389
|
+
border: 1px dashed var(--border);
|
|
1390
|
+
border-radius: 6px;
|
|
1391
|
+
padding: 14px;
|
|
1392
|
+
background: rgba(30, 41, 59, 0.4);
|
|
1393
|
+
}
|
|
1394
|
+
.btn {
|
|
1395
|
+
background: var(--surface-elevated);
|
|
1396
|
+
color: var(--text);
|
|
1397
|
+
border: 1px solid var(--border);
|
|
1398
|
+
border-radius: 4px;
|
|
1399
|
+
padding: 6px 12px;
|
|
1400
|
+
font-family: var(--sans);
|
|
1401
|
+
font-size: 12px;
|
|
1402
|
+
font-weight: 600;
|
|
1403
|
+
cursor: pointer;
|
|
1404
|
+
}
|
|
1405
|
+
.btn:hover { border-color: var(--accent); }
|
|
1406
|
+
</style>
|
|
1407
|
+
</head>
|
|
1408
|
+
<body>
|
|
1409
|
+
<div class="container">
|
|
1410
|
+
<header class="top-header">
|
|
1411
|
+
<div>
|
|
1412
|
+
<div class="eyebrow">BlendOps · Web-Ready GLB Handoff Report</div>
|
|
1413
|
+
<h1>${escapeHtml(art.filename)}</h1>
|
|
1414
|
+
<div class="metric-sub">
|
|
1415
|
+
SHA-256: <code>${escapeHtml(art.sha256 || 'none')}</code> · Size: <code>${(art.byteSize ?? 0).toLocaleString('en-US')} bytes</code> · Target stack: <code>${escapeHtml(manifest.targetViewer.stack)}</code>
|
|
1416
|
+
</div>
|
|
1417
|
+
</div>
|
|
1418
|
+
<div style="display:flex; gap:8px; align-items:center; flex-wrap:wrap;">
|
|
1419
|
+
<span class="badge ${verdictBadgeClass}">Verdict: ${escapeHtml(val.overallVerdict)}</span>
|
|
1420
|
+
<span class="badge badge-neutral">Runtime: ${escapeHtml(ts.runtimeStatus)}</span>
|
|
1421
|
+
<span class="badge badge-neutral">Artifact: ${escapeHtml(ts.artifactStatus)}</span>
|
|
1422
|
+
<span class="badge badge-neutral">Provenance: ${escapeHtml(art.provenance.sourceKind)}</span>
|
|
1423
|
+
</div>
|
|
1424
|
+
</header>
|
|
1425
|
+
|
|
1426
|
+
<section class="truth-banner" aria-label="Evidence and Truth Boundary">
|
|
1427
|
+
<strong>Evidence-Before-Done Truth Boundary:</strong>
|
|
1428
|
+
${escapeHtml(CONTAINER_TRUTH_DISCLAIMER)}
|
|
1429
|
+
<br />
|
|
1430
|
+
<strong>Provenance note:</strong> ${escapeHtml(art.provenance.notes)}
|
|
1431
|
+
</section>
|
|
1432
|
+
|
|
1433
|
+
<section class="grid-4" aria-label="4-Tier Validation Matrix">
|
|
1434
|
+
<div class="panel" style="margin-bottom:0;">
|
|
1435
|
+
<div class="metric-label">Tier 1 · Container Structure</div>
|
|
1436
|
+
<div class="metric-value">${escapeHtml(val.tiers.containerStructural.status)}</div>
|
|
1437
|
+
<div class="metric-sub">${escapeHtml(val.tiers.containerStructural.summary)}</div>
|
|
1438
|
+
</div>
|
|
1439
|
+
<div class="panel" style="margin-bottom:0;">
|
|
1440
|
+
<div class="metric-label">Tier 2 · Khronos glTF 2.0 Spec</div>
|
|
1441
|
+
<div class="metric-value">${escapeHtml(val.tiers.gltfSpecification.status)}</div>
|
|
1442
|
+
<div class="metric-sub">${escapeHtml(val.tiers.gltfSpecification.summary)}</div>
|
|
1443
|
+
</div>
|
|
1444
|
+
<div class="panel" style="margin-bottom:0;">
|
|
1445
|
+
<div class="metric-label">Tier 3 · Visual Quality</div>
|
|
1446
|
+
<div class="metric-value">${escapeHtml(val.tiers.visualQuality.status)}</div>
|
|
1447
|
+
<div class="metric-sub">${escapeHtml(val.tiers.visualQuality.summary)}</div>
|
|
1448
|
+
</div>
|
|
1449
|
+
<div class="panel" style="margin-bottom:0;">
|
|
1450
|
+
<div class="metric-label">Tier 4 · Live Blender Runtime</div>
|
|
1451
|
+
<div class="metric-value">${escapeHtml(val.tiers.liveRuntime.status)}</div>
|
|
1452
|
+
<div class="metric-sub">${escapeHtml(val.tiers.liveRuntime.summary)}</div>
|
|
1453
|
+
</div>
|
|
1454
|
+
</section>
|
|
1455
|
+
|
|
1456
|
+
<section class="panel" aria-label="Local Client-Side GLB Preview and Bounds Inspector">
|
|
1457
|
+
<div style="display:flex; justify-content:space-between; align-items:center; flex-wrap:wrap; gap:8px; margin-bottom:12px;">
|
|
1458
|
+
<h2 style="margin:0;">Interactive Local GLB Bounding-Box Preview & Client-Side Binary Inspector</h2>
|
|
1459
|
+
<span class="badge badge-neutral">100% Local Browser Inspection · Zero External Uploads</span>
|
|
1460
|
+
</div>
|
|
1461
|
+
<p style="margin:0 0 12px; color:var(--text-muted); font-size:13px;">
|
|
1462
|
+
This preview renders the measured bounding box and coordinate axes (<code>+Y up</code>, <code>${escapeHtml(spatial.coordinateSystem.forwardAxis)} forward</code>, <code>1 unit = ${spatial.unitScaleMetersPerUnit}m</code>) and lets you inspect any local <code>.glb</code> file directly in your browser without transmitting data externally.
|
|
1463
|
+
<strong>Note:</strong> Client-side previewing does not prove production visual correctness or lighting/material accuracy.
|
|
1464
|
+
</p>
|
|
1465
|
+
<div class="preview-grid">
|
|
1466
|
+
<div class="canvas-stage">
|
|
1467
|
+
<canvas id="glbWireframeCanvas" width="720" height="240" aria-label="3D bounding box wireframe preview"></canvas>
|
|
1468
|
+
<div style="display:flex; justify-content:space-between; align-items:center; font-family:var(--mono); font-size:12px; color:var(--text-muted);">
|
|
1469
|
+
<span id="previewBoundsLabel">
|
|
1470
|
+
Bounds: ${spatial.sceneBoundingBox.dimensions ? `[${spatial.sceneBoundingBox.dimensions.join('m × ')}m]` : 'No POSITION bounds'}
|
|
1471
|
+
</span>
|
|
1472
|
+
<button type="button" class="btn" id="resetRotationBtn">Reset Turntable Angle</button>
|
|
1473
|
+
</div>
|
|
1474
|
+
</div>
|
|
1475
|
+
<div class="file-drop-zone">
|
|
1476
|
+
<div style="font-weight:600; margin-bottom:6px;">Inspect Local .glb File (Client-Side)</div>
|
|
1477
|
+
<p style="font-size:12px; color:var(--text-muted); margin:0 0 10px;">
|
|
1478
|
+
Select a local <code>.glb</code> file on your machine to verify its 12-byte GLB header, JSON chunk counts, and POSITION bounding box locally.
|
|
1479
|
+
</p>
|
|
1480
|
+
<input type="file" id="localGlbInput" accept=".glb" style="font-size:12px; width:100%; margin-bottom:12px;" aria-label="Select local GLB file to inspect" />
|
|
1481
|
+
<div id="localInspectResult" style="font-family:var(--mono); font-size:12px; color:var(--text-muted); white-space:pre-wrap;">Loaded manifest: ${escapeHtml(art.filename)} (${counts.meshes} mesh, ${counts.vertices} verts, ~${counts.trianglesEstimate} tris)</div>
|
|
1482
|
+
</div>
|
|
1483
|
+
</div>
|
|
1484
|
+
</section>
|
|
1485
|
+
|
|
1486
|
+
<section class="grid-2" aria-label="Spatial Assumptions and Extensions">
|
|
1487
|
+
<div class="panel" style="margin-bottom:0;">
|
|
1488
|
+
<h2>Spatial, Coordinate & Transform Assumptions</h2>
|
|
1489
|
+
<table>
|
|
1490
|
+
<tbody>
|
|
1491
|
+
<tr><th>Unit Scale</th><td class="num">1 unit = ${spatial.unitScaleMetersPerUnit} m</td></tr>
|
|
1492
|
+
<tr><th>Coordinate Axes</th><td class="num">${escapeHtml(spatial.coordinateSystem.upAxis)} up / ${escapeHtml(spatial.coordinateSystem.forwardAxis)} forward (${escapeHtml(spatial.coordinateSystem.handedness)})</td></tr>
|
|
1493
|
+
<tr><th>Origin Policy</th><td class="num"><code>${escapeHtml(spatial.originPolicy)}</code></td></tr>
|
|
1494
|
+
<tr><th>Bounding Box Min</th><td class="num"><code>${spatial.sceneBoundingBox.min ? `[${spatial.sceneBoundingBox.min.join(', ')}]` : 'null'}</code></td></tr>
|
|
1495
|
+
<tr><th>Bounding Box Max</th><td class="num"><code>${spatial.sceneBoundingBox.max ? `[${spatial.sceneBoundingBox.max.join(', ')}]` : 'null'}</code></td></tr>
|
|
1496
|
+
<tr><th>Dimensions (W×H×D)</th><td class="num"><code>${spatial.sceneBoundingBox.dimensions ? `[${spatial.sceneBoundingBox.dimensions.join(', ')}]` : 'null'}</code></td></tr>
|
|
1497
|
+
</tbody>
|
|
1498
|
+
</table>
|
|
1499
|
+
</div>
|
|
1500
|
+
<div class="panel" style="margin-bottom:0;">
|
|
1501
|
+
<h2>Extensions, Compression & Decoder Requirements</h2>
|
|
1502
|
+
<table>
|
|
1503
|
+
<tbody>
|
|
1504
|
+
<tr><th>Extensions Used</th><td><code>${escapeHtml(ext.extensionsUsed.join(', ') || 'none')}</code></td></tr>
|
|
1505
|
+
<tr><th>Extensions Required</th><td><code>${escapeHtml(ext.extensionsRequired.join(', ') || 'none')}</code></td></tr>
|
|
1506
|
+
<tr><th>Draco (<code>KHR_draco_mesh_compression</code>)</th><td>${ext.compression.draco.decoderRequired ? '<span class="badge badge-warn">DRACOLoader Required</span>' : '<span class="badge badge-pass">Not Required</span>'}</td></tr>
|
|
1507
|
+
<tr><th>Meshopt (<code>EXT_meshopt_compression</code>)</th><td>${ext.compression.meshopt.decoderRequired ? '<span class="badge badge-warn">MeshoptDecoder Required</span>' : '<span class="badge badge-pass">Not Required</span>'}</td></tr>
|
|
1508
|
+
<tr><th>KTX2 / BasisU (<code>KHR_texture_basisu</code>)</th><td>${ext.compression.ktx2BasisU.transcoderRequired ? '<span class="badge badge-warn">KTX2Loader Required</span>' : '<span class="badge badge-pass">Not Required</span>'}</td></tr>
|
|
1509
|
+
<tr><th>External URI References</th><td class="num">${ext.externalResources.filter((r) => r.isExternalFile).length}</td></tr>
|
|
1510
|
+
</tbody>
|
|
1511
|
+
</table>
|
|
1512
|
+
</div>
|
|
1513
|
+
</section>
|
|
1514
|
+
|
|
1515
|
+
<section class="panel" aria-label="Mesh Inventory">
|
|
1516
|
+
<h2>Mesh & Primitive Inventory (${counts.meshes} mesh(es), ${counts.vertices.toLocaleString('en-US')} vertices, ~${counts.trianglesEstimate.toLocaleString('en-US')} triangles)</h2>
|
|
1517
|
+
<table>
|
|
1518
|
+
<thead>
|
|
1519
|
+
<tr>
|
|
1520
|
+
<th class="num">#</th>
|
|
1521
|
+
<th>Mesh Name</th>
|
|
1522
|
+
<th class="num">Primitives</th>
|
|
1523
|
+
<th class="num">Vertices</th>
|
|
1524
|
+
<th class="num">Est. Triangles</th>
|
|
1525
|
+
<th>Vertex Attributes</th>
|
|
1526
|
+
<th class="num">Morph Targets</th>
|
|
1527
|
+
</tr>
|
|
1528
|
+
</thead>
|
|
1529
|
+
<tbody>
|
|
1530
|
+
${meshRows}
|
|
1531
|
+
</tbody>
|
|
1532
|
+
</table>
|
|
1533
|
+
</section>
|
|
1534
|
+
|
|
1535
|
+
<section class="panel" aria-label="Material Inventory">
|
|
1536
|
+
<h2>Material & Texture Portability (${counts.materials} material(s), ${counts.textures} texture(s))</h2>
|
|
1537
|
+
<table>
|
|
1538
|
+
<thead>
|
|
1539
|
+
<tr>
|
|
1540
|
+
<th class="num">#</th>
|
|
1541
|
+
<th>Material Name</th>
|
|
1542
|
+
<th>Alpha Mode</th>
|
|
1543
|
+
<th>Double Sided</th>
|
|
1544
|
+
<th class="num">Metal / Rough</th>
|
|
1545
|
+
<th>Bound Texture Maps</th>
|
|
1546
|
+
<th>Material Extensions</th>
|
|
1547
|
+
</tr>
|
|
1548
|
+
</thead>
|
|
1549
|
+
<tbody>
|
|
1550
|
+
${materialRows}
|
|
1551
|
+
</tbody>
|
|
1552
|
+
</table>
|
|
1553
|
+
</section>
|
|
1554
|
+
|
|
1555
|
+
<section class="panel" aria-label="Animation Inventory">
|
|
1556
|
+
<h2>Animation Clips & Playback Contract (${counts.animations} clip(s))</h2>
|
|
1557
|
+
<table>
|
|
1558
|
+
<thead>
|
|
1559
|
+
<tr>
|
|
1560
|
+
<th class="num">#</th>
|
|
1561
|
+
<th>Clip Name</th>
|
|
1562
|
+
<th class="num">Channels</th>
|
|
1563
|
+
<th class="num">Samplers</th>
|
|
1564
|
+
<th class="num">Duration</th>
|
|
1565
|
+
<th>Target Paths</th>
|
|
1566
|
+
<th>Interpolation</th>
|
|
1567
|
+
</tr>
|
|
1568
|
+
</thead>
|
|
1569
|
+
<tbody>
|
|
1570
|
+
${animationRows}
|
|
1571
|
+
</tbody>
|
|
1572
|
+
</table>
|
|
1573
|
+
</section>
|
|
1574
|
+
|
|
1575
|
+
<section class="grid-2" aria-label="Diagnostics and Next Actions">
|
|
1576
|
+
<div class="panel" style="margin-bottom:0;">
|
|
1577
|
+
<h2>Diagnostics, Warnings & Unresolved Caveats</h2>
|
|
1578
|
+
${
|
|
1579
|
+
val.errors.length > 0
|
|
1580
|
+
? `<div style="margin-bottom:10px;"><strong style="color:var(--fail-text);">Structural Errors (${val.errors.length}):</strong><ul class="compact-list">${val.errors.map((e) => `<li>${escapeHtml(e)}</li>`).join('')}</ul></div>`
|
|
1581
|
+
: ''
|
|
1582
|
+
}
|
|
1583
|
+
${
|
|
1584
|
+
val.warnings.length + val.performanceWarnings.length > 0
|
|
1585
|
+
? `<div style="margin-bottom:10px;"><strong style="color:var(--warn-text);">Warnings (${val.warnings.length + val.performanceWarnings.length}):</strong><ul class="compact-list">${[...val.warnings, ...val.performanceWarnings].map((w) => `<li>${escapeHtml(w)}</li>`).join('')}</ul></div>`
|
|
1586
|
+
: ''
|
|
1587
|
+
}
|
|
1588
|
+
<div>
|
|
1589
|
+
<strong>Unresolved Issues & Verification Boundaries:</strong>
|
|
1590
|
+
<ul class="compact-list">
|
|
1591
|
+
${manifest.unresolvedIssues.map((u) => `<li>${escapeHtml(u)}</li>`).join('')}
|
|
1592
|
+
</ul>
|
|
1593
|
+
</div>
|
|
1594
|
+
</div>
|
|
1595
|
+
<div class="panel" style="margin-bottom:0;">
|
|
1596
|
+
<h2>Recommended Next Actions</h2>
|
|
1597
|
+
<ul class="compact-list">
|
|
1598
|
+
${manifest.nextActions.map((a) => `<li>${escapeHtml(a)}</li>`).join('')}
|
|
1599
|
+
</ul>
|
|
1600
|
+
</div>
|
|
1601
|
+
</section>
|
|
1602
|
+
|
|
1603
|
+
<section class="panel" aria-label="Three.js Integration Code">
|
|
1604
|
+
<h2>Three.js Integration Module (<code>GLTFLoader</code> + Framing + Disposal)</h2>
|
|
1605
|
+
<pre class="code-block"><code>${escapeHtml(snippets.threejs)}</code></pre>
|
|
1606
|
+
</section>
|
|
1607
|
+
|
|
1608
|
+
<section class="panel" aria-label="React Three Fiber Integration Code">
|
|
1609
|
+
<h2>React Three Fiber Component Integration (<code>@react-three/fiber</code> + <code>@react-three/drei</code>)</h2>
|
|
1610
|
+
<pre class="code-block"><code>${escapeHtml(snippets.reactThreeFiber)}</code></pre>
|
|
1611
|
+
</section>
|
|
1612
|
+
</div>
|
|
1613
|
+
|
|
1614
|
+
<script id="blendops-handoff-manifest-data" type="application/json">${embeddedManifestJson}</script>
|
|
1615
|
+
<script>
|
|
1616
|
+
(function () {
|
|
1617
|
+
const manifestDataEl = document.getElementById('blendops-handoff-manifest-data');
|
|
1618
|
+
const initialManifest = manifestDataEl ? JSON.parse(manifestDataEl.textContent) : null;
|
|
1619
|
+
const canvas = document.getElementById('glbWireframeCanvas');
|
|
1620
|
+
const resetBtn = document.getElementById('resetRotationBtn');
|
|
1621
|
+
const fileInput = document.getElementById('localGlbInput');
|
|
1622
|
+
const resultBox = document.getElementById('localInspectResult');
|
|
1623
|
+
const boundsLabel = document.getElementById('previewBoundsLabel');
|
|
1624
|
+
|
|
1625
|
+
let activeDims = (initialManifest &&
|
|
1626
|
+
initialManifest.spatialAndTransformAssumptions &&
|
|
1627
|
+
initialManifest.spatialAndTransformAssumptions.sceneBoundingBox &&
|
|
1628
|
+
initialManifest.spatialAndTransformAssumptions.sceneBoundingBox.dimensions) || [1, 1, 1];
|
|
1629
|
+
let yaw = 0.62;
|
|
1630
|
+
|
|
1631
|
+
function drawWireframeBounds() {
|
|
1632
|
+
if (!canvas || !canvas.getContext) return;
|
|
1633
|
+
const ctx = canvas.getContext('2d');
|
|
1634
|
+
const w = canvas.width;
|
|
1635
|
+
const h = canvas.height;
|
|
1636
|
+
ctx.clearRect(0, 0, w, h);
|
|
1637
|
+
|
|
1638
|
+
const dx = Math.max(Number(activeDims[0]) || 1, 0.15);
|
|
1639
|
+
const dy = Math.max(Number(activeDims[1]) || 1, 0.15);
|
|
1640
|
+
const dz = Math.max(Number(activeDims[2]) || 0.25, 0.15);
|
|
1641
|
+
const maxD = Math.max(dx, dy, dz, 0.5);
|
|
1642
|
+
const sx = (dx / maxD) * 70;
|
|
1643
|
+
const sy = (dy / maxD) * 70;
|
|
1644
|
+
const sz = (dz / maxD) * 70;
|
|
1645
|
+
|
|
1646
|
+
const cosY = Math.cos(yaw);
|
|
1647
|
+
const sinY = Math.sin(yaw);
|
|
1648
|
+
function project(x, y, z) {
|
|
1649
|
+
const rx = x * cosY - z * sinY;
|
|
1650
|
+
const rz = x * sinY + z * cosY;
|
|
1651
|
+
const px = w / 2 + rx * 1.15;
|
|
1652
|
+
const py = h / 2 - y * 1.05 + rz * 0.35;
|
|
1653
|
+
return [px, py];
|
|
1654
|
+
}
|
|
1655
|
+
|
|
1656
|
+
const corners = [
|
|
1657
|
+
[-sx, -sy, -sz], [sx, -sy, -sz], [sx, sy, -sz], [-sx, sy, -sz],
|
|
1658
|
+
[-sx, -sy, sz], [sx, -sy, sz], [sx, sy, sz], [-sx, sy, sz],
|
|
1659
|
+
].map((c) => project(c[0], c[1], c[2]));
|
|
1660
|
+
|
|
1661
|
+
const edges = [
|
|
1662
|
+
[0,1],[1,2],[2,3],[3,0],
|
|
1663
|
+
[4,5],[5,6],[6,7],[7,4],
|
|
1664
|
+
[0,4],[1,5],[2,6],[3,7],
|
|
1665
|
+
];
|
|
1666
|
+
|
|
1667
|
+
ctx.strokeStyle = '#38bdf8';
|
|
1668
|
+
ctx.lineWidth = 1.6;
|
|
1669
|
+
ctx.beginPath();
|
|
1670
|
+
for (let i = 0; i < edges.length; i++) {
|
|
1671
|
+
const a = corners[edges[i][0]];
|
|
1672
|
+
const b = corners[edges[i][1]];
|
|
1673
|
+
ctx.moveTo(a[0], a[1]);
|
|
1674
|
+
ctx.lineTo(b[0], b[1]);
|
|
1675
|
+
}
|
|
1676
|
+
ctx.stroke();
|
|
1677
|
+
|
|
1678
|
+
// Draw +Y up and +Z forward indicator at origin
|
|
1679
|
+
const o = project(0, 0, 0);
|
|
1680
|
+
const up = project(0, 48, 0);
|
|
1681
|
+
ctx.strokeStyle = '#4ade80';
|
|
1682
|
+
ctx.beginPath();
|
|
1683
|
+
ctx.moveTo(o[0], o[1]);
|
|
1684
|
+
ctx.lineTo(up[0], up[1]);
|
|
1685
|
+
ctx.stroke();
|
|
1686
|
+
ctx.fillStyle = '#4ade80';
|
|
1687
|
+
ctx.font = '11px monospace';
|
|
1688
|
+
ctx.fillText('+Y up', up[0] + 4, up[1]);
|
|
1689
|
+
}
|
|
1690
|
+
|
|
1691
|
+
drawWireframeBounds();
|
|
1692
|
+
if (resetBtn) {
|
|
1693
|
+
resetBtn.addEventListener('click', function () {
|
|
1694
|
+
yaw += 0.45;
|
|
1695
|
+
drawWireframeBounds();
|
|
1696
|
+
});
|
|
1697
|
+
}
|
|
1698
|
+
|
|
1699
|
+
if (fileInput) {
|
|
1700
|
+
fileInput.addEventListener('change', function (ev) {
|
|
1701
|
+
const file = ev.target && ev.target.files && ev.target.files[0];
|
|
1702
|
+
if (!file) return;
|
|
1703
|
+
const reader = new FileReader();
|
|
1704
|
+
reader.onload = function () {
|
|
1705
|
+
try {
|
|
1706
|
+
const buf = reader.result;
|
|
1707
|
+
const view = new DataView(buf);
|
|
1708
|
+
if (buf.byteLength < 20) {
|
|
1709
|
+
resultBox.textContent = 'Invalid GLB: file is smaller than 20-byte header.';
|
|
1710
|
+
return;
|
|
1711
|
+
}
|
|
1712
|
+
const magic = view.getUint32(0, true);
|
|
1713
|
+
const version = view.getUint32(4, true);
|
|
1714
|
+
const declaredLen = view.getUint32(8, true);
|
|
1715
|
+
const jsonLen = view.getUint32(12, true);
|
|
1716
|
+
const jsonType = view.getUint32(16, true);
|
|
1717
|
+
if (magic !== 0x46546c67 || version !== 2 || jsonType !== 0x4e4f534a) {
|
|
1718
|
+
resultBox.textContent = 'Invalid GLB header or Chunk 0 type.';
|
|
1719
|
+
return;
|
|
1720
|
+
}
|
|
1721
|
+
const jsonBytes = new Uint8Array(buf, 20, jsonLen);
|
|
1722
|
+
const jsonStr = new TextDecoder('utf-8').decode(jsonBytes);
|
|
1723
|
+
const gltf = JSON.parse(jsonStr);
|
|
1724
|
+
const meshes = Array.isArray(gltf.meshes) ? gltf.meshes.length : 0;
|
|
1725
|
+
const mats = Array.isArray(gltf.materials) ? gltf.materials.length : 0;
|
|
1726
|
+
const anims = Array.isArray(gltf.animations) ? gltf.animations.length : 0;
|
|
1727
|
+
resultBox.textContent =
|
|
1728
|
+
'Client-side GLB check passed:\\n' +
|
|
1729
|
+
'- File: ' + file.name + ' (' + declaredLen + ' bytes)\\n' +
|
|
1730
|
+
'- Meshes: ' + meshes + ', Materials: ' + mats + ', Animations: ' + anims + '\\n' +
|
|
1731
|
+
'- Visual/runtime status: Not Verified (local container parse only)';
|
|
1732
|
+
if (boundsLabel) {
|
|
1733
|
+
boundsLabel.textContent = 'Inspected locally: ' + file.name + ' (' + declaredLen + ' bytes)';
|
|
1734
|
+
}
|
|
1735
|
+
yaw += 0.35;
|
|
1736
|
+
drawWireframeBounds();
|
|
1737
|
+
} catch (err) {
|
|
1738
|
+
resultBox.textContent = 'Client-side GLB parse error: ' + (err && err.message ? err.message : String(err));
|
|
1739
|
+
}
|
|
1740
|
+
};
|
|
1741
|
+
reader.readAsArrayBuffer(file);
|
|
1742
|
+
});
|
|
1743
|
+
}
|
|
1744
|
+
})();
|
|
1745
|
+
</script>
|
|
1746
|
+
</body>
|
|
1747
|
+
</html>
|
|
1748
|
+
`;
|
|
1749
|
+
}
|
|
1750
|
+
|
|
1751
|
+
function assembleHandoffReportBundleFromInspection(
|
|
1752
|
+
inspection,
|
|
1753
|
+
{
|
|
1754
|
+
filename = 'artifact.glb',
|
|
1755
|
+
targetViewerStack = 'threejs',
|
|
1756
|
+
sourceKind = 'unverified',
|
|
1757
|
+
isSyntheticFixture = false,
|
|
1758
|
+
currentRunProvenanceVerified = false,
|
|
1759
|
+
runtimePath = 'none',
|
|
1760
|
+
runtimeStatus = 'Not Run',
|
|
1761
|
+
artifactStatus = 'Not Produced',
|
|
1762
|
+
unitScaleMetersPerUnit = 1.0,
|
|
1763
|
+
forwardAxis = '+Z',
|
|
1764
|
+
originPolicy = 'unverified',
|
|
1765
|
+
performanceBudget = DEFAULT_WEB_PERFORMANCE_BUDGET,
|
|
1766
|
+
} = {},
|
|
1767
|
+
) {
|
|
1768
|
+
const manifest = buildGlbWebHandoffManifestFromInspection(inspection, {
|
|
1769
|
+
filename,
|
|
1770
|
+
targetViewerStack,
|
|
1771
|
+
sourceKind,
|
|
1772
|
+
isSyntheticFixture,
|
|
1773
|
+
currentRunProvenanceVerified,
|
|
1774
|
+
runtimePath,
|
|
1775
|
+
runtimeStatus,
|
|
1776
|
+
artifactStatus,
|
|
1777
|
+
unitScaleMetersPerUnit,
|
|
1778
|
+
forwardAxis,
|
|
1779
|
+
originPolicy,
|
|
1780
|
+
performanceBudget,
|
|
1781
|
+
});
|
|
1782
|
+
|
|
1783
|
+
const manifestValidation = validateGlbWebHandoffManifest(manifest);
|
|
1784
|
+
const snippets = buildWebIntegrationCodeSnippets(manifest);
|
|
1785
|
+
const markdownSummary = formatGlbHandoffMarkdownSummary(manifest);
|
|
1786
|
+
const htmlReport = renderGlbHandoffHtmlReport(manifest, snippets);
|
|
1787
|
+
|
|
1788
|
+
const jsonReport = {
|
|
1789
|
+
schemaVersion: '1.0.0',
|
|
1790
|
+
reportKind: 'glb-web-handoff-report',
|
|
1791
|
+
valid: Boolean(inspection.valid && manifestValidation.valid),
|
|
1792
|
+
manifestValidation,
|
|
1793
|
+
manifest,
|
|
1794
|
+
inspection: {
|
|
1795
|
+
valid: inspection.valid,
|
|
1796
|
+
byteSize: inspection.byteSize,
|
|
1797
|
+
sha256: inspection.sha256,
|
|
1798
|
+
header: inspection.header,
|
|
1799
|
+
chunks: inspection.chunks,
|
|
1800
|
+
counts: inspection.counts,
|
|
1801
|
+
extensions: inspection.extensions,
|
|
1802
|
+
bounds: inspection.bounds,
|
|
1803
|
+
validationTiers: inspection.validationTiers,
|
|
1804
|
+
truthBoundary: inspection.truthBoundary,
|
|
1805
|
+
errors: inspection.errors,
|
|
1806
|
+
warnings: inspection.warnings,
|
|
1807
|
+
},
|
|
1808
|
+
integrationSnippets: snippets,
|
|
1809
|
+
markdownSummary,
|
|
1810
|
+
};
|
|
1811
|
+
|
|
1812
|
+
return {
|
|
1813
|
+
ok: Boolean(inspection.valid && manifestValidation.valid),
|
|
1814
|
+
manifest,
|
|
1815
|
+
manifestValidation,
|
|
1816
|
+
inspection,
|
|
1817
|
+
snippets,
|
|
1818
|
+
markdownSummary,
|
|
1819
|
+
jsonReport,
|
|
1820
|
+
htmlReport,
|
|
1821
|
+
};
|
|
1822
|
+
}
|
|
1823
|
+
|
|
1824
|
+
export function generateGlbHandoffReportFromBufferSync(
|
|
1825
|
+
buffer,
|
|
1826
|
+
{
|
|
1827
|
+
filename = 'artifact.glb',
|
|
1828
|
+
targetViewerStack = 'threejs',
|
|
1829
|
+
sourceKind = 'unverified',
|
|
1830
|
+
isSyntheticFixture = false,
|
|
1831
|
+
currentRunProvenanceVerified = false,
|
|
1832
|
+
runtimePath = 'none',
|
|
1833
|
+
runtimeStatus = 'Not Run',
|
|
1834
|
+
artifactStatus = 'Not Produced',
|
|
1835
|
+
unitScaleMetersPerUnit = 1.0,
|
|
1836
|
+
forwardAxis = '+Z',
|
|
1837
|
+
originPolicy = 'unverified',
|
|
1838
|
+
strictPositionBounds = false,
|
|
1839
|
+
performanceBudget = DEFAULT_WEB_PERFORMANCE_BUDGET,
|
|
1840
|
+
} = {},
|
|
1841
|
+
) {
|
|
1842
|
+
const inspection = inspectGlbBuffer(buffer, { strictPositionBounds });
|
|
1843
|
+
return assembleHandoffReportBundleFromInspection(inspection, {
|
|
1844
|
+
filename,
|
|
1845
|
+
targetViewerStack,
|
|
1846
|
+
sourceKind,
|
|
1847
|
+
isSyntheticFixture,
|
|
1848
|
+
currentRunProvenanceVerified,
|
|
1849
|
+
runtimePath,
|
|
1850
|
+
runtimeStatus,
|
|
1851
|
+
artifactStatus,
|
|
1852
|
+
unitScaleMetersPerUnit,
|
|
1853
|
+
forwardAxis,
|
|
1854
|
+
originPolicy,
|
|
1855
|
+
performanceBudget,
|
|
1856
|
+
});
|
|
1857
|
+
}
|
|
1858
|
+
|
|
1859
|
+
export async function generateGlbHandoffReportFromBuffer(
|
|
1860
|
+
buffer,
|
|
1861
|
+
{
|
|
1862
|
+
filename = 'artifact.glb',
|
|
1863
|
+
targetViewerStack = 'threejs',
|
|
1864
|
+
sourceKind = 'unverified',
|
|
1865
|
+
isSyntheticFixture = false,
|
|
1866
|
+
currentRunProvenanceVerified = false,
|
|
1867
|
+
runtimePath = 'none',
|
|
1868
|
+
runtimeStatus = 'Not Run',
|
|
1869
|
+
artifactStatus = 'Not Produced',
|
|
1870
|
+
unitScaleMetersPerUnit = 1.0,
|
|
1871
|
+
forwardAxis = '+Z',
|
|
1872
|
+
originPolicy = 'unverified',
|
|
1873
|
+
strictPositionBounds = false,
|
|
1874
|
+
runKhronos = false,
|
|
1875
|
+
validatorModuleLoader,
|
|
1876
|
+
performanceBudget = DEFAULT_WEB_PERFORMANCE_BUDGET,
|
|
1877
|
+
} = {},
|
|
1878
|
+
) {
|
|
1879
|
+
const inspection = inspectGlbBuffer(buffer, { strictPositionBounds });
|
|
1880
|
+
if (runKhronos && Buffer.isBuffer(buffer) && inspection.valid) {
|
|
1881
|
+
const { runKhronosGltfValidator } = await import('./inspect-glb.mjs');
|
|
1882
|
+
const khronosRes = await runKhronosGltfValidator(buffer, { validatorModuleLoader });
|
|
1883
|
+
inspection.khronosValidator = khronosRes;
|
|
1884
|
+
if (khronosRes.status === 'passed') {
|
|
1885
|
+
inspection.validationTiers.gltfSpecification = {
|
|
1886
|
+
status: (khronosRes.issues?.numWarnings ?? 0) > 0 ? 'Warn' : 'Passed',
|
|
1887
|
+
tool: 'gltf-validator',
|
|
1888
|
+
summary: khronosRes.message,
|
|
1889
|
+
};
|
|
1890
|
+
} else if (khronosRes.status === 'unavailable') {
|
|
1891
|
+
inspection.validationTiers.gltfSpecification = {
|
|
1892
|
+
status: 'Unavailable',
|
|
1893
|
+
tool: 'gltf-validator',
|
|
1894
|
+
summary: khronosRes.message,
|
|
1895
|
+
};
|
|
1896
|
+
} else if (khronosRes.status === 'failed' || khronosRes.status === 'error') {
|
|
1897
|
+
inspection.valid = false;
|
|
1898
|
+
inspection.errors.push(khronosRes.message);
|
|
1899
|
+
inspection.validationTiers.gltfSpecification = {
|
|
1900
|
+
status: 'Failed',
|
|
1901
|
+
tool: 'gltf-validator',
|
|
1902
|
+
summary: khronosRes.message,
|
|
1903
|
+
};
|
|
1904
|
+
}
|
|
1905
|
+
}
|
|
1906
|
+
|
|
1907
|
+
return assembleHandoffReportBundleFromInspection(inspection, {
|
|
1908
|
+
filename,
|
|
1909
|
+
targetViewerStack,
|
|
1910
|
+
sourceKind,
|
|
1911
|
+
isSyntheticFixture,
|
|
1912
|
+
currentRunProvenanceVerified,
|
|
1913
|
+
runtimePath,
|
|
1914
|
+
runtimeStatus,
|
|
1915
|
+
artifactStatus,
|
|
1916
|
+
unitScaleMetersPerUnit,
|
|
1917
|
+
forwardAxis,
|
|
1918
|
+
originPolicy,
|
|
1919
|
+
performanceBudget,
|
|
1920
|
+
});
|
|
1921
|
+
}
|
|
1922
|
+
|
|
1923
|
+
function pathsEqualOnPlatform(pathA, pathB) {
|
|
1924
|
+
if (!pathA || !pathB) return false;
|
|
1925
|
+
const normA = path.resolve(pathA);
|
|
1926
|
+
const normB = path.resolve(pathB);
|
|
1927
|
+
if (process.platform === 'win32') {
|
|
1928
|
+
return normA.toLowerCase() === normB.toLowerCase();
|
|
1929
|
+
}
|
|
1930
|
+
return normA === normB;
|
|
1931
|
+
}
|
|
1932
|
+
|
|
1933
|
+
export function validateSafeReportOutputDir(
|
|
1934
|
+
rawOutDir,
|
|
1935
|
+
{ repoRoot = path.resolve(__dirname, '..'), inputGlbPath = null } = {},
|
|
1936
|
+
) {
|
|
1937
|
+
if (typeof rawOutDir !== 'string' || rawOutDir.trim().length === 0 || rawOutDir.includes('\0')) {
|
|
1938
|
+
throw new Error('Invalid --out-dir path: must be a non-empty string');
|
|
1939
|
+
}
|
|
1940
|
+
const trimmed = rawOutDir.trim();
|
|
1941
|
+
if (trimmed === '~' || trimmed.startsWith('~/') || trimmed.startsWith('~\\')) {
|
|
1942
|
+
throw new Error(`Unsafe --out-dir path (home directory '${trimmed}' is rejected)`);
|
|
1943
|
+
}
|
|
1944
|
+
if (/^[a-zA-Z]:[\\/]?$/.test(trimmed) || trimmed.startsWith('\\\\') || trimmed === '/' || trimmed === '\\') {
|
|
1945
|
+
throw new Error(
|
|
1946
|
+
`Unsafe --out-dir path (filesystem root, drive root, or UNC path is forbidden): ${rawOutDir}`,
|
|
1947
|
+
);
|
|
1948
|
+
}
|
|
1949
|
+
|
|
1950
|
+
const absOut = path.resolve(trimmed.replace(/\\/g, path.sep));
|
|
1951
|
+
const parsedRoot = path.parse(absOut).root;
|
|
1952
|
+
if (pathsEqualOnPlatform(absOut, parsedRoot)) {
|
|
1953
|
+
throw new Error(`Unsafe --out-dir path (filesystem root is forbidden): ${rawOutDir}`);
|
|
1954
|
+
}
|
|
1955
|
+
|
|
1956
|
+
const home = os.homedir ? path.resolve(os.homedir()) : '';
|
|
1957
|
+
const homeReal = home && fs.existsSync(home) ? fs.realpathSync(home) : home;
|
|
1958
|
+
if ((home && pathsEqualOnPlatform(absOut, home)) || (homeReal && pathsEqualOnPlatform(absOut, homeReal))) {
|
|
1959
|
+
throw new Error(`Unsafe --out-dir path (user home root is forbidden): ${rawOutDir}`);
|
|
1960
|
+
}
|
|
1961
|
+
|
|
1962
|
+
const tmpRoot = path.resolve(os.tmpdir());
|
|
1963
|
+
const tmpReal = fs.existsSync(tmpRoot) ? fs.realpathSync(tmpRoot) : tmpRoot;
|
|
1964
|
+
if (pathsEqualOnPlatform(absOut, tmpRoot) || pathsEqualOnPlatform(absOut, tmpReal)) {
|
|
1965
|
+
throw new Error(`Unsafe --out-dir path (OS temp root itself is forbidden): ${rawOutDir}`);
|
|
1966
|
+
}
|
|
1967
|
+
|
|
1968
|
+
// Check nearest existing directory and ancestors for symlinks/junctions
|
|
1969
|
+
let cursor = absOut;
|
|
1970
|
+
const tail = [];
|
|
1971
|
+
while (!fs.existsSync(cursor)) {
|
|
1972
|
+
const parent = path.dirname(cursor);
|
|
1973
|
+
if (parent === cursor) break;
|
|
1974
|
+
tail.unshift(path.basename(cursor));
|
|
1975
|
+
cursor = parent;
|
|
1976
|
+
}
|
|
1977
|
+
const existingLstat = fs.lstatSync(cursor);
|
|
1978
|
+
if (existingLstat.isSymbolicLink()) {
|
|
1979
|
+
throw new Error(`Refusing symbolic link in --out-dir path: ${cursor}`);
|
|
1980
|
+
}
|
|
1981
|
+
if (!existingLstat.isDirectory()) {
|
|
1982
|
+
throw new Error(`Target --out-dir path or ancestor is not a directory: ${cursor}`);
|
|
1983
|
+
}
|
|
1984
|
+
|
|
1985
|
+
const realRepoRoot = fs.existsSync(repoRoot) ? fs.realpathSync(repoRoot) : path.resolve(repoRoot);
|
|
1986
|
+
let ancestorCheck = cursor;
|
|
1987
|
+
while (ancestorCheck && !pathsEqualOnPlatform(ancestorCheck, path.parse(ancestorCheck).root)) {
|
|
1988
|
+
if (
|
|
1989
|
+
pathsEqualOnPlatform(ancestorCheck, tmpRoot) ||
|
|
1990
|
+
pathsEqualOnPlatform(ancestorCheck, tmpReal) ||
|
|
1991
|
+
pathsEqualOnPlatform(ancestorCheck, realRepoRoot)
|
|
1992
|
+
) {
|
|
1993
|
+
break;
|
|
1994
|
+
}
|
|
1995
|
+
const st = fs.lstatSync(ancestorCheck);
|
|
1996
|
+
if (st.isSymbolicLink()) {
|
|
1997
|
+
throw new Error(`Refusing symbolic link in --out-dir path: ${ancestorCheck}`);
|
|
1998
|
+
}
|
|
1999
|
+
const nextParent = path.dirname(ancestorCheck);
|
|
2000
|
+
if (nextParent === ancestorCheck) break;
|
|
2001
|
+
ancestorCheck = nextParent;
|
|
2002
|
+
}
|
|
2003
|
+
|
|
2004
|
+
const realBase = fs.realpathSync(cursor);
|
|
2005
|
+
const resolvedOut = tail.length > 0 ? path.join(realBase, ...tail) : realBase;
|
|
2006
|
+
|
|
2007
|
+
if (pathsEqualOnPlatform(resolvedOut, tmpRoot) || pathsEqualOnPlatform(resolvedOut, tmpReal)) {
|
|
2008
|
+
throw new Error(`Unsafe --out-dir path (OS temp root itself is forbidden): ${rawOutDir}`);
|
|
2009
|
+
}
|
|
2010
|
+
if (
|
|
2011
|
+
(home && pathsEqualOnPlatform(resolvedOut, home)) ||
|
|
2012
|
+
(homeReal && pathsEqualOnPlatform(resolvedOut, homeReal))
|
|
2013
|
+
) {
|
|
2014
|
+
throw new Error(`Unsafe --out-dir path (user home root is forbidden): ${rawOutDir}`);
|
|
2015
|
+
}
|
|
2016
|
+
|
|
2017
|
+
if (pathsEqualOnPlatform(resolvedOut, realRepoRoot) || pathsEqualOnPlatform(absOut, realRepoRoot)) {
|
|
2018
|
+
throw new Error(`Refusing to write handoff report files directly into repository root (${realRepoRoot})`);
|
|
2019
|
+
}
|
|
2020
|
+
|
|
2021
|
+
const relFromRepo = path.relative(
|
|
2022
|
+
process.platform === 'win32' ? realRepoRoot.toLowerCase() : realRepoRoot,
|
|
2023
|
+
process.platform === 'win32' ? resolvedOut.toLowerCase() : resolvedOut,
|
|
2024
|
+
);
|
|
2025
|
+
const isInsideRepo = relFromRepo !== '' && !relFromRepo.startsWith('..') && !path.isAbsolute(relFromRepo);
|
|
2026
|
+
if (isInsideRepo) {
|
|
2027
|
+
const topSeg = relFromRepo.split(path.sep)[0];
|
|
2028
|
+
if (PROTECTED_REPO_DIRS.has(topSeg)) {
|
|
2029
|
+
throw new Error(
|
|
2030
|
+
`Unsafe --out-dir destination inside protected BlendOps repository directory '${topSeg}': ${rawOutDir}`,
|
|
2031
|
+
);
|
|
2032
|
+
}
|
|
2033
|
+
if (topSeg === 'dist' && relFromRepo.split(path.sep).length < 2) {
|
|
2034
|
+
throw new Error('Unsafe --out-dir destination: must be a subdirectory inside dist/, not dist/ itself');
|
|
2035
|
+
}
|
|
2036
|
+
}
|
|
2037
|
+
|
|
2038
|
+
if (inputGlbPath) {
|
|
2039
|
+
const absGlb = path.resolve(inputGlbPath);
|
|
2040
|
+
const realGlb = fs.existsSync(absGlb) ? fs.realpathSync(absGlb) : absGlb;
|
|
2041
|
+
if (
|
|
2042
|
+
pathsEqualOnPlatform(absGlb, resolvedOut) ||
|
|
2043
|
+
pathsEqualOnPlatform(absGlb, absOut) ||
|
|
2044
|
+
pathsEqualOnPlatform(realGlb, resolvedOut)
|
|
2045
|
+
) {
|
|
2046
|
+
throw new Error('Refusing --out-dir that collides with the input GLB file path');
|
|
2047
|
+
}
|
|
2048
|
+
}
|
|
2049
|
+
|
|
2050
|
+
return resolvedOut;
|
|
2051
|
+
}
|
|
2052
|
+
|
|
2053
|
+
function writeAtomicReportFile(targetAbsPath, content) {
|
|
2054
|
+
if (fs.existsSync(targetAbsPath)) {
|
|
2055
|
+
const lstat = fs.lstatSync(targetAbsPath);
|
|
2056
|
+
if (lstat.isSymbolicLink()) {
|
|
2057
|
+
throw new Error(`Refusing to overwrite symbolic link at ${targetAbsPath}`);
|
|
2058
|
+
}
|
|
2059
|
+
}
|
|
2060
|
+
const dir = path.dirname(targetAbsPath);
|
|
2061
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
2062
|
+
const tmpPath = path.join(
|
|
2063
|
+
dir,
|
|
2064
|
+
`.${path.basename(targetAbsPath)}.tmp-${process.pid}-${Date.now()}-${crypto.randomBytes(6).toString('hex')}`,
|
|
2065
|
+
);
|
|
2066
|
+
try {
|
|
2067
|
+
fs.writeFileSync(tmpPath, content, { encoding: 'utf8', flag: 'wx' });
|
|
2068
|
+
fs.renameSync(tmpPath, targetAbsPath);
|
|
2069
|
+
} finally {
|
|
2070
|
+
if (fs.existsSync(tmpPath)) {
|
|
2071
|
+
try {
|
|
2072
|
+
fs.rmSync(tmpPath, { force: true });
|
|
2073
|
+
} catch {
|
|
2074
|
+
// ignore cleanup error
|
|
2075
|
+
}
|
|
2076
|
+
}
|
|
2077
|
+
}
|
|
2078
|
+
}
|
|
2079
|
+
|
|
2080
|
+
function persistHandoffBundleToOutDir(bundle, { outDir, repoRoot, resolvedGlb }) {
|
|
2081
|
+
if (outDir === null || outDir === undefined) return null;
|
|
2082
|
+
const safeOutDir = validateSafeReportOutputDir(outDir, {
|
|
2083
|
+
repoRoot,
|
|
2084
|
+
inputGlbPath: resolvedGlb,
|
|
2085
|
+
});
|
|
2086
|
+
fs.mkdirSync(safeOutDir, { recursive: true });
|
|
2087
|
+
|
|
2088
|
+
const manifestPath = path.join(safeOutDir, 'handoff-manifest.json');
|
|
2089
|
+
const jsonReportPath = path.join(safeOutDir, 'handoff-report.json');
|
|
2090
|
+
const htmlReportPath = path.join(safeOutDir, 'handoff-report.html');
|
|
2091
|
+
const markdownPath = path.join(safeOutDir, 'HANDOFF_SUMMARY.md');
|
|
2092
|
+
|
|
2093
|
+
for (const candidate of [manifestPath, jsonReportPath, htmlReportPath, markdownPath]) {
|
|
2094
|
+
if (path.resolve(candidate) === resolvedGlb) {
|
|
2095
|
+
throw new Error(`Refusing to overwrite input GLB file: ${resolvedGlb}`);
|
|
2096
|
+
}
|
|
2097
|
+
}
|
|
2098
|
+
|
|
2099
|
+
writeAtomicReportFile(manifestPath, `${JSON.stringify(bundle.manifest, null, 2)}\n`);
|
|
2100
|
+
writeAtomicReportFile(jsonReportPath, `${JSON.stringify(bundle.jsonReport, null, 2)}\n`);
|
|
2101
|
+
writeAtomicReportFile(htmlReportPath, bundle.htmlReport);
|
|
2102
|
+
writeAtomicReportFile(markdownPath, bundle.markdownSummary);
|
|
2103
|
+
|
|
2104
|
+
return {
|
|
2105
|
+
outDir: safeOutDir,
|
|
2106
|
+
manifestPath,
|
|
2107
|
+
jsonReportPath,
|
|
2108
|
+
htmlReportPath,
|
|
2109
|
+
markdownPath,
|
|
2110
|
+
};
|
|
2111
|
+
}
|
|
2112
|
+
|
|
2113
|
+
export function generateGlbHandoffReportFromFileSync(
|
|
2114
|
+
glbFilePath,
|
|
2115
|
+
{
|
|
2116
|
+
outDir = null,
|
|
2117
|
+
targetViewerStack = 'threejs',
|
|
2118
|
+
sourceKind = 'user_supplied',
|
|
2119
|
+
isSyntheticFixture = false,
|
|
2120
|
+
currentRunProvenanceVerified = false,
|
|
2121
|
+
runtimePath = 'none',
|
|
2122
|
+
runtimeStatus = 'Not Run',
|
|
2123
|
+
artifactStatus = 'Not Produced',
|
|
2124
|
+
unitScaleMetersPerUnit = 1.0,
|
|
2125
|
+
forwardAxis = '+Z',
|
|
2126
|
+
originPolicy = 'unverified',
|
|
2127
|
+
strictPositionBounds = false,
|
|
2128
|
+
performanceBudget = DEFAULT_WEB_PERFORMANCE_BUDGET,
|
|
2129
|
+
repoRoot = path.resolve(__dirname, '..'),
|
|
2130
|
+
} = {},
|
|
2131
|
+
) {
|
|
2132
|
+
if (typeof glbFilePath !== 'string' || glbFilePath.trim().length === 0) {
|
|
2133
|
+
throw new Error('GLB file path must be a non-empty string');
|
|
2134
|
+
}
|
|
2135
|
+
const resolvedGlb = path.resolve(glbFilePath);
|
|
2136
|
+
if (!fs.existsSync(resolvedGlb)) {
|
|
2137
|
+
throw new Error(`GLB file does not exist: ${glbFilePath}`);
|
|
2138
|
+
}
|
|
2139
|
+
const lstat = fs.lstatSync(resolvedGlb);
|
|
2140
|
+
if (lstat.isSymbolicLink()) {
|
|
2141
|
+
throw new Error(`Refusing symbolic link for GLB input file: ${glbFilePath}`);
|
|
2142
|
+
}
|
|
2143
|
+
if (!lstat.isFile()) {
|
|
2144
|
+
throw new Error(`GLB path is not a regular file: ${glbFilePath}`);
|
|
2145
|
+
}
|
|
2146
|
+
|
|
2147
|
+
const originalBuffer = fs.readFileSync(resolvedGlb);
|
|
2148
|
+
const preSha256 = crypto.createHash('sha256').update(originalBuffer).digest('hex');
|
|
2149
|
+
|
|
2150
|
+
const bundle = generateGlbHandoffReportFromBufferSync(originalBuffer, {
|
|
2151
|
+
filename: path.basename(resolvedGlb),
|
|
2152
|
+
targetViewerStack,
|
|
2153
|
+
sourceKind,
|
|
2154
|
+
isSyntheticFixture,
|
|
2155
|
+
currentRunProvenanceVerified,
|
|
2156
|
+
runtimePath,
|
|
2157
|
+
runtimeStatus,
|
|
2158
|
+
artifactStatus,
|
|
2159
|
+
unitScaleMetersPerUnit,
|
|
2160
|
+
forwardAxis,
|
|
2161
|
+
originPolicy,
|
|
2162
|
+
strictPositionBounds,
|
|
2163
|
+
performanceBudget,
|
|
2164
|
+
});
|
|
2165
|
+
|
|
2166
|
+
const writtenFiles = persistHandoffBundleToOutDir(bundle, {
|
|
2167
|
+
outDir,
|
|
2168
|
+
repoRoot,
|
|
2169
|
+
resolvedGlb,
|
|
2170
|
+
});
|
|
2171
|
+
|
|
2172
|
+
const postBuffer = fs.readFileSync(resolvedGlb);
|
|
2173
|
+
const postSha256 = crypto.createHash('sha256').update(postBuffer).digest('hex');
|
|
2174
|
+
if (preSha256 !== postSha256) {
|
|
2175
|
+
throw new Error('Invariant violation: input GLB file digest changed during inspection');
|
|
2176
|
+
}
|
|
2177
|
+
|
|
2178
|
+
return {
|
|
2179
|
+
...bundle,
|
|
2180
|
+
inputGlbPath: resolvedGlb,
|
|
2181
|
+
inputSha256: preSha256,
|
|
2182
|
+
writtenFiles,
|
|
2183
|
+
};
|
|
2184
|
+
}
|
|
2185
|
+
|
|
2186
|
+
export async function generateGlbHandoffReportFromFile(
|
|
2187
|
+
glbFilePath,
|
|
2188
|
+
{
|
|
2189
|
+
outDir = null,
|
|
2190
|
+
targetViewerStack = 'threejs',
|
|
2191
|
+
sourceKind = 'user_supplied',
|
|
2192
|
+
isSyntheticFixture = false,
|
|
2193
|
+
currentRunProvenanceVerified = false,
|
|
2194
|
+
runtimePath = 'none',
|
|
2195
|
+
runtimeStatus = 'Not Run',
|
|
2196
|
+
artifactStatus = 'Not Produced',
|
|
2197
|
+
unitScaleMetersPerUnit = 1.0,
|
|
2198
|
+
forwardAxis = '+Z',
|
|
2199
|
+
originPolicy = 'unverified',
|
|
2200
|
+
strictPositionBounds = false,
|
|
2201
|
+
runKhronos = false,
|
|
2202
|
+
validatorModuleLoader,
|
|
2203
|
+
performanceBudget = DEFAULT_WEB_PERFORMANCE_BUDGET,
|
|
2204
|
+
repoRoot = path.resolve(__dirname, '..'),
|
|
2205
|
+
} = {},
|
|
2206
|
+
) {
|
|
2207
|
+
if (typeof glbFilePath !== 'string' || glbFilePath.trim().length === 0) {
|
|
2208
|
+
throw new Error('GLB file path must be a non-empty string');
|
|
2209
|
+
}
|
|
2210
|
+
const resolvedGlb = path.resolve(glbFilePath);
|
|
2211
|
+
if (!fs.existsSync(resolvedGlb)) {
|
|
2212
|
+
throw new Error(`GLB file does not exist: ${glbFilePath}`);
|
|
2213
|
+
}
|
|
2214
|
+
const lstat = fs.lstatSync(resolvedGlb);
|
|
2215
|
+
if (lstat.isSymbolicLink()) {
|
|
2216
|
+
throw new Error(`Refusing symbolic link for GLB input file: ${glbFilePath}`);
|
|
2217
|
+
}
|
|
2218
|
+
if (!lstat.isFile()) {
|
|
2219
|
+
throw new Error(`GLB path is not a regular file: ${glbFilePath}`);
|
|
2220
|
+
}
|
|
2221
|
+
|
|
2222
|
+
const originalBuffer = fs.readFileSync(resolvedGlb);
|
|
2223
|
+
const preSha256 = crypto.createHash('sha256').update(originalBuffer).digest('hex');
|
|
2224
|
+
|
|
2225
|
+
const bundle = await generateGlbHandoffReportFromBuffer(originalBuffer, {
|
|
2226
|
+
filename: path.basename(resolvedGlb),
|
|
2227
|
+
targetViewerStack,
|
|
2228
|
+
sourceKind,
|
|
2229
|
+
isSyntheticFixture,
|
|
2230
|
+
currentRunProvenanceVerified,
|
|
2231
|
+
runtimePath,
|
|
2232
|
+
runtimeStatus,
|
|
2233
|
+
artifactStatus,
|
|
2234
|
+
unitScaleMetersPerUnit,
|
|
2235
|
+
forwardAxis,
|
|
2236
|
+
originPolicy,
|
|
2237
|
+
strictPositionBounds,
|
|
2238
|
+
runKhronos,
|
|
2239
|
+
validatorModuleLoader,
|
|
2240
|
+
performanceBudget,
|
|
2241
|
+
});
|
|
2242
|
+
|
|
2243
|
+
const writtenFiles = persistHandoffBundleToOutDir(bundle, {
|
|
2244
|
+
outDir,
|
|
2245
|
+
repoRoot,
|
|
2246
|
+
resolvedGlb,
|
|
2247
|
+
});
|
|
2248
|
+
|
|
2249
|
+
const postBuffer = fs.readFileSync(resolvedGlb);
|
|
2250
|
+
const postSha256 = crypto.createHash('sha256').update(postBuffer).digest('hex');
|
|
2251
|
+
if (preSha256 !== postSha256) {
|
|
2252
|
+
throw new Error('Invariant violation: input GLB file digest changed during inspection');
|
|
2253
|
+
}
|
|
2254
|
+
|
|
2255
|
+
return {
|
|
2256
|
+
...bundle,
|
|
2257
|
+
inputGlbPath: resolvedGlb,
|
|
2258
|
+
inputSha256: preSha256,
|
|
2259
|
+
writtenFiles,
|
|
2260
|
+
};
|
|
2261
|
+
}
|
|
2262
|
+
|
|
2263
|
+
async function main() {
|
|
2264
|
+
const args = process.argv.slice(2);
|
|
2265
|
+
let glbPath = null;
|
|
2266
|
+
let outDir = null;
|
|
2267
|
+
let validateManifestPath = null;
|
|
2268
|
+
let viewerStack = 'threejs';
|
|
2269
|
+
let jsonOutput = false;
|
|
2270
|
+
let selfTest = false;
|
|
2271
|
+
let strictBounds = false;
|
|
2272
|
+
let runKhronos = false;
|
|
2273
|
+
let syntheticFlag = false;
|
|
2274
|
+
|
|
2275
|
+
for (let i = 0; i < args.length; i += 1) {
|
|
2276
|
+
const arg = args[i];
|
|
2277
|
+
if (arg === '--json') {
|
|
2278
|
+
jsonOutput = true;
|
|
2279
|
+
} else if (arg === '--self-test') {
|
|
2280
|
+
selfTest = true;
|
|
2281
|
+
} else if (arg === '--strict-bounds') {
|
|
2282
|
+
strictBounds = true;
|
|
2283
|
+
} else if (arg === '--khronos') {
|
|
2284
|
+
runKhronos = true;
|
|
2285
|
+
} else if (arg === '--synthetic') {
|
|
2286
|
+
syntheticFlag = true;
|
|
2287
|
+
} else if (arg === '--glb' && i + 1 < args.length) {
|
|
2288
|
+
glbPath = args[++i];
|
|
2289
|
+
} else if (arg === '--out-dir' && i + 1 < args.length) {
|
|
2290
|
+
outDir = args[++i];
|
|
2291
|
+
} else if (arg === '--validate-manifest' && i + 1 < args.length) {
|
|
2292
|
+
validateManifestPath = args[++i];
|
|
2293
|
+
} else if (arg === '--viewer' && i + 1 < args.length) {
|
|
2294
|
+
viewerStack = args[++i];
|
|
2295
|
+
} else if (!arg.startsWith('--') && !glbPath) {
|
|
2296
|
+
glbPath = arg;
|
|
2297
|
+
}
|
|
2298
|
+
}
|
|
2299
|
+
|
|
2300
|
+
try {
|
|
2301
|
+
if (selfTest) {
|
|
2302
|
+
const buf = buildMinimalValidGlbBuffer();
|
|
2303
|
+
const res = await generateGlbHandoffReportFromBuffer(buf, {
|
|
2304
|
+
filename: 'synthetic-self-test.glb',
|
|
2305
|
+
targetViewerStack: viewerStack,
|
|
2306
|
+
sourceKind: 'synthetic_fixture',
|
|
2307
|
+
isSyntheticFixture: true,
|
|
2308
|
+
strictPositionBounds: true,
|
|
2309
|
+
runKhronos,
|
|
2310
|
+
});
|
|
2311
|
+
if (jsonOutput) {
|
|
2312
|
+
process.stdout.write(`${JSON.stringify(res.jsonReport, null, 2)}\n`);
|
|
2313
|
+
} else {
|
|
2314
|
+
process.stdout.write(res.markdownSummary);
|
|
2315
|
+
}
|
|
2316
|
+
process.exitCode = res.ok ? 0 : 1;
|
|
2317
|
+
return;
|
|
2318
|
+
}
|
|
2319
|
+
|
|
2320
|
+
if (validateManifestPath) {
|
|
2321
|
+
const absManifest = path.resolve(validateManifestPath);
|
|
2322
|
+
if (!fs.existsSync(absManifest)) {
|
|
2323
|
+
process.stderr.write(`Handoff manifest file not found: ${validateManifestPath}\n`);
|
|
2324
|
+
process.exitCode = 1;
|
|
2325
|
+
return;
|
|
2326
|
+
}
|
|
2327
|
+
const parsed = JSON.parse(fs.readFileSync(absManifest, 'utf8'));
|
|
2328
|
+
const res = validateGlbWebHandoffManifest(parsed);
|
|
2329
|
+
if (jsonOutput) {
|
|
2330
|
+
process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
|
|
2331
|
+
} else if (res.valid) {
|
|
2332
|
+
process.stdout.write(
|
|
2333
|
+
`GLB web handoff manifest valid: ${parsed.manifestId} (runtime=${parsed.truthStates.runtimeStatus}, artifact=${parsed.truthStates.artifactStatus}, verdict=${parsed.validationSummary.overallVerdict})\n`,
|
|
2334
|
+
);
|
|
2335
|
+
} else {
|
|
2336
|
+
process.stderr.write(
|
|
2337
|
+
`GLB web handoff manifest validation failed:\n${res.errors.map((e) => `- ${e}`).join('\n')}\n`,
|
|
2338
|
+
);
|
|
2339
|
+
}
|
|
2340
|
+
process.exitCode = res.valid ? 0 : 1;
|
|
2341
|
+
return;
|
|
2342
|
+
}
|
|
2343
|
+
|
|
2344
|
+
if (!glbPath) {
|
|
2345
|
+
process.stderr.write(
|
|
2346
|
+
'Usage: node scripts/generate-glb-handoff-report.mjs <file.glb> [--out-dir <dir>] [--viewer <threejs|react-three-fiber|model-viewer|babylonjs|generic-webgl>] [--json] [--strict-bounds] [--khronos] | --validate-manifest <manifest.json> | --self-test\n',
|
|
2347
|
+
);
|
|
2348
|
+
process.exitCode = 1;
|
|
2349
|
+
return;
|
|
2350
|
+
}
|
|
2351
|
+
|
|
2352
|
+
const res = await generateGlbHandoffReportFromFile(glbPath, {
|
|
2353
|
+
outDir,
|
|
2354
|
+
targetViewerStack: viewerStack,
|
|
2355
|
+
sourceKind: syntheticFlag ? 'synthetic_fixture' : 'user_supplied',
|
|
2356
|
+
isSyntheticFixture: syntheticFlag,
|
|
2357
|
+
strictPositionBounds: strictBounds,
|
|
2358
|
+
runKhronos,
|
|
2359
|
+
});
|
|
2360
|
+
|
|
2361
|
+
if (jsonOutput) {
|
|
2362
|
+
process.stdout.write(`${JSON.stringify(res.jsonReport, null, 2)}\n`);
|
|
2363
|
+
} else {
|
|
2364
|
+
process.stdout.write(res.markdownSummary);
|
|
2365
|
+
}
|
|
2366
|
+
process.exitCode = res.ok ? 0 : 1;
|
|
2367
|
+
} catch (err) {
|
|
2368
|
+
const msg = err instanceof Error ? err.message : String(err);
|
|
2369
|
+
process.stderr.write(`GLB handoff report error: ${msg}\n`);
|
|
2370
|
+
process.exitCode = 1;
|
|
2371
|
+
}
|
|
2372
|
+
}
|
|
2373
|
+
|
|
2374
|
+
if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
|
|
2375
|
+
main();
|
|
2376
|
+
}
|