@zylem/editor 0.8.8 → 0.9.2

package/dist/zylem-editor.d.ts

@@ -1,23 +1,25 @@
 import * as _zylem_bridge from '@zylem/bridge';
-import { BridgePose, BridgeVec3, BridgeQuat, SnapSettingsPayload, BridgeDebugTool, SceneOperationPayload, EntityTypeDescriptor } from '@zylem/bridge';
+import { CameraViewPreset, BridgePose, EntitySelectMode, BridgeVec3, BridgeQuat, LevelBuffer, SnapSettingsPayload, BridgeDebugTool, SceneOperationPayload, EntityTypeDescriptor } from '@zylem/bridge';
 import { LucideProps } from 'lucide-solid';
 import { Component } from 'solid-js';
 
-declare const channel: _zylem_bridge.BridgeChannel;
 /**
- * Subscribe the editor stores to game→editor bridge messages and hydrate
- * from the channel's retained state.
+ * The editor's handle on the shared editor ↔ game bridge channel.
  *
- * Reference-counted: the game gates expensive editor-only work (thumbnails,
- * entity summaries) on these subscriptions existing, so the last editor to
- * unmount must actually release them, while any editor still mounted must
- * keep them alive.
+ * Owned here, and only here, so the game→editor sync modules, the
+ * editor→game commands, and stores such as `history-store` can all reach the
+ * same singleton without importing each other.
+ */
+declare const channel: _zylem_bridge.BridgeChannel;
+
+/**
+ * Editor → game commands.
  *
- * @returns A release function; safe to call more than once.
+ * Thin, typed wrappers over `channel.send` so UI code never has to spell out
+ * message names or payload shapes, and has no runtime dependency on game-lib
+ * internals.
  */
-declare function connectEditorBridge(): () => void;
-/** Tear down all bridge subscriptions, ignoring the reference count. */
-declare function disconnectEditorBridge(): void;
+
 /** Toggle the game's debug mode. */
 declare function sendDebugEnabled(enabled: boolean): void;
 /** Switch the active editor tool in the game. */
@@ -26,6 +28,12 @@ declare function sendTool(tool: BridgeDebugTool): void;
 declare function sendPlayback(paused: boolean): void;
 /** Select an entity in the game (null clears the selection). */
 declare function sendEntitySelect(uuid: string | null): void;
+/**
+ * Replace, extend, reduce, or toggle the game's selection with several
+ * entities at once. `uuid` mirrors the first entry for single-select
+ * consumers.
+ */
+declare function sendEntitySelectMany(uuids: string[], mode?: EntitySelectMode): void;
 /** Focus/frame the game debug camera on an entity. */
 declare function sendEntityFocus(uuid: string): void;
 /** Write a stage variable in the running game. */
@@ -44,6 +52,8 @@ declare function sendEntityTransform(uuid: string, transform: {
 }): void;
 /** Arm the game's add tool with a catalog type, or `null` to disarm it. */
 declare function sendAddType(typeId: string | null, props?: Record<string, unknown>): void;
+/** Stream a recorded level into the running stage. */
+declare function sendLevelLoad(buffer: LevelBuffer): void;
 /** Spawn a catalog entity without a placement click. */
 declare function sendEntityCreate(typeId: string, options?: {
     props?: Record<string, unknown>;
@@ -53,6 +63,30 @@ declare function sendEntityCreate(typeId: string, options?: {
 declare function sendSnapSettings(snap: SnapSettingsPayload): void;
 /** Show or hide the game's construction-plane grid. */
 declare function sendGridVisible(visible: boolean): void;
+/** Lock the game's debug orbit camera to a view preset. */
+declare function sendCameraView(preset: CameraViewPreset): void;
+
+/**
+ * Connection lifecycle for the editor side of the bridge.
+ *
+ * Subscribes the game→editor sync modules to the channel and hydrates from
+ * `channel.getState()` on connect, so an editor mounted after the game started
+ * shows current config/entities immediately.
+ */
+/**
+ * Subscribe the editor stores to game→editor bridge messages and hydrate
+ * from the channel's retained state.
+ *
+ * Reference-counted: the game gates expensive editor-only work (thumbnails,
+ * entity summaries) on these subscriptions existing, so the last editor to
+ * unmount must actually release them, while any editor still mounted must
+ * keep them alive.
+ *
+ * @returns A release function; safe to call more than once.
+ */
+declare function connectEditorBridge(): () => void;
+/** Tear down all bridge subscriptions, ignoring the reference count. */
+declare function disconnectEditorBridge(): void;
 
 /**
  * Shared types for the editor store.
@@ -135,6 +169,11 @@ interface DockRect {
     height: number;
 }
 declare const DOCK_SIDES: readonly DockSide[];
+/**
+ * The toolbar window. When it is the only panel on its edge it takes that
+ * whole edge, and every other dock lays out in the space left over.
+ */
+declare const TOOLBAR_PANEL_ID = "toolbar";
 declare const findDockedSide: (registry: DockRegistry, panelId: DockPanelId) => DockSide | null;
 interface DockLayoutOptions {
     /** Smallest slot extent along a zone's long axis. */
@@ -146,6 +185,11 @@ interface DockLayoutOptions {
  * Left and right zones take the full viewport height and win over top and
  * bottom, which inset horizontally to the space between them. Panels sharing a
  * zone split its long axis evenly.
+ *
+ * The toolbar is the exception when it is alone on its edge: that strip runs
+ * the full length of the edge, and the rules above apply to everyone else
+ * inside the leftover rectangle. Sharing its edge with another panel drops
+ * the exception and the toolbar splits that edge like any other panel.
  */
 declare const computeDockLayout: (registry: DockRegistry, viewport: Viewport, options?: DockLayoutOptions) => Record<DockPanelId, DockRect>;
 
@@ -204,6 +248,7 @@ declare const gameState: GameState;
 
 /** Registry id of the main editor panel; detached sections use their panel id. */
 declare const MAIN_PANEL_ID = "main";
+
 interface DetachedPanelState {
     position: {
         x: number;
@@ -243,6 +288,9 @@ declare const debugStore: {
     panelZOrder: string[];
     docks: DockRegistry;
     dockDefaultsApplied: boolean;
+    toolbarSeeded: boolean;
+    toolbarCollapsed: boolean;
+    mainCollapsed: boolean;
     draggingPanelId: string | null;
     dropTargetIndex: number | null;
 };
@@ -359,6 +407,55 @@ declare function redo(): boolean;
  */
 declare function clearHistory(): void;
 
+/**
+ * Level-editor mode.
+ *
+ * Build mode owns a buffer of catalog placements. Turning it on seeds that
+ * buffer from the stage currently loaded; turning it off freezes the buffer
+ * so later stage changes do not rewrite a level the user has stepped out of.
+ * Turning it on again reseeds.
+ */
+
+/**
+ * How a recorded entry was placed.
+ *
+ * `level` is the only role marked for bake. The editor does not merge meshes;
+ * the game bakes later. `actor` and `doodad` are recorded and left out of that set.
+ */
+type LevelRole = 'actor' | 'level' | 'doodad';
+/** Role and actor props, kept beside `LevelEntry` because the bridge entry has neither. */
+interface LevelAnnotation {
+    role: LevelRole;
+    props: Record<string, string>;
+}
+interface LevelState {
+    active: boolean;
+    /** Present after Build has been turned on at least once. Frozen while inactive. */
+    buffer: LevelBuffer | null;
+    /** Keyed by entry id. Entries that leave the buffer lose their annotation. */
+    annotations: Record<string, LevelAnnotation>;
+    /**
+     * Role stamped on entries that appear while the Add tool is armed.
+     * Cleared when the tool leaves Add, so a later stage update is not mis-tagged.
+     */
+    placementRole: LevelRole | null;
+}
+/** A plain copy of the buffer, safe to post across a frame or write to a file. */
+interface LevelSnapshot {
+    buffer: LevelBuffer;
+    annotations: Record<string, LevelAnnotation>;
+    /** Stage id the buffer was recorded against, when the game has published one. */
+    stageId: string | null;
+}
+declare const levelState: LevelState;
+/**
+ * Copy the recorded level out of the editor.
+ *
+ * `null` when Build has never been turned on. A buffer frozen by leaving Build
+ * mode is still returned. The copy is plain data, not the live proxy.
+ */
+declare function snapshotLevelBuffer(): LevelSnapshot | null;
+
 /**
  * Stage export.
  *
@@ -437,6 +534,176 @@ declare function setArmedType(typeId: string | null): void;
 /** Drop the armed placement type and return to the neutral tool. */
 declare function disarmTools(): boolean;
 
+/**
+ * What each toolbar button does when pressed, as plain functions.
+ *
+ * Kept out of the components so the keyboard shortcuts run the same code. Where
+ * a key and its button differ — the tool keys select, the tool buttons toggle —
+ * both variants live here over one shared primitive, so the two cannot drift.
+ * The components keep the reactive reads that drive `selected` and `disabled`,
+ * and call in here on click.
+ *
+ * Everything reads the valtio proxies rather than their Solid mirrors. These run
+ * outside any tracking scope — from a `keydown` on `window` as often as from a
+ * click — and the mirrors lag the proxies by a microtask.
+ */
+
+type TransformTool = Extract<DebugTools, 'translate' | 'rotate' | 'scale'>;
+type ClickTool = Extract<DebugTools, 'select' | 'delete'>;
+/** Debug mode on or off, in the editor and the game. */
+declare function toggleDebug(): void;
+/**
+ * Make a click tool the active one. Pressing the key of the tool already active
+ * keeps it, so the keyboard behaves like a row of radio buttons; Escape is the
+ * way out.
+ */
+declare function selectTool(tool: ClickTool): void;
+/** Toggle a click tool from its button: a second press returns to the neutral tool. */
+declare function toggleTool(tool: ClickTool): void;
+/**
+ * Enter a gizmo mode from its key. Pressing the key of the mode already active
+ * keeps it — and still counts as handled, so the keystroke goes nowhere else.
+ */
+declare function selectTransformTool(tool: TransformTool): boolean;
+/** Toggle a gizmo mode from its button: a second press returns to the neutral tool. */
+declare function toggleTransformTool(tool: TransformTool): boolean;
+/**
+ * Arm placement with a catalog type and the role those new entries are tagged
+ * with. Arming an armed tool leaves it armed — Escape is the way out — so
+ * placing ten of something is one arm and ten clicks.
+ *
+ * @returns `false` when the catalog has no such type.
+ */
+declare function armAddType(typeId: string, role?: LevelRole): boolean;
+/**
+ * Arm placement with what the Add button's face shows.
+ *
+ * @returns `false` on an empty catalog, the one state with nothing to arm.
+ */
+declare function armAddTool(role?: LevelRole): boolean;
+/** Open the Add palette, if a toolbar is showing one. */
+declare function openAddPalette(): boolean;
+declare function toggleSnap(): void;
+declare function toggleGrid(): void;
+/** Pause or resume the simulation, in the editor and the game. */
+declare function togglePlayback(): void;
+
+/**
+ * Keyboard shortcuts for the toolbar.
+ *
+ * The tool row follows the Godot/Unreal layout — Q select, W move, E rotate,
+ * R scale — with mnemonics for the rest: A add, B build, X delete, D debug,
+ * S snap, G grid. Every key sits under the left hand on a QWERTY board, so
+ * the right hand can stay on the mouse.
+ *
+ * The keys are live whenever the editor panel is open, playing or paused: the
+ * panel being up is the signal that the keyboard is addressing the editor. The
+ * same letters are gameplay input — game-lib's keyboard provider listens on the
+ * same `window`, maps `a`, `s`, `q`, `e`, `x`, `z` and `Enter` for its default
+ * pad, and pays no attention to `preventDefault` — so while the panel is open
+ * the shortcuts are stopped here, in the capture phase, before any other
+ * listener sees them. Close the panel and the keys are the game's again.
+ *
+ * Undo and redo keep Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z from `history-shortcuts`,
+ * behind their own option; they are listed here so the tooltips can show them.
+ */
+interface ShortcutChord {
+    /** `KeyboardEvent.key`, matched case-insensitively so Caps Lock changes nothing. */
+    key: string;
+    shift?: boolean;
+    /** Cmd on macOS, Ctrl elsewhere; either is accepted. */
+    mod?: boolean;
+}
+/** Every toolbar action's chord, keyed by the button it belongs to. */
+declare const TOOLBAR_SHORTCUTS: {
+    readonly debug: {
+        readonly key: "d";
+    };
+    readonly build: {
+        readonly key: "b";
+    };
+    readonly select: {
+        readonly key: "q";
+    };
+    readonly translate: {
+        readonly key: "w";
+    };
+    readonly rotate: {
+        readonly key: "e";
+    };
+    readonly scale: {
+        readonly key: "r";
+    };
+    readonly add: {
+        readonly key: "a";
+    };
+    readonly addPalette: {
+        readonly key: "a";
+        readonly shift: true;
+    };
+    readonly delete: {
+        readonly key: "x";
+    };
+    readonly snap: {
+        readonly key: "s";
+    };
+    readonly grid: {
+        readonly key: "g";
+    };
+    readonly undo: {
+        readonly key: "z";
+        readonly mod: true;
+    };
+    readonly redo: {
+        readonly key: "z";
+        readonly mod: true;
+        readonly shift: true;
+    };
+    readonly playback: {
+        readonly key: "Enter";
+        readonly mod: true;
+    };
+};
+type ToolbarShortcutId = keyof typeof TOOLBAR_SHORTCUTS;
+/** The shortcuts this module runs; undo and redo are `history-shortcuts`'. */
+declare const TOOLBAR_ACTIONS: readonly ["debug", "build", "select", "translate", "rotate", "scale", "add", "addPalette", "delete", "snap", "grid", "playback"];
+type ToolbarAction = (typeof TOOLBAR_ACTIONS)[number];
+/**
+ * A chord as tooltip text: `W`, `Shift+A`, `Cmd+Enter`.
+ *
+ * Words rather than ⌘ and ⇧, because the toolbar buttons use one string for
+ * both the tooltip and the accessible name.
+ */
+declare function formatShortcut(chord: ShortcutChord, apple?: boolean): string;
+/**
+ * Run the action a shortcut stands for.
+ *
+ * The tool keys select rather than toggle: W in Move stays in Move, and Escape
+ * is the way out. The buttons keep their toggle, since a lit button is its own
+ * "press again to leave" affordance. Everything else is a toggle by nature.
+ *
+ * @returns Whether anything happened. `false` mirrors a disabled button: Move
+ * with nothing to move, Add with an empty catalog, the palette with no toolbar.
+ */
+declare function runToolbarAction(action: ToolbarAction): boolean;
+interface ToolbarShortcutOptions {
+    /** @default true */
+    enabled?: boolean;
+    /**
+     * Whether the keys belong to the editor right now — the web component passes
+     * "the panel is open". Read per keystroke, so it can follow UI state.
+     * @default always
+     */
+    isActive?: () => boolean;
+    target?: Window;
+}
+/**
+ * Install the toolbar shortcuts.
+ *
+ * @returns An uninstall function.
+ */
+declare function installToolbarShortcuts(options?: ToolbarShortcutOptions): () => void;
+
 /**
  * Keeps the gizmo modes from outliving the selection they act on.
  *
@@ -535,6 +802,18 @@ interface ZylemEditorConfig {
      * @default true
      */
     enableEscapeShortcut?: boolean;
+    /**
+     * Whether the toolbar's keys are installed: Q/W/E/R for the tools, A to arm
+     * placement, X for delete, D/S/G for debug, snap and grid, and Cmd/Ctrl+Enter
+     * for play/pause. They are live while the editor panel is open, whether the
+     * simulation is playing or paused, and are stopped before the game's own key
+     * bindings see them; with the panel closed the keys are the game's.
+     *
+     * Disable it to bind the keys yourself; the actions are exported as
+     * `selectTool`, `selectTransformTool`, `togglePlayback` and friends.
+     * @default true
+     */
+    enableToolbarShortcuts?: boolean;
 }
 /**
  * ZylemEditorElement - A web component that wraps the Zylem Editor.
@@ -596,6 +875,8 @@ declare class ZylemEditorElement extends HTMLElement {
     openPanel(): void;
     closePanel(): void;
     togglePanel(): void;
+    /** Whether either editor window is showing. Collapsed counts as showing; closed does not. */
+    isPanelOpen(): boolean;
     /**
      * Dock a panel to a viewport edge, or pass `null` to float it again.
      * Defaults to the main editor panel.
@@ -705,13 +986,14 @@ interface MountZylemEditorOptions extends EditorStateBridgeOptions {
      */
     launcherMode?: EditorLauncherMode;
     /**
-     * Dock layout to seed on first run, keyed by viewport edge. `'main'` is the
-     * editor panel; any other id is a section such as `'console'`. Ignored once
-     * the user has a saved layout.
+     * Dock layout to seed on first run, keyed by viewport edge. `'toolbar'` is
+     * the tool strip, `'main'` is the panel container, and any other id is a
+     * section such as `'console'`. A host that omits the toolbar still gets it
+     * on top. Ignored once the user has a saved layout.
      *
      * @example
      * ```ts
-     * mountZylemEditor({ defaultDocks: { left: ['main'], bottom: ['console'] } });
+     * mountZylemEditor({ defaultDocks: { top: ['toolbar'], left: ['main'] } });
      * ```
      */
     defaultDocks?: EditorDockDefaults;
@@ -756,4 +1038,4 @@ type SceneOperationListener = (op: SceneOperationPayload) => void;
  */
 declare function onSceneOperation(listener: SceneOperationListener): () => void;
 
-export { type CatalogState, DEFAULT_ROTATE_SNAP, DOCK_SIDES, type DockPanelId, type DockRect, type DockRegistry, type DockSide, type DockZoneState, type EditorDockDefaults, type EditorEvent, type EditorEventType, type EditorStateBridge, type EditorStateBridgeOptions, type EditorUpdatePayload, type HistoryState, Icon, MAIN_PANEL_ID, MAX_HISTORY_DEPTH, type MountZylemEditorOptions, type MountedZylemEditor, type SceneOperationListener, type StageExport, type StageExportEntity, type TransformState, type TransformToolGuardOptions, type ZylemEditorConfig, ZylemEditorElement, attachEditorStateBridge, channel as bridgeChannel, buildStageExport, canRedo, canUndo, catalogState, clearHistory, computeDockLayout, connectEditorBridge, copyStageExport, debugState, debugStore, disarmTools, disconnectEditorBridge, dispatchEditorUpdate, dispatchToEditor, dockPanelToSide, editorEvents, findDockedSide, gameState, getDockedSide, historyState, installTransformToolGuard, mountZylemEditor, onSceneOperation, redo, redoLabel, registerZylemEditor, releaseOrphanedTransformTool, sendAddType, sendDebugEnabled, sendEntityCreate, sendEntityFocus, sendEntitySelect, sendEntityTransform, sendGridVisible, sendPlayback, sendSnapSettings, sendStageVariable, sendTool, setArmedType, setEntityCatalog, setGridVisible, setSnapEnabled, setSnapIncrements, stageExportToString, stageState, transformState, undo, undoLabel, undockPanelFromSides };
+export { type CatalogState, type ClickTool, DEFAULT_ROTATE_SNAP, DOCK_SIDES, type DockPanelId, type DockRect, type DockRegistry, type DockSide, type DockZoneState, type EditorDockDefaults, type EditorEvent, type EditorEventType, type EditorStateBridge, type EditorStateBridgeOptions, type EditorUpdatePayload, type HistoryState, Icon, type LevelSnapshot, MAIN_PANEL_ID, MAX_HISTORY_DEPTH, type MountZylemEditorOptions, type MountedZylemEditor, type SceneOperationListener, type ShortcutChord, type StageExport, type StageExportEntity, TOOLBAR_PANEL_ID, TOOLBAR_SHORTCUTS, type ToolbarAction, type ToolbarShortcutId, type ToolbarShortcutOptions, type TransformState, type TransformTool, type TransformToolGuardOptions, type ZylemEditorConfig, ZylemEditorElement, armAddTool, armAddType, attachEditorStateBridge, channel as bridgeChannel, buildStageExport, canRedo, canUndo, catalogState, clearHistory, computeDockLayout, connectEditorBridge, copyStageExport, debugState, debugStore, disarmTools, disconnectEditorBridge, dispatchEditorUpdate, dispatchToEditor, dockPanelToSide, editorEvents, findDockedSide, formatShortcut, gameState, getDockedSide, historyState, installToolbarShortcuts, installTransformToolGuard, levelState, mountZylemEditor, onSceneOperation, openAddPalette, redo, redoLabel, registerZylemEditor, releaseOrphanedTransformTool, runToolbarAction, selectTool, selectTransformTool, sendAddType, sendCameraView, sendDebugEnabled, sendEntityCreate, sendEntityFocus, sendEntitySelect, sendEntitySelectMany, sendEntityTransform, sendGridVisible, sendLevelLoad, sendPlayback, sendSnapSettings, sendStageVariable, sendTool, setArmedType, setEntityCatalog, setGridVisible, setSnapEnabled, setSnapIncrements, snapshotLevelBuffer, stageExportToString, stageState, toggleDebug, toggleGrid, togglePlayback, toggleSnap, toggleTool, toggleTransformTool, transformState, undo, undoLabel, undockPanelFromSides };