@ai-matrx/summon 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,9 +1,22 @@
 # Changelog
 
+## 0.1.4
+### Unreleased
+
+- **New: `./dock`, the one primitive for floating chrome-less cards, pills and docks** (design R5 wave 2). `<Dock>` / `<DockHandle>` / `useDock()` / `useDockContext()` / `<DockProvider>`: pointer drag that never re-renders while moving (CSS `translate` in one animation frame, one commit on release), corner-relative positions clamped to the viewport with an optional nearest-corner snap and fixed-control avoidance, the position remembered per dock id (own store, `DockProvider`, else localStorage) or reported to a controlled host, the window manager's z-order lane on press, the design-system drag cursor hold, a click-vs-drag threshold that swallows the trailing click. Replaces the copies in AI Matrx (`useDraggableFloat`, the assists `useDockDrag`) and in `@ai-matrx/chat` (`useDraggablePanel`, the agent widget drags). Guard: `src/dock/__tests__/dock.test.tsx`. Consumer action: none.
+- **New: the render map can live on the host.** `render` is now optional on `defineOverlay`, and `<SummonHost renders={…}>` takes an id → `() => import("./<id>.render")` map (`OverlayRenderMap`, data type erased, no `any`) for definitions declared without one. A definition's own `render` still wins. Why: every file that imports a definition to open it also inherited an `import()` edge to that overlay's window subtree; with ~220 overlays and ~450 opener files in AI Matrx that multiplied the build graph (a sub-app build went from ~10 s to an out-of-memory kill). An opened overlay with no render source shows its error card (`OverlayRenderMissingError`, `MISSING_RENDER_ERROR`) and logs in development. Guard: `src/react/__tests__/hostRenders.test.tsx`. Consumer action: none for existing users.
+
 ## 0.1.2
 
-UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
-Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/summon/src`.
+SOURCE CHANGED WITH NO RELEASE NOTE. This release shipped source changes that nobody described in an Unreleased entry,
+so they may include breaking API changes. Consumer action is UNKNOWN: read the diff before upgrading.
+Diff: `git diff b7bc6ffc86 19d4c1f55d -- apps/shared/summon/src`
+
+Changed shipped source files (4):
+- `apps/shared/summon/src/persistence/controller.ts`
+- `apps/shared/summon/src/persistence/data/createDataPersistence.ts`
+- `apps/shared/summon/src/sheet/OverlaySheets.tsx`
+- `apps/shared/summon/src/window/useWindowPanel.ts`
 
 ## 0.1.1
 ### Unreleased

package/README.md

@@ -25,7 +25,7 @@ pnpm add @ai-matrx/summon react react-dom react-redux @reduxjs/toolkit
 | `html-to-image` (optional) | tray thumbnails of minimized windows (without it the tile shows no preview) |
 | `@supabase/supabase-js` | only `./persistence/data`, through `@ai-matrx/data` |
 
-Entries: `.` (core, no React), `./handles` (no React, no Redux), `./react`, `./window`, `./window-host` (the root-mountable half of the window section: `WindowsProvider`, `WindowTraySync`, `registerTrayPreview` — never loads WindowPanel), `./dialog`, `./sheet`, `./lite`, `./url`, `./persistence`, `./persistence/data`, `./next`, `./testing`, `./styles.css`.
+Entries: `.` (core, no React), `./handles` (no React, no Redux), `./react`, `./window`, `./window-host` (the root-mountable half of the window section: `WindowsProvider`, `WindowTraySync`, `registerTrayPreview` — never loads WindowPanel), `./dialog`, `./sheet`, `./lite`, `./dock`, `./url`, `./persistence`, `./persistence/data`, `./next`, `./testing`, `./styles.css`.
 
 ## Quick start
 
@@ -121,6 +121,7 @@ const Always = () => <notesWindow.Controller noteId="42" />;
 | `window` | `{ mobile, mobileSidebarAs, ephemeral, preservation, restoreDefaults, windowId, deprecated, unbiddenHome }` for window overlays |
 | `link` | `{ key, aliases?, hydrate }`, see Links |
 | `parse` | narrow raw data once; `null` refuses |
+| `render` | `() => import("./x.render")`; optional when the host supplies it (see below), and wins over the host map when present |
 
 Minimizing a window always keeps its component mounted, whatever `keepAlive` says.
 
@@ -159,6 +160,26 @@ emit("uploaded", { url });
 
 Closing the instance disposes the channel. Emitting after that is a silent no-op.
 
+### Large apps: the render map lives on the host
+
+Every file that imports a definition to open it also imports that definition's `render: () => import(…)`. To a bundler, each such file gains an edge to the overlay's whole window subtree. With a few overlays that is free. With hundreds of overlays and hundreds of opener files it multiplies the build graph: in AI Matrx, about 450 opener files each reached about 220 window subtrees, and a sub-app build went from about 10 s to an out-of-memory kill. This is the host-build law: never fan out `import()` edges.
+
+The fix keeps "declare once" at two files plus one line. Leave `render` off the definitions, and give the host one id → import map, generated from the file names, that only the host imports:
+
+```ts
+// definitions/notes.overlay.ts — no render: importing it costs nothing
+export const notes = defineOverlay<{ noteId?: string }>()({ id: "notes", label: "Notes" });
+
+// definitions/render-map.ts — generated, imported ONLY by the host (behind its own lazy boundary)
+import type { OverlayRenderMap } from "@ai-matrx/summon/react";
+export const RENDER_MAP: OverlayRenderMap = { notes: () => import("./notes.render") };
+
+// the host
+<SummonHost definitions={APP_OVERLAYS} renders={RENDER_MAP} />
+```
+
+`OverlayRenderMap` erases each module's data type (`OverlayRenderProps<never>`), so differently typed render modules share one map without `any`. An overlay that is opened with no render source at all (no `render`, no map entry) shows its error card (`OverlayRenderMissingError`, exported as `MISSING_RENDER_ERROR`) and logs in development. It is never a silent blank.
+
 ## Mounting into an existing Redux store
 
 ```ts
@@ -351,6 +372,26 @@ import { LiteWindow } from "@ai-matrx/summon/lite";
 
 `OverlayDialog`, `OverlaySheet`, `OverlayDrawer` and `OverlayBottomSheet` take the design-system component's props plus the close binding: `boundToOverlay` (open while the instance is shown) or `onClose` (+ `open`). `LiteWindow` has drag, edge resize, Escape when topmost, focus in and out, and a bottom drawer on phones; no minimize, tray, persistence or links.
 
+### Dock (floating chrome-less cards, pills and docks)
+
+```tsx
+import { Dock, DockHandle, DockProvider, useDock, useDockContext } from "@ai-matrx/summon/dock";
+
+<Dock id="attention" corner="bottom-right" defaultPosition={{ x: 16, y: 16 }} zIndex={50} className="w-80">
+  <DockHandle>⋮⋮ Alerts <button onClick={…}>Close</button></DockHandle>
+  …
+</Dock>
+
+// Your own markup: spread the bindings.
+const dock = useDock({ id: "assists", corner: "bottom-right", position, onPositionChange: save, touch: false, clamp: { margin: 0, minVisible: { width: 120, height: 32 } } });
+<div ref={dock.ref} style={dock.style}><button {...dock.handleProps}>pill</button></div>
+
+// Hand every dock the host's storage (declared keys, per-user sync).
+<DockProvider store={{ read: (id) => …, write: (id, position) => … }}>…</DockProvider>
+```
+
+Pointer drag that never re-renders while moving: each move paints the CSS `translate` property in one animation frame and the position is committed to React state once, on release (`dragging` flips twice per gesture, never per move), so a dock with a streaming answer inside stays cheap. Positions are offsets from a corner (`corner`, default bottom-right), clamped to the viewport on every render (`clamp: { margin = 8, minVisible }`; a dock bigger than the room keeps its top-left reachable); `snapToCorner` re-anchors to the nearest corner on release; `avoid: { selector, gap }` keeps it off fixed controls. Without a position it rests on `defaultPosition`, or on a CSS `anchor` (`top/bottom/left/right/centerX`). Remembered per id: the dock's `store`, else the nearest `DockProvider`, else localStorage (`matrx:summon:dock:<id>`); `persist={false}` for per-moment docks; a controlled host passes `position` + `onPositionChange` (told once per drag, and `null` on `reset()`). A press passes a 4px `threshold` before it is a drag, and a drag swallows its trailing click; controls inside the handle (`ignore`, default buttons/links/fields/`[data-no-drag]`) never start one; `touch={false}` leaves touch to page scroll; `draggable={false}` pins it (phones). On press it joins the window manager's z-order lane (`raiseTransientWindow`, above windows, below modals) when a `SummonProvider` is present, and the drag holds `grabbing` through design-system `holdDragCursor`. No listener exists outside an active press.
+
 ## Styling
 
 Import the structural CSS once, and make Tailwind v4 scan the package, since the components use utility classes:

package/dist/dock.cjs

@@ -0,0 +1,552 @@
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/dock.ts
+var dock_exports = {};
+__export(dock_exports, {
+  DEFAULT_DOCK_IGNORE: () => DEFAULT_DOCK_IGNORE,
+  DEFAULT_DOCK_MARGIN: () => DEFAULT_DOCK_MARGIN,
+  DEFAULT_DRAG_THRESHOLD: () => DEFAULT_DRAG_THRESHOLD,
+  DOCK_STORAGE_PREFIX: () => DOCK_STORAGE_PREFIX,
+  Dock: () => Dock,
+  DockHandle: () => DockHandle,
+  DockProvider: () => DockProvider,
+  avoidExclusions: () => avoidExclusions,
+  clampOffset: () => clampOffset,
+  createLocalDockStore: () => createLocalDockStore,
+  fromScreen: () => fromScreen,
+  memoryOnlyDockStore: () => memoryOnlyDockStore,
+  nearestCorner: () => nearestCorner,
+  parseDockPosition: () => parseDockPosition,
+  toScreen: () => toScreen,
+  useDock: () => useDock,
+  useDockContext: () => useDockContext,
+  useDockStore: () => useDockStore
+});
+module.exports = __toCommonJS(dock_exports);
+
+// src/dock/Dock.tsx
+var import_react4 = require("react");
+
+// src/dock/useDock.ts
+var import_react2 = require("react");
+var import_design_system = require("@ai-matrx/design-system");
+var import_summon = require("@ai-matrx/summon");
+var import_react3 = require("@ai-matrx/summon/react");
+
+// src/dock/geometry.ts
+var DEFAULT_DOCK_MARGIN = 8;
+var DEFAULT_DRAG_THRESHOLD = 4;
+var fromLeft = (corner) => corner.endsWith("left");
+var fromTop = (corner) => corner.startsWith("top");
+function toScreen(offset, corner, size, viewport) {
+  return {
+    left: fromLeft(corner) ? offset.x : viewport.width - size.width - offset.x,
+    top: fromTop(corner) ? offset.y : viewport.height - size.height - offset.y
+  };
+}
+function fromScreen(point, corner, size, viewport) {
+  return {
+    x: fromLeft(corner) ? point.left : viewport.width - size.width - point.left,
+    y: fromTop(corner) ? point.top : viewport.height - size.height - point.top
+  };
+}
+function clampOffset(offset, corner, size, viewport, clamp = {}) {
+  const margin = clamp.margin ?? DEFAULT_DOCK_MARGIN;
+  const visible = clamp.minVisible ?? size;
+  const axis = (value, room, extent, nearIsStart) => {
+    const min = margin;
+    const max = room - extent - margin;
+    if (max < min) return Math.round(nearIsStart ? min : max);
+    return Math.round(Math.min(Math.max(value, min), max));
+  };
+  return {
+    x: axis(offset.x, viewport.width, visible.width, fromLeft(corner)),
+    y: axis(offset.y, viewport.height, visible.height, fromTop(corner))
+  };
+}
+function nearestCorner(point, size, viewport) {
+  const top = point.top + size.height / 2 < viewport.height / 2;
+  const left = point.left + size.width / 2 < viewport.width / 2;
+  return `${top ? "top" : "bottom"}-${left ? "left" : "right"}`;
+}
+function overlaps(a, b) {
+  return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
+}
+function avoidExclusions(point, size, excluded, gap, keepOnScreen) {
+  const bounded = keepOnScreen(point);
+  if (excluded.length === 0) return bounded;
+  const rectFor = (candidate) => ({
+    left: candidate.left,
+    top: candidate.top,
+    right: candidate.left + size.width,
+    bottom: candidate.top + size.height
+  });
+  const isClear = (candidate) => !excluded.some((target) => overlaps(rectFor(candidate), target));
+  if (isClear(bounded)) return bounded;
+  const clear = excluded.flatMap((target) => [
+    { left: bounded.left, top: target.top - size.height - gap },
+    { left: bounded.left, top: target.bottom + gap },
+    { left: target.left - size.width - gap, top: bounded.top },
+    { left: target.right + gap, top: bounded.top }
+  ]).map(keepOnScreen).filter(isClear);
+  if (clear.length === 0) return bounded;
+  const distance = (candidate) => Math.hypot(candidate.left - bounded.left, candidate.top - bounded.top);
+  return clear.reduce((nearest, candidate) => distance(candidate) < distance(nearest) ? candidate : nearest);
+}
+function samePosition(a, b) {
+  if (!a || !b) return a === b || !a && !b;
+  return a.x === b.x && a.y === b.y && a.corner === b.corner;
+}
+
+// src/dock/store.ts
+var import_react = require("react");
+var DOCK_STORAGE_PREFIX = "matrx:summon:dock:";
+var CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right"];
+function parseDockPosition(value) {
+  if (!value || typeof value !== "object") return null;
+  const { x, y, corner } = value;
+  if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y)) return null;
+  if (corner !== void 0 && !CORNERS.includes(corner)) return null;
+  return corner === void 0 ? { x, y } : { x, y, corner };
+}
+function storage() {
+  try {
+    return typeof window === "undefined" ? null : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function createLocalDockStore(prefix = DOCK_STORAGE_PREFIX) {
+  return {
+    read(id) {
+      try {
+        const raw = storage()?.getItem(prefix + id);
+        return raw ? parseDockPosition(JSON.parse(raw)) : null;
+      } catch {
+        return null;
+      }
+    },
+    write(id, position) {
+      try {
+        const area = storage();
+        if (!area) return;
+        if (position) area.setItem(prefix + id, JSON.stringify(position));
+        else area.removeItem(prefix + id);
+      } catch {
+      }
+    }
+  };
+}
+var memoryOnlyDockStore = { read: () => null, write: () => void 0 };
+var defaultStore = createLocalDockStore();
+var DockStoreContext = (0, import_react.createContext)(null);
+function DockProvider({ store, children }) {
+  return (0, import_react.createElement)(DockStoreContext.Provider, { value: store }, children);
+}
+function useDockStore(own) {
+  const provided = (0, import_react.useContext)(DockStoreContext);
+  return own ?? provided ?? defaultStore;
+}
+
+// src/dock/useDock.ts
+var DEFAULT_DOCK_IGNORE = "button,a,input,select,textarea,[contenteditable='true'],[data-no-drag]";
+var SSR_VIEWPORT = { width: 1280, height: 800 };
+var noopSubscribe = () => () => void 0;
+function readViewport() {
+  return typeof window === "undefined" ? SSR_VIEWPORT : { width: window.innerWidth, height: window.innerHeight };
+}
+function measure(element) {
+  return { width: element?.offsetWidth ?? 0, height: element?.offsetHeight ?? 0 };
+}
+function excludedRects(avoid, self) {
+  if (!avoid || typeof document === "undefined") return [];
+  return [...document.querySelectorAll(avoid.selector)].filter((target) => target !== self && !self?.contains(target)).map((target) => target.getBoundingClientRect()).filter((rect) => rect.width > 0 && rect.height > 0);
+}
+function useDock(options) {
+  const {
+    id,
+    corner = "bottom-right",
+    defaultPosition = null,
+    anchor,
+    position: controlled,
+    onPositionChange,
+    persist = true,
+    draggable = true,
+    touch = true,
+    threshold = DEFAULT_DRAG_THRESHOLD,
+    clamp,
+    avoid,
+    snapToCorner = false,
+    zIndex: baseZ,
+    raiseOnPress = true,
+    ignore = DEFAULT_DOCK_IGNORE
+  } = options;
+  const isControlled = controlled !== void 0;
+  const providedStore = useDockStore(options.store);
+  const store = persist && !isControlled ? providedStore : memoryOnlyDockStore;
+  const [element, setElement] = (0, import_react2.useState)(null);
+  const [local, setLocal] = (0, import_react2.useState)(null);
+  const [pending, setPending] = (0, import_react2.useState)(null);
+  const [geometry, setGeometry] = (0, import_react2.useState)({ viewport: SSR_VIEWPORT, size: { width: 0, height: 0 } });
+  const [nudge, setNudge] = (0, import_react2.useState)(null);
+  const [dragging, setDragging] = (0, import_react2.useState)(false);
+  const pressRef = (0, import_react2.useRef)(null);
+  const frameRef = (0, import_react2.useRef)(null);
+  const adoptingRef = (0, import_react2.useRef)(false);
+  const restoredRef = (0, import_react2.useRef)(null);
+  const chosen = isControlled ? pending && samePosition(pending.forProp, controlled) ? pending.value : controlled : local;
+  const raw = chosen ?? defaultPosition;
+  const rawCorner = raw?.corner ?? corner;
+  const offset = raw ? clampOffset(raw, rawCorner, geometry.size, geometry.viewport, clamp) : null;
+  const live = (0, import_react2.useRef)({ offset, rawCorner, clamp, avoid, threshold, snapToCorner, onPositionChange, isControlled, controlled, store, id });
+  (0, import_react2.useEffect)(() => {
+    live.current = { offset, rawCorner, clamp, avoid, threshold, snapToCorner, onPositionChange, isControlled, controlled, store, id };
+  });
+  (0, import_react2.useLayoutEffect)(() => {
+    if (!element || restoredRef.current === id) return;
+    restoredRef.current = id;
+    if (isControlled) return;
+    setLocal(store.read(id));
+  }, [element, id, isControlled, store]);
+  (0, import_react2.useLayoutEffect)(() => {
+    if (!element) return void 0;
+    let frame = null;
+    const read = () => {
+      const next = { viewport: readViewport(), size: measure(element) };
+      setGeometry(
+        (current) => current.viewport.width === next.viewport.width && current.viewport.height === next.viewport.height && current.size.width === next.size.width && current.size.height === next.size.height ? current : next
+      );
+    };
+    const schedule = () => {
+      if (frame !== null) return;
+      frame = window.requestAnimationFrame(() => {
+        frame = null;
+        read();
+      });
+    };
+    read();
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+    observer?.observe(element);
+    window.addEventListener("resize", schedule);
+    return () => {
+      observer?.disconnect();
+      window.removeEventListener("resize", schedule);
+      if (frame !== null) window.cancelAnimationFrame(frame);
+    };
+  }, [element]);
+  const avoidSelector = avoid?.selector;
+  const avoidGap = avoid?.gap;
+  (0, import_react2.useLayoutEffect)(() => {
+    if (!element || !avoidSelector || offset) {
+      setNudge((current) => current === null ? current : null);
+      return void 0;
+    }
+    let frame = null;
+    let applied = null;
+    const reconcile = () => {
+      const rect = element.getBoundingClientRect();
+      const size = measure(element);
+      const viewport = readViewport();
+      const base = { left: rect.left - (applied?.left ?? 0), top: rect.top - (applied?.top ?? 0) };
+      const keep = (p) => {
+        const o = clampOffset(fromScreen(p, "top-left", size, viewport), "top-left", size, viewport, live.current.clamp);
+        return toScreen(o, "top-left", size, viewport);
+      };
+      const clear = avoidExclusions(base, size, excludedRects({ selector: avoidSelector }, element), avoidGap ?? DEFAULT_DOCK_MARGIN, keep);
+      const next = { left: Math.round(clear.left - base.left), top: Math.round(clear.top - base.top) };
+      applied = next.left === 0 && next.top === 0 ? null : next;
+      setNudge(
+        (current) => current === null && applied === null || current && applied && current.left === applied.left && current.top === applied.top ? current : applied
+      );
+    };
+    const schedule = () => {
+      if (frame !== null) return;
+      frame = window.requestAnimationFrame(() => {
+        frame = null;
+        reconcile();
+      });
+    };
+    reconcile();
+    const mutations = typeof MutationObserver === "undefined" ? null : new MutationObserver(schedule);
+    mutations?.observe(document.body, { childList: true, subtree: true });
+    window.addEventListener("resize", schedule);
+    window.addEventListener("scroll", schedule, true);
+    return () => {
+      mutations?.disconnect();
+      window.removeEventListener("resize", schedule);
+      window.removeEventListener("scroll", schedule, true);
+      if (frame !== null) window.cancelAnimationFrame(frame);
+    };
+  }, [element, avoidSelector, avoidGap, offset === null]);
+  let placed = null;
+  if (offset) {
+    placed = toScreen(offset, rawCorner, geometry.size, geometry.viewport);
+    if (avoid && element) {
+      const size = geometry.size;
+      const viewport = geometry.viewport;
+      const keep = (p) => toScreen(clampOffset(fromScreen(p, "top-left", size, viewport), "top-left", size, viewport, clamp), "top-left", size, viewport);
+      placed = avoidExclusions(placed, size, excludedRects(avoid, element), avoid.gap ?? DEFAULT_DOCK_MARGIN, keep);
+    }
+  }
+  const renderedOffset = placed && offset ? fromScreen(placed, rawCorner, geometry.size, geometry.viewport) : offset;
+  (0, import_react2.useLayoutEffect)(() => {
+    if (!adoptingRef.current) return;
+    adoptingRef.current = false;
+    element?.style.removeProperty("translate");
+  });
+  const summonStore = (0, import_react3.useOptionalSummonStore)();
+  const laneZ = (0, import_react2.useSyncExternalStore)(
+    summonStore ? summonStore.subscribe : noopSubscribe,
+    () => summonStore ? summonStore.getState().windowManager?.transientZ?.[id] : void 0,
+    () => void 0
+  );
+  (0, import_react2.useEffect)(() => {
+    if (!summonStore) return void 0;
+    return () => {
+      const state = summonStore.getState();
+      if (state.windowManager?.transientZ?.[id] !== void 0) summonStore.dispatch((0, import_summon.releaseTransientWindow)(id));
+    };
+  }, [summonStore, id]);
+  const zIndex = laneZ ?? baseZ;
+  (0, import_react2.useEffect)(
+    () => () => {
+      pressRef.current?.cleanup();
+      pressRef.current = null;
+    },
+    []
+  );
+  const commit = (0, import_react2.useCallback)((next) => {
+    const current = live.current;
+    adoptingRef.current = true;
+    if (current.isControlled) setPending({ value: next, forProp: current.controlled ?? null });
+    else {
+      setLocal(next);
+      current.store.write(current.id, next);
+    }
+    current.onPositionChange?.(next);
+  }, []);
+  const onPointerDown = (0, import_react2.useCallback)(
+    (event) => {
+      if (!draggable || event.button !== 0 || !element) return;
+      if (!touch && event.pointerType === "touch") return;
+      const target = event.target;
+      if (ignore && target) {
+        const hit = target.closest(ignore);
+        if (hit && hit !== event.currentTarget && event.currentTarget.contains(hit)) return;
+      }
+      pressRef.current?.cleanup();
+      if (raiseOnPress && summonStore) summonStore.dispatch((0, import_summon.raiseTransientWindow)(id));
+      if (!target?.closest("button,a,input,select,textarea,label,[role=button]")) event.preventDefault();
+      const rect = element.getBoundingClientRect();
+      const viewport = readViewport();
+      const size = measure(element);
+      const press = {
+        pointerId: event.pointerId,
+        startX: event.clientX,
+        startY: event.clientY,
+        origin: { left: rect.left, top: rect.top },
+        size,
+        viewport,
+        active: false,
+        latest: { left: rect.left, top: rect.top },
+        release: null,
+        cleanup: () => void 0
+      };
+      const startOffset = live.current.offset ?? fromScreen(press.origin, live.current.rawCorner, size, viewport);
+      const startCorner = live.current.rawCorner;
+      const startScreen = toScreen(startOffset, startCorner, size, viewport);
+      const paint = () => {
+        frameRef.current = null;
+        const active = pressRef.current;
+        if (!active || !active.active) return;
+        element.style.translate = `${active.latest.left - startScreen.left}px ${active.latest.top - startScreen.top}px`;
+      };
+      const move = (e) => {
+        if (e.pointerId !== press.pointerId) return;
+        const dx = e.clientX - press.startX;
+        const dy = e.clientY - press.startY;
+        const opts = live.current;
+        if (!press.active) {
+          if (Math.abs(dx) < opts.threshold && Math.abs(dy) < opts.threshold) return;
+          press.active = true;
+          press.release = (0, import_design_system.holdDragCursor)("grabbing");
+          setDragging(true);
+        }
+        const desired = fromScreen({ left: startScreen.left + dx, top: startScreen.top + dy }, startCorner, size, viewport);
+        let next = toScreen(clampOffset(desired, startCorner, size, viewport, opts.clamp), startCorner, size, viewport);
+        if (opts.avoid) {
+          const keep = (p) => toScreen(clampOffset(fromScreen(p, "top-left", size, viewport), "top-left", size, viewport, opts.clamp), "top-left", size, viewport);
+          next = avoidExclusions(next, size, excludedRects(opts.avoid, element), opts.avoid.gap ?? DEFAULT_DOCK_MARGIN, keep);
+        }
+        press.latest = next;
+        if (frameRef.current === null) {
+          if (typeof window.requestAnimationFrame === "function") frameRef.current = window.requestAnimationFrame(paint);
+          else paint();
+        }
+      };
+      const end = (e) => {
+        if (e.pointerId !== press.pointerId) return;
+        press.cleanup();
+        pressRef.current = null;
+        if (!press.active) return;
+        press.release?.();
+        setDragging(false);
+        const opts = live.current;
+        const finalCorner = opts.snapToCorner ? nearestCorner(press.latest, size, viewport) : startCorner;
+        const finalOffset = clampOffset(fromScreen(press.latest, finalCorner, size, viewport), finalCorner, size, viewport, opts.clamp);
+        commit(finalCorner === corner ? { x: finalOffset.x, y: finalOffset.y } : { ...finalOffset, corner: finalCorner });
+        const swallow = (click) => {
+          click.stopPropagation();
+          click.preventDefault();
+        };
+        window.addEventListener("click", swallow, { capture: true, once: true });
+        window.setTimeout(() => window.removeEventListener("click", swallow, { capture: true }), 0);
+      };
+      press.cleanup = () => {
+        window.removeEventListener("pointermove", move);
+        window.removeEventListener("pointerup", end);
+        window.removeEventListener("pointercancel", end);
+        if (frameRef.current !== null) {
+          window.cancelAnimationFrame?.(frameRef.current);
+          frameRef.current = null;
+        }
+        if (!press.active) return;
+        press.release?.();
+        press.release = null;
+      };
+      pressRef.current = press;
+      window.addEventListener("pointermove", move);
+      window.addEventListener("pointerup", end);
+      window.addEventListener("pointercancel", end);
+    },
+    [commit, corner, draggable, element, id, ignore, raiseOnPress, summonStore, touch]
+  );
+  const reset = (0, import_react2.useCallback)(() => {
+    adoptingRef.current = true;
+    commit(null);
+  }, [commit]);
+  let style;
+  if (renderedOffset) {
+    const left = rawCorner.endsWith("left");
+    const top = rawCorner.startsWith("top");
+    style = {
+      position: "fixed",
+      left: left ? renderedOffset.x : "auto",
+      right: left ? "auto" : renderedOffset.x,
+      top: top ? renderedOffset.y : "auto",
+      bottom: top ? "auto" : renderedOffset.y
+    };
+  } else {
+    const transform = [anchor?.centerX ? "translateX(-50%)" : null, nudge ? `translate(${nudge.left}px, ${nudge.top}px)` : null].filter(Boolean).join(" ");
+    style = {
+      position: "fixed",
+      top: anchor?.top,
+      bottom: anchor?.bottom,
+      left: anchor?.centerX ? "50%" : anchor?.left,
+      right: anchor?.right,
+      ...transform ? { transform } : {}
+    };
+  }
+  if (zIndex !== void 0) style.zIndex = zIndex;
+  return {
+    ref: setElement,
+    element,
+    style,
+    handleProps: {
+      onPointerDown,
+      style: draggable ? { cursor: "grab", touchAction: touch ? "none" : "auto" } : {},
+      "data-dock-handle": ""
+    },
+    offset: renderedOffset,
+    corner: rawCorner,
+    dragging,
+    moved: chosen !== null,
+    zIndex,
+    reset
+  };
+}
+
+// src/dock/Dock.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var DockContext = (0, import_react4.createContext)(null);
+function useDockContext() {
+  const dock = (0, import_react4.useContext)(DockContext);
+  if (!dock) throw new Error("[summon] useDockContext() must be used inside <Dock>");
+  return dock;
+}
+var OPTION_KEYS = [
+  "id",
+  "corner",
+  "defaultPosition",
+  "anchor",
+  "position",
+  "onPositionChange",
+  "persist",
+  "store",
+  "draggable",
+  "touch",
+  "threshold",
+  "clamp",
+  "avoid",
+  "snapToCorner",
+  "zIndex",
+  "raiseOnPress",
+  "ignore"
+];
+function Dock(props) {
+  const options = {};
+  const rest = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (OPTION_KEYS.includes(key)) options[key] = value;
+    else if (key !== "handle" && key !== "children" && key !== "style") rest[key] = value;
+  }
+  const dock = useDock(options);
+  const self = props.handle === "self";
+  const style = { ...props.style, ...dock.style, ...self ? dock.handleProps.style : {} };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DockContext.Provider, { value: dock, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      ...rest,
+      ref: dock.ref,
+      "data-dock": props.id,
+      "data-dragging": dock.dragging ? "" : void 0,
+      style,
+      ...self ? { onPointerDown: dock.handleProps.onPointerDown, "data-dock-handle": "" } : {},
+      children: typeof props.children === "function" ? props.children(dock) : props.children
+    }
+  ) });
+}
+function DockHandle({ style, onPointerDown, ...rest }) {
+  const dock = useDockContext();
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      ...rest,
+      ...dock.handleProps,
+      style: { ...style, ...dock.handleProps.style },
+      onPointerDown: (event) => {
+        onPointerDown?.(event);
+        dock.handleProps.onPointerDown(event);
+      }
+    }
+  );
+}
+//# sourceMappingURL=dock.cjs.map