@ggui-ai/iframe-runtime 0.11.0 → 0.13.0

package/dist/mcp-app-iframe-host.js

@@ -77,8 +77,13 @@ export function mountMcpAppIframe(container, opts) {
     iframe.style.maxWidth = dims.maxWidth !== undefined ? `${dims.maxWidth}px` : '100%';
     if (dims.maxHeight !== undefined)
         iframe.style.maxHeight = `${dims.maxHeight}px`;
-    iframe.style.border = '1px solid #e5e5e5';
-    iframe.style.borderRadius = '8px';
+    // Round-6 doctrine (ggui#589 @6e15724a1, kit C1 grade): the helper
+    // paints CONTAINMENT ONLY — silhouette (border/radius) belongs to
+    // the embedding host's own chrome, tokens to the theme. The former
+    // 1px #e5e5e5 / radius-8 here was the same ungoverned-chrome class
+    // the RN helper shipped, surfaced by the host-helper catalog's
+    // first-party run (ggui#600 OPEN FINDING, closed here).
+    iframe.style.border = 'none';
     iframe.style.display = 'block';
     container.appendChild(iframe);
     // Cache contentWindow — on detach, `iframe.contentWindow` is null

package/dist/observability.d.ts

@@ -151,10 +151,7 @@ export interface ChannelPollRecoveredEvent {
  * mirror `UiFeedbackPayload` in `@ggui-ai/mcp-apps-react` / `@ggui-ai/mcp-apps-react-native`
  * (the host-chrome twin of this affordance):
  *
- *   - `verdict` — `'love'` / `'dislike'`, or `'other'` for the
- *     free-text flow.
- *   - `comment` — present only for `verdict: 'other'` with a non-empty
- *     trimmed comment.
+ *   - `verdict` — `'up'` / `'down'` (the two thumb verdicts, #653).
  *   - `sessionId` / `toolName` — present exactly when the runtime knew
  *     them at mount time.
  *
@@ -175,9 +172,7 @@ export interface ChannelPollRecoveredEvent {
  */
 export interface UiFeedbackEvent {
     readonly kind: 'ui-feedback';
-    readonly verdict: 'love' | 'dislike' | 'other';
-    /** Trimmed free-text comment; only on `verdict: 'other'`, never empty. */
-    readonly comment?: string;
+    readonly verdict: 'up' | 'down';
     /** GguiSession id of the render the feedback is about. */
     readonly sessionId?: string;
     /** Tool that produced the render (e.g. `ggui_render`). */

package/dist/react-renderer.d.ts

@@ -81,6 +81,28 @@ export interface ReactRootMountOptions {
     readonly appTheme?: {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
+        /**
+         * The REGISTERED base ladder, delivered over the wire (ggui#598-C
+         * runtime theme registration — see protocol's `appThemeSchema`).
+         * BOTH modes' resolved variable sets ride the envelope; when
+         * present, the mode-selected set REPLACES the compiled ladder
+         * block (`getScopedThemeCss`/`getScopedCssTokens`) at the base
+         * position of the #573 precedence above — delivery changes WHERE
+         * the ladder's bytes come from, never WHICH layer wins. Mode
+         * selection reuses the mount's already-resolved `themeMode` (one
+         * projection — no second mode resolution here), and a mode switch
+         * re-paints from the retained other set with no network activity.
+         * Values are injection-safe by the wire schema — never
+         * re-validated here; serialization is key-sorted for byte-stable
+         * output. `documentHash` is the registration's identity (joins a
+         * painted ladder to its registration record); the renderer
+         * carries it but exposes no observability surface for it today.
+         */
+        readonly base?: {
+            readonly documentHash: string;
+            readonly light: Readonly<Record<string, string>>;
+            readonly dark: Readonly<Record<string, string>>;
+        };
     };
     /**
      * Host-announced palette, already translated onto `--ggui-*` tokens

package/dist/react-renderer.js

@@ -31,7 +31,7 @@
  */
 import React, { Component, createElement, Fragment, } from 'react';
 import { createRoot } from 'react-dom/client';
-import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
+import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, assembleDeliveredThemeCss, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
 import { hoistImports, loadModule, loadModuleInline, probeUrlModuleLoad, } from '@ggui-ai/design/module-loader';
 /**
  * Document-lifetime verdict: URL-scheme module loading (`blob:` main
@@ -314,9 +314,25 @@ export async function mountReactRoot(container, opts) {
         }
     }
     function renderTree(opts) {
-        let themeCss = opts.themeId
-            ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
-            : getScopedCssTokens(scopeClass, opts.themeMode);
+        // Delivered base ladder (ggui#598-C): when the slice theme carries
+        // `base`, the mode-selected set REPLACES the compiled ladder block
+        // at the base position — same precedence slot, different byte
+        // source. Mode selection reuses the already-resolved `themeMode`
+        // (one projection; absent means light — the same default
+        // `getScopedThemeCss` applies). Both sets stay retained on the
+        // options, so a mode-switch re-render picks the other ladder from
+        // memory — never the network.
+        const deliveredBase = opts.appTheme?.base;
+        let themeCss = deliveredBase !== undefined
+            ? // Design-package assembler (ggui#598-C, injection-review flag 1):
+                // the delivered ladder gets the SAME scaffolding the compiled
+                // ladder gets — base inherits, derived gradient/effect tokens
+                // (color-mix fallback split), box-sizing, font-inherit — from
+                // ONE shared builder, so the two paths cannot drift.
+                assembleDeliveredThemeCss(scopeClass, opts.themeMode === 'dark' ? deliveredBase.dark : deliveredBase.light)
+            : opts.themeId
+                ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
+                : getScopedCssTokens(scopeClass, opts.themeMode);
         if (opts.hostPalette) {
             // Host palette = the fallback layer (ggui#572, #573 ruling):
             // after the base scoped block so it can repaint at all (the base

package/dist/render-item.d.ts

@@ -51,10 +51,19 @@ export interface RenderItemOptions {
      * so the renderer injects the `--ggui-*` overrides + `color-scheme` at
      * `:root`. Sourced from the bootstrap's `_meta["ai.ggui/render"].theme`.
      * A structural subset of protocol's `AppTheme` (`name` is display-only).
+     * `base` is the delivered registered ladder (ggui#598-C) — forwarded
+     * verbatim; the renderer injects the mode-selected set in place of
+     * the compiled ladder block (see
+     * {@link ReactRootMountOptions.appTheme}).
      */
     readonly appTheme?: {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
+        readonly base?: {
+            readonly documentHash: string;
+            readonly light: Readonly<Record<string, string>>;
+            readonly dark: Readonly<Record<string, string>>;
+        };
     };
     /**
      * Host-announced palette, pre-mapped onto `--ggui-*` tokens by the

package/dist/runtime.d.ts

@@ -276,6 +276,18 @@ export interface BootSequenceOptions {
      * or not this option is bound.
      */
     readonly onObserve?: ObservabilityEmitter;
+    /**
+     * Opt-in knob for the in-iframe UI-feedback chrome (#653). DEFAULT
+     * OFF by founder ruling — a generated component card carries no
+     * feedback affordance unless the embedding deployment passes `true`
+     * here. Even when opted in, the #471 live-sink gate still applies
+     * (see `shouldMountUiFeedbackChrome`): hosts that drop the
+     * `ggui:observe` envelope never get the affordance. Chrome
+     * configuration, not wire data — the agent cannot observe this knob
+     * (data-vs-behavior), so it is a boot option, never a contract
+     * field.
+     */
+    readonly uiFeedback?: boolean;
     /**
      * Optional {@link LifecycleEmitter} sink. Fires on every renderer
      * mount-state transition (`mounting` → `code-ready` | `error`,

package/dist/runtime.js

@@ -28,6 +28,7 @@
 // schema-defining dependency initializes (see zod-jitless.ts).
 import './zod-jitless.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 { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
@@ -42,13 +43,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 { 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';
@@ -213,7 +214,16 @@ export function hostAnnouncedThemeMode() {
  *   `buildOpts` inside `bootSequence`.
  */
 export function resolveMountThemeMode(meta) {
-    return meta.themeMode ?? meta.theme?.mode ?? hostAnnouncedThemeMode();
+    // The CLIENT projection of the protocol's normative theme-binding
+    // total order (@ggui-ai/protocol/integrations/theme-binding,
+    // ggui#598 leg 4) — the server stamps via the sibling projection and
+    // the protocol's composition-law test pins that the two compose
+    // without rank drift.
+    return effectiveThemeMode({
+        stamped: meta.themeMode,
+        sessionSidecar: meta.theme?.mode,
+        hostAnnounced: hostAnnouncedThemeMode(),
+    });
 }
 /**
  * Resolve the mount's base-theme id from the slice (ggui#589 ask 3):
@@ -235,7 +245,12 @@ export function resolveMountThemeMode(meta) {
  *   `buildOpts` inside `bootSequence`.
  */
 export function resolveMountThemeId(meta) {
-    return meta.themeId ?? meta.theme?.name;
+    // Client projection of the normative theme-binding order — see
+    // resolveMountThemeMode above.
+    return effectiveThemeId({
+        stamped: meta.themeId,
+        sidecarName: meta.theme?.name,
+    });
 }
 /**
  * The host's announced palette, read from the connected App's
@@ -320,7 +335,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
@@ -400,6 +415,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 };
     }
@@ -496,6 +512,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 };
     }
@@ -532,10 +549,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
@@ -545,9 +564,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,
@@ -615,6 +637,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
@@ -706,6 +731,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 };
     }
@@ -1630,9 +1656,11 @@ export function emitAudit(args) {
  * Returns `'success'` when the handler said `ok:true`. Returns
  * `'fallback'` for any other outcome — pipe missing
  * (`PIPE_NOT_FOUND`), envelope rejected (`INVALID_ACTION_KIND`),
- * relay error, no host relay wired, or any unexpected shape. The
- * iframe-runtime then falls through to `ui/message` so the gesture
- * still reaches the agent on its next turn.
+ * relay error, no host relay wired, or any unexpected shape. On
+ * `'fallback'` the gesture was NOT enqueued and is dropped with local
+ * feedback only (toast / #440 latch) — no `ui/message` fires (the
+ * doorbell is success-path-only: there is nothing to point it at), and
+ * no alternate transport is attempted today (ggui#599's open leg).
  */
 /**
  * Unwrap the payload record of a relayed submit-action tool result.
@@ -1698,6 +1726,16 @@ function isRelayShapedFailure(resp) {
  * consumer" — the doorbell rings. Shares {@link submitActionPayload}
  * with {@link classifySubmitActionResponse} so both reads agree on
  * which envelope tier carries the payload.
+ *
+ * RELAY CONTRACT (ggui#603): this read only works when the host's
+ * `tools/call` relay threads the server's tool result VERBATIM — the
+ * `consumerPresent` marker rides `structuredContent` on the real
+ * result. A relay that wraps or synthesizes the response silently
+ * strips the marker, and every healthy gesture then misclassifies as
+ * "agent not listening" (a persistent `action_required` toast per
+ * gesture). Verbatim threading is the same obligation that keeps
+ * `_meta` alive on `resources/read` relays; a conformance vector for
+ * it is tracked on ggui#603.
  */
 function extractConsumerPresent(resp) {
     const inner = submitActionPayload(resp);
@@ -1908,7 +1946,7 @@ function showActionToast(text, kind, onDismiss) {
             'bottom:16px',
             'left:50%',
             'transform:translateX(-50%)',
-            'z-index:2147483647',
+            `z-index:${ACTION_TOAST_Z_INDEX}`,
             'pointer-events:auto',
             'max-width:90%',
             'padding:8px 14px',
@@ -3404,20 +3442,30 @@ async function bootProduction(opts) {
                     }
                 },
             };
-            // Spec-canonical outbound dispatch. The WS pipe is for streamSpec
-            // subscriptions ONLY (inbound `ggui_emit` fanout + `props_update` +
-            // `render` + `data` + `drain_ack` + `channel_payload`).
-            // Outbound user actions go through the MCP-Apps host relay per
-            // spec §401: postMessage `tools/call:ggui_runtime_submit_action`
-            // to the parent → `AppRenderer.onCallTool` → sample agent's
-            // `/relay/tools-call` → ggui MCP server →
-            // `createGguiSubmitActionHandler.append` → `pendingEventConsumer`
-            // → `ggui_consume` wakes the agent. The server's WS
-            // `handleInboundAction` writes to the render ledger only — no
-            // downstream consumer — so the WS action path silently drops
-            // clicks. `routeDispatch` is the shared named-export helper
-            // (production + tests exercise the same code path); threading it
-            // here keeps LIVE-mode on the canonical dispatch pipeline.
+            // Spec-canonical outbound dispatch: user actions go through the
+            // MCP-Apps host relay (SPEC §4.7): postMessage
+            // `tools/call:ggui_runtime_submit_action` to the parent →
+            // `AppRenderer.onCallTool` → host's MCP client → ggui MCP server
+            // → `createGguiSubmitActionHandler.append` → `pendingEventConsumer`
+            // → `ggui_consume` wakes the agent. NOTE (truth, ggui#596 +
+            // adversarial-cycle correction): the server's WS ingress
+            // dual-writes accepted `data:submit` frames onto the consume pipe
+            // ONLY when the live channel is composed with a
+            // `pendingEventConsumer` — which `createGguiServer` threads for
+            // DEFAULT-handlers compositions only (a custom `handlers` list
+            // drains its own pipe; bridging the channel onto an instance
+            // nobody drains would buffer gestures into the void — see the
+            // hoist note in server.ts). The hosted pod IS a custom-handlers
+            // caller: on it, a WS gesture lands on the retained ledger only
+            // and never reaches the agent. Any WS action fallback (ggui#599's
+            // open design leg) therefore requires the server/pod bridge
+            // FIRST — it is a capability gap on that composition today. The WS pipe otherwise carries
+            // streamSpec subscriptions (inbound `ggui_emit` fanout +
+            // `props_update` + `render` + `data` + `drain_ack` +
+            // `channel_payload`). `routeDispatch` is the shared named-export
+            // helper (production + tests exercise the same code path);
+            // threading it here keeps LIVE-mode on the canonical dispatch
+            // pipeline.
             // Single mounted render — populated by `applyRender` on the first
             // render frame. The wire config + data channel handler read it
             // through `currentRender`-returning thunks so they always see the

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

package/dist/system-cards/UiFeedbackCard.js

@@ -1,17 +1,22 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * UiFeedbackCard — the runtime's in-iframe UI-feedback affordance
  * ("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
@@ -56,6 +61,8 @@ function buildStyles(scheme) {
         },
         verdictButton: {
             appearance: 'none',
+            display: 'inline-flex',
+            alignItems: 'center',
             background: dark
                 ? 'var(--ggui-color-neutral-50, #1f2937)'
                 : 'var(--ggui-color-neutral-50, #f9fafb)',
@@ -63,9 +70,10 @@ function buildStyles(scheme) {
                 ? '1px solid var(--ggui-color-neutral-200, #374151)'
                 : '1px solid var(--ggui-color-neutral-200, #e5e7eb)',
             borderRadius: 'var(--ggui-shape-radius-sm, 4px)',
-            padding: '2px 8px',
+            padding: '3px 7px',
             fontFamily: 'inherit',
             fontSize: 'inherit',
+            // The icons stroke in currentColor — this token IS the icon ink.
             color: dark
                 ? 'var(--ggui-color-neutral-600, #d1d5db)'
                 : 'var(--ggui-color-neutral-600, #4b5563)',
@@ -83,51 +91,34 @@ function buildStyles(scheme) {
                 : 'var(--ggui-color-neutral-400, #9ca3af)',
             cursor: 'pointer',
         },
-        commentForm: {
-            display: 'inline-flex',
-            alignItems: 'center',
-            gap: 4,
-            margin: 0,
-        },
-        commentInput: {
-            fontFamily: 'inherit',
-            fontSize: 'inherit',
-            padding: '2px 6px',
-            minWidth: 140,
-            border: dark
-                ? '1px solid var(--ggui-color-neutral-200, #374151)'
-                : '1px solid var(--ggui-color-neutral-200, #e5e7eb)',
-            borderRadius: 'var(--ggui-shape-radius-sm, 4px)',
-            background: dark
-                ? 'var(--ggui-color-neutral-50, #111827)'
-                : 'var(--ggui-color-neutral-50, #ffffff)',
-            color: dark
-                ? 'var(--ggui-color-neutral-800, #e5e7eb)'
-                : 'var(--ggui-color-neutral-800, #1f2937)',
-        },
     };
 }
+/**
+ * Monochrome stroked thumb icons. `stroke="currentColor"` is the
+ * theme-applicability contract: the glyph takes whatever ink the
+ * button's `color` token resolves to, in either mode.
+ */
+function ThumbIcon({ direction, }) {
+    return (_jsx("svg", { width: 13, height: 13, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: direction === 'up' ? (_jsxs(_Fragment, { children: [_jsx("path", { d: "M7 10v12" }), _jsx("path", { d: "M15 5.88 14 10h5.83a2 2 0 0 1 1.92 2.56l-2.33 8A2 2 0 0 1 17.5 22H4a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2h2.76a2 2 0 0 0 1.79-1.11L12 2a3.13 3.13 0 0 1 3 3.88Z" })] })) : (_jsxs(_Fragment, { children: [_jsx("path", { d: "M17 14V2" }), _jsx("path", { d: "M9 18.12 10 14H4.17a2 2 0 0 1-1.92-2.56l2.33-8A2 2 0 0 1 6.5 2H20a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2h-2.76a2 2 0 0 0-1.79 1.11L12 22a3.13 3.13 0 0 1-3-3.88Z" })] })) }));
+}
+const VERDICT_LABELS = {
+    up: 'Thumbs up',
+    down: 'Thumbs down',
+};
 export function UiFeedbackCard({ emit, sessionId, toolName, }) {
     const [phase, setPhase] = React.useState('idle');
-    const [comment, setComment] = React.useState('');
     const scheme = useColorScheme();
     const styles = buildStyles(scheme);
-    const send = React.useCallback((verdict, commentText) => {
-        const trimmed = commentText?.trim();
+    const send = React.useCallback((verdict) => {
         emit({
             kind: 'ui-feedback',
             verdict,
-            ...(trimmed !== undefined && trimmed.length > 0 ? { comment: trimmed } : {}),
             ...(sessionId !== undefined ? { sessionId } : {}),
             ...(toolName !== undefined ? { toolName } : {}),
         });
         setPhase('sent');
     }, [emit, sessionId, toolName]);
-    const onCommentSubmit = React.useCallback((e) => {
-        e.preventDefault();
-        send('other', comment);
-    }, [send, comment]);
     if (phase === 'dismissed')
         return null;
-    return (_jsxs("div", { "data-ggui-ui-feedback": true, role: "group", "aria-label": "Share feedback on this UI", style: styles.root, children: [phase === 'sent' ? (_jsx("span", { "data-ggui-ui-feedback-thanks": true, children: "Thanks for the feedback" })) : phase === 'comment' ? (_jsxs("form", { onSubmit: onCommentSubmit, style: styles.commentForm, "data-ggui-ui-feedback-comment-form": true, children: [_jsx("input", { type: "text", value: comment, onChange: (e) => setComment(e.target.value), placeholder: "What happened?", "aria-label": "Feedback comment", "data-ggui-ui-feedback-comment": true, style: styles.commentInput, autoFocus: true }), _jsx("button", { type: "submit", style: styles.verdictButton, "data-ggui-ui-feedback-send": true, children: "Send" })] })) : (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", style: styles.verdictButton, "data-ggui-ui-feedback-verdict": "love", onClick: () => send('love'), children: "Love" }), _jsx("button", { type: "button", style: styles.verdictButton, "data-ggui-ui-feedback-verdict": "dislike", onClick: () => send('dislike'), children: "Dislike" }), _jsx("button", { type: "button", style: styles.verdictButton, "data-ggui-ui-feedback-verdict": "other", onClick: () => setPhase('comment'), children: "Other\u2026" })] })), _jsx("button", { type: "button", style: styles.dismissButton, "aria-label": "Dismiss feedback", "data-ggui-ui-feedback-dismiss": true, onClick: () => setPhase('dismissed'), children: '×' })] }));
+    return (_jsxs("div", { "data-ggui-ui-feedback": true, role: "group", "aria-label": "Share feedback on this UI", style: styles.root, children: [phase === 'sent' ? (_jsx("span", { "data-ggui-ui-feedback-thanks": true, children: "Thanks for the feedback" })) : (['up', 'down'].map((verdict) => (_jsx("button", { type: "button", style: styles.verdictButton, "data-ggui-ui-feedback-verdict": verdict, "aria-label": VERDICT_LABELS[verdict], title: VERDICT_LABELS[verdict], onClick: () => send(verdict), children: _jsx(ThumbIcon, { direction: verdict }) }, verdict)))), _jsx("button", { type: "button", style: styles.dismissButton, "aria-label": "Dismiss feedback", "data-ggui-ui-feedback-dismiss": true, onClick: () => setPhase('dismissed'), children: '×' })] }));
 }

package/dist/ui-feedback-chrome.d.ts

@@ -1,4 +1,50 @@
 import type { ObservabilityEmitter } from './observability.js';
+/**
+ * Stacking contract between the two body-appended runtime layers
+ * (ggui#603): the feedback chrome must sit strictly ABOVE the action
+ * toast. The persistent `action_required` toast parks
+ * `pointer-events:auto` at fixed bottom-center — the same region this
+ * chrome occupies — and is re-armed per gesture; without this order an
+ * armed toast eats every tap aimed at the feedback controls. The toast
+ * remains dismissable on its own uncovered area (it accepts the click
+ * anywhere on itself), so partial occlusion costs it nothing.
+ *
+ * Single source: `runtime.ts`'s toast reads {@link ACTION_TOAST_Z_INDEX};
+ * this module applies {@link UI_FEEDBACK_CHROME_Z_INDEX} to the chrome
+ * container. The test suite pins the relationship, not the numbers.
+ */
+export declare const UI_FEEDBACK_CHROME_Z_INDEX = 2147483647;
+export declare const ACTION_TOAST_Z_INDEX = 2147483646;
+/** Inputs to the boot path's mount decision — see
+ * {@link shouldMountUiFeedbackChrome}. */
+export interface UiFeedbackMountDecisionInput {
+    /**
+     * The opt-in knob from the boot options (#653). Feedback chrome is
+     * DEFAULT OFF: only an explicit `true` can mount it.
+     */
+    readonly uiFeedback: boolean | undefined;
+    /** Whether the boot bound an `onObserve` emitter. */
+    readonly onObserveBound: boolean;
+    /** The MCP-Apps host's announced name, when known. */
+    readonly hostName: string | undefined;
+}
+/**
+ * Pure mount decision the boot path consults before touching the DOM.
+ * Two independent gates compose:
+ *
+ *   1. **The #653 opt-in knob** — the founder's default-off ruling:
+ *      generated-component cards carry NO feedback chrome unless the
+ *      embedding deployment explicitly opts in (`uiFeedback: true` on
+ *      the boot options). Absent or `false` ⇒ never mount, regardless
+ *      of sink state.
+ *   2. **The #471 live-sink gate** — even opted in, only a parent that
+ *      actually consumes the `ggui:observe` envelope gets the
+ *      affordance: a bound `onObserve` emitter, or the first-party
+ *      embed host. Third-party MCP-Apps hosts drop the envelope, and a
+ *      feedback control that can never deliver feedback is worse than
+ *      none.
+ */
+export declare function shouldMountUiFeedbackChrome(input: UiFeedbackMountDecisionInput): boolean;
 export interface UiFeedbackChromeOptions {
     /**
      * Observability sink the card emits `ui-feedback` events into.