@skenora/scene-plan

Pure SceneBlueprint and ScenePatch contracts, validation, normalization, and compilation for Skenora.

This package is not currently published to npm; install examples describe the intended release. The procedural V1 sections describe current repository source and are not covered by the 2026-08-28 package/browser evidence.

This package is intentionally separate from @skenora/editor and @skenora/sdk:

• it contains serializable Blueprint/Patch data, parsing, normalization, validation, diagnostics, and compilation;
• it does not create an Editor, Runtime, Babylon scene, DOM element, or AI runtime;
• it does not own resource acquisition, workspace writes, approval, or policy;
• it compiles to the existing SceneDocumentData source of truth.

The package boundary and execution split are documented in:

• Scene Plan;
• Scene Plan execution;
• Scene Plan modules;
• AI scene skill contract.

The SDK scene-plan executor may expose Gateway operations as a composition entry point, but the pure package must remain usable without a Canvas, DOM, Editor, Runtime, Workspace, or resource locator.

Public information and examples

import {
  getScenePlanInformation,
  getSceneBlueprintExamples,
  getSceneBlueprintJsonSchema,
  applySceneRecipe,
  compileSceneBlueprint,
  toPublicScenePlanDiagnostics,
} from "@skenora/scene-plan";

// Data only: no Canvas, engine, model provider, resource acquisition or Editor.
const information = getScenePlanInformation();
const schema = getSceneBlueprintJsonSchema();
const example = getSceneBlueprintExamples()[0].blueprint;
const compiled = compileSceneBlueprint(example, {
  // Obtained from an initialized Runtime/Renderer or the host deployment.
  capabilityAvailability: observedHostCapabilities,
});
if (!compiled.ok) {
  console.log(toPublicScenePlanDiagnostics(compiled.diagnostics));
}

checkSceneInput(input) is the single pure preflight for native SceneDocument, Blueprint, and Patch input. It parses JSON once, returns stable shared diagnostics, capability requirements and counts, and marks whether a Blueprint was fully compiled. Resource-bearing Blueprints are not compiled until the host supplies resource bindings.

The information bundle includes versioned capability descriptions, input and normalized-Blueprint schemas, native defaults, examples, safe repair guidance and the neutral-v1 / studio-v1 recipe descriptions. The getters return detached serializable source data. A new development package build will emit them into dist; the checked-in pre-procedural dist is stale and is not evidence for these additions. A host can select descriptions by domains or capabilityIds and serialize only the relevant information for its own AI.

Do not turn information.capabilities into an availability snapshot. It describes accepted syntax; it does not prove that a backend is installed, enabled, or compatible with the active device.

The information bundle includes dedicated skenora.entity.procedural@1 and skenora.material.program@1 descriptions, their JSON Schemas, limits, diagnostics, and the complete procedural-ai Blueprint example. A procedural Blueprint needs no resource binding when it uses no assets, but declared required capabilities still need a matching host capability snapshot.

listSkenoraExamples(), searchSkenoraExamples(), and getSkenoraExample() expose the immutable generated public gallery. Blueprint and Recipe entries contain ordinary Blueprint data; Renderer Lab entries carry a bounded SimulationProgram and are intentionally excluded from persistent scene compilation. The information bundle describes the simulation schema but does not claim device availability.

SceneBlueprintInput expresses omitted arrays/settings; normalization fills Blueprint defaults, then compilation fills native settings and owned materials. Schema validation does not resolve references or prove rendering compatibility. When known, pass the current host's capabilityAvailability snapshot in the compiler context; unknown/disabled capabilities cannot satisfy required usage.

applySceneRecipe(input, "studio-v1", options) expands ordinary fields without fetching assets. Explicit fields win, including a supplied empty light array. Use options.bounds with world-space meters for pure camera framing; otherwise let the renderer frame loaded geometry. Environment resources must be declared and bound explicitly by the host.

New PBR input opts in with creation: { version: 1, family: "pbr" } and uses explicit materialBindings. Legacy material overrides remain supported. Group entities without sourceNode provide transform-only composition.

Owned PBR also accepts versioned effects and local animations. The metadata contains their exact property allowlists, interpolation/loop rules and render-pass restrictions. Public examples include gradient-rim, animated-dissolve, flow-material-animation, texture-motion, presentation-atoms, and a grouped tube/wall/polygon/polyline composition, plus procedural-ai. The host chooses which information to give its AI; no provider, prompt runner or model connection is included.

Contract tests, actual development-package imports, public declarations and 12 public WebGL2 rendering examples passed verification on 2026-08-28. This does not cover the later procedural-program additions, claim other GPU/browser support, or mean that an updated package was published.