@guuey/mcp-apps-host 0.19.0 → 0.20.0

package/dist/auto-resize.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The `autoResize` sizing POLICY (guuey#992) — the host's side of the
+ * `ui/notifications/size-changed` handshake, kept pure so the loop it
+ * prevents is pinned by `auto-resize.test.ts` without a DOM.
+ *
+ * Why a policy and not "apply the report": the view runtime
+ * (`@ggui-ai/iframe-runtime`) measures `documentElement` at `max-content`.
+ * A view whose body is viewport-bound (`min-height: 100vh` — routine in
+ * generated card CSS, and agent-generated HTML is not ours to control)
+ * measures the frame's OWN height plus a constant δ (margins, padding) and
+ * reports it back; a host that applies every report verbatim grows the
+ * frame by δ per tick without bound. The founder's first prod card sat at
+ * 86,816 px. The view cannot tell the two apart; the host can:
+ *
+ *   1. CEILING — a report is clamped to `ceiling` (the host viewport, or
+ *      the embedder's `maxHeight`). A taller card scrolls inside its frame,
+ *      as in every chat client.
+ *   2. ECHO DETECTOR — a SECOND consecutive growth by the same δ (±2 px),
+ *      arriving within {@link ECHO_WINDOW_MS} of our own apply, is the view
+ *      echoing the frame, not content: the frame is HELD. The runtime
+ *      dedupes identical reports, so a held frame goes quiet.
+ *
+ * Everything else applies: the first report, every shrink (which also
+ * releases a hold), and a growth that is not an echo — real content growth
+ * (a section opened) still sizes the frame.
+ */
+/** Two same-δ growths inside this window after our apply = the echo. */
+export declare const ECHO_WINDOW_MS = 1000;
+/** δ tolerance between the two growths — sub-pixel rounding, not content. */
+export declare const ECHO_DELTA_TOLERANCE_PX = 2;
+export interface AutoResizeState {
+    /** The height the host last applied to the frame, if any. */
+    readonly applied?: number;
+    /** When it was applied (ms clock the caller supplies). */
+    readonly appliedAt?: number;
+    /** The growth (report − applied) the last apply was, if it was a growth. */
+    readonly lastDelta?: number;
+    /** When the last report arrived — a held frame stays held while growth reports keep coming. */
+    readonly lastReportAt?: number;
+    /** True while the frame is held against an echo. */
+    readonly held: boolean;
+}
+export interface AutoResizeDecision {
+    /** The height to apply now, or `undefined` to leave the frame as it is. */
+    readonly apply: number | undefined;
+    readonly state: AutoResizeState;
+}
+export declare function initialAutoResizeState(): AutoResizeState;
+export declare function decideAutoResize(state: AutoResizeState, reportedHeight: number, nowMs: number, ceiling?: number): AutoResizeDecision;
+//# sourceMappingURL=auto-resize.d.ts.map

package/dist/auto-resize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-resize.d.ts","sourceRoot":"","sources":["../src/auto-resize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,wEAAwE;AACxE,eAAO,MAAM,cAAc,OAAQ,CAAC;AACpC,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC;AAED,wBAAgB,sBAAsB,IAAI,eAAe,CAExD;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf,kBAAkB,CAmCpB"}

package/dist/auto-resize.js

@@ -0,0 +1,66 @@
+/**
+ * The `autoResize` sizing POLICY (guuey#992) — the host's side of the
+ * `ui/notifications/size-changed` handshake, kept pure so the loop it
+ * prevents is pinned by `auto-resize.test.ts` without a DOM.
+ *
+ * Why a policy and not "apply the report": the view runtime
+ * (`@ggui-ai/iframe-runtime`) measures `documentElement` at `max-content`.
+ * A view whose body is viewport-bound (`min-height: 100vh` — routine in
+ * generated card CSS, and agent-generated HTML is not ours to control)
+ * measures the frame's OWN height plus a constant δ (margins, padding) and
+ * reports it back; a host that applies every report verbatim grows the
+ * frame by δ per tick without bound. The founder's first prod card sat at
+ * 86,816 px. The view cannot tell the two apart; the host can:
+ *
+ *   1. CEILING — a report is clamped to `ceiling` (the host viewport, or
+ *      the embedder's `maxHeight`). A taller card scrolls inside its frame,
+ *      as in every chat client.
+ *   2. ECHO DETECTOR — a SECOND consecutive growth by the same δ (±2 px),
+ *      arriving within {@link ECHO_WINDOW_MS} of our own apply, is the view
+ *      echoing the frame, not content: the frame is HELD. The runtime
+ *      dedupes identical reports, so a held frame goes quiet.
+ *
+ * Everything else applies: the first report, every shrink (which also
+ * releases a hold), and a growth that is not an echo — real content growth
+ * (a section opened) still sizes the frame.
+ */
+/** Two same-δ growths inside this window after our apply = the echo. */
+export const ECHO_WINDOW_MS = 1_000;
+/** δ tolerance between the two growths — sub-pixel rounding, not content. */
+export const ECHO_DELTA_TOLERANCE_PX = 2;
+export function initialAutoResizeState() {
+    return { held: false };
+}
+export function decideAutoResize(state, reportedHeight, nowMs, ceiling) {
+    const target = ceiling !== undefined ? Math.min(reportedHeight, ceiling) : reportedHeight;
+    const { applied } = state;
+    // First report, or nothing to change.
+    if (applied === undefined) {
+        return { apply: target, state: { applied: target, appliedAt: nowMs, lastReportAt: nowMs, held: false } };
+    }
+    if (target === applied)
+        return { apply: undefined, state: { ...state, lastReportAt: nowMs } };
+    // A shrink always applies and releases any hold.
+    if (target < applied) {
+        return { apply: target, state: { applied: target, appliedAt: nowMs, lastReportAt: nowMs, held: false } };
+    }
+    // A growth while HELD: growth reports still arriving in quick succession
+    // are the same echo (or a view growing on its own clock regardless of the
+    // frame — equally not a reason to move); a growth after a quiet window is
+    // content and falls through to a fresh judgement.
+    if (state.held && state.lastReportAt !== undefined && nowMs - state.lastReportAt <= ECHO_WINDOW_MS) {
+        return { apply: undefined, state: { ...state, lastReportAt: nowMs } };
+    }
+    // A growth: the echo test — the same δ as the growth we just applied,
+    // inside the window of that apply, is the view measuring the taller frame.
+    const delta = target - applied;
+    const withinWindow = state.appliedAt !== undefined && nowMs - state.appliedAt <= ECHO_WINDOW_MS;
+    const sameDelta = state.lastDelta !== undefined && Math.abs(delta - state.lastDelta) <= ECHO_DELTA_TOLERANCE_PX;
+    if (withinWindow && sameDelta) {
+        return { apply: undefined, state: { ...state, lastReportAt: nowMs, held: true } };
+    }
+    return {
+        apply: target,
+        state: { applied: target, appliedAt: nowMs, lastDelta: delta, lastReportAt: nowMs, held: false },
+    };
+}

package/dist/react.d.ts

@@ -76,6 +76,15 @@ export interface GuueyViewProps extends Pick<AttachViewHostConfig, "hostCapabili
      * fires either way.
      */
     autoResize?: boolean;
+    /**
+     * The tallest frame `autoResize` may apply, in px (guuey#992). Default:
+     * the host window's `innerHeight` at the time of the report — a card
+     * taller than the viewport scrolls inside its frame. Reports are also
+     * judged by the echo detector in `auto-resize.ts`: a view whose body is
+     * viewport-bound measures the frame's own height back to the host, and a
+     * host that applied every report verbatim grew a frame to 86,816 px.
+     */
+    maxHeight?: number;
     /**
      * Sandbox flags appended to the safe default (`allow-scripts`). Every
      * entry widens what agent-generated HTML may do — `allow-same-origin`

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAwC,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACjG,OAAO,EAAoC,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACzG,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC/F,YAAY,EAAE,iBAAiB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAKtF,MAAM,WAAW,cACf,SAAQ,IAAI,CACV,oBAAoB,EAClB,kBAAkB,GAClB,UAAU,GACV,aAAa,GACb,YAAY,GACZ,sBAAsB,GACtB,eAAe,GACf,YAAY,GACZ,gBAAgB,GAChB,eAAe,GACf,sBAAsB,GACtB,YAAY,GACZ,gBAAgB,CACnB;IACD,iFAAiF;IACjF,KAAK,EAAE,iBAAiB,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;IACtC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,gBAAgB,KAAK,SAAS,CAAC;CAClF;AA8CD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CA0K1D"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAwC,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACjG,OAAO,EAAoC,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACzG,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC/F,YAAY,EAAE,iBAAiB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAKtF,MAAM,WAAW,cACf,SAAQ,IAAI,CACV,oBAAoB,EAClB,kBAAkB,GAClB,UAAU,GACV,aAAa,GACb,YAAY,GACZ,sBAAsB,GACtB,eAAe,GACf,YAAY,GACZ,gBAAgB,GAChB,eAAe,GACf,sBAAsB,GACtB,YAAY,GACZ,gBAAgB,CACnB;IACD,iFAAiF;IACjF,KAAK,EAAE,iBAAiB,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;IACtC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,gBAAgB,KAAK,SAAS,CAAC;CAClF;AA8CD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAkL1D"}

package/dist/react.js

@@ -36,6 +36,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { attachViewHost, viewDocumentHtml } from "./view-host.js";
 import { attachSandboxPageDelivery } from "./sandbox-page.js";
+import { decideAutoResize, initialAutoResizeState } from "./auto-resize.js";
 export { attachViewHost, viewDocumentHtml } from "./view-host.js";
 export { attachSandboxPageDelivery, isSandboxProxyReady, SANDBOX_PROXY_READY_METHOD, SANDBOX_RESOURCE_READY_METHOD, } from "./sandbox-page.js";
 /** Accessible name for a mounted view when the caller has nothing better. */
@@ -75,13 +76,15 @@ function defaultStatus(phase, channel, diagnosis) {
  * docblock for the sandbox and state contracts.
  */
 export function GuueyView(props) {
-    const { mount, sandboxPageUrl, autoResize, dangerouslyAddSandboxFlags, allow, title, className, style, onPhaseChange, renderStatus, ...hostConfig } = props;
+    const { mount, sandboxPageUrl, autoResize, maxHeight, dangerouslyAddSandboxFlags, allow, title, className, style, onPhaseChange, renderStatus, ...hostConfig } = props;
     const frameRef = useRef(null);
     const [phase, setPhase] = useState("negotiating");
     // The CSP tripwire's verdict for THIS document, if any (guuey#235).
     const [diagnosis, setDiagnosis] = useState(undefined);
-    // The view's own size report, applied only under `autoResize`.
+    // The view's own size report, applied only under `autoResize` — and only
+    // as the sizing policy allows (ceiling + echo detector, guuey#992).
     const [reportedHeight, setReportedHeight] = useState(undefined);
+    const sizing = useRef(initialAutoResizeState());
     const html = viewDocumentHtml(mount.resource);
     // Vet the sandbox page once per URL. Same-origin is REFUSED (the widget's
     // ResourceMount precedent, generalized): the whole point of the page is
@@ -109,8 +112,8 @@ export function GuueyView(props) {
     // The attachment is keyed to the mounted DOCUMENT, not to every render's
     // fresh callback identities — host config rides a ref so the effect's
     // dependency list is honestly just the document identity.
-    const latest = useRef({ hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize });
-    latest.current = { hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize };
+    const latest = useRef({ hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize, maxHeight });
+    latest.current = { hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize, maxHeight };
     useEffect(() => {
         // Keyed to the same identity the frame is (the resource uri): a new
         // document boots fresh, and the previous negotiation's phase must not
@@ -118,6 +121,7 @@ export function GuueyView(props) {
         setPhase("negotiating");
         setDiagnosis(undefined);
         setReportedHeight(undefined);
+        sizing.current = initialAutoResizeState();
         const frame = frameRef.current;
         if (frame === null || html === undefined)
             return;
@@ -144,7 +148,11 @@ export function GuueyView(props) {
             },
             onSizeChanged: (size) => {
                 if (latest.current.autoResize === true && size.height !== undefined) {
-                    setReportedHeight(size.height);
+                    const ceiling = latest.current.maxHeight ?? (typeof window !== "undefined" ? window.innerHeight : undefined);
+                    const decision = decideAutoResize(sizing.current, size.height, Date.now(), ceiling);
+                    sizing.current = decision.state;
+                    if (decision.apply !== undefined)
+                        setReportedHeight(decision.apply);
                 }
                 latest.current.hostConfig.onSizeChanged?.(size);
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "The MCP Apps (SEP-1865) Host role for guuey's chat surfaces — view-mount narrowing across UI channels, ui:// locator rehydration by resources/read, and the sandbox-trust channel contract. Vendor-neutral: any spec-following MCP App mounts through it.",
   "license": "MIT",
   "type": "module",

package/src/auto-resize.ts

@@ -0,0 +1,96 @@
+/**
+ * The `autoResize` sizing POLICY (guuey#992) — the host's side of the
+ * `ui/notifications/size-changed` handshake, kept pure so the loop it
+ * prevents is pinned by `auto-resize.test.ts` without a DOM.
+ *
+ * Why a policy and not "apply the report": the view runtime
+ * (`@ggui-ai/iframe-runtime`) measures `documentElement` at `max-content`.
+ * A view whose body is viewport-bound (`min-height: 100vh` — routine in
+ * generated card CSS, and agent-generated HTML is not ours to control)
+ * measures the frame's OWN height plus a constant δ (margins, padding) and
+ * reports it back; a host that applies every report verbatim grows the
+ * frame by δ per tick without bound. The founder's first prod card sat at
+ * 86,816 px. The view cannot tell the two apart; the host can:
+ *
+ *   1. CEILING — a report is clamped to `ceiling` (the host viewport, or
+ *      the embedder's `maxHeight`). A taller card scrolls inside its frame,
+ *      as in every chat client.
+ *   2. ECHO DETECTOR — a SECOND consecutive growth by the same δ (±2 px),
+ *      arriving within {@link ECHO_WINDOW_MS} of our own apply, is the view
+ *      echoing the frame, not content: the frame is HELD. The runtime
+ *      dedupes identical reports, so a held frame goes quiet.
+ *
+ * Everything else applies: the first report, every shrink (which also
+ * releases a hold), and a growth that is not an echo — real content growth
+ * (a section opened) still sizes the frame.
+ */
+
+/** Two same-δ growths inside this window after our apply = the echo. */
+export const ECHO_WINDOW_MS = 1_000;
+/** δ tolerance between the two growths — sub-pixel rounding, not content. */
+export const ECHO_DELTA_TOLERANCE_PX = 2;
+
+export interface AutoResizeState {
+  /** The height the host last applied to the frame, if any. */
+  readonly applied?: number;
+  /** When it was applied (ms clock the caller supplies). */
+  readonly appliedAt?: number;
+  /** The growth (report − applied) the last apply was, if it was a growth. */
+  readonly lastDelta?: number;
+  /** When the last report arrived — a held frame stays held while growth reports keep coming. */
+  readonly lastReportAt?: number;
+  /** True while the frame is held against an echo. */
+  readonly held: boolean;
+}
+
+export interface AutoResizeDecision {
+  /** The height to apply now, or `undefined` to leave the frame as it is. */
+  readonly apply: number | undefined;
+  readonly state: AutoResizeState;
+}
+
+export function initialAutoResizeState(): AutoResizeState {
+  return { held: false };
+}
+
+export function decideAutoResize(
+  state: AutoResizeState,
+  reportedHeight: number,
+  nowMs: number,
+  ceiling?: number,
+): AutoResizeDecision {
+  const target = ceiling !== undefined ? Math.min(reportedHeight, ceiling) : reportedHeight;
+  const { applied } = state;
+
+  // First report, or nothing to change.
+  if (applied === undefined) {
+    return { apply: target, state: { applied: target, appliedAt: nowMs, lastReportAt: nowMs, held: false } };
+  }
+  if (target === applied) return { apply: undefined, state: { ...state, lastReportAt: nowMs } };
+
+  // A shrink always applies and releases any hold.
+  if (target < applied) {
+    return { apply: target, state: { applied: target, appliedAt: nowMs, lastReportAt: nowMs, held: false } };
+  }
+
+  // A growth while HELD: growth reports still arriving in quick succession
+  // are the same echo (or a view growing on its own clock regardless of the
+  // frame — equally not a reason to move); a growth after a quiet window is
+  // content and falls through to a fresh judgement.
+  if (state.held && state.lastReportAt !== undefined && nowMs - state.lastReportAt <= ECHO_WINDOW_MS) {
+    return { apply: undefined, state: { ...state, lastReportAt: nowMs } };
+  }
+
+  // A growth: the echo test — the same δ as the growth we just applied,
+  // inside the window of that apply, is the view measuring the taller frame.
+  const delta = target - applied;
+  const withinWindow = state.appliedAt !== undefined && nowMs - state.appliedAt <= ECHO_WINDOW_MS;
+  const sameDelta = state.lastDelta !== undefined && Math.abs(delta - state.lastDelta) <= ECHO_DELTA_TOLERANCE_PX;
+  if (withinWindow && sameDelta) {
+    return { apply: undefined, state: { ...state, lastReportAt: nowMs, held: true } };
+  }
+  return {
+    apply: target,
+    state: { applied: target, appliedAt: nowMs, lastDelta: delta, lastReportAt: nowMs, held: false },
+  };
+}

package/src/react.tsx

@@ -35,6 +35,7 @@
 import { useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from "react";
 import { attachViewHost, viewDocumentHtml, type AttachViewHostConfig } from "./view-host.js";
 import { attachSandboxPageDelivery } from "./sandbox-page.js";
+import { decideAutoResize, initialAutoResizeState, type AutoResizeState } from "./auto-resize.js";
 import type { ViewCspDiagnosis, ViewHostPhase } from "./view-host-protocol.js";
 import type { ResolvedViewMount } from "./card-mount.js";
 
@@ -103,6 +104,15 @@ export interface GuueyViewProps
    * fires either way.
    */
   autoResize?: boolean;
+  /**
+   * The tallest frame `autoResize` may apply, in px (guuey#992). Default:
+   * the host window's `innerHeight` at the time of the report — a card
+   * taller than the viewport scrolls inside its frame. Reports are also
+   * judged by the echo detector in `auto-resize.ts`: a view whose body is
+   * viewport-bound measures the frame's own height back to the host, and a
+   * host that applied every report verbatim grew a frame to 86,816 px.
+   */
+  maxHeight?: number;
   /**
    * Sandbox flags appended to the safe default (`allow-scripts`). Every
    * entry widens what agent-generated HTML may do — `allow-same-origin`
@@ -185,6 +195,7 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
     mount,
     sandboxPageUrl,
     autoResize,
+    maxHeight,
     dangerouslyAddSandboxFlags,
     allow,
     title,
@@ -198,8 +209,10 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
   const [phase, setPhase] = useState<ViewHostPhase>("negotiating");
   // The CSP tripwire's verdict for THIS document, if any (guuey#235).
   const [diagnosis, setDiagnosis] = useState<ViewCspDiagnosis | undefined>(undefined);
-  // The view's own size report, applied only under `autoResize`.
+  // The view's own size report, applied only under `autoResize` — and only
+  // as the sizing policy allows (ceiling + echo detector, guuey#992).
   const [reportedHeight, setReportedHeight] = useState<number | undefined>(undefined);
+  const sizing = useRef<AutoResizeState>(initialAutoResizeState());
   const html = viewDocumentHtml(mount.resource);
 
   // Vet the sandbox page once per URL. Same-origin is REFUSED (the widget's
@@ -225,8 +238,8 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
   // The attachment is keyed to the mounted DOCUMENT, not to every render's
   // fresh callback identities — host config rides a ref so the effect's
   // dependency list is honestly just the document identity.
-  const latest = useRef({ hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize });
-  latest.current = { hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize };
+  const latest = useRef({ hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize, maxHeight });
+  latest.current = { hostConfig, onPhaseChange, dangerouslyAddSandboxFlags, autoResize, maxHeight };
 
   useEffect(() => {
     // Keyed to the same identity the frame is (the resource uri): a new
@@ -235,6 +248,7 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
     setPhase("negotiating");
     setDiagnosis(undefined);
     setReportedHeight(undefined);
+    sizing.current = initialAutoResizeState();
     const frame = frameRef.current;
     if (frame === null || html === undefined) return;
     if (sandboxPageUrl !== undefined && page === undefined) return; // refused config — nothing mounts
@@ -259,7 +273,11 @@ export function GuueyView(props: GuueyViewProps): ReactNode {
       },
       onSizeChanged: (size) => {
         if (latest.current.autoResize === true && size.height !== undefined) {
-          setReportedHeight(size.height);
+          const ceiling =
+            latest.current.maxHeight ?? (typeof window !== "undefined" ? window.innerHeight : undefined);
+          const decision = decideAutoResize(sizing.current, size.height, Date.now(), ceiling);
+          sizing.current = decision.state;
+          if (decision.apply !== undefined) setReportedHeight(decision.apply);
         }
         latest.current.hostConfig.onSizeChanged?.(size);
       },