@ggui-ai/iframe-runtime 0.25.0 → 0.27.0

package/dist/stream-seq.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The view's stream cursor (ggui#1496, rev 2.4).
+ *
+ * `StreamEnvelope.seq` is session-scoped and gap-free, and stream delivery
+ * is at-least-once, so the view applies a stamped envelope only when its
+ * `seq` is above the highest one it has applied. That highest `seq` is
+ * also where a new subscribe resumes the stream from
+ * (`SubscribePayload.fromSeq`). An unstamped envelope (a deployment with no
+ * stream buffer) is single-shot and always passes, and it moves nothing.
+ *
+ * A server's counter can restart (a process restart, an in-memory buffer, a
+ * stored counter that expired), after which its `seq` starts over below the
+ * view's cursor and every new envelope would be dropped. The ack reveals
+ * it: its `streamSeq` is the server's current counter, and a monotonic
+ * counter can never be below a `seq` this view applied. So an ack whose
+ * `streamSeq` is lower means the counter restarted, and the cursor is
+ * forgotten.
+ *
+ * That numeric test misses a counter that restarted and has already
+ * climbed past the cursor before the next ack. The stream EPOCH closes it
+ * (ggui#1531): the server names each counter generation, on every stamped
+ * envelope and on the ack, and a different epoch means a new generation
+ * whatever the numbers say, so the cursor resets to nothing applied. A
+ * missing epoch (a server, or an envelope, from before epochs) is
+ * unknown, never a mismatch: the `seq` rule alone decides, and a first
+ * epoch after unknown history is adopted without a reset.
+ *
+ * The cursor never moves back to an epoch it has left: it remembers the
+ * last {@link LEFT_EPOCHS_KEPT}, and drops their frames and ignores their
+ * acks. Otherwise a late frame of the old generation (a cross-replica frame
+ * published just before the restart) would move it back with nothing
+ * applied, and the next frame of the new one would move it forward again
+ * with an empty floor, letting a duplicate through. The server keeps the
+ * same rule (SPEC §12.2.1 invariant 4).
+ */
+export interface StreamSeqTracker {
+    /**
+     * Whether to apply an envelope with this `seq` and `streamEpoch`; records
+     * it when so. An envelope from a different epoch first resets the cursor.
+     */
+    admit(seq: number | undefined, epoch?: string): boolean;
+    /** The highest `seq` applied so far; `undefined` before the first stamped envelope. */
+    last(): number | undefined;
+    /** The counter generation the cursor belongs to; `undefined` until one is seen. */
+    epoch(): string | undefined;
+    /**
+     * An ack's stream position (`AckPayload.streamSeq`, `AckPayload.streamEpoch`).
+     * A different epoch, or a `streamSeq` below the highest applied `seq`,
+     * means the counter restarted: the cursor is forgotten, and `true` says
+     * so.
+     */
+    observeAck(streamSeq: number | undefined, streamEpoch: string | undefined): boolean;
+}
+/** How many epochs the cursor remembers having left; the server keeps as many. */
+export declare const LEFT_EPOCHS_KEPT = 4;
+export declare function createStreamSeqTracker(): StreamSeqTracker;

package/dist/stream-seq.js

@@ -0,0 +1,46 @@
+/** How many epochs the cursor remembers having left; the server keeps as many. */
+export const LEFT_EPOCHS_KEPT = 4;
+export function createStreamSeqTracker() {
+    let highest;
+    let current;
+    let left = [];
+    const hasLeft = (epoch) => epoch !== undefined && left.includes(epoch);
+    /** Adopt `epoch`; a different known epoch resets the cursor. Returns whether it reset. */
+    const meetEpoch = (epoch) => {
+        if (epoch === undefined)
+            return false;
+        const from = current;
+        const changed = from !== undefined && epoch !== from;
+        current = epoch;
+        if (changed) {
+            left = [...left, from].slice(-LEFT_EPOCHS_KEPT);
+            highest = undefined;
+        }
+        return changed;
+    };
+    return {
+        admit(seq, epoch) {
+            if (seq === undefined)
+                return true;
+            if (hasLeft(epoch))
+                return false;
+            meetEpoch(epoch);
+            if (highest !== undefined && seq <= highest)
+                return false;
+            highest = seq;
+            return true;
+        },
+        last: () => highest,
+        epoch: () => current,
+        observeAck(streamSeq, streamEpoch) {
+            if (hasLeft(streamEpoch))
+                return false;
+            if (meetEpoch(streamEpoch))
+                return true;
+            if (streamSeq === undefined || highest === undefined || streamSeq >= highest)
+                return false;
+            highest = undefined;
+            return true;
+        },
+    };
+}

package/dist/system-cards/ProtocolProbeCard.d.ts

@@ -49,6 +49,21 @@
  * the submit-action bridge + native idioms in response.
  */
 import * as React from 'react';
+/**
+ * One canonical View→Host method the spec defines (apps.mdx:963-1102).
+ * Keep this list aligned with the §"Requests (View → Host)" section.
+ * Adding a new probe button means adding one entry here + one
+ * matching renderer in the JSX below.
+ */
+type ProbeMethod = 'ui/message' | 'ui/update-model-context' | 'ui/open-link' | 'ui/request-display-mode' | 'tools/call';
+/**
+ * Build a default param payload for each canonical method. The shapes
+ * mirror the spec examples (apps.mdx:963-1102) exactly so any host
+ * with a strict validator accepts them.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function defaultParams(method: ProbeMethod): unknown;
 export interface ProtocolProbeCardProps {
     /**
      * Optional: the original prompt that triggered the probe render.
@@ -58,3 +73,4 @@ export interface ProtocolProbeCardProps {
     readonly intent?: string;
 }
 export declare function ProtocolProbeCard({ intent, }: ProtocolProbeCardProps): React.JSX.Element;
+export {};

package/dist/system-cards/ProtocolProbeCard.js

@@ -51,6 +51,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import * as React from 'react';
 import { Card, Stack, Heading, Text, Button, Badge, } from '@ggui-ai/design/primitives';
+import { withViewProof } from '../view-origin.js';
 const PROBE_TIMEOUT_MS = 5_000;
 /**
  * Lifetime-scoped JSON-RPC caller. One instance per card mount —
@@ -158,8 +159,10 @@ function useNotificationLog() {
  * Build a default param payload for each canonical method. The shapes
  * mirror the spec examples (apps.mdx:963-1102) exactly so any host
  * with a strict validator accepts them.
+ *
+ * @internal — exported for unit tests.
  */
-function defaultParams(method) {
+export function defaultParams(method) {
     switch (method) {
         case 'ui/message':
             // Empirical 2026-05-03: claude.ai's validator wants `content`
@@ -199,20 +202,20 @@ function defaultParams(method) {
             // The probe uses `kind: 'dispatch'` so the chained 3-message
             // follow-up (`ui/update-model-context` + `ui/message`)
             // semantically matches a real submit-action click.
-            return {
-                name: 'ggui_runtime_submit_action',
-                arguments: {
-                    kind: 'dispatch',
-                    payload: {
-                        intent: 'probe-click',
-                        data: { note: 'hello from the protocol probe' },
-                    },
-                    sessionId: 'probe-render',
-                    appId: 'probe-app',
-                    actionId: '00000000', // overwritten in onClick with real FNV-1a
-                    firedAt: new Date().toISOString(),
+            // Through the one wrapper, like every call of the three runtime tools
+            // (ggui#1415). The probe's fixed session is keyed by no door, so it
+            // carries a proof only if a root for it were ever held.
+            return withViewProof('ggui_runtime_submit_action', {
+                kind: 'dispatch',
+                payload: {
+                    intent: 'probe-click',
+                    data: { note: 'hello from the protocol probe' },
                 },
-            };
+                sessionId: 'probe-render',
+                appId: 'probe-app',
+                actionId: '00000000',
+                firedAt: new Date().toISOString(),
+            });
     }
 }
 /**

package/dist/tool-result-error.d.ts

@@ -0,0 +1,6 @@
+/** Whether a tool result is an error result. */
+export declare function isErrorToolResult(result: unknown): boolean;
+/** The text of a tool result's first text block, if it has one. */
+export declare function toolResultText(result: unknown): string | undefined;
+/** The domain-error code an error result carries; `undefined` for any other result. */
+export declare function domainErrorCodeOf(result: unknown): string | undefined;

package/dist/tool-result-error.js

@@ -0,0 +1,32 @@
+/**
+ * Reading a tool result the server answered with an error (ggui#1496).
+ *
+ * A server tool that throws reaches the view, through the host's
+ * `tools/call` relay, as a result with `isError: true` whose first text
+ * block is the error's text. A domain error's text is `<code>: <detail>`,
+ * read by the protocol's own parser.
+ */
+import { parseDomainErrorText } from '@ggui-ai/protocol/wire';
+/** Whether a tool result is an error result. */
+export function isErrorToolResult(result) {
+    return typeof result === 'object' && result !== null && Reflect.get(result, 'isError') === true;
+}
+/** The text of a tool result's first text block, if it has one. */
+export function toolResultText(result) {
+    if (typeof result !== 'object' || result === null)
+        return undefined;
+    const content = Reflect.get(result, 'content');
+    if (!Array.isArray(content) || content.length === 0)
+        return undefined;
+    const first = content[0];
+    if (typeof first !== 'object' || first === null)
+        return undefined;
+    const text = Reflect.get(first, 'text');
+    return typeof text === 'string' ? text : undefined;
+}
+/** The domain-error code an error result carries; `undefined` for any other result. */
+export function domainErrorCodeOf(result) {
+    if (!isErrorToolResult(result))
+        return undefined;
+    return parseDomainErrorText(toolResultText(result) ?? '')?.code;
+}

package/dist/types.d.ts

@@ -97,8 +97,56 @@ export type McpAppAiGguiMetaParseResult = {
     readonly ok: true;
     readonly meta: McpAppAiGguiRenderMeta;
     readonly hostContext?: HostContextProjection;
+    /**
+     * The live credential the parse dropped because it had expired
+     * (ggui#1496). The meta carries no live trio then; the view may
+     * refresh this through its host.
+     */
+    readonly held?: HeldCredential;
+    /** The slice's view key root, when it carries one (ggui#1415). */
+    readonly viewRoot?: ViewRoot;
 } | {
     readonly ok: false;
-    readonly reason: McpAppAiGguiMetaParseFailureReason;
+    readonly reason: Exclude<McpAppAiGguiMetaParseFailureReason, 'EXPIRED_BOOTSTRAP'>;
+} | {
+    readonly ok: false;
+    /**
+     * A live-only slice whose credential expired. It still carries the
+     * projected meta (with no live trio) and the held credential, so a
+     * view with a host relay can refresh before giving up (ggui#1496).
+     */
+    readonly reason: 'EXPIRED_BOOTSTRAP';
+    readonly meta: McpAppAiGguiRenderMeta;
+    readonly held: HeldCredential;
+    /** The slice's view key root, captured before its credential was dropped (ggui#1415). */
+    readonly viewRoot?: ViewRoot;
 };
+/**
+ * A view's live credential, with the URLs that carry it (ggui#1496).
+ * Runtime-local, never a protocol member: the parse returns an expired one
+ * as `held`, and the credential controller refreshes it.
+ */
+export interface HeldCredential {
+    readonly wsToken: string;
+    readonly wsUrl: string;
+    /** ISO-8601, as the slice or the refresh stated it. */
+    readonly expiresAt?: string;
+    readonly sseUrl?: string;
+    readonly pollingUrl?: string;
+    /** `root`: minted with the render. `refreshed`: came back from a refresh. */
+    readonly origin: 'root' | 'refreshed';
+}
+/**
+ * The key root a view proves its app-only runtime calls with (ggui#1415):
+ * `P`, the payload segment of the slice's `wsToken`, and `K`, the slice's
+ * `viewKey`. Runtime-local, never a protocol member: the parse captures it
+ * from the slice before an expired credential is dropped, and the runtime
+ * adopts it only once `P` decodes to the slice's own session.
+ */
+export interface ViewRoot {
+    /** `P`: the `wsToken`'s payload segment, base64url. */
+    readonly root: string;
+    /** `K`: the slice's `viewKey`, base64url. */
+    readonly key: string;
+}
 export {};

package/dist/view-origin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The document's view origin (ggui#1415): its one key-root holder, the
+ * prover over it, and the user-activation reading a dispatch signs with.
+ *
+ * One per document, like the mount it proves for. The boot and every later
+ * tool result offer their slice's root to {@link documentViewRoots}; every
+ * `tools/call` of the three app-only runtime tools goes through
+ * {@link withViewProof}. Everything here is held in this module's closure
+ * and captured when the runtime bundle evaluates, before card code runs.
+ */
+import type { JsonObject } from '@ggui-ai/protocol/wire';
+import { type ViewRootHolder } from './view-root.js';
+import { type ViewProofOptions, type ViewToolCall } from './view-proof-signer.js';
+/** The document's view key root. */
+export declare const documentViewRoots: ViewRootHolder;
+/**
+ * The one wrapper for a view's `tools/call`: the normalized arguments, and a
+ * proof at `_meta["ai.ggui/view"]` for the three app-only runtime tools when
+ * the document holds a root for the call's session. Any other tool passes
+ * through untouched. Never throws.
+ */
+export declare function withViewProof<A extends object>(name: string, args: A, opts?: ViewProofOptions): ViewToolCall<A | JsonObject>;
+/**
+ * Whether the current task carries transient user activation, read through
+ * the accessor captured at load. `false` where the browser does not expose
+ * it. A dispatch reads it at entry and signs it as flag bit 0: measured,
+ * never enforced.
+ */
+export declare function userActivationIsActive(): boolean;

package/dist/view-origin.js

@@ -0,0 +1,33 @@
+import { createViewRootHolder } from './view-root.js';
+import { createViewProver } from './view-proof-signer.js';
+/** The document's view key root. */
+export const documentViewRoots = createViewRootHolder();
+const documentProver = createViewProver({ roots: documentViewRoots });
+/**
+ * The one wrapper for a view's `tools/call`: the normalized arguments, and a
+ * proof at `_meta["ai.ggui/view"]` for the three app-only runtime tools when
+ * the document holds a root for the call's session. Any other tool passes
+ * through untouched. Never throws.
+ */
+export function withViewProof(name, args, opts) {
+    return documentProver.withViewProof(name, args, opts);
+}
+// `navigator.userActivation` and its `isActive` getter, captured before card
+// code can replace either.
+const capturedActivation = typeof navigator !== 'undefined' && navigator.userActivation !== undefined ? navigator.userActivation : undefined;
+const capturedIsActive = capturedActivation !== undefined
+    ? Object.getOwnPropertyDescriptor(Object.getPrototypeOf(capturedActivation), 'isActive')?.get
+    : undefined;
+/**
+ * Whether the current task carries transient user activation, read through
+ * the accessor captured at load. `false` where the browser does not expose
+ * it. A dispatch reads it at entry and signs it as flag bit 0: measured,
+ * never enforced.
+ */
+export function userActivationIsActive() {
+    if (capturedActivation === undefined)
+        return false;
+    if (capturedIsActive !== undefined)
+        return capturedIsActive.call(capturedActivation) === true;
+    return capturedActivation.isActive;
+}

package/dist/view-proof-signer.d.ts

@@ -0,0 +1,31 @@
+import { MCP_APP_AI_GGUI_VIEW_META_KEY } from '@ggui-ai/protocol/integrations/mcp-apps';
+import type { JsonObject } from '@ggui-ai/protocol/wire';
+import type { ViewRootHolder } from './view-root.js';
+/** A `tools/call` request's params, as a view sends them. */
+export interface ViewToolCall<A> {
+    readonly name: string;
+    readonly arguments: A;
+    readonly _meta?: {
+        readonly [MCP_APP_AI_GGUI_VIEW_META_KEY]: string;
+    };
+}
+export interface ViewProofOptions {
+    /**
+     * Whether the gesture carried transient user activation, read at dispatch
+     * entry (`navigator.userActivation.isActive`). Sets flag bit 0. Measured,
+     * never enforced: any holder of the key can set it.
+     */
+    readonly userActivation?: boolean;
+}
+export interface ViewProver {
+    withViewProof<A extends object>(name: string, args: A, opts?: ViewProofOptions): ViewToolCall<A | JsonObject>;
+}
+export interface ViewProverDeps {
+    readonly roots: ViewRootHolder;
+    /** Epoch milliseconds. Defaults to the clock captured when this module loaded. */
+    readonly now?: () => number;
+    /** Fills `bytes` with random values. Defaults to the source captured when this module loaded. */
+    readonly randomBytes?: (bytes: Uint8Array) => void;
+}
+/** A prover over the view's key root holder. */
+export declare function createViewProver(deps: ViewProverDeps): ViewProver;

package/dist/view-proof-signer.js

@@ -0,0 +1,99 @@
+/**
+ * The view's prover (ggui#1415): the one wrapper every `tools/call` of the
+ * three app-only runtime tools goes through.
+ *
+ * {@link ViewProver.withViewProof} sends the JSON-normalized arguments and,
+ * when the view holds a key root for the call's session, a v1 proof at
+ * `_meta["ai.ggui/view"]`, the only `_meta` key it sets. Any other tool
+ * passes through untouched. It never throws and never changes whether or
+ * where a call is sent: a failure means the call goes without a proof.
+ *
+ * The HMAC is synchronous (`@noble/hashes`), so wrapping a raw send keeps
+ * its place in the send order, and it works where `crypto.subtle` is absent
+ * (a plain-http self-host).
+ */
+import { hmac } from '@noble/hashes/hmac';
+import { sha256 } from '@noble/hashes/sha2';
+import { MCP_APP_AI_GGUI_VIEW_META_KEY, VIEW_PROOF_FLAG_USER_ACTIVATION, VIEW_PROOF_V1_PATTERN, formatViewProofV1, isViewProofTool, viewProofArgsBytes, viewProofCallBytes, } from '@ggui-ai/protocol/integrations/mcp-apps';
+// Captured when the runtime bundle evaluates, before any card code runs in
+// this realm, so a card that replaces these globals later does not reach
+// the prover.
+const capturedNow = Date.now.bind(Date);
+const capturedCrypto = typeof crypto !== 'undefined' ? crypto : undefined;
+const capturedGetRandomValues = capturedCrypto?.getRandomValues.bind(capturedCrypto);
+function capturedRandomBytes(bytes) {
+    if (capturedGetRandomValues === undefined)
+        throw new Error('no random source');
+    capturedGetRandomValues(bytes);
+}
+const NONCE_BYTES = 16;
+function toBase64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+const BASE64URL = /^[A-Za-z0-9_-]*$/;
+function fromBase64Url(text) {
+    if (!BASE64URL.test(text))
+        throw new Error('not base64url');
+    const padded = text.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((text.length + 3) % 4);
+    return Uint8Array.from(atob(padded), (ch) => ch.charCodeAt(0));
+}
+function isJsonObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** The arguments as JSON carries them, or `undefined` when JSON cannot carry them. */
+function normalize(args) {
+    try {
+        const text = JSON.stringify(args);
+        if (text === undefined)
+            return undefined;
+        const value = JSON.parse(text);
+        return isJsonObject(value) ? value : undefined;
+    }
+    catch {
+        // A BigInt or a cycle: JSON cannot carry these arguments, so there is
+        // nothing to sign, and the call goes as the caller built it.
+        return undefined;
+    }
+}
+/** A prover over the view's key root holder. */
+export function createViewProver(deps) {
+    const now = deps.now ?? capturedNow;
+    const randomBytes = deps.randomBytes ?? capturedRandomBytes;
+    return {
+        withViewProof(name, args, opts) {
+            if (!isViewProofTool(name))
+                return { name, arguments: args };
+            const normalized = normalize(args);
+            if (normalized === undefined)
+                return { name, arguments: args };
+            const sessionId = normalized['sessionId'];
+            const root = typeof sessionId === 'string' ? deps.roots.current(sessionId) : undefined;
+            if (root === undefined)
+                return { name, arguments: normalized };
+            try {
+                const key = fromBase64Url(root.key);
+                const argmac = toBase64Url(hmac(sha256, key, viewProofArgsBytes(name, normalized)));
+                const nonceBytes = new Uint8Array(NONCE_BYTES);
+                randomBytes(nonceBytes);
+                const nonce = toBase64Url(nonceBytes);
+                const vtime = String(Math.trunc(now()));
+                const flags = (opts?.userActivation === true ? VIEW_PROOF_FLAG_USER_ACTIVATION : 0).toString(16);
+                const callmac = toBase64Url(hmac(sha256, key, viewProofCallBytes({ toolName: name, nonce, vtime, flags, argmac })));
+                const proof = formatViewProofV1({ root: root.root, nonce, vtime, flags, argmac, callmac });
+                // A clock or a key outside the grammar makes a string no verifier
+                // would parse: send none rather than one that can only fail.
+                if (!VIEW_PROOF_V1_PATTERN.test(proof))
+                    return { name, arguments: normalized };
+                return { name, arguments: normalized, _meta: { [MCP_APP_AI_GGUI_VIEW_META_KEY]: proof } };
+            }
+            catch {
+                // Total by contract: a failed mint sends the call without a proof,
+                // which the server counts as `missing`, never a failed call.
+                return { name, arguments: normalized };
+            }
+        },
+    };
+}

package/dist/view-root.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The view's key root (ggui#1415): what the parse captures from a render
+ * slice, and which root the view proves its app-only runtime calls with.
+ *
+ * A slice that carries a `viewKey` roots it in its `wsToken`: `K` is
+ * derived by the server from `P`, the token's payload segment. The parse
+ * takes the pair before an expired credential is dropped from the meta
+ * ({@link viewRootOf}), and {@link createViewRootHolder} decides whether a
+ * later slice's root replaces the one the view holds.
+ */
+import { type McpAppAiGguiRenderMeta, type ViewRootClaims } from '@ggui-ai/protocol/integrations/mcp-apps';
+import type { ViewRoot } from './types.js';
+/**
+ * The slice's key root: `P` from its `wsToken`, `K` from its `viewKey`.
+ * `undefined` when either is absent, since a key means nothing without the
+ * token it is rooted in. The protocol parser already keeps a `viewKey` only
+ * beside its ws envelope and only in its shape.
+ */
+export declare function viewRootOf(meta: Pick<McpAppAiGguiRenderMeta, 'wsToken' | 'viewKey'>): ViewRoot | undefined;
+/** A held root, with the claims its `P` decoded to. */
+export interface HeldViewRoot extends ViewRoot {
+    readonly claims: ViewRootClaims;
+}
+/**
+ * Why an offered root was not adopted. `no_key`: the slice carried none (a
+ * `/state` poll, a keyless door). `oversize`: `P` is longer than a proof can
+ * carry. `malformed`: `P` does not decode to ws claims. `session_mismatch`:
+ * `P` names another session than the slice. `not_newer`: the view already
+ * holds a root for this session at the same or a later `iat`.
+ */
+export type ViewRootRefusal = 'no_key' | 'oversize' | 'malformed' | 'session_mismatch' | 'not_newer';
+export type ViewRootOffer = {
+    readonly adopted: true;
+} | {
+    readonly adopted: false;
+    readonly reason: ViewRootRefusal;
+};
+export interface ViewRootHolder {
+    /** Offer the root a slice for `sessionId` carried. */
+    offer(sessionId: string, root: ViewRoot | undefined): ViewRootOffer;
+    /** The held root, only when it was adopted for `sessionId`. */
+    current(sessionId: string): HeldViewRoot | undefined;
+}
+/**
+ * One view's key root. It adopts a root only when `P` fits a proof and
+ * decodes to the offering slice's own session. For the session it already
+ * holds, it adopts only a greater `iat`, so a replayed or reordered slice
+ * never winds the root back. A slice for another session replaces it: a
+ * view proves calls only for the session they name.
+ */
+export declare function createViewRootHolder(): ViewRootHolder;

package/dist/view-root.js

@@ -0,0 +1,56 @@
+/**
+ * The view's key root (ggui#1415): what the parse captures from a render
+ * slice, and which root the view proves its app-only runtime calls with.
+ *
+ * A slice that carries a `viewKey` roots it in its `wsToken`: `K` is
+ * derived by the server from `P`, the token's payload segment. The parse
+ * takes the pair before an expired credential is dropped from the meta
+ * ({@link viewRootOf}), and {@link createViewRootHolder} decides whether a
+ * later slice's root replaces the one the view holds.
+ */
+import { VIEW_PROOF_ROOT_MAX_CHARS, decodeViewRootClaims, } from '@ggui-ai/protocol/integrations/mcp-apps';
+/**
+ * The slice's key root: `P` from its `wsToken`, `K` from its `viewKey`.
+ * `undefined` when either is absent, since a key means nothing without the
+ * token it is rooted in. The protocol parser already keeps a `viewKey` only
+ * beside its ws envelope and only in its shape.
+ */
+export function viewRootOf(meta) {
+    const { wsToken, viewKey } = meta;
+    if (typeof viewKey !== 'string' || viewKey.length === 0)
+        return undefined;
+    if (typeof wsToken !== 'string' || wsToken.length === 0)
+        return undefined;
+    return { root: wsToken.split('.')[0] ?? '', key: viewKey };
+}
+/**
+ * One view's key root. It adopts a root only when `P` fits a proof and
+ * decodes to the offering slice's own session. For the session it already
+ * holds, it adopts only a greater `iat`, so a replayed or reordered slice
+ * never winds the root back. A slice for another session replaces it: a
+ * view proves calls only for the session they name.
+ */
+export function createViewRootHolder() {
+    let held;
+    return {
+        offer(sessionId, root) {
+            if (root === undefined)
+                return { adopted: false, reason: 'no_key' };
+            if (root.root.length > VIEW_PROOF_ROOT_MAX_CHARS)
+                return { adopted: false, reason: 'oversize' };
+            const claims = decodeViewRootClaims(root.root);
+            if (typeof claims === 'string')
+                return { adopted: false, reason: 'malformed' };
+            if (claims.sessionId !== sessionId)
+                return { adopted: false, reason: 'session_mismatch' };
+            if (held !== undefined && held.claims.sessionId === sessionId && claims.iat <= held.claims.iat) {
+                return { adopted: false, reason: 'not_newer' };
+            }
+            held = { root: root.root, key: root.key, claims };
+            return { adopted: true };
+        },
+        current(sessionId) {
+            return held !== undefined && held.claims.sessionId === sessionId ? held : undefined;
+        },
+    };
+}

package/dist/wire-config.d.ts

@@ -55,6 +55,13 @@ export interface BuildRootWireConfigOptions {
      * Passed through as wire's `spentInputsChanged` and `pendingInputsChanged`.
      */
     readonly renderChanges?: (listener: () => void) => () => void;
+    /**
+     * ggui#1424 — the `oneShot` names the SERVER refused for this card as
+     * already spent (a `CONTRACT_VIOLATION` at `actionSpec.<name>.oneShot`),
+     * which the runtime marks so the guard reads them beside the card's
+     * persisted record. Read on every dispatch; `undefined` means none.
+     */
+    readonly refusedSpentOneShots?: () => readonly string[] | undefined;
     /** Handle to the renderer's WS manager; used for outbound `action` frames. */
     readonly manager: RendererSendSurface;
     /** Shared bus for inbound stream deliveries. */
@@ -116,6 +123,12 @@ export interface BuildRootWireConfigOptions {
      * relay (see iframe-runtime's `routeDispatch`).
      */
     readonly onDispatchEnvelope?: (envelope: ActionEnvelope) => void;
+    /**
+     * Called with the action's name when the outbound check refuses a
+     * dispatch (ggui#1536), after the refusal is posted to the embedding
+     * host. The renderer tells the visitor the tap did nothing.
+     */
+    readonly onDispatchRefused?: (actionName: string) => void;
 }
 /**
  * Build the per-render `WireConfig` for the iframe runtime.