# @skenora/runtime

Babylon.js presentation and projection for validated Skenora SceneDocuments.

> This package snapshot is version `0.3.0`. Consume SDK, tooling and offline
> documentation from the same release. See
> [implementation status](../../docs/IMPLEMENTATION_STATUS.md) for dated
> verification and remaining limits.

```bash
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`     | action input, device adapters and third-person control |
| `@skenora/runtime/simulation`      | optional owned WebGPU compute/fullscreen renderer      |
| `@skenora/runtime/physics`         | explicit injected Havok Physics V2 services            |
| `@skenora/runtime/audio`           | explicitly bound Audio V2 engines and sources          |
| `@skenora/runtime/navigation`      | offline pre-baked Recast nearest/path queries          |
| `@skenora/runtime/water`           | official WaterMaterial with shared simulation phase    |
| `@skenora/runtime/geometry-motion` | fixed-topology line, tube and GreasedLine updates      |
| `@skenora/runtime/instances`       | bounded regular/thin instances with logical IDs        |
| `@skenora/runtime/animation`       | controlled two-group imported animation mixing         |

These optional plugins compose inside the existing Runtime. Their contracts,
preparation barriers, transform leases, transient entities, time domains and
resource lifetimes are described in `docs/FOUNDATION_CAPABILITIES.md`, also
available through MCP as `docs.foundation-capabilities`. Hosts inject native
Havok/Recast modules and explicit resources. Registering a plugin does not prove
preparation or user-gesture readiness; inspect the current Runtime state.

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.

```ts
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](https://github.com/zhangjiadi225/skenora); the current
working-tree guides are `docs/RUNTIME.md` and `docs/PROCEDURAL_AI.md`.