@hienlh/ppm 0.23.13 → 0.23.15

package/src/web/components/floating-window/window-chrome-contract.ts

@@ -6,9 +6,23 @@
  * `titlebarProps` — a chrome that spreads it gets drag, focus and keyboard for free.
  */
 
-import type { ComponentType, HTMLAttributes } from "react";
+import type { ComponentType, ElementType, HTMLAttributes } from "react";
 import type { WindowKind, WindowVisualState } from "./window-store-types";
 
+/** What a titlebar says about its window beyond the title; see `useWindowMeta`. */
+export interface WindowChromeIdentity {
+  /** The window's own glyph, drawn on a tile tinted with `tone`. */
+  icon: ElementType;
+  /** A CSS colour (a theme token); designs get one of their own. */
+  tone: string;
+  /** Second, dimmer label after the title, e.g. "Design · ppm". */
+  subtitle?: string;
+  /** Something is running in the window (an AI turn); the titlebar says so. */
+  busy: boolean;
+  /** False for content that must not move into picture-in-picture (a design canvas). */
+  allowPip: boolean;
+}
+
 export interface WindowChromeProps {
   id: string;
   kind: WindowKind;
@@ -22,8 +36,11 @@ export interface WindowChromeProps {
    * A chrome may append its own className/style; it must not drop these.
    */
   titlebarProps: HTMLAttributes<HTMLElement> & { tabIndex: number };
+  identity: WindowChromeIdentity;
   onMinimize: () => void;
   onToggleMaximize: () => void;
+  /** Snap to the right part of the layer, or back from it. */
+  onToggleSnap: () => void;
   onClose: () => void;
 }
 
@@ -34,5 +51,5 @@ export interface WindowChromeProps {
  */
 export type WindowChrome = ComponentType<WindowChromeProps>;
 
-/** Titlebar height the frame reserves when a window is collapsed (minimised). */
+/** Titlebar height; a picture-in-picture window takes it off the requested height. */
 export const TITLEBAR_HEIGHT = 36;

package/src/web/components/floating-window/window-dock-layout.ts

@@ -0,0 +1,72 @@
+/**
+ * How the status bar's window dock fits its chips into the width it has. Pure, so the
+ * squeeze order can be tested without a layout engine.
+ *
+ * The order, from roomy to cramped:
+ *  1. `full`    — every chip with its title.
+ *  2. `compact` — only the window in front keeps its title; the others are icons.
+ *  3. overflow  — chips are folded into `+N`, newest first, never the one in front.
+ *  4. `tight`   — left too little room for a useful slice of its title, the front chip
+ *                 drops its title as well.
+ * Past `maxChips` the row stops being scannable, so it folds even when it would fit.
+ */
+
+export type DockMode = "full" | "compact" | "tight";
+
+export interface DockLayoutInput {
+  /** Width the dock can use, in px. */
+  available: number;
+  /** Each chip's width with its title, in open order. */
+  fullWidths: number[];
+  /** A chip's width without its title. */
+  iconWidth: number;
+  /** Gap between chips. */
+  gap: number;
+  /** Width of the `+N` button. */
+  moreWidth: number;
+  /** Index of the window in front, or -1 when every window is minimized. */
+  frontIndex: number;
+  maxChips: number;
+  /** Below this many px of title, the front chip shows none at all. */
+  minTitle?: number;
+}
+
+export interface DockLayout {
+  mode: DockMode;
+  /** Indexes folded into `+N`. */
+  hidden: number[];
+}
+
+const sum = (xs: number[], gap: number) => xs.reduce((a, b) => a + b, 0) + Math.max(0, xs.length - 1) * gap;
+
+export function planDock(input: DockLayoutInput): DockLayout {
+  const { available, fullWidths, iconWidth, gap, moreWidth, frontIndex, maxChips } = input;
+  const minTitle = input.minTitle ?? 56;
+  const n = fullWidths.length;
+  if (n === 0) return { mode: "full", hidden: [] };
+
+  if (n <= maxChips && sum(fullWidths, gap) <= available) return { mode: "full", hidden: [] };
+
+  const compactWidth = (i: number) => (i === frontIndex ? fullWidths[i]! : iconWidth);
+  const compact = fullWidths.map((_, i) => compactWidth(i));
+  if (n <= maxChips && sum(compact, gap) <= available) return { mode: "compact", hidden: [] };
+
+  // Fold from the newest end until the rest fits beside `+N`.
+  const hidden: number[] = [];
+  const visible = () => compact.filter((_, i) => !hidden.includes(i));
+  const fits = () => sum(visible(), gap) + gap + moreWidth <= available;
+  for (let i = n - 1; i >= 0; i--) {
+    if (fits() && n - hidden.length <= maxChips) break;
+    if (i === frontIndex) continue;
+    hidden.push(i);
+  }
+
+  // Whatever is left over goes to the front chip's title; too little of it reads as noise.
+  if (frontIndex >= 0 && !hidden.includes(frontIndex)) {
+    const others = visible().length - 1;
+    const room = available - moreWidth - gap - others * (iconWidth + gap);
+    const titleRoom = room - iconWidth;
+    if (titleRoom < minTitle) return { mode: "tight", hidden };
+  }
+  return { mode: "compact", hidden };
+}

package/src/web/components/floating-window/window-dock-list.tsx

@@ -0,0 +1,156 @@
+/**
+ * Every floating window in one list, opened from the dock's `+N` or a right-click on the
+ * dock: search, the open ones and the minimized ones in two groups, a close button per row,
+ * and "Minimize all".
+ *
+ * The close button is revealed on hover only where hovering exists; on a touch screen it is
+ * always shown.
+ */
+
+import { useState, type RefObject } from "react";
+import { Popover } from "radix-ui";
+import { Search, X } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import { closeWindow } from "./close-window";
+import { useWindowMeta, useWindowSearchText } from "./use-window-meta";
+import { windowTitle } from "./window-content-registry";
+import { useWindowStore, type WindowRuntimeState } from "./window-store";
+import { WindowTile } from "./window-title-identity";
+
+export function WindowDockList({ open, onOpenChange, anchorRef, windows, frontId }: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  anchorRef: RefObject<HTMLElement | null>;
+  windows: WindowRuntimeState[];
+  frontId: string | null;
+}) {
+  const [query, setQuery] = useState("");
+  const shown = windows.filter((w) => w.state !== "minimized");
+  const minimized = windows.filter((w) => w.state === "minimized");
+
+  const setOpen = (next: boolean) => {
+    if (next) setQuery("");
+    onOpenChange(next);
+  };
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Anchor virtualRef={anchorRef as RefObject<HTMLElement>} />
+      <Popover.Portal>
+        <Popover.Content
+          aria-label="All windows"
+          side="top"
+          align="end"
+          sideOffset={6}
+          collisionPadding={8}
+          // `+N` toggles the list itself: let its click close it rather than the outside
+          // press closing it and the click opening it again.
+          onPointerDownOutside={(e) => {
+            if ((e.target as Element | null)?.closest?.("[data-more]")) e.preventDefault();
+          }}
+          className="z-50 flex max-h-[min(440px,70vh)] w-[300px] max-w-[calc(100vw-24px)] flex-col overflow-hidden rounded-xl border border-border bg-panel-2 font-sans shadow-lg"
+        >
+          <div className="flex items-center gap-2 pb-2 pl-3.5 pr-2.5 pt-2.5">
+            <span className="text-[13px] font-semibold text-text">Windows</span>
+            <span className="font-mono text-[11px] text-text-3">{windows.length}</span>
+            <span className="flex-1" />
+            <button
+              type="button"
+              onClick={() => { useWindowStore.getState().minimizeAll(); setOpen(false); }}
+              className="rounded-md px-1.5 py-1 text-xs font-medium text-primary can-hover:hover:bg-accent-wash"
+            >
+              Minimize all
+            </button>
+          </div>
+          <label className="mx-2.5 mb-1.5 flex h-[30px] items-center gap-1.5 rounded-lg border border-border-soft bg-panel px-2 text-text-3 focus-within:border-accent-wash-border">
+            <Search className="size-3.5 shrink-0" />
+            <input
+              autoFocus
+              type="text"
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              placeholder="Find a window…"
+              aria-label="Find a window"
+              autoComplete="off"
+              className="min-w-0 flex-1 bg-transparent text-[12.5px] text-text outline-none placeholder:text-text-3"
+            />
+          </label>
+          <WindowRows query={query} shown={shown} minimized={minimized} frontId={frontId} onPicked={() => setOpen(false)} />
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}
+
+function WindowRows({ query, shown, minimized, frontId, onPicked }: {
+  query: string;
+  shown: WindowRuntimeState[];
+  minimized: WindowRuntimeState[];
+  frontId: string | null;
+  onPicked: () => void;
+}) {
+  const all = [...shown, ...minimized];
+  const text = useWindowSearchText(all);
+  const q = query.trim().toLowerCase();
+  const matching = new Set(all.filter((_, i) => !q || text[i]!.includes(q)).map((w) => w.id));
+
+  const group = (label: string, list: WindowRuntimeState[]) => {
+    const rows = list.filter((w) => matching.has(w.id));
+    return rows.length > 0 && (
+      <>
+        <p className="mx-2 mb-1 mt-2 text-[10.5px] font-semibold uppercase tracking-[0.06em] text-text-3">
+          {label} · {rows.length}
+        </p>
+        {rows.map((w) => <WindowRow key={w.id} win={w} front={w.id === frontId} onPicked={onPicked} />)}
+      </>
+    );
+  };
+
+  return (
+    <div className="min-h-0 overflow-y-auto px-1.5 pb-2 pt-0.5">
+      {group("Open", shown)}
+      {group("Minimized", minimized)}
+      {matching.size === 0 && <p className="p-4 text-center text-xs text-text-3">No window matches</p>}
+    </div>
+  );
+}
+
+function WindowRow({ win, front, onPicked }: {
+  win: WindowRuntimeState;
+  front: boolean;
+  onPicked: () => void;
+}) {
+  const meta = useWindowMeta(win);
+  const title = meta.title || windowTitle(win.kind, win.payload);
+  const minimized = win.state === "minimized";
+  const sub = meta.busy ? `${meta.kindLabel} · working` : front ? `${meta.kindLabel} · in front` : meta.kindLabel;
+  return (
+    <div className={cn("group relative flex items-center rounded-lg can-hover:hover:bg-surface-hover", front && "bg-accent-wash")}>
+      {front && <span aria-hidden="true" className="absolute bottom-2 left-0 top-2 w-[3px] rounded-r-[3px] bg-primary" />}
+      <button
+        type="button"
+        onClick={() => { if (!front) useWindowStore.getState().focus(win.id); onPicked(); }}
+        className="flex min-h-11 min-w-0 flex-1 items-center gap-2.5 py-1.5 pl-2.5 pr-2 text-left md:min-h-0"
+      >
+        <WindowTile icon={meta.icon} tone={meta.tone} size="lg" filled={meta.filled} muted={minimized} />
+        <span className="flex min-w-0 flex-col gap-0.5">
+          <span className="truncate text-[12.5px] font-medium text-text">{title}</span>
+          <span className={cn("truncate text-[11px]", meta.busy ? "text-success" : "text-text-3")}>{sub}</span>
+        </span>
+      </button>
+      <button
+        type="button"
+        aria-label={`Close ${title}`}
+        title="Close"
+        onClick={() => closeWindow(win.id)}
+        className={cn(
+          "mr-1 grid size-[26px] shrink-0 place-items-center rounded-md text-text-3 transition-colors",
+          "can-hover:opacity-0 can-hover:group-hover:opacity-100 focus-visible:opacity-100",
+          "can-hover:hover:bg-[color-mix(in_srgb,var(--color-error)_18%,transparent)] can-hover:hover:text-error",
+        )}
+      >
+        <X className="size-3.5" />
+      </button>
+    </div>
+  );
+}

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

@@ -0,0 +1,192 @@
+/**
+ * The status bar's window dock: one chip per floating window, in the order they were opened,
+ * like a taskbar. Three states read at a glance — in front (tinted, long accent bar), open
+ * behind (short bar), minimized (no bar, dimmed tile) — plus a pulsing dot while an AI turn
+ * runs in the window.
+ *
+ * Clicking the chip in front minimizes its window; any other chip brings its window forward,
+ * from the dock if need be. Squeezed, chips give up their titles and then fold into `+N`
+ * (`planDock`); `+N`, or a right-click anywhere on the dock, lists every window.
+ *
+ * The chip widths `planDock` needs come from a second, invisible row of full-size chips:
+ * the visible row is already squeezed, so it cannot say how wide a chip would like to be.
+ */
+
+import { memo, useLayoutEffect, useRef, useState } from "react";
+import { ChevronUp } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+import { useBusyWindowIds, useWindowMeta } from "./use-window-meta";
+import { windowTitle } from "./window-content-registry";
+import { planDock, type DockLayout } from "./window-dock-layout";
+import { WindowDockList } from "./window-dock-list";
+import { isPipOnlyWindow } from "./window-pip-registry";
+import { frontWindowId, useWindowStore, windowsInOpenOrder, type WindowRuntimeState } from "./window-store";
+import { WindowBusyDot, WindowTile } from "./window-title-identity";
+
+/** Past this many chips the row stops being scannable; the rest goes into `+N`. */
+const MAX_CHIPS = 8;
+const CHIP_GAP = 2;
+/** A chip without its title: 16px tile + 5px padding each side. */
+const ICON_CHIP_WIDTH = 26;
+
+type ChipState = "front" | "behind" | "min";
+
+export const WindowDock = memo(function WindowDock() {
+  const windows = useWindowStore((s) => s.windows);
+  // A window carrying a tab into picture-in-picture is never on screen; it is not one the
+  // user opened.
+  const list = windowsInOpenOrder(windows).filter((w) => !isPipOnlyWindow(w.id));
+  const frontId = frontWindowId(windows);
+  const frontIndex = list.findIndex((w) => w.id === frontId);
+  const busy = useBusyWindowIds(list);
+
+  const rootRef = useRef<HTMLDivElement>(null);
+  const measureRef = useRef<HTMLDivElement>(null);
+  const [layout, setLayout] = useState<DockLayout>({ mode: "full", hidden: [] });
+  const [listOpen, setListOpen] = useState(false);
+
+  const key = list.map((w) => w.id).join(",");
+  useLayoutEffect(() => {
+    const root = rootRef.current;
+    const measure = measureRef.current;
+    if (!root || !measure) return;
+    const replan = () => {
+      const chips = [...measure.querySelectorAll<HTMLElement>("[data-chip]")];
+      const more = measure.querySelector<HTMLElement>("[data-more]");
+      const style = getComputedStyle(root);
+      const available = root.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
+      const next = planDock({
+        available,
+        fullWidths: chips.map((c) => c.offsetWidth),
+        iconWidth: ICON_CHIP_WIDTH,
+        gap: CHIP_GAP,
+        // +2: the button's own left margin.
+        moreWidth: (more?.offsetWidth ?? 40) + 2,
+        frontIndex,
+        maxChips: MAX_CHIPS,
+      });
+      setLayout((prev) => (prev.mode === next.mode && prev.hidden.join() === next.hidden.join() ? prev : next));
+    };
+    replan();
+    // The root follows the bar's width; the measuring row follows the titles.
+    const observer = new ResizeObserver(replan);
+    observer.observe(root);
+    observer.observe(measure);
+    return () => observer.disconnect();
+  }, [key, frontIndex]);
+
+  if (list.length === 0) return null;
+
+  const stateOf = (w: WindowRuntimeState): ChipState =>
+    w.id === frontId ? "front" : w.state === "minimized" ? "min" : "behind";
+  const hidden = new Set(layout.hidden);
+  const hiddenBusy = list.some((w, i) => hidden.has(i) && busy.has(w.id));
+
+  return (
+    <div
+      ref={rootRef}
+      role="toolbar"
+      aria-label="Windows"
+      onContextMenu={(e) => { e.preventDefault(); setListOpen(true); }}
+      className="relative flex h-full min-w-0 flex-1 basis-0 items-center gap-0.5 overflow-hidden border-l border-border-soft pl-2.5 font-sans"
+    >
+      {list.map((w, i) => hidden.has(i) ? null : (
+        <DockChip
+          key={w.id}
+          win={w}
+          state={stateOf(w)}
+          showTitle={layout.mode === "full" || (layout.mode === "compact" && w.id === frontId)}
+          busy={busy.has(w.id)}
+        />
+      ))}
+      {layout.hidden.length > 0 && (
+        <MoreButton count={layout.hidden.length} busy={hiddenBusy} expanded={listOpen} onClick={() => setListOpen(!listOpen)} />
+      )}
+
+      {/* Invisible, full-size twins of the chips: the widths `planDock` works from. */}
+      <div ref={measureRef} aria-hidden="true" className="pointer-events-none invisible absolute left-0 top-0 flex gap-0.5 whitespace-nowrap">
+        {list.map((w) => <DockChip key={w.id} win={w} state={stateOf(w)} showTitle busy={false} measuring />)}
+        <MoreButton count={list.length} busy={false} expanded={false} measuring />
+      </div>
+
+      <WindowDockList open={listOpen} onOpenChange={setListOpen} anchorRef={rootRef} windows={list} frontId={frontId} />
+    </div>
+  );
+});
+
+function DockChip({ win, state, showTitle, busy, measuring }: {
+  win: WindowRuntimeState;
+  state: ChipState;
+  showTitle: boolean;
+  busy: boolean;
+  measuring?: boolean;
+}) {
+  const meta = useWindowMeta(win);
+  const title = meta.title || windowTitle(win.kind, win.payload);
+  const label = `${title}${state === "min" ? " (minimized)" : ""}${busy ? " · working" : ""}`;
+  return (
+    <button
+      type="button"
+      data-chip=""
+      tabIndex={measuring ? -1 : undefined}
+      title={label}
+      aria-label={label}
+      aria-pressed={state !== "min"}
+      onClick={() => useWindowStore.getState().activateFromDock(win.id)}
+      className={cn(
+        "relative flex h-[22px] max-w-[168px] items-center gap-1.5 rounded-md text-[11.5px] font-medium leading-none transition-colors",
+        "can-hover:hover:bg-surface-hover can-hover:hover:text-text",
+        showTitle ? "pl-1 pr-2" : "px-[5px]",
+        // The front chip is the one that gives way first, so it is never folded away.
+        state === "front" ? "min-w-[26px] shrink bg-accent-wash text-text" : "shrink-0",
+        state === "behind" && "text-text-2",
+        state === "min" && "text-text-3",
+      )}
+    >
+      <WindowTile icon={meta.icon} tone={meta.tone} size="sm" filled={meta.filled} muted={state === "min"}>
+        {busy && <WindowBusyDot />}
+      </WindowTile>
+      {showTitle && <span className="min-w-0 truncate">{title}</span>}
+      {state !== "min" && (
+        <span
+          aria-hidden="true"
+          className={cn(
+            "absolute bottom-0 left-1/2 h-[2px] -translate-x-1/2 rounded-full transition-[width,background-color]",
+            state === "front" ? "w-[18px] bg-primary" : "w-1.5 bg-text-3",
+          )}
+        />
+      )}
+    </button>
+  );
+}
+
+function MoreButton({ count, busy, expanded, onClick, measuring }: {
+  count: number;
+  busy: boolean;
+  expanded: boolean;
+  onClick?: () => void;
+  measuring?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      data-more=""
+      tabIndex={measuring ? -1 : undefined}
+      title={`${count} more window${count === 1 ? "" : "s"}`}
+      aria-label={`${count} more window${count === 1 ? "" : "s"}`}
+      aria-haspopup="dialog"
+      aria-expanded={expanded}
+      onClick={onClick}
+      className={cn(
+        "relative ml-0.5 flex h-[22px] shrink-0 items-center gap-0.5 rounded-md border pl-2 pr-1.5 text-[11px] font-semibold leading-none transition-colors",
+        expanded
+          ? "border-accent-wash-border bg-accent-wash text-text"
+          : "border-border-soft bg-panel-2 text-text-2 can-hover:hover:border-accent-wash-border can-hover:hover:bg-accent-wash can-hover:hover:text-text",
+      )}
+    >
+      +{count}
+      <ChevronUp className={cn("size-3 transition-transform", expanded && "rotate-180")} />
+      {busy && <WindowBusyDot className="-right-0.5 -top-0.5" />}
+    </button>
+  );
+}

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

@@ -34,7 +34,10 @@ 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. */
+/**
+ * Hard cap on simultaneous windows so the z-band stays inside 30..38. Minimized windows
+ * count too: they come back without asking for a slot.
+ */
 export const MAX_WINDOWS = 8;
 
 /** Base z-index of the layer; strictly below the app's z-40 backdrops and z-50 popovers. */
@@ -133,6 +136,41 @@ export function portraitSpawnRect(existing: Rect[], bounds: Bounds): Rect {
   );
 }
 
+/** Share of the layer a snapped window takes, measured from the right edge. */
+export const SNAP_FRACTION = 0.55;
+
+/**
+ * How far a window's right edge has to be dragged past the layer's right edge before
+ * releasing it snaps the window. Measured on the window, not the pointer, so grabbing the
+ * titlebar near its left end does not make the snap unreachable.
+ */
+export const SNAP_TRIGGER = 40;
+
+/** The rect of a window snapped to the right: full height, `SNAP_FRACTION` of the width. */
+export function snapRect(bounds: Bounds): Rect {
+  const w = Math.min(bounds.w, Math.max(MIN_SIZE.w, Math.round(bounds.w * SNAP_FRACTION)));
+  return { x: bounds.w - w, y: 0, w, h: bounds.h };
+}
+
+/**
+ * True when a drag that started at `start` has carried the window (`rect`, before clamping)
+ * far enough right to snap on release.
+ *
+ * Measured from wherever the right edge already was when it lies past the layer's: a window
+ * may rest hanging off the right side, and grabbing one there to pull it back in must move
+ * it, not snap it.
+ */
+export function wantsSnap(rect: Rect, start: Rect, bounds: Bounds): boolean {
+  return rect.x + rect.w > Math.max(start.x + start.w, bounds.w) + SNAP_TRIGGER;
+}
+
+/** Where a window in `state` is drawn; `rect` is the restore rect it keeps meanwhile. */
+export function displayedRect(state: string, rect: Rect, bounds: Bounds): Rect {
+  if (state === "maximized") return { x: 0, y: 0, w: bounds.w, h: bounds.h };
+  if (state === "snapped") return snapRect(bounds);
+  return rect;
+}
+
 /** 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

@@ -13,9 +13,10 @@
 import { Suspense, useCallback, useLayoutEffect, useRef, useState } from "react";
 import { useIsMobile } from "@/hooks/use-is-mobile";
 import { FloatingWindow } from "./floating-window";
+import { useWindowMeta } from "./use-window-meta";
 import { WINDOW_CONTENT, windowTitle } from "./window-content-registry";
-import { Z_BASE, MAX_WINDOWS } from "./window-geometry";
-import { useWindowStore, windowsInRankOrder } from "./window-store";
+import { snapRect, Z_BASE, MAX_WINDOWS, type Bounds } from "./window-geometry";
+import { frontWindowId, useWindowStore, windowsInRankOrder, type WindowRuntimeState } from "./window-store";
 
 export function WindowLayer() {
   const isMobile = useIsMobile();
@@ -27,6 +28,7 @@ function DesktopWindowLayer() {
   const containerRef = useRef<HTMLDivElement>(null);
   const windows = useWindowStore((s) => s.windows);
   const bounds = useWindowStore((s) => s.bounds);
+  const snapPreview = useWindowStore((s) => s.snapPreviewId !== null);
   const [capturing, setCapturing] = useState(false);
 
   useLayoutEffect(() => {
@@ -56,29 +58,24 @@ function DesktopWindowLayer() {
   }, []);
 
   const ordered = windowsInRankOrder(windows);
-  const frontId = ordered[ordered.length - 1]?.id;
+  const frontId = frontWindowId(windows);
 
   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}
-          >
-            <Suspense fallback={<div className="p-3 text-xs text-text-2">Loading…</div>}>
-              <Content id={win.id} payload={win.payload} />
-            </Suspense>
-          </FloatingWindow>
-        );
-      })}
+    // Stops at the status bar (26px) rather than covering it: the bar holds the window dock,
+    // and a maximized or snapped window must never hide the way back to the others.
+    <div ref={containerRef} className="absolute inset-x-0 top-0 bottom-[26px] overflow-hidden pointer-events-none">
+      {snapPreview && <SnapGhost bounds={bounds} />}
+
+      {ordered.map((win) => (
+        <LayerWindow
+          key={win.id}
+          win={win}
+          bounds={bounds}
+          focused={win.id === frontId}
+          getScale={getScale}
+          onGestureActive={setCapturing}
+        />
+      ))}
 
       {/* Transparent capture surface: iframes and editors swallow pointer events, which
           would stall a drag the moment the cursor crossed one. Stays inside the window
@@ -89,3 +86,42 @@ function DesktopWindowLayer() {
     </div>
   );
 }
+
+/** One window with its titlebar identity resolved — a component so the meta hook has a home. */
+function LayerWindow({ win, bounds, focused, getScale, onGestureActive }: {
+  win: WindowRuntimeState;
+  bounds: Bounds;
+  focused: boolean;
+  getScale: () => number;
+  onGestureActive: (active: boolean) => void;
+}) {
+  const Content = WINDOW_CONTENT[win.kind];
+  const meta = useWindowMeta(win);
+  return (
+    <FloatingWindow
+      win={win}
+      bounds={bounds}
+      title={meta.title || windowTitle(win.kind, win.payload)}
+      identity={meta}
+      focused={focused}
+      getScale={getScale}
+      onGestureActive={onGestureActive}
+    >
+      <Suspense fallback={<div className="p-3 text-xs text-text-2">Loading…</div>}>
+        <Content id={win.id} payload={win.payload} />
+      </Suspense>
+    </FloatingWindow>
+  );
+}
+
+/** Where a window dragged off the right edge will land when it is let go. */
+function SnapGhost({ bounds }: { bounds: Bounds }) {
+  const r = snapRect(bounds);
+  return (
+    <div
+      aria-hidden="true"
+      className="absolute rounded border-2 border-dashed border-primary bg-accent-wash transition-opacity"
+      style={{ left: r.x, top: r.y, width: r.w, height: r.h, zIndex: Z_BASE }}
+    />
+  );
+}