@ggui-ai/iframe-runtime 0.12.0 → 0.14.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, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayIncapabilityEvent, UnknownObservabilityEvent, } from './observability.js';
-export { postObservabilityToParent } from './observability.js';
+export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, 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/index.js

@@ -1,4 +1,4 @@
 export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
 export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
-export { postObservabilityToParent } from './observability.js';
+export { isObservabilityMessage, isRelayDeadTapEvent, isRelayIncapabilityEvent, postObservabilityToParent, } from './observability.js';
 export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

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 | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | UnknownObservabilityEvent;
+export type ObservabilityEvent = SchemaVersionMismatchEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | RelayDeadTapEvent | UnknownObservabilityEvent;
 /**
  * Fired when the protocol-version handshake rejects the connection.
  * Parallel to `UpgradeRequiredError` — the host can choose to render
@@ -151,10 +151,7 @@ export interface ChannelPollRecoveredEvent {
  * mirror `UiFeedbackPayload` in `@ggui-ai/mcp-apps-react` / `@ggui-ai/mcp-apps-react-native`
  * (the host-chrome twin of this affordance):
  *
- *   - `verdict` — `'love'` / `'dislike'`, or `'other'` for the
- *     free-text flow.
- *   - `comment` — present only for `verdict: 'other'` with a non-empty
- *     trimmed comment.
+ *   - `verdict` — `'up'` / `'down'` (the two thumb verdicts, #653).
  *   - `sessionId` / `toolName` — present exactly when the runtime knew
  *     them at mount time.
  *
@@ -175,34 +172,47 @@ export interface ChannelPollRecoveredEvent {
  */
 export interface UiFeedbackEvent {
     readonly kind: 'ui-feedback';
-    readonly verdict: 'love' | 'dislike' | 'other';
-    /** Trimmed free-text comment; only on `verdict: 'other'`, never empty. */
-    readonly comment?: string;
+    readonly verdict: 'up' | 'down';
     /** GguiSession id of the render the feedback is about. */
     readonly sessionId?: string;
     /** Tool that produced the render (e.g. `ggui_render`). */
     readonly toolName?: string;
 }
+/**
+ * The evidence that latched a relay dead zone (ggui#599 cycle-2):
+ * `'confirmed-refusal'` — the relay answered a declared refusal code
+ * (helper-minted; outranks any positive advertisement), vs
+ * `'advert-silent'` — the host never advertised `serverTools` and the
+ * attempt failed relay-shaped.
+ *
+ * @public
+ */
+export type RelayLatchTrigger = 'confirmed-refusal' | 'advert-silent';
 /**
  * Fired at the two transition edges of the renderer's
  * relay-incapability latch — the runtime's confirmed determination
  * that the host cannot relay `tools/call` to the MCP server:
  *
- *   - `'latched'` — a real user gesture just failed relay-shaped (no
- *     well-formed result envelope came back at all) on a host whose
- *     captured capability handshake never advertised `serverTools`.
+ *   - `'latched'` — a real user gesture just failed relay-shaped on a
+ *     host whose captured capability handshake never advertised
+ *     `serverTools`, or the relay answered a declared refusal code.
  *     The runtime now treats relay as confirmed-unavailable: it shows
- *     one persistent explanation instead of a per-gesture error toast,
- *     and channel polls fail fast without a transport round-trip.
+ *     one persistent explanation, arms the dead-zone cue for every
+ *     later gesture, and channel polls fail fast without a transport
+ *     round-trip.
  *   - `'cleared'` — a later well-formed result envelope arrived
  *     (`ok:true` and `ok:false` alike — either proves the host relayed
- *     the call there and back), so the determination no longer holds;
- *     per-gesture feedback and channel transport attempts resume.
+ *     the call there and back), so the determination no longer holds.
+ *     Carries the dead zone's summary: how long it stood and how many
+ *     gestures were attempted inside it.
  *
- * Emitted once per edge, never per channel poll tick: repeated failing
- * gestures while latched emit nothing further, and the router's
- * fail-fast ticks emit nothing at all — the edges carry the full
- * information.
+ * Emitted once per edge, never per channel poll tick. Gestures
+ * attempted while latched are NOT silent on this stream: each one is a
+ * {@link RelayDeadTapEvent} (ggui#670 Phase 3) — one per real user
+ * gesture, never per tick — so a host can count dead taps and measure
+ * dead-tap-to-recovery without watching the render. A boot that finds
+ * a latch standing from a prior mount closes it with a `'cleared'`
+ * edge before the new session starts.
  *
  * Always emitted via the postMessage-to-parent default — the emission
  * sites live in module-level gesture-dispatch code outside the boot
@@ -210,9 +220,61 @@ export interface UiFeedbackEvent {
  *
  * @public
  */
-export interface RelayIncapabilityEvent {
+export type RelayIncapabilityEvent = {
     readonly kind: 'relay-incapability';
-    readonly state: 'latched' | 'cleared';
+    readonly state: 'latched';
+    readonly trigger: RelayLatchTrigger;
+    /** GguiSession id of the render, when the latching gesture carried one. */
+    readonly sessionId?: string;
+    /** App id of the render, when the latching gesture carried one. */
+    readonly appId?: string;
+} | {
+    readonly kind: 'relay-incapability';
+    readonly state: 'cleared';
+    /** How long the dead zone stood, in milliseconds. */
+    readonly latchedForMs: number;
+    /**
+     * Gestures attempted inside the zone — equals the last
+     * {@link RelayDeadTapEvent} `ordinal` this edge closes (0 when
+     * none was attempted).
+     */
+    readonly deadTaps: number;
+    readonly sessionId?: string;
+    readonly appId?: string;
+};
+/**
+ * A user gesture attempted while the relay-incapability latch stands
+ * (ggui#670 Phase 3). The runtime never suppresses the attempt — the
+ * attempt is the self-heal sensor (ggui#443) — and presents it in the
+ * document (pulse, spoken cue, fallback toast); this event makes the
+ * attempt COUNTABLE by the host.
+ *
+ * Contract: exactly one per gesture attempted while latched whose
+ * attempt comes back undelivered (relay-shaped failure or a declared
+ * refusal); never emitted off-latch, and never from the channel
+ * router's fail-fast ticks. Counted at the outcome, not the tap: the
+ * gesture that latched the zone is the `'latched'` edge and the gesture
+ * that heals it is the `'cleared'` edge — neither is a dead tap.
+ * `ordinal` counts from 1 within one dead zone; the `'cleared'` edge
+ * reports the total as `deadTaps`. `latchAgeMs` is measured when the
+ * outcome lands. Hosts MUST tolerate the event being absent (an older
+ * renderer) — absence means no attempt was observed, not that none
+ * happened.
+ *
+ * @public
+ */
+export interface RelayDeadTapEvent {
+    readonly kind: 'relay-dead-tap';
+    /** The gesture's intent — the action name the component dispatched. */
+    readonly intent: string;
+    /** Milliseconds since the latch set. */
+    readonly latchAgeMs: number;
+    /** 1-based position of this attempt within the current dead zone. */
+    readonly ordinal: number;
+    /** The evidence that latched the zone this attempt landed in. */
+    readonly trigger: RelayLatchTrigger;
+    readonly sessionId?: string;
+    readonly appId?: string;
 }
 /**
  * Catch-all branch for event kinds the host's typings don't recognize.
@@ -250,6 +312,52 @@ export interface ObservabilityMessage {
  * @public
  */
 export type ObservabilityEmitter = (event: ObservabilityEvent) => void;
+/**
+ * Type guard for the `ggui:observe` envelope as it arrives on a host's
+ * `message` listener — narrows `event.data` to {@link ObservabilityMessage}.
+ * Read fields through the per-kind guards, never through
+ * `switch (event.kind)`: the union's open tail (`kind: string & {}`)
+ * keeps TypeScript from using `kind` as a discriminant, so a `case`
+ * body sees the whole union. Unknown kinds stay in that tail: hosts
+ * MUST ignore them, never throw.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   isObservabilityMessage,
+ *   isRelayDeadTapEvent,
+ *   isRelayIncapabilityEvent,
+ * } from '@ggui-ai/iframe-runtime/observability';
+ *
+ * window.addEventListener('message', ({ data, source }) => {
+ *   if (source !== iframe.contentWindow || !isObservabilityMessage(data)) return;
+ *   const { event } = data;
+ *   if (isRelayDeadTapEvent(event)) count(event.intent, event.latchAgeMs);
+ *   else if (isRelayIncapabilityEvent(event) && event.state === 'cleared') recovered(event.deadTaps);
+ *   // any other kind: ignore
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function isObservabilityMessage(value: unknown): value is ObservabilityMessage;
+/**
+ * Narrows to {@link RelayDeadTapEvent}. The union's open tail
+ * (`kind: string & {}`) keeps TypeScript from using `kind` as a
+ * discriminant, so `switch (event.kind)` never narrows across
+ * {@link ObservabilityEvent} — hosts read fields through the per-kind
+ * guards (first-consumer finding, ggui#670 Phase 3).
+ *
+ * @public
+ */
+export declare function isRelayDeadTapEvent(event: ObservabilityEvent): event is RelayDeadTapEvent;
+/**
+ * Narrows to {@link RelayIncapabilityEvent}; inside it `state`
+ * discriminates the `'latched'` / `'cleared'` edges normally.
+ *
+ * @public
+ */
+export declare function isRelayIncapabilityEvent(event: ObservabilityEvent): event is RelayIncapabilityEvent;
 /**
  * Default emitter — posts an {@link ObservabilityMessage} to
  * `window.parent`. Mirrors `postBootFailure` / `postRendererReady`

package/dist/observability.js

@@ -1,4 +1,63 @@
 import { MCP_APP_OBSERVE_TYPE } from '@ggui-ai/protocol/integrations/mcp-apps';
+/**
+ * Type guard for the `ggui:observe` envelope as it arrives on a host's
+ * `message` listener — narrows `event.data` to {@link ObservabilityMessage}.
+ * Read fields through the per-kind guards, never through
+ * `switch (event.kind)`: the union's open tail (`kind: string & {}`)
+ * keeps TypeScript from using `kind` as a discriminant, so a `case`
+ * body sees the whole union. Unknown kinds stay in that tail: hosts
+ * MUST ignore them, never throw.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   isObservabilityMessage,
+ *   isRelayDeadTapEvent,
+ *   isRelayIncapabilityEvent,
+ * } from '@ggui-ai/iframe-runtime/observability';
+ *
+ * window.addEventListener('message', ({ data, source }) => {
+ *   if (source !== iframe.contentWindow || !isObservabilityMessage(data)) return;
+ *   const { event } = data;
+ *   if (isRelayDeadTapEvent(event)) count(event.intent, event.latchAgeMs);
+ *   else if (isRelayIncapabilityEvent(event) && event.state === 'cleared') recovered(event.deadTaps);
+ *   // any other kind: ignore
+ * });
+ * ```
+ *
+ * @public
+ */
+export function isObservabilityMessage(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const probe = value;
+    if (probe.type !== MCP_APP_OBSERVE_TYPE)
+        return false;
+    if (typeof probe.event !== 'object' || probe.event === null)
+        return false;
+    return typeof probe.event.kind === 'string';
+}
+/**
+ * Narrows to {@link RelayDeadTapEvent}. The union's open tail
+ * (`kind: string & {}`) keeps TypeScript from using `kind` as a
+ * discriminant, so `switch (event.kind)` never narrows across
+ * {@link ObservabilityEvent} — hosts read fields through the per-kind
+ * guards (first-consumer finding, ggui#670 Phase 3).
+ *
+ * @public
+ */
+export function isRelayDeadTapEvent(event) {
+    return event.kind === 'relay-dead-tap';
+}
+/**
+ * Narrows to {@link RelayIncapabilityEvent}; inside it `state`
+ * discriminates the `'latched'` / `'cleared'` edges normally.
+ *
+ * @public
+ */
+export function isRelayIncapabilityEvent(event) {
+    return event.kind === 'relay-incapability';
+}
 /**
  * Default emitter — posts an {@link ObservabilityMessage} to
  * `window.parent`. Mirrors `postBootFailure` / `postRendererReady`

package/dist/react-renderer.d.ts

@@ -30,6 +30,7 @@
  * TypeScript config doesn't need a JSX runtime plumbing.
  */
 import React, { type ReactNode } from 'react';
+import type { AppTheme } from '@ggui-ai/protocol';
 export interface ReactRootMountOptions {
     /**
      * GguiSession whose componentCode + props drive the mount. Only
@@ -98,11 +99,7 @@ export interface ReactRootMountOptions {
          * painted ladder to its registration record); the renderer
          * carries it but exposes no observability surface for it today.
          */
-        readonly base?: {
-            readonly documentHash: string;
-            readonly light: Readonly<Record<string, string>>;
-            readonly dark: Readonly<Record<string, string>>;
-        };
+        readonly base?: NonNullable<AppTheme['base']>;
     };
     /**
      * Host-announced palette, already translated onto `--ggui-*` tokens

package/dist/react-renderer.js

@@ -329,7 +329,15 @@ export async function mountReactRoot(container, opts) {
                 // ladder gets — base inherits, derived gradient/effect tokens
                 // (color-mix fallback split), box-sizing, font-inherit — from
                 // ONE shared builder, so the two paths cannot drift.
-                assembleDeliveredThemeCss(scopeClass, opts.themeMode === 'dark' ? deliveredBase.dark : deliveredBase.light)
+                assembleDeliveredThemeCss(scopeClass, opts.themeMode === 'dark' ? deliveredBase.dark : deliveredBase.light, {
+                    // ggui#613 residual 2 — the two former v1 deltas ride:
+                    // the active mode's keyframes block + the frameless
+                    // silhouette suppression, both same-rule as compiled.
+                    keyframes: opts.themeMode === 'dark'
+                        ? deliveredBase.keyframes?.dark
+                        : deliveredBase.keyframes?.light,
+                    frameless: deliveredBase.frameless,
+                })
             : opts.themeId
                 ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
                 : getScopedCssTokens(scopeClass, opts.themeMode);
@@ -367,9 +375,17 @@ export async function mountReactRoot(container, opts) {
         // `ThemeProvider` so a Studio/Portal context with both runtime + RP
         // active doesn't double-stack.
         if (typeof document !== 'undefined') {
-            let rootCss = opts.themeId
-                ? getThemeCss(opts.themeId, opts.themeMode)
-                : getCssTokens(opts.themeMode);
+            // ggui#613 residual 5: under a DELIVERED base the body-chrome
+            // ladder is the delivered set too — mirroring the scoped ternary
+            // above — so the standalone viewer's body chrome and its tree
+            // content resolve the same values. Pre-fix this started from the
+            // compiled/default ladder regardless, and body chrome painted the
+            // default brand under a registered theme.
+            let rootCss = deliveredBase !== undefined
+                ? `:root{${toCssDecls(opts.themeMode === 'dark' ? deliveredBase.dark : deliveredBase.light)}}`
+                : opts.themeId
+                    ? getThemeCss(opts.themeId, opts.themeMode)
+                    : getCssTokens(opts.themeMode);
             if (opts.hostPalette) {
                 // BODY-CHROME ONLY, same as the appTheme `:root` append below —
                 // and beneath it, mirroring the scoped-block order (#573:

package/dist/render-item.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { GguiSession } from '@ggui-ai/protocol';
+import type { AppTheme, GguiSession } from '@ggui-ai/protocol';
 import type { GguiSessionSeedInput } from './types.js';
 import { type WireConfig } from '@ggui-ai/wire';
 import type { StreamBus } from './wire-config.js';
@@ -59,11 +59,7 @@ export interface RenderItemOptions {
     readonly appTheme?: {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
-        readonly base?: {
-            readonly documentHash: string;
-            readonly light: Readonly<Record<string, string>>;
-            readonly dark: Readonly<Record<string, string>>;
-        };
+        readonly base?: NonNullable<AppTheme['base']>;
     };
     /**
      * Host-announced palette, pre-mapped onto `--ggui-*` tokens by the

package/dist/runtime.d.ts

@@ -56,6 +56,15 @@ import { type LifecycleEmitter } from './lifecycle.js';
  */
 type DrainAckListener = (payload: DrainAckPayload) => boolean | void;
 export declare function subscribeDrainAck(listener: DrainAckListener): () => void;
+/**
+ * The `drain_ack` ingress — fans a frame out to subscribers until one
+ * claims it.
+ *
+ * @internal — exported for unit tests: a late ack for an earlier
+ * delivered gesture is the path that retires the standing relay notice
+ * without any user click (ggui#670 Phase 3, truth-2).
+ */
+export declare function dispatchDrainAck(payload: DrainAckPayload): void;
 export type ConnectAppResult = {
     readonly ok: true;
 } | {
@@ -276,6 +285,18 @@ export interface BootSequenceOptions {
      * or not this option is bound.
      */
     readonly onObserve?: ObservabilityEmitter;
+    /**
+     * Opt-in knob for the in-iframe UI-feedback chrome (#653). DEFAULT
+     * OFF by founder ruling — a generated component card carries no
+     * feedback affordance unless the embedding deployment passes `true`
+     * here. Even when opted in, the #471 live-sink gate still applies
+     * (see `shouldMountUiFeedbackChrome`): hosts that drop the
+     * `ggui:observe` envelope never get the affordance. Chrome
+     * configuration, not wire data — the agent cannot observe this knob
+     * (data-vs-behavior), so it is a boot option, never a contract
+     * field.
+     */
+    readonly uiFeedback?: boolean;
     /**
      * Optional {@link LifecycleEmitter} sink. Fires on every renderer
      * mount-state transition (`mounting` → `code-ready` | `error`,
@@ -648,6 +669,16 @@ interface ToastLiveRegions {
  * @internal — exported for unit tests.
  */
 export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions | null;
+/**
+ * Boot-time reset of the relay latch (ggui#670 Phase 3). A latch
+ * standing from a prior mount in a re-booted document is closed through
+ * the ONE writer — the host gets its `cleared` edge with the zone's
+ * summary — and the prior mount's standing notice is removed rather
+ * than left describing a session that no longer exists.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function resetRelayLatchForBoot(): void;
 /** @internal — exported for unit tests to reset module state. */
 export declare function __resetRelayNoticeForTest(): void;
 /**