@ggui-ai/iframe-runtime 0.16.0 → 0.18.0

package/dist/dismiss-intent.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The dismiss INTENT the card forwards and never acts on (ggui#1109).
+ *
+ * An MCP-Apps card is an iframe: a key pressed while focus is inside its
+ * document never reaches the page around it. So a user who has just clicked
+ * the card — the exact moment they press Escape to close it — presses it into
+ * a document that has no reason to care and no way to pass it on. Before this,
+ * the runtime had NO keydown listener at all, and the surrounding host could
+ * add a perfect one and still never hear that gesture.
+ *
+ * What the card guarantees (protocol's docblock on `McpAppDismissMessage`, and
+ * this module is its implementation): it emits on the gesture, at most ONE
+ * intent per gesture — a held key auto-repeating is one gesture, so repeats are
+ * skipped — it does NOT act on it (no unmount, no visual dismissal, no state
+ * change), and it never learns whether the host honoured it. Ignoring is
+ * conformant: the host owns the surface.
+ */
+import { type McpAppDismissReason } from '@ggui-ai/protocol/integrations/mcp-apps';
+/** Post one intent to the embedding host. Best-effort, like every other parent post. */
+export declare function postDismissIntent(reason: McpAppDismissReason): void;
+/**
+ * Listen for the dismiss gesture inside the card document and forward it.
+ * Idempotent: a second call replaces the first listener rather than stacking a
+ * second one, so a re-boot in the same document cannot double-post.
+ */
+export declare function installDismissIntentListener(doc?: Document): void;
+/** Remove the listener (teardown; also the test seam). */
+export declare function removeDismissIntentListener(doc?: Document): void;

package/dist/dismiss-intent.js

@@ -0,0 +1,65 @@
+/**
+ * The dismiss INTENT the card forwards and never acts on (ggui#1109).
+ *
+ * An MCP-Apps card is an iframe: a key pressed while focus is inside its
+ * document never reaches the page around it. So a user who has just clicked
+ * the card — the exact moment they press Escape to close it — presses it into
+ * a document that has no reason to care and no way to pass it on. Before this,
+ * the runtime had NO keydown listener at all, and the surrounding host could
+ * add a perfect one and still never hear that gesture.
+ *
+ * What the card guarantees (protocol's docblock on `McpAppDismissMessage`, and
+ * this module is its implementation): it emits on the gesture, at most ONE
+ * intent per gesture — a held key auto-repeating is one gesture, so repeats are
+ * skipped — it does NOT act on it (no unmount, no visual dismissal, no state
+ * change), and it never learns whether the host honoured it. Ignoring is
+ * conformant: the host owns the surface.
+ */
+import { MCP_APP_DISMISS_TYPE, } from '@ggui-ai/protocol/integrations/mcp-apps';
+/** The key that means "close this", as the platform names it. */
+const ESCAPE_KEY = 'Escape';
+let installed = null;
+/** Post one intent to the embedding host. Best-effort, like every other parent post. */
+export function postDismissIntent(reason) {
+    if (typeof window === 'undefined' || window.parent === null)
+        return;
+    const message = { type: MCP_APP_DISMISS_TYPE, reason };
+    try {
+        window.parent.postMessage(message, '*');
+    }
+    catch {
+        // Parent unreachable (detached window). Fire-and-forget — the same posture
+        // every other outbound notification takes, and dismissing is the host's
+        // decision anyway.
+    }
+}
+/**
+ * Listen for the dismiss gesture inside the card document and forward it.
+ * Idempotent: a second call replaces the first listener rather than stacking a
+ * second one, so a re-boot in the same document cannot double-post.
+ */
+export function installDismissIntentListener(doc = document) {
+    removeDismissIntentListener(doc);
+    const listener = (ev) => {
+        if (ev.key !== ESCAPE_KEY)
+            return;
+        // A held key auto-repeating is ONE gesture (protocol's guarantee): a user
+        // leaning on Escape must not flood the host with intents.
+        if (ev.repeat)
+            return;
+        // The gesture is NOT consumed: no `preventDefault`, no `stopPropagation`.
+        // Anything else inside the card that listens for Escape — a menu, a
+        // combobox — keeps hearing it, and the host hears it too. The card
+        // forwards; it does not decide.
+        postDismissIntent('escape');
+    };
+    doc.addEventListener('keydown', listener);
+    installed = listener;
+}
+/** Remove the listener (teardown; also the test seam). */
+export function removeDismissIntentListener(doc = document) {
+    if (installed === null)
+        return;
+    doc.removeEventListener('keydown', installed);
+    installed = null;
+}

package/dist/events-polling.js

@@ -231,6 +231,14 @@ export function buildBridgePolling(opts) {
     //     holds the card is presumed quiet; drop to sparse un-held
     //     pulls every `idleIntervalMs` so a dormant card doesn't pin
     //     the host's relay open forever.
+    //   - A FAILED pull (the relay's own `tools/call` timeout, `-32001`,
+    //     a transport error) is not a live session either (ggui#1029):
+    //     it counts toward demotion exactly like an empty hold, and
+    //     repeated failures back off geometrically from `intervalMs`
+    //     up to `idleIntervalMs` — a relay whose call timeout is shorter
+    //     than `holdSeconds` used to answer every held pull with an
+    //     error, which never advanced the counter, so a dormant card
+    //     re-fired a full hold every few seconds forever.
     // Any delivered event promotes straight back to subscription mode.
     let consecutiveEmpties = 0;
     const hot = () => consecutiveEmpties < demoteAfterEmpties;
@@ -246,6 +254,10 @@ export function buildBridgePolling(opts) {
             return unwrapCallToolResult(result);
         },
         parseSnapshot: createEventsSnapshotParser(cursor),
+        nextDelayOnFailureMs: (consecutiveFailures) => {
+            consecutiveEmpties += 1;
+            return Math.min(idleIntervalMs, intervalMs * 2 ** Math.max(0, consecutiveFailures - 1));
+        },
         nextDelayMs: (body) => {
             if (isEventsResponse(body)) {
                 if (body.events.length > 0) {