@ggui-ai/iframe-runtime 0.13.0 → 0.15.0

package/dist/runtime.js

@@ -27,10 +27,11 @@
 // 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';
-import { projectHostContext } from '@ggui-ai/protocol';
+import { projectHostContext } from '@ggui-ai/protocol/wire';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
 import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, } from './host-context-emitter.js';
 import { mapHostPaletteToGguiVars } from './host-palette-bridge.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)
@@ -412,11 +421,35 @@ export async function bootSequence(opts) {
     // covers every boot path; arrivals before a renderer publishes
     // `applyRender` no-op inside the listener.
     installPersistentToolResultListener(app);
+    // 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.
+    // It runs BEFORE the handshake so that every boot passes the close
+    // edge before it can latch — the boot-failed write below is then
+    // always on-edge (ggui#830 fold): a prior zone ends with its
+    // 'cleared' edge and its summary, never buried under a second
+    // 'latched' with its tally erased.
+    resetRelayLatchForBoot();
     const initResult = await connectApp(app, transport);
     if (!initResult.ok) {
         setStatus(refs, `ui/initialize failed: ${initResult.message}`, 'error');
         retireShellLoadingIndicator(doc);
         emitBootFailure('UI_INITIALIZE_FAILED', initResult.message);
+        // The maximal dead zone (ggui#830): the host refused the handshake
+        // every session begins with, so nothing can be delivered here — the
+        // relay latch sets through its one writer (store false, 'latched'
+        // edge, standing notice) instead of leaving this document with
+        // `isConnected === true`, no explanation and no count. No gesture
+        // is needed for that knowledge, and no gesture is suppressed by it:
+        // every later tap still attempts (attempt-always) and lands as a
+        // counted dead tap. The scope is empty because no bootstrap has
+        // named a session yet; it clears the only way a handshake failure
+        // can — the next boot's close edge, which this boot itself already
+        // passed above, so this write is on-edge by construction. The
+        // gesture gate's pre-capture rule ("never latch before the host has
+        // been asked") does not apply here: the host HAS been asked — this
+        // is its answer to `ui/initialize`, resolved as failure.
+        announceRelayIncapability('boot-failed', {});
         return { ok: false, mountedRender };
     }
     // Record what this host said it can do (ggui#440). Earliest valid
@@ -1606,13 +1639,69 @@ 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 never CONFIRM (they can latch only through
+ * the advert-silent leg, never on an advertising host); off-latch they
+ * stay on the per-gesture transient path, and inside a standing zone
+ * they count as dead taps like every other undelivered outcome
+ * (ggui#826).
+ */
+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
@@ -1710,6 +1799,20 @@ function classifySubmitActionResponse(resp) {
  * carries a result envelope, so neither is evidence the relay worked.
  */
 function isRelayShapedFailure(resp) {
+    // "Relay-shaped" IS "undelivered" on this leg, by construction — not
+    // by hope (ggui#832, ruled from the hosts' source): every JSON-RPC
+    // error the iframe sees here is host- or transport-minted. The MCP
+    // SDK server turns a tool handler's throw into an `isError` RESULT and
+    // mints JSON-RPC codes only for its own gate; the guuey view-host
+    // answers a rejecting relay with an in-band unavailable RESULT, never
+    // an error; ggui's embed host proxies over HTTP and mints its OWN
+    // codes for a failed proxy. So a server-side outcome always arrives
+    // as a `CallToolResult` (`ok:true` and `ok:false` alike clear the
+    // latch), and an error envelope always means the call did not round
+    // trip. A third-party host that forwarded a server's JSON-RPC error
+    // verbatim would be indistinguishable by code — that is the
+    // host-helper conformance catalog's business (H3 / R1), not this
+    // predicate's.
     // Null-tolerant on `error`, matching `classifySubmitActionResponse`'s
     // own check: an `{error:null, result:{...}}` envelope classifies as
     // success there, so it must also read as NOT relay-shaped-failure
@@ -1930,13 +2033,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 +2074,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 +2307,147 @@ 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 = {};
+}
+/**
+ * Set the latch AND present it — the three steps every latch-set path
+ * takes, in one place: the transition through the ONE writer (store
+ * flip + `'latched'` edge), a fresh dead zone (unspent cue throttles —
+ * the state belongs to THIS notice, so a second latch-set path never
+ * has to know the clear edge already reset it), and the standing
+ * explanation, marked so the per-gesture cue arms on its dismissal.
+ * Callers: the dispatch outcome gate (a gesture's confirmed relay
+ * failure) and the boot sequence (a refused `ui/initialize`, ggui#830).
+ */
+function announceRelayIncapability(trigger, scope) {
+    transitionRelayLatch(true, trigger, scope);
+    resetRelayCueThrottles();
+    showActionToast('This host cannot relay actions to the agent — interactive controls will not work here.', 'action_required');
+    markRelayNotice();
+}
+/**
+ * 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 +2465,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 +2540,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 +2604,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 +2661,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 +2672,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 +2781,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 +2858,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,32 +2939,52 @@ 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 — they never CONFIRM (the
+        // advert-silent leg alone can latch on them); inside a standing
+        // zone they are counted like every other undelivered outcome by
+        // the branch below (ggui#826). The un-classify edge for
+        // BOTH legs 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 (relayIncapabilityAnnounced && isRelayShapedFailure(resp)) {
+            // A gesture whose undelivered outcome landed inside a standing
+            // dead zone — a dead tap, counted for the host (ggui#670 Phase 3);
+            // an in-flight gesture that raced the latching one counts too.
+            // Counted on the OUTCOME and keyed on the LATCH, never on
+            // advertisement (ggui#826): the advertises-but-refuses host
+            // latches by a confirmed refusal, and its later code-less or
+            // timeout failures are exactly the undelivered gestures the
+            // RelayDeadTapEvent contract promises to count. The eligibility
+            // predicate below is the LATCH-SET rule — a timeout or unknown
+            // code never CONFIRMS; it can latch only through the advert-silent
+            // leg, never on an advertising host — and is the wrong key for
+            // counting. Every outcome that
+            // reaches here while the latch stands is relay-shaped by
+            // construction (the response-arrival guard above cleared on any
+            // well-formed result); the conjunct states the contract instead
+            // of trusting that. The latching gesture 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;
+        }
         if (hostCapabilitiesCaptured() &&
-            !hostCanRelayToolCalls() &&
-            isRelayShapedFailure(resp)) {
-            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',
-                });
-                // 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
-                // re-latch already passes through the clear edge above (which
-                // 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;
-                });
-            }
+            ((!hostCanRelayToolCalls() && isRelayShapedFailure(resp)) ||
+                confirmedRefusal)) {
+            // 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. A
+            // standing latch never reaches here: its undelivered outcomes
+            // were counted above, and a delivered one cleared it.
+            announceRelayIncapability(confirmedRefusal ? 'confirmed-refusal' : 'advert-silent', { sessionId, appId });
             return;
         }
         showActionToast(`⚠ ${intent} — could not reach the agent`, 'error');
@@ -2742,19 +2993,22 @@ export function dispatchSubmitAction(args) {
 /**
  * Channel-transport router's `tools/call` invoker (ggui#440) —
  * iframe-polling transport, `tools/call` against the parent MCP host
- * via `app.callServerTool` (spec-canonical) when the App handle is
- * set; falls back to raw postMessage pre-handshake or in tests.
+ * via `app.callServerTool` (spec-canonical); with no App bound the
+ * call answers a code-less error envelope — never a raw postMessage.
  * Direct call (no LLM consent loop). Returns the tool's
  * structuredContent (or `content[0]` if that's where the payload
  * landed) as a `JsonValue`. On RPC error we throw — the router
  * catches and silently retries on the next tick.
  *
- * Once a REAL gesture has confirmed this host can't relay (the latch
- * above — set only after {@link dispatchSubmitAction} actually tried
- * and failed on a host with no `serverTools` advertised, with
- * capabilities already captured, AND the failure was relay-shaped —
- * not a well-formed `{ok:false}` result; see `isRelayShapedFailure`),
- * every subsequent poll will fail identically.
+ * Once this document has confirmed it cannot relay (the latch above —
+ * set through the ONE writer on exactly three paths: a REAL gesture
+ * that failed relay-shaped on a host that never advertised
+ * `serverTools`, with capabilities already captured (`advert-silent`);
+ * a declared refusal code answered under a positive advertisement
+ * (`confirmed-refusal`); or the host's own failure of the mandatory
+ * `ui/initialize` handshake, before any gesture (`boot-failed`,
+ * ggui#830) — never a well-formed `{ok:false}` result; see
+ * `isRelayShapedFailure`), every subsequent poll will fail identically.
  *
  * This guard does NOT stop the router's poll loop, and nothing here
  * should ever be written so that it could (ggui#443). It does two
@@ -2780,10 +3034,13 @@ export function dispatchSubmitAction(args) {
  * (ggui's own embed host pre-Task-2 is exactly this case) — silently
  * killing working channel polls forever. That is "absence of a
  * capability blocks an attempt", which the fail-safe constraint
- * forbids. The latch implies `!hostCanRelayToolCalls()` (it only
- * ever sets inside that guard), so testing it alone is sufficient —
- * a host that never fails a real gesture never latches, and its
- * channels keep working.
+ * forbids. The latch is set only by a CONFIRMED OUTCOME — a failed
+ * real gesture (the advert-silent leg, or a confirmed refusal under a
+ * positive advertisement, ggui#599 cycle-2) or a failed handshake
+ * (ggui#830), never by an advertisement's absence — so testing the
+ * latch alone is sufficient: a host that answers its handshake and
+ * never fails a real gesture never latches, and its channels keep
+ * working.
  *
  * Extracted to a named export (rather than an inline closure inside
  * `bootProduction`) so unit tests can drive it directly through the

package/dist/types.d.ts

@@ -15,7 +15,7 @@
  * declared the manager's constructor bag has been retired.
  */
 import type { McpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
-import type { HostContextProjection, ComponentGguiSession, SystemGguiSession } from '@ggui-ai/protocol';
+import type { HostContextProjection, ComponentGguiSession, SystemGguiSession } from '@ggui-ai/protocol/wire';
 /**
  * The four server-assigned ledger fields on every wire-delivered
  * {@link GguiSession}. They're stamped by the server's per-render event

package/dist/validation.d.ts

@@ -26,7 +26,7 @@
  * host wrapper explicitly does NOT run this path — its only contract is
  * the postMessage bridge to the renderer iframe.
  */
-import type { ActionSpec, ActionEnvelope, ContextSpec, JsonObject, PropsSpec, ReservedChannelValidator, StreamSpec, ValidationResult } from '@ggui-ai/protocol';
+import type { ActionSpec, ActionEnvelope, ContextSpec, JsonObject, PropsSpec, ReservedChannelValidator, StreamSpec, ValidationResult } from '@ggui-ai/protocol/wire';
 import type { CompiledValidatorSet } from './compiled-validators.js';
 /**
  * Install the precompiled validators loaded from the bootstrap. Called

package/dist/validation.js

@@ -1,4 +1,4 @@
-import { isKnownReservedChannel, validateActionEnvelope, validateContextData, validatePropsData, validateStreamData, } from '@ggui-ai/protocol';
+import { isKnownReservedChannel, validateActionEnvelope, validateContextData, validatePropsData, validateStreamData, } from '@ggui-ai/protocol/wire';
 // =============================================================================
 // Active precompiled-validator set
 // =============================================================================

package/dist/wire-config.d.ts

@@ -16,7 +16,7 @@
  * ProtocolError dual-emission policy, and the tools/call-vs-WS
  * dispatch transport.
  */
-import type { ActionEnvelope, GguiSession } from '@ggui-ai/protocol';
+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 type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';

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.