@ai-matrx/summon 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.1
+### Unreleased
+
+- **Fixed: an open overlay re-rendered on every render of the host's parent** (runtime sweep, 2026-10-16: a `shareLinkDialog` opened without its file id logged its refusal 425 times in its first 2 s inside AI Matrx). SummonHost's per-definition slot, its per-instance slot and every definition's instance body are now `memo` components (SummonHost itself stays a plain function), so an open overlay re-renders only when ITS instance changes (data reference, hidden), never because the app shell above the host re-rendered. Guard: `src/react/__tests__/renderStorm.test.tsx` (null-render under host churn, `parse()` refusal closes once, close-on-mount renders once, Controller never reopens a self-closed overlay, keepAlive hidden not re-rendered) — red on 0.1.0 (21 renders vs 1). Consumer action: none.
+- **New: `useOptionalSummonStore()`** (`./react`) — the nearest provider's store or `null`, for a package that mounts its own `SummonProvider` only when the host has none (`@ai-matrx/chat` does). Consumer action: none.
+- Source passes stricter consumer compilers (`verbatimModuleSyntax`, `erasableSyntaxOnly`, `noUnusedLocals`): type-only import in the window-manager slice, no constructor parameter properties in `KeepAliveRegistry` / `LoaderCache`, four unused names removed. Consumer action: none.
+
+## 0.1.0 — 2026-10-16
+
+First release (C38): the Redux-driven render system carved out of matrx-frontend.
+
+- Core: store, slices (`overlays`, `windowManager`, `urlSync`, `overlayState`), close lifecycle, render watchdog, ports with working defaults, definition registry.
+- Handles: the callbackManager successor (same verbs), event channels, one-shot requests, object handles, owner-scoped disposal on close. Fixed: group membership never shrank after trigger/remove.
+- React: `SummonProvider` (own store context or the host's store), `defineOverlay` + `def.useSummon()` / `def.Controller`, `SummonHost` (one subscriber per overlay; closed = nothing mounted, no chunk fetched), keep-alive none/hidden/restore, `useOverlayState`, lazy loader with timeout, retry and error boundary.
+- Window: the WindowPanel desktop (drag, resize, snap, arrange, tray with thumbnails, minimize/hide all, pop-out, phone presentations). Minimize always keeps the body mounted; pop-out and dock keep the body's identity (fixed: it remounted).
+- window-host (root-mountable config, tray sync, tray previews), lite window, dialog and sheet wrappers.
+- Links: `?panels=` manager, grammar v2 (percent-encoded, v1-compatible), one open-from-link door. Fixed: link vs restore race (link data wins, restored geometry wins).
+- Persistence: browser-local store (per tab or per person) and `@ai-matrx/data` adapter over `users.user_surface_state`; Next.js router port; testing helpers.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,381 @@
 # @ai-matrx/summon
 
-Name reservation. No usable API yet; do not adopt.
+Summon any React component from anywhere — with its handlers, refs and state — and never mount it until it is called.
+
+- **Dispatch to open.** Open a window, dialog, sheet or any component from anywhere with a hook or an action. A closed overlay puts nothing in the React tree and fetches no code.
+- **Single or multi instance** per overlay.
+- **Handles beside Redux.** Callbacks, event channels, one-shot requests and imperative refs live in a registry next to the store, owned by the open instance and disposed when it closes.
+- **Keep-alive.** On close an overlay unmounts (`none`), stays alive hidden (`hidden`), or unmounts and remembers its saved state (`restore`). `useOverlayState` is the saved-state hook.
+- **Address-bar links.** `?panels=notes:42` names an open overlay, loads its data and survives reload.
+- **Persistence**, off or on: browser-local, your own database through a small port, or `@ai-matrx/data`.
+- **Surfaces.** `WindowPanel` is a desktop in the browser (drag, resize, snap, arrange, tray with thumbnails, minimize, pop-out to a real browser window, three phone presentations). `dialog`, `sheet` and `lite` (a light floating window) share the same close binding.
+
+The package owns its Redux slices. It runs on a private store, or mounts into the store you already have.
+
+## Install
+
+```bash
+pnpm add @ai-matrx/summon react react-dom react-redux @reduxjs/toolkit
+```
+
+| Peer | Needed for |
+|---|---|
+| `react` ≥ 19, `react-dom`, `react-redux` ≥ 9, `@reduxjs/toolkit` ≥ 2 | everything except the framework-free `.` and `./handles` entries |
+| `next` ≥ 16 (optional) | only `./next` |
+| `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`, `./dialog`, `./sheet`, `./lite`, `./url`, `./persistence`, `./persistence/data`, `./next`, `./testing`, `./styles.css`.
+
+## Quick start
+
+**1. Provider and host, once, near the root.**
+
+```tsx
+"use client";
+import { SummonProvider, SummonHost } from "@ai-matrx/summon/react";
+import { APP_OVERLAYS } from "./overlays";
+
+export function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <SummonProvider>
+      {children}
+      <SummonHost definitions={APP_OVERLAYS} />
+    </SummonProvider>
+  );
+}
+```
+
+**2. Declare an overlay once**: a light definition file (safe to import anywhere) and a render module (the lazy chunk).
+
+```ts
+// notes.overlay.ts
+import { defineOverlay } from "@ai-matrx/summon/react";
+
+export interface NotesWindowData {
+  noteId?: string;
+}
+
+export const notesWindow = defineOverlay<NotesWindowData>()({
+  id: "notesWindow",
+  label: "Notes",
+  render: () => import("./notes.render"),
+});
+
+// One line per overlay: opens are type-checked and a mistyped id is a compile error.
+declare module "@ai-matrx/summon" {
+  interface OverlayRegistry {
+    notesWindow: NotesWindowData;
+  }
+}
+```
+
+```tsx
+// notes.render.tsx — loaded only when the overlay is first opened
+import type { OverlayRenderProps } from "@ai-matrx/summon/react";
+import { WindowPanel } from "@ai-matrx/summon/window";
+
+export default function render({ data }: OverlayRenderProps) {
+  const noteId = typeof data?.noteId === "string" ? data.noteId : null;
+  return (
+    <WindowPanel id="notes" title="Notes" boundToOverlay width={480} height={420}>
+      <NoteEditor noteId={noteId} />
+    </WindowPanel>
+  );
+}
+```
+
+`data` arrives as untrusted `Readonly<Record<string, unknown>> | null` (it crossed Redux, a URL or storage). Narrow it in the render module, or give the definition a `parse(raw)` that returns the typed value (or `null` to refuse and close with a warning).
+
+```ts
+// overlays.ts
+import { notesWindow } from "./notes.overlay";
+export const APP_OVERLAYS = [notesWindow];
+```
+
+**3. Open it.**
+
+```tsx
+import { notesWindow } from "./notes.overlay";
+
+function OpenNotes() {
+  const open = notesWindow.useSummon();
+  return <button onClick={() => open({ data: { noteId: "42" } })}>Notes</button>;
+}
+
+// Declarative: opens on mount, closes on unmount, re-opens when the (serialisable) props change.
+const Always = () => <notesWindow.Controller noteId="42" />;
+```
+
+`open()` returns `{ overlayId, instanceId, close() }`. The definition also gives you `useIsOpen(instanceId?)`, `useClose()` and, inside the render tree, `useEmit()`.
+
+### Definition options
+
+| Field | Meaning |
+|---|---|
+| `id`, `label` | id is the registry key; label shows in the tray, menus and diagnostics |
+| `instance` | `"single"` (default, instance id `"default"`) or `"multi"` (a fresh id per open, or pass `instanceId`) |
+| `keepAlive` | `"none"` (default), `"hidden"` or `"restore"` |
+| `closesOnNavigation` | close when the route changes (the overlay shows a piece of the page that opened it) |
+| `defaults` | merged under every open's data |
+| `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 |
+
+Minimizing a window always keeps its component mounted, whatever `keepAlive` says.
+
+### Keep-alive and saved state
+
+```tsx
+import { useOverlayState, useOverlayInstance } from "@ai-matrx/summon/react";
+
+function Draft() {
+  const [text, setText] = useOverlayState("draft", ""); // like useState; scoped to this open instance
+  const { close, hidden } = useOverlayInstance();
+  return <textarea value={text} onChange={(e) => setText(e.target.value)} />;
+}
+```
+
+- `keepAlive: "hidden"`: closing hides the live component (`<Activity mode="hidden">`); reopening shows the same instance. At most `keepAliveLimit` (default 8) closed instances stay mounted; the oldest is evicted and released.
+- `keepAlive: "restore"`: closing unmounts; `useOverlayState` values come back on reopen (and persist when persistence is on).
+- `useOverlayState` values must be serialisable. Any descendant of the overlay may call it.
+
+### Callbacks without functions in Redux
+
+Declare an event map and pass plain functions when opening. They travel through an event channel owned by the instance; only its id rides in the data.
+
+```ts
+export const uploader = defineOverlay<{ folder?: string }, { uploaded: { url: string }; cleared: void }>()({
+  id: "uploader", label: "Uploader", render: () => import("./uploader.render"),
+});
+
+const open = uploader.useSummon();
+open({ data: { folder: "logos" }, handlers: { uploaded: (r) => setUrl(r.url) } });
+
+// inside the overlay's render tree
+const emit = uploader.useEmit();
+emit("uploaded", { url });
+```
+
+Closing the instance disposes the channel. Emitting after that is a silent no-op.
+
+## Mounting into an existing Redux store
+
+```ts
+import { configureStore } from "@reduxjs/toolkit";
+import { summonReducers, createSummonMiddleware } from "@ai-matrx/summon";
+
+const ports = { /* see Ports */ };
+export const store = configureStore({
+  reducer: { ...appReducers, ...summonReducers }, // keys: overlays, windowManager, urlSync, overlayState
+  middleware: (getDefault) => getDefault().concat(createSummonMiddleware(ports)),
+});
+```
+
+```tsx
+<SummonProvider store={store} ports={ports}>…</SummonProvider>
+```
+
+Pass the same `ports` object to both. The overlays slice keys are fixed. Without `store`, the provider makes a private store (`createSummonStore({ ports })`).
+
+Provider knobs: `fallbacks` (`loading`, `error` components), `errorReportExtras` (extra controls in the error card), `renderWrapper` (wrap every rendered overlay), `keepAliveLimit` (8), `importTimeoutMs` (12 s; a render module that has not loaded becomes a `ChunkLoadError` with Try again), `stallWarnMs` (10 s).
+
+## Ports
+
+Every port has a working default, so a bare host needs none. Override only what you have; pass them as `ports` on the provider (a partial object).
+
+| Port | Shape | Default |
+|---|---|---|
+| `identity` | `current(): { key, ready }`, `subscribe(listener)` | anonymous, always ready. A changing `key` swaps all saved state |
+| `router` | `pathname()`, `search()`, `replaceSearch(next)`, `subscribe(listener)` | `window.location` + `history.replaceState` (inert on the server) |
+| `notify` | `info`, `warn`, `error(message, options?)`, optional `dismiss(id)` | console |
+| `errors` | `capture(error, context)` | console.error |
+| `debug` | `enabled()`, optional `subscribe` | off |
+| `persistence` | an `OverlayPersistencePort`, or `null` | `null` (persistence off) |
+
+Next.js: `import { useNextRouterPort } from "@ai-matrx/summon/next"` returns a stable `RouterPort` (call it inside a client component under Suspense; it reads `useSearchParams`). Testing fakes: see Testing.
+
+## Links
+
+`OverlayLinkManager` keeps `?panels=` and open overlays in sync through `ports.router`. Mount it once inside the provider.
+
+```tsx
+import { OverlayLinkManager, useOverlayLink } from "@ai-matrx/summon/url";
+
+<SummonProvider><OverlayLinkManager /><SummonHost definitions={APP_OVERLAYS} /></SummonProvider>
+```
+
+Give the definition a link:
+
+```ts
+defineOverlay<NotesWindowData>()({
+  id: "notesWindow", label: "Notes", render: () => import("./notes.render"),
+  link: {
+    key: "notes",
+    hydrate: ({ id, args, open }) => open({ data: { noteId: id } }), // return "refused" to drop the token
+  },
+});
+```
+
+- Opening `/page?panels=notes:42` runs `hydrate({ id: "42", args, open, dispatch })`. `hydrate` may be async (load a record, then `open`).
+- A mounted overlay publishes its own address with `useOverlayLink("notes", noteId, { tab: "history" })`. `WindowPanel` does it for you from its `urlSyncKey`, `urlSyncId` and `urlSyncArgs` props.
+- Unknown keys are announced at once; tokens whose overlay never registers are announced at a deadline and kept verbatim.
+- **Grammar v2**: `panels = token ("," token)*`, `token = key[:id[:k-v(_k-v)*]]`. Ids are percent-encoded for `% , :`, arg keys and values for `% , : _ -`, so any value survives; v1 links still parse. Helpers: `parseLinkToken`, `parseLinkParam`, `formatLinkToken`, `readPanelsParam`, `withPanelsParam`.
+- **One door**: `openFromLink(searchOrUrl, { dispatch, requireAll?, onError? })` returns `{ opened, refused, unknown, failed }` and serves the address bar, notifications and any bridge. `requireAll: true` opens nothing if any key is unknown. `openPanelRequest(payload, { dispatch })` validates and opens a `{ panelId, instanceId?, data? }` request from a bridge (returns `{ ok: true, … }` or `{ ok: false, error: "invalid_payload" | "unknown_panel" }`).
+
+## Persistence
+
+Off by default. Turn it on with a `persistence` port plus one mounted component:
+
+```tsx
+import { createLocalPersistence, OverlayPersistence } from "@ai-matrx/summon/persistence";
+
+const persistence = createLocalPersistence(); // create once, module level
+<SummonProvider ports={{ persistence }}>
+  <OverlayPersistence />            {/* mount once */}
+  <SummonHost definitions={APP_OVERLAYS} />
+</SummonProvider>
+```
+
+What is saved: the person's open windows and layout (the *workspace*), and the component state of instances that are `keepAlive: "restore"` or preserved windows. Window data is saved only for the keys a window lists in `window.preservation.dataKeys` (default-deny); `window.ephemeral: true` never saves. Caps: 256 KiB workspace, 64 sessions, 32 KiB per window's data and per state entry; overruns report through `ports.errors.capture` (`source: "overlay-persistence"`).
+
+`<OverlayPersistence>` options: `scope` (`"tab"` one workspace per browser tab, `"person"` one per person; default `"tab"` for the local store, `"person"` for per-person stores), `seedFromPerson` (a new tab starts from the person's last layout; default true), `saveDebounceMs` (250), `viewport`. `useOverlayPersistence(options)` returns `{ hydrated }`.
+
+**Browser-local store.** `createLocalPersistence({ namespace?, backend?, storage?, session?, locks?, idbReadBudgetMs?, isReload?, now? })`: a localStorage mirror plus IndexedDB, per identity, per tab workspace with leases. It also has `purgeIdentity(identityKey)` for sign-out cleanup.
+
+**Your own database.** Implement the port:
+
+```ts
+import type { OverlayPersistencePort } from "@ai-matrx/summon";
+
+export const myPersistence: OverlayPersistencePort = {
+  perPerson: true, // true: rows are already scoped to the signed-in person (plain keys). Omit/false: keys arrive prefixed "<identityKey>/"
+  load: async (key) => /* { value, version } | null */ null,
+  save: async (key, value, options) => {
+    /* if options?.expectedVersion is set and differs from the stored version, throw an error named "PersistenceVersionConflictError" */
+    return { version: 1 };
+  },
+  remove: async (key) => {},
+  list: async (prefix) => [], // keys starting with prefix
+};
+```
+
+Keys written: `workspace`, `workspace:<tabWorkspaceId>` (tab scope), `state:<overlayId>:<instanceId>`. Values are JSON. Suggested table:
+
+| Column | Type | |
+|---|---|---|
+| `person_id` | uuid | owner; rows are read and written only for the signed-in person |
+| `key` | text | one of the keys above; unique with `person_id` |
+| `value` | jsonb | the saved value |
+| `version` | int | starts at 1, +1 per save (optimistic concurrency) |
+
+On a conflict the controller re-reads the version and writes once more, so the latest device wins. Version conflicts are recognised by error name (`isVersionConflict(error)`).
+
+**`@ai-matrx/data` hosts.** `createDataPersistence({ db, userId?, table?, feature? })` from `@ai-matrx/summon/persistence/data` maps each key to a row of `users.user_surface_state` (`feature = "summon"`, `surface_key = key`, `state = value`, `version`), through the data package's doors. The organization comes from `createDb({ client, organization })` and the insert is refused when there is none.
+
+```ts
+import { createDb } from "@ai-matrx/data/db";
+import { createDataPersistence } from "@ai-matrx/summon/persistence/data";
+
+const persistence = createDataPersistence({ db: createDb({ client: supabase, organization: () => activeOrgId }) });
+```
+
+## Handles
+
+`@ai-matrx/summon/handles` is framework-free. State lives in one global slot, so duplicated bundles share one registry.
+
+- `callbackManager` (verbs): `register`, `registerWithContext(callback, { context, groupId, owner })`, `subscribe`, `unsubscribe`, `trigger`, `triggerWithContext`, `triggerGroup`, `triggerGroupCommand`, `updateProgress`, `createGroup`, `removeGroup`, `remove` / `unregister`, `get`, `has`, `registerWidgetHandle`, `ownedBy`, `groupMembers`, `disposeOwner`, `size`, `subscribeToRegistry`.
+- Typed helpers, each accepting `{ owner }`:
+
+```ts
+import { createEventChannel, getEventChannel, createRequest, getRequest, registerHandle, getHandle } from "@ai-matrx/summon/handles";
+
+const owner = "notesWindow:default"; // overlayId:instanceId
+
+const channel = createEventChannel<{ saved: string }>({ owner });   // many-shot; pass channel.id in open data
+channel.subscribe((e) => console.log(e)); channel.emit({ saved: "42" });
+getEventChannel<{ saved: string }>(channel.id)?.emit({ saved: "43" }); // overlay side
+
+const request = createRequest<{ prompt: string }, boolean>({ prompt: "Discard?" }, { owner }); // one-shot
+getRequest<{ prompt: string }, boolean>(request.id)?.resolve(true);   // overlay answers
+const answer = await request.promise; // rejects with HandleDisposedError if disposed unanswered
+
+const dispose = registerHandle("editor:42", { focus() {} }, { owner }); // imperative ref
+getHandle<{ focus(): void }>("editor:42")?.focus();
+dispose();
+```
+
+**Owner disposal.** When an instance closes, everything registered with its `overlayId:instanceId` as `owner` is disposed: pending requests reject, channels drop subscribers, handles are removed. No opener disposes by hand. Disposing a group member removes it from the group.
+
+## WindowPanel
+
+```tsx
+import { WindowsProvider, WindowPanel } from "@ai-matrx/summon/window";
+```
+
+Slots contract: the **body is content only**. Everything that is window chrome goes in a slot, never in the body.
+
+| Slot | Props |
+|---|---|
+| Title | `title`, `titleNode` |
+| Header actions | `actionsLeft`, `actionsRight` |
+| Footer | `footer`, or zoned `footerLeft` / `footerCenter` / `footerRight`; `footerVariant: "bar" \| "rich"` |
+| Left sidebar | `sidebar`, `sidebarDefaultSize`, `sidebarMinSize`, `defaultSidebarOpen`, `sidebarExpandsWindow` |
+| Right panel | `secondaryPanel`, `secondaryPanelOpen`, `secondaryPanelDefaultSize`, `secondaryPanelMinSize` |
+
+**Close binding** is required and checked by the type system: exactly one of `overlayId` (close that overlay), `boundToOverlay` (close the enclosing `SummonHost` instance) or `onClose` (page-local). A window with none of them does not compile.
+
+Other props: `id`, `width`/`height` (numbers or `"60vw"`), `minWidth`/`minHeight`, `position`, `fitContent`, `closeOnEscape`, `hidePopOutButton`, `urlSyncKey`/`urlSyncId`/`urlSyncArgs`, `onCollectData`, `captureTraySnapshot`.
+
+Behaviour you can rely on: maximize, minimize, pop-out and dock never remount the body (state, refs and effects survive; minimize keeps the body mounted and captures the tray thumbnail). Pop-out uses a real browser window (Document Picture-in-Picture where available). On phones a window renders as `fullscreen`, `drawer` or `card` per the definition's `window.mobile`.
+
+**`WindowsProvider`** is optional; options: `escapeYieldSelector` (visible elements matching it own the Escape key; default `[data-overlay-escape-yield]`), `mobileTopOffset` (default `var(--header-height, 0px)`), `selectionSurface` (a component wrapping every window body, for a host's selection or right-click menu).
+
+Also exported from `./window`: `WindowTraySync`, `LayoutIcon`, `registerTrayPreview` (a semantic preview for a minimized tile), `usePopoutControl`, `MobileDrawerSurface`, `MobileCardSurface`, `useWindowPanel`.
+
+### Dialog, sheet, light window
+
+```tsx
+import { OverlayDialog } from "@ai-matrx/summon/dialog";
+import { OverlaySheet, OverlayDrawer, OverlayBottomSheet } from "@ai-matrx/summon/sheet";
+import { LiteWindow } from "@ai-matrx/summon/lite";
+
+// inside a render module: closes through the overlay instance
+<OverlayDialog boundToOverlay>{/* DialogContent, DialogTitle … from @ai-matrx/design-system */}</OverlayDialog>
+
+// page-local: you own the state
+<OverlayDialog open={open} onClose={() => setOpen(false)}>…</OverlayDialog>
+
+<LiteWindow id="inspector" title="Inspector">…</LiteWindow> {/* inside an SummonHost overlay, onClose can be omitted */}
+```
+
+`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.
+
+## Styling
+
+Import the structural CSS once, and make Tailwind v4 scan the package, since the components use utility classes:
+
+```css
+@import "tailwindcss";
+@import "@ai-matrx/summon/styles.css";
+@source "../node_modules/@ai-matrx/summon/dist"; /* path relative to this CSS file */
+```
+
+Colors come only from `@ai-matrx/design-system` tokens, so the host's theme applies. The traffic-light colors are `--matrx-window-light-*` custom properties you can override.
+
+## Testing
+
+```tsx
+import { createTestPorts, createTestSummonStore, createMemoryPersistence } from "@ai-matrx/summon/testing";
+
+const ports = createTestPorts({ persistence: createMemoryPersistence() });
+const store = createTestSummonStore(ports);
+
+render(<SummonProvider store={store} ports={ports}><SummonHost definitions={[notesWindow]} /></SummonProvider>);
+```
+
+`createTestPorts` gives a controllable `identity` (`set(key, ready?)`), a controllable `router` (`navigate(path, search?)`) and recording `notify` and `errors` (`messages`, `captured`). `createMemoryPersistence` is an in-memory, versioned port. No test-runner dependency.
+
+## Gates
+
+`pnpm typecheck` (also compiles the package with a host-augmented registry), `npx vitest run`, `pnpm check:package`.

package/dist/closeBinding-C6raC3qJ.d.cts

@@ -0,0 +1,20 @@
+type OverlaySurfaceCloseBinding = {
+    /** Page-local: called when the surface asks to close (Escape, scrim, close button). */
+    onClose: () => void;
+    boundToOverlay?: never;
+    /** Page-local open state. Default true (render it only while open, or pass it). */
+    open?: boolean | undefined;
+} | {
+    /** Close through the enclosing SummonHost instance. */
+    boundToOverlay: true;
+    /** Optional extra hook run before the instance closes. */
+    onClose?: (() => void) | undefined;
+    open?: never;
+};
+interface ResolvedSurfaceClose {
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+}
+declare function useOverlaySurfaceClose(binding: OverlaySurfaceCloseBinding, surface: string): ResolvedSurfaceClose;
+
+export { type OverlaySurfaceCloseBinding as O, type ResolvedSurfaceClose as R, useOverlaySurfaceClose as u };

package/dist/closeBinding-C6raC3qJ.d.ts

@@ -0,0 +1,20 @@
+type OverlaySurfaceCloseBinding = {
+    /** Page-local: called when the surface asks to close (Escape, scrim, close button). */
+    onClose: () => void;
+    boundToOverlay?: never;
+    /** Page-local open state. Default true (render it only while open, or pass it). */
+    open?: boolean | undefined;
+} | {
+    /** Close through the enclosing SummonHost instance. */
+    boundToOverlay: true;
+    /** Optional extra hook run before the instance closes. */
+    onClose?: (() => void) | undefined;
+    open?: never;
+};
+interface ResolvedSurfaceClose {
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+}
+declare function useOverlaySurfaceClose(binding: OverlaySurfaceCloseBinding, surface: string): ResolvedSurfaceClose;
+
+export { type OverlaySurfaceCloseBinding as O, type ResolvedSurfaceClose as R, useOverlaySurfaceClose as u };

package/dist/dialog.cjs

@@ -0,0 +1,60 @@
+"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/dialog.ts
+var dialog_exports = {};
+__export(dialog_exports, {
+  OverlayDialog: () => OverlayDialog,
+  useOverlaySurfaceClose: () => useOverlaySurfaceClose
+});
+module.exports = __toCommonJS(dialog_exports);
+
+// src/dialog/OverlayDialog.tsx
+var import_design_system = require("@ai-matrx/design-system");
+
+// src/dialog/closeBinding.ts
+var import_react = require("react");
+var import_react2 = require("@ai-matrx/summon/react");
+function useOverlaySurfaceClose(binding, surface) {
+  const instance = (0, import_react2.useOptionalOverlayInstance)();
+  const ports = (0, import_react2.useOptionalSummonPorts)();
+  const { onClose, boundToOverlay } = binding;
+  const open = boundToOverlay ? instance ? !instance.hidden : false : binding.open ?? true;
+  const onOpenChange = (0, import_react.useCallback)(
+    (next) => {
+      if (next) return;
+      onClose?.();
+      if (!boundToOverlay) return;
+      if (instance) instance.close();
+      else ports.errors.capture(new Error(`[summon] ${surface} boundToOverlay rendered outside an overlay instance`), { surface });
+    },
+    [boundToOverlay, instance, onClose, ports, surface]
+  );
+  return { open, onOpenChange };
+}
+
+// src/dialog/OverlayDialog.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function OverlayDialog({ onClose, boundToOverlay, open, children, ...rest }) {
+  const binding = boundToOverlay ? { boundToOverlay, onClose } : { onClose, open };
+  const resolved = useOverlaySurfaceClose(binding, "OverlayDialog");
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_design_system.Dialog, { ...rest, open: resolved.open, onOpenChange: resolved.onOpenChange, children });
+}
+//# sourceMappingURL=dialog.cjs.map

package/dist/dialog.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/dialog.ts","../src/dialog/OverlayDialog.tsx","../src/dialog/closeBinding.ts"],"sourcesContent":["// @ai-matrx/summon/dialog — the design-system Dialog, close-bound: closes through its overlay\n// instance when rendered by SummonHost, or through onClose when page-local. Non-blocking on\n// desktop by default. See SUMMON-PACKAGE-DESIGN.md (common-docs) for its contract.\nexport { OverlayDialog, type OverlayDialogProps } from \"./dialog/OverlayDialog\";\nexport { useOverlaySurfaceClose, type OverlaySurfaceCloseBinding, type ResolvedSurfaceClose } from \"./dialog/closeBinding\";\n","\"use client\";\n\nimport type { ComponentProps } from \"react\";\nimport { Dialog } from \"@ai-matrx/design-system\";\nimport { useOverlaySurfaceClose, type OverlaySurfaceCloseBinding } from \"./closeBinding\";\n\ntype DialogRootProps = Omit<ComponentProps<typeof Dialog>, \"open\" | \"onOpenChange\" | \"defaultOpen\">;\n\nexport type OverlayDialogProps = DialogRootProps & OverlaySurfaceCloseBinding;\n\n/**\n * The design-system Dialog, close-bound: windowed (non-blocking) on desktop and a blocking sheet on\n * a phone by default — the design-system's own routing; `modal` forces either. Compose its content\n * with `DialogContent`, `DialogTitle`, … from `@ai-matrx/design-system` as usual.\n */\nexport function OverlayDialog({ onClose, boundToOverlay, open, children, ...rest }: OverlayDialogProps) {\n  const binding = (boundToOverlay ? { boundToOverlay, onClose } : { onClose, open }) as OverlaySurfaceCloseBinding;\n  const resolved = useOverlaySurfaceClose(binding, \"OverlayDialog\");\n  return (\n    <Dialog {...rest} open={resolved.open} onOpenChange={resolved.onOpenChange}>\n      {children}\n    </Dialog>\n  );\n}\n","\"use client\";\n\n/**\n * The close binding every close-bound surface (dialog, sheet, drawer, bottom sheet) shares.\n *\n * Exactly one of two shapes, enforced by the type system (passing neither is a compile error):\n *   - page-local: `onClose` (and usually `open`) — the page owns whether it is shown;\n *   - instance-bound: `boundToOverlay` — rendered by an SummonHost; open while the instance is\n *     shown (a `keepAlive: \"hidden\"` instance closes it), and closing closes the instance.\n */\nimport { useCallback } from \"react\";\nimport { useOptionalOverlayInstance, useOptionalSummonPorts } from \"@ai-matrx/summon/react\";\n\nexport type OverlaySurfaceCloseBinding =\n  | {\n      /** Page-local: called when the surface asks to close (Escape, scrim, close button). */\n      onClose: () => void;\n      boundToOverlay?: never;\n      /** Page-local open state. Default true (render it only while open, or pass it). */\n      open?: boolean | undefined;\n    }\n  | {\n      /** Close through the enclosing SummonHost instance. */\n      boundToOverlay: true;\n      /** Optional extra hook run before the instance closes. */\n      onClose?: (() => void) | undefined;\n      open?: never;\n    };\n\nexport interface ResolvedSurfaceClose {\n  readonly open: boolean;\n  readonly onOpenChange: (open: boolean) => void;\n}\n\nexport function useOverlaySurfaceClose(binding: OverlaySurfaceCloseBinding, surface: string): ResolvedSurfaceClose {\n  const instance = useOptionalOverlayInstance();\n  const ports = useOptionalSummonPorts();\n  const { onClose, boundToOverlay } = binding;\n  const open = boundToOverlay ? (instance ? !instance.hidden : false) : (binding.open ?? true);\n  const onOpenChange = useCallback(\n    (next: boolean) => {\n      if (next) return;\n      onClose?.();\n      if (!boundToOverlay) return;\n      if (instance) instance.close();\n      else ports.errors.capture(new Error(`[summon] ${surface} boundToOverlay rendered outside an overlay instance`), { surface });\n    },\n    [boundToOverlay, instance, onClose, ports, surface],\n  );\n  return { open, onOpenChange };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACGA,2BAAuB;;;ACOvB,mBAA4B;AAC5B,IAAAA,gBAAmE;AAuB5D,SAAS,uBAAuB,SAAqC,SAAuC;AACjH,QAAM,eAAW,0CAA2B;AAC5C,QAAM,YAAQ,sCAAuB;AACrC,QAAM,EAAE,SAAS,eAAe,IAAI;AACpC,QAAM,OAAO,iBAAkB,WAAW,CAAC,SAAS,SAAS,QAAU,QAAQ,QAAQ;AACvF,QAAM,mBAAe;AAAA,IACnB,CAAC,SAAkB;AACjB,UAAI,KAAM;AACV,gBAAU;AACV,UAAI,CAAC,eAAgB;AACrB,UAAI,SAAU,UAAS,MAAM;AAAA,UACxB,OAAM,OAAO,QAAQ,IAAI,MAAM,YAAY,OAAO,sDAAsD,GAAG,EAAE,QAAQ,CAAC;AAAA,IAC7H;AAAA,IACA,CAAC,gBAAgB,UAAU,SAAS,OAAO,OAAO;AAAA,EACpD;AACA,SAAO,EAAE,MAAM,aAAa;AAC9B;;;AD/BI;AAJG,SAAS,cAAc,EAAE,SAAS,gBAAgB,MAAM,UAAU,GAAG,KAAK,GAAuB;AACtG,QAAM,UAAW,iBAAiB,EAAE,gBAAgB,QAAQ,IAAI,EAAE,SAAS,KAAK;AAChF,QAAM,WAAW,uBAAuB,SAAS,eAAe;AAChE,SACE,4CAAC,+BAAQ,GAAG,MAAM,MAAM,SAAS,MAAM,cAAc,SAAS,cAC3D,UACH;AAEJ;","names":["import_react"]}

package/dist/dialog.d.cts

@@ -0,0 +1,16 @@
+import * as react from 'react';
+import { ComponentProps } from 'react';
+import { Dialog } from '@ai-matrx/design-system';
+import { O as OverlaySurfaceCloseBinding } from './closeBinding-C6raC3qJ.cjs';
+export { R as ResolvedSurfaceClose, u as useOverlaySurfaceClose } from './closeBinding-C6raC3qJ.cjs';
+
+type DialogRootProps = Omit<ComponentProps<typeof Dialog>, "open" | "onOpenChange" | "defaultOpen">;
+type OverlayDialogProps = DialogRootProps & OverlaySurfaceCloseBinding;
+/**
+ * The design-system Dialog, close-bound: windowed (non-blocking) on desktop and a blocking sheet on
+ * a phone by default — the design-system's own routing; `modal` forces either. Compose its content
+ * with `DialogContent`, `DialogTitle`, … from `@ai-matrx/design-system` as usual.
+ */
+declare function OverlayDialog({ onClose, boundToOverlay, open, children, ...rest }: OverlayDialogProps): react.JSX.Element;
+
+export { OverlayDialog, type OverlayDialogProps, OverlaySurfaceCloseBinding };

package/dist/dialog.d.ts

@@ -0,0 +1,16 @@
+import * as react from 'react';
+import { ComponentProps } from 'react';
+import { Dialog } from '@ai-matrx/design-system';
+import { O as OverlaySurfaceCloseBinding } from './closeBinding-C6raC3qJ.js';
+export { R as ResolvedSurfaceClose, u as useOverlaySurfaceClose } from './closeBinding-C6raC3qJ.js';
+
+type DialogRootProps = Omit<ComponentProps<typeof Dialog>, "open" | "onOpenChange" | "defaultOpen">;
+type OverlayDialogProps = DialogRootProps & OverlaySurfaceCloseBinding;
+/**
+ * The design-system Dialog, close-bound: windowed (non-blocking) on desktop and a blocking sheet on
+ * a phone by default — the design-system's own routing; `modal` forces either. Compose its content
+ * with `DialogContent`, `DialogTitle`, … from `@ai-matrx/design-system` as usual.
+ */
+declare function OverlayDialog({ onClose, boundToOverlay, open, children, ...rest }: OverlayDialogProps): react.JSX.Element;
+
+export { OverlayDialog, type OverlayDialogProps, OverlaySurfaceCloseBinding };

package/dist/dialog.js

@@ -0,0 +1,38 @@
+"use client";
+
+// src/dialog/OverlayDialog.tsx
+import { Dialog } from "@ai-matrx/design-system";
+
+// src/dialog/closeBinding.ts
+import { useCallback } from "react";
+import { useOptionalOverlayInstance, useOptionalSummonPorts } from "@ai-matrx/summon/react";
+function useOverlaySurfaceClose(binding, surface) {
+  const instance = useOptionalOverlayInstance();
+  const ports = useOptionalSummonPorts();
+  const { onClose, boundToOverlay } = binding;
+  const open = boundToOverlay ? instance ? !instance.hidden : false : binding.open ?? true;
+  const onOpenChange = useCallback(
+    (next) => {
+      if (next) return;
+      onClose?.();
+      if (!boundToOverlay) return;
+      if (instance) instance.close();
+      else ports.errors.capture(new Error(`[summon] ${surface} boundToOverlay rendered outside an overlay instance`), { surface });
+    },
+    [boundToOverlay, instance, onClose, ports, surface]
+  );
+  return { open, onOpenChange };
+}
+
+// src/dialog/OverlayDialog.tsx
+import { jsx } from "react/jsx-runtime";
+function OverlayDialog({ onClose, boundToOverlay, open, children, ...rest }) {
+  const binding = boundToOverlay ? { boundToOverlay, onClose } : { onClose, open };
+  const resolved = useOverlaySurfaceClose(binding, "OverlayDialog");
+  return /* @__PURE__ */ jsx(Dialog, { ...rest, open: resolved.open, onOpenChange: resolved.onOpenChange, children });
+}
+export {
+  OverlayDialog,
+  useOverlaySurfaceClose
+};
+//# sourceMappingURL=dialog.js.map

package/dist/dialog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/dialog/OverlayDialog.tsx","../src/dialog/closeBinding.ts"],"sourcesContent":["\"use client\";\n\nimport type { ComponentProps } from \"react\";\nimport { Dialog } from \"@ai-matrx/design-system\";\nimport { useOverlaySurfaceClose, type OverlaySurfaceCloseBinding } from \"./closeBinding\";\n\ntype DialogRootProps = Omit<ComponentProps<typeof Dialog>, \"open\" | \"onOpenChange\" | \"defaultOpen\">;\n\nexport type OverlayDialogProps = DialogRootProps & OverlaySurfaceCloseBinding;\n\n/**\n * The design-system Dialog, close-bound: windowed (non-blocking) on desktop and a blocking sheet on\n * a phone by default — the design-system's own routing; `modal` forces either. Compose its content\n * with `DialogContent`, `DialogTitle`, … from `@ai-matrx/design-system` as usual.\n */\nexport function OverlayDialog({ onClose, boundToOverlay, open, children, ...rest }: OverlayDialogProps) {\n  const binding = (boundToOverlay ? { boundToOverlay, onClose } : { onClose, open }) as OverlaySurfaceCloseBinding;\n  const resolved = useOverlaySurfaceClose(binding, \"OverlayDialog\");\n  return (\n    <Dialog {...rest} open={resolved.open} onOpenChange={resolved.onOpenChange}>\n      {children}\n    </Dialog>\n  );\n}\n","\"use client\";\n\n/**\n * The close binding every close-bound surface (dialog, sheet, drawer, bottom sheet) shares.\n *\n * Exactly one of two shapes, enforced by the type system (passing neither is a compile error):\n *   - page-local: `onClose` (and usually `open`) — the page owns whether it is shown;\n *   - instance-bound: `boundToOverlay` — rendered by an SummonHost; open while the instance is\n *     shown (a `keepAlive: \"hidden\"` instance closes it), and closing closes the instance.\n */\nimport { useCallback } from \"react\";\nimport { useOptionalOverlayInstance, useOptionalSummonPorts } from \"@ai-matrx/summon/react\";\n\nexport type OverlaySurfaceCloseBinding =\n  | {\n      /** Page-local: called when the surface asks to close (Escape, scrim, close button). */\n      onClose: () => void;\n      boundToOverlay?: never;\n      /** Page-local open state. Default true (render it only while open, or pass it). */\n      open?: boolean | undefined;\n    }\n  | {\n      /** Close through the enclosing SummonHost instance. */\n      boundToOverlay: true;\n      /** Optional extra hook run before the instance closes. */\n      onClose?: (() => void) | undefined;\n      open?: never;\n    };\n\nexport interface ResolvedSurfaceClose {\n  readonly open: boolean;\n  readonly onOpenChange: (open: boolean) => void;\n}\n\nexport function useOverlaySurfaceClose(binding: OverlaySurfaceCloseBinding, surface: string): ResolvedSurfaceClose {\n  const instance = useOptionalOverlayInstance();\n  const ports = useOptionalSummonPorts();\n  const { onClose, boundToOverlay } = binding;\n  const open = boundToOverlay ? (instance ? !instance.hidden : false) : (binding.open ?? true);\n  const onOpenChange = useCallback(\n    (next: boolean) => {\n      if (next) return;\n      onClose?.();\n      if (!boundToOverlay) return;\n      if (instance) instance.close();\n      else ports.errors.capture(new Error(`[summon] ${surface} boundToOverlay rendered outside an overlay instance`), { surface });\n    },\n    [boundToOverlay, instance, onClose, ports, surface],\n  );\n  return { open, onOpenChange };\n}\n"],"mappings":";;;AAGA,SAAS,cAAc;;;ACOvB,SAAS,mBAAmB;AAC5B,SAAS,4BAA4B,8BAA8B;AAuB5D,SAAS,uBAAuB,SAAqC,SAAuC;AACjH,QAAM,WAAW,2BAA2B;AAC5C,QAAM,QAAQ,uBAAuB;AACrC,QAAM,EAAE,SAAS,eAAe,IAAI;AACpC,QAAM,OAAO,iBAAkB,WAAW,CAAC,SAAS,SAAS,QAAU,QAAQ,QAAQ;AACvF,QAAM,eAAe;AAAA,IACnB,CAAC,SAAkB;AACjB,UAAI,KAAM;AACV,gBAAU;AACV,UAAI,CAAC,eAAgB;AACrB,UAAI,SAAU,UAAS,MAAM;AAAA,UACxB,OAAM,OAAO,QAAQ,IAAI,MAAM,YAAY,OAAO,sDAAsD,GAAG,EAAE,QAAQ,CAAC;AAAA,IAC7H;AAAA,IACA,CAAC,gBAAgB,UAAU,SAAS,OAAO,OAAO;AAAA,EACpD;AACA,SAAO,EAAE,MAAM,aAAa;AAC9B;;;AD/BI;AAJG,SAAS,cAAc,EAAE,SAAS,gBAAgB,MAAM,UAAU,GAAG,KAAK,GAAuB;AACtG,QAAM,UAAW,iBAAiB,EAAE,gBAAgB,QAAQ,IAAI,EAAE,SAAS,KAAK;AAChF,QAAM,WAAW,uBAAuB,SAAS,eAAe;AAChE,SACE,oBAAC,UAAQ,GAAG,MAAM,MAAM,SAAS,MAAM,cAAc,SAAS,cAC3D,UACH;AAEJ;","names":[]}