@zylem/game-lib 0.8.4 → 0.8.7

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';
@@ -84,10 +85,12 @@ import { EditorToGameMessages } from '@zylem/bridge';
 import { emitRuntimeGoal } from '@zylem/behaviors/runtime-2d';
 import { emitRuntimeRicochet } from '@zylem/behaviors/runtime-2d';
 import { emitRuntimeTriggerRegionEnter } from '@zylem/behaviors/runtime-2d';
+import { EntityApplySwatchPayload } from '@zylem/bridge';
 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 +276,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 +337,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 +428,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 +1225,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 +1361,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 +1763,26 @@ 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;
+    /**
+     * Host-driven hover picking (e.g. Creator swatch drag). Raycasts even when
+     * the Select tool is not armed, and keeps the hover highlight painted.
+     */
+    pickMode: boolean;
     flags: Set<string>;
 }
 
@@ -1731,6 +1790,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 +1851,9 @@ export { defineBehavior }
 
 export { DefineBehaviorConfig }
 
+/** Degrees to radians. */
+export declare function degreesToRadians(degrees: number): number;
+
 /**
  * Wait for a duration. Useful inside `sequence()`.
  *
@@ -1829,6 +1893,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 {
@@ -1872,6 +1952,8 @@ declare interface Entity<T = any> {
     tag?: Set<string>;
 }
 
+export { EntityApplySwatchPayload }
+
 export declare type EntityBlueprint = Static<typeof EntitySchema>;
 
 declare abstract class EntityBuilder<T extends GameEntity<U> & P, U extends GameEntityOptions, P = any> {
@@ -2136,6 +2218,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.
@@ -2518,6 +2603,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.
@@ -2581,6 +2671,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;
 }
 
 /**
@@ -2603,6 +2704,12 @@ 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;
+    /** Attach a catalog shader or behavior to a live entity (`entity:apply-swatch`). */
+    applySwatch?(payload: EntityApplySwatchPayload): void;
 }
 
 /**
@@ -2865,6 +2972,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()) */
@@ -2904,6 +3023,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. */
@@ -2975,6 +3096,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())`.
@@ -3403,6 +3535,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
@@ -3414,6 +3552,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) => { ... }))
@@ -3634,6 +3796,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
  */
@@ -3645,12 +3815,16 @@ export declare function isManagedRenderEntity(entity: {
     isBundled?: boolean;
 }): boolean;
 
+export declare function isPickMode(): boolean;
+
 declare interface IStage {
     onUpdate: (callback: UpdateFunction<IStage>) => void;
     onSetup: (callback: SetupFunction<IStage>) => void;
     onDestroy: (callback: DestroyFunction<IStage>) => void;
 }
 
+export declare function isTransformTool(tool: DebugTools): tool is TransformTool;
+
 /**
  * Check if a shader is a TSL shader
  */
@@ -4480,6 +4654,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>;
@@ -5175,6 +5369,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.
  *
@@ -5214,10 +5411,15 @@ 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;
 
+/** Hosts arm this while forwarding pointer coords for entity hover (no Select tool). */
+export declare function setPickMode(enabled: boolean): void;
+
 export { setPosition }
 
 export { setPositionX }
@@ -5274,6 +5476,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 */
@@ -5459,6 +5670,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;
 
 /**
@@ -5721,10 +5962,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;
@@ -5732,6 +5973,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
@@ -5751,18 +5997,116 @@ 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;
+    /**
+     * Raycast at NDC coordinates (from a host that cannot send DOM pointer
+     * events, e.g. an overlay sitting on a preview iframe). Updates hover so
+     * the next `update()` paints the highlight.
+     */
+    pickAtNdc(ndcX: number, ndcY: number): {
+        uuid: string;
+        name: string;
+    } | null;
+    /** 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 {
@@ -5805,6 +6149,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;
@@ -5854,10 +6203,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. */
@@ -5899,6 +6286,11 @@ declare class StageEntityDelegate {
      */
     destroyAll(): void;
     private registerBehaviorLinks;
+    /**
+     * Re-index an entity's behavior refs after a late `entity.use(...)`.
+     * Spawn-time registration only sees refs that existed at attach.
+     */
+    syncBehaviorLinks(entity: any): void;
     private unregisterBehaviorLinks;
 }
 
@@ -6575,6 +6967,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.
@@ -6632,6 +7027,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.
  */
@@ -6642,6 +7122,8 @@ export declare interface TransformLike {
 
 export { TransformState }
 
+export declare type TransformTool = (typeof TRANSFORM_TOOLS)[number];
+
 export { uniform }
 
 export { updateBoundaryRicochet }
@@ -7437,6 +7919,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.
      */
@@ -7771,6 +8264,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;
@@ -7781,6 +8276,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;
@@ -8405,7 +8904,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;