@zylem/editor 0.7.4 → 0.8.8

package/dist/zylem-editor.d.ts

@@ -1,112 +1,58 @@
-import { Component } from 'solid-js';
-import { LucideProps } from 'lucide-solid';
 import * as _zylem_bridge from '@zylem/bridge';
-import { BridgeDebugTool, BridgeVec3, BridgeQuat, BridgePose, SnapSettingsPayload, SceneOperationPayload, EntityTypeDescriptor } from '@zylem/bridge';
-
-/**
- * Editor Event Bus
- *
- * Wraps the shared zylemEventBus to provide backward-compatible API
- * for the editor package. This allows external code to dispatch state
- * updates to the editor using the familiar editorEvents API.
- */
+import { BridgePose, BridgeVec3, BridgeQuat, SnapSettingsPayload, BridgeDebugTool, SceneOperationPayload, EntityTypeDescriptor } from '@zylem/bridge';
+import { LucideProps } from 'lucide-solid';
+import { Component } from 'solid-js';
 
-type EditorEventType = 'debug' | 'game' | 'stage' | 'entities';
-interface EditorEvent<T = unknown> {
-    type: EditorEventType;
-    payload: T;
-}
-type EventHandler<T = unknown> = (event: EditorEvent<T>) => void;
-/**
- * Backward-compatible wrapper around zylemEventBus.
- * Maintains the existing editorEvents.emit({ type, payload }) API
- * while internally using the shared Mitt-based event bus.
- */
-declare class EditorEventBusWrapper {
-    private legacyListeners;
-    /**
-     * Emit an event to all registered listeners of that type.
-     * Also emits to the global zylemEventBus for cross-package communication.
-     */
-    emit<T>(event: EditorEvent<T>): void;
-    /**
-     * Subscribe to events of a specific type.
-     * Returns an unsubscribe function.
-     */
-    on<T>(type: EditorEventType, handler: EventHandler<T>): () => void;
-    /**
-     * Remove all listeners (useful for cleanup).
-     */
-    clear(): void;
-}
+declare const channel: _zylem_bridge.BridgeChannel;
 /**
- * Global editor event bus instance.
+ * Subscribe the editor stores to game→editor bridge messages and hydrate
+ * from the channel's retained state.
  *
- * Usage from game-lib:
- * ```ts
- * import { editorEvents } from '@zylem/editor';
- * editorEvents.emit({ type: 'debug', payload: { enabled: true } });
- * ```
+ * 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.
  *
- * Usage from editor components:
- * ```ts
- * editorEvents.on('debug', (e) => setDebugState(e.payload));
- * ```
- */
-declare const editorEvents: EditorEventBusWrapper;
-
-/**
- * Entities state for the entities section.
- * Manages debug state and entity selection/hover.
+ * @returns A release function; safe to call more than once.
  */
-type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'add' | 'none';
-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;
-
+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. */
+declare function sendTool(tool: BridgeDebugTool): void;
+/** Pause or resume the game loop. */
+declare function sendPlayback(paused: boolean): void;
+/** Select an entity in the game (null clears the selection). */
+declare function sendEntitySelect(uuid: string | null): void;
+/** Focus/frame the game debug camera on an entity. */
+declare function sendEntityFocus(uuid: string): void;
+/** Write a stage variable in the running game. */
+declare function sendStageVariable(key: string, value: unknown): void;
 /**
- * Game state for the game section.
- * Manages global game variables and state.
+ * Set an entity's transform absolutely.
+ *
+ * `quaternion` is authoritative when supplied; `rotation` is Euler radians for
+ * the numeric fields, and round-trips less cleanly.
  */
-/** Game config state from game-lib */
-interface GameConfigState {
-    id: string;
-    aspectRatio: number;
-    fullscreen: boolean;
-    bodyBackground: string | undefined;
-    internalResolution: {
-        width: number;
-        height: number;
-    } | undefined;
-    debug: boolean;
-}
-interface GameState {
-    id: string;
-    globals: Record<string, unknown>;
-    time: number;
-    config: GameConfigState | null;
-}
-declare const gameState: GameState;
+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;
 
 /**
  * Shared types for the editor store.
@@ -153,13 +99,6 @@ interface StageStateInterface {
     entities: Partial<BaseEntityInterface>[];
 }
 
-/**
- * Stage state for the stages section.
- * Manages stage configuration and entity list.
- */
-
-declare const stageState: StageStateInterface;
-
 /**
  * Dock layout geometry.
  *
@@ -210,6 +149,59 @@ interface DockLayoutOptions {
  */
 declare const computeDockLayout: (registry: DockRegistry, viewport: Viewport, options?: DockLayoutOptions) => Record<DockPanelId, DockRect>;
 
+/**
+ * Entities state for the entities section.
+ * Manages debug state and entity selection/hover.
+ */
+type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'add' | 'none';
+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;
+
+/**
+ * Game state for the game section.
+ * Manages global game variables and state.
+ */
+/** Game config state from game-lib */
+interface GameConfigState {
+    id: string;
+    aspectRatio: number;
+    fullscreen: boolean;
+    bodyBackground: string | undefined;
+    internalResolution: {
+        width: number;
+        height: number;
+    } | undefined;
+    debug: boolean;
+}
+interface GameState {
+    id: string;
+    globals: Record<string, unknown>;
+    time: number;
+    config: GameConfigState | null;
+}
+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 {
@@ -258,200 +250,69 @@ declare const dockPanelToSide: (panelId: DockPanelId, side: DockSide, index?: nu
 declare const undockPanelFromSides: (panelId: DockPanelId) => void;
 declare const getDockedSide: (panelId: DockPanelId) => DockSide | null;
 
-type EditorLauncherMode = 'floating' | 'hidden';
-
 /**
- * Configuration options for the ZylemEditorElement
+ * Editor Event Bus
+ *
+ * Wraps the shared zylemEventBus to provide backward-compatible API
+ * for the editor package. This allows external code to dispatch state
+ * updates to the editor using the familiar editorEvents API.
  */
-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;
+
+type EditorEventType = 'debug' | 'game' | 'stage' | 'entities';
+interface EditorEvent<T = unknown> {
+    type: EditorEventType;
+    payload: T;
 }
+type EventHandler<T = unknown> = (event: EditorEvent<T>) => void;
 /**
- * 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);
- * ```
+ * Backward-compatible wrapper around zylemEventBus.
+ * Maintains the existing editorEvents.emit({ type, payload }) API
+ * while internally using the shared Mitt-based event bus.
  */
-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;
+declare class EditorEventBusWrapper {
+    private legacyListeners;
     /**
-     * Observed attributes for the web component
+     * Emit an event to all registered listeners of that type.
+     * Also emits to the global zylemEventBus for cross-package communication.
      */
-    static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
-    connectedCallback(): void;
-    private initialize;
-    openPanel(): void;
-    closePanel(): void;
-    togglePanel(): void;
+    emit<T>(event: EditorEvent<T>): void;
     /**
-     * Dock a panel to a viewport edge, or pass `null` to float it again.
-     * Defaults to the main editor panel.
+     * Subscribe to events of a specific type.
+     * Returns an unsubscribe function.
      */
-    dockPanel(side: DockSide | null, panelId?: DockPanelId): void;
+    on<T>(type: EditorEventType, handler: EventHandler<T>): () => void;
     /**
-     * Reinitialize the editor with new configuration.
-     * Call this after changing the `config` property if the element is already connected.
+     * Remove all listeners (useful for cleanup).
      */
-    reinitialize(): void;
-    disconnectedCallback(): void;
-    private teardown;
+    clear(): void;
 }
 /**
- * Register the ZylemEditorElement as a custom element.
- * Call this function to use the default 'zylem-editor' tag name.
+ * Global editor event bus instance.
  *
- * @example
- * ```js
- * import { registerZylemEditor } from '@zylem/editor';
- * registerZylemEditor();
- * // Now you can use <zylem-editor> in your HTML
+ * Usage from game-lib:
+ * ```ts
+ * import { editorEvents } from '@zylem/editor';
+ * editorEvents.emit({ type: 'debug', payload: { enabled: true } });
  * ```
- */
-declare function registerZylemEditor(tagName?: string): void;
-
-interface IconProps extends LucideProps {
-    icon: Component<LucideProps>;
-}
-declare const Icon: Component<IconProps>;
-
-declare const channel: _zylem_bridge.BridgeChannel;
-/**
- * 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.
+ * Usage from editor components:
+ * ```ts
+ * editorEvents.on('debug', (e) => setDebugState(e.payload));
+ * ```
  */
-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. */
-declare function sendTool(tool: BridgeDebugTool): void;
-/** Pause or resume the game loop. */
-declare function sendPlayback(paused: boolean): void;
-/** Select an entity in the game (null clears the selection). */
-declare function sendEntitySelect(uuid: string | null): void;
-/** Focus/frame the game debug camera on an entity. */
-declare function sendEntityFocus(uuid: string): void;
-/** Write a stage variable in the running game. */
-declare function sendStageVariable(key: string, value: unknown): void;
+declare const editorEvents: EditorEventBusWrapper;
+
 /**
- * Set an entity's transform absolutely.
- *
- * `quaternion` is authoritative when supplied; `rotation` is Euler radians for
- * the numeric fields, and round-trips less cleanly.
+ * Stage state for the stages section.
+ * Manages stage configuration and entity list.
  */
-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;
+
+declare const stageState: StageStateInterface;
+
+interface IconProps extends LucideProps {
+    icon: Component<LucideProps>;
+}
+declare const Icon: Component<IconProps>;
 
 /**
  * Undo/redo history for scene edits.
@@ -498,6 +359,56 @@ declare function redo(): boolean;
  */
 declare function clearHistory(): 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>;
+
 /**
  * The placeable entity types the game offers, and which one the Add tool is
  * armed with.
@@ -572,73 +483,144 @@ 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 EditorLauncherMode = 'floating' | 'hidden';
 
-type SceneOperationListener = (op: SceneOperationPayload) => void;
 /**
- * Observe committed scene operations.
- *
- * @returns An unsubscribe function.
+ * Configuration options for the ZylemEditorElement
  */
-declare function onSceneOperation(listener: SceneOperationListener): () => void;
-
+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;
+}
 /**
- * Stage export.
+ * ZylemEditorElement - A web component that wraps the Zylem Editor.
  *
- * 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.
+ * This component is fully self-contained with bundled styles.
+ * It can be imported and used in any project without additional CSS configuration.
  *
- * 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.
+ * @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);
+ * ```
  */
-
-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[];
+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;
 }
-/** 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.
+ * Register the ZylemEditorElement as a custom element.
+ * Call this function to use the default 'zylem-editor' tag name.
  *
- * @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.
+ * @example
+ * ```js
+ * import { registerZylemEditor } from '@zylem/editor';
+ * registerZylemEditor();
+ * // Now you can use <zylem-editor> in your HTML
+ * ```
  */
-declare function copyStageExport(): Promise<string | null>;
+declare function registerZylemEditor(tagName?: string): void;
 
 /**
  * Editor Host Helpers
@@ -756,4 +738,22 @@ interface MountedZylemEditor extends EditorStateBridge {
  */
 declare function mountZylemEditor(options?: MountZylemEditorOptions): MountedZylemEditor;
 
+/**
+ * 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;
+
 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 };