@skenora/scene-plan 0.1.2

package/dist/description/information.js

@@ -0,0 +1,980 @@
+import { createEmptySceneDocument, describeOwnedPbrCapability, fieldRuleToJsonSchema, getAuthoredMaterialJsonSchema, getRuntimeQualityPolicyJsonSchema, getMaterialExecutionPolicyJsonSchema, describeMaterialEffects, describeMaterialEffectParameters, describeMaterialAnimation, describeMaterialProgramCapability, describeMaterialProgramV2Capability, describeTextureProgramCapability, describeRenderGraphCapability, describeSimulationProgramCapability, describeProceduralGeometryCapability, getMaterialProgramJsonSchema, getTextureProgramJsonSchema, getRenderGraphJsonSchema, getSimulationProgramJsonSchema, getProceduralGeometryProgramJsonSchema, SCENE_CAPABILITY_VERSIONS, TEXTURE_REFERENCE_RULE, } from "@skenora/contracts";
+import { createBuiltInFlowNodeRegistry } from "@skenora/flow";
+import { SCENE_BLUEPRINT_SCHEMA, SCENE_PLAN_VERSION, SCENE_PLAN_DEFAULTS_PROFILE, } from "../model/types.js";
+import { applySceneRecipe, describeSceneRecipes } from "./recipes.js";
+import { describeSkenoraExampleRecipes } from "./example-recipes.js";
+import { BLUEPRINT_BINDING_RULE, BLUEPRINT_CAMERA_PATH_RULE, BLUEPRINT_ENTITY_RULES, BLUEPRINT_LIGHT_RULE, BLUEPRINT_RESOURCE_RULE, BLUEPRINT_SETTING_RULES, BLUEPRINT_TEXTURE_ANIMATION_RULE, BLUEPRINT_TRANSFORM_RULE, } from "./scene-fields.js";
+export const SCENE_INFORMATION_VERSION = 1;
+/** Detached data; safe to serialize without importing Babylon or starting a host. */
+export function describeSceneCapabilities(options = {}) {
+    const descriptions = [
+        describeOwnedPbrCapability(),
+        ...describeMaterialEffects(),
+        describeMaterialAnimation(),
+        describeMaterialProgramCapability(),
+        describeMaterialProgramV2Capability(),
+        describeTextureProgramCapability(),
+        describeRenderGraphCapability(),
+        describeSimulationProgramCapability(),
+        describeProceduralGeometryCapability(),
+    ];
+    const add = (id, domain, rule, targets, semantics, requirements = []) => {
+        descriptions.push({
+            id,
+            version: SCENE_CAPABILITY_VERSIONS[id],
+            domain,
+            description: rule.description,
+            inputSchema: fieldRuleToJsonSchema(rule),
+            targets,
+            semantics,
+            requirements,
+            diagnostics: [
+                {
+                    code: "unavailable-scene-capability",
+                    repair: DIAGNOSTIC_REPAIRS["unavailable-scene-capability"],
+                },
+            ],
+        });
+    };
+    for (const [kind, rule] of Object.entries(BLUEPRINT_ENTITY_RULES)) {
+        if (kind === "procedural")
+            continue;
+        add(`skenora.entity.${kind}`, "entities", rule, [kind], [
+            "IDs are stable within a Blueprint. parentId references another entity; cycles are rejected.",
+            "Coordinates are local, Y-up, in meters. The runtime uses its existing left-handed scene; imported glTF conversion stays inside the importer.",
+            kind === "group"
+                ? "A group without sourceNode is authored. Imported source groups remain borrowed from their model asset."
+                : "A capability description does not provide model bounds, texture bytes, or visual approval.",
+        ], kind === "model"
+            ? [
+                "A host-supplied glTF/GLB logical resource binding and permitted resource provider.",
+            ]
+            : kind === "particle"
+                ? [
+                    "Provide textureAssetRef and its host texture binding for visible particles; no default image is downloaded.",
+                ]
+                : kind === "annotation"
+                    ? [
+                        "Renderer.projectAnnotations() returns render-pixel coordinates and visibility. The host presents text and converts render pixels to its layout coordinates.",
+                    ]
+                    : []);
+    }
+    for (const [key, rule] of Object.entries(BLUEPRINT_SETTING_RULES)) {
+        add(`skenora.scene.${key === "postProcess" ? "post-process" : key}`, "presentation", rule, ["scene"], [
+            "Omitted fields use scene-v1 native defaults. Explicit values are preserved unless a separate host execution policy limits them.",
+            "Resource declarations do not enable a network provider. The host owns resource access.",
+        ]);
+    }
+    add("skenora.scene.lights", "presentation", BLUEPRINT_LIGHT_RULE, ["scene"], [
+        "Omitted lights use the explicit default light. An empty array creates no direct lights.",
+    ]);
+    add("skenora.animation.texture", "animation", BLUEPRINT_TEXTURE_ANIMATION_RULE, ["material texture"], [
+        "Targets are authored material IDs; a shared texture is updated once, independent instances receive the same sample.",
+        "Texture presence and compatibility are checked at runtime.",
+    ]);
+    add("skenora.camera.path", "animation", BLUEPRINT_CAMERA_PATH_RULE, ["viewport camera"], ["Playback is transient and does not write an Editor history entry."]);
+    return descriptions.filter((item) => (!options.domains || options.domains.includes(item.domain)) &&
+        (!options.capabilityIds || options.capabilityIds.includes(item.id)));
+}
+const text = { type: "string" };
+const id = {
+    type: "string",
+    pattern: "^[A-Za-z][A-Za-z0-9._:-]{0,127}$",
+};
+const array = (items) => ({
+    type: "array",
+    items,
+    default: [],
+});
+const object = (properties, required = [], closed = false) => ({
+    type: "object",
+    properties,
+    required,
+    additionalProperties: !closed,
+});
+/** Syntax contract only. Reference, hierarchy, resource, device and host checks remain mandatory. */
+export function getSceneBlueprintJsonSchema(options = {}) {
+    const entitySchemas = Object.entries(BLUEPRINT_ENTITY_RULES).map(([kind, rule]) => {
+        const schema = fieldRuleToJsonSchema(rule);
+        const properties = schema.properties;
+        properties.id = { ...properties.id, ...id };
+        properties.kind = { const: kind };
+        properties.transform = getTransformSchema(options.normalized ?? false);
+        if (kind === "procedural")
+            properties.program = getProceduralGeometryProgramJsonSchema();
+        if (options.normalized)
+            schema.required = [
+                ...schema.required,
+                "name",
+                "parentId",
+                "enabled",
+                "visible",
+                "transform",
+            ];
+        return schema;
+    });
+    const legacyMaterial = object({ id }, ["id"]);
+    legacyMaterial.not = { required: ["creation"] };
+    legacyMaterial.description =
+        "Legacy imported-material override; use owned creation for a typed new surface. Native material validation still applies.";
+    const flow = object({
+        schema: { const: "skenora.flow" },
+        version: { const: 1 },
+        id,
+        name: text,
+        enabled: { type: "boolean" },
+        concurrency: { enum: ["parallel", "restart", "drop"] },
+        errorPolicy: { enum: ["stop", "continue"] },
+        nodes: array(object({
+            id,
+            type: text,
+            name: text,
+            enabled: { type: "boolean" },
+            config: { type: "object" },
+            position: object({ x: { type: "number" }, y: { type: "number" } }, [
+                "x",
+                "y",
+            ]),
+        }, ["id", "type", "config"])),
+        edges: array(object({
+            id,
+            kind: { enum: ["control", "value"] },
+            sourceNodeId: id,
+            sourcePort: text,
+            targetNodeId: id,
+            targetPort: text,
+        }, [
+            "id",
+            "kind",
+            "sourceNodeId",
+            "sourcePort",
+            "targetNodeId",
+            "targetPort",
+        ])),
+    }, ["schema", "version", "id", "name", "enabled", "nodes", "edges"]);
+    const properties = {
+        schema: { const: SCENE_BLUEPRINT_SCHEMA },
+        version: { const: SCENE_PLAN_VERSION },
+        defaultsProfile: {
+            const: SCENE_PLAN_DEFAULTS_PROFILE,
+            default: SCENE_PLAN_DEFAULTS_PROFILE,
+        },
+        scene: object({ id, name: text }, ["id", "name"]),
+        requires: array(object({ id, version: text, required: { type: "boolean" }, config: {} }, [
+            "id",
+            "version",
+            "required",
+        ])),
+        resources: array(fieldRuleToJsonSchema(BLUEPRINT_RESOURCE_RULE)),
+        entities: array({ oneOf: entitySchemas }),
+        materials: array({
+            oneOf: [getAuthoredMaterialJsonSchema(), legacyMaterial],
+        }),
+        materialBindings: array(fieldRuleToJsonSchema(BLUEPRINT_BINDING_RULE)),
+        textureAnimations: array(fieldRuleToJsonSchema(BLUEPRINT_TEXTURE_ANIMATION_RULE)),
+        cameraPaths: array(fieldRuleToJsonSchema(BLUEPRINT_CAMERA_PATH_RULE)),
+        lights: {
+            type: "array",
+            items: fieldRuleToJsonSchema(BLUEPRINT_LIGHT_RULE),
+        },
+        flows: array(flow),
+        initialVariables: { type: "object", default: {} },
+        extensions: array(object({
+            namespace: text,
+            version: { type: "integer" },
+            capability: text,
+            required: { type: "boolean" },
+            data: {},
+        }, ["namespace", "version", "capability", "required", "data"])),
+    };
+    for (const [key, rule] of Object.entries(BLUEPRINT_SETTING_RULES))
+        properties[key] = fieldRuleToJsonSchema(rule);
+    const required = ["schema", "version", "scene"];
+    if (options.normalized)
+        required.push("defaultsProfile", "requires", "resources", "entities", "materials", "materialBindings", "textureAnimations", "cameraPaths", "flows", "initialVariables", "extensions");
+    return {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        $id: `urn:skenora:scene-blueprint:1:${options.normalized ? "normalized" : "input"}`,
+        ...object(properties, required, true),
+        description: "Skenora SceneBlueprint V1. Schema validation does not compile, resolve references, load resources, execute behaviors or validate GPU readiness.",
+    };
+}
+function getTransformSchema(normalized) {
+    const schema = fieldRuleToJsonSchema(BLUEPRINT_TRANSFORM_RULE);
+    schema.not = { required: ["rotationRadians", "rotationQuaternion"] };
+    if (normalized) {
+        schema.required = ["coordinateSpace", "units", "position", "scaling"];
+        schema.oneOf = [
+            { required: ["rotationRadians"] },
+            { required: ["rotationQuaternion"] },
+        ];
+    }
+    return schema;
+}
+const DIAGNOSTIC_REPAIRS = Object.freeze({
+    "material-effect-pass-unsupported": "Dissolve version 1 supports opaque main-pass depth only. Remove dissolve or explicitly disable shadows, SSAO, depth-of-field and glow; quality limits do not rewrite this authoring restriction.",
+    "invalid-json": "Provide finite, serializable JSON values without functions or cycles.",
+    "invalid-input": "Provide a Blueprint object or JSON text.",
+    "invalid-schema": "Use schema skenora.scene.blueprint and version 1.",
+    "unsupported-version": "Use the protocol and defaults versions in the information bundle.",
+    "unknown-field": "Remove the unsupported field or use an explicitly registered extension.",
+    "missing-field": "Supply the required field at the reported input path.",
+    "invalid-value": "Use the declared type, range, enum and cross-field constraints.",
+    "budget-exceeded": "Reduce graph nodes, parameters, segments, array counts, vertices or triangles to fit the advertised host limits.",
+    "invalid-id": "Use a stable ID starting with a letter and containing at most 128 allowed characters.",
+    "duplicate-id": "Give each declaration a unique ID within its domain.",
+    "missing-reference": "Declare the referenced logical entity, material or resource, or correct its ID.",
+    "hierarchy-cycle": "Remove the cyclic parent relationship.",
+    "invalid-transform": "Use local meters and either Euler radians or a unit quaternion.",
+    "invalid-quaternion": "Supply all four components with unit length.",
+    "missing-resource-binding": "Ask the host for an authorized logical resource binding; do not invent a URL.",
+    "resource-kind-mismatch": "Choose a resource of the required kind.",
+    "resource-integrity-mismatch": "Use the host-supplied resource revision and integrity metadata.",
+    "missing-capability": "Choose a capability ID/version the host reports as available.",
+    "unsupported-capability": "Remove or replace the unavailable capability; JSON cannot install it.",
+    "unavailable-scene-capability": "The input uses an unavailable, disabled or unconfirmed capability. Replace that feature or ask the host to enable a compatible implementation.",
+    "flow-invalid": "Check node types, ports and configuration against the supplied Flow definitions.",
+    "flow-target-missing": "Use a declared and supported target ID for the Flow action.",
+    "native-document-invalid": "Correct the compiled-domain field indicated by source mappings and native semantic validation.",
+});
+/** Redacts arbitrary plugin messages/details. IDs/paths originate in authoring input. */
+export function toPublicScenePlanDiagnostics(diagnostics) {
+    return diagnostics.map((item) => ({
+        code: Object.hasOwn(DIAGNOSTIC_REPAIRS, item.code)
+            ? item.code
+            : "scene-plan-failed",
+        severity: item.severity,
+        stage: item.stage,
+        path: [...item.path],
+        repair: DIAGNOSTIC_REPAIRS[item.code] ??
+            "Review the reported input path using the public contract; ask the host for a sanitized diagnostic if needed.",
+    }));
+}
+export function getScenePlanInformation(options = {}) {
+    return {
+        informationVersion: SCENE_INFORMATION_VERSION,
+        protocol: {
+            schema: SCENE_BLUEPRINT_SCHEMA,
+            version: SCENE_PLAN_VERSION,
+            defaultsProfile: SCENE_PLAN_DEFAULTS_PROFILE,
+        },
+        capabilities: describeSceneCapabilities(options),
+        schemas: {
+            blueprintInput: getSceneBlueprintJsonSchema(),
+            normalizedBlueprint: getSceneBlueprintJsonSchema({ normalized: true }),
+            authoredMaterial: getAuthoredMaterialJsonSchema(),
+            proceduralGeometryProgram: getProceduralGeometryProgramJsonSchema(),
+            materialProgram: getMaterialProgramJsonSchema(),
+            textureProgram: getTextureProgramJsonSchema(),
+            renderGraph: getRenderGraphJsonSchema(),
+            simulationProgram: getSimulationProgramJsonSchema(),
+            textureReference: fieldRuleToJsonSchema(TEXTURE_REFERENCE_RULE),
+            hostQualityPolicy: getRuntimeQualityPolicyJsonSchema(),
+            hostMaterialPolicy: getMaterialExecutionPolicyJsonSchema(),
+        },
+        nativeDefaults: createEmptySceneDocument(),
+        flowNodes: createBuiltInFlowNodeRegistry()
+            .list()
+            .map(({ type, category, inputs, outputs }) => structuredClone({ type, category, inputs, outputs })),
+        diagnostics: { ...DIAGNOSTIC_REPAIRS },
+        examples: getSceneBlueprintExamples(),
+        repairExamples: getSceneBlueprintRepairExamples(),
+        recipes: [...describeSceneRecipes(), ...describeSkenoraExampleRecipes()],
+        materialEffectParameters: describeMaterialEffectParameters(),
+        resourceMetadata: [
+            "logical id",
+            "kind",
+            "media type",
+            "safe label",
+            "optional integrity",
+            "host-supplied bounds and source material slots",
+        ],
+        boundaries: [
+            "Descriptions are not availability. Supply observed capabilityAvailability to compilation when known; runtime checks the features used by the document again.",
+            "Only host resource bindings resolve bytes. Do not send private locators, tokens, credentials, arbitrary error messages or provider configuration to a model.",
+            "Defaults in JSON Schema are annotations. Skenora normalization/compilation applies the documented defaults.",
+            "The normalized Blueprint schema describes normalizeSceneBlueprint output, not the native document; compilation fills native setting and material defaults afterwards.",
+            "Material preparation checks resource decoding and a surface program variant, not every render pass or visual quality.",
+            "Flow port metadata is not a complete configuration schema. The built-in registry and semantic validator remain authoritative for behavior configuration.",
+            "SimulationProgram is a renderer-lab contract, not SceneDocument persistence. Its optional WebGPU runtime is imported from @skenora/runtime/simulation.",
+        ],
+    };
+}
+export function getSceneBlueprintExamples() {
+    const examples = [
+        {
+            id: "shared-pbr",
+            note: "No external assets. One owned material, two entity-scoped bindings. Geometry and camera are explicit.",
+            blueprint: {
+                schema: SCENE_BLUEPRINT_SCHEMA,
+                version: 1,
+                scene: { id: "shared-pbr", name: "Shared PBR" },
+                entities: [
+                    { id: "composition", kind: "group" },
+                    {
+                        id: "sphere",
+                        kind: "primitive",
+                        primitive: "sphere",
+                        parentId: "composition",
+                        transform: { position: { x: -0.8, y: 0.5, z: 0 } },
+                    },
+                    {
+                        id: "box",
+                        kind: "primitive",
+                        primitive: "box",
+                        parentId: "composition",
+                        transform: { position: { x: 0.8, y: 0.5, z: 0 } },
+                    },
+                ],
+                materials: [
+                    {
+                        id: "ceramic",
+                        creation: { version: 1, family: "pbr", sharing: "shared" },
+                        baseColor: { r: 0.08, g: 0.32, b: 0.55 },
+                        metallic: 0,
+                        roughness: 0.35,
+                    },
+                ],
+                materialBindings: [
+                    { id: "sphere-ceramic", materialId: "ceramic", entityId: "sphere" },
+                    { id: "box-ceramic", materialId: "ceramic", entityId: "box" },
+                ],
+                camera: {
+                    mode: "orbit",
+                    position: { x: 3, y: 2.4, z: -5 },
+                    target: { x: 0, y: 0.5, z: 0 },
+                },
+                environment: {
+                    enabled: false,
+                    background: { mode: "color", color: "#202124" },
+                },
+                lights: [
+                    {
+                        id: "fill",
+                        type: "hemispheric",
+                        enabled: true,
+                        intensity: 1,
+                        color: { r: 1, g: 1, b: 1 },
+                        rotation: { x: -Math.PI / 2, y: 0, z: 0 },
+                    },
+                ],
+                postProcess: {
+                    enabled: true,
+                    antialiasing: "fxaa",
+                    toneMappingEnabled: true,
+                    toneMappingType: "aces",
+                    exposure: 1,
+                },
+            },
+        },
+    ];
+    const shared = examples[0].blueprint;
+    examples.push({
+        id: "supplied-model-slot",
+        note: "Requires the original two-parts.gltf fixture under logical resource two-parts. Selectors use its declared extras IDs; runtime slot discovery remains authoritative after any asset replacement.",
+        blueprint: {
+            schema: SCENE_BLUEPRINT_SCHEMA,
+            version: 1,
+            scene: {
+                id: "supplied-model-slot",
+                name: "Explicit supplied model slot",
+            },
+            resources: [
+                {
+                    id: "two-parts",
+                    kind: "model",
+                    mediaType: "model/gltf+json",
+                    label: "Original two-part material fixture",
+                },
+            ],
+            entities: [
+                { id: "composition", kind: "group" },
+                {
+                    id: "model",
+                    kind: "model",
+                    parentId: "composition",
+                    assetRef: "two-parts",
+                },
+            ],
+            materials: [
+                {
+                    id: "replacement",
+                    creation: { version: 1, family: "pbr" },
+                    baseColor: { r: 0.1, g: 0.55, b: 0.3 },
+                    roughness: 0.6,
+                    doubleSided: true,
+                },
+            ],
+            materialBindings: [
+                {
+                    id: "left-replacement",
+                    materialId: "replacement",
+                    entityId: "model",
+                    target: { nodeId: "left-part", slot: 0 },
+                },
+            ],
+            camera: structuredClone(shared.camera),
+            // The legacy default points along +Z. Use upward fill so both sides of
+            // this planar fixture receive light without changing scene-v1 defaults.
+            lights: structuredClone(shared.lights),
+        },
+    });
+    examples.push({
+        id: "gradient-rim",
+        note: "Bounded gradient albedo and view-dependent rim emission on two shared instances. No screen-space glow, external shader code or hidden assets.",
+        blueprint: {
+            ...structuredClone(shared),
+            scene: { id: "gradient-rim", name: "Gradient and rim emission" },
+            materials: shared.materials.map((material) => ({
+                ...structuredClone(material),
+                effects: {
+                    version: 1,
+                    gradient: {
+                        axis: "y",
+                        space: "local",
+                        start: -0.5,
+                        end: 0.5,
+                        colorStart: { r: 0.05, g: 0.1, b: 0.6 },
+                        colorEnd: { r: 0.7, g: 0.1, b: 0.3 },
+                        strength: 0.9,
+                    },
+                    rim: { color: { r: 0.1, g: 0.4, b: 1 }, intensity: 1.5, power: 3 },
+                },
+            })),
+        },
+    });
+    examples.push({
+        id: "independent-pbr",
+        note: "The same definition creates one instance per binding; material-ID operations still affect both. Use distinct definitions for independent authored values.",
+        blueprint: {
+            ...structuredClone(shared),
+            scene: { id: "independent-pbr", name: "Independent PBR instances" },
+            materials: shared.materials.map((material) => ({
+                ...structuredClone(material),
+                creation: {
+                    version: 1,
+                    family: "pbr",
+                    sharing: "per-binding",
+                },
+            })),
+        },
+    });
+    const dissolve = {
+        ...structuredClone(shared),
+        scene: { id: "animated-dissolve", name: "Bounded animated dissolve" },
+        materials: [
+            {
+                id: "ceramic",
+                creation: { version: 1, family: "pbr" },
+                roughness: 0.4,
+                effects: {
+                    version: 1,
+                    gradient: {
+                        start: -0.5,
+                        end: 0.5,
+                        colorStart: { r: 0.05, g: 0.1, b: 0.6 },
+                        colorEnd: { r: 0.7, g: 0.1, b: 0.3 },
+                    },
+                    rim: { color: { r: 0.1, g: 0.4, b: 1 }, intensity: 0.5 },
+                    dissolve: {
+                        progress: 0,
+                        scale: 6,
+                        seed: 7,
+                        edgeWidth: 0.06,
+                        edgeColor: { r: 1, g: 0.25, b: 0.03 },
+                        edgeIntensity: 2,
+                    },
+                },
+                animations: [
+                    {
+                        version: 1,
+                        id: "reveal",
+                        property: "dissolveProgress",
+                        from: 1,
+                        to: 0,
+                        durationMs: 1800,
+                        easing: "easeInOut",
+                        autoStart: true,
+                    },
+                ],
+            },
+        ],
+        // These are authored restrictions; the host does not silently disable them.
+        postProcess: {
+            ...structuredClone(shared.postProcess),
+            glow: false,
+            depthOfField: false,
+            ssao: { enabled: false },
+        },
+    };
+    examples.push({
+        id: "animated-dissolve",
+        blueprint: dissolve,
+        note: "No external assets. Playback reveals both shared surfaces once on the session clock. Opaque cutout only; all shadow/depth-effect/glow passes are explicitly off.",
+    });
+    const flowAnimation = {
+        ...structuredClone(dissolve),
+        scene: {
+            id: "flow-material-animation",
+            name: "Flow controlled material animation",
+        },
+        materials: [
+            {
+                ...structuredClone(dissolve.materials[0]),
+                animations: [
+                    {
+                        version: 1,
+                        id: "reveal",
+                        property: "dissolveProgress",
+                        from: 1,
+                        to: 0,
+                        durationMs: 1800,
+                        autoStart: false,
+                    },
+                ],
+            },
+        ],
+        flows: [
+            {
+                schema: "skenora.flow",
+                version: 1,
+                id: "reveal-on-ready",
+                name: "Reveal on ready",
+                enabled: true,
+                nodes: [
+                    { id: "ready", type: "trigger.scene.ready", config: {} },
+                    {
+                        id: "play",
+                        type: "action.materialAnimation.play",
+                        config: { materialId: "ceramic", animationId: "reveal" },
+                    },
+                ],
+                edges: [
+                    {
+                        id: "start-reveal",
+                        kind: "control",
+                        sourceNodeId: "ready",
+                        sourcePort: "next",
+                        targetNodeId: "play",
+                        targetPort: "in",
+                    },
+                ],
+            },
+        ],
+    };
+    examples.push({
+        id: "flow-material-animation",
+        blueprint: flowAnimation,
+        note: "The same declared animation starts through the existing Flow boundary. Requires host Flow enablement; graph cancellation cancels its awaited run.",
+    });
+    const textured = {
+        ...structuredClone(shared),
+        scene: { id: "textured-pbr", name: "Explicit texture resource" },
+        resources: [
+            {
+                id: "checker",
+                kind: "texture",
+                mediaType: "image/png",
+                label: "Host-supplied color checker",
+            },
+        ],
+        materials: shared.materials.map((material) => ({
+            ...structuredClone(material),
+            textures: { baseColor: { assetId: "checker", gammaSpace: true } },
+        })),
+    };
+    examples.push({
+        id: "textured-pbr",
+        note: "Requires an authorized checker texture binding. No URL is assumed. The original PNG fixture in examples/materials is suitable; host owns acquisition.",
+        blueprint: textured,
+    });
+    const geometric = {
+        schema: SCENE_BLUEPRINT_SCHEMA,
+        version: 1,
+        scene: { id: "path-composition", name: "Paths and grouped surfaces" },
+        entities: [
+            {
+                id: "composition",
+                kind: "group",
+                transform: { rotationRadians: { x: 0, y: 0.35, z: 0 } },
+            },
+            {
+                id: "tube",
+                parentId: "composition",
+                kind: "shape",
+                shape: "tube",
+                tubeRadius: 0.04,
+                closed: false,
+                points: [
+                    { x: -1, y: 0.2, z: 0 },
+                    { x: 0, y: 1, z: 0 },
+                    { x: 1, y: 0.2, z: 0 },
+                ],
+            },
+            {
+                id: "wall",
+                parentId: "composition",
+                kind: "shape",
+                shape: "wall",
+                wallHeight: 0.3,
+                closed: false,
+                points: [
+                    { x: -1, y: 0, z: 0.5 },
+                    { x: 1, y: 0, z: 0.5 },
+                ],
+            },
+            {
+                id: "panel",
+                parentId: "composition",
+                kind: "shape",
+                shape: "polygon",
+                closed: true,
+                points: [
+                    { x: -0.8, y: 0, z: -0.4 },
+                    { x: 0.8, y: 0, z: -0.4 },
+                    { x: 0.8, y: 0, z: 0.3 },
+                    { x: -0.8, y: 0, z: 0.3 },
+                ],
+            },
+            {
+                id: "guide",
+                parentId: "composition",
+                kind: "shape",
+                shape: "polyline",
+                closed: false,
+                points: [
+                    { x: -1, y: 1.2, z: 0 },
+                    { x: 0, y: 1.4, z: 0 },
+                    { x: 1, y: 1.2, z: 0 },
+                ],
+                strokeColor: { r: 0.8, g: 0.6, b: 0.2 },
+            },
+        ],
+        materials: [
+            {
+                id: "surface",
+                creation: { version: 1, family: "pbr" },
+                baseColor: { r: 0.1, g: 0.5, b: 0.3 },
+                roughness: 0.4,
+                doubleSided: true,
+            },
+        ],
+        materialBindings: [
+            { id: "tube-surface", materialId: "surface", entityId: "tube" },
+            { id: "wall-surface", materialId: "surface", entityId: "wall" },
+            {
+                id: "panel-surface",
+                materialId: "surface",
+                entityId: "panel",
+                target: { nodeId: "panel-fill", slot: 0 },
+            },
+        ],
+    };
+    examples.push({
+        id: "path-composition",
+        note: "Tube, wall, polygon fill and a separate polyline composed by one authored group. PBR selects panel-fill explicitly and leaves its line stroke untouched. No new extrusion/instancing engine is required.",
+        blueprint: applySceneRecipe(geometric, "studio-v1", {
+            bounds: {
+                minimum: { x: -1.5, y: 0, z: -0.5 },
+                maximum: { x: 1.5, y: 1.5, z: 1 },
+            },
+        }),
+    });
+    examples.push({
+        id: "texture-motion",
+        note: "The host supplies checker. Existing UV animation now follows the same paused render clock as parameter animation; it changes transient UV values, not texture pixels or document history.",
+        blueprint: {
+            ...structuredClone(textured),
+            scene: { id: "texture-motion", name: "UV motion" },
+            textureAnimations: [
+                {
+                    id: "scroll",
+                    materialId: "ceramic",
+                    slot: "baseColor",
+                    property: "uOffset",
+                    from: 0,
+                    to: 1,
+                    durationMs: 3000,
+                    autoStart: true,
+                    loop: true,
+                    easing: "linear",
+                },
+            ],
+        },
+    });
+    examples.push({
+        id: "presentation-atoms",
+        note: "Declared checker powers a small particle system. Annotation output contains projected coordinates for the host to present; it does not create a UI. The alternate camera and path are activated explicitly through public Renderer methods.",
+        blueprint: {
+            ...structuredClone(shared),
+            scene: { id: "presentation-atoms", name: "Presentation atoms" },
+            resources: structuredClone(textured.resources),
+            entities: [
+                ...structuredClone(shared.entities),
+                {
+                    id: "label",
+                    kind: "annotation",
+                    parentId: "sphere",
+                    transform: { position: { x: 0, y: 0.8, z: 0 } },
+                    properties: { text: "Shared surface", color: "#ffffff", priority: 1 },
+                },
+                {
+                    id: "alternate-camera",
+                    kind: "camera",
+                    parentId: "composition",
+                    transform: { position: { x: 0, y: 0.5, z: -5 } },
+                    properties: {
+                        projection: "perspective",
+                        fov: 0.8,
+                        minZ: 0.01,
+                        maxZ: 100,
+                    },
+                },
+                {
+                    id: "particles",
+                    kind: "particle",
+                    parentId: "composition",
+                    textureAssetRef: "checker",
+                    transform: { position: { x: 0, y: 0.2, z: 0 } },
+                    properties: {
+                        capacity: 128,
+                        emitRate: 16,
+                        minLifeTime: 0.4,
+                        maxLifeTime: 1,
+                        autoStart: true,
+                        gravity: { x: 0, y: -0.2, z: 0 },
+                    },
+                },
+            ],
+            cameraPaths: [
+                {
+                    id: "orbit-pass",
+                    name: "Two-point camera pass",
+                    durationMs: 3000,
+                    loop: false,
+                    interpolation: "linear",
+                    restoreCameraOnStop: true,
+                    keyframes: [
+                        {
+                            id: "start",
+                            timeMs: 0,
+                            position: { x: 3, y: 2.4, z: -5 },
+                            target: { x: 0, y: 0.5, z: 0 },
+                        },
+                        {
+                            id: "end",
+                            timeMs: 3000,
+                            position: { x: -3, y: 2.4, z: -5 },
+                            target: { x: 0, y: 0.5, z: 0 },
+                            easing: "easeInOut",
+                        },
+                    ],
+                },
+            ],
+        },
+    });
+    examples.push({
+        id: "procedural-ai",
+        note: "A bounded geometry graph and typed material graph. Both are plain JSON, compile without external resources, and contain no JavaScript or GLSL source.",
+        blueprint: {
+            schema: SCENE_BLUEPRINT_SCHEMA,
+            version: 1,
+            scene: { id: "procedural-ai", name: "Procedural AI" },
+            requires: [
+                {
+                    id: "skenora.entity.procedural",
+                    version: "1",
+                    required: true,
+                },
+                { id: "skenora.material.pbr", version: "1", required: true },
+                { id: "skenora.material.program", version: "1", required: true },
+            ],
+            entities: [
+                {
+                    id: "procedural-stage",
+                    kind: "procedural",
+                    program: {
+                        schema: "skenora.geometry.program",
+                        version: 1,
+                        output: "stage",
+                        nodes: [
+                            {
+                                id: "platform",
+                                type: "geometry.cylinder",
+                                height: 0.25,
+                                diameterTop: 3.2,
+                                diameterBottom: 3.5,
+                                segments: 48,
+                            },
+                            {
+                                id: "post",
+                                type: "geometry.box",
+                                size: { x: 0.18, y: 0.8, z: 0.18 },
+                            },
+                            {
+                                id: "posts",
+                                type: "modifier.array-radial",
+                                input: "post",
+                                count: 12,
+                                radius: 1.35,
+                            },
+                            {
+                                id: "raise-posts",
+                                type: "modifier.transform",
+                                input: "posts",
+                                translation: { x: 0, y: 0.45, z: 0 },
+                            },
+                            {
+                                id: "stage",
+                                type: "combine.merge",
+                                inputs: ["platform", "raise-posts"],
+                            },
+                        ],
+                    },
+                },
+            ],
+            materials: [
+                {
+                    id: "procedural-surface",
+                    creation: { version: 1, family: "pbr" },
+                    roughness: 0.38,
+                    program: {
+                        schema: "skenora.material.program",
+                        version: 1,
+                        parameters: {
+                            accent: {
+                                type: "color",
+                                value: { r: 0.05, g: 0.72, b: 1.4 },
+                            },
+                            glow: { type: "number", value: 0.12, minimum: 0, maximum: 2 },
+                        },
+                        nodes: [
+                            {
+                                id: "dark",
+                                type: "value.color",
+                                value: { r: 0.015, g: 0.025, b: 0.05 },
+                            },
+                            { id: "accent", type: "parameter.color", parameter: "accent" },
+                            {
+                                id: "height",
+                                type: "input.coordinate",
+                                space: "local",
+                                axis: "y",
+                            },
+                            { id: "low", type: "value.number", value: -0.15 },
+                            { id: "high", type: "value.number", value: 0.9 },
+                            {
+                                id: "ramp",
+                                type: "math.smoothstep",
+                                edge0: "low",
+                                edge1: "high",
+                                input: "height",
+                            },
+                            {
+                                id: "surface",
+                                type: "color.mix",
+                                a: "dark",
+                                b: "accent",
+                                factor: "ramp",
+                            },
+                            { id: "glow", type: "parameter.number", parameter: "glow" },
+                            {
+                                id: "emission",
+                                type: "color.scale",
+                                color: "accent",
+                                factor: "glow",
+                            },
+                        ],
+                        outputs: { baseColor: "surface", emissive: "emission" },
+                    },
+                },
+            ],
+            materialBindings: [
+                {
+                    id: "procedural-stage-surface",
+                    materialId: "procedural-surface",
+                    entityId: "procedural-stage",
+                },
+            ],
+        },
+    });
+    for (const recipe of ["neutral-v1", "studio-v1"]) {
+        const input = {
+            schema: SCENE_BLUEPRINT_SCHEMA,
+            version: 1,
+            scene: { id: recipe, name: recipe },
+            entities: structuredClone(shared.entities),
+            materials: structuredClone(shared.materials),
+            materialBindings: structuredClone(shared.materialBindings),
+        };
+        examples.push({
+            id: recipe,
+            note: "An expanded recipe using ordinary input, explicit supplied bounds and no environment assets. The host chooses execution quality; matching pixels across devices are not promised.",
+            blueprint: applySceneRecipe(input, recipe, {
+                bounds: {
+                    minimum: { x: -1.3, y: 0, z: -0.5 },
+                    maximum: { x: 1.3, y: 1, z: 0.5 },
+                },
+                aspectRatio: 1.5,
+            }),
+        });
+    }
+    return examples;
+}
+export function getSceneBlueprintRepairExamples() {
+    const base = getSceneBlueprintExamples()[0].blueprint;
+    return [
+        {
+            id: "unsupported-dissolve-depth-pass",
+            input: {
+                ...structuredClone(getSceneBlueprintExamples().find((item) => item.id === "animated-dissolve").blueprint),
+                postProcess: { enabled: true, depthOfField: true },
+            },
+            expected: {
+                stage: "compile",
+                code: "material-effect-pass-unsupported",
+                path: ["postProcess", "depthOfField"],
+            },
+            repair: "Disable depthOfField explicitly or remove dissolve. Version 1 never renders an inconsistent auxiliary depth mask as a fallback.",
+        },
+        {
+            id: "unknown-material-field",
+            input: {
+                ...structuredClone(base),
+                materials: base.materials.map((material) => ({
+                    ...structuredClone(material),
+                    shaderSource: "unsupported",
+                })),
+            },
+            expected: {
+                stage: "validate",
+                code: "unknown-field",
+                path: ["materials", 0, "shaderSource"],
+            },
+            repair: "Remove shaderSource. Use the declared PBR/effect fields; raw shader text is not executable input.",
+        },
+        {
+            id: "missing-texture-binding",
+            input: getSceneBlueprintExamples().find((item) => item.id === "textured-pbr").blueprint,
+            expected: {
+                stage: "validate",
+                code: "missing-resource-binding",
+                path: ["resources", 0, "id"],
+            },
+            repair: "Ask the host for the checker resource binding and compile with that explicit context.",
+        },
+        {
+            id: "missing-runtime-slot",
+            input: {
+                ...structuredClone(base),
+                materialBindings: base.materialBindings.map((binding) => ({
+                    ...binding,
+                    target: { nodeId: "missing-source-node", slot: 0 },
+                })),
+            },
+            expected: { stage: "runtime", code: "missing-material-slot" },
+            repair: "Use describeMaterialSlots(entityId) on the current loaded asset or the host's matching asset metadata.",
+        },
+    ];
+}
+//# sourceMappingURL=information.js.map