pmx-canvas 0.1.33 → 0.1.35

package/dist/types/client/canvas/auto-fit.d.ts

@@ -1,5 +1,19 @@
 import type { CanvasNodeState } from '../types';
 export declare const AUTO_FIT_TITLEBAR_HEIGHT = 37;
 export declare const AUTO_FIT_MAX_HEIGHT = 600;
+export declare const AUTO_FIT_MAX_HEIGHT_IFRAME = 1400;
+export declare const AUTO_FIT_BODY_PADDING = 24;
+/** DOM-content nodes (markdown/status/file/…) whose body scrollHeight is directly
+ *  measurable — the one-shot ResizeObserver auto-fit in CanvasNode handles these. */
 export declare function shouldAutoFitNode(node: CanvasNodeState): boolean;
 export declare function computeAutoFitHeight(node: CanvasNodeState, contentHeight: number): number | null;
+/** Iframe surfaces that should GROW to fit their reported content height. */
+export declare function shouldContentFitIframeNode(node: CanvasNodeState): boolean;
+/**
+ * Grow-only target height from a surface-reported content height. Returns null
+ * when the node is exempt, the report is non-positive, or the node already fits
+ * (so it never shrinks — monotonic growth can't oscillate). Adds the titlebar +
+ * node-body padding so the content fully clears (no residual inner scrollbar),
+ * capped at the iframe ceiling.
+ */
+export declare function computeContentGrowHeight(node: CanvasNodeState, contentHeight: number): number | null;

package/dist/types/client/nodes/surface-url.d.ts

@@ -13,17 +13,16 @@ export interface SurfaceUrlOptions {
     v?: string;
     /** Nonce authorizing iframe → parent AX emits (html bridge). */
     axToken?: string;
+    /** Nonce for the content-height reporter (node grows to fit content). */
+    frameToken?: string;
 }
 /** Build the stable per-node surface URL (/api/canvas/surface/:id) the iframe and "Open as site" both use. */
 export declare function nodeSurfaceUrl(nodeId: string, opts?: SurfaceUrlOptions): string;
 /** Whether a node can be opened as a standalone site (shared with the server). */
 export declare function canOpenAsSite(node: CanvasNodeState): boolean;
-/** Open the node's surface in a new browser tab. */
-export declare function openNodeAsSite(node: CanvasNodeState): void;
 /**
- * Open the node's surface in the user's real SYSTEM browser via the server's OS
- * launcher — for hosts (e.g. Codex) whose embedded browser makes a normal
- * `_blank` tab feel in-place. Falls back to a normal new-tab open when the server
- * can't launch (headless / PMX_CANVAS_DISABLE_BROWSER_OPEN).
+ * Open the node's standalone surface in the user's system browser. Falls back to
+ * `window.open` when the server cannot launch a browser, preserving in-browser tests
+ * and headless/disabled-browser environments.
  */
-export declare function openNodeInSystemBrowser(node: CanvasNodeState): Promise<void>;
+export declare function openNodeAsSite(node: CanvasNodeState): Promise<void>;

package/dist/types/client/nodes/use-iframe-content-height.d.ts

@@ -0,0 +1,16 @@
+import type { CanvasNodeState } from '../types';
+/**
+ * Grow an iframe-surface node to fit the content height its surface reports over
+ * the nonce-validated `content-height` postMessage bridge. Grow-only and gated
+ * (see computeContentGrowHeight / shouldContentFitIframeNode), so it never clips,
+ * never shrinks, never fights a manual resize / strictSize / docked node, and —
+ * because growth is monotonic with a dead-band — cannot oscillate. This is the
+ * fix for iframe nodes whose body scrollHeight the parent can't measure.
+ *
+ * The latest node is read through a ref so the effect stays mounted across the
+ * grow (its deps are only id + token). Putting node.size in the deps would re-run
+ * the effect on each grow and its cleanup would cancel the pending persist.
+ */
+export declare function useIframeContentHeight(node: CanvasNodeState, iframeRef: {
+    current: HTMLIFrameElement | null;
+}, frameToken: string): void;

package/dist/types/client/state/intent-bridge.d.ts

@@ -129,7 +129,7 @@ export interface AxInteractionResponse {
 /** Fetch the compact AX state snapshot pushed into AX-enabled surfaces. */
 export declare function fetchAxSurfaceState(): Promise<unknown>;
 /** Ask the server to open a node's surface in the system browser. */
-export declare function openNodeInSystemBrowserRequest(nodeId: string): Promise<{
+export declare function openNodeInSystemBrowserRequest(nodeId: string, url?: string): Promise<{
     ok: boolean;
     opened: boolean;
 }>;

package/dist/types/json-render/server.d.ts

@@ -93,4 +93,10 @@ export declare function buildJsonRenderViewerHtml(options: {
     nodeId?: string;
     axToken?: string;
     axState?: unknown;
+    /** Nonce for the content-height reporter so the node can grow to fit the chart. */
+    frameToken?: string;
+    /** When true, charts render at their natural (intrinsic) height instead of
+     *  filling the viewport down — so the reported scrollHeight is stable and the
+     *  node grows to it. Off for strictSize / user-resized nodes (they fill-down). */
+    fitContent?: boolean;
 }): Promise<string>;

package/dist/types/server/html-surface.d.ts

@@ -38,6 +38,13 @@ export declare function buildAxBridge(axToken: string, nodeId: string): string;
  * the existing AX-enabled gate.
  */
 export declare function buildAxStateBridge(axToken: string, snapshotJson: string): string;
+/**
+ * Reports the surface's natural content height to the parent canvas so the node
+ * can GROW to fit it (the fix for iframe nodes the parent can't measure — graph,
+ * json-render, html, web-artifact). Thin wrapper over the shared reporter so this
+ * and the json-render injection site stay byte-identical (no drift).
+ */
+export declare function buildContentHeightReporter(frameToken: string): string;
 export interface HtmlSurfaceOptions {
     theme: SurfaceTheme;
     /**
@@ -61,6 +68,8 @@ export interface HtmlSurfaceOptions {
      * axBridge is enabled). Kept live via parent → iframe `ax-update` messages.
      */
     axState?: unknown;
+    /** Nonce for the content-height reporter (lets the node grow to fit content). */
+    contentHeightToken?: string;
 }
 /**
  * Wrap author HTML into a complete, themed standalone document. Accepts either a

package/dist/types/shared/content-height-reporter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Content-height reporter — injected into iframe-backed canvas surfaces so the
+ * parent canvas can grow the node to fit its content (the #48 graph-clipping fix).
+ *
+ * The surface posts its natural `document` scrollHeight to `window.parent` over a
+ * nonce-validated channel; the parent (use-iframe-content-height) grows the node
+ * grow-only to fit. Debounced (~100ms) + dead-banded (>4px) so a stray re-measure
+ * can't spam, and grow-only growth on the parent side cannot oscillate.
+ *
+ * Shared by both injection sites — src/server/html-surface.ts (html / web-artifact
+ * surfaces) and src/json-render/server.ts (the json-render/graph viewer) — so the
+ * two stay byte-identical. This module is framework-agnostic and imports nothing
+ * from src/server, preserving the json-render package's decoupling.
+ */
+/** Sanitize a nonce for safe interpolation into an inline script literal. */
+export declare function sanitizeFrameToken(token: string): string;
+/** Inline JS (no `<script>` wrapper) that reports content height to the parent. */
+export declare function contentHeightReporterSource(frameToken: string): string;
+/** `<script>`-wrapped reporter for injection into an HTML `<head>` / document. */
+export declare function contentHeightReporterTag(frameToken: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -833,7 +833,7 @@ what the human has set up and what they're focusing on.
 | `canvas://ax-context` | Agent-ready AX context: pinned context + current focus |
 | `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations, elicitations, mode requests, and tool/prompt policy |
 | `canvas://ax-timeline` | Bounded AX timeline: recent agent events, evidence, and steering messages |
-| `canvas://ax-pending-steering` | Undelivered steering an MCP client can claim, act on, and mark delivered (adapterless delivery) |
+| `canvas://ax-pending-steering` | Adapterless delivery: `pending` steering to claim + mark delivered, and `pendingActivity` (open work items / pending approvals / elicitations / mode requests awaiting the agent) |
 | `canvas://ax-delivery` | Steering delivery state (delivered flag) for diagnostics |
 | `canvas://skills` | Index of bundled agent skills shipped with the install. Each skill is also addressable as `canvas://skills/<name>` (e.g. `canvas://skills/web-artifacts-builder`) and returns the full SKILL.md. Read this resource first to discover companion workflows the canvas is built to support. |
 
@@ -861,10 +861,22 @@ elicitation, or mode request. One envelope, many transports:
   **`mcp-app`** nodes get the same `window.PMX_AX.emit` injected
   (`sourceSurface: 'mcp-app'`). The server re-validates capabilities regardless
   of transport — bridges are convenience, not a trust boundary.
-- **Delivery:** steering can be claimed by adapterless MCP clients via
-  `canvas://ax-pending-steering` / `canvas_claim_ax_delivery` and acknowledged
-  with `canvas_mark_ax_delivery` (loop-safe — a consumer never receives steering
-  it originated).
+- **Delivery (adapterless):** `canvas://ax-pending-steering` /
+  `canvas_claim_ax_delivery` return two things, both loop-safe (a consumer never
+  receives items it originated):
+  - `pending` — undelivered **steering** (directives). Act, then acknowledge with
+    `canvas_mark_ax_delivery`.
+  - `pendingActivity` — open canvas-bound items **awaiting the agent** (open work
+    items, pending approval gates / elicitations / mode requests), usually created
+    by the human in the browser. These are **state, not steering**: don't
+    `canvas_mark_ax_delivery` them — resolve each via its own tool
+    (`canvas_resolve_approval` / `canvas_respond_elicitation` /
+    `canvas_resolve_mode` / `canvas_update_work_item`).
+  - **Contract:** every AX mutation fires `ax-state-changed`, so MCP clients that
+    **subscribe** to resources are pushed `canvas://ax-work` / `canvas://ax-context`
+    live. Clients that **poll** instead should poll `canvas_claim_ax_delivery` —
+    `pendingActivity` is how non-steering browser changes reach them. Only steering
+    flows through the claim/ack queue.
 - **Elicitation / mode:** request structured human input
   (`canvas_request_elicitation` → `canvas_respond_elicitation`) or a workflow
   mode transition (`canvas_request_mode` → `canvas_resolve_mode`); both are

package/src/client/canvas/CanvasNode.tsx

@@ -25,7 +25,7 @@ import {
   viewport,
 } from '../state/canvas-store';
 import { removeNodeFromClient, updateNodeFromClient } from '../state/intent-bridge';
-import { canOpenAsSite, openNodeAsSite, openNodeInSystemBrowser } from '../nodes/surface-url';
+import { canOpenAsSite, openNodeAsSite } from '../nodes/surface-url';
 import { getNodeIcon } from '../icons';
 import { EXPANDABLE_TYPES, TYPE_LABELS } from '../types';
 import type { CanvasNodeState } from '../types';
@@ -86,7 +86,16 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
     updateNode(id, { size: { width, height } });
   }, []);
 
-  const handleResizeEnd = useCallback(() => persistLayout(), []);
+  const handleResizeEnd = useCallback(() => {
+    // A manual resize is explicit user intent — stop auto/content-fit from
+    // overriding it (see isAutoSizeExempt in auto-fit.ts). Persist the flag to the
+    // server (mirrors the rename path below) so it survives layout reconciles,
+    // undo/redo, and snapshots — a client-only flag is wiped by the next
+    // canvas-layout-update broadcast. persistLayout() persists the new size.
+    updateNodeData(node.id, { userResized: true });
+    void updateNodeFromClient(node.id, { data: { userResized: true } });
+    persistLayout();
+  }, [node.id]);
 
   const startResize = useNodeResize({
     nodeId: node.id,
@@ -278,35 +287,20 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
           </button>
           {/* Open as site — full-page standalone view of this node's surface,
               served from /api/canvas/surface/:id (same document as the canvas
-              iframe). Covers html, web-artifact/ext-app/url mcp-apps,
-              json-render/graph, and webpage nodes. */}
+              iframe). Opens via the system browser so embedded hosts do not trap
+              it in their own webview. */}
           {canOpenAsSite(node) && (
             <button
               type="button"
               onClick={(e) => {
                 e.stopPropagation();
-                openNodeAsSite(node);
+                void openNodeAsSite(node);
               }}
-              title="Open as site (new tab)"
+              title="Open as site"
             >
               ↗
             </button>
           )}
-          {/* Open in the real system browser (for hosts whose embedded browser
-              makes a normal new tab feel in-place, e.g. Codex). Falls back to a
-              new tab when the server can't launch the OS browser. */}
-          {canOpenAsSite(node) && (
-            <button
-              type="button"
-              onClick={(e) => {
-                e.stopPropagation();
-                void openNodeInSystemBrowser(node);
-              }}
-              title="Open in system browser"
-            >
-              ⤤
-            </button>
-          )}
           {/* Expand — opens node as full-viewport overlay for focused work */}
           {EXPANDABLE_TYPES.has(node.type) && (
             <button

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -8,7 +8,7 @@ import { StatusNode } from '../nodes/StatusNode';
 import { ImageNode } from '../nodes/ImageNode';
 import { WebpageNode } from '../nodes/WebpageNode';
 import { HtmlNode, shouldShowPresentationControls } from '../nodes/HtmlNode';
-import { canOpenAsSite, openNodeAsSite, openNodeInSystemBrowser } from '../nodes/surface-url';
+import { canOpenAsSite, openNodeAsSite } from '../nodes/surface-url';
 import { PromptNode } from '../nodes/PromptNode';
 import { ResponseNode } from '../nodes/ResponseNode';
 import { TraceNode } from '../nodes/TraceNode';
@@ -308,24 +308,13 @@ export function ExpandedNodeOverlay() {
               <button
                 type="button"
                 class="expanded-action-btn"
-                onClick={() => openNodeAsSite(node)}
-                title="Open as a full-page site in a new tab"
+                onClick={() => void openNodeAsSite(node)}
+                title="Open as a full-page site in the system browser"
               >
                 Open as site
               </button>
             )}
 
-            {canOpenAsSite(node) && (
-              <button
-                type="button"
-                class="expanded-action-btn"
-                onClick={() => void openNodeInSystemBrowser(node)}
-                title="Open in the system browser (e.g. Chrome) — useful when the host browser opens tabs in-place"
-              >
-                Open in system browser
-              </button>
-            )}
-
             {canPresent && (
               <button
                 type="button"

package/src/client/canvas/auto-fit.ts

@@ -2,24 +2,78 @@ import type { CanvasNodeState } from '../types';
 
 export const AUTO_FIT_TITLEBAR_HEIGHT = 37;
 export const AUTO_FIT_MAX_HEIGHT = 600;
+// Iframe surfaces (charts/dashboards/rich html) can legitimately need more room
+// than a text node, so they grow to a higher ceiling before scrolling.
+export const AUTO_FIT_MAX_HEIGHT_IFRAME = 1400;
+// `.node-body` adds 12px padding top+bottom around an iframe surface (global.css).
+// The bridge reports the iframe's OWN document scrollHeight, so the grow target
+// must add titlebar + this body padding or the node settles ~24px short and the
+// surface shows a residual inner scrollbar. (The DOM auto-fit above doesn't need
+// this: body.scrollHeight already includes the body's padding.)
+export const AUTO_FIT_BODY_PADDING = 24;
 
-function isExtAppNode(node: CanvasNodeState): boolean {
-  return node.type === 'mcp-app' && node.data.mode === 'ext-app';
+/** Node types the DOM auto-fit can't measure: iframe-backed surfaces (html/
+ *  json-render/graph/mcp-app), where the body's scrollHeight equals the iframe
+ *  height (circular), and webpage (its card uses a bounded flex/overflow layout,
+ *  so auto-fit was already a no-op). Iframe surfaces are sized by the content-
+ *  height bridge (use-iframe-content-height) instead; webpage intentionally
+ *  scrolls. Excluding them from the DOM path is behaviour-neutral. */
+function isIframeNode(node: CanvasNodeState): boolean {
+  return node.type === 'html'
+    || node.type === 'json-render'
+    || node.type === 'graph'
+    || node.type === 'mcp-app'
+    || node.type === 'webpage';
 }
 
-function hasExplicitStructuredFrame(node: CanvasNodeState): boolean {
-  return node.type === 'graph' || node.type === 'json-render';
+/** Authored iframe surfaces whose content has a bounded natural height — they may
+ *  grow to fit it. Excludes presentation decks, hosted ext-apps, and URL/webpage
+ *  viewers (unbounded/scrolling content that must not drive node height). */
+function isContentFitSurface(node: CanvasNodeState): boolean {
+  if (node.type === 'html') return node.data.presentation !== true;
+  if (node.type === 'json-render' || node.type === 'graph') return true;
+  if (node.type === 'mcp-app') return node.data.viewerType === 'web-artifact';
+  return false;
 }
 
-function isPresentationHtmlNode(node: CanvasNodeState): boolean {
-  return node.type === 'html' && node.data.presentation === true;
+/** Shared exemptions: never auto-size a node the user/agent has fixed or a node
+ *  whose height is controlled elsewhere. */
+function isAutoSizeExempt(node: CanvasNodeState): boolean {
+  return node.collapsed === true
+    || node.dockPosition != null
+    || node.data.strictSize === true
+    || node.data.userResized === true
+    || node.type === 'group';
 }
 
+/** DOM-content nodes (markdown/status/file/…) whose body scrollHeight is directly
+ *  measurable — the one-shot ResizeObserver auto-fit in CanvasNode handles these. */
 export function shouldAutoFitNode(node: CanvasNodeState): boolean {
-  return !node.collapsed && !node.dockPosition && node.data.strictSize !== true && node.type !== 'group' && !isExtAppNode(node) && !hasExplicitStructuredFrame(node) && !isPresentationHtmlNode(node);
+  return !isAutoSizeExempt(node) && !isIframeNode(node);
 }
 
 export function computeAutoFitHeight(node: CanvasNodeState, contentHeight: number): number | null {
   if (!shouldAutoFitNode(node) || contentHeight <= 0) return null;
   return Math.min(contentHeight + AUTO_FIT_TITLEBAR_HEIGHT, AUTO_FIT_MAX_HEIGHT);
 }
+
+/** Iframe surfaces that should GROW to fit their reported content height. */
+export function shouldContentFitIframeNode(node: CanvasNodeState): boolean {
+  return isContentFitSurface(node) && !isAutoSizeExempt(node);
+}
+
+/**
+ * Grow-only target height from a surface-reported content height. Returns null
+ * when the node is exempt, the report is non-positive, or the node already fits
+ * (so it never shrinks — monotonic growth can't oscillate). Adds the titlebar +
+ * node-body padding so the content fully clears (no residual inner scrollbar),
+ * capped at the iframe ceiling.
+ */
+export function computeContentGrowHeight(node: CanvasNodeState, contentHeight: number): number | null {
+  if (!shouldContentFitIframeNode(node) || contentHeight <= 0) return null;
+  const want = Math.min(
+    contentHeight + AUTO_FIT_TITLEBAR_HEIGHT + AUTO_FIT_BODY_PADDING,
+    AUTO_FIT_MAX_HEIGHT_IFRAME,
+  );
+  return want > node.size.height + 8 ? want : null;
+}

package/src/client/nodes/HtmlNode.tsx

@@ -4,6 +4,7 @@ import { submitAxInteractionFromClient } from '../state/intent-bridge';
 import { showToast } from '../state/attention-bridge';
 import type { CanvasNodeState } from '../types';
 import { nodeSurfaceUrl, surfaceContentHash } from './surface-url';
+import { useIframeContentHeight } from './use-iframe-content-height';
 
 export function shouldShowPresentationControls(node: CanvasNodeState): boolean {
   return node.type === 'html' && node.data.presentation === true;
@@ -22,6 +23,8 @@ export function HtmlNode({
   const themeToken = useMemo(() => `theme-${crypto.randomUUID()}`, []);
   // Per-mount nonce authorizing iframe → parent AX emits (Phase 3 HTML bridge).
   const axToken = useMemo(() => `ax-${crypto.randomUUID()}`, []);
+  // Per-mount nonce for the content-height reporter (node grows to fit content).
+  const frameToken = useMemo(() => `frame-${crypto.randomUUID()}`, []);
   const html = typeof node.data.html === 'string'
     ? node.data.html
     : typeof node.data.content === 'string'
@@ -36,11 +39,15 @@ export function HtmlNode({
   // itself changes.
   const surfaceSrc = useMemo(
     () => (html
-      ? nodeSurfaceUrl(node.id, { theme, themeToken, present: presentation, presentToken: presentationExitToken, v, axToken })
+      ? nodeSurfaceUrl(node.id, { theme, themeToken, present: presentation, presentToken: presentationExitToken, v, axToken, frameToken })
       : ''),
-    [html, presentation, presentationExitToken, themeToken, v, node.id, axToken],
+    [html, presentation, presentationExitToken, themeToken, v, node.id, axToken, frameToken],
   );
 
+  // Grow the node to fit the surface's reported content height (grow-only, gated).
+  // Never in the expanded overlay — there the surface fills the large overlay frame.
+  useIframeContentHeight(node, iframeRef, expanded ? '' : frameToken);
+
   // Phase 3 HTML bridge: receive window.PMX_AX.emit(...) messages from the
   // sandboxed iframe, validate the nonce + node id, and submit the interaction
   // through the capability-gated endpoint (the server re-validates capabilities).

package/src/client/nodes/McpAppNode.tsx

@@ -1,11 +1,21 @@
 import { useEffect, useMemo, useRef } from 'preact/hooks';
 import type { CanvasNodeState } from '../types';
 import { axSurfaceState, canvasTheme } from '../state/canvas-store';
+import { shouldContentFitIframeNode } from '../canvas/auto-fit';
 import { submitAxInteractionFromClient } from '../state/intent-bridge';
 import { showToast } from '../state/attention-bridge';
 import { ExtAppFrame } from './ExtAppFrame';
+import { useIframeContentHeight } from './use-iframe-content-height';
 
-function withViewerParams(url: string, expanded: boolean, specVersion?: number, axToken?: string, axNodeId?: string): string {
+function withViewerParams(
+  url: string,
+  expanded: boolean,
+  specVersion?: number,
+  axToken?: string,
+  axNodeId?: string,
+  frameToken?: string,
+  fitContent?: boolean,
+): string {
   if (!url) return url;
   try {
     const resolved = new URL(url, window.location.origin);
@@ -16,9 +26,12 @@ function withViewerParams(url: string, expanded: boolean, specVersion?: number,
     if (typeof specVersion === 'number') resolved.searchParams.set('v', String(specVersion));
     // AX bridge nonce for json-render/graph + web-artifact viewer nodes.
     if (axToken) resolved.searchParams.set('axToken', axToken);
-    // The /artifact route needs the node id to inject the AX bridge (the json-render
-    // view route already gets nodeId from its own query param).
+    // The /artifact route needs the node id to inject the AX/content bridges (the
+    // json-render view route already gets nodeId from its own query param).
     if (axNodeId) resolved.searchParams.set('axNodeId', axNodeId);
+    // Content-fit: report natural height (charts render intrinsic) so the node grows.
+    if (frameToken) resolved.searchParams.set('frameToken', frameToken);
+    if (fitContent) resolved.searchParams.set('fit', 'content');
     return resolved.toString();
   } catch {
     return url;
@@ -59,6 +72,14 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
   const isAxViewer = (isJsonViewer || isWebArtifact) && axOn;
   const axSurface: 'json-render' | 'mcp-app' = isWebArtifact ? 'mcp-app' : 'json-render';
   const axToken = useMemo(() => (isAxViewer ? `ax-${crypto.randomUUID()}` : ''), [isAxViewer]);
+  // Content-fit: grow the node to the viewer's natural height (charts render
+  // intrinsic via fit=content). Gated by shouldContentFitIframeNode (json-render /
+  // graph / web-artifact, unless strictSize / user-resized / docked / collapsed).
+  // NEVER in the expanded overlay — there the chart must stretch to fill the large
+  // overlay frame (fill-down), not sit at its intrinsic in-canvas height.
+  const contentFit = shouldContentFitIframeNode(node) && !expanded;
+  const frameToken = useMemo(() => (contentFit ? `frame-${crypto.randomUUID()}` : ''), [contentFit]);
+  useIframeContentHeight(node, iframeRef, frameToken);
 
   // Receive AX emits forwarded by the json-render viewer; validate (bound to this
   // node's iframe + nonce + node id) and submit through the capability-gated
@@ -105,7 +126,15 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
   useEffect(pushAxState, [isAxViewer, axToken, axStateValue]);
 
   const specVersion = typeof node.data.specVersion === 'number' ? node.data.specVersion : undefined;
-  const url = withViewerParams((node.data.url as string) || '', expanded, specVersion, axToken || undefined, isAxViewer ? node.id : undefined);
+  const url = withViewerParams(
+    (node.data.url as string) || '',
+    expanded,
+    specVersion,
+    axToken || undefined,
+    isAxViewer ? node.id : undefined,
+    frameToken || undefined,
+    contentFit,
+  );
   const sourceServer = (node.data.sourceServer as string) || '';
   const hostMode = (node.data.hostMode as string) || 'hosted';
   const fallbackReason = node.data.fallbackReason as string | undefined;

package/src/client/nodes/surface-url.ts

@@ -24,6 +24,8 @@ export interface SurfaceUrlOptions {
   v?: string;
   /** Nonce authorizing iframe → parent AX emits (html bridge). */
   axToken?: string;
+  /** Nonce for the content-height reporter (node grows to fit content). */
+  frameToken?: string;
 }
 
 /** Build the stable per-node surface URL (/api/canvas/surface/:id) the iframe and "Open as site" both use. */
@@ -35,6 +37,7 @@ export function nodeSurfaceUrl(nodeId: string, opts: SurfaceUrlOptions = {}): st
   if (opts.presentToken) params.set('presentToken', opts.presentToken);
   if (opts.v) params.set('v', opts.v);
   if (opts.axToken) params.set('axToken', opts.axToken);
+  if (opts.frameToken) params.set('frameToken', opts.frameToken);
   return `/api/canvas/surface/${encodeURIComponent(nodeId)}?${params.toString()}`;
 }
 
@@ -43,18 +46,13 @@ export function canOpenAsSite(node: CanvasNodeState): boolean {
   return canOpenNodeAsSurface(node.type, node.data as Record<string, unknown>);
 }
 
-/** Open the node's surface in a new browser tab. */
-export function openNodeAsSite(node: CanvasNodeState): void {
-  window.open(nodeSurfaceUrl(node.id), '_blank', 'noopener');
-}
-
 /**
- * Open the node's surface in the user's real SYSTEM browser via the server's OS
- * launcher — for hosts (e.g. Codex) whose embedded browser makes a normal
- * `_blank` tab feel in-place. Falls back to a normal new-tab open when the server
- * can't launch (headless / PMX_CANVAS_DISABLE_BROWSER_OPEN).
+ * Open the node's standalone surface in the user's system browser. Falls back to
+ * `window.open` when the server cannot launch a browser, preserving in-browser tests
+ * and headless/disabled-browser environments.
  */
-export async function openNodeInSystemBrowser(node: CanvasNodeState): Promise<void> {
-  const res = await openNodeInSystemBrowserRequest(node.id);
-  if (!res.opened) openNodeAsSite(node);
+export async function openNodeAsSite(node: CanvasNodeState): Promise<void> {
+  const url = nodeSurfaceUrl(node.id);
+  const res = await openNodeInSystemBrowserRequest(node.id, url);
+  if (!res.opened) window.open(url, '_blank', 'noopener');
 }

package/src/client/nodes/use-iframe-content-height.ts

@@ -0,0 +1,53 @@
+import { useEffect, useRef } from 'preact/hooks';
+import { persistLayout, resizeNode } from '../state/canvas-store';
+import { computeContentGrowHeight } from '../canvas/auto-fit';
+import type { CanvasNodeState } from '../types';
+
+/**
+ * Grow an iframe-surface node to fit the content height its surface reports over
+ * the nonce-validated `content-height` postMessage bridge. Grow-only and gated
+ * (see computeContentGrowHeight / shouldContentFitIframeNode), so it never clips,
+ * never shrinks, never fights a manual resize / strictSize / docked node, and —
+ * because growth is monotonic with a dead-band — cannot oscillate. This is the
+ * fix for iframe nodes whose body scrollHeight the parent can't measure.
+ *
+ * The latest node is read through a ref so the effect stays mounted across the
+ * grow (its deps are only id + token). Putting node.size in the deps would re-run
+ * the effect on each grow and its cleanup would cancel the pending persist.
+ */
+export function useIframeContentHeight(
+  node: CanvasNodeState,
+  iframeRef: { current: HTMLIFrameElement | null },
+  frameToken: string,
+): void {
+  const nodeRef = useRef(node);
+  nodeRef.current = node;
+  const persistTimer = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (!frameToken) return undefined;
+    function onMessage(event: MessageEvent) {
+      if (event.source !== iframeRef.current?.contentWindow) return;
+      const d = event.data as { source?: string; type?: string; token?: string; height?: unknown } | null;
+      if (!d || d.source !== 'pmx-canvas-frame' || d.type !== 'content-height' || d.token !== frameToken) return;
+      const current = nodeRef.current;
+      const reported = typeof d.height === 'number' ? d.height : 0;
+      const target = computeContentGrowHeight(current, reported);
+      if (target === null) return;
+      resizeNode(current.id, { width: current.size.width, height: target });
+      if (persistTimer.current !== null) window.clearTimeout(persistTimer.current);
+      persistTimer.current = window.setTimeout(() => {
+        persistLayout({ recordHistory: false });
+        persistTimer.current = null;
+      }, 300);
+    }
+    window.addEventListener('message', onMessage);
+    return () => {
+      window.removeEventListener('message', onMessage);
+      if (persistTimer.current !== null) {
+        window.clearTimeout(persistTimer.current);
+        persistTimer.current = null;
+      }
+    };
+  }, [node.id, frameToken]);
+}

package/src/client/state/intent-bridge.ts

@@ -261,7 +261,7 @@ export async function fetchAxSurfaceState(): Promise<unknown> {
 }
 
 /** Ask the server to open a node's surface in the system browser. */
-export async function openNodeInSystemBrowserRequest(nodeId: string): Promise<{ ok: boolean; opened: boolean }> {
+export async function openNodeInSystemBrowserRequest(nodeId: string, url?: string): Promise<{ ok: boolean; opened: boolean }> {
   return requestJson<{ ok: boolean; opened: boolean }>(
     'openNodeInSystemBrowserRequest',
     '/api/canvas/open-external',
@@ -269,7 +269,7 @@ export async function openNodeInSystemBrowserRequest(nodeId: string): Promise<{
     {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ nodeId }),
+      body: JSON.stringify({ nodeId, url }),
     },
   );
 }

package/src/json-render/charts/components.tsx

@@ -155,9 +155,19 @@ export function useChartFrameHeight(explicitHeight: number | null | undefined, f
     };
   }, [explicitHeight]);
 
+  // Content-fit mode (node grows to fit, set by the viewer when fit=content): the
+  // chart takes its INTRINSIC height — explicit, or the fallback — independent of
+  // the node/viewport height. That makes the document's scrollHeight stable so the
+  // node can grow to it once and converge (no fill-down feedback loop). When NOT in
+  // content-fit (strictSize / user-resized nodes), it fills the frame down as before.
+  const fitContent = typeof window !== 'undefined'
+    && (window as { __PMX_CANVAS_FIT_CONTENT__?: boolean }).__PMX_CANVAS_FIT_CONTENT__ === true;
+  const height = fitContent
+    ? (typeof explicitHeight === 'number' ? explicitHeight : fallbackHeight)
+    : (typeof explicitHeight === 'number' ? Math.min(explicitHeight, autoHeight) : autoHeight);
   return {
     frameRef,
-    height: typeof explicitHeight === 'number' ? Math.min(explicitHeight, autoHeight) : autoHeight,
+    height,
     width: autoWidth,
   };
 }