@zylem/game-lib 0.8.3 → 0.8.6

package/dist/api/game-lib.d.ts

@@ -28,6 +28,7 @@ import { BridgeHandler } from '@zylem/bridge';
 import { GameLoadingPayload as BridgeLoadingPayload } from '@zylem/bridge';
 import { BridgeMessages } from '@zylem/bridge';
 import { BridgeMessageType } from '@zylem/bridge';
+import { BridgePose } from '@zylem/bridge';
 import { BridgeVec3 } from '@zylem/bridge';
 import { BufferGeometry } from 'three';
 import { BurstParticlePresetOptions } from '@zylem/behaviors';
@@ -88,6 +89,7 @@ import { EntityDefinition } from '@zylem/behaviors/core';
 import { EntityHandle } from '@zylem/behaviors/core';
 import { EntitySummaryPayload } from '@zylem/bridge';
 import { EntityThumbnailPayload } from '@zylem/bridge';
+import { EntityTypeDescriptor } from '@zylem/bridge';
 import { exp } from 'three/tsl';
 import { FacingAngle2DEntity } from '@zylem/behaviors';
 import { fireCooldown } from '@zylem/behaviors';
@@ -273,6 +275,7 @@ import { RuntimeTriggerRegion2DEvent } from '@zylem/behaviors/runtime-2d';
 import { RuntimeTriggerRegion2DHandle } from '@zylem/behaviors/runtime-2d';
 import { RuntimeTriggerRegion2DOptions } from '@zylem/behaviors/runtime-2d';
 import { Scene } from 'three';
+import { SceneOperationPayload } from '@zylem/bridge';
 import { ScreenVisibilityBehavior } from '@zylem/behaviors';
 import { ScreenVisibilityChangeContext } from '@zylem/behaviors';
 import { ScreenVisibilityFSM } from '@zylem/behaviors';
@@ -333,6 +336,7 @@ import { StageTopDownPlane } from '@zylem/behaviors/core';
 import { Static } from '@sinclair/typebox';
 import { step } from 'three/tsl';
 import { Texture } from 'three';
+import * as three from 'three';
 import { ThrusterBehavior } from '@zylem/behaviors';
 import { ThrusterBehaviorOptions } from '@zylem/behaviors';
 import { ThrusterEntity } from '@zylem/behaviors';
@@ -423,13 +427,16 @@ declare type ActorOptions = BaseNode | ZylemActorOptions;
 /**
  * Owns the stage's in-world debug/editor interaction layer.
  *
- * Self-manages around the global `debugState`: when debug is enabled it draws
- * the wasm simulation's collider wireframes, attaches mouse listeners,
- * raycasts into the physics world to hover/select/delete/spawn entities, and
- * drives the `DebugEntityCursor` highlight. When disabled it tears down
- * visuals but stays alive to re-activate. Centralizes all debug-tool plumbing
- * so `ZylemStage` doesn't have to know about raycasting, DOM input, or debug
- * rendering.
+ * Self-manages around the global `debugState`, in two layers that switch on
+ * independently. The tool layer — mouse listeners, physics raycasts to
+ * hover/select/delete/spawn, the `DebugEntityCursor` highlight and the
+ * `PlacementGhost` — is live whenever a tool is armed, so the toolbar's buttons
+ * work on their own. The debug layer — the wasm simulation's collider
+ * wireframes and the orbit camera — is the part `debugState.enabled` gates, and
+ * is torn down when it goes off while the delegate stays alive to re-activate.
+ *
+ * Centralizes all of this so `ZylemStage` doesn't have to know about
+ * raycasting, DOM input, or debug rendering.
  */
 
 declare type AddEntityFactory = (params: {
@@ -1217,6 +1224,14 @@ declare interface CleanupFunction<T, TGlobals extends GlobalRecord = any> {
  */
 export declare function clearGlobalSubscriptions(): void;
 
+/**
+ * Closest point along an infinite line to a ray, as a distance along the line.
+ *
+ * Returns `null` when the ray is close enough to parallel with the line that the
+ * closest point becomes unstable; see {@link MAX_DRAG_GAIN}.
+ */
+export declare function closestAxisValue(ray: GizmoRay, origin: Vector3, axis: Vector3): number | null;
+
 /**
  * Builds plain body + collider definitions consumable by the behaviors
  * `Simulation` (`simulation.spawn(...)`). No physics-engine types appear
@@ -1345,6 +1360,31 @@ declare interface ConeMeshOptions extends BaseMeshOptions {
 
 declare type ConeOptions = BaseNode | Partial<ZylemConeOptions>;
 
+/**
+ * The y=0 construction plane, drawn so the snap lattice is legible.
+ *
+ * Two overlaid grids: fine lines at the translation snap increment, and heavier
+ * lines every metre. Without the coarse pass a 0.25 grid over any useful area
+ * reads as flat grey noise.
+ */
+
+export declare class ConstructionGrid {
+    private group;
+    private scene;
+    private fine;
+    private coarse;
+    private increment;
+    constructor();
+    addTo(scene: Scene): void;
+    /** Rebuild only when the increment actually changed; this allocates. */
+    setIncrement(increment: number): void;
+    setVisible(visible: boolean): void;
+    get visible(): boolean;
+    dispose(): void;
+    private rebuild;
+    private clearHelpers;
+}
+
 export { CooldownBehavior }
 
 export { CooldownConfig }
@@ -1722,8 +1762,21 @@ declare interface DebugState {
      * Proxy wrappers to engine code that expects real instances.
      */
     selectedEntityId: string | null;
+    /**
+     * Full selection, in click order. `selectedEntityId` mirrors the first
+     * entry. Only ever holds one uuid today, but the gizmo and scene operations
+     * are already written against the list so multi-select needs no rework here.
+     */
+    selectedEntityIds: string[];
     /** UUID of the hovered entity. Same constraint as `selectedEntityId`. */
     hoveredEntityId: string | null;
+    snap: SnapSettings;
+    /** Whether the construction-plane grid is drawn. */
+    gridVisible: boolean;
+    /** Catalog type the add tool will spawn, or null when disarmed. */
+    addTypeId: string | null;
+    /** Creation options merged over the armed type's defaults. */
+    addTypeProps: Record<string, unknown> | null;
     flags: Set<string>;
 }
 
@@ -1731,6 +1784,8 @@ export declare const debugState: DebugState;
 
 export declare type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'add' | 'none';
 
+export declare const DEFAULT_SNAP_SETTINGS: SnapSettings;
+
 /**
  * Builds a ready-to-use {@link GameInputConfig} that wires up themed
  * virtual touch controls for a player. Internally composes
@@ -1790,6 +1845,9 @@ export { defineBehavior }
 
 export { DefineBehaviorConfig }
 
+/** Degrees to radians. */
+export declare function degreesToRadians(degrees: number): number;
+
 /**
  * Wait for a duration. Useful inside `sequence()`.
  *
@@ -1829,6 +1887,22 @@ export { DestructibleMesh }
 
 export { DestructiblePrebakeWorkerAPI }
 
+/** A detached entity plus the pose to restore it at. */
+declare interface DetachedEntity {
+    entity: any;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    } | null;
+}
+
 export declare type DeviceProfile = 'auto' | 'desktop' | 'mobile';
 
 export declare interface DirectionalLightOptions extends BaseLightOptions {
@@ -2055,6 +2129,12 @@ export { EntitySummaryPayload }
 /**
  * Generates and caches entity thumbnail previews for the editor entity list.
  * Renders a cloned Object3D into an offscreen RenderTarget on the shared WebGPU renderer.
+ *
+ * A rendered URL leaves this cache the moment it is read, and the editor holds
+ * it for as long as the entity is listed. Dropping an entry here therefore
+ * must not revoke its blob URL — the consumer owns that lifetime and releases
+ * it when the thumbnail is replaced, the entity is removed, or the stage
+ * changes.
  */
 export declare class EntityThumbnailCache {
     private cache;
@@ -2130,6 +2210,9 @@ export declare interface EntityTypeMap {
     [LINE_TYPE]: ZylemLine;
 }
 
+/** Convert Euler angles (radians, XYZ order) to a quaternion. */
+export declare function eulerToQuaternion(rotation: Vec3): Quat;
+
 /**
  * Reusable delegate for event emission and subscription.
  * Use via composition in Game, Stage, and Entity classes.
@@ -2512,6 +2595,11 @@ export declare class GameBridge {
      * an editor command can never echo back as a game update.
      */
     private editorKnown;
+    /**
+     * True while an undo/redo is being applied, so the writes it performs are
+     * not themselves recorded as new operations.
+     */
+    private applyingSceneOperation;
     constructor();
     /**
      * Subscribe to editor commands and announce the game side as ready.
@@ -2542,6 +2630,12 @@ export declare class GameBridge {
      * Run a callback when an editor first subscribes to entity data, so the
      * game can backfill state produced while nothing was listening.
      *
+     * An editor takes out both entity subscriptions as it mounts, and each is
+     * a first-subscriber transition. Backfilling on both would republish the
+     * config, the whole stage snapshot, and every thumbnail twice per mount,
+     * so a signal is ignored while the other entity type still has a
+     * listener — that is the same editor finishing its setup, not a new one.
+     *
      * @returns An unsubscribe function.
      */
     onEditorAttached(callback: () => void): () => void;
@@ -2551,6 +2645,14 @@ export declare class GameBridge {
         paused?: boolean;
         debug?: boolean;
     }): void;
+    /**
+     * Publish a global's new value.
+     *
+     * Sent rather than queued: a queued payload is merged into the pending one
+     * for its type, and since each message names a single `path`, two globals
+     * changing in the same frame would collapse into one and the first
+     * variable's update would never reach the editor.
+     */
     publishVariable(payload: GameVariablePayload): void;
     /** Surface a diagnostic message in the editor console. */
     publishNotice(level: GameNoticePayload['level'], message: string): void;
@@ -2561,6 +2663,17 @@ export declare class GameBridge {
     queueEntityRemoved(uuids: string[]): void;
     /** RAF-coalesced thumbnail stream; merged by uuid per frame. */
     queueThumbnails(thumbnails: EntityThumbnailPayload[]): void;
+    /** Publish the placeable entity types the editor's Add palette offers. */
+    publishCatalog(entities: EntityTypeDescriptor[]): void;
+    /**
+     * Publish a committed, invertible change for the editor's undo stack.
+     *
+     * Sent rather than queued: coalescing merges same-type payloads within a
+     * frame, which would fuse two operations into one and lose an undo step.
+     */
+    publishSceneOperation(op: SceneOperationPayload): void;
+    /** Whether an editor is tracking scene operations for undo. */
+    wantsSceneOperations(): boolean;
 }
 
 /**
@@ -2583,6 +2696,10 @@ export declare interface GameBridgeHost {
     resolveEntity(uuid: string): GameEntity<any> | null;
     /** Write a stage variable (editor `stage:variable:set`). */
     setStageVariable?(key: string, value: unknown): void;
+    /** Spawn a catalog entity into the current stage (editor `entity:create`). */
+    createEntity?(typeId: string, props: Record<string, unknown> | undefined, pose: BridgePose | undefined): void;
+    /** Undo or redo a committed scene operation (`scene:operation:apply`). */
+    applySceneOperation?(op: SceneOperationPayload, direction: 'undo' | 'redo'): void;
 }
 
 /**
@@ -2845,6 +2962,18 @@ export declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O>
     physicsWorldRef: unknown;
     colliderDesc: SimulationColliderDefinition | undefined;
     custom: Record<string, any>;
+    /**
+     * Pristine collider definitions captured before the first scale change, so
+     * scaling stays absolute rather than compounding. See
+     * {@link ensureColliderBaseline}.
+     */
+    colliderBaseline: SimulationColliderDefinition[] | null;
+    /**
+     * Set when {@link GameEntity.setScale} has scaled the render object but the
+     * colliders have not been rebuilt yet. Cleared by
+     * {@link commitColliderScale}.
+     */
+    colliderScaleDirty: boolean;
     /** All collider descriptions for this entity (including primary) */
     colliderDescs: SimulationColliderDefinition[];
     /** Additional meshes for compound visual entities (added via add()) */
@@ -2884,6 +3013,8 @@ export declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O>
     private trackAddedComponents;
     private trackedComponents;
     transformStore: TransformState;
+    /** Absolute scale, authored by the editor. Unit scale until changed. */
+    private _scale;
     /** Hide render target until spawn placement is confirmed. */
     _spawnPlacementPending: boolean;
     /** Author passed `position` in create options. */
@@ -2955,6 +3086,17 @@ export declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O>
             w: number;
         };
     }): boolean;
+    /** Current absolute scale. */
+    getScale(): Vec3;
+    /**
+     * Set absolute scale on the render object.
+     *
+     * Colliders are *not* resized here — they are baked into the wasm
+     * simulation and can only be replaced by respawning the body, which is far
+     * too costly to do per drag frame. The entity is flagged instead, and
+     * {@link commitColliderScale} rebuilds them once the gesture commits.
+     */
+    setScale(x: number, y: number, z: number): void;
     /**
      * Add meshes, collision components, or child entities to this entity.
      * Supports fluent chaining: `entity.add(boxMesh()).add(boxCollision())`.
@@ -3383,6 +3525,12 @@ export declare function getSelectedEntity(): GameEntity<any> | null;
 
 export declare function getSelectedEntityId(): string | null;
 
+/** Every selected uuid, in click order. */
+export declare function getSelectedEntityIds(): string[];
+
+/** Current snap increments. */
+export declare function getSnapSettings(): SnapSettings;
+
 /**
  * Get a variable from an object by path.
  * @example getVariable(stage1, 'totalAngle') // 0.5
@@ -3394,6 +3542,30 @@ export { getVelocity }
 
 export { getZylemBridge }
 
+/** Single-axis, planar, and uniform handle identifiers. */
+export declare type GizmoAxis = 'x' | 'y' | 'z' | 'xy' | 'yz' | 'xz' | 'xyz';
+
+/** A raw, unsnapped drag result in world space. */
+export declare type GizmoDelta = {
+    kind: 'translate';
+    offset: Vector3;
+} | {
+    kind: 'rotate';
+    axis: Vector3;
+    angle: number;
+} | {
+    kind: 'scale';
+    factor: Vector3;
+};
+
+export declare type GizmoMode = 'translate' | 'rotate' | 'scale';
+
+/** A mouse ray in world space. */
+export declare interface GizmoRay {
+    origin: Vector3;
+    direction: Vector3;
+}
+
 /**
  * Listen for a single global key change inside an onUpdate pipeline.
  * Usage: onUpdate(globalChange('p1Score', (value) => { ... }))
@@ -3614,6 +3786,14 @@ declare class InstanceManager {
     private growPack;
 }
 
+/**
+ * Intersect a ray with the plane through `origin` with the given normal.
+ *
+ * Returns `null` for a plane seen too close to edge-on, where the hit point
+ * races away across the plane for very little pointer motion.
+ */
+export declare function intersectPlane(ray: GizmoRay, origin: Vector3, normal: Vector3, target: Vector3): Vector3 | null;
+
 /**
  * Check if a shader is a GLSL shader
  */
@@ -3631,6 +3811,8 @@ declare interface IStage {
     onDestroy: (callback: DestroyFunction<IStage>) => void;
 }
 
+export declare function isTransformTool(tool: DebugTools): tool is TransformTool;
+
 /**
  * Check if a shader is a TSL shader
  */
@@ -4460,6 +4642,26 @@ declare interface PyramidMeshOptions extends BaseMeshOptions {
 
 declare type PyramidOptions = BaseNode | Partial<ZylemPyramidOptions>;
 
+/**
+ * Pure transform math shared by the editor gizmo, the bridge adapter, and
+ * their tests. No THREE scene state and no simulation access, so it can be
+ * exercised in a plain node environment.
+ */
+
+/** Quaternion as carried by the bridge and the wasm runtime. */
+export declare interface Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+
+/** Convert a quaternion to Euler angles (radians, XYZ order). */
+export declare function quaternionToEuler(rotation: Quat): Vec3;
+
+/** Radians to degrees. */
+export declare function radiansToDegrees(radians: number): number;
+
 export declare const RECT_TYPE: unique symbol;
 
 declare type RectOptions = BaseNode | Partial<ZylemRectOptions>;
@@ -5155,6 +5357,9 @@ export { SemanticParticlePresetOptions }
  */
 export declare function sequence(...actions: Action[]): Action;
 
+/** Arm the add tool with a catalog type, or pass `null` to disarm it. */
+export declare function setAddType(typeId: string | null, props?: Record<string, unknown> | null): void;
+
 /**
  * Display a camera's live feed on an entity's mesh surface.
  *
@@ -5194,6 +5399,8 @@ export declare function setDebugTool(tool: DebugTools): void;
  */
 export declare function setGlobal(path: string, value: unknown): void;
 
+export declare function setGridVisible(visible: boolean): void;
+
 export declare function setHoveredEntityId(uuid: string | null): void;
 
 export declare function setPaused(paused: boolean): void;
@@ -5254,6 +5461,15 @@ export declare function setSelectedEntity(entity: GameEntity<any> | string | nul
 
 export declare function setSelectedEntityId(uuid: string | null): void;
 
+/**
+ * Replace the selection. `selectedEntityId` follows the first entry so the
+ * single-select consumers (debug cursor, orbit focus target, bridge mirror)
+ * keep working unchanged.
+ */
+export declare function setSelectedEntityIds(uuids: string[]): void;
+
+export declare function setSnapSettings(snap: Partial<SnapSettings>): void;
+
 export declare function setStageFrameProfilerEnabled(value: boolean): void;
 
 /** Setup */
@@ -5338,8 +5554,16 @@ export declare class SimulationBody implements PhysicsRenderPoseProvider {
      */
     private interpolationValidAfterStep;
     constructor(simulation: Simulation, handle: EntityHandle, clock: SimulationStepClock);
-    /** Suppress interpolation until the render buffers catch up. */
-    private markPoseDiscontinuity;
+    /**
+     * Suppress interpolation until the render buffers catch up.
+     *
+     * Called automatically by the pose setters below. Wasm-side behaviors that
+     * teleport a body during a step (e.g. `screen_wrap`) bypass those setters,
+     * so their host systems must call this after the step and before render
+     * poses are synced — otherwise the render buffers straddle the teleport and
+     * the body is drawn sweeping between the two poses.
+     */
+    markPoseDiscontinuity(): void;
     private isInterpolationStale;
     translation(): PhysicsVector3;
     rotation(): PhysicsQuaternion;
@@ -5431,6 +5655,36 @@ export { sin }
 
 export { smoothstep }
 
+/**
+ * Snap a scale, clamped away from zero.
+ *
+ * A snapped-to-zero axis would collapse the collider into a degenerate shape
+ * that the physics runtime cannot solve, so the smallest representable scale
+ * is one increment.
+ */
+export declare function snapScale(value: Vec3, increment: number): Vec3;
+
+/** Grid increments applied to gizmo drags, in world units and radians. */
+export declare interface SnapSettings {
+    enabled: boolean;
+    translate: number;
+    /** Radians. Defaults to 15 degrees. */
+    rotate: number;
+    scale: number;
+}
+
+/**
+ * Snap a value onto an absolute lattice of `increment`-sized steps.
+ *
+ * Absolute rather than relative to where the drag started: the result is
+ * always a multiple of the increment, so independently placed entities line up
+ * with each other instead of each keeping its own arbitrary offset.
+ */
+export declare function snapToIncrement(value: number, increment: number): number;
+
+/** {@link snapToIncrement} across all three components. */
+export declare function snapVec3(value: Vec3, increment: number): Vec3;
+
 export declare const SPHERE_TYPE: unique symbol;
 
 /**
@@ -5497,6 +5751,21 @@ export declare type SpriteImage = {
 
 declare type SpriteOptions = BaseNode | Partial<ZylemSpriteOptions>;
 
+/**
+ * A single texture divided into a uniform grid of frames, addressed by UV
+ * offset. Prefer this over {@link SpriteImage} lists for character sheets: one
+ * texture and one draw call instead of one per frame.
+ */
+export declare type SpriteSheet = {
+    file: string;
+    columns: number;
+    rows: number;
+    /** Frame names in row-major order. `null` marks an unused cell. */
+    frames: Array<string | null>;
+    /** Texture filtering. Defaults to `nearest`, which keeps pixel art crisp. */
+    filter?: 'nearest' | 'linear';
+};
+
 declare class Stage {
     wrappedStage: ZylemStage | null;
     options: StageOptionItem[];
@@ -5678,10 +5947,10 @@ declare class StageDebugDelegate {
     private options;
     private mouseNdc;
     private raycaster;
-    private isMouseDown;
     private domDisposeFns;
     private domListenersAttached;
     private debugCursor;
+    private placementGhost;
     private debugLines;
     private cameraDebugDelegate;
     private debugStateUnsubscribe;
@@ -5689,6 +5958,11 @@ declare class StageDebugDelegate {
     private entityResolverUnregister;
     private lastDebugEnabled;
     private warnedMissingAddFactory;
+    private transformTool;
+    private grid;
+    private lastTool;
+    /** Element the current gizmo drag captured, so pointerup is never missed. */
+    private capturedPointer;
     constructor(stage: ZylemStage, options?: StageDebugDelegateOptions);
     /**
      * Supply the factory the `add` tool uses to spawn entities at the clicked
@@ -5708,18 +5982,107 @@ declare class StageDebugDelegate {
      * rebuild the render pipeline once per frame.
      */
     private syncWithDebugState;
+    /** Hand the transform tool its mode whenever the active tool changes. */
+    private syncToolMode;
+    private syncGrid;
     /** Initialize DOM listeners and switch rendering to the debug orbit camera. */
     private activate;
     /** Tear down visuals and restore the gameplay primary camera. */
     private deactivate;
     private rebindPostProcessing;
+    /**
+     * Collider wireframes: the one overlay that really is debug-mode-only, since
+     * it draws the simulation itself rather than anything being edited.
+     */
     private initDebugVisuals;
     private disposeDebugVisuals;
+    /**
+     * Tool feedback, built on first use and kept for the delegate's life.
+     *
+     * Separate from {@link initDebugVisuals} because the hover highlight and the
+     * placement ghost belong to the tools, not to debug mode: they have to be
+     * available when a tool is armed with debug off.
+     */
+    private ensureToolVisuals;
+    /**
+     * Hide the overlays whose tool has just gone away.
+     *
+     * `update()` normally does this, but it stops being called once nothing is
+     * armed and debug is off — so the frame that would have hidden a disarmed
+     * Add's ghost never arrives, and the preview is left floating in the scene.
+     * Driven from the tool transition, which always fires.
+     */
+    private parkToolVisuals;
+    private disposeToolVisuals;
     update(): void;
+    /** Collider wireframes, straight from the wasm simulation. */
+    private updateColliderWireframes;
+    /**
+     * Make sure an armed tool can actually receive the pointer.
+     *
+     * The listeners outlive debug mode once attached — `deactivate()` leaves them
+     * in place and only `dispose()` removes them — so this only ever has to run
+     * until it succeeds.
+     */
+    private ensureInteraction;
+    /**
+     * Drive the translucent preview of the armed entity type from the cursor.
+     *
+     * Runs while the game is paused as well as while it plays: only the
+     * fixed-step `step()` is pause-gated, so this pass still ticks and the
+     * ghost keeps following the mouse in a frozen scene — which is exactly when
+     * a scene is usually being built. It runs with debug mode off too, for the
+     * same reason: arming Add is a request to place something, not to inspect
+     * colliders.
+     *
+     * The ghost is a scene overlay, not an entity, so it is invisible to the
+     * physics raycast here and cannot preview itself.
+     */
+    private updatePlacementGhost;
     /** Full teardown — unsubscribes from debugState and cleans up all resources. */
     dispose(): void;
-    private handleActionOnHit;
+    /**
+     * Undo or redo a committed operation.
+     *
+     * The editor holds the history but cannot apply it: reverting a delete means
+     * producing the original entity, which only the stage can do. So the editor
+     * hands the record back and the inversion happens here.
+     */
+    applySceneOperation(op: SceneOperationPayload, direction: 'undo' | 'redo'): void;
+    /** The mouse ray in world space, from the last pointer position. */
+    private currentRay;
+    private handleAction;
+    /**
+     * Spawn the armed entity type at the clicked point.
+     *
+     * Placement resolves in two steps because a click into empty sky is the
+     * common case when building a scene from nothing: the physics hit is
+     * preferred (the entity rests on the surface it was dropped onto), and
+     * otherwise the ray is intersected with the y=0 construction plane. Before
+     * this, clicking anywhere without an existing collider under the cursor did
+     * nothing at all.
+     */
+    private placeEntity;
+    /**
+     * Nudge a freshly placed entity out along the surface normal by half its
+     * own size, so it sits on the surface rather than half-buried in it.
+     *
+     * Runs after spawn because the entity's bounds are not known until its mesh
+     * exists.
+     */
+    private restOnSurface;
+    private warnMissingAddSource;
     private attachDomListeners;
+    /**
+     * Own the pointer for the duration of a gizmo drag.
+     *
+     * Capture keeps events coming even when the cursor leaves the canvas, which
+     * happens constantly when dragging an axis toward the edge of the viewport.
+     * Orbit is suspended for the same window so the drag does not also swing the
+     * camera.
+     */
+    private beginPointerCapture;
+    private endPointerCapture;
 }
 
 declare interface StageDebugDelegateOptions {
@@ -5762,6 +6125,11 @@ declare class StageEntityDelegate {
     readonly childrenMap: Map<string, BaseNode>;
     /** UUID → BaseNode map populated when debug mode is active. */
     readonly debugMap: Map<string, BaseNode>;
+    /**
+     * Entities detached from the stage but kept alive so an editor undo can put
+     * them back. See {@link StageEntityDelegate.detachEntity}.
+     */
+    readonly detachedMap: Map<string, DetachedEntity>;
     private pendingEntities;
     private pendingPromises;
     private _isLoaded;
@@ -5811,10 +6179,48 @@ declare class StageEntityDelegate {
     /** Add the entity to internal maps and notify listeners. */
     addEntityToStage(entity: BaseNode): void;
     /**
-     * Remove an entity and its resources by its UUID.
+     * Remove an entity from the stage by its UUID.
+     *
+     * Detaches rather than destroys, so an editor undo can put the same
+     * instance back. See {@link StageEntityDelegate.detachEntity}.
+     *
      * @returns true if removed, false if not found or stage not ready
      */
     removeEntityByUuid(uuid: string): boolean;
+    /**
+     * Take an entity out of the stage while keeping the instance alive.
+     *
+     * The editor cannot rebuild an entity — all it ever receives is a summary of
+     * name, type, and transform, with no material, behaviors, or collider
+     * config. So undoing a delete has to restore the original object, which
+     * means holding onto it here. Keeping the same instance also keeps its uuid
+     * stable, which every other entry in the undo stack depends on.
+     *
+     * Observers are still told the entity is gone: from the outside it has left
+     * the stage, and leaving it in the editor's list or the thumbnail cache
+     * would leak.
+     *
+     * @returns true when the entity was found and detached.
+     */
+    detachEntity(uuid: string): boolean;
+    /**
+     * Put a detached entity back into the stage at the pose it left.
+     *
+     * Unlike {@link StageEntityDelegate.spawnEntity} this never calls
+     * `create()`: the entity is already fully built, and rebuilding it would
+     * discard its meshes and colliders along with any editor scale applied to
+     * them.
+     *
+     * @returns true when the entity was found and restored.
+     */
+    restoreEntity(uuid: string): boolean;
+    /** Whether a uuid is currently recoverable via {@link restoreEntity}. */
+    isDetached(uuid: string): boolean;
+    /**
+     * Destroy detached entities past the recoverable window. Insertion-ordered,
+     * so the oldest detachments go first.
+     */
+    private evictOldestDetached;
     /** Get an entity by its name; returns null if not found. */
     getEntityByName(name: string): BaseNode | null;
     /** Build a serializable state snapshot for an entity. */
@@ -6532,6 +6938,9 @@ export declare const touchThemes: {
     readonly lagoon: TouchTheme;
 };
 
+/** Tools that manipulate a selected entity's transform via the gizmo. */
+export declare const TRANSFORM_TOOLS: readonly ["translate", "rotate", "scale"];
+
 /**
  * Structural slice of the simulation body facade used to flush transform
  * intents. `SimulationBody` satisfies this shape.
@@ -6589,6 +6998,91 @@ declare interface TransformableEntity {
 
 export { TransformComponent }
 
+export declare class TransformGizmo {
+    /** Root added to the scene; carries the pivot transform. */
+    readonly root: Group<three.Object3DEventMap>;
+    private scene;
+    private modeGroups;
+    private handles;
+    private materials;
+    private geometries;
+    private mode;
+    private highlighted;
+    private drag;
+    private raycaster;
+    constructor();
+    addTo(scene: Scene): void;
+    removeFromScene(): void;
+    dispose(): void;
+    setMode(mode: GizmoMode): void;
+    getMode(): GizmoMode;
+    /** Place the gizmo at a pivot and show it. */
+    show(pivot: Vector3): void;
+    hide(): void;
+    get visible(): boolean;
+    get pivot(): Vector3;
+    /**
+     * Keep the gizmo a constant size on screen.
+     *
+     * A world-sized gizmo is unusable in an orbit view: it fills the screen up
+     * close and disappears from a distance.
+     */
+    update(camera: Camera): void;
+    /**
+     * Which handle a ray hits, or `null`.
+     *
+     * Raycasts the gizmo's own meshes rather than the physics world. Handles are
+     * render-only objects with no colliders, so the physics raycast used to pick
+     * entities cannot see them at all.
+     */
+    pick(ray: GizmoRay): GizmoAxis | null;
+    /**
+     * Whether a handle can be dragged from the current viewing angle.
+     *
+     * Each handle type degenerates differently: an arrow aimed at the camera has
+     * no screen-space direction left to follow, while a plane quad or rotation
+     * ring seen edge-on turns a pixel of motion into a huge sweep across it.
+     */
+    private isHandleDraggable;
+    /** Tint a handle to show it is hovered or being dragged. */
+    setHighlight(axis: GizmoAxis | null): void;
+    /**
+     * Begin a drag on a handle.
+     *
+     * @returns `false` when the gesture cannot be tracked (a near-parallel view
+     * of the drag axis), so the caller can ignore the press rather than start a
+     * drag that would jump.
+     */
+    beginDrag(axis: GizmoAxis, ray: GizmoRay, camera: Camera): boolean;
+    /** Raw delta for the current pointer position, or `null` when unusable. */
+    updateDrag(ray: GizmoRay, camera: Camera): GizmoDelta | null;
+    endDrag(): void;
+    get isDragging(): boolean;
+    get draggingAxis(): GizmoAxis | null;
+    private isPlaneAxis;
+    /** Signed angle of the ray's hit point around `normal`, in radians. */
+    private angleOnPlane;
+    /** Distance from pivot to the ray hit on the camera-facing plane. */
+    private cameraPlaneRadius;
+    private applyModeVisibility;
+    private makeMaterial;
+    private track;
+    /**
+     * An invisible, generously sized mesh used only for hit testing.
+     *
+     * The visible shafts and rings are a couple of pixels wide, which is
+     * miserable to click. The raycaster still reaches `visible: false` meshes,
+     * so picking accuracy is decoupled from how thin the handle looks.
+     */
+    private makePicker;
+    private orientAlongAxis;
+    private buildTranslate;
+    private positionPlaneHandle;
+    private buildRotate;
+    private orientRing;
+    private buildScale;
+}
+
 /**
  * Minimal transform representation for pipeline targets.
  */
@@ -6599,6 +7093,8 @@ export declare interface TransformLike {
 
 export { TransformState }
 
+export declare type TransformTool = (typeof TRANSFORM_TOOLS)[number];
+
 export { uniform }
 
 export { updateBoundaryRicochet }
@@ -7394,6 +7890,17 @@ declare class ZylemCamera {
      * Frame the debug orbit camera on an Object3D (AABB fit).
      */
     frameObject(object: Object3D): void;
+    /**
+     * Suspend or resume orbit input. Used by the debug transform tools so a
+     * gizmo drag does not also swing the camera.
+     */
+    setOrbitInteractionEnabled(enabled: boolean): void;
+    /**
+     * Stop or resume tracking the debug selection with the orbit target. Used by
+     * the transform tools, which cannot be dragged accurately while the camera
+     * re-aims at the entity being moved.
+     */
+    setOrbitFollowEnabled(enabled: boolean): void;
     /**
      * Directly set the camera position.
      */
@@ -7728,6 +8235,8 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
     private lastPublishedGameConfig;
     /** Editor ↔ game bridge adapter (RAF-coalesced publishes, command intake). */
     private gameBridge;
+    /** Stops republishing the entity catalog on registry changes. */
+    private catalogUnsubscribe;
     private readonly gameUpdateParams;
     private readonly stageSetupParams;
     private readonly stageUpdateParams;
@@ -7738,6 +8247,10 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
     static FRAME_DURATION: number;
     static MAX_DELTA_SECONDS: number;
     constructor(options: ZylemGameOptions<TGlobals>, wrapperRef: Game<TGlobals>, displayRuntime?: ResolveGameConfigRuntime);
+    /** Publish the placeable entity types the editor's Add palette lists. */
+    private publishEntityCatalog;
+    /** Spawn a catalog type programmatically (editor `entity:create`). */
+    private createCatalogEntity;
     setDisplayRuntime(runtime: ResolveGameConfigRuntime): void;
     loadGameCanvas(config: GameConfig): void;
     loadDebugOptions(options: ZylemGameOptions<TGlobals>): void;
@@ -8255,15 +8768,34 @@ export declare class ZylemSprite extends GameEntity<ZylemSpriteOptions> {
     protected spriteMap: Map<string, number>;
     protected currentSpriteIndex: number;
     protected animations: Map<string, any>;
-    protected currentAnimation: any;
+    protected currentAnimation: string | null;
     protected currentAnimationFrame: string;
     protected currentAnimationIndex: number;
     protected currentAnimationTime: number;
+    /** Set only in sheet mode; the shared texture whose UV window we shift. */
+    protected sheetTexture: Texture | null;
+    protected flippedX: boolean;
     constructor(options?: ZylemSpriteOptions);
     create(): this;
     protected createSpritesFromImages(images: SpriteImage[]): void;
+    protected createSpriteFromSheet(sheet: SpriteSheet): void;
     protected createAnimations(animations: SpriteAnimation[]): void;
     setSprite(key: string): void;
+    /**
+     * Mirror the sprite horizontally, for characters whose sheet only contains
+     * one facing direction.
+     *
+     * In sheet mode this flips the UV window rather than the sprite scale,
+     * because {@link syncSpriteMaterials} rewrites scale from `options.size`
+     * every frame and would immediately undo a negative scale.
+     */
+    setFlipX(flip: boolean): void;
+    isFlippedX(): boolean;
+    private applySheetFrame;
+    /**
+     * Advance a named clip. Call once per frame from an update loop; `delta` is
+     * seconds, so scaling it scales playback rate.
+     */
     setAnimation(name: string, delta: number): void;
     private getCurrentRotationQuaternion;
     private syncSpriteMaterials;
@@ -8275,6 +8807,7 @@ export declare class ZylemSprite extends GameEntity<ZylemSpriteOptions> {
 
 declare type ZylemSpriteOptions = GameEntityOptions & {
     images?: SpriteImage[];
+    sheet?: SpriteSheet;
     animations?: SpriteAnimation[];
     size?: Vec3Input;
     collisionSize?: Vec3Input;
@@ -8342,7 +8875,7 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     protected _setup(params: SetupContext<ZylemStage>): void;
     protected _update(params: UpdateContext<ZylemStage>): void;
     outOfLoop(): void;
-    /** Update debug overlays and helpers if enabled. */
+    /** Update debug overlays and the editor's pointer tools. */
     debugUpdate(): void;
     /** Cleanup owned resources when the stage is destroyed. */
     protected _destroy(params: DestroyContext<ZylemStage>): void;