@ai-matrx/summon 0.1.3 → 0.1.5

package/dist/dock.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/dock.ts","../src/dock/Dock.tsx","../src/dock/useDock.ts","../src/dock/geometry.ts","../src/dock/store.ts"],"sourcesContent":["// @ai-matrx/summon/dock — the one primitive for floating chrome-less cards, pills and docks:\n// pointer drag that never re-renders while moving (CSS translate in one rAF, one commit on release),\n// corner-relative positions clamped to the viewport with an optional nearest-corner snap, a position\n// remembered per dock id (host store via DockProvider, else localStorage) or reported to a controlled\n// host, the window manager's z-order lane on press, THE CURSOR LAW drag hold. Zero cost until mounted.\nexport { Dock, DockHandle, useDockContext, type DockProps, type DockHandleProps } from \"./dock/Dock\";\nexport {\n  useDock,\n  DEFAULT_DOCK_IGNORE,\n  type UseDockOptions,\n  type DockApi,\n  type DockAnchor,\n  type DockHandleBindings,\n} from \"./dock/useDock\";\nexport {\n  DockProvider,\n  useDockStore,\n  createLocalDockStore,\n  memoryOnlyDockStore,\n  parseDockPosition,\n  DOCK_STORAGE_PREFIX,\n  type DockPositionStore,\n  type DockProviderProps,\n} from \"./dock/store\";\nexport {\n  clampOffset,\n  toScreen,\n  fromScreen,\n  nearestCorner,\n  avoidExclusions,\n  DEFAULT_DOCK_MARGIN,\n  DEFAULT_DRAG_THRESHOLD,\n  type DockCorner,\n  type DockOffset,\n  type DockPosition,\n  type DockSize,\n  type DockClamp,\n  type ScreenPoint,\n  type ScreenRect,\n} from \"./dock/geometry\";\n","/**\n * `<Dock>` — the component form of `useDock()`: a fixed, chrome-less element that\n * moves. Drag it by a `<DockHandle>` inside it, or by the whole dock with\n * `handle=\"self\"`. `useDockContext()` reaches the dock's API from anywhere inside\n * (a \"Move back to the corner\" menu item calls `reset()`).\n */\n\nimport { createContext, useContext, type CSSProperties, type HTMLAttributes, type ReactNode } from \"react\";\nimport { useDock, type DockApi, type UseDockOptions } from \"./useDock\";\n\nconst DockContext = createContext<DockApi | null>(null);\n\n/** The enclosing dock's API; throws outside a `<Dock>`. */\nexport function useDockContext(): DockApi {\n  const dock = useContext(DockContext);\n  if (!dock) throw new Error(\"[summon] useDockContext() must be used inside <Dock>\");\n  return dock;\n}\n\nexport interface DockProps extends UseDockOptions, Omit<HTMLAttributes<HTMLDivElement>, \"id\" | \"children\" | \"draggable\"> {\n  /** \"self\": the whole dock is the drag handle. Default: only `<DockHandle>`s drag. */\n  handle?: \"self\" | \"inner\";\n  children?: ReactNode | ((dock: DockApi) => ReactNode);\n}\n\nconst OPTION_KEYS = [\n  \"id\", \"corner\", \"defaultPosition\", \"anchor\", \"position\", \"onPositionChange\", \"persist\", \"store\", \"draggable\",\n  \"touch\", \"threshold\", \"clamp\", \"avoid\", \"snapToCorner\", \"zIndex\", \"raiseOnPress\", \"ignore\",\n] as const satisfies readonly (keyof UseDockOptions)[];\n\nexport function Dock(props: DockProps): ReactNode {\n  const options = {} as UseDockOptions;\n  const rest: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(props)) {\n    if ((OPTION_KEYS as readonly string[]).includes(key)) (options as unknown as Record<string, unknown>)[key] = value;\n    else if (key !== \"handle\" && key !== \"children\" && key !== \"style\") rest[key] = value;\n  }\n  const dock = useDock(options);\n  const self = props.handle === \"self\";\n  const style: CSSProperties = { ...props.style, ...dock.style, ...(self ? dock.handleProps.style : {}) };\n  return (\n    <DockContext.Provider value={dock}>\n      <div\n        {...(rest as HTMLAttributes<HTMLDivElement>)}\n        ref={dock.ref}\n        data-dock={props.id}\n        data-dragging={dock.dragging ? \"\" : undefined}\n        style={style}\n        {...(self ? { onPointerDown: dock.handleProps.onPointerDown, \"data-dock-handle\": \"\" } : {})}\n      >\n        {typeof props.children === \"function\" ? props.children(dock) : props.children}\n      </div>\n    </DockContext.Provider>\n  );\n}\n\nexport interface DockHandleProps extends HTMLAttributes<HTMLDivElement> {\n  children?: ReactNode;\n}\n\n/** The part of a `<Dock>` you drag it by. Buttons and fields inside stay controls. */\nexport function DockHandle({ style, onPointerDown, ...rest }: DockHandleProps): ReactNode {\n  const dock = useDockContext();\n  return (\n    <div\n      {...rest}\n      {...dock.handleProps}\n      style={{ ...style, ...dock.handleProps.style }}\n      onPointerDown={(event) => {\n        onPointerDown?.(event);\n        dock.handleProps.onPointerDown(event);\n      }}\n    />\n  );\n}\n","/**\n * `useDock()` — the one primitive for floating chrome-less cards, pills and docks.\n *\n * THE RULE (paid for in the Workflow Studio's FloatingChatPanel and chat's\n * ChatPanel): a pointer move paints the CSS `translate` property inside ONE\n * requestAnimationFrame and React state is committed EXACTLY ONCE, on release.\n * Writing state per pointer event re-renders whatever streams inside the dock\n * sixty times a second. `translate` composes with the host's own `transform`\n * and with any `left/right/top/bottom` it computes, so a host that builds its\n * own placement (CSS variables, lifts) still drags without re-rendering.\n *\n * What else it carries:\n *  - a drag is never a click: below `threshold` px the gesture stays a click;\n *    past it the trailing click is swallowed once;\n *  - the position is an offset from a corner, clamped to the viewport on every\n *    render (a position saved on a wide monitor never strands the dock), and\n *    can snap to the nearest corner on release;\n *  - it remembers its place per dock id (the store chain in ./store) or reports\n *    it to a controlled host (`position` + `onPositionChange`, e.g. per-user sync);\n *  - it joins the window manager's z-order lane on press (raised above every\n *    window, below modals) when a SummonProvider is present;\n *  - THE CURSOR LAW: the drag holds `grabbing` with design-system `holdDragCursor`;\n *  - zero cost until mounted: no listener exists outside an active press.\n */\n\nimport {\n  useCallback,\n  useEffect,\n  useLayoutEffect,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type CSSProperties,\n  type PointerEvent as ReactPointerEvent,\n} from \"react\";\nimport { holdDragCursor } from \"@ai-matrx/design-system\";\nimport { raiseTransientWindow, releaseTransientWindow } from \"@ai-matrx/summon\";\nimport { useOptionalSummonStore } from \"@ai-matrx/summon/react\";\nimport {\n  avoidExclusions,\n  clampOffset,\n  DEFAULT_DOCK_MARGIN,\n  DEFAULT_DRAG_THRESHOLD,\n  fromScreen,\n  nearestCorner,\n  samePosition,\n  toScreen,\n  type DockClamp,\n  type DockCorner,\n  type DockOffset,\n  type DockPosition,\n  type DockSize,\n  type ScreenPoint,\n  type ScreenRect,\n} from \"./geometry\";\nimport { memoryOnlyDockStore, useDockStore, type DockPositionStore } from \"./store\";\n\n/** CSS placement used while the dock has no position (never moved, no `defaultPosition`). */\nexport interface DockAnchor {\n  top?: string;\n  bottom?: string;\n  left?: string;\n  right?: string;\n  /** Centre horizontally (`left: 50%` + translateX(-50%)). */\n  centerX?: boolean;\n}\n\n/** Controls inside the handle that stay controls — a press there never starts a drag. */\nexport const DEFAULT_DOCK_IGNORE = \"button,a,input,select,textarea,[contenteditable='true'],[data-no-drag]\";\n\nexport interface UseDockOptions {\n  /** Identity: the remembered position, the z-order lane entry. Unique per dock. */\n  id: string;\n  /** The corner positions are measured from. Default \"bottom-right\". */\n  corner?: DockCorner;\n  /** Resting offset from `corner` before the person moves it. Omit to rest on `anchor`. */\n  defaultPosition?: DockOffset | null;\n  /** CSS resting place when there is no position at all. */\n  anchor?: DockAnchor;\n  /** Controlled position (the host owns storage, e.g. a per-user preference). `null` = resting. */\n  position?: DockPosition | null;\n  /** Told once per drag, on release, and on `reset()` (with `null`). */\n  onPositionChange?: (position: DockPosition | null) => void;\n  /** Remember the position across reloads (uncontrolled only). Default true. */\n  persist?: boolean;\n  /** This dock's own store; otherwise the nearest `<DockProvider>`, else localStorage. */\n  store?: DockPositionStore;\n  /** Default true. Pass false on surfaces that must not move (a phone sheet). */\n  draggable?: boolean;\n  /** Allow touch drags. Default true; a dock that fights page scroll passes false. */\n  touch?: boolean;\n  /** Px a pointer must travel before a press becomes a drag. Default 4. */\n  threshold?: number;\n  clamp?: DockClamp;\n  /** Fixed controls the dock must stay off (nearest clear spot wins). */\n  avoid?: { selector: string; gap?: number };\n  /** On release, re-anchor to the nearest corner. Default false. */\n  snapToCorner?: boolean;\n  /** z-index before the first press raises it into the window lane. */\n  zIndex?: number;\n  /** Raise into the window manager's z-order lane on press. Default true. */\n  raiseOnPress?: boolean;\n  /** Selector of controls inside the handle that never start a drag. `null` = every press may drag. */\n  ignore?: string | null;\n}\n\nexport interface DockHandleBindings {\n  onPointerDown(event: ReactPointerEvent<HTMLElement>): void;\n  style: CSSProperties;\n  \"data-dock-handle\": \"\";\n}\n\nexport interface DockApi {\n  /** Attach to the element that MOVES. */\n  ref: (element: HTMLElement | null) => void;\n  element: HTMLElement | null;\n  /** Spread onto the moving element: fixed placement (placed or anchored) + z-index. */\n  style: CSSProperties;\n  /** Spread onto the element you drag BY (or the whole dock). */\n  handleProps: DockHandleBindings;\n  /** The clamped offset from `corner`; null while resting on `anchor`. */\n  offset: DockOffset | null;\n  /** The corner `offset` is measured from. */\n  corner: DockCorner;\n  /** True from the moment a press passes the threshold until release. */\n  dragging: boolean;\n  /** The person has moved it (a remembered or controlled position exists). */\n  moved: boolean;\n  /** Current z-index: the lane's once raised, else the `zIndex` option. */\n  zIndex: number | undefined;\n  /** Forget the position; the dock returns to its resting place. */\n  reset(): void;\n}\n\nconst SSR_VIEWPORT: DockSize = { width: 1280, height: 800 };\nconst noopSubscribe = () => () => undefined;\n\ninterface Geometry {\n  viewport: DockSize;\n  size: DockSize;\n}\n\ninterface Press {\n  pointerId: number;\n  startX: number;\n  startY: number;\n  /** The dock's top-left when pressed. */\n  origin: ScreenPoint;\n  size: DockSize;\n  viewport: DockSize;\n  active: boolean;\n  latest: ScreenPoint;\n  release: (() => void) | null;\n  cleanup: () => void;\n}\n\nfunction readViewport(): DockSize {\n  return typeof window === \"undefined\" ? SSR_VIEWPORT : { width: window.innerWidth, height: window.innerHeight };\n}\n\nfunction measure(element: HTMLElement | null): DockSize {\n  return { width: element?.offsetWidth ?? 0, height: element?.offsetHeight ?? 0 };\n}\n\nfunction excludedRects(avoid: UseDockOptions[\"avoid\"], self: HTMLElement | null): ScreenRect[] {\n  if (!avoid || typeof document === \"undefined\") return [];\n  return [...document.querySelectorAll<HTMLElement>(avoid.selector)]\n    .filter((target) => target !== self && !self?.contains(target))\n    .map((target) => target.getBoundingClientRect())\n    .filter((rect) => rect.width > 0 && rect.height > 0);\n}\n\nexport function useDock(options: UseDockOptions): DockApi {\n  const {\n    id,\n    corner = \"bottom-right\",\n    defaultPosition = null,\n    anchor,\n    position: controlled,\n    onPositionChange,\n    persist = true,\n    draggable = true,\n    touch = true,\n    threshold = DEFAULT_DRAG_THRESHOLD,\n    clamp,\n    avoid,\n    snapToCorner = false,\n    zIndex: baseZ,\n    raiseOnPress = true,\n    ignore = DEFAULT_DOCK_IGNORE,\n  } = options;\n  const isControlled = controlled !== undefined;\n  const providedStore = useDockStore(options.store);\n  const store = persist && !isControlled ? providedStore : memoryOnlyDockStore;\n\n  const [element, setElement] = useState<HTMLElement | null>(null);\n  const [local, setLocal] = useState<DockPosition | null>(null);\n  /** A controlled commit, shown until the host's `position` changes (it may update async). */\n  const [pending, setPending] = useState<{ value: DockPosition | null; forProp: DockPosition | null } | null>(null);\n  const [geometry, setGeometry] = useState<Geometry>({ viewport: SSR_VIEWPORT, size: { width: 0, height: 0 } });\n  const [nudge, setNudge] = useState<ScreenPoint | null>(null);\n  const [dragging, setDragging] = useState(false);\n  const pressRef = useRef<Press | null>(null);\n  const frameRef = useRef<number | null>(null);\n  const adoptingRef = useRef(false);\n  const restoredRef = useRef<string | null>(null);\n\n  // ── The position, resolved ───────────────────────────────────────────────\n  const chosen: DockPosition | null = isControlled\n    ? pending && samePosition(pending.forProp, controlled) ? pending.value : controlled\n    : local;\n  const raw: DockPosition | null = chosen ?? defaultPosition;\n  const rawCorner = raw?.corner ?? corner;\n  const offset = raw ? clampOffset(raw, rawCorner, geometry.size, geometry.viewport, clamp) : null;\n\n  // Live refs for the press listeners (written in effects, never during render).\n  const live = useRef({ offset, rawCorner, clamp, avoid, threshold, snapToCorner, onPositionChange, isControlled, controlled, store, id });\n  useEffect(() => {\n    live.current = { offset, rawCorner, clamp, avoid, threshold, snapToCorner, onPositionChange, isControlled, controlled, store, id };\n  });\n\n  // Restore the remembered position BEFORE paint, once per id, as soon as the element exists.\n  useLayoutEffect(() => {\n    if (!element || restoredRef.current === id) return;\n    restoredRef.current = id;\n    if (isControlled) return;\n    setLocal(store.read(id));\n  }, [element, id, isControlled, store]);\n\n  // Track the viewport and the dock's own size (expanded/collapsed content), re-clamping on change.\n  useLayoutEffect(() => {\n    if (!element) return undefined;\n    let frame: number | null = null;\n    const read = () => {\n      const next: Geometry = { viewport: readViewport(), size: measure(element) };\n      setGeometry((current) =>\n        current.viewport.width === next.viewport.width &&\n        current.viewport.height === next.viewport.height &&\n        current.size.width === next.size.width &&\n        current.size.height === next.size.height\n          ? current\n          : next,\n      );\n    };\n    const schedule = () => {\n      if (frame !== null) return;\n      frame = window.requestAnimationFrame(() => {\n        frame = null;\n        read();\n      });\n    };\n    read();\n    const observer = typeof ResizeObserver === \"undefined\" ? null : new ResizeObserver(schedule);\n    observer?.observe(element);\n    window.addEventListener(\"resize\", schedule);\n    return () => {\n      observer?.disconnect();\n      window.removeEventListener(\"resize\", schedule);\n      if (frame !== null) window.cancelAnimationFrame(frame);\n    };\n  }, [element]);\n\n  // Exclusions: a placed dock is moved to the nearest clear spot at render; a resting (anchored)\n  // dock gets a measured nudge, re-read whenever the page under it changes.\n  const avoidSelector = avoid?.selector;\n  const avoidGap = avoid?.gap;\n  useLayoutEffect(() => {\n    if (!element || !avoidSelector || offset) {\n      setNudge((current) => (current === null ? current : null));\n      return undefined;\n    }\n    let frame: number | null = null;\n    let applied: ScreenPoint | null = null;\n    const reconcile = () => {\n      const rect = element.getBoundingClientRect();\n      const size = measure(element);\n      const viewport = readViewport();\n      const base = { left: rect.left - (applied?.left ?? 0), top: rect.top - (applied?.top ?? 0) };\n      const keep = (p: ScreenPoint) => {\n        const o = clampOffset(fromScreen(p, \"top-left\", size, viewport), \"top-left\", size, viewport, live.current.clamp);\n        return toScreen(o, \"top-left\", size, viewport);\n      };\n      const clear = avoidExclusions(base, size, excludedRects({ selector: avoidSelector }, element), avoidGap ?? DEFAULT_DOCK_MARGIN, keep);\n      const next = { left: Math.round(clear.left - base.left), top: Math.round(clear.top - base.top) };\n      applied = next.left === 0 && next.top === 0 ? null : next;\n      setNudge((current) =>\n        (current === null && applied === null) || (current && applied && current.left === applied.left && current.top === applied.top)\n          ? current\n          : applied,\n      );\n    };\n    const schedule = () => {\n      if (frame !== null) return;\n      frame = window.requestAnimationFrame(() => {\n        frame = null;\n        reconcile();\n      });\n    };\n    reconcile();\n    const mutations = typeof MutationObserver === \"undefined\" ? null : new MutationObserver(schedule);\n    mutations?.observe(document.body, { childList: true, subtree: true });\n    window.addEventListener(\"resize\", schedule);\n    window.addEventListener(\"scroll\", schedule, true);\n    return () => {\n      mutations?.disconnect();\n      window.removeEventListener(\"resize\", schedule);\n      window.removeEventListener(\"scroll\", schedule, true);\n      if (frame !== null) window.cancelAnimationFrame(frame);\n    };\n  }, [element, avoidSelector, avoidGap, offset === null]); // eslint-disable-line react-hooks/exhaustive-deps\n\n  /** A placed dock that would cover an excluded control renders at the nearest clear spot. */\n  let placed: ScreenPoint | null = null;\n  if (offset) {\n    placed = toScreen(offset, rawCorner, geometry.size, geometry.viewport);\n    if (avoid && element) {\n      const size = geometry.size;\n      const viewport = geometry.viewport;\n      const keep = (p: ScreenPoint) =>\n        toScreen(clampOffset(fromScreen(p, \"top-left\", size, viewport), \"top-left\", size, viewport, clamp), \"top-left\", size, viewport);\n      placed = avoidExclusions(placed, size, excludedRects(avoid, element), avoid.gap ?? DEFAULT_DOCK_MARGIN, keep);\n    }\n  }\n  const renderedOffset = placed && offset ? fromScreen(placed, rawCorner, geometry.size, geometry.viewport) : offset;\n\n  // The committed position replaces the paint offset in the SAME commit: clear `translate` now.\n  useLayoutEffect(() => {\n    if (!adoptingRef.current) return;\n    adoptingRef.current = false;\n    element?.style.removeProperty(\"translate\");\n  });\n\n  // ── The z-order lane ────────────────────────────────────────────────────\n  const summonStore = useOptionalSummonStore();\n  const laneZ = useSyncExternalStore(\n    summonStore ? summonStore.subscribe : noopSubscribe,\n    () => (summonStore ? (summonStore.getState() as { windowManager?: { transientZ?: Record<string, number> } }).windowManager?.transientZ?.[id] : undefined),\n    () => undefined,\n  );\n  useEffect(() => {\n    if (!summonStore) return undefined;\n    return () => {\n      const state = summonStore.getState() as { windowManager?: { transientZ?: Record<string, number> } };\n      if (state.windowManager?.transientZ?.[id] !== undefined) summonStore.dispatch(releaseTransientWindow(id));\n    };\n  }, [summonStore, id]);\n  const zIndex = laneZ ?? baseZ;\n\n  // ── The drag ────────────────────────────────────────────────────────────\n  useEffect(\n    () => () => {\n      pressRef.current?.cleanup();\n      pressRef.current = null;\n    },\n    [],\n  );\n\n  const commit = useCallback((next: DockPosition | null) => {\n    const current = live.current;\n    adoptingRef.current = true;\n    if (current.isControlled) setPending({ value: next, forProp: current.controlled ?? null });\n    else {\n      setLocal(next);\n      current.store.write(current.id, next);\n    }\n    current.onPositionChange?.(next);\n  }, []);\n\n  const onPointerDown = useCallback(\n    (event: ReactPointerEvent<HTMLElement>) => {\n      if (!draggable || event.button !== 0 || !element) return;\n      if (!touch && event.pointerType === \"touch\") return;\n      const target = event.target as HTMLElement | null;\n      if (ignore && target) {\n        const hit = target.closest(ignore);\n        if (hit && hit !== event.currentTarget && event.currentTarget.contains(hit)) return;\n      }\n      pressRef.current?.cleanup();\n      if (raiseOnPress && summonStore) summonStore.dispatch(raiseTransientWindow(id));\n      // A press on bare chrome must not start a text selection; a press on a control keeps its default.\n      if (!target?.closest(\"button,a,input,select,textarea,label,[role=button]\")) event.preventDefault();\n\n      const rect = element.getBoundingClientRect();\n      const viewport = readViewport();\n      const size = measure(element);\n      const press: Press = {\n        pointerId: event.pointerId,\n        startX: event.clientX,\n        startY: event.clientY,\n        origin: { left: rect.left, top: rect.top },\n        size,\n        viewport,\n        active: false,\n        latest: { left: rect.left, top: rect.top },\n        release: null,\n        cleanup: () => undefined,\n      };\n      // A placed dock starts from its committed offset (the host may add lifts on top of it);\n      // a resting dock starts from where it is on screen.\n      const startOffset: DockOffset =\n        live.current.offset ?? fromScreen(press.origin, live.current.rawCorner, size, viewport);\n      const startCorner = live.current.rawCorner;\n      const startScreen = toScreen(startOffset, startCorner, size, viewport);\n\n      const paint = () => {\n        frameRef.current = null;\n        const active = pressRef.current;\n        if (!active || !active.active) return;\n        element.style.translate = `${active.latest.left - startScreen.left}px ${active.latest.top - startScreen.top}px`;\n      };\n      const move = (e: PointerEvent) => {\n        if (e.pointerId !== press.pointerId) return;\n        const dx = e.clientX - press.startX;\n        const dy = e.clientY - press.startY;\n        const opts = live.current;\n        if (!press.active) {\n          if (Math.abs(dx) < opts.threshold && Math.abs(dy) < opts.threshold) return;\n          press.active = true;\n          press.release = holdDragCursor(\"grabbing\");\n          setDragging(true);\n        }\n        const desired = fromScreen({ left: startScreen.left + dx, top: startScreen.top + dy }, startCorner, size, viewport);\n        let next = toScreen(clampOffset(desired, startCorner, size, viewport, opts.clamp), startCorner, size, viewport);\n        if (opts.avoid) {\n          const keep = (p: ScreenPoint) =>\n            toScreen(clampOffset(fromScreen(p, \"top-left\", size, viewport), \"top-left\", size, viewport, opts.clamp), \"top-left\", size, viewport);\n          next = avoidExclusions(next, size, excludedRects(opts.avoid, element), opts.avoid.gap ?? DEFAULT_DOCK_MARGIN, keep);\n        }\n        press.latest = next;\n        if (frameRef.current === null) {\n          if (typeof window.requestAnimationFrame === \"function\") frameRef.current = window.requestAnimationFrame(paint);\n          else paint();\n        }\n      };\n      const end = (e: PointerEvent) => {\n        if (e.pointerId !== press.pointerId) return;\n        press.cleanup();\n        pressRef.current = null;\n        if (!press.active) return;\n        press.release?.();\n        setDragging(false);\n        const opts = live.current;\n        const finalCorner = opts.snapToCorner ? nearestCorner(press.latest, size, viewport) : startCorner;\n        const finalOffset = clampOffset(fromScreen(press.latest, finalCorner, size, viewport), finalCorner, size, viewport, opts.clamp);\n        commit(finalCorner === corner ? { x: finalOffset.x, y: finalOffset.y } : { ...finalOffset, corner: finalCorner });\n        // The click the browser fires next is the tail of this drag, never an intent.\n        const swallow = (click: MouseEvent) => {\n          click.stopPropagation();\n          click.preventDefault();\n        };\n        window.addEventListener(\"click\", swallow, { capture: true, once: true });\n        window.setTimeout(() => window.removeEventListener(\"click\", swallow, { capture: true }), 0);\n      };\n      press.cleanup = () => {\n        window.removeEventListener(\"pointermove\", move);\n        window.removeEventListener(\"pointerup\", end);\n        window.removeEventListener(\"pointercancel\", end);\n        if (frameRef.current !== null) {\n          window.cancelAnimationFrame?.(frameRef.current);\n          frameRef.current = null;\n        }\n        if (!press.active) return;\n        press.release?.();\n        press.release = null;\n      };\n      pressRef.current = press;\n      window.addEventListener(\"pointermove\", move);\n      window.addEventListener(\"pointerup\", end);\n      window.addEventListener(\"pointercancel\", end);\n    },\n    [commit, corner, draggable, element, id, ignore, raiseOnPress, summonStore, touch],\n  );\n\n  const reset = useCallback(() => {\n    adoptingRef.current = true;\n    commit(null);\n  }, [commit]);\n\n  // ── Placement ───────────────────────────────────────────────────────────\n  let style: CSSProperties;\n  if (renderedOffset) {\n    const left = rawCorner.endsWith(\"left\");\n    const top = rawCorner.startsWith(\"top\");\n    style = {\n      position: \"fixed\",\n      left: left ? renderedOffset.x : \"auto\",\n      right: left ? \"auto\" : renderedOffset.x,\n      top: top ? renderedOffset.y : \"auto\",\n      bottom: top ? \"auto\" : renderedOffset.y,\n    };\n  } else {\n    const transform = [anchor?.centerX ? \"translateX(-50%)\" : null, nudge ? `translate(${nudge.left}px, ${nudge.top}px)` : null]\n      .filter(Boolean)\n      .join(\" \");\n    style = {\n      position: \"fixed\",\n      top: anchor?.top,\n      bottom: anchor?.bottom,\n      left: anchor?.centerX ? \"50%\" : anchor?.left,\n      right: anchor?.right,\n      ...(transform ? { transform } : {}),\n    };\n  }\n  if (zIndex !== undefined) style.zIndex = zIndex;\n\n  return {\n    ref: setElement,\n    element,\n    style,\n    handleProps: {\n      onPointerDown,\n      style: draggable ? { cursor: \"grab\", touchAction: touch ? \"none\" : \"auto\" } : {},\n      \"data-dock-handle\": \"\",\n    },\n    offset: renderedOffset,\n    corner: rawCorner,\n    dragging,\n    moved: chosen !== null,\n    zIndex,\n    reset,\n  };\n}\n","/**\n * Dock geometry — the pure half of a dock: corner-relative offsets, the clamp\n * that keeps a dock reachable, the nearest-corner snap and the exclusion\n * avoidance. No DOM reads except `avoidExclusions`, which is handed the\n * rectangles it must stay off.\n *\n * A dock's position is stored as an OFFSET FROM A CORNER, not as left/top: a\n * dock resting 12px from the bottom-right keeps that relationship when the\n * window is resized, and a position saved on a wide monitor comes back next to\n * the same corner on a laptop.\n */\n\nexport type DockCorner = \"top-left\" | \"top-right\" | \"bottom-left\" | \"bottom-right\";\n\n/** Distance in px from the corner's horizontal (`x`) and vertical (`y`) edges. */\nexport interface DockOffset {\n  x: number;\n  y: number;\n}\n\n/** A remembered position: an offset and the corner it is measured from (the dock's corner when omitted). */\nexport interface DockPosition extends DockOffset {\n  corner?: DockCorner;\n}\n\nexport interface DockSize {\n  width: number;\n  height: number;\n}\n\nexport interface DockClamp {\n  /** Smallest gap kept between the dock and the viewport edge. Default 8. */\n  margin?: number;\n  /**\n   * How much of the dock must stay on screen. Default: all of it. A dock that\n   * may hang off an edge (a pill you can park half-hidden) passes its grab area.\n   */\n  minVisible?: DockSize;\n}\n\nexport interface ScreenPoint {\n  left: number;\n  top: number;\n}\n\nexport interface ScreenRect extends ScreenPoint {\n  right: number;\n  bottom: number;\n}\n\nexport const DEFAULT_DOCK_MARGIN = 8;\n\n/** A pointer that moved less than this is a click, not a drag. */\nexport const DEFAULT_DRAG_THRESHOLD = 4;\n\nconst fromLeft = (corner: DockCorner): boolean => corner.endsWith(\"left\");\nconst fromTop = (corner: DockCorner): boolean => corner.startsWith(\"top\");\n\n/** The offset → the dock's top-left in viewport px. */\nexport function toScreen(offset: DockOffset, corner: DockCorner, size: DockSize, viewport: DockSize): ScreenPoint {\n  return {\n    left: fromLeft(corner) ? offset.x : viewport.width - size.width - offset.x,\n    top: fromTop(corner) ? offset.y : viewport.height - size.height - offset.y,\n  };\n}\n\n/** A top-left in viewport px → the offset from `corner`. */\nexport function fromScreen(point: ScreenPoint, corner: DockCorner, size: DockSize, viewport: DockSize): DockOffset {\n  return {\n    x: fromLeft(corner) ? point.left : viewport.width - size.width - point.left,\n    y: fromTop(corner) ? point.top : viewport.height - size.height - point.top,\n  };\n}\n\n/**\n * Keep the offset inside the viewport. When the dock is larger than the room\n * there is, its TOP and LEFT stay visible — that is where a header, a grip\n * and a close button live, and an unreachable close button is how a movable\n * notice turns into an unclosable one.\n */\nexport function clampOffset(\n  offset: DockOffset,\n  corner: DockCorner,\n  size: DockSize,\n  viewport: DockSize,\n  clamp: DockClamp = {},\n): DockOffset {\n  const margin = clamp.margin ?? DEFAULT_DOCK_MARGIN;\n  const visible = clamp.minVisible ?? size;\n  const axis = (value: number, room: number, extent: number, nearIsStart: boolean): number => {\n    const min = margin;\n    const max = room - extent - margin;\n    if (max < min) return Math.round(nearIsStart ? min : max);\n    return Math.round(Math.min(Math.max(value, min), max));\n  };\n  return {\n    x: axis(offset.x, viewport.width, visible.width, fromLeft(corner)),\n    y: axis(offset.y, viewport.height, visible.height, fromTop(corner)),\n  };\n}\n\n/** The corner nearest the dock's centre — where a dropped dock re-anchors when snapping is on. */\nexport function nearestCorner(point: ScreenPoint, size: DockSize, viewport: DockSize): DockCorner {\n  const top = point.top + size.height / 2 < viewport.height / 2;\n  const left = point.left + size.width / 2 < viewport.width / 2;\n  return `${top ? \"top\" : \"bottom\"}-${left ? \"left\" : \"right\"}`;\n}\n\nfunction overlaps(a: ScreenRect, b: ScreenRect): boolean {\n  return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;\n}\n\n/**\n * Keep the dock off fixed controls it must never cover (a table's pager, a\n * composer) without reserving page space. A clear position is returned\n * untouched; a covering one moves to the NEAREST clear candidate — never\n * further than it has to.\n */\nexport function avoidExclusions(\n  point: ScreenPoint,\n  size: DockSize,\n  excluded: readonly ScreenRect[],\n  gap: number,\n  keepOnScreen: (point: ScreenPoint) => ScreenPoint,\n): ScreenPoint {\n  const bounded = keepOnScreen(point);\n  if (excluded.length === 0) return bounded;\n  const rectFor = (candidate: ScreenPoint): ScreenRect => ({\n    left: candidate.left,\n    top: candidate.top,\n    right: candidate.left + size.width,\n    bottom: candidate.top + size.height,\n  });\n  const isClear = (candidate: ScreenPoint) => !excluded.some((target) => overlaps(rectFor(candidate), target));\n  if (isClear(bounded)) return bounded;\n  const clear = excluded\n    .flatMap((target) => [\n      { left: bounded.left, top: target.top - size.height - gap },\n      { left: bounded.left, top: target.bottom + gap },\n      { left: target.left - size.width - gap, top: bounded.top },\n      { left: target.right + gap, top: bounded.top },\n    ])\n    .map(keepOnScreen)\n    .filter(isClear);\n  if (clear.length === 0) return bounded;\n  const distance = (candidate: ScreenPoint) => Math.hypot(candidate.left - bounded.left, candidate.top - bounded.top);\n  return clear.reduce((nearest, candidate) => (distance(candidate) < distance(nearest) ? candidate : nearest));\n}\n\nexport function samePosition(a: DockPosition | null | undefined, b: DockPosition | null | undefined): boolean {\n  if (!a || !b) return a === b || (!a && !b);\n  return a.x === b.x && a.y === b.y && a.corner === b.corner;\n}\n","/**\n * Where a dock remembers its position.\n *\n * The package never decides WHICH storage a host uses: a host that keeps\n * browser state behind its own declared keys (or syncs it per user) hands a\n * `DockPositionStore` to `<DockProvider>`, or to one dock through its `store`\n * option. With neither, positions live in this browser's localStorage under\n * `matrx:summon:dock:<id>` — every read and write is SSR-safe and never throws\n * (private mode, quota and disabled storage degrade to \"nothing stored\").\n */\n\nimport { createContext, createElement, useContext, type ReactNode } from \"react\";\nimport type { DockCorner, DockPosition } from \"./geometry\";\n\nexport interface DockPositionStore {\n  read(id: string): DockPosition | null;\n  /** `null` forgets the position (the dock goes back to its resting place). */\n  write(id: string, position: DockPosition | null): void;\n}\n\nexport const DOCK_STORAGE_PREFIX = \"matrx:summon:dock:\";\n\nconst CORNERS: readonly DockCorner[] = [\"top-left\", \"top-right\", \"bottom-left\", \"bottom-right\"];\n\n/** Accept only a well-formed position; anything else reads as \"nothing stored\". */\nexport function parseDockPosition(value: unknown): DockPosition | null {\n  if (!value || typeof value !== \"object\") return null;\n  const { x, y, corner } = value as Record<string, unknown>;\n  if (typeof x !== \"number\" || typeof y !== \"number\" || !Number.isFinite(x) || !Number.isFinite(y)) return null;\n  if (corner !== undefined && !CORNERS.includes(corner as DockCorner)) return null;\n  return corner === undefined ? { x, y } : { x, y, corner: corner as DockCorner };\n}\n\nfunction storage(): Storage | null {\n  try {\n    return typeof window === \"undefined\" ? null : window.localStorage;\n  } catch {\n    return null;\n  }\n}\n\n/** The default store: one localStorage key per dock id. */\nexport function createLocalDockStore(prefix: string = DOCK_STORAGE_PREFIX): DockPositionStore {\n  return {\n    read(id) {\n      try {\n        const raw = storage()?.getItem(prefix + id);\n        return raw ? parseDockPosition(JSON.parse(raw)) : null;\n      } catch {\n        return null;\n      }\n    },\n    write(id, position) {\n      try {\n        const area = storage();\n        if (!area) return;\n        if (position) area.setItem(prefix + id, JSON.stringify(position));\n        else area.removeItem(prefix + id);\n      } catch {\n        // Storage refused: the in-memory position still applies for this page.\n      }\n    },\n  };\n}\n\n/** A store that remembers nothing — for docks whose place is per-moment (a toast, a stacked widget). */\nexport const memoryOnlyDockStore: DockPositionStore = { read: () => null, write: () => undefined };\n\nconst defaultStore = createLocalDockStore();\n\nconst DockStoreContext = createContext<DockPositionStore | null>(null);\n\nexport interface DockProviderProps {\n  store: DockPositionStore;\n  children?: ReactNode;\n}\n\n/** Hand every dock below one position store (the host's declared keys, a per-user sync). */\nexport function DockProvider({ store, children }: DockProviderProps): ReactNode {\n  return createElement(DockStoreContext.Provider, { value: store }, children);\n}\n\n/** The store a dock uses: its own option, else the nearest provider, else localStorage. */\nexport function useDockStore(own?: DockPositionStore): DockPositionStore {\n  const provided = useContext(DockStoreContext);\n  return own ?? provided ?? defaultStore;\n}\n"],"mappings":"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","names":["import_react","import_react"]}

package/dist/dock.d.cts

@@ -0,0 +1,224 @@
+import { ReactNode, CSSProperties, PointerEvent, HTMLAttributes } from 'react';
+
+/**
+ * Dock geometry — the pure half of a dock: corner-relative offsets, the clamp
+ * that keeps a dock reachable, the nearest-corner snap and the exclusion
+ * avoidance. No DOM reads except `avoidExclusions`, which is handed the
+ * rectangles it must stay off.
+ *
+ * A dock's position is stored as an OFFSET FROM A CORNER, not as left/top: a
+ * dock resting 12px from the bottom-right keeps that relationship when the
+ * window is resized, and a position saved on a wide monitor comes back next to
+ * the same corner on a laptop.
+ */
+type DockCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/** Distance in px from the corner's horizontal (`x`) and vertical (`y`) edges. */
+interface DockOffset {
+    x: number;
+    y: number;
+}
+/** A remembered position: an offset and the corner it is measured from (the dock's corner when omitted). */
+interface DockPosition extends DockOffset {
+    corner?: DockCorner;
+}
+interface DockSize {
+    width: number;
+    height: number;
+}
+interface DockClamp {
+    /** Smallest gap kept between the dock and the viewport edge. Default 8. */
+    margin?: number;
+    /**
+     * How much of the dock must stay on screen. Default: all of it. A dock that
+     * may hang off an edge (a pill you can park half-hidden) passes its grab area.
+     */
+    minVisible?: DockSize;
+}
+interface ScreenPoint {
+    left: number;
+    top: number;
+}
+interface ScreenRect extends ScreenPoint {
+    right: number;
+    bottom: number;
+}
+declare const DEFAULT_DOCK_MARGIN = 8;
+/** A pointer that moved less than this is a click, not a drag. */
+declare const DEFAULT_DRAG_THRESHOLD = 4;
+/** The offset → the dock's top-left in viewport px. */
+declare function toScreen(offset: DockOffset, corner: DockCorner, size: DockSize, viewport: DockSize): ScreenPoint;
+/** A top-left in viewport px → the offset from `corner`. */
+declare function fromScreen(point: ScreenPoint, corner: DockCorner, size: DockSize, viewport: DockSize): DockOffset;
+/**
+ * Keep the offset inside the viewport. When the dock is larger than the room
+ * there is, its TOP and LEFT stay visible — that is where a header, a grip
+ * and a close button live, and an unreachable close button is how a movable
+ * notice turns into an unclosable one.
+ */
+declare function clampOffset(offset: DockOffset, corner: DockCorner, size: DockSize, viewport: DockSize, clamp?: DockClamp): DockOffset;
+/** The corner nearest the dock's centre — where a dropped dock re-anchors when snapping is on. */
+declare function nearestCorner(point: ScreenPoint, size: DockSize, viewport: DockSize): DockCorner;
+/**
+ * Keep the dock off fixed controls it must never cover (a table's pager, a
+ * composer) without reserving page space. A clear position is returned
+ * untouched; a covering one moves to the NEAREST clear candidate — never
+ * further than it has to.
+ */
+declare function avoidExclusions(point: ScreenPoint, size: DockSize, excluded: readonly ScreenRect[], gap: number, keepOnScreen: (point: ScreenPoint) => ScreenPoint): ScreenPoint;
+
+/**
+ * Where a dock remembers its position.
+ *
+ * The package never decides WHICH storage a host uses: a host that keeps
+ * browser state behind its own declared keys (or syncs it per user) hands a
+ * `DockPositionStore` to `<DockProvider>`, or to one dock through its `store`
+ * option. With neither, positions live in this browser's localStorage under
+ * `matrx:summon:dock:<id>` — every read and write is SSR-safe and never throws
+ * (private mode, quota and disabled storage degrade to "nothing stored").
+ */
+
+interface DockPositionStore {
+    read(id: string): DockPosition | null;
+    /** `null` forgets the position (the dock goes back to its resting place). */
+    write(id: string, position: DockPosition | null): void;
+}
+declare const DOCK_STORAGE_PREFIX = "matrx:summon:dock:";
+/** Accept only a well-formed position; anything else reads as "nothing stored". */
+declare function parseDockPosition(value: unknown): DockPosition | null;
+/** The default store: one localStorage key per dock id. */
+declare function createLocalDockStore(prefix?: string): DockPositionStore;
+/** A store that remembers nothing — for docks whose place is per-moment (a toast, a stacked widget). */
+declare const memoryOnlyDockStore: DockPositionStore;
+interface DockProviderProps {
+    store: DockPositionStore;
+    children?: ReactNode;
+}
+/** Hand every dock below one position store (the host's declared keys, a per-user sync). */
+declare function DockProvider({ store, children }: DockProviderProps): ReactNode;
+/** The store a dock uses: its own option, else the nearest provider, else localStorage. */
+declare function useDockStore(own?: DockPositionStore): DockPositionStore;
+
+/**
+ * `useDock()` — the one primitive for floating chrome-less cards, pills and docks.
+ *
+ * THE RULE (paid for in the Workflow Studio's FloatingChatPanel and chat's
+ * ChatPanel): a pointer move paints the CSS `translate` property inside ONE
+ * requestAnimationFrame and React state is committed EXACTLY ONCE, on release.
+ * Writing state per pointer event re-renders whatever streams inside the dock
+ * sixty times a second. `translate` composes with the host's own `transform`
+ * and with any `left/right/top/bottom` it computes, so a host that builds its
+ * own placement (CSS variables, lifts) still drags without re-rendering.
+ *
+ * What else it carries:
+ *  - a drag is never a click: below `threshold` px the gesture stays a click;
+ *    past it the trailing click is swallowed once;
+ *  - the position is an offset from a corner, clamped to the viewport on every
+ *    render (a position saved on a wide monitor never strands the dock), and
+ *    can snap to the nearest corner on release;
+ *  - it remembers its place per dock id (the store chain in ./store) or reports
+ *    it to a controlled host (`position` + `onPositionChange`, e.g. per-user sync);
+ *  - it joins the window manager's z-order lane on press (raised above every
+ *    window, below modals) when a SummonProvider is present;
+ *  - THE CURSOR LAW: the drag holds `grabbing` with design-system `holdDragCursor`;
+ *  - zero cost until mounted: no listener exists outside an active press.
+ */
+
+/** CSS placement used while the dock has no position (never moved, no `defaultPosition`). */
+interface DockAnchor {
+    top?: string;
+    bottom?: string;
+    left?: string;
+    right?: string;
+    /** Centre horizontally (`left: 50%` + translateX(-50%)). */
+    centerX?: boolean;
+}
+/** Controls inside the handle that stay controls — a press there never starts a drag. */
+declare const DEFAULT_DOCK_IGNORE = "button,a,input,select,textarea,[contenteditable='true'],[data-no-drag]";
+interface UseDockOptions {
+    /** Identity: the remembered position, the z-order lane entry. Unique per dock. */
+    id: string;
+    /** The corner positions are measured from. Default "bottom-right". */
+    corner?: DockCorner;
+    /** Resting offset from `corner` before the person moves it. Omit to rest on `anchor`. */
+    defaultPosition?: DockOffset | null;
+    /** CSS resting place when there is no position at all. */
+    anchor?: DockAnchor;
+    /** Controlled position (the host owns storage, e.g. a per-user preference). `null` = resting. */
+    position?: DockPosition | null;
+    /** Told once per drag, on release, and on `reset()` (with `null`). */
+    onPositionChange?: (position: DockPosition | null) => void;
+    /** Remember the position across reloads (uncontrolled only). Default true. */
+    persist?: boolean;
+    /** This dock's own store; otherwise the nearest `<DockProvider>`, else localStorage. */
+    store?: DockPositionStore;
+    /** Default true. Pass false on surfaces that must not move (a phone sheet). */
+    draggable?: boolean;
+    /** Allow touch drags. Default true; a dock that fights page scroll passes false. */
+    touch?: boolean;
+    /** Px a pointer must travel before a press becomes a drag. Default 4. */
+    threshold?: number;
+    clamp?: DockClamp;
+    /** Fixed controls the dock must stay off (nearest clear spot wins). */
+    avoid?: {
+        selector: string;
+        gap?: number;
+    };
+    /** On release, re-anchor to the nearest corner. Default false. */
+    snapToCorner?: boolean;
+    /** z-index before the first press raises it into the window lane. */
+    zIndex?: number;
+    /** Raise into the window manager's z-order lane on press. Default true. */
+    raiseOnPress?: boolean;
+    /** Selector of controls inside the handle that never start a drag. `null` = every press may drag. */
+    ignore?: string | null;
+}
+interface DockHandleBindings {
+    onPointerDown(event: PointerEvent<HTMLElement>): void;
+    style: CSSProperties;
+    "data-dock-handle": "";
+}
+interface DockApi {
+    /** Attach to the element that MOVES. */
+    ref: (element: HTMLElement | null) => void;
+    element: HTMLElement | null;
+    /** Spread onto the moving element: fixed placement (placed or anchored) + z-index. */
+    style: CSSProperties;
+    /** Spread onto the element you drag BY (or the whole dock). */
+    handleProps: DockHandleBindings;
+    /** The clamped offset from `corner`; null while resting on `anchor`. */
+    offset: DockOffset | null;
+    /** The corner `offset` is measured from. */
+    corner: DockCorner;
+    /** True from the moment a press passes the threshold until release. */
+    dragging: boolean;
+    /** The person has moved it (a remembered or controlled position exists). */
+    moved: boolean;
+    /** Current z-index: the lane's once raised, else the `zIndex` option. */
+    zIndex: number | undefined;
+    /** Forget the position; the dock returns to its resting place. */
+    reset(): void;
+}
+declare function useDock(options: UseDockOptions): DockApi;
+
+/**
+ * `<Dock>` — the component form of `useDock()`: a fixed, chrome-less element that
+ * moves. Drag it by a `<DockHandle>` inside it, or by the whole dock with
+ * `handle="self"`. `useDockContext()` reaches the dock's API from anywhere inside
+ * (a "Move back to the corner" menu item calls `reset()`).
+ */
+
+/** The enclosing dock's API; throws outside a `<Dock>`. */
+declare function useDockContext(): DockApi;
+interface DockProps extends UseDockOptions, Omit<HTMLAttributes<HTMLDivElement>, "id" | "children" | "draggable"> {
+    /** "self": the whole dock is the drag handle. Default: only `<DockHandle>`s drag. */
+    handle?: "self" | "inner";
+    children?: ReactNode | ((dock: DockApi) => ReactNode);
+}
+declare function Dock(props: DockProps): ReactNode;
+interface DockHandleProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+/** The part of a `<Dock>` you drag it by. Buttons and fields inside stay controls. */
+declare function DockHandle({ style, onPointerDown, ...rest }: DockHandleProps): ReactNode;
+
+export { DEFAULT_DOCK_IGNORE, DEFAULT_DOCK_MARGIN, DEFAULT_DRAG_THRESHOLD, DOCK_STORAGE_PREFIX, Dock, type DockAnchor, type DockApi, type DockClamp, type DockCorner, DockHandle, type DockHandleBindings, type DockHandleProps, type DockOffset, type DockPosition, type DockPositionStore, type DockProps, DockProvider, type DockProviderProps, type DockSize, type ScreenPoint, type ScreenRect, type UseDockOptions, avoidExclusions, clampOffset, createLocalDockStore, fromScreen, memoryOnlyDockStore, nearestCorner, parseDockPosition, toScreen, useDock, useDockContext, useDockStore };

package/dist/dock.d.ts

@@ -0,0 +1,224 @@
+import { ReactNode, CSSProperties, PointerEvent, HTMLAttributes } from 'react';
+
+/**
+ * Dock geometry — the pure half of a dock: corner-relative offsets, the clamp
+ * that keeps a dock reachable, the nearest-corner snap and the exclusion
+ * avoidance. No DOM reads except `avoidExclusions`, which is handed the
+ * rectangles it must stay off.
+ *
+ * A dock's position is stored as an OFFSET FROM A CORNER, not as left/top: a
+ * dock resting 12px from the bottom-right keeps that relationship when the
+ * window is resized, and a position saved on a wide monitor comes back next to
+ * the same corner on a laptop.
+ */
+type DockCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/** Distance in px from the corner's horizontal (`x`) and vertical (`y`) edges. */
+interface DockOffset {
+    x: number;
+    y: number;
+}
+/** A remembered position: an offset and the corner it is measured from (the dock's corner when omitted). */
+interface DockPosition extends DockOffset {
+    corner?: DockCorner;
+}
+interface DockSize {
+    width: number;
+    height: number;
+}
+interface DockClamp {
+    /** Smallest gap kept between the dock and the viewport edge. Default 8. */
+    margin?: number;
+    /**
+     * How much of the dock must stay on screen. Default: all of it. A dock that
+     * may hang off an edge (a pill you can park half-hidden) passes its grab area.
+     */
+    minVisible?: DockSize;
+}
+interface ScreenPoint {
+    left: number;
+    top: number;
+}
+interface ScreenRect extends ScreenPoint {
+    right: number;
+    bottom: number;
+}
+declare const DEFAULT_DOCK_MARGIN = 8;
+/** A pointer that moved less than this is a click, not a drag. */
+declare const DEFAULT_DRAG_THRESHOLD = 4;
+/** The offset → the dock's top-left in viewport px. */
+declare function toScreen(offset: DockOffset, corner: DockCorner, size: DockSize, viewport: DockSize): ScreenPoint;
+/** A top-left in viewport px → the offset from `corner`. */
+declare function fromScreen(point: ScreenPoint, corner: DockCorner, size: DockSize, viewport: DockSize): DockOffset;
+/**
+ * Keep the offset inside the viewport. When the dock is larger than the room
+ * there is, its TOP and LEFT stay visible — that is where a header, a grip
+ * and a close button live, and an unreachable close button is how a movable
+ * notice turns into an unclosable one.
+ */
+declare function clampOffset(offset: DockOffset, corner: DockCorner, size: DockSize, viewport: DockSize, clamp?: DockClamp): DockOffset;
+/** The corner nearest the dock's centre — where a dropped dock re-anchors when snapping is on. */
+declare function nearestCorner(point: ScreenPoint, size: DockSize, viewport: DockSize): DockCorner;
+/**
+ * Keep the dock off fixed controls it must never cover (a table's pager, a
+ * composer) without reserving page space. A clear position is returned
+ * untouched; a covering one moves to the NEAREST clear candidate — never
+ * further than it has to.
+ */
+declare function avoidExclusions(point: ScreenPoint, size: DockSize, excluded: readonly ScreenRect[], gap: number, keepOnScreen: (point: ScreenPoint) => ScreenPoint): ScreenPoint;
+
+/**
+ * Where a dock remembers its position.
+ *
+ * The package never decides WHICH storage a host uses: a host that keeps
+ * browser state behind its own declared keys (or syncs it per user) hands a
+ * `DockPositionStore` to `<DockProvider>`, or to one dock through its `store`
+ * option. With neither, positions live in this browser's localStorage under
+ * `matrx:summon:dock:<id>` — every read and write is SSR-safe and never throws
+ * (private mode, quota and disabled storage degrade to "nothing stored").
+ */
+
+interface DockPositionStore {
+    read(id: string): DockPosition | null;
+    /** `null` forgets the position (the dock goes back to its resting place). */
+    write(id: string, position: DockPosition | null): void;
+}
+declare const DOCK_STORAGE_PREFIX = "matrx:summon:dock:";
+/** Accept only a well-formed position; anything else reads as "nothing stored". */
+declare function parseDockPosition(value: unknown): DockPosition | null;
+/** The default store: one localStorage key per dock id. */
+declare function createLocalDockStore(prefix?: string): DockPositionStore;
+/** A store that remembers nothing — for docks whose place is per-moment (a toast, a stacked widget). */
+declare const memoryOnlyDockStore: DockPositionStore;
+interface DockProviderProps {
+    store: DockPositionStore;
+    children?: ReactNode;
+}
+/** Hand every dock below one position store (the host's declared keys, a per-user sync). */
+declare function DockProvider({ store, children }: DockProviderProps): ReactNode;
+/** The store a dock uses: its own option, else the nearest provider, else localStorage. */
+declare function useDockStore(own?: DockPositionStore): DockPositionStore;
+
+/**
+ * `useDock()` — the one primitive for floating chrome-less cards, pills and docks.
+ *
+ * THE RULE (paid for in the Workflow Studio's FloatingChatPanel and chat's
+ * ChatPanel): a pointer move paints the CSS `translate` property inside ONE
+ * requestAnimationFrame and React state is committed EXACTLY ONCE, on release.
+ * Writing state per pointer event re-renders whatever streams inside the dock
+ * sixty times a second. `translate` composes with the host's own `transform`
+ * and with any `left/right/top/bottom` it computes, so a host that builds its
+ * own placement (CSS variables, lifts) still drags without re-rendering.
+ *
+ * What else it carries:
+ *  - a drag is never a click: below `threshold` px the gesture stays a click;
+ *    past it the trailing click is swallowed once;
+ *  - the position is an offset from a corner, clamped to the viewport on every
+ *    render (a position saved on a wide monitor never strands the dock), and
+ *    can snap to the nearest corner on release;
+ *  - it remembers its place per dock id (the store chain in ./store) or reports
+ *    it to a controlled host (`position` + `onPositionChange`, e.g. per-user sync);
+ *  - it joins the window manager's z-order lane on press (raised above every
+ *    window, below modals) when a SummonProvider is present;
+ *  - THE CURSOR LAW: the drag holds `grabbing` with design-system `holdDragCursor`;
+ *  - zero cost until mounted: no listener exists outside an active press.
+ */
+
+/** CSS placement used while the dock has no position (never moved, no `defaultPosition`). */
+interface DockAnchor {
+    top?: string;
+    bottom?: string;
+    left?: string;
+    right?: string;
+    /** Centre horizontally (`left: 50%` + translateX(-50%)). */
+    centerX?: boolean;
+}
+/** Controls inside the handle that stay controls — a press there never starts a drag. */
+declare const DEFAULT_DOCK_IGNORE = "button,a,input,select,textarea,[contenteditable='true'],[data-no-drag]";
+interface UseDockOptions {
+    /** Identity: the remembered position, the z-order lane entry. Unique per dock. */
+    id: string;
+    /** The corner positions are measured from. Default "bottom-right". */
+    corner?: DockCorner;
+    /** Resting offset from `corner` before the person moves it. Omit to rest on `anchor`. */
+    defaultPosition?: DockOffset | null;
+    /** CSS resting place when there is no position at all. */
+    anchor?: DockAnchor;
+    /** Controlled position (the host owns storage, e.g. a per-user preference). `null` = resting. */
+    position?: DockPosition | null;
+    /** Told once per drag, on release, and on `reset()` (with `null`). */
+    onPositionChange?: (position: DockPosition | null) => void;
+    /** Remember the position across reloads (uncontrolled only). Default true. */
+    persist?: boolean;
+    /** This dock's own store; otherwise the nearest `<DockProvider>`, else localStorage. */
+    store?: DockPositionStore;
+    /** Default true. Pass false on surfaces that must not move (a phone sheet). */
+    draggable?: boolean;
+    /** Allow touch drags. Default true; a dock that fights page scroll passes false. */
+    touch?: boolean;
+    /** Px a pointer must travel before a press becomes a drag. Default 4. */
+    threshold?: number;
+    clamp?: DockClamp;
+    /** Fixed controls the dock must stay off (nearest clear spot wins). */
+    avoid?: {
+        selector: string;
+        gap?: number;
+    };
+    /** On release, re-anchor to the nearest corner. Default false. */
+    snapToCorner?: boolean;
+    /** z-index before the first press raises it into the window lane. */
+    zIndex?: number;
+    /** Raise into the window manager's z-order lane on press. Default true. */
+    raiseOnPress?: boolean;
+    /** Selector of controls inside the handle that never start a drag. `null` = every press may drag. */
+    ignore?: string | null;
+}
+interface DockHandleBindings {
+    onPointerDown(event: PointerEvent<HTMLElement>): void;
+    style: CSSProperties;
+    "data-dock-handle": "";
+}
+interface DockApi {
+    /** Attach to the element that MOVES. */
+    ref: (element: HTMLElement | null) => void;
+    element: HTMLElement | null;
+    /** Spread onto the moving element: fixed placement (placed or anchored) + z-index. */
+    style: CSSProperties;
+    /** Spread onto the element you drag BY (or the whole dock). */
+    handleProps: DockHandleBindings;
+    /** The clamped offset from `corner`; null while resting on `anchor`. */
+    offset: DockOffset | null;
+    /** The corner `offset` is measured from. */
+    corner: DockCorner;
+    /** True from the moment a press passes the threshold until release. */
+    dragging: boolean;
+    /** The person has moved it (a remembered or controlled position exists). */
+    moved: boolean;
+    /** Current z-index: the lane's once raised, else the `zIndex` option. */
+    zIndex: number | undefined;
+    /** Forget the position; the dock returns to its resting place. */
+    reset(): void;
+}
+declare function useDock(options: UseDockOptions): DockApi;
+
+/**
+ * `<Dock>` — the component form of `useDock()`: a fixed, chrome-less element that
+ * moves. Drag it by a `<DockHandle>` inside it, or by the whole dock with
+ * `handle="self"`. `useDockContext()` reaches the dock's API from anywhere inside
+ * (a "Move back to the corner" menu item calls `reset()`).
+ */
+
+/** The enclosing dock's API; throws outside a `<Dock>`. */
+declare function useDockContext(): DockApi;
+interface DockProps extends UseDockOptions, Omit<HTMLAttributes<HTMLDivElement>, "id" | "children" | "draggable"> {
+    /** "self": the whole dock is the drag handle. Default: only `<DockHandle>`s drag. */
+    handle?: "self" | "inner";
+    children?: ReactNode | ((dock: DockApi) => ReactNode);
+}
+declare function Dock(props: DockProps): ReactNode;
+interface DockHandleProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+/** The part of a `<Dock>` you drag it by. Buttons and fields inside stay controls. */
+declare function DockHandle({ style, onPointerDown, ...rest }: DockHandleProps): ReactNode;
+
+export { DEFAULT_DOCK_IGNORE, DEFAULT_DOCK_MARGIN, DEFAULT_DRAG_THRESHOLD, DOCK_STORAGE_PREFIX, Dock, type DockAnchor, type DockApi, type DockClamp, type DockCorner, DockHandle, type DockHandleBindings, type DockHandleProps, type DockOffset, type DockPosition, type DockPositionStore, type DockProps, DockProvider, type DockProviderProps, type DockSize, type ScreenPoint, type ScreenRect, type UseDockOptions, avoidExclusions, clampOffset, createLocalDockStore, fromScreen, memoryOnlyDockStore, nearestCorner, parseDockPosition, toScreen, useDock, useDockContext, useDockStore };