@nextclaw/ui 0.25.4 → 0.26.0

package/src/shared/components/doc-browser/use-doc-link-interceptor.ts

@@ -1,36 +1,34 @@
 import { useEffect } from 'react';
-import { isDocsUrl, useDocBrowser } from './doc-browser-context';
+import { useNavigate } from 'react-router-dom';
+import { useAppPresenter } from '@/app/components/app-presenter-provider';
+import { isDocsUrl } from './doc-browser-context';
+import { toast } from 'sonner';
+import { t } from '@/shared/lib/i18n';
 
-/**
- * Global click interceptor for docs links.
- * Captures clicks on <a> tags pointing to the docs domain
- * and opens them in the in-app micro-browser instead.
- */
+/** Resource links use the same opening policy as navigation and page menus. */
 export function useDocLinkInterceptor() {
-    const docBrowser = useDocBrowser();
-
-    useEffect(() => {
-        const handler = (e: MouseEvent) => {
-            // Walk up from the click target to find an anchor
-            const anchor = (e.target as HTMLElement).closest<HTMLAnchorElement>('a[href]');
-            if (!anchor) return;
-
-            const href = anchor.getAttribute('href') || '';
-            if (!isDocsUrl(href)) return;
-
-            // Don't intercept links explicitly marked for external opening
-            if (anchor.hasAttribute('data-doc-external')) return;
-
-            // Don't intercept if modifier keys are held (user wants new tab behavior)
-            if (e.ctrlKey || e.metaKey || e.shiftKey) return;
-
-            e.preventDefault();
-            e.stopPropagation();
-            docBrowser.open(href);
-        };
-
-        // Use capture phase to intercept before React's synthetic events
-        document.addEventListener('click', handler, true);
-        return () => document.removeEventListener('click', handler, true);
-    }, [docBrowser]);
+  const app = useAppPresenter();
+  const navigate = useNavigate();
+  useEffect(() => {
+    const handler = (event: MouseEvent) => {
+      if (event.defaultPrevented || event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;
+      const anchor = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>('a[href]') : null;
+      if (!anchor || anchor.hasAttribute('data-doc-external') || anchor.hasAttribute('download')) return;
+      const href = anchor.getAttribute('href') ?? '';
+      if (!href.startsWith('nextclaw://') && !isDocsUrl(href)) return;
+      event.preventDefault();
+      event.stopPropagation();
+      const origin = anchor.closest<HTMLElement>('[data-resource-session]');
+      const page = app.pageResourceManager.resolve(href, { workingDir: origin?.dataset.resourceWorkingDir, sessionKey: origin?.dataset.resourceSession });
+      if (page) {
+        const label = anchor.cloneNode(true) as HTMLAnchorElement;
+        label.querySelectorAll('[aria-hidden="true"]').forEach((element) => element.remove());
+        const title = label.textContent?.trim();
+        app.pageResourceManager.open(title ? { ...page, title, target: { ...page.target, title } } : page, 'default', navigate);
+      }
+      else toast.error(t('pageUnavailable'));
+    };
+    document.addEventListener('click', handler, true);
+    return () => document.removeEventListener('click', handler, true);
+  }, [app, navigate]);
 }

package/src/shared/components/doc-browser/utils/doc-browser-state.utils.ts

@@ -13,6 +13,7 @@ import {
   DOC_BROWSER_HOME_URL,
   inferTabTitle,
 } from './doc-browser-url.utils';
+import { pushNavigationHistoryEntry } from '@/shared/lib/navigation-history';
 import { t } from '@/shared/lib/i18n';
 import {
   createUiContentParamsWindowName,
@@ -44,6 +45,7 @@ export function createDocBrowserTab(
   resourceUri?: string,
   dockIcon?: DocBrowserDockIcon,
   contentParams?: UiContentParams,
+  viewState?: unknown,
 ): DocBrowserTab {
   const tabTitle = title?.trim() || inferTabTitle(url, kind, kind === 'docs' ? t('docBrowserHelp') : 'Detail');
   const normalizedResourceUri = resourceUri?.trim();
@@ -55,6 +57,7 @@ export function createDocBrowserTab(
     currentUrl: url,
     resourceUri: normalizedResourceUri ? normalizedResourceUri : undefined,
     contentParams,
+    viewState,
     dockIcon,
     dedupeKey,
     history: [url],
@@ -67,11 +70,8 @@ export function appendManualNavigation(
   tab: DocBrowserTab,
   url: string,
 ): Pick<DocBrowserTab, 'history' | 'historyIndex'> {
-  const history = [...tab.history.slice(0, tab.historyIndex + 1), url];
-  return {
-    history,
-    historyIndex: history.length - 1,
-  };
+  const next = pushNavigationHistoryEntry({ entries: tab.history, index: tab.historyIndex }, url);
+  return { history: [...next.entries], historyIndex: next.index };
 }
 
 export function updateTabForOpen(
@@ -89,6 +89,7 @@ export function updateTabForOpen(
     dockIcon: options?.dockIcon ?? target.dockIcon,
     dedupeKey,
     contentParams: target.contentParams,
+    viewState: options?.viewState ?? target.viewState ?? tab.viewState,
   };
   const hasSameUrl = routeResolver.areUrlsEquivalent(
     tab.currentUrl,
@@ -130,7 +131,6 @@ export function createDefaultDocBrowserState(): DocBrowserState {
   const initialTab = createDocBrowserTab(DOC_BROWSER_HOME_URL, DOC_BROWSER_HOME_TAB_KIND, t('docBrowserHomeTitle'));
   return {
     isOpen: false,
-    mode: 'docked',
     dockedWidth: DOC_BROWSER_DOCKED_DEFAULT_WIDTH,
     tabs: [initialTab],
     activeTabId: initialTab.id,

package/src/shared/components/ui/context-menu/__tests__/context-menu.test.tsx

@@ -4,6 +4,28 @@ import { describe, expect, it, vi } from 'vitest';
 import { ContextMenu, ContextMenuTrigger } from '@/shared/components/ui/context-menu/context-menu';
 
 describe('ContextMenu', () => {
+  it('keeps modal actions inside the dialog focus boundary and consumes Escape', async () => {
+    const onSelect = vi.fn();
+    const onDialogKeyDown = vi.fn();
+    render(
+      <div role="dialog" onKeyDown={onDialogKeyDown}>
+        <ContextMenu label="Resource actions" groups={[{ key: 'open', items: [{ key: 'open', label: 'Open resource', onSelect }] }]}>
+          <div><ContextMenuTrigger><button type="button">Actions</button></ContextMenuTrigger></div>
+        </ContextMenu>
+      </div>,
+    );
+    await userEvent.click(screen.getByRole('button', { name: 'Actions' }));
+    const menu = screen.getByRole('menu');
+    expect(menu.closest('[role="dialog"]')).toBe(screen.getByRole('dialog'));
+    expect(menu.parentElement?.className).toContain('pointer-events-auto');
+    await userEvent.keyboard('{Escape}');
+    expect(screen.queryByRole('menu')).toBeNull();
+    expect(onDialogKeyDown).not.toHaveBeenCalled();
+    await userEvent.click(screen.getByRole('button', { name: 'Actions' }));
+    await userEvent.click(screen.getByRole('menuitem', { name: 'Open resource' }));
+    expect(onSelect).toHaveBeenCalledOnce();
+  });
+
   it('opens at the trigger and supports keyboard selection', async () => {
     const onSelect = vi.fn();
     render(

package/src/shared/components/ui/context-menu/context-menu.tsx

@@ -18,6 +18,7 @@ type ContextMenuItemBase = {
   icon?: ReactNode;
   destructive?: boolean;
   disabled?: boolean;
+  pressed?: boolean;
   restoreFocus?: boolean;
 };
 
@@ -68,26 +69,31 @@ function ContextMenuSurface({
   position: ContextMenuPosition;
 }) {
   const menuRef = useRef<HTMLDivElement | null>(null);
+  // Keep modal menus inside the dialog's focus and pointer-event boundary.
+  const portalHost = position.trigger.closest<HTMLElement>('[role="dialog"]') ?? document.body;
+  const isModal = portalHost !== document.body;
 
   useLayoutEffect(() => {
     const menu = menuRef.current;
     if (!menu) {
       return;
     }
+    const bounds = isModal ? portalHost.getBoundingClientRect() : { left: 0, top: 0, right: window.innerWidth, bottom: window.innerHeight, height: window.innerHeight };
+    menu.style.maxHeight = `${Math.max(0, bounds.height - CONTEXT_MENU_EDGE_GAP * 2)}px`;
     const rect = menu.getBoundingClientRect();
     const preferredLeft = position.align === 'end' ? position.x - rect.width : position.x;
     const left = Math.max(
-      CONTEXT_MENU_EDGE_GAP,
-      Math.min(preferredLeft, window.innerWidth - rect.width - CONTEXT_MENU_EDGE_GAP),
+      bounds.left + CONTEXT_MENU_EDGE_GAP,
+      Math.min(preferredLeft, bounds.right - rect.width - CONTEXT_MENU_EDGE_GAP),
     );
     const top = Math.max(
-      CONTEXT_MENU_EDGE_GAP,
-      Math.min(position.y, window.innerHeight - rect.height - CONTEXT_MENU_EDGE_GAP),
+      bounds.top + CONTEXT_MENU_EDGE_GAP,
+      Math.min(position.y, bounds.bottom - rect.height - CONTEXT_MENU_EDGE_GAP),
     );
-    menu.style.left = `${left}px`;
-    menu.style.top = `${top}px`;
+    menu.style.left = `${left - bounds.left}px`;
+    menu.style.top = `${top - bounds.top}px`;
     menu.querySelector<HTMLElement>('[role="menuitem"]:not(:disabled)')?.focus();
-  }, [position]);
+  }, [position, portalHost, isModal]);
 
   const moveFocus = (direction: 1 | -1) => {
     const items = Array.from(menuRef.current?.querySelectorAll<HTMLElement>('[role="menuitem"]:not(:disabled)') ?? []);
@@ -101,7 +107,7 @@ function ContextMenuSurface({
 
   return createPortal(
     <div
-      className="fixed inset-0 z-[var(--z-tooltip)]"
+      className={cn("pointer-events-auto inset-0 z-[var(--z-tooltip)]", isModal ? "absolute" : "fixed")}
       onContextMenu={(event) => event.preventDefault()}
       onPointerDown={() => onClose(true)}
     >
@@ -110,12 +116,13 @@ function ContextMenuSurface({
         role="menu"
         data-theme-overlay="menu"
         aria-label={label}
-        className="fixed min-w-52 max-w-72 overflow-hidden rounded-xl border border-border bg-popover p-1 text-popover-foreground shadow-[0_18px_48px_-20px_rgba(15,23,42,0.42)]"
+        className={cn("min-w-52 max-w-72 overflow-y-auto rounded-xl border border-border bg-popover p-1 text-popover-foreground shadow-[0_18px_48px_-20px_rgba(15,23,42,0.42)]", isModal ? "absolute" : "fixed")}
         style={{ left: position.x, top: position.y }}
         onPointerDown={(event) => event.stopPropagation()}
         onKeyDown={(event) => {
           if (event.key === 'Escape') {
             event.preventDefault();
+            event.stopPropagation();
             onClose(true);
           } else if (event.key === 'ArrowDown') {
             event.preventDefault();
@@ -176,6 +183,7 @@ function ContextMenuSurface({
                   type="button"
                   role="menuitem"
                   disabled={item.disabled}
+                  aria-pressed={item.pressed}
                   className={itemClassName}
                   onClick={() => {
                     item.onSelect?.();
@@ -190,7 +198,7 @@ function ContextMenuSurface({
         ))}
       </div>
     </div>,
-    document.body,
+    portalHost,
   );
 }
 

package/src/shared/components/workbench/__tests__/workbench-surface.manager.test.ts

@@ -0,0 +1,70 @@
+import { beforeEach, expect, it } from "vitest";
+import { WorkbenchSurfaceManager } from "@/shared/components/workbench/managers/workbench-surface.manager";
+import { useWorkbenchSurfaceStore } from "@/shared/components/workbench/stores/workbench-surface.store";
+import { resizeWorkbenchRect } from "@/shared/components/workbench/utils/workbench-surface-geometry.utils";
+
+const manager = new WorkbenchSurfaceManager();
+beforeEach(() => useWorkbenchSurfaceStore.setState({ surfaces: {} }));
+
+it("keeps geometry and placement through maximize, collapse and restore", () => {
+  manager.place("file", "floating");
+  manager.move("file", manager.get("file").rect, 100, 20, {
+    width: 1400,
+    height: 1000,
+  });
+  const { rect } = manager.get("file");
+  manager.toggleMaximize("file");
+  expect(manager.get("file")).toMatchObject({
+    maximized: true,
+    placement: "floating",
+    rect,
+  });
+  manager.toggleMaximize("file");
+  manager.minimize("file");
+  manager.restore("file");
+  expect(manager.get("file")).toMatchObject({
+    minimized: false,
+    maximized: false,
+    rect,
+  });
+  manager.place("file", "docked");
+  manager.place("file", "floating");
+  expect(manager.get("file").rect).toEqual(rect);
+});
+
+it("isolates scopes, orders focused windows and constrains after viewport shrink", () => {
+  manager.place("global", "floating");
+  manager.place("session", "floating");
+  manager.focus("global");
+  expect(manager.get("global").layer).toBeGreaterThan(
+    manager.get("session").layer,
+  );
+  manager.minimize("global");
+  expect(manager.get("session").minimized).toBe(false);
+  manager.constrain("global", { width: 280, height: 200 });
+  const { rect } = manager.get("global");
+  expect(rect.x).toBeGreaterThanOrEqual(0);
+  expect(rect.x + rect.w).toBeLessThanOrEqual(280);
+  expect(rect.y + rect.h).toBeLessThanOrEqual(200);
+});
+
+it("anchors the opposite edge when resizing from left or top", () => {
+  const rect = { x: 100, y: 100, w: 560, h: 640 };
+  const next = resizeWorkbenchRect(rect, "top-left", 30, 40, {
+    width: 1400,
+    height: 1000,
+  });
+  expect(next.x + next.w).toBe(rect.x + rect.w);
+  expect(next.y + next.h).toBe(rect.y + rect.h);
+});
+
+it("reloads validated layout without reviving transient maximized or collapsed state", async () => {
+  manager.place("global", "floating");
+  manager.minimize("global");
+  await useWorkbenchSurfaceStore.persist.rehydrate();
+  expect(manager.get("global")).toMatchObject({
+    placement: "floating",
+    minimized: false,
+    maximized: false,
+  });
+});

package/src/shared/components/workbench/__tests__/workbench-surface.test.tsx

@@ -0,0 +1,111 @@
+import { act, fireEvent, render, screen, within } from "@testing-library/react";
+import { beforeEach, expect, it, vi } from "vitest";
+import { WorkbenchSurface } from "@/shared/components/workbench/workbench-surface";
+import { WorkbenchSurfaceManager } from "@/shared/components/workbench/managers/workbench-surface.manager";
+import { useWorkbenchSurfaceStore } from "@/shared/components/workbench/stores/workbench-surface.store";
+
+const manager = new WorkbenchSurfaceManager();
+beforeEach(() => {
+  useWorkbenchSurfaceStore.setState({ surfaces: {} });
+  Object.defineProperty(window, "innerWidth", {
+    configurable: true,
+    value: 1200,
+  });
+});
+
+it("retains the exact input and iframe nodes through every presentation transition and hiding", () => {
+  const props = {
+    id: "resource",
+    title: "Resource",
+    manager,
+    onClose: vi.fn(),
+  };
+  const content = (
+    <>
+      <textarea aria-label="Draft" defaultValue="Keep me" />
+      <iframe title="App" src="about:blank" />
+    </>
+  );
+  const view = render(
+    <WorkbenchSurface {...props}>{content}</WorkbenchSurface>,
+  );
+  const input = screen.getByRole("textbox");
+  const iframe = screen.getByTitle("App");
+  for (const action of [
+    "Float view group",
+    "Maximize",
+    "Restore size",
+    "Collapse view",
+    "Expand view",
+    "Dock to sidebar",
+  ]) {
+    fireEvent.click(screen.getByRole("button", { name: action }));
+    expect(input.isConnected).toBe(true);
+    expect(iframe.isConnected).toBe(true);
+    expect(view.container.querySelector("textarea")).toBe(input);
+    expect(view.container.querySelector("iframe")).toBe(iframe);
+  }
+  view.rerender(
+    <WorkbenchSurface {...props} hidden>
+      {content}
+    </WorkbenchSurface>,
+  );
+  expect(screen.queryByRole("textbox")).toBeNull();
+  view.rerender(<WorkbenchSurface {...props}>{content}</WorkbenchSurface>);
+  expect(screen.getByRole("textbox")).toBe(input);
+});
+
+it("restores size before collapsing on Escape and keeps close separate", () => {
+  const onClose = vi.fn();
+  manager.place("resource", "floating");
+  render(
+    <WorkbenchSurface
+      id="resource"
+      manager={manager}
+      title="Resource"
+      onClose={onClose}
+    >
+      <textarea />
+    </WorkbenchSurface>,
+  );
+  fireEvent.click(screen.getByRole("button", { name: "Maximize" }));
+  fireEvent.keyDown(screen.getByRole("textbox"), { key: "Escape" });
+  expect(manager.get("resource")).toMatchObject({
+    minimized: false,
+    maximized: false,
+  });
+  fireEvent.keyDown(screen.getByRole("textbox"), { key: "Escape" });
+  expect(manager.get("resource").minimized).toBe(true);
+  expect(onClose).not.toHaveBeenCalled();
+  fireEvent.click(screen.getByRole("button", { name: "Close view" }));
+  expect(onClose).toHaveBeenCalledOnce();
+});
+
+it("offers keyboard resize and a compact viewport without unusable desktop controls", () => {
+  const onWidthCommit = vi.fn();
+  render(
+    <WorkbenchSurface
+      id="resource"
+      manager={manager}
+      title="Resource"
+      onClose={vi.fn()}
+      width={480}
+      onWidthCommit={onWidthCommit}
+    >
+      <input />
+    </WorkbenchSurface>,
+  );
+  fireEvent.keyDown(screen.getByRole("separator"), { key: "ArrowLeft" });
+  expect(onWidthCommit).toHaveBeenCalledWith(504);
+  act(() => {
+    Object.defineProperty(window, "innerWidth", {
+      configurable: true,
+      value: 375,
+    });
+    window.dispatchEvent(new Event("resize"));
+  });
+  const region = screen.getByRole("region");
+  expect(region.style.position).toBe("fixed");
+  expect(within(region).queryByRole("button", { name: "Maximize" })).toBeNull();
+  expect(within(region).queryByRole("separator")).toBeNull();
+});

package/src/shared/components/workbench/managers/workbench-surface.manager.ts

@@ -0,0 +1,120 @@
+import { useWorkbenchSurfaceStore } from "@/shared/components/workbench/stores/workbench-surface.store";
+import {
+  DEFAULT_WORKBENCH_SURFACE,
+  type WorkbenchPlacement,
+  type WorkbenchRect,
+  type WorkbenchResizeEdge,
+  type WorkbenchSurfaceState,
+  type WorkbenchViewport,
+} from "@/shared/components/workbench/types/workbench-surface.types";
+import {
+  constrainWorkbenchRect,
+  resizeWorkbenchRect,
+} from "@/shared/components/workbench/utils/workbench-surface-geometry.utils";
+
+export class WorkbenchSurfaceManager {
+  isVisible = (id: string): boolean =>
+    useWorkbenchSurfaceStore.getState().visibleSurfaceIds.includes(id);
+
+  setVisible = (id: string, visible: boolean): void => {
+    useWorkbenchSurfaceStore.setState(({ visibleSurfaceIds }) => ({
+      visibleSurfaceIds: visible
+        ? [...new Set([...visibleSurfaceIds, id])]
+        : visibleSurfaceIds.filter((key) => key !== id),
+    }));
+  };
+
+  get = (id: string): WorkbenchSurfaceState =>
+    useWorkbenchSurfaceStore.getState().surfaces[id] ??
+    DEFAULT_WORKBENCH_SURFACE;
+
+  private update = (
+    id: string,
+    patch: Partial<WorkbenchSurfaceState>,
+  ): void => {
+    useWorkbenchSurfaceStore.setState(({ surfaces }) => ({
+      surfaces: { ...surfaces, [id]: { ...this.get(id), ...patch } },
+    }));
+  };
+
+  place = (id: string, placement: WorkbenchPlacement): void => {
+    this.update(id, { placement, minimized: false, maximized: false });
+    this.focus(id);
+  };
+
+  minimize = (id: string): void =>
+    this.update(id, { minimized: true, maximized: false });
+  restore = (id: string): void => this.update(id, { minimized: false });
+  toggleMaximize = (id: string): void => {
+    this.update(id, { maximized: !this.get(id).maximized, minimized: false });
+    this.focus(id);
+  };
+
+  focus = (id: string): void => {
+    const { surfaces } = useWorkbenchSurfaceStore.getState();
+    const ids = Object.keys(surfaces).sort(
+      (left, right) => surfaces[left].layer - surfaces[right].layer,
+    );
+    if (ids.at(-1) === id && this.get(id).layer > 0) return;
+    const ordered = [...ids.filter((key) => key !== id), id];
+    useWorkbenchSurfaceStore.setState({
+      surfaces: Object.fromEntries(
+        ordered.map((key, index) => [
+          key,
+          { ...this.get(key), layer: index + 1 },
+        ]),
+      ),
+    });
+  };
+
+  reset = (id: string): void => {
+    useWorkbenchSurfaceStore.setState(({ surfaces }) => {
+      const next = { ...surfaces };
+      delete next[id];
+      return { surfaces: next };
+    });
+  };
+
+  constrain = (id: string, viewport: WorkbenchViewport): void => {
+    const current = this.get(id).rect;
+    const rect = constrainWorkbenchRect(current, viewport);
+    if (
+      Object.keys(rect).some(
+        (key) =>
+          rect[key as keyof WorkbenchRect] !==
+          current[key as keyof WorkbenchRect],
+      )
+    )
+      this.update(id, { rect });
+  };
+
+  move = (
+    id: string,
+    start: WorkbenchRect,
+    dx: number,
+    dy: number,
+    viewport: WorkbenchViewport,
+  ): void => {
+    this.update(id, {
+      rect: constrainWorkbenchRect(
+        { ...start, x: start.x + dx, y: start.y + dy },
+        viewport,
+      ),
+    });
+  };
+
+  resize = (
+    id: string,
+    start: WorkbenchRect,
+    edge: WorkbenchResizeEdge,
+    dx: number,
+    dy: number,
+    viewport: WorkbenchViewport,
+  ): void => {
+    this.update(id, {
+      rect: resizeWorkbenchRect(start, edge, dx, dy, viewport),
+    });
+  };
+}
+
+export const workbenchSurfaceManager = new WorkbenchSurfaceManager();

package/src/shared/components/workbench/stores/workbench-surface.store.ts

@@ -0,0 +1,83 @@
+import { ViewMemoryStorage } from "@/shared/lib/navigation-history";
+import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+import {
+  DEFAULT_WORKBENCH_SURFACE,
+  GLOBAL_WORKBENCH_SURFACE,
+  type WorkbenchSurfaceState,
+} from "@/shared/components/workbench/types/workbench-surface.types";
+
+function restoreSurfaces(
+  value: unknown,
+): Record<string, WorkbenchSurfaceState> {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    !("surfaces" in value) ||
+    !value.surfaces ||
+    typeof value.surfaces !== "object"
+  )
+    return {};
+  const result: Record<string, WorkbenchSurfaceState> = {};
+  for (const [id, candidate] of Object.entries(value.surfaces).slice(-64)) {
+    if (!candidate || typeof candidate !== "object") continue;
+    const { placement, rect } = candidate;
+    if (
+      (placement !== "docked" && placement !== "floating") ||
+      !rect ||
+      !["x", "y", "w", "h"].every(
+        (key) => typeof rect[key] === "number" && Number.isFinite(rect[key]),
+      )
+    )
+      continue;
+    result[id] = { ...DEFAULT_WORKBENCH_SURFACE, placement, rect };
+  }
+  return result;
+}
+
+function initialSurfaces(): Record<string, WorkbenchSurfaceState> {
+  // One-way import of the former browser-only placement. New writes have one owner.
+  try {
+    const legacy = JSON.parse(
+      window.localStorage.getItem("nextclaw.doc-browser.state") ?? "null",
+    );
+    if (legacy?.state?.snapshot?.mode === "floating")
+      return {
+        [GLOBAL_WORKBENCH_SURFACE]: {
+          ...DEFAULT_WORKBENCH_SURFACE,
+          placement: "floating",
+        },
+      };
+  } catch {
+    /* Storage may be unavailable. The default dock remains usable. */
+  }
+  return {};
+}
+
+export const useWorkbenchSurfaceStore = create<{
+  surfaces: Record<string, WorkbenchSurfaceState>;
+  visibleSurfaceIds: string[];
+}>()(
+  persist(
+    () => ({ surfaces: initialSurfaces(), visibleSurfaceIds: [] as string[] }),
+    {
+      name: "nextclaw.workbench.layout",
+      version: 1,
+      storage: createJSONStorage(() => new ViewMemoryStorage()),
+      partialize: ({ surfaces }) => ({
+        surfaces: Object.fromEntries(
+          Object.entries(surfaces)
+            .slice(-64)
+            .map(([id, state]) => [
+              id,
+              { ...state, minimized: false, maximized: false, layer: 0 },
+            ]),
+        ),
+      }),
+      merge: (persisted, current) => ({
+        ...current,
+        surfaces: { ...current.surfaces, ...restoreSurfaces(persisted) },
+      }),
+    },
+  ),
+);

package/src/shared/components/workbench/types/workbench-surface.types.ts

@@ -0,0 +1,32 @@
+export type WorkbenchPlacement = "docked" | "floating";
+export type WorkbenchRect = { x: number; y: number; w: number; h: number };
+export type WorkbenchResizeEdge =
+  | "left"
+  | "right"
+  | "top"
+  | "bottom"
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right";
+export type WorkbenchViewport = { width: number; height: number };
+
+/** Presentation only. Resources, tabs, drafts and execution remain with their domain owners. */
+export type WorkbenchSurfaceState = {
+  placement: WorkbenchPlacement;
+  minimized: boolean;
+  maximized: boolean;
+  rect: WorkbenchRect;
+  layer: number;
+};
+
+export const GLOBAL_WORKBENCH_SURFACE = "global-resources";
+export const SESSION_WORKBENCH_SURFACE = "floating-conversation";
+
+export const DEFAULT_WORKBENCH_SURFACE: WorkbenchSurfaceState = {
+  placement: "docked",
+  minimized: false,
+  maximized: false,
+  rect: { x: 80, y: 80, w: 560, h: 640 },
+  layer: 0,
+};