@ai-matrx/summon 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,9 +1,21 @@
 # Changelog
 
+## 0.1.3
+### Unreleased
+
+- **New: the render map can live on the host.** `render` is now optional on `defineOverlay`, and `<SummonHost renders={…}>` takes an id → `() => import("./<id>.render")` map (`OverlayRenderMap`, data type erased, no `any`) for definitions declared without one. A definition's own `render` still wins. Why: every file that imports a definition to open it also inherited an `import()` edge to that overlay's window subtree; with ~220 overlays and ~450 opener files in AI Matrx that multiplied the build graph (a sub-app build went from ~10 s to an out-of-memory kill). An opened overlay with no render source shows its error card (`OverlayRenderMissingError`, `MISSING_RENDER_ERROR`) and logs in development. Guard: `src/react/__tests__/hostRenders.test.tsx`. Consumer action: none for existing users.
+
 ## 0.1.2
 
-UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
-Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/summon/src`.
+SOURCE CHANGED WITH NO RELEASE NOTE. This release shipped source changes that nobody described in an Unreleased entry,
+so they may include breaking API changes. Consumer action is UNKNOWN: read the diff before upgrading.
+Diff: `git diff b7bc6ffc86 19d4c1f55d -- apps/shared/summon/src`
+
+Changed shipped source files (4):
+- `apps/shared/summon/src/persistence/controller.ts`
+- `apps/shared/summon/src/persistence/data/createDataPersistence.ts`
+- `apps/shared/summon/src/sheet/OverlaySheets.tsx`
+- `apps/shared/summon/src/window/useWindowPanel.ts`
 
 ## 0.1.1
 ### Unreleased

package/README.md

@@ -121,6 +121,7 @@ const Always = () => <notesWindow.Controller noteId="42" />;
 | `window` | `{ mobile, mobileSidebarAs, ephemeral, preservation, restoreDefaults, windowId, deprecated, unbiddenHome }` for window overlays |
 | `link` | `{ key, aliases?, hydrate }`, see Links |
 | `parse` | narrow raw data once; `null` refuses |
+| `render` | `() => import("./x.render")`; optional when the host supplies it (see below), and wins over the host map when present |
 
 Minimizing a window always keeps its component mounted, whatever `keepAlive` says.
 
@@ -159,6 +160,26 @@ emit("uploaded", { url });
 
 Closing the instance disposes the channel. Emitting after that is a silent no-op.
 
+### Large apps: the render map lives on the host
+
+Every file that imports a definition to open it also imports that definition's `render: () => import(…)`. To a bundler, each such file gains an edge to the overlay's whole window subtree. With a few overlays that is free. With hundreds of overlays and hundreds of opener files it multiplies the build graph: in AI Matrx, about 450 opener files each reached about 220 window subtrees, and a sub-app build went from about 10 s to an out-of-memory kill. This is the host-build law: never fan out `import()` edges.
+
+The fix keeps "declare once" at two files plus one line. Leave `render` off the definitions, and give the host one id → import map, generated from the file names, that only the host imports:
+
+```ts
+// definitions/notes.overlay.ts — no render: importing it costs nothing
+export const notes = defineOverlay<{ noteId?: string }>()({ id: "notes", label: "Notes" });
+
+// definitions/render-map.ts — generated, imported ONLY by the host (behind its own lazy boundary)
+import type { OverlayRenderMap } from "@ai-matrx/summon/react";
+export const RENDER_MAP: OverlayRenderMap = { notes: () => import("./notes.render") };
+
+// the host
+<SummonHost definitions={APP_OVERLAYS} renders={RENDER_MAP} />
+```
+
+`OverlayRenderMap` erases each module's data type (`OverlayRenderProps<never>`), so differently typed render modules share one map without `any`. An overlay that is opened with no render source at all (no `render`, no map entry) shows its error card (`OverlayRenderMissingError`, exported as `MISSING_RENDER_ERROR`) and logs in development. It is never a silent blank.
+
 ## Mounting into an existing Redux store
 
 ```ts

package/dist/react.cjs

@@ -25,6 +25,7 @@ __export(react_exports, {
   DEFAULT_IMPORT_TIMEOUT_MS: () => DEFAULT_IMPORT_TIMEOUT_MS,
   DEFAULT_KEEP_ALIVE_LIMIT: () => DEFAULT_KEEP_ALIVE_LIMIT,
   DEFAULT_STALL_WARN_MS: () => DEFAULT_STALL_WARN_MS,
+  MISSING_RENDER_ERROR: () => MISSING_RENDER_ERROR,
   OverlayErrorBoundary: () => OverlayErrorBoundary,
   OverlayErrorFallback: () => OverlayErrorFallback,
   OverlayLoadingFallback: () => OverlayLoadingFallback,
@@ -310,7 +311,7 @@ function SummonProvider({
 }
 
 // src/react/defineOverlay.tsx
-var import_react9 = require("react");
+var import_react10 = require("react");
 var import_summon7 = require("@ai-matrx/summon");
 var import_summon8 = require("@ai-matrx/summon");
 
@@ -348,7 +349,7 @@ function emitOverlayEvent(channelId, type, payload) {
 }
 
 // src/react/instanceBody.tsx
-var import_react8 = require("react");
+var import_react9 = require("react");
 
 // src/react/OverlayErrorBoundary.tsx
 var import_react6 = require("react");
@@ -433,6 +434,26 @@ function useOverlayState(name, initial) {
   return [value, setValue];
 }
 
+// src/react/hostRenders.ts
+var import_react8 = require("react");
+var HostRendersContext = (0, import_react8.createContext)(null);
+var MISSING_RENDER_ERROR = "OverlayRenderMissingError";
+var missing = /* @__PURE__ */ new Map();
+function missingRenderLoader(overlayId) {
+  let loader = missing.get(overlayId);
+  if (!loader) {
+    const message = `Overlay "${overlayId}" is open but has no render module: its definition has no \`render\` and <SummonHost renders> has no "${overlayId}" entry.`;
+    loader = () => {
+      if (process.env.NODE_ENV !== "production") console.error(`[summon] ${message}`);
+      const error = new Error(message);
+      error.name = MISSING_RENDER_ERROR;
+      return Promise.reject(error);
+    };
+    missing.set(overlayId, loader);
+  }
+  return loader;
+}
+
 // src/react/instanceBody.tsx
 var import_jsx_runtime4 = require("react/jsx-runtime");
 function LazyRender({ overlayId, instanceId, data, hidden, close, render, attemptRef }) {
@@ -442,14 +463,17 @@ function LazyRender({ overlayId, instanceId, data, hidden, close, render, attemp
   const Render = entry.Component;
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(Render, { overlayId, instanceId, data, isOpen: true, close, hidden });
 }
-function createInstanceBody(overlayId, label, render, parse, refusable) {
+function createInstanceBody(overlayId, label, ownRender, parse, refusable) {
   function OverlayInstanceBody({ instanceId, instanceKey, data, hidden, close }) {
     const config = useSummonConfig();
     const ports = useSummonPorts();
-    const attemptRef = (0, import_react8.useRef)(0);
-    const parsed = (0, import_react8.useMemo)(() => parse(data), [data]);
+    const hostRenders = (0, import_react9.useContext)(HostRendersContext);
+    const hostRender = ownRender ? void 0 : hostRenders?.[overlayId];
+    const render = ownRender ?? hostRender ?? missingRenderLoader(overlayId);
+    const attemptRef = (0, import_react9.useRef)(0);
+    const parsed = (0, import_react9.useMemo)(() => parse(data), [data]);
     const refused = refusable && parsed === null;
-    (0, import_react8.useEffect)(() => {
+    (0, import_react9.useEffect)(() => {
       if (!refused) return;
       if (process.env.NODE_ENV !== "production") {
         ports.notify.warn(`Overlay "${overlayId}" was opened with data its parse() refused; closing it.`, {
@@ -458,7 +482,7 @@ function createInstanceBody(overlayId, label, render, parse, refusable) {
       }
       close();
     }, [refused, ports, instanceKey, close]);
-    const instance = (0, import_react8.useMemo)(
+    const instance = (0, import_react9.useMemo)(
       () => ({ overlayId, instanceId, instanceKey, close, hidden, rawData: data }),
       [instanceId, instanceKey, close, hidden, data]
     );
@@ -476,7 +500,7 @@ function createInstanceBody(overlayId, label, render, parse, refusable) {
         extras: config.errorReportExtras,
         onRetry: () => config.loaders.retry(overlayId, render, attemptRef.current),
         onClose: close,
-        children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_react8.Suspense, { fallback: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(config.loadingFallback, { overlayId, label }), children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+        children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_react9.Suspense, { fallback: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(config.loadingFallback, { overlayId, label }), children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
           LazyRender,
           {
             overlayId,
@@ -493,7 +517,7 @@ function createInstanceBody(overlayId, label, render, parse, refusable) {
     return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(OverlayInstanceContext.Provider, { value: instance, children: config.renderWrapper ? config.renderWrapper(body, context) : body });
   }
   OverlayInstanceBody.displayName = `Overlay(${overlayId})`;
-  return (0, import_react8.memo)(OverlayInstanceBody);
+  return (0, import_react9.memo)(OverlayInstanceBody);
 }
 
 // src/react/defineOverlay.tsx
@@ -525,19 +549,19 @@ function defineOverlay() {
     const meta = spec;
     function useSummon() {
       const dispatch = useSummonDispatch();
-      return (0, import_react9.useCallback)((options) => openWith(dispatch, id, multi, options), [dispatch]);
+      return (0, import_react10.useCallback)((options) => openWith(dispatch, id, multi, options), [dispatch]);
     }
     function useIsOpen(instanceId = import_summon7.DEFAULT_INSTANCE_ID) {
       return useSummonSelector((state) => (0, import_summon8.selectIsOverlayOpen)(state, id, instanceId));
     }
     function useClose() {
       const dispatch = useSummonDispatch();
-      return (0, import_react9.useCallback)((instanceId) => dispatchClose(dispatch, id, instanceId ?? import_summon7.DEFAULT_INSTANCE_ID), [dispatch]);
+      return (0, import_react10.useCallback)((instanceId) => dispatchClose(dispatch, id, instanceId ?? import_summon7.DEFAULT_INSTANCE_ID), [dispatch]);
     }
     function useEmit() {
       const instance = useOptionalOverlayInstance();
       const channelId = instance?.overlayId === id ? instance.rawData?.[CALLBACK_GROUP_KEY] : void 0;
-      return (0, import_react9.useCallback)(
+      return (0, import_react10.useCallback)(
         (event, payload) => {
           if (typeof channelId === "string") emitOverlayEvent(channelId, event, payload);
         },
@@ -546,12 +570,12 @@ function defineOverlay() {
     }
     function Controller(props) {
       const dispatch = useSummonDispatch();
-      const [ownInstanceId] = (0, import_react9.useState)(() => multi ? newInstanceId(id) : import_summon7.DEFAULT_INSTANCE_ID);
+      const [ownInstanceId] = (0, import_react10.useState)(() => multi ? newInstanceId(id) : import_summon7.DEFAULT_INSTANCE_ID);
       const instanceId = props.instanceId ?? ownInstanceId;
-      const handlersRef = (0, import_react9.useRef)(props.handlers);
+      const handlersRef = (0, import_react10.useRef)(props.handlers);
       handlersRef.current = props.handlers;
       const hasHandlers = props.handlers !== void 0;
-      const data = (0, import_react9.useMemo)(() => {
+      const data = (0, import_react10.useMemo)(() => {
         const out = {};
         for (const [key, value] of Object.entries(props)) {
           if (key !== "instanceId" && key !== "handlers") out[key] = value;
@@ -559,9 +583,9 @@ function defineOverlay() {
         return out;
       }, [props]);
       const signature = dataSignature(data);
-      const dataRef = (0, import_react9.useRef)(data);
+      const dataRef = (0, import_react10.useRef)(data);
       dataRef.current = data;
-      (0, import_react9.useEffect)(() => {
+      (0, import_react10.useEffect)(() => {
         const key = (0, import_summon7.instanceKey)(id, instanceId);
         const open = { ...dataRef.current };
         if (hasHandlers) open[CALLBACK_GROUP_KEY] = openOverlayEventChannel(key, () => handlersRef.current);
@@ -589,7 +613,7 @@ function defineOverlay() {
 }
 
 // src/react/SummonHost.tsx
-var import_react10 = require("react");
+var import_react11 = require("react");
 var import_summon9 = require("@ai-matrx/summon");
 var import_summon10 = require("@ai-matrx/summon");
 var import_summon11 = require("@ai-matrx/summon");
@@ -612,7 +636,7 @@ var NO_RETAINED = /* @__PURE__ */ new Map();
 function useCloseOnNavigation() {
   const ports = useSummonPorts();
   const dispatch = useSummonDispatch();
-  (0, import_react10.useEffect)(() => {
+  (0, import_react11.useEffect)(() => {
     const router = ports.router;
     let previous = router.pathname();
     return router.subscribe(() => {
@@ -624,19 +648,19 @@ function useCloseOnNavigation() {
     });
   }, [ports, dispatch]);
 }
-var InstanceSlot = (0, import_react10.memo)(function InstanceSlot2({ definition, instanceId, data, hidden }) {
+var InstanceSlot = (0, import_react11.memo)(function InstanceSlot2({ definition, instanceId, data, hidden }) {
   const dispatch = useSummonDispatch();
-  const close = (0, import_react10.useCallback)(() => dispatchClose(dispatch, definition.id, instanceId), [dispatch, definition.id, instanceId]);
+  const close = (0, import_react11.useCallback)(() => dispatchClose(dispatch, definition.id, instanceId), [dispatch, definition.id, instanceId]);
   const Body = definition.Body;
   return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(Body, { instanceId, instanceKey: (0, import_summon12.instanceKey)(definition.id, instanceId), data, hidden, close });
 });
-var DefinitionSlot = (0, import_react10.memo)(function DefinitionSlot2({ definition }) {
+var DefinitionSlot = (0, import_react11.memo)(function DefinitionSlot2({ definition }) {
   const { keepAlive } = useSummonConfig();
   const dispatch = useSummonDispatch();
   const open = useSummonSelector((state) => (0, import_summon11.selectOpenInstances)(state, definition.id), sameInstances);
   const keepHidden = definition.keepAlive === "hidden";
-  const [retained, setRetained] = (0, import_react10.useState)(NO_RETAINED);
-  const [previousOpen, setPreviousOpen] = (0, import_react10.useState)(open);
+  const [retained, setRetained] = (0, import_react11.useState)(NO_RETAINED);
+  const [previousOpen, setPreviousOpen] = (0, import_react11.useState)(open);
   if (previousOpen !== open) {
     setPreviousOpen(open);
     if (keepHidden) {
@@ -649,8 +673,8 @@ var DefinitionSlot = (0, import_react10.memo)(function DefinitionSlot2({ definit
       setRetained(next);
     }
   }
-  const registered = (0, import_react10.useRef)(/* @__PURE__ */ new Set());
-  (0, import_react10.useEffect)(() => {
+  const registered = (0, import_react11.useRef)(/* @__PURE__ */ new Set());
+  (0, import_react11.useEffect)(() => {
     const seen = registered.current;
     for (const instanceId of retained.keys()) {
       if (seen.has(instanceId)) continue;
@@ -673,7 +697,7 @@ var DefinitionSlot = (0, import_react10.memo)(function DefinitionSlot2({ definit
       keepAlive.release((0, import_summon12.instanceKey)(definition.id, instanceId));
     }
   }, [retained, keepAlive, definition.id, dispatch]);
-  (0, import_react10.useEffect)(() => {
+  (0, import_react11.useEffect)(() => {
     const seen = registered.current;
     return () => {
       for (const instanceId of seen) {
@@ -689,30 +713,30 @@ var DefinitionSlot = (0, import_react10.memo)(function DefinitionSlot2({ definit
   for (const instance of open) {
     const node = /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(InstanceSlot, { definition, instanceId: instance.instanceId, data: asRawData(instance.data), hidden: false }, instance.instanceId);
     nodes.push(
-      keepHidden ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_react10.Activity, { mode: "visible", children: node }, instance.instanceId) : node
+      keepHidden ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_react11.Activity, { mode: "visible", children: node }, instance.instanceId) : node
     );
   }
   if (keepHidden) {
     for (const [instanceId, data] of retained) {
       nodes.push(
-        /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_react10.Activity, { mode: "hidden", children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(InstanceSlot, { definition, instanceId, data, hidden: true }, instanceId) }, instanceId)
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_react11.Activity, { mode: "hidden", children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(InstanceSlot, { definition, instanceId, data, hidden: true }, instanceId) }, instanceId)
       );
     }
   }
   return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_jsx_runtime5.Fragment, { children: nodes });
 });
-function SummonHost({ definitions }) {
-  const registeredFor = (0, import_react10.useRef)(null);
+function SummonHost({ definitions, renders }) {
+  const registeredFor = (0, import_react11.useRef)(null);
   if (registeredFor.current !== definitions) {
     (0, import_summon10.registerOverlayMeta)(definitions.map((definition) => definition.meta));
     registeredFor.current = definitions;
   }
   useCloseOnNavigation();
-  return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_jsx_runtime5.Fragment, { children: definitions.map((definition) => /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(DefinitionSlot, { definition }, definition.id)) });
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(HostRendersContext.Provider, { value: renders ?? null, children: definitions.map((definition) => /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(DefinitionSlot, { definition }, definition.id)) });
 }
 
 // src/react/hooks.ts
-var import_react11 = require("react");
+var import_react12 = require("react");
 var import_summon13 = require("@ai-matrx/summon");
 var import_summon14 = require("@ai-matrx/summon");
 var import_summon15 = require("@ai-matrx/summon");
@@ -721,7 +745,7 @@ function useIsOverlayOpen(overlayId, instanceId = import_summon15.DEFAULT_INSTAN
 }
 function useOpenOverlay(overlayId) {
   const dispatch = useSummonDispatch();
-  return (0, import_react11.useCallback)(
+  return (0, import_react12.useCallback)(
     (options) => {
       const multi = (0, import_summon13.getOverlayMeta)(overlayId)?.instance === "multi";
       const instanceId = options?.instanceId ?? (multi ? newInstanceId(overlayId) : import_summon15.DEFAULT_INSTANCE_ID);
@@ -733,6 +757,6 @@ function useOpenOverlay(overlayId) {
 }
 function useCloseOverlay(overlayId, instanceId = import_summon15.DEFAULT_INSTANCE_ID) {
   const dispatch = useSummonDispatch();
-  return (0, import_react11.useCallback)(() => dispatchClose(dispatch, overlayId, instanceId), [dispatch, overlayId, instanceId]);
+  return (0, import_react12.useCallback)(() => dispatchClose(dispatch, overlayId, instanceId), [dispatch, overlayId, instanceId]);
 }
 //# sourceMappingURL=react.cjs.map