@opsydyn/effect-three 0.0.0-stage → 0.1.0

package/dist/kernel/renderKit.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What a renderer brings to a scene graph besides drawing: the parts of a scene written
+ * in its shading language. The kernel stays free of shader code (ADR-003): it describes a
+ * sky, a shader grid or contact shadows, and the renderer's kit makes them. The WebGL kit
+ * is `webglKit` from `@opsydyn/effect-three/webgl`, which `webglRendererFactory` carries;
+ * without a kit these parts are not drawn.
+ *
+ * @module
+ */
+import type { Object3D, Scene } from 'three';
+import type { ContactShadows, ShaderGridNode, Sky } from './description.ts';
+import type { SceneRenderer } from './renderer.ts';
+/** A sky as a kit draws it: the object the graph adds to its scene, never picked. */
+export type HostedSky = {
+    readonly object: Object3D;
+    readonly update: (sky: Sky) => void;
+    readonly dispose: () => void;
+};
+/** A shader grid as a kit draws it, placed by the kit from its description. */
+export type HostedShaderGrid = {
+    readonly object: Object3D;
+    readonly update: (previous: ShaderGridNode, next: ShaderGridNode) => void;
+    readonly dispose: () => void;
+};
+/** The contact shadow passes for one scene, drawn by the frame loop before each frame. */
+export type ContactShadowPasses = {
+    /** Draws the scene's contact shadows, if it has any, before the frame is drawn. */
+    readonly draw: () => void;
+    readonly dispose: () => void;
+};
+/** What contact shadows need from a scene graph: its scene and their description. */
+export type ShadowedScene = {
+    readonly scene: Scene;
+    readonly contactShadows: () => ContactShadows | null;
+};
+/** A renderer's shaded parts. */
+export type RenderKit = {
+    /**
+     * Whether the renderer can draw a label engine's labels. troika's are WebGL materials:
+     * the WebGPU renderer cannot (on real WebGPU they break the frame), so its kit says no
+     * and labels stay empty.
+     */
+    readonly drawsLabels: boolean;
+    readonly sky: () => HostedSky;
+    readonly shaderGrid: (node: ShaderGridNode) => HostedShaderGrid;
+    readonly contactShadows: (graph: ShadowedScene, renderer: SceneRenderer) => ContactShadowPasses;
+};
+//# sourceMappingURL=renderKit.d.ts.map

package/dist/kernel/renderKit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderKit.d.ts","sourceRoot":"","sources":["../../src/kernel/renderKit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,qFAAqF;AACrF,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,mBAAmB,GAAG;IAChC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,cAAc,GAAG,IAAI,CAAC;CACtD,CAAC;AAEF,iCAAiC;AACjC,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,SAAS,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,gBAAgB,CAAC;IAChE,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,KAAK,mBAAmB,CAAC;CACjG,CAAC"}

package/dist/kernel/renderer.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The renderer boundary (requirement 7). Synchronous and backend-neutral: a WebGL or
+ * WebGPU implementation lives outside the DOM-free core and is handed in as a factory.
+ *
+ * @module
+ */
+import { type Camera, type Scene, Texture } from 'three';
+import type { RenderSettings } from './description.ts';
+import type { RenderKit } from './renderKit.ts';
+/** Size of the drawing surface in CSS pixels, plus the device pixel ratio. */
+export type Viewport = {
+    readonly width: number;
+    readonly height: number;
+    readonly pixelRatio: number;
+};
+/** GPU memory counters, as reported by three.js `renderer.info.memory`. */
+export type RendererMemory = {
+    readonly geometries: number;
+    readonly textures: number;
+};
+/** A live renderer bound to one drawing surface. */
+/** A rectangle of the drawing surface in CSS pixels, from the top left. */
+export type RenderArea = {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+};
+/** An offscreen surface: render into it, then use its texture. Dispose exactly once. */
+export type RenderTarget = {
+    readonly texture: Texture;
+    readonly dispose: () => void;
+};
+export type SceneRenderer = {
+    /**
+     * Draws the scene through `camera`, into `area` when given (clearing only that area),
+     * otherwise across the whole surface.
+     */
+    readonly render: (scene: Scene, camera: Camera, area?: RenderArea, target?: RenderTarget) => void;
+    /** Creates an offscreen target of `width` × `height` pixels to render into. */
+    readonly createTarget: (width: number, height: number) => RenderTarget;
+    /**
+     * Creates the environment map of three.js's `RoomEnvironment`, prefiltered for this
+     * renderer (WebGL: `PMREMGenerator.fromScene(new RoomEnvironment(), 0.04)`).
+     */
+    readonly createEnvironment: () => RenderTarget;
+    /** Applies scene-wide render settings. Called before the first frame and on each change. */
+    readonly configure: (settings: RenderSettings) => void;
+    readonly setViewport: (viewport: Viewport) => void;
+    readonly memory: () => RendererMemory;
+    /** Releases the renderer and its drawing context. Called exactly once. */
+    readonly dispose: () => void;
+    /**
+     * Settles when the renderer can draw, for renderers that start asynchronously (three's
+     * `WebGPURenderer.init()`); the runtime waits for it before the first frame. Absent for
+     * renderers ready at once.
+     */
+    readonly ready?: (() => Promise<void>) | undefined;
+};
+/** Creates a renderer. `create` may throw when the backend is unavailable. */
+export type RendererFactory = {
+    readonly create: () => SceneRenderer;
+    /**
+     * The renderer's shaded parts, given to the scene graphs it draws (the sky, shader
+     * grids, contact shadows). A factory wrapping another keeps its kit (`...factory`).
+     */
+    readonly kit?: RenderKit | undefined;
+};
+/** A renderer that records calls instead of drawing. For headless tests. */
+export type RecordingRenderer = SceneRenderer & {
+    readonly renders: () => number;
+    /** Every `configure` call, in order. */
+    readonly configured: () => ReadonlyArray<RenderSettings>;
+    readonly viewport: () => Viewport | undefined;
+    readonly disposed: () => boolean;
+};
+/** A factory of recording renderers that remembers every renderer it created. */
+export type RecordingRendererFactory = RendererFactory & {
+    readonly created: () => ReadonlyArray<RecordingRenderer>;
+};
+/** Creates a factory of recording renderers. */
+export declare const recordingRendererFactory: () => RecordingRendererFactory;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/kernel/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/kernel/renderer.ts"],"names":[],"mappings":"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"}

package/dist/kernel/resources.d.ts

@@ -0,0 +1,112 @@
+/**
+ * GPU resource ownership (PLAN D5).
+ *
+ * - Owned: created for one mesh, disposed when that mesh releases it.
+ * - Shared: defined by id, created on first use, reference-counted by the meshes using
+ *   it, disposed when the last user releases it. Several scene graphs may share one store.
+ *
+ * Definitions are upserts. Changing a live shared material within its kind updates it in
+ * place. Changing a live shared geometry, or a shared material's kind, creates a
+ * replacement, notifies subscribers (each scene graph swaps it onto its meshes) and
+ * disposes the old one.
+ *
+ * The store is synchronous so the applier stays synchronous. The Effect runtime owns the
+ * store's lifetime and calls `dispose` from a scope finalizer.
+ *
+ * @module
+ */
+import { BufferGeometry, type Object3D, type Texture } from 'three';
+import type { Font } from 'three/addons/loaders/FontLoader.js';
+import type { GeometryRef, MaterialRef, ResourceDefinitions, SurfaceMaterial } from './description.ts';
+import { type HostMaterial } from './materials.ts';
+/** Lifetime counters for one resource type. `live` is `created - disposed`. */
+export type ResourceCounts = {
+    readonly created: number;
+    readonly disposed: number;
+    readonly live: number;
+};
+export type ResourceStats = {
+    readonly geometries: ResourceCounts;
+    readonly materials: ResourceCounts;
+    /** Acquisitions per live shared resource id. */
+    readonly sharedGeometryUsers: ReadonlyMap<string, number>;
+    readonly sharedMaterialUsers: ReadonlyMap<string, number>;
+};
+/** A loan that changed: an object for `borrowed` nodes, or a texture for materials. */
+export type Loan = {
+    readonly kind: 'object' | 'texture' | 'font' | 'geometry';
+    readonly id: string;
+};
+/** Raised when a live shared geometry is replaced because its definition changed. */
+export type GeometryReplaced = {
+    readonly previous: BufferGeometry;
+    readonly next: BufferGeometry;
+};
+/** Raised when a live shared material is replaced because its kind changed. */
+export type MaterialReplaced = {
+    readonly previous: HostMaterial;
+    readonly next: HostMaterial;
+};
+export type ResourceStore = {
+    readonly define: (definitions: ResourceDefinitions) => void;
+    readonly acquireGeometry: (ref: GeometryRef) => BufferGeometry;
+    /** Releases one acquisition. `geometry` is the value currently held for `ref`. */
+    readonly releaseGeometry: (ref: GeometryRef, geometry: BufferGeometry) => void;
+    readonly acquireMaterial: (ref: MaterialRef) => HostMaterial;
+    /** Releases one acquisition. `material` is the value currently held for `ref`. */
+    readonly releaseMaterial: (ref: MaterialRef, material: HostMaterial) => void;
+    /** Subscribes to shared geometry replacement. Returns an unsubscribe function. */
+    readonly onGeometryReplaced: (listener: (event: GeometryReplaced) => void) => () => void;
+    /**
+     * Subscribes to any change to a live shared resource (updated in place or replaced),
+     * so scenes using it know to draw again. Returns an unsubscribe function.
+     */
+    readonly onSharedChanged: (listener: () => void) => () => void;
+    /**
+     * Lends an application-owned three.js object under `id`, replacing any earlier loan.
+     * Scenes show it wherever a `borrowed` node names `id`. The store never disposes it.
+     * Returns a function that withdraws this loan (and nothing lent since).
+     */
+    readonly lend: (id: string, object: Object3D) => () => void;
+    /** The object lent under `id`, if any. */
+    readonly lent: (id: string) => Object3D | undefined;
+    /**
+     * Lends an application-owned texture under `id`, for materials' `map`. Materials using
+     * it update at once, owned and shared alike. The store never disposes it. Returns a
+     * function that withdraws this loan.
+     */
+    readonly lendTexture: (id: string, texture: Texture) => () => void;
+    /** The texture lent under `id`, if any. */
+    readonly texture: (id: string) => Texture | undefined;
+    /**
+     * Lends a typeface font under `id` for text geometries naming it. Text already shown
+     * is rebuilt. Returns a function that withdraws the loan.
+     */
+    readonly lendFont: (id: string, font: Font) => () => void;
+    /** The font lent under `id`, if any. */
+    readonly font: (id: string) => Font | undefined;
+    /**
+     * Lends an application-owned geometry under `id`, for meshes whose geometry is
+     * `lentGeometry(id)`; they show it at once, and nothing once it is withdrawn. The store
+     * never disposes it. Returns a function that withdraws this loan.
+     */
+    readonly lendGeometry: (id: string, geometry: BufferGeometry) => () => void;
+    /** Subscribes to loans and withdrawals of objects and textures. Returns an unsubscribe. */
+    readonly onLoanChanged: (listener: (loan: Loan) => void) => () => void;
+    /** Subscribes to shared material replacement. Returns an unsubscribe function. */
+    readonly onMaterialReplaced: (listener: (event: MaterialReplaced) => void) => () => void;
+    /**
+     * Applies new parameters to an owned material in place. Returns `false`, changing
+     * nothing, when `next` is a different kind: release it and acquire a new one instead.
+     */
+    readonly updateOwnedMaterial: (material: HostMaterial, next: SurfaceMaterial) => boolean;
+    /** The shared id of a live geometry, or `undefined` if it is owned or unknown. */
+    readonly sharedGeometryId: (geometry: BufferGeometry) => string | undefined;
+    /** The shared id of a live material, or `undefined` if it is owned or unknown. */
+    readonly sharedMaterialId: (material: HostMaterial) => string | undefined;
+    readonly stats: () => ResourceStats;
+    /** Disposes every live resource. Idempotent. */
+    readonly dispose: () => void;
+};
+export declare const createResourceStore: () => ResourceStore;
+//# sourceMappingURL=resources.d.ts.map

package/dist/kernel/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/kernel/resources.ts"],"names":[],"mappings":"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"}

package/dist/kernel/sceneGraph.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The hosted three.js scene graph: applies diff operations to real three.js objects.
+ *
+ * `reconcile` is atomic: an invalid description is rejected before anything changes.
+ * Objects keep their identity across updates; only a change of node kind replaces one.
+ *
+ * @module
+ */
+import { type BufferGeometry, Mesh, type Object3D, OrthographicCamera, PerspectiveCamera, Scene } from 'three';
+import { type BodyCollision, type BodyContactForce } from './bodies.ts';
+import type { RenderSettings, SceneDescription, ContactShadows, Environment, Gestures, Overlay, Xr, XrSpace, Vec3 } from './description.ts';
+import { type Op } from './diff.ts';
+import type { LabelEngine, LabelLayout } from './labels.ts';
+import type { HostMaterial } from './materials.ts';
+import { type Behaviour } from './motion.ts';
+import type { BodyPose, PhysicsEngine } from './physics.ts';
+import type { RenderKit } from './renderKit.ts';
+import { type ResourceStore } from './resources.ts';
+import { type DescriptionError } from './sceneIndex.ts';
+/** The mesh type the kernel hosts. */
+export type HostMesh = Mesh<BufferGeometry, HostMaterial>;
+/** A render texture as hosted: its id, size and the nested graph that draws it. */
+export type HostedTexture = {
+    readonly id: string;
+    readonly graph: SceneGraph;
+    readonly width: number;
+    readonly height: number;
+};
+/** A view as hosted: its key, its camera and its rectangle in CSS pixels from the top left. */
+export type HostedView = {
+    readonly key: string;
+    readonly camera: HostCamera;
+    readonly area: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+};
+export type ReconcileResult = {
+    readonly _tag: 'Applied';
+    readonly ops: ReadonlyArray<Op>;
+} | {
+    readonly _tag: 'Invalid';
+    readonly error: DescriptionError;
+};
+export type SceneGraphOptions = {
+    /** A store shared with other graphs. When omitted the graph owns a private store. */
+    readonly store?: ResourceStore;
+    /** Behaviours nodes may name, in addition to the built-in ones (`float`). */
+    readonly behaviours?: Readonly<Record<string, Behaviour>>;
+    /** Simulates meshes with a `body` when the scene has `physics`; without it they stay put. */
+    readonly physics?: PhysicsEngine | undefined;
+    /** Draws `label` nodes (distance-field text); without it they are empty. */
+    readonly labels?: LabelEngine | undefined;
+    /**
+     * The renderer's shaded parts (sky, shader grids, contact shadows); without it they are
+     * not drawn. `webglKit` from `@opsydyn/effect-three/webgl` for three's WebGL renderer.
+     */
+    readonly kit?: RenderKit | undefined;
+};
+export type SceneGraph = {
+    readonly scene: Scene;
+    /** The render kit the graph was made with, for the frame loop's contact shadows. */
+    readonly kit: RenderKit | undefined;
+    /** The active camera. Changing the description's camera kind replaces it. */
+    readonly camera: HostCamera;
+    /** The scene's views, fitted to the viewport; empty when `camera` fills the canvas. */
+    readonly views: () => ReadonlyArray<HostedView>;
+    /** Holds every camera's turning (`autoRotate`) still while a gesture is pressed. */
+    readonly holdCameras: (held: boolean) => void;
+    /**
+     * Where turning has taken the camera of `view` (or, without one, the scene's camera),
+     * when it has turned since its description: for an `AutoRotated` event.
+     */
+    readonly turned: (view: string | undefined) => Vec3 | undefined;
+    /** Render textures, each a nested graph to draw into its texture (by the frame loop). */
+    readonly renderTextures: () => ReadonlyArray<HostedTexture>;
+    /** Whether the scene claims the pointer's gestures from the page. */
+    readonly gestures: () => Gestures;
+    /** Points to show HTML at; the frame loop places them after drawing. */
+    readonly overlays: () => ReadonlyArray<Overlay>;
+    /** Image-based lighting and background; the frame loop applies it. */
+    readonly environment: () => Environment | null;
+    /** Soft ground shadows; the frame loop draws them. */
+    readonly contactShadows: () => ContactShadows | null;
+    /** Collisions between bodies since the last call, for the frame loop to report. */
+    readonly collisions: () => ReadonlyArray<BodyCollision>;
+    /** Contact forces over their bodies' thresholds since the last call. */
+    readonly contactForces: () => ReadonlyArray<BodyContactForce>;
+    /** How the scene is presented immersively, for the host; `null` if it never is. */
+    readonly xr: () => Xr | null;
+    /** Keys of the nodes whose bounds the frame loop reports. */
+    readonly measured: () => ReadonlyArray<string>;
+    /** A label's laid-out size, once its engine has laid it out. */
+    readonly labelLayout: (key: string) => LabelLayout | undefined;
+    /**
+     * Places the groups that follow tracked spaces where `locate` says each space is (in the
+     * scene), hiding those it cannot find. A presenting session calls it every frame, and
+     * once with nothing found when it ends.
+     */
+    readonly follow: (locate: (space: XrSpace) => BodyPose | undefined) => void;
+    readonly store: ResourceStore;
+    /** Diffs against the last applied description and applies the result. */
+    readonly reconcile: (next: SceneDescription) => ReconcileResult;
+    /** Advances behaviours to `elapsedSeconds` of scene time. Allocation-free. */
+    readonly tick: (elapsedSeconds: number) => void;
+    /** Scene time of the last `tick`. */
+    readonly elapsedSeconds: () => number;
+    /**
+     * The scene's current render settings. A new value (by reference) means they changed,
+     * so the frame loop can reconfigure the renderer without comparing fields.
+     */
+    readonly renderSettings: () => RenderSettings;
+    /**
+     * While not animating (reduced motion, a paused debugger), transitions land at once and
+     * any in flight finish, because frozen scene time would otherwise strand them mid-way.
+     */
+    readonly setAnimating: (animating: boolean) => void;
+    /**
+     * Whether the next frame would draw something new: after any change (reconcile, resize,
+     * animation toggle, a shared resource changed elsewhere) or while something animates.
+     */
+    readonly needsFrame: () => boolean;
+    /** Marks the current state as drawn. The frame loop calls it after each render. */
+    readonly drawn: () => void;
+    /** Calls `listener` whenever the graph changes in a way that needs a frame. */
+    readonly onInvalidated: (listener: () => void) => () => void;
+    /** The hosted object for a key. */
+    readonly object: (key: string) => Object3D | undefined;
+    /** The key of a hosted object. */
+    readonly keyOf: (object: Object3D) => string | undefined;
+    /** The key of instance `instanceId` of a hosted instances node, if it has one. */
+    readonly instanceKeyOf: (object: Object3D, instanceId: number) => string | undefined;
+    /**
+     * Hosted objects of interactive meshes and groups (picking descends into groups). The
+     * array is cached until the set changes and is mutable only because three's
+     * `Raycaster.intersectObjects` requires it: don't modify it.
+     */
+    readonly interactiveObjects: () => Array<Object3D>;
+    /** Fits the camera to a viewport of `width` by `height` CSS pixels. */
+    readonly resize: (width: number, height: number) => void;
+    /** The last `resize`, in CSS pixels. `1 × 1` until the first resize. */
+    readonly viewport: () => {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Removes every node and releases its resources. Disposes the store if the graph owns it. */
+    readonly dispose: () => void;
+};
+/** The three.js camera kinds the kernel hosts. */
+export type HostCamera = PerspectiveCamera | OrthographicCamera;
+/** Creates an empty scene graph. */
+export declare const createSceneGraph: (options?: SceneGraphOptions) => SceneGraph;
+//# sourceMappingURL=sceneGraph.d.ts.map

package/dist/kernel/sceneGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sceneGraph.d.ts","sourceRoot":"","sources":["../../src/kernel/sceneGraph.ts"],"names":[],"mappings":"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"}

package/dist/kernel/sceneIndex.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Flattened, validated view of a scene description, used by the diff.
+ *
+ * @module
+ */
+import type { SceneDescription, SceneNode } from './description.ts';
+/** Parent of a node: another node's key, or `null` for the scene root. */
+export type ParentKey = string | null;
+/** A node with its position in the tree. */
+export type IndexedNode = {
+    readonly node: SceneNode;
+    readonly parent: ParentKey;
+};
+/** A description is rejected as a whole; nothing is applied (no partial updates). */
+export type DescriptionError = {
+    readonly _tag: 'DuplicateKey';
+    readonly key: string;
+} | {
+    readonly _tag: 'DuplicateResourceId';
+    readonly resource: 'geometry' | 'material';
+    readonly id: string;
+} | {
+    readonly _tag: 'UnknownSharedGeometry';
+    readonly nodeKey: string;
+    readonly id: string;
+} | {
+    readonly _tag: 'UnknownSharedMaterial';
+    readonly nodeKey: string;
+    readonly id: string;
+} | {
+    readonly _tag: 'DuplicateInstanceKey';
+    readonly nodeKey: string;
+    readonly key: string;
+} | {
+    readonly _tag: 'UnknownBehaviour';
+    readonly nodeKey: string;
+    readonly name: string;
+} | {
+    readonly _tag: 'DuplicateViewKey';
+    readonly key: string;
+} | {
+    readonly _tag: 'DuplicateRenderTextureId';
+    readonly id: string;
+} | {
+    readonly _tag: 'DuplicateOverlayKey';
+    readonly key: string;
+} | {
+    readonly _tag: 'UnknownOverlayNode';
+    readonly key: string;
+    readonly node: string;
+} | {
+    readonly _tag: 'UnknownOverlayView';
+    readonly key: string;
+    readonly view: string;
+} | {
+    readonly _tag: 'UnknownMeasuredNode';
+    readonly key: string;
+}
+/** Two joints share a key. */
+ | {
+    readonly _tag: 'DuplicateJointKey';
+    readonly key: string;
+}
+/** A joint names a node that is not in the scene. */
+ | {
+    readonly _tag: 'UnknownJointBody';
+    readonly joint: string;
+    readonly body: string;
+};
+/** A validated scene. Keys are unique across the whole scene. */
+export type SceneIndex = {
+    readonly description: SceneDescription | null;
+    readonly nodes: ReadonlyMap<string, IndexedNode>;
+    /** Child keys per parent, in description order. Includes the root (`null`). */
+    readonly children: ReadonlyMap<ParentKey, ReadonlyArray<string>>;
+    /** Keys in depth-first pre-order: parents always precede their children. */
+    readonly preOrder: ReadonlyArray<string>;
+};
+/** The index of the empty scene that every graph starts from. */
+export declare const emptyIndex: SceneIndex;
+export type IndexResult = {
+    readonly _tag: 'Indexed';
+    readonly index: SceneIndex;
+} | {
+    readonly _tag: 'Invalid';
+    readonly error: DescriptionError;
+};
+/** Validates and flattens a description. */
+export declare const indexScene: (description: SceneDescription, behaviours?: ReadonlySet<string>) => IndexResult;
+//# sourceMappingURL=sceneIndex.d.ts.map

package/dist/kernel/sceneIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sceneIndex.d.ts","sourceRoot":"","sources":["../../src/kernel/sceneIndex.ts"],"names":[],"mappings":"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"}

package/dist/kernel/stage.d.ts

@@ -0,0 +1,87 @@
+import type { ContactShadows, Environment, SceneNode, Vec3 } from './description.ts';
+import type { Box } from './orbit.ts';
+/** Where the main and fill lights sit, in multiples of the content's radius. */
+export type StageLighting = {
+    readonly main: Vec3;
+    readonly fill: Vec3;
+};
+/** Drei's lighting presets. */
+export declare const stagePresets: {
+    rembrandt: {
+        main: [number, number, number];
+        fill: [number, number, number];
+    };
+    portrait: {
+        main: [number, number, number];
+        fill: [number, number, number];
+    };
+    upfront: {
+        main: [number, number, number];
+        fill: [number, number, number];
+    };
+    soft: {
+        main: [number, number, number];
+        fill: [number, number, number];
+    };
+};
+export type StagePreset = keyof typeof stagePresets;
+/** The scene parts a stage contributes: spread them into `scene`. */
+export type Stage = {
+    /** The stage's lights; add them to the scene's children. */
+    readonly lights: ReadonlyArray<SceneNode>;
+    readonly contactShadows: ContactShadows | null;
+    readonly environment: Environment | null;
+};
+/**
+ * Lights, ground shadows and an environment for content centred on the origin with
+ * bounding radius `radius` and height `height`. Defaults as Drei's `Stage`: the
+ * Rembrandt preset, intensity 0.5, contact shadows (`radius × 4` across, reaching
+ * `radius` up, blur 2) and a spot light that casts shadow maps when the scene enables
+ * them (bias −0.0001, 1024 texels). Drei's default environment is the "city" HDR from a
+ * CDN; here it is three.js's `RoomEnvironment`, built in code. `keyPrefix` names the
+ * lights (`stage-ambient`, `stage-main`, `stage-fill` by default).
+ */
+export declare const stage: (options: {
+    readonly radius: number;
+    readonly height: number;
+    readonly preset?: StagePreset | StageLighting;
+    readonly intensity?: number;
+    readonly shadows?: 'contact' | 'none';
+    readonly environment?: Environment | null;
+    readonly keyPrefix?: string;
+}) => Stage;
+/**
+ * Which way to align content instead of centring it, per axis, as Drei's `Center` props:
+ * `top` stands it on y = 0 (on top of the origin), `bottom` hangs it below; `left` puts
+ * it left of x = 0, `right` right of it; `front` before z = 0, `back` behind. `disableY`
+ * leaves that axis as it is.
+ */
+export type CenterAlign = {
+    readonly top?: boolean;
+    readonly bottom?: boolean;
+    readonly left?: boolean;
+    readonly right?: boolean;
+    readonly front?: boolean;
+    readonly back?: boolean;
+    readonly disableX?: boolean;
+    readonly disableY?: boolean;
+    readonly disableZ?: boolean;
+};
+/**
+ * Where to put content whose box (as measured where it is drawn now, at no offset) is
+ * `box` so that it is centred on the origin, or aligned by `align`: Drei's `Center`
+ * (`src/core/Center.tsx` at `bf6f4ad`), which sets its inner group to this position.
+ */
+export declare const centerOffset: (box: Box, align?: CenterAlign) => Vec3;
+/**
+ * The sizes Drei's `Stage` takes from `Center`'s report: the box's bounding sphere radius
+ * (half its diagonal) and its width, height and depth. Pass to `stage` for lights and
+ * shadows scaled to the content.
+ */
+export declare const stageBounds: (box: Box) => {
+    readonly radius: number;
+    readonly width: number;
+    readonly height: number;
+    readonly depth: number;
+};
+//# sourceMappingURL=stage.d.ts.map

package/dist/kernel/stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../src/kernel/stage.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAEzE,+BAA+B;AAC/B,eAAO,MAAM,YAAY;;QACV,IAAI;QAAa,IAAI;;;QACtB,IAAI;QAAgB,IAAI;;;QACzB,IAAI;QAAa,IAAI;;;QACxB,IAAI;QAAc,IAAI;;CACS,CAAC;AAE1C,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AAEpD,qEAAqE;AACrE,MAAM,MAAM,KAAK,GAAG;IAClB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,QAAQ,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;CAC1C,CAAC;AAIF;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,YAAa;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,KAAG,KA4BH,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAmBF;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAS,GAAG,UAAS,WAAW,KAAQ,IAIhE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,QACjB,GAAG,KACP;IACD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAMxB,CAAC"}

package/dist/kernel/textLayout.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lays out text from a typeface font as shapes, with letter spacing, line height and
+ * alignment.
+ *
+ * Behavioural reference: three.js `FontLoader.js` `createPaths` at 0.186.1 (each glyph
+ * advanced by its `ha`, a new line down by the font's bounding box height plus its
+ * underline thickness, a missing glyph drawn as `?`). Drei's `Text3D` (`bf6f4ad`) takes
+ * `letterSpacing` and `lineHeight` and hands them to `TextGeometry`, which ignores them;
+ * here they are applied, in the units troika's `Text` uses: letter spacing in ems, line
+ * height as a multiple of the font's own. At the defaults the shapes are three's.
+ *
+ * @module
+ */
+import { type Shape } from 'three';
+import type { Font } from 'three/addons/loaders/FontLoader.js';
+import type { TextAlign } from './description.ts';
+/** How to lay the text out. */
+export type TextLayout = {
+    readonly size: number;
+    /** Extra space after each glyph, in ems (multiples of `size`). */
+    readonly letterSpacing: number;
+    /** Line spacing as a multiple of the font's. */
+    readonly lineHeight: number;
+    /** Where each line sits within the widest. */
+    readonly align: TextAlign;
+};
+/** The shapes of `text` laid out by `layout`, the first line's baseline at y = 0. */
+export declare const layoutText: (font: Font, text: string, layout: TextLayout) => ReadonlyArray<Shape>;
+//# sourceMappingURL=textLayout.d.ts.map

package/dist/kernel/textLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textLayout.d.ts","sourceRoot":"","sources":["../../src/kernel/textLayout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAsB,KAAK,KAAK,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAE/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,+BAA+B;AAC/B,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B,CAAC;AAoDF,qFAAqF;AACrF,eAAO,MAAM,UAAU,SAAU,IAAI,QAAQ,MAAM,UAAU,UAAU,KAAG,aAAa,CAAC,KAAK,CAqB5F,CAAC"}