@adatechnology/game-interactables-three 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# @adatechnology/game-interactables-three
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+three.js adapter for [`@adatechnology/game-interactables`](../game-interactables) and for content packs that draw through a
+`HouseholdApi` (the `PropsApi` of [`@adatechnology/game-props3d`](../game-props3d) plus `part(id, pivot, ry, draw)`).
+
+It turns the primitives of a content pack into a few merged meshes, moves the parts the world animates, and draws the effects, screens,
+mirrors and cords of the world. `three` is a peer dependency imported **as a type only**: the host passes its own `THREE` (and `Reflector`)
+in, so there is never a second copy of three in the bundle. No assets, no other runtime dependencies.
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-interactables-three three
+```
+
+Browser without a bundler (the global is `GameInteractablesThree`):
+
+```html
+<script src="https://unpkg.com/@adatechnology/game-interactables-three/dist/index.global.js"></script>
+<script>
+  const adapter = GameInteractablesThree.createThreeAdapter(THREE, { document })
+</script>
+```
+
+## Usage
+
+```ts
+import * as THREE from 'three'
+import { Reflector } from 'three/examples/jsm/objects/Reflector.js'
+import { createThreeAdapter } from '@adatechnology/game-interactables-three'
+
+const gfx = createThreeAdapter(THREE, { document, Reflector, envMap })
+
+// 1. build an object: every primitive is merged into one geometry per material, every part into its own group
+const { api, finish } = gfx.createMeshApi({ quality: 'game' })
+pack.build('wardrobe', {}, api) // your content pack draws through api.box / cylinder / leaf / plane / light / part
+const { group, parts } = finish() // parts: { door: Group, drawer_1: Group, ... }
+scene.add(group)
+
+// 2. each frame
+world.update(dt)
+gfx.syncObject(world, 'wardrobe-1', parts, { time: clock.elapsedTime })
+effects.update(dt, world.emitters())
+mirrors.update(camera, world.mirrors([x, y, z], 6))
+```
+
+Every function also exists unbound and takes `THREE` first: `createMeshApi(THREE, options)`, `applyPose(THREE, group, motion, t)`, ...
+
+### Mesh api
+
+`createMeshApi(THREE, { materials, quality, shadows })` returns `{ api, finish, materials }`.
+
+- Implements `box`, `cylinder` (shapes `cyl`, `cyl6`, `cone`, `sphere`), `leaf`, `plane` (with atlas `uv`), `light` and `part`.
+- Static primitives are baked (vertex colors) into **one `BufferGeometry` per material**: the draw calls of the static body are the number
+  of materials in use (`plain`, `metal`, `wood`, `glass`, `fabric`, `plant`, `water`, `emissive`, `atlas_picture`, `atlas_floor`).
+- `part(id, pivot, ry, draw)` routes everything drawn inside `draw` into a group of its own, merged per material as well. The group origin is
+  the pivot and it is turned by `ry`, so a hinge or slide axis is expressed in the part frame. Names are `part:<id>` and `userData.part = id`
+  on the group **and** its meshes, so `raycaster.intersectObject(group, true)[0].object.userData.part` gives the part that was hit.
+- `M.x`, `M.z`, `M.ry` of each primitive's item are applied; pivots are object-local, coordinates drawn inside a part are relative to its pivot.
+- `materials` maps keys to your materials; missing keys get defaults with `vertexColors` (`MeshStandardMaterial` for `quality: 'high'`,
+  `MeshLambertMaterial` for `'game'`, which also uses fewer segments). Atlas materials are yours to provide (a `CanvasTexture` of the atlas).
+- `api.light` creates a `PointLight` inside the right group; `finish()` also returns them as `lights`.
+- **Draw calls in `game` quality.** `plain`, `metal`, `wood` and `fabric` are one shared Lambert material, so they merge into one mesh per
+  target. `finish(spec)` (pass the spec the pack returned; option `mergeParts`, default on in `game` quality) also merges the parts of one
+  `PartSpec.group` that share a motion (blind slats: a per-vertex pivot in the vertex shader, one set of uniforms, shadows follow) and the
+  `cloth` soft volumes (clothes on a line: one mesh, a per-vertex cloth index and anchor, each cloth keeps its own swing). `parts[id]` then
+  points at the merged group (`userData.merged`) and `syncObject` drives it. Parts with a mirror, a turned part (`ry`) or a lone part stay as they are.
+  Measured on the household pack: blinds 38 meshes to 3, clothesline 31 to 2.
+- **Material hook.** `materialFor(key, partId)` (option of `createMeshApi`, or `finish(spec, { materialFor })` which wins) returns the material
+  of each mesh (`partId` is `null` for the static body), e.g. one carrying a per-room light mask. Merged groups clone that material for their
+  batch shader but **keep** its `onBeforeCompile`, `customProgramCacheKey`, `defines` and `userData` (the batch patch runs after yours), so a
+  merged blind or clothesline is masked and lit like everything else; meshes with different materials are never mixed into one merged mesh.
+- `createScreen` asks for a `willReadFrequently` 2D context (the canvas is re-uploaded every redraw; this avoids the browser's readback warning).
+
+### Poses and sync
+
+`applyPose(THREE, group, motion, t)` poses a part from its `Motion` (hinge / rocker / knob rotate, slide translates, scale scales along
+the axis). The rest pose is remembered in `group.userData.rest`, so calling it every frame never drifts. `syncObject(THREE, world, objectId,
+parts, { time })` applies every part's t from the world and the swing of every soft volume (the group under `soft.part ?? soft.id`).
+
+### Cloth sway that casts the right shadow
+
+```ts
+const handle = gfx.attachSway(clothMesh, { amplitude: 0.04 })
+```
+
+`swayMaterial(THREE, base, { amplitude, anchorY })` clones the material and patches the vertex shader (uniforms `time`, `ax`, `az`,
+`anchorY`) so vertices hang from the anchor line and swing. The **same patch** goes into `customDepthMaterial` (directional and spot
+shadows) and `customDistanceMaterial` (point-light shadows), so shadows follow the animation instead of flickering. `attachSway` sets all
+three on a mesh; `syncObject` drives its uniforms from `world.sway(...)`.
+
+### Effects
+
+```ts
+// `scene` (where the particle objects go) and `camera` (its fov sizes the point sprites) are required options.
+// `camera` may also be a function returning the current camera, or `null` for a 90 degree lens.
+const effects = gfx.createEffects({ scene, camera, maxParticles: 800, document })
+effects.update(dt, world.emitters()) // reads the camera it was created with; `effects.setCamera(other)` swaps it
+effects.setViewHeight(renderer.domElement.height) // on resize
+```
+
+Smoke and steam (thick, soft, rising and growing), fire (additive, yellow to red), sparks and water. One `Points` per kind, fixed buffers,
+swap-remove, no allocations per frame; the total alive never exceeds `maxParticles` (split by kind). The sprite is painted on a canvas from
+`document`, or generated as a data texture without one. Seeded, so the same seed gives the same plumes. Sprite sizes use the camera's
+vertical `fov` (and `zoom`), read on every `update` (or `setCamera(camera)`); without a camera a 90 degree lens is assumed.
+
+- **Water** (intensity 0.25 and up) is a tapered, translucent stream mesh with scrolling streaks along the gravity arc from the outlet down
+  to the floor (`floorY` option) or to `emitter.reach` meters below it (a tap ends in the basin), plus spray droplets around it and a splash
+  with a little mist where it lands. A thin emitter (tap) narrows as it falls, a wide one (shower) opens up. One draw call per stream
+  (`maxStreams`, default 6). Low intensities drip.
+- **Gas `flame`** is a ring of small blue cones per burner (all rings share one mesh, one draw call, `maxFlames`) plus a soft glow.
+- The meshes live in `effects.meshes` (`group`, `streams`, `flames`).
+
+### Screens
+
+```ts
+const tv = gfx.createScreen({ w: 128, h: 72 })
+tvMesh.material = tv.material
+tv.setOn(true); tv.setChannel(2); tv.update(dt)
+```
+
+Canvas texture: black and not emissive when off; when on, channel 0 is color bars, 1 static noise, 2 an animated landscape (higher
+numbers repeat them with shifted hues).
+
+### Mirrors
+
+```ts
+const mirrors = gfx.createMirrors({ max: 1, resolution: 512 })
+mirrors.register('wardrobe-1:mirror', mirrorMesh) // world id objectId:mirrorId
+mirrors.update(camera, world.mirrors(eye, 6)) // returns the ids that got a real reflector
+```
+
+Registered meshes show an env-map material. The nearest `max` facing the camera get a pooled `Reflector`, placed 1 mm in front of the plane
+with the mesh's rotation and size. Without a `Reflector` everything stays on the env map.
+
+**`renderer.info` and the Reflector.** three's `Reflector` renders the scene again inside the main `render()`; that nested render resets
+`renderer.info` (when `info.autoReset` is on), so `info.render.calls` would only count the reflector pass. `createMirrors({ keepInfo })`
+(default `true`) wraps the reflector so the counters of the main pass are added back and `info.render.calls` / `triangles` cover the whole
+frame. A host that sets `renderer.info.autoReset = false` and resets it itself is left alone.
+
+### Cords
+
+`createCord(THREE, points, radius, material)` builds a tube; `catenary(a, b, sag, n)` returns `n` points of a hanging cord whose lowest
+point is `sag` meters below the chord.
+
+## Notes
+
+- `poseOf` converts the pose math of the interactables package (same defaults) to a quaternion, so the rendered part always matches the engine.
+- Everything is deterministic: effects and screen noise use seeded generators.
+
+## Destruction
+
+`finish(spec)` copies the spec's destruction tags to Three objects so a destruction host can find what each mesh is made of: `userData.destructionMaterial` (SDK material id) on the static meshes (object default) and on each part group and its meshes, and, on part groups and their meshes, `userData.destructionPart` (the part id, as `@adatechnology/game-destruction-three` expects), `userData.destructionPiece` and `userData.destructionJoint`. Parts merged into a shared group (blind slats) carry the tags of the first part. The damage itself is done by `@adatechnology/game-destruction`; this package only tags. Without a spec nothing is tagged.
+
+## Português
+
+Adaptador three.js para o `@adatechnology/game-interactables`. Recebe as primitivas dos packs de conteúdo (`box`, `cylinder`, `leaf`,
+`plane`, `light` e `part`) e as junta em **uma geometria por material**, com cada parte móvel (porta, gaveta, tampa) em um grupo próprio com
+a origem no pivô. O `THREE` é sempre passado pelo jogo (o pacote só importa tipos).
+
+```ts
+const gfx = createThreeAdapter(THREE, { document, Reflector, envMap })
+const { api, finish } = gfx.createMeshApi({ quality: 'game' })
+pack.build('guarda_roupa', {}, api)
+const { group, parts } = finish()
+scene.add(group)
+// a cada quadro
+gfx.syncObject(world, 'guarda-roupa-1', parts, { time: clock.elapsedTime })
+```
+
+Também traz `swayMaterial` / `attachSway` (balanço de roupa no vertex shader, com material de profundidade e de distância iguais, para a
+sombra acompanhar), efeitos em pool (fumaça, fogo, vapor, água, faíscas), telas com canais animados, espelhos com `Reflector` só para o mais
+próximo, e cabos (`createCord`, `catenary`).

package/dist/index.d.ts

@@ -0,0 +1,395 @@
+import { ActiveEmitter, ObjectSpec, Motion, World } from '@adatechnology/game-interactables';
+import * as ThreeNS from 'three';
+import { PropsApi } from '@adatechnology/game-props3d';
+
+/** The host's `THREE` namespace (or any object with the same classes). Always passed in, never imported at runtime. */
+type ThreeLib = typeof ThreeNS;
+
+type Vec3 = [number, number, number];
+/** Material keys the mesh api understands (same as `PropsApi` materials). */
+type MaterialKey = 'plain' | 'metal' | 'wood' | 'glass' | 'fabric' | 'plant' | 'water' | 'emissive' | 'atlas_picture' | 'atlas_floor';
+declare const MATERIAL_KEYS: readonly MaterialKey[];
+type Quality = 'high' | 'game';
+/**
+ * What content packs draw through: the props primitives plus `part`.
+ * `part(id, pivot, ry, draw)` runs `draw()` and routes every primitive drawn inside it into the movable part `id`.
+ * `pivot` is object-local; the primitives drawn inside `draw` are in the part frame (relative to the pivot, turned by `ry`): the part's
+ * group origin sits at `pivot`, turned by `ry` around +y.
+ */
+interface HouseholdApi extends PropsApi {
+    part(id: string, pivot: Vec3, ry: number, draw: () => void): void;
+}
+/** Anything that can create a canvas (the global `document`, or a fake in tests). */
+interface CanvasFactory {
+    createElement(tag: 'canvas'): any;
+}
+
+interface EffectsOptions {
+    /** Where the particle objects are added (the `Points` of every kind, the water streams and the flame ring). Required. */
+    scene: ThreeNS.Object3D;
+    /**
+     * Camera whose vertical field of view sizes the sprites, read again every `update` so zoom and fov changes follow. Required: pass the
+     * camera the scene is rendered with (a `PerspectiveCamera` fits), or a function returning the current one (`null` = 90 degree lens).
+     */
+    camera: PerspectiveLike | (() => PerspectiveLike | null) | null;
+    /** Total particles alive at once, shared by all kinds (split by weight). Default 800. */
+    maxParticles?: number;
+    /** Used to paint the soft sprite on a canvas. Without it (or without a 2D context) a data texture is generated. */
+    document?: CanvasFactory;
+    /** Seed of the random spread. Default 1. */
+    seed?: number;
+    /** Wind vector [x, z] in m/s that bends smoke and steam. Default [0, 0]. */
+    wind?: [number, number];
+    /** Viewport height in pixels, used to size the point sprites. Update with `setViewHeight` on resize. Default 720. */
+    viewHeight?: number;
+    /** Height (m) water streams fall to when the emitter has no `reach`. Default 0. */
+    floorY?: number;
+    /** Most water streams drawn at once (one draw call each). Default 6. */
+    maxStreams?: number;
+    /** Most gas flame rings drawn at once (all rings share one draw call). Default 16. */
+    maxFlames?: number;
+}
+/** What the effects read from a camera. */
+interface PerspectiveLike {
+    /** Vertical field of view in degrees. */
+    fov: number;
+    zoom?: number;
+}
+interface EffectsStats {
+    alive: number;
+    capacity: number;
+    byKind: Record<PoolKind, number>;
+}
+type PoolKind = 'smoke' | 'steam' | 'fire' | 'water' | 'spark';
+interface Effects {
+    /**
+     * Spawns for the active emitters and advances every particle by `dt` seconds, sizing the sprites for the camera given to
+     * `createEffects` (or `setCamera`). No allocations per frame once warmed up. `camera` overrides it for this call (deprecated).
+     */
+    update(dt: number, emitters: readonly ActiveEmitter[], camera?: PerspectiveLike): void;
+    /** Replace the camera used for the sprite size (or `null` to go back to a 90 degree lens). */
+    setCamera(camera: PerspectiveLike | (() => PerspectiveLike | null) | null): void;
+    setWind(x: number, z: number): void;
+    setViewHeight(px: number): void;
+    stats(): EffectsStats;
+    /** The Points objects (one per kind). */
+    objects: Record<PoolKind, ThreeNS.Points>;
+    /** Water stream meshes (tapered, translucent, following the gravity arc) and the one mesh holding every gas flame ring. */
+    meshes: {
+        group: ThreeNS.Group;
+        streams: ThreeNS.Mesh[];
+        flames: ThreeNS.Mesh;
+    };
+    clear(): void;
+    dispose(): void;
+}
+/**
+ * Pooled particle effects: smoke, steam, fire (and the blue gas `flame` ring), water streams with drips, and sparks.
+ * One `Points` per kind, fixed-size buffers, swap-remove; the total alive never exceeds `maxParticles`.
+ */
+declare function createEffects(THREE: ThreeLib, options: EffectsOptions): Effects;
+/** @deprecated Pass `{ scene, camera, ... }` as the one options argument. */
+declare function createEffects(THREE: ThreeLib, scene: ThreeNS.Object3D, options?: Partial<EffectsOptions>): Effects;
+
+/**
+ * Points of a hanging cord between `a` and `b` (n points including both ends, n >= 2). The deepest point sits `sag` meters below
+ * the straight line between the ends, on a real catenary (y = a cosh(x/a)); when the ends differ in height the curve is
+ * measured against the straight line between them.
+ */
+declare function catenary(a: Vec3, b: Vec3, sag: number, n?: number): Vec3[];
+/** A thin tube through `points` (Catmull-Rom smoothed) for wires, cords and conduits. */
+declare function createCord(THREE: ThreeLib, points: readonly Vec3[], radius: number, material: ThreeNS.Material, radialSegments?: number): ThreeNS.Mesh;
+
+type MaterialMap = Partial<Record<MaterialKey, ThreeNS.Material>>;
+interface MeshApiOptions {
+    /** Materials per key. Missing keys get a default (vertex-colored) material. */
+    materials?: MaterialMap;
+    /** `high`: smoother cylinders and spheres, standard materials. `game`: fewer segments, Lambert materials. Default `high`. */
+    quality?: Quality;
+    /** Cast and receive shadows on the merged meshes. Default true. */
+    shadows?: boolean;
+    /** Make `plane` primitives double sided (applies to the default materials only). Default false. */
+    doubleSidedPlanes?: boolean;
+    /**
+     * Cut draw calls: `finish(spec)` merges the parts of one `PartSpec.group` that share a motion (blind slats) and the `cloth` soft
+     * volumes (clothes on a line) into one mesh per material (see `mergeParts`). Needs the spec in `finish`. Default: on in `game` quality.
+     */
+    mergeParts?: boolean;
+    /** Idle flutter of merged cloth. Default 0.04. */
+    swayAmplitude?: number;
+    /**
+     * Material of one draw: called per mesh with its material key and the part id (`null` for the static body). Return the material the
+     * host wants there (a per-room light mask, a flickering emissive...); the default is `materials[key]`. Merged groups (blind slats,
+     * clothes) keep what you return, including its `onBeforeCompile`, `customProgramCacheKey`, `defines` and `userData`.
+     */
+    materialFor?: (key: MaterialKey, partId: string | null) => ThreeNS.Material | undefined;
+}
+interface MeshResult {
+    /** Root group: static meshes (one per material) plus one child group per part (merged parts share one group, see `mergeParts`). */
+    group: ThreeNS.Group;
+    /** Part groups by id. Origin at the pivot, rotated by the part's `ry`; `userData.rest` holds the rest pose. A merged part maps to the shared group (`userData.merged`). */
+    parts: Record<string, ThreeNS.Group>;
+    /** Real lights requested by the builders (already children of their group). */
+    lights: ThreeNS.Light[];
+}
+interface FinishOptions {
+    /** Same as `MeshApiOptions.materialFor`; wins over it for this call. */
+    materialFor?: MeshApiOptions['materialFor'];
+}
+interface MeshApi {
+    api: HouseholdApi;
+    /** Builds the groups from everything drawn so far. Call once; the api is spent afterwards. Pass the spec the pack returned to allow `mergeParts`. */
+    finish(spec?: ObjectSpec, finishOptions?: FinishOptions): MeshResult;
+    /** Materials in use (defaults merged with the given ones). */
+    materials: Record<MaterialKey, ThreeNS.Material>;
+}
+/** Default materials: vertex colors everywhere (in `game` quality plain, metal, wood and fabric are one shared Lambert material), glass and water transparent, emissive unlit. */
+declare function createDefaultMaterials(THREE: ThreeLib, quality?: Quality): Record<MaterialKey, ThreeNS.Material>;
+/**
+ * Mesh api for content packs. Every primitive is baked (vertex colors) into one `BufferGeometry` per material and per target
+ * (the root, or a part), so the draw calls are the number of materials in use plus the same again for each part.
+ */
+declare function createMeshApi(THREE: ThreeLib, options?: MeshApiOptions): MeshApi;
+
+/** `Reflector` from `three/examples/jsm/objects/Reflector.js`, passed by the host. */
+type ReflectorConstructor = new (geometry: ThreeNS.BufferGeometry, options?: {
+    textureWidth?: number;
+    textureHeight?: number;
+    clipBias?: number;
+    color?: ThreeNS.ColorRepresentation;
+}) => ThreeNS.Mesh;
+interface MirrorOptions {
+    /** Without it every mirror shows the env map only. */
+    Reflector?: ReflectorConstructor;
+    /** Cube / equirect env map for the cheap look. */
+    envMap?: ThreeNS.Texture | null;
+    /** Real reflectors alive at once. Default 1. */
+    max?: number;
+    /** Reflector texture size in pixels. Default 512. */
+    resolution?: number;
+    /** Where reflectors are added. Default: the root ancestor of the registered mesh. */
+    scene?: ThreeNS.Object3D;
+    /** Distance in front of the plane, meters. Default 0.001. */
+    offset?: number;
+    /**
+     * three's `Reflector` renders the scene again inside the main `render()`, and that nested render resets `renderer.info` when
+     * `info.autoReset` is on, so the counters would only show the reflector pass. With `keepInfo` (default true) the reflector adds
+     * what was counted before it back, so `renderer.info.render.calls` covers the whole frame. Skipped when `info.autoReset` is off.
+     */
+    keepInfo?: boolean;
+}
+/** The mirror entries of `world.mirrors(...)` (only these fields are read). */
+interface MirrorCandidate {
+    id: string;
+    center: Vec3;
+    normal: Vec3;
+}
+interface Mirrors {
+    /** Registers the display mesh of a mirror (world id `objectId:mirrorId`). It gets the env-map material. `normal` is the world normal; default: the mesh's +z. */
+    register(id: string, mesh: ThreeNS.Mesh, normal?: Vec3): void;
+    unregister(id: string): void;
+    /** Activates real reflectors for the nearest facing registered mirrors among `candidates`. Returns the active ids. */
+    update(camera: ThreeNS.Camera, candidates: readonly MirrorCandidate[]): string[];
+    /** Ids that currently have a real reflector. */
+    active(): string[];
+    /** The shared env-map material registered meshes use. */
+    envMaterial: ThreeNS.Material;
+    dispose(): void;
+}
+/**
+ * Mirrors: every registered mirror shows an env-map material; the nearest `max` that face the camera get a real `Reflector`
+ * (pooled and reused), placed `offset` in front of the plane with the mesh's rotation and size.
+ */
+declare function createMirrors(THREE: ThreeLib, options?: MirrorOptions): Mirrors;
+
+/** Pure pose of a part at `t`, in the part's own frame (the frame at rest: pivot at the origin, already turned by the part's `ry`). */
+interface Pose {
+    /** Translation, part frame. */
+    position: Vec3;
+    /** Rotation as a quaternion [x, y, z, w], part frame. */
+    quaternion: [number, number, number, number];
+    /** Scale per local axis. */
+    scale: Vec3;
+}
+/**
+ * The engine's pose math, as a quaternion. This is the engine's own `poseOf` (same default angles and distances), so the rendered
+ * part and the engine's `slotPosition`, colliders, mirrors and `fitSweep` always agree. `t` is clamped to [0, 1].
+ */
+declare function poseOf(motion: Motion, t: number): Pose;
+interface Rest {
+    position: Vec3;
+    quaternion: [number, number, number, number];
+    scale: Vec3;
+}
+/** Remembers the rest transform of a part group in `userData.rest` (once). */
+declare function rememberRest(group: {
+    position: any;
+    quaternion: any;
+    scale: any;
+    userData: Record<string, any>;
+}): Rest;
+/**
+ * Poses `group` for a motion at `t`. The rest pose (position at the pivot, rotation `ry`) is saved in `group.userData.rest` the first
+ * time, so calling this every frame never drifts. The motion axis lives in the part frame (after `ry`).
+ */
+declare function applyPose<G extends ThreeNS.Object3D>(THREE: ThreeLib, group: G, motion: Motion, t: number): G;
+interface SyncOptions {
+    /** Seconds, drives the idle flutter of sway shaders. Default 0. */
+    time?: number;
+}
+/**
+ * Per-frame sync of one world object: every part group takes the motion of its `PartSpec` at the world's current t,
+ * and every soft volume swings. A soft volume drives the group in `parts` under its `part` (or, failing that, its own id):
+ * meshes patched with `attachSway` get the swing through their shader uniforms (so shadows follow), any other group is rotated
+ * around the anchor line.
+ */
+declare function syncObject(THREE: ThreeLib, world: World, objectId: string, parts: Record<string, ThreeNS.Object3D>, options?: SyncOptions): void;
+
+interface ScreenOptions {
+    /** Where the canvas is created (the global `document`, or a fake). */
+    document: CanvasFactory;
+    /** Canvas size in pixels. Default 128 x 72. */
+    w?: number;
+    h?: number;
+    /** Seed of the static noise. Default 1. */
+    seed?: number;
+    /** Redraws per second while on. Default 15. */
+    fps?: number;
+    /** Emissive strength while on. Default 1. */
+    intensity?: number;
+}
+interface Screen {
+    material: ThreeNS.MeshStandardMaterial;
+    texture: ThreeNS.CanvasTexture;
+    canvas: any;
+    readonly on: boolean;
+    readonly channel: number;
+    setOn(on: boolean): void;
+    setChannel(channel: number): void;
+    /** Advance the animation; redraws the canvas at `fps` while on. */
+    update(dt: number): void;
+    dispose(): void;
+}
+/**
+ * A screen material backed by a canvas texture. Off: black canvas, no emission. On: the channel's content (0 color bars,
+ * 1 static noise, 2 animated landscape, higher numbers repeat them with shifted hues) lights the surface.
+ */
+declare function createScreen(THREE: ThreeLib, options: ScreenOptions): Screen;
+
+interface SwayOptions {
+    /** Strength of the idle flutter (wind) in meters per meter of hang, 0..1. Default 0.04. */
+    amplitude?: number;
+    /** Local y (geometry space) of the line the cloth hangs from. Default: top of the mesh's bounding box. */
+    anchorY?: number;
+}
+interface SwayUniforms {
+    time: {
+        value: number;
+    };
+    ax: {
+        value: number;
+    };
+    az: {
+        value: number;
+    };
+    anchorY: {
+        value: number;
+    };
+}
+/** Shared state of one swaying mesh: the three materials read the same uniforms. */
+interface SwayHandle {
+    uniforms: SwayUniforms;
+    /** Sets the swing (radians around x and z) and, optionally, the clock for the idle flutter. */
+    set(ax: number, az: number, time?: number): void;
+}
+/** Patches a vertex shader so the vertices hang from the anchor line and swing with the shared uniforms. */
+declare function patchSwayShader(shader: {
+    uniforms: Record<string, any>;
+    vertexShader: string;
+}, uniforms: SwayUniforms, amplitude: number): void;
+/**
+ * Clones `base` and patches it with a vertex-shader sway (uniforms `time`, `ax`, `az`, `anchorY`). The returned material carries
+ * `userData.sway` (a `SwayHandle`), `customDepthMaterial` and `customDistanceMaterial` patched with the same uniforms, so
+ * directional / spot shadow maps and point-light shadow cubes follow the animation. Assign it to a mesh, and set
+ * `mesh.customDepthMaterial` / `mesh.customDistanceMaterial` from the material (or just use `attachSway`).
+ */
+declare function swayMaterial(THREE: ThreeLib, base: ThreeNS.Material, options?: SwayOptions): ThreeNS.Material & {
+    userData: {
+        sway: SwayHandle;
+        depthMaterial: ThreeNS.MeshDepthMaterial;
+        distanceMaterial: ThreeNS.MeshDistanceMaterial;
+    };
+};
+/**
+ * Makes a mesh sway: replaces its material with `swayMaterial(...)` and sets `customDepthMaterial` and `customDistanceMaterial`.
+ * `mesh.userData.sway` is the handle `syncObject` drives. Returns the handle.
+ */
+declare function attachSway(THREE: ThreeLib, mesh: ThreeNS.Mesh, options?: SwayOptions): SwayHandle;
+
+interface ThreeAdapterOptions {
+    /** Default for `createMeshApi` / `createScreen` / `createEffects`. */
+    document?: CanvasFactory;
+    quality?: Quality;
+    materials?: MeshApiOptions['materials'];
+    /** `Reflector` and env map for `createMirrors`. */
+    Reflector?: MirrorOptions['Reflector'];
+    envMap?: MirrorOptions['envMap'];
+}
+/** The package functions with `THREE` and the common options already bound. */
+interface ThreeAdapter {
+    THREE: ThreeLib;
+    createMeshApi(options?: MeshApiOptions): MeshApi;
+    applyPose<G extends ThreeNS.Object3D>(group: G, motion: Motion, t: number): G;
+    syncObject(world: World, objectId: string, parts: Record<string, ThreeNS.Object3D>, options?: SyncOptions): void;
+    swayMaterial(base: ThreeNS.Material, options?: SwayOptions): ReturnType<typeof swayMaterial>;
+    attachSway(mesh: ThreeNS.Mesh, options?: SwayOptions): SwayHandle;
+    createEffects(options: EffectsOptions): Effects;
+    /** @deprecated Pass `{ scene, camera, ... }`. */
+    createEffects(scene: ThreeNS.Object3D, options?: Partial<EffectsOptions>): Effects;
+    createScreen(options?: Partial<ScreenOptions>): Screen;
+    createMirrors(options?: MirrorOptions): Mirrors;
+    createCord(points: readonly Vec3[], radius: number, material: ThreeNS.Material): ThreeNS.Mesh;
+    catenary: typeof catenary;
+}
+/** Binds the host's `THREE` (and shared options) once, so the rest of the host code never passes it around. */
+declare function createThreeAdapter(THREE: ThreeLib, options?: ThreeAdapterOptions): ThreeAdapter;
+
+interface MergeOptions {
+    /** Idle flutter of merged cloth (see `SwayOptions.amplitude`). Default 0.04. */
+    swayAmplitude?: number;
+}
+/** Posed by `syncObject` in place of the part groups it replaced. */
+interface PoseBatch {
+    kind: 'pose';
+    /** Part ids that moved into the batch. */
+    ids: string[];
+    /** Applies the motion at `t` to every vertex, each around its own pivot. */
+    apply(motion: Motion, t: number): void;
+}
+/** Cloth hanging from a line: every merged cloth swings with its own (ax, az). */
+interface SwayBatch {
+    kind: 'sway';
+    /** Soft volume id -> index. */
+    index: Record<string, number>;
+    setAt(index: number, ax: number, az: number): void;
+    setTime(time: number): void;
+}
+type MergedGroup = ThreeNS.Group & {
+    userData: {
+        merged: PoseBatch | SwayBatch;
+    };
+};
+/**
+ * Merges parts after `finish()` to cut draw calls (the `mergeParts` option of `createMeshApi`):
+ *
+ * - parts of one `PartSpec.group` with the same motion (blind slats) become one mesh per material whose vertices carry their own pivot;
+ *   `syncObject` poses them with one set of uniforms and the shadow materials follow;
+ * - `cloth` soft volumes (clothes on a line) become one mesh per material with a per-vertex cloth index and anchor height; each
+ *   cloth keeps its own swing.
+ *
+ * The merged group is added to `root`, the part groups are removed, and `parts[id]` points at the merged group for every member.
+ * Parts that carry a mirror, that are turned (`ry`) or that stand alone are left as they are.
+ */
+declare function mergeParts(THREE: ThreeLib, root: ThreeNS.Group, parts: Record<string, ThreeNS.Group>, spec: ObjectSpec, options?: MergeOptions): void;
+
+export { type CanvasFactory, type Effects, type EffectsOptions, type EffectsStats, type FinishOptions, type HouseholdApi, MATERIAL_KEYS, type MaterialKey, type MaterialMap, type MergeOptions, type MergedGroup, type MeshApi, type MeshApiOptions, type MeshResult, type MirrorCandidate, type MirrorOptions, type Mirrors, type PerspectiveLike, type PoolKind, type Pose, type PoseBatch, type Quality, type ReflectorConstructor, type Screen, type ScreenOptions, type SwayBatch, type SwayHandle, type SwayOptions, type SwayUniforms, type SyncOptions, type ThreeAdapter, type ThreeAdapterOptions, type ThreeLib, type Vec3, applyPose, attachSway, catenary, createCord, createDefaultMaterials, createEffects, createMeshApi, createMirrors, createScreen, createThreeAdapter, mergeParts, patchSwayShader, poseOf, rememberRest, swayMaterial, syncObject };