@ggui-ai/iframe-runtime 0.13.0 → 0.14.0

package/dist/runtime.js

@@ -27,6 +27,7 @@
 // FIRST import on purpose — declares zod jitless before any
 // schema-defining dependency initializes (see zod-jitless.ts).
 import './zod-jitless.js';
+import { connectionStore } 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, } from './meta-parse.js';
@@ -74,7 +75,15 @@ export function subscribeDrainAck(listener) {
         drainAckListeners.delete(listener);
     };
 }
-function dispatchDrainAck(payload) {
+/**
+ * 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 function dispatchDrainAck(payload) {
     for (const listener of drainAckListeners) {
         try {
             if (listener(payload) === true)
@@ -669,6 +678,10 @@ export async function bootSequence(opts) {
     // Fresh boot ⇒ not superseded (matters only for test re-runs that
     // reuse the module; a real iframe boots once).
     mountSuperseded = false;
+    // Fresh boot ⇒ the relay latch and the connection store start
+    // aligned (ggui#670): a standing latch from a prior mount in a
+    // re-booted document must not outlive the store it was written to.
+    resetRelayLatchForBoot();
     telemetry?.record('boot.path', JSON.stringify({
         hasStaticContent,
         hasLiveTrio,
@@ -1606,13 +1619,65 @@ async function callServerToolSpec(toolName, args) {
         return { jsonrpc: '2.0', result: result };
     }
     catch (err) {
+        // Preserve the JSON-RPC error code when the SDK throw carries one
+        // (McpError does) — ggui#599 cycle-2: without it a genuine helper
+        // refusal (-32601 / -32000) is indistinguishable from a socket
+        // drop at both latch call sites, and the confirmed-refusal
+        // classification below this file cannot exist. Code-less throws
+        // stay code-less: transport-shaped, never a confirmed refusal.
+        const code = err.code;
         return {
             error: {
+                ...(typeof code === 'number' ? { code } : {}),
                 message: err instanceof Error ? err.message : String(err),
             },
         };
     }
 }
+/**
+ * Declared relay-refusal registry (ggui#599 cycle-2, finding 34): the
+ * JSON-RPC error codes a HELPER mints to refuse the relay leg itself —
+ * proof the envelope never round-tripped to the server. Server-side
+ * tool failures come back as well-formed `CallToolResult`s (often
+ * `{ok:false}`), never as JSON-RPC errors on this leg, so a registry
+ * code here is helper-minted by construction:
+ *
+ *   - `-32601` — method not supported (the spec's in-band refusal; the
+ *     host-helper conformance catalog's H3 shape). The ONLY registry
+ *     entry, deliberately.
+ *
+ * `-32000` is EXCLUDED by ruling (ggui#599 cycle-2): it collides with
+ * the MCP SDK's `ErrorCode.ConnectionClosed`, so through the App-SDK
+ * catch a helper-minted -32000 refusal and an SDK-local transport loss
+ * are indistinguishable — and a transport loss must NEVER classify
+ * (misbranding a dropped connection as incapability is the
+ * misclassification asymmetry the cycle killed the mount probe over).
+ * The one live -32000 minter (the RN dispatcher's `no-tool-handler`)
+ * was fixed at source to -32601 in the same slice.
+ *
+ * Unknown codes NEVER confirm — they may be proxy- or server-minted
+ * (e.g. `-32603` internal error), and classifying them would misbrand
+ * capable mounts. They stay on the per-gesture transient path.
+ */
+const CONFIRMED_RELAY_REFUSAL_CODES = new Set([-32601]);
+/**
+ * A CONFIRMED relay refusal: the response is an error envelope whose
+ * code is in the declared registry. Strictly stronger evidence than
+ * {@link isRelayShapedFailure} (every confirmed refusal is
+ * relay-shaped; a null/timeout or code-less error never confirms).
+ * Confirmed refusal outranks a positive `serverTools` advertisement at
+ * the latch — classification keys on confirmed attempt outcomes, never
+ * advertisement (#440's doctrine applied symmetrically; the
+ * advertises-but-refuses host is H2's worst dead-tap shape and was
+ * unlatchable before this predicate existed).
+ */
+function isConfirmedRelayRefusal(resp) {
+    return (resp !== null &&
+        resp.error !== undefined &&
+        resp.error !== null &&
+        typeof resp.error.code === 'number' &&
+        CONFIRMED_RELAY_REFUSAL_CODES.has(resp.error.code));
+}
 /**
  * Fire a single canonical action envelope (`tools/call
  * ggui_runtime_submit_action`) carrying the typed `{kind, payload, …}` shape
@@ -1930,13 +1995,12 @@ function hideToast(el) {
     el.setAttribute('aria-hidden', 'true');
     clearToastAnnouncement();
 }
+/** The single action-toast element, reused for every message. */
+const ACTION_TOAST_ID = '__ggui-action-toast__';
 function showActionToast(text, kind, onDismiss) {
     if (typeof document === 'undefined')
         return;
-    const w = window;
-    if (w.__GGUI_TOAST_DISABLED__)
-        return;
-    const id = '__ggui-action-toast__';
+    const id = ACTION_TOAST_ID;
     let el = document.getElementById(id);
     if (!el) {
         el = document.createElement('div');
@@ -1972,6 +2036,9 @@ function showActionToast(text, kind, onDismiss) {
                 : 'rgba(178,54,54,.94)';
     el.style.background = bg;
     el.textContent = text;
+    // Any message rendered here replaces whatever stood before — a
+    // standing relay notice included; the mark goes with it.
+    el.removeAttribute(RELAY_NOTICE_ATTR);
     el.style.opacity = '1';
     el.style.transform = 'translateX(-50%) translateY(0)';
     // Reset to the non-interactive posture every time, so a toast that
@@ -2202,6 +2269,131 @@ function emitUserActionDoorbell(args) {
  * nothing else about the latch is observable to the host.
  */
 let relayIncapabilityAnnounced = false;
+/**
+ * The current dead zone's origin and tally (ggui#670 Phase 3 — the
+ * instrument's state): when the latch set, what set it, which render
+ * it belongs to, and how many gestures have been attempted inside it.
+ * Written only by {@link transitionRelayLatch} and
+ * {@link emitRelayDeadTap}; read by nothing else.
+ */
+let relayLatchedAt;
+let relayDeadTaps = 0;
+let relayLatchTrigger;
+let relayLatchScope = {};
+function transitionRelayLatch(next, trigger, scope = {}) {
+    relayIncapabilityAnnounced = next;
+    connectionStore.set(!next);
+    if (next && trigger !== undefined) {
+        relayLatchedAt = Date.now();
+        relayDeadTaps = 0;
+        relayLatchTrigger = trigger;
+        relayLatchScope = scope;
+        postObservabilityToParent({
+            kind: 'relay-incapability',
+            state: 'latched',
+            trigger,
+            ...scope,
+        });
+        return;
+    }
+    postObservabilityToParent({
+        kind: 'relay-incapability',
+        state: 'cleared',
+        latchedForMs: relayLatchedAt === undefined ? 0 : Date.now() - relayLatchedAt,
+        deadTaps: relayDeadTaps,
+        ...relayLatchScope,
+    });
+    relayLatchedAt = undefined;
+    relayDeadTaps = 0;
+    relayLatchTrigger = undefined;
+    relayLatchScope = {};
+}
+/**
+ * One {@link RelayDeadTapEvent} per gesture attempted inside a standing
+ * dead zone that came back UNDELIVERED (ggui#670 Phase 3). Called from
+ * the dispatch outcome branch ONLY — the channel router's fail-fast
+ * never dispatches, so poll ticks are never counted; off-latch it is a
+ * no-op by construction. Counted at the outcome, not the tap, so the
+ * gesture that heals the zone is never a dead tap.
+ */
+function emitRelayDeadTap(intent, scope) {
+    if (!relayIncapabilityAnnounced ||
+        relayLatchedAt === undefined ||
+        relayLatchTrigger === undefined) {
+        return;
+    }
+    relayDeadTaps += 1;
+    postObservabilityToParent({
+        kind: 'relay-dead-tap',
+        intent,
+        latchAgeMs: Date.now() - relayLatchedAt,
+        ordinal: relayDeadTaps,
+        trigger: relayLatchTrigger,
+        ...scope,
+    });
+}
+/**
+ * Marks the toast element as the STANDING relay notice. The dead-zone
+ * cue arms on this element's absence or invisibility — however it went
+ * away (the user's click or a late `drain_ack` retiring it). `showActionToast`
+ * drops the mark whenever it renders any other message, so a fallback
+ * cue or a later pending toast never passes for the explanation.
+ */
+const RELAY_NOTICE_ATTR = 'data-ggui-relay-notice';
+/**
+ * Tag the just-shown notice and place it BEFORE the render root in
+ * document order, so a keyboard or virtual-cursor user meets the
+ * explanation before the dead controls it explains (ggui#670 Phase 3,
+ * a11y fold). Reading order only — the element's fixed-position paint
+ * is unchanged.
+ */
+function markRelayNotice() {
+    if (typeof document === 'undefined')
+        return;
+    const el = document.getElementById(ACTION_TOAST_ID);
+    if (el === null)
+        return; // no document surface to mark (pre-boot); the cue covers every attempt
+    el.setAttribute(RELAY_NOTICE_ATTR, '');
+    const root = document.querySelector('[data-ggui-session-root]');
+    if (root !== null &&
+        root.parentNode !== null &&
+        (root.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0) {
+        root.parentNode.insertBefore(el, root);
+    }
+}
+/** Whether the standing relay notice is on screen right now. */
+function isRelayNoticeVisible() {
+    if (typeof document === 'undefined')
+        return false;
+    const el = document.getElementById(ACTION_TOAST_ID);
+    return (el !== null &&
+        el.hasAttribute(RELAY_NOTICE_ATTR) &&
+        el.style.opacity !== '0' &&
+        el.getAttribute('aria-hidden') !== 'true');
+}
+/**
+ * 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 function resetRelayLatchForBoot() {
+    if (typeof document !== 'undefined') {
+        const el = document.getElementById(ACTION_TOAST_ID);
+        if (el !== null && el.hasAttribute(RELAY_NOTICE_ATTR))
+            el.remove();
+    }
+    resetRelayCueThrottles();
+    if (relayIncapabilityAnnounced) {
+        transitionRelayLatch(false);
+    }
+    else {
+        connectionStore.set(true);
+    }
+}
 /**
  * Module-level handle to the CURRENT boot's telemetry sink so
  * module-scope paths (the doorbell emitter below) can report without
@@ -2219,24 +2411,6 @@ let currentTelemetrySink = null;
  * `currentTelemetrySink`.
  */
 let mountSuperseded = false;
-/**
- * Whether the user has manually dismissed the CURRENTLY-STANDING relay
- * notice (ggui#442).
- *
- * "Dismissed the one explanation" is not "wants zero feedback forever",
- * but it IS consent that the explanation itself has been read. So the
- * dead zone this opens is filled with a per-gesture CUE, never with the
- * notice again.
- *
- * Scoped to the notice, not to toasts in general: the doorbell's
- * `action_required` toast is a different message with a different
- * dismissal meaning, so the flag is set from the relay notice's own
- * `onDismiss` callback rather than from `showActionToast` at large.
- *
- * Reset on BOTH latch edges — a re-latch shows a fresh notice nobody
- * has dismissed yet, and a self-heal must leave no residue behind.
- */
-let relayNoticeDismissed = false;
 /**
  * Timestamp of the last fallback cue toast, for the throttle below.
  * Reset alongside the latch so a new dead zone never inherits an old
@@ -2312,7 +2486,11 @@ function resetRelayCueThrottles() {
 /** @internal — exported for unit tests to reset module state. */
 export function __resetRelayNoticeForTest() {
     relayIncapabilityAnnounced = false;
-    relayNoticeDismissed = false;
+    connectionStore.set(true);
+    relayLatchedAt = undefined;
+    relayDeadTaps = 0;
+    relayLatchTrigger = undefined;
+    relayLatchScope = {};
     resetRelayCueThrottles();
 }
 /**
@@ -2372,10 +2550,8 @@ function resolveRelayCueTarget() {
  * be a lie about someone else's element. The honest counterpart is a
  * message in the announcer's own region, saying what the pulse means.
  *
- * NOT gated on `__GGUI_TOAST_DISABLED__`: that flag suppresses our
- * toast chrome, and the pulse is not toast chrome — it fires either
- * way. Announcing on the same condition as the visual keeps the two
- * cues telling the same story.
+ * Announcing on the same condition as the visual keeps the two cues
+ * telling the same story.
  *
  * Throttled on its own clock, unlike the pulse — but only against
  * IDENTICAL repeats. A flash repeating on every gesture costs a sighted
@@ -2431,8 +2607,10 @@ function retractRelayCueAnnouncement() {
 }
 /**
  * The dead-zone cue (ggui#442): the smallest honest "that did nothing"
- * signal, for a gesture on a host already known — and already
- * explained — to be relay-incapable.
+ * signal, for a gesture on a host already known to be relay-incapable
+ * while the standing explanation is NOT on screen — dismissed by the
+ * user or retired by a late `drain_ack` (ggui#670 Phase 3: the cue arms
+ * on the notice's absence, never on how it went away).
  *
  * Component-agnostic by construction. It pulses whatever the user
  * focused without knowing what that is, and falls back to the toast
@@ -2440,7 +2618,7 @@ function retractRelayCueAnnouncement() {
  * (ggui#447) — the pulse via {@link announceRelayCue}, the fallback via
  * the toast primitive's own announcement.
  */
-function showPostDismissalCue(intent) {
+function showDeadZoneCue(intent) {
     if (typeof document === 'undefined')
         return;
     const target = resolveRelayCueTarget();
@@ -2549,16 +2727,20 @@ export function dispatchSubmitAction(args) {
     // that nothing downstream ever restores — the opposite of "left
     // standing" (see the latch declaration + terminal branch below).
     //
-    // Once that explanation has been DISMISSED, though, skipping leaves
-    // the gesture with no feedback at all — the dead zone ggui#442
-    // names. The cue fills it here, at dispatch time, because the
-    // element it pulses is the one the user has focused NOW; by the time
-    // the relay response settles, focus may have moved on.
+    // While the latch stands the gesture still dispatches (attempt-always,
+    // #443 — the attempt is the self-heal sensor); its outcome is counted
+    // for the host where it lands (ggui#670 Phase 3, the terminal branch
+    // below). When the standing explanation is not on screen — dismissed,
+    // or retired by a late `drain_ack` — skipping would leave the gesture
+    // with no feedback at all: the dead zone ggui#442 names. The cue fills it
+    // here, at dispatch time, because the element it pulses is the one
+    // the user has focused NOW; by the time the relay response settles,
+    // focus may have moved on.
     if (!relayIncapabilityAnnounced) {
         showActionToast(`→ ${intent}${dataPart}`, 'pending');
     }
-    else if (relayNoticeDismissed) {
-        showPostDismissalCue(intent);
+    else if (!isRelayNoticeVisible()) {
+        showDeadZoneCue(intent);
     }
     // (2) Try submit_action via host relay. Spec-compliant hosts
     // forward the tools/call to the MCP server's submit_action handler;
@@ -2622,16 +2804,11 @@ export function dispatchSubmitAction(args) {
         if (relayIncapabilityAnnounced &&
             resp !== null &&
             !isRelayShapedFailure(resp)) {
-            relayIncapabilityAnnounced = false;
             // Self-heal leaves NO cue residue (ggui#442): the dead zone is
             // gone, so the state that armed the cue goes with it. A later
             // re-latch starts from a clean slate.
-            relayNoticeDismissed = false;
             resetRelayCueThrottles();
-            postObservabilityToParent({
-                kind: 'relay-incapability',
-                state: 'cleared',
-            });
+            transitionRelayLatch(false);
             // The (1.5) pending toast above was SKIPPED for this gesture —
             // the latch was still standing at dispatch time — so a bare
             // clear leaves the now-false "cannot relay" notice standing with
@@ -2708,19 +2885,26 @@ export function dispatchSubmitAction(args) {
         //     standing latch at the response-arrival guard above, and
         //     keeps routing to the ordinary per-gesture transient toast
         //     below instead.
+        // Two evidence classes latch (ggui#599 cycle-2): the original
+        // advert-silent leg (nothing advertised AND the attempt failed
+        // relay-shaped), and the CONFIRMED-REFUSAL leg — a declared
+        // helper-minted refusal code, which outranks any positive
+        // advertisement (the advertises-but-refuses host previously got a
+        // fresh transient toast per tap, forever). Timeouts and unknown
+        // codes never reach the second leg; the un-classify edge for BOTH
+        // is the same response-arrival clear guard above (attempt-always
+        // preserved — nothing here suppresses dispatch, per the #443
+        // doctrine: the attempt is the self-heal sensor).
+        const confirmedRefusal = isConfirmedRelayRefusal(resp);
         if (hostCapabilitiesCaptured() &&
-            !hostCanRelayToolCalls() &&
-            isRelayShapedFailure(resp)) {
+            ((!hostCanRelayToolCalls() && isRelayShapedFailure(resp)) ||
+                confirmedRefusal)) {
             if (!relayIncapabilityAnnounced) {
-                relayIncapabilityAnnounced = true;
                 // Transition edge — the paired 'cleared' edge lives at the
                 // response-arrival guard above. NEVER emit off-edge (e.g. per
                 // channel poll tick): the router ticks on an interval and
                 // would spam; the two edges carry the full information.
-                postObservabilityToParent({
-                    kind: 'relay-incapability',
-                    state: 'latched',
-                });
+                transitionRelayLatch(true, confirmedRefusal ? 'confirmed-refusal' : 'advert-silent', { sessionId, appId });
                 // Establish the flag's invariant where the notice it describes
                 // is created: a freshly-shown notice is undismissed, and its
                 // dead zone starts with an unspent throttle. Today every
@@ -2728,11 +2912,17 @@ export function dispatchSubmitAction(args) {
                 // resets both), so this is the same value arriving by a second
                 // route — kept because the state belongs to THIS notice, and a
                 // future second latch-set path shouldn't have to know that.
-                relayNoticeDismissed = false;
                 resetRelayCueThrottles();
-                showActionToast('This host cannot relay actions to the agent — interactive controls will not work here.', 'action_required', () => {
-                    relayNoticeDismissed = true;
-                });
+                showActionToast('This host cannot relay actions to the agent — interactive controls will not work here.', 'action_required');
+                markRelayNotice();
+            }
+            else {
+                // A gesture attempted inside a standing dead zone came back
+                // undelivered — a dead tap, counted for the host (ggui#670
+                // Phase 3). The latching gesture above is the 'latched' edge,
+                // and a gesture that heals the zone is the 'cleared' edge —
+                // neither is a dead tap.
+                emitRelayDeadTap(intent, { sessionId, appId });
             }
             return;
         }

package/dist/wire-config.js

@@ -1,9 +1,12 @@
 import { buildWireConfig, StreamBus, } from '@ggui-ai/wire';
 import { validateOutboundActionEnvelope } from './validation.js';
 import { defaultProtocolErrorEmitter, fromClientContractViolation, } from './protocol-error.js';
-// `StreamBus` (and its bounded reserved-channel replay ring) was
-// hoisted into `@ggui-ai/wire` so `<GguiRender>` and this runtime share
-// one implementation. Re-exported for the runtime's internal modules.
+// `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
+// component and its WS action path are DELETED (react host-helper
+// ruling; ggui#599 cycle-2 caught the stale reference here) — and the
+// hoist stands on its own merits. Re-exported for internal modules.
 export { StreamBus };
 /**
  * Build the per-render `WireConfig` for the iframe runtime.
@@ -44,6 +47,9 @@ export function buildRootWireConfig(opts) {
     }
     return buildWireConfig({
         app: { appId: opts.appId, appName: opts.appId },
+        // `isConnected` here is the static config field; `useRender()`
+        // reads the LIVE value from wire's document connection store,
+        // which the runtime writes at the relay latch's edges (ggui#670).
         render: { sessionId: opts.sessionId, isConnected: true },
         auth: { isAuthenticated: false },
         // Resolve the active render's actionSpec on every dispatch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/iframe-runtime",
-  "version": "0.13.0",
+  "version": "0.14.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",
@@ -28,6 +28,11 @@
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js",
       "default": "./dist/server.js"
+    },
+    "./observability": {
+      "types": "./dist/observability.d.ts",
+      "import": "./dist/observability.js",
+      "default": "./dist/observability.js"
     }
   },
   "dependencies": {
@@ -36,12 +41,12 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.13.0",
-    "@ggui-ai/preview-a2ui": "0.13.0",
-    "@ggui-ai/gadgets": "0.13.0",
-    "@ggui-ai/protocol": "0.13.0",
-    "@ggui-ai/wire": "0.13.0",
-    "@ggui-ai/live-channel": "0.13.0"
+    "@ggui-ai/gadgets": "0.14.0",
+    "@ggui-ai/preview-a2ui": "0.14.0",
+    "@ggui-ai/live-channel": "0.14.0",
+    "@ggui-ai/protocol": "0.14.0",
+    "@ggui-ai/design": "0.14.0",
+    "@ggui-ai/wire": "0.14.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0"
@@ -52,7 +57,7 @@
     "@types/node": "^24.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "esbuild": "^0.25.12",
+    "esbuild": "^0.28.2",
     "jsdom": "^24.0.0",
     "tsx": "^4.21.0",
     "typescript": "^5.0.0",
@@ -71,11 +76,11 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "author": "ggui contributors <hello@ggui.ai>",
   "scripts": {
-    "build": "rm -rf dist.staging && tsc -p tsconfig.types.json --outDir dist.staging && GGUI_ESBUILD_OUT_DIR=dist.staging node esbuild.config.mjs && node ../scripts/atomic-swap.mjs dist.staging dist && pnpm run check:bundle-size",
+    "build": "rm -rf dist.staging-$$ && tsc -p tsconfig.types.json --outDir dist.staging-$$ && GGUI_ESBUILD_OUT_DIR=dist.staging-$$ node esbuild.config.mjs && node ../scripts/atomic-swap.mjs dist.staging-$$ dist && pnpm run check:bundle-size",
     "check:bundle-size": "tsx scripts/check-bundle-size.ts",
     "check:bundle-size:self-test": "tsx scripts/check-bundle-size.ts --self-test",
     "typecheck": "tsc --noEmit",