@ggui-ai/iframe-runtime 0.21.0 → 0.23.0

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './m
 export type { RendererBootFailureReason, RendererBootFailedMessage, } from './runtime.js';
 export type { ProtocolError, ProtocolErrorEmitter, BootstrapFailureReason, } from './protocol-error.js';
 export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
-export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, FontFaceBlockedEvent, AppThemeInvalidEvent, AppThemeMemberStrippedEvent, ThemeReinjectFailedEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayDeadTapEvent, RelayIncapabilityEvent, RelayLatchTrigger, UnknownObservabilityEvent, } from './observability.js';
+export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, FontFaceBlockedEvent, AppThemeInvalidEvent, AppThemeMemberStrippedEvent, ActionSpecInvalidEvent, ActionSpecMemberStrippedEvent, SpentOneShotsInvalidEvent, ThemeReinjectFailedEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayDeadTapEvent, RelayIncapabilityEvent, RelayLatchTrigger, ComponentEmptyEvent, OneShotUnenforceableEvent, UnknownObservabilityEvent, } from './observability.js';
 export { isObservabilityMessage, isRelayDeadTapEvent, isRelayIncapabilityEvent, postObservabilityToParent, } from './observability.js';
 export type { LifecycleEmitter } from './lifecycle.js';
 export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

package/dist/meta-parse.d.ts

@@ -1,4 +1,5 @@
 import type { McpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { type ParseMcpAppAiGguiRenderMetaOptions } from '@ggui-ai/protocol/integrations/mcp-apps';
 import type { McpAppAiGguiMetaParseResult } from './types.js';
 /**
  * Validate an {@link McpAppAiGguiRenderMeta} slice. Enforces mode
@@ -33,6 +34,36 @@ export declare function reportInvalidAppTheme(issues: readonly string[]): void;
  * on every `parseMcpAppAiGguiRenderMeta` call in this package.
  */
 export declare function reportStrippedThemeMembers(keys: readonly string[]): void;
+/**
+ * The wire parser refused the slice's `actionSpec` (ggui#1178): report it
+ * to the embedding host as `action-spec-invalid` and mount without the
+ * action contract. Passed as `onInvalidActionSpec` on every
+ * `parseMcpAppAiGguiRenderMeta` call in this package.
+ */
+export declare function reportInvalidActionSpec(issues: readonly string[]): void;
+/**
+ * The read door KEPT the slice's `actionSpec` but stripped entry members
+ * this release does not name (ggui#1178, VERSION-POLICY §3.6): report the
+ * `<action>.<member>` paths so a newer writer's member is visible, not
+ * swallowed. Passed as `onStrippedActionSpecMembers` on every
+ * `parseMcpAppAiGguiRenderMeta` call in this package.
+ */
+export declare function reportStrippedActionSpecMembers(keys: readonly string[]): void;
+/**
+ * The wire parser refused the slice's `spentOneShots` (ggui#1223): report it
+ * to the embedding host as `spent-one-shots-invalid` and mount without it.
+ * The runtime keeps its in-memory guard alone, so a consumed action would
+ * look live again after a reload — never silently.
+ */
+export declare function reportInvalidSpentOneShots(issues: readonly string[]): void;
+/**
+ * Every degradation the wire parser's read door can report, bound to its
+ * observability event — the ONE options object every
+ * `parseMcpAppAiGguiRenderMeta` call in this package passes, so a door
+ * that learns a new report is wired everywhere at once rather than at
+ * whichever call site someone remembered.
+ */
+export declare const READ_DOOR_REPORTERS: ParseMcpAppAiGguiRenderMetaOptions;
 /**
  * Parse the render slice from `globalThis.__GGUI_META__` — the
  * synchronous self-contained shell delivery channel.

package/dist/meta-parse.js

@@ -51,7 +51,7 @@
  * is structurally rejected by the combiner.
  */
 import { PUBLIC_ENV_APP_KEY_RE } from '@ggui-ai/protocol/wire';
-import { parseMcpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { parseMcpAppAiGguiRenderMeta, } from '@ggui-ai/protocol/integrations/mcp-apps';
 import { postObservabilityToParent } from './observability.js';
 /**
  * Type guard — true iff `value` is a non-null, non-array plain object.
@@ -251,6 +251,13 @@ function projectMeta(meta, hasStaticContent) {
         // Per-app theme overlay carried through verbatim. Already validated
         // via `appThemeSchema` by the wire parser, so no re-validation here.
         ...(meta.theme !== undefined ? { theme: meta.theme } : {}),
+        // The slice's action contract (ggui#1178), carried through whole.
+        // Already validated at the wire parser's tolerant read door, so no
+        // re-validation here.
+        ...(meta.actionSpec !== undefined ? { actionSpec: meta.actionSpec } : {}),
+        // The card's spent oneShot names (ggui#1223), carried through whole —
+        // validated at the wire parser's tolerant read door.
+        ...(meta.spentOneShots !== undefined ? { spentOneShots: meta.spentOneShots } : {}),
         ...(gadgets !== undefined ? { gadgets } : {}),
         ...(publicEnv !== undefined ? { publicEnv } : {}),
         ...(streamWebSocketLocalTools !== undefined
@@ -345,6 +352,48 @@ export function reportInvalidAppTheme(issues) {
 export function reportStrippedThemeMembers(keys) {
     postObservabilityToParent({ kind: 'app-theme-member-stripped', keys: [...keys] });
 }
+/**
+ * The wire parser refused the slice's `actionSpec` (ggui#1178): report it
+ * to the embedding host as `action-spec-invalid` and mount without the
+ * action contract. Passed as `onInvalidActionSpec` on every
+ * `parseMcpAppAiGguiRenderMeta` call in this package.
+ */
+export function reportInvalidActionSpec(issues) {
+    postObservabilityToParent({ kind: 'action-spec-invalid', issues: [...issues] });
+}
+/**
+ * The read door KEPT the slice's `actionSpec` but stripped entry members
+ * this release does not name (ggui#1178, VERSION-POLICY §3.6): report the
+ * `<action>.<member>` paths so a newer writer's member is visible, not
+ * swallowed. Passed as `onStrippedActionSpecMembers` on every
+ * `parseMcpAppAiGguiRenderMeta` call in this package.
+ */
+export function reportStrippedActionSpecMembers(keys) {
+    postObservabilityToParent({ kind: 'action-spec-member-stripped', keys: [...keys] });
+}
+/**
+ * The wire parser refused the slice's `spentOneShots` (ggui#1223): report it
+ * to the embedding host as `spent-one-shots-invalid` and mount without it.
+ * The runtime keeps its in-memory guard alone, so a consumed action would
+ * look live again after a reload — never silently.
+ */
+export function reportInvalidSpentOneShots(issues) {
+    postObservabilityToParent({ kind: 'spent-one-shots-invalid', issues: [...issues] });
+}
+/**
+ * Every degradation the wire parser's read door can report, bound to its
+ * observability event — the ONE options object every
+ * `parseMcpAppAiGguiRenderMeta` call in this package passes, so a door
+ * that learns a new report is wired everywhere at once rather than at
+ * whichever call site someone remembered.
+ */
+export const READ_DOOR_REPORTERS = {
+    onInvalidTheme: reportInvalidAppTheme,
+    onStrippedThemeMembers: reportStrippedThemeMembers,
+    onInvalidActionSpec: reportInvalidActionSpec,
+    onStrippedActionSpecMembers: reportStrippedActionSpecMembers,
+    onInvalidSpentOneShots: reportInvalidSpentOneShots,
+};
 /**
  * Parse the render slice from `globalThis.__GGUI_META__` — the
  * synchronous self-contained shell delivery channel.
@@ -367,10 +416,7 @@ export function parseMetaFromGlobal() {
     if (!isPlainObject(raw)) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }
-    const parsed = parseMcpAppAiGguiRenderMeta(raw, {
-        onInvalidTheme: reportInvalidAppTheme,
-        onStrippedThemeMembers: reportStrippedThemeMembers,
-    });
+    const parsed = parseMcpAppAiGguiRenderMeta(raw, READ_DOOR_REPORTERS);
     if (!parsed.ok) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }
@@ -421,10 +467,7 @@ export function parseMetaFromToolResult(params) {
         return { ok: false, reason: 'MISSING_META_GGUI_BOOTSTRAP' };
     }
     const meta = topMeta;
-    const parsed = parseMcpAppAiGguiRenderMeta(meta, {
-        onInvalidTheme: reportInvalidAppTheme,
-        onStrippedThemeMembers: reportStrippedThemeMembers,
-    });
+    const parsed = parseMcpAppAiGguiRenderMeta(meta, READ_DOOR_REPORTERS);
     if (!parsed.ok) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }

package/dist/observability.d.ts

@@ -33,7 +33,7 @@ import { MCP_APP_OBSERVE_TYPE } from '@ggui-ai/protocol/integrations/mcp-apps';
  *
  * @public
  */
-export type ObservabilityEvent = SchemaVersionMismatchEvent | FontFaceBlockedEvent | AppThemeInvalidEvent | AppThemeMemberStrippedEvent | ThemeReinjectFailedEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | RelayDeadTapEvent | ComponentEmptyEvent | UnknownObservabilityEvent;
+export type ObservabilityEvent = SchemaVersionMismatchEvent | FontFaceBlockedEvent | AppThemeInvalidEvent | AppThemeMemberStrippedEvent | ActionSpecInvalidEvent | ActionSpecMemberStrippedEvent | OneShotUnenforceableEvent | SpentOneShotsInvalidEvent | ThemeReinjectFailedEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | RelayDeadTapEvent | ComponentEmptyEvent | UnknownObservabilityEvent;
 /**
  * Fired when the protocol-version handshake rejects the connection.
  * Parallel to `UpgradeRequiredError` — the host can choose to render
@@ -364,6 +364,56 @@ export interface AppThemeMemberStrippedEvent {
     readonly kind: 'app-theme-member-stripped';
     readonly keys: readonly string[];
 }
+/**
+ * The render slice carried an `actionSpec` the wire schema refused
+ * (ggui#1178): the parser dropped it and the card mounted without the
+ * action contract. `issues` are the schema's own messages — the
+ * operator's pointer to the writer that projected a malformed contract.
+ *
+ * @public
+ */
+export interface ActionSpecInvalidEvent {
+    readonly kind: 'action-spec-invalid';
+    readonly issues: readonly string[];
+}
+/**
+ * The render slice's `actionSpec` carried entry members THIS release does
+ * not name (ggui#1178, VERSION-POLICY §3.6): the read door kept every
+ * action and stripped those members, and the card says which. `keys` are
+ * `<action>.<member>` paths only, never their content.
+ *
+ * @public
+ */
+export interface ActionSpecMemberStrippedEvent {
+    readonly kind: 'action-spec-member-stripped';
+    readonly keys: readonly string[];
+}
+/**
+ * A component render dispatched with no action contract on either carrier
+ * (ggui#1178, SPEC §5.5.1): the one-shot guard cannot know whether the
+ * action is `oneShot`, so the dispatch proceeds unguarded. Posted once per
+ * render, on its first such dispatch. `actionName` is the action that
+ * dispatched, never its payload.
+ *
+ * @public
+ */
+export interface OneShotUnenforceableEvent {
+    readonly kind: 'one-shot-unenforceable';
+    readonly renderId: string;
+    readonly actionName: string;
+}
+/**
+ * The render slice carried a `spentOneShots` the wire schema refused
+ * (ggui#1223): the parser dropped it, and the card mounted with only its
+ * in-memory one-shot guard — a consumed action reads as live again after a
+ * reload. `issues` are the schema's own messages.
+ *
+ * @public
+ */
+export interface SpentOneShotsInvalidEvent {
+    readonly kind: 'spent-one-shots-invalid';
+    readonly issues: readonly string[];
+}
 /**
  * The live re-injection on a host theme flip (ggui#987 §4) failed: the
  * renderer's update rejected, so the card kept its previous overlay /

package/dist/protocol-error.d.ts

@@ -38,8 +38,11 @@ import { ClientContractViolationError } from '@ggui-ai/wire';
  *      `McpAppAiGguiMetaParseFailureReason` (`MISSING_TOOL_OUTPUT` /
  *      `MISSING_META_GGUI_BOOTSTRAP` / `MALFORMED_BOOTSTRAP` /
  *      `EXPIRED_BOOTSTRAP`). `MISSING_META_GGUI_BOOTSTRAP` and
- *      `BOOTSTRAP_META_MISSING` are synonyms — the latter is the
- *      on-wire name, the former the parse-internal name.
+ *      `BOOTSTRAP_META_MISSING` name one condition. The runtime and the
+ *      reference shell emit `MISSING_META_GGUI_BOOTSTRAP` on
+ *      `ggui:bootstrap-failed`; `BOOTSTRAP_META_MISSING` stays a member
+ *      so a host classifies either spelling as that condition
+ *      (SPEC §5.5.2).
  *
  *   2. **Post-parse orchestration failures** — `UI_INITIALIZE_FAILED`
  *      / `WS_HANDSHAKE_FAILED`. Matches `RendererBootFailureReason`.

package/dist/react-renderer.js

@@ -32,6 +32,7 @@
 import React, { Component, createElement, Fragment, } from 'react';
 import { createRoot } from 'react-dom/client';
 import { postObservabilityToParent } from './observability.js';
+import { trackThemeFontFaces } from './host-fonts.js';
 import { stripMarkers, rewriteImports, composeThemeCss, } from '@ggui-ai/design/rendering';
 import { hoistImports, loadModule, loadModuleInline, probeUrlModuleLoad, } from '@ggui-ai/design/module-loader';
 /**
@@ -367,6 +368,10 @@ export async function mountReactRoot(container, opts) {
             if (styleEl.textContent !== rootCss) {
                 styleEl.textContent = rootCss;
             }
+            // ggui#1147: the chrome CSS carries the stored theme's @font-face rules,
+            // mid-session included, while `font-src` was fixed at mount. Track them so
+            // a blocked face is reported as `font-face-blocked`, not lost silently.
+            trackThemeFontFaces(rootCss);
         }
         const componentElement = currentComponent === null
             ? null

package/dist/runtime.d.ts

@@ -524,6 +524,17 @@ export declare function readSelfContainedMeta(): McpAppAiGguiRenderMeta | null;
  * surface a typed boot failure. The four server-assigned ledger fields
  * are intentionally absent — the first ack reconciles the seed to a
  * full `GguiSession` (no fabrication).
+ *
+ * A component seed carries the slice's `actionSpec` when the slice has one
+ * (ggui#1178): a mount with no live session frame paints from this seed, and
+ * the one-shot guard reads the current render's spec, so a seed without it
+ * could not enforce `oneShot`. A system seed never carries one.
+ *
+ * It also carries the card's `epoch` and, when the slice lists them, the
+ * `oneShot` names this card already spent, as the render's record
+ * `{ epoch, actions }` (ggui#1223). `deriveRenderMeta` projected those names
+ * for this card only, so the record's epoch is the card's own and the guard
+ * stops the first gesture on a spent action after a reload.
  */
 export declare function buildGguiSessionSeedInput(meta: McpAppAiGguiRenderMeta): Promise<GguiSessionSeedInput | null>;
 /**

package/dist/runtime.js

@@ -30,7 +30,7 @@ import './zod-jitless.js';
 import { runtimeConnectionWriter } from './connection.js';
 import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, parseMcpAppAiGguiRenderMeta, readGguiShellEnvelope, } from '@ggui-ai/protocol/integrations/mcp-apps';
 import { effectiveThemeId, effectiveThemeMode, } from '@ggui-ai/protocol/integrations/theme-binding';
-import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, reportInvalidAppTheme, reportStrippedThemeMembers, } from './meta-parse.js';
+import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, READ_DOOR_REPORTERS, } from './meta-parse.js';
 import { projectHostContext } from '@ggui-ai/protocol/wire';
 import { installDismissIntentListener } from './dismiss-intent.js';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
@@ -1175,9 +1175,27 @@ function parseSeedProps(propsJson) {
  * surface a typed boot failure. The four server-assigned ledger fields
  * are intentionally absent — the first ack reconciles the seed to a
  * full `GguiSession` (no fabrication).
+ *
+ * A component seed carries the slice's `actionSpec` when the slice has one
+ * (ggui#1178): a mount with no live session frame paints from this seed, and
+ * the one-shot guard reads the current render's spec, so a seed without it
+ * could not enforce `oneShot`. A system seed never carries one.
+ *
+ * It also carries the card's `epoch` and, when the slice lists them, the
+ * `oneShot` names this card already spent, as the render's record
+ * `{ epoch, actions }` (ggui#1223). `deriveRenderMeta` projected those names
+ * for this card only, so the record's epoch is the card's own and the guard
+ * stops the first gesture on a spent action after a reload.
  */
 export async function buildGguiSessionSeedInput(meta) {
     const props = parseSeedProps(meta.propsJson);
+    const componentFields = {
+        ...(meta.actionSpec !== undefined ? { actionSpec: meta.actionSpec } : {}),
+        ...(typeof meta.epoch === 'number' ? { epoch: meta.epoch } : {}),
+        ...(meta.spentOneShots !== undefined
+            ? { spentOneShots: { epoch: meta.epoch ?? 0, actions: meta.spentOneShots } }
+            : {}),
+    };
     // System-card mode — `kind` keyed against the built-in registry.
     if (meta.kind !== undefined) {
         return {
@@ -1195,6 +1213,7 @@ export async function buildGguiSessionSeedInput(meta) {
             appId: meta.appId,
             componentCode: decodeCodeB64(meta.codeB64),
             ...(props !== undefined ? { props } : {}),
+            ...componentFields,
         };
     }
     // Compiled-component mode — fetch the content-addressable bytes.
@@ -1210,6 +1229,7 @@ export async function buildGguiSessionSeedInput(meta) {
         appId: meta.appId,
         componentCode,
         ...(props !== undefined ? { props } : {}),
+        ...componentFields,
     };
 }
 /**
@@ -1398,10 +1418,7 @@ export async function resolveMetaViaReadDoor(app, locator) {
     const envelope = readGguiShellEnvelope(text);
     if (envelope === undefined)
         return null;
-    const parsed = parseMcpAppAiGguiRenderMeta(envelope, {
-        onInvalidTheme: reportInvalidAppTheme,
-        onStrippedThemeMembers: reportStrippedThemeMembers,
-    });
+    const parsed = parseMcpAppAiGguiRenderMeta(envelope, READ_DOOR_REPORTERS);
     if (!parsed.ok || parsed.meta === undefined)
         return null;
     const validated = validateMeta(parsed.meta);

package/dist/types.d.ts

@@ -37,9 +37,12 @@ type GguiSessionLedgerFields = 'eventSequence' | 'createdAt' | 'lastActivityAt'
  * the seed with the authoritative `GguiSession`.
  *
  * Carries the SAME contract-spec fields a full `ComponentGguiSession` does
- * (`propsSpec` / `streamSpec` / `actionSpec`), as `undefined` on a
- * seed — so the channel handlers that read those after the
- * `type !== 'mcpApps' && type !== 'system'` narrowing stay type-clean.
+ * (`propsSpec` / `streamSpec` / `actionSpec`), so the channel handlers that
+ * read those after the `type !== 'mcpApps' && type !== 'system'` narrowing
+ * stay type-clean. On a seed, `propsSpec` and `streamSpec` are `undefined`;
+ * `actionSpec` is the slice's own when the slice carried one (ggui#1178), and
+ * so are `epoch` and the spent-`oneShot` record built from the slice's
+ * `spentOneShots` (ggui#1223).
  */
 export type GguiSessionSeedInput = Omit<ComponentGguiSession, GguiSessionLedgerFields> | Omit<SystemGguiSession, GguiSessionLedgerFields>;
 /**
@@ -58,9 +61,10 @@ export type GguiSessionSeedInput = Omit<ComponentGguiSession, GguiSessionLedgerF
  *     deferred.)
  *   - `MISSING_META_GGUI_BOOTSTRAP` — `params` is an object but
  *     `params._meta` is absent or carries no `ai.ggui/render` slice.
- *     The on-wire synonym is `BOOTSTRAP_META_MISSING`. (Name retained
- *     pre-R4 for the observability + host-postMessage protocol;
- *     cosmetic rename is deferred.)
+ *     This is the spelling emitted on `ggui:bootstrap-failed`;
+ *     `BOOTSTRAP_META_MISSING` is a synonym a host classifies alike
+ *     (SPEC §5.5.2). (Name retained pre-R4 for the observability +
+ *     host-postMessage protocol; cosmetic rename is deferred.)
  *   - `MALFORMED_BOOTSTRAP` — slice is present but fails business
  *     rules (no live mode and no static content, mode discriminators
  *     mutually exclusive, structural rejection by the combiner).

package/dist/wire-config.js

@@ -1,6 +1,7 @@
 import { buildWireConfig, StreamBus, } from '@ggui-ai/wire';
 import { validateOutboundActionEnvelope } from './validation.js';
 import { defaultProtocolErrorEmitter, fromClientContractViolation, } from './protocol-error.js';
+import { postObservabilityToParent } from './observability.js';
 // `StreamBus` (and its bounded reserved-channel replay ring) lives in
 // `@ggui-ai/wire` (one implementation for every first-party renderer).
 // It was originally hoisted to share with `<GguiRender>` — that
@@ -45,6 +46,27 @@ export function buildRootWireConfig(opts) {
         }
         emitProtocolError(fromClientContractViolation(err));
     }
+    // ggui#1178 — a card paints and takes gestures even when no action spec
+    // reached it (a mount past the WS token's TTL, a host with no live channel,
+    // an older server that never put the spec on the render slice). The one-shot
+    // guard then cannot know an action is `oneShot` and fails open. The runtime's
+    // obligation is to NAME that, never silently: once per component render, as
+    // the `one-shot-unenforceable` observability event posted to the embedding
+    // host (the channel every other degradation in this runtime uses), and the
+    // dispatch proceeds. It is named on the first spec-less DISPATCH, not at
+    // paint: an absent spec also means "this card declares no actions", so a
+    // paint-time name would fire on every display-only card. System and mcpApps
+    // renders carry no spec by design and are never named.
+    let namedUnenforceableFor = null;
+    const nameUnenforceableOnce = (actionName) => {
+        const currentRender = opts.getCurrentGguiSession();
+        if (currentRender === null || currentRender.type === 'mcpApps' || currentRender.type === 'system')
+            return;
+        if (namedUnenforceableFor === currentRender.id)
+            return;
+        namedUnenforceableFor = currentRender.id;
+        postObservabilityToParent({ kind: 'one-shot-unenforceable', renderId: currentRender.id, actionName });
+    };
     return buildWireConfig({
         app: { appId: opts.appId, appName: opts.appId },
         // `isConnected` here is the static config field; `useRender()`
@@ -64,6 +86,21 @@ export function buildRootWireConfig(opts) {
                 ? currentRender.actionSpec
                 : undefined;
         },
+        onActionSpecAbsent: nameUnenforceableOnce,
+        // ggui#1223 — the card's persisted spent `oneShot` names. A re-served card
+        // boots a new iframe, so the guard's in-memory set starts empty; the
+        // render's record says what this card already spent. It counts only when
+        // written on THIS card (its epoch is the render's own; absent ⇒ 0), the
+        // same gate `deriveRenderMeta` applies, since a `ggui_update` mints a fresh
+        // card whose record would otherwise carry over.
+        getSpentOneShots: () => {
+            const currentRender = opts.getCurrentGguiSession();
+            if (currentRender === null || currentRender.type === 'mcpApps' || currentRender.type === 'system') {
+                return undefined;
+            }
+            const record = currentRender.spentOneShots;
+            return record !== undefined && record.epoch === (currentRender.epoch ?? 0) ? record.actions : undefined;
+        },
         // The iframe's precompiled-validator variant — the dispatch never
         // trips the iframe's no-`unsafe-eval` CSP.
         validateEnvelope: validateOutboundActionEnvelope,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/iframe-runtime",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "The iframe-local ggui runtime: a self-contained ESM bundle that boots inside an MCP Apps host iframe, runs the protocol-version handshake, opens the live-channel WebSocket, and mounts the rendered UI. Bundles React, ReactDOM, and the ggui design system so generated component code has a single seam to read from.",
   "keywords": [
     "ggui",
@@ -41,12 +41,12 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.21.0",
-    "@ggui-ai/gadgets": "0.21.0",
-    "@ggui-ai/live-channel": "0.21.0",
-    "@ggui-ai/protocol": "0.21.0",
-    "@ggui-ai/wire": "0.21.0",
-    "@ggui-ai/preview-a2ui": "0.21.0"
+    "@ggui-ai/live-channel": "0.23.0",
+    "@ggui-ai/preview-a2ui": "0.23.0",
+    "@ggui-ai/protocol": "0.23.0",
+    "@ggui-ai/gadgets": "0.23.0",
+    "@ggui-ai/design": "0.23.0",
+    "@ggui-ai/wire": "0.23.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0"