@adatechnology/game-test-room 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,115 @@
-# Temporary Holding Version
+# @adatechnology/game-test-room
 
-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.
+A self-contained first-person test room for three.js. Drop your own catalogue of objects in, walk around, shoot, hit, burn, cut, throw, drink and pour,
+and read what happened in plain words in an on-screen behaviour log that you (or an agent) can also export as JSON or NDJSON. Scripted scenarios
+check the behaviour and write pass/fail lines to the same log.
+
+It composes `@adatechnology/game-destruction`, `game-destruction-three`, `game-weapons`, `game-fluids` and `game-fluids-three`. `three` is a peer dependency used only as a type: you pass the namespace in.
+
+Contracts live in [`@adatechnology/game-contracts`](../game-contracts); the types are re-exported here, so existing imports keep working.
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-test-room three
+```
+
+## Usage
+
+```ts
+import * as THREE from 'three'
+import { createTestRoom, demoItems } from '@adatechnology/game-test-room'
+
+const room = createTestRoom({
+  THREE,
+  container: document.getElementById('app')!,
+  locale: 'en', // 'en' or 'pt-BR'
+  catalog: demoItems('en'),
+})
+room.runScenarios().then((report) => console.log(report.passed, report.failed))
+console.log(room.log.toNDJSON())
+```
+
+The IIFE build exposes `GameTestRoom`. Without an injected `renderer` the room owns the canvas and its render loop.
+
+## Plugging in your own catalogue and scenarios
+
+```ts
+const room = createTestRoom({
+  THREE,
+  container,
+  catalog: [
+    ...demoItems('en'),
+    { id: 'my_crate', name: 'My crate', group: 'Mine', build: (T) => buildMyCrate(T), specOptions: { /* material per mesh name */ } },
+  ],
+  scenarios: [
+    { id: 'my_crate_breaks', name: 'My crate breaks', run: ({ room, step, expect }) => {
+      const o = room.spawn('my_crate', [0, 0, -4])
+      room.setTool('pistol_9mm')
+      room.look([0, 1, -2], [0, 0.5, -4])
+      room.use()
+      step(2)
+      expect(room.world.state(o.objectId)!.parts.some((p) => p.status !== 'intact'), 'a part was hurt')
+    } },
+  ],
+})
+```
+
+`DEMO_MATERIALS` is now empty (kept for compatibility: the demo items use only core materials). `buildFromSpec` turns a `DestructibleSpec` into meshes,
+and `brickWallSpec` / `DEMO_ITEMS` / `SCENARIOS` are exported to reuse or extend.
+
+## Loading a module
+
+A game module hands the room a `TestableModule` from `@adatechnology/game-contracts` (items, each with an optional `impl` for its own destruction and `animations`, plus scenarios):
+
+```ts
+const report = room.loadModule(RENTAL_CARS) // { module, items, scenarios, ok, problems }
+```
+
+The items join the catalogue under the module's group and its scenarios become buttons. The contract checks run at once and write one line per result to the log: `checkDestructible` for every item with an `impl`, `checkAnimation` for every clip (`✓ Rental car: destructible contract ok (4 parts...)` or `✗ ...: <problem>`). The animations panel lists the clips of the aimed or held item; `room.playAnimation(clipId)` plays one (poses are offsets from the rest pose, events go to the log and `sound` events to `onSound`). The example (`examples/test-room`) loads a `DEMO_MODULE` rental car that owns its damage rule, its door `open` clip and a wheel that comes off with a wrench.
+
+## Controls
+
+| Input | Action |
+|---|---|
+| Click / Esc | capture / release the mouse (without pointer lock: drag to look) |
+| WASD, Shift, Space | walk, run, jump |
+| 1-0, wheel | pick a tool from the hotbar |
+| Left button | use the tool (shoot, hit, flame, heat, throw, work a joint, extinguish, grab) |
+| E | grab / drop |
+| R | rotate the held item |
+| Right button or G | throw |
+| F | use a fluid item (drink); Z tilt; C fill from the tap; V pour (holding a fluid item) or kick (otherwise, with the `kick` tool whatever is selected) |
+| Tab | show / hide the panels |
+
+Panels: catalogue tabs (spawn, Clear, Reset all), slow motion 0.25x, time x10, quality select, inspector (material, state, hp, temperature, char, marks, joints, load and stress) and the behaviour log with filters.
+
+## Log format
+
+One JSON object per line (`log.toNDJSON()`, "Baixar NDJSON"):
+
+```json
+{"seq":1,"t":0,"channel":"action","type":"spawn","text":"Spawned Steel sheet with stand at (0.0, 0.0, -4.0)","objectId":"steel_sheet_1","itemId":"steel_sheet","data":{"position":[0,0,-4],"movable":false,"massKg":43.6}}
+```
+
+`channel` is `action`, `event` or `check`; `t` is room time in seconds; `data` is machine-readable. `log.toText()` gives the plain-text version and `log.entries({ type, objectId })` filters.
+
+## Scenarios
+
+`room.scenarios` lists them; `room.runScenarios(list?)` resets the room, runs each one deterministically with `step(seconds)` instead of rendering, and returns
+`{ passed, failed, results: [{ id, name, ok, checks: [{ label, ok }] }] }`. 21 ship with the package (bullets vs steel, concrete and glass, hammer, shotgun, kick, screwdriver,
+fire and torch, gas bottle, bottle drop, thrown chair, coffee sips and spills, jerrycan leak, fuel fire, columns and a roof, extinguisher). Open the example with `?scenario=all` to run them.
+
+### Inside a claude.ai Artifact
+
+An Artifact page cannot use `<a download>` or blob links. When `globalThis.claude.use('downloads')` resolves, `log.download(format)` offers the file through that capability (the NDJSON goes out as `test-room-log.ndjson.txt`, since `.ndjson` is not on the allowlist) and a declined save writes an `export_cancelled` line to the log; otherwise it falls back to the blob link. **The artifact page must declare the `downloads` capability.** "Copy JSON" falls back to selecting the text in a textarea when `navigator.clipboard` is missing.
+
+## Português
+
+Uma sala de testes em primeira pessoa para three.js. Você passa o seu catálogo de objetos, anda, atira, bate, queima, corta, arremessa, bebe café e
+derrama líquidos, e lê o que aconteceu em linguagem simples no registro de comportamento (também exportável em JSON, NDJSON ou texto). Os cenários
+automáticos conferem o resultado e gravam aprovado/reprovado no mesmo registro. Use `locale: 'pt-BR'` para textos em português.
+
+## Known limitations
+
+The quality select does not recreate the destruction renderer; it only changes the room's own settings. Unit tests use an injected stub renderer (no WebGL).

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+import * as THREE_NS from 'three';
+import { DestructibleSpec, Vec3, DestructionWorld, DestructionOptions, DestructionEvent, MaterialDef } from '@adatechnology/game-destruction';
+export { DestructionEvent, Vec3 } from '@adatechnology/game-destruction';
+import { SpecFromObjectOptions, DestructionRenderer, Quality } from '@adatechnology/game-destruction-three';
+import { Arsenal, WeaponState, WeaponDef } from '@adatechnology/game-weapons';
+import { FluidRenderer } from '@adatechnology/game-fluids-three';
+import { ContainerSpec, FluidWorld, LiquidDef, ItemUseDef, SurfaceSpec } from '@adatechnology/game-fluids';
+import { DestructibleImpl, AnimationClipSpec, TestableModule } from '@adatechnology/game-contracts';
+export { AnimationClipSpec, DestructibleImpl, ItemAnimationContract, ModuleScenario, TestableItem, TestableModule } from '@adatechnology/game-contracts';
+
+type NewEntry = NewLogEntry;
+/** The log the room writes to (a `TestRoomLog` plus the write side). */
+interface WritableLog extends TestRoomLog {
+    /** Called before every read, so pending work (the room batches events per frame) is flushed first. */
+    setBeforeRead(fn: (() => void) | null): void;
+    setClock(fn: () => number): void;
+}
+interface LogOptions {
+    /** Text of the `action` line written when the viewer declines (or fails) an export from an Artifact page. */
+    exportCancelled?: () => string;
+}
+declare function createLog(options?: LogOptions): WritableLog;
+
+/** Locales shipped with the package. Unknown locales fall back to `en`. */
+type TestRoomLocale = 'en' | 'pt-BR';
+interface RoomStrings {
+    /** Display name per demo item id (see `DEMO_ITEMS`). */
+    items: Record<string, string>;
+    /** Display name per demo catalogue group. */
+    groups: Record<string, string>;
+    /** Every other text: UI, log lines, scenario names and checks. `{name}` placeholders are replaced. */
+    text: Record<string, string>;
+}
+declare const locales: Record<TestRoomLocale, RoomStrings>;
+declare const resolveStrings: (locale: string | undefined) => RoomStrings;
+
+interface InspectInfo {
+    object: string;
+    objectId: string;
+    part: string;
+    material: string;
+    status: string;
+    hp: number;
+    maxHp: number;
+    temperature: number;
+    burning: boolean;
+    char: number;
+    melt: number;
+    liters?: number;
+    dents: number;
+    holes: number;
+    cracks: number;
+    mass: number;
+    /** Structural load in kg and stress (load / capacity) when the core reports them. */
+    load?: number;
+    stress?: number;
+    joints: Array<{
+        id: string;
+        kind: string;
+        tools: string[];
+        open: boolean;
+        progress: number;
+    }>;
+    note?: string;
+    distance: number;
+}
+interface HudState {
+    toolName: string;
+    toolId: string;
+    ammo: string;
+    slots: string[];
+    slot: number;
+    page: number;
+    pages: number;
+    status: string;
+    progress: {
+        label: string;
+        value: number;
+    } | null;
+    held: {
+        name: string;
+        uses: Array<{
+            key: string;
+            label: string;
+        }>;
+        weapon?: string;
+        using: string;
+    } | null;
+    inspect: InspectInfo | null;
+    /** Animations of the aimed or held item. */
+    animations: AnimationInfo | null;
+    locked: boolean;
+    timeScale: number;
+    fast: boolean;
+    tap: boolean;
+    quality: string;
+    objects: number;
+}
+
+/**
+ * Public types of @adatechnology/game-test-room.
+ *
+ * A self-contained test room any team can drop into its viewer: a floor with a target wall, shelves and a table, a first-person player
+ * (pointer lock, WASD) with an orbit fallback, a catalogue of the host's objects, and tools. The player can spawn objects, grab them, carry,
+ * drop and throw them (a thrown or dropped object takes and deals blunt damage), shoot them with real calibres, hit, cut, burn, melt, blow up
+ * and take them apart joint by joint, inspect the state of every part, and use items that hold liquids (fill a cup, drink a coffee, pour, spill, shoot a jerrycan and watch it leak).
+ * Every action and result goes to a behaviour log shown on screen in plain words and exportable as JSON / NDJSON, and scripted scenarios run
+ * from buttons (or headless in tests) and write pass/fail checks to the same log, so people and agents can verify the behaviour.
+ */
+
+type ThreeNamespace = typeof THREE_NS;
+/** One entry of the catalogue: something the host can build. */
+interface TestRoomItem {
+    /** snake_case id. */
+    id: string;
+    /** Display name (already translated by the host). */
+    name: string;
+    /** Catalogue tab (free text: e.g. `Furniture`, `Vehicles`, `Plants`, `House`, `Weapons and items`). */
+    group: string;
+    /** Build the three.js object, origin at the centre of its footprint on the floor, front facing +z. */
+    build: (THREE: ThreeNamespace) => THREE_NS.Object3D;
+    /** Destruction spec. Default: `specFromObject3D` on the built object with `specOptions`. A function gets the built root. */
+    spec?: DestructibleSpec | ((root: THREE_NS.Object3D) => DestructibleSpec);
+    specOptions?: SpecFromObjectOptions;
+    /** Can be grabbed and thrown (default: total mass <= `maxCarryKg`). Vehicles and trees are usually `false`. */
+    movable?: boolean;
+    /** Short note shown in the inspector. */
+    note?: string;
+    /**
+     * The item holds a liquid (a cup of coffee, a bottle, a jerrycan, a fuel tank). `part` is the destruction part that is the container (a
+     * bullet hole in it makes it leak). `uses` are the item uses offered while it is held (`drink`, `pour`...; defaults from `ITEM_USES`).
+     */
+    fluid?: {
+        container: ContainerSpec;
+        part?: string;
+        uses?: string[];
+        offset?: Vec3;
+    };
+    /** The item is also a weapon the player can equip from the catalogue (e.g. a crowbar, a knife, a pistol on the table). */
+    weapon?: string;
+    /**
+     * The item's own destruction (a `DestructibleImpl` of a game module). The room registers it in the world (`world.register`) instead of
+     * building a default object from `spec`; `id` is the object id the room gives it and `DestructibleImpl.id` must be that id. Impl items are not movable.
+     */
+    impl?: (root: THREE_NS.Object3D, id: string) => DestructibleImpl;
+    /** Use animations the item brings (see `TestRoom.playAnimation`). Part poses move the child of the built object named after the part id. */
+    animations?: AnimationClipSpec[];
+}
+interface TestRoomOptions {
+    THREE: ThreeNamespace;
+    /** Element the bench fills (canvas + HUD). */
+    container: HTMLElement;
+    /** `en` (default) or `pt-BR`. */
+    locale?: string;
+    catalog: TestRoomItem[];
+    /** Weapons and tools in the hotbar: ids of the arsenal (default `DEFAULT_LOADOUT`), plus extra definitions merged into the arsenal. */
+    loadout?: string[];
+    weapons?: WeaponDef[];
+    /** An existing arsenal (default `createArsenal({ locale })`). */
+    arsenal?: Arsenal;
+    /** Fluids: an existing world, extra liquids, item uses, and surfaces (the arena floor and the table are added automatically). */
+    fluids?: FluidWorld;
+    liquids?: LiquidDef[];
+    itemUses?: ItemUseDef[];
+    surfaces?: SurfaceSpec[];
+    /** Extra scripted checks offered as buttons (the built-in `SCENARIOS` are always there). */
+    scenarios?: TestRoomScenario[];
+    /** Use the host's renderer/scene/camera instead of making its own (then the host calls `bench.update(dt)` every frame). */
+    renderer?: THREE_NS.WebGLRenderer;
+    scene?: THREE_NS.Scene;
+    camera?: THREE_NS.PerspectiveCamera;
+    /** World options (seed, extra materials). Or pass an existing world. */
+    world?: DestructionWorld;
+    worldOptions?: DestructionOptions;
+    quality?: Quality;
+    /** Heaviest object the player can carry (default 60 kg). */
+    maxCarryKg?: number;
+    /** Arena half size in metres (default 14). */
+    arenaSize?: number;
+    /** Spawn these catalogue ids on start, in a row in front of the player. */
+    initial?: string[];
+    /** Called for every destruction event (to log, play sounds, sync over LAN). Fluid events reach the log too. */
+    onEvent?: (event: DestructionEvent) => void;
+    onSound?: (key: string, point: Vec3, volume: number) => void;
+    /** Show the built-in HUD and panels (default true). */
+    ui?: boolean;
+}
+interface SpawnedObject {
+    objectId: string;
+    itemId: string;
+    root: THREE_NS.Object3D;
+    movable: boolean;
+}
+interface TestRoom {
+    readonly world: DestructionWorld;
+    readonly renderer: DestructionRenderer;
+    readonly scene: THREE_NS.Scene;
+    readonly camera: THREE_NS.PerspectiveCamera;
+    /** Spawn a catalogue item at a world position (default in front of the player). */
+    spawn(itemId: string, position?: Vec3, rotationY?: number): SpawnedObject;
+    /** Remove every spawned object, fragment and particle. */
+    clear(): void;
+    /** Repair every spawned object in place. */
+    resetAll(): void;
+    readonly arsenal: Arsenal;
+    readonly fluids: FluidWorld;
+    /** Equip a weapon or tool of the loadout (or any arsenal id). */
+    setTool(weaponId: string): void;
+    readonly tool: WeaponState;
+    /** Play an item use on the held item (`drink`, `pour`...). Returns false when nothing is held or the use does not apply. */
+    useItem(useId: string): boolean;
+    /** Use the current tool once from the camera (tests and scripted demos). `hold` seconds for continuous tools. */
+    use(hold?: number): void;
+    /** Grab what the camera looks at (or drop what is held). */
+    grab(): boolean;
+    /** Throw what is held at `speed` m/s (default 9). */
+    throwHeld(speed?: number): boolean;
+    /** Point the camera (scripted demos and tests). */
+    look(position: Vec3, target: Vec3): void;
+    /** Object and part the camera looks at, with its state, for the inspector. */
+    inspect(): {
+        objectId: string;
+        partId: string;
+        itemId: string;
+    } | null;
+    /** Everything the inspector panel shows for the aimed part (state, joints and the tools that undo them), or null. */
+    inspectInfo(): InspectInfo | null;
+    spawned(): SpawnedObject[];
+    /** Advance one frame (only needed when the host owns the loop). */
+    update(dt: number): void;
+    on(type: 'spawn' | 'tool' | 'grab' | 'throw' | 'event', fn: (data: unknown) => void): () => void;
+    /** Tilt the held item by `rad` radians around its own x axis (hold Z in the room). Pouring and spilling follow from the tilt. */
+    tilt(rad: number): void;
+    /** Open or close the tap over the table (default: toggle). Returns whether it is open. */
+    toggleTap(on?: boolean): boolean;
+    /** Stop the simulation (time, physics, animations, tools, walks): the UI, the camera and the log stay live. `step` and `update` do nothing until `resume`. Scenarios run unpaused. */
+    pause(): void;
+    resume(): void;
+    readonly paused: boolean;
+    /** Walk the player in a straight line to the floor position `to` (x and z; y is ignored) over `seconds` of simulated time, during the next `step()` / frames. Colliders still block. 0 seconds moves at once. */
+    walk(to: Vec3, seconds: number): void;
+    /** 0.25x simulation speed. */
+    setSlowMotion(on: boolean): void;
+    /** Run the simulation 10x per frame (fire, melting and drying take a tenth of the time). */
+    setFastForward(on: boolean): void;
+    /** Equip a weapon by id, adding it to the hotbar when it is not there. Same as selecting a catalogue item with `TestRoomItem.weapon`. */
+    equip(weaponId: string): void;
+    /** The scenarios the panel offers: the built-in `SCENARIOS` in the room locale plus `TestRoomOptions.scenarios`. */
+    readonly scenarios: TestRoomScenario[];
+    /** The liquid renderer of `@adatechnology/game-fluids-three` (containers, streams, stains). */
+    readonly fluidRenderer: FluidRenderer;
+    /** The behaviour log (see `TestRoomLog`). */
+    readonly log: TestRoomLog;
+    /** Run scripted checks (no input needed; works headless in tests and from the browser console). */
+    runScenarios(scenarios?: TestRoomScenario[]): Promise<ScenarioReport>;
+    /**
+     * Load a module that follows the `TestableModule` contract of `@adatechnology/game-contracts`: its items join the catalogue under `module.group`,
+     * its scenarios become buttons, and the contract checks run now (`checkDestructible` for every item with an `impl`, `checkAnimation` for every
+     * clip) writing a check line (pass or fail) per result to the log. Loading the same module twice replaces its items and scenarios.
+     */
+    loadModule(module: TestableModule<ScenarioContext>): ModuleReport;
+    /** Animations of the aimed (or held) item: what the animations panel shows. */
+    animations(): AnimationInfo | null;
+    /**
+     * Play an animation clip of an item (default the held, else the aimed one). Returns false when there is no such item or clip. Poses are
+     * offsets from the rest pose, interpolated linearly; the item keeps the last pose. Events are logged (and `sound` events reach `onSound`).
+     */
+    playAnimation(clipId: string, objectId?: string): boolean;
+    dispose(): void;
+}
+/** What `TestRoom.loadModule` did. */
+interface ModuleReport {
+    module: string;
+    /** Catalogue ids added. */
+    items: string[];
+    /** Scenario ids added. */
+    scenarios: string[];
+    /** Every contract check passed. */
+    ok: boolean;
+    /** Each failed check, in words. */
+    problems: string[];
+}
+interface AnimationInfo {
+    objectId: string;
+    itemId: string;
+    name: string;
+    clips: Array<{
+        id: string;
+        duration: number;
+    }>;
+    /** Clip playing now, if any. */
+    playing: string | null;
+}
+/**
+ * One line of the behaviour log. Every destruction event becomes one entry with the material, the part status and the numbers that matter, plus
+ * the player's actions (spawn, tool use, grab, drop, throw, disassemble) so a reader (a person or an agent) can check the behaviour is right.
+ */
+interface LogEntry {
+    /** Monotonic index. */
+    seq: number;
+    /** Bench time in seconds. */
+    t: number;
+    /** `action` = something the player or a script did; `event` = a destruction event; `check` = a scenario assertion. */
+    channel: 'action' | 'event' | 'check';
+    /** Event or action type (`dent`, `hole`, `fracture`, `ignite`, `spawn`, `shoot`, `grab`, `throw`, `disassemble`...). */
+    type: string;
+    objectId?: string;
+    itemId?: string;
+    part?: string;
+    material?: string;
+    /** Part status and numbers after the event (hp, maxHp, temperature, char, melt, liters, group count). */
+    state?: Record<string, number | string | boolean>;
+    /** Everything else (energy, caliber, depth, diameter, fragment count, joint, tool, pass/fail...). */
+    data?: Record<string, unknown>;
+    /** One human line in the bench locale, e.g. "Cadeira › perna_1 (madeira macia): amassado 4 mm, hp 38/60". */
+    text: string;
+}
+interface TestRoomLog {
+    entries(filter?: {
+        channel?: LogEntry['channel'];
+        type?: string;
+        objectId?: string;
+    }): LogEntry[];
+    clear(): void;
+    /** JSON array of entries. */
+    toJSON(): string;
+    /** One JSON object per line (easy to grep and diff). */
+    toNDJSON(): string;
+    /** Plain text lines (the on-screen panel). */
+    toText(): string;
+    /**
+     * Download the log as a file (`.ndjson` by default). In a claude.ai Artifact page (a `globalThis.claude.use('downloads')` that resolves) it asks the
+     * viewer through the `downloads` capability (`ndjson` is saved as `.ndjson.txt`, the allowlist has no `.ndjson`); if the viewer declines, an
+     * `export_cancelled` action line is logged. Elsewhere it uses a blob link.
+     */
+    download(format?: 'json' | 'ndjson' | 'txt'): Promise<void>;
+    /** Counts per event type and per material (quick summary for checks). */
+    summary(): {
+        byType: Record<string, number>;
+        byMaterial: Record<string, number>;
+        objects: number;
+        destroyed: number;
+    };
+    /** Listener for new entries and for in-place updates of coalesced ones (`updated` true, same entry object). */
+    on(fn: (entry: LogEntry, updated: boolean) => void): () => void;
+    /** Write a line (hosts and scenarios add their own). `seq` and `t` (room time) are filled in. */
+    add(entry: NewLogEntry): LogEntry;
+    /**
+     * Write a line, or update in place the last line written with the same `key` when it was touched less than `windowS` seconds ago (default 1).
+     * Used for noisy sequences: melting, dripping, taking something apart.
+     */
+    coalesce(key: string, entry: NewLogEntry, windowS?: number): LogEntry;
+}
+/** What `TestRoomLog.add` takes. */
+type NewLogEntry = Omit<LogEntry, 'seq' | 't'> & {
+    t?: number;
+};
+/** A scripted check: spawn things, act, then assert on the log and the world state. */
+interface TestRoomScenario {
+    id: string;
+    /** Shown in the report (already translated). */
+    name: string;
+    run: (ctx: ScenarioContext) => void | Promise<void>;
+}
+interface ScenarioContext {
+    room: TestRoom;
+    /** Advance the simulation by `seconds` in fixed steps (no rendering needed). */
+    step(seconds: number): void;
+    /** Record a pass/fail line in the log (`channel: 'check'`). */
+    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
+}
+interface ScenarioReport {
+    passed: number;
+    failed: number;
+    results: Array<{
+        id: string;
+        name: string;
+        ok: boolean;
+        checks: Array<{
+            label: string;
+            ok: boolean;
+        }>;
+    }>;
+}
+
+/**
+ * Create the test room. See `TestRoomOptions`. The room owns a renderer, scene and camera unless you pass them; with your own renderer you call
+ * `room.update(dt)` every frame and render yourself.
+ */
+declare function createTestRoom(options: TestRoomOptions): TestRoom;
+
+/**
+ * Extra materials the demo items need on top of the core ones. None any more (the bottle uses the core `glass`, which now breaks from a drop);
+ * kept so that code passing it to `worldOptions.materials` keeps working.
+ */
+declare const DEMO_MATERIALS: MaterialDef[];
+/** Spec of the brick target wall: `cols` x `rows` brick panels, the bottom row anchored, mortar joints between neighbours. */
+declare function brickWallSpec(cols?: number, rows?: number, panel?: Vec3): DestructibleSpec;
+/**
+ * The generic demo catalogue, names and groups translated for `locale` (`en` or `pt-BR`). Every item is a procedural low-poly build (one mesh per
+ * destruction part, drawn by `buildFromSpec`) plus an explicit destruction spec. Containers carry a fluid container where it makes sense.
+ */
+declare function demoItems(locale?: string, extra?: TestRoomItem[]): TestRoomItem[];
+/** The demo catalogue in English (see `demoItems` for other locales). */
+declare const DEMO_ITEMS: TestRoomItem[];
+
+type T = (key: string, vars?: Record<string, string | number>) => string;
+type Num = (n: number, digits?: number) => string;
+/** Built-in scripted checks over the generic `DEMO_ITEMS`. Names and check texts come from the room locale. */
+declare function makeScenarios(t: T, num: Num, _locale?: string): TestRoomScenario[];
+/** The built-in scenarios for a locale (`en` or `pt-BR`), standalone: no room needed to list them. */
+declare function scenariosFor(locale?: string): TestRoomScenario[];
+/** The built-in scenarios in English. The room offers them in its own locale. */
+declare const SCENARIOS: TestRoomScenario[];
+
+/** Default look of each built-in destruction material (`0xRRGGBB`). */
+declare const MATERIAL_COLORS: Record<string, number>;
+interface BuildFromSpecOptions {
+    /** Colour per part id, then per material id (falls back to `MATERIAL_COLORS`, then grey). */
+    colors?: Record<string, number>;
+    /** Segments of cylinders and spheres (default 12: low poly on purpose). */
+    segments?: number;
+    /** Cast and receive shadows (default true). */
+    shadows?: boolean;
+}
+/**
+ * Draw any `DestructibleSpec` as plain meshes: one mesh per part (box, cylinder or sphere) with `name` and `userData.destructionPart` set to the
+ * part id and `userData.destructionMaterial` to its material, so `renderer.bind` and `specFromObject3D` find them. Useful for teams that describe
+ * objects as specs and want something to look at while they tune them.
+ */
+declare function buildFromSpec(THREE: typeof THREE_NS, spec: DestructibleSpec, options?: BuildFromSpecOptions): THREE_NS.Group;
+
+export { type AnimationInfo, type BuildFromSpecOptions, DEMO_ITEMS, DEMO_MATERIALS, type HudState, type InspectInfo, type LogEntry, MATERIAL_COLORS, type ModuleReport, type NewEntry, type NewLogEntry, type RoomStrings, SCENARIOS, type ScenarioContext, type ScenarioReport, type SpawnedObject, type TestRoom, type TestRoomItem, type TestRoomLocale, type TestRoomLog, type TestRoomOptions, type TestRoomScenario, type ThreeNamespace, type WritableLog, brickWallSpec, buildFromSpec, createLog, createTestRoom, demoItems, locales, makeScenarios, resolveStrings, scenariosFor };