@proteos/component-sdk 0.41.1 → 0.42.1

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/context.tsx","../src/hooks.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type {\n  AccountClient,\n  AgentClient,\n  ConversationClient,\n  DataClient,\n  FunctionsClient,\n  KnowledgeClient,\n  MetaClient,\n  StorageClient,\n} from '@proteos/sdk'\nimport { createContext, type ReactNode, useMemo } from 'react'\n\nimport {\n  type Envelope,\n  MESSAGE_SOURCE,\n  type NavigateMessage,\n  type OpenPeekMessage,\n  type PageContext,\n} from './protocol'\n\n/** Options for {@link RuntimeContextValue.navigate}. */\nexport interface NavigateOptions {\n  /** Open the target in a peek (slide-over) panel instead of full-page. */\n  peek?: boolean\n}\n\n/**\n * The authenticated `@proteos/sdk` clients the runtime injects. Same instances\n * the host app uses — pre-wired with a refreshing bearer token, so a component\n * never touches auth headers.\n */\nexport interface ComponentSdk {\n  account: AccountClient\n  agents: AgentClient\n  /**\n   * Conversations, messages, contacts, connections (conversation-service) —\n   * e.g. the DraftMessageComposer review surface. Plural per the platform's\n   * resource-naming rule; the web app's own `useSdk().conversation` predates\n   * it (documented asymmetry).\n   */\n  conversations: ConversationClient\n  data: DataClient\n  functions: FunctionsClient\n  knowledge: KnowledgeClient\n  meta: MetaClient\n  storage: StorageClient\n}\n\n/**\n * The raw runtime payload the shell hands a component at INIT. The shell builds\n * this; component authors read it through the hooks.\n */\nexport interface RuntimeValue {\n  /**\n   * The injected sdk clients. On an authenticated page these are the full,\n   * bearer-wired clients. On a PUBLIC page (`isPublic: true`) only\n   * `functions.actions.invokePublic` reaches the platform — every other\n   * client throws on use (there is no token, and the server rejects\n   * unauthenticated calls anyway).\n   */\n  sdk: ComponentSdk\n  /** Liquid-resolved props (a snapshot — not a live binding). */\n  props: Record<string, unknown>\n  /** Page context snapshot: the host record, entity, and URL params. */\n  pageCtx: PageContext\n  /** API origin SDK calls + asset URLs resolve against. */\n  apiBaseUrl: string\n  /** Current bearer token getter (escape hatch for raw fetches). Returns ''\n   *  on public pages. */\n  getToken: () => string\n  /** True when rendering on an unauthenticated public page. */\n  isPublic?: boolean\n  /** Org id, set in public mode (public API routes carry it in the path). */\n  orgId?: string\n}\n\n/** Runtime value plus the derived helpers the hooks expose. */\nexport interface RuntimeContextValue extends RuntimeValue {\n  /** Navigate the host SPA to an in-app path (posts a NAVIGATE message), or\n   *  open it in a peek panel with `{ peek: true }` (posts OPEN_PEEK). */\n  navigate: (to: string, options?: NavigateOptions) => void\n}\n\nexport const RuntimeContext = createContext<RuntimeContextValue | null>(null)\n\n/** Post a NAVIGATE envelope to the host. The host only honours relative,\n *  in-app targets (it ignores absolute/external URLs). */\nfunction postNavigate(to: string): void {\n  const envelope: Envelope<NavigateMessage> = { source: MESSAGE_SOURCE, type: 'NAVIGATE', to }\n  window.parent?.postMessage(envelope, '*')\n}\n\n/** Post an OPEN_PEEK envelope to the host — open the in-app path in a peek\n *  panel. Same relative-path contract as {@link postNavigate}. */\nfunction postOpenPeek(to: string): void {\n  const envelope: Envelope<OpenPeekMessage> = { source: MESSAGE_SOURCE, type: 'OPEN_PEEK', to }\n  window.parent?.postMessage(envelope, '*')\n}\n\n/** Navigate full-page (default) or into a peek panel (`{ peek: true }`). */\nfunction navigate(to: string, options?: NavigateOptions): void {\n  if (options?.peek) postOpenPeek(to)\n  else postNavigate(to)\n}\n\n/**\n * Provides the runtime value + derived helpers to a component subtree. Mounted\n * by the component-runtime shell around the loaded component — authors never\n * render this themselves. Lives in `@proteos/component-sdk` (a shared,\n * import-mapped singleton) so the context the shell provides is the very same\n * context the component's hooks read, across the bundle boundary.\n */\nexport function RuntimeProvider({ value, children }: { value: RuntimeValue; children: ReactNode }) {\n  // The shell builds `value` once at INIT (a stable state object — clients,\n  // props and pageCtx are all set once), so memoizing on its identity recreates\n  // the context only when the runtime genuinely re-inits.\n  const ctx = useMemo<RuntimeContextValue>(() => ({ ...value, navigate }), [value])\n  return <RuntimeContext.Provider value={ctx}>{children}</RuntimeContext.Provider>\n}\n","import { useContext, useEffect, useState } from 'react'\n\nimport {\n  type ComponentSdk,\n  type NavigateOptions,\n  RuntimeContext,\n  type RuntimeContextValue,\n} from './context'\nimport type { PageContext } from './protocol'\n\n/**\n * Low-level escape hatch: the whole runtime context (sdk, props, pageCtx,\n * apiBaseUrl, getToken, navigate). Prefer the focused hooks below. Throws a\n * clear error if used outside the component runtime.\n */\nexport function useRuntime(): RuntimeContextValue {\n  const ctx = useContext(RuntimeContext)\n  if (!ctx) {\n    throw new Error(\n      '@proteos/component-sdk: hooks must run inside the Proteos component runtime. ' +\n        'This usually means the component is rendered outside its iframe, or a ' +\n        'second copy of @proteos/component-sdk was bundled instead of using the ' +\n        'runtime-provided one (keep it external).',\n    )\n  }\n  return ctx\n}\n\n/** The authenticated SDK clients (account / agents / conversations / data / functions / knowledge / meta / storage). */\nexport function useSdk(): ComponentSdk {\n  return useRuntime().sdk\n}\n\n/** The component's Liquid-resolved props (a snapshot, not a live binding). */\nexport function useProps<T extends Record<string, unknown> = Record<string, unknown>>(): T {\n  return useRuntime().props as T\n}\n\n/**\n * The full page context: host `record`, `entity`, and URL `params`. The\n * `record` is a snapshot taken at mount (`undefined` on record-less platform\n * pages) — fetch via `useSdk().data` for anything that must stay fresh.\n */\nexport function usePageContext(): PageContext {\n  return useRuntime().pageCtx\n}\n\n/**\n * Navigate the host SPA to an in-app path, e.g.\n * `navigate('/org/acme/record/task/123')`. The host ignores absolute/external\n * URLs. Build org/app-prefixed paths with `useHostLocation().appBasePath`.\n *\n * Pass `{ peek: true }` to open the path in a peek (slide-over) panel instead\n * of full-page navigation — e.g. `navigate(path, { peek: true })`. The host\n * peeks what it can (today: platform pages) and falls back to full navigation.\n */\nexport function useNavigate(): (to: string, options?: NavigateOptions) => void {\n  return useRuntime().navigate\n}\n\n/** The API origin SDK calls resolve against (for building raw asset URLs). */\nexport function useApiBaseUrl(): string {\n  return useRuntime().apiBaseUrl\n}\n\n/**\n * A getter for the current bearer token. Returns a function (not the token)\n * because the token is refreshed in place — read it at call time for a raw\n * `fetch`. Most components never need this; prefer `useSdk()`.\n */\nexport function useAuthToken(): () => string {\n  return useRuntime().getToken\n}\n\nexport interface HostLocation {\n  /** The host tab's pathname (same-origin read), or null if unavailable. */\n  pathname: string | null\n  /** The org id parsed from `/org/<orgId>/…`, or null. */\n  orgId: string | null\n  /** The `/org/<orgId>/app/<appId>` prefix, or null when not on an app page. */\n  appBasePath: string | null\n}\n\nfunction readHostLocation(): HostLocation {\n  const empty: HostLocation = { pathname: null, orgId: null, appBasePath: null }\n  try {\n    const parentWindow = window.parent\n    if (!parentWindow || parentWindow === window) return empty\n    const pathname = parentWindow.location.pathname\n    const appMatch = pathname.match(/^\\/org\\/[^/]+\\/app\\/[^/]+/)\n    const orgMatch = pathname.match(/^\\/org\\/([^/]+)\\//)\n    return {\n      pathname,\n      orgId: orgMatch ? (orgMatch[1] ?? null) : null,\n      appBasePath: appMatch ? appMatch[0] : null,\n    }\n  } catch {\n    // Cross-origin (untrusted-component future) or detached — fall back to null.\n    return empty\n  }\n}\n\n/**\n * Read the host tab's location (same-origin) — the org id and `/org/.../app/...`\n * prefix needed to build navigation targets on platform pages. Read once on\n * mount (the iframe re-inits when the host route changes).\n */\nexport function useHostLocation(): HostLocation {\n  const [loc] = useState(readHostLocation)\n  return loc\n}\n\nexport interface FillViewportOptions {\n  /** Gap left below the component (px). Default 24. */\n  bottomMargin?: number\n  /** Floor for the computed height (px). Default 320. */\n  minHeight?: number\n}\n\n/**\n * Compute a \"fill the rest of the viewport\" height for full-bleed layouts\n * (boards, canvases). The runtime auto-sizes the iframe to its content, so a\n * component can't use its own `vh` units (circular). The iframe is same-origin,\n * so this measures the parent viewport minus the iframe's offset instead.\n * Returns `null` when it can't measure (fall back to natural height).\n */\nexport function useFillViewportHeight(options: FillViewportOptions = {}): number | null {\n  const { bottomMargin = 24, minHeight = 320 } = options\n  const [height, setHeight] = useState<number | null>(null)\n\n  useEffect(() => {\n    function compute(): void {\n      try {\n        const frame = window.frameElement\n        const parentWindow = window.parent\n        if (!frame || !parentWindow || parentWindow === window) return\n        const available =\n          parentWindow.innerHeight - frame.getBoundingClientRect().top - bottomMargin\n        setHeight(Math.max(available, minHeight))\n      } catch {\n        setHeight(null) // cross-origin or detached — fall back to natural height\n      }\n    }\n    compute()\n    try {\n      window.parent.addEventListener('resize', compute)\n      return () => window.parent.removeEventListener('resize', compute)\n    } catch {\n      return\n    }\n  }, [bottomMargin, minHeight])\n\n  return height\n}\n"]}
+{"version":3,"sources":["../src/context.tsx","../src/hooks.ts"],"names":["useMemo"],"mappings":";;;;;AAuHO,IAAM,cAAA,GAAiB,cAA0C,IAAI,CAAA;AAI5E,SAAS,aAAa,EAAA,EAAkB;AACtC,EAAA,MAAM,WAAsC,EAAE,MAAA,EAAQ,cAAA,EAAgB,IAAA,EAAM,YAAY,EAAA,EAAG;AAC3F,EAAA,MAAA,CAAO,MAAA,EAAQ,WAAA,CAAY,QAAA,EAAU,GAAG,CAAA;AAC1C;AAIA,SAAS,aAAa,EAAA,EAAkB;AACtC,EAAA,MAAM,WAAsC,EAAE,MAAA,EAAQ,cAAA,EAAgB,IAAA,EAAM,aAAa,EAAA,EAAG;AAC5F,EAAA,MAAA,CAAO,MAAA,EAAQ,WAAA,CAAY,QAAA,EAAU,GAAG,CAAA;AAC1C;AAGA,SAAS,QAAA,CAAS,IAAY,OAAA,EAAiC;AAC7D,EAAA,IAAI,OAAA,EAAS,IAAA,EAAM,YAAA,CAAa,EAAE,CAAA;AAAA,oBAChB,EAAE,CAAA;AACtB;AAMA,IAAM,aAAA,uBAAoB,GAAA,EAAuC;AACjE,IAAI,qBAAA,GAAwB,KAAA;AAE5B,SAAS,mBAAA,GAA4B;AACnC,EAAA,IAAI,qBAAA,EAAuB;AAC3B,EAAA,qBAAA,GAAwB,IAAA;AACxB,EAAA,MAAA,CAAO,gBAAA,CAAiB,SAAA,EAAW,CAAC,KAAA,KAAwB;AAC1D,IAAA,MAAM,OAAgB,KAAA,CAAM,IAAA;AAC5B,IAAA,IAAI,CAAC,aAAA,CAAc,IAAI,CAAA,IAAK,IAAA,CAAK,SAAS,cAAA,EAAgB;AAC1D,IAAA,MAAM,OAAA,GAAU,aAAA,CAAc,GAAA,CAAI,IAAA,CAAK,SAAS,CAAA;AAEhD,IAAA,IAAI,CAAC,OAAA,EAAS;AACd,IAAA,aAAA,CAAc,MAAA,CAAO,KAAK,SAAS,CAAA;AACnC,IAAA,OAAA,CAAQ,KAAK,MAAM,CAAA;AAAA,EACrB,CAAC,CAAA;AACH;AAEA,SAAS,YAAA,GAAuB;AAC9B,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,IAAe,OAAO,MAAA,CAAO,eAAe,UAAA,EAAY;AAC5E,IAAA,OAAO,OAAO,UAAA,EAAW;AAAA,EAC3B;AACA,EAAA,OAAO,SAAS,IAAA,CAAK,GAAA,EAAI,CAAE,QAAA,CAAS,EAAE,CAAC,CAAA,CAAA,EAAI,IAAA,CAAK,MAAA,GAAS,QAAA,CAAS,EAAE,EAAE,KAAA,CAAM,CAAA,EAAG,EAAE,CAAC,CAAA,CAAA;AACpF;AAGA,SAAS,SAAA,CACP,aAAA,EACA,KAAA,EACA,OAAA,EACkB;AAClB,EAAA,mBAAA,EAAoB;AACpB,EAAA,MAAM,YAAY,YAAA,EAAa;AAC/B,EAAA,MAAM,QAAA,GAAuC;AAAA,IAC3C,MAAA,EAAQ,cAAA;AAAA,IACR,IAAA,EAAM,YAAA;AAAA,IACN,SAAA;AAAA,IACA,aAAA;AAAA,IACA,GAAI,KAAA,KAAU,MAAA,GAAY,EAAE,KAAA,KAAU,EAAC;AAAA,IACvC,GAAI,SAAS,KAAA,KAAU,MAAA,GAAY,EAAE,KAAA,EAAO,OAAA,CAAQ,KAAA,EAAM,GAAI;AAAC,GACjE;AACA,EAAA,OAAO,IAAI,OAAA,CAAiB,CAAC,OAAA,KAAY;AACvC,IAAA,aAAA,CAAc,GAAA,CAAI,WAAW,OAAO,CAAA;AACpC,IAAA,MAAA,CAAO,MAAA,EAAQ,WAAA,CAAY,QAAA,EAAU,GAAG,CAAA;AAAA,EAC1C,CAAC,CAAA;AACH;AAGO,SAAS,eAAA,CAAgB,WAAmB,MAAA,EAAwB;AACzE,EAAA,MAAM,QAAA,GAAyC;AAAA,IAC7C,MAAA,EAAQ,cAAA;AAAA,IACR,IAAA,EAAM,cAAA;AAAA,IACN,SAAA;AAAA,IACA,GAAI,MAAA,KAAW,MAAA,GAAY,EAAE,MAAA,KAAW;AAAC,GAC3C;AACA,EAAA,MAAA,CAAO,MAAA,EAAQ,WAAA,CAAY,QAAA,EAAU,GAAG,CAAA;AAC1C;AASO,SAAS,eAAA,CAAgB,EAAE,KAAA,EAAO,QAAA,EAAS,EAAiD;AAIjG,EAAA,MAAM,GAAA,GAAM,OAAA,CAA6B,OAAO,EAAE,GAAG,KAAA,EAAO,QAAA,EAAU,SAAA,EAAU,CAAA,EAAI,CAAC,KAAK,CAAC,CAAA;AAC3F,EAAA,2BAAQ,cAAA,CAAe,QAAA,EAAf,EAAwB,KAAA,EAAO,KAAM,QAAA,EAAS,CAAA;AACxD;ACrMO,SAAS,UAAA,GAAkC;AAChD,EAAA,MAAM,GAAA,GAAM,WAAW,cAAc,CAAA;AACrC,EAAA,IAAI,CAAC,GAAA,EAAK;AACR,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAIF;AAAA,EACF;AACA,EAAA,OAAO,GAAA;AACT;AAGO,SAAS,MAAA,GAAuB;AACrC,EAAA,OAAO,YAAW,CAAE,GAAA;AACtB;AAGO,SAAS,QAAA,GAA2E;AACzF,EAAA,OAAO,YAAW,CAAE,KAAA;AACtB;AAOO,SAAS,cAAA,GAA8B;AAC5C,EAAA,OAAO,YAAW,CAAE,OAAA;AACtB;AAWO,SAAS,WAAA,GAA+D;AAC7E,EAAA,OAAO,YAAW,CAAE,QAAA;AACtB;AAGO,SAAS,aAAA,GAAwB;AACtC,EAAA,OAAO,YAAW,CAAE,UAAA;AACtB;AAEA,IAAM,YAAA,GAAkC;AAAA,EACtC,QAAQ,MAAM;AACZ,IAAA,OAAA,CAAQ,IAAA;AAAA,MACN;AAAA,KAEF;AAAA,EACF,CAAA;AAAA,EACA,UAAU,MAAM;AAAA,EAAC,CAAA;AAAA,EACjB,YAAY,MAAM;AACpB,CAAA;AAaO,SAAS,mBAAA,GAAyC;AACvD,EAAA,OAAO,UAAA,GAAa,OAAA,IAAW,YAAA;AACjC;AAgBO,SAAS,iBAAA,GAIM;AACpB,EAAA,OAAO,YAAW,CAAE,SAAA;AACtB;AAgBO,SAAS,YAAA,GAA0B;AACxC,EAAA,MAAM,SAAA,GAAY,YAAW,CAAE,cAAA;AAC/B,EAAA,MAAM,KAAA,GAAQ,WAAA;AAAA,IACZ,CAAC,MAAA,KAAqB;AACpB,MAAA,IAAI,cAAc,MAAA,EAAW;AAC7B,MAAA,eAAA,CAAgB,WAAW,MAAM,CAAA;AAAA,IACnC,CAAA;AAAA,IACA,CAAC,SAAS;AAAA,GACZ;AACA,EAAA,OAAOA,OAAAA,CAAQ,OAAO,EAAE,SAAA,EAAW,SAAA,KAAc,MAAA,EAAW,KAAA,EAAM,CAAA,EAAI,CAAC,SAAA,EAAW,KAAK,CAAC,CAAA;AAC1F;AAOO,SAAS,YAAA,GAA6B;AAC3C,EAAA,OAAO,YAAW,CAAE,QAAA;AACtB;AAWA,SAAS,gBAAA,GAAiC;AACxC,EAAA,MAAM,QAAsB,EAAE,QAAA,EAAU,MAAM,KAAA,EAAO,IAAA,EAAM,aAAa,IAAA,EAAK;AAC7E,EAAA,IAAI;AACF,IAAA,MAAM,eAAe,MAAA,CAAO,MAAA;AAC5B,IAAA,IAAI,CAAC,YAAA,IAAgB,YAAA,KAAiB,MAAA,EAAQ,OAAO,KAAA;AACrD,IAAA,MAAM,QAAA,GAAW,aAAa,QAAA,CAAS,QAAA;AACvC,IAAA,MAAM,QAAA,GAAW,QAAA,CAAS,KAAA,CAAM,2BAA2B,CAAA;AAC3D,IAAA,MAAM,QAAA,GAAW,QAAA,CAAS,KAAA,CAAM,mBAAmB,CAAA;AACnD,IAAA,OAAO;AAAA,MACL,QAAA;AAAA,MACA,KAAA,EAAO,QAAA,GAAY,QAAA,CAAS,CAAC,KAAK,IAAA,GAAQ,IAAA;AAAA,MAC1C,WAAA,EAAa,QAAA,GAAW,QAAA,CAAS,CAAC,CAAA,GAAI;AAAA,KACxC;AAAA,EACF,CAAA,CAAA,MAAQ;AAEN,IAAA,OAAO,KAAA;AAAA,EACT;AACF;AAOO,SAAS,eAAA,GAAgC;AAC9C,EAAA,MAAM,CAAC,GAAG,CAAA,GAAI,QAAA,CAAS,gBAAgB,CAAA;AACvC,EAAA,OAAO,GAAA;AACT;AAgBO,SAAS,qBAAA,CAAsB,OAAA,GAA+B,EAAC,EAAkB;AACtF,EAAA,MAAM,EAAE,YAAA,GAAe,EAAA,EAAI,SAAA,GAAY,KAAI,GAAI,OAAA;AAC/C,EAAA,MAAM,CAAC,MAAA,EAAQ,SAAS,CAAA,GAAI,SAAwB,IAAI,CAAA;AAExD,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,SAAS,OAAA,GAAgB;AACvB,MAAA,IAAI;AACF,QAAA,MAAM,QAAQ,MAAA,CAAO,YAAA;AACrB,QAAA,MAAM,eAAe,MAAA,CAAO,MAAA;AAC5B,QAAA,IAAI,CAAC,KAAA,IAAS,CAAC,YAAA,IAAgB,iBAAiB,MAAA,EAAQ;AACxD,QAAA,MAAM,YACJ,YAAA,CAAa,WAAA,GAAc,KAAA,CAAM,qBAAA,GAAwB,GAAA,GAAM,YAAA;AACjE,QAAA,SAAA,CAAU,IAAA,CAAK,GAAA,CAAI,SAAA,EAAW,SAAS,CAAC,CAAA;AAAA,MAC1C,CAAA,CAAA,MAAQ;AACN,QAAA,SAAA,CAAU,IAAI,CAAA;AAAA,MAChB;AAAA,IACF;AACA,IAAA,OAAA,EAAQ;AACR,IAAA,IAAI;AACF,MAAA,MAAA,CAAO,MAAA,CAAO,gBAAA,CAAiB,QAAA,EAAU,OAAO,CAAA;AAChD,MAAA,OAAO,MAAM,MAAA,CAAO,MAAA,CAAO,mBAAA,CAAoB,UAAU,OAAO,CAAA;AAAA,IAClE,CAAA,CAAA,MAAQ;AACN,MAAA;AAAA,IACF;AAAA,EACF,CAAA,EAAG,CAAC,YAAA,EAAc,SAAS,CAAC,CAAA;AAE5B,EAAA,OAAO,MAAA;AACT","file":"index.js","sourcesContent":["import type {\n  AccountClient,\n  AgentClient,\n  ConversationClient,\n  DataClient,\n  FunctionsClient,\n  KnowledgeClient,\n  MetaClient,\n  StorageClient,\n} from '@proteos/sdk'\nimport { createContext, type ReactNode, useMemo } from 'react'\n\nimport {\n  type Envelope,\n  isHostMessage,\n  MESSAGE_SOURCE,\n  type ModalResultMessage,\n  type NavigateMessage,\n  type OpenModalMessage,\n  type OpenPeekMessage,\n  type PageContext,\n} from './protocol'\n\n/** Options for {@link RuntimeContextValue.navigate}. */\nexport interface NavigateOptions {\n  /** Open the target in a peek (slide-over) panel instead of full-page. */\n  peek?: boolean\n}\n\n/** Options for {@link RuntimeContextValue.openModal}. */\nexport interface OpenModalOptions {\n  /** Heading rendered in the modal chrome. */\n  title?: string\n}\n\n/**\n * Manual control over iframe overlay promotion. The runtime already detects\n * overlays automatically (anything portaled to the iframe's `document.body` —\n * every `@proteos/ui` overlay qualifies), so components need this only for\n * custom portal targets, or to promote a frame *before* opening an overlay.\n * Calls are reference-counted: every `expand()` needs its `collapse()`.\n */\nexport interface OverlayController {\n  expand: () => void\n  collapse: () => void\n  isExpanded: () => boolean\n}\n\n/**\n * The authenticated `@proteos/sdk` clients the runtime injects. Same instances\n * the host app uses — pre-wired with a refreshing bearer token, so a component\n * never touches auth headers.\n */\nexport interface ComponentSdk {\n  account: AccountClient\n  agents: AgentClient\n  /**\n   * Conversations, messages, contacts, connections (conversation-service) —\n   * e.g. the DraftMessageComposer review surface. Plural per the platform's\n   * resource-naming rule; the web app's own `useSdk().conversation` predates\n   * it (documented asymmetry).\n   */\n  conversations: ConversationClient\n  data: DataClient\n  functions: FunctionsClient\n  knowledge: KnowledgeClient\n  meta: MetaClient\n  storage: StorageClient\n}\n\n/**\n * The raw runtime payload the shell hands a component at INIT. The shell builds\n * this; component authors read it through the hooks.\n */\nexport interface RuntimeValue {\n  /**\n   * The injected sdk clients. On an authenticated page these are the full,\n   * bearer-wired clients. On a PUBLIC page (`isPublic: true`) only\n   * `functions.actions.invokePublic` reaches the platform — every other\n   * client throws on use (there is no token, and the server rejects\n   * unauthenticated calls anyway).\n   */\n  sdk: ComponentSdk\n  /** Liquid-resolved props (a snapshot — not a live binding). */\n  props: Record<string, unknown>\n  /** Page context snapshot: the host record, entity, and URL params. */\n  pageCtx: PageContext\n  /** API origin SDK calls + asset URLs resolve against. */\n  apiBaseUrl: string\n  /** Current bearer token getter (escape hatch for raw fetches). Returns ''\n   *  on public pages. */\n  getToken: () => string\n  /** True when rendering on an unauthenticated public page. */\n  isPublic?: boolean\n  /** Org id, set in public mode (public API routes carry it in the path). */\n  orgId?: string\n  /** Set when this component is the content of a host component modal — the\n   *  correlation id it closes with. See `useModalHost()`. */\n  modalRequestId?: string\n  /** Overlay promotion controller, provided by the shell. Absent on older\n   *  shells / non-promoting hosts, in which case `useOverlayExpansion()`\n   *  no-ops. */\n  overlay?: OverlayController\n}\n\n/** Runtime value plus the derived helpers the hooks expose. */\nexport interface RuntimeContextValue extends RuntimeValue {\n  /** Navigate the host SPA to an in-app path (posts a NAVIGATE message), or\n   *  open it in a peek panel with `{ peek: true }` (posts OPEN_PEEK). */\n  navigate: (to: string, options?: NavigateOptions) => void\n  /** Open another component in a host-rendered modal; resolves with the value\n   *  that component closed with (`undefined` if dismissed). */\n  openModal: (\n    componentSlug: string,\n    props?: Record<string, unknown>,\n    options?: OpenModalOptions,\n  ) => Promise<unknown>\n}\n\nexport const RuntimeContext = createContext<RuntimeContextValue | null>(null)\n\n/** Post a NAVIGATE envelope to the host. The host only honours relative,\n *  in-app targets (it ignores absolute/external URLs). */\nfunction postNavigate(to: string): void {\n  const envelope: Envelope<NavigateMessage> = { source: MESSAGE_SOURCE, type: 'NAVIGATE', to }\n  window.parent?.postMessage(envelope, '*')\n}\n\n/** Post an OPEN_PEEK envelope to the host — open the in-app path in a peek\n *  panel. Same relative-path contract as {@link postNavigate}. */\nfunction postOpenPeek(to: string): void {\n  const envelope: Envelope<OpenPeekMessage> = { source: MESSAGE_SOURCE, type: 'OPEN_PEEK', to }\n  window.parent?.postMessage(envelope, '*')\n}\n\n/** Navigate full-page (default) or into a peek panel (`{ peek: true }`). */\nfunction navigate(to: string, options?: NavigateOptions): void {\n  if (options?.peek) postOpenPeek(to)\n  else postNavigate(to)\n}\n\n// ── Component modals ────────────────────────────────────────────────────────\n// One module-level listener + a pending map, rather than a listener per call:\n// the SDK is an import-mapped singleton, so this is per-iframe state.\n\nconst pendingModals = new Map<string, (result: unknown) => void>()\nlet modalListenerAttached = false\n\nfunction ensureModalListener(): void {\n  if (modalListenerAttached) return\n  modalListenerAttached = true\n  window.addEventListener('message', (event: MessageEvent) => {\n    const data: unknown = event.data\n    if (!isHostMessage(data) || data.type !== 'MODAL_CLOSED') return\n    const resolve = pendingModals.get(data.requestId)\n    // An unknown requestId is someone else's modal (or a stale reply) — drop it.\n    if (!resolve) return\n    pendingModals.delete(data.requestId)\n    resolve(data.result)\n  })\n}\n\nfunction newRequestId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {\n    return crypto.randomUUID()\n  }\n  return `modal_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`\n}\n\n/** Post OPEN_MODAL and resolve when the host answers MODAL_CLOSED. */\nfunction openModal(\n  componentSlug: string,\n  props?: Record<string, unknown>,\n  options?: OpenModalOptions,\n): Promise<unknown> {\n  ensureModalListener()\n  const requestId = newRequestId()\n  const envelope: Envelope<OpenModalMessage> = {\n    source: MESSAGE_SOURCE,\n    type: 'OPEN_MODAL',\n    requestId,\n    componentSlug,\n    ...(props !== undefined ? { props } : {}),\n    ...(options?.title !== undefined ? { title: options.title } : {}),\n  }\n  return new Promise<unknown>((resolve) => {\n    pendingModals.set(requestId, resolve)\n    window.parent?.postMessage(envelope, '*')\n  })\n}\n\n/** Post MODAL_RESULT — the component inside a host modal closing with a value. */\nexport function postModalResult(requestId: string, result?: unknown): void {\n  const envelope: Envelope<ModalResultMessage> = {\n    source: MESSAGE_SOURCE,\n    type: 'MODAL_RESULT',\n    requestId,\n    ...(result !== undefined ? { result } : {}),\n  }\n  window.parent?.postMessage(envelope, '*')\n}\n\n/**\n * Provides the runtime value + derived helpers to a component subtree. Mounted\n * by the component-runtime shell around the loaded component — authors never\n * render this themselves. Lives in `@proteos/component-sdk` (a shared,\n * import-mapped singleton) so the context the shell provides is the very same\n * context the component's hooks read, across the bundle boundary.\n */\nexport function RuntimeProvider({ value, children }: { value: RuntimeValue; children: ReactNode }) {\n  // The shell builds `value` once at INIT (a stable state object — clients,\n  // props and pageCtx are all set once), so memoizing on its identity recreates\n  // the context only when the runtime genuinely re-inits.\n  const ctx = useMemo<RuntimeContextValue>(() => ({ ...value, navigate, openModal }), [value])\n  return <RuntimeContext.Provider value={ctx}>{children}</RuntimeContext.Provider>\n}\n","import { useCallback, useContext, useEffect, useMemo, useState } from 'react'\n\nimport {\n  type ComponentSdk,\n  type NavigateOptions,\n  type OpenModalOptions,\n  type OverlayController,\n  postModalResult,\n  RuntimeContext,\n  type RuntimeContextValue,\n} from './context'\nimport type { PageContext } from './protocol'\n\n/**\n * Low-level escape hatch: the whole runtime context (sdk, props, pageCtx,\n * apiBaseUrl, getToken, navigate). Prefer the focused hooks below. Throws a\n * clear error if used outside the component runtime.\n */\nexport function useRuntime(): RuntimeContextValue {\n  const ctx = useContext(RuntimeContext)\n  if (!ctx) {\n    throw new Error(\n      '@proteos/component-sdk: hooks must run inside the Proteos component runtime. ' +\n        'This usually means the component is rendered outside its iframe, or a ' +\n        'second copy of @proteos/component-sdk was bundled instead of using the ' +\n        'runtime-provided one (keep it external).',\n    )\n  }\n  return ctx\n}\n\n/** The authenticated SDK clients (account / agents / conversations / data / functions / knowledge / meta / storage). */\nexport function useSdk(): ComponentSdk {\n  return useRuntime().sdk\n}\n\n/** The component's Liquid-resolved props (a snapshot, not a live binding). */\nexport function useProps<T extends Record<string, unknown> = Record<string, unknown>>(): T {\n  return useRuntime().props as T\n}\n\n/**\n * The full page context: host `record`, `entity`, and URL `params`. The\n * `record` is a snapshot taken at mount (`undefined` on record-less platform\n * pages) — fetch via `useSdk().data` for anything that must stay fresh.\n */\nexport function usePageContext(): PageContext {\n  return useRuntime().pageCtx\n}\n\n/**\n * Navigate the host SPA to an in-app path, e.g.\n * `navigate('/org/acme/record/task/123')`. The host ignores absolute/external\n * URLs. Build org/app-prefixed paths with `useHostLocation().appBasePath`.\n *\n * Pass `{ peek: true }` to open the path in a peek (slide-over) panel instead\n * of full-page navigation — e.g. `navigate(path, { peek: true })`. The host\n * peeks what it can (today: platform pages) and falls back to full navigation.\n */\nexport function useNavigate(): (to: string, options?: NavigateOptions) => void {\n  return useRuntime().navigate\n}\n\n/** The API origin SDK calls resolve against (for building raw asset URLs). */\nexport function useApiBaseUrl(): string {\n  return useRuntime().apiBaseUrl\n}\n\nconst NOOP_OVERLAY: OverlayController = {\n  expand: () => {\n    console.warn(\n      '@proteos/component-sdk: useOverlayExpansion() has no effect — this runtime ' +\n        'does not support overlay promotion (older shell or non-promoting host).',\n    )\n  },\n  collapse: () => {},\n  isExpanded: () => false,\n}\n\n/**\n * Manual overlay promotion — lifts the whole component iframe over the rest of\n * the page so an overlay can escape the frame's box.\n *\n * You rarely need this. Every `@proteos/ui` overlay (Modal, Popover, Menu,\n * Select, Tooltip, …) portals to the iframe document's `<body>`, which the\n * runtime watches — those promote automatically, with no code. Reach for this\n * hook only when you portal somewhere else yourself, or want the frame lifted\n * *before* the overlay mounts. Reference-counted: pair every `expand()` with a\n * `collapse()`.\n */\nexport function useOverlayExpansion(): OverlayController {\n  return useRuntime().overlay ?? NOOP_OVERLAY\n}\n\n/**\n * Open ANOTHER component in a modal the host renders above everything — the\n * cross-component flow (a picker, a wizard step, a confirm dialog shared by\n * several components). Resolves with whatever that component closed with, or\n * `undefined` if the user dismissed it.\n *\n * ```ts\n * const openModal = useComponentModal()\n * const picked = await openModal('contact-picker', { entity: 'contact' }, { title: 'Pick a contact' })\n * ```\n *\n * For an overlay that is part of THIS component, just render a `<Modal>` from\n * `@proteos/ui` — it promotes automatically.\n */\nexport function useComponentModal(): (\n  componentSlug: string,\n  props?: Record<string, unknown>,\n  options?: OpenModalOptions,\n) => Promise<unknown> {\n  return useRuntime().openModal\n}\n\nexport interface ModalHost {\n  /** True when this component is rendered as the content of a host modal. */\n  isInModal: boolean\n  /** Close the host modal, resolving the opener's promise with `result`.\n   *  No-op outside a modal. */\n  close: (result?: unknown) => void\n}\n\n/**\n * For a component that is being shown INSIDE a host modal (opened by another\n * component's `useComponentModal()`): close it and hand a value back.\n * `isInModal` is false on ordinary page-hosted mounts, so one component can\n * serve both roles.\n */\nexport function useModalHost(): ModalHost {\n  const requestId = useRuntime().modalRequestId\n  const close = useCallback(\n    (result?: unknown) => {\n      if (requestId === undefined) return\n      postModalResult(requestId, result)\n    },\n    [requestId],\n  )\n  return useMemo(() => ({ isInModal: requestId !== undefined, close }), [requestId, close])\n}\n\n/**\n * A getter for the current bearer token. Returns a function (not the token)\n * because the token is refreshed in place — read it at call time for a raw\n * `fetch`. Most components never need this; prefer `useSdk()`.\n */\nexport function useAuthToken(): () => string {\n  return useRuntime().getToken\n}\n\nexport interface HostLocation {\n  /** The host tab's pathname (same-origin read), or null if unavailable. */\n  pathname: string | null\n  /** The org id parsed from `/org/<orgId>/…`, or null. */\n  orgId: string | null\n  /** The `/org/<orgId>/app/<appId>` prefix, or null when not on an app page. */\n  appBasePath: string | null\n}\n\nfunction readHostLocation(): HostLocation {\n  const empty: HostLocation = { pathname: null, orgId: null, appBasePath: null }\n  try {\n    const parentWindow = window.parent\n    if (!parentWindow || parentWindow === window) return empty\n    const pathname = parentWindow.location.pathname\n    const appMatch = pathname.match(/^\\/org\\/[^/]+\\/app\\/[^/]+/)\n    const orgMatch = pathname.match(/^\\/org\\/([^/]+)\\//)\n    return {\n      pathname,\n      orgId: orgMatch ? (orgMatch[1] ?? null) : null,\n      appBasePath: appMatch ? appMatch[0] : null,\n    }\n  } catch {\n    // Cross-origin (untrusted-component future) or detached — fall back to null.\n    return empty\n  }\n}\n\n/**\n * Read the host tab's location (same-origin) — the org id and `/org/.../app/...`\n * prefix needed to build navigation targets on platform pages. Read once on\n * mount (the iframe re-inits when the host route changes).\n */\nexport function useHostLocation(): HostLocation {\n  const [loc] = useState(readHostLocation)\n  return loc\n}\n\nexport interface FillViewportOptions {\n  /** Gap left below the component (px). Default 24. */\n  bottomMargin?: number\n  /** Floor for the computed height (px). Default 320. */\n  minHeight?: number\n}\n\n/**\n * Compute a \"fill the rest of the viewport\" height for full-bleed layouts\n * (boards, canvases). The runtime auto-sizes the iframe to its content, so a\n * component can't use its own `vh` units (circular). The iframe is same-origin,\n * so this measures the parent viewport minus the iframe's offset instead.\n * Returns `null` when it can't measure (fall back to natural height).\n */\nexport function useFillViewportHeight(options: FillViewportOptions = {}): number | null {\n  const { bottomMargin = 24, minHeight = 320 } = options\n  const [height, setHeight] = useState<number | null>(null)\n\n  useEffect(() => {\n    function compute(): void {\n      try {\n        const frame = window.frameElement\n        const parentWindow = window.parent\n        if (!frame || !parentWindow || parentWindow === window) return\n        const available =\n          parentWindow.innerHeight - frame.getBoundingClientRect().top - bottomMargin\n        setHeight(Math.max(available, minHeight))\n      } catch {\n        setHeight(null) // cross-origin or detached — fall back to natural height\n      }\n    }\n    compute()\n    try {\n      window.parent.addEventListener('resize', compute)\n      return () => window.parent.removeEventListener('resize', compute)\n    } catch {\n      return\n    }\n  }, [bottomMargin, minHeight])\n\n  return height\n}\n"]}

package/dist/protocol.cjs

@@ -1,20 +1,24 @@
 'use strict';
 
-var chunkGL7ZEEP4_cjs = require('./chunk-GL7ZEEP4.cjs');
+var chunkP4MKRWPA_cjs = require('./chunk-P4MKRWPA.cjs');
 
 
 
+Object.defineProperty(exports, "COMPONENT_OVERLAY_Z_INDEX", {
+  enumerable: true,
+  get: function () { return chunkP4MKRWPA_cjs.COMPONENT_OVERLAY_Z_INDEX; }
+});
 Object.defineProperty(exports, "MESSAGE_SOURCE", {
   enumerable: true,
-  get: function () { return chunkGL7ZEEP4_cjs.MESSAGE_SOURCE; }
+  get: function () { return chunkP4MKRWPA_cjs.MESSAGE_SOURCE; }
 });
 Object.defineProperty(exports, "isHostMessage", {
   enumerable: true,
-  get: function () { return chunkGL7ZEEP4_cjs.isHostMessage; }
+  get: function () { return chunkP4MKRWPA_cjs.isHostMessage; }
 });
 Object.defineProperty(exports, "isRuntimeMessage", {
   enumerable: true,
-  get: function () { return chunkGL7ZEEP4_cjs.isRuntimeMessage; }
+  get: function () { return chunkP4MKRWPA_cjs.isRuntimeMessage; }
 });
 //# sourceMappingURL=protocol.cjs.map
 //# sourceMappingURL=protocol.cjs.map

package/dist/protocol.d.cts

@@ -1,4 +1,33 @@
 declare const MESSAGE_SOURCE: "proteos-component-runtime";
+/**
+ * z-index the component iframe is promoted to while one of its own overlays
+ * (modal, popover, menu, select, tooltip) is open. The iframe goes
+ * `position: fixed; inset: 0` at this z so the overlay — which portals to the
+ * IFRAME's body and would otherwise clip at the frame's box — can paint over
+ * the rest of the page.
+ *
+ * Host z ladder this slots into:
+ *   50    @proteos/ui Modal / Tooltip / ImageLightbox (default tier)
+ *   1000+ full-page panel stack (scrim 1000, panels 1001+n)
+ *   1090  peek scrim   1100  peek panel, ask-proteos window
+ *   1150  ← THIS
+ *   1200  menu popover, command palette, action dialog, component modal
+ *   1300  select popover
+ *
+ * Above the peek/full-page surfaces a component can live on, below the global
+ * host chrome. Note the cap: inside a peek (a `fixed` + z-index ancestor) the
+ * promoted iframe paints within that 1100 stacking context — it covers the
+ * peek's own content and everything under it, but host chrome at 1200+ still
+ * wins. That is the intended layering, not a bug.
+ */
+declare const COMPONENT_OVERLAY_Z_INDEX = 1150;
+/** Viewport-relative box of the iframe's in-flow placeholder, in CSS px. */
+interface OverlayRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
 interface PageContext {
     record?: Record<string, unknown>;
     entity?: {
@@ -28,6 +57,11 @@ interface InitMessage {
     /** Org id for public mode — public endpoints carry the org in the path
      *  because there is no token to scope from. */
     orgId?: string;
+    /** Set when this frame is the CONTENT of a host component modal (opened by
+     *  another component via OPEN_MODAL). The component reads it through
+     *  `useModalHost()` and closes with a result by posting MODAL_RESULT with
+     *  this id. Absent on ordinary page-hosted frames. */
+    modalRequestId?: string;
 }
 interface AuthRefreshMessage {
     type: 'AUTH_REFRESH';
@@ -37,7 +71,23 @@ interface DataInvalidateMessage {
     type: 'DATA_INVALIDATE';
     queryKey?: unknown[];
 }
-type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage;
+/** Where the iframe's in-flow box sits in the host viewport. Sent while the
+ *  frame is promoted (OVERLAY_STATE open) so the runtime can keep its content
+ *  parked at the original rect while the iframe itself covers the viewport —
+ *  and re-sent when the host window resizes under an open overlay. */
+interface OverlayRectMessage {
+    type: 'OVERLAY_RECT';
+    rect: OverlayRect;
+}
+/** Resolution of an OPEN_MODAL request: the host modal closed. `result` is the
+ *  value the modal's component passed to MODAL_RESULT, and is absent when the
+ *  modal was dismissed (backdrop / Esc / ×). */
+interface ModalClosedMessage {
+    type: 'MODAL_CLOSED';
+    requestId: string;
+    result?: unknown;
+}
+type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage | OverlayRectMessage | ModalClosedMessage;
 interface ReadyMessage {
     type: 'READY';
 }
@@ -56,16 +106,63 @@ interface OpenPeekMessage {
     type: 'OPEN_PEEK';
     to: string;
 }
+/** The runtime has (or no longer has) an overlay open and needs the host to
+ *  promote (or restore) the iframe. See {@link COMPONENT_OVERLAY_Z_INDEX}.
+ *
+ *  Same-origin today, so the runtime applies the promotion styles to its own
+ *  `window.frameElement` synchronously (pre-paint, no flicker) and this message
+ *  is the host's cue to MIRROR that state into React — gate RESIZE, hold the
+ *  placeholder height, start posting OVERLAY_RECT. When components move to a
+ *  dedicated origin the runtime can no longer touch the frame and this message
+ *  becomes the actuation instead; the runtime hides its overlay until the
+ *  answering OVERLAY_RECT arrives. */
+interface OverlayStateMessage {
+    type: 'OVERLAY_STATE';
+    open: boolean;
+}
+/** Ask the host to open ANOTHER component in a central modal, above everything
+ *  this frame could reach on its own. The host answers with MODAL_CLOSED
+ *  carrying the same `requestId`. */
+interface OpenModalMessage {
+    type: 'OPEN_MODAL';
+    /** Correlates the eventual MODAL_CLOSED. Generated by the opener. */
+    requestId: string;
+    /** Slug of the component to mount inside the modal. */
+    componentSlug: string;
+    /** Props for that component (already literal values — no Liquid). */
+    props?: Record<string, unknown>;
+    /** Optional modal heading. */
+    title?: string;
+}
+/** Escape was pressed with focus inside the iframe, and nothing in the runtime
+ *  consumed it.
+ *
+ *  Keyboard events don't cross the iframe boundary, and react-aria binds its
+ *  Escape handling to the overlay element in its own React tree — so a
+ *  host-rendered dialog CANNOT see Escape once the user has clicked into a
+ *  component. The runtime forwards it so the host can dismiss on the user's
+ *  behalf. Not sent while the runtime has its own overlay open: that overlay
+ *  owns Escape. */
+interface EscapePressedMessage {
+    type: 'ESCAPE_PRESSED';
+}
+/** Posted by the component INSIDE a host modal to close it with a value. The
+ *  `requestId` is the one INIT carried as `modalRequestId`. */
+interface ModalResultMessage {
+    type: 'MODAL_RESULT';
+    requestId: string;
+    result?: unknown;
+}
 interface ErrorMessage {
     type: 'ERROR';
     message: string;
     stack?: string;
 }
-type RuntimeMessage = ReadyMessage | ResizeMessage | NavigateMessage | OpenPeekMessage | ErrorMessage;
+type RuntimeMessage = ReadyMessage | ResizeMessage | NavigateMessage | OpenPeekMessage | OverlayStateMessage | OpenModalMessage | ModalResultMessage | EscapePressedMessage | ErrorMessage;
 type Envelope<T> = T & {
     source: typeof MESSAGE_SOURCE;
 };
 declare function isHostMessage(data: unknown): data is Envelope<HostMessage>;
 declare function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage>;
 
-export { type AuthRefreshMessage, type DataInvalidateMessage, type Envelope, type ErrorMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type NavigateMessage, type OpenPeekMessage, type PageContext, type ReadyMessage, type ResizeMessage, type RuntimeMessage, isHostMessage, isRuntimeMessage };
+export { type AuthRefreshMessage, COMPONENT_OVERLAY_Z_INDEX, type DataInvalidateMessage, type Envelope, type ErrorMessage, type EscapePressedMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type ModalClosedMessage, type ModalResultMessage, type NavigateMessage, type OpenModalMessage, type OpenPeekMessage, type OverlayRect, type OverlayRectMessage, type OverlayStateMessage, type PageContext, type ReadyMessage, type ResizeMessage, type RuntimeMessage, isHostMessage, isRuntimeMessage };

package/dist/protocol.d.ts

@@ -1,4 +1,33 @@
 declare const MESSAGE_SOURCE: "proteos-component-runtime";
+/**
+ * z-index the component iframe is promoted to while one of its own overlays
+ * (modal, popover, menu, select, tooltip) is open. The iframe goes
+ * `position: fixed; inset: 0` at this z so the overlay — which portals to the
+ * IFRAME's body and would otherwise clip at the frame's box — can paint over
+ * the rest of the page.
+ *
+ * Host z ladder this slots into:
+ *   50    @proteos/ui Modal / Tooltip / ImageLightbox (default tier)
+ *   1000+ full-page panel stack (scrim 1000, panels 1001+n)
+ *   1090  peek scrim   1100  peek panel, ask-proteos window
+ *   1150  ← THIS
+ *   1200  menu popover, command palette, action dialog, component modal
+ *   1300  select popover
+ *
+ * Above the peek/full-page surfaces a component can live on, below the global
+ * host chrome. Note the cap: inside a peek (a `fixed` + z-index ancestor) the
+ * promoted iframe paints within that 1100 stacking context — it covers the
+ * peek's own content and everything under it, but host chrome at 1200+ still
+ * wins. That is the intended layering, not a bug.
+ */
+declare const COMPONENT_OVERLAY_Z_INDEX = 1150;
+/** Viewport-relative box of the iframe's in-flow placeholder, in CSS px. */
+interface OverlayRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
 interface PageContext {
     record?: Record<string, unknown>;
     entity?: {
@@ -28,6 +57,11 @@ interface InitMessage {
     /** Org id for public mode — public endpoints carry the org in the path
      *  because there is no token to scope from. */
     orgId?: string;
+    /** Set when this frame is the CONTENT of a host component modal (opened by
+     *  another component via OPEN_MODAL). The component reads it through
+     *  `useModalHost()` and closes with a result by posting MODAL_RESULT with
+     *  this id. Absent on ordinary page-hosted frames. */
+    modalRequestId?: string;
 }
 interface AuthRefreshMessage {
     type: 'AUTH_REFRESH';
@@ -37,7 +71,23 @@ interface DataInvalidateMessage {
     type: 'DATA_INVALIDATE';
     queryKey?: unknown[];
 }
-type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage;
+/** Where the iframe's in-flow box sits in the host viewport. Sent while the
+ *  frame is promoted (OVERLAY_STATE open) so the runtime can keep its content
+ *  parked at the original rect while the iframe itself covers the viewport —
+ *  and re-sent when the host window resizes under an open overlay. */
+interface OverlayRectMessage {
+    type: 'OVERLAY_RECT';
+    rect: OverlayRect;
+}
+/** Resolution of an OPEN_MODAL request: the host modal closed. `result` is the
+ *  value the modal's component passed to MODAL_RESULT, and is absent when the
+ *  modal was dismissed (backdrop / Esc / ×). */
+interface ModalClosedMessage {
+    type: 'MODAL_CLOSED';
+    requestId: string;
+    result?: unknown;
+}
+type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage | OverlayRectMessage | ModalClosedMessage;
 interface ReadyMessage {
     type: 'READY';
 }
@@ -56,16 +106,63 @@ interface OpenPeekMessage {
     type: 'OPEN_PEEK';
     to: string;
 }
+/** The runtime has (or no longer has) an overlay open and needs the host to
+ *  promote (or restore) the iframe. See {@link COMPONENT_OVERLAY_Z_INDEX}.
+ *
+ *  Same-origin today, so the runtime applies the promotion styles to its own
+ *  `window.frameElement` synchronously (pre-paint, no flicker) and this message
+ *  is the host's cue to MIRROR that state into React — gate RESIZE, hold the
+ *  placeholder height, start posting OVERLAY_RECT. When components move to a
+ *  dedicated origin the runtime can no longer touch the frame and this message
+ *  becomes the actuation instead; the runtime hides its overlay until the
+ *  answering OVERLAY_RECT arrives. */
+interface OverlayStateMessage {
+    type: 'OVERLAY_STATE';
+    open: boolean;
+}
+/** Ask the host to open ANOTHER component in a central modal, above everything
+ *  this frame could reach on its own. The host answers with MODAL_CLOSED
+ *  carrying the same `requestId`. */
+interface OpenModalMessage {
+    type: 'OPEN_MODAL';
+    /** Correlates the eventual MODAL_CLOSED. Generated by the opener. */
+    requestId: string;
+    /** Slug of the component to mount inside the modal. */
+    componentSlug: string;
+    /** Props for that component (already literal values — no Liquid). */
+    props?: Record<string, unknown>;
+    /** Optional modal heading. */
+    title?: string;
+}
+/** Escape was pressed with focus inside the iframe, and nothing in the runtime
+ *  consumed it.
+ *
+ *  Keyboard events don't cross the iframe boundary, and react-aria binds its
+ *  Escape handling to the overlay element in its own React tree — so a
+ *  host-rendered dialog CANNOT see Escape once the user has clicked into a
+ *  component. The runtime forwards it so the host can dismiss on the user's
+ *  behalf. Not sent while the runtime has its own overlay open: that overlay
+ *  owns Escape. */
+interface EscapePressedMessage {
+    type: 'ESCAPE_PRESSED';
+}
+/** Posted by the component INSIDE a host modal to close it with a value. The
+ *  `requestId` is the one INIT carried as `modalRequestId`. */
+interface ModalResultMessage {
+    type: 'MODAL_RESULT';
+    requestId: string;
+    result?: unknown;
+}
 interface ErrorMessage {
     type: 'ERROR';
     message: string;
     stack?: string;
 }
-type RuntimeMessage = ReadyMessage | ResizeMessage | NavigateMessage | OpenPeekMessage | ErrorMessage;
+type RuntimeMessage = ReadyMessage | ResizeMessage | NavigateMessage | OpenPeekMessage | OverlayStateMessage | OpenModalMessage | ModalResultMessage | EscapePressedMessage | ErrorMessage;
 type Envelope<T> = T & {
     source: typeof MESSAGE_SOURCE;
 };
 declare function isHostMessage(data: unknown): data is Envelope<HostMessage>;
 declare function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage>;
 
-export { type AuthRefreshMessage, type DataInvalidateMessage, type Envelope, type ErrorMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type NavigateMessage, type OpenPeekMessage, type PageContext, type ReadyMessage, type ResizeMessage, type RuntimeMessage, isHostMessage, isRuntimeMessage };
+export { type AuthRefreshMessage, COMPONENT_OVERLAY_Z_INDEX, type DataInvalidateMessage, type Envelope, type ErrorMessage, type EscapePressedMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type ModalClosedMessage, type ModalResultMessage, type NavigateMessage, type OpenModalMessage, type OpenPeekMessage, type OverlayRect, type OverlayRectMessage, type OverlayStateMessage, type PageContext, type ReadyMessage, type ResizeMessage, type RuntimeMessage, isHostMessage, isRuntimeMessage };

package/dist/protocol.js

@@ -1,3 +1,3 @@
-export { MESSAGE_SOURCE, isHostMessage, isRuntimeMessage } from './chunk-DD7AKVFC.js';
+export { COMPONENT_OVERLAY_Z_INDEX, MESSAGE_SOURCE, isHostMessage, isRuntimeMessage } from './chunk-2EAOQNQB.js';
 //# sourceMappingURL=protocol.js.map
 //# sourceMappingURL=protocol.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/component-sdk",
-  "version": "0.41.1",
+  "version": "0.42.1",
   "license": "Apache-2.0",
   "description": "Typed runtime hooks for authoring Proteos custom components — the SDK you import inside a component bundle.",
   "repository": {
@@ -42,7 +42,7 @@
     "src"
   ],
   "dependencies": {
-    "@proteos/sdk": "^0.41.1"
+    "@proteos/sdk": "^0.42.1"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",

package/src/context.tsx

@@ -12,8 +12,11 @@ import { createContext, type ReactNode, useMemo } from 'react'
 
 import {
   type Envelope,
+  isHostMessage,
   MESSAGE_SOURCE,
+  type ModalResultMessage,
   type NavigateMessage,
+  type OpenModalMessage,
   type OpenPeekMessage,
   type PageContext,
 } from './protocol'
@@ -24,6 +27,25 @@ export interface NavigateOptions {
   peek?: boolean
 }
 
+/** Options for {@link RuntimeContextValue.openModal}. */
+export interface OpenModalOptions {
+  /** Heading rendered in the modal chrome. */
+  title?: string
+}
+
+/**
+ * Manual control over iframe overlay promotion. The runtime already detects
+ * overlays automatically (anything portaled to the iframe's `document.body` —
+ * every `@proteos/ui` overlay qualifies), so components need this only for
+ * custom portal targets, or to promote a frame *before* opening an overlay.
+ * Calls are reference-counted: every `expand()` needs its `collapse()`.
+ */
+export interface OverlayController {
+  expand: () => void
+  collapse: () => void
+  isExpanded: () => boolean
+}
+
 /**
  * The authenticated `@proteos/sdk` clients the runtime injects. Same instances
  * the host app uses — pre-wired with a refreshing bearer token, so a component
@@ -72,6 +94,13 @@ export interface RuntimeValue {
   isPublic?: boolean
   /** Org id, set in public mode (public API routes carry it in the path). */
   orgId?: string
+  /** Set when this component is the content of a host component modal — the
+   *  correlation id it closes with. See `useModalHost()`. */
+  modalRequestId?: string
+  /** Overlay promotion controller, provided by the shell. Absent on older
+   *  shells / non-promoting hosts, in which case `useOverlayExpansion()`
+   *  no-ops. */
+  overlay?: OverlayController
 }
 
 /** Runtime value plus the derived helpers the hooks expose. */
@@ -79,6 +108,13 @@ export interface RuntimeContextValue extends RuntimeValue {
   /** Navigate the host SPA to an in-app path (posts a NAVIGATE message), or
    *  open it in a peek panel with `{ peek: true }` (posts OPEN_PEEK). */
   navigate: (to: string, options?: NavigateOptions) => void
+  /** Open another component in a host-rendered modal; resolves with the value
+   *  that component closed with (`undefined` if dismissed). */
+  openModal: (
+    componentSlug: string,
+    props?: Record<string, unknown>,
+    options?: OpenModalOptions,
+  ) => Promise<unknown>
 }
 
 export const RuntimeContext = createContext<RuntimeContextValue | null>(null)
@@ -103,6 +139,67 @@ function navigate(to: string, options?: NavigateOptions): void {
   else postNavigate(to)
 }
 
+// ── Component modals ────────────────────────────────────────────────────────
+// One module-level listener + a pending map, rather than a listener per call:
+// the SDK is an import-mapped singleton, so this is per-iframe state.
+
+const pendingModals = new Map<string, (result: unknown) => void>()
+let modalListenerAttached = false
+
+function ensureModalListener(): void {
+  if (modalListenerAttached) return
+  modalListenerAttached = true
+  window.addEventListener('message', (event: MessageEvent) => {
+    const data: unknown = event.data
+    if (!isHostMessage(data) || data.type !== 'MODAL_CLOSED') return
+    const resolve = pendingModals.get(data.requestId)
+    // An unknown requestId is someone else's modal (or a stale reply) — drop it.
+    if (!resolve) return
+    pendingModals.delete(data.requestId)
+    resolve(data.result)
+  })
+}
+
+function newRequestId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID()
+  }
+  return `modal_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
+}
+
+/** Post OPEN_MODAL and resolve when the host answers MODAL_CLOSED. */
+function openModal(
+  componentSlug: string,
+  props?: Record<string, unknown>,
+  options?: OpenModalOptions,
+): Promise<unknown> {
+  ensureModalListener()
+  const requestId = newRequestId()
+  const envelope: Envelope<OpenModalMessage> = {
+    source: MESSAGE_SOURCE,
+    type: 'OPEN_MODAL',
+    requestId,
+    componentSlug,
+    ...(props !== undefined ? { props } : {}),
+    ...(options?.title !== undefined ? { title: options.title } : {}),
+  }
+  return new Promise<unknown>((resolve) => {
+    pendingModals.set(requestId, resolve)
+    window.parent?.postMessage(envelope, '*')
+  })
+}
+
+/** Post MODAL_RESULT — the component inside a host modal closing with a value. */
+export function postModalResult(requestId: string, result?: unknown): void {
+  const envelope: Envelope<ModalResultMessage> = {
+    source: MESSAGE_SOURCE,
+    type: 'MODAL_RESULT',
+    requestId,
+    ...(result !== undefined ? { result } : {}),
+  }
+  window.parent?.postMessage(envelope, '*')
+}
+
 /**
  * Provides the runtime value + derived helpers to a component subtree. Mounted
  * by the component-runtime shell around the loaded component — authors never
@@ -114,6 +211,6 @@ export function RuntimeProvider({ value, children }: { value: RuntimeValue; chil
   // The shell builds `value` once at INIT (a stable state object — clients,
   // props and pageCtx are all set once), so memoizing on its identity recreates
   // the context only when the runtime genuinely re-inits.
-  const ctx = useMemo<RuntimeContextValue>(() => ({ ...value, navigate }), [value])
+  const ctx = useMemo<RuntimeContextValue>(() => ({ ...value, navigate, openModal }), [value])
   return <RuntimeContext.Provider value={ctx}>{children}</RuntimeContext.Provider>
 }

package/src/hooks.test.tsx

@@ -3,8 +3,18 @@ import type { ReactNode } from 'react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { RuntimeProvider, type RuntimeValue } from './context'
-import { useApiBaseUrl, useNavigate, usePageContext, useProps, useRuntime, useSdk } from './hooks'
-import { MESSAGE_SOURCE } from './protocol'
+import {
+  useApiBaseUrl,
+  useComponentModal,
+  useModalHost,
+  useNavigate,
+  useOverlayExpansion,
+  usePageContext,
+  useProps,
+  useRuntime,
+  useSdk,
+} from './hooks'
+import { type Envelope, MESSAGE_SOURCE, type ModalClosedMessage } from './protocol'
 
 // A stable stand-in for the injected SDK — the hooks only pass it through.
 const sdk = {} as RuntimeValue['sdk']
@@ -65,6 +75,79 @@ describe('runtime hooks', () => {
     )
   })
 
+  it('useOverlayExpansion drives the shell controller', () => {
+    const overlay = { expand: vi.fn(), collapse: vi.fn(), isExpanded: () => true }
+    const { result } = renderHook(() => useOverlayExpansion(), {
+      wrapper: wrapper(makeValue({ overlay })),
+    })
+    result.current.expand()
+    result.current.collapse()
+    expect(overlay.expand).toHaveBeenCalledTimes(1)
+    expect(overlay.collapse).toHaveBeenCalledTimes(1)
+    expect(result.current.isExpanded()).toBe(true)
+  })
+
+  it('useOverlayExpansion warns and no-ops on a runtime without promotion support', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const { result } = renderHook(() => useOverlayExpansion(), { wrapper: wrapper(makeValue()) })
+    result.current.expand()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('overlay promotion'))
+    expect(result.current.isExpanded()).toBe(false)
+  })
+
+  it('useComponentModal posts OPEN_MODAL and resolves on the matching MODAL_CLOSED', async () => {
+    const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
+    const { result } = renderHook(() => useComponentModal(), { wrapper: wrapper(makeValue()) })
+
+    const pending = result.current('contact-picker', { entity: 'contact' }, { title: 'Pick one' })
+    const [payload] = post.mock.calls.at(-1) as [Record<string, unknown>]
+    expect(payload).toMatchObject({
+      source: MESSAGE_SOURCE,
+      type: 'OPEN_MODAL',
+      componentSlug: 'contact-picker',
+      props: { entity: 'contact' },
+      title: 'Pick one',
+    })
+
+    // Another modal's reply must not resolve ours.
+    const reply = (requestId: string, result?: unknown): Envelope<ModalClosedMessage> => ({
+      source: MESSAGE_SOURCE,
+      type: 'MODAL_CLOSED',
+      requestId,
+      ...(result !== undefined ? { result } : {}),
+    })
+    window.dispatchEvent(new MessageEvent('message', { data: reply('someone-else', 'nope') }))
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: reply(payload.requestId as string, { id: 'con_9' }),
+      }),
+    )
+    await expect(pending).resolves.toEqual({ id: 'con_9' })
+  })
+
+  it('useModalHost closes with a result only when mounted inside a modal', () => {
+    const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
+    const outside = renderHook(() => useModalHost(), { wrapper: wrapper(makeValue()) })
+    expect(outside.result.current.isInModal).toBe(false)
+    outside.result.current.close('ignored')
+    expect(post).not.toHaveBeenCalled()
+
+    const inside = renderHook(() => useModalHost(), {
+      wrapper: wrapper(makeValue({ modalRequestId: 'cmodal_3' })),
+    })
+    expect(inside.result.current.isInModal).toBe(true)
+    inside.result.current.close({ picked: true })
+    expect(post).toHaveBeenCalledWith(
+      {
+        source: MESSAGE_SOURCE,
+        type: 'MODAL_RESULT',
+        requestId: 'cmodal_3',
+        result: { picked: true },
+      },
+      '*',
+    )
+  })
+
   it('throws a clear error when used outside the runtime', () => {
     // Silence the expected React error-boundary console noise.
     vi.spyOn(console, 'error').mockImplementation(() => {})