@ggui-ai/iframe-runtime 0.22.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, ActionSpecInvalidEvent, ActionSpecMemberStrippedEvent, 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

@@ -49,6 +49,13 @@ export declare function reportInvalidActionSpec(issues: readonly string[]): void
  * `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

package/dist/meta-parse.js

@@ -255,6 +255,9 @@ function projectMeta(meta, hasStaticContent) {
         // 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
@@ -368,6 +371,15 @@ export function reportInvalidActionSpec(issues) {
 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
@@ -380,6 +392,7 @@ export const READ_DOOR_REPORTERS = {
     onStrippedThemeMembers: reportStrippedThemeMembers,
     onInvalidActionSpec: reportInvalidActionSpec,
     onStrippedActionSpecMembers: reportStrippedActionSpecMembers,
+    onInvalidSpentOneShots: reportInvalidSpentOneShots,
 };
 /**
  * Parse the render slice from `globalThis.__GGUI_META__` — the

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 | ActionSpecInvalidEvent | ActionSpecMemberStrippedEvent | OneShotUnenforceableEvent | 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
@@ -402,6 +402,18 @@ export interface OneShotUnenforceableEvent {
     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

@@ -529,6 +529,12 @@ export declare function readSelfContainedMeta(): McpAppAiGguiRenderMeta | null;
  * (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

@@ -1180,10 +1180,22 @@ function parseSeedProps(propsJson) {
  * (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 actionSpec = meta.actionSpec !== undefined ? { actionSpec: meta.actionSpec } : {};
+    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 {
@@ -1201,7 +1213,7 @@ export async function buildGguiSessionSeedInput(meta) {
             appId: meta.appId,
             componentCode: decodeCodeB64(meta.codeB64),
             ...(props !== undefined ? { props } : {}),
-            ...actionSpec,
+            ...componentFields,
         };
     }
     // Compiled-component mode — fetch the content-addressable bytes.
@@ -1217,7 +1229,7 @@ export async function buildGguiSessionSeedInput(meta) {
         appId: meta.appId,
         componentCode,
         ...(props !== undefined ? { props } : {}),
-        ...actionSpec,
+        ...componentFields,
     };
 }
 /**

package/dist/types.d.ts

@@ -40,7 +40,9 @@ type GguiSessionLedgerFields = 'eventSequence' | 'createdAt' | 'lastActivityAt'
  * (`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).
+ * `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>;
 /**
@@ -59,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

@@ -87,6 +87,20 @@ export function buildRootWireConfig(opts) {
                 : 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.22.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.22.0",
-    "@ggui-ai/live-channel": "0.22.0",
-    "@ggui-ai/preview-a2ui": "0.22.0",
-    "@ggui-ai/gadgets": "0.22.0",
-    "@ggui-ai/protocol": "0.22.0",
-    "@ggui-ai/wire": "0.22.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"