@skenora/runtime

Babylon.js presentation and projection for validated Skenora SceneDocuments.

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

pnpm add @skenora/runtime

Entry points are intentionally separated:

| Import | Purpose | | ------------------------------ | ----------------------------------------------------- | | @skenora/runtime | stable read-only SceneRenderer facade | | @skenora/runtime/projection | RuntimeSession, capabilities, plugins | | @skenora/runtime/editor | selection, gizmo, drawing, path, and inspection tools | | @skenora/runtime/interaction | third-person controllers | | @skenora/runtime/simulation | optional owned WebGPU compute/fullscreen renderer |

Runtime state is a disposable projection. Persisted changes belong in SceneDocument commands, not Babylon nodes. Hosts must dispose sessions and any resource scopes they create. Runtime lifecycle additions use RuntimePlugin; RuntimeExtension remains as a compatibility alias. Domain contributions such as resource providers, entity projectors, and Flow nodes keep their specialized registries.

glTF sidecar buffers and images normally use scoped Blob URLs. In an opaque-origin host where the browser creates blob:null/... URLs, Runtime converts only those dependencies to data: URLs so sandboxed directory imports remain loadable without network or XHR access. Data URL fallback increases the temporary encoded payload, so prefer GLB for large models used in opaque-origin hosts.

Owned materials opt in through creation: { version: 1, family: "pbr" } and explicit entity/slot bindings. Runtime stages textures and surface programs, then activates replacements and restores borrowed assignments on unbind. Legacy overrides keep their existing path. Material policy limits instances, textures, preparation waiting and active parameter animation writers.

The projection entry exports RUNTIME_MATERIAL_ANIMATIONS_CAPABILITY. Its play(materialId, animationId, { signal }), pause/resume/stop/reset and state operations address material-local typed tracks. Material and texture animations share active render time; material updates and document disposal cancel runs. The runtime publishes runtime.material.preparation, runtime.material.animation and runtime.quality.changed data events.

Runtime also exposes getBackendSnapshot(), probe(), and getGpuProgramCacheSnapshot(). Probe returns healthy only after a real scene render and pixel readback. Material programs use a versioned trusted GLSL emitter, a bounded Runtime-owned structural cache, and runtime.gpu-program.preparation reports. The default scene path still runs Babylon WebGL.

The separate ./simulation entry owns a raw WebGPU adapter/device, Canvas context, pipelines, two stable storage buffers, fixed-step clock, explicit probe readback, resize/reset, device-loss handling, and disposal. It never exposes the device and never coexists with Babylon inside one Example load.

import { WebGpuSimulationRenderer } from "@skenora/runtime/simulation";

const simulation = await WebGpuSimulationRenderer.create({ canvas, program });
console.log(simulation.snapshot());
const probe = await simulation.probe(); // explicit readback only
simulation.dispose();

This entry is a Renderer Lab capability, not SceneDocument persistence. Hosts without WebGPU receive WebGpuSimulationUnsupportedError and must use the manifest fallback rather than claiming a WebGL compute equivalent.

Bounded gradient, rim and dissolve effects keep shader source internal. Dissolve version 1 accepts opaque main-pass cutout only and rejects shadow/depth/glow auxiliary passes and runtime transparency/highlight overrides. Availability is not shader readiness, and readiness is not visual approval. Bounded lifecycle tests, development-package consumption and WebGL2 rendering passed on 2026-08-28. This is not a cross-device or arbitrary-asset guarantee.

Procedural geometry and material programs are separate V1 capabilities. procedural entities compile through @skenora/procedural into session-owned meshes. An owned PBR program is lowered from typed intermediate data to trusted internal GLSL with uniform parameters. Capability availability reports their current graph and geometry limits. These additions are not covered by the 2026-08-28 verification snapshot until a new verification run is explicitly authorized and recorded.

See the repository; the current working-tree guides are docs/RUNTIME.md and docs/PROCEDURAL_AI.md.