@ai-matrx/summon 0.0.0 → 0.1.1

package/dist/window.d.ts

@@ -0,0 +1,796 @@
+import * as react from 'react';
+import react__default, { ComponentType, SVGAttributes, ReactNode } from 'react';
+import { WindowRect, WindowPersistenceRegistration, MobilePresentation } from '@ai-matrx/summon';
+import { TraySnapshotCapture } from '@ai-matrx/summon/window-host';
+export { DEFAULT_ESCAPE_YIELD_SELECTOR, DEFAULT_MOBILE_TOP_OFFSET, DEFAULT_WINDOW_CONFIG, TrayPreviewContext, TrayPreviewEntry, TraySnapshotCapture, WindowConfig, WindowSelectionSurface, WindowSelectionSurfaceProps, WindowTraySync, WindowsProvider, WindowsProviderProps, getTrayPreviewEntry, registerTrayPreview, resetTrayPreviews, useWindowConfig } from '@ai-matrx/summon/window-host';
+
+type ResizeEdge = "e" | "s" | "se" | "w" | "sw" | "n" | "ne" | "nw";
+/** Where to place the window when it first opens. */
+type WindowPosition = "center" | "top-right" | "top-left" | "bottom-right" | "bottom-left";
+declare function resetDefaultWindowCascade(): void;
+declare function resolvePosition(pos: WindowPosition | undefined, w: number, h: number): {
+    x: number;
+    y: number;
+};
+interface UseWindowPanelOptions {
+    /** Stable, unique id. If omitted a React useId-based id is used. */
+    id?: string | undefined;
+    /** Title shown in the header and tray chip. */
+    title?: string | undefined;
+    /**
+     * Initial width. Accepts pixels (number) or viewport strings ("60vw").
+     * Default: 320.
+     */
+    width?: number | string | undefined;
+    /**
+     * Initial height. Accepts pixels (number) or viewport strings ("60dvh").
+     * Default: 400.
+     */
+    height?: number | string | undefined;
+    /** Minimum width during pointer resize. Default: 180. */
+    minWidth?: number | undefined;
+    /** Minimum height during pointer resize. Default: 80. */
+    minHeight?: number | undefined;
+    /** Where to place the window initially. Default: "center". */
+    position?: WindowPosition | undefined;
+    /** Park a brand-new desktop window in the tray without a visible flash. */
+    initialState?: "windowed" | "minimized" | undefined;
+    /**
+     * The system (not a person) opened this window. It docks in a free gutter beside the page's
+     * working column, or parks in the tray when none fits — never over the page. See
+     * `utils/autoOpenPlacement.ts`. WindowPanel sets this from `markAutoOpened`.
+     */
+    autoOpened?: boolean | undefined;
+    /**
+     * MKT-104: an auto-opened window with no gutter left beside the page closes itself through this
+     * instead of parking a tray card over the page's controls.
+     */
+    onAutoNoRoom?: (() => void) | undefined;
+    /**
+     * @deprecated Pass `width`, `height`, and `position` instead.
+     * Low-level initial rect — overrides width/height/position when provided.
+     */
+    initialRect?: Partial<WindowRect> | undefined;
+    /** Maximum width the user can resize to. */
+    maxWidth?: number | undefined;
+    /** Maximum height the user can resize to. */
+    maxHeight?: number | undefined;
+    /**
+     * Optional callback fired when the user drags the window outside the
+     * viewport long enough to count as a pop-out gesture. Caller is expected
+     * to open the popout window synchronously inside the user-gesture stack
+     * (i.e. without `await` before the open call).
+     *
+     * Pass the current rect at the time of release — the popout uses it for
+     * sizing.
+     *
+     * `undefined` disables drag-out detection entirely. Use `undefined` for
+     * popouts that aren't supported (mobile, no-capability browsers, etc.)
+     * so we don't waste cycles on the per-move evaluation.
+     */
+    onTriggerPopout?: ((rect: WindowRect) => void) | undefined;
+    /** Audited local preservation identity and initial semantic/chrome state. */
+    persistence?: WindowPersistenceRegistration | undefined;
+}
+interface UseWindowPanelReturn {
+    /** The stable window id. */
+    id: string;
+    /** Current window state from Redux. */
+    windowState: "windowed" | "maximized" | "minimized";
+    /** Current windowed rect from Redux. */
+    rect: WindowRect;
+    /** z-index from Redux. */
+    zIndex: number;
+    /** Pointerdown handler for the drag handle (header). Works with mouse + touch + pen. */
+    onDragStart: (e: React.PointerEvent) => void;
+    /** Pointerdown handler factory for resize handles. Works with mouse + touch + pen. */
+    onResizeStart: (edge: ResizeEdge) => (e: React.PointerEvent) => void;
+    /** Bring this window to the top. */
+    onFocus: () => void;
+    /** Transition to windowed state. */
+    onRestore: () => void;
+    /** Transition to maximized state. */
+    onMaximize: () => void;
+    /** Transition to minimized (tray) state. */
+    onMinimize: () => void;
+    /** Toggle maximized ↔ windowed. */
+    onToggleMaximize: () => void;
+    /**
+     * True while the user is actively dragging or resizing with the pointer.
+     * The shell disables its geometry transition during interaction so the
+     * window tracks the pointer 1:1, and re-enables it for programmatic rect
+     * changes (snap, arrange, minimize→tray, restore, clamp) which then glide.
+     */
+    isInteracting: boolean;
+}
+declare function useWindowPanel(opts?: UseWindowPanelOptions): UseWindowPanelReturn;
+
+/**
+ * WindowPanel — a floating, draggable, resizable, maximizable, minimizable OS-style window, with
+ * snap/arrange, a minimized tile with a captured preview, pop-out to a real browser window, and
+ * three phone presentations. Ported from matrx-frontend `features/window-panels/WindowPanel.tsx`.
+ *
+ * Body identity: the body subtree renders into ONE stable detached container through a portal at a
+ * fixed position in this component's tree; each presentation (windowed, maximized, minimized,
+ * popped out) only decides WHERE that container is attached. So maximize, minimize, pop-out and
+ * dock never remount the body — its state, refs, effects and subscriptions survive every move.
+ */
+
+/**
+ * Props that don't participate in the close-binding discrimination.
+ * Kept as an intersection base so the discriminated union below can layer
+ * the close-binding contract on top without losing intellisense on the
+ * common props.
+ */
+interface WindowPanelBaseProps extends UseWindowPanelOptions {
+    children: react__default.ReactNode;
+    title?: string | undefined;
+    /** Rich title rendered in the header. Falls back to `title` (string) when omitted. */
+    titleNode?: react__default.ReactNode | undefined;
+    /** @deprecated Use `actionsLeft` and `actionsRight` instead */
+    actions?: react__default.ReactNode | undefined;
+    actionsLeft?: react__default.ReactNode | undefined;
+    actionsRight?: react__default.ReactNode | undefined;
+    bodyClassName?: string | undefined;
+    className?: string | undefined;
+    /**
+     * Rare escape hatch for page-local windows that have no overlay definition
+     * but still need an explicit mobile surface. Registered overlays keep their
+     * presentation in their definition (`window.mobile`).
+     */
+    mobilePresentationOverride?: MobilePresentation | undefined;
+    /**
+     * The surface this window REGISTERS (its own `SurfaceRuntimeProvider`).
+     * Marks every root with `data-surface-layer`, so the unregistered-window
+     * reader (`features/surfaces/runtime/window-forms.ts`) leaves it alone —
+     * one way for an agent to write a field, never two.
+     */
+    surfaceLayer?: string | undefined;
+    /** Phone drawer presentation: size the sheet to the content (max 85dvh). */
+    mobileSizeToContent?: boolean | undefined;
+    /**
+     * Escape closes this window when it is the TOPMOST window and nothing above
+     * it (a menu, popover, dialog, the workspace picker) is open to take the
+     * key. Opt in for windows whose close is safe (their draft is kept, or
+     * there is nothing to lose). Desktop only — a phone sheet has its own.
+     */
+    closeOnEscape?: boolean | undefined;
+    /** Phone drawer presentation: no title-row ✕ (the handle and the window's own Cancel dismiss it). */
+    mobileHideClose?: boolean | undefined;
+    minWidth?: number | undefined;
+    minHeight?: number | undefined;
+    urlSyncKey?: string | undefined;
+    urlSyncId?: string | undefined;
+    urlSyncArgs?: Record<string, string> | undefined;
+    /** Content to render in a collapsible left sidebar panel */
+    sidebar?: react__default.ReactNode | undefined;
+    /** Default width for the sidebar in pixels (default: 200) */
+    sidebarDefaultSize?: number | undefined;
+    /** Minimum width in pixels before the sidebar collapses (default: 150) */
+    sidebarMinSize?: number | undefined;
+    /** Whether the sidebar starts open (default: true) */
+    defaultSidebarOpen?: boolean | undefined;
+    /** Class name applied to the sidebar panel content wrapper */
+    sidebarClassName?: string | undefined;
+    /**
+     * When true, opening the sidebar grows the window width by sidebarDefaultSize
+     * and closing it shrinks it back, keeping the body content width constant.
+     */
+    sidebarExpandsWindow?: boolean | undefined;
+    /**
+     * Content for a collapsible RIGHT secondary panel — the canonical home for a
+     * history / inspector / details pane that belongs to the window, not the body.
+     * Resizable, mirrors the left `sidebar`. Desktop only; handle mobile in the
+     * consumer (e.g. a Drawer) — see `features/notes` for the reference pattern.
+     */
+    secondaryPanel?: react__default.ReactNode | undefined;
+    /** Whether the secondary panel is open (default: true when `secondaryPanel` is provided). */
+    secondaryPanelOpen?: boolean | undefined;
+    /** Default width for the secondary panel in pixels (default: 360) */
+    secondaryPanelDefaultSize?: number | undefined;
+    /** Minimum width in pixels for the secondary panel (default: 240) */
+    secondaryPanelMinSize?: number | undefined;
+    /** Class name applied to the secondary panel content wrapper */
+    secondaryPanelClassName?: string | undefined;
+    /**
+     * When true, hides the header pop-out affordance (icon + green-dropdown entry).
+     * Pop-out is shown by default on desktop when the browser supports it.
+     */
+    hidePopOutButton?: boolean | undefined;
+    /** Content rendered in a full-width footer bar below the body. Renders as a single flex row. For zoned layout, use footerLeft/footerCenter/footerRight instead. */
+    footer?: react__default.ReactNode | undefined;
+    /** Left-aligned footer content (use instead of `footer` for zoned layout) */
+    footerLeft?: react__default.ReactNode | undefined;
+    /** Center-aligned footer content */
+    footerCenter?: react__default.ReactNode | undefined;
+    /** Right-aligned footer content */
+    footerRight?: react__default.ReactNode | undefined;
+    /**
+     * Styling posture for the footer wrapper. Default `"bar"` applies the compact
+     * metadata-bar chrome (thin chips, `text-xs`, tiny buttons/icons via descendant
+     * selectors) tuned for status rows like `NoteMetadataBar`. That chrome CRUSHES
+     * rich content — use `"rich"` when the footer hosts a composer / input bar /
+     * anything with full-size buttons or a multi-row textarea (e.g. `SmartAgentInput`).
+     * `"rich"` drops the compact descendant selectors and the `bg-muted/40` chrome,
+     * leaving just `shrink-0 border-t` so the slot's own content owns its layout.
+     */
+    footerVariant?: "bar" | "rich" | undefined;
+    /**
+     * When true, the windowed panel sizes itself to fit its content rather than
+     * using the explicit width/height from Redux. A ResizeObserver syncs the
+     * measured dimensions back into Redux so drag/snap operations still work.
+     * The panel will still respect minWidth/minHeight constraints.
+     */
+    fitContent?: boolean | undefined;
+    /**
+     * Called by WindowPanel before a save so the child component can return
+     * its current content state for the local refresh-preservation cache.
+     * Return value must be a plain object (JSON-serializable).
+     */
+    onCollectData?: (() => Record<string, unknown>) | undefined;
+    /**
+     * Optional snapshot capture function for the minimized tray chip.
+     * WindowPanel invokes it after minimizing against a briefly retained,
+     * offscreen body and stores the resulting Blob in a bounded local cache.
+     * Pass this from the window component if it implements custom capture logic.
+     */
+    captureTraySnapshot?: TraySnapshotCapture | undefined;
+    /** Overlay instance used by semantic minimized previews. Defaults to `default`. */
+    overlayInstanceId?: string | undefined;
+}
+/**
+ * The close-binding contract — enforced by the type system.
+ *
+ * Every WindowPanel declares HOW it closes. Exactly three shapes are valid:
+ *
+ *   1. Overlay-managed: `overlayId`. Close dispatches `closeOverlay` for that overlay (and the
+ *      instance this window renders, when it renders inside an SummonHost instance or passes
+ *      `overlayInstanceId`). The close-lifecycle middleware tombstones preservation, disposes the
+ *      instance's handles and runs persistence flushers; the host then unmounts the body. `onClose`
+ *      is an OPTIONAL hook for extra work.
+ *   2. Instance-bound: `boundToOverlay` — the window renders inside an SummonHost-rendered overlay
+ *      and closes through that instance (`useOptionalOverlayInstance().close`). Rendering it outside
+ *      an overlay reports an error through the error port and the close button closes nothing.
+ *   3. Page-local: `onClose`, REQUIRED, because nothing else will close the window.
+ *
+ * Passing none of them is a compile error: the silent-failure mode where the X rendered as a dead
+ * button (matrx-frontend, Notes incident 2026-05-26). Do NOT make these all optional.
+ */
+type WindowPanelCloseBinding = {
+    overlayId: string;
+    boundToOverlay?: never | undefined;
+    /** Optional extra cleanup hook (cancel uploads, save drafts, etc.). */
+    onClose?: (() => void) | undefined;
+} | {
+    overlayId?: never | undefined;
+    /** Close through the enclosing SummonHost instance. */
+    boundToOverlay: true;
+    onClose?: (() => void) | undefined;
+} | {
+    overlayId?: never | undefined;
+    boundToOverlay?: never | undefined;
+    /** Required when the panel is rendered page-locally (no overlay). */
+    onClose: () => void;
+};
+type WindowPanelProps = WindowPanelBaseProps & WindowPanelCloseBinding;
+declare function WindowPanel({ children, title, titleNode, actions, actionsLeft, actionsRight, onClose, bodyClassName, className, mobilePresentationOverride, surfaceLayer, mobileSizeToContent, closeOnEscape, mobileHideClose, minWidth, minHeight, urlSyncKey, urlSyncId, urlSyncArgs, sidebar, sidebarDefaultSize, sidebarMinSize, defaultSidebarOpen, sidebarClassName, sidebarExpandsWindow, secondaryPanel, secondaryPanelOpen, secondaryPanelDefaultSize, secondaryPanelMinSize, secondaryPanelClassName, footer, footerLeft, footerCenter, footerRight, footerVariant, fitContent, overlayId: overlayIdProp, boundToOverlay, onCollectData, captureTraySnapshot, overlayInstanceId: overlayInstanceIdProp, hidePopOutButton, ...hookOpts }: WindowPanelProps): react__default.JSX.Element | null;
+
+interface WindowSidebarItem {
+    value: string;
+    label: string;
+    icon: react__default.ElementType;
+    description?: string | undefined;
+}
+interface WindowSidebarProps<T extends string = string> {
+    items: WindowSidebarItem[];
+    activeItem: T;
+    onSelect: (value: T) => void;
+    className?: string | undefined;
+}
+declare function WindowSidebar<T extends string = string>({ items, activeItem, onSelect, className, }: WindowSidebarProps<T>): react__default.JSX.Element;
+
+type LayoutIconType = "left-half" | "right-half" | "top-half" | "bottom-half" | "centre" | "full" | "grid4" | "grid6" | "grid8" | "grid9" | "grid12" | "stackLeft2" | "stackLeft3" | "stackLeft4" | "stackLeft5" | "stackRight2" | "stackRight3" | "stackRight4" | "stackRight5";
+declare function LayoutIcon({ type, className, }: {
+    type: LayoutIconType;
+    className?: string | undefined;
+}): react.JSX.Element;
+declare function LayoutIconButton({ onClick, type, className, }: {
+    onClick: () => void;
+    type: LayoutIconType;
+    className?: string | undefined;
+}): react.JSX.Element;
+
+/**
+ * Acknowledge a visible presentation that intentionally replaces WindowPanel.
+ *
+ * Registered singleton window overlays normally prove they are on screen by mounting a
+ * WindowPanel and registering geometry. Mobile drawers, sheets, and full-screen
+ * viewers have no window-manager geometry, so their composition root must use
+ * this hook while that alternate surface is active.
+ */
+declare function useOverlaySurfaceRenderAck(overlayId: string, active: boolean): void;
+
+/** Store a local snapshot blob for a window and notify subscribers. */
+declare function setTraySnapshot(id: string, blob: Blob): void;
+/** Clear the snapshot for a given window id. */
+declare function clearTraySnapshot(id: string): void;
+/** Read the snapshot for a given window id, or null. */
+declare function getTraySnapshot(id: string): string | null;
+/** Subscribe to map changes (useSyncExternalStore-shaped). */
+declare function subscribeTraySnapshotMap(listener: () => void): () => void;
+
+/**
+ * defaultTraySnapshotCapture — the fallback `captureTraySnapshot` for any window without a
+ * registered preview, so its minimized tile shows a small image of the real body.
+ *
+ * `html-to-image` is an OPTIONAL peer, loaded through ONE dynamic import on the first capture: a
+ * host that never installs it gets the labelled default tile (no error, no bundle cost).
+ *
+ * Performance contract (do not weaken when editing):
+ *  - Runs exactly ONCE per minimize, inside WindowPanel's timeout race. No polling, no network, no
+ *    storage — the Blob lands in the bounded object-URL cache (16 entries, revoked on restore).
+ *  - Oversized DOM subtrees are skipped (the clone pass is synchronous and would jank).
+ *  - Output is downscaled (320px longest edge, 1x pixel density) WebP.
+ */
+interface ElementThumbnailOptions {
+    /** Longest edge in px (min 64). Default 320. */
+    readonly maxEdge?: number;
+    /** WebP quality 0–1. Default 0.62. */
+    readonly quality?: number;
+}
+/** A small display-ready WebP thumbnail of one element, or null when html-to-image is absent. */
+declare function captureElementThumbnail(element: HTMLElement, options?: ElementThumbnailOptions): Promise<Blob | null>;
+declare function defaultTraySnapshotCapture(bodyEl: HTMLElement): Promise<Blob | null>;
+
+interface TrayChipPreviewProps {
+    /** Registry key — the overlay id for overlay-managed windows, else the runtime id. */
+    registryKey: string;
+    /** Unique runtime window id used for the local snapshot cache. */
+    snapshotKey: string;
+    overlayInstanceId?: string | undefined;
+    previewData?: Record<string, unknown> | undefined;
+    title: string;
+}
+declare const TrayChipPreview: react.MemoExoticComponent<({ registryKey, snapshotKey, overlayInstanceId, previewData, title, }: TrayChipPreviewProps) => react.JSX.Element>;
+
+interface MinimizedWindowContentProps {
+    /** Registry key — `overlayId` for overlay-managed windows, else runtime id. */
+    registryKey: string;
+    /** Unique runtime id for the local screenshot cache. */
+    snapshotKey: string;
+    overlayInstanceId?: string | undefined;
+    previewData?: Record<string, unknown> | undefined;
+    /** Window title; falls back to the registry label when not a plain string. */
+    title?: string | undefined;
+    /** Restore (un-minimize) the window. Wired to a click on the whole body. */
+    onRestore?: (() => void) | undefined;
+}
+declare function MinimizedWindowContent({ registryKey, snapshotKey, overlayInstanceId, previewData, title, onRestore, }: MinimizedWindowContentProps): react.JSX.Element;
+
+/**
+ * Severity scale, loudest-last. Maps onto the captured-error tiers but is
+ * intentionally generic so non-error windows can reuse it:
+ *   neutral  — inert / nothing notable (muted)
+ *   info     — active & healthy, "monitoring" (info token)
+ *   warning  — low / silent (yellow)
+ *   elevated — minor / worth a glance (amber)
+ *   critical — loud / needs attention (destructive red)
+ */
+type TrayStatusTone = "neutral" | "info" | "warning" | "elevated" | "critical";
+interface TrayStatusSegment {
+    count: number;
+    tone: TrayStatusTone;
+    /** Accessible/tooltip label, e.g. "clear errors". */
+    label?: string | undefined;
+}
+interface TrayStatusChipProps {
+    /** Icon component (any SVG icon taking className) — the glanceable identity/severity mark. */
+    icon: ComponentType<SVGAttributes<SVGSVGElement>>;
+    /** Overall severity — tints the icon (and the primary count). */
+    tone: TrayStatusTone;
+    /** Primary number. Omit (or pass undefined) to show only the caption. */
+    count?: number | undefined;
+    /** Shown when there's no count (e.g. the all-clear / idle state). */
+    caption?: string | undefined;
+    /** Per-tone breakdown. Only renders when 2+ entries are non-zero. */
+    segments?: TrayStatusSegment[] | undefined;
+    /** Pulse the icon (e.g. unseen activity since minimize). */
+    pulse?: boolean | undefined;
+}
+declare function TrayStatusChip({ icon: Icon, tone, count, caption, segments, pulse, }: TrayStatusChipProps): react.JSX.Element;
+
+type PopoutMode = "pip" | "popup";
+interface PopoutContextValue {
+    /**
+     * The popout `Document`. `null` when this subtree is rendered in the
+     * parent (the default).
+     */
+    popoutDocument: Document | null;
+    /**
+     * The popout `Window`. `null` when this subtree is rendered in the parent.
+     * Use for `addEventListener`, `matchMedia`, `innerWidth`, etc., when the
+     * popout-scoped answer is what you need.
+     */
+    popoutWindow: Window | null;
+    /**
+     * Element to use as the Radix `Portal.container` prop so floating UI
+     * (tooltips, popovers, dropdowns) renders inside the popout instead of
+     * the parent `document.body`. Returns `null` outside a popout —
+     * `usePopoutContainer` coerces this to `undefined` so Radix falls back
+     * to its default container automatically.
+     */
+    popoutContainer: HTMLElement | null;
+    /**
+     * Which popout mechanism is in use. `null` outside a popout.
+     * Currently only used for diagnostics; downstream components may branch
+     * on it later (e.g. show different chrome for `popup` vs `pip`).
+     */
+    mode: PopoutMode | null;
+}
+declare const PopoutContext: react.Context<PopoutContextValue>;
+/** Read the current popout context. Always defined — never throws. */
+declare function usePopout(): PopoutContextValue;
+
+declare function usePopoutContainer(): HTMLElement | undefined;
+
+interface OpenPopoutOptions {
+    width: number;
+    height: number;
+    title: string;
+}
+type OpenPopoutResult = {
+    ok: true;
+    mode: "pip" | "popup";
+} | {
+    ok: false;
+    reason: "pip-slot-taken" | "popup-blocked" | "no-capability" | "request-failed";
+};
+interface UsePopoutWindowReturn {
+    /**
+     * Open a popout for this window. MUST be called synchronously inside a
+     * user-gesture handler (pointerup, click, keydown) — otherwise the browser
+     * rejects the request.
+     */
+    openPopout(opts: OpenPopoutOptions): Promise<OpenPopoutResult>;
+    /**
+     * Programmatically close the popout. Triggers the same cleanup path as
+     * the user clicking the browser X button. Safe to call when there's no
+     * popout open.
+     */
+    close(): void;
+}
+declare function usePopoutWindow(windowId: string): UsePopoutWindowReturn;
+
+type OpenPopoutFn = (opts: OpenPopoutOptions) => Promise<OpenPopoutResult>;
+/** Get the live openPopout for a given window id, or null. */
+declare function getPopoutOpener(windowId: string): OpenPopoutFn | null;
+interface PopoutControlApi {
+    /**
+     * Pop out a specific window by its id. Must be called inside a
+     * user-gesture stack. Returns the same result shape as
+     * `usePopoutWindow.openPopout`. If the window isn't currently mounted,
+     * returns `{ ok: false, reason: "not-mounted" }`.
+     */
+    popOut(windowId: string, opts: OpenPopoutOptions): Promise<OpenPopoutResult | {
+        ok: false;
+        reason: "not-mounted";
+    }>;
+    /** Dock a popped-out window back into the parent viewport. */
+    dock(windowId: string): void;
+}
+declare function usePopoutControl(): PopoutControlApi;
+interface PopOutByIdOptions {
+    /** Falls back to 480 if not provided. */
+    width?: number | undefined;
+    /** Falls back to 320 if not provided. */
+    height?: number | undefined;
+    /** Falls back to "Window" if not provided. */
+    title?: string | undefined;
+}
+declare function buildPopoutOpts(rect: Partial<WindowRect> | undefined, opts: PopOutByIdOptions | undefined): OpenPopoutOptions;
+
+/** Get the popout window for a given id, or `null` if none is registered. */
+declare function getPopoutWindow(id: string): Window | null;
+/** Iterate over every currently-registered popout window. */
+declare function forEachPopoutWindow(cb: (win: Window, id: string) => void): void;
+/**
+ * Subscribe to map changes. Returns an unsubscribe function.
+ * Used internally by `usePopoutWindowRef` for `useSyncExternalStore`.
+ */
+declare function subscribePopoutWindowMap(listener: () => void): () => void;
+/**
+ * React hook: subscribe to the popout window for a given id and re-render
+ * when it changes. Returns the live `Window` reference or `null`.
+ *
+ * Uses `useSyncExternalStore` for tearing-free reads under React 19 strict
+ * mode and concurrent rendering.
+ */
+declare function usePopoutWindowRef(id: string): Window | null;
+
+/** Read all pending window ids (used on hydration to surface the toast). */
+declare function getPendingPopoutWindowIds(): string[];
+/** Clear ALL pending entries — used after surfacing the recovery toast. */
+declare function clearAllPopoutPending(): void;
+
+/**
+ * Feature detection for the window-panels pop-out system.
+ *
+ * Three capability tiers, in order of preference:
+ *
+ * 1. **`"pip"`** — Document Picture-in-Picture API (Chromium-based browsers,
+ *    Chrome 116+, Edge 116+, Opera). Frameless, always-on-top floating window.
+ *    Detected by presence of `window.documentPictureInPicture.requestWindow`.
+ *
+ * 2. **`"popup"`** — `window.open()` fallback (Safari, Firefox, anything else).
+ *    Universal browser support. Shows browser chrome (URL bar, tabs).
+ *    Acceptable degradation: user still gets a separate window for multi-
+ *    monitor workflows.
+ *
+ * 3. **`"none"`** — Embedded WebViews or other contexts where neither API is
+ *    available (rare). The "Pop out" affordance should be hidden entirely.
+ *
+ * The detection is intentionally simple and synchronous — it runs once on
+ * the client at component mount time and the result is stable for the
+ * lifetime of the page.
+ *
+ * SSR safety: every code path branches on `typeof window` first.
+ */
+type PopoutCapability = "pip" | "popup" | "none";
+/**
+ * Returns the highest-fidelity popout mechanism available in the current
+ * browser. Safe to call during SSR (returns `"none"`).
+ */
+declare function detectPopoutCapability(): PopoutCapability;
+/**
+ * True when the browser supports Document Picture-in-Picture (the preferred
+ * popout mode). Convenience wrapper around `detectPopoutCapability()` for
+ * use in conditional rendering and feature flags.
+ */
+declare function supportsDocumentPictureInPicture(): boolean;
+/**
+ * True when popout is available in any form (DPiP or popup).
+ * Use this to decide whether to show the "Pop out" affordance at all.
+ */
+declare function supportsAnyPopout(): boolean;
+
+/**
+ * popoutDragDetector — pure logic for "is the user dragging this window
+ * out of the viewport hard enough to mean they want to pop it out?"
+ *
+ * **Threshold strategy:**
+ *   1. Cursor must cross outside the viewport rect, AND
+ *   2. Cursor must be at least `outsideThreshold` pixels past the edge
+ *      (a deliberate intent signal, not a stray mouse twitch), AND
+ *   3. Cursor must DWELL outside for at least `dwellMs` milliseconds
+ *      (filters out drags that just transit through the edge en route
+ *      to a different on-screen position).
+ *
+ * The dwell timer resets every time the cursor crosses back inside the
+ * viewport — a glance outside doesn't latch the candidate state.
+ *
+ * **Return shape:**
+ *   - `state` — the next `DragOutState` (replaces the previous on the next call)
+ *   - `shouldTrigger` — true when the dwell threshold has just been met. The
+ *     caller should fire popout on `pointerup`, NOT on this flag — the flag
+ *     is purely for animation/visual feedback (`isCandidate`).
+ *
+ * Pure function: no DOM access, no side effects. Easy to unit test.
+ */
+interface DragOutConfig {
+    /** Pixels past the viewport edge before considering the drag "outside". */
+    outsideThreshold: number;
+    /** Milliseconds the cursor must remain outside before becoming a candidate. */
+    dwellMs: number;
+}
+interface DragOutState {
+    /** Whether the dwell threshold is currently met (drives visual feedback). */
+    isCandidate: boolean;
+    /**
+     * `performance.now()` timestamp when the cursor first crossed `outsideThreshold`.
+     * `null` when the cursor is currently inside (or hasn't been outside yet).
+     */
+    outsideSinceMs: number | null;
+}
+interface DragOutInput {
+    clientX: number;
+    clientY: number;
+}
+interface DragOutEvalResult {
+    state: DragOutState;
+    /**
+     * Edge-trigger: `true` ONLY on the first call where `isCandidate` flips
+     * from `false` to `true`. Useful if a caller wants to dispatch a one-shot
+     * action (e.g. haptic) on candidate entry.
+     */
+    shouldTrigger: boolean;
+}
+declare const DEFAULT_DRAG_OUT_CONFIG: DragOutConfig;
+declare const INITIAL_DRAG_OUT_STATE: DragOutState;
+/**
+ * Evaluate one pointermove event against the previous drag-out state.
+ *
+ * @param e   Pointer event coords (clientX/clientY are viewport-relative)
+ * @param prev Previous state from the last call (or `INITIAL_DRAG_OUT_STATE`)
+ * @param cfg Threshold config
+ * @param vpW Current `window.innerWidth`
+ * @param vpH Current `window.innerHeight`
+ * @param now Current `performance.now()` reading
+ */
+declare function evaluateDragOut(e: DragOutInput, prev: DragOutState, cfg: DragOutConfig, vpW: number, vpH: number, now: number): DragOutEvalResult;
+
+interface MobileDrawerSurfaceProps {
+    title: ReactNode;
+    children: ReactNode;
+    onClose: () => void;
+    sidebar?: ReactNode | undefined;
+    footer?: ReactNode | undefined;
+    /** Open state — mirrors the parent's overlay-isOpen flag. */
+    isOpen: boolean;
+    actionsLeft?: ReactNode | undefined;
+    actionsRight?: ReactNode | undefined;
+    /** Optional className applied to the body scroll container. */
+    bodyClassName?: string | undefined;
+    /** Marks the root `data-surface-layer` (see WindowPanel `surfaceLayer`). */
+    surfaceLayer?: string | undefined;
+    /**
+     * Size the sheet to its content (capped at 85dvh) instead of a fixed 85dvh:
+     * a short form no longer sits on a band of empty sheet.
+     */
+    sizeToContent?: boolean | undefined;
+    /** No title-row ✕: the drag handle and the window's own Cancel dismiss it. */
+    hideClose?: boolean | undefined;
+    /**
+     * Whether the sidebar should collapse into a nested drawer when the user
+     * taps the sidebar toggle. When "inline", the sidebar pushes the body
+     * instead. Default: "drawer".
+     */
+    sidebarAs?: "drawer" | "inline" | undefined;
+}
+declare function MobileDrawerSurface({ title, children, onClose, sidebar, footer, isOpen, actionsLeft, actionsRight, bodyClassName, surfaceLayer, sizeToContent, hideClose, sidebarAs, }: MobileDrawerSurfaceProps): react.JSX.Element;
+
+interface MobileCardSurfaceProps {
+    title: ReactNode;
+    children: ReactNode;
+    onClose: () => void;
+    footer?: ReactNode | undefined;
+    isOpen: boolean;
+    actionsRight?: ReactNode | undefined;
+    bodyClassName?: string | undefined;
+    /** Marks the root `data-surface-layer` (see WindowPanel `surfaceLayer`). */
+    surfaceLayer?: string | undefined;
+    /** Override the default max-height (60dvh). Accepts any CSS length. */
+    maxHeight?: string | undefined;
+}
+declare function MobileCardSurface({ title, children, onClose, footer, isOpen, actionsRight, bodyClassName, surfaceLayer, maxHeight, }: MobileCardSurfaceProps): react.ReactPortal | null;
+
+/** Two lines, then an ellipsis — never a one-line `truncate`. */
+declare const MOBILE_WINDOW_TITLE_TEXT = "line-clamp-2 break-words text-sm font-medium leading-snug text-foreground";
+/**
+ * The title slot's classes. A text title wraps to two lines; a RICH title (a
+ * control, e.g. the Chat window's agent picker) keeps its own layout. Exported
+ * for a host whose title element is fixed (the drawer's accessible
+ * `DrawerTitle`) — put these classes and `data-window-mobile-title` on it.
+ */
+declare function mobileWindowTitleClass(title: ReactNode): string;
+/** The title slot. */
+declare function MobileWindowTitle({ title, className, }: {
+    title: ReactNode;
+    className?: string | undefined;
+}): react.JSX.Element;
+/** Row 1: whatever leads (close / minimize) and the title, nothing else. */
+declare function MobileWindowTitleRow({ leading, trailing, children, className, }: {
+    leading?: ReactNode | undefined;
+    /** A close ✕ only — never window actions. */
+    trailing?: ReactNode | undefined;
+    children: ReactNode;
+    className?: string | undefined;
+}): react.JSX.Element;
+/** Row 2: pane toggle + window actions. Absent when both are empty. */
+declare function MobileWindowActionsRow({ leading, actions, className, }: {
+    leading?: ReactNode | undefined;
+    actions?: ReactNode | undefined;
+    className?: string | undefined;
+}): react.JSX.Element | null;
+
+/**
+ * AUTO-OPENED WINDOW PLACEMENT (MKT-104, Arman 2026-10-15).
+ *
+ * Some windows open by themselves (debug mode's Workflow run + Watch AI windows) so a person can
+ * watch progress live. They must NEVER cover the page's working column or take its clicks. This
+ * is the ONE place that decides where such a window goes, for every window that is opened by the
+ * system rather than by a person:
+ *
+ *   1. The caller marks the open with `markAutoOpened(overlayId, instanceId)` (see
+ *      `features/overlays/openers/openAutoOverlay.ts`); `WindowPanel` consumes the mark.
+ *   2. The working column is measured from the page itself: the bounds of every visible control
+ *      (button, link, field) in the page body. Anything outside that box takes no clicks anyway.
+ *   3. The window is docked in the widest free side gutter, shrunk to fit, stacked under any other
+ *      auto-opened window already there. No gutter wide enough (a narrow screen, a page that
+ *      fills the width) → it is not opened (`autoOpenHasRoom`), or, when the page grew under it,
+ *      it closes itself. A person's own press of Watch AI / Workflow run always opens it.
+ *
+ * Pure module: no Redux import (WindowPanel stays a leaf).
+ */
+
+/** Narrowest window worth docking; anything tighter goes to the tray. */
+declare const AUTO_OPEN_MIN_WIDTH = 280;
+/** Call BEFORE dispatching the open of a window the system (not a person) opens. */
+declare function markAutoOpened(overlayId: string, instanceId: string): void;
+/** Peek (does not consume, so StrictMode's double render sees the same answer). */
+declare function isAutoOpened(overlayId: string, instanceId: string): boolean;
+/** Forget the mark once the window is gone: a person's later reopen places normally. */
+declare function clearAutoOpened(overlayId: string, instanceId: string): void;
+/** Left/right edge of everything on the page body that takes a click. */
+declare function measureWorkingColumn(): {
+    left: number;
+    right: number;
+} | null;
+/** Fired (detail `{ overlayId, instanceId }`) when a docked auto-opened window closes itself for lack of room. */
+declare const AUTO_OPEN_NO_ROOM_EVENT = "matrx:auto-open-no-room";
+/**
+ * True when a gutter beside the page's working column can hold an auto-opened window right now.
+ * Callers that open windows by themselves check this FIRST: with no room the window is not opened
+ * (a parked tray tile sits over the page's own bottom-right controls — MKT-104).
+ */
+declare function autoOpenHasRoom(): boolean;
+interface AutoOpenPlacement {
+    rect: WindowRect;
+    /** True when no gutter fits: open parked in the tray instead of over the page. */
+    minimized: boolean;
+}
+/**
+ * @param siblings rects of auto-opened windows already docked (to stack under them)
+ */
+declare function resolveAutoOpenPlacement(args: {
+    width: number;
+    height: number;
+    minWidth: number;
+    minHeight: number;
+    top: number;
+    viewport: {
+        vw: number;
+        vh: number;
+    };
+    siblings: WindowRect[];
+}): AutoOpenPlacement;
+
+type UnbiddenRefusalCode = 
+/** The registry entry declares no `unbiddenHome` (or there is no entry). */
+"no-declared-home"
+/** It has a home; the viewer is not on it. Try again when they are. */
+ | "away-from-home";
+interface UnbiddenRaiseVerdict {
+    /** True only when this window may raise itself, here, right now. */
+    allowed: boolean;
+    /** Plain-English why, for logs and for the caller's own warning. */
+    reason: string;
+    /** Set only when `allowed` is false. */
+    code?: UnbiddenRefusalCode | undefined;
+    /** The routes this window declared as home, for diagnostics (exact ones end in " (exact)"). */
+    home: readonly string[];
+}
+/**
+ * True when `pathname` is `route` itself or a page nested under it.
+ * `/administration` covers `/administration/spend`; it does not cover
+ * `/administration-archive`.
+ */
+declare function isUnderRoute(pathname: string, route: string): boolean;
+/**
+ * May this window raise ITSELF — with nobody having clicked anything — while
+ * the viewer is on `pathname`?
+ *
+ * Refusals are announced, never swallowed: a window with no declared home
+ * warns (that is a registry bug someone must fix), and an away-from-home
+ * deferral logs at info (that is the system working as designed).
+ */
+declare function mayRaiseUnbidden(overlayId: string, pathname: string | null | undefined): UnbiddenRaiseVerdict;
+
+/**
+ * Warn when `moduleId` is evaluated during boot. `report` replaces the default console warning
+ * (route it to the host's error sink).
+ */
+declare function assertLazyLoaded(moduleId: string, report?: (message: string, stack: string) => void): void;
+
+declare function sanitizeWindowData(value: unknown, allowedKeys: readonly string[]): Record<string, unknown>;
+
+export { AUTO_OPEN_MIN_WIDTH, AUTO_OPEN_NO_ROOM_EVENT, type AutoOpenPlacement, DEFAULT_DRAG_OUT_CONFIG, type DragOutConfig, type DragOutEvalResult, type DragOutInput, type DragOutState, type ElementThumbnailOptions, INITIAL_DRAG_OUT_STATE, LayoutIcon, LayoutIconButton, type LayoutIconType, MOBILE_WINDOW_TITLE_TEXT, MinimizedWindowContent, MobileCardSurface, MobileDrawerSurface, MobileWindowActionsRow, MobileWindowTitle, MobileWindowTitleRow, type OpenPopoutOptions, type OpenPopoutResult, type PopOutByIdOptions, type PopoutCapability, PopoutContext, type PopoutContextValue, type PopoutControlApi, type PopoutMode, type ResizeEdge, TrayChipPreview, TrayStatusChip, type TrayStatusChipProps, type TrayStatusSegment, type TrayStatusTone, type UnbiddenRaiseVerdict, type UnbiddenRefusalCode, type UsePopoutWindowReturn, type UseWindowPanelOptions, type UseWindowPanelReturn, WindowPanel, type WindowPanelBaseProps, type WindowPanelCloseBinding, type WindowPanelProps, type WindowPosition, WindowSidebar, type WindowSidebarItem, assertLazyLoaded, autoOpenHasRoom, buildPopoutOpts, captureElementThumbnail, clearAllPopoutPending, clearAutoOpened, clearTraySnapshot, defaultTraySnapshotCapture, detectPopoutCapability, evaluateDragOut, forEachPopoutWindow, getPendingPopoutWindowIds, getPopoutOpener, getPopoutWindow, getTraySnapshot, isAutoOpened, isUnderRoute, markAutoOpened, mayRaiseUnbidden, measureWorkingColumn, mobileWindowTitleClass, resetDefaultWindowCascade, resolveAutoOpenPlacement, resolvePosition, sanitizeWindowData, setTraySnapshot, subscribePopoutWindowMap, subscribeTraySnapshotMap, supportsAnyPopout, supportsDocumentPictureInPicture, useOverlaySurfaceRenderAck, usePopout, usePopoutContainer, usePopoutControl, usePopoutWindow, usePopoutWindowRef, useWindowPanel };