@ggui-ai/iframe-runtime 0.22.0 → 0.24.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/render-item.d.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
 import type { AppTheme, GguiSession } from '@ggui-ai/protocol/wire';
 import type { GguiSessionSeedInput } from './types.js';
-import { type WireConfig } from '@ggui-ai/wire';
+import { type BuiltWireConfig } from '@ggui-ai/wire';
 import type { StreamBus } from './wire-config.js';
 export interface RenderItemOptions {
     /** The render to mount. */
@@ -10,8 +10,10 @@ export interface RenderItemOptions {
      *  `buildRootWireConfig(...)` (see `wire-config.ts`). `null` ⇒ the
      *  component mounts without a wire provider (standalone — matches
      *  today's DynamicComponent fallback when no GguiRender parent is
-     *  present). */
-    readonly scopedWireConfig: WireConfig | null;
+     *  present). The config carries the card's `actionSpent` source
+     *  (ggui#1223), and the component mounts inside `ActionSpentContext` too,
+     *  so `useActionSpent` reads the one-shot guard's own spent set. */
+    readonly scopedWireConfig: BuiltWireConfig | null;
     /** Shared stream bus — provisional renderer subscribes to
      *  `_ggui:preview` for this render. */
     readonly streamBus: StreamBus;

package/dist/render-item.js

@@ -39,6 +39,7 @@
  */
 import { createElement } from 'react';
 import { GguiWireProvider } from '@ggui-ai/wire';
+import { ActionSpentContext } from '@ggui-ai/wire/internal';
 import { mountReactRoot } from './react-renderer.js';
 import { mountProvisional, } from './provisional-renderer.js';
 import { mountMcpAppIframe, } from './mcp-app-iframe-host.js';
@@ -208,9 +209,13 @@ export async function mountRender(container, opts) {
      * mount. When absent, the wire provider is the only wrapper.
      */
     function wrapInScopedProvider(mountedComponent) {
-        const wireWrapped = currentOpts.scopedWireConfig === null
+        const config = currentOpts.scopedWireConfig;
+        const wireWrapped = config === null
             ? mountedComponent
-            : createElement(GguiWireProvider, { config: currentOpts.scopedWireConfig, children: mountedComponent });
+            : createElement(GguiWireProvider, {
+                config,
+                children: createElement(ActionSpentContext.Provider, { value: config.actionSpent, children: mountedComponent }),
+            });
         return currentOpts.wrapOuter !== undefined
             ? currentOpts.wrapOuter(wireWrapped)
             : wireWrapped;

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,
     };
 }
 /**
@@ -3782,6 +3794,15 @@ async function bootProduction(opts) {
             // through `currentRender`-returning thunks so they always see the
             // latest snapshot without holding stale refs.
             let currentRender = null;
+            // ggui#1223 — who to tell when `currentRender` is replaced, so the card's
+            // spent state (read through `getCurrentGguiSession`) is re-read at once.
+            const renderListeners = new Set();
+            const onRenderChange = (listener) => {
+                renderListeners.add(listener);
+                return () => {
+                    renderListeners.delete(listener);
+                };
+            };
             let renderHandle = null;
             const dispatchToolName = resolveDispatchToolName();
             // Native-idiom interceptors — the replacement for the retired
@@ -3829,6 +3850,7 @@ async function bootProduction(opts) {
                 sessionId: meta.sessionId,
                 appId: meta.appId,
                 getCurrentGguiSession: () => currentRender,
+                renderChanges: onRenderChange,
                 manager,
                 streamBus,
                 onDispatchEnvelope: (envelope) => {
@@ -3986,6 +4008,8 @@ async function bootProduction(opts) {
             };
             const applyRender = async (render) => {
                 currentRender = render;
+                for (const listener of [...renderListeners])
+                    listener();
                 if (renderHandle === null) {
                     renderHandle = await mountRender(renderInto, buildOpts(render));
                     return;

package/dist/shims/wire.js

@@ -1 +1 @@
-const w = globalThis.__ggui__.wire; export const useAction = w.useAction; export const useStream = w.useStream; export const useAuth = w.useAuth; export const useApp = w.useApp; export const useRender = w.useRender; export const useGguiContext = w.useGguiContext; export const useContract = w.useContract; export const useWireContext = w.useWireContext; export const GguiWireProvider = w.GguiWireProvider; export default w;
+const w = globalThis.__ggui__.wire; export const useAction = w.useAction; export const useStream = w.useStream; export const useAuth = w.useAuth; export const useApp = w.useApp; export const useRender = w.useRender; export const useGguiContext = w.useGguiContext; export const useContract = w.useContract; export const useWireContext = w.useWireContext; export const useActionSpent = w.useActionSpent; export const GguiWireProvider = w.GguiWireProvider; export default w;

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.d.ts

@@ -18,7 +18,7 @@
  */
 import type { ActionEnvelope, GguiSession } from '@ggui-ai/protocol/wire';
 import type { GguiSessionSeedInput } from './types.js';
-import { ClientContractViolationError, StreamBus, type WireConfig } from '@ggui-ai/wire';
+import { ClientContractViolationError, StreamBus, type BuiltWireConfig } from '@ggui-ai/wire';
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
 /**
  * Outbound send surface — the minimal shape wire-config calls on the
@@ -48,6 +48,12 @@ export interface BuildRootWireConfigOptions {
      * WireConfig.
      */
     readonly getCurrentGguiSession: () => GguiSession | GguiSessionSeedInput | null;
+    /**
+     * The runtime's notice that the current render was replaced (a props
+     * update, a later live frame), so the card's spent state is re-read at
+     * once (ggui#1223). Passed through as wire's `spentInputsChanged`.
+     */
+    readonly renderChanges?: (listener: () => void) => () => void;
     /** Handle to the renderer's WS manager; used for outbound `action` frames. */
     readonly manager: RendererSendSurface;
     /** Shared bus for inbound stream deliveries. */
@@ -124,4 +130,4 @@ export interface BuildRootWireConfigOptions {
  * `RootWireConfigBundle` / `scopeWireConfig` / `buildScopedConfig`
  * indirection collapsed to a single `WireConfig`.
  */
-export declare function buildRootWireConfig(opts: BuildRootWireConfigOptions): WireConfig;
+export declare function buildRootWireConfig(opts: BuildRootWireConfigOptions): BuiltWireConfig;

package/dist/wire-config.js

@@ -87,6 +87,21 @@ export function buildRootWireConfig(opts) {
                 : undefined;
         },
         onActionSpecAbsent: nameUnenforceableOnce,
+        ...(opts.renderChanges !== undefined ? { spentInputsChanged: opts.renderChanges } : {}),
+        // 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.24.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/design": "0.24.0",
+    "@ggui-ai/gadgets": "0.24.0",
+    "@ggui-ai/live-channel": "0.24.0",
+    "@ggui-ai/preview-a2ui": "0.24.0",
+    "@ggui-ai/protocol": "0.24.0",
+    "@ggui-ai/wire": "0.24.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0"