@hienlh/ppm 0.17.56 → 0.18.0

package/src/web/components/floating-window/window-content-registry.ts

@@ -0,0 +1,51 @@
+/**
+ * Maps a window `kind` to the component that fills its body.
+ *
+ * The registry is the only coupling point between the generic window layer and real
+ * features: adding a kind means adding an entry here plus a title resolver, and nothing in
+ * the frame, store or gestures changes. Entries are lazy so a window's content (and its
+ * icon/virtualisation deps) never lands in the initial bundle.
+ */
+
+import { lazy, type ComponentType, type LazyExoticComponent } from "react";
+import { ExplorerSkinChrome } from "@/components/os-explorer/skins/explorer-skin-chrome";
+import type { WindowChrome } from "./window-chrome-contract";
+import type { WindowKind } from "./window-store-types";
+
+export interface WindowContentProps {
+  /** Window id — content may call the store to close/retitle itself. */
+  id: string;
+  /** Kind-specific state persisted with the window (e.g. the explorer's current path). */
+  payload?: Record<string, unknown>;
+}
+
+export const WINDOW_CONTENT: Record<WindowKind, LazyExoticComponent<ComponentType<WindowContentProps>>> = {
+  explorer: lazy(() => import("@/components/os-explorer/explorer-window-content")),
+};
+
+/**
+ * Per-kind titlebar chrome. `FloatingWindow` renders `chrome` directly with no
+ * `<Suspense>` around it, so — unlike `WINDOW_CONTENT` — entries here must be plain,
+ * synchronously-renderable components, not `lazy()`.
+ */
+export const WINDOW_CHROME: Partial<Record<WindowKind, WindowChrome>> = {
+  explorer: ExplorerSkinChrome,
+};
+
+/** Chrome for a window kind, or `undefined` to fall back to `DefaultWindowChrome`. */
+export function chromeFor(kind: WindowKind): WindowChrome | undefined {
+  return WINDOW_CHROME[kind];
+}
+
+/** Titlebar text for a window. Falls back to the kind's generic name. */
+export function windowTitle(kind: WindowKind, payload?: Record<string, unknown>): string {
+  const explicit = payload?.title;
+  if (typeof explicit === "string" && explicit.trim()) return explicit;
+  const path = payload?.path;
+  if (kind === "explorer" && typeof path === "string" && path) {
+    const segments = path.split(/[\\/]/).filter(Boolean);
+    // A drive or POSIX root has no last segment worth showing; the raw path is the name.
+    return segments[segments.length - 1] ?? path;
+  }
+  return "Explorer";
+}

package/src/web/components/floating-window/window-geometry.ts

@@ -0,0 +1,121 @@
+/**
+ * Pure geometry for the floating window layer — no DOM, no React, so every rule
+ * (min size, on-screen clamping, per-handle resize, spawn cascade) is unit-testable.
+ *
+ * All coordinates are relative to the layer container (the app content area), not the
+ * browser viewport: the nav rail must stay usable while a window is maximised.
+ */
+
+export interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** Size of the layer container the rects live in. */
+export interface Bounds {
+  w: number;
+  h: number;
+}
+
+export type ResizeHandle = "n" | "s" | "e" | "w" | "ne" | "nw" | "se" | "sw";
+
+export const RESIZE_HANDLES: ResizeHandle[] = ["n", "s", "e", "w", "ne", "nw", "se", "sw"];
+
+export const MIN_SIZE = { w: 360, h: 240 } as const;
+
+/**
+ * How much of the titlebar must remain reachable after a clamp. A window dragged past an
+ * edge keeps this many pixels inside the layer so it can always be grabbed back.
+ */
+export const KEEP_VISIBLE = 48;
+
+/** Offset between consecutive spawns, matching desktop window managers. */
+export const CASCADE_STEP = 24;
+
+/** Hard cap on simultaneous windows so the z-band stays inside 30..38. */
+export const MAX_WINDOWS = 8;
+
+/** Base z-index of the layer; strictly below the app's z-40 backdrops and z-50 popovers. */
+export const Z_BASE = 30;
+
+const PREFERRED = { w: 880, h: 560 } as const;
+const SPAWN_MARGIN = 48;
+
+const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
+
+/** Inline z-index for a window at `rank` (0 = backmost). Never exceeds Z_BASE + 8. */
+export function windowZIndex(rank: number): number {
+  return Z_BASE + clamp(Math.trunc(rank), 0, MAX_WINDOWS);
+}
+
+/**
+ * Fit a rect inside the layer: at least MIN_SIZE, never wider/taller than the layer, and
+ * positioned so KEEP_VISIBLE px of the titlebar row stay inside. Values are rounded to
+ * whole pixels — sub-pixel transforms blur text on high-DPI screens.
+ */
+export function clampRect(rect: Rect, bounds: Bounds): Rect {
+  const w = Math.max(MIN_SIZE.w, Math.min(rect.w, Math.max(bounds.w, MIN_SIZE.w)));
+  const h = Math.max(MIN_SIZE.h, Math.min(rect.h, Math.max(bounds.h, MIN_SIZE.h)));
+  // Left edge may go negative (window hangs off the left) as long as its right edge
+  // still shows KEEP_VISIBLE px; the top edge may never go above the layer, or the
+  // titlebar becomes unreachable.
+  const x = clamp(rect.x, KEEP_VISIBLE - w, Math.max(KEEP_VISIBLE - w, bounds.w - KEEP_VISIBLE));
+  const y = clamp(rect.y, 0, Math.max(0, bounds.h - KEEP_VISIBLE));
+  return { x: Math.round(x), y: Math.round(y), w: Math.round(w), h: Math.round(h) };
+}
+
+/**
+ * Apply a drag delta to one of the 8 handles.
+ *
+ * Edges anchored by the handle stay put; the opposite edge moves. Shrinking past the
+ * minimum stops the moving edge instead of pushing the anchored one, which is what makes
+ * a resize feel like a native window instead of sliding away under the cursor.
+ */
+export function applyResize(
+  rect: Rect,
+  handle: ResizeHandle,
+  dx: number,
+  dy: number,
+  min: { w: number; h: number } = MIN_SIZE,
+): Rect {
+  let { x, y, w, h } = rect;
+
+  if (handle.includes("e")) {
+    w = Math.max(min.w, rect.w + dx);
+  } else if (handle.includes("w")) {
+    const right = rect.x + rect.w;
+    w = Math.max(min.w, rect.w - dx);
+    x = right - w;
+  }
+
+  if (handle.includes("s")) {
+    h = Math.max(min.h, rect.h + dy);
+  } else if (handle.includes("n")) {
+    const bottom = rect.y + rect.h;
+    h = Math.max(min.h, rect.h - dy);
+    y = bottom - h;
+  }
+
+  return { x, y, w, h };
+}
+
+/**
+ * Where a newly opened window goes: cascaded from the top-left by CASCADE_STEP per existing
+ * window, wrapping before it would walk off the layer.
+ */
+export function cascadeSpawnRect(existing: Rect[], bounds: Bounds): Rect {
+  const w = Math.min(PREFERRED.w, Math.max(MIN_SIZE.w, bounds.w - SPAWN_MARGIN * 2));
+  const h = Math.min(PREFERRED.h, Math.max(MIN_SIZE.h, bounds.h - SPAWN_MARGIN * 2));
+  const step = existing.length % MAX_WINDOWS;
+  return clampRect(
+    { x: SPAWN_MARGIN + step * CASCADE_STEP, y: SPAWN_MARGIN + step * CASCADE_STEP, w, h },
+    bounds,
+  );
+}
+
+/** Nudge step for arrow keys on a focused titlebar (Shift = fine-grained). */
+export function nudgeRect(rect: Rect, dx: number, dy: number, bounds: Bounds): Rect {
+  return clampRect({ ...rect, x: rect.x + dx, y: rect.y + dy }, bounds);
+}

package/src/web/components/floating-window/window-layer.tsx

@@ -0,0 +1,92 @@
+/**
+ * Host for all floating windows, sized to the app's content area.
+ *
+ * It is deliberately a plain absolutely-positioned child of the content wrapper rather than
+ * a body-level portal: window coordinates stay relative to the working area, so a maximized
+ * window covers the panels but never the nav rail, and the container's own resize is what
+ * triggers re-clamping.
+ *
+ * The layer is desktop-only. Below the `md` breakpoint it renders nothing and never touches
+ * the store, leaving the mobile sheet presentation free to own the same content.
+ */
+
+import { Suspense, useCallback, useLayoutEffect, useRef, useState } from "react";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import { FloatingWindow } from "./floating-window";
+import { chromeFor, WINDOW_CONTENT, windowTitle } from "./window-content-registry";
+import { Z_BASE, MAX_WINDOWS } from "./window-geometry";
+import { useWindowStore, windowsInRankOrder } from "./window-store";
+
+export function WindowLayer() {
+  const isMobile = useIsMobile();
+  if (isMobile) return null;
+  return <DesktopWindowLayer />;
+}
+
+function DesktopWindowLayer() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const windows = useWindowStore((s) => s.windows);
+  const bounds = useWindowStore((s) => s.bounds);
+  const [capturing, setCapturing] = useState(false);
+
+  useLayoutEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const measure = () => {
+      const r = el.getBoundingClientRect();
+      const scale = el.offsetWidth > 0 ? r.width / el.offsetWidth : 1;
+      // Report layout pixels, not scaled screen pixels, so rects match the CSS coordinates
+      // the windows are positioned in.
+      return { w: Math.round(r.width / scale), h: Math.round(r.height / scale) };
+    };
+    const store = useWindowStore.getState();
+    store.setBounds(measure());
+    store.restoreAll(measure());
+    // Panels, the sidebar and the browser all resize this box; window.resize alone misses
+    // the first two and would leave windows stranded outside the layer.
+    const observer = new ResizeObserver(() => useWindowStore.getState().setBounds(measure()));
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  const getScale = useCallback(() => {
+    const el = containerRef.current;
+    if (!el || el.offsetWidth === 0) return 1;
+    return el.getBoundingClientRect().width / el.offsetWidth;
+  }, []);
+
+  const ordered = windowsInRankOrder(windows);
+  const frontId = ordered[ordered.length - 1]?.id;
+
+  return (
+    <div ref={containerRef} className="absolute inset-0 overflow-hidden pointer-events-none">
+      {ordered.map((win) => {
+        const Content = WINDOW_CONTENT[win.kind];
+        const title = windowTitle(win.kind, win.payload);
+        return (
+          <FloatingWindow
+            key={win.id}
+            win={win}
+            bounds={bounds}
+            title={title}
+            focused={win.id === frontId}
+            getScale={getScale}
+            onGestureActive={setCapturing}
+            chrome={chromeFor(win.kind)}
+          >
+            <Suspense fallback={<div className="p-3 text-xs text-text-2">Loading…</div>}>
+              <Content id={win.id} payload={win.payload} />
+            </Suspense>
+          </FloatingWindow>
+        );
+      })}
+
+      {/* Transparent capture surface: iframes and editors swallow pointer events, which
+          would stall a drag the moment the cursor crossed one. Stays inside the window
+          z-band so app popovers and dialogs remain above it. */}
+      {capturing && (
+        <div className="absolute inset-0 pointer-events-auto" style={{ zIndex: Z_BASE + MAX_WINDOWS }} />
+      )}
+    </div>
+  );
+}

package/src/web/components/floating-window/window-persistence.ts

@@ -0,0 +1,104 @@
+/**
+ * Manual localStorage persistence for floating windows.
+ *
+ * Hand-rolled instead of zustand's `persist` because the saved rects must be re-clamped
+ * against the *current* layer size on load (a rect saved on a 4K screen is off-screen on a
+ * laptop), and because only gesture-end commits should hit storage, not every drag frame.
+ */
+
+import { clampRect, type Bounds, type Rect } from "./window-geometry";
+import type { WindowKind, WindowRuntimeState, WindowVisualState } from "./window-store-types";
+
+const STORAGE_KEY = "ppm-windows";
+
+/** Only JSON-safe payloads survive a reload — anything else is dropped with the window. */
+export interface PersistedWindow {
+  id: string;
+  kind: WindowKind;
+  rect: Rect;
+  state: WindowVisualState;
+  payload?: Record<string, unknown>;
+}
+
+const KINDS: WindowKind[] = ["explorer"];
+const STATES: WindowVisualState[] = ["normal", "maximized", "minimized"];
+
+function isRect(v: unknown): v is Rect {
+  if (!v || typeof v !== "object") return false;
+  const r = v as Record<string, unknown>;
+  return (["x", "y", "w", "h"] as const).every((k) => typeof r[k] === "number" && Number.isFinite(r[k]));
+}
+
+function isSerialisable(payload: unknown): payload is Record<string, unknown> | undefined {
+  if (payload === undefined) return true;
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+  try {
+    JSON.stringify(payload);
+    return true;
+  } catch {
+    return false; // cyclic or non-serialisable payload (e.g. a live handle)
+  }
+}
+
+function toPersisted(win: WindowRuntimeState): PersistedWindow | null {
+  if (!isSerialisable(win.payload)) return null;
+  return { id: win.id, kind: win.kind, rect: win.rect, state: win.state, payload: win.payload };
+}
+
+export function saveWindowRects(windows: WindowRuntimeState[]): void {
+  try {
+    // Persisted back-to-front so the restored rank order matches what the user last saw.
+    const ordered = [...windows].sort((a, b) => a.rank - b.rank);
+    const payload = ordered.map(toPersisted).filter((w): w is PersistedWindow => w !== null);
+    if (payload.length === 0) localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, JSON.stringify(payload));
+  } catch {
+    /* quota exceeded or storage disabled — geometry is cosmetic, never block the UI */
+  }
+}
+
+/** Read persisted windows, dropping anything malformed, and re-clamp to the current layer. */
+export function loadWindowRects(bounds: Bounds): PersistedWindow[] {
+  let raw: string | null = null;
+  try {
+    raw = localStorage.getItem(STORAGE_KEY);
+  } catch {
+    return [];
+  }
+  if (!raw) return [];
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+
+  const out: PersistedWindow[] = [];
+  for (const item of parsed) {
+    if (!item || typeof item !== "object") continue;
+    const w = item as Record<string, unknown>;
+    if (typeof w.id !== "string" || !KINDS.includes(w.kind as WindowKind)) continue;
+    if (!isRect(w.rect) || !isSerialisable(w.payload)) continue;
+    const state = STATES.includes(w.state as WindowVisualState)
+      ? (w.state as WindowVisualState)
+      : "normal";
+    out.push({
+      id: w.id,
+      kind: w.kind as WindowKind,
+      rect: clampRect(w.rect, bounds),
+      state,
+      payload: w.payload as Record<string, unknown> | undefined,
+    });
+  }
+  return out;
+}
+
+export function clearWindowRects(): void {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {
+    /* storage disabled */
+  }
+}

package/src/web/components/floating-window/window-resize-handles.tsx

@@ -0,0 +1,81 @@
+/**
+ * The eight invisible grab strips around a window. Corners sit on top of the edges, matching
+ * the hit areas desktop window managers use.
+ *
+ * A window at this size can be reached with a finger — a tablet past the `md` breakpoint gets
+ * the desktop layer — and a 6 px strip is far below any touch target, so the grab areas grow
+ * on coarse pointers. They are transparent, so nothing about the window's look changes.
+ */
+
+import { useMediaQuery } from "@/hooks/use-media-query";
+import { RESIZE_HANDLES, type ResizeHandle } from "./window-geometry";
+
+type HandleBinder = (handle: ResizeHandle) => Record<string, unknown>;
+
+interface HandleSizes {
+  edge: number;
+  corner: number;
+}
+
+const MOUSE_SIZES: HandleSizes = { edge: 6, corner: 12 };
+const TOUCH_SIZES: HandleSizes = { edge: 12, corner: 20 };
+
+const CURSORS: Record<ResizeHandle, string> = {
+  n: "cursor-n-resize",
+  s: "cursor-s-resize",
+  e: "cursor-e-resize",
+  w: "cursor-w-resize",
+  ne: "cursor-ne-resize",
+  nw: "cursor-nw-resize",
+  se: "cursor-se-resize",
+  sw: "cursor-sw-resize",
+};
+
+/**
+ * Absolute placement per handle, expressed in the same units the frame uses. Each strip is
+ * centred on its border, so half of the extra width grows outwards and half inwards — the
+ * window's own border never moves.
+ */
+function styleFor(handle: ResizeHandle, sizes: HandleSizes): React.CSSProperties {
+  const corner = handle.length === 2;
+  const s: React.CSSProperties = { position: "absolute", touchAction: "none", zIndex: 1 };
+  if (handle.includes("n")) s.top = -sizes.edge / 2;
+  if (handle.includes("s")) s.bottom = -sizes.edge / 2;
+  if (handle.includes("w")) s.left = -sizes.edge / 2;
+  if (handle.includes("e")) s.right = -sizes.edge / 2;
+  if (corner) {
+    s.width = sizes.corner;
+    s.height = sizes.corner;
+    return s;
+  }
+  // Edge strips stop short of the corners so the corner handles keep their full hit area.
+  if (handle === "n" || handle === "s") {
+    s.left = sizes.corner;
+    s.right = sizes.corner;
+    s.height = sizes.edge;
+  } else {
+    s.top = sizes.corner;
+    s.bottom = sizes.corner;
+    s.width = sizes.edge;
+  }
+  return s;
+}
+
+export function WindowResizeHandles({ bind }: { bind: HandleBinder }) {
+  const coarsePointer = useMediaQuery("(pointer: coarse)");
+  const sizes = coarsePointer ? TOUCH_SIZES : MOUSE_SIZES;
+  return (
+    <>
+      {RESIZE_HANDLES.map((handle) => (
+        <div
+          key={handle}
+          {...bind(handle)}
+          data-resize-handle={handle}
+          aria-hidden
+          className={CURSORS[handle]}
+          style={styleFor(handle, sizes)}
+        />
+      ))}
+    </>
+  );
+}

package/src/web/components/floating-window/window-store-types.ts

@@ -0,0 +1,20 @@
+/** Shared window types — split out so the store and the persistence layer do not import each other. */
+
+import type { Rect } from "./window-geometry";
+
+/** Content families the layer can host. The registry maps each kind to its body component. */
+export type WindowKind = "explorer";
+
+export type WindowVisualState = "normal" | "maximized" | "minimized";
+
+export interface WindowRuntimeState {
+  id: string;
+  kind: WindowKind;
+  /** Geometry in layer coordinates. While maximized this holds the restore rect. */
+  rect: Rect;
+  /** Dense stacking order, 0 = backmost, renormalised on every focus. */
+  rank: number;
+  state: WindowVisualState;
+  /** Kind-specific, must stay JSON-serialisable to survive a reload. */
+  payload?: Record<string, unknown>;
+}

package/src/web/components/floating-window/window-store.ts

@@ -0,0 +1,192 @@
+/**
+ * Floating window state: geometry, stacking order and lifecycle for the desktop window layer.
+ *
+ * Content-agnostic on purpose — the store knows a `kind` and an opaque payload, the registry
+ * decides what renders inside. Ranks are kept dense (0..n-1) so the inline z-index never
+ * escapes the band reserved below the app's click-away backdrops.
+ */
+
+import { create } from "zustand";
+import {
+  cascadeSpawnRect,
+  clampRect,
+  MAX_WINDOWS,
+  type Bounds,
+  type Rect,
+} from "./window-geometry";
+import { loadWindowRects, saveWindowRects } from "./window-persistence";
+import type { WindowKind, WindowRuntimeState, WindowVisualState } from "./window-store-types";
+
+export type { WindowKind, WindowRuntimeState, WindowVisualState };
+
+/** Fallback layer size used before the container has been measured. */
+const DEFAULT_BOUNDS: Bounds = { w: 1280, h: 800 };
+
+interface WindowStore {
+  windows: Record<string, WindowRuntimeState>;
+  /** Measured size of the layer container; all rects are clamped against it. */
+  bounds: Bounds;
+  /** True once persisted windows have been read, so restore runs exactly once. */
+  restored: boolean;
+
+  open(kind: WindowKind, payload?: Record<string, unknown>, rect?: Rect): string;
+  close(id: string): void;
+  focus(id: string): void;
+  move(id: string, position: { x: number; y: number }): void;
+  resize(id: string, rect: Rect): void;
+  setState(id: string, state: WindowVisualState): void;
+  /** Merge into a window's payload; persisted so a reload restores the latest state. */
+  setPayload(id: string, payload: Record<string, unknown>): void;
+  setBounds(bounds: Bounds): void;
+  /** Re-hydrate persisted windows into the layer (no-op after the first call). */
+  restoreAll(bounds: Bounds): void;
+}
+
+const sortedByRank = (windows: Record<string, WindowRuntimeState>): WindowRuntimeState[] =>
+  Object.values(windows).sort((a, b) => a.rank - b.rank);
+
+/** Rewrite ranks to 0..n-1 in the given order (last = frontmost). */
+function densify(ordered: WindowRuntimeState[]): Record<string, WindowRuntimeState> {
+  const out: Record<string, WindowRuntimeState> = {};
+  ordered.forEach((win, rank) => {
+    out[win.id] = win.rank === rank ? win : { ...win, rank };
+  });
+  return out;
+}
+
+function persist(windows: Record<string, WindowRuntimeState>): void {
+  saveWindowRects(Object.values(windows));
+}
+
+function newId(): string {
+  return `win-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export const useWindowStore = create<WindowStore>((set, get) => ({
+  windows: {},
+  bounds: DEFAULT_BOUNDS,
+  restored: false,
+
+  open: (kind, payload, rect) => {
+    const { windows, bounds } = get();
+    const ordered = sortedByRank(windows);
+
+    // At the cap the layer would leave its z band, so the oldest window is raised instead
+    // of silently dropping the request.
+    if (ordered.length >= MAX_WINDOWS) {
+      const oldest = ordered[0]!;
+      get().focus(oldest.id);
+      return oldest.id;
+    }
+
+    const id = newId();
+    const spawn = rect ? clampRect(rect, bounds) : cascadeSpawnRect(ordered.map((w) => w.rect), bounds);
+    const next = densify([
+      ...ordered,
+      { id, kind, rect: spawn, rank: ordered.length, state: "normal" as const, payload },
+    ]);
+    set({ windows: next });
+    persist(next);
+    return id;
+  },
+
+  close: (id) => {
+    const { windows } = get();
+    if (!windows[id]) return;
+    const next = densify(sortedByRank(windows).filter((w) => w.id !== id));
+    set({ windows: next });
+    persist(next);
+  },
+
+  focus: (id) => {
+    const { windows } = get();
+    const target = windows[id];
+    if (!target) return;
+    const ordered = sortedByRank(windows);
+    if (ordered[ordered.length - 1]?.id === id) return; // already frontmost
+    const next = densify([...ordered.filter((w) => w.id !== id), target]);
+    set({ windows: next });
+    persist(next); // stacking order is part of the restored layout
+  },
+
+  move: (id, position) => {
+    const { windows, bounds } = get();
+    const win = windows[id];
+    if (!win) return;
+    const rect = clampRect({ ...win.rect, ...position }, bounds);
+    const next = { ...windows, [id]: { ...win, rect } };
+    set({ windows: next });
+    persist(next);
+  },
+
+  resize: (id, rect) => {
+    const { windows, bounds } = get();
+    const win = windows[id];
+    if (!win) return;
+    const next = { ...windows, [id]: { ...win, rect: clampRect(rect, bounds) } };
+    set({ windows: next });
+    persist(next);
+  },
+
+  setState: (id, state) => {
+    const { windows } = get();
+    const win = windows[id];
+    if (!win || win.state === state) return;
+    const next = { ...windows, [id]: { ...win, state } };
+    set({ windows: next });
+    persist(next);
+  },
+
+  setPayload: (id, payload) => {
+    const { windows } = get();
+    const win = windows[id];
+    if (!win) return;
+    const merged = { ...win.payload, ...payload };
+    // Content re-renders on every keystroke in some bodies; skip the write when the
+    // payload is unchanged so persistence is not hit for nothing.
+    const unchanged = Object.entries(merged).every(
+      ([key, value]) => win.payload?.[key] === value,
+    );
+    if (unchanged && Object.keys(merged).length === Object.keys(win.payload ?? {}).length) return;
+    const next = { ...windows, [id]: { ...win, payload: merged } };
+    set({ windows: next });
+    persist(next);
+  },
+
+  setBounds: (bounds) => {
+    const current = get();
+    if (current.bounds.w === bounds.w && current.bounds.h === bounds.h) return;
+    // A shrinking content area (sidebar opened, browser resized) would otherwise strand
+    // windows outside the layer with no way to drag them back.
+    const windows: Record<string, WindowRuntimeState> = {};
+    for (const win of Object.values(current.windows)) {
+      const rect = clampRect(win.rect, bounds);
+      windows[win.id] =
+        rect.x === win.rect.x && rect.y === win.rect.y && rect.w === win.rect.w && rect.h === win.rect.h
+          ? win
+          : { ...win, rect };
+    }
+    set({ bounds, windows });
+  },
+
+  restoreAll: (bounds) => {
+    if (get().restored) return;
+    const saved = loadWindowRects(bounds).slice(0, MAX_WINDOWS);
+    const windows = densify(
+      saved.map((w, rank) => ({
+        id: w.id,
+        kind: w.kind,
+        rect: w.rect,
+        rank,
+        state: w.state,
+        payload: w.payload,
+      })),
+    );
+    set({ bounds, windows, restored: true });
+  },
+}));
+
+/** Windows in paint order (backmost first) — stable identity per store update. */
+export function windowsInRankOrder(windows: Record<string, WindowRuntimeState>): WindowRuntimeState[] {
+  return sortedByRank(windows);
+}

package/src/web/components/layout/command-palette.tsx

@@ -18,7 +18,9 @@ import {
   Plus,
   Columns2,
   Cloud,
+  AppWindow,
 } from "lucide-react";
+import { openExplorer } from "@/components/os-explorer/open-explorer";
 import { useTabStore, type TabType } from "@/stores/tab-store";
 import { useProjectStore } from "@/stores/project-store";
 import { useSettingsStore } from "@/stores/settings-store";
@@ -232,6 +234,14 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
         group: "action",
         shortcut: formatShortcut(getBinding("open-settings")),
       },
+      {
+        id: "open-file-explorer", label: "Open File Explorer", icon: AppWindow, group: "action",
+        keywords: "open file explorer finder browse files folders disk drive window",
+        action: () => {
+          void openExplorer();
+          onClose();
+        },
+      },
     ];
 
     // Append extension-contributed commands (with keybinding shortcuts, respecting user overrides)