@skenora/sdk

Optional particle/weather presets and local generated textures are available through @skenora/sdk/particles. See docs/PARTICLE_PRESETS.md in the repository for resource-provider setup, custom textures, and ordinary scene composition.

High-level, local-first, framework-neutral scene SDK over Skenora's headless packages.

Skenora is currently pre-1.0. Product boundaries are implemented, but public APIs may still evolve. The SDK 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/sdk

Choose one product-level entry point:

| Product | Models | Editing | Behavior startup | | ----------------- | ----------: | ------- | ------------------ | | Lightbox | Exactly one | No | Never | | SkenoraEditor | One or many | Yes | Manual preview | | SkenoraRenderer | One or many | No | Automatic playback |

import { SkenoraEditor } from "@skenora/sdk/editor";

const scene = await SkenoraEditor.create({
  canvas: document.querySelector("canvas"),
  id: "demo",
  name: "Demo scene",
});
await scene.setEnvironment({ intensity: 1.2 });
await scene.addProcedural({
  id: "generated-stage",
  program: geometryProgram,
});

// Declarative SceneBlueprint/ScenePatch execution for host or AI workflows.
const summary = scene.scenePlan.inspectScene();
sendToAi({
  capabilities: summary.capabilities,
  availability: summary.capabilityAvailability,
  outline: summary.outline,
});
const result = await scene.scenePlan.applyPlan(blueprint, {
  expectedRevisionToken: summary.revisionToken,
  modelLoadPolicy: "strict",
  idempotencyKey: "request-001",
});

// Optional: manually preview authored behavior without leaving the editor.
await scene.startPreview();
scene.stopPreview();

The package exposes explicit product subpaths so applications do not place unrelated product implementations in the same static module graph. The root entry remains an editor-focused compatibility alias.

SkenoraScene remains available as a compatibility name for SkenoraEditor.

For a read-only model viewer, File objects can be opened directly without constructing a workspace document or resource provider:

import { createLightbox } from "@skenora/sdk/lightbox";

const viewer = await createLightbox({ canvas, model: modelFile });

Lightbox is a strict single-model viewer. Multi-model read-only playback uses SkenoraRenderer, which automatically runs enabled Flow graphs and configured camera-path or third-person behavior without exposing editor mutations.

Read-only applications can use the dedicated lightweight export:

import { SkenoraRenderer } from "@skenora/sdk/renderer";

The renderer accepts a native scene document produced by compileSceneBlueprint from @skenora/scene-plan; it never contacts an AI. Use that package's getScenePlanInformation() for descriptions, schemas and complete input examples. The host supplies resource bindings/providers.

Both Editor and Renderer subpaths re-export the pure compileProceduralGeometry() and compileMaterialProgram() helpers. Editor's addProcedural() stores the versioned geometry program through history; Renderer projects the validated program read-only. Lightbox remains a strict single-model product and does not accept procedural scene authoring.

renderer.getCapabilityAvailability() reports the instance's built-in visual capabilities and host material limits. renderer.describeMaterialSlots(entityId) returns logical source-node/slot data after loading. Material preparation is observable through material.preparation (unbound, preparing, ready, failed). Pass runtime.materialPolicy to set material enablement, instance and texture limits, and preparation waiting time. These settings cannot be changed by scene JSON. Ready is not a visual-quality assertion.

renderer.getBackendSnapshot() returns observed backend/device facts, renderer.getGpuProgramCacheSnapshot() returns bounded generated-program cache statistics, and await renderer.probe() requires a real render and pixel readback before reporting healthy. GPU-program preparation details are emitted through gpu-program.preparation.

The Lightbox session exposes the same three observation methods after its single-model document is ready; it still excludes editing and behavior execution.

For safe model-facing failures, toPublicRendererDiagnostic(error) from the renderer subpath omits arbitrary error messages, stacks, causes and resource locators. Keep original errors private to the host. Always dispose the renderer when its host view is removed; shared resource resolvers remain caller-owned.

The bounded material/discovery paths passed tests, development-package consumption and WebGL2 rendering verification on 2026-08-28. The checks do not establish cross-device compatibility or arbitrary-asset visual quality, and they predate the procedural geometry/material-program V1 additions.

Optional runtime.qualityPolicy caps render pixel ratio, explicit-light shadow resolution, pipeline samples and selected post-processing effects. Read renderer.getQualityState() or quality.changed for requested/effective settings and reductions. Authored JSON is not rewritten to fit the device.

Owned materials may declare typed effects (gradient, rim, dissolve) and local animations. Renderer exposes playMaterialAnimation, pauseMaterialAnimation, resumeMaterialAnimation, stopMaterialAnimation, resetMaterialAnimation, getMaterialAnimationState, and material.animation events. Play takes material ID, local track ID and an optional AbortSignal; it returns completed/cancelled. These are transient operations. Material and texture motion follow paused render time, not a separate RAF per target.

Dissolve version 1 supports opaque main-pass cutout only. It rejects shadows, SSAO, depth of field, glow, opacity/refraction and runtime transparency/highlight overrides. Remove the effect or explicitly disable the incompatible feature; there is no implicit fallback. Host material policy separately bounds active parameter animation writers and can disable individual effects.

renderer.projectAnnotations() returns detached annotation positions, visibility and payload in render-pixel coordinates. The host owns text/UI layout and CSS/DPR conversion; the library does not create a framework component or page.

Resource loading is local-only by default. Applications may add explicit workspace, HTTP, memory, catalog, or custom providers and use the SDK's resource search, description, attachment, and preflight methods.

scene.scenePlan is the host-facing declarative gateway. It exposes inspectScene, searchResources, validatePlan, applyPlan, and waitOperation; it keeps resource locators and Babylon/Editor instances out of the plan DTO surface. The built-in gateway feeds its Runtime availability snapshot into validation and returns both static capability IDs/versions and observed installed/enabled/backend facts plus a paginated model-safe scene outline from inspectScene().

Repository guides cover the complete composition, model import, configuration, resource, JSON bundle, lifecycle, and ownership APIs:

• SDK overview
• Lightbox
• Editor
• Renderer
• Runtime
• Flow
• SceneDocument
• Current working-tree procedural guide: docs/PROCEDURAL_AI.md