@ai-matrx/summon 0.1.7 → 0.1.8

package/dist/root.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/root.ts","../src/root/SummonRoot.tsx","../src/root/context.ts","../src/root/host.ts","../src/root/storeHooks.ts","../src/root/defineOverlay.tsx","../src/root/dispatchers.ts","../src/root/emit.ts","../src/root/instance.ts"],"sourcesContent":["// @ai-matrx/summon/root — the light React half: `<SummonRoot>` (store + host settings, nothing\n// heavy), the store hooks, `defineOverlay` (openers, Controller, open/close hooks, emitter) and the\n// instance context. Importing it never loads a slice, the host, a window or the handles registry.\nexport { SummonRoot, type SummonRootProps } from \"./root/SummonRoot\";\nexport { SummonStoreContext, SummonPortsContext } from \"./root/context\";\nexport {\n  configureSummonHost,\n  getSummonHostConfig,\n  getSummonHostPorts,\n  getSummonHostVersion,\n  type SummonHostConfig,\n  type SummonHostWindows,\n  type OverlayRenderContext,\n  type OverlayErrorExtrasContext,\n} from \"./root/host\";\nexport {\n  useSummonSelector,\n  useSummonDispatch,\n  useSummonStore,\n  useSummonPorts,\n  useOptionalSummonPorts,\n  useOptionalSummonStore,\n  type SummonReactDispatch,\n  type SummonReactStore,\n} from \"./root/storeHooks\";\nexport {\n  defineOverlay,\n  CALLBACK_GROUP_KEY,\n  type OverlayDefinition,\n  type OverlaySpec,\n  type HostableOverlay,\n  type OverlayHandle,\n  type OverlayOpener,\n  type OverlayOpenOptions,\n  type OverlayControllerProps,\n  type OverlayEmitter,\n  type OverlayEventMap,\n  type OverlayHandlers,\n} from \"./root/defineOverlay\";\nexport { newInstanceId, dispatchOpen, dispatchClose } from \"./root/dispatchers\";\nexport { OverlayInstanceContext, useOverlayInstance, useOptionalOverlayInstance, type OverlayInstanceContextValue } from \"./root/instance\";\nexport { registerOverlayEmitter, emitOverlayEventLight } from \"./root/emit\";\n","// `<SummonRoot>` — the only summon component a host mounts at its root, and it does next to\n// nothing: it hands the host's store to the summon context (so every opener works at once) and\n// records the host's settings. Nothing heavy loads here. The host's runtime component (tray sync,\n// router bridge — whatever only matters once windows exist) is fetched and mounted the moment the\n// summon core installs: on the first open, a page's own WindowPanel, a link, or saved windows.\n\nimport { lazy, Suspense, useEffect, useState, useSyncExternalStore, type ComponentType, type ReactNode } from \"react\";\nimport { Provider } from \"react-redux\";\nimport type { Store } from \"@reduxjs/toolkit\";\nimport { isSummonInstalled, subscribeSummonInstalled } from \"@ai-matrx/summon/open\";\nimport { SummonStoreContext } from \"./context\";\nimport { configureSummonHost, type SummonHostConfig } from \"./host\";\n\nexport interface SummonRootProps extends SummonHostConfig {\n  /** The host store, with the gate (`createSummonGate`) in its middleware chain. */\n  readonly store: Store<unknown>;\n  /** Mounted once the summon core is installed; one import() of the host's whole runtime set. */\n  readonly runtime?: () => Promise<{ default: ComponentType }>;\n  readonly children?: ReactNode;\n}\n\nconst serverSnapshot = () => false;\n\nexport function SummonRoot({ store, runtime, children, ports, renderWrapper, errorReportExtras, windows }: SummonRootProps) {\n  // Settings are recorded before the first child renders (a page's WindowPanel may read them).\n  const [config] = useState<SummonHostConfig>(() => {\n    const initial = { ports, renderWrapper, errorReportExtras, windows };\n    configureSummonHost(initial);\n    return initial;\n  });\n  useEffect(() => {\n    if (config.ports === ports && config.renderWrapper === renderWrapper && config.errorReportExtras === errorReportExtras && config.windows === windows) return;\n    configureSummonHost({ ports, renderWrapper, errorReportExtras, windows });\n  }, [config, ports, renderWrapper, errorReportExtras, windows]);\n\n  const installed = useSyncExternalStore(subscribeSummonInstalled, isSummonInstalled, serverSnapshot);\n  const [Runtime] = useState(() => (runtime ? lazy(runtime) : null));\n\n  return (\n    <Provider store={store} context={SummonStoreContext}>\n      {children}\n      {installed && Runtime ? (\n        <Suspense fallback={null}>\n          <Runtime />\n        </Suspense>\n      ) : null}\n    </Provider>\n  );\n}\n","// The contexts every summon section reads, light enough for the root: the overlays store rides\n// its OWN react-redux context (chat-package pattern), so a private overlays store never collides\n// with a host's store and a host that hands its one store to `<SummonRoot>` simply passes it in.\nimport { createContext } from \"react\";\nimport type { ReactReduxContextValue } from \"react-redux\";\nimport type { SummonPorts } from \"@ai-matrx/summon/open\";\n\nexport const SummonStoreContext = createContext<ReactReduxContextValue | null>(null);\nSummonStoreContext.displayName = \"SummonStoreContext\";\n\nexport const SummonPortsContext = createContext<SummonPorts | null>(null);\nSummonPortsContext.displayName = \"SummonPortsContext\";\n","// The host's settings, configured ONCE at the root (`<SummonRoot>`) and read wherever a provider\n// is absent: a WindowPanel rendered by a page, the lazily loaded host, links and persistence. A\n// heavy `<SummonProvider>` still overrides them for its subtree (a package's own bare host).\nimport { globalSlot } from \"@ai-matrx/kit/global-slot\";\nimport { resolvePorts, type SummonPorts } from \"@ai-matrx/summon/open\";\nimport type { ComponentType, ReactNode } from \"react\";\n\n/** One rendered overlay instance, as the host wrapper and error extras see it. */\nexport interface OverlayRenderContext {\n  readonly overlayId: string;\n  readonly instanceId: string;\n  readonly instanceKey: string;\n  readonly label: string;\n}\n\nexport interface OverlayErrorExtrasContext extends OverlayRenderContext {\n  readonly error: unknown;\n  readonly componentStack: string | null;\n}\n\nexport interface SummonHostWindows {\n  readonly escapeYieldSelector?: string | undefined;\n  readonly mobileTopOffset?: string | undefined;\n  readonly selectionSurface?: ComponentType<{ readonly children: ReactNode }> | undefined;\n}\n\nexport interface SummonHostConfig {\n  readonly ports?: Partial<SummonPorts> | undefined;\n  /** Wrap every rendered overlay (AI Matrx: its surface layer boundary). */\n  readonly renderWrapper?: ((node: ReactNode, context: OverlayRenderContext) => ReactNode) | undefined;\n  /** Extra controls in the default error card's footer (AI Matrx: \"Copy for AI\"). */\n  readonly errorReportExtras?: ((context: OverlayErrorExtrasContext) => ReactNode) | undefined;\n  /** Window host options (the window section reads them when no WindowsProvider is above). */\n  readonly windows?: SummonHostWindows | undefined;\n}\n\ninterface HostSlot {\n  config: SummonHostConfig;\n  ports: SummonPorts | null;\n  version: number;\n}\n\nconst slot = (): HostSlot => globalSlot<HostSlot>(\"ai-matrx.summon.host\", () => ({ config: {}, ports: null, version: 0 }));\n\nexport function configureSummonHost(config: SummonHostConfig): void {\n  const s = slot();\n  if (s.config === config) return;\n  s.config = config;\n  s.ports = null;\n  s.version += 1;\n}\n\nexport function getSummonHostConfig(): SummonHostConfig {\n  return slot().config;\n}\n\n/** The configured ports, resolved over the working defaults (stable until reconfigured). */\nexport function getSummonHostPorts(): SummonPorts {\n  const s = slot();\n  return (s.ports ??= resolvePorts(s.config.ports));\n}\n\n/** Bumps on every reconfigure; memo keys for values derived from the host config. */\nexport function getSummonHostVersion(): number {\n  return slot().version;\n}\n","// Typed hooks over the package's own store context. Every package component reads the overlays\n// store through these, never react-redux's default context, so a host's own <Provider> and the\n// overlays store never collide.\n\nimport { useContext } from \"react\";\nimport {\n  createDispatchHook,\n  createSelectorHook,\n  createStoreHook,\n  type UseDispatch,\n  type UseSelector,\n  type UseStore,\n} from \"react-redux\";\nimport type { Dispatch, Store, UnknownAction } from \"@reduxjs/toolkit\";\nimport type { SummonRootState } from \"@ai-matrx/summon\";\nimport type { SummonPorts } from \"@ai-matrx/summon/open\";\nimport { SummonPortsContext, SummonStoreContext } from \"./context\";\nimport { getSummonHostPorts } from \"./host\";\n\n/** Dispatch as the React section uses it: plain actions (thunks are the host's business). */\nexport type SummonReactDispatch = Dispatch<UnknownAction>;\n\n/** The store as the React section sees it: the overlays slices at their root keys (a host store has more). */\nexport type SummonReactStore = Store<SummonRootState>;\n\n/** Select from the overlays store. */\nexport const useSummonSelector: UseSelector<SummonRootState> = createSelectorHook(SummonStoreContext).withTypes<SummonRootState>();\n\n/** The overlays store's dispatch. */\nexport const useSummonDispatch: UseDispatch<SummonReactDispatch> = createDispatchHook(SummonStoreContext).withTypes<SummonReactDispatch>();\n\n/** The overlays store itself (for `getState()` inside callbacks). */\nexport const useSummonStore: UseStore<SummonReactStore> = createStoreHook(SummonStoreContext).withTypes<SummonReactStore>();\n\n/** The nearest provider's ports, else the ports configured at the root, else the working defaults. */\nexport function useSummonPorts(): SummonPorts {\n  return useContext(SummonPortsContext) ?? getSummonHostPorts();\n}\n\n/** Same as `useSummonPorts` (kept for components written to work page-local). */\nexport function useOptionalSummonPorts(): SummonPorts {\n  return useContext(SummonPortsContext) ?? getSummonHostPorts();\n}\n\n/**\n * The nearest provider's store, or `null` when nothing above provides one — for packages that\n * mount their own provider only when the host has none (chat's windows on a bare host).\n */\nexport function useOptionalSummonStore(): SummonReactStore | null {\n  const context = useContext(SummonStoreContext);\n  return context ? (context.store as unknown as SummonReactStore) : null;\n}\n","// `defineOverlay` — the declare-once API (C38 R2). One light definition per overlay carries its\n// metadata and (optionally) a lazy `render` import; the definition generates the opener hook, the declarative\n// Controller, the open/close hooks and a typed event emitter. The host renders definitions; the\n// render module is the old controller block, moved verbatim, and is fetched only when opened.\n//\n// Light by construction (the root section): no slice, no host, no handles registry. Opening goes\n// through the light creators (a gated host store loads the core on the first one); a callback-aware\n// open reserves its event channel and the handles section arrives with that first open.\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport {\n  DEFAULT_INSTANCE_ID,\n  instanceKey as toInstanceKey,\n  openPendingEventChannel,\n  selectIsOverlayOpen,\n  type InstanceKey,\n  type OverlayDefinitionMeta,\n  type OverlayRawData,\n  type AnyOverlayMeta,\n} from \"@ai-matrx/summon/open\";\nimport type { OverlayRenderProps } from \"../react/instanceBody\";\nimport type { RenderModule } from \"../react/loaderCache\";\nimport { dispatchClose, dispatchOpen, newInstanceId } from \"./dispatchers\";\nimport { emitOverlayEventLight } from \"./emit\";\nimport { useOptionalOverlayInstance } from \"./instance\";\nimport { useSummonDispatch, useSummonSelector, type SummonReactDispatch } from \"./storeHooks\";\n\n/** Event name → payload, declared once per overlay: `defineOverlay<Data, { uploaded: Result }>()`. */\nexport type OverlayEventMap = Record<string, unknown>;\n\nexport type OverlayHandlers<Events extends OverlayEventMap> = {\n  readonly [K in keyof Events]?: (payload: Events[K]) => void;\n};\n\nfunction openOverlayEventChannel<Events extends OverlayEventMap>(\n  owner: InstanceKey,\n  getHandlers: () => OverlayHandlers<Events> | undefined,\n): string {\n  return openPendingEventChannel(owner, getHandlers as () => Readonly<Record<string, ((payload: unknown) => void) | undefined>> | undefined);\n}\n\n/** The open-data key that carries an overlay's event channel id (the old callback-group key). */\nexport const CALLBACK_GROUP_KEY = \"callbackGroupId\";\n\nexport interface OverlayHandle {\n  readonly overlayId: string;\n  readonly instanceId: string;\n  close(): void;\n}\n\nexport interface OverlayOpenOptions<Data, Events extends OverlayEventMap> {\n  readonly data?: Data;\n  /** Single-instance overlays ignore it unless given; multi-instance generate one when omitted. */\n  readonly instanceId?: string;\n  /** Plain functions; they reach the caller through an event channel owned by the instance. */\n  readonly handlers?: OverlayHandlers<Events>;\n}\n\nexport type OverlayOpener<Data, Events extends OverlayEventMap> = (options?: OverlayOpenOptions<Data, Events>) => OverlayHandle;\n\nexport type OverlayControllerProps<Data, Events extends OverlayEventMap> = Data & {\n  readonly instanceId?: string;\n  readonly handlers?: OverlayHandlers<Events>;\n};\n\nexport type OverlayEmitter<Events extends OverlayEventMap> = <K extends keyof Events & string>(event: K, payload: Events[K]) => void;\n\n/** What a definition file passes to `defineOverlay<Data>()(…)`. */\nexport interface OverlaySpec<Id extends string, Data, Parsed> extends OverlayDefinitionMeta<Id, Data> {\n  /**\n   * The lazily loaded render module. Its default export receives `OverlayRenderProps<Parsed>`.\n   * Optional: a large app leaves it out and hands `<SummonHost renders={…}>` one id → import map,\n   * so files that import a definition for its opener never gain an import() edge to the window\n   * (the host-build law). When present it wins over the host map.\n   */\n  readonly render?: () => Promise<RenderModule<OverlayRenderProps<NoInfer<Parsed>>>>;\n  /** Narrow raw open data once. `null` = refuse: the instance is closed with a warning. */\n  readonly parse?: (raw: OverlayRawData) => Parsed | null;\n}\n\n/** The type-erased half the host renders; no data types cross this line. */\nexport interface HostableOverlay {\n  readonly id: string;\n  readonly label: string;\n  readonly instance: \"single\" | \"multi\";\n  readonly keepAlive: \"none\" | \"hidden\" | \"restore\";\n  /** The metadata the core registry stores (links, window options, defaults…). */\n  readonly meta: AnyOverlayMeta;\n  /** The definition's own render loader (the host's `renders` map is used when absent). */\n  readonly render?: (() => Promise<unknown>) | undefined;\n  /** Narrows raw open data; the host builds each instance body from it on first render. */\n  readonly parse?: ((raw: OverlayRawData) => unknown) | undefined;\n}\n\nexport interface OverlayDefinition<Id extends string, Data, Parsed, Events extends OverlayEventMap>\n  extends Omit<OverlayDefinitionMeta<Id, Data>, \"id\" | \"instance\" | \"keepAlive\">,\n    HostableOverlay {\n  readonly id: Id;\n  readonly render?: () => Promise<RenderModule<OverlayRenderProps<Parsed>>>;\n  /** Imperative opener: `const open = def.useSummon(); open({ data })` → handle. */\n  useSummon(): OverlayOpener<Data, Events>;\n  /** Declarative form: opens on mount, closes on unmount, re-opens when its data changes. */\n  readonly Controller: (props: OverlayControllerProps<Data, Events>) => null;\n  useIsOpen(instanceId?: string): boolean;\n  /** `const close = def.useClose(); close(instanceId?)`. */\n  useClose(): (instanceId?: string) => void;\n  /** Inside the render tree: emit a declared event to the opener's handlers. */\n  useEmit(): OverlayEmitter<Events>;\n}\n\nfunction openWith<Data, Events extends OverlayEventMap>(\n  dispatch: SummonReactDispatch,\n  id: string,\n  multi: boolean,\n  options: OverlayOpenOptions<Data, Events> | undefined,\n): OverlayHandle {\n  const instanceId = options?.instanceId ?? (multi ? newInstanceId(id) : DEFAULT_INSTANCE_ID);\n  const key = toInstanceKey(id, instanceId);\n  const data: Record<string, unknown> = {};\n  const given: unknown = options?.data;\n  if (typeof given === \"object\" && given !== null) Object.assign(data, given);\n  const handlers = options?.handlers;\n  if (handlers) data[CALLBACK_GROUP_KEY] = openOverlayEventChannel<Events>(key, () => handlers);\n  dispatchOpen(dispatch, id, instanceId, data);\n  return { overlayId: id, instanceId, close: () => dispatchClose(dispatch, id, instanceId) };\n}\n\n/** Stable identity for the serialisable part of Controller props (functions never reopen). */\nfunction dataSignature(data: Readonly<Record<string, unknown>>): string {\n  try {\n    return JSON.stringify(data, (_key, value: unknown) => (typeof value === \"function\" ? undefined : value));\n  } catch {\n    return String(Date.now());\n  }\n}\n\n/**\n * Declare an overlay once. Curried so `Data` (and `Events`) are named while the id and the\n * parsed-data type are inferred:\n *\n *   export const notesWindow = defineOverlay<NotesWindowData>()({\n *     id: \"notesWindow\", label: \"Notes\", render: () => import(\"./notesWindow.render\"),\n *   });\n */\nexport function defineOverlay<Data extends object = Record<string, never>, Events extends OverlayEventMap = Record<never, never>>() {\n  return function define<const Id extends string, Parsed = OverlayRawData>(\n    spec: OverlaySpec<Id, Data, Parsed>,\n  ): OverlayDefinition<Id, Data, Parsed, Events> {\n    const id = spec.id;\n    const multi = spec.instance === \"multi\";\n    // The registry stores every definition's metadata under one erased type (AnyOverlayMeta).\n    const meta: AnyOverlayMeta = spec;\n\n    function useSummon(): OverlayOpener<Data, Events> {\n      const dispatch = useSummonDispatch();\n      return useCallback((options) => openWith(dispatch, id, multi, options), [dispatch]);\n    }\n\n    function useIsOpen(instanceId: string = DEFAULT_INSTANCE_ID): boolean {\n      return useSummonSelector((state) => selectIsOverlayOpen(state, id, instanceId));\n    }\n\n    function useClose(): (instanceId?: string) => void {\n      const dispatch = useSummonDispatch();\n      return useCallback((instanceId?: string) => dispatchClose(dispatch, id, instanceId ?? DEFAULT_INSTANCE_ID), [dispatch]);\n    }\n\n    function useEmit(): OverlayEmitter<Events> {\n      const instance = useOptionalOverlayInstance();\n      const channelId = instance?.overlayId === id ? instance.rawData?.[CALLBACK_GROUP_KEY] : undefined;\n      return useCallback<OverlayEmitter<Events>>(\n        (event, payload) => {\n          if (typeof channelId === \"string\") emitOverlayEventLight(channelId, event, payload);\n        },\n        [channelId],\n      );\n    }\n\n    function Controller(props: OverlayControllerProps<Data, Events>): null {\n      const dispatch = useSummonDispatch();\n      const [ownInstanceId] = useState(() => (multi ? newInstanceId(id) : DEFAULT_INSTANCE_ID));\n      const instanceId = props.instanceId ?? ownInstanceId;\n      // Latest handlers, read at emit time: a new function identity never reopens the overlay.\n      const handlersRef = useRef(props.handlers);\n      handlersRef.current = props.handlers;\n      const hasHandlers = props.handlers !== undefined;\n\n      const data = useMemo(() => {\n        const out: Record<string, unknown> = {};\n        for (const [key, value] of Object.entries(props)) {\n          if (key !== \"instanceId\" && key !== \"handlers\") out[key] = value;\n        }\n        return out;\n      }, [props]);\n      const signature = dataSignature(data);\n      const dataRef = useRef(data);\n      dataRef.current = data;\n\n      useEffect(() => {\n        const key: InstanceKey = toInstanceKey(id, instanceId);\n        const open: Record<string, unknown> = { ...dataRef.current };\n        if (hasHandlers) open[CALLBACK_GROUP_KEY] = openOverlayEventChannel<Events>(key, () => handlersRef.current);\n        dispatchOpen(dispatch, id, instanceId, open);\n        return () => dispatchClose(dispatch, id, instanceId);\n      }, [dispatch, instanceId, signature, hasHandlers]);\n\n      return null;\n    }\n    Controller.displayName = `${id}Controller`;\n\n    return {\n      ...spec,\n      id,\n      label: spec.label,\n      instance: multi ? \"multi\" : \"single\",\n      keepAlive: spec.keepAlive ?? \"none\",\n      meta,\n      useSummon,\n      Controller,\n      useIsOpen,\n      useClose,\n      useEmit,\n    };\n  };\n}\n","// The one place a definition turns an untyped (string) overlay id into the typed action creators.\n// Inside the package `OverlayId` is `string`; a host that augments the registry narrows it to its\n// ids, and these keep compiling there because definitions carry their own id.\n\nimport { closeOverlay, openOverlay, DEFAULT_INSTANCE_ID, type OverlayDataOf, type OverlayId } from \"@ai-matrx/summon/open\";\nimport type { SummonReactDispatch } from \"./storeHooks\";\n\nexport function newInstanceId(overlayId: string): string {\n  return `${overlayId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;\n}\n\nexport function dispatchOpen(dispatch: SummonReactDispatch, overlayId: string, instanceId: string, data: unknown): void {\n  dispatch(\n    openOverlay({\n      overlayId: overlayId as OverlayId,\n      instanceId,\n      data: (data ?? null) as OverlayDataOf<OverlayId> | null,\n    }),\n  );\n}\n\nexport function dispatchClose(dispatch: SummonReactDispatch, overlayId: string, instanceId: string = DEFAULT_INSTANCE_ID): void {\n  dispatch(closeOverlay({ overlayId: overlayId as OverlayId, instanceId }));\n}\n","// Emitting an overlay event from inside its render tree. The render tree has the handles registry\n// loaded (the react section registers its synchronous emitter on evaluation); before that, the\n// emit waits for the one handles import.\nimport { globalSlot } from \"@ai-matrx/kit/global-slot\";\nimport { materializePendingChannels } from \"@ai-matrx/summon/open\";\n\ntype Emitter = (channelId: string, type: string, payload: unknown) => void;\n\nconst slot = (): { emit: Emitter | null } => globalSlot(\"ai-matrx.summon.emitter\", () => ({ emit: null as Emitter | null }));\n\n/** The react section installs the synchronous emitter (it holds handles statically). */\nexport function registerOverlayEmitter(emit: Emitter): void {\n  slot().emit = emit;\n}\n\nexport function emitOverlayEventLight(channelId: string, type: string, payload: unknown): void {\n  const emit = slot().emit;\n  if (emit) {\n    emit(channelId, type, payload);\n    return;\n  }\n  void import(\"@ai-matrx/summon/handles\").then(({ createEventChannel, getEventChannel }) => {\n    materializePendingChannels(createEventChannel);\n    getEventChannel<{ type: string; payload: unknown }>(channelId)?.emit({ type, payload });\n  });\n}\n","// The context every rendered overlay instance provides to its subtree, and the hooks that read who\n// it is. Light: a definition's `useEmit` reads it; the saved-state hook stays in `./react`.\nimport { createContext, useContext } from \"react\";\nimport type { InstanceKey, OverlayRawData } from \"@ai-matrx/summon/open\";\n\nexport interface OverlayInstanceContextValue {\n  readonly overlayId: string;\n  readonly instanceId: string;\n  readonly instanceKey: InstanceKey;\n  readonly close: () => void;\n  readonly hidden: boolean;\n  /** The open data as it arrived (pre-parse); event emitters read their channel id from it. */\n  readonly rawData: OverlayRawData;\n}\n\nexport const OverlayInstanceContext = createContext<OverlayInstanceContextValue | null>(null);\nOverlayInstanceContext.displayName = \"OverlayInstanceContext\";\n\n/** The open instance this component renders inside. Throws outside an overlay. */\nexport function useOverlayInstance(): OverlayInstanceContextValue {\n  const value = useContext(OverlayInstanceContext);\n  if (!value) throw new Error(\"[summon] useOverlayInstance() was called outside a rendered overlay.\");\n  return value;\n}\n\n/** Same as `useOverlayInstance`, but `null` outside an overlay. */\nexport function useOptionalOverlayInstance(): OverlayInstanceContextValue | null {\n  return useContext(OverlayInstanceContext);\n}\n"],"mappings":"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","names":["import_react","import_open","import_react","import_react_redux","import_react","import_open","import_open","import_global_slot","import_open","slot","import_react","toInstanceKey"]}

package/dist/root.d.cts

@@ -0,0 +1,175 @@
+import * as react from 'react';
+import { ReactNode, ComponentType } from 'react';
+import * as _reduxjs_toolkit from '@reduxjs/toolkit';
+import { Store, Dispatch, UnknownAction } from '@reduxjs/toolkit';
+import { SummonPorts, AnyOverlayMeta, OverlayRawData, OverlayDefinitionMeta, InstanceKey } from '@ai-matrx/summon/open';
+import { ReactReduxContextValue, UseDispatch, UseSelector, UseStore } from 'react-redux';
+import { SummonRootState } from '@ai-matrx/summon';
+import { a as RenderModule, O as OverlayRenderProps } from './instanceBody-CgZAFnic.cjs';
+
+/** One rendered overlay instance, as the host wrapper and error extras see it. */
+interface OverlayRenderContext {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    readonly instanceKey: string;
+    readonly label: string;
+}
+interface OverlayErrorExtrasContext extends OverlayRenderContext {
+    readonly error: unknown;
+    readonly componentStack: string | null;
+}
+interface SummonHostWindows {
+    readonly escapeYieldSelector?: string | undefined;
+    readonly mobileTopOffset?: string | undefined;
+    readonly selectionSurface?: ComponentType<{
+        readonly children: ReactNode;
+    }> | undefined;
+}
+interface SummonHostConfig {
+    readonly ports?: Partial<SummonPorts> | undefined;
+    /** Wrap every rendered overlay (AI Matrx: its surface layer boundary). */
+    readonly renderWrapper?: ((node: ReactNode, context: OverlayRenderContext) => ReactNode) | undefined;
+    /** Extra controls in the default error card's footer (AI Matrx: "Copy for AI"). */
+    readonly errorReportExtras?: ((context: OverlayErrorExtrasContext) => ReactNode) | undefined;
+    /** Window host options (the window section reads them when no WindowsProvider is above). */
+    readonly windows?: SummonHostWindows | undefined;
+}
+declare function configureSummonHost(config: SummonHostConfig): void;
+declare function getSummonHostConfig(): SummonHostConfig;
+/** The configured ports, resolved over the working defaults (stable until reconfigured). */
+declare function getSummonHostPorts(): SummonPorts;
+/** Bumps on every reconfigure; memo keys for values derived from the host config. */
+declare function getSummonHostVersion(): number;
+
+interface SummonRootProps extends SummonHostConfig {
+    /** The host store, with the gate (`createSummonGate`) in its middleware chain. */
+    readonly store: Store<unknown>;
+    /** Mounted once the summon core is installed; one import() of the host's whole runtime set. */
+    readonly runtime?: () => Promise<{
+        default: ComponentType;
+    }>;
+    readonly children?: ReactNode;
+}
+declare function SummonRoot({ store, runtime, children, ports, renderWrapper, errorReportExtras, windows }: SummonRootProps): react.JSX.Element;
+
+declare const SummonStoreContext: react.Context<ReactReduxContextValue<any, _reduxjs_toolkit.UnknownAction> | null>;
+declare const SummonPortsContext: react.Context<SummonPorts | null>;
+
+/** Dispatch as the React section uses it: plain actions (thunks are the host's business). */
+type SummonReactDispatch = Dispatch<UnknownAction>;
+/** The store as the React section sees it: the overlays slices at their root keys (a host store has more). */
+type SummonReactStore = Store<SummonRootState>;
+/** Select from the overlays store. */
+declare const useSummonSelector: UseSelector<SummonRootState>;
+/** The overlays store's dispatch. */
+declare const useSummonDispatch: UseDispatch<SummonReactDispatch>;
+/** The overlays store itself (for `getState()` inside callbacks). */
+declare const useSummonStore: UseStore<SummonReactStore>;
+/** The nearest provider's ports, else the ports configured at the root, else the working defaults. */
+declare function useSummonPorts(): SummonPorts;
+/** Same as `useSummonPorts` (kept for components written to work page-local). */
+declare function useOptionalSummonPorts(): SummonPorts;
+/**
+ * The nearest provider's store, or `null` when nothing above provides one — for packages that
+ * mount their own provider only when the host has none (chat's windows on a bare host).
+ */
+declare function useOptionalSummonStore(): SummonReactStore | null;
+
+/** Event name → payload, declared once per overlay: `defineOverlay<Data, { uploaded: Result }>()`. */
+type OverlayEventMap = Record<string, unknown>;
+type OverlayHandlers<Events extends OverlayEventMap> = {
+    readonly [K in keyof Events]?: (payload: Events[K]) => void;
+};
+/** The open-data key that carries an overlay's event channel id (the old callback-group key). */
+declare const CALLBACK_GROUP_KEY = "callbackGroupId";
+interface OverlayHandle {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    close(): void;
+}
+interface OverlayOpenOptions<Data, Events extends OverlayEventMap> {
+    readonly data?: Data;
+    /** Single-instance overlays ignore it unless given; multi-instance generate one when omitted. */
+    readonly instanceId?: string;
+    /** Plain functions; they reach the caller through an event channel owned by the instance. */
+    readonly handlers?: OverlayHandlers<Events>;
+}
+type OverlayOpener<Data, Events extends OverlayEventMap> = (options?: OverlayOpenOptions<Data, Events>) => OverlayHandle;
+type OverlayControllerProps<Data, Events extends OverlayEventMap> = Data & {
+    readonly instanceId?: string;
+    readonly handlers?: OverlayHandlers<Events>;
+};
+type OverlayEmitter<Events extends OverlayEventMap> = <K extends keyof Events & string>(event: K, payload: Events[K]) => void;
+/** What a definition file passes to `defineOverlay<Data>()(…)`. */
+interface OverlaySpec<Id extends string, Data, Parsed> extends OverlayDefinitionMeta<Id, Data> {
+    /**
+     * The lazily loaded render module. Its default export receives `OverlayRenderProps<Parsed>`.
+     * Optional: a large app leaves it out and hands `<SummonHost renders={…}>` one id → import map,
+     * so files that import a definition for its opener never gain an import() edge to the window
+     * (the host-build law). When present it wins over the host map.
+     */
+    readonly render?: () => Promise<RenderModule<OverlayRenderProps<NoInfer<Parsed>>>>;
+    /** Narrow raw open data once. `null` = refuse: the instance is closed with a warning. */
+    readonly parse?: (raw: OverlayRawData) => Parsed | null;
+}
+/** The type-erased half the host renders; no data types cross this line. */
+interface HostableOverlay {
+    readonly id: string;
+    readonly label: string;
+    readonly instance: "single" | "multi";
+    readonly keepAlive: "none" | "hidden" | "restore";
+    /** The metadata the core registry stores (links, window options, defaults…). */
+    readonly meta: AnyOverlayMeta;
+    /** The definition's own render loader (the host's `renders` map is used when absent). */
+    readonly render?: (() => Promise<unknown>) | undefined;
+    /** Narrows raw open data; the host builds each instance body from it on first render. */
+    readonly parse?: ((raw: OverlayRawData) => unknown) | undefined;
+}
+interface OverlayDefinition<Id extends string, Data, Parsed, Events extends OverlayEventMap> extends Omit<OverlayDefinitionMeta<Id, Data>, "id" | "instance" | "keepAlive">, HostableOverlay {
+    readonly id: Id;
+    readonly render?: () => Promise<RenderModule<OverlayRenderProps<Parsed>>>;
+    /** Imperative opener: `const open = def.useSummon(); open({ data })` → handle. */
+    useSummon(): OverlayOpener<Data, Events>;
+    /** Declarative form: opens on mount, closes on unmount, re-opens when its data changes. */
+    readonly Controller: (props: OverlayControllerProps<Data, Events>) => null;
+    useIsOpen(instanceId?: string): boolean;
+    /** `const close = def.useClose(); close(instanceId?)`. */
+    useClose(): (instanceId?: string) => void;
+    /** Inside the render tree: emit a declared event to the opener's handlers. */
+    useEmit(): OverlayEmitter<Events>;
+}
+/**
+ * Declare an overlay once. Curried so `Data` (and `Events`) are named while the id and the
+ * parsed-data type are inferred:
+ *
+ *   export const notesWindow = defineOverlay<NotesWindowData>()({
+ *     id: "notesWindow", label: "Notes", render: () => import("./notesWindow.render"),
+ *   });
+ */
+declare function defineOverlay<Data extends object = Record<string, never>, Events extends OverlayEventMap = Record<never, never>>(): <const Id extends string, Parsed = OverlayRawData>(spec: OverlaySpec<Id, Data, Parsed>) => OverlayDefinition<Id, Data, Parsed, Events>;
+
+declare function newInstanceId(overlayId: string): string;
+declare function dispatchOpen(dispatch: SummonReactDispatch, overlayId: string, instanceId: string, data: unknown): void;
+declare function dispatchClose(dispatch: SummonReactDispatch, overlayId: string, instanceId?: string): void;
+
+interface OverlayInstanceContextValue {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    readonly instanceKey: InstanceKey;
+    readonly close: () => void;
+    readonly hidden: boolean;
+    /** The open data as it arrived (pre-parse); event emitters read their channel id from it. */
+    readonly rawData: OverlayRawData;
+}
+declare const OverlayInstanceContext: react.Context<OverlayInstanceContextValue | null>;
+/** The open instance this component renders inside. Throws outside an overlay. */
+declare function useOverlayInstance(): OverlayInstanceContextValue;
+/** Same as `useOverlayInstance`, but `null` outside an overlay. */
+declare function useOptionalOverlayInstance(): OverlayInstanceContextValue | null;
+
+type Emitter = (channelId: string, type: string, payload: unknown) => void;
+/** The react section installs the synchronous emitter (it holds handles statically). */
+declare function registerOverlayEmitter(emit: Emitter): void;
+declare function emitOverlayEventLight(channelId: string, type: string, payload: unknown): void;
+
+export { CALLBACK_GROUP_KEY, type HostableOverlay, type OverlayControllerProps, type OverlayDefinition, type OverlayEmitter, type OverlayErrorExtrasContext, type OverlayEventMap, type OverlayHandle, type OverlayHandlers, OverlayInstanceContext, type OverlayInstanceContextValue, type OverlayOpenOptions, type OverlayOpener, type OverlayRenderContext, type OverlaySpec, type SummonHostConfig, type SummonHostWindows, SummonPortsContext, type SummonReactDispatch, type SummonReactStore, SummonRoot, type SummonRootProps, SummonStoreContext, configureSummonHost, defineOverlay, dispatchClose, dispatchOpen, emitOverlayEventLight, getSummonHostConfig, getSummonHostPorts, getSummonHostVersion, newInstanceId, registerOverlayEmitter, useOptionalOverlayInstance, useOptionalSummonPorts, useOptionalSummonStore, useOverlayInstance, useSummonDispatch, useSummonPorts, useSummonSelector, useSummonStore };

package/dist/root.d.ts

@@ -0,0 +1,175 @@
+import * as react from 'react';
+import { ReactNode, ComponentType } from 'react';
+import * as _reduxjs_toolkit from '@reduxjs/toolkit';
+import { Store, Dispatch, UnknownAction } from '@reduxjs/toolkit';
+import { SummonPorts, AnyOverlayMeta, OverlayRawData, OverlayDefinitionMeta, InstanceKey } from '@ai-matrx/summon/open';
+import { ReactReduxContextValue, UseDispatch, UseSelector, UseStore } from 'react-redux';
+import { SummonRootState } from '@ai-matrx/summon';
+import { a as RenderModule, O as OverlayRenderProps } from './instanceBody-CgZAFnic.js';
+
+/** One rendered overlay instance, as the host wrapper and error extras see it. */
+interface OverlayRenderContext {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    readonly instanceKey: string;
+    readonly label: string;
+}
+interface OverlayErrorExtrasContext extends OverlayRenderContext {
+    readonly error: unknown;
+    readonly componentStack: string | null;
+}
+interface SummonHostWindows {
+    readonly escapeYieldSelector?: string | undefined;
+    readonly mobileTopOffset?: string | undefined;
+    readonly selectionSurface?: ComponentType<{
+        readonly children: ReactNode;
+    }> | undefined;
+}
+interface SummonHostConfig {
+    readonly ports?: Partial<SummonPorts> | undefined;
+    /** Wrap every rendered overlay (AI Matrx: its surface layer boundary). */
+    readonly renderWrapper?: ((node: ReactNode, context: OverlayRenderContext) => ReactNode) | undefined;
+    /** Extra controls in the default error card's footer (AI Matrx: "Copy for AI"). */
+    readonly errorReportExtras?: ((context: OverlayErrorExtrasContext) => ReactNode) | undefined;
+    /** Window host options (the window section reads them when no WindowsProvider is above). */
+    readonly windows?: SummonHostWindows | undefined;
+}
+declare function configureSummonHost(config: SummonHostConfig): void;
+declare function getSummonHostConfig(): SummonHostConfig;
+/** The configured ports, resolved over the working defaults (stable until reconfigured). */
+declare function getSummonHostPorts(): SummonPorts;
+/** Bumps on every reconfigure; memo keys for values derived from the host config. */
+declare function getSummonHostVersion(): number;
+
+interface SummonRootProps extends SummonHostConfig {
+    /** The host store, with the gate (`createSummonGate`) in its middleware chain. */
+    readonly store: Store<unknown>;
+    /** Mounted once the summon core is installed; one import() of the host's whole runtime set. */
+    readonly runtime?: () => Promise<{
+        default: ComponentType;
+    }>;
+    readonly children?: ReactNode;
+}
+declare function SummonRoot({ store, runtime, children, ports, renderWrapper, errorReportExtras, windows }: SummonRootProps): react.JSX.Element;
+
+declare const SummonStoreContext: react.Context<ReactReduxContextValue<any, _reduxjs_toolkit.UnknownAction> | null>;
+declare const SummonPortsContext: react.Context<SummonPorts | null>;
+
+/** Dispatch as the React section uses it: plain actions (thunks are the host's business). */
+type SummonReactDispatch = Dispatch<UnknownAction>;
+/** The store as the React section sees it: the overlays slices at their root keys (a host store has more). */
+type SummonReactStore = Store<SummonRootState>;
+/** Select from the overlays store. */
+declare const useSummonSelector: UseSelector<SummonRootState>;
+/** The overlays store's dispatch. */
+declare const useSummonDispatch: UseDispatch<SummonReactDispatch>;
+/** The overlays store itself (for `getState()` inside callbacks). */
+declare const useSummonStore: UseStore<SummonReactStore>;
+/** The nearest provider's ports, else the ports configured at the root, else the working defaults. */
+declare function useSummonPorts(): SummonPorts;
+/** Same as `useSummonPorts` (kept for components written to work page-local). */
+declare function useOptionalSummonPorts(): SummonPorts;
+/**
+ * The nearest provider's store, or `null` when nothing above provides one — for packages that
+ * mount their own provider only when the host has none (chat's windows on a bare host).
+ */
+declare function useOptionalSummonStore(): SummonReactStore | null;
+
+/** Event name → payload, declared once per overlay: `defineOverlay<Data, { uploaded: Result }>()`. */
+type OverlayEventMap = Record<string, unknown>;
+type OverlayHandlers<Events extends OverlayEventMap> = {
+    readonly [K in keyof Events]?: (payload: Events[K]) => void;
+};
+/** The open-data key that carries an overlay's event channel id (the old callback-group key). */
+declare const CALLBACK_GROUP_KEY = "callbackGroupId";
+interface OverlayHandle {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    close(): void;
+}
+interface OverlayOpenOptions<Data, Events extends OverlayEventMap> {
+    readonly data?: Data;
+    /** Single-instance overlays ignore it unless given; multi-instance generate one when omitted. */
+    readonly instanceId?: string;
+    /** Plain functions; they reach the caller through an event channel owned by the instance. */
+    readonly handlers?: OverlayHandlers<Events>;
+}
+type OverlayOpener<Data, Events extends OverlayEventMap> = (options?: OverlayOpenOptions<Data, Events>) => OverlayHandle;
+type OverlayControllerProps<Data, Events extends OverlayEventMap> = Data & {
+    readonly instanceId?: string;
+    readonly handlers?: OverlayHandlers<Events>;
+};
+type OverlayEmitter<Events extends OverlayEventMap> = <K extends keyof Events & string>(event: K, payload: Events[K]) => void;
+/** What a definition file passes to `defineOverlay<Data>()(…)`. */
+interface OverlaySpec<Id extends string, Data, Parsed> extends OverlayDefinitionMeta<Id, Data> {
+    /**
+     * The lazily loaded render module. Its default export receives `OverlayRenderProps<Parsed>`.
+     * Optional: a large app leaves it out and hands `<SummonHost renders={…}>` one id → import map,
+     * so files that import a definition for its opener never gain an import() edge to the window
+     * (the host-build law). When present it wins over the host map.
+     */
+    readonly render?: () => Promise<RenderModule<OverlayRenderProps<NoInfer<Parsed>>>>;
+    /** Narrow raw open data once. `null` = refuse: the instance is closed with a warning. */
+    readonly parse?: (raw: OverlayRawData) => Parsed | null;
+}
+/** The type-erased half the host renders; no data types cross this line. */
+interface HostableOverlay {
+    readonly id: string;
+    readonly label: string;
+    readonly instance: "single" | "multi";
+    readonly keepAlive: "none" | "hidden" | "restore";
+    /** The metadata the core registry stores (links, window options, defaults…). */
+    readonly meta: AnyOverlayMeta;
+    /** The definition's own render loader (the host's `renders` map is used when absent). */
+    readonly render?: (() => Promise<unknown>) | undefined;
+    /** Narrows raw open data; the host builds each instance body from it on first render. */
+    readonly parse?: ((raw: OverlayRawData) => unknown) | undefined;
+}
+interface OverlayDefinition<Id extends string, Data, Parsed, Events extends OverlayEventMap> extends Omit<OverlayDefinitionMeta<Id, Data>, "id" | "instance" | "keepAlive">, HostableOverlay {
+    readonly id: Id;
+    readonly render?: () => Promise<RenderModule<OverlayRenderProps<Parsed>>>;
+    /** Imperative opener: `const open = def.useSummon(); open({ data })` → handle. */
+    useSummon(): OverlayOpener<Data, Events>;
+    /** Declarative form: opens on mount, closes on unmount, re-opens when its data changes. */
+    readonly Controller: (props: OverlayControllerProps<Data, Events>) => null;
+    useIsOpen(instanceId?: string): boolean;
+    /** `const close = def.useClose(); close(instanceId?)`. */
+    useClose(): (instanceId?: string) => void;
+    /** Inside the render tree: emit a declared event to the opener's handlers. */
+    useEmit(): OverlayEmitter<Events>;
+}
+/**
+ * Declare an overlay once. Curried so `Data` (and `Events`) are named while the id and the
+ * parsed-data type are inferred:
+ *
+ *   export const notesWindow = defineOverlay<NotesWindowData>()({
+ *     id: "notesWindow", label: "Notes", render: () => import("./notesWindow.render"),
+ *   });
+ */
+declare function defineOverlay<Data extends object = Record<string, never>, Events extends OverlayEventMap = Record<never, never>>(): <const Id extends string, Parsed = OverlayRawData>(spec: OverlaySpec<Id, Data, Parsed>) => OverlayDefinition<Id, Data, Parsed, Events>;
+
+declare function newInstanceId(overlayId: string): string;
+declare function dispatchOpen(dispatch: SummonReactDispatch, overlayId: string, instanceId: string, data: unknown): void;
+declare function dispatchClose(dispatch: SummonReactDispatch, overlayId: string, instanceId?: string): void;
+
+interface OverlayInstanceContextValue {
+    readonly overlayId: string;
+    readonly instanceId: string;
+    readonly instanceKey: InstanceKey;
+    readonly close: () => void;
+    readonly hidden: boolean;
+    /** The open data as it arrived (pre-parse); event emitters read their channel id from it. */
+    readonly rawData: OverlayRawData;
+}
+declare const OverlayInstanceContext: react.Context<OverlayInstanceContextValue | null>;
+/** The open instance this component renders inside. Throws outside an overlay. */
+declare function useOverlayInstance(): OverlayInstanceContextValue;
+/** Same as `useOverlayInstance`, but `null` outside an overlay. */
+declare function useOptionalOverlayInstance(): OverlayInstanceContextValue | null;
+
+type Emitter = (channelId: string, type: string, payload: unknown) => void;
+/** The react section installs the synchronous emitter (it holds handles statically). */
+declare function registerOverlayEmitter(emit: Emitter): void;
+declare function emitOverlayEventLight(channelId: string, type: string, payload: unknown): void;
+
+export { CALLBACK_GROUP_KEY, type HostableOverlay, type OverlayControllerProps, type OverlayDefinition, type OverlayEmitter, type OverlayErrorExtrasContext, type OverlayEventMap, type OverlayHandle, type OverlayHandlers, OverlayInstanceContext, type OverlayInstanceContextValue, type OverlayOpenOptions, type OverlayOpener, type OverlayRenderContext, type OverlaySpec, type SummonHostConfig, type SummonHostWindows, SummonPortsContext, type SummonReactDispatch, type SummonReactStore, SummonRoot, type SummonRootProps, SummonStoreContext, configureSummonHost, defineOverlay, dispatchClose, dispatchOpen, emitOverlayEventLight, getSummonHostConfig, getSummonHostPorts, getSummonHostVersion, newInstanceId, registerOverlayEmitter, useOptionalOverlayInstance, useOptionalSummonPorts, useOptionalSummonStore, useOverlayInstance, useSummonDispatch, useSummonPorts, useSummonSelector, useSummonStore };