react-dockable-desktop 5.0.0 → 5.1.1

package/dist/index.d.cts

@@ -110,6 +110,30 @@ interface BuiltInPanelEvents {
     'panel:restored': {
         id: string;
     };
+    /**
+     * Fires whenever something `saveLayout()` would capture changes — open/close/minimize/restore,
+     * and an `openPanel` `dedupeKey` redirect. Coalesces those into one signal for autosave-style
+     * consumers, so they don't need to subscribe to four separate events. Does **not** cover a
+     * `registerStateProvider` callback's return value changing on its own — that's a pull, there's
+     * no way to observe it changing without the panel separately notifying — nor resize/split-ratio
+     * drag/dock-rearrange, which have no hooks yet.
+     */
+    'layout:changed': Record<string, never>;
+    /**
+     * Fires from inside `saveLayout()` itself, only when that specific call excluded at least one
+     * panel (a panel whose current `props` — static or from a `registerStateProvider` — failed
+     * {@link isSerializable}). A passive `PanelInfo.serializable` flag alone isn't enough for this:
+     * nobody may be polling it at the exact moment a save happens and something silently drops out
+     * (e.g. a floating window rendering data from a live class instance). This is deliberately just
+     * a signal, not a UI opinion — decide for yourself whether that becomes a toast, a console
+     * warning, or nothing.
+     */
+    'layout:panels-excluded': {
+        panels: {
+            id: string;
+            component: string;
+        }[];
+    };
 }
 /** Per-panel definition supplied to WorkspaceClient constructor. */
 interface PanelDefinition {
@@ -228,6 +252,9 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     isOpen(id: string): boolean;
     /** Returns the IDs of all currently open panels. */
     getOpenPanelIds(): string[];
+    /** Finds an already-open panel of the given component with a matching `dedupeKey` (set via
+     * `openPanel`'s `dedupeKey` option). Returns `null` if none is open. */
+    findPanelId(component: string, dedupeKey: string): string | null;
     saveLayout(): string;
     loadLayout(json: string): boolean;
     setDirection(dir: 'ltr' | 'rtl'): void;
@@ -247,6 +274,12 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     registerCloseGuard(id: string, guard: () => boolean | Promise<boolean>): void;
     /** Removes a previously registered close guard. */
     unregisterCloseGuard(id: string): void;
+    /** Registers a callback reporting a panel's current restorable state, pulled fresh on every
+     * `saveLayout()` call — see {@link BuiltInPanelEvents}'s `'layout:panels-excluded'` doc and
+     * `FormContainerContract.registerStateProvider`. */
+    registerStateProvider(id: string, provider: () => unknown): void;
+    /** Removes a previously registered state provider. */
+    unregisterStateProvider(id: string): void;
     /** Sets/clears a panel's dirty (unsaved changes) flag. */
     setPanelDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
     /** Updates a panel's displayed title. */
@@ -277,6 +310,16 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     onPanelMinimize(callback: (id: string) => void): () => void;
     /** Subscribe to panel restore events. */
     onPanelRestore(callback: (id: string) => void): () => void;
+    /** Subscribe to the coalesced layout-change signal — see {@link BuiltInPanelEvents}'s
+     * `'layout:changed'` doc for exactly what it covers (and doesn't). */
+    onLayoutChanged(callback: () => void): () => void;
+    /** Subscribe to notification that a `saveLayout()` call excluded one or more panels because
+     * their current props weren't serializable — see {@link BuiltInPanelEvents}'s
+     * `'layout:panels-excluded'` doc. */
+    onPanelsExcluded(callback: (panels: {
+        id: string;
+        component: string;
+    }[]) => void): () => void;
 }
 
 /**
@@ -534,6 +577,51 @@ interface PanelInfo {
     dirty?: boolean;
     /** Custom options applied to the automatic unsaved changes modal. */
     dirtyOptions?: DirtyStateOptions;
+    /** Custom per-instance data passed via `openPanel(id, component, { props })`. Unconstrained —
+     *  any value is accepted, but only a value that passes {@link isSerializable} is actually
+     *  included in {@link WindowActions.saveLayout}'s output. See {@link PanelInfo.serializable}. */
+    props?: Record<string, unknown>;
+    /** Whether this panel's current `props` can round-trip through `saveLayout()`/`loadLayout()`.
+     *  Computed automatically — `true` when no `props` were passed, or when they were and passed
+     *  {@link isSerializable}. A panel with `serializable: false` still renders and works normally;
+     *  it's simply excluded from the next `saveLayout()` call (and pruned from `gridRoot`/
+     *  `floating`/`minimized` in that saved snapshot) rather than corrupting or throwing. */
+    serializable: boolean;
+    /** Optional dedup key. If another open panel of the same `component` already has this exact
+     *  key, `openPanel` focuses that existing panel instead of creating a new one — see
+     *  {@link WindowActions.openPanel}'s `dedupeKey` option and {@link WindowActions.findPanelId}. */
+    dedupeKey?: string;
+}
+/**
+ * Options accepted by {@link WindowActions.openPanel}.
+ */
+interface OpenPanelOptions<P extends object = Record<string, unknown>> {
+    /** Override the panel tab/window title. Accepts a plain string or an i18n message descriptor. */
+    title?: string | ContextMenuPredefinedMessage;
+    /** Initial placement: `'floating'`, `'docked'` (default when a grid exists), or `'tabbed'`. */
+    initialTarget?: 'floating' | 'docked' | 'tabbed';
+    /** Pin the new floating window to a workspace corner on creation. Has no effect when
+     *  `initialTarget` is `'docked'` or `'tabbed'`. */
+    anchor?: FloatAnchor | null;
+    /** Set `state.activePanelId` to this panel. @default true */
+    focus?: boolean;
+    /**
+     * Custom per-instance data spread onto the panel component alongside `panelId`, matching
+     * `openModal`/`openLeftPanel`/`openRightPanel`'s already-unconstrained `props` argument — no
+     * type restriction here either. Whether a specific value round-trips through `saveLayout()` is
+     * a runtime fact, not a type-level guarantee: see {@link PanelInfo.serializable} and the
+     * `'layout:panels-excluded'` event.
+     */
+    props?: P;
+    /**
+     * If set, and another currently-open panel of the same `component` already has this exact
+     * `dedupeKey`, that existing panel is focused instead of opening a new one — the `id`/`props`
+     * passed to *this* call are ignored in that case, the same way re-opening an already-open exact
+     * `id` already focuses it instead of duplicating it. Use this when multiple call sites might
+     * not agree on the same literal `id` for what is semantically the same entity (e.g. "the panel
+     * for the document at this path"). See also {@link WindowActions.findPanelId}.
+     */
+    dedupeKey?: string;
 }
 /**
  * Global window manager state tree representing grid nodes, windows, and panels.
@@ -592,6 +680,8 @@ interface WindowActions {
      * @param options.initialTarget - Initial placement: `'floating'`, `'docked'` (default when a grid exists), or `'tabbed'`.
      * @param options.anchor - Pin the new floating window to a workspace corner on creation. Has no effect when `initialTarget` is `'docked'` or `'tabbed'`.
      * @param options.focus - Set `state.activePanelId` to this panel. @default true
+     * @param options.props - Custom per-instance data spread onto the component alongside `panelId`. Unconstrained, like `openModal`/`openLeftPanel`/`openRightPanel`'s `props` — see {@link PanelInfo.serializable} for what determines whether it survives `saveLayout()`.
+     * @param options.dedupeKey - If another open panel of the same `component` already has this key, that panel is focused instead of opening a new one.
      * @example
      * ```ts
      * // Open floating and pin to the top-right corner:
@@ -599,14 +689,15 @@ interface WindowActions {
      *
      * // Open in the background without stealing focus:
      * actions.openPanel('prefetch', 'report', { focus: false });
+     *
+     * // Open with per-instance data, deduped by document path:
+     * actions.openPanel(crypto.randomUUID(), 'document', {
+     *   props: { path: '/notes/todo.md' },
+     *   dedupeKey: '/notes/todo.md',
+     * });
      * ```
      */
-    openPanel: (id: string, component: string, options?: {
-        title?: string | ContextMenuPredefinedMessage;
-        initialTarget?: 'floating' | 'docked' | 'tabbed';
-        anchor?: FloatAnchor | null;
-        focus?: boolean;
-    }) => void;
+    openPanel: <P extends object = Record<string, unknown>>(id: string, component: string, options?: OpenPanelOptions<P>) => void;
     /**
      * Closes a panel immediately, bypassing dirty-state close guards.
      * For guarded close, use {@link requestClosePanel}.
@@ -691,6 +782,15 @@ interface WindowActions {
      * @returns Array of panel instance IDs.
      */
     getOpenPanelIds: () => string[];
+    /**
+     * Finds the ID of an already-open panel of the given `component` with a matching `dedupeKey`
+     * (set via `openPanel`'s `dedupeKey` option). Uses a synchronous `stateRef` read — safe to
+     * call outside of render.
+     * @param component - Component key registered in the panel catalog.
+     * @param dedupeKey - The dedup key to search for.
+     * @returns The matching panel's ID, or `null` if none is open.
+     */
+    findPanelId: (component: string, dedupeKey: string) => string | null;
     /**
      * Serializes the entire workspace state to a JSON string.
      * Includes grid layout, floating window positions, minimized panels, and panel metadata.
@@ -757,6 +857,23 @@ interface WindowActions {
      * @param id - Panel instance ID.
      */
     unregisterCloseGuard: (id: string) => void;
+    /**
+     * Registers a callback reporting a docked/floating panel's *current* restorable state, pulled
+     * fresh every `saveLayout()` call — for panels whose props alone can't capture state they
+     * accumulate after opening (scroll position, an in-progress edit, a view-mode toggle). A panel
+     * that registers nothing keeps its static open-time `props` (or none). The returned value goes
+     * through the same {@link isSerializable} check as static props, re-evaluated on every save —
+     * a provider-backed panel's serializability can flip over its lifetime.
+     * @param id - Panel instance ID.
+     * @param provider - Called synchronously at each `saveLayout()`; return the current state (or
+     * `undefined` to fall back to the static `props` this panel was opened with).
+     */
+    registerStateProvider: (id: string, provider: () => unknown) => void;
+    /**
+     * Removes a previously registered state provider.
+     * @param id - Panel instance ID.
+     */
+    unregisterStateProvider: (id: string) => void;
     /**
      * Marks a panel as dirty (has unsaved changes). Dirty panels show a visual indicator
      * and the built-in close guard prompts the user before closing.
@@ -1059,6 +1176,26 @@ interface DockableDesktopProviderProps extends WindowManagerProviderProps {
  */
 declare const DockableDesktopProvider: React$1.FC<DockableDesktopProviderProps>;
 
+/**
+ * Recursively checks whether a value can round-trip through `JSON.stringify`/`JSON.parse`
+ * without silently losing information.
+ *
+ * Deliberately **not** a `JSON.stringify` try/catch — that call doesn't throw for the actual
+ * failure case this guards against: a function-valued property is simply dropped by
+ * `JSON.stringify`, not rejected. This walks the value tree instead, returning `false` as soon as
+ * it finds a function, symbol, `undefined`, React element, or any non-plain object (a class
+ * instance, `Map`, `Set`, `RegExp`, etc.).
+ *
+ * `Date` is treated as an explicit exception — serializable-enough, matching `JSON.stringify`'s
+ * own behavior — even though it doesn't round-trip back to a `Date` instance on parse. That's a
+ * smaller, more tolerable gotcha than a silently-vanishing function, so it's documented rather
+ * than treated as a disqualifying case.
+ *
+ * Used to decide whether a docked/floating panel's `props` can be included in
+ * `WorkspaceClient.saveLayout()`'s output — see {@link PanelInfo.serializable}.
+ */
+declare function isSerializable(value: unknown): boolean;
+
 /**
  * Options used when requesting to close a container.
  */
@@ -1079,6 +1216,17 @@ interface FormContainerContract {
     setDirty: (dirty: boolean, options?: DirtyStateOptions) => void;
     /** Register a custom close guard handler. Returning false or a promise resolving to false blocks closing. */
     onCloseRequested: (handler: () => boolean | Promise<boolean>) => (() => void);
+    /**
+     * Registers a callback reporting this panel's *current* restorable state, pulled fresh by
+     * `WorkspaceClient.saveLayout()` every time it's called — for panels whose static open-time
+     * props can't capture state accumulated after opening (scroll position, an in-progress edit, a
+     * view-mode toggle). Only meaningful for docked/floating panels — left/right side panels and
+     * modals already have a complete answer to this via `openLeftPanel`/`openRightPanel`/
+     * `openModal`'s own `props` argument plus `updateInstance`, so this is `undefined` there.
+     * The returned value must be synchronous — `saveLayout()` itself never returns a `Promise`.
+     * Return `undefined` to fall back to the static `props` this panel was opened with.
+     */
+    registerStateProvider?: (getState: () => unknown) => (() => void);
     /** Change the display title of the containing tab or window dynamically. */
     setTitle: (title: string | {
         id: string;
@@ -2131,4 +2279,4 @@ declare function computeResizedRect(dir: ResizeDir, dx: number, dy: number, star
  */
 declare function useColorScheme(): 'dark' | 'light';
 
-export { type BuiltInPanelEvents, type ButtonVariant, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, ContextMenu, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuPredefinedMessage, type ContextMenuProps, ContextMenuProvider, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, DefaultContextMenuAdapter, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type ManagedWindowConfig, type MenuItemAction, type MessageFormatter, type ModalOptions, ModalStackRenderer, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, PanelFloatingWindow, type PanelFloatingWindowManagerHandle, type PanelFloatingWindowProps, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelOverlayRoot, type PanelOverlayRootProps, PanelProvider, PanelRegistry, PanelRegistryClass, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, PanelToolbar, ToolbarItem as PanelToolbarItem, type PanelToolbarProps, ToolbarSeparator as PanelToolbarSeparator, type PointerDragConfig, type PredefinedMessageKey, type ResizeConstraints, type ResizeDir, type ResizeRect, type ResolvedToastOptions, RightPanelRenderer, type SearchResult, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type StyleClasses, type TaskbarVisibility, type ToastAdapter, ToastContainer, type ToastContainerProps, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, Toolbar, type ToolbarActionItem, ToolbarButton, type ToolbarButtonProps, ToolbarCenter, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarProps, ToolbarProvider, type ToolbarRadioItem, ToolbarSearchInput, type ToolbarSearchInputProps, type ToolbarSeparator$1 as ToolbarSeparator, ToolbarSpacer, ToolbarToggle, type ToolbarToggleItem, type ToolbarToggleProps, type ToolbarVariant, type UsePanelFloatingWindowReturn, type WindowActions, WindowManager, type WindowManagerProps, WindowManagerProvider, type WindowManagerProviderProps, type WindowState, WorkspaceClient, type WorkspaceClientConfig, computeResizedRect, defaultPredefinedMessages, formatLabel, sidebarSectionToTab, startPointerDrag, toast, useActivePanelContribution, useColorScheme, useFormContainer, useFormatMessage, useMergedSidebarTabs, useMergedToolbarItems, usePanelActions, usePanelContext, usePanelContextMenu, usePanelContribution, usePanelFloatingWindow, usePanelFloatingWindowManager, usePanelId, usePanelSize, usePanelState, usePredefinedMessages, useRegistry, useShowContextMenu, useSidebar, useSidebarTab, useStyleClasses, useToolbar, useWindowManagerActions, useWindowManagerState };
+export { type BuiltInPanelEvents, type ButtonVariant, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, ContextMenu, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuPredefinedMessage, type ContextMenuProps, ContextMenuProvider, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, DefaultContextMenuAdapter, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type ManagedWindowConfig, type MenuItemAction, type MessageFormatter, type ModalOptions, ModalStackRenderer, type OpenPanelOptions, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, PanelFloatingWindow, type PanelFloatingWindowManagerHandle, type PanelFloatingWindowProps, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelOverlayRoot, type PanelOverlayRootProps, PanelProvider, PanelRegistry, PanelRegistryClass, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, PanelToolbar, ToolbarItem as PanelToolbarItem, type PanelToolbarProps, ToolbarSeparator as PanelToolbarSeparator, type PointerDragConfig, type PredefinedMessageKey, type ResizeConstraints, type ResizeDir, type ResizeRect, type ResolvedToastOptions, RightPanelRenderer, type SearchResult, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type StyleClasses, type TaskbarVisibility, type ToastAdapter, ToastContainer, type ToastContainerProps, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, Toolbar, type ToolbarActionItem, ToolbarButton, type ToolbarButtonProps, ToolbarCenter, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarProps, ToolbarProvider, type ToolbarRadioItem, ToolbarSearchInput, type ToolbarSearchInputProps, type ToolbarSeparator$1 as ToolbarSeparator, ToolbarSpacer, ToolbarToggle, type ToolbarToggleItem, type ToolbarToggleProps, type ToolbarVariant, type UsePanelFloatingWindowReturn, type WindowActions, WindowManager, type WindowManagerProps, WindowManagerProvider, type WindowManagerProviderProps, type WindowState, WorkspaceClient, type WorkspaceClientConfig, computeResizedRect, defaultPredefinedMessages, formatLabel, isSerializable, sidebarSectionToTab, startPointerDrag, toast, useActivePanelContribution, useColorScheme, useFormContainer, useFormatMessage, useMergedSidebarTabs, useMergedToolbarItems, usePanelActions, usePanelContext, usePanelContextMenu, usePanelContribution, usePanelFloatingWindow, usePanelFloatingWindowManager, usePanelId, usePanelSize, usePanelState, usePredefinedMessages, useRegistry, useShowContextMenu, useSidebar, useSidebarTab, useStyleClasses, useToolbar, useWindowManagerActions, useWindowManagerState };

package/dist/index.d.ts

@@ -110,6 +110,30 @@ interface BuiltInPanelEvents {
     'panel:restored': {
         id: string;
     };
+    /**
+     * Fires whenever something `saveLayout()` would capture changes — open/close/minimize/restore,
+     * and an `openPanel` `dedupeKey` redirect. Coalesces those into one signal for autosave-style
+     * consumers, so they don't need to subscribe to four separate events. Does **not** cover a
+     * `registerStateProvider` callback's return value changing on its own — that's a pull, there's
+     * no way to observe it changing without the panel separately notifying — nor resize/split-ratio
+     * drag/dock-rearrange, which have no hooks yet.
+     */
+    'layout:changed': Record<string, never>;
+    /**
+     * Fires from inside `saveLayout()` itself, only when that specific call excluded at least one
+     * panel (a panel whose current `props` — static or from a `registerStateProvider` — failed
+     * {@link isSerializable}). A passive `PanelInfo.serializable` flag alone isn't enough for this:
+     * nobody may be polling it at the exact moment a save happens and something silently drops out
+     * (e.g. a floating window rendering data from a live class instance). This is deliberately just
+     * a signal, not a UI opinion — decide for yourself whether that becomes a toast, a console
+     * warning, or nothing.
+     */
+    'layout:panels-excluded': {
+        panels: {
+            id: string;
+            component: string;
+        }[];
+    };
 }
 /** Per-panel definition supplied to WorkspaceClient constructor. */
 interface PanelDefinition {
@@ -228,6 +252,9 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     isOpen(id: string): boolean;
     /** Returns the IDs of all currently open panels. */
     getOpenPanelIds(): string[];
+    /** Finds an already-open panel of the given component with a matching `dedupeKey` (set via
+     * `openPanel`'s `dedupeKey` option). Returns `null` if none is open. */
+    findPanelId(component: string, dedupeKey: string): string | null;
     saveLayout(): string;
     loadLayout(json: string): boolean;
     setDirection(dir: 'ltr' | 'rtl'): void;
@@ -247,6 +274,12 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     registerCloseGuard(id: string, guard: () => boolean | Promise<boolean>): void;
     /** Removes a previously registered close guard. */
     unregisterCloseGuard(id: string): void;
+    /** Registers a callback reporting a panel's current restorable state, pulled fresh on every
+     * `saveLayout()` call — see {@link BuiltInPanelEvents}'s `'layout:panels-excluded'` doc and
+     * `FormContainerContract.registerStateProvider`. */
+    registerStateProvider(id: string, provider: () => unknown): void;
+    /** Removes a previously registered state provider. */
+    unregisterStateProvider(id: string): void;
     /** Sets/clears a panel's dirty (unsaved changes) flag. */
     setPanelDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
     /** Updates a panel's displayed title. */
@@ -277,6 +310,16 @@ declare class WorkspaceClient<TUserEvents extends Record<string, unknown> = Reco
     onPanelMinimize(callback: (id: string) => void): () => void;
     /** Subscribe to panel restore events. */
     onPanelRestore(callback: (id: string) => void): () => void;
+    /** Subscribe to the coalesced layout-change signal — see {@link BuiltInPanelEvents}'s
+     * `'layout:changed'` doc for exactly what it covers (and doesn't). */
+    onLayoutChanged(callback: () => void): () => void;
+    /** Subscribe to notification that a `saveLayout()` call excluded one or more panels because
+     * their current props weren't serializable — see {@link BuiltInPanelEvents}'s
+     * `'layout:panels-excluded'` doc. */
+    onPanelsExcluded(callback: (panels: {
+        id: string;
+        component: string;
+    }[]) => void): () => void;
 }
 
 /**
@@ -534,6 +577,51 @@ interface PanelInfo {
     dirty?: boolean;
     /** Custom options applied to the automatic unsaved changes modal. */
     dirtyOptions?: DirtyStateOptions;
+    /** Custom per-instance data passed via `openPanel(id, component, { props })`. Unconstrained —
+     *  any value is accepted, but only a value that passes {@link isSerializable} is actually
+     *  included in {@link WindowActions.saveLayout}'s output. See {@link PanelInfo.serializable}. */
+    props?: Record<string, unknown>;
+    /** Whether this panel's current `props` can round-trip through `saveLayout()`/`loadLayout()`.
+     *  Computed automatically — `true` when no `props` were passed, or when they were and passed
+     *  {@link isSerializable}. A panel with `serializable: false` still renders and works normally;
+     *  it's simply excluded from the next `saveLayout()` call (and pruned from `gridRoot`/
+     *  `floating`/`minimized` in that saved snapshot) rather than corrupting or throwing. */
+    serializable: boolean;
+    /** Optional dedup key. If another open panel of the same `component` already has this exact
+     *  key, `openPanel` focuses that existing panel instead of creating a new one — see
+     *  {@link WindowActions.openPanel}'s `dedupeKey` option and {@link WindowActions.findPanelId}. */
+    dedupeKey?: string;
+}
+/**
+ * Options accepted by {@link WindowActions.openPanel}.
+ */
+interface OpenPanelOptions<P extends object = Record<string, unknown>> {
+    /** Override the panel tab/window title. Accepts a plain string or an i18n message descriptor. */
+    title?: string | ContextMenuPredefinedMessage;
+    /** Initial placement: `'floating'`, `'docked'` (default when a grid exists), or `'tabbed'`. */
+    initialTarget?: 'floating' | 'docked' | 'tabbed';
+    /** Pin the new floating window to a workspace corner on creation. Has no effect when
+     *  `initialTarget` is `'docked'` or `'tabbed'`. */
+    anchor?: FloatAnchor | null;
+    /** Set `state.activePanelId` to this panel. @default true */
+    focus?: boolean;
+    /**
+     * Custom per-instance data spread onto the panel component alongside `panelId`, matching
+     * `openModal`/`openLeftPanel`/`openRightPanel`'s already-unconstrained `props` argument — no
+     * type restriction here either. Whether a specific value round-trips through `saveLayout()` is
+     * a runtime fact, not a type-level guarantee: see {@link PanelInfo.serializable} and the
+     * `'layout:panels-excluded'` event.
+     */
+    props?: P;
+    /**
+     * If set, and another currently-open panel of the same `component` already has this exact
+     * `dedupeKey`, that existing panel is focused instead of opening a new one — the `id`/`props`
+     * passed to *this* call are ignored in that case, the same way re-opening an already-open exact
+     * `id` already focuses it instead of duplicating it. Use this when multiple call sites might
+     * not agree on the same literal `id` for what is semantically the same entity (e.g. "the panel
+     * for the document at this path"). See also {@link WindowActions.findPanelId}.
+     */
+    dedupeKey?: string;
 }
 /**
  * Global window manager state tree representing grid nodes, windows, and panels.
@@ -592,6 +680,8 @@ interface WindowActions {
      * @param options.initialTarget - Initial placement: `'floating'`, `'docked'` (default when a grid exists), or `'tabbed'`.
      * @param options.anchor - Pin the new floating window to a workspace corner on creation. Has no effect when `initialTarget` is `'docked'` or `'tabbed'`.
      * @param options.focus - Set `state.activePanelId` to this panel. @default true
+     * @param options.props - Custom per-instance data spread onto the component alongside `panelId`. Unconstrained, like `openModal`/`openLeftPanel`/`openRightPanel`'s `props` — see {@link PanelInfo.serializable} for what determines whether it survives `saveLayout()`.
+     * @param options.dedupeKey - If another open panel of the same `component` already has this key, that panel is focused instead of opening a new one.
      * @example
      * ```ts
      * // Open floating and pin to the top-right corner:
@@ -599,14 +689,15 @@ interface WindowActions {
      *
      * // Open in the background without stealing focus:
      * actions.openPanel('prefetch', 'report', { focus: false });
+     *
+     * // Open with per-instance data, deduped by document path:
+     * actions.openPanel(crypto.randomUUID(), 'document', {
+     *   props: { path: '/notes/todo.md' },
+     *   dedupeKey: '/notes/todo.md',
+     * });
      * ```
      */
-    openPanel: (id: string, component: string, options?: {
-        title?: string | ContextMenuPredefinedMessage;
-        initialTarget?: 'floating' | 'docked' | 'tabbed';
-        anchor?: FloatAnchor | null;
-        focus?: boolean;
-    }) => void;
+    openPanel: <P extends object = Record<string, unknown>>(id: string, component: string, options?: OpenPanelOptions<P>) => void;
     /**
      * Closes a panel immediately, bypassing dirty-state close guards.
      * For guarded close, use {@link requestClosePanel}.
@@ -691,6 +782,15 @@ interface WindowActions {
      * @returns Array of panel instance IDs.
      */
     getOpenPanelIds: () => string[];
+    /**
+     * Finds the ID of an already-open panel of the given `component` with a matching `dedupeKey`
+     * (set via `openPanel`'s `dedupeKey` option). Uses a synchronous `stateRef` read — safe to
+     * call outside of render.
+     * @param component - Component key registered in the panel catalog.
+     * @param dedupeKey - The dedup key to search for.
+     * @returns The matching panel's ID, or `null` if none is open.
+     */
+    findPanelId: (component: string, dedupeKey: string) => string | null;
     /**
      * Serializes the entire workspace state to a JSON string.
      * Includes grid layout, floating window positions, minimized panels, and panel metadata.
@@ -757,6 +857,23 @@ interface WindowActions {
      * @param id - Panel instance ID.
      */
     unregisterCloseGuard: (id: string) => void;
+    /**
+     * Registers a callback reporting a docked/floating panel's *current* restorable state, pulled
+     * fresh every `saveLayout()` call — for panels whose props alone can't capture state they
+     * accumulate after opening (scroll position, an in-progress edit, a view-mode toggle). A panel
+     * that registers nothing keeps its static open-time `props` (or none). The returned value goes
+     * through the same {@link isSerializable} check as static props, re-evaluated on every save —
+     * a provider-backed panel's serializability can flip over its lifetime.
+     * @param id - Panel instance ID.
+     * @param provider - Called synchronously at each `saveLayout()`; return the current state (or
+     * `undefined` to fall back to the static `props` this panel was opened with).
+     */
+    registerStateProvider: (id: string, provider: () => unknown) => void;
+    /**
+     * Removes a previously registered state provider.
+     * @param id - Panel instance ID.
+     */
+    unregisterStateProvider: (id: string) => void;
     /**
      * Marks a panel as dirty (has unsaved changes). Dirty panels show a visual indicator
      * and the built-in close guard prompts the user before closing.
@@ -1059,6 +1176,26 @@ interface DockableDesktopProviderProps extends WindowManagerProviderProps {
  */
 declare const DockableDesktopProvider: React$1.FC<DockableDesktopProviderProps>;
 
+/**
+ * Recursively checks whether a value can round-trip through `JSON.stringify`/`JSON.parse`
+ * without silently losing information.
+ *
+ * Deliberately **not** a `JSON.stringify` try/catch — that call doesn't throw for the actual
+ * failure case this guards against: a function-valued property is simply dropped by
+ * `JSON.stringify`, not rejected. This walks the value tree instead, returning `false` as soon as
+ * it finds a function, symbol, `undefined`, React element, or any non-plain object (a class
+ * instance, `Map`, `Set`, `RegExp`, etc.).
+ *
+ * `Date` is treated as an explicit exception — serializable-enough, matching `JSON.stringify`'s
+ * own behavior — even though it doesn't round-trip back to a `Date` instance on parse. That's a
+ * smaller, more tolerable gotcha than a silently-vanishing function, so it's documented rather
+ * than treated as a disqualifying case.
+ *
+ * Used to decide whether a docked/floating panel's `props` can be included in
+ * `WorkspaceClient.saveLayout()`'s output — see {@link PanelInfo.serializable}.
+ */
+declare function isSerializable(value: unknown): boolean;
+
 /**
  * Options used when requesting to close a container.
  */
@@ -1079,6 +1216,17 @@ interface FormContainerContract {
     setDirty: (dirty: boolean, options?: DirtyStateOptions) => void;
     /** Register a custom close guard handler. Returning false or a promise resolving to false blocks closing. */
     onCloseRequested: (handler: () => boolean | Promise<boolean>) => (() => void);
+    /**
+     * Registers a callback reporting this panel's *current* restorable state, pulled fresh by
+     * `WorkspaceClient.saveLayout()` every time it's called — for panels whose static open-time
+     * props can't capture state accumulated after opening (scroll position, an in-progress edit, a
+     * view-mode toggle). Only meaningful for docked/floating panels — left/right side panels and
+     * modals already have a complete answer to this via `openLeftPanel`/`openRightPanel`/
+     * `openModal`'s own `props` argument plus `updateInstance`, so this is `undefined` there.
+     * The returned value must be synchronous — `saveLayout()` itself never returns a `Promise`.
+     * Return `undefined` to fall back to the static `props` this panel was opened with.
+     */
+    registerStateProvider?: (getState: () => unknown) => (() => void);
     /** Change the display title of the containing tab or window dynamically. */
     setTitle: (title: string | {
         id: string;
@@ -2131,4 +2279,4 @@ declare function computeResizedRect(dir: ResizeDir, dx: number, dy: number, star
  */
 declare function useColorScheme(): 'dark' | 'light';
 
-export { type BuiltInPanelEvents, type ButtonVariant, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, ContextMenu, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuPredefinedMessage, type ContextMenuProps, ContextMenuProvider, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, DefaultContextMenuAdapter, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type ManagedWindowConfig, type MenuItemAction, type MessageFormatter, type ModalOptions, ModalStackRenderer, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, PanelFloatingWindow, type PanelFloatingWindowManagerHandle, type PanelFloatingWindowProps, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelOverlayRoot, type PanelOverlayRootProps, PanelProvider, PanelRegistry, PanelRegistryClass, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, PanelToolbar, ToolbarItem as PanelToolbarItem, type PanelToolbarProps, ToolbarSeparator as PanelToolbarSeparator, type PointerDragConfig, type PredefinedMessageKey, type ResizeConstraints, type ResizeDir, type ResizeRect, type ResolvedToastOptions, RightPanelRenderer, type SearchResult, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type StyleClasses, type TaskbarVisibility, type ToastAdapter, ToastContainer, type ToastContainerProps, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, Toolbar, type ToolbarActionItem, ToolbarButton, type ToolbarButtonProps, ToolbarCenter, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarProps, ToolbarProvider, type ToolbarRadioItem, ToolbarSearchInput, type ToolbarSearchInputProps, type ToolbarSeparator$1 as ToolbarSeparator, ToolbarSpacer, ToolbarToggle, type ToolbarToggleItem, type ToolbarToggleProps, type ToolbarVariant, type UsePanelFloatingWindowReturn, type WindowActions, WindowManager, type WindowManagerProps, WindowManagerProvider, type WindowManagerProviderProps, type WindowState, WorkspaceClient, type WorkspaceClientConfig, computeResizedRect, defaultPredefinedMessages, formatLabel, sidebarSectionToTab, startPointerDrag, toast, useActivePanelContribution, useColorScheme, useFormContainer, useFormatMessage, useMergedSidebarTabs, useMergedToolbarItems, usePanelActions, usePanelContext, usePanelContextMenu, usePanelContribution, usePanelFloatingWindow, usePanelFloatingWindowManager, usePanelId, usePanelSize, usePanelState, usePredefinedMessages, useRegistry, useShowContextMenu, useSidebar, useSidebarTab, useStyleClasses, useToolbar, useWindowManagerActions, useWindowManagerState };
+export { type BuiltInPanelEvents, type ButtonVariant, type CloseOptions, ConfirmationForm, type ConfirmationFormProps, ContextMenu, type ContextMenuAdapter, type ContextMenuCheckbox, type ContextMenuHandle, type ContextMenuItem, type ContextMenuLabel, type ContextMenuPredefinedMessage, type ContextMenuProps, ContextMenuProvider, type ContextMenuSeparator, type ContextMenuSimpleItem, type ContextMenuSubMenu, DefaultContextMenuAdapter, DockableDesktopProvider, type DockableDesktopProviderProps, type DropPosition, type DropTarget, type FloatAnchor, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type ManagedWindowConfig, type MenuItemAction, type MessageFormatter, type ModalOptions, ModalStackRenderer, type OpenPanelOptions, type PanelActions, type PanelContribution, PanelContributionProvider, type PanelDefinition, PanelFloatingWindow, type PanelFloatingWindowManagerHandle, type PanelFloatingWindowProps, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelOverlayRoot, type PanelOverlayRootProps, PanelProvider, PanelRegistry, PanelRegistryClass, type PanelRegistryEntry, type PanelSidebarSection, type PanelState, type PanelTitle, PanelToolbar, ToolbarItem as PanelToolbarItem, type PanelToolbarProps, ToolbarSeparator as PanelToolbarSeparator, type PointerDragConfig, type PredefinedMessageKey, type ResizeConstraints, type ResizeDir, type ResizeRect, type ResolvedToastOptions, RightPanelRenderer, type SearchResult, type SerializedLayout, type ShowContextMenuOptions, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarContextValue, type SidebarHandle, type SidebarProps, type SidebarTab, type SidebarTabContextValue, type SplitDirection, type SplitOrientation, type StyleClasses, type TaskbarVisibility, type ToastAdapter, ToastContainer, type ToastContainerProps, type ToastFunction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastType, Toolbar, type ToolbarActionItem, ToolbarButton, type ToolbarButtonProps, ToolbarCenter, type ToolbarContextValue, type ToolbarGroupEntry, type ToolbarGroupItem, type ToolbarGroupSubItem, type ToolbarHandle, type ToolbarItem$1 as ToolbarItem, type ToolbarPosition, type ToolbarProps, ToolbarProvider, type ToolbarRadioItem, ToolbarSearchInput, type ToolbarSearchInputProps, type ToolbarSeparator$1 as ToolbarSeparator, ToolbarSpacer, ToolbarToggle, type ToolbarToggleItem, type ToolbarToggleProps, type ToolbarVariant, type UsePanelFloatingWindowReturn, type WindowActions, WindowManager, type WindowManagerProps, WindowManagerProvider, type WindowManagerProviderProps, type WindowState, WorkspaceClient, type WorkspaceClientConfig, computeResizedRect, defaultPredefinedMessages, formatLabel, isSerializable, sidebarSectionToTab, startPointerDrag, toast, useActivePanelContribution, useColorScheme, useFormContainer, useFormatMessage, useMergedSidebarTabs, useMergedToolbarItems, usePanelActions, usePanelContext, usePanelContextMenu, usePanelContribution, usePanelFloatingWindow, usePanelFloatingWindowManager, usePanelId, usePanelSize, usePanelState, usePredefinedMessages, useRegistry, useShowContextMenu, useSidebar, useSidebarTab, useStyleClasses, useToolbar, useWindowManagerActions, useWindowManagerState };