From a9cf4d9378fde68b061e9c6f3476a89a4b96fe1f Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Sat, 11 Jul 2026 15:41:36 +0200
Subject: [PATCH] fix(agent): preserve preview backgrounds across breakpoints

---
 docs/features/agent.md                        |   6 +-
 docs/features/canvas-iframe-per-frame.md      |  16 +-
 server/ai/tools/site/writeTools.ts            |   2 +-
 .../agent/agentBreakpointCapture.test.tsx     | 546 ++++++++++++++++++
 src/__tests__/agent/renderEvidence.test.ts    | 312 +++++++++-
 src/__tests__/base-modules.test.ts            |  77 ++-
 .../canvas/bodyPresentation.test.tsx          | 359 ++++++++++++
 .../canvas/canvasPreviewReadiness.test.ts     |  64 ++
 .../media/hooks/useCmsMediaAssetByPath.ts     |  10 +-
 src/admin/pages/site/agent/executor.ts        |   4 +-
 src/admin/pages/site/agent/index.ts           |   8 +-
 src/admin/pages/site/agent/renderEvidence.ts  | 286 +++++++--
 .../site/agent/renderSnapshotAtBreakpoint.ts  |  83 +++
 .../pages/site/agent/renderSnapshotTool.ts    |   2 +
 .../site/canvas/AgentSnapshotFrame.module.css |   8 +
 .../pages/site/canvas/AgentSnapshotFrame.tsx  | 234 ++++++++
 .../pages/site/canvas/CanvasComposedTree.tsx  |  71 ++-
 src/admin/pages/site/canvas/CanvasContexts.ts |   4 +
 .../site/canvas/CanvasPreviewReadiness.ts     |  63 ++
 src/admin/pages/site/canvas/CanvasRoot.tsx    |  21 +-
 .../pages/site/canvas/IframeFrameSurface.tsx  |  72 ++-
 .../site/canvas/iframeBodyPresentation.ts     | 117 ++++
 .../pages/site/canvas/iframeBodyReset.ts      |  18 +-
 .../pages/site/canvas/useLoopPreviewItems.ts  |  16 +-
 .../site/hooks/useTemplatePreviewContext.ts   |  35 +-
 .../pages/site/preview/PreviewOverlay.tsx     |   2 +-
 .../pages/site/store/slices/canvasSlice.ts    |  19 +
 src/modules/base/body/BodyEditor.tsx          |  84 +--
 src/modules/base/body/index.ts                |   5 +-
 29 files changed, 2371 insertions(+), 173 deletions(-)
 create mode 100644 src/__tests__/agent/agentBreakpointCapture.test.tsx
 create mode 100644 src/__tests__/canvas/bodyPresentation.test.tsx
 create mode 100644 src/__tests__/canvas/canvasPreviewReadiness.test.ts
 create mode 100644 src/admin/pages/site/agent/renderSnapshotAtBreakpoint.ts
 create mode 100644 src/admin/pages/site/canvas/AgentSnapshotFrame.module.css
 create mode 100644 src/admin/pages/site/canvas/AgentSnapshotFrame.tsx
 create mode 100644 src/admin/pages/site/canvas/CanvasPreviewReadiness.ts
 create mode 100644 src/admin/pages/site/canvas/iframeBodyPresentation.ts

diff --git a/docs/features/agent.md b/docs/features/agent.md
index 46d32aa68..07e25e855 100644
--- a/docs/features/agent.md
+++ b/docs/features/agent.md
@@ -497,7 +497,7 @@ The agent works **design-system-first**: it establishes or reuses tokens, then r
 
 | Tool              | Input                 | Success `data` | What it does                                                     |
 |-------------------|-----------------------|----------------|------------------------------------------------------------------|
-| `site_render_snapshot` | `{ breakpointId?, nodeId? }`   | `{ breakpointId, nodeId?, label, width, capturedAt, layout, screenshot }` + optional `images[]` | Inspect the rendered canvas: always returns a layout report (viewport, per-node bounding boxes, overflow / broken-image / invisible warnings); when the active provider supports native image-bearing tool results, a PNG is attached via the tool-output **image channel**. `breakpointId` picks the frame (defaults to active); `nodeId` scopes the capture to that node's subtree — image and report cover only that section, with coordinates relative to its box, and the report carries the same `nodeId`. Omit `nodeId` for the whole page; an unknown `nodeId` returns an `aiToolError` |
+| `site_render_snapshot` | `{ breakpointId?, nodeId? }`   | `{ breakpointId, nodeId?, label, width, capturedAt, layout, screenshot }` + optional `images[]` | Inspect the rendered canvas: always returns a layout report (viewport, per-node bounding boxes, overflow / broken-image / invisible warnings); when the active provider supports native image-bearing tool results, a PNG is attached via the tool-output **image channel**. `breakpointId` picks any configured viewport at its exact configured width (defaults to active). Evidence always renders through a deterministic one-shot frame, so Live mode, collapsed frames, and `previewFrame:false` do not change the result or the user's visible canvas state. `nodeId` crops the rendered document to a smaller, sharper model image while preserving HTML/body/ancestor paint; the report covers the same section with coordinates relative to its box. Unknown breakpoint/node ids return `aiToolError` |
 
 ### Auto-navigation
 
@@ -550,6 +550,10 @@ The content system prompt is markdown-native: it tells the model to exchange bod
 4. **`site_read_document` is cleaned and paged before it reaches the model.** `renderAgentDocument` strips pathological strings from the broad read surface: long base64/data URLs become `data:<mime>;base64,[omitted N chars]`, and very long URLs are middle-truncated. The returned object always includes `pageInfo` with `part`, `totalParts`, `nextPart`, `ranges`, `serializedChars`, and cleanup counts. The hard budget is measured against `JSON.stringify({ html, css, pageInfo }).length`, because that is the text providers receive as the tool result. If `nextPart` is not `null`, the agent calls `site_read_document({ document, part: nextPart })` to continue. For exact node-level markup, use the `uid` with `site_get_node_html`.
 5. **Stale evidence is elided.** Within one tool loop, only the **most recent** heavy result per tool name (`site_render_snapshot`, `site_read_document`, `site_get_node_html`, or anything with an image) is replayed at full fidelity; earlier ones are rewritten to a one-line breadcrumb (`"Earlier <tool> output removed… Call <tool> again…"`). Older snapshots describe page state the model has since mutated, so they carry no value. See `applyHeavyElision` in `server/ai/drivers/http/toolLoop.ts`.
 
+Snapshot pixels come from the iframe document's authored rendering. Full-page captures rasterise `<html>` at the exact iframe viewport width and full document height, so a narrow/transformed body cannot shrink the reported viewport or omit document gutters. Node-scoped captures rasterise that same document painting context and crop to the node rectangle, so transparent sections retain HTML/body/ancestor colors, gradients, and background images. A white browser-default fallback is composited only behind pixels the authored page leaves transparent — it is never written onto the cloned document.
+
+Every request uses `AgentSnapshotFrame`, an offscreen one-shot `IframeFrameSurface` at the configured width. Before it becomes capturable, a revisioned barrier waits for template preview rows, nested loop data, media metadata, web fonts, the resulting React commit, and a quiet DOM window. Readiness lives on the host iframe, never on authored `<html>`/`<body>`, so user attribute selectors cannot distinguish Agent evidence from the published page. Lazy `<img>` resources are left authored as-is; `html-to-image` makes its private clones eager and embeds image/background resources before `toCanvas()` resolves. The frame deliberately does not execute authored runtime scripts, and it is released after capture without changing `activeBreakpointId`, `canvasView`, or collapsed-frame state. Parallel requests are serialized so they cannot replace the single transient frame mid-capture.
+
 ---
 
 ## System prompt
diff --git a/docs/features/canvas-iframe-per-frame.md b/docs/features/canvas-iframe-per-frame.md
index f5665b639..201ea3355 100644
--- a/docs/features/canvas-iframe-per-frame.md
+++ b/docs/features/canvas-iframe-per-frame.md
@@ -8,9 +8,10 @@ Each viewport frame runs in its own `<iframe>` with its own `<html><body>`. The
 
 ## TL;DR
 
-- `IframeFrameSurface` is the iframe primitive. It boots from an empty `srcDoc`, captures the iframe document, and mounts children via `createPortal(tree, iframeDoc.body)`.
+- `IframeFrameSurface` is the iframe primitive. It boots from a sentinel-tagged empty `srcDoc`, ignores the browser's short-lived initial `about:blank` document, and mounts children once via `createPortal(tree, iframeDoc.body)` only after the final document is ready. `CanvasDocumentContext` exposes that document to body ownership/evidence helpers without inserting probe elements into authored DOM.
 - **Design mode** renders one `IframeFrameSurface` per framed viewport context inside `CanvasTransformLayer` (pan/zoom). All frames mount as soon as the page document is in the store — the tree is already in memory, so there is nothing to stagger; `CanvasTransformLayer` renders skeleton frames only while the document itself hasn't loaded yet (`page === null`). **Live mode** renders a single real-size `IframeFrameSurface` inside `CanvasLiveSurface` (normal scroll).
 - Both modes are fully editable — click-to-select, properties panel, structural edits all work. Neither is a read-only preview.
+- Agent evidence can request any configured viewport. Each capture renders once through an offscreen `AgentSnapshotFrame` at the configured width, then removes it without changing the visible canvas state.
 - CSS arrives in each iframe via three injectors: `EditorChromeInjector` (unlayered), `ClassStyleInjector` (`@layer user-authored`), `UserStylesheetInjector` (`@layer user-authored`).
 - Wheel, pointer, and keyboard events are forwarded from inside the iframe to the parent's gesture / reorder-drag / shortcut handlers. `Tab` is blocked to prevent tab-walking inside the design preview.
 - Plugin canvas modules use a separate, sandboxed `ModuleSandboxFrame` (not `IframeFrameSurface`).
@@ -74,6 +75,18 @@ Frames mount as soon as the page document is in the store. The node tree is alre
 
 The active viewport context (highlighted, drives style override routing) is tracked by `activeBreakpointId` in `canvasSlice`.
 
+### Agent evidence frames
+
+`site_render_snapshot` always asks `CanvasRoot` to mount one `AgentSnapshotFrame` through a portal outside the canvas clipping/transform layers. It uses the same `IframeFrameSurface`, `CanvasComposedTree`, breakpoint context, class CSS, and user stylesheet path as the editor, at the breakpoint's configured width. A deterministic transient path avoids capturing a visible frame midway through an asynchronous preview fetch and makes Live/collapsed/disabled-frame state irrelevant. The frame sits offscreen rather than using `display:none`, so it has real layout geometry for evidence collection.
+
+This frame is transient editor-session state. It does not change the active viewport, Design/Live mode, pan/zoom, or collapsed frame ids, and it never runs authored runtime scripts (a read must not duplicate arbitrary side effects or network calls). A revisioned readiness tracker covers post-type preview rows, loop data, and media metadata; capture additionally waits for fonts, React/DOM settling, and cloned image/background embedding. The request-specific marker is stored on the host iframe rather than authored DOM. The executor captures only after that marker appears and releases the request in `finally`. Explicit breakpoint lookup is exact; it never substitutes another frame.
+
+### Body presentation and snapshot paint
+
+The iframe's real `<body>` owns the root node's classes, inline styles, and sanitized authored HTML attributes, matching the publisher's `<body class="…" style="…" data-…>`. `applyIframeBodyPresentation` is shared by the editable `base.body` component and template composition, where the outermost wrapper body owns the published body. Both consume `CanvasDocumentContext` and render no editor-only probe child, so `body > :first-child`, `:nth-child`, sibling, and `:empty` selectors see the published structure. The helper restores only the declarations/attributes it touched; design-frame height/overflow declarations remain owned by the grow-to-content reset, while Live keeps authored body sizing exactly as published.
+
+Agent screenshots preserve the complete document paint. A full capture rasterises `<html>` at the exact iframe viewport width and full document height; a node-scoped capture rasterises the same HTML/body/ancestor context and crops it to the target rectangle instead of detaching the transparent subtree. The raster fallback is composited behind the finished page pixels, so it cannot overwrite authored colors, gradients, or background images.
+
 **Initial centering on load and document switch.** The transform layer always starts at pan `(0, 0)`, which places the leftmost (narrowest) frame at the top-left. On first load and whenever the active document changes (page switch, entering/leaving a Visual Component), `CanvasRoot` runs a `useEffect` keyed on `canvasPage.id` that calls `useCanvas().centerOnBreakpointFrame` to pan the canvas so the active breakpoint frame is horizontally centered and its top sits just below the viewport top. The geometry is computed by `panToCenterBreakpointFrame` in `canvasDomGeometry.ts`. The effect retries on a short `setTimeout` loop (not `requestAnimationFrame`, which is skipped for backgrounded tabs) until the iframe-backed frames have real layout geometry. The current zoom is preserved; only the pan changes. Breakpoint switches within the same document (toolbar, node clicks) do not re-center — the designer keeps their place. See [docs/features/editor-preferences.md](editor-preferences.md) for how the `defaultBreakpoint` preference plugs into this.
 
 ### Viewport Activation UX
@@ -198,6 +211,7 @@ Tests that render the canvas and query nodes must use the `iframeCanvasQuery.ts`
 - Source-of-truth files:
   - `src/admin/pages/site/canvas/IframeFrameSurface.tsx` — iframe primitive
   - `src/admin/pages/site/canvas/CanvasLiveSurface.tsx` — live mode surface
+  - `src/admin/pages/site/canvas/AgentSnapshotFrame.tsx` — one-shot offscreen frame for exact Agent breakpoint evidence
   - `src/admin/pages/site/canvas/BreakpointFrame.tsx` — design mode per-viewport frame
   - `src/admin/pages/site/canvas/CanvasTransformLayer.tsx` — design mode pan/zoom container; renders all frames once the document loads, skeleton frames while it hasn't
   - `src/admin/shared/CanvasFrameSkeleton/CanvasFrameSkeleton.tsx` — shared frame skeleton for the document-loading / startup states
diff --git a/server/ai/tools/site/writeTools.ts b/server/ai/tools/site/writeTools.ts
index 212b67cbe..26faeb373 100644
--- a/server/ai/tools/site/writeTools.ts
+++ b/server/ai/tools/site/writeTools.ts
@@ -400,7 +400,7 @@ const renderSnapshotTool: AiTool = {
   scope: 'site',
   execution: 'browser',
   description:
-    "Inspect the rendered canvas. Returns a layout report: viewport size, per-node bounding boxes, image-load status, and warnings (overflow / broken-image / invisible-node) — enough to catch most layout bugs in text. When the active provider supports native image-bearing tool results, a screenshot is also attached as an image. Pass `breakpointId` to choose which breakpoint frame (defaults to active). Pass `nodeId` to capture just that node's subtree — a sharper, cheaper image than the whole page, and a report scoped to that section with coordinates relative to the node; omit `nodeId` to capture the full page.",
+    "Inspect the rendered canvas. Returns a layout report: viewport size, per-node bounding boxes, image-load status, and warnings (overflow / broken-image / invisible-node) — enough to catch most layout bugs in text. When the active provider supports native image-bearing tool results, a screenshot is also attached as an image. Pass any configured `breakpointId` to render a readiness-aware one-shot frame at that exact configured width, independent of collapsed/disabled frames or the viewport active in Live mode (defaults to active; unknown ids error). Pass `nodeId` to crop the document rendering to that node while preserving its HTML/body/ancestor background — a smaller, sharper model image with a report scoped to that section and coordinates relative to the node; omit `nodeId` to capture the full page.",
   inputSchema: RenderSnapshotInputSchema,
 }
 
diff --git a/src/__tests__/agent/agentBreakpointCapture.test.tsx b/src/__tests__/agent/agentBreakpointCapture.test.tsx
new file mode 100644
index 000000000..b3165ebb3
--- /dev/null
+++ b/src/__tests__/agent/agentBreakpointCapture.test.tsx
@@ -0,0 +1,546 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import type { AiToolOutput } from '@core/ai'
+import { DEFAULT_BREAKPOINTS, type Breakpoint } from '@core/page-tree'
+import { DEFAULT_MODULE_INSERTER_PREFERENCE } from '@core/persistence/userPreferences'
+import {
+  executeAgentTool,
+  findAgentRenderFrame,
+  waitForAgentRenderFrame,
+} from '@site/agent'
+import { CanvasRoot } from '@site/canvas/CanvasRoot'
+import { useEditorStore } from '@site/store/store'
+import { __resetModuleInserterPreferenceForTests } from '@site/module-picker/useModuleInserterPreference'
+import { makeNode, makePage, makeSite } from '../fixtures'
+import '@modules/base'
+
+const originalFetch = globalThis.fetch
+
+const BREAKPOINTS: Breakpoint[] = DEFAULT_BREAKPOINTS.map((breakpoint) => ({
+  ...breakpoint,
+  previewFrame: breakpoint.id !== 'mobile',
+}))
+
+const POSTS_TABLE = {
+  id: 'posts',
+  name: 'Posts',
+  slug: 'posts',
+  kind: 'postType',
+  routeBase: '/posts',
+  singularLabel: 'Post',
+  pluralLabel: 'Posts',
+  primaryFieldId: 'title',
+  fields: [
+    { type: 'text', id: 'title', label: 'Title', required: true, builtIn: true },
+  ],
+  system: true,
+  rowCount: 1,
+  createdByUserId: null,
+  updatedByUserId: null,
+  createdAt: '2026-07-11T10:00:00.000Z',
+  updatedAt: '2026-07-11T10:00:00.000Z',
+}
+
+function deferred() {
+  let resolve!: () => void
+  const promise = new Promise<void>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
+function jsonResponse(value: unknown): Response {
+  return new Response(JSON.stringify(value), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+beforeEach(() => {
+  cleanup()
+  document.body.replaceChildren()
+  __resetModuleInserterPreferenceForTests()
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    const url = typeof input === 'string' ? input : input.toString()
+    if (url.includes('/admin/api/cms/me/preferences/module-inserter')) {
+      return new Response(JSON.stringify({ value: DEFAULT_MODULE_INSERTER_PREFERENCE }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+    return new Response('', { status: 404 })
+  }) as typeof globalThis.fetch
+
+  const page = makePage({
+    id: 'page-1',
+    rootNodeId: 'root',
+    nodes: {
+      root: makeNode({ id: 'root', moduleId: 'base.body', children: ['headline'] }),
+      headline: makeNode({
+        id: 'headline',
+        moduleId: 'base.text',
+        props: { text: 'Breakpoint evidence', tag: 'h1' },
+      }),
+    },
+  })
+  useEditorStore.setState({
+    site: makeSite({ pages: [page], breakpoints: BREAKPOINTS }),
+    activePageId: page.id,
+    activeDocument: null,
+    activeBreakpointId: 'desktop',
+    activeConditionId: null,
+    canvasView: 'live',
+    runScripts: false,
+    collapsedBreakpointIds: ['tablet'],
+    agentSnapshotCaptureRequest: null,
+    selectedNodeId: null,
+    selectedNodeIds: [],
+    hoveredNodeId: null,
+    hoveredBreakpointId: null,
+    previewClassAssignment: null,
+    propertiesPanel: { collapsed: false, x: 0, y: 0, width: 360 },
+    propertiesPanelMode: 'docked',
+    _historyPast: [],
+    _historyFuture: [],
+    canUndo: false,
+    canRedo: false,
+    hasUnsavedChanges: false,
+  } as Parameters<typeof useEditorStore.setState>[0])
+})
+
+afterEach(() => {
+  cleanup()
+  document.body.replaceChildren()
+  globalThis.fetch = originalFetch
+  __resetModuleInserterPreferenceForTests()
+  useEditorStore.setState({
+    agentSnapshotCaptureRequest: null,
+    collapsedBreakpointIds: [],
+    canvasView: 'design',
+    runScripts: false,
+  })
+})
+
+describe('agent breakpoint snapshot capture', () => {
+  it('mounts one exact-width transient frame without runtime scripts', async () => {
+    render(<CanvasRoot />)
+
+    act(() => {
+      useEditorStore.getState().setAgentSnapshotCaptureRequest({
+        requestId: 'manual-mobile-capture',
+        breakpointId: 'mobile',
+      })
+    })
+
+    let frame: HTMLElement | null = null
+    await act(async () => {
+      frame = await waitForAgentRenderFrame({
+        breakpointId: 'mobile',
+        source: 'transient',
+        requestId: 'manual-mobile-capture',
+      })
+    })
+    expect(frame).not.toBeNull()
+    const iframe = frame!.querySelector('iframe')
+    expect(iframe?.style.width).toBe('375px')
+    expect(iframe?.dataset.instaticCanvasDocumentLoaded).toBe('true')
+    expect(iframe?.dataset.agentSnapshotReady).toBe('manual-mobile-capture')
+    expect(iframe?.contentDocument?.documentElement.hasAttribute(
+      'data-instatic-canvas-document',
+    )).toBe(false)
+    expect(iframe?.contentDocument?.querySelector('[data-instatic-canvas-runtime-script]')).toBeNull()
+    expect(iframe?.contentDocument?.body.querySelector('[data-instatic-body-probe]')).toBeNull()
+    expect(iframe?.contentDocument?.body.hasAttribute('data-agent-snapshot-ready')).toBe(false)
+    expect(iframe?.contentDocument?.body.children).toHaveLength(1)
+    expect(iframe?.contentDocument?.body.firstElementChild?.getAttribute('data-node-id')).toBe('headline')
+    expect(findAgentRenderFrame({ breakpointId: 'mobile', source: 'visible' })).toBeNull()
+
+    act(() => useEditorStore.getState().setAgentSnapshotCaptureRequest(null))
+    await waitFor(() => {
+      expect(findAgentRenderFrame({ breakpointId: 'mobile', source: 'transient' })).toBeNull()
+    })
+  })
+
+  it('ignores the initial about:blank portal until the loaded document commits', () => {
+    const requestId = 'replacement-race'
+    const frame = document.createElement('div')
+    frame.dataset.agentSnapshotFrame = ''
+    frame.dataset.agentSnapshotRequestId = requestId
+    frame.dataset.agentSnapshotBreakpointId = 'mobile'
+    const iframe = document.createElement('iframe')
+    frame.appendChild(iframe)
+    document.body.appendChild(frame)
+
+    const initialDocument = document.implementation.createHTMLDocument('initial')
+    initialDocument.body.dataset.breakpointId = 'mobile'
+    initialDocument.body.dataset.agentSnapshotReady = requestId
+    const loadedDocument = document.implementation.createHTMLDocument('loaded')
+    loadedDocument.body.dataset.breakpointId = 'mobile'
+    let currentDocument = initialDocument
+    Object.defineProperty(iframe, 'contentDocument', {
+      configurable: true,
+      get: () => currentDocument,
+    })
+
+    const query = {
+      breakpointId: 'mobile',
+      source: 'transient' as const,
+      requestId,
+      requireReady: true,
+    }
+    expect(findAgentRenderFrame(query)).toBeNull()
+
+    // The srcDoc load replaces the initial document. Its React portal has not
+    // committed yet, so the iframe load marker alone is still insufficient.
+    currentDocument = loadedDocument
+    iframe.dataset.instaticCanvasDocumentLoaded = 'true'
+    expect(findAgentRenderFrame(query)).toBeNull()
+
+    iframe.dataset.agentSnapshotReady = requestId
+    expect(findAgentRenderFrame(query)).toBe(frame)
+  })
+
+  it('captures a frameless breakpoint from live mode without changing visible canvas state', async () => {
+    render(<CanvasRoot />)
+    const before = visibleCanvasState()
+    const requests: string[] = []
+    const unsubscribe = useEditorStore.subscribe((state) => {
+      const breakpointId = state.agentSnapshotCaptureRequest?.breakpointId
+      if (breakpointId) requests.push(breakpointId)
+    })
+
+    let capturePromise!: Promise<AiToolOutput>
+    act(() => {
+      capturePromise = executeAgentTool('site_render_snapshot', {
+        breakpointId: 'mobile',
+        captureScreenshot: false,
+      })
+    })
+    const result = await act(async () => await capturePromise)
+    unsubscribe()
+
+    expect(result.ok).toBe(true)
+    expect(result.data).toMatchObject({ breakpointId: 'mobile' })
+    expect(requests).toContain('mobile')
+    expect(visibleCanvasState()).toEqual(before)
+    expect(useEditorStore.getState().agentSnapshotCaptureRequest).toBeNull()
+  })
+
+  it('does not reuse a live frame clamped below the configured viewport width', async () => {
+    render(<CanvasRoot />)
+    let visibleFrame: HTMLElement | null = null
+    await act(async () => {
+      visibleFrame = await waitForAgentRenderFrame({
+        breakpointId: 'desktop',
+        source: 'visible',
+      })
+    })
+    const iframeWindow = visibleFrame!.querySelector('iframe')!.contentWindow!
+    Object.defineProperty(iframeWindow, 'innerWidth', {
+      configurable: true,
+      value: 800,
+    })
+
+    const requests: string[] = []
+    const unsubscribe = useEditorStore.subscribe((state) => {
+      const breakpointId = state.agentSnapshotCaptureRequest?.breakpointId
+      if (breakpointId) requests.push(breakpointId)
+    })
+    let capturePromise!: Promise<AiToolOutput>
+    act(() => {
+      capturePromise = executeAgentTool('site_render_snapshot', {
+        breakpointId: 'desktop',
+        captureScreenshot: false,
+      })
+    })
+    const result = await act(async () => await capturePromise)
+    unsubscribe()
+
+    expect(result.ok).toBe(true)
+    expect(result.data).toMatchObject({ breakpointId: 'desktop' })
+    expect(requests).toContain('desktop')
+    expect(useEditorStore.getState().activeBreakpointId).toBe('desktop')
+    expect(useEditorStore.getState().canvasView).toBe('live')
+  })
+
+  it('uses the readiness-aware transient frame even when a visible frame is exact', async () => {
+    useEditorStore.setState({ canvasView: 'design' })
+    render(<CanvasRoot />)
+    let visibleFrame: HTMLElement | null = null
+    await act(async () => {
+      visibleFrame = await waitForAgentRenderFrame({
+        breakpointId: 'desktop',
+        source: 'visible',
+      })
+    })
+    Object.defineProperty(visibleFrame!.querySelector('iframe')!.contentWindow!, 'innerWidth', {
+      configurable: true,
+      value: 1440,
+    })
+
+    const requests: string[] = []
+    const unsubscribe = useEditorStore.subscribe((state) => {
+      const breakpointId = state.agentSnapshotCaptureRequest?.breakpointId
+      if (breakpointId) requests.push(breakpointId)
+    })
+    const result = await act(async () => await executeAgentTool('site_render_snapshot', {
+      breakpointId: 'desktop',
+      captureScreenshot: false,
+    }))
+    unsubscribe()
+
+    expect(result.ok).toBe(true)
+    expect(result.data).toMatchObject({ breakpointId: 'desktop' })
+    expect(requests).toEqual(['desktop'])
+  })
+
+  it('captures a collapsed design frame without expanding it', async () => {
+    useEditorStore.setState({ canvasView: 'design' })
+    render(<CanvasRoot />)
+    expect(findAgentRenderFrame({ breakpointId: 'tablet', source: 'visible' })).toBeNull()
+    const before = visibleCanvasState()
+
+    let capturePromise!: Promise<AiToolOutput>
+    act(() => {
+      capturePromise = executeAgentTool('site_render_snapshot', {
+        breakpointId: 'tablet',
+        captureScreenshot: false,
+      })
+    })
+    const result = await act(async () => await capturePromise)
+
+    expect(result.ok).toBe(true)
+    expect(result.data).toMatchObject({ breakpointId: 'tablet' })
+    expect(visibleCanvasState()).toEqual(before)
+    expect(useEditorStore.getState().collapsedBreakpointIds).toContain('tablet')
+  })
+
+  it('waits for delayed loop preview data before marking and capturing the frame', async () => {
+    const tableGate = deferred()
+    const rowsGate = deferred()
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input)
+      if (url.includes('/admin/api/cms/me/preferences/module-inserter')) {
+        return jsonResponse({ value: DEFAULT_MODULE_INSERTER_PREFERENCE })
+      }
+      if (url === '/admin/api/cms/data/tables/posts') {
+        await tableGate.promise
+        return jsonResponse({ table: POSTS_TABLE })
+      }
+      if (url.startsWith('/admin/api/cms/data/tables/posts/loop-preview')) {
+        await rowsGate.promise
+        return jsonResponse({
+          items: [{ id: 'post-1', fields: { title: 'Delayed loop row' } }],
+          totalItems: 1,
+        })
+      }
+      return new Response('', { status: 404 })
+    }) as typeof globalThis.fetch
+
+    const root = makeNode({ id: 'root', moduleId: 'base.body', children: ['loop'] })
+    const loop = makeNode({
+      id: 'loop',
+      moduleId: 'base.loop',
+      props: {
+        sourceId: 'data.rows',
+        filters: { tableId: 'posts' },
+        orderBy: 'publishedAt',
+        direction: 'desc',
+        limit: 3,
+        offset: 0,
+        tag: 'section',
+      },
+      children: ['loop-title'],
+    })
+    const title = makeNode({
+      id: 'loop-title',
+      moduleId: 'base.text',
+      props: { text: '{currentEntry.title}', tag: 'h2' },
+    })
+    const page = makePage({
+      id: 'loop-page',
+      rootNodeId: root.id,
+      nodes: { [root.id]: root, [loop.id]: loop, [title.id]: title },
+    })
+    useEditorStore.setState({
+      site: makeSite({ pages: [page], breakpoints: BREAKPOINTS }),
+      activePageId: page.id,
+    } as Parameters<typeof useEditorStore.setState>[0])
+
+    render(<CanvasRoot />)
+    let settled = false
+    let capturePromise!: Promise<AiToolOutput>
+    act(() => {
+      capturePromise = executeAgentTool('site_render_snapshot', {
+        breakpointId: 'mobile',
+        captureScreenshot: false,
+      })
+      void capturePromise.then(() => {
+        settled = true
+      })
+    })
+
+    let transientFrame: HTMLElement | null = null
+    await waitFor(() => {
+      transientFrame = findAgentRenderFrame({ breakpointId: 'mobile', source: 'transient' })
+      expect(transientFrame).not.toBeNull()
+    })
+    expect(transientFrame!.querySelector('iframe')?.dataset.agentSnapshotReady).toBeUndefined()
+    expect(settled).toBe(false)
+
+    await act(async () => {
+      tableGate.resolve()
+      await Promise.resolve()
+    })
+    expect(settled).toBe(false)
+    expect(transientFrame!.querySelector('iframe')?.dataset.agentSnapshotReady).toBeUndefined()
+
+    await act(async () => {
+      rowsGate.resolve()
+      await Promise.resolve()
+    })
+    const result = await act(async () => await capturePromise)
+    expect(result.ok).toBe(true)
+    expect(JSON.stringify(result.data)).toContain('Delayed loop row')
+  })
+
+  it('waits for a post-type template preview row before capturing bindings', async () => {
+    const tablesGate = deferred()
+    const rowsGate = deferred()
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input)
+      if (url.includes('/admin/api/cms/me/preferences/module-inserter')) {
+        return jsonResponse({ value: DEFAULT_MODULE_INSERTER_PREFERENCE })
+      }
+      if (url === '/admin/api/cms/data/tables') {
+        await tablesGate.promise
+        return jsonResponse({ tables: [POSTS_TABLE] })
+      }
+      if (url.startsWith('/admin/api/cms/data/tables/posts/loop-preview')) {
+        await rowsGate.promise
+        return jsonResponse({
+          items: [{ id: 'post-1', fields: { title: 'Delayed template row' } }],
+          totalItems: 1,
+        })
+      }
+      return new Response('', { status: 404 })
+    }) as typeof globalThis.fetch
+
+    const root = makeNode({ id: 'template-root', moduleId: 'base.body', children: ['title'] })
+    const title = makeNode({
+      id: 'title',
+      moduleId: 'base.text',
+      props: { text: 'Fallback title', tag: 'h1' },
+      dynamicBindings: {
+        text: { source: 'currentEntry', field: 'title' },
+      },
+    })
+    const template = makePage({
+      id: 'post-template',
+      rootNodeId: root.id,
+      nodes: { [root.id]: root, [title.id]: title },
+      template: {
+        enabled: true,
+        target: { kind: 'postTypes', tableSlugs: ['posts'] },
+        priority: 100,
+      },
+    })
+    useEditorStore.setState({
+      site: makeSite({ pages: [template], breakpoints: BREAKPOINTS }),
+      activePageId: template.id,
+      activeDocument: { kind: 'page', pageId: template.id },
+    } as Parameters<typeof useEditorStore.setState>[0])
+
+    render(<CanvasRoot />)
+    let settled = false
+    let capturePromise!: Promise<AiToolOutput>
+    act(() => {
+      capturePromise = executeAgentTool('site_render_snapshot', {
+        breakpointId: 'mobile',
+        captureScreenshot: false,
+      })
+      void capturePromise.then(() => {
+        settled = true
+      })
+    })
+
+    await waitFor(() => {
+      expect(findAgentRenderFrame({ breakpointId: 'mobile', source: 'transient' })).not.toBeNull()
+    })
+    expect(settled).toBe(false)
+
+    await act(async () => {
+      tablesGate.resolve()
+      await Promise.resolve()
+    })
+    expect(settled).toBe(false)
+
+    await act(async () => {
+      rowsGate.resolve()
+      await Promise.resolve()
+    })
+    const result = await act(async () => await capturePromise)
+    expect(result.ok).toBe(true)
+    expect(JSON.stringify(result.data)).toContain('Delayed template row')
+    expect(JSON.stringify(result.data)).not.toContain('Fallback title')
+  })
+
+  it('serializes parallel captures that both need the one transient frame', async () => {
+    useEditorStore.setState({ canvasView: 'design' })
+    render(<CanvasRoot />)
+    const before = visibleCanvasState()
+    const requests: string[] = []
+    const unsubscribe = useEditorStore.subscribe((state) => {
+      const breakpointId = state.agentSnapshotCaptureRequest?.breakpointId
+      if (breakpointId && requests.at(-1) !== breakpointId) requests.push(breakpointId)
+    })
+
+    const [mobileResult, tabletResult] = await act(async () => await Promise.all([
+      executeAgentTool('site_render_snapshot', {
+        breakpointId: 'mobile',
+        captureScreenshot: false,
+      }),
+      executeAgentTool('site_render_snapshot', {
+        breakpointId: 'tablet',
+        captureScreenshot: false,
+      }),
+    ]))
+    unsubscribe()
+
+    expect(mobileResult).toMatchObject({ ok: true, data: { breakpointId: 'mobile' } })
+    expect(tabletResult).toMatchObject({ ok: true, data: { breakpointId: 'tablet' } })
+    expect(requests).toEqual(['mobile', 'tablet'])
+    expect(visibleCanvasState()).toEqual(before)
+    expect(useEditorStore.getState().agentSnapshotCaptureRequest).toBeNull()
+  })
+
+  it('rejects an unknown breakpoint without mounting a fallback frame', async () => {
+    render(<CanvasRoot />)
+    await act(async () => {
+      await waitForAgentRenderFrame({
+        breakpointId: 'desktop',
+        source: 'visible',
+      })
+    })
+    const result = await act(async () => await executeAgentTool('site_render_snapshot', {
+      breakpointId: 'invented-phone',
+      captureScreenshot: false,
+    }))
+
+    expect(result).toEqual({ ok: false, error: 'Breakpoint not found: invented-phone' })
+    expect(useEditorStore.getState().agentSnapshotCaptureRequest).toBeNull()
+    expect(findAgentRenderFrame({
+      breakpointId: 'invented-phone',
+      source: 'transient',
+    })).toBeNull()
+  })
+})
+
+function visibleCanvasState() {
+  const state = useEditorStore.getState()
+  return {
+    activeBreakpointId: state.activeBreakpointId,
+    canvasView: state.canvasView,
+    collapsedBreakpointIds: [...state.collapsedBreakpointIds],
+  }
+}
diff --git a/src/__tests__/agent/renderEvidence.test.ts b/src/__tests__/agent/renderEvidence.test.ts
index 835032763..6a8e48dc2 100644
--- a/src/__tests__/agent/renderEvidence.test.ts
+++ b/src/__tests__/agent/renderEvidence.test.ts
@@ -1,8 +1,92 @@
-import { describe, expect, it, beforeEach, afterEach } from 'bun:test'
-import { captureAgentRenderSnapshot, SnapshotNodeNotFoundError } from '@site/agent'
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test'
+
+interface RasterOptions {
+  backgroundColor?: string
+  cacheBust?: boolean
+  imagePlaceholder?: string
+  pixelRatio?: number
+  width?: number
+  height?: number
+  canvasWidth?: number
+  canvasHeight?: number
+  style?: Partial<CSSStyleDeclaration>
+}
+
+interface RasterCall {
+  root: HTMLElement
+  options: RasterOptions
+  canvasWidth: number
+  canvasHeight: number
+  compositeOperation: string
+  fillStyle: string
+  fillRects: Array<[number, number, number, number]>
+  saveCount: number
+  restoreCount: number
+  dataUrlType?: string
+}
+
+const rasterCalls: RasterCall[] = []
+const toCanvasMock = mock(async (root: HTMLElement, options: RasterOptions = {}) => {
+  const ratio = options.pixelRatio ?? 1
+  const rect = root.getBoundingClientRect()
+  // Canvas width/height use WebIDL integer conversion rather than rounding.
+  const canvasWidth = Math.trunc((options.canvasWidth ?? options.width ?? rect.width) * ratio)
+  const canvasHeight = Math.trunc((options.canvasHeight ?? options.height ?? rect.height) * ratio)
+  const call: RasterCall = {
+    root,
+    options,
+    canvasWidth,
+    canvasHeight,
+    compositeOperation: 'source-over',
+    fillStyle: '',
+    fillRects: [],
+    saveCount: 0,
+    restoreCount: 0,
+  }
+  const context = {
+    get globalCompositeOperation() {
+      return call.compositeOperation
+    },
+    set globalCompositeOperation(value: string) {
+      call.compositeOperation = value
+    },
+    get fillStyle() {
+      return call.fillStyle
+    },
+    set fillStyle(value: string | CanvasGradient | CanvasPattern) {
+      call.fillStyle = String(value)
+    },
+    save() {
+      call.saveCount += 1
+    },
+    restore() {
+      call.restoreCount += 1
+    },
+    fillRect(x: number, y: number, width: number, height: number) {
+      call.fillRects.push([x, y, width, height])
+    },
+  } as CanvasRenderingContext2D
+  const canvas = {
+    width: canvasWidth,
+    height: canvasHeight,
+    getContext: (type: string) => type === '2d' ? context : null,
+    toDataURL: (type?: string) => {
+      call.dataUrlType = type
+      return 'data:image/png;base64,cG5n'
+    },
+  } as HTMLCanvasElement
+  rasterCalls.push(call)
+  return canvas
+})
+
+mock.module('html-to-image', () => ({ toCanvas: toCanvasMock }))
+
+const { captureAgentRenderSnapshot, SnapshotNodeNotFoundError } = await import('@site/agent')
 
 beforeEach(() => {
   document.body.innerHTML = ''
+  rasterCalls.length = 0
+  toCanvasMock.mockClear()
 })
 
 // Clear DOM after each test too — these tests inject ad-hoc elements directly
@@ -37,7 +121,11 @@ function setRect(el: Element, rect: Partial<DOMRectReadOnly>) {
  * wrapper containing an <iframe> whose `contentDocument` holds the rendered
  * page nodes. Returns the iframe's document so the test can populate it.
  */
-function mountFrame(breakpointId: string): Document {
+function mountFrame(
+  breakpointId: string,
+  viewportWidth: number = { mobile: 375, tablet: 768, desktop: 1440 }[breakpointId] ?? 1024,
+  viewportHeight = 900,
+): Document {
   const viewport = document.createElement('div')
   viewport.dataset.breakpointId = breakpointId
   const iframe = document.createElement('iframe')
@@ -45,10 +133,191 @@ function mountFrame(breakpointId: string): Document {
   document.body.appendChild(viewport)
   const doc = iframe.contentDocument
   if (!doc) throw new Error('iframe.contentDocument unavailable in test env')
+  Object.defineProperties(doc.defaultView, {
+    innerWidth: { configurable: true, value: viewportWidth },
+    innerHeight: { configurable: true, value: viewportHeight },
+  })
   return doc
 }
 
 describe('captureAgentRenderSnapshot — on-demand browser bridge', () => {
+  it('rasterizes a node crop from the iframe document without replacing authored backgrounds', async () => {
+    const doc = mountFrame('desktop', 2400, 1200)
+    const html = doc.documentElement
+    const body = doc.body
+    html.style.backgroundColor = 'rgb(9, 9, 15)'
+    body.style.backgroundImage = 'linear-gradient(black, rebeccapurple)'
+    body.style.transform = 'translate(20px, 30px)'
+    Object.defineProperties(html, {
+      clientWidth: { configurable: true, value: 2400 },
+      clientHeight: { configurable: true, value: 1200 },
+      scrollWidth: { configurable: true, value: 2400 },
+      scrollHeight: { configurable: true, value: 3000 },
+    })
+    Object.defineProperties(body, {
+      clientWidth: { configurable: true, value: 2400 },
+      clientHeight: { configurable: true, value: 3000 },
+      scrollWidth: { configurable: true, value: 2400 },
+      scrollHeight: { configurable: true, value: 3000 },
+    })
+    setRect(html, { x: 0, y: 0, width: 2400, height: 3000 })
+    setRect(body, { x: 20, y: 30, width: 2400, height: 3000 })
+
+    const hero = doc.createElement('section')
+    hero.dataset.nodeId = 'hero'
+    hero.dataset.moduleId = 'base.container'
+    setRect(hero, { x: 120, y: 230, width: 2000, height: 1000 })
+    body.appendChild(hero)
+
+    const snapshot = await captureAgentRenderSnapshot({
+      breakpointId: 'desktop',
+      nodeId: 'hero',
+      captureScreenshot: true,
+    })
+
+    expect(snapshot?.screenshot).toEqual({
+      status: 'ok',
+      mimeType: 'image/png',
+      data: 'cG5n',
+      width: 1568,
+      height: 784,
+    })
+    expect(rasterCalls).toHaveLength(1)
+    const call = rasterCalls[0]!
+    expect(call.root).toBe(html)
+    expect(call.root.querySelector('body')).toBe(body)
+    expect(call.root.style.backgroundColor).not.toBe('')
+    expect(body.style.backgroundImage).not.toBe('')
+    expect(body.style.transform).not.toBe('')
+    expect(call.options).not.toHaveProperty('backgroundColor')
+    expect(call.options).toMatchObject({
+      cacheBust: true,
+      imagePlaceholder: '',
+      pixelRatio: 1568 / 2000,
+      width: 2000,
+      height: 1000,
+      canvasWidth: 2000,
+      canvasHeight: 1000,
+      style: {
+        width: '2400px',
+        height: '3030px',
+        transform: 'translate(-120px, -230px)',
+        transformOrigin: 'top left',
+      },
+    })
+    expect(call.compositeOperation).toBe('destination-over')
+    expect(call.fillStyle).toBe('#ffffff')
+    expect(call.fillRects).toEqual([[0, 0, 1568, 784]])
+    expect(call.saveCount).toBe(1)
+    expect(call.restoreCount).toBe(1)
+    expect(call.dataUrlType).toBe('image/png')
+  })
+
+  it('uses the iframe viewport and full document when the authored body is narrow and transformed', async () => {
+    const doc = mountFrame('desktop', 1440, 900)
+    const html = doc.documentElement
+    const body = doc.body
+    html.style.backgroundColor = 'rgb(9, 9, 15)'
+    body.style.backgroundImage = 'linear-gradient(black, rebeccapurple)'
+    body.style.maxWidth = '960px'
+    body.style.transform = 'translateX(240px)'
+    Object.defineProperties(html, {
+      clientWidth: { configurable: true, value: 1440 },
+      clientHeight: { configurable: true, value: 900 },
+      scrollWidth: { configurable: true, value: 1440 },
+      scrollHeight: { configurable: true, value: 2400 },
+    })
+    Object.defineProperties(body, {
+      clientWidth: { configurable: true, value: 960 },
+      clientHeight: { configurable: true, value: 2400 },
+      scrollWidth: { configurable: true, value: 960 },
+      scrollHeight: { configurable: true, value: 2400 },
+    })
+    setRect(html, { x: 0, y: 0, width: 1440, height: 2400 })
+    setRect(body, { x: 240, y: 0, width: 960, height: 2400 })
+
+    const heading = doc.createElement('h1')
+    heading.dataset.nodeId = 'heading'
+    heading.dataset.moduleId = 'base.text'
+    setRect(heading, { x: 280, y: 80, width: 640, height: 96 })
+    body.appendChild(heading)
+
+    const snapshot = await captureAgentRenderSnapshot({
+      breakpointId: 'desktop',
+      captureScreenshot: true,
+    })
+
+    expect(snapshot?.width).toBe(1440)
+    expect(snapshot?.layout.viewport).toEqual({
+      width: 1440,
+      height: 2400,
+      scrollWidth: 1440,
+      scrollHeight: 2400,
+    })
+    expect(snapshot?.layout.nodes[0]?.rect.x).toBe(280)
+    expect(snapshot?.screenshot).toMatchObject({
+      status: 'ok',
+      width: 940,
+      height: 1568,
+    })
+
+    expect(rasterCalls).toHaveLength(1)
+    const call = rasterCalls[0]!
+    expect(call.root).toBe(html)
+    expect(call.root.querySelector('body')).toBe(body)
+    expect(call.root.style.backgroundColor).not.toBe('')
+    expect(body.style.backgroundImage).not.toBe('')
+    expect(body.style.maxWidth).toBe('960px')
+    expect(body.style.transform).not.toBe('')
+    expect(call.options).not.toHaveProperty('backgroundColor')
+    expect(call.options).toMatchObject({
+      cacheBust: true,
+      imagePlaceholder: '',
+      pixelRatio: 1568 / 2400,
+      width: 1440,
+      height: 2400,
+      canvasWidth: 1440,
+      canvasHeight: 2400,
+    })
+    expect(call.options.style).toBeUndefined()
+    expect(call.compositeOperation).toBe('destination-over')
+    expect(call.fillStyle).toBe('#ffffff')
+    expect(call.fillRects).toEqual([[0, 0, 940, 1568]])
+  })
+
+  it('captures every explicitly requested mounted breakpoint', async () => {
+    const breakpoints = [
+      { id: 'mobile', width: 375 },
+      { id: 'tablet', width: 768 },
+      { id: 'desktop', width: 1440 },
+    ]
+    for (const breakpoint of breakpoints) {
+      const doc = mountFrame(breakpoint.id)
+      setRect(doc.body, { x: 0, y: 0, width: breakpoint.width, height: 900 })
+    }
+
+    for (const breakpoint of breakpoints) {
+      const snapshot = await captureAgentRenderSnapshot({
+        breakpointId: breakpoint.id,
+        captureScreenshot: false,
+      })
+      expect(snapshot?.breakpointId).toBe(breakpoint.id)
+      expect(snapshot?.width).toBe(breakpoint.width)
+    }
+  })
+
+  it('does not substitute the first frame when an explicit breakpoint is unavailable', async () => {
+    const doc = mountFrame('desktop')
+    setRect(doc.body, { x: 0, y: 0, width: 1440, height: 900 })
+
+    const snapshot = await captureAgentRenderSnapshot({
+      breakpointId: 'mobile',
+      captureScreenshot: false,
+    })
+
+    expect(snapshot).toBeNull()
+  })
+
   it('captures breakpoint layout, node boxes, and overflow warnings from the canvas DOM', async () => {
     const doc = mountFrame('mobile')
     const body = doc.body
@@ -81,6 +350,43 @@ describe('captureAgentRenderSnapshot — on-demand browser bridge', () => {
     )).toBe(true)
   })
 
+  it('distinguishes deferred lazy images from completed broken images', async () => {
+    const doc = mountFrame('mobile')
+    const deferredImage = doc.createElement('img')
+    deferredImage.dataset.nodeId = 'deferred-image'
+    deferredImage.src = '/uploads/deferred.png'
+    deferredImage.loading = 'lazy'
+    Object.defineProperties(deferredImage, {
+      complete: { configurable: true, value: false },
+      naturalWidth: { configurable: true, value: 0 },
+      naturalHeight: { configurable: true, value: 0 },
+    })
+    setRect(deferredImage, { x: 0, y: 0, width: 320, height: 180 })
+
+    const brokenImage = doc.createElement('img')
+    brokenImage.dataset.nodeId = 'broken-image'
+    brokenImage.src = '/uploads/missing.png'
+    Object.defineProperties(brokenImage, {
+      complete: { configurable: true, value: true },
+      naturalWidth: { configurable: true, value: 0 },
+      naturalHeight: { configurable: true, value: 0 },
+    })
+    setRect(brokenImage, { x: 0, y: 200, width: 320, height: 180 })
+    doc.body.append(deferredImage, brokenImage)
+
+    const snapshot = await captureAgentRenderSnapshot({
+      breakpointId: 'mobile',
+      captureScreenshot: false,
+    })
+
+    const brokenWarnings = snapshot!.layout.warnings.filter(
+      (warning) => warning.type === 'broken-image',
+    )
+    expect(brokenWarnings).toHaveLength(1)
+    expect(brokenWarnings[0]?.nodeId).toBe('broken-image')
+    expect(snapshot!.layout.images.find((image) => image.nodeId === 'deferred-image')?.complete).toBe(false)
+  })
+
   it('scopes the capture to a node subtree when nodeId is given', async () => {
     const doc = mountFrame('desktop')
 
diff --git a/src/__tests__/base-modules.test.ts b/src/__tests__/base-modules.test.ts
index 8606cc79a..3c1713c57 100644
--- a/src/__tests__/base-modules.test.ts
+++ b/src/__tests__/base-modules.test.ts
@@ -20,6 +20,7 @@ import './matchers'  // Register toBeCleanHTML
 
 import { runModuleConformanceSuite, renderModule, withBannedGlobals } from './helpers'
 import { escapeProps } from '@core/publisher'
+import { CanvasDocumentContext } from '@site/canvas/CanvasContexts'
 
 // ---------------------------------------------------------------------------
 // Import base modules (self-register into global registry on import)
@@ -426,23 +427,45 @@ describe('base.body — render() specifics', () => {
 
   it('applies editor identity to the iframe body without wrapping children', () => {
     const editorDocument = document.implementation.createHTMLDocument('canvas')
+    editorDocument.body.className = 'frame-default'
+    editorDocument.body.dataset.breakpointId = 'desktop'
+    editorDocument.body.style.backgroundColor = 'rgb(1, 2, 3)'
     const mount = editorDocument.createElement('div')
     editorDocument.body.appendChild(mount)
 
-    const { container } = renderReact(
-      React.createElement(BodyModule.component, {
-        props: {},
-        nodeId: 'body-node',
-        isSelected: true,
-        mcClassName: 'ist-body',
-        nodeWrapperProps: {
-          'data-node-id': 'body-node',
-          'data-module-id': 'base.body',
-          'data-canvas-selected': 'true',
-          tabIndex: 0,
-        },
-        children: React.createElement('p', null, 'Body child'),
-      } as never),
+    const { container, unmount } = renderReact(
+      React.createElement(
+        CanvasDocumentContext.Provider,
+        { value: editorDocument },
+        React.createElement(BodyModule.component, {
+          props: {
+            htmlAttributes: {
+              id: 'site-body',
+              dir: 'rtl',
+              role: 'document',
+              'aria-pressed': 'false',
+              'data-theme': 'dark',
+              'data-breakpoint-id': 'forged',
+              tabindex: '9',
+              onclick: 'alert(1)',
+            },
+          },
+          nodeId: 'body-node',
+          isSelected: true,
+          mcClassName: 'ist-body',
+          nodeWrapperProps: {
+            'data-node-id': 'body-node',
+            'data-module-id': 'base.body',
+            'data-canvas-selected': 'true',
+            tabIndex: 0,
+            style: {
+              backgroundColor: 'rgb(9, 10, 11)',
+              backgroundImage: 'linear-gradient(red, blue)',
+            },
+          },
+          children: React.createElement('p', null, 'Body child'),
+        } as never),
+      ),
       { container: mount },
     )
 
@@ -450,10 +473,32 @@ describe('base.body — render() specifics', () => {
     expect(editorDocument.body.getAttribute('data-module-id')).toBe('base.body')
     expect(editorDocument.body.getAttribute('data-canvas-selected')).toBe('true')
     expect(editorDocument.body.getAttribute('tabindex')).toBe('0')
+    expect(editorDocument.body.getAttribute('id')).toBe('site-body')
+    expect(editorDocument.body.getAttribute('dir')).toBe('rtl')
+    expect(editorDocument.body.getAttribute('role')).toBe('document')
+    expect(editorDocument.body.getAttribute('aria-pressed')).toBe('false')
+    expect(editorDocument.body.getAttribute('data-theme')).toBe('dark')
+    expect(editorDocument.body.getAttribute('data-breakpoint-id')).toBe('desktop')
+    expect(editorDocument.body.hasAttribute('onclick')).toBe(false)
     expect(editorDocument.body.className).toBe('ist-body')
-    expect(container.querySelector('[data-instatic-body-probe]')?.getAttribute('aria-hidden')).toBe('true')
+    expect(editorDocument.body.style.backgroundColor).toBe('rgb(9, 10, 11)')
+    expect(editorDocument.body.style.backgroundImage).toBe('linear-gradient(red, blue)')
+    expect(container.querySelector('[data-instatic-body-probe]')).toBeNull()
     expect(container.querySelector('p')?.textContent).toBe('Body child')
-    expect(container.firstElementChild?.nextElementSibling?.tagName).toBe('P')
+    expect(container.children).toHaveLength(1)
+    expect(container.firstElementChild?.tagName).toBe('P')
+
+    unmount()
+    expect(editorDocument.body.className).toBe('frame-default')
+    expect(editorDocument.body.style.backgroundColor).toBe('rgb(1, 2, 3)')
+    expect(editorDocument.body.style.backgroundImage).toBe('')
+    expect(editorDocument.body.hasAttribute('id')).toBe(false)
+    expect(editorDocument.body.hasAttribute('data-theme')).toBe(false)
+    expect(editorDocument.body.getAttribute('data-breakpoint-id')).toBe('desktop')
+    expect(editorDocument.body.hasAttribute('data-node-id')).toBe(false)
+    expect(editorDocument.body.hasAttribute('data-module-id')).toBe(false)
+    expect(editorDocument.body.hasAttribute('data-canvas-selected')).toBe(false)
+    expect(editorDocument.body.hasAttribute('tabindex')).toBe(false)
   })
 
   it('does not access DOM globals during publish render', () => {
diff --git a/src/__tests__/canvas/bodyPresentation.test.tsx b/src/__tests__/canvas/bodyPresentation.test.tsx
new file mode 100644
index 000000000..7d3a50a4c
--- /dev/null
+++ b/src/__tests__/canvas/bodyPresentation.test.tsx
@@ -0,0 +1,359 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import React from 'react'
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import { DndContext } from '@dnd-kit/core'
+import { classKindSelector, type StyleRule } from '@core/page-tree'
+import { useEditorStore } from '@site/store/store'
+import { CanvasRoot } from '@site/canvas/CanvasRoot'
+import { makeNode, makePage, makeSite } from '../fixtures'
+import { waitForCanvasFrameDocument } from './iframeCanvasQuery'
+import '@modules/base'
+
+const originalFetch = globalThis.fetch
+
+function renderCanvas() {
+  return render(<DndContext><CanvasRoot /></DndContext>)
+}
+
+function bodyNode(
+  id: string,
+  children: string[],
+  backgroundColor: string,
+  backgroundImage?: string,
+) {
+  return {
+    ...makeNode({ id, moduleId: 'base.body', children }),
+    inlineStyles: {
+      backgroundColor,
+      ...(backgroundImage ? { backgroundImage } : {}),
+    },
+  }
+}
+
+beforeEach(() => {
+  cleanup()
+  globalThis.fetch = (async () =>
+    new Response(JSON.stringify({ value: null }), { status: 200 })) as typeof fetch
+  useEditorStore.setState({
+    site: null,
+    activePageId: null,
+    activeDocument: null,
+    activeBreakpointId: 'desktop',
+    activeConditionId: null,
+    canvasView: 'design',
+    collapsedBreakpointIds: [],
+    selectedNodeId: null,
+    selectedNodeIds: [],
+    hoveredNodeId: null,
+    _historyPast: [],
+    _historyFuture: [],
+    canUndo: false,
+    canRedo: false,
+    hasUnsavedChanges: false,
+  } as Parameters<typeof useEditorStore.setState>[0])
+})
+
+afterEach(() => {
+  cleanup()
+  globalThis.fetch = originalFetch
+})
+
+describe('canvas iframe body presentation', () => {
+  it('does not insert editor-only children before authored body content', async () => {
+    const root = bodyNode('page-root', ['main'], 'rgb(12, 18, 24)')
+    const main = makeNode({
+      id: 'main',
+      moduleId: 'base.container',
+      props: { tag: 'main' },
+    })
+    const page = makePage({
+      id: 'page',
+      rootNodeId: root.id,
+      nodes: { [root.id]: root, [main.id]: main },
+    })
+
+    useEditorStore.setState({
+      site: makeSite({ pages: [page] }),
+      activePageId: page.id,
+    } as Parameters<typeof useEditorStore.setState>[0])
+
+    renderCanvas()
+    const frameDocument = await waitForCanvasFrameDocument('desktop')
+
+    await waitFor(() => {
+      const firstChild = frameDocument.body.firstElementChild
+      expect(firstChild?.tagName).toBe('MAIN')
+      expect(firstChild?.getAttribute('data-node-id')).toBe(main.id)
+      expect(firstChild?.matches(':first-child')).toBe(true)
+      expect(frameDocument.body.children).toHaveLength(1)
+    })
+  })
+
+  it('lets sanitized body attributes drive authored selector styling', async () => {
+    const root = makeNode({
+      id: 'page-root',
+      moduleId: 'base.body',
+      props: { htmlAttributes: { 'data-theme': 'dark' } },
+    })
+    const page = makePage({
+      id: 'page',
+      rootNodeId: root.id,
+      nodes: { [root.id]: root },
+    })
+    const themeRule: StyleRule = {
+      id: 'dark-body',
+      name: 'body dark theme',
+      kind: 'ambient',
+      selector: 'body[data-theme="dark"]',
+      order: 0,
+      styles: { backgroundColor: 'rgb(6, 10, 18)' },
+      contextStyles: {},
+      createdAt: 0,
+      updatedAt: 0,
+    }
+
+    useEditorStore.setState({
+      site: makeSite({ pages: [page], styleRules: { [themeRule.id]: themeRule } }),
+      activePageId: page.id,
+    } as Parameters<typeof useEditorStore.setState>[0])
+
+    renderCanvas()
+    const frameDocument = await waitForCanvasFrameDocument('desktop')
+
+    await waitFor(() => {
+      expect(frameDocument.body.dataset.theme).toBe('dark')
+      expect(frameDocument.body.matches('body[data-theme="dark"]')).toBe(true)
+      expect(frameDocument.head.textContent).toContain('body[data-theme="dark"]')
+      expect(frameDocument.head.textContent).toContain('background-color: rgb(6, 10, 18)')
+    })
+  })
+
+  it('applies the active page body inline background to the real iframe body', async () => {
+    const root = bodyNode(
+      'page-root',
+      [],
+      'rgb(12, 18, 24)',
+      'linear-gradient(rgb(12, 18, 24), rgb(24, 36, 48))',
+    )
+    root.inlineStyles = {
+      ...root.inlineStyles,
+      height: '40px',
+      minHeight: '10px',
+      overflow: 'scroll',
+      overflowX: 'auto',
+    }
+    root.props.htmlAttributes = {
+      id: 'site-body',
+      role: 'document',
+      'data-theme': 'dark',
+      'data-breakpoint-id': 'forged',
+    }
+    const page = makePage({
+      id: 'page',
+      rootNodeId: root.id,
+      nodes: { [root.id]: root },
+    })
+
+    useEditorStore.setState({
+      site: makeSite({ pages: [page] }),
+      activePageId: page.id,
+    } as Parameters<typeof useEditorStore.setState>[0])
+
+    renderCanvas()
+    const frameDocument = await waitForCanvasFrameDocument('desktop')
+
+    await waitFor(() => {
+      expect(frameDocument.body.style.backgroundColor).toBe('rgb(12, 18, 24)')
+      expect(frameDocument.body.style.backgroundImage).toBe(
+        'linear-gradient(rgb(12, 18, 24), rgb(24, 36, 48))',
+      )
+      expect(frameDocument.body.style.height).toBe('auto')
+      expect(frameDocument.body.style.minHeight).toBe('800px')
+      expect(frameDocument.body.style.overflow).toBe('hidden')
+      expect(frameDocument.body.style.overflowX).toBe('')
+      expect(frameDocument.body.id).toBe('site-body')
+      expect(frameDocument.body.getAttribute('role')).toBe('document')
+      expect(frameDocument.body.dataset.theme).toBe('dark')
+      expect(frameDocument.body.dataset.breakpointId).toBe('desktop')
+    })
+
+    act(() => {
+      useEditorStore.getState().setNodeInlineStyles(root.id, {
+        backgroundColor: 'rgb(30, 42, 54)',
+        height: '25px',
+        minHeight: '5px',
+        overflow: 'visible',
+        overflowY: 'scroll',
+      })
+      useEditorStore.getState().updateNodeProps(root.id, {
+        htmlAttributes: { dir: 'rtl', 'data-theme': 'dusk' },
+      })
+    })
+
+    await waitFor(() => {
+      expect(frameDocument.body.style.backgroundColor).toBe('rgb(30, 42, 54)')
+      expect(frameDocument.body.style.height).toBe('auto')
+      expect(frameDocument.body.style.minHeight).toBe('800px')
+      expect(frameDocument.body.style.overflow).toBe('hidden')
+      expect(frameDocument.body.style.overflowY).toBe('')
+      expect(frameDocument.body.hasAttribute('id')).toBe(false)
+      expect(frameDocument.body.getAttribute('dir')).toBe('rtl')
+      expect(frameDocument.body.dataset.theme).toBe('dusk')
+    })
+  })
+
+  it('keeps authored root sizing and overflow in the live published-behaviour frame', async () => {
+    const root = bodyNode('page-root', [], 'rgb(20, 24, 32)')
+    root.inlineStyles = {
+      ...root.inlineStyles,
+      height: '40px',
+      minHeight: '10px',
+      overflow: 'scroll',
+    }
+    const page = makePage({
+      id: 'page',
+      rootNodeId: root.id,
+      nodes: { [root.id]: root },
+    })
+
+    useEditorStore.setState({
+      site: makeSite({ pages: [page] }),
+      activePageId: page.id,
+      canvasView: 'live',
+    } as Parameters<typeof useEditorStore.setState>[0])
+
+    renderCanvas()
+    const frameDocument = await waitForCanvasFrameDocument('desktop')
+
+    await waitFor(() => {
+      expect(frameDocument.body.style.backgroundColor).toBe('rgb(20, 24, 32)')
+      expect(frameDocument.body.style.height).toBe('40px')
+      expect(frameDocument.body.style.minHeight).toBe('10px')
+      expect(frameDocument.body.style.overflow).toBe('scroll')
+    })
+  })
+
+  it('uses the outer wrapper body class and inline background, matching publisher ownership', async () => {
+    const outerBodyClass: StyleRule = {
+      id: 'outer-body-class',
+      name: 'outer-body',
+      kind: 'class',
+      selector: classKindSelector('outer-body'),
+      order: 0,
+      styles: {},
+      contextStyles: {},
+      createdAt: 0,
+      updatedAt: 0,
+    }
+    const wrapperRoot = {
+      ...bodyNode('wrapper-root', ['outlet'], 'rgb(7, 11, 19)'),
+      classIds: [outerBodyClass.id],
+    }
+    wrapperRoot.props.htmlAttributes = {
+      id: 'outer-body',
+      dir: 'rtl',
+      'data-theme': 'outer-dark',
+      'data-breakpoint-id': 'forged',
+    }
+    const outlet = makeNode({ id: 'outlet', moduleId: 'base.outlet' })
+    const wrapper = makePage({
+      id: 'wrapper',
+      title: 'Everywhere',
+      rootNodeId: wrapperRoot.id,
+      nodes: { [wrapperRoot.id]: wrapperRoot, [outlet.id]: outlet },
+      template: {
+        enabled: true,
+        target: { kind: 'everywhere' },
+        priority: 100,
+      },
+    })
+    const pageRoot = bodyNode('page-root', [], 'rgb(220, 30, 40)')
+    pageRoot.props.htmlAttributes = {
+      id: 'inner-body',
+      'data-theme': 'inner-light',
+    }
+    const page = makePage({
+      id: 'page',
+      rootNodeId: pageRoot.id,
+      nodes: { [pageRoot.id]: pageRoot },
+    })
+
+    useEditorStore.setState({
+      site: makeSite({
+        pages: [wrapper, page],
+        styleRules: { [outerBodyClass.id]: outerBodyClass },
+      }),
+      activePageId: page.id,
+    } as Parameters<typeof useEditorStore.setState>[0])
+
+    renderCanvas()
+    const frameDocument = await waitForCanvasFrameDocument('desktop')
+
+    await waitFor(() => {
+      expect(frameDocument.body.classList.contains('outer-body')).toBe(true)
+      expect(frameDocument.body.style.backgroundColor).toBe('rgb(7, 11, 19)')
+      expect(frameDocument.body.style.backgroundColor).not.toBe('rgb(220, 30, 40)')
+      expect(frameDocument.body.id).toBe('outer-body')
+      expect(frameDocument.body.dir).toBe('rtl')
+      expect(frameDocument.body.dataset.theme).toBe('outer-dark')
+      expect(frameDocument.body.dataset.breakpointId).toBe('desktop')
+    })
+  })
+
+  it('removes editable body identity when switching to wrapped composition', async () => {
+    const wrapperRoot = bodyNode('wrapper-root', ['outlet'], 'rgb(7, 11, 19)')
+    const outlet = makeNode({ id: 'outlet', moduleId: 'base.outlet' })
+    const wrapper = makePage({
+      id: 'wrapper',
+      title: 'Everywhere',
+      rootNodeId: wrapperRoot.id,
+      nodes: { [wrapperRoot.id]: wrapperRoot, [outlet.id]: outlet },
+      template: {
+        enabled: true,
+        target: { kind: 'everywhere' },
+        priority: 100,
+      },
+    })
+    const pageRoot = bodyNode('page-root', [], 'rgb(20, 30, 40)')
+    const page = makePage({
+      id: 'page',
+      rootNodeId: pageRoot.id,
+      nodes: { [pageRoot.id]: pageRoot },
+    })
+
+    useEditorStore.setState({
+      site: makeSite({ pages: [wrapper, page] }),
+      activePageId: wrapper.id,
+      selectedNodeId: wrapperRoot.id,
+      selectedNodeIds: [wrapperRoot.id],
+      hoveredNodeId: wrapperRoot.id,
+    } as Parameters<typeof useEditorStore.setState>[0])
+
+    renderCanvas()
+    const frameDocument = await waitForCanvasFrameDocument('desktop')
+    await waitFor(() => {
+      expect(frameDocument.body.dataset.nodeId).toBe(wrapperRoot.id)
+      expect(frameDocument.body.dataset.moduleId).toBe('base.body')
+      expect(frameDocument.body.dataset.canvasSelected).toBe('true')
+      expect(frameDocument.body.getAttribute('tabindex')).toBe('0')
+    })
+
+    act(() => {
+      useEditorStore.setState({
+        activePageId: page.id,
+        selectedNodeId: null,
+        selectedNodeIds: [],
+        hoveredNodeId: null,
+      })
+    })
+
+    await waitFor(() => {
+      expect(frameDocument.body.hasAttribute('data-node-id')).toBe(false)
+      expect(frameDocument.body.hasAttribute('data-module-id')).toBe(false)
+      expect(frameDocument.body.hasAttribute('data-canvas-selected')).toBe(false)
+      expect(frameDocument.body.hasAttribute('data-hovered')).toBe(false)
+      expect(frameDocument.body.hasAttribute('tabindex')).toBe(false)
+      expect(frameDocument.body.style.backgroundColor).toBe('rgb(7, 11, 19)')
+    })
+  })
+})
diff --git a/src/__tests__/canvas/canvasPreviewReadiness.test.ts b/src/__tests__/canvas/canvasPreviewReadiness.test.ts
new file mode 100644
index 000000000..33bac2b62
--- /dev/null
+++ b/src/__tests__/canvas/canvasPreviewReadiness.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'bun:test'
+import { createCanvasPreviewReadiness } from '@site/canvas/CanvasPreviewReadiness'
+
+function deferred() {
+  let resolve!: () => void
+  let reject!: (error: Error) => void
+  const promise = new Promise<void>((onResolve, onReject) => {
+    resolve = onResolve
+    reject = onReject
+  })
+  return { promise, resolve, reject }
+}
+
+describe('canvas preview readiness', () => {
+  it('waits for every tracked task and advances its revision', async () => {
+    const readiness = createCanvasPreviewReadiness()
+    const first = deferred()
+    const second = deferred()
+    readiness.track(first.promise)
+    readiness.track(second.promise)
+
+    const controller = new AbortController()
+    let settled = false
+    const idle = readiness.waitUntilIdle(controller.signal).then((value) => {
+      settled = true
+      return value
+    })
+
+    first.resolve()
+    await Promise.resolve()
+    expect(settled).toBe(false)
+    expect(readiness.pendingCount()).toBe(1)
+
+    second.resolve()
+    expect(await idle).toBe(true)
+    expect(readiness.pendingCount()).toBe(0)
+    expect(readiness.revision()).toBe(4)
+  })
+
+  it('releases rejected tasks without creating a poisoned barrier', async () => {
+    const readiness = createCanvasPreviewReadiness()
+    const task = deferred()
+    readiness.track(task.promise)
+    const idle = readiness.waitUntilIdle(new AbortController().signal)
+
+    task.reject(new Error('preview failed'))
+    expect(await idle).toBe(true)
+    expect(readiness.pendingCount()).toBe(0)
+  })
+
+  it('returns false when the waiter is aborted', async () => {
+    const readiness = createCanvasPreviewReadiness()
+    const task = deferred()
+    readiness.track(task.promise)
+    const controller = new AbortController()
+    const idle = readiness.waitUntilIdle(controller.signal)
+
+    controller.abort()
+    expect(await idle).toBe(false)
+    task.resolve()
+    await Promise.resolve()
+    expect(readiness.pendingCount()).toBe(0)
+  })
+})
diff --git a/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts b/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts
index be09f7144..567aed13b 100644
--- a/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts
+++ b/src/admin/pages/media/hooks/useCmsMediaAssetByPath.ts
@@ -15,8 +15,9 @@
  * invalidates on `refreshCmsMediaAssetCache()` — call after a replace /
  * delete so stale rows don't linger.
  */
-import { useEffect, useState } from 'react'
+import { use, useEffect, useState } from 'react'
 import { listCmsMediaAssets, type CmsMediaAsset } from '@core/persistence/cmsMedia'
+import { CanvasPreviewReadinessContext } from '@site/canvas/CanvasPreviewReadiness'
 
 // Module-level cache, shared across every consumer. CmsMediaAsset objects
 // are small (< 1 KB each), so a Map of every asset the user has touched
@@ -97,6 +98,7 @@ export function useCmsMediaAssetByPath(publicPath: string | null | undefined): C
 }
 
 export function useCmsMediaAssetsByPath(publicPaths: readonly string[]): ReadonlyMap<string, CmsMediaAsset> {
+  const previewReadiness = use(CanvasPreviewReadinessContext)
   const key = publicPathsKey(publicPaths)
   const [snapshot, setSnapshot] = useState<CachedAssetSnapshot>(() => ({
     key,
@@ -118,7 +120,9 @@ export function useCmsMediaAssetsByPath(publicPaths: readonly string[]): Readonl
     subscribers.add(updateSnapshot)
 
     if (!paths.every((path) => cache.has(path))) {
-      void ensureList()
+      const request = ensureList()
+      previewReadiness?.track(request)
+      void request
         .then(updateSnapshot)
         .catch(() => { /* swallow — editor still renders raw urls */ })
     }
@@ -127,7 +131,7 @@ export function useCmsMediaAssetsByPath(publicPaths: readonly string[]): Readonl
       canceled = true
       subscribers.delete(updateSnapshot)
     }
-  }, [key])
+  }, [key, previewReadiness])
 
   return currentAssets
 }
diff --git a/src/admin/pages/site/agent/executor.ts b/src/admin/pages/site/agent/executor.ts
index c6d013771..1294bea1e 100644
--- a/src/admin/pages/site/agent/executor.ts
+++ b/src/admin/pages/site/agent/executor.ts
@@ -88,7 +88,7 @@ import {
   runReadCodeAsset,
   runWriteCodeAsset,
 } from './codeAssetTools'
-import { runRenderSnapshot } from './renderSnapshotTool'
+import { runRenderSnapshotAtBreakpoint } from './renderSnapshotAtBreakpoint'
 import {
   activeDocumentNodes,
   activeRenderPage,
@@ -685,7 +685,7 @@ export async function executeAgentTool(
         // Default to the breakpoint the user is actually viewing, not the first
         // frame in the DOM (which is mobile in a mobile-first canvas layout).
         const breakpointId = parsed.breakpointId ?? getStoreState().activeBreakpointId
-        return await runRenderSnapshot({ ...parsed, breakpointId })
+        return await runRenderSnapshotAtBreakpoint({ ...parsed, breakpointId })
       }
       default:
         return aiToolError(`Unknown instatic tool: ${toolName}`)
diff --git a/src/admin/pages/site/agent/index.ts b/src/admin/pages/site/agent/index.ts
index 60f0249d5..8c132d2c6 100644
--- a/src/admin/pages/site/agent/index.ts
+++ b/src/admin/pages/site/agent/index.ts
@@ -23,7 +23,13 @@ export { buildCurrentPageContext } from './pageContext'
 
 // Browser-side tool dispatch + render evidence + markdown rendering.
 export { executeAgentTool } from './executor'
-export { captureAgentRenderSnapshot, SnapshotNodeNotFoundError } from './renderEvidence'
+export {
+  captureAgentRenderSnapshot,
+  findAgentRenderFrame,
+  waitForAgentRenderFrame,
+  SnapshotNodeNotFoundError,
+} from './renderEvidence'
+export type { AgentRenderFrameQuery } from './renderEvidence'
 export { renderMarkdownToHtml } from './markdown'
 
 // Store handle wiring.
diff --git a/src/admin/pages/site/agent/renderEvidence.ts b/src/admin/pages/site/agent/renderEvidence.ts
index dcc45320d..9c2d7a32d 100644
--- a/src/admin/pages/site/agent/renderEvidence.ts
+++ b/src/admin/pages/site/agent/renderEvidence.ts
@@ -11,6 +11,8 @@ import { getErrorMessage } from '@core/utils/errorMessage'
 
 const MAX_TEXT_LENGTH = 300
 const OVERFLOW_TOLERANCE_PX = 2
+const FRAME_WAIT_TIMEOUT_MS = 5_000
+const FRAME_WAIT_POLL_MS = 16
 
 // Anthropic rejects any image dimension > 8000px outright (400), and internally
 // downsizes the long edge to ~1568px before the model ever sees it. So we cap
@@ -29,6 +31,23 @@ interface CaptureRenderSnapshotOptions {
   nodeId?: string
   /** When false, only layout is collected (no html-to-image) — faster. */
   captureScreenshot?: boolean
+  /** Exact visible or transient frame selected by the browser executor. */
+  frame?: HTMLElement
+}
+
+interface CaptureRegion {
+  rect: DOMRectReadOnly
+  width: number
+  height: number
+  scrollWidth: number
+  scrollHeight: number
+}
+
+export interface AgentRenderFrameQuery {
+  breakpointId?: string
+  source?: 'visible' | 'transient'
+  requestId?: string
+  requireReady?: boolean
 }
 
 /**
@@ -67,55 +86,114 @@ export async function captureAgentRenderSnapshot({
   breakpointId,
   nodeId,
   captureScreenshot = true,
+  frame: selectedFrame,
 }: CaptureRenderSnapshotOptions = {}): Promise<AgentRenderSnapshotPayload | null> {
   if (typeof document === 'undefined') return null
 
-  const frame = findCanvasFrame(breakpointId)
+  const frame = selectedFrame ?? findAgentRenderFrame({ breakpointId })
   if (!frame) return null
+  const frameBreakpointId = agentRenderFrameBreakpointId(frame)
+  if (breakpointId && frameBreakpointId !== breakpointId) return null
 
-  const resolvedBreakpointId = frame.dataset.breakpointId ?? breakpointId ?? ''
+  const resolvedBreakpointId = frameBreakpointId || breakpointId || ''
 
-  // Each breakpoint renders the page inside its own <iframe>; `data-breakpoint-id`
-  // is on the host wrapper, but the actual nodes (`data-node-id`) live in the
-  // iframe's document. So search + capture against `contentDocument`, NOT the
-  // host frame (which is why scoped node lookups previously never matched).
+  // Each breakpoint renders the page inside its own <iframe>; the visible host
+  // uses `data-breakpoint-id` and the transient host uses a dedicated agent
+  // attribute, but actual nodes (`data-node-id`) always live in the iframe's
+  // document. So search + capture against `contentDocument`, NOT the host frame.
   const iframe = frame.querySelector<HTMLIFrameElement>('iframe')
   const doc = iframe?.contentDocument ?? null
   if (!doc?.body) return null // frame collapsed or iframe not mounted yet
 
-  // The capture root is the iframe body, or — when scoped — the target node.
-  let root: HTMLElement = doc.body
+  // Full-page evidence is framed by the iframe viewport, not by the authored
+  // body box. A body may intentionally be centered, transformed, or capped by
+  // max-width; none of those styles change the browser viewport the model is
+  // meant to inspect. Rasterising <html> also retains the document-canvas
+  // background propagation rules that are lost when the body is cloned alone.
+  const documentRegion = measureDocumentRegion(doc)
+  let root: HTMLElement = doc.documentElement
+  let captureRegion = documentRegion
   if (nodeId) {
     const target = doc.querySelector<HTMLElement>(`[data-node-id="${cssAttrEscape(nodeId)}"]`)
     if (!target) throw new SnapshotNodeNotFoundError(nodeId, resolvedBreakpointId)
     root = target
+    captureRegion = measureElementRegion(target)
   }
 
-  const layout = collectLayoutReport(root, resolvedBreakpointId, nodeId)
+  const layout = collectLayoutReport(root, captureRegion, resolvedBreakpointId, nodeId)
   const screenshot = captureScreenshot
-    ? await captureElementScreenshot(root)
+    ? await captureElementScreenshot(root, captureRegion, documentRegion)
     : unavailableScreenshot('Screenshot capture not requested.')
 
   return {
     breakpointId: resolvedBreakpointId,
     ...(nodeId ? { nodeId } : {}),
     label: nodeId ? `${resolvedBreakpointId} · ${nodeId}` : resolvedBreakpointId,
-    width: Math.round(root.getBoundingClientRect().width),
+    width: Math.round(captureRegion.width),
     capturedAt: Date.now(),
     screenshot,
     layout,
   }
 }
 
-function findCanvasFrame(breakpointId?: string): HTMLElement | null {
+/** Find an exact visible canvas frame or one one-shot offscreen capture frame. */
+export function findAgentRenderFrame({
+  breakpointId,
+  source = 'visible',
+  requestId,
+  requireReady = false,
+}: AgentRenderFrameQuery = {}): HTMLElement | null {
   if (typeof document === 'undefined') return null
-  if (breakpointId) {
-    const exact = document.querySelector<HTMLElement>(
-      `[data-breakpoint-id="${cssAttrEscape(breakpointId)}"]`,
-    )
-    if (exact) return exact
+
+  const breakpointAttribute = source === 'transient'
+    ? 'data-agent-snapshot-breakpoint-id'
+    : 'data-breakpoint-id'
+  const breakpointSelector = breakpointId
+    ? `[${breakpointAttribute}="${cssAttrEscape(breakpointId)}"]`
+    : `[${breakpointAttribute}]`
+  const sourceSelector = source === 'transient' ? '[data-agent-snapshot-frame]' : ''
+  const requestSelector = requestId
+    ? `[data-agent-snapshot-request-id="${cssAttrEscape(requestId)}"]`
+    : ''
+  const candidates = document.querySelectorAll<HTMLElement>(
+    `${breakpointSelector}${sourceSelector}${requestSelector}`,
+  )
+
+  for (const frame of candidates) {
+    if (!requireReady || isAgentRenderFrameReady(frame, requestId)) return frame
+  }
+  return null
+}
+
+/** Wait for React to mount and commit an exact canvas iframe. */
+export async function waitForAgentRenderFrame(
+  query: AgentRenderFrameQuery,
+  timeoutMs: number = FRAME_WAIT_TIMEOUT_MS,
+): Promise<HTMLElement | null> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() <= deadline) {
+    const frame = findAgentRenderFrame({ ...query, requireReady: true })
+    if (frame) return frame
+    await new Promise<void>((resolve) => setTimeout(resolve, FRAME_WAIT_POLL_MS))
   }
-  return document.querySelector<HTMLElement>('[data-breakpoint-id]')
+  return null
+}
+
+function isAgentRenderFrameReady(frame: HTMLElement, requestId?: string): boolean {
+  const breakpointId = agentRenderFrameBreakpointId(frame)
+  const iframe = frame.querySelector<HTMLIFrameElement>('iframe')
+  // Every IframeFrameSurface first exposes a short-lived about:blank document;
+  // the load marker identifies the final srcDoc document for visible and
+  // transient frames alike. Without this gate, a snapshot requested while a
+  // frame is mounting can capture the detached initial body.
+  if (iframe?.dataset.instaticCanvasDocumentLoaded !== 'true') return false
+  const body = iframe?.contentDocument?.body
+  if (!breakpointId || !body || body.dataset.breakpointId !== breakpointId) return false
+  return !requestId || iframe.dataset.agentSnapshotReady === requestId
+}
+
+function agentRenderFrameBreakpointId(frame: HTMLElement): string {
+  return frame.dataset.breakpointId ?? frame.dataset.agentSnapshotBreakpointId ?? ''
 }
 
 function cssAttrEscape(value: string): string {
@@ -125,26 +203,27 @@ function cssAttrEscape(value: string): string {
 
 function collectLayoutReport(
   root: HTMLElement,
+  captureRegion: CaptureRegion,
   breakpointId: string,
   nodeId?: string,
 ): AgentLayoutReportContext {
-  const rootRect = root.getBoundingClientRect()
+  const rootRect = captureRegion.rect
   const viewport = {
-    width: Math.round(rootRect.width || root.clientWidth),
-    height: Math.round(rootRect.height || root.clientHeight),
-    scrollWidth: root.scrollWidth,
-    scrollHeight: root.scrollHeight,
+    width: Math.round(captureRegion.width),
+    height: Math.round(captureRegion.height),
+    scrollWidth: captureRegion.scrollWidth,
+    scrollHeight: captureRegion.scrollHeight,
   }
 
   const warnings: AgentLayoutWarningContext[] = []
-  if (root.scrollWidth > root.clientWidth + OVERFLOW_TOLERANCE_PX) {
+  if (captureRegion.scrollWidth > captureRegion.width + OVERFLOW_TOLERANCE_PX) {
     warnings.push({
       type: 'horizontal-overflow',
       severity: 'warning',
       message: 'The captured region has horizontal overflow.',
     })
   }
-  if (root.scrollHeight > root.clientHeight + OVERFLOW_TOLERANCE_PX) {
+  if (captureRegion.scrollHeight > captureRegion.height + OVERFLOW_TOLERANCE_PX) {
     warnings.push({
       type: 'vertical-overflow',
       severity: 'info',
@@ -259,7 +338,11 @@ function collectImageLayout(
     rect: relativeRect(frameRect, img.getBoundingClientRect()),
   }
 
-  if (!img.complete || img.naturalWidth === 0 || img.naturalHeight === 0) {
+  // `loading="lazy"` images in a transient offscreen frame may intentionally
+  // be incomplete. html-to-image makes its cloned images eager and embeds them
+  // before `toCanvas()` resolves; only a completed zero-dimension image is
+  // evidence of a real load failure.
+  if (img.complete && (img.naturalWidth === 0 || img.naturalHeight === 0)) {
     warnings.push({
       type: 'broken-image',
       severity: 'warning',
@@ -271,11 +354,14 @@ function collectImageLayout(
   return image
 }
 
-async function captureElementScreenshot(root: HTMLElement): Promise<AgentScreenshotContext> {
+async function captureElementScreenshot(
+  root: HTMLElement,
+  captureRegion: CaptureRegion,
+  documentRegion: CaptureRegion,
+): Promise<AgentScreenshotContext> {
   try {
-    const { toPng } = await import('html-to-image')
-    const rect = root.getBoundingClientRect()
-    if (rect.width <= 0 || rect.height <= 0) {
+    const { toCanvas } = await import('html-to-image')
+    if (captureRegion.width <= 0 || captureRegion.height <= 0) {
       return unavailableScreenshot('Captured element has no visible size.')
     }
 
@@ -283,23 +369,59 @@ async function captureElementScreenshot(root: HTMLElement): Promise<AgentScreens
     // page is constrained by its height; a wide one by its width.
     const pixelRatio = Math.min(
       1,
-      MAX_IMAGE_EDGE / Math.max(1, rect.width),
-      MAX_IMAGE_EDGE / Math.max(1, rect.height),
+      MAX_IMAGE_EDGE / Math.max(1, captureRegion.width),
+      MAX_IMAGE_EDGE / Math.max(1, captureRegion.height),
     )
-    const dataUrl = await toPng(root, {
+
+    // Always rasterise the iframe document element. A node on its own has no
+    // ancestor painting context, while a cloned body omits the <html>/viewport
+    // backdrop (including CSS body-background propagation). For node captures,
+    // translate that complete document behind a target-sized canvas instead.
+    const documentElement = root.ownerDocument.documentElement
+    const options: Parameters<typeof toCanvas>[1] = {
       cacheBust: true,
       pixelRatio,
-      backgroundColor: '#ffffff',
       imagePlaceholder: '',
-    })
+      width: captureRegion.width,
+      height: captureRegion.height,
+      canvasWidth: captureRegion.width,
+      canvasHeight: captureRegion.height,
+    }
+    if (root !== documentElement) {
+      options.style = {
+        width: `${documentRegion.width}px`,
+        height: `${documentRegion.height}px`,
+        transform: `translate(${formatPixelOffset(documentRegion.rect.left - captureRegion.rect.left)}, ${formatPixelOffset(documentRegion.rect.top - captureRegion.rect.top)})`,
+        transformOrigin: 'top left',
+      }
+    }
+
+    const canvas = await toCanvas(documentElement, options)
+    const context = canvas.getContext('2d')
+    if (!context) throw new Error('Screenshot canvas does not expose a 2D context.')
+
+    // Composite the fallback AFTER html-to-image has painted the authored page.
+    // `backgroundColor` cannot be used here: html-to-image also writes it onto
+    // the cloned root, which replaces the body's real background. Destination-
+    // over fills only pixels the page intentionally left transparent.
+    context.save()
+    context.globalCompositeOperation = 'destination-over'
+    context.fillStyle = '#ffffff'
+    context.fillRect(0, 0, canvas.width, canvas.height)
+    context.restore()
+
+    const dataUrl = canvas.toDataURL('image/png')
     const marker = 'base64,'
     const markerIndex = dataUrl.indexOf(marker)
     return {
       status: 'ok',
       mimeType: 'image/png',
       data: markerIndex >= 0 ? dataUrl.slice(markerIndex + marker.length) : dataUrl,
-      width: Math.round(rect.width * pixelRatio),
-      height: Math.round(rect.height * pixelRatio),
+      // Report the PNG's real integer dimensions. Canvas WebIDL conversion can
+      // truncate a fractional scaled edge, so recomputing with Math.round()
+      // can disagree with the bytes attached to the tool result.
+      width: canvas.width,
+      height: canvas.height,
     }
   } catch (err) {
     return {
@@ -309,6 +431,96 @@ async function captureElementScreenshot(root: HTMLElement): Promise<AgentScreens
   }
 }
 
+function measureElementRegion(element: HTMLElement): CaptureRegion {
+  const rect = element.getBoundingClientRect()
+  return {
+    rect,
+    width: rect.width,
+    height: rect.height,
+    scrollWidth: element.scrollWidth,
+    scrollHeight: element.scrollHeight,
+  }
+}
+
+function measureDocumentRegion(doc: Document): CaptureRegion {
+  const html = doc.documentElement
+  const body = doc.body
+  const view = doc.defaultView
+  const htmlRect = html.getBoundingClientRect()
+  const bodyRect = body.getBoundingClientRect()
+  const viewportWidth = firstPositiveFinite(
+    view?.innerWidth,
+    html.clientWidth,
+    body.clientWidth,
+    htmlRect.width,
+    bodyRect.width,
+  )
+  const viewportHeight = firstPositiveFinite(
+    view?.innerHeight,
+    html.clientHeight,
+    body.clientHeight,
+    htmlRect.height,
+    bodyRect.height,
+  )
+  const scrollX = firstFinite(view?.scrollX, view?.pageXOffset, html.scrollLeft, body.scrollLeft)
+  const scrollY = firstFinite(view?.scrollY, view?.pageYOffset, html.scrollTop, body.scrollTop)
+  const scrollWidth = maxFinite(
+    viewportWidth,
+    html.scrollWidth,
+    body.scrollWidth,
+    html.offsetWidth,
+    body.offsetWidth,
+  )
+  const scrollHeight = maxFinite(
+    viewportHeight,
+    html.scrollHeight,
+    body.scrollHeight,
+    html.offsetHeight,
+    body.offsetHeight,
+    htmlRect.bottom + scrollY,
+    bodyRect.bottom + scrollY,
+  )
+
+  return {
+    rect: createRect(-scrollX, -scrollY, viewportWidth, scrollHeight),
+    width: viewportWidth,
+    height: scrollHeight,
+    scrollWidth,
+    scrollHeight,
+  }
+}
+
+function firstPositiveFinite(...values: Array<number | undefined>): number {
+  return values.find((value) => value !== undefined && Number.isFinite(value) && value > 0) ?? 0
+}
+
+function firstFinite(...values: Array<number | undefined>): number {
+  return values.find((value) => value !== undefined && Number.isFinite(value)) ?? 0
+}
+
+function maxFinite(...values: Array<number | undefined>): number {
+  return Math.max(0, ...values.filter((value): value is number => value !== undefined && Number.isFinite(value)))
+}
+
+function createRect(x: number, y: number, width: number, height: number): DOMRectReadOnly {
+  return {
+    x,
+    y,
+    width,
+    height,
+    top: y,
+    right: x + width,
+    bottom: y + height,
+    left: x,
+    toJSON: () => ({ x, y, width, height }),
+  }
+}
+
+function formatPixelOffset(value: number): string {
+  const normalized = Object.is(value, -0) ? 0 : round(value)
+  return `${normalized}px`
+}
+
 function unavailableScreenshot(error: string): AgentScreenshotContext {
   return {
     status: 'unavailable',
diff --git a/src/admin/pages/site/agent/renderSnapshotAtBreakpoint.ts b/src/admin/pages/site/agent/renderSnapshotAtBreakpoint.ts
new file mode 100644
index 000000000..ff91feb6f
--- /dev/null
+++ b/src/admin/pages/site/agent/renderSnapshotAtBreakpoint.ts
@@ -0,0 +1,83 @@
+/**
+ * Exact-breakpoint orchestration for `site_render_snapshot`.
+ *
+ * Every capture renders once through CanvasRoot's transient AgentSnapshotFrame
+ * at the configured viewport width. That deterministic path can wait for async
+ * preview data/media and never depends on whether a visible frame happens to
+ * be mounted, collapsed, clamped, or in Live mode. The transient slot is
+ * serialized because providers may issue tool calls in parallel while
+ * CanvasRoot intentionally owns only one such frame.
+ */
+
+import { nanoid } from 'nanoid'
+import {
+  aiToolError,
+  RenderSnapshotInputSchema,
+  type AiToolOutput,
+} from '@core/ai'
+import type { Static } from '@core/utils/typeboxHelpers'
+import type { EditorStore } from '@site/store/types'
+import { getAgentStoreApi } from './storeRef'
+import { runRenderSnapshot } from './renderSnapshotTool'
+import { waitForAgentRenderFrame } from './renderEvidence'
+
+type RenderSnapshotAtBreakpointInput = Static<typeof RenderSnapshotInputSchema> & {
+  breakpointId: string
+  captureScreenshot?: boolean
+}
+
+const getStoreState = (): EditorStore => getAgentStoreApi<EditorStore>().getState()
+
+// The tail never rejects, so one failed capture cannot poison later requests.
+let transientSnapshotCaptureTail: Promise<void> = Promise.resolve()
+
+async function withTransientSnapshotFrame<T>(capture: () => Promise<T>): Promise<T> {
+  const precedingCapture = transientSnapshotCaptureTail
+  let releaseCapture!: () => void
+  transientSnapshotCaptureTail = new Promise<void>((resolve) => {
+    releaseCapture = resolve
+  })
+
+  await precedingCapture
+  try {
+    return await capture()
+  } finally {
+    releaseCapture()
+  }
+}
+
+export async function runRenderSnapshotAtBreakpoint(
+  input: RenderSnapshotAtBreakpointInput,
+): Promise<AiToolOutput> {
+  const store = getStoreState()
+  const breakpoint = store.site?.breakpoints.find(
+    (candidate) => candidate.id === input.breakpointId,
+  )
+  if (!breakpoint) return aiToolError(`Breakpoint not found: ${input.breakpointId}`)
+
+  return withTransientSnapshotFrame(async () => {
+    const requestId = nanoid()
+    getStoreState().setAgentSnapshotCaptureRequest({
+      requestId,
+      breakpointId: input.breakpointId,
+    })
+    try {
+      const transientFrame = await waitForAgentRenderFrame({
+        breakpointId: input.breakpointId,
+        source: 'transient',
+        requestId,
+      })
+      if (!transientFrame) {
+        return aiToolError(
+          `Canvas frame for breakpoint ${input.breakpointId} did not become ready.`,
+        )
+      }
+      return await runRenderSnapshot(input, transientFrame)
+    } finally {
+      const latest = getStoreState()
+      if (latest.agentSnapshotCaptureRequest?.requestId === requestId) {
+        latest.setAgentSnapshotCaptureRequest(null)
+      }
+    }
+  })
+}
diff --git a/src/admin/pages/site/agent/renderSnapshotTool.ts b/src/admin/pages/site/agent/renderSnapshotTool.ts
index 9d187f1fc..39ccab24b 100644
--- a/src/admin/pages/site/agent/renderSnapshotTool.ts
+++ b/src/admin/pages/site/agent/renderSnapshotTool.ts
@@ -15,6 +15,7 @@ type RenderSnapshotToolInput = Static<typeof RenderSnapshotInputSchema> & {
 
 export async function runRenderSnapshot(
   input: RenderSnapshotToolInput,
+  frame?: HTMLElement,
 ): Promise<AiToolOutput> {
   // Default true so a direct (non-server) invocation still works; the AI loop
   // always sets this explicitly from the model's vision capability.
@@ -25,6 +26,7 @@ export async function runRenderSnapshot(
       breakpointId: input.breakpointId,
       nodeId: input.nodeId,
       captureScreenshot,
+      frame,
     })
   } catch (err) {
     if (err instanceof SnapshotNodeNotFoundError) return aiToolError(err.message)
diff --git a/src/admin/pages/site/canvas/AgentSnapshotFrame.module.css b/src/admin/pages/site/canvas/AgentSnapshotFrame.module.css
new file mode 100644
index 000000000..26c8f0d68
--- /dev/null
+++ b/src/admin/pages/site/canvas/AgentSnapshotFrame.module.css
@@ -0,0 +1,8 @@
+.frame {
+  position: fixed;
+  inset-block-start: 0;
+  inset-inline-start: -100000px;
+  inline-size: max-content;
+  block-size: max-content;
+  pointer-events: none;
+}
diff --git a/src/admin/pages/site/canvas/AgentSnapshotFrame.tsx b/src/admin/pages/site/canvas/AgentSnapshotFrame.tsx
new file mode 100644
index 000000000..fcca136b2
--- /dev/null
+++ b/src/admin/pages/site/canvas/AgentSnapshotFrame.tsx
@@ -0,0 +1,234 @@
+/**
+ * One-shot, offscreen canvas frame used by `site_render_snapshot`.
+ *
+ * The visible editor intentionally omits some viewport iframes: live mode only
+ * mounts the active viewport, design frames may be collapsed, and a persisted
+ * breakpoint may opt out through `previewFrame:false`. Snapshot capture must
+ * not change any of that user-owned UI state, so CanvasRoot mounts this exact-
+ * width frame only while the agent is waiting for it.
+ *
+ * Runtime scripts are deliberately absent. A visual evidence read must not run
+ * authored behavior a second time or let an arbitrary script mutate the
+ * transient DOM before it is captured.
+ */
+
+import { use, useEffect, useState } from 'react'
+import { createPortal } from 'react-dom'
+import type { Breakpoint, Page } from '@core/page-tree'
+import type { TemplateRenderDataContext } from '@core/templates/dynamicBindings'
+import { CanvasComposedTree } from './CanvasComposedTree'
+import {
+  CanvasBreakpointContext,
+  CanvasDocumentContext,
+  CanvasFrameElementContext,
+  CanvasTemplateContext,
+} from './CanvasContexts'
+import { IframeFrameSurface } from './IframeFrameSurface'
+import {
+  CanvasPreviewReadinessContext,
+  createCanvasPreviewReadiness,
+  type CanvasPreviewReadiness,
+} from './CanvasPreviewReadiness'
+import styles from './AgentSnapshotFrame.module.css'
+
+const DOM_QUIET_MS = 32
+
+interface AgentSnapshotFrameProps {
+  requestId: string
+  page: Page
+  breakpoint: Breakpoint
+  templateContext?: TemplateRenderDataContext
+  templateContextLoading: boolean
+}
+
+export function AgentSnapshotFrame({
+  requestId,
+  page,
+  breakpoint,
+  templateContext,
+  templateContextLoading,
+}: AgentSnapshotFrameProps) {
+  const [previewReadiness] = useState(createCanvasPreviewReadiness)
+  if (typeof document === 'undefined') return null
+
+  return createPortal(
+    <CanvasPreviewReadinessContext.Provider value={previewReadiness}>
+      <div
+        className={styles.frame}
+        data-agent-snapshot-frame=""
+        data-agent-snapshot-request-id={requestId}
+        data-agent-snapshot-breakpoint-id={breakpoint.id}
+        aria-hidden="true"
+        inert
+      >
+        <IframeFrameSurface
+          breakpointId={breakpoint.id}
+          width={breakpoint.width}
+          dataAttrs={{ 'data-agent-snapshot-iframe': requestId }}
+        >
+          <CanvasTemplateContext.Provider value={templateContext}>
+            <CanvasBreakpointContext.Provider value={breakpoint.id}>
+              <CanvasComposedTree page={page} />
+              {!templateContextLoading ? (
+                <AgentSnapshotReadyMarker
+                  requestId={requestId}
+                  previewReadiness={previewReadiness}
+                />
+              ) : null}
+            </CanvasBreakpointContext.Provider>
+          </CanvasTemplateContext.Provider>
+        </IframeFrameSurface>
+      </div>
+    </CanvasPreviewReadinessContext.Provider>,
+    document.body,
+  )
+}
+
+/** Marks the host iframe after async preview data, fonts, and DOM settle. */
+function AgentSnapshotReadyMarker({
+  requestId,
+  previewReadiness,
+}: {
+  requestId: string
+  previewReadiness: CanvasPreviewReadiness
+}) {
+  const iframeDocument = use(CanvasDocumentContext)
+  const iframe = use(CanvasFrameElementContext)
+
+  useEffect(() => {
+    if (!iframeDocument || !iframe) return
+    const controller = new AbortController()
+    void markAgentSnapshotFrameReady(
+      iframe,
+      iframeDocument,
+      requestId,
+      previewReadiness,
+      controller.signal,
+    )
+    return () => {
+      cleanupAgentSnapshotFrameReady(iframe, requestId, controller)
+    }
+  }, [iframe, iframeDocument, previewReadiness, requestId])
+
+  return null
+}
+
+// Keep cross-document mutation outside the React component so the compiler can
+// treat the context values as read-only React input.
+async function markAgentSnapshotFrameReady(
+  iframe: HTMLIFrameElement,
+  iframeDocument: Document,
+  requestId: string,
+  previewReadiness: CanvasPreviewReadiness,
+  signal: AbortSignal,
+): Promise<void> {
+  // Let descendant effects register their first data/media requests before an
+  // initially-idle tracker can be mistaken for a finished preview.
+  if (!await waitForDelay(0, signal)) return
+
+  while (!signal.aborted) {
+    if (!await previewReadiness.waitUntilIdle(signal)) return
+    const settledRevision = previewReadiness.revision()
+    if (!await waitForDocumentQuiet(iframeDocument, signal)) return
+    if (
+      previewReadiness.pendingCount() !== 0 ||
+      previewReadiness.revision() !== settledRevision
+    ) continue
+
+    const fonts = iframeDocument.fonts
+    if (fonts?.status === 'loading' && !await waitForPromise(fonts.ready, signal)) return
+    if (!await waitForDocumentQuiet(iframeDocument, signal)) return
+    // A settled data request can add more asynchronous preview work during the
+    // resource phase. Restart so the final committed DOM is included as well.
+    if (
+      previewReadiness.pendingCount() === 0 &&
+      previewReadiness.revision() === settledRevision
+    ) break
+  }
+
+  if (signal.aborted) return
+  // Readiness metadata belongs to editor chrome, not authored <html>/<body>.
+  // User selectors therefore see exactly the DOM that will publish.
+  iframe.dataset.agentSnapshotReady = requestId
+}
+
+function cleanupAgentSnapshotFrameReady(
+  iframe: HTMLIFrameElement,
+  requestId: string,
+  controller: AbortController,
+): void {
+  controller.abort()
+  if (iframe.dataset.agentSnapshotReady === requestId) {
+    delete iframe.dataset.agentSnapshotReady
+  }
+}
+
+function waitForDocumentQuiet(
+  iframeDocument: Document,
+  signal: AbortSignal,
+): Promise<boolean> {
+  if (signal.aborted) return Promise.resolve(false)
+  const MutationObserverCtor = iframeDocument.defaultView?.MutationObserver ?? MutationObserver
+
+  return new Promise<boolean>((resolve) => {
+    let finished = false
+    let quietTimer: ReturnType<typeof setTimeout> | undefined
+    const observer = new MutationObserverCtor(() => scheduleQuietWindow())
+    const finish = (settled: boolean) => {
+      if (finished) return
+      finished = true
+      if (quietTimer !== undefined) clearTimeout(quietTimer)
+      observer.disconnect()
+      signal.removeEventListener('abort', onAbort)
+      resolve(settled)
+    }
+    const onAbort = () => finish(false)
+    const scheduleQuietWindow = () => {
+      if (finished) return
+      if (quietTimer !== undefined) clearTimeout(quietTimer)
+      quietTimer = setTimeout(() => finish(true), DOM_QUIET_MS)
+    }
+
+    observer.observe(iframeDocument.documentElement, {
+      attributes: true,
+      characterData: true,
+      childList: true,
+      subtree: true,
+    })
+    signal.addEventListener('abort', onAbort, { once: true })
+    scheduleQuietWindow()
+  })
+}
+
+function waitForPromise(promise: Promise<unknown>, signal: AbortSignal): Promise<boolean> {
+  if (signal.aborted) return Promise.resolve(false)
+  return new Promise<boolean>((resolve) => {
+    let finished = false
+    const finish = (settled: boolean) => {
+      if (finished) return
+      finished = true
+      signal.removeEventListener('abort', onAbort)
+      resolve(settled)
+    }
+    const onAbort = () => finish(false)
+    signal.addEventListener('abort', onAbort, { once: true })
+    void promise.then(() => finish(true), () => finish(true))
+  })
+}
+
+function waitForDelay(delayMs: number, signal: AbortSignal): Promise<boolean> {
+  if (signal.aborted) return Promise.resolve(false)
+  return new Promise<boolean>((resolve) => {
+    let finished = false
+    const timer = setTimeout(() => finish(true), delayMs)
+    const finish = (settled: boolean) => {
+      if (finished) return
+      finished = true
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      resolve(settled)
+    }
+    const onAbort = () => finish(false)
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
diff --git a/src/admin/pages/site/canvas/CanvasComposedTree.tsx b/src/admin/pages/site/canvas/CanvasComposedTree.tsx
index 88f2e4889..a97a6b4dc 100644
--- a/src/admin/pages/site/canvas/CanvasComposedTree.tsx
+++ b/src/admin/pages/site/canvas/CanvasComposedTree.tsx
@@ -14,9 +14,10 @@
  * Body ownership mirrors the publisher: the published `<body>` is the OUTERMOST
  * wrapper's body element (the inner document's `base.body` is dropped and its
  * children spliced in — inner body classes are not preserved). So in the wrapped
- * case we apply the outermost wrapper body's classes to the iframe `<body>` and
- * render the active document as its body CHILDREN, rather than letting the inner
- * body claim the iframe body with classes the published page would not carry.
+ * case we apply the outermost wrapper body's classes, inline styles, and safe
+ * HTML attributes to the iframe `<body>` and render the active document as its
+ * body CHILDREN, rather than letting the inner body claim presentation the
+ * published page would not carry.
  *
  * When nothing wraps the document (editing the `everywhere` layout itself, or a
  * site with no matching template), it renders exactly as before — a plain
@@ -25,14 +26,17 @@
  * `OutletEditor`.
  */
 
-import { use, useEffect, useRef, type ReactNode } from 'react'
+import { use, useEffect, type ReactNode } from 'react'
 import type { BaseNode, Page } from '@core/page-tree'
 import { classNamesForClassIds } from '@core/page-tree'
 import { useEditorStore } from '@site/store/store'
 import { ReadOnlyNodeTree } from '@modules/base/utils/ReadOnlyNodeTree'
+import { htmlAttributesForReact } from '@modules/base/shared/htmlAttributes'
+import { useResponsiveBackgroundStyle } from '@admin/pages/media/hooks/useResponsiveBackgroundStyle'
 import { NodeRenderer } from './NodeRenderer'
 import { resolveEditorWrapperTemplates } from './canvasComposition'
-import { CanvasTemplateContext } from './CanvasContexts'
+import { CanvasDocumentContext, CanvasTemplateContext } from './CanvasContexts'
+import { applyIframeBodyPresentation } from './iframeBodyPresentation'
 
 const NO_WRAPPERS: Page[] = []
 
@@ -50,6 +54,7 @@ export function CanvasComposedTree({ page }: CanvasComposedTreeProps) {
   // Templates wrapping the active document (outermost-first). A Visual
   // Component edit surface is never a published route, so it is never wrapped.
   const wrappers = !isVcMode && site ? resolveEditorWrapperTemplates(site, page) : NO_WRAPPERS
+  const outerBody = wrappers[0]?.nodes[wrappers[0].rootNodeId]
 
   // No wrapping templates → render the document exactly as before; its own
   // base.body claims the iframe <body>.
@@ -82,45 +87,49 @@ export function CanvasComposedTree({ page }: CanvasComposedTreeProps) {
     )
   }
 
-  // Mirror the outermost wrapper body's classes onto the iframe <body>, exactly
-  // as the published document would carry them.
-  const outerBody = wrappers[0]?.nodes[wrappers[0].rootNodeId]
+  // Mirror the outermost wrapper body's classes + inline styles onto the
+  // iframe <body>, exactly as the published document would carry them.
   const bodyClassName = outerBody
     ? classNamesForClassIds(styleRules, outerBody.classIds).join(' ')
     : ''
 
   return (
     <>
-      <IframeBodyClassName className={bodyClassName} />
+      <IframeBodyPresentationOwner
+        className={bodyClassName}
+        inlineStyles={outerBody?.inlineStyles}
+        htmlAttributes={outerBody?.props.htmlAttributes}
+      />
       {composed}
     </>
   )
 }
 
 /**
- * Apply `className` to the host iframe's `<body>` element while mounted (and
- * restore it on unmount). A `display: contents` probe gives the effect a ref
- * into the iframe document without contributing any layout — the same technique
- * `base.body`'s editor uses. Only used in the wrapped case, where no `base.body`
- * editor runs to own the iframe body.
+ * Apply the outer body's presentation to the host iframe's `<body>` while
+ * mounted (and restore it on unmount). The frame supplies its final srcDoc
+ * through context, so this owner contributes no editor-only body child. Only
+ * used in the wrapped case, where no `base.body` editor runs to own the body.
  */
-function IframeBodyClassName({ className }: { className: string }) {
-  const probeRef = useRef<HTMLSpanElement | null>(null)
+function IframeBodyPresentationOwner({
+  className,
+  inlineStyles,
+  htmlAttributes,
+}: {
+  className: string
+  inlineStyles?: BaseNode['inlineStyles']
+  htmlAttributes?: unknown
+}) {
+  const iframeDocument = use(CanvasDocumentContext)
+  const style = useResponsiveBackgroundStyle(inlineStyles)
   useEffect(() => {
-    const body = probeRef.current?.ownerDocument?.body
+    const body = iframeDocument?.body
     if (!body) return
-    const previous = body.className
-    body.className = className
-    return () => {
-      body.className = previous
-    }
-  }, [className])
-  return (
-    <span
-      ref={probeRef}
-      aria-hidden="true"
-      style={{ display: 'contents' }}
-      data-instatic-wrapper-body-probe=""
-    />
-  )
+    return applyIframeBodyPresentation(body, {
+      className,
+      style,
+      attributes: htmlAttributesForReact(htmlAttributes),
+    })
+  }, [className, htmlAttributes, iframeDocument, style])
+  return null
 }
diff --git a/src/admin/pages/site/canvas/CanvasContexts.ts b/src/admin/pages/site/canvas/CanvasContexts.ts
index 056bead38..98de4fad6 100644
--- a/src/admin/pages/site/canvas/CanvasContexts.ts
+++ b/src/admin/pages/site/canvas/CanvasContexts.ts
@@ -25,3 +25,7 @@ export const CanvasViewportActionsContext =
 
 export const CanvasBreakpointContext = createContext<string | undefined>(undefined)
 export const CanvasTemplateContext = createContext<TemplateRenderDataContext | undefined>(undefined)
+/** Final srcDoc document owned by the nearest IframeFrameSurface. */
+export const CanvasDocumentContext = createContext<Document | null>(null)
+/** Host iframe element owned by the nearest IframeFrameSurface. */
+export const CanvasFrameElementContext = createContext<HTMLIFrameElement | null>(null)
diff --git a/src/admin/pages/site/canvas/CanvasPreviewReadiness.ts b/src/admin/pages/site/canvas/CanvasPreviewReadiness.ts
new file mode 100644
index 000000000..9dd865b0b
--- /dev/null
+++ b/src/admin/pages/site/canvas/CanvasPreviewReadiness.ts
@@ -0,0 +1,63 @@
+/**
+ * Tracks asynchronous work that can change a canvas preview after its first
+ * React commit. Visible editor frames do not provide this context; the Agent's
+ * one-shot evidence frame does, so only that read path waits for data/media
+ * lookups before it captures pixels and layout.
+ */
+
+import { createContext } from 'react'
+
+export interface CanvasPreviewReadiness {
+  track: (task: Promise<unknown>) => void
+  waitUntilIdle: (signal: AbortSignal) => Promise<boolean>
+  pendingCount: () => number
+  revision: () => number
+}
+
+export const CanvasPreviewReadinessContext =
+  createContext<CanvasPreviewReadiness | null>(null)
+
+export function createCanvasPreviewReadiness(): CanvasPreviewReadiness {
+  let pending = 0
+  let revision = 0
+  const idleListeners = new Set<() => void>()
+
+  const release = () => {
+    pending = Math.max(0, pending - 1)
+    revision += 1
+    if (pending !== 0) return
+    for (const listener of idleListeners) listener()
+    idleListeners.clear()
+  }
+
+  return {
+    track(task) {
+      pending += 1
+      revision += 1
+      // Observe both branches so a failed preview request still releases the
+      // barrier and never creates an unhandled rejection of our own.
+      void task.then(release, release)
+    },
+    waitUntilIdle(signal) {
+      if (pending === 0) return Promise.resolve(true)
+      if (signal.aborted) return Promise.resolve(false)
+
+      return new Promise<boolean>((resolve) => {
+        let settled = false
+        const finish = (idle: boolean) => {
+          if (settled) return
+          settled = true
+          idleListeners.delete(onIdle)
+          signal.removeEventListener('abort', onAbort)
+          resolve(idle)
+        }
+        const onIdle = () => finish(true)
+        const onAbort = () => finish(false)
+        idleListeners.add(onIdle)
+        signal.addEventListener('abort', onAbort, { once: true })
+      })
+    },
+    pendingCount: () => pending,
+    revision: () => revision,
+  }
+}
diff --git a/src/admin/pages/site/canvas/CanvasRoot.tsx b/src/admin/pages/site/canvas/CanvasRoot.tsx
index 0a699aeca..9c91990c4 100644
--- a/src/admin/pages/site/canvas/CanvasRoot.tsx
+++ b/src/admin/pages/site/canvas/CanvasRoot.tsx
@@ -34,6 +34,7 @@ import { useCanvas } from '@site/hooks/useCanvas'
 import { useEditorPermissions } from '@site/editorPermissionsContext'
 import { CanvasTransformLayer } from './CanvasTransformLayer'
 import { CanvasLiveSurface } from './CanvasLiveSurface'
+import { AgentSnapshotFrame } from './AgentSnapshotFrame'
 import { useRuntimeScriptBuild } from './useRuntimeScriptBuild'
 import { CanvasNotch } from './CanvasNotch'
 import { CanvasModeToggle } from './CanvasModeToggle'
@@ -87,6 +88,7 @@ export function CanvasRoot({ editable = true }: CanvasRootProps) {
   const breakpoints = useEditorStore((s) => s.site?.breakpoints ?? EMPTY_BREAKPOINTS)
   const activeBreakpointId = useEditorStore((s) => s.activeBreakpointId)
   const canvasView = useEditorStore((s) => s.canvasView)
+  const agentSnapshotCaptureRequest = useEditorStore((s) => s.agentSnapshotCaptureRequest)
   const rightSidebarExpanded = useEditorStore(selectRightSidebarExpanded)
   const isLive = canvasView === 'live'
   const runScripts = useEditorStore((s) => s.runScripts)
@@ -116,7 +118,13 @@ export function CanvasRoot({ editable = true }: CanvasRootProps) {
   const setFocusedPanel = useEditorStore((s) => s.setFocusedPanel)
   const setActiveDocument = useEditorStore((s) => s.setActiveDocument)
   const activeDocument = useEditorStore((s) => s.activeDocument)
-  const templatePreviewContext = useTemplatePreviewContext(canvasPage)
+  const {
+    context: templatePreviewContext,
+    loading: templatePreviewContextLoading,
+  } = useTemplatePreviewContext(canvasPage)
+  const agentSnapshotBreakpoint = agentSnapshotCaptureRequest
+    ? breakpoints.find((breakpoint) => breakpoint.id === agentSnapshotCaptureRequest.breakpointId) ?? null
+    : null
   // Permission context — gates canvas affordances:
   //   canEditContent → double-click inline text editing
   //   canEditStyle / canEditStructure → properties sidebar
@@ -551,6 +559,17 @@ export function CanvasRoot({ editable = true }: CanvasRootProps) {
               onClose={renameDialog.close}
             />
           )}
+
+          {agentSnapshotCaptureRequest && canvasPage && agentSnapshotBreakpoint ? (
+            <AgentSnapshotFrame
+              key={agentSnapshotCaptureRequest.requestId}
+              requestId={agentSnapshotCaptureRequest.requestId}
+              page={canvasPage}
+              breakpoint={agentSnapshotBreakpoint}
+              templateContext={templatePreviewContext}
+              templateContextLoading={templatePreviewContextLoading}
+            />
+          ) : null}
         </div>
       </CanvasSelectionContext.Provider>
     </CanvasViewportActionsContext.Provider>
diff --git a/src/admin/pages/site/canvas/IframeFrameSurface.tsx b/src/admin/pages/site/canvas/IframeFrameSurface.tsx
index f71fdee04..6000915b9 100644
--- a/src/admin/pages/site/canvas/IframeFrameSurface.tsx
+++ b/src/admin/pages/site/canvas/IframeFrameSurface.tsx
@@ -89,9 +89,30 @@ import {
 } from './canvasPanInput'
 import { useEditorStore } from '@site/store/store'
 import { closestReadonlyRegion, isElementLike } from './readonlyRegion'
+import { CanvasDocumentContext, CanvasFrameElementContext } from './CanvasContexts'
 import styles from './IframeFrameSurface.module.css'
 
-const IFRAME_SRC_DOC = '<!doctype html><html><head></head><body></body></html>'
+const IFRAME_DOCUMENT_SENTINEL = 'data-instatic-canvas-document'
+const IFRAME_SRC_DOC = `<!doctype html><html ${IFRAME_DOCUMENT_SENTINEL}><head></head><body></body></html>`
+const IFRAME_DOCUMENT_FLAG = '__instaticCanvasDocument'
+
+type InstaticIframeDocument = Document & { [IFRAME_DOCUMENT_FLAG]?: true }
+
+function claimIframeSrcDocument(doc: Document): boolean {
+  const taggedDocument = doc as InstaticIframeDocument
+  if (taggedDocument[IFRAME_DOCUMENT_FLAG]) return true
+  if (!doc.documentElement.hasAttribute(IFRAME_DOCUMENT_SENTINEL)) return false
+
+  // The sentinel identifies the final srcDoc only during bootstrap. Remove it
+  // before authored CSS/DOM selectors run, then keep the identity off-DOM so
+  // the editor document matches published <html> structure.
+  doc.documentElement.removeAttribute(IFRAME_DOCUMENT_SENTINEL)
+  Object.defineProperty(taggedDocument, IFRAME_DOCUMENT_FLAG, {
+    configurable: true,
+    value: true,
+  })
+  return true
+}
 
 /** Stable empty list so a script-less frame doesn't churn the injector's deps. */
 const EMPTY_RUNTIME_SCRIPTS: InjectableRuntimeScript[] = []
@@ -214,18 +235,33 @@ export const IframeFrameSurface = forwardRef<IframeFrameSurfaceHandle, IframeFra
         setIframeDoc(null)
         return
       }
-      const tryCapture = () => {
+      delete iframe.dataset.instaticCanvasDocumentLoaded
+      const captureSrcDoc = () => {
         const doc = iframe.contentDocument
-        if (doc && doc.readyState !== 'loading') setIframeDoc(doc)
+        if (
+          !doc ||
+          doc.readyState === 'loading' ||
+          !claimIframeSrcDocument(doc)
+        ) return
+        // Never portal the canvas tree into the short-lived initial about:blank
+        // document. Module effects, media reads, and authored runtime scripts
+        // must run once against the final srcDoc document only.
+        setIframeDoc(doc)
+        iframe.dataset.instaticCanvasDocumentLoaded = 'true'
       }
-      tryCapture()
-      iframe.addEventListener('load', tryCapture)
+      // srcDoc often parses before the ref commits; otherwise its load event
+      // retries. The bootstrap sentinel, not event timing or URL heuristics,
+      // identifies the document we own; claimIframeSrcDocument removes it from
+      // authored DOM before the portal mounts.
+      captureSrcDoc()
+      iframe.addEventListener('load', captureSrcDoc)
       // Stash the cleanup on the ref so React's ref-callback contract (the
       // function may be called again with null on unmount) doesn't leak
       // listeners.
       const cleanableIframe = iframe as IframeWithCleanup
       cleanableIframe._instaticCleanup = () => {
-        iframe.removeEventListener('load', tryCapture)
+        iframe.removeEventListener('load', captureSrcDoc)
+        delete iframe.dataset.instaticCanvasDocumentLoaded
         cleanableIframe._instaticCleanup = undefined
       }
     }
@@ -616,17 +652,19 @@ export const IframeFrameSurface = forwardRef<IframeFrameSurfaceHandle, IframeFra
         />
         {iframeDoc &&
           createPortal(
-            <>
-              {/* Editor-chrome stylesheet — UNLAYERED so it beats @layer user-authored author CSS */}
-              <EditorChromeInjector targetDocument={iframeDoc} parentDocument={document} />
-              {/* Author CSS — both wrapped in @layer user-authored inside the injectors */}
-              <ClassStyleInjector targetDocument={iframeDoc} viewport={viewport} />
-              <UserStylesheetInjector targetDocument={iframeDoc} viewport={viewport} />
-              {children}
-              {/* Runtime scripts (opt-in) run against the node tree mounted
-                  above. Empty list = no-op, so this is safe to always mount. */}
-              <RuntimeScriptInjector targetDocument={iframeDoc} scripts={runtimeScripts ?? EMPTY_RUNTIME_SCRIPTS} />
-            </>,
+            <CanvasFrameElementContext.Provider value={iframeRef.current}>
+              <CanvasDocumentContext.Provider value={iframeDoc}>
+                {/* Editor-chrome stylesheet — UNLAYERED so it beats @layer user-authored author CSS */}
+                <EditorChromeInjector targetDocument={iframeDoc} parentDocument={document} />
+                {/* Author CSS — both wrapped in @layer user-authored inside the injectors */}
+                <ClassStyleInjector targetDocument={iframeDoc} viewport={viewport} />
+                <UserStylesheetInjector targetDocument={iframeDoc} viewport={viewport} />
+                {children}
+                {/* Runtime scripts (opt-in) run against the node tree mounted
+                    above. Empty list = no-op, so this is safe to always mount. */}
+                <RuntimeScriptInjector targetDocument={iframeDoc} scripts={runtimeScripts ?? EMPTY_RUNTIME_SCRIPTS} />
+              </CanvasDocumentContext.Provider>
+            </CanvasFrameElementContext.Provider>,
             iframeDoc.body,
           )}
       </>
diff --git a/src/admin/pages/site/canvas/iframeBodyPresentation.ts b/src/admin/pages/site/canvas/iframeBodyPresentation.ts
new file mode 100644
index 000000000..88ed8420e
--- /dev/null
+++ b/src/admin/pages/site/canvas/iframeBodyPresentation.ts
@@ -0,0 +1,117 @@
+/**
+ * Apply authored presentation to a canvas iframe's real `<body>` element.
+ *
+ * Both the editable `base.body` module and template composition use this
+ * helper so body classes and inline styles follow one lifecycle: apply only
+ * the fields they own, then restore the exact previous values on cleanup.
+ * Restoring individual declarations (instead of `cssText`) preserves the
+ * iframe sizing/overflow reset maintained independently by the frame surface.
+ */
+
+import { CANVAS_BODY_RESET_PROPERTIES } from './iframeBodyReset'
+
+export interface IframeBodyPresentation {
+  className?: string
+  style?: Record<string, string | number>
+  /** Sanitized authored attributes that publish on the real `<body>`. */
+  attributes?: Record<string, string>
+}
+
+interface PreviousInlineStyle {
+  property: string
+  value: string
+  priority: string
+}
+
+interface PreviousAttribute {
+  name: string
+  value: string | null
+}
+
+// Canvas plumbing owns these fields regardless of authored body attributes.
+// The shared HTML-attribute sanitizer already rejects most of them; keeping the
+// list here is defence-in-depth for imperative callers and protects the exact
+// attributes Agent readiness/selection depends on.
+const EDITOR_OWNED_BODY_ATTRIBUTES = new Set([
+  'class',
+  'style',
+  'tabindex',
+  'data-breakpoint-id',
+  'data-node-id',
+  'data-module-id',
+  'data-canvas-selected',
+  'data-hovered',
+])
+
+export function applyIframeBodyPresentation(
+  body: HTMLElement,
+  presentation: IframeBodyPresentation,
+): () => void {
+  const previousClassName = presentation.className === undefined
+    ? undefined
+    : body.className
+
+  if (presentation.className !== undefined) {
+    body.className = presentation.className
+  }
+
+  const declarations = normaliseInlineStyles(presentation.style)
+  if (body.dataset.instaticIframeInteraction === 'canvas') {
+    for (const property of CANVAS_BODY_RESET_PROPERTIES) declarations.delete(property)
+  }
+  // Snapshot every touched declaration BEFORE applying any of them. A
+  // shorthand such as `background` can mutate its longhands, so interleaving
+  // snapshot/apply would record already-mutated values for a later
+  // `backgroundColor` entry and restore the wrong cascade on cleanup.
+  const previousStyles: PreviousInlineStyle[] = [...declarations.keys()].map(
+    (property) => ({
+      property,
+      value: body.style.getPropertyValue(property),
+      priority: body.style.getPropertyPriority(property),
+    }),
+  )
+  for (const [property, value] of declarations) {
+    body.style.setProperty(property, value)
+  }
+
+  const attributes = Object.entries(presentation.attributes ?? {})
+    .filter(([name]) => !EDITOR_OWNED_BODY_ATTRIBUTES.has(name))
+  const previousAttributes: PreviousAttribute[] = attributes.map(([name]) => ({
+    name,
+    value: body.getAttribute(name),
+  }))
+  for (const [name, value] of attributes) body.setAttribute(name, value)
+
+  return () => {
+    if (previousClassName !== undefined) body.className = previousClassName
+    for (const previous of previousStyles) {
+      if (previous.value) {
+        body.style.setProperty(previous.property, previous.value, previous.priority)
+      } else {
+        body.style.removeProperty(previous.property)
+      }
+    }
+    for (const previous of previousAttributes) {
+      if (previous.value === null) body.removeAttribute(previous.name)
+      else body.setAttribute(previous.name, previous.value)
+    }
+  }
+}
+
+function normaliseInlineStyles(
+  style: Record<string, string | number> | undefined,
+): Map<string, string> {
+  const declarations = new Map<string, string>()
+  for (const [property, value] of Object.entries(style ?? {})) {
+    declarations.set(toCssPropertyName(property), String(value))
+  }
+  return declarations
+}
+
+function toCssPropertyName(property: string): string {
+  if (property.startsWith('--')) return property
+  const kebab = property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+  // `msTransition` is the one vendor-prefixed DOM style key whose JS spelling
+  // starts lowercase but whose CSS spelling still needs the leading dash.
+  return kebab.startsWith('ms-') ? `-${kebab}` : kebab
+}
diff --git a/src/admin/pages/site/canvas/iframeBodyReset.ts b/src/admin/pages/site/canvas/iframeBodyReset.ts
index 3d6d5adfe..9c89c09ea 100644
--- a/src/admin/pages/site/canvas/iframeBodyReset.ts
+++ b/src/admin/pages/site/canvas/iframeBodyReset.ts
@@ -23,6 +23,20 @@ import { CANVAS_VIEWPORT_HEIGHT } from './resolveViewportUnits'
  */
 export type IframeInteraction = 'canvas' | 'live'
 
+/**
+ * Inline declarations owned by the design-frame sizing contract. Authored
+ * body styles still publish normally and apply in live mode, but these fields
+ * cannot replace the design iframe's grow-to-content/scrollbar reset after it
+ * has mounted.
+ */
+export const CANVAS_BODY_RESET_PROPERTIES = new Set([
+  'height',
+  'min-height',
+  'overflow',
+  'overflow-x',
+  'overflow-y',
+])
+
 // Canvas-only chrome: neutralize interaction affordances inside design frames.
 // Kept at module scope so the React Compiler does not treat the cross-frame
 // DOM writes as React-owned state mutation.
@@ -53,6 +67,7 @@ export function applyIframeBodyReset(
   interaction: IframeInteraction,
 ): void {
   iframeDoc.body.setAttribute('data-breakpoint-id', breakpointId)
+  iframeDoc.body.dataset.instaticIframeInteraction = interaction
   // Live frames render the page exactly as published: html/body keep the
   // `:where(html, body) { height: 100% }` reset (the iframe is the scroll
   // viewport, short pages still fill it), and the canvas-chrome CSS
@@ -60,10 +75,7 @@ export function applyIframeBodyReset(
   // cursors, text selection, and embedded iframes behave like the live site.
   if (interaction === 'live') {
     iframeDoc.documentElement.style.height = ''
-    iframeDoc.body.style.height = ''
-    iframeDoc.body.style.minHeight = ''
     iframeDoc.documentElement.style.overflow = ''
-    iframeDoc.body.style.overflow = ''
     return
   }
   iframeDoc.documentElement.style.height = 'auto'
diff --git a/src/admin/pages/site/canvas/useLoopPreviewItems.ts b/src/admin/pages/site/canvas/useLoopPreviewItems.ts
index 7bae99457..efc4d17a3 100644
--- a/src/admin/pages/site/canvas/useLoopPreviewItems.ts
+++ b/src/admin/pages/site/canvas/useLoopPreviewItems.ts
@@ -34,7 +34,7 @@
  * `site`, and only when such a source is selected.
  */
 
-import { useEffect, useState } from 'react'
+import { use, useEffect, useState } from 'react'
 import { useEditorStore } from '@site/store/store'
 import { loopSourceRegistry } from '@core/loops/registry'
 import { type LoopItem, pageToLoopItem, filterPagesForLoop } from '@core/loops'
@@ -43,6 +43,7 @@ import type { Page, PageNode } from '@core/page-tree'
 import { getCmsDataTable, previewCmsDataLoopItems } from '@core/persistence/cmsData'
 import { listCmsMediaAssets, type CmsMediaAsset } from '@core/persistence/cmsMedia'
 import { dataTablePreviewToLoopItem } from '@core/templates/templatePreviewData'
+import { CanvasPreviewReadinessContext } from './CanvasPreviewReadiness'
 
 // ---------------------------------------------------------------------------
 // Loop prop reader
@@ -226,6 +227,7 @@ export function selectSitePagesLoopItems(node: PageNode, pages: readonly Page[]
 const BUILT_IN_SOURCE_IDS = new Set(['data.rows', 'site.media', 'site.pages'])
 
 export function useLoopPreviewItems(node: PageNode): LoopItem[] {
+  const previewReadiness = use(CanvasPreviewReadinessContext)
   // `readLoopProps()` reuses the shared `EMPTY_FILTERS` sentinel when the
   // node has no filters set, so `filters` identity is stable across renders
   // for the no-filter case. When filters ARE set, the value comes straight
@@ -269,14 +271,14 @@ export function useLoopPreviewItems(node: PageNode): LoopItem[] {
     // (which would violate react-hooks/set-state-in-effect).
     if (sourceId !== 'data.rows' || !tableId) return
     let cancelled = false
-    getCmsDataTable(tableId)
+    const tableRequest = getCmsDataTable(tableId)
       .then((table) => {
         if (!cancelled) setAsyncDataTable(table)
       })
       .catch(() => {
         if (!cancelled) setAsyncDataTable(null)
       })
-    previewCmsDataLoopItems(tableId, {
+    const rowsRequest = previewCmsDataLoopItems(tableId, {
       orderBy: orderBy || 'publishedAt',
       direction,
       limit,
@@ -288,16 +290,17 @@ export function useLoopPreviewItems(node: PageNode): LoopItem[] {
       .catch(() => {
         if (!cancelled) setAsyncDataRowItems([])
       })
+    previewReadiness?.track(Promise.all([tableRequest, rowsRequest]))
     return () => {
       cancelled = true
     }
-  }, [sourceId, tableId, orderBy, direction, limit, offset])
+  }, [sourceId, tableId, orderBy, direction, limit, offset, previewReadiness])
 
   // ── Async fetch: site.media ─────────────────────────────────────────
   useEffect(() => {
     if (sourceId !== 'site.media') return
     let cancelled = false
-    listCmsMediaAssets()
+    const request = listCmsMediaAssets()
       .then((assets) => {
         if (cancelled) return
         setAsyncMedia(assets)
@@ -305,10 +308,11 @@ export function useLoopPreviewItems(node: PageNode): LoopItem[] {
       .catch(() => {
         if (!cancelled) setAsyncMedia([])
       })
+    previewReadiness?.track(request)
     return () => {
       cancelled = true
     }
-  }, [sourceId])
+  }, [sourceId, previewReadiness])
 
   // ── Sort + offset + limit pipeline ──────────────────────────────────
   if (!sourceId) return EMPTY_ITEMS
diff --git a/src/admin/pages/site/hooks/useTemplatePreviewContext.ts b/src/admin/pages/site/hooks/useTemplatePreviewContext.ts
index c3d523f36..de4a9f8c4 100644
--- a/src/admin/pages/site/hooks/useTemplatePreviewContext.ts
+++ b/src/admin/pages/site/hooks/useTemplatePreviewContext.ts
@@ -10,8 +10,9 @@ import { useEditorStore } from '@site/store/store'
 /**
  * Build the canvas-side render context used by `resolveDynamicProps`.
  *
- * Always returns a populated context so bindings resolve live in the
- * editor without needing preview mode:
+ * Returns the context plus its post-type entry loading state so bindings
+ * resolve live in the editor and Agent evidence can wait for real preview
+ * data before capturing:
  *   - `page`, `site`, `route` — built from the in-memory site document
  *     and the currently active page. Match the values the publisher
  *     will compute at render time.
@@ -19,7 +20,13 @@ import { useEditorStore } from '@site/store/store'
  *     synthetic preview row from the table's schema. Loop iterations
  *     push/pop on top of this stack via `NodeRenderer`'s loop branch.
  */
-export function useTemplatePreviewContext(page: Page | null): TemplateRenderDataContext | undefined {
+interface TemplatePreviewContextState {
+  context: TemplateRenderDataContext | undefined
+  /** True while a post-type template's real preview row is still loading. */
+  loading: boolean
+}
+
+export function useTemplatePreviewContext(page: Page | null): TemplatePreviewContextState {
   // Read site once; the page argument is already reactive via the caller.
   const site = useEditorStore((s) => s.site)
 
@@ -37,7 +44,7 @@ export function useTemplatePreviewContext(page: Page | null): TemplateRenderData
   // Fetch a window of published rows once per table; the chosen row is picked
   // from it below so changing the preview selection never refetches. A failed
   // load resolves to an empty window so bindings stay empty rather than throw.
-  const { data: previewState } = useAsyncResource<{
+  const { data: previewState, loading } = useAsyncResource<{
     tableSlug: string
     items: TemplateRenderDataContext['entryStack']
     synthetic: TemplateRenderDataContext['entryStack'][number] | null
@@ -69,7 +76,8 @@ export function useTemplatePreviewContext(page: Page | null): TemplateRenderData
   // tableSlug; outside that, the stack stays empty so bindings against
   // currentEntry stay empty until the loop interceptor pushes a real
   // iteration on top.
-  if (!page || !site) return undefined
+  const previewEntryLoading = Boolean(tableSlug) && loading
+  if (!page || !site) return { context: undefined, loading: previewEntryLoading }
   let entryStack: TemplateRenderDataContext['entryStack'] = []
   if (tableSlug && previewState?.tableSlug === tableSlug) {
     // Selected row → first published row → synthetic sample (empty table).
@@ -81,12 +89,15 @@ export function useTemplatePreviewContext(page: Page | null): TemplateRenderData
   }
   const pageFrame = buildPageFrame(page)
   return {
-    entryStack,
-    page: pageFrame,
-    site: buildSiteFrame(site),
-    // Route frame mirrors what the published page will see. Editor
-    // doesn't have the real request URL, so we derive from the page's
-    // permalink — same shape, same fields.
-    route: buildRouteFrame(pageFrame.permalink),
+    loading: previewEntryLoading,
+    context: {
+      entryStack,
+      page: pageFrame,
+      site: buildSiteFrame(site),
+      // Route frame mirrors what the published page will see. Editor
+      // doesn't have the real request URL, so we derive from the page's
+      // permalink — same shape, same fields.
+      route: buildRouteFrame(pageFrame.permalink),
+    },
   }
 }
diff --git a/src/admin/pages/site/preview/PreviewOverlay.tsx b/src/admin/pages/site/preview/PreviewOverlay.tsx
index e0faa3816..e160e1cd0 100644
--- a/src/admin/pages/site/preview/PreviewOverlay.tsx
+++ b/src/admin/pages/site/preview/PreviewOverlay.tsx
@@ -31,7 +31,7 @@ export function PreviewOverlay() {
   const closePreview = useEditorStore((s) => s.closePreview)
   const site = useEditorStore((s) => s.site)
   const activePage = useEditorStore(selectActivePage)
-  const templatePreviewContext = useTemplatePreviewContext(activePage)
+  const { context: templatePreviewContext } = useTemplatePreviewContext(activePage)
 
   const closeBtnRef = useRef<HTMLButtonElement>(null)
   const triggerRef = useRef<HTMLElement | null>(null)
diff --git a/src/admin/pages/site/store/slices/canvasSlice.ts b/src/admin/pages/site/store/slices/canvasSlice.ts
index 5ec08d1f5..7956668ae 100644
--- a/src/admin/pages/site/store/slices/canvasSlice.ts
+++ b/src/admin/pages/site/store/slices/canvasSlice.ts
@@ -9,6 +9,11 @@ import {
 
 type CanvasMode = 'select' | 'pan' | 'insert'
 
+interface AgentSnapshotCaptureRequest {
+  requestId: string
+  breakpointId: string
+}
+
 /**
  * Canvas render mode.
  *
@@ -71,6 +76,13 @@ interface CanvasSlice {
    * the frame entirely via Settings). Reloading the editor clears it.
    */
   collapsedBreakpointIds: string[]
+  /**
+   * One ephemeral, offscreen frame requested by `site_render_snapshot` when the
+   * exact viewport is not already mounted on the visible canvas. This is editor
+   * session state only: it never changes the active viewport, canvas mode, or
+   * persisted breakpoint configuration.
+   */
+  agentSnapshotCaptureRequest: AgentSnapshotCaptureRequest | null
 
   setZoom: (zoom: number) => void
   setPan: (x: number, y: number) => void
@@ -85,6 +97,8 @@ interface CanvasSlice {
   setRunScripts: (run: boolean) => void
   /** Toggle whether a breakpoint's design-canvas frame is collapsed to its slim header. */
   toggleBreakpointCollapsed: (id: string) => void
+  /** Mount or release the agent's one-shot offscreen snapshot frame. */
+  setAgentSnapshotCaptureRequest: (request: AgentSnapshotCaptureRequest | null) => void
   resetView: () => void
   /**
    * Step zoom up to the next preset level. When `originX`/`originY` are
@@ -117,6 +131,7 @@ export const createCanvasSlice: EditorStoreSliceCreator<CanvasSlice> = (set, get
   canvasView: 'design',
   runScripts: false,
   collapsedBreakpointIds: [],
+  agentSnapshotCaptureRequest: null,
 
   setZoom: (zoom) => set({ zoom: clampZoom(zoom) }),
 
@@ -148,6 +163,10 @@ export const createCanvasSlice: EditorStoreSliceCreator<CanvasSlice> = (set, get
     else s.collapsedBreakpointIds.splice(idx, 1)
   }),
 
+  setAgentSnapshotCaptureRequest: (agentSnapshotCaptureRequest) => set({
+    agentSnapshotCaptureRequest,
+  }),
+
   resetView: () => set({ zoom: RESET_ZOOM, panX: 0, panY: 0 }),
 
   zoomIn: (originX, originY) => {
diff --git a/src/modules/base/body/BodyEditor.tsx b/src/modules/base/body/BodyEditor.tsx
index 8a1a0873c..3874fe5fb 100644
--- a/src/modules/base/body/BodyEditor.tsx
+++ b/src/modules/base/body/BodyEditor.tsx
@@ -8,45 +8,41 @@
  *
  * Editor metadata that used to live on a wrapping `<div>` (data-node-id,
  * canvas selection attrs, click handlers, the user's mcClassName) is now
- * applied to the iframe's actual `<body>` element via `useEffect` —
- * `BodyOwnerProbe` is a tiny
- * `display: contents` component that gives the effect a ref into the
- * iframe document. The probe element contributes no layout or accessible
- * affordance; it disappears from the DOM tree from CSS's perspective.
+ * applied to the iframe's actual `<body>` element via the document context
+ * supplied by `IframeFrameSurface`. No editor-only probe is inserted into the
+ * body, so authored child/sibling selectors see the published DOM exactly.
  *
  * Component-only file so React Fast Refresh can hot-patch edits without
  * re-running module registration.
  */
-import { useEffect, useRef } from 'react'
+import { use, useEffect } from 'react'
 import type { ModuleComponentProps, NodeWrapperProps as NodeWrapperPropsType } from '@core/module-engine'
+import { applyIframeBodyPresentation } from '@site/canvas/iframeBodyPresentation'
+import { htmlAttributesForReact } from '@modules/base/shared/htmlAttributes'
+import { CanvasDocumentContext } from '@site/canvas/CanvasContexts'
 
-type BodyProps = Record<string, unknown>
+type BodyProps = { htmlAttributes?: unknown }
 
-export const BodyEditor = ({ children, mcClassName, nodeWrapperProps }: ModuleComponentProps<BodyProps>) => {
-  // `display: contents` probe — has zero layout footprint and is invisible
-  // to CSS selectors used by the user, but it has an `ownerDocument` we
-  // can read inside the effect to apply attrs to the iframe `<body>`.
-  const probeRef = useRef<HTMLDivElement | null>(null)
+export const BodyEditor = ({
+  children,
+  mcClassName,
+  nodeWrapperProps,
+  props,
+}: ModuleComponentProps<BodyProps>) => {
+  const iframeDocument = use(CanvasDocumentContext)
 
   useEffect(() => {
-    const probe = probeRef.current
-    if (!probe) return
-    const body = probe.ownerDocument?.body
+    const body = iframeDocument?.body
     if (!body) return
-    return applyEditorAttrsToBody(body, mcClassName, nodeWrapperProps)
-  }, [mcClassName, nodeWrapperProps])
+    return applyEditorAttrsToBody(
+      body,
+      mcClassName,
+      nodeWrapperProps,
+      htmlAttributesForReact(props.htmlAttributes),
+    )
+  }, [iframeDocument, mcClassName, nodeWrapperProps, props.htmlAttributes])
 
-  return (
-    <>
-      <div
-        ref={probeRef}
-        aria-hidden="true"
-        style={{ display: 'contents' }}
-        data-instatic-body-probe=""
-      />
-      {children}
-    </>
-  )
+  return children
 }
 
 /**
@@ -58,7 +54,21 @@ function applyEditorAttrsToBody(
   body: HTMLElement,
   mcClassName: string | undefined,
   nodeWrapperProps: NodeWrapperPropsType | undefined,
+  htmlAttributes: Record<string, string>,
 ): () => void {
+  const restorePresentation = applyIframeBodyPresentation(body, {
+    className: mcClassName,
+    style: nodeWrapperProps?.style,
+    attributes: htmlAttributes,
+  })
+  const restoreEditorAttributes = snapshotBodyAttributes(body, [
+    'data-node-id',
+    'data-module-id',
+    'tabindex',
+    'data-canvas-selected',
+    'data-hovered',
+  ])
+
   if (nodeWrapperProps?.['data-node-id']) {
     body.setAttribute('data-node-id', nodeWrapperProps['data-node-id'])
   }
@@ -66,8 +76,6 @@ function applyEditorAttrsToBody(
     body.setAttribute('data-module-id', nodeWrapperProps['data-module-id'])
   }
   body.setAttribute('tabindex', '0')
-  body.removeAttribute('role')
-  body.removeAttribute('aria-pressed')
   if (nodeWrapperProps?.['data-canvas-selected']) {
     body.setAttribute('data-canvas-selected', nodeWrapperProps['data-canvas-selected'])
   } else {
@@ -78,10 +86,6 @@ function applyEditorAttrsToBody(
   } else {
     body.removeAttribute('data-hovered')
   }
-  if (mcClassName !== undefined) {
-    body.className = mcClassName
-  }
-
   const handlers: Array<[string, EventListener]> = []
   const addListener = <K extends keyof HTMLElementEventMap>(
     name: K,
@@ -113,5 +117,17 @@ function applyEditorAttrsToBody(
     for (const [name, handler] of handlers) {
       body.removeEventListener(name, handler)
     }
+    restoreEditorAttributes()
+    restorePresentation()
+  }
+}
+
+function snapshotBodyAttributes(body: HTMLElement, names: string[]): () => void {
+  const previous = names.map((name) => ({ name, value: body.getAttribute(name) }))
+  return () => {
+    for (const attribute of previous) {
+      if (attribute.value === null) body.removeAttribute(attribute.name)
+      else body.setAttribute(attribute.name, attribute.value)
+    }
   }
 }
diff --git a/src/modules/base/body/index.ts b/src/modules/base/body/index.ts
index 1a8739d85..3830a1233 100644
--- a/src/modules/base/body/index.ts
+++ b/src/modules/base/body/index.ts
@@ -5,9 +5,8 @@
  * time: the body node's children render directly into `<body>`, and any user
  * classes applied to the body land on `<body class="...">` via the publisher
  * (see `publishPage` in `src/core/publisher/render.ts`). The editor preview
- * component still wraps children in a `<div>` so the canvas has a click
- * target / drop zone for the body node — that wrapper is editor-only and
- * never reaches published HTML.
+ * applies identity/presentation directly to the iframe's real body through
+ * `CanvasDocumentContext`; it adds no wrapper or probe child.
  */
 import type { ModuleDefinition } from '@core/module-engine'
 import { registry } from '@core/module-engine'