@hienlh/ppm 0.17.56 → 0.18.0

package/src/web/components/explorer/use-tree-row-dnd.ts

@@ -0,0 +1,206 @@
+/**
+ * Drag source + drop target wiring for one tree row.
+ *
+ * Two drags share this row: the tree's own internal move (a single relative path, its own
+ * `application/x-ppm-path` MIME, its own project-scoped `/files/move` endpoint) and OS file
+ * uploads — both pre-dating this hook and left byte-for-byte as they were. Layered on top,
+ * the shared cross-surface entry-drag handlers let an explorer window or a different
+ * project's tree drag onto (or receive a drag from) this same row.
+ *
+ * Every tree-origin drag dual-writes the legacy MIME, regardless of which project it started
+ * in — so its mere presence is not enough to take the legacy project-scoped move: that path
+ * treats the dragged path as relative to *this* row's project, which is wrong the moment the
+ * drag started in a different project's tree (two panels, two active projects). The legacy
+ * path is only safe when the absolute payload says the drag's own `projectName` matches this
+ * row's; anything else — including a same-name coincidence across two different projects,
+ * which the payload's `projectName` alone cannot tell apart from the real thing, so this
+ * additionally requires it came from a tree — falls through to the shared absolute-path
+ * handlers, which are correct for any project by construction.
+ */
+
+import { useRef, useState } from "react";
+import { toast } from "sonner";
+import { api, projectUrl } from "@/lib/api-client";
+import { useFileStore, absoluteProjectPath } from "@/stores/file-store";
+import { fsChanged } from "@/components/os-explorer/explorer-store";
+import {
+  decodeEntryDrag, ENTRY_DRAG_MIME, TREE_LEGACY_DRAG_MIME, type EntryDragPayload,
+} from "@/components/os-explorer/dnd/entry-drag-payload";
+import { getInFlightDrag } from "@/components/os-explorer/dnd/entry-drag-state";
+import {
+  enterDragDepth, leaveDragDepth, resetDragDepth, type DragDepthCounter,
+} from "@/components/os-explorer/dnd/drag-depth-counter";
+import { executeEntryDrop, type DropRunner } from "@/components/os-explorer/dnd/entry-drop-executor";
+import { useEntryDragSource, type EntryDragSourceProps } from "@/components/os-explorer/dnd/use-entry-drag-source";
+import { useEntryDropTarget } from "@/components/os-explorer/dnd/use-entry-drop-target";
+
+/** Check if drag event is from OS files (not internal PPM drag). */
+export function isExternalFileDrag(e: React.DragEvent): boolean {
+  return e.dataTransfer.types.includes("Files") && !e.dataTransfer.types.includes(TREE_LEGACY_DRAG_MIME);
+}
+
+/**
+ * Pure routing decision, extracted for unit testing: given the decoded payload this row can
+ * currently see (module ref on hover, real `dataTransfer` at drop) and whether the legacy
+ * MIME is present at all, is the legacy project-scoped move safe to use? Only when the drag
+ * both carries that MIME and genuinely originated in *this* project's tree.
+ */
+export function isSameProjectLegacyPayload(
+  payload: EntryDragPayload | null,
+  hasLegacyMime: boolean,
+  projectName: string,
+): boolean {
+  return hasLegacyMime && payload?.origin === "tree" && payload.projectName === projectName;
+}
+
+function parentDirOf(path: string): string {
+  return path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+}
+
+export interface TreeRowDndOptions {
+  path: string;
+  name: string;
+  isDir: boolean;
+  /** Flat rows: dropping on a file targets its parent directory. */
+  effectivePath: string;
+  isSelected: boolean;
+  selectedFiles: string[];
+  isExpanded: boolean;
+  projectName: string;
+  projectRoot: string | undefined;
+  toggleExpand(projectName: string, path: string): void;
+  onFileDrop(targetDir: string, files: FileList): void;
+  /** Runs a cross-surface entry drop through the shared collision-prompt transfer. */
+  transferRun: DropRunner;
+}
+
+export interface TreeRowDnd {
+  entrySource: EntryDragSourceProps;
+  containerHandlers: {
+    onDragEnter(e: React.DragEvent): void;
+    onDragLeave(e: React.DragEvent): void;
+    onDragOver(e: React.DragEvent): void;
+    onDrop(e: React.DragEvent): void;
+  };
+  /** True while this row is a claimed target of either drag kind — draw the ring from it. */
+  isDragOver: boolean;
+}
+
+export function useTreeRowDnd(options: TreeRowDndOptions): TreeRowDnd {
+  const {
+    path, name, isDir, effectivePath, isSelected, selectedFiles, isExpanded,
+    projectName, projectRoot, toggleExpand, onFileDrop, transferRun,
+  } = options;
+
+  const [isDragOver, setIsDragOver] = useState(false);
+  // `useRef<number>`'s `{ current }` shape already matches `DragDepthCounter` structurally.
+  const dragCounter: DragDepthCounter = useRef(0);
+
+  // Absolute host paths — the address space an explorer window or another project's tree
+  // shares with this one. A multi-selected drag carries the whole selection; a lone node
+  // carries just itself, matching what the context menu would act on.
+  const dragAbsolutePaths = (isSelected && selectedFiles.length > 1 ? selectedFiles : [path])
+    .map((p) => (projectRoot ? absoluteProjectPath(projectRoot, p) : p));
+
+  const entrySource = useEntryDragSource({
+    paths: dragAbsolutePaths,
+    origin: "tree",
+    projectName,
+    // The tree's own internal move keeps reading this single-path type exactly as before —
+    // multi-select was never wired into it, and this dual-write does not change that.
+    extraData: { [TREE_LEGACY_DRAG_MIME]: isDir ? `${path}/` : path },
+  });
+
+  const dropTargetDir = isDir ? effectivePath : parentDirOf(path);
+  const dropTargetAbsolute = isDir && projectRoot ? absoluteProjectPath(projectRoot, dropTargetDir) : null;
+
+  const entryTarget = useEntryDropTarget({
+    targetDir: dropTargetAbsolute,
+    onDropEntries: (payload, op, dstDir) => void executeEntryDrop(payload, dstDir, op, transferRun),
+    springLoad: isDir && !isExpanded ? () => toggleExpand(projectName, path) : undefined,
+  });
+
+  // dataTransfer values are unreadable during dragenter/dragover in Chromium — read the
+  // module-level in-flight payload there (set at dragstart by the row that began the drag,
+  // in this same document), and the real dataTransfer once it is actually readable, at drop.
+  function legacyDragPayload(e: React.DragEvent): EntryDragPayload | null {
+    return e.type === "drop" ? decodeEntryDrag(e.dataTransfer.getData(ENTRY_DRAG_MIME)) : getInFlightDrag();
+  }
+
+  function canAcceptDrop(e: React.DragEvent): boolean {
+    if (isExternalFileDrag(e)) return true;
+    return isSameProjectLegacyPayload(
+      legacyDragPayload(e),
+      e.dataTransfer.types.includes(TREE_LEGACY_DRAG_MIME),
+      projectName,
+    );
+  }
+
+  function handleNodeDragEnter(e: React.DragEvent) {
+    if (!canAcceptDrop(e)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    if (enterDragDepth(dragCounter, true)) setIsDragOver(true);
+  }
+  function handleNodeDragLeave(e: React.DragEvent) {
+    e.stopPropagation();
+    if (leaveDragDepth(dragCounter, true)) setIsDragOver(false);
+  }
+  function handleNodeDragOver(e: React.DragEvent) {
+    if (!canAcceptDrop(e)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    e.dataTransfer.dropEffect = isExternalFileDrag(e) ? "copy" : "move";
+  }
+  function handleNodeDrop(e: React.DragEvent) {
+    e.preventDefault();
+    e.stopPropagation();
+    resetDragDepth(dragCounter);
+    setIsDragOver(false);
+
+    // External file upload
+    if (isExternalFileDrag(e)) {
+      if (e.dataTransfer.files.length > 0) onFileDrop(dropTargetDir, e.dataTransfer.files);
+      return;
+    }
+
+    // Internal tree move — canAcceptDrop already confirmed this drag's own projectName
+    // matches this row's, so the legacy relative path is safe to resolve against it.
+    const sourcePath = e.dataTransfer.getData(TREE_LEGACY_DRAG_MIME).replace(/\/$/, "");
+    if (!sourcePath) return;
+    // Prevent dropping into self or descendant
+    if (sourcePath === dropTargetDir || dropTargetDir.startsWith(`${sourcePath}/`)) return;
+    // Prevent no-op (already in this folder)
+    const sourceParent = parentDirOf(sourcePath);
+    if (sourceParent === dropTargetDir) return;
+
+    const sourceName = sourcePath.includes("/") ? sourcePath.slice(sourcePath.lastIndexOf("/") + 1) : sourcePath;
+    const destination = dropTargetDir ? `${dropTargetDir}/${sourceName}` : sourceName;
+    api.post(`${projectUrl(projectName)}/files/move`, { source: sourcePath, destination })
+      .then(() => {
+        const store = useFileStore.getState();
+        store.invalidateIndex();
+        store.loadIndex(projectName);
+        store.invalidateFolder(projectName, sourceParent);
+        store.invalidateFolder(projectName, dropTargetDir);
+        // An explorer window showing either folder must refresh too.
+        if (projectRoot) {
+          fsChanged(absoluteProjectPath(projectRoot, sourceParent), absoluteProjectPath(projectRoot, dropTargetDir));
+        }
+      })
+      .catch((err) => {
+        toast.error(err instanceof Error ? err.message : "Move failed");
+      });
+  }
+
+  return {
+    entrySource,
+    isDragOver: isDragOver || entryTarget.isOver,
+    containerHandlers: {
+      onDragEnter: (e) => { if (canAcceptDrop(e)) handleNodeDragEnter(e); else entryTarget.handlers.onDragEnter(e); },
+      onDragLeave: (e) => { if (canAcceptDrop(e)) handleNodeDragLeave(e); else entryTarget.handlers.onDragLeave(e); },
+      onDragOver: (e) => { if (canAcceptDrop(e)) handleNodeDragOver(e); else entryTarget.handlers.onDragOver(e); },
+      onDrop: (e) => { if (canAcceptDrop(e)) handleNodeDrop(e); else entryTarget.handlers.onDrop(e); },
+    },
+  };
+}

package/src/web/components/floating-window/default-window-chrome.tsx

@@ -0,0 +1,71 @@
+/**
+ * Neutral titlebar used until an OS skin supplies its own chrome. Uses PPM semantic tokens
+ * so it inherits the active theme instead of hard-coding a platform look.
+ *
+ * A chrome is a component, not a render callback: a skin is free to hold its own hover,
+ * focus or animation state without entangling itself with the window frame's hooks.
+ */
+
+import { Minus, Square, Copy, X } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { TITLEBAR_HEIGHT, type WindowChromeProps } from "./window-chrome-contract";
+
+/**
+ * Caption buttons follow the Windows metric (44 px wide) rather than a square 44 px touch
+ * target: the window layer never renders below the `md` breakpoint, where mobile sheets
+ * take over, so the titlebar can stay at desktop height.
+ */
+const CAPTION_BUTTON = "grid place-items-center w-11 self-stretch text-text-2 can-hover:hover:bg-surface-elevated can-hover:hover:text-text transition-colors";
+
+export function DefaultWindowChrome({
+  title,
+  state,
+  focused,
+  titlebarProps,
+  onMinimize,
+  onToggleMaximize,
+  onClose,
+}: WindowChromeProps) {
+  const { className, style, ...rest } = titlebarProps;
+  return (
+    <div
+      {...rest}
+      style={{ height: TITLEBAR_HEIGHT, ...style }}
+      className={cn(
+        "flex items-stretch shrink-0 border-b border-border bg-panel-2 rounded-t-[8px] overflow-hidden",
+        "outline-none focus-visible:ring-1 focus-visible:ring-primary focus-visible:ring-inset",
+        className,
+      )}
+    >
+      <div className="flex-1 min-w-0 flex items-center px-3 cursor-default">
+        <span className={cn("truncate text-xs font-medium", focused ? "text-text" : "text-text-2")}>
+          {title}
+        </span>
+      </div>
+      <button
+        type="button"
+        aria-label="Minimize window"
+        className={CAPTION_BUTTON}
+        onClick={onMinimize}
+      >
+        <Minus className="size-3.5" />
+      </button>
+      <button
+        type="button"
+        aria-label={state === "maximized" ? "Restore window" : "Maximize window"}
+        className={CAPTION_BUTTON}
+        onClick={onToggleMaximize}
+      >
+        {state === "maximized" ? <Copy className="size-3" /> : <Square className="size-3" />}
+      </button>
+      <button
+        type="button"
+        aria-label="Close window"
+        className={cn(CAPTION_BUTTON, "can-hover:hover:bg-destructive can-hover:hover:text-white")}
+        onClick={onClose}
+      >
+        <X className="size-3.5" />
+      </button>
+    </div>
+  );
+}

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

@@ -0,0 +1,167 @@
+/**
+ * One floating window: geometry, gestures, keyboard, and a chrome slot.
+ *
+ * Geometry is written straight to the element instead of through React state — a drag emits
+ * a pointermove per frame and re-rendering the window (and its content) on each one is what
+ * makes a window manager feel heavy. The store is written only when a gesture ends, which is
+ * also the moment the rect is rounded to whole pixels.
+ */
+
+import { useCallback, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { cn } from "@/lib/utils";
+import { DefaultWindowChrome } from "./default-window-chrome";
+import { TITLEBAR_HEIGHT, type WindowChrome } from "./window-chrome-contract";
+import { windowZIndex, type Bounds, type Rect } from "./window-geometry";
+import { useWindowStore, type WindowRuntimeState } from "./window-store";
+import { useWindowDrag } from "./use-window-drag";
+import { useWindowKeyboard } from "./use-window-keyboard";
+import { useWindowResize } from "./use-window-resize";
+import { WindowResizeHandles } from "./window-resize-handles";
+
+export interface FloatingWindowProps {
+  win: WindowRuntimeState;
+  /** Size of the layer container; a maximized window fills exactly this. */
+  bounds: Bounds;
+  title: string;
+  focused: boolean;
+  /** Reads the layer's CSS scale so pointer deltas can be corrected. */
+  getScale: () => number;
+  /** Told when a gesture starts/ends so the layer can raise its capture overlay. */
+  onGestureActive: (active: boolean) => void;
+  /** Skin component for the titlebar; owns its own hooks and state. */
+  chrome?: WindowChrome;
+  children: ReactNode;
+}
+
+function applyRect(el: HTMLElement | null, rect: Rect, collapsed: boolean): void {
+  if (!el) return;
+  el.style.transform = `translate3d(${Math.round(rect.x)}px, ${Math.round(rect.y)}px, 0)`;
+  el.style.width = `${Math.round(rect.w)}px`;
+  el.style.height = collapsed ? `${TITLEBAR_HEIGHT}px` : `${Math.round(rect.h)}px`;
+}
+
+export function FloatingWindow({
+  win,
+  bounds,
+  title,
+  focused,
+  getScale,
+  onGestureActive,
+  chrome,
+  children,
+}: FloatingWindowProps) {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const [gesturing, setGesturing] = useState(false);
+
+  const maximized = win.state === "maximized";
+  const minimized = win.state === "minimized";
+  const rect: Rect = maximized ? { x: 0, y: 0, w: bounds.w, h: bounds.h } : win.rect;
+
+  // Latest committed geometry, read at the first frame of a gesture (never mid-gesture,
+  // where it would compound the cumulative movement).
+  const rectRef = useRef(rect);
+  rectRef.current = rect;
+  const boundsRef = useRef(bounds);
+  boundsRef.current = bounds;
+
+  useLayoutEffect(() => {
+    applyRect(rootRef.current, rectRef.current, minimized);
+  }, [rect.x, rect.y, rect.w, rect.h, minimized]);
+
+  const setActive = useCallback(
+    (active: boolean) => {
+      setGesturing(active);
+      onGestureActive(active);
+    },
+    [onGestureActive],
+  );
+
+  const commitMove = useCallback((next: Rect, committed: boolean) => {
+    applyRect(rootRef.current, next, useWindowStore.getState().windows[win.id]?.state === "minimized");
+    if (committed) useWindowStore.getState().move(win.id, { x: next.x, y: next.y });
+  }, [win.id]);
+
+  const commitResize = useCallback((next: Rect, committed: boolean) => {
+    applyRect(rootRef.current, next, false);
+    if (committed) useWindowStore.getState().resize(win.id, next);
+  }, [win.id]);
+
+  const shared = {
+    getRect: () => rectRef.current,
+    getBounds: () => boundsRef.current,
+    getScale,
+    onGestureActive: setActive,
+  };
+  const bindDrag = useWindowDrag({ ...shared, onChange: commitMove, disabled: maximized });
+  const bindResize = useWindowResize({ ...shared, onChange: commitResize, disabled: maximized || minimized });
+
+  const close = useCallback(() => useWindowStore.getState().close(win.id), [win.id]);
+  const toggleMaximize = useCallback(() => {
+    useWindowStore.getState().setState(win.id, maximized ? "normal" : "maximized");
+  }, [win.id, maximized]);
+  const minimize = useCallback(() => {
+    useWindowStore.getState().setState(win.id, minimized ? "normal" : "minimized");
+  }, [win.id, minimized]);
+
+  const onKeyDown = useWindowKeyboard({
+    getRect: () => rectRef.current,
+    getBounds: () => boundsRef.current,
+    onMove: (next) => useWindowStore.getState().move(win.id, { x: next.x, y: next.y }),
+    onToggleMaximize: toggleMaximize,
+    onClose: close,
+    movable: !maximized,
+  });
+
+  const Chrome = chrome ?? DefaultWindowChrome;
+
+  return (
+    <div
+      ref={rootRef}
+      role="group"
+      aria-roledescription="window"
+      aria-label={title}
+      // Any pointer inside the window raises it, including clicks on its content.
+      onPointerDownCapture={() => useWindowStore.getState().focus(win.id)}
+      style={{ zIndex: windowZIndex(win.rank) }}
+      className={cn(
+        "absolute left-0 top-0 flex flex-col pointer-events-auto",
+        "rounded-[8px] border border-border bg-panel overflow-visible",
+        focused ? "shadow-2xl shadow-black/40" : "shadow-lg shadow-black/20",
+        // Transitions are for maximize/restore only; during a gesture they would lag the pointer.
+        gesturing ? "transition-none" : "transition-[transform,width,height] duration-150 motion-reduce:transition-none",
+      )}
+    >
+      <Chrome
+        id={win.id}
+        kind={win.kind}
+        title={title}
+        state={win.state}
+        focused={focused}
+        titlebarProps={{
+          ...(bindDrag() as Record<string, unknown>),
+          onKeyDown,
+          tabIndex: 0,
+          role: "toolbar",
+          "aria-label": `${title} title bar`,
+          // Scoped here rather than on document: a global user-select hack leaks into
+          // unrelated panels and survives a gesture that ends outside the window.
+          style: { touchAction: "none", userSelect: "none" },
+        }}
+        onMinimize={minimize}
+        onToggleMaximize={toggleMaximize}
+        onClose={close}
+      />
+
+
+      {/* Always mounted, even minimized — content owns per-window state (explorer history,
+          selection, filter) that a remount would wipe. Hidden via CSS, not unmounted. */}
+      <div className={cn("relative flex-1 min-h-0 overflow-hidden rounded-b-[8px] bg-panel", minimized && "hidden")}>
+        {children}
+      </div>
+
+      {!maximized && !minimized && (
+        <WindowResizeHandles bind={(handle) => bindResize(handle) as Record<string, unknown>} />
+      )}
+    </div>
+  );
+}

package/src/web/components/floating-window/use-window-drag.ts

@@ -0,0 +1,28 @@
+/** Titlebar drag: moves a window, committing to the store only when the gesture ends. */
+
+import { useDrag } from "@use-gesture/react";
+import { clampRect, type Rect } from "./window-geometry";
+import {
+  gestureDisplacement,
+  WINDOW_DRAG_CONFIG,
+  type WindowGestureContext,
+} from "./use-window-gesture-context";
+
+export function useWindowDrag(ctx: WindowGestureContext) {
+  return useDrag(
+    ({ xy, initial, first, last, memo }) => {
+      // The rect is captured once per gesture: the displacement is cumulative from the
+      // start, so re-reading a rect that we ourselves are mutating would compound it.
+      const base: Rect = first ? { ...ctx.getRect() } : (memo as Rect);
+      if (first) ctx.onGestureActive(true);
+
+      const { dx, dy } = gestureDisplacement(xy, initial, ctx.getScale());
+      const next = clampRect({ ...base, x: base.x + dx, y: base.y + dy }, ctx.getBounds());
+      ctx.onChange(next, last);
+
+      if (last) ctx.onGestureActive(false);
+      return base;
+    },
+    { ...WINDOW_DRAG_CONFIG, enabled: !ctx.disabled },
+  );
+}

package/src/web/components/floating-window/use-window-gesture-context.ts

@@ -0,0 +1,44 @@
+/** Shared plumbing between the window drag and resize gestures. */
+
+import type { Bounds, Rect } from "./window-geometry";
+
+export interface WindowGestureContext {
+  /** Rect at the moment the gesture starts — read lazily so it is never stale. */
+  getRect: () => Rect;
+  getBounds: () => Bounds;
+  /**
+   * Layer scale when an ancestor applies a CSS transform/zoom. Pointer deltas are in
+   * screen pixels, layout coordinates are not, so deltas must be divided by it or the
+   * window drifts away from the cursor.
+   */
+  getScale: () => number;
+  /** `committed` is true on the last frame of the gesture — the only time the store is written. */
+  onChange: (rect: Rect, committed: boolean) => void;
+  /** Raises the transparent capture overlay so iframes/editors cannot swallow the pointer. */
+  onGestureActive: (active: boolean) => void;
+  disabled?: boolean;
+}
+
+/** Gesture config shared by both hooks: keep the pointer captured, ignore taps. */
+export const WINDOW_DRAG_CONFIG = {
+  filterTaps: true,
+  pointer: { capture: true },
+} as const;
+
+/**
+ * Pointer displacement since the gesture started, corrected for layer scale.
+ *
+ * Derived from the raw pointer coordinates (`xy` minus `initial`) rather than the
+ * recogniser's `movement`: with a tap threshold in play, `movement` has those first pixels
+ * subtracted, which would leave the window trailing the pointer by the threshold for the
+ * rest of the gesture. Both values are cumulative from the gesture's start, so applying
+ * them to the rect captured at that moment can never drift the way per-frame deltas do.
+ */
+export function gestureDisplacement(
+  xy: readonly [number, number],
+  initial: readonly [number, number],
+  scale: number,
+): { dx: number; dy: number } {
+  const s = scale > 0 ? scale : 1;
+  return { dx: (xy[0] - initial[0]) / s, dy: (xy[1] - initial[1]) / s };
+}

package/src/web/components/floating-window/use-window-keyboard.ts

@@ -0,0 +1,55 @@
+/**
+ * Keyboard operation for a focused titlebar — the accessible path for users who cannot drag.
+ *
+ * Arrows nudge (Shift = 1 px), Alt+Enter toggles maximize, Escape closes. There is
+ * deliberately no Ctrl/Cmd+W: Chromium reserves it for the browser tab outside PWA and
+ * fullscreen contexts and ignores preventDefault, so binding it would close the app instead.
+ */
+
+import { useCallback } from "react";
+import type { KeyboardEvent } from "react";
+import { nudgeRect, type Bounds, type Rect } from "./window-geometry";
+
+const NUDGE = 10;
+const NUDGE_FINE = 1;
+
+const ARROWS: Record<string, [number, number]> = {
+  ArrowLeft: [-1, 0],
+  ArrowRight: [1, 0],
+  ArrowUp: [0, -1],
+  ArrowDown: [0, 1],
+};
+
+export interface WindowKeyboardActions {
+  getRect: () => Rect;
+  getBounds: () => Bounds;
+  onMove: (rect: Rect) => void;
+  onToggleMaximize: () => void;
+  onClose: () => void;
+  /** Nudging a maximized window would fight the layout, so it is ignored. */
+  movable: boolean;
+}
+
+export function useWindowKeyboard(actions: WindowKeyboardActions) {
+  return useCallback(
+    (e: KeyboardEvent<HTMLElement>) => {
+      if (e.key === "Escape") {
+        e.stopPropagation();
+        actions.onClose();
+        return;
+      }
+      if (e.altKey && e.key === "Enter") {
+        e.preventDefault();
+        actions.onToggleMaximize();
+        return;
+      }
+      const dir = ARROWS[e.key];
+      if (!dir || !actions.movable) return;
+      // Arrows would otherwise scroll the panel behind the window.
+      e.preventDefault();
+      const step = e.shiftKey ? NUDGE_FINE : NUDGE;
+      actions.onMove(nudgeRect(actions.getRect(), dir[0] * step, dir[1] * step, actions.getBounds()));
+    },
+    [actions],
+  );
+}

package/src/web/components/floating-window/use-window-resize.ts

@@ -0,0 +1,30 @@
+/**
+ * Eight-direction resize. One `useDrag` instance is bound per handle via `bind(handle)`;
+ * the handle id arrives in `args`, so all eight edges share a single recogniser.
+ */
+
+import { useDrag } from "@use-gesture/react";
+import { applyResize, clampRect, type Rect, type ResizeHandle } from "./window-geometry";
+import {
+  gestureDisplacement,
+  WINDOW_DRAG_CONFIG,
+  type WindowGestureContext,
+} from "./use-window-gesture-context";
+
+export function useWindowResize(ctx: WindowGestureContext) {
+  return useDrag(
+    ({ args, xy, initial, first, last, memo }) => {
+      const handle = args[0] as ResizeHandle;
+      const base: Rect = first ? { ...ctx.getRect() } : (memo as Rect);
+      if (first) ctx.onGestureActive(true);
+
+      const { dx, dy } = gestureDisplacement(xy, initial, ctx.getScale());
+      const next = clampRect(applyResize(base, handle, dx, dy), ctx.getBounds());
+      ctx.onChange(next, last);
+
+      if (last) ctx.onGestureActive(false);
+      return base;
+    },
+    { ...WINDOW_DRAG_CONFIG, enabled: !ctx.disabled },
+  );
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Contract between the window frame and whatever draws its titlebar.
+ *
+ * The frame owns geometry, gestures and keyboard handling; a chrome implementation owns
+ * only the look. Everything a titlebar needs to be draggable and operable arrives in
+ * `titlebarProps` — a chrome that spreads it gets drag, focus and keyboard for free.
+ */
+
+import type { ComponentType, HTMLAttributes } from "react";
+import type { WindowKind, WindowVisualState } from "./window-store-types";
+
+export interface WindowChromeProps {
+  id: string;
+  kind: WindowKind;
+  title: string;
+  state: WindowVisualState;
+  /** True when this window is frontmost — chrome should dim its titlebar otherwise. */
+  focused: boolean;
+  /**
+   * Spread on the titlebar element. Carries the drag recogniser, the keyboard handler,
+   * `tabIndex`, and the `touch-action`/`user-select` suppression the gesture needs.
+   * A chrome may append its own className/style; it must not drop these.
+   */
+  titlebarProps: HTMLAttributes<HTMLElement> & { tabIndex: number };
+  onMinimize: () => void;
+  onToggleMaximize: () => void;
+  onClose: () => void;
+}
+
+/**
+ * Rendered as an element by the frame, so a skin owns its own hooks and state (hover and
+ * focus handling for traffic lights, animation, its own effects) without touching the
+ * frame's hook order.
+ */
+export type WindowChrome = ComponentType<WindowChromeProps>;
+
+/** Titlebar height the frame reserves when a window is collapsed (minimised). */
+export const TITLEBAR_HEIGHT = 36;