@ai-matrx/summon 0.0.0 → 0.1.0

package/dist/window-host.d.ts

@@ -0,0 +1,72 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+
+interface WindowSelectionSurfaceProps {
+    readonly children: ReactNode;
+}
+interface WindowConfig {
+    /**
+     * Visible elements matching this selector own the Escape key: a window with `closeOnEscape`
+     * yields to them (menus, popovers, listboxes and open dialogs always do). Default
+     * `[data-overlay-escape-yield]` — mark any host surface that must take Escape first.
+     */
+    readonly escapeYieldSelector: string;
+    /** Top offset of a phone fullscreen window (below the host's header). Default `var(--header-height, 0px)`. */
+    readonly mobileTopOffset: string;
+    /**
+     * Wraps every window body (desktop, popped out, and all three phone presentations). Default:
+     * passthrough. AI Matrx injects its selection toolbar + right-click menu here.
+     */
+    readonly selectionSurface: ComponentType<WindowSelectionSurfaceProps>;
+}
+declare const DEFAULT_ESCAPE_YIELD_SELECTOR = "[data-overlay-escape-yield]";
+declare const DEFAULT_MOBILE_TOP_OFFSET = "var(--header-height, 0px)";
+declare const DEFAULT_WINDOW_CONFIG: WindowConfig;
+interface WindowsProviderProps extends Partial<WindowConfig> {
+    readonly children?: ReactNode;
+}
+declare function WindowsProvider({ escapeYieldSelector, mobileTopOffset, selectionSurface, children }: WindowsProviderProps): react.JSX.Element;
+declare function useWindowConfig(): WindowConfig;
+/** The configured selection surface, as a component. */
+declare function WindowSelectionSurface({ children }: WindowSelectionSurfaceProps): react.JSX.Element;
+
+declare function WindowTraySync(): null;
+
+/**
+ * Tray previews — overlay id → a semantic minimized preview and/or a custom snapshot capture.
+ *
+ * The host registers its previews once (AI Matrx keeps its own preview components in the app):
+ *
+ *   registerTrayPreview("notesWindow", NotesTrayPreview);
+ *   registerTrayPreview("canvasWindow", { captureTraySnapshot: captureCanvas });
+ *
+ * A window with a preview component skips snapshot capture entirely (cheaper, higher fidelity).
+ * A window with neither gets the default capture (`defaultTraySnapshotCapture`, html-to-image when
+ * the host installed it). State lives in a global slot (kit globalSlot, D9).
+ */
+
+interface TrayPreviewContext {
+    /** The window's allowlisted semantic data (open data merged with what `onCollectData` returned). */
+    readonly data: Readonly<Record<string, unknown>>;
+    /** Stable overlay id (the registry key). */
+    readonly overlayId: string;
+    /** Instance id — `"default"` for singleton windows. */
+    readonly instanceId: string;
+    /** The display title. */
+    readonly title: string;
+}
+type TraySnapshotCapture = (bodyEl: HTMLElement) => Promise<Blob | null>;
+interface TrayPreviewEntry {
+    readonly Preview?: ComponentType<TrayPreviewContext>;
+    readonly captureTraySnapshot?: TraySnapshotCapture;
+}
+/**
+ * Register the minimized preview for an overlay (or any window id). Pass a component, or an entry
+ * with `Preview` and/or `captureTraySnapshot`. Re-registering replaces. Returns an unregister.
+ */
+declare function registerTrayPreview(overlayId: string, preview: ComponentType<TrayPreviewContext> | TrayPreviewEntry): () => void;
+declare function getTrayPreviewEntry(overlayId: string): TrayPreviewEntry;
+/** Test-only. */
+declare function resetTrayPreviews(): void;
+
+export { DEFAULT_ESCAPE_YIELD_SELECTOR, DEFAULT_MOBILE_TOP_OFFSET, DEFAULT_WINDOW_CONFIG, type TrayPreviewContext, type TrayPreviewEntry, type TraySnapshotCapture, type WindowConfig, WindowSelectionSurface, type WindowSelectionSurfaceProps, WindowTraySync, WindowsProvider, type WindowsProviderProps, getTrayPreviewEntry, registerTrayPreview, resetTrayPreviews, useWindowConfig };

package/dist/window-host.js

@@ -0,0 +1,104 @@
+"use client";
+
+// src/window/config.tsx
+import { createContext, useContext, useMemo } from "react";
+import { Fragment, jsx } from "react/jsx-runtime";
+function PassthroughSurface({ children }) {
+  return /* @__PURE__ */ jsx(Fragment, { children });
+}
+var DEFAULT_ESCAPE_YIELD_SELECTOR = "[data-overlay-escape-yield]";
+var DEFAULT_MOBILE_TOP_OFFSET = "var(--header-height, 0px)";
+var DEFAULT_WINDOW_CONFIG = {
+  escapeYieldSelector: DEFAULT_ESCAPE_YIELD_SELECTOR,
+  mobileTopOffset: DEFAULT_MOBILE_TOP_OFFSET,
+  selectionSurface: PassthroughSurface
+};
+var WindowConfigContext = createContext(DEFAULT_WINDOW_CONFIG);
+WindowConfigContext.displayName = "WindowConfigContext";
+function WindowsProvider({ escapeYieldSelector, mobileTopOffset, selectionSurface, children }) {
+  const value = useMemo(
+    () => ({
+      escapeYieldSelector: escapeYieldSelector ?? DEFAULT_WINDOW_CONFIG.escapeYieldSelector,
+      mobileTopOffset: mobileTopOffset ?? DEFAULT_WINDOW_CONFIG.mobileTopOffset,
+      selectionSurface: selectionSurface ?? DEFAULT_WINDOW_CONFIG.selectionSurface
+    }),
+    [escapeYieldSelector, mobileTopOffset, selectionSurface]
+  );
+  return /* @__PURE__ */ jsx(WindowConfigContext.Provider, { value, children });
+}
+function useWindowConfig() {
+  return useContext(WindowConfigContext);
+}
+function WindowSelectionSurface({ children }) {
+  const Surface = useWindowConfig().selectionSurface;
+  return /* @__PURE__ */ jsx(Surface, { children });
+}
+
+// src/window/WindowTraySync.tsx
+import { useEffect } from "react";
+import { useSummonDispatch } from "@ai-matrx/summon/react";
+import {
+  recomputeTrayPositions,
+  clampAllWindowRects
+} from "@ai-matrx/summon";
+import { safeViewportDims } from "@ai-matrx/summon";
+var DEBOUNCE_MS = 500;
+function WindowTraySync() {
+  const dispatch = useSummonDispatch();
+  useEffect(() => {
+    let timer = null;
+    const syncWindowGeometry = () => {
+      const { vw, vh, degenerate } = safeViewportDims();
+      if (degenerate) return;
+      dispatch(
+        recomputeTrayPositions({ viewportWidth: vw, viewportHeight: vh })
+      );
+      dispatch(clampAllWindowRects({ viewportWidth: vw, viewportHeight: vh }));
+    };
+    syncWindowGeometry();
+    const handleResize = () => {
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        syncWindowGeometry();
+      }, DEBOUNCE_MS);
+    };
+    window.addEventListener("resize", handleResize, { passive: true });
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      if (timer !== null) clearTimeout(timer);
+    };
+  }, [dispatch]);
+  return null;
+}
+
+// src/window/tray/trayPreviewRegistry.ts
+import { globalSlot } from "@ai-matrx/kit/global-slot";
+var EMPTY = {};
+var registry = () => globalSlot("ai-matrx.summon.window.trayPreviews", () => /* @__PURE__ */ new Map());
+function registerTrayPreview(overlayId, preview) {
+  const entry = typeof preview === "function" ? { Preview: preview } : preview;
+  registry().set(overlayId, entry);
+  return () => {
+    if (registry().get(overlayId) === entry) registry().delete(overlayId);
+  };
+}
+function getTrayPreviewEntry(overlayId) {
+  return registry().get(overlayId) ?? EMPTY;
+}
+function resetTrayPreviews() {
+  registry().clear();
+}
+export {
+  DEFAULT_ESCAPE_YIELD_SELECTOR,
+  DEFAULT_MOBILE_TOP_OFFSET,
+  DEFAULT_WINDOW_CONFIG,
+  WindowSelectionSurface,
+  WindowTraySync,
+  WindowsProvider,
+  getTrayPreviewEntry,
+  registerTrayPreview,
+  resetTrayPreviews,
+  useWindowConfig
+};
+//# sourceMappingURL=window-host.js.map

package/dist/window-host.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/window/config.tsx","../src/window/WindowTraySync.tsx","../src/window/tray/trayPreviewRegistry.ts"],"sourcesContent":["\"use client\";\n\n/**\n * WindowsProvider — the window section's host options, read by every WindowPanel through context.\n * Everything has a working default, so no provider is needed at all; a host passes only what it\n * has (AI Matrx: its right-click selection menu and its header offset).\n */\nimport { createContext, useContext, useMemo, type ComponentType, type ReactNode } from \"react\";\n\nexport interface WindowSelectionSurfaceProps {\n  readonly children: ReactNode;\n}\n\nexport interface WindowConfig {\n  /**\n   * Visible elements matching this selector own the Escape key: a window with `closeOnEscape`\n   * yields to them (menus, popovers, listboxes and open dialogs always do). Default\n   * `[data-overlay-escape-yield]` — mark any host surface that must take Escape first.\n   */\n  readonly escapeYieldSelector: string;\n  /** Top offset of a phone fullscreen window (below the host's header). Default `var(--header-height, 0px)`. */\n  readonly mobileTopOffset: string;\n  /**\n   * Wraps every window body (desktop, popped out, and all three phone presentations). Default:\n   * passthrough. AI Matrx injects its selection toolbar + right-click menu here.\n   */\n  readonly selectionSurface: ComponentType<WindowSelectionSurfaceProps>;\n}\n\nfunction PassthroughSurface({ children }: WindowSelectionSurfaceProps) {\n  return <>{children}</>;\n}\n\nexport const DEFAULT_ESCAPE_YIELD_SELECTOR = \"[data-overlay-escape-yield]\";\nexport const DEFAULT_MOBILE_TOP_OFFSET = \"var(--header-height, 0px)\";\n\nexport const DEFAULT_WINDOW_CONFIG: WindowConfig = {\n  escapeYieldSelector: DEFAULT_ESCAPE_YIELD_SELECTOR,\n  mobileTopOffset: DEFAULT_MOBILE_TOP_OFFSET,\n  selectionSurface: PassthroughSurface,\n};\n\nconst WindowConfigContext = createContext<WindowConfig>(DEFAULT_WINDOW_CONFIG);\nWindowConfigContext.displayName = \"WindowConfigContext\";\n\nexport interface WindowsProviderProps extends Partial<WindowConfig> {\n  readonly children?: ReactNode;\n}\n\nexport function WindowsProvider({ escapeYieldSelector, mobileTopOffset, selectionSurface, children }: WindowsProviderProps) {\n  const value = useMemo<WindowConfig>(\n    () => ({\n      escapeYieldSelector: escapeYieldSelector ?? DEFAULT_WINDOW_CONFIG.escapeYieldSelector,\n      mobileTopOffset: mobileTopOffset ?? DEFAULT_WINDOW_CONFIG.mobileTopOffset,\n      selectionSurface: selectionSurface ?? DEFAULT_WINDOW_CONFIG.selectionSurface,\n    }),\n    [escapeYieldSelector, mobileTopOffset, selectionSurface],\n  );\n  return <WindowConfigContext.Provider value={value}>{children}</WindowConfigContext.Provider>;\n}\n\nexport function useWindowConfig(): WindowConfig {\n  return useContext(WindowConfigContext);\n}\n\n/** The configured selection surface, as a component. */\nexport function WindowSelectionSurface({ children }: WindowSelectionSurfaceProps) {\n  const Surface = useWindowConfig().selectionSurface;\n  return <Surface>{children}</Surface>;\n}\n","\"use client\";\n\n/**\n * WindowTraySync\n *\n * Mounts ONCE in the root layout. Attaches a single debounced resize listener\n * that:\n *  1. Recomputes the positions of all minimized windows (tray slots can change\n *     when chips-per-row shifts on viewport resize).\n *  2. Clamps every docked windowed window into the new viewport so windows\n *     positioned for a larger screen stay reachable after a downsize.\n *\n * Zero re-renders — fires and forgets.\n *\n * Debounce: 500ms — a continuous window-drag generates exactly one dispatch\n * when the user stops moving. Short bursts (e.g. snapping) are ignored.\n *\n * Usage (in both authenticated and SSR root layouts):\n *   <WindowTraySync />\n */\n\nimport { useEffect } from \"react\";\nimport { useSummonDispatch } from \"@ai-matrx/summon/react\";\nimport {\n  recomputeTrayPositions,\n  clampAllWindowRects,\n} from \"@ai-matrx/summon\";\nimport { safeViewportDims } from \"@ai-matrx/summon\";\n\nconst DEBOUNCE_MS = 500;\n\nexport function WindowTraySync() {\n  const dispatch = useSummonDispatch();\n\n  useEffect(() => {\n    let timer: ReturnType<typeof setTimeout> | null = null;\n\n    const syncWindowGeometry = () => {\n      // A resize that measures 0×0 is a hidden/undisplayed tab or a\n      // display:none ancestor, never a real screen. Bail WITHOUT dispatching:\n      // reacting to it would rewrite every window rect and every tray slot\n      // against invented dimensions, and the next real measurement would\n      // then have to undo it. No measurement, no write.\n      const { vw, vh, degenerate } = safeViewportDims();\n      if (degenerate) return;\n      dispatch(\n        recomputeTrayPositions({ viewportWidth: vw, viewportHeight: vh }),\n      );\n      dispatch(clampAllWindowRects({ viewportWidth: vw, viewportHeight: vh }));\n    };\n\n    // This island may load after the viewport already changed. Synchronising\n    // once on mount closes that event-listener gap for persisted windows.\n    syncWindowGeometry();\n\n    const handleResize = () => {\n      if (timer !== null) clearTimeout(timer);\n      timer = setTimeout(() => {\n        timer = null;\n        syncWindowGeometry();\n      }, DEBOUNCE_MS);\n    };\n\n    window.addEventListener(\"resize\", handleResize, { passive: true });\n\n    return () => {\n      window.removeEventListener(\"resize\", handleResize);\n      if (timer !== null) clearTimeout(timer);\n    };\n  }, [dispatch]);\n\n  return null;\n}\n\nexport default WindowTraySync;\n","/**\n * Tray previews — overlay id → a semantic minimized preview and/or a custom snapshot capture.\n *\n * The host registers its previews once (AI Matrx keeps its own preview components in the app):\n *\n *   registerTrayPreview(\"notesWindow\", NotesTrayPreview);\n *   registerTrayPreview(\"canvasWindow\", { captureTraySnapshot: captureCanvas });\n *\n * A window with a preview component skips snapshot capture entirely (cheaper, higher fidelity).\n * A window with neither gets the default capture (`defaultTraySnapshotCapture`, html-to-image when\n * the host installed it). State lives in a global slot (kit globalSlot, D9).\n */\nimport type { ComponentType } from \"react\";\nimport { globalSlot } from \"@ai-matrx/kit/global-slot\";\n\nexport interface TrayPreviewContext {\n  /** The window's allowlisted semantic data (open data merged with what `onCollectData` returned). */\n  readonly data: Readonly<Record<string, unknown>>;\n  /** Stable overlay id (the registry key). */\n  readonly overlayId: string;\n  /** Instance id — `\"default\"` for singleton windows. */\n  readonly instanceId: string;\n  /** The display title. */\n  readonly title: string;\n}\n\nexport type TraySnapshotCapture = (bodyEl: HTMLElement) => Promise<Blob | null>;\n\nexport interface TrayPreviewEntry {\n  readonly Preview?: ComponentType<TrayPreviewContext>;\n  readonly captureTraySnapshot?: TraySnapshotCapture;\n}\n\nconst EMPTY: TrayPreviewEntry = {};\n\nconst registry = (): Map<string, TrayPreviewEntry> =>\n  globalSlot<Map<string, TrayPreviewEntry>>(\"ai-matrx.summon.window.trayPreviews\", () => new Map());\n\n/**\n * Register the minimized preview for an overlay (or any window id). Pass a component, or an entry\n * with `Preview` and/or `captureTraySnapshot`. Re-registering replaces. Returns an unregister.\n */\nexport function registerTrayPreview(\n  overlayId: string,\n  preview: ComponentType<TrayPreviewContext> | TrayPreviewEntry,\n): () => void {\n  const entry: TrayPreviewEntry = typeof preview === \"function\" ? { Preview: preview } : preview;\n  registry().set(overlayId, entry);\n  return () => {\n    if (registry().get(overlayId) === entry) registry().delete(overlayId);\n  };\n}\n\nexport function getTrayPreviewEntry(overlayId: string): TrayPreviewEntry {\n  return registry().get(overlayId) ?? EMPTY;\n}\n\n/** Test-only. */\nexport function resetTrayPreviews(): void {\n  registry().clear();\n}\n"],"mappings":";;;AAOA,SAAS,eAAe,YAAY,eAAmD;AAuB9E;AADT,SAAS,mBAAmB,EAAE,SAAS,GAAgC;AACrE,SAAO,gCAAG,UAAS;AACrB;AAEO,IAAM,gCAAgC;AACtC,IAAM,4BAA4B;AAElC,IAAM,wBAAsC;AAAA,EACjD,qBAAqB;AAAA,EACrB,iBAAiB;AAAA,EACjB,kBAAkB;AACpB;AAEA,IAAM,sBAAsB,cAA4B,qBAAqB;AAC7E,oBAAoB,cAAc;AAM3B,SAAS,gBAAgB,EAAE,qBAAqB,iBAAiB,kBAAkB,SAAS,GAAyB;AAC1H,QAAM,QAAQ;AAAA,IACZ,OAAO;AAAA,MACL,qBAAqB,uBAAuB,sBAAsB;AAAA,MAClE,iBAAiB,mBAAmB,sBAAsB;AAAA,MAC1D,kBAAkB,oBAAoB,sBAAsB;AAAA,IAC9D;AAAA,IACA,CAAC,qBAAqB,iBAAiB,gBAAgB;AAAA,EACzD;AACA,SAAO,oBAAC,oBAAoB,UAApB,EAA6B,OAAe,UAAS;AAC/D;AAEO,SAAS,kBAAgC;AAC9C,SAAO,WAAW,mBAAmB;AACvC;AAGO,SAAS,uBAAuB,EAAE,SAAS,GAAgC;AAChF,QAAM,UAAU,gBAAgB,EAAE;AAClC,SAAO,oBAAC,WAAS,UAAS;AAC5B;;;AChDA,SAAS,iBAAiB;AAC1B,SAAS,yBAAyB;AAClC;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP,SAAS,wBAAwB;AAEjC,IAAM,cAAc;AAEb,SAAS,iBAAiB;AAC/B,QAAM,WAAW,kBAAkB;AAEnC,YAAU,MAAM;AACd,QAAI,QAA8C;AAElD,UAAM,qBAAqB,MAAM;AAM/B,YAAM,EAAE,IAAI,IAAI,WAAW,IAAI,iBAAiB;AAChD,UAAI,WAAY;AAChB;AAAA,QACE,uBAAuB,EAAE,eAAe,IAAI,gBAAgB,GAAG,CAAC;AAAA,MAClE;AACA,eAAS,oBAAoB,EAAE,eAAe,IAAI,gBAAgB,GAAG,CAAC,CAAC;AAAA,IACzE;AAIA,uBAAmB;AAEnB,UAAM,eAAe,MAAM;AACzB,UAAI,UAAU,KAAM,cAAa,KAAK;AACtC,cAAQ,WAAW,MAAM;AACvB,gBAAQ;AACR,2BAAmB;AAAA,MACrB,GAAG,WAAW;AAAA,IAChB;AAEA,WAAO,iBAAiB,UAAU,cAAc,EAAE,SAAS,KAAK,CAAC;AAEjE,WAAO,MAAM;AACX,aAAO,oBAAoB,UAAU,YAAY;AACjD,UAAI,UAAU,KAAM,cAAa,KAAK;AAAA,IACxC;AAAA,EACF,GAAG,CAAC,QAAQ,CAAC;AAEb,SAAO;AACT;;;AC3DA,SAAS,kBAAkB;AAoB3B,IAAM,QAA0B,CAAC;AAEjC,IAAM,WAAW,MACf,WAA0C,uCAAuC,MAAM,oBAAI,IAAI,CAAC;AAM3F,SAAS,oBACd,WACA,SACY;AACZ,QAAM,QAA0B,OAAO,YAAY,aAAa,EAAE,SAAS,QAAQ,IAAI;AACvF,WAAS,EAAE,IAAI,WAAW,KAAK;AAC/B,SAAO,MAAM;AACX,QAAI,SAAS,EAAE,IAAI,SAAS,MAAM,MAAO,UAAS,EAAE,OAAO,SAAS;AAAA,EACtE;AACF;AAEO,SAAS,oBAAoB,WAAqC;AACvE,SAAO,SAAS,EAAE,IAAI,SAAS,KAAK;AACtC;AAGO,SAAS,oBAA0B;AACxC,WAAS,EAAE,MAAM;AACnB;","names":[]}