@proteos/component-sdk 0.60.0 → 0.75.0

package/dist/protocol.d.cts

@@ -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';
 }
@@ -190,16 +288,96 @@ interface ModalResultMessage {
     requestId: string;
     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). */
+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. */
+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 | 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 DataInvalidateMessage, type Envelope, type ErrorMessage, type EscapePressedMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type ModalClosedMessage, type ModalResultMessage, type ModalWidth, type NavigateMessage, 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.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';
 }
@@ -190,16 +288,96 @@ interface ModalResultMessage {
     requestId: string;
     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). */
+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. */
+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 | 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 DataInvalidateMessage, type Envelope, type ErrorMessage, type EscapePressedMessage, type HostMessage, type InitMessage, MESSAGE_SOURCE, type ModalClosedMessage, type ModalResultMessage, type ModalWidth, type NavigateMessage, 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-HODSL6ER.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.60.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.60.0"
+    "@proteos/sdk": "^0.75.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",