@zylem/editor 0.6.9 → 0.7.3

package/dist/zylem-editor.d.ts

@@ -1,121 +1,7 @@
 import { Component } from 'solid-js';
 import { LucideProps } from 'lucide-solid';
 import * as _zylem_bridge from '@zylem/bridge';
-import { BridgeDebugTool } from '@zylem/bridge';
-
-type EditorLauncherMode = 'floating' | 'hidden';
-
-/**
- * Configuration options for the ZylemEditorElement
- */
-interface ZylemEditorConfig {
-    /**
-     * External debug state to sync with.
-     * If provided, the editor will use this state instead of its internal state.
-     */
-    debugState?: any;
-    /**
-     * External game state to sync with.
-     */
-    gameState?: any;
-    /**
-     * External stage state to sync with.
-     */
-    stageState?: any;
-    /**
-     * Whether to include default styles.
-     * @default true
-     */
-    includeStyles?: boolean;
-    /**
-     * Controls whether the internal floating launcher is rendered.
-     * @default 'floating'
-     */
-    launcherMode?: EditorLauncherMode;
-}
-/**
- * ZylemEditorElement - A web component that wraps the Zylem Editor.
- *
- * This component is fully self-contained with bundled styles.
- * It can be imported and used in any project without additional CSS configuration.
- *
- * @example
- * ```html
- * <!-- Standalone usage -->
- * <zylem-editor></zylem-editor>
- * ```
- *
- * @example
- * ```js
- * // Configured usage
- * const editor = document.querySelector('zylem-editor');
- * editor.config = {
- *   debugState: myGame.debugState,
- *   gameState: myGame.gameState,
- *   stageState: myGame.stageState,
- * };
- * ```
- *
- * @example
- * ```js
- * // Manual registration in another project
- * import { ZylemEditorElement } from '@zylem/editor';
- *
- * // Optionally customize before registering
- * customElements.define('my-editor', ZylemEditorElement);
- * ```
- */
-declare class ZylemEditorElement extends HTMLElement {
-    private dispose;
-    private _config;
-    private _initialized;
-    private controller;
-    /** Releases this element's bridge subscription (reference-counted). */
-    private releaseBridge;
-    constructor();
-    /**
-     * Set configuration for the editor.
-     * Must be set before the element is connected to the DOM, or call `reinitialize()` after.
-     */
-    set config(value: ZylemEditorConfig);
-    get config(): ZylemEditorConfig;
-    set launcherMode(value: EditorLauncherMode);
-    get launcherMode(): EditorLauncherMode;
-    /**
-     * Observed attributes for the web component
-     */
-    static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
-    connectedCallback(): void;
-    private initialize;
-    openPanel(): void;
-    closePanel(): void;
-    togglePanel(): void;
-    /**
-     * Reinitialize the editor with new configuration.
-     * Call this after changing the `config` property if the element is already connected.
-     */
-    reinitialize(): void;
-    disconnectedCallback(): void;
-    private teardown;
-}
-/**
- * Register the ZylemEditorElement as a custom element.
- * Call this function to use the default 'zylem-editor' tag name.
- *
- * @example
- * ```js
- * import { registerZylemEditor } from '@zylem/editor';
- * registerZylemEditor();
- * // Now you can use <zylem-editor> in your HTML
- * ```
- */
-declare function registerZylemEditor(tagName?: string): void;
-
-interface IconProps extends LucideProps {
-    icon: Component<LucideProps>;
-}
-declare const Icon: Component<IconProps>;
+import { BridgeDebugTool, BridgeVec3, BridgeQuat, BridgePose, SnapSettingsPayload, SceneOperationPayload, EntityTypeDescriptor } from '@zylem/bridge';
 
 /**
  * Editor Event Bus
@@ -178,7 +64,22 @@ interface DebugState {
     paused: boolean;
     tool: DebugTools;
     selectedEntityId: string | null;
+    /**
+     * Full selection, mirroring the game. `selectedEntityId` is its first entry,
+     * kept so single-select consumers need no change.
+     */
+    selectedEntityIds: string[];
     hoveredEntityId: string | null;
+    /**
+     * Most recently selected or created entity, kept after it is deselected.
+     *
+     * What the gizmo tools fall back to: pressing Rotate with nothing selected
+     * should turn the thing you were last working on, rather than nothing. Never
+     * cleared on deselect — only overwritten — and validated against the current
+     * entity list at the point of use, since the entity it names can be deleted
+     * or undone away.
+     */
+    lastTouchedEntityId: string | null;
     flags: Set<string>;
 }
 declare const debugState: DebugState;
@@ -259,6 +160,58 @@ interface StageStateInterface {
 
 declare const stageState: StageStateInterface;
 
+/**
+ * Dock layout geometry.
+ *
+ * Docking used to be per-panel: each panel snapped itself to a viewport edge
+ * and sized itself from `window.innerWidth`. That cannot express two panels
+ * sharing a side, or a bottom strip that stops at a left-docked panel, so the
+ * dock state lives in one registry (persisted in the editor store) and every
+ * panel's rect comes from `computeDockLayout`.
+ *
+ * This module is deliberately free of Solid and `window` so the geometry can
+ * be unit tested directly.
+ */
+type DockSide = 'left' | 'right' | 'top' | 'bottom';
+/** `'main'` is the editor panel; any other id is a detached section id. */
+type DockPanelId = string;
+interface DockZoneState {
+    /** Occupants in slot order along the zone's long axis. */
+    panels: DockPanelId[];
+    /**
+     * Width for left/right, height for top/bottom.
+     * `0` means "not chosen yet"; the layout falls back to a viewport quarter.
+     */
+    thickness: number;
+}
+type DockRegistry = Record<DockSide, DockZoneState>;
+interface Viewport {
+    width: number;
+    height: number;
+}
+interface DockRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+declare const DOCK_SIDES: readonly DockSide[];
+declare const findDockedSide: (registry: DockRegistry, panelId: DockPanelId) => DockSide | null;
+interface DockLayoutOptions {
+    /** Smallest slot extent along a zone's long axis. */
+    minSlotExtent?: number;
+}
+/**
+ * Rect for every docked panel.
+ *
+ * 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.
+ */
+declare const computeDockLayout: (registry: DockRegistry, viewport: Viewport, options?: DockLayoutOptions) => Record<DockPanelId, DockRect>;
+
+/** Registry id of the main editor panel; detached sections use their panel id. */
+declare const MAIN_PANEL_ID = "main";
 interface DetachedPanelState {
     position: {
         x: number;
@@ -269,16 +222,25 @@ interface DetachedPanelState {
         height: number;
     };
 }
+/** First-run dock assignments a host can request; see `applyDefaultDocks`. */
+type EditorDockDefaults = Partial<Record<DockSide, DockPanelId[]>>;
 declare const debugStore: {
     debug: boolean;
     tool: DebugTools;
     paused: boolean;
     hovered: string | null;
     selected: string[];
+    /** Fallback target for the gizmo tools; see `DebugState.lastTouchedEntityId`. */
+    lastTouched: string | null;
     panelPosition: {
         x: number;
         y: number;
     } | null;
+    /** Main panel's floating size; its docked size comes from the registry. */
+    panelSize: {
+        width: number;
+        height: number;
+    } | null;
     toggleButtonPosition: {
         x: number;
         y: number;
@@ -287,9 +249,158 @@ declare const debugStore: {
     detachedPanels: Record<string, DetachedPanelState>;
     openSections: string[];
     panelZOrder: string[];
+    docks: DockRegistry;
+    dockDefaultsApplied: boolean;
     draggingPanelId: string | null;
     dropTargetIndex: number | null;
 };
+declare const dockPanelToSide: (panelId: DockPanelId, side: DockSide, index?: number) => void;
+declare const undockPanelFromSides: (panelId: DockPanelId) => void;
+declare const getDockedSide: (panelId: DockPanelId) => DockSide | null;
+
+type EditorLauncherMode = 'floating' | 'hidden';
+
+/**
+ * Configuration options for the ZylemEditorElement
+ */
+interface ZylemEditorConfig {
+    /**
+     * External debug state to sync with.
+     * If provided, the editor will use this state instead of its internal state.
+     */
+    debugState?: any;
+    /**
+     * External game state to sync with.
+     */
+    gameState?: any;
+    /**
+     * External stage state to sync with.
+     */
+    stageState?: any;
+    /**
+     * Whether to include default styles.
+     * @default true
+     */
+    includeStyles?: boolean;
+    /**
+     * Controls whether the internal floating launcher is rendered.
+     * @default 'floating'
+     */
+    launcherMode?: EditorLauncherMode;
+    /**
+     * Dock layout to seed the first time the editor runs in this browser, keyed
+     * by viewport edge. Use `'main'` for the editor panel itself; any other id is
+     * a section (for example `'console'`), which gets detached from the accordion
+     * so it can hold a dock slot.
+     *
+     * Ignored once the user has a saved layout, so it sets a starting point
+     * rather than forcing one.
+     */
+    defaultDocks?: EditorDockDefaults;
+    /**
+     * Whether the editor claims cmd/ctrl+z for its own undo stack.
+     *
+     * Disable it when embedding the editor in an app with its own history, and
+     * call the exported `undo()` / `redo()` from that app's handler instead.
+     * @default true
+     */
+    enableUndoShortcut?: boolean;
+    /**
+     * Whether Escape disarms the active tool.
+     * @default true
+     */
+    enableEscapeShortcut?: boolean;
+}
+/**
+ * ZylemEditorElement - A web component that wraps the Zylem Editor.
+ *
+ * This component is fully self-contained with bundled styles.
+ * It can be imported and used in any project without additional CSS configuration.
+ *
+ * @example
+ * ```html
+ * <!-- Standalone usage -->
+ * <zylem-editor></zylem-editor>
+ * ```
+ *
+ * @example
+ * ```js
+ * // Configured usage
+ * const editor = document.querySelector('zylem-editor');
+ * editor.config = {
+ *   debugState: myGame.debugState,
+ *   gameState: myGame.gameState,
+ *   stageState: myGame.stageState,
+ * };
+ * ```
+ *
+ * @example
+ * ```js
+ * // Manual registration in another project
+ * import { ZylemEditorElement } from '@zylem/editor';
+ *
+ * // Optionally customize before registering
+ * customElements.define('my-editor', ZylemEditorElement);
+ * ```
+ */
+declare class ZylemEditorElement extends HTMLElement {
+    private dispose;
+    private _config;
+    private _initialized;
+    private controller;
+    /** Releases this element's bridge subscription (reference-counted). */
+    private releaseBridge;
+    /** Keyboard shortcuts and the snap/grid mirror, torn down with the element. */
+    private teardownHooks;
+    constructor();
+    /**
+     * Set configuration for the editor.
+     * Must be set before the element is connected to the DOM, or call `reinitialize()` after.
+     */
+    set config(value: ZylemEditorConfig);
+    get config(): ZylemEditorConfig;
+    set launcherMode(value: EditorLauncherMode);
+    get launcherMode(): EditorLauncherMode;
+    /**
+     * Observed attributes for the web component
+     */
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    connectedCallback(): void;
+    private initialize;
+    openPanel(): void;
+    closePanel(): void;
+    togglePanel(): void;
+    /**
+     * Dock a panel to a viewport edge, or pass `null` to float it again.
+     * Defaults to the main editor panel.
+     */
+    dockPanel(side: DockSide | null, panelId?: DockPanelId): void;
+    /**
+     * Reinitialize the editor with new configuration.
+     * Call this after changing the `config` property if the element is already connected.
+     */
+    reinitialize(): void;
+    disconnectedCallback(): void;
+    private teardown;
+}
+/**
+ * Register the ZylemEditorElement as a custom element.
+ * Call this function to use the default 'zylem-editor' tag name.
+ *
+ * @example
+ * ```js
+ * import { registerZylemEditor } from '@zylem/editor';
+ * registerZylemEditor();
+ * // Now you can use <zylem-editor> in your HTML
+ * ```
+ */
+declare function registerZylemEditor(tagName?: string): void;
+
+interface IconProps extends LucideProps {
+    icon: Component<LucideProps>;
+}
+declare const Icon: Component<IconProps>;
 
 declare const channel: _zylem_bridge.BridgeChannel;
 /**
@@ -318,6 +429,216 @@ declare function sendEntitySelect(uuid: string | null): void;
 declare function sendEntityFocus(uuid: string): void;
 /** Write a stage variable in the running game. */
 declare function sendStageVariable(key: string, value: unknown): void;
+/**
+ * Set an entity's transform absolutely.
+ *
+ * `quaternion` is authoritative when supplied; `rotation` is Euler radians for
+ * the numeric fields, and round-trips less cleanly.
+ */
+declare function sendEntityTransform(uuid: string, transform: {
+    position?: BridgeVec3;
+    rotation?: BridgeVec3;
+    quaternion?: BridgeQuat;
+    scale?: BridgeVec3;
+}): 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;
+/** Spawn a catalog entity without a placement click. */
+declare function sendEntityCreate(typeId: string, options?: {
+    props?: Record<string, unknown>;
+    pose?: BridgePose;
+}): void;
+/** Push snap increments to the game's gizmo. */
+declare function sendSnapSettings(snap: SnapSettingsPayload): void;
+/** Show or hide the game's construction-plane grid. */
+declare function sendGridVisible(visible: boolean): void;
+
+/**
+ * Undo/redo history for scene edits.
+ *
+ * The editor owns the stack but never the inversion. Every edit originates in
+ * the game (gizmo drags, placement clicks, delete clicks), so the game publishes
+ * a committed before/after record and the editor stores it. Replaying one sends
+ * it back over the bridge: undoing a delete has to produce the original entity
+ * with its original uuid, which the editor could not do — all it ever receives
+ * is a summary of name, type, and transform.
+ *
+ * In-memory only. A reload drops history, which is correct: the game's entities
+ * are gone too, so the uuids every entry refers to would be dangling.
+ */
+
+/**
+ * Depth cap. Each entry holds two poses per affected entity, so this is cheap;
+ * the limit exists so a long editing session cannot grow without bound. The
+ * game's detached-entity bin is sized above this, so a uuid still reachable
+ * from here is still restorable.
+ */
+declare const MAX_HISTORY_DEPTH = 100;
+interface HistoryState {
+    /** Oldest first; the last entry is what `undo()` reverts. */
+    undoStack: SceneOperationPayload[];
+    /** Operations that have been undone, newest last. */
+    redoStack: SceneOperationPayload[];
+}
+declare const historyState: HistoryState;
+declare function canUndo(): boolean;
+declare function canRedo(): boolean;
+/** Label of the operation `undo()` would revert, for menu text. */
+declare function undoLabel(): string | null;
+/** Label of the operation `redo()` would replay. */
+declare function redoLabel(): string | null;
+/** Revert the most recent operation. */
+declare function undo(): boolean;
+/** Replay the most recently undone operation. */
+declare function redo(): boolean;
+/**
+ * Drop all history. Called on a fresh stage snapshot, because the entities the
+ * stack refers to are gone and replaying an entry would either do nothing or
+ * hit an unrelated entity that happens to share a uuid.
+ */
+declare function clearHistory(): void;
+
+/**
+ * The placeable entity types the game offers, and which one the Add tool is
+ * armed with.
+ *
+ * The list is game-owned: it arrives over the bridge as `catalog:snapshot`, so
+ * a host that registers its own entity types game-side gets them in the palette
+ * with no editor change. Icons come through as inline SVG markup because the
+ * editor and its hosts do not share an icon library.
+ */
+
+interface CatalogState {
+    entities: EntityTypeDescriptor[];
+    /** Type the Add tool will place, or null when disarmed. */
+    armedTypeId: string | null;
+    /**
+     * Last type chosen from the palette, so re-arming the tool does not make the
+     * user re-pick. Survives disarming; cleared only when the catalog no longer
+     * contains it.
+     */
+    lastTypeId: string | null;
+}
+declare const catalogState: CatalogState;
+declare function setEntityCatalog(entities: EntityTypeDescriptor[]): void;
+declare function setArmedType(typeId: string | null): void;
+
+/** Drop the armed placement type and return to the neutral tool. */
+declare function disarmTools(): boolean;
+
+/**
+ * Keeps the gizmo modes from outliving the selection they act on.
+ *
+ * The Move/Rotate/Scale buttons are only shown while something is selected, so
+ * a tool left active after the selection clears would be unreachable: no button
+ * to toggle it off, and the game keeps the simulation paused for the whole time
+ * a transform tool is held (see `StageTransformTool.setMode`). Escape already
+ * offers a manual way out via `disarmTools`; this is the automatic one.
+ */
+
+/**
+ * Drop an active transform tool when nothing is selected.
+ *
+ * @returns `true` when a tool was reset.
+ */
+declare function releaseOrphanedTransformTool(): boolean;
+interface TransformToolGuardOptions {
+    /** @default true */
+    enabled?: boolean;
+}
+/**
+ * Watch the selection and release orphaned transform tools.
+ *
+ * @returns An uninstall function.
+ */
+declare function installTransformToolGuard(options?: TransformToolGuardOptions): () => void;
+
+/**
+ * Snap settings and grid visibility for the transform tools.
+ *
+ * Owned by the editor because it is the UI for them, and mirrored to the game
+ * over `snap:set` — the gizmo does the actual snapping, since only it knows the
+ * drag target.
+ */
+
+/** 15 degrees, the default rotation increment. */
+declare const DEFAULT_ROTATE_SNAP: number;
+interface TransformState extends SnapSettingsPayload {
+    /** Whether the game draws its construction-plane grid. */
+    gridVisible: boolean;
+}
+declare const transformState: TransformState;
+declare function setSnapEnabled(enabled: boolean): void;
+declare function setSnapIncrements(increments: Partial<Pick<TransformState, 'translate' | 'rotate' | 'scale'>>): void;
+declare function setGridVisible(visible: boolean): void;
+
+/**
+ * Host observation of committed scene edits.
+ *
+ * Every edit the editor records is also announced here, so an embedding app can
+ * react to it — persisting a layout, marking a document dirty, or eventually
+ * writing changes back to source. Kept in its own module so `editor-bridge` does
+ * not have to import the host surface (which imports the bridge), which would be
+ * circular.
+ */
+
+type SceneOperationListener = (op: SceneOperationPayload) => void;
+/**
+ * Observe committed scene operations.
+ *
+ * @returns An unsubscribe function.
+ */
+declare function onSceneOperation(listener: SceneOperationListener): () => void;
+
+/**
+ * Stage export.
+ *
+ * Edits are runtime-only: moving a crate in the editor does not rewrite the
+ * source that created it. Export is the bridge between the two — it dumps the
+ * current stage as JSON so the values can be pasted back into the code that
+ * authored the scene. Source write-back is a later problem; this makes the work
+ * recoverable in the meantime.
+ *
+ * Built from the editor's own bridge state rather than `@zylem/game-lib/schema`,
+ * because the editor has no game-lib dependency at runtime and the entity
+ * blueprint schema stores 2D positions, which would drop the Z of every
+ * transform this feature exists to preserve.
+ */
+
+interface StageExportEntity {
+    uuid: string;
+    name?: string;
+    type?: string;
+    position?: Vector3Like;
+    /** Euler angles in radians, matching the game's own representation. */
+    rotation?: Vector3Like;
+    scale?: Vector3Like;
+}
+interface StageExport {
+    /** Bumped when the shape changes, so an old file is recognisable. */
+    version: 1;
+    exportedAt: string;
+    stage: {
+        id: string;
+        backgroundColor: string;
+        backgroundImage: string | null;
+        gravity: Vector3Like;
+        variables: Record<string, unknown>;
+    } | null;
+    entities: StageExportEntity[];
+}
+/** Snapshot the current stage as a plain, serializable object. */
+declare function buildStageExport(): StageExport;
+/** The export as formatted JSON. */
+declare function stageExportToString(): string;
+/**
+ * Copy the export to the clipboard.
+ *
+ * @returns The serialized stage when the copy succeeded, or `null` when the
+ * clipboard was unavailable — over plain HTTP, or without a user gesture, the
+ * API is either missing or rejects, and the caller falls back to the console.
+ */
+declare function copyStageExport(): Promise<string | null>;
 
 /**
  * Editor Host Helpers
@@ -401,6 +722,17 @@ interface MountZylemEditorOptions extends EditorStateBridgeOptions {
      * @default 'floating'
      */
     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.
+     *
+     * @example
+     * ```ts
+     * mountZylemEditor({ defaultDocks: { left: ['main'], bottom: ['console'] } });
+     * ```
+     */
+    defaultDocks?: EditorDockDefaults;
     /**
      * Element the <zylem-editor> overlay is appended to.
      * @default document.body
@@ -409,6 +741,8 @@ interface MountZylemEditorOptions extends EditorStateBridgeOptions {
 }
 interface MountedZylemEditor extends EditorStateBridge {
     element: ZylemEditorElement;
+    /** Dock a panel to a viewport edge, or pass `null` to float it again. */
+    dockPanel(side: DockSide | null, panelId?: DockPanelId): void;
 }
 /**
  * Imperatively mount a <zylem-editor> overlay and attach the state bridge.
@@ -422,4 +756,4 @@ interface MountedZylemEditor extends EditorStateBridge {
  */
 declare function mountZylemEditor(options?: MountZylemEditorOptions): MountedZylemEditor;
 
-export { type EditorEvent, type EditorEventType, type EditorStateBridge, type EditorStateBridgeOptions, type EditorUpdatePayload, Icon, type MountZylemEditorOptions, type MountedZylemEditor, type ZylemEditorConfig, ZylemEditorElement, attachEditorStateBridge, channel as bridgeChannel, connectEditorBridge, debugState, debugStore, disconnectEditorBridge, dispatchEditorUpdate, dispatchToEditor, editorEvents, gameState, mountZylemEditor, registerZylemEditor, sendDebugEnabled, sendEntityFocus, sendEntitySelect, sendPlayback, sendStageVariable, sendTool, stageState };
+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 };