@ggui-ai/iframe-runtime 0.6.2 → 0.7.0

package/dist/runtime.js

@@ -5,8 +5,9 @@ import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
 import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, } from './host-context-emitter.js';
 import { buildRootWireConfig, StreamBus, } from './wire-config.js';
 import { createChannelTransportRouter, } from './channel-transport.js';
+import { RelayIncapableError } from './relay-incapability.js';
 import { ChannelRegistry } from '@ggui-ai/live-channel';
-import { createChannelErrorHandler, createChannelPayloadHandler, createDataHandler, createDrainAckHandler, createPropsUpdateHandler, createRenderHandler, createSystemHandler, } from './channels/index.js';
+import { createChannelErrorHandler, createChannelPayloadHandler, createDataHandler, createDrainAckHandler, createPropsUpdateHandler, createRenderHandler, } from './channels/index.js';
 import { connectViaRegistry, } from './registry-subscribe.js';
 import { buildEventsPolling } from './events-polling.js';
 import { ensureStatusDom, setStatus, setConnectedStatus, } from './status-dom.js';
@@ -16,6 +17,7 @@ import { mountRender, } from './render-item.js';
 import { fromBootstrapFailure, } from './protocol-error.js';
 import { postObservabilityToParent, } from './observability.js';
 import { mountUiFeedbackChrome } from './ui-feedback-chrome.js';
+import { hostCanReceiveMessages, hostCanRelayToolCalls, hostCapabilitiesCaptured, setHostCapabilities, } from './host-capabilities.js';
 import { makeLifecycleEvent, postLifecycleToParent, } from './lifecycle.js';
 import { contextSlotLastValues, createContextStateHost, installContextRegistry, reemitLastContextValues, } from './context-observer.js';
 const RENDERER_VERSION = typeof __GGUI_RUNTIME_VERSION__ === 'string' ? __GGUI_RUNTIME_VERSION__ : 'dev';
@@ -214,6 +216,14 @@ export async function bootSequence(opts) {
         onLifecycle?.(makeLifecycleEvent('error', { error: { code: reason, message } }));
     };
     const refs = ensureStatusDom(doc);
+    // Live regions up BEFORE anything can announce through them
+    // (ggui#447). A region created in the same tick as its first message
+    // is a region no screen reader was watching yet, and that first
+    // message — the one telling the user their very first gesture was
+    // received — is the one that gets lost. Mounted here, alongside the
+    // render root, because every toast is at minimum a user gesture away
+    // from this point.
+    ensureToastAnnouncer(doc);
     // The mounted render is established after the first ack lands —
     // populated by `applyAck` below + read back by every channel handler
     // that needs `propsSpec` / `streamSpec`. Tracked as a closure-scoped
@@ -253,6 +263,11 @@ export async function bootSequence(opts) {
         emitBootFailure('UI_INITIALIZE_FAILED', initResult.message);
         return { ok: false, mountedRender };
     }
+    // Record what this host said it can do (ggui#440). Earliest valid
+    // read: `getHostCapabilities()` is undefined until `connect()`
+    // resolves. Used to EXPLAIN failures (gesture relay, doorbell), never
+    // to pre-empt an attempt — see `./host-capabilities.ts`.
+    setHostCapabilities(app.getHostCapabilities());
     // Connected — expose the App on the module-level slot so outbound
     // `tools/call` (dispatchSubmitAction, channel-transport router)
     // routes through `app.callServerTool` instead of the legacy raw
@@ -683,15 +698,13 @@ function createPlaceholderRegistry(params) {
  * Frame dispatch lives inside `@ggui-ai/live-channel`'s
  * `ChannelRegistry`. Every WS frame type (`render`, `data`,
  * `props_update`, `drain_ack`, `channel_payload`,
- * `channel_error`, `system`) has a registered handler in
- * `channels/*.ts`; the registry's bound transport routes inbound
- * frames directly to them. Observability emission (`auth-required`)
- * is inside the system handler.
+ * `channel_error`) has a registered handler in `channels/*.ts`; the
+ * registry's bound transport routes inbound frames directly to them.
  *
  * The pre-B3b helpers (`handleServerMessage`, `handleRendererMessage`,
- * `handleObservableMessage`, `emitAuthRequiredFromSystemFrame`,
- * `BufferedManagerShim`) lived here and have been retired — see
- * commit message + plan B3b for the full retirement notes.
+ * `handleObservableMessage`, `BufferedManagerShim`) lived here and
+ * have been retired — see commit message + plan B3b for the full
+ * retirement notes.
  */
 /**
  * Type guard for the `UpgradeRequiredError` class without importing
@@ -1253,6 +1266,32 @@ function classifySubmitActionResponse(resp) {
         : r;
     return inner.ok === true ? 'success' : 'fallback';
 }
+/**
+ * Did the relay itself fail — as opposed to relaying successfully to a
+ * well-formed `{ok:false}` result (ggui#440)? `classifySubmitActionResponse`
+ * collapses BOTH into `'fallback'`, which is the right call for the
+ * generic "enqueue failed" toast (either way the gesture isn't on the
+ * pipe) but the WRONG call for the relay-incapability latch: a result
+ * envelope arriving at all — `{ok:false, code:'PIPE_NOT_FOUND'}` is the
+ * common case (an otherwise-healthy relay, expired pipe) — is proof the
+ * host DID relay the call to the server and back. Latching "cannot
+ * relay" on that evidence would be false: a host that plainly can relay
+ * would get permanently mislabeled from one stale-pipe response.
+ *
+ * `resp === null` covers the transport-throw / no-App-bound paths (the
+ * outer `catch` above resets `resp` to `null`); `resp.error !== undefined
+ * && resp.error !== null` covers the JSON-RPC error envelope. Neither
+ * carries a result envelope, so neither is evidence the relay worked.
+ */
+function isRelayShapedFailure(resp) {
+    // 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
+    // here — otherwise the two predicates disagree on that shape and the
+    // response-arrival clear guard above would refuse to release a
+    // standing latch on an unambiguous success.
+    return resp === null || (resp.error !== undefined && resp.error !== null);
+}
 /**
  * Extract `consumerPresent` from a successful submit_action response.
  * Returns the boolean if present + well-typed; `undefined` otherwise
@@ -1275,7 +1314,147 @@ function extractConsumerPresent(resp) {
     const flag = inner.consumerPresent;
     return typeof flag === 'boolean' ? flag : undefined;
 }
-function showActionToast(text, kind) {
+/** Container id for the announcer holding both live regions. */
+const TOAST_ANNOUNCER_ID = '__ggui-toast-announcer__';
+/**
+ * Ensure the pair of live regions the toast surface announces through.
+ *
+ * MUST be called before the first message can land — a live region
+ * created in the same tick as its first content is a region the screen
+ * reader was never watching, and that first announcement is lost. The
+ * boot path calls this at the same point it mounts the render root, so
+ * every toast (at minimum a user gesture away) lands in a region that
+ * has been registered for many frames. The toast + cue paths call it
+ * again defensively; it is idempotent per document.
+ *
+ * Visually hidden rather than `display:none`: a region that is not
+ * rendered is not in the accessibility tree, and content added to it is
+ * never announced. The clip rectangle keeps it out of the visual layout
+ * while leaving it live.
+ *
+ * Returns `null` when the document has no body yet — nothing to attach
+ * to, and no announcement is possible.
+ *
+ * @internal — exported for unit tests.
+ */
+export function ensureToastAnnouncer(doc) {
+    if (doc.body === null)
+        return null;
+    const existing = doc.getElementById(TOAST_ANNOUNCER_ID);
+    if (existing !== null) {
+        const polite = existing.querySelector('[data-ggui-toast-announce="polite"]');
+        const assertive = existing.querySelector('[data-ggui-toast-announce="assertive"]');
+        if (polite !== null && assertive !== null)
+            return { polite, assertive };
+        // Half a container is worse than none — it looks mounted to the
+        // idempotence check while announcing nothing. Rebuild whole.
+        existing.remove();
+    }
+    const host = doc.createElement('div');
+    host.id = TOAST_ANNOUNCER_ID;
+    host.style.cssText = [
+        'position:absolute',
+        'width:1px',
+        'height:1px',
+        'margin:-1px',
+        'padding:0',
+        'border:0',
+        'overflow:hidden',
+        'clip:rect(0 0 0 0)',
+        'clip-path:inset(50%)',
+        'white-space:nowrap',
+    ].join(';');
+    const makeRegion = (politeness) => {
+        const region = doc.createElement('div');
+        region.setAttribute('data-ggui-toast-announce', politeness);
+        // Role and `aria-live` together: the role is the semantic, the
+        // explicit `aria-live` is the belt for assistive technology that
+        // does not map `role="status"` to a politeness on its own.
+        region.setAttribute('role', politeness === 'polite' ? 'status' : 'alert');
+        region.setAttribute('aria-live', politeness);
+        // Toast text is one sentence that only makes sense whole — read the
+        // region, not the diff.
+        region.setAttribute('aria-atomic', 'true');
+        host.appendChild(region);
+        return region;
+    };
+    const polite = makeRegion('polite');
+    const assertive = makeRegion('assertive');
+    doc.body.appendChild(host);
+    return { polite, assertive };
+}
+/**
+ * Speak a toast message. `error` + `action_required` interrupt (a
+ * gesture failed, or needs the user to act); everything else queues.
+ *
+ * Exactly one region carries text at a time — the other is cleared, so
+ * a user who navigates to the announcer afterwards finds the current
+ * message and not a transcript. Clearing is silent: assistive
+ * technology announces content arriving in a live region, not content
+ * leaving one.
+ */
+function announceToast(text, kind) {
+    if (typeof document === 'undefined')
+        return;
+    const regions = ensureToastAnnouncer(document);
+    if (regions === null)
+        return;
+    // Whatever speaks last owns the region. A retraction scheduled for an
+    // earlier relay cue would otherwise come due in the middle of THIS
+    // message and take it down instead — and it could not be filtered out
+    // by comparing text, because a cue and the fallback cue toast for the
+    // same intent are character-identical. (Declared below; this only
+    // ever runs long after module init.)
+    cancelRelayCueRetraction();
+    const interrupts = kind === 'error' || kind === 'action_required';
+    const target = interrupts ? regions.assertive : regions.polite;
+    const idle = interrupts ? regions.polite : regions.assertive;
+    idle.textContent = '';
+    target.textContent = text;
+}
+/**
+ * Empty both live regions. Paired with every route that takes the
+ * visible toast away, so the spoken surface and the visual one carry
+ * the same message at the same time — including "nothing".
+ */
+function clearToastAnnouncement() {
+    if (typeof document === 'undefined')
+        return;
+    const host = document.getElementById(TOAST_ANNOUNCER_ID);
+    if (host === null)
+        return;
+    for (const region of Array.from(host.children)) {
+        region.textContent = '';
+    }
+}
+/**
+ * Take the visible toast away, on every route that does so (auto-
+ * dismiss timer, user dismissal, `drain_ack` resolution).
+ *
+ * A hidden toast must be inert to pointer, keyboard AND assistive
+ * technology alike: the element keeps its fixed position over the top
+ * of the render for the rest of the session, so anything left behind —
+ * a live click target, a tab stop, an announced sentence — outlives the
+ * message it belonged to.
+ */
+function hideToast(el) {
+    el.style.opacity = '0';
+    el.style.transform = 'translateX(-50%) translateY(8px)';
+    el.style.pointerEvents = 'none';
+    el.onclick = null;
+    el.onkeydown = null;
+    // Blur BEFORE `aria-hidden` lands: hiding the focused element from
+    // the accessibility tree strands the screen reader's cursor on a node
+    // it can no longer describe.
+    if (el.ownerDocument.activeElement === el)
+        el.blur();
+    el.removeAttribute('role');
+    el.removeAttribute('tabindex');
+    el.removeAttribute('aria-label');
+    el.setAttribute('aria-hidden', 'true');
+    clearToastAnnouncement();
+}
+function showActionToast(text, kind, onDismiss) {
     if (typeof document === 'undefined')
         return;
     const w = window;
@@ -1319,34 +1498,62 @@ function showActionToast(text, kind) {
     el.textContent = text;
     el.style.opacity = '1';
     el.style.transform = 'translateX(-50%) translateY(0)';
+    // Reset to the non-interactive posture every time, so a toast that
+    // follows an `action_required` notice does not inherit its tab stop
+    // and name. The `action_required` branch below re-applies them.
+    el.setAttribute('aria-hidden', 'true');
+    el.removeAttribute('role');
+    el.removeAttribute('tabindex');
+    el.removeAttribute('aria-label');
+    el.style.pointerEvents = 'none';
+    el.onkeydown = null;
+    announceToast(text, kind);
     // Clear any prior auto-dismiss timer so a fresh pending toast
     // doesn't get hidden mid-flight.
     const elWithTimer = el;
     if (elWithTimer.__toastTimer)
         clearTimeout(elWithTimer.__toastTimer);
-    // `action_required` PERSISTS until the user clicks the toast
-    // (manual dismiss). Per MCP Apps spec, `ui/message` is a
+    // `action_required` PERSISTS until the user dismisses the toast
+    // (click, Enter or Space). Per MCP Apps spec, `ui/message` is a
     // PREPARED user prompt — the host renders it into the chat input
     // but the user must press send for it to reach the agent. So the
     // toast can't auto-dismiss; doing so would imply the gesture went
     // through when it actually requires a user follow-up.
+    //
+    // `onDismiss` fires on that click — the only signal a caller gets
+    // that the user has read and closed a persistent notice. The relay
+    // notice uses it to arm the post-dismissal cue (ggui#442).
     if (kind === 'action_required') {
-        el.onclick = () => {
-            if (!el)
+        // The dismissal is a real control, so it carries real control
+        // semantics: a role, an accessible name that says what activating
+        // it does, a tab stop, and the two keys a button responds to. The
+        // announcement already carried the message; this carries the way
+        // out of it.
+        const target = el;
+        target.removeAttribute('aria-hidden');
+        target.setAttribute('role', 'button');
+        target.setAttribute('tabindex', '0');
+        target.setAttribute('aria-label', `${text} Activate to dismiss.`);
+        target.style.pointerEvents = 'auto';
+        const dismiss = () => {
+            hideToast(target);
+            onDismiss?.();
+        };
+        target.onclick = dismiss;
+        target.onkeydown = (ev) => {
+            if (ev.key !== 'Enter' && ev.key !== ' ')
                 return;
-            el.style.opacity = '0';
-            el.style.transform = 'translateX(-50%) translateY(8px)';
-            el.onclick = null;
+            // Space scrolls the page by default; a button must not.
+            ev.preventDefault();
+            dismiss();
         };
     }
     else {
         el.onclick = null;
         if (kind === 'success' || kind === 'fallback' || kind === 'error') {
+            const target = el;
             elWithTimer.__toastTimer = window.setTimeout(() => {
-                if (!el)
-                    return;
-                el.style.opacity = '0';
-                el.style.transform = 'translateX(-50%) translateY(8px)';
+                hideToast(target);
             }, 2500);
         }
     }
@@ -1362,8 +1569,7 @@ function dismissActionToast() {
     const el = document.getElementById('__ggui-action-toast__');
     if (!el)
         return;
-    el.style.opacity = '0';
-    el.style.transform = 'translateX(-50%) translateY(8px)';
+    hideToast(el);
     const elWithTimer = el;
     if (elWithTimer.__toastTimer) {
         clearTimeout(elWithTimer.__toastTimer);
@@ -1506,6 +1712,284 @@ function emitUserActionDoorbell(args) {
         },
     });
 }
+/**
+ * Latch for the relay-incapability notice (ggui#440). A host that
+ * cannot relay fails EVERY gesture, so the explanation is stated once
+ * and left standing; without the latch the user gets one identical
+ * toast per click, which is the #426 failure mode this closes.
+ *
+ * Cleared by ANY well-formed result envelope — `{ok:true}` and
+ * `{ok:false}` alike, either proves the host can relay (see the
+ * response-arrival guard in {@link dispatchSubmitAction}). Both
+ * transition edges emit a `relay-incapability` observability event;
+ * nothing else about the latch is observable to the host.
+ */
+let relayIncapabilityAnnounced = 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
+ * one's quiet period.
+ */
+let lastRelayCueToastAt = 0;
+/**
+ * Timestamp of the last SPOKEN cue (ggui#447), on its own clock.
+ *
+ * Separate from the toast clock because the two cue shapes are
+ * mutually exclusive per gesture — a gesture either pulses a focused
+ * control or falls back to the toast — and each needs its own quiet
+ * period to be the one it advertises.
+ */
+let lastRelayCueAnnouncedAt = 0;
+/**
+ * Intent named by the standing spoken cue, or `null` when none is.
+ *
+ * The throttle is keyed on this as well as the clock. A quiet period
+ * that ignores WHICH action was attempted does not merely withhold the
+ * second cue — it leaves the region still naming the FIRST one, so a
+ * screen reader asked to re-read it reports the wrong action as the
+ * thing that just failed. Silence is a defensible answer to a repeat;
+ * it is never a defensible answer to a different gesture.
+ */
+let lastRelayCueAnnouncedIntent = null;
+/**
+ * Expiry timer for the standing spoken cue, held so a repeat can cancel
+ * its predecessor instead of racing it.
+ */
+let relayCueAnnounceTimer;
+/** Class carrying the pulse animation; also the `@keyframes` name. */
+const RELAY_CUE_CLASS = 'ggui-relay-cue-pulse';
+/** Stable id for the injected `<style>` — idempotent per document. */
+const RELAY_CUE_STYLE_ID = 'ggui-relay-cue-style';
+/** Pulse duration (ms). Brief enough to read as acknowledgement. */
+const RELAY_CUE_DURATION_MS = 400;
+/** At most one fallback cue toast, and one spoken cue, per window (ms). */
+const RELAY_CUE_THROTTLE_MS = 5_000;
+/**
+ * How long a spoken cue stands before it is retracted (ms).
+ *
+ * Matches the toast's own auto-dismiss cadence, and deliberately
+ * outlasts the 400ms pulse by a wide margin: content pulled out of a
+ * live region too soon after it lands can be dropped before the screen
+ * reader gets to it, so retracting at pulse-end would trade a stale
+ * announcement for a missing one.
+ */
+const RELAY_CUE_ANNOUNCE_TTL_MS = 2_500;
+/**
+ * Drop the retraction a standing spoken cue has pending, because
+ * something newer is about to own the region — another cue, a toast, or
+ * a latch edge that ends the dead zone entirely. Left armed, it comes
+ * due mid-message and clears whatever is in the region then.
+ */
+function cancelRelayCueRetraction() {
+    if (relayCueAnnounceTimer === undefined)
+        return;
+    clearTimeout(relayCueAnnounceTimer);
+    relayCueAnnounceTimer = undefined;
+}
+/**
+ * Give the dead zone a fresh quiet period. Called on both latch edges
+ * and from the test reset — every throttle belongs to the notice that
+ * is standing NOW, so a new one never inherits an old one's silence.
+ */
+function resetRelayCueThrottles() {
+    lastRelayCueToastAt = 0;
+    lastRelayCueAnnouncedAt = 0;
+    lastRelayCueAnnouncedIntent = null;
+    cancelRelayCueRetraction();
+}
+/** @internal — exported for unit tests to reset module state. */
+export function __resetRelayNoticeForTest() {
+    relayIncapabilityAnnounced = false;
+    relayNoticeDismissed = false;
+    resetRelayCueThrottles();
+}
+/**
+ * Inject the pulse keyframes once per document. Mirrors how
+ * `react-renderer.ts` injects its theme CSS — `<style>` with a stable
+ * id on `<head>`, idempotent on repeat calls.
+ *
+ * Lazy rather than at boot: a session that never enters the dead zone
+ * never pays for the rule.
+ */
+function ensureRelayCueStyle() {
+    if (document.getElementById(RELAY_CUE_STYLE_ID) !== null)
+        return;
+    const style = document.createElement('style');
+    style.id = RELAY_CUE_STYLE_ID;
+    // Opacity only. Anything touching geometry (scale, translate, outline
+    // width) would have to make assumptions about the generated markup it
+    // lands on — this cue is applied to whatever the user happened to
+    // focus, so it must be incapable of disturbing any layout.
+    style.textContent =
+        `@keyframes ${RELAY_CUE_CLASS}{0%,100%{opacity:1}50%{opacity:.45}}` +
+            `.${RELAY_CUE_CLASS}{animation:${RELAY_CUE_CLASS} ` +
+            `${RELAY_CUE_DURATION_MS}ms ease-in-out}`;
+    document.head.appendChild(style);
+}
+/**
+ * The element to pulse, or `null` when there isn't a usable one.
+ *
+ * Usable means: a real focused element that belongs to the render. A
+ * document with nothing focused reports `document.body`, which is not a
+ * control the user just pressed; and anything outside
+ * `[data-ggui-session-root]` (host chrome, the toast itself) is not
+ * ours to animate. Both fall through to the toast.
+ *
+ * The root ITSELF is excluded too. `contains` is reflexive, so a
+ * focused session root would otherwise pulse the whole render — the
+ * opposite of a cue pointing at one control. That is reachable: the
+ * root is reused if one already exists in the document (see
+ * `ensureStatusDom`), so a host or a generated tree can hand it a
+ * `tabindex` and focus it.
+ */
+function resolveRelayCueTarget() {
+    const active = document.activeElement;
+    if (active === null || active === document.body)
+        return null;
+    const root = document.querySelector('[data-ggui-session-root]');
+    if (root === null || active === root || !root.contains(active))
+        return null;
+    return active;
+}
+/**
+ * Speak the pulse (ggui#447).
+ *
+ * The pulse animates opacity on a control the runtime does not own, so
+ * it carries nothing to assistive technology and nothing may be added
+ * to that control — a role or label written onto generated markup would
+ * 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.
+ *
+ * Throttled on its own clock, unlike the pulse — but only against
+ * IDENTICAL repeats. A flash repeating on every gesture costs a sighted
+ * user nothing to ignore, while the same sentence read aloud each time
+ * buries whatever else the screen reader was saying and carries no new
+ * information. A DIFFERENT action is new information: withholding it
+ * would leave the region naming the previous gesture, which reads as a
+ * confident answer about the wrong thing. The two cues share a meaning,
+ * not a rate.
+ *
+ * The cue also expires. A live region is a description of what is
+ * happening now, and a 400ms pulse that leaves a sentence standing for
+ * the rest of the session is the same stale-announcement defect the
+ * toast half avoids by clearing on hide.
+ */
+function announceRelayCue(intent) {
+    const now = Date.now();
+    if (intent === lastRelayCueAnnouncedIntent &&
+        now - lastRelayCueAnnouncedAt < RELAY_CUE_THROTTLE_MS) {
+        return;
+    }
+    lastRelayCueAnnouncedAt = now;
+    lastRelayCueAnnouncedIntent = intent;
+    // `announceToast` cancels any retraction still pending, so the timer
+    // armed here is always the only one in flight.
+    announceToast(`⚠ ${intent} — not delivered`, 'error');
+    relayCueAnnounceTimer = window.setTimeout(() => {
+        relayCueAnnounceTimer = undefined;
+        retractRelayCueAnnouncement();
+    }, RELAY_CUE_ANNOUNCE_TTL_MS);
+}
+/**
+ * Take a spoken cue back down once it has been heard.
+ *
+ * Unconditional, because by the time it runs the region can only hold
+ * this cue's own sentence or nothing at all: every other write to the
+ * region goes through {@link announceToast}, which cancels this
+ * retraction before it speaks.
+ *
+ * That cancellation is the whole mechanism — comparing text here could
+ * not substitute for it. The pulse cue and the fallback cue toast build
+ * their sentences from the SAME template, so for one intent the two are
+ * character-identical and no comparison can tell a dead cue from a live
+ * toast.
+ */
+function retractRelayCueAnnouncement() {
+    if (typeof document === 'undefined')
+        return;
+    const regions = ensureToastAnnouncer(document);
+    if (regions === null)
+        return;
+    regions.assertive.textContent = '';
+}
+/**
+ * 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.
+ *
+ * Component-agnostic by construction. It pulses whatever the user
+ * focused without knowing what that is, and falls back to the toast
+ * primitive when there is nothing to pulse. Either shape also SPEAKS
+ * (ggui#447) — the pulse via {@link announceRelayCue}, the fallback via
+ * the toast primitive's own announcement.
+ */
+function showPostDismissalCue(intent) {
+    if (typeof document === 'undefined')
+        return;
+    const target = resolveRelayCueTarget();
+    if (target !== null) {
+        // A pulse already running on this element IS the acknowledgement
+        // for this gesture too. Re-adding a present class would not restart
+        // the animation anyway (that needs a reflow), and racing two
+        // removal timers on one element is how a class gets stranded.
+        if (target.classList.contains(RELAY_CUE_CLASS))
+            return;
+        ensureRelayCueStyle();
+        target.classList.add(RELAY_CUE_CLASS);
+        announceRelayCue(intent);
+        // Both cleanup routes cancel the other. Without the `clearTimeout`,
+        // a pulse ended early by `animationend` leaves its timer armed, and
+        // that timer later strips whatever class is on the element THEN —
+        // truncating the next pulse partway through. The window is the gap
+        // between the two, which widens on any host that ends the
+        // animation early.
+        const clear = () => {
+            target.classList.remove(RELAY_CUE_CLASS);
+            target.removeEventListener('animationend', clear);
+            // `timer` is declared below; `clear` only ever RUNS after that
+            // line, so it always reads an initialized id.
+            clearTimeout(timer);
+        };
+        target.addEventListener('animationend', clear, { once: true });
+        // Belt for real browsers, braces for everything that never fires
+        // `animationend`: jsdom, a display:none subtree, and any host whose
+        // reduced-motion policy skips the animation outright.
+        const timer = window.setTimeout(clear, RELAY_CUE_DURATION_MS + 100);
+        return;
+    }
+    const now = Date.now();
+    if (now - lastRelayCueToastAt < RELAY_CUE_THROTTLE_MS)
+        return;
+    lastRelayCueToastAt = now;
+    // The toast primitive's auto-dismissing variant — this is a cue, not
+    // a second explanation, so it must clear itself. Throttled because a
+    // per-click toast on a host that fails every click is the #426
+    // failure mode the latch exists to prevent.
+    showActionToast(`⚠ ${intent} — not delivered`, 'error');
+}
 /**
  * Dispatch a submit-action via the empirically-validated bridge
  * chain (validated against claude.ai): a `tools/call` to
@@ -1551,7 +2035,24 @@ export function dispatchSubmitAction(args) {
     // immediately so they know the click was registered, even when
     // submit_action's HTTP round-trip takes a moment. State updates
     // when the response (or fallback) lands.
-    showActionToast(`→ ${intent}${dataPart}`, 'pending');
+    //
+    // Skipped once the relay-incapability notice has latched (ggui#440):
+    // we already know this host can't relay, so a fresh "sending…" flash
+    // would clobber the persistent explanation with a transient state
+    // 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.
+    if (!relayIncapabilityAnnounced) {
+        showActionToast(`→ ${intent}${dataPart}`, 'pending');
+    }
+    else if (relayNoticeDismissed) {
+        showPostDismissalCue(intent);
+    }
     // (2) Try submit_action via host relay. Spec-compliant hosts
     // forward the tools/call to the MCP server's submit_action handler;
     // the pipe entry lands with `id: actionId`. On success, branch on
@@ -1590,10 +2091,60 @@ export function dispatchSubmitAction(args) {
             showActionToast(`⚠ ${intent} — transport error`, 'error');
             resp = null;
         }
+        // Self-healing (ggui#440): a result envelope arriving at all is
+        // proof this host CAN relay — `{ok:false, code:'PIPE_NOT_FOUND'}`
+        // (an otherwise-healthy relay, expired pipe) proves it exactly as
+        // much as `{ok:true}` — so any earlier (possibly false — see
+        // `isRelayShapedFailure`) "cannot relay" latch no longer holds.
+        // Cleared HERE, at response arrival, so the success path and the
+        // `{ok:false}` path below both release it; clearing also
+        // un-freezes `channelToolsCall`'s guard, which reads this same
+        // latch. Transition-edged: acts (and emits the observability
+        // edge) only when a latch was actually standing. No oscillation
+        // within one dispatch — the latch-set branch below requires
+        // `isRelayShapedFailure(resp)`, which this guard excludes.
+        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',
+            });
+            // 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
+            // no successor until a `drain_ack` frame that may never arrive
+            // in MCP-Apps relay contexts. On the success sub-case, replace
+            // it with the ordinary pending toast so the drain_ack dismissal
+            // chain below has a predecessor to dismiss. No equivalent is
+            // needed on the {ok:false} sub-case: that path always falls
+            // through to the terminal "could not reach the agent" toast a
+            // few lines down, which already replaces the stale notice.
+            if (classifySubmitActionResponse(resp) === 'success') {
+                showActionToast(`→ ${intent}${dataPart}`, 'pending');
+            }
+        }
         if (resp !== null && classifySubmitActionResponse(resp) === 'success') {
             const consumerPresent = extractConsumerPresent(resp);
             if (consumerPresent === false) {
-                showActionToast(`💬 ${intent}${dataPart} — agent not listening, sent to chat`, 'action_required');
+                // No `ggui_consume` long-poll is draining this render's pipe,
+                // so the gesture needs a fresh agent turn. `ui/message` is the
+                // ONLY view→host method that can start one — a host that does
+                // not accept it cannot be woken by us at all, and the user has
+                // to send a message themselves (ggui#440).
+                //
+                // The doorbell is posted either way: capability absence is an
+                // unconfirmed signal, not a proven "cannot", and a dropped
+                // postMessage costs nothing.
+                showActionToast(hostCanReceiveMessages()
+                    ? `💬 ${intent}${dataPart} — agent not listening, sent to chat`
+                    : `💬 ${intent}${dataPart} — agent not listening. Send a message to continue.`, 'action_required');
                 emitUserActionDoorbell({
                     intent,
                     sessionId,
@@ -1607,12 +2158,135 @@ export function dispatchSubmitAction(args) {
             // it when ggui_consume drains the event.
             return;
         }
-        // Enqueue failed (pipe gone / transport error). The gesture is not
-        // on any pipe, so a doorbell would point at an empty queue. Surface
-        // the failure as a toast; no `ui/message` is emitted.
+        // Enqueue failed (pipe gone / transport error / host has no relay).
+        // The gesture is not on any pipe, so a doorbell would point at an
+        // empty queue; no `ui/message` is emitted either way.
+        //
+        // Separate the STRUCTURAL case from the transient one (ggui#440):
+        // when the host never advertised `serverTools`, every gesture will
+        // fail identically, so explain it once, persistently, instead of
+        // one identical error toast per click. Latching requires ALL of:
+        //
+        //   - `hostCapabilitiesCaptured()` — the handshake has actually
+        //     resolved. Before that, capability absence is "not asked
+        //     yet", not "advertised nothing"; a gesture that fails in the
+        //     mount-to-handshake window would otherwise falsely latch a
+        //     fully-capable host that just hasn't finished connecting.
+        //   - `!hostCanRelayToolCalls()` — the host never advertised
+        //     `serverTools`.
+        //   - `isRelayShapedFailure(resp)` — NO well-formed result
+        //     envelope arrived. A `{ok:false, code:'PIPE_NOT_FOUND'}`
+        //     result (the common expired-pipe case) is proof the host DID
+        //     relay the call there and back; latching on that would falsely
+        //     brand a working relay as incapable and freeze the channel
+        //     router pre-attempt. That case has already CLEARED any
+        //     standing latch at the response-arrival guard above, and
+        //     keeps routing to the ordinary per-gesture transient toast
+        //     below instead.
+        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;
+                });
+            }
+            return;
+        }
         showActionToast(`⚠ ${intent} — could not reach the agent`, 'error');
     })();
 }
+/**
+ * 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.
+ * 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.
+ *
+ * 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
+ * things. It makes each doomed tick CHEAP — the poll throws before
+ * the `callServerToolSpec` round-trip. And, by throwing the typed
+ * {@link RelayIncapableError} rather than a bare `Error`, it tells
+ * the router WHICH KIND of failure this is: `channel-transport.ts`'s
+ * tick classifies structural rejections apart from transient ones and
+ * drops the channel to a slow probe cadence, emitting one
+ * `channel-poll-degraded` event per transition. The first poll that
+ * succeeds after the latch clears restores the normal cadence and
+ * emits `channel-poll-recovered`.
+ *
+ * The channel keeps probing throughout, which is what makes that
+ * recovery possible: the latch clears only when a call succeeds, and
+ * only an attempt can discover that. A channel stopped on structural
+ * failure could never come back.
+ *
+ * Keyed on the LATCH, not on `hostCanRelayToolCalls()` directly: raw
+ * advertisement absence never changes after boot, so gating on it
+ * here would throw pre-attempt for the LIFE OF THE SESSION on any
+ * host that under-advertises but genuinely proxies `tools/call`
+ * (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.
+ *
+ * Extracted to a named export (rather than an inline closure inside
+ * `bootProduction`) so unit tests can drive it directly through the
+ * lightweight `MockTransport` harness — `bootProduction` dynamic-
+ * imports the full react/design/wire module graph, which is too
+ * heavy to exercise from a spec file (see
+ * `boot-production-context.test.ts`'s docstring for precedent).
+ *
+ * @internal — exported for unit tests + production reuse.
+ */
+export async function channelToolsCall(args) {
+    if (relayIncapabilityAnnounced) {
+        throw new RelayIncapableError();
+    }
+    const resp = await callServerToolSpec(args.toolName, args.args);
+    if (resp.error !== undefined) {
+        throw new Error(resp.error.message ?? 'tools/call failed');
+    }
+    const result = resp.result;
+    if (result === null || typeof result !== 'object') {
+        return null;
+    }
+    const structured = result
+        .structuredContent;
+    if (structured !== undefined)
+        return structured;
+    return result;
+}
 /**
  * Resolve the name of the spec-canonical submit-action receiver tool
  * the dispatch path targets with `tools/call`.
@@ -2397,28 +3071,11 @@ async function bootProduction(opts) {
                     }
                     : {}),
                 send: (msg) => manager.send(msg),
-                toolsCall: async ({ toolName, args }) => {
-                    // 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. 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.
-                    const resp = await callServerToolSpec(toolName, args);
-                    if (resp.error !== undefined) {
-                        throw new Error(resp.error.message ?? 'tools/call failed');
-                    }
-                    const result = resp.result;
-                    if (result === null || typeof result !== 'object') {
-                        return null;
-                    }
-                    const structured = result.structuredContent;
-                    if (structured !== undefined)
-                        return structured;
-                    return result;
-                },
+                // See `channelToolsCall`'s docstring (defined alongside
+                // `dispatchSubmitAction`, its sibling consumer of the
+                // relay-incapability latch) for the fail-fast + fail-safe
+                // rationale (ggui#440).
+                toolsCall: channelToolsCall,
                 streamBus,
                 ...(onObserve !== undefined
                     ? {
@@ -2475,9 +3132,6 @@ async function bootProduction(opts) {
             channelRegistry.register(createChannelErrorHandler({
                 getChannelTransport: () => channelTransport,
             }));
-            channelRegistry.register(createSystemHandler({
-                ...(onObserve !== undefined ? { onObserve } : {}),
-            }));
             return {
                 rootWireConfig: rootConfig,
                 streamBus,