@ggui-ai/iframe-runtime 0.12.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';
@@ -43,13 +44,13 @@ import { createChannelErrorHandler, createChannelPayloadHandler, createDataHandl
 import { connectViaRegistry, } from './registry-subscribe.js';
 import { buildBridgePolling, buildEventsPolling, createSequenceCursor, } from './events-polling.js';
 import { unwrapCallToolResult } from './call-tool-unwrap.js';
-import { ensureStatusDom, setStatus, setConnectedStatus, } from './status-dom.js';
+import { ensureStatusDom, setStatus, setConnectedStatus, retireShellLoadingIndicator, } from './status-dom.js';
 import { mergeReservedValidators, setActiveValidatorSet, } from './validation.js';
 import { loadCompiledValidatorsFromUrl } from './compiled-validators.js';
 import { mountRender, } from './render-item.js';
 import { fromBootstrapFailure, } from './protocol-error.js';
 import { postObservabilityToParent, } from './observability.js';
-import { ACTION_TOAST_Z_INDEX, mountUiFeedbackChrome } from './ui-feedback-chrome.js';
+import { ACTION_TOAST_Z_INDEX, mountUiFeedbackChrome, shouldMountUiFeedbackChrome, } 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';
@@ -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)
@@ -335,7 +344,7 @@ function postBootFailure(reason, message) {
     }
 }
 export async function bootSequence(opts) {
-    const { doc, app, transport, notifyParent, renderer: rendererHooks, onProtocolError, onObserve, onLifecycle } = opts;
+    const { doc, app, transport, notifyParent, renderer: rendererHooks, onProtocolError, onObserve, onLifecycle, uiFeedback } = opts;
     const connectFn = opts.connectFn ?? connectViaRegistry;
     const toolResultTimeoutMs = opts.toolResultTimeoutMs ?? POSTMESSAGE_BOOT_TIMEOUT_MS;
     // Emit typed {@link ProtocolError} for every bootstrap-failure site
@@ -415,6 +424,7 @@ export async function bootSequence(opts) {
     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);
         return { ok: false, mountedRender };
     }
@@ -511,6 +521,7 @@ export async function bootSequence(opts) {
     if (!parsed.ok) {
         const message = `slice-meta parse failed: ${parsed.reason}`;
         setStatus(refs, message, 'error');
+        retireShellLoadingIndicator(doc);
         emitBootFailure(parsed.reason, message);
         return { ok: false, mountedRender };
     }
@@ -547,10 +558,12 @@ export async function bootSequence(opts) {
             ...(onObserve !== undefined ? { onObserve } : {}),
         })
         : null;
-    // In-iframe UI-feedback affordance (ggui#244) — mounted adjacent to
-    // the session root, gated inside the helper on `window.parent !==
-    // window` (top-level `/r/<shortCode>` tabs have no `ggui:observe`
-    // egress, so they get NO affordance) AND here on a LIVE SINK: an
+    // In-iframe UI-feedback affordance (ggui#244) — DEFAULT OFF since
+    // #653 (founder ruling): mounts only when the boot options opt in
+    // via `uiFeedback: true`. When opted in it is additionally gated
+    // inside the helper on `window.parent !== window` (top-level
+    // `/r/<shortCode>` tabs have no `ggui:observe` egress, so they get
+    // NO affordance) AND here on a LIVE SINK: an
     // injected `onObserve` emitter, or a first-party embed host — the
     // only parent that consumes the `ggui:observe` envelope
     // (mcp-app-iframe-host answers `ui/initialize` with exactly this
@@ -560,9 +573,12 @@ export async function bootSequence(opts) {
     // retest surfaced it as unstyled clutter that could never deliver
     // feedback anywhere. Fire-and-forget: chrome never blocks or fails
     // the boot.
-    const feedbackSinkLive = onObserve !== undefined ||
-        app.getHostVersion()?.name === 'ggui-iframe-runtime-embed-host';
-    if (feedbackSinkLive) {
+    const mountFeedback = shouldMountUiFeedbackChrome({
+        uiFeedback,
+        onObserveBound: onObserve !== undefined,
+        hostName: app.getHostVersion()?.name,
+    });
+    if (mountFeedback) {
         void mountUiFeedbackChrome(doc, {
             emit: onObserve ?? postObservabilityToParent,
             sessionId: meta.sessionId,
@@ -630,6 +646,9 @@ export async function bootSequence(opts) {
         if (codeReadyEmitted)
             return;
         codeReadyEmitted = true;
+        // First real paint — the served shell's working-state mark (#667)
+        // becomes a lie the moment content lands.
+        retireShellLoadingIndicator(doc);
         onLifecycle?.(makeLifecycleEvent('code-ready', { sessionId: meta.sessionId }));
     };
     // Mode discriminators. The mount surface is DECOUPLED from the live
@@ -659,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,
@@ -721,6 +744,7 @@ export async function bootSequence(opts) {
     if (!hasLiveTrio && mountedRender === null) {
         const message = 'bootstrap carries neither static content (codeUrl/codeB64/kind) nor a live trio (wsUrl/wsToken)';
         setStatus(refs, message, 'error');
+        retireShellLoadingIndicator(doc);
         emitBootFailure('MISSING_META_GGUI_BOOTSTRAP', message);
         return { ok: false, mountedRender };
     }
@@ -1595,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
@@ -1919,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');
@@ -1961,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
@@ -2191,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
@@ -2208,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
@@ -2301,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();
 }
 /**
@@ -2361,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
@@ -2420,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
@@ -2429,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();
@@ -2538,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;
@@ -2611,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
@@ -2697,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
@@ -2717,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/status-dom.d.ts

@@ -75,3 +75,12 @@ export declare function setStatus(refs: StatusRefs, text: string, state: StatusK
  * intercepting `console.log`) get a stable string on every render.
  */
 export declare function setConnectedStatus(refs: StatusRefs): void;
+/**
+ * Retire the served shell's pre-render working-state mark (#667 —
+ * `[data-ggui-shell-loading]`, the ggui glyph treatment or an
+ * operator's court block). Called at `code-ready` (the first real
+ * paint makes a loading mark a lie) and on terminal boot failure (the
+ * failure card must not sit under an "everything is fine" animation).
+ * Idempotent; a shell without the mark is a no-op.
+ */
+export declare function retireShellLoadingIndicator(doc: Document): void;

package/dist/status-dom.js

@@ -66,3 +66,14 @@ export function setStatus(refs, text, state) {
 export function setConnectedStatus(refs) {
     setStatus(refs, 'Connected.', 'connected');
 }
+/**
+ * Retire the served shell's pre-render working-state mark (#667 —
+ * `[data-ggui-shell-loading]`, the ggui glyph treatment or an
+ * operator's court block). Called at `code-ready` (the first real
+ * paint makes a loading mark a lie) and on terminal boot failure (the
+ * failure card must not sit under an "everything is fine" animation).
+ * Idempotent; a shell without the mark is a no-op.
+ */
+export function retireShellLoadingIndicator(doc) {
+    doc.querySelector('[data-ggui-shell-loading]')?.remove();
+}

package/dist/system-cards/UiFeedbackCard.d.ts

@@ -3,14 +3,19 @@
  * ("did this generated UI work for you?").
  *
  * The in-iframe twin of the host-chrome `UiFeedback` component in
- * `@ggui-ai/mcp-apps-react`: same three verdicts — Love / Dislike / Other
- * (free-text comment) — same acknowledgement after submit, same
- * dismiss control, same payload semantics (trimmed comment only on
- * `verdict: 'other'`, context stamps present exactly when known).
- * Where the host-chrome twin hands a payload to an `onUiFeedback`
- * callback, this card builds a {@link UiFeedbackEvent} and hands it to
- * the injected {@link ObservabilityEmitter} — production binds the
- * `ggui:observe` postMessage-to-parent default, tests record.
+ * `@ggui-ai/mcp-apps-react`: same two verdicts — thumbs up / thumbs
+ * down (#653) — same acknowledgement after submit, same dismiss
+ * control, same payload semantics (context stamps present exactly when
+ * known). Where the host-chrome twin hands a payload to an
+ * `onUiFeedback` callback, this card builds a {@link UiFeedbackEvent}
+ * and hands it to the injected {@link ObservabilityEmitter} —
+ * production binds the `ggui:observe` postMessage-to-parent default,
+ * tests record.
+ *
+ * The verdict buttons are icon-only: monochrome stroked SVGs drawn in
+ * `currentColor`, so the icon ink follows the button's `--ggui-*`
+ * color token in both modes (the #653 theme-applicability
+ * requirement). The verdict's name lives in the `aria-label`.
  *
  * This is CHROME the runtime mounts adjacent to the session root
  * (see `ui-feedback-chrome.ts`), NOT a system card: it has no