@proteos/component-sdk 0.61.0 → 0.75.0

package/dist/protocol.d.ts

@@ -1,3 +1,5 @@
+import { PageAction } from '@proteos/sdk';
+
 declare const MESSAGE_SOURCE: "proteos-component-runtime";
 /**
  * z-index the component iframe is promoted to while one of its own overlays
@@ -28,6 +30,34 @@ interface OverlayRect {
     width: number;
     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. */
+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`. */
+type TriggerPhase = 'input' | 'running' | 'result';
 interface PageContext {
     record?: Record<string, unknown>;
     entity?: {
@@ -35,6 +65,8 @@ interface PageContext {
         [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. */
@@ -55,6 +87,21 @@ 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;
@@ -96,7 +143,58 @@ interface ModalClosedMessage {
     requestId: string;
     result?: unknown;
 }
-type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage | OverlayRectMessage | ModalClosedMessage;
+/** 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). */
+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. */
+interface PageActionSettledMessage {
+    type: 'PAGE_ACTION_SETTLED';
+    requestId: string;
+    outcome: PageActionOutcome;
+}
+type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage | OverlayRectMessage | ModalClosedMessage | PageActionSettledMessage;
 interface ReadyMessage {
     type: 'READY';
 }
@@ -204,22 +302,82 @@ interface OpenAgentWindowMessage {
     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. */
 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. */
+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. */
+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. */
+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`. */
+interface RunPageActionMessage {
+    type: 'RUN_PAGE_ACTION';
+    /** Correlates the eventual PAGE_ACTION_SETTLED. Generated by the runtime. */
+    requestId: string;
+    action: PageAction;
+    context?: PageActionContext;
+}
 interface ErrorMessage {
     type: 'ERROR';
     message: string;
     stack?: string;
 }
-type RuntimeMessage = ReadyMessage | ResizeMessage | NavigateMessage | OpenPeekMessage | OpenCallMessage | OverlayStateMessage | OpenModalMessage | ModalResultMessage | EscapePressedMessage | OpenAgentWindowMessage | CloseAgentWindowMessage | ErrorMessage;
+type RuntimeMessage = ReadyMessage | ResizeMessage | NavigateMessage | OpenPeekMessage | OpenCallMessage | OverlayStateMessage | OpenModalMessage | ModalResultMessage | EscapePressedMessage | OpenAgentWindowMessage | CloseAgentWindowMessage | RecordWrittenMessage | RunPageActionMessage | 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, COMPONENT_OVERLAY_Z_INDEX, type CloseAgentWindowMessage, type DataInvalidateMessage, type Envelope, type ErrorMessage, type EscapePressedMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type ModalClosedMessage, type ModalResultMessage, type ModalWidth, type NavigateMessage, type OpenAgentWindowMessage, type OpenCallMessage, type OpenModalMessage, type OpenPeekMessage, type OverlayRect, type OverlayRectMessage, type OverlayStateMessage, type PageContext, type ReadyMessage, type ResizeMessage, type RuntimeMessage, isHostMessage, isRuntimeMessage };
+export { type AuthRefreshMessage, COMPONENT_OVERLAY_Z_INDEX, type CloseAgentWindowMessage, type DataInvalidateMessage, type Envelope, type ErrorMessage, type EscapePressedMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type ModalClosedMessage, type ModalResultMessage, type ModalWidth, type NavigateMessage, type OpenAgentWindowMessage, type OpenCallMessage, type OpenModalMessage, type OpenPeekMessage, type OverlayRect, type OverlayRectMessage, type OverlayStateMessage, type PageActionContext, type PageActionOutcome, type PageActionRecord, type PageActionSettledMessage, type PageContext, type PageMode, type ReadyMessage, type RecordWrittenMessage, type ResizeMessage, type RunPageActionMessage, type RuntimeMessage, type TriggerPhase, isHostMessage, isRuntimeMessage };

package/dist/protocol.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/component-sdk",
-  "version": "0.61.0",
+  "version": "0.75.0",
   "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.61.0"
+    "@proteos/sdk": "^0.75.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",

package/src/context.tsx

@@ -6,6 +6,7 @@ import type {
   FunctionsClient,
   KnowledgeClient,
   MetaClient,
+  PageAction,
   StorageClient,
 } from '@proteos/sdk'
 import { createContext, type ReactNode, useMemo } from 'react'
@@ -22,7 +23,10 @@ import {
   type OpenCallMessage,
   type OpenModalMessage,
   type OpenPeekMessage,
+  type PageActionContext,
+  type PageActionOutcome,
   type PageContext,
+  type RunPageActionMessage,
 } from './protocol'
 
 /** Options for {@link RuntimeContextValue.navigate}. */
@@ -58,6 +62,10 @@ export interface OpenAgentWindowOptions {
   /** A message to send — into the resumed session, or as the first message
    *  of the fresh one. */
   prompt?: string
+  /** Context handed to the model alongside `prompt` (what the component knows:
+   *  the record on screen, a selection …). Read by the model, never shown in
+   *  the chat; sent only together with a `prompt`. Not for secrets. */
+  context?: string
 }
 
 /**
@@ -158,6 +166,9 @@ export interface RuntimeContextValue extends RuntimeValue {
   /** Open / minimize the host's agent session window (posts OPEN_AGENT_WINDOW
    *  / CLOSE_AGENT_WINDOW). */
   agentWindow: AgentWindowController
+  /** Run a page action defined inline (posts RUN_PAGE_ACTION); resolves with
+   *  how its flow ended. */
+  runPageAction: (action: PageAction, context?: PageActionContext) => Promise<PageActionOutcome>
 }
 
 export const RuntimeContext = createContext<RuntimeContextValue | null>(null)
@@ -194,6 +205,7 @@ function openAgentWindow(options?: OpenAgentWindowOptions): void {
     ...(options?.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
     ...(options?.agentKey !== undefined ? { agentKey: options.agentKey } : {}),
     ...(options?.prompt !== undefined ? { prompt: options.prompt } : {}),
+    ...(options?.context !== undefined ? { context: options.context } : {}),
   }
   window.parent?.postMessage(envelope, '*')
 }
@@ -215,24 +227,35 @@ 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.
+// ── Host requests (component modals, page actions) ──────────────────────────
+// One module-level listener + a pending map per request kind, 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
+const pendingPageActions = new Map<string, (outcome: PageActionOutcome) => void>()
+let replyListenerAttached = false
 
-function ensureModalListener(): void {
-  if (modalListenerAttached) return
-  modalListenerAttached = true
+function ensureReplyListener(): void {
+  if (replyListenerAttached) return
+  replyListenerAttached = 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)
+    if (!isHostMessage(data)) return
+    // An unknown requestId is someone else's request (or a stale reply) — drop it.
+    if (data.type === 'MODAL_CLOSED') {
+      const resolve = pendingModals.get(data.requestId)
+      if (!resolve) return
+      pendingModals.delete(data.requestId)
+      resolve(data.result)
+      return
+    }
+    if (data.type === 'PAGE_ACTION_SETTLED') {
+      const resolve = pendingPageActions.get(data.requestId)
+      if (!resolve) return
+      pendingPageActions.delete(data.requestId)
+      resolve(data.outcome)
+    }
   })
 }
 
@@ -275,7 +298,7 @@ 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)}`
+  return `request_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
 }
 
 /** Post OPEN_MODAL and resolve when the host answers MODAL_CLOSED. */
@@ -284,7 +307,7 @@ function openModal(
   props?: Record<string, unknown>,
   options?: OpenModalOptions,
 ): Promise<unknown> {
-  ensureModalListener()
+  ensureReplyListener()
   const requestId = newRequestId()
   const envelope: Envelope<OpenModalMessage> = {
     source: MESSAGE_SOURCE,
@@ -306,6 +329,32 @@ function openModal(
   })
 }
 
+/** Post RUN_PAGE_ACTION and resolve when the host answers PAGE_ACTION_SETTLED.
+ *  The host's dialogs take focus, so it goes back to the pressed control
+ *  afterwards — as for a modal. */
+function runPageAction(
+  action: PageAction,
+  context?: PageActionContext,
+): Promise<PageActionOutcome> {
+  ensureReplyListener()
+  const requestId = newRequestId()
+  const envelope: Envelope<RunPageActionMessage> = {
+    source: MESSAGE_SOURCE,
+    type: 'RUN_PAGE_ACTION',
+    requestId,
+    action,
+    ...(context !== undefined ? { context } : {}),
+  }
+  const opener = document.activeElement instanceof HTMLElement ? document.activeElement : null
+  return new Promise<PageActionOutcome>((resolve) => {
+    pendingPageActions.set(requestId, (outcome) => {
+      restoreFocus(opener)
+      resolve(outcome)
+    })
+    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> = {
@@ -329,7 +378,7 @@ export function RuntimeProvider({ value, children }: { value: RuntimeValue; chil
   // 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, openCall, openModal, agentWindow }),
+    () => ({ ...value, navigate, openCall, openModal, agentWindow, runPageAction }),
     [value],
   )
   return <RuntimeContext.Provider value={ctx}>{children}</RuntimeContext.Provider>

package/src/hooks.test.tsx

@@ -10,12 +10,18 @@ import {
   useModalHost,
   useNavigate,
   useOverlayExpansion,
+  usePageAction,
   usePageContext,
   useProps,
   useRuntime,
   useSdk,
 } from './hooks'
-import { type Envelope, MESSAGE_SOURCE, type ModalClosedMessage } from './protocol'
+import {
+  type Envelope,
+  MESSAGE_SOURCE,
+  type ModalClosedMessage,
+  type PageActionSettledMessage,
+} from './protocol'
 
 // A stable stand-in for the injected SDK — the hooks only pass it through.
 const sdk = {} as RuntimeValue['sdk']
@@ -24,7 +30,7 @@ function makeValue(overrides: Partial<RuntimeValue> = {}): RuntimeValue {
   return {
     sdk,
     props: { title: 'Hello' },
-    pageCtx: { record: { id: 'rec_1', name: 'ACME' }, entity: { slug: 'company' } },
+    pageCtx: { record: { id: 'rec_1', name: 'ACME' }, entity: { slug: 'company' }, mode: 'view' },
     apiBaseUrl: 'https://api.test',
     getToken: () => 'tok_123',
     ...overrides,
@@ -57,11 +63,12 @@ describe('runtime hooks', () => {
     expect(result.current.props.title).toBe('Hello')
     expect(result.current.ctx.record).toEqual({ id: 'rec_1', name: 'ACME' })
     expect(result.current.ctx.entity?.slug).toBe('company')
+    expect(result.current.ctx.mode).toBe('view')
     expect(result.current.base).toBe('https://api.test')
   })
 
   it('usePageContext().record is undefined when the page has no bound record', () => {
-    const value = makeValue({ pageCtx: { entity: { slug: 'dashboard' } } })
+    const value = makeValue({ pageCtx: { entity: { slug: 'dashboard' }, mode: 'view' } })
     const { result } = renderHook(() => usePageContext(), { wrapper: wrapper(value) })
     expect(result.current.record).toBeUndefined()
   })
@@ -103,6 +110,18 @@ describe('runtime hooks', () => {
       '*',
     )
 
+    result.current.open({ agentKey: 'sales-bot', prompt: 'Follow up', context: 'Deal #7' })
+    expect(post).toHaveBeenLastCalledWith(
+      {
+        source: MESSAGE_SOURCE,
+        type: 'OPEN_AGENT_WINDOW',
+        agentKey: 'sales-bot',
+        prompt: 'Follow up',
+        context: 'Deal #7',
+      },
+      '*',
+    )
+
     result.current.close()
     expect(post).toHaveBeenLastCalledWith(
       { source: MESSAGE_SOURCE, type: 'CLOSE_AGENT_WINDOW' },
@@ -188,6 +207,65 @@ describe('runtime hooks', () => {
     opener.remove()
   })
 
+  it('usePageAction posts RUN_PAGE_ACTION and resolves with the matching outcome', async () => {
+    const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
+    const { result } = renderHook(() => usePageAction(), { wrapper: wrapper(makeValue()) })
+    const action = {
+      kind: 'intent' as const,
+      intent: 'update_record' as const,
+      entity: 'deal',
+      label: 'Update deal',
+      icon: 'Sparkles',
+      prompt: 'Apply what was agreed',
+    }
+
+    const pending = result.current(action, {
+      scope: { notes: 'Signed' },
+      records: [{ entitySlug: 'deal', recordId: 'deal_1' }],
+    })
+    const [payload] = post.mock.calls.at(-1) as [Record<string, unknown>]
+    expect(payload).toMatchObject({
+      source: MESSAGE_SOURCE,
+      type: 'RUN_PAGE_ACTION',
+      action,
+      context: {
+        scope: { notes: 'Signed' },
+        records: [{ entitySlug: 'deal', recordId: 'deal_1' }],
+      },
+    })
+
+    const reply = (requestId: string): Envelope<PageActionSettledMessage> => ({
+      source: MESSAGE_SOURCE,
+      type: 'PAGE_ACTION_SETTLED',
+      requestId,
+      outcome: {
+        status: 'done',
+        kind: 'intent',
+        mode: 'update',
+        entitySlug: 'deal',
+        recordId: 'deal_1',
+        title: 'Acme renewal',
+      },
+    })
+    // Another request's reply — and a modal's with our id — must not resolve ours.
+    window.dispatchEvent(new MessageEvent('message', { data: reply('someone-else') }))
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: { source: MESSAGE_SOURCE, type: 'MODAL_CLOSED', requestId: payload.requestId },
+      }),
+    )
+    window.dispatchEvent(new MessageEvent('message', { data: reply(payload.requestId as string) }))
+    await expect(pending).resolves.toMatchObject({ status: 'done', recordId: 'deal_1' })
+  })
+
+  it('usePageAction leaves out a context it was not given', () => {
+    const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
+    const { result } = renderHook(() => usePageAction(), { wrapper: wrapper(makeValue()) })
+    void result.current({ kind: 'link', url: 'https://example.com', label: 'Open', icon: 'Link' })
+    const [payload] = post.mock.calls.at(-1) as [Record<string, unknown>]
+    expect(payload).not.toHaveProperty('context')
+  })
+
   it('useComponentModal carries the width and height the opener asked for', () => {
     const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
     const { result } = renderHook(() => useComponentModal(), { wrapper: wrapper(makeValue()) })

package/src/hooks.ts

@@ -1,3 +1,4 @@
+import type { PageAction } from '@proteos/sdk'
 import { useCallback, useContext, useEffect, useMemo, useState } from 'react'
 
 import {
@@ -10,7 +11,7 @@ import {
   RuntimeContext,
   type RuntimeContextValue,
 } from './context'
-import type { PageContext } from './protocol'
+import type { PageActionContext, PageActionOutcome, PageContext } from './protocol'
 
 /**
  * Low-level escape hatch: the whole runtime context (sdk, props, pageCtx,
@@ -41,9 +42,13 @@ export function useProps<T extends Record<string, unknown> = Record<string, unkn
 }
 
 /**
- * The full page context: host `record`, `entity`, and URL `params`. The
- * `record` is a snapshot taken at mount (`undefined` on record-less platform
- * pages) — fetch via `useSdk().data` for anything that must stay fresh.
+ * The full page context: host `record`, `entity`, URL `params`, the viewer as
+ * `current_user` (absent on public pages) and the page `mode`
+ * (`'view' | 'create' | 'edit'` — what the viewer is doing with the record).
+ * The `record` is a snapshot taken at mount (`undefined` on record-less
+ * platform pages) — fetch via `useSdk().data` for anything that must stay
+ * fresh. `mode` is a snapshot too: the host remounts the frame when the page
+ * switches between view and edit.
  */
 export function usePageContext(): PageContext {
   return useRuntime().pageCtx
@@ -156,6 +161,45 @@ export function useComponentModal(): (
   return useRuntime().openModal
 }
 
+/**
+ * Run a page action from a component's own button — the very `PageAction` a
+ * page or list toolbar carries, defined inline. The HOST runs it exactly as a
+ * toolbar press: `action` / `workflow` open the invoke dialog, `intent`
+ * prepares a record proposal for review, `agent` opens the agent window,
+ * `link` opens a new tab. Resolves once that flow is over.
+ *
+ * ```ts
+ * const runPageAction = usePageAction()
+ * const outcome = await runPageAction(
+ *   {
+ *     kind: 'intent',
+ *     intent: 'update_record',
+ *     entity: 'deal',
+ *     label: 'Update deal',
+ *     icon: 'Sparkles',
+ *     prompt: 'Apply what was agreed',
+ *     context: '{{ notes }}',
+ *   },
+ *   { scope: { notes }, records: [{ entitySlug: 'deal', recordId: deal.id }] },
+ * )
+ * if (outcome.status === 'done' && outcome.kind === 'intent') refetch()
+ * ```
+ *
+ * The action's Liquid templates render against the page scope (`record`,
+ * `entity`, `params`, `mode`, `current_user`) with `context.scope` merged over
+ * it; `context.records` says what it acts on (default: the page record). See
+ * {@link PageActionContext} and {@link PageActionOutcome}. `visible_when`
+ * still applies — an action whose rule does not match resolves
+ * `unavailable: hidden` without opening anything. One page action at a time;
+ * public pages and previews resolve `unavailable: unsupported`.
+ */
+export function usePageAction(): (
+  action: PageAction,
+  context?: PageActionContext,
+) => Promise<PageActionOutcome> {
+  return useRuntime().runPageAction
+}
+
 export interface ModalHost {
   /** True when this component is rendered as the content of a host modal. */
   isInModal: boolean

package/src/index.ts

@@ -30,6 +30,7 @@ export {
   useNavigate,
   useOpenCall,
   useOverlayExpansion,
+  usePageAction,
   usePageContext,
   useProps,
   useRuntime,
@@ -59,8 +60,15 @@ export {
   type OverlayRect,
   type OverlayRectMessage,
   type OverlayStateMessage,
+  type PageActionContext,
+  type PageActionOutcome,
+  type PageActionRecord,
+  type PageActionSettledMessage,
   type PageContext,
+  type PageMode,
   type ReadyMessage,
   type ResizeMessage,
+  type RunPageActionMessage,
   type RuntimeMessage,
+  type TriggerPhase,
 } from './protocol'