@zylem/editor 0.8.8 → 0.9.0

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 { BridgePose, EntitySelectMode, BridgeVec3, BridgeQuat, 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. */
@@ -54,6 +62,28 @@ declare function sendSnapSettings(snap: SnapSettingsPayload): void;
 /** Show or hide the game's construction-plane grid. */
 declare function sendGridVisible(visible: boolean): 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.
  * These mirror types from game-lib to avoid direct dependencies.
@@ -437,6 +467,172 @@ 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. 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): 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(): 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, 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 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", "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 +731,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 +804,8 @@ declare class ZylemEditorElement extends HTMLElement {
     openPanel(): void;
     closePanel(): void;
     togglePanel(): void;
+    /** Whether the main panel 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.
@@ -756,4 +966,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, MAIN_PANEL_ID, MAX_HISTORY_DEPTH, type MountZylemEditorOptions, type MountedZylemEditor, type SceneOperationListener, type ShortcutChord, type StageExport, type StageExportEntity, 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, mountZylemEditor, onSceneOperation, openAddPalette, redo, redoLabel, registerZylemEditor, releaseOrphanedTransformTool, runToolbarAction, selectTool, selectTransformTool, sendAddType, sendDebugEnabled, sendEntityCreate, sendEntityFocus, sendEntitySelect, sendEntitySelectMany, sendEntityTransform, sendGridVisible, sendPlayback, sendSnapSettings, sendStageVariable, sendTool, setArmedType, setEntityCatalog, setGridVisible, setSnapEnabled, setSnapIncrements, stageExportToString, stageState, toggleDebug, toggleGrid, togglePlayback, toggleSnap, toggleTool, toggleTransformTool, transformState, undo, undoLabel, undockPanelFromSides };