@proteos/component-sdk 0.60.0 → 0.75.0

package/src/protocol.ts

@@ -8,6 +8,8 @@
 // Every message carries `source: MESSAGE_SOURCE` so we can ignore the unrelated
 // postMessage traffic that shares the window (OIDC silent-renew, Vite HMR, …).
 
+import type { PageAction } from '@proteos/sdk'
+
 export const MESSAGE_SOURCE = 'proteos-component-runtime' as const
 
 /**
@@ -41,10 +43,42 @@ export interface OverlayRect {
   height: number
 }
 
+/** What the viewer is doing with the record on the host page.
+ *
+ *  - `view`   — a read-only record page, or a page without a record
+ *               (platform, kiosk, public, previews).
+ *  - `create` — the form for a record that is not saved yet (`record` holds
+ *               the seed values only, no `id`).
+ *  - `edit`   — the form over an existing record (`record` is the SAVED row;
+ *               in-flight edits are not reflected).
+ *
+ *  Inside an action's / workflow's invoke dialog (a trigger page) `mode` is
+ *  `create` while the person fills the params and `view` once the run is on
+ *  its way; `phase` says where the run is.
+ *
+ *  A snapshot like `record`: the host remounts the frame when the page
+ *  switches between view and edit, so a new INIT carries the new mode. Also
+ *  the Liquid scope key `mode` when props are resolved. */
+export type PageMode = 'view' | 'create' | 'edit'
+
+/** Where an invocation is in the invoke dialog's lifecycle — set only on a
+ *  trigger page (the dialog of an action / workflow); absent everywhere else.
+ *
+ *  - `input`   — the form over the params (`record` = the seeded params).
+ *  - `running` — the run is in flight (`record` = the submitted params;
+ *                `params.execution` for a workflow).
+ *  - `result`  — the run ended (`record` = the params plus the action's
+ *                returns; `params.result` / `params.execution`).
+ *
+ *  Also the Liquid scope key `phase`. */
+export type TriggerPhase = 'input' | 'running' | 'result'
+
 export interface PageContext {
   record?: Record<string, unknown>
   entity?: { slug: string; [key: string]: unknown }
   params?: Record<string, unknown>
+  mode: PageMode
+  phase?: TriggerPhase
   /** The signed-in viewer (absent on public pages and offline previews). The
    *  host resolves `{{ current_user.* }}` and the bare `current_user` prop
    *  sentinel against it before posting props. */
@@ -63,6 +97,21 @@ export interface InitMessage {
   authToken: string
   /** API origin the bundle endpoint + SDK calls resolve against. */
   apiBaseUrl: string
+  /** Content hash (hex SHA-256) of the component's deployed bundle, from the
+   *  component's `bundle_checksum`. The runtime appends it as `?v=` to the
+   *  bundle request so the server can mark the response immutable — the
+   *  browser then serves every later mount from its cache without a round
+   *  trip. Absent when the host does not know it yet (metadata still
+   *  loading, or a row deployed before checksum stamping); the bundle then
+   *  revalidates as before. */
+  bundleVersion?: string
+  /** Key under which the runtime shares its query cache with sibling and
+   *  successor frames of the same component through the host (same
+   *  origin): the host warms a new frame from the last state a frame with
+   *  this key left behind. Covers the slug AND the resolved props, so two
+   *  placements configured differently never share. Absent on hosts that
+   *  do not keep a store (previews, public pages). */
+  cacheKey?: string
   /** Resolved props for the component (Liquid templating happens host-side). */
   props: Record<string, unknown>
   pageCtx: PageContext
@@ -109,12 +158,51 @@ export interface ModalClosedMessage {
   result?: unknown
 }
 
+/** How a RUN_PAGE_ACTION ended, by what the button did:
+ *
+ *  - `done`        — the run went through: an action's `returns` (null when it
+ *                    returned none), a workflow's accepted `executionId`, the
+ *                    record an intent created / updated.
+ *  - `failed`      — the invocation failed and the person closed the error.
+ *  - `cancelled`   — the person stepped out before anything ran or saved.
+ *  - `handed_over` — an `agent` / `link` button: the chat or the tab is open;
+ *                    what happens there is not reported back.
+ *  - `unavailable` — nothing was opened: `invalid` (the action does not parse),
+ *                    `hidden` (its `visible_when` does not match, an intent
+ *                    has no record to act on, a link no address to open),
+ *                    `busy` (another page action is still open), `unsupported`
+ *                    (a public page, a host without page actions — a preview —
+ *                    or an agent button where there is no agent window). */
+export type PageActionOutcome =
+  | { status: 'done'; kind: 'action'; returns: Record<string, unknown> | null }
+  | { status: 'done'; kind: 'workflow'; executionId: string }
+  | {
+      status: 'done'
+      kind: 'intent'
+      mode: 'create' | 'update'
+      entitySlug: string
+      recordId: string
+      title: string
+    }
+  | { status: 'failed'; error: { code: string; message: string } }
+  | { status: 'cancelled' }
+  | { status: 'handed_over'; kind: 'agent' | 'link' }
+  | { status: 'unavailable'; reason: 'invalid' | 'hidden' | 'busy' | 'unsupported' }
+
+/** Resolution of a RUN_PAGE_ACTION request, once the run's flow is over. */
+export interface PageActionSettledMessage {
+  type: 'PAGE_ACTION_SETTLED'
+  requestId: string
+  outcome: PageActionOutcome
+}
+
 export type HostMessage =
   | InitMessage
   | AuthRefreshMessage
   | DataInvalidateMessage
   | OverlayRectMessage
   | ModalClosedMessage
+  | PageActionSettledMessage
 
 // ── Runtime → host ──────────────────────────────────────────────────────────
 
@@ -221,6 +309,92 @@ export interface ModalResultMessage {
   result?: unknown
 }
 
+/** Ask the host to open its agent session window (the floating assistant).
+ *
+ *  - `sessionId` set: the window resumes THAT session (its agent is read from
+ *    the session). A `prompt` is sent into it.
+ *  - no `sessionId`: a fresh session with `agentKey` (or the agent currently
+ *    selected in the window); a `prompt` is sent as its first message. With
+ *    neither field the window just opens as it is.
+ *
+ *  Ignored on public pages (there is no signed-in user to run an agent as). */
+export interface OpenAgentWindowMessage {
+  type: 'OPEN_AGENT_WINDOW'
+  sessionId?: string
+  agentKey?: string
+  prompt?: string
+  /** Model-only context sent with `prompt`; never rendered. */
+  context?: string
+}
+
+/** Ask the host to minimize its agent session window. The active session and
+ *  its stream stay alive — reopening resumes it. */
+export interface CloseAgentWindowMessage {
+  type: 'CLOSE_AGENT_WINDOW'
+}
+
+/** A record write the component made through its sdk (`data.records.*`)
+ *  succeeded. Posted by the runtime shell — not by component code — so the
+ *  host can refresh what it shows of that entity and, when the component
+ *  sits in a surface that reports edits (the Ava workspace), tell the agent.
+ *  `patch` is what was submitted, `record` what the server returned. */
+export interface RecordWrittenMessage {
+  type: 'RECORD_WRITTEN'
+  entitySlug: string
+  operation: 'create' | 'update' | 'delete' | 'batch_upsert'
+  recordId?: string
+  patch?: Record<string, unknown>
+  record?: Record<string, unknown>
+  /** Rows in a batch upsert. */
+  count?: number
+}
+
+/** A record a page action acts on, as the component names it. */
+export interface PageActionRecord {
+  entitySlug: string
+  recordId: string
+  /** Shown when the person picks among several records for an intent. */
+  title?: string
+  /** The entity's display name, shown beside `title` in that pick. */
+  entityName?: string
+}
+
+/** What the component knows that the button needs — layered over what the
+ *  host already knows about the page. */
+export interface PageActionContext {
+  /** Merged over the page scope (`record`, `entity`, `params`, `mode`,
+   *  `current_user`) the action's Liquid templates render against — `params`
+   *  / `inputs` prefill, `prompt`, `context`, `entity`, `record`, `url`.
+   *  Shallow: a key given here replaces the page's. `current_user` is always
+   *  the host's. */
+  scope?: Record<string, unknown>
+  /** The records the button acts on. Default: the page record (none on a page
+   *  without one).
+   *
+   *  - `action` with entity scope — the one record it is invoked on.
+   *  - `action` with entity_batch scope — every record, in ONE invocation.
+   *  - `intent` `update_record` without a `record` — the records of the
+   *    intent's entity it may update: one is updated, several are offered
+   *    to pick from. */
+  records?: PageActionRecord[]
+}
+
+/** Ask the host to run a page action — the same button a page or list toolbar
+ *  carries, defined inline by the component. The host dispatches it exactly
+ *  as a toolbar press (invoke dialog, record proposal review, agent window,
+ *  new tab) and answers PAGE_ACTION_SETTLED with the same `requestId` once
+ *  the flow is over.
+ *
+ *  One page action at a time: while one is open (from any component) the
+ *  host answers further requests `unavailable: busy`. */
+export interface RunPageActionMessage {
+  type: 'RUN_PAGE_ACTION'
+  /** Correlates the eventual PAGE_ACTION_SETTLED. Generated by the runtime. */
+  requestId: string
+  action: PageAction
+  context?: PageActionContext
+}
+
 export interface ErrorMessage {
   type: 'ERROR'
   message: string
@@ -237,6 +411,10 @@ export type RuntimeMessage =
   | OpenModalMessage
   | ModalResultMessage
   | EscapePressedMessage
+  | OpenAgentWindowMessage
+  | CloseAgentWindowMessage
+  | RecordWrittenMessage
+  | RunPageActionMessage
   | ErrorMessage
 
 // Wire envelope: the message plus the source discriminator.

package/dist/chunk-3VUWWDED.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/protocol.ts"],"names":[],"mappings":";;;AAUO,IAAM,cAAA,GAAiB;AAuBvB,IAAM,yBAAA,GAA4B;AAmNlC,SAAS,cAAc,IAAA,EAA8C;AAC1E,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD;AAEO,SAAS,iBAAiB,IAAA,EAAiD;AAChF,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD","file":"chunk-3VUWWDED.cjs","sourcesContent":["// postMessage protocol between the host page and the component-runtime iframe.\n// This is the single source of truth for the wire contract: the host renderer\n// (clients/web .../component-frame.tsx), the runtime shell\n// (clients/web/component-runtime/shell.tsx), and the author-facing hooks\n// (this package's RuntimeProvider / useNavigate) all import these same types so\n// every end stays in lockstep.\n//\n// Every message carries `source: MESSAGE_SOURCE` so we can ignore the unrelated\n// postMessage traffic that shares the window (OIDC silent-renew, Vite HMR, …).\n\nexport const MESSAGE_SOURCE = 'proteos-component-runtime' as const\n\n/**\n * z-index the component iframe is promoted to while one of its own overlays\n * (modal, popover, menu, select, tooltip) is open. The iframe goes\n * `position: fixed; inset: 0` at this z so the overlay — which portals to the\n * IFRAME's body and would otherwise clip at the frame's box — can paint over\n * the rest of the page.\n *\n * Host z ladder this slots into:\n *   50    @proteos/ui Modal / Tooltip / ImageLightbox (default tier)\n *   1000+ full-page panel stack (scrim 1000, panels 1001+n)\n *   1090  peek scrim   1100  peek panel, ask-proteos window\n *   1150  ← THIS\n *   1200  menu popover, command palette, action dialog, component modal\n *   1300  select popover\n *\n * Above the peek/full-page surfaces a component can live on, below the global\n * host chrome. Note the cap: inside a peek (a `fixed` + z-index ancestor) the\n * promoted iframe paints within that 1100 stacking context — it covers the\n * peek's own content and everything under it, but host chrome at 1200+ still\n * wins. That is the intended layering, not a bug.\n */\nexport const COMPONENT_OVERLAY_Z_INDEX = 1150\n\n/** Viewport-relative box of the iframe's in-flow placeholder, in CSS px. */\nexport interface OverlayRect {\n  top: number\n  left: number\n  width: number\n  height: number\n}\n\nexport interface PageContext {\n  record?: Record<string, unknown>\n  entity?: { slug: string; [key: string]: unknown }\n  params?: Record<string, unknown>\n  /** The signed-in viewer (absent on public pages and offline previews). The\n   *  host resolves `{{ current_user.* }}` and the bare `current_user` prop\n   *  sentinel against it before posting props. */\n  current_user?: { id: string; email: string; given_name: string; family_name: string }\n  [key: string]: unknown\n}\n\n// ── Host → runtime ──────────────────────────────────────────────────────────\n\nexport interface InitMessage {\n  type: 'INIT'\n  /** Raw bearer token (the OIDC `id_token`). The runtime's ProteosClient\n   *  prepends `Bearer ` when building the Authorization header, so the host\n   *  sends the token verbatim — NOT a full `Bearer …` header value.\n   *  Empty string in public mode (`isPublic: true`). */\n  authToken: string\n  /** API origin the bundle endpoint + SDK calls resolve against. */\n  apiBaseUrl: string\n  /** Resolved props for the component (Liquid templating happens host-side). */\n  props: Record<string, unknown>\n  pageCtx: PageContext\n  /** PUBLIC mode: the component renders on an unauthenticated public page.\n   *  The shell fetches the bundle from the public endpoint (no bearer) and\n   *  injects a restricted sdk — only `functions.actions.invokePublic` reaches\n   *  the platform. Requires `orgId`. */\n  isPublic?: boolean\n  /** Org id for public mode — public endpoints carry the org in the path\n   *  because there is no token to scope from. */\n  orgId?: string\n  /** Set when this frame is the CONTENT of a host component modal (opened by\n   *  another component via OPEN_MODAL). The component reads it through\n   *  `useModalHost()` and closes with a result by posting MODAL_RESULT with\n   *  this id. Absent on ordinary page-hosted frames. */\n  modalRequestId?: string\n}\n\nexport interface AuthRefreshMessage {\n  type: 'AUTH_REFRESH'\n  token: string\n}\n\nexport interface DataInvalidateMessage {\n  type: 'DATA_INVALIDATE'\n  queryKey?: unknown[]\n}\n\n/** Where the iframe's in-flow box sits in the host viewport. Sent while the\n *  frame is promoted (OVERLAY_STATE open) so the runtime can keep its content\n *  parked at the original rect while the iframe itself covers the viewport —\n *  and re-sent when the host window resizes under an open overlay. */\nexport interface OverlayRectMessage {\n  type: 'OVERLAY_RECT'\n  rect: OverlayRect\n}\n\n/** Resolution of an OPEN_MODAL request: the host modal closed. `result` is the\n *  value the modal's component passed to MODAL_RESULT, and is absent when the\n *  modal was dismissed (backdrop / Esc / ×). */\nexport interface ModalClosedMessage {\n  type: 'MODAL_CLOSED'\n  requestId: string\n  result?: unknown\n}\n\nexport type HostMessage =\n  | InitMessage\n  | AuthRefreshMessage\n  | DataInvalidateMessage\n  | OverlayRectMessage\n  | ModalClosedMessage\n\n// ── Runtime → host ──────────────────────────────────────────────────────────\n\nexport interface ReadyMessage {\n  type: 'READY'\n}\n\nexport interface ResizeMessage {\n  type: 'RESIZE'\n  height: number\n}\n\nexport interface NavigateMessage {\n  type: 'NAVIGATE'\n  to: string\n}\n\n/** Open an in-app path in a peek (slide-over) panel instead of full-page\n *  navigation. Same `/…` in-app path grammar as NAVIGATE; the host decides\n *  what can peek (today: platform pages) and falls back to NAVIGATE otherwise. */\nexport interface OpenPeekMessage {\n  type: 'OPEN_PEEK'\n  to: string\n}\n\n/** Ask the host to open a prepared call: the host shows the conversation brief's\n *  preview (its softphone owns the dial) and lets the user place the call.\n *  Ignored on public pages and on hosts without a softphone. */\nexport interface OpenCallMessage {\n  type: 'OPEN_CALL'\n  /** The conversation brief to preview and dial from. */\n  conversationBriefId: string\n}\n\n/** The runtime has (or no longer has) an overlay open and needs the host to\n *  promote (or restore) the iframe. See {@link COMPONENT_OVERLAY_Z_INDEX}.\n *\n *  Same-origin today, so the runtime applies the promotion styles to its own\n *  `window.frameElement` synchronously (pre-paint, no flicker) and this message\n *  is the host's cue to MIRROR that state into React — gate RESIZE, hold the\n *  placeholder height, start posting OVERLAY_RECT. When components move to a\n *  dedicated origin the runtime can no longer touch the frame and this message\n *  becomes the actuation instead; the runtime hides its overlay until the\n *  answering OVERLAY_RECT arrives. */\nexport interface OverlayStateMessage {\n  type: 'OVERLAY_STATE'\n  open: boolean\n}\n\n/** Width of a host component modal's panel: `sm` 384px, `md` 512px, `lg` 672px,\n *  `xl` 896px. Below 640px the modal is a full-screen sheet whatever the\n *  width. */\nexport type ModalWidth = 'sm' | 'md' | 'lg' | 'xl'\n\n/** Ask the host to open ANOTHER component in a central modal, above everything\n *  this frame could reach on its own. The host answers with MODAL_CLOSED\n *  carrying the same `requestId`.\n *\n *  One modal per opener at a time: while a request from this frame is still\n *  open, the host answers any further OPEN_MODAL from it as dismissed (a\n *  double click must not stack two dialogs). The modal's own component may\n *  open another — that request comes from a different frame. */\nexport interface OpenModalMessage {\n  type: 'OPEN_MODAL'\n  /** Correlates the eventual MODAL_CLOSED. Generated by the opener. */\n  requestId: string\n  /** Slug of the component to mount inside the modal. */\n  componentSlug: string\n  /** Props for that component. The host renders Liquid in every string value\n   *  against the OPENER's page scope (`record`, `entity`, `params`,\n   *  `current_user`) before handing them over — exactly as it does for a\n   *  page-placed component. So `{{ … }}` / `{% … %}` in a value is evaluated,\n   *  not passed through. */\n  props?: Record<string, unknown>\n  /** Optional modal heading. */\n  title?: string\n  /** Panel width. Defaults to `lg`. */\n  width?: ModalWidth\n  /** Height of the component's frame, in px. Set: the frame is that tall from\n   *  the first paint (capped at the viewport), scrolls its own content, and\n   *  sits edge to edge in the panel — the component owns its padding. Unset:\n   *  the frame grows with its content inside the host's padded body. */\n  height?: number\n}\n\n/** Escape was pressed with focus inside the iframe, and nothing in the runtime\n *  consumed it.\n *\n *  Keyboard events don't cross the iframe boundary, and react-aria binds its\n *  Escape handling to the overlay element in its own React tree — so a\n *  host-rendered dialog CANNOT see Escape once the user has clicked into a\n *  component. The runtime forwards it so the host can dismiss on the user's\n *  behalf. Not sent while the runtime has its own overlay open: that overlay\n *  owns Escape. */\nexport interface EscapePressedMessage {\n  type: 'ESCAPE_PRESSED'\n}\n\n/** Posted by the component INSIDE a host modal to close it with a value. The\n *  `requestId` is the one INIT carried as `modalRequestId`. */\nexport interface ModalResultMessage {\n  type: 'MODAL_RESULT'\n  requestId: string\n  result?: unknown\n}\n\nexport interface ErrorMessage {\n  type: 'ERROR'\n  message: string\n  stack?: string\n}\n\nexport type RuntimeMessage =\n  | ReadyMessage\n  | ResizeMessage\n  | NavigateMessage\n  | OpenPeekMessage\n  | OpenCallMessage\n  | OverlayStateMessage\n  | OpenModalMessage\n  | ModalResultMessage\n  | EscapePressedMessage\n  | ErrorMessage\n\n// Wire envelope: the message plus the source discriminator.\nexport type Envelope<T> = T & { source: typeof MESSAGE_SOURCE }\n\nexport function isHostMessage(data: unknown): data is Envelope<HostMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n\nexport function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n"]}

package/dist/chunk-HODSL6ER.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/protocol.ts"],"names":[],"mappings":";AAUO,IAAM,cAAA,GAAiB;AAuBvB,IAAM,yBAAA,GAA4B;AAmNlC,SAAS,cAAc,IAAA,EAA8C;AAC1E,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD;AAEO,SAAS,iBAAiB,IAAA,EAAiD;AAChF,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD","file":"chunk-HODSL6ER.js","sourcesContent":["// postMessage protocol between the host page and the component-runtime iframe.\n// This is the single source of truth for the wire contract: the host renderer\n// (clients/web .../component-frame.tsx), the runtime shell\n// (clients/web/component-runtime/shell.tsx), and the author-facing hooks\n// (this package's RuntimeProvider / useNavigate) all import these same types so\n// every end stays in lockstep.\n//\n// Every message carries `source: MESSAGE_SOURCE` so we can ignore the unrelated\n// postMessage traffic that shares the window (OIDC silent-renew, Vite HMR, …).\n\nexport const MESSAGE_SOURCE = 'proteos-component-runtime' as const\n\n/**\n * z-index the component iframe is promoted to while one of its own overlays\n * (modal, popover, menu, select, tooltip) is open. The iframe goes\n * `position: fixed; inset: 0` at this z so the overlay — which portals to the\n * IFRAME's body and would otherwise clip at the frame's box — can paint over\n * the rest of the page.\n *\n * Host z ladder this slots into:\n *   50    @proteos/ui Modal / Tooltip / ImageLightbox (default tier)\n *   1000+ full-page panel stack (scrim 1000, panels 1001+n)\n *   1090  peek scrim   1100  peek panel, ask-proteos window\n *   1150  ← THIS\n *   1200  menu popover, command palette, action dialog, component modal\n *   1300  select popover\n *\n * Above the peek/full-page surfaces a component can live on, below the global\n * host chrome. Note the cap: inside a peek (a `fixed` + z-index ancestor) the\n * promoted iframe paints within that 1100 stacking context — it covers the\n * peek's own content and everything under it, but host chrome at 1200+ still\n * wins. That is the intended layering, not a bug.\n */\nexport const COMPONENT_OVERLAY_Z_INDEX = 1150\n\n/** Viewport-relative box of the iframe's in-flow placeholder, in CSS px. */\nexport interface OverlayRect {\n  top: number\n  left: number\n  width: number\n  height: number\n}\n\nexport interface PageContext {\n  record?: Record<string, unknown>\n  entity?: { slug: string; [key: string]: unknown }\n  params?: Record<string, unknown>\n  /** The signed-in viewer (absent on public pages and offline previews). The\n   *  host resolves `{{ current_user.* }}` and the bare `current_user` prop\n   *  sentinel against it before posting props. */\n  current_user?: { id: string; email: string; given_name: string; family_name: string }\n  [key: string]: unknown\n}\n\n// ── Host → runtime ──────────────────────────────────────────────────────────\n\nexport interface InitMessage {\n  type: 'INIT'\n  /** Raw bearer token (the OIDC `id_token`). The runtime's ProteosClient\n   *  prepends `Bearer ` when building the Authorization header, so the host\n   *  sends the token verbatim — NOT a full `Bearer …` header value.\n   *  Empty string in public mode (`isPublic: true`). */\n  authToken: string\n  /** API origin the bundle endpoint + SDK calls resolve against. */\n  apiBaseUrl: string\n  /** Resolved props for the component (Liquid templating happens host-side). */\n  props: Record<string, unknown>\n  pageCtx: PageContext\n  /** PUBLIC mode: the component renders on an unauthenticated public page.\n   *  The shell fetches the bundle from the public endpoint (no bearer) and\n   *  injects a restricted sdk — only `functions.actions.invokePublic` reaches\n   *  the platform. Requires `orgId`. */\n  isPublic?: boolean\n  /** Org id for public mode — public endpoints carry the org in the path\n   *  because there is no token to scope from. */\n  orgId?: string\n  /** Set when this frame is the CONTENT of a host component modal (opened by\n   *  another component via OPEN_MODAL). The component reads it through\n   *  `useModalHost()` and closes with a result by posting MODAL_RESULT with\n   *  this id. Absent on ordinary page-hosted frames. */\n  modalRequestId?: string\n}\n\nexport interface AuthRefreshMessage {\n  type: 'AUTH_REFRESH'\n  token: string\n}\n\nexport interface DataInvalidateMessage {\n  type: 'DATA_INVALIDATE'\n  queryKey?: unknown[]\n}\n\n/** Where the iframe's in-flow box sits in the host viewport. Sent while the\n *  frame is promoted (OVERLAY_STATE open) so the runtime can keep its content\n *  parked at the original rect while the iframe itself covers the viewport —\n *  and re-sent when the host window resizes under an open overlay. */\nexport interface OverlayRectMessage {\n  type: 'OVERLAY_RECT'\n  rect: OverlayRect\n}\n\n/** Resolution of an OPEN_MODAL request: the host modal closed. `result` is the\n *  value the modal's component passed to MODAL_RESULT, and is absent when the\n *  modal was dismissed (backdrop / Esc / ×). */\nexport interface ModalClosedMessage {\n  type: 'MODAL_CLOSED'\n  requestId: string\n  result?: unknown\n}\n\nexport type HostMessage =\n  | InitMessage\n  | AuthRefreshMessage\n  | DataInvalidateMessage\n  | OverlayRectMessage\n  | ModalClosedMessage\n\n// ── Runtime → host ──────────────────────────────────────────────────────────\n\nexport interface ReadyMessage {\n  type: 'READY'\n}\n\nexport interface ResizeMessage {\n  type: 'RESIZE'\n  height: number\n}\n\nexport interface NavigateMessage {\n  type: 'NAVIGATE'\n  to: string\n}\n\n/** Open an in-app path in a peek (slide-over) panel instead of full-page\n *  navigation. Same `/…` in-app path grammar as NAVIGATE; the host decides\n *  what can peek (today: platform pages) and falls back to NAVIGATE otherwise. */\nexport interface OpenPeekMessage {\n  type: 'OPEN_PEEK'\n  to: string\n}\n\n/** Ask the host to open a prepared call: the host shows the conversation brief's\n *  preview (its softphone owns the dial) and lets the user place the call.\n *  Ignored on public pages and on hosts without a softphone. */\nexport interface OpenCallMessage {\n  type: 'OPEN_CALL'\n  /** The conversation brief to preview and dial from. */\n  conversationBriefId: string\n}\n\n/** The runtime has (or no longer has) an overlay open and needs the host to\n *  promote (or restore) the iframe. See {@link COMPONENT_OVERLAY_Z_INDEX}.\n *\n *  Same-origin today, so the runtime applies the promotion styles to its own\n *  `window.frameElement` synchronously (pre-paint, no flicker) and this message\n *  is the host's cue to MIRROR that state into React — gate RESIZE, hold the\n *  placeholder height, start posting OVERLAY_RECT. When components move to a\n *  dedicated origin the runtime can no longer touch the frame and this message\n *  becomes the actuation instead; the runtime hides its overlay until the\n *  answering OVERLAY_RECT arrives. */\nexport interface OverlayStateMessage {\n  type: 'OVERLAY_STATE'\n  open: boolean\n}\n\n/** Width of a host component modal's panel: `sm` 384px, `md` 512px, `lg` 672px,\n *  `xl` 896px. Below 640px the modal is a full-screen sheet whatever the\n *  width. */\nexport type ModalWidth = 'sm' | 'md' | 'lg' | 'xl'\n\n/** Ask the host to open ANOTHER component in a central modal, above everything\n *  this frame could reach on its own. The host answers with MODAL_CLOSED\n *  carrying the same `requestId`.\n *\n *  One modal per opener at a time: while a request from this frame is still\n *  open, the host answers any further OPEN_MODAL from it as dismissed (a\n *  double click must not stack two dialogs). The modal's own component may\n *  open another — that request comes from a different frame. */\nexport interface OpenModalMessage {\n  type: 'OPEN_MODAL'\n  /** Correlates the eventual MODAL_CLOSED. Generated by the opener. */\n  requestId: string\n  /** Slug of the component to mount inside the modal. */\n  componentSlug: string\n  /** Props for that component. The host renders Liquid in every string value\n   *  against the OPENER's page scope (`record`, `entity`, `params`,\n   *  `current_user`) before handing them over — exactly as it does for a\n   *  page-placed component. So `{{ … }}` / `{% … %}` in a value is evaluated,\n   *  not passed through. */\n  props?: Record<string, unknown>\n  /** Optional modal heading. */\n  title?: string\n  /** Panel width. Defaults to `lg`. */\n  width?: ModalWidth\n  /** Height of the component's frame, in px. Set: the frame is that tall from\n   *  the first paint (capped at the viewport), scrolls its own content, and\n   *  sits edge to edge in the panel — the component owns its padding. Unset:\n   *  the frame grows with its content inside the host's padded body. */\n  height?: number\n}\n\n/** Escape was pressed with focus inside the iframe, and nothing in the runtime\n *  consumed it.\n *\n *  Keyboard events don't cross the iframe boundary, and react-aria binds its\n *  Escape handling to the overlay element in its own React tree — so a\n *  host-rendered dialog CANNOT see Escape once the user has clicked into a\n *  component. The runtime forwards it so the host can dismiss on the user's\n *  behalf. Not sent while the runtime has its own overlay open: that overlay\n *  owns Escape. */\nexport interface EscapePressedMessage {\n  type: 'ESCAPE_PRESSED'\n}\n\n/** Posted by the component INSIDE a host modal to close it with a value. The\n *  `requestId` is the one INIT carried as `modalRequestId`. */\nexport interface ModalResultMessage {\n  type: 'MODAL_RESULT'\n  requestId: string\n  result?: unknown\n}\n\nexport interface ErrorMessage {\n  type: 'ERROR'\n  message: string\n  stack?: string\n}\n\nexport type RuntimeMessage =\n  | ReadyMessage\n  | ResizeMessage\n  | NavigateMessage\n  | OpenPeekMessage\n  | OpenCallMessage\n  | OverlayStateMessage\n  | OpenModalMessage\n  | ModalResultMessage\n  | EscapePressedMessage\n  | ErrorMessage\n\n// Wire envelope: the message plus the source discriminator.\nexport type Envelope<T> = T & { source: typeof MESSAGE_SOURCE }\n\nexport function isHostMessage(data: unknown): data is Envelope<HostMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n\nexport function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n"]}