@ai-matrx/summon 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -1,6 +1,27 @@
 # Changelog
 
+## 0.1.11
+
+UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
+Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/summon/src`.
+
+## 0.1.10
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 33bf3a23be 24a38ba927 -- apps/shared/summon/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.1.9
+
+SOURCE CHANGED WITH NO RELEASE NOTE. This release shipped source changes that nobody described in an Unreleased entry,
+so they may include breaking API changes. Consumer action is UNKNOWN: read the diff before upgrading.
+Diff: `git diff b3962adfda 33bf3a23be -- apps/shared/summon/src`
+
+Changed shipped source files (3):
+- `apps/shared/summon/src/core/augment.ts`
+- `apps/shared/summon/src/core/types.ts`
+- `apps/shared/summon/src/index.ts`
+
+## 0.1.8
 ### Unreleased
 
 - **New: `./open` and `./root` — a page pays next to nothing until something opens.** `./open` (framework-free) holds the action creators (plain objects carrying the slices' own type strings: `openOverlay`, `closeOverlay`, `toggleOverlay`, `closeAllInstancesOfOverlay`, `closeOverlaysBoundToPage`, `closeAllOverlays`, `pruneStaleInstances`, `focusWindow`, `restoreWindow`, `toggleWindowsHidden`, `restoreAll`, `minimizeAll`), selectors that read "closed" while the slices are absent, the registry, ports, and `createSummonGate()`. `./root` holds `<SummonRoot store runtime …settings>`, the store hooks, `defineOverlay` and the instance context. The gate is one middleware in a host store: the store carries no summon slice or middleware; the first summon action queues and starts ONE `import()` of the core, which installs itself on evaluation (injects the slices through the host's `attachReducer` inject, adds the close lifecycle + render watchdog, replays the queue). Any module that imports the core statically (the window section, links, persistence) installs it before it renders. `<SummonRoot>` records the host settings (ports, renderWrapper, errorReportExtras, windows) once; `useSummonPorts`, `useSummonConfig` and `useWindowConfig` fall back to them when no provider is above, so a page's own WindowPanel and the lazily loaded host need no provider. Callback-aware opens reserve their event channel id and the handles registry arrives with that first open (`openPendingEventChannel`). Measured in AI Matrx: summon first load per route 73 KB min / 23 KB gz before. Guards: `src/importCost.test.ts` (`./open`/`./root` reach no slice, middleware, react section, window or handles), `src/open/gate.test.ts`, `src/open/actions.parity.test.ts`, `src/root/summonRoot.test.tsx`. Consumer action: none for hosts that mount `summonReducers` or use `<SummonProvider>`; to drop summon from first load, mount `createSummonGate()` + `<SummonRoot>` instead and import openers/selectors from `./open`, `defineOverlay` from `./root`.

package/README.md

@@ -201,6 +201,30 @@ Pass the same `ports` object to both. The overlays slice keys are fixed. Without
 
 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).
 
+### Pay only when something opens: the gate
+
+A large app keeps summon out of every route's first load: the store carries no summon slice or
+middleware, and the root mounts only `<SummonRoot>`.
+
+```tsx
+import { configureStore } from "@reduxjs/toolkit";
+import { createSummonGate } from "@ai-matrx/summon/open";
+import { SummonRoot } from "@ai-matrx/summon/root";
+
+const gate = createSummonGate({ ports });
+const root = createInjectableRootReducer(); // your combineReducers wrapper with an inject(reducers)
+gate.attachReducer((reducers) => root.inject(reducers));
+export const store = configureStore({ reducer: root, middleware: (g) => g().concat(gate.middleware) });
+
+<SummonRoot store={store} ports={ports} runtime={() => import("./WindowRuntime")}>{app}</SummonRoot>;
+```
+
+Openers and selectors come from `./open`, `defineOverlay` from `./root`. The first summon action is
+queued and starts one `import()` of the core, which injects the slices, adds the middleware and
+replays the queue; a module that imports the core statically (a page's `WindowPanel`) installs it
+before it renders. `runtime` (tray sync, router port) mounts once the core is installed.
+`prefetchSummonRuntime()` starts the load early (idle, pointer intent).
+
 ## 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).

package/dist/{gate-CfjdNWP6.d.cts → gate-2V3LrLFh.d.cts}

@@ -324,6 +324,19 @@ declare const minimizeAll: Creator<[payload: {
     viewportWidth: number;
     viewportHeight: number;
 }>;
+interface UrlSyncEntryPayload {
+    typeKey: string;
+    instanceId: string;
+    args?: Readonly<Record<string, string>>;
+}
+declare const registerSyncEntry: Creator<[payload: UrlSyncEntryPayload], UrlSyncEntryPayload>;
+declare const unregisterSyncEntry: Creator<[payload: {
+    typeKey: string;
+    instanceId: string;
+}], {
+    typeKey: string;
+    instanceId: string;
+}>;
 /** Every slice key the summon reducers own; an action under one of them needs the runtime. */
 declare const SUMMON_SLICE_KEYS: readonly ["overlays", "windowManager", "urlSync", "overlayState"];
 declare function isSummonAction(action: unknown): action is {
@@ -362,6 +375,15 @@ declare const selectWindowsHidden: (state: {
         windowsHidden: boolean;
     };
 }) => boolean;
+interface WindowLike {
+    readonly zIndex: number;
+}
+/** Every registered window, topmost first (empty before the runtime is installed). Memoized on the map. */
+declare function selectAllWindows<W extends WindowLike = WindowLike>(state: {
+    windowManager?: {
+        windows: Record<string, W>;
+    };
+}): readonly W[];
 
 /** What the core hands the gate when it loads. */
 interface SummonCore {
@@ -394,4 +416,4 @@ interface CreateSummonGateOptions {
 }
 declare function createSummonGate(options?: CreateSummonGateOptions): SummonGate;
 
-export { locationRouter as $, type AnyOverlayMeta as A, closeOverlay as B, type CloseOverlaysBoundToPagePayload as C, DEFAULT_INSTANCE_ID as D, type ErrorSinkPort as E, closeOverlaysBoundToPage as F, consoleErrorSink as G, consoleNotify as H, type InstanceKey as I, debugOff as J, type KeepAlive as K, type LinkHydrateContext as L, type MobilePresentation as M, type NotifyOptions as N, type OverlayState as O, type PruneStaleInstancesPayload as P, defaultWindowIdFor as Q, type RawOpenPayload as R, type SummonPorts as S, type ToggleOverlayPayload as T, type UnbiddenHomeRoute as U, getOverlayMeta as V, type WindowPreservation as W, getOverlayMetaByLinkKey as X, instanceKey as Y, isRegisteredOverlay as Z, listOpenInstanceKeys as _, type StateWithOverlays as a, openOverlay as a0, overlayIdsBoundToPage as a1, parseInstanceKey as a2, registerOverlayMeta as a3, resetOverlayRegistry as a4, resolvePorts as a5, selectIsOverlayOpen as a6, selectOpenInstances as a7, selectOverlay as a8, selectOverlayData as a9, subscribeToOverlayRegistry as aa, toggleOverlay as ab, type CreateSummonGateOptions as ac, SUMMON_INSTALLED_ACTION as ad, SUMMON_SLICE_KEYS as ae, type SummonAction as af, type SummonGate as ag, closeAllOverlays as ah, createSummonGate as ai, ensureSummonRuntime as aj, focusWindow as ak, installSummonCore as al, isSummonAction as am, isSummonInstalled as an, minimizeAll as ao, prefetchSummonRuntime as ap, pruneStaleInstances as aq, restoreAll as ar, restoreWindow as as, selectAnyOverlayTouched as at, selectWindowsHidden as au, subscribeSummonInstalled as av, toggleWindowsHidden as aw, type OverlayDefinitionMeta as b, type SummonCore as c, type CloseAllInstancesPayload as d, type CloseOverlayPayload as e, DEFAULT_PORTS as f, type DebugPort as g, type IdentityPort as h, type InstanceMode as i, type NotifyPort as j, type OpenInstanceView as k, type OpenOverlayPayload as l, type OverlayDataOf as m, type OverlayHostDispatch as n, type OverlayId as o, type OverlayInstance as p, type OverlayLinkSpec as q, type OverlayPersistencePort as r, type OverlayRawData as s, type OverlayWindowOptions as t, type RouterPort as u, type StoredValue as v, type Unsubscribe as w, allOverlayMeta as x, anonymousIdentity as y, closeAllInstancesOfOverlay as z };
+export { locationRouter as $, type AnyOverlayMeta as A, closeOverlay as B, type CloseOverlaysBoundToPagePayload as C, DEFAULT_INSTANCE_ID as D, type ErrorSinkPort as E, closeOverlaysBoundToPage as F, consoleErrorSink as G, consoleNotify as H, type InstanceKey as I, debugOff as J, type KeepAlive as K, type LinkHydrateContext as L, type MobilePresentation as M, type NotifyOptions as N, type OverlayState as O, type PruneStaleInstancesPayload as P, defaultWindowIdFor as Q, type RawOpenPayload as R, type SummonPorts as S, type ToggleOverlayPayload as T, type UnbiddenHomeRoute as U, getOverlayMeta as V, type WindowPreservation as W, getOverlayMetaByLinkKey as X, instanceKey as Y, isRegisteredOverlay as Z, listOpenInstanceKeys as _, type StateWithOverlays as a, openOverlay as a0, overlayIdsBoundToPage as a1, parseInstanceKey as a2, registerOverlayMeta as a3, resetOverlayRegistry as a4, resolvePorts as a5, selectIsOverlayOpen as a6, selectOpenInstances as a7, selectOverlay as a8, selectOverlayData as a9, unregisterSyncEntry as aA, subscribeToOverlayRegistry as aa, toggleOverlay as ab, type CreateSummonGateOptions as ac, SUMMON_INSTALLED_ACTION as ad, SUMMON_SLICE_KEYS as ae, type SummonAction as af, type SummonGate as ag, type UrlSyncEntryPayload as ah, closeAllOverlays as ai, createSummonGate as aj, ensureSummonRuntime as ak, focusWindow as al, installSummonCore as am, isSummonAction as an, isSummonInstalled as ao, minimizeAll as ap, prefetchSummonRuntime as aq, pruneStaleInstances as ar, registerSyncEntry as as, restoreAll as at, restoreWindow as au, selectAllWindows as av, selectAnyOverlayTouched as aw, selectWindowsHidden as ax, subscribeSummonInstalled as ay, toggleWindowsHidden as az, type OverlayDefinitionMeta as b, type SummonCore as c, type CloseAllInstancesPayload as d, type CloseOverlayPayload as e, DEFAULT_PORTS as f, type DebugPort as g, type IdentityPort as h, type InstanceMode as i, type NotifyPort as j, type OpenInstanceView as k, type OpenOverlayPayload as l, type OverlayDataOf as m, type OverlayHostDispatch as n, type OverlayId as o, type OverlayInstance as p, type OverlayLinkSpec as q, type OverlayPersistencePort as r, type OverlayRawData as s, type OverlayWindowOptions as t, type RouterPort as u, type StoredValue as v, type Unsubscribe as w, allOverlayMeta as x, anonymousIdentity as y, closeAllInstancesOfOverlay as z };

package/dist/{gate-CfjdNWP6.d.ts → gate-2V3LrLFh.d.ts}

@@ -324,6 +324,19 @@ declare const minimizeAll: Creator<[payload: {
     viewportWidth: number;
     viewportHeight: number;
 }>;
+interface UrlSyncEntryPayload {
+    typeKey: string;
+    instanceId: string;
+    args?: Readonly<Record<string, string>>;
+}
+declare const registerSyncEntry: Creator<[payload: UrlSyncEntryPayload], UrlSyncEntryPayload>;
+declare const unregisterSyncEntry: Creator<[payload: {
+    typeKey: string;
+    instanceId: string;
+}], {
+    typeKey: string;
+    instanceId: string;
+}>;
 /** Every slice key the summon reducers own; an action under one of them needs the runtime. */
 declare const SUMMON_SLICE_KEYS: readonly ["overlays", "windowManager", "urlSync", "overlayState"];
 declare function isSummonAction(action: unknown): action is {
@@ -362,6 +375,15 @@ declare const selectWindowsHidden: (state: {
         windowsHidden: boolean;
     };
 }) => boolean;
+interface WindowLike {
+    readonly zIndex: number;
+}
+/** Every registered window, topmost first (empty before the runtime is installed). Memoized on the map. */
+declare function selectAllWindows<W extends WindowLike = WindowLike>(state: {
+    windowManager?: {
+        windows: Record<string, W>;
+    };
+}): readonly W[];
 
 /** What the core hands the gate when it loads. */
 interface SummonCore {
@@ -394,4 +416,4 @@ interface CreateSummonGateOptions {
 }
 declare function createSummonGate(options?: CreateSummonGateOptions): SummonGate;
 
-export { locationRouter as $, type AnyOverlayMeta as A, closeOverlay as B, type CloseOverlaysBoundToPagePayload as C, DEFAULT_INSTANCE_ID as D, type ErrorSinkPort as E, closeOverlaysBoundToPage as F, consoleErrorSink as G, consoleNotify as H, type InstanceKey as I, debugOff as J, type KeepAlive as K, type LinkHydrateContext as L, type MobilePresentation as M, type NotifyOptions as N, type OverlayState as O, type PruneStaleInstancesPayload as P, defaultWindowIdFor as Q, type RawOpenPayload as R, type SummonPorts as S, type ToggleOverlayPayload as T, type UnbiddenHomeRoute as U, getOverlayMeta as V, type WindowPreservation as W, getOverlayMetaByLinkKey as X, instanceKey as Y, isRegisteredOverlay as Z, listOpenInstanceKeys as _, type StateWithOverlays as a, openOverlay as a0, overlayIdsBoundToPage as a1, parseInstanceKey as a2, registerOverlayMeta as a3, resetOverlayRegistry as a4, resolvePorts as a5, selectIsOverlayOpen as a6, selectOpenInstances as a7, selectOverlay as a8, selectOverlayData as a9, subscribeToOverlayRegistry as aa, toggleOverlay as ab, type CreateSummonGateOptions as ac, SUMMON_INSTALLED_ACTION as ad, SUMMON_SLICE_KEYS as ae, type SummonAction as af, type SummonGate as ag, closeAllOverlays as ah, createSummonGate as ai, ensureSummonRuntime as aj, focusWindow as ak, installSummonCore as al, isSummonAction as am, isSummonInstalled as an, minimizeAll as ao, prefetchSummonRuntime as ap, pruneStaleInstances as aq, restoreAll as ar, restoreWindow as as, selectAnyOverlayTouched as at, selectWindowsHidden as au, subscribeSummonInstalled as av, toggleWindowsHidden as aw, type OverlayDefinitionMeta as b, type SummonCore as c, type CloseAllInstancesPayload as d, type CloseOverlayPayload as e, DEFAULT_PORTS as f, type DebugPort as g, type IdentityPort as h, type InstanceMode as i, type NotifyPort as j, type OpenInstanceView as k, type OpenOverlayPayload as l, type OverlayDataOf as m, type OverlayHostDispatch as n, type OverlayId as o, type OverlayInstance as p, type OverlayLinkSpec as q, type OverlayPersistencePort as r, type OverlayRawData as s, type OverlayWindowOptions as t, type RouterPort as u, type StoredValue as v, type Unsubscribe as w, allOverlayMeta as x, anonymousIdentity as y, closeAllInstancesOfOverlay as z };
+export { locationRouter as $, type AnyOverlayMeta as A, closeOverlay as B, type CloseOverlaysBoundToPagePayload as C, DEFAULT_INSTANCE_ID as D, type ErrorSinkPort as E, closeOverlaysBoundToPage as F, consoleErrorSink as G, consoleNotify as H, type InstanceKey as I, debugOff as J, type KeepAlive as K, type LinkHydrateContext as L, type MobilePresentation as M, type NotifyOptions as N, type OverlayState as O, type PruneStaleInstancesPayload as P, defaultWindowIdFor as Q, type RawOpenPayload as R, type SummonPorts as S, type ToggleOverlayPayload as T, type UnbiddenHomeRoute as U, getOverlayMeta as V, type WindowPreservation as W, getOverlayMetaByLinkKey as X, instanceKey as Y, isRegisteredOverlay as Z, listOpenInstanceKeys as _, type StateWithOverlays as a, openOverlay as a0, overlayIdsBoundToPage as a1, parseInstanceKey as a2, registerOverlayMeta as a3, resetOverlayRegistry as a4, resolvePorts as a5, selectIsOverlayOpen as a6, selectOpenInstances as a7, selectOverlay as a8, selectOverlayData as a9, unregisterSyncEntry as aA, subscribeToOverlayRegistry as aa, toggleOverlay as ab, type CreateSummonGateOptions as ac, SUMMON_INSTALLED_ACTION as ad, SUMMON_SLICE_KEYS as ae, type SummonAction as af, type SummonGate as ag, type UrlSyncEntryPayload as ah, closeAllOverlays as ai, createSummonGate as aj, ensureSummonRuntime as ak, focusWindow as al, installSummonCore as am, isSummonAction as an, isSummonInstalled as ao, minimizeAll as ap, prefetchSummonRuntime as aq, pruneStaleInstances as ar, registerSyncEntry as as, restoreAll as at, restoreWindow as au, selectAllWindows as av, selectAnyOverlayTouched as aw, selectWindowsHidden as ax, subscribeSummonInstalled as ay, toggleWindowsHidden as az, type OverlayDefinitionMeta as b, type SummonCore as c, type CloseAllInstancesPayload as d, type CloseOverlayPayload as e, DEFAULT_PORTS as f, type DebugPort as g, type IdentityPort as h, type InstanceMode as i, type NotifyPort as j, type OpenInstanceView as k, type OpenOverlayPayload as l, type OverlayDataOf as m, type OverlayHostDispatch as n, type OverlayId as o, type OverlayInstance as p, type OverlayLinkSpec as q, type OverlayPersistencePort as r, type OverlayRawData as s, type OverlayWindowOptions as t, type RouterPort as u, type StoredValue as v, type Unsubscribe as w, allOverlayMeta as x, anonymousIdentity as y, closeAllInstancesOfOverlay as z };

package/dist/index.cjs

@@ -115,7 +115,7 @@ __export(src_exports, {
   rectsEqual: () => rectsEqual,
   registerCloseFlusher: () => registerCloseFlusher,
   registerOverlayMeta: () => registerOverlayMeta,
-  registerSyncEntry: () => registerSyncEntry,
+  registerSyncEntry: () => registerSyncEntry2,
   registerWindow: () => registerWindow,
   releaseOverlayInstance: () => releaseOverlayInstance,
   releaseTransientWindow: () => releaseTransientWindow,
@@ -165,7 +165,7 @@ __export(src_exports, {
   toggleWindowsHidden: () => toggleWindowsHidden2,
   trayChipsPerRow: () => trayChipsPerRow,
   traySlotRect: () => traySlotRect,
-  unregisterSyncEntry: () => unregisterSyncEntry,
+  unregisterSyncEntry: () => unregisterSyncEntry2,
   unregisterWindow: () => unregisterWindow,
   updateWindowPersistence: () => updateWindowPersistence,
   updateWindowRect: () => updateWindowRect,
@@ -341,6 +341,8 @@ var restoreWindow = creator(W + "restoreWindow", pass());
 var toggleWindowsHidden = creator(W + "toggleWindowsHidden", () => void 0);
 var restoreAll = creator(W + "restoreAll", () => void 0);
 var minimizeAll = creator(W + "minimizeAll", pass());
+var registerSyncEntry = creator("urlSync/registerSyncEntry", pass());
+var unregisterSyncEntry = creator("urlSync/unregisterSyncEntry", pass());
 
 // src/open/selectors.ts
 var import_global_slot2 = require("@ai-matrx/kit/global-slot");
@@ -371,6 +373,7 @@ function listOpenInstanceKeys(state2) {
   }
   return keys;
 }
+var EMPTY_WINDOWS = Object.freeze([]);
 
 // src/core/overlaysSlice.ts
 var initialState = { overlays: {} };
@@ -1700,7 +1703,7 @@ var urlSyncSlice = (0, import_toolkit3.createSlice)({
   }
 });
 var linksReducer = urlSyncSlice.reducer;
-var { setHydrated, registerSyncEntry, unregisterSyncEntry } = urlSyncSlice.actions;
+var { setHydrated, registerSyncEntry: registerSyncEntry2, unregisterSyncEntry: unregisterSyncEntry2 } = urlSyncSlice.actions;
 var selectUrlSyncEntries = (state2) => state2.urlSync.entries;
 var selectIsUrlHydrated = (state2) => state2.urlSync.isHydrated;