@ggui-ai/iframe-runtime 0.20.0 → 0.22.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, ThemeReinjectFailedEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayDeadTapEvent, RelayIncapabilityEvent, RelayLatchTrigger, 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,29 @@ 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;
+/**
+ * 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,10 @@ 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 } : {}),
         ...(gadgets !== undefined ? { gadgets } : {}),
         ...(publicEnv !== undefined ? { publicEnv } : {}),
         ...(streamWebSocketLocalTools !== undefined
@@ -345,6 +349,38 @@ 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] });
+}
+/**
+ * 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,
+};
 /**
  * Parse the render slice from `globalThis.__GGUI_META__` — the
  * synchronous self-contained shell delivery channel.
@@ -367,10 +403,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 +454,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 | 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,44 @@ 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 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/runtime.d.ts

@@ -524,6 +524,11 @@ 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.
  */
 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,15 @@ 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.
  */
 export async function buildGguiSessionSeedInput(meta) {
     const props = parseSeedProps(meta.propsJson);
+    const actionSpec = meta.actionSpec !== undefined ? { actionSpec: meta.actionSpec } : {};
     // System-card mode — `kind` keyed against the built-in registry.
     if (meta.kind !== undefined) {
         return {
@@ -1195,6 +1201,7 @@ export async function buildGguiSessionSeedInput(meta) {
             appId: meta.appId,
             componentCode: decodeCodeB64(meta.codeB64),
             ...(props !== undefined ? { props } : {}),
+            ...actionSpec,
         };
     }
     // Compiled-component mode — fetch the content-addressable bytes.
@@ -1210,6 +1217,7 @@ export async function buildGguiSessionSeedInput(meta) {
         appId: meta.appId,
         componentCode,
         ...(props !== undefined ? { props } : {}),
+        ...actionSpec,
     };
 }
 /**
@@ -1398,10 +1406,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/shims/tokens.js

@@ -1 +1 @@
-const M = (globalThis.__ggui__&&globalThis.__ggui__["tokens"]||window["__GGUI_TOKENS"]||{}); export const animation = M["animation"]; export const duration = M["duration"]; export const easing = M["easing"]; export const transition = M["transition"]; export const keyframes = M["keyframes"]; export const thinkingAnimation = M["thinkingAnimation"]; export const thinkingKeyframes = M["thinkingKeyframes"]; export const thinkingPresets = M["thinkingPresets"]; export const THINKING_DEFAULT_STYLE = M["THINKING_DEFAULT_STYLE"]; export const motionSafe = M["motionSafe"]; export const reducedMotion = M["reducedMotion"]; export const reducedMotionCSS = M["reducedMotionCSS"]; export const colors = M["colors"]; export const gray = M["gray"]; export const primary = M["primary"]; export const semantic = M["semantic"]; export const chartColors = M["chartColors"]; export const success = M["success"]; export const warning = M["warning"]; export const error = M["error"]; export const info = M["info"]; export const highContrast = M["highContrast"]; export const typography = M["typography"]; export const fontFamily = M["fontFamily"]; export const fontSize = M["fontSize"]; export const fontSizeValues = M["fontSizeValues"]; export const fontWeight = M["fontWeight"]; export const lineHeight = M["lineHeight"]; export const letterSpacing = M["letterSpacing"]; export const headingStyles = M["headingStyles"]; export const spacing = M["spacing"]; export const spacingValues = M["spacingValues"]; export const radius = M["radius"]; export const shadow = M["shadow"]; export const elevation = M["elevation"]; export const maxWidth = M["maxWidth"]; export const zIndex = M["zIndex"]; export const accessibility = M["accessibility"]; export const focusRing = M["focusRing"]; export const nativeTokens = M["nativeTokens"]; export const tokens = M["tokens"]; export default M;
+const M = (globalThis.__ggui__&&globalThis.__ggui__["tokens"]||window["__GGUI_TOKENS"]||{}); export const animation = M["animation"]; export const duration = M["duration"]; export const easing = M["easing"]; export const transition = M["transition"]; export const motionVar = M["motionVar"]; export const keyframes = M["keyframes"]; export const thinkingAnimation = M["thinkingAnimation"]; export const thinkingKeyframes = M["thinkingKeyframes"]; export const thinkingPresets = M["thinkingPresets"]; export const THINKING_DEFAULT_STYLE = M["THINKING_DEFAULT_STYLE"]; export const motionSafe = M["motionSafe"]; export const reducedMotion = M["reducedMotion"]; export const reducedMotionCSS = M["reducedMotionCSS"]; export const colors = M["colors"]; export const gray = M["gray"]; export const primary = M["primary"]; export const semantic = M["semantic"]; export const chartColors = M["chartColors"]; export const success = M["success"]; export const warning = M["warning"]; export const error = M["error"]; export const info = M["info"]; export const highContrast = M["highContrast"]; export const typography = M["typography"]; export const fontFamily = M["fontFamily"]; export const fontSize = M["fontSize"]; export const fontSizeValues = M["fontSizeValues"]; export const fontWeight = M["fontWeight"]; export const lineHeight = M["lineHeight"]; export const letterSpacing = M["letterSpacing"]; export const headingStyles = M["headingStyles"]; export const spacing = M["spacing"]; export const spacingValues = M["spacingValues"]; export const radius = M["radius"]; export const shadow = M["shadow"]; export const elevation = M["elevation"]; export const maxWidth = M["maxWidth"]; export const zIndex = M["zIndex"]; export const accessibility = M["accessibility"]; export const focusRing = M["focusRing"]; export const nativeTokens = M["nativeTokens"]; export const tokens = M["tokens"]; export default M;

package/dist/types.d.ts

@@ -37,9 +37,10 @@ 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).
  */
 export type GguiSessionSeedInput = Omit<ComponentGguiSession, GguiSessionLedgerFields> | Omit<SystemGguiSession, GguiSessionLedgerFields>;
 /**

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,7 @@ export function buildRootWireConfig(opts) {
                 ? currentRender.actionSpec
                 : undefined;
         },
+        onActionSpecAbsent: nameUnenforceableOnce,
         // 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.20.0",
+  "version": "0.22.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.20.0",
-    "@ggui-ai/gadgets": "0.20.0",
-    "@ggui-ai/live-channel": "0.20.0",
-    "@ggui-ai/preview-a2ui": "0.20.0",
-    "@ggui-ai/protocol": "0.20.0",
-    "@ggui-ai/wire": "0.20.0"
+    "@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"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0"