vue-dockable-desktop 1.0.0

package/dist/core/messages.d.ts

@@ -0,0 +1,117 @@
+import type { Label, MessageFormatter } from '../types';
+/**
+ * The library's own UI strings.
+ *
+ * Each `id` is the key an application defines in its i18n message table; `defaultMessage`
+ * is the fallback when no formatter is supplied. Override any subset via
+ * `createWorkspace({ messages })` — the object is merged, so partial overrides work.
+ */
+export declare const defaultMessages: {
+    readonly floatWindow: {
+        readonly id: "vdd.floatWindow";
+        readonly defaultMessage: "Float Window";
+    };
+    readonly minimizePanel: {
+        readonly id: "vdd.minimizePanel";
+        readonly defaultMessage: "Minimize Panel";
+    };
+    readonly closeTab: {
+        readonly id: "vdd.closeTab";
+        readonly defaultMessage: "Close Tab";
+    };
+    readonly restorePanel: {
+        readonly id: "vdd.restorePanel";
+        readonly defaultMessage: "Restore Panel";
+    };
+    readonly maximizePanel: {
+        readonly id: "vdd.maximizePanel";
+        readonly defaultMessage: "Maximize Panel";
+    };
+    readonly closePanel: {
+        readonly id: "vdd.closePanel";
+        readonly defaultMessage: "Close Panel";
+    };
+    readonly dockWindow: {
+        readonly id: "vdd.dockWindow";
+        readonly defaultMessage: "Dock Window";
+    };
+    readonly minimize: {
+        readonly id: "vdd.minimize";
+        readonly defaultMessage: "Minimize";
+    };
+    readonly maximize: {
+        readonly id: "vdd.maximize";
+        readonly defaultMessage: "Maximize";
+    };
+    readonly restoreSize: {
+        readonly id: "vdd.restoreSize";
+        readonly defaultMessage: "Restore Size";
+    };
+    readonly close: {
+        readonly id: "vdd.close";
+        readonly defaultMessage: "Close";
+    };
+    readonly closeEmptyGroup: {
+        readonly id: "vdd.closeEmptyGroup";
+        readonly defaultMessage: "Close empty split group";
+    };
+    readonly emptyGroup: {
+        readonly id: "vdd.emptyGroup";
+        readonly defaultMessage: "Empty workspace section";
+    };
+    readonly unsavedChangesTitle: {
+        readonly id: "vdd.unsavedChangesTitle";
+        readonly defaultMessage: "Unsaved Changes";
+    };
+    readonly unsavedChangesMessage: {
+        readonly id: "vdd.unsavedChangesMessage";
+        readonly defaultMessage: "\"{title}\" has unsaved changes. Do you want to discard your changes and close?";
+    };
+    readonly discardChanges: {
+        readonly id: "vdd.discardChanges";
+        readonly defaultMessage: "Discard Changes";
+    };
+    readonly cancel: {
+        readonly id: "vdd.cancel";
+        readonly defaultMessage: "Cancel";
+    };
+    readonly yes: {
+        readonly id: "vdd.yes";
+        readonly defaultMessage: "Yes";
+    };
+    readonly no: {
+        readonly id: "vdd.no";
+        readonly defaultMessage: "No";
+    };
+    readonly ok: {
+        readonly id: "vdd.ok";
+        readonly defaultMessage: "OK";
+    };
+    readonly closeTooltip: {
+        readonly id: "vdd.closeTooltip";
+        readonly defaultMessage: "Close";
+    };
+    readonly scrollTabsLeft: {
+        readonly id: "vdd.scrollTabsLeft";
+        readonly defaultMessage: "Scroll tabs left";
+    };
+    readonly scrollTabsRight: {
+        readonly id: "vdd.scrollTabsRight";
+        readonly defaultMessage: "Scroll tabs right";
+    };
+    readonly moreActions: {
+        readonly id: "vdd.moreActions";
+        readonly defaultMessage: "More actions";
+    };
+    readonly search: {
+        readonly id: "vdd.search";
+        readonly defaultMessage: "Search";
+    };
+};
+/**
+ * Every message key. Import it in your own message table to get a compile-time guarantee
+ * that all keys are present and none are misspelled.
+ */
+export type MessageKey = keyof typeof defaultMessages;
+/** Resolve a label with a formatter, falling back to its `defaultMessage` then its `id`. */
+export declare function formatLabel(label: Label | undefined, format?: MessageFormatter): string;

package/dist/core/overlayState.d.ts

@@ -0,0 +1,64 @@
+import type { Component, InjectionKey, Ref } from 'vue';
+import type { FloatAnchor, Label } from '../types';
+import type { Stretch, PanelFloatPlacement } from './stretch';
+import type { ToolbarInsets, ToolbarPosition } from './panelOverlay';
+/** A widget opened through `useFloatingWidgets()` rather than placed in the template. */
+export interface ManagedWidget {
+    /**
+     * The widget's header text: plain, or a localisable descriptor.
+     *
+     * A descriptor matters most here of all the title surfaces, because this object is *stored*:
+     * a resolved string handed to `openManaged` is frozen at the language that was current when
+     * the widget opened, while a descriptor is resolved on every render and so follows a locale
+     * change with no reopen.
+     */
+    title: Label;
+    icon?: Component;
+    /** Rendered as the widget's content. */
+    component: Component;
+    props?: Record<string, unknown>;
+    anchor?: FloatAnchor;
+    width?: number;
+    height?: number;
+    stretch?: Stretch | null;
+}
+export interface OverlayStacks {
+    'top-left': string[];
+    'top-right': string[];
+    'bottom-left': string[];
+    'bottom-right': string[];
+}
+export interface PanelOverlayStore {
+    /** The overlay root element, for measuring drop zones. */
+    container: Ref<HTMLElement | null>;
+    /** Space each toolbar edge claims. */
+    insets: ToolbarInsets;
+    /** The widget on top, or `null`. */
+    topId: Ref<string | null>;
+    zOrders: Record<string, number>;
+    /** Which widgets are stacked in each corner bucket. */
+    stacks: OverlayStacks;
+    /** Each docked widget's block size, so its stack peers can offset past it. */
+    dockedSizes: Record<string, number>;
+    /** The widget being dragged, or `null`. */
+    draggingId: Ref<string | null>;
+    /** The corner the drag is currently over, or `null`. */
+    hovered: Ref<FloatAnchor | null>;
+    /** Widgets opened through `useFloatingWidgets()`. */
+    managed: Map<string, ManagedWidget>;
+    /** Bumped whenever `managed` changes, since a `Map` is not reactive by itself. */
+    managedVersion: Ref<number>;
+    registerToolbar(position: ToolbarPosition, size: number): void;
+    unregisterToolbar(position: ToolbarPosition): void;
+    focus(id: string): void;
+    dock(id: string, anchor: FloatAnchor, stretch: Stretch | null): void;
+    undock(id: string): void;
+    reportSize(id: string, size: number): void;
+    openManaged(id: string, widget: ManagedWidget): void;
+    closeManaged(id: string): void;
+    closeAllManaged(): void;
+    managedIds(): string[];
+}
+export declare const PANEL_OVERLAY_KEY: InjectionKey<PanelOverlayStore>;
+export declare function createPanelOverlayStore(): PanelOverlayStore;
+export type { PanelFloatPlacement };

package/dist/core/overlays.d.ts

@@ -0,0 +1,114 @@
+import type { Component } from 'vue';
+import type { DirtyStateOptions, Label } from '../types';
+/** Which of the three overlay slots an instance occupies. */
+export type OverlayKind = 'left-panel' | 'right-panel' | 'modal';
+/** Options for `openLeftPanel` / `openRightPanel`. */
+export interface SidePanelOptions {
+    title?: Label;
+    /** Rendered in the header, before the title. */
+    icon?: Component;
+    /** A number is pixels; a string is used as-is (`'40vw'`). @default 400 */
+    width?: number | string;
+    /**
+     * Padding for the body. A number is pixels; a string is any CSS value or shorthand.
+     * Nothing is set at all by default, so the stylesheet decides and content can go
+     * edge-to-edge.
+     */
+    bodyPadding?: number | string;
+}
+/** Options for `openModal`. */
+export interface ModalOptions {
+    title?: Label;
+    icon?: Component;
+    /** Maps to a `max-width` rule. @default 'auto' */
+    size?: 'small' | 'medium' | 'large' | 'fullscreen' | 'auto';
+    /** `false` removes the close button *and* dismissal by backdrop click or Escape. @default true */
+    closable?: boolean;
+    /** As `SidePanelOptions.bodyPadding`. */
+    bodyPadding?: number | string;
+}
+/** One open side panel or modal. */
+export interface OverlayInstance {
+    id: string;
+    /** Kept raw: a component definition is not reactive data, and proxying one is wasteful. */
+    component: Component;
+    props: Record<string, unknown>;
+    kind: OverlayKind;
+    options: SidePanelOptions & ModalOptions;
+    dirty: boolean;
+    dirtyOptions?: DirtyStateOptions;
+}
+export interface OverlayState {
+    leftPanel: OverlayInstance | null;
+    rightPanel: OverlayInstance | null;
+    /** Bottom to top: the last entry is the topmost modal. */
+    modals: OverlayInstance[];
+}
+/**
+ * What the built-in unsaved-changes question needs to know.
+ *
+ * Deliberately not an `OverlayInstance` or a `PanelInfo`: a docked tab, a floating window, a
+ * drawer and a modal all ask the same question, and narrowing it to these two fields is what
+ * lets one implementation serve all four.
+ */
+export interface DiscardRequest {
+    /** The thing being closed, already formatted — it appears in the message. */
+    title: string;
+    dirtyOptions?: DirtyStateOptions;
+}
+/** Ask the user whether to discard unsaved changes. Resolves `false` for every refusal. */
+export type ConfirmDiscard = (request: DiscardRequest) => Promise<boolean>;
+export interface Overlays {
+    readonly state: OverlayState;
+    /**
+     * Open a drawer on the left. Resolves to the new instance's id, or `null` when a panel was
+     * already open there and its close guard refused — a drawer is a single slot, so opening
+     * one is also closing the other.
+     */
+    openLeftPanel(component: Component, props?: Record<string, unknown>, options?: SidePanelOptions): Promise<string | null>;
+    openRightPanel(component: Component, props?: Record<string, unknown>, options?: SidePanelOptions): Promise<string | null>;
+    /** Push a modal onto the stack. Synchronous: a stack has room for another. */
+    openModal(component: Component, props?: Record<string, unknown>, options?: ModalOptions): string;
+    /** Remove an instance immediately, with no guard and no dirty check. */
+    close(id: string): void;
+    closeAll(): void;
+    closeAllModals(): void;
+    getInstance(id: string): OverlayInstance | undefined;
+    updateInstance(id: string, updates: Partial<Pick<OverlayInstance, 'props' | 'options' | 'dirty' | 'dirtyOptions'>>): void;
+    setDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
+    /**
+     * Close, honouring this instance's close guard and its dirty state.
+     *
+     * `force` skips both. Without a `confirm`, a dirty instance stays open rather than
+     * discarding the user's edits silently — the same refusal `requestClosePanel` makes.
+     */
+    requestClose(id: string, options?: {
+        force?: boolean;
+        confirm?: (instance: OverlayInstance) => Promise<boolean>;
+    }): Promise<void>;
+    /** Veto an instance's close. Returning `false` blocks it. */
+    registerCloseGuard(id: string, guard: () => boolean | Promise<boolean>): () => void;
+    /** The topmost modal, or `null`. */
+    topmostModal(): OverlayInstance | null;
+    /**
+     * Ask the user whether to discard unsaved changes, as a modal on top of the stack.
+     *
+     * Resolves `false` when nothing can render the question — which is why a dirty close with
+     * no `<VddModals>` mounted refuses instead of discarding. Every close path in the library
+     * routes through this one function: a tab's ×, a floating window's ×, a drawer, a modal,
+     * and `usePanel().close()`. rdd wired an equivalent separately into each container, and
+     * the docked-panel path was wired to nothing at all.
+     */
+    confirmDiscard: ConfirmDiscard;
+    /**
+     * Register the component that renders that question, and the formatter for its message.
+     * Called by `<VddModals>` on mount: asking requires somewhere to render.
+     * @internal
+     */
+    setConfirmRenderer(renderer: ConfirmRenderer | null): void;
+    /** @internal */
+    dispose(): void;
+}
+/** Supplied by `<VddModals>`: opens the question and resolves the user's answer. @internal */
+export type ConfirmRenderer = (request: DiscardRequest) => Promise<boolean>;
+export declare function createOverlays(): Overlays;

package/dist/core/panelDom.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The persistence port: the mechanism that makes a panel survive being moved.
+ *
+ * Each panel gets **one** element for its whole lifetime. Panel content is teleported into
+ * that element once; moving the panel between the grid, a floating window, a hover preview
+ * and the off-screen store moves *the element*, which Vue never observes. That is what keeps
+ * a WebGL context, a Monaco model, a playing video and an open socket alive across every
+ * layout change.
+ *
+ * Proven in the M0 spike, including the choice of this strategy over teleporting straight to
+ * the host — see docs/decisions/0002-zero-unmount-via-teleport.md. One instance per
+ * `<VddDesktop>`, never a module-level singleton: rdd's module-level `domCache` meant two
+ * workspaces on a page shared panel DOM.
+ */
+export declare class PanelDomCache {
+    private readonly doc;
+    private elements;
+    /**
+     * Preserved state, **owned per panel and outliving the hidden period**.
+     *
+     * Capturing at each move is not enough: while a panel sits in the hidden store it has no
+     * layout, so every scroller reports `scrollHeight === clientHeight === 0` and there is
+     * nothing to read. So the record is only refreshed while the panel is laid out, and always
+     * applied when it becomes laid out again — which is what makes minimise → restore work.
+     * M0 verified this failing, then fixed.
+     */
+    private preserved;
+    /**
+     * The last size each panel was laid out at.
+     *
+     * Kept here because it outlives any one host: the taskbar's hover preview needs to know how
+     * big a panel *was* in order to scale a thumbnail of it, and by then the panel is minimised
+     * and has no size of its own.
+     */
+    private sizes;
+    private hidden;
+    constructor(doc?: Document);
+    /** The off-screen store. Panels live here while minimised, and before their first host. */
+    hiddenStore(): HTMLElement;
+    /**
+     * This panel's element, created on first ask.
+     *
+     * Created **already in the document**, inside the hidden store: a `<Teleport>` target must
+     * exist when the teleport mounts, or Vue warns and renders nothing.
+     */
+    elementFor(id: string): HTMLDivElement;
+    /** Whether this panel has an element yet. */
+    has(id: string): boolean;
+    /** Record the size a panel was last laid out at. */
+    reportSize(id: string, size: {
+        width: number;
+        height: number;
+    }): void;
+    /** The size a panel was last laid out at, or a sensible default for a thumbnail. */
+    sizeOf(id: string): {
+        width: number;
+        height: number;
+    };
+    /** The host this panel's element is currently inside. */
+    hostOf(id: string): HTMLElement | null;
+    /**
+     * Move a panel's element into `host` (or the hidden store when `null`), preserving scroll
+     * and focus around the move.
+     *
+     * @param refocus restore focus as well. Only true when the panel is becoming the active
+     *   one — restoring focus into a background panel would steal the caret from wherever the
+     *   user is actually typing.
+     */
+    moveTo(id: string, host: HTMLElement | null, options?: {
+        refocus?: boolean;
+        preserveScroll?: boolean;
+    }): void;
+    /** Forget a panel entirely. Called when the panel closes. */
+    release(id: string): void;
+    /** Drop every element and the hidden store. */
+    dispose(): void;
+    private remember;
+    private apply;
+}

package/dist/core/panelMenu.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The standard menus the library offers for a panel.
+ *
+ * Built here rather than in a component so the same menu is offered wherever a panel is
+ * right-clicked — a tab, a floating window's title bar, a taskbar icon — and so the item
+ * set is testable without rendering anything.
+ */
+import type { ContextMenuItem } from './contextMenu';
+import type { PanelDefaultOptions } from './registry';
+import type { Label, MessageDescriptor } from '../types';
+/**
+ * Just enough of the workspace to build a menu, so this module does not depend on the store.
+ *
+ * `format` takes `Label | undefined`, matching the workspace exactly: widening it to
+ * `unknown` looks harmless but breaks assignability, since a function accepting a narrow
+ * type cannot stand in for one accepting anything.
+ */
+interface MenuHost {
+    format: (label: Label | undefined) => string;
+    messages: Record<string, MessageDescriptor>;
+    panelMenuItems: (id: string) => ContextMenuItem[];
+}
+export interface PanelMenuActions {
+    float: () => void;
+    minimize: () => void;
+    close: () => void;
+    restore: () => void;
+    maximize: () => void;
+}
+/**
+ * The menu for a docked tab or a floating window.
+ *
+ * Entries the panel forbids are absent rather than disabled: an action a panel has opted out
+ * of is not a temporarily unavailable action, it is not an action at all.
+ */
+export declare function buildPanelMenu(host: MenuHost, panelId: string, options: PanelDefaultOptions, actions: PanelMenuActions): ContextMenuItem[];
+/**
+ * The menu for a minimised panel's taskbar icon.
+ *
+ * "Maximize" works here. rdd offered the same item but its `maximizePanel` only mapped over
+ * floating windows, where a minimised panel is not — so the item did nothing at all
+ * (divergence D1). Restoring first is what makes it mean something.
+ */
+export declare function buildTaskbarMenu(host: MenuHost, panelId: string, options: PanelDefaultOptions, actions: PanelMenuActions): ContextMenuItem[];
+export {};

package/dist/core/panelOverlay.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Geometry and rules for the panel overlay — the toolbars and floating widgets that live
+ * *inside* one panel, over its content.
+ *
+ * Everything here is pure, so the parts that were hardest to get right in rdd — which resize
+ * handles a placement offers, and where a docked widget is allowed to grow to — are testable
+ * without a DOM. The stretch algebra they build on is in `core/stretch.ts`.
+ */
+import type { FloatAnchor } from '../types';
+import type { ResizeDir } from './dragResize';
+import type { Stretch } from './stretch';
+/** Which edge of the panel a toolbar attaches to. */
+export type ToolbarPosition = 'top' | 'bottom' | 'left' | 'right';
+/** Background treatment of a toolbar strip. */
+export type ToolbarVariant = 'transparent' | 'frosted' | 'solid';
+/** Button treatment, inherited by the toolbar's own buttons. */
+export type ButtonVariant = 'ghost' | 'soft' | 'outlined' | 'filled';
+/** Smallest a widget may be resized to. */
+export declare const MIN_W = 120;
+export declare const MIN_H = 60;
+/** Gutter between a docked widget and the panel's inline edge. */
+export declare const DOCK_INSET = 8;
+/** Gap between widgets stacked in the same corner. */
+export declare const DOCK_GAP = 8;
+/** Side of the corner drop zones, in pixels. */
+export declare const DROP_ZONE_SIZE = 80;
+/** How far the header must move before a click becomes a drag. */
+export declare const DRAG_THRESHOLD = 4;
+/**
+ * Resize-to-stretch snapping thresholds, asymmetric on purpose.
+ *
+ * A drag arms within `SNAP_IN` of the full extent but only disarms once it pulls back past the
+ * wider `SNAP_OUT`. Without that hysteresis, releasing a stretched axis by dragging a few
+ * pixels inward immediately re-arms and snaps straight back on release, which makes the
+ * gesture feel broken.
+ */
+export declare const SNAP_IN = 16;
+export declare const SNAP_OUT = 40;
+/** Space claimed by toolbars. Block values are physical; inline values are logical. */
+export interface ToolbarInsets {
+    top: number;
+    bottom: number;
+    /** Inline-start, so `left` under LTR and `right` under RTL. */
+    inlineStart: number;
+    inlineEnd: number;
+}
+export declare const NO_INSETS: ToolbarInsets;
+/** The four corners. */
+export declare const ANCHORS: readonly FloatAnchor[];
+/** Which corner zone a pointer is over, or `null` for the middle. */
+export declare function hoveredZone(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, clientX: number, clientY: number): FloatAnchor | null;
+/** A drop zone is named by its physical corner, so under RTL the inline half mirrors. */
+export declare const flipZoneHorizontal: (zone: FloatAnchor) => FloatAnchor;
+/**
+ * The band a docked widget may occupy, in **physical** pixels from the container's edges.
+ *
+ * The block axis keeps clear of top/bottom toolbars only. The inline axis also adds the
+ * `DOCK_INSET` gutter, matching how a docked widget is positioned in the first place. rdd
+ * fixed docked widgets *positioning* themselves over a toolbar in 5.x and never gave the
+ * resize path the same treatment, so a docked widget could still be resized straight over
+ * the toolbar on the far side.
+ *
+ * Inline is converted from logical to physical here because handle directions and measured
+ * rects are physical, while a toolbar claims its space logically.
+ */
+export declare function dockedBand(insets: ToolbarInsets, isRtl: boolean): {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+/**
+ * Which resize handles a placement offers.
+ *
+ * **Free-floating:** all eight. Nothing is pinned.
+ *
+ * **Docked:** only the edges that can actually move. A docked widget pins one edge per axis,
+ * so a handle on a pinned side would move the *opposite* edge instead of the one under the
+ * cursor — an inert stub with a resize cursor on it. rdd hardcoded the five non-northern
+ * directions regardless of anchor, which looked harmless for top anchors but left every
+ * bottom-anchored widget with no working vertical resize at all: `n` was not rendered, and
+ * `s` was the stub.
+ *
+ * **Stretched:** a stretched axis has both ends pinned, but both are *releasable* — dragging
+ * either moves that edge and pins the opposite one. So it offers handles on both ends, which
+ * is also what keeps the fully-stretched state from being a dead end with nothing to grab.
+ * The corner belongs only to the all-pinned state; in a stretched state it would mix a
+ * resize and a release into one gesture.
+ *
+ * The block axis is direction-agnostic; the inline axis is not. The pin is a logical property
+ * (`inset-inline-end`) while the handle classes are physical (`.vdd-resize-e { right: 0 }`),
+ * so which *physical* side is pinned depends on the reading direction.
+ */
+export declare function handleDirs(mode: 'docked' | 'free', anchor: FloatAnchor, stretch: Stretch | null, isRtl: boolean): ResizeDir[];
+/**
+ * Where a released axis re-pins.
+ *
+ * The edge under the pointer becomes the moving one and the opposite end becomes the new pin,
+ * so the gesture reads exactly like an ordinary resize. Handle directions are physical and
+ * anchors are logical, hence the direction term on the inline half.
+ */
+export declare function anchorAfterRelease(anchor: FloatAnchor, dir: ResizeDir, axes: {
+    inline: boolean;
+    block: boolean;
+}, isRtl: boolean): FloatAnchor;
+/**
+ * How far down its edge a docked widget sits, given what it is stacked behind.
+ *
+ * The largest offset across every bucket the widget occupies, so a strip spanning an edge
+ * clears whatever is stacked in *both* of that edge's corners rather than only the one it is
+ * anchored to.
+ */
+export declare function stackOffset(id: string, buckets: FloatAnchor[], stacks: Record<FloatAnchor, string[]>, sizes: Record<string, number>, fallbackHeight: number): {
+    offset: number;
+    registered: boolean;
+};

package/dist/core/registry.d.ts

@@ -0,0 +1,61 @@
+import type { Component } from 'vue';
+import type { FloatAnchor, Label } from '../types';
+/** Defaults applied to every instance of a registered panel. All optional. */
+export interface PanelDefaultOptions {
+    /** Tab and window title. */
+    title?: Label;
+    /** Icon shown in the tab, title bar and taskbar. */
+    icon?: Component;
+    /** Where the panel goes when first opened. @default 'docked' */
+    initialTarget?: 'floating' | 'docked' | 'tabbed';
+    /** Bounds used the first time the panel is floated. Numbers are px; strings any CSS length. */
+    favoritePosition?: {
+        x: number | string;
+        y: number | string;
+        width: number | string;
+        height: number | string;
+    };
+    /** Corner to pin newly-floated windows to. */
+    defaultAnchor?: FloatAnchor;
+    /** Show the close button. @default true */
+    canClose?: boolean;
+    /** Show the minimise button. @default true */
+    canMinimize?: boolean;
+    /** Allow dragging the tab, which is also what allows floating by drag. @default true */
+    canDrag?: boolean;
+    /** Show a letter tile instead of a live thumbnail in the taskbar hover preview. @default false */
+    disableLivePreview?: boolean;
+    /**
+     * Restore scroll offsets after the panel is re-parented. Turn off for a panel that
+     * manages virtualised scrolling itself and would rather react to `isMinimized`.
+     * @default true
+     * @see docs/decisions/0014-preserve-scroll-and-focus.md
+     */
+    preserveScroll?: boolean;
+}
+/** A registered panel kind. */
+export interface PanelRegistryEntry {
+    component: Component;
+    defaultOptions?: PanelDefaultOptions;
+}
+/**
+ * The panel catalogue: component keys → components.
+ *
+ * One instance per workspace, never a module-level singleton, so two workspaces on a page
+ * cannot see each other's panels (docs/decisions/0004-store-outside-components.md).
+ */
+export declare class PanelRegistry {
+    private entries;
+    /**
+     * Register a panel kind. `markRaw` is applied to the component: a component placed in
+     * reactive state would otherwise be deep-proxied by Vue, which both warns and is
+     * pointless — a component definition is never reactive data.
+     */
+    register(id: string, component: Component, defaultOptions?: PanelDefaultOptions): void;
+    /** Look up a panel kind, or `undefined` if the key was never registered. */
+    get(id: string): PanelRegistryEntry | undefined;
+    /** Whether a key is registered. */
+    has(id: string): boolean;
+    /** Every registered key. */
+    keys(): string[];
+}

package/dist/core/serializable.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether a value can round-trip through `JSON.stringify`/`JSON.parse` without silently
+ * losing information.
+ *
+ * Deliberately **not** a `JSON.stringify` try/catch: that does not throw for the failure
+ * case this guards against — a function-valued property is quietly dropped, not rejected.
+ * This walks the value tree instead, returning `false` as soon as it finds a function,
+ * symbol, `undefined`, VNode, or any non-plain object (a class instance, `Map`, `Set`,
+ * `RegExp`, …).
+ *
+ * A Vue **component** needs no special case: an options object or SFC carries `setup`,
+ * `render` or similar function properties, and the recursive walk rejects any object
+ * containing a function. An async component *is* a function and is rejected directly.
+ *
+ * `Date` is an explicit exception — serialisable-enough, matching `JSON.stringify`'s own
+ * behaviour — even though it comes back as an ISO string rather than a `Date`. That is a
+ * smaller, documentable gotcha than a silently vanishing function.
+ *
+ * This classification is a **compatibility surface**: it must agree with
+ * react-dockable-desktop's, or the same workspace would prune different panels in each
+ * library. See docs/decisions/0009-layout-json-compatibility.md.
+ *
+ * Pass raw values. A reactive proxy of plain data does pass, but prefer `toRaw()` at the
+ * call site so the answer is about the data and not about Vue's wrapper.
+ */
+export declare function isSerializable(value: unknown): boolean;

package/dist/core/serialize.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reading a saved layout.
+ *
+ * The format is byte-compatible with react-dockable-desktop 6.2.0 in both directions at
+ * `version: 2` — a hard requirement, see docs/decisions/0009-layout-json-compatibility.md.
+ * Anything in this file that changes what is read or written is a compatibility change.
+ */
+import type { FloatingWindow, LayoutNode, PanelInfo } from '../types';
+/** A validated payload, with `activePanelId` already resolved. */
+export interface ParsedLayout {
+    gridRoot: LayoutNode;
+    floating: FloatingWindow[];
+    minimized: {
+        id: string;
+        title: PanelInfo['title'];
+        component: string;
+    }[];
+    panels: Record<string, PanelInfo>;
+    activePanelId: string | null;
+}
+/**
+ * Validate and normalise a parsed JSON payload, or return `null` if it is not a layout.
+ *
+ * Both entry points — a workspace's `initialState` and `loadLayout()` — go through here, so
+ * the shape check, the migration and the `activePanelId` resolution cannot drift apart
+ * between them. In rdd they once did: only one of the two ran the migration.
+ */
+export declare function parseLayoutPayload(parsed: unknown, onWarn?: (msg: string) => void): ParsedLayout | null;
+/** Parse a layout string, falling back to an empty workspace. Never throws. */
+export declare function parseInitialState(json: string | null | undefined, onWarn?: (msg: string) => void): ParsedLayout;
+/** The schema version this library writes. Changing it is a breaking change for both libraries. */
+export declare const LAYOUT_VERSION = 2;