From de43ea5a4dd8a8b4e3e6a07de0b290b647b2db13 Mon Sep 17 00:00:00 2001
From: Saatvik Arya <aryasaatvik@gmail.com>
Date: Mon, 5 Oct 2026 10:22:53 +0530
Subject: [PATCH 1/2] feat(editor): prepare preview documents before mounting

---
 .../editor-preview-document-preparation.md    |  12 ++
 packages/editor/README.md                     |  37 +++++
 packages/editor/src/canvas/email-frame.tsx    |  44 +++---
 .../editor/src/canvas/preview-document.ts     |  16 ++
 packages/editor/src/shell.ts                  |   1 +
 packages/editor/src/state/provider.tsx        |  12 +-
 .../editor/tests/preview-document.test.tsx    | 141 ++++++++++++++++++
 7 files changed, 245 insertions(+), 18 deletions(-)
 create mode 100644 .tegami/editor-preview-document-preparation.md
 create mode 100644 packages/editor/src/canvas/preview-document.ts
 create mode 100644 packages/editor/tests/preview-document.test.tsx

diff --git a/.tegami/editor-preview-document-preparation.md b/.tegami/editor-preview-document-preparation.md
new file mode 100644
index 0000000..256ef16
--- /dev/null
+++ b/.tegami/editor-preview-document-preparation.md
@@ -0,0 +1,12 @@
+---
+packages:
+  npm:@samva/editor:
+    type: minor
+---
+
+## Hosts can prepare preview documents before parsing
+
+`EditorProvider` accepts `preparePreviewDocument`, and `@samva/editor/shell` exports
+`PreparedPreviewDocument`. Canvas and Preview write the prepared HTML, then mount host resources
+before measurement and paint. Resources are cleaned up for their exact document on replacement,
+unmount, and StrictMode replay. Replacing the preparation callback replaces the preview frames.
diff --git a/packages/editor/README.md b/packages/editor/README.md
index fd070b2..c6654f2 100644
--- a/packages/editor/README.md
+++ b/packages/editor/README.md
@@ -73,6 +73,43 @@ exact source replacement saved like any other edit. Expressions, conditionals an
 inside a body are locked segments, so a form edit cannot rewrite them, and an edit that would
 leave the static profile is refused with its reason.
 
+## Preparing preview documents
+
+`EditorProvider` accepts `preparePreviewDocument?: (html: string) => PreparedPreviewDocument`.
+Both the editing canvas and Preview call it with the original host HTML before writing to the
+attached iframe. Only the returned `html` reaches that parser. Preview applies its forced
+light/dark scheme to the prepared HTML.
+
+```tsx
+import { EditorProvider, EditorShell, type PreparedPreviewDocument } from "@samva/editor/shell";
+
+const preparePreviewDocument = (html: string): PreparedPreviewDocument => ({
+  html,
+  mount(document) {
+    const style = document.createElement("style");
+    style.textContent = "body { min-height: 200px; }";
+    document.head.appendChild(style);
+    return () => style.remove();
+  },
+});
+
+<EditorProvider host={host} preparePreviewDocument={preparePreviewDocument}>
+  <EditorShell />
+</EditorProvider>;
+```
+
+Preparation must be pure and synchronous: React can repeat or discard it during render.
+Install document resources in `mount`, which runs synchronously after `document.close()` and
+before measurement, canvas overlays, or paint. Its returned cleanup belongs to that exact
+document and runs on replacement, unmount, and StrictMode effect replay. Mount and cleanup must
+support that replay. Asynchronous resource work remains the host's responsibility; the editor
+does not wait for it before measuring or painting.
+
+Keep the preparation callback stable while its policy stays the same. Changing its identity
+replaces the frames and their resources without resetting the editor session. Without the prop,
+the editor writes the host HTML as supplied (with Preview's existing scheme simulation).
+Preparation affects iframe previews only; exported HTML and the HTML view retain host output.
+
 ## Host contract
 
 Every host provides a scoped `DocumentReader`. Editable hosts additionally
diff --git a/packages/editor/src/canvas/email-frame.tsx b/packages/editor/src/canvas/email-frame.tsx
index 2f84546..5e87764 100644
--- a/packages/editor/src/canvas/email-frame.tsx
+++ b/packages/editor/src/canvas/email-frame.tsx
@@ -1,14 +1,15 @@
-import { type ReactNode, useLayoutEffect, useRef, useState } from "react";
+import { type ReactNode, useContext, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 
 import { isCanvasActivationTarget, resolveInstancePath } from "./instance-dom";
+import { PreviewDocumentContext, type PreparedPreviewDocument } from "./preview-document";
 
 /**
- * The rendered email, mounted as-is in a same-origin iframe.
+ * The rendered email, mounted in a same-origin iframe.
  *
  * The host renders the template and hands back one HTML document; nothing here
- * compiles or rewrites it. The frame owns three things the document itself does
- * not: it sizes to the content, it resolves a click to the `data-samva-instance`
+ * compiles it. Optional host preparation runs before parsing. The frame sizes
+ * to content, resolves a click to the `data-samva-instance`
  * the renderer stamped on every element, and it hosts chrome (selection outline,
  * label chip) as a React portal above the document.
  */
@@ -117,6 +118,7 @@ export interface EmailFrameProps {
  */
 const FrameDocument = ({
   document_,
+  mount,
   width,
   dark,
   overlay,
@@ -125,6 +127,7 @@ const FrameDocument = ({
   onContextMenu,
 }: {
   readonly document_: string;
+  readonly mount: PreparedPreviewDocument["mount"] | undefined;
   readonly width: number;
   readonly dark: boolean;
   readonly overlay?: ReactNode | undefined;
@@ -146,6 +149,9 @@ const FrameDocument = ({
   useLayoutEffect(() => {
     const iframe = ref.current;
     if (iframe === null) return;
+    const idoc = iframe.contentDocument;
+    if (idoc === null) return;
+    let cleanupDocument: (() => void) | undefined;
 
     let fitFrame: number | null = null;
     const scheduleFit = () => {
@@ -163,8 +169,6 @@ const FrameDocument = ({
     const mutations = new MutationObserver(scheduleFit);
 
     const updateChrome = () => {
-      const idoc = iframe.contentDocument;
-      if (idoc === null) return;
       let chrome = idoc.head.querySelector<HTMLStyleElement>("style[data-samva-editor-chrome]");
       if (chrome === null) {
         chrome = idoc.createElement("style");
@@ -175,14 +179,13 @@ const FrameDocument = ({
     };
 
     const wire = () => {
-      const idoc = iframe.contentDocument;
-      if (idoc === null) return;
       // A src-less same-origin iframe exposes its document synchronously, so the
       // rendered email is installed by writing it rather than through `srcdoc`,
       // whose load is asynchronous and would leave one empty frame on screen.
       idoc.open();
       idoc.write(document_);
       idoc.close();
+      cleanupDocument = mount?.(idoc);
       updateChrome();
       setBody(idoc.body);
       observer.disconnect();
@@ -219,16 +222,12 @@ const FrameDocument = ({
     };
 
     const attach = () => {
-      const idoc = iframe.contentDocument;
-      if (idoc === null) return;
       idoc.addEventListener("click", onClick);
       idoc.addEventListener("mousemove", onMove);
       idoc.addEventListener("mouseleave", onLeave);
       idoc.addEventListener("contextmenu", onContext);
     };
     const detach = () => {
-      const idoc = iframe.contentDocument;
-      if (idoc === null) return;
       idoc.removeEventListener("click", onClick);
       idoc.removeEventListener("mousemove", onMove);
       idoc.removeEventListener("mouseleave", onLeave);
@@ -254,10 +253,11 @@ const FrameDocument = ({
       mutations.disconnect();
       themeObserver.disconnect();
       if (fitFrame !== null) cancelAnimationFrame(fitFrame);
+      cleanupDocument?.();
     };
-    // `document_` is this frame's React key, so it is fixed for the frame's whole
-    // life: the effect installs the document once and never rewrites it.
-  }, [document_]);
+    // The frame key includes source, scheme, and preparation identity so a live
+    // portal never survives replacement of its document.
+  }, [document_, mount]);
 
   return (
     <iframe
@@ -283,11 +283,21 @@ const FrameDocument = ({
 };
 
 export const EmailFrame = ({ html, forceColorScheme, ...rest }: EmailFrameProps): ReactNode => {
-  const document_ = forceColorScheme === undefined ? html : forceScheme(html, forceColorScheme);
+  const prepare = useContext(PreviewDocumentContext);
+  const prepared = useMemo(() => prepare?.(html), [html, prepare]);
+  const [preparation, setPreparation] = useState({ prepare, generation: 0 });
+  if (preparation.prepare !== prepare) {
+    setPreparation({ prepare, generation: preparation.generation + 1 });
+  }
+  const preparedHtml = prepared?.html ?? html;
+  const document_ =
+    forceColorScheme === undefined ? preparedHtml : forceScheme(preparedHtml, forceColorScheme);
   return (
     <FrameDocument
-      key={document_}
+      // Original HTML remains part of identity even when preparation strips the changed content.
+      key={`${preparation.generation}:${forceColorScheme ?? ""}:${html}`}
       document_={document_}
+      mount={prepared?.mount}
       dark={forceColorScheme === "dark"}
       {...rest}
     />
diff --git a/packages/editor/src/canvas/preview-document.ts b/packages/editor/src/canvas/preview-document.ts
new file mode 100644
index 0000000..a560fc8
--- /dev/null
+++ b/packages/editor/src/canvas/preview-document.ts
@@ -0,0 +1,16 @@
+import { createContext } from "react";
+
+/** Host-prepared HTML and resources owned by one mounted preview document. */
+export interface PreparedPreviewDocument {
+  /** The only HTML written to the attached iframe's parser. */
+  readonly html: string;
+  /**
+   * Runs synchronously after document.close(), before measurement and paint.
+   * Returns cleanup for this exact document, including StrictMode effect replay.
+   */
+  readonly mount: (document: Document) => () => void;
+}
+
+export const PreviewDocumentContext = createContext<
+  ((html: string) => PreparedPreviewDocument) | undefined
+>(undefined);
diff --git a/packages/editor/src/shell.ts b/packages/editor/src/shell.ts
index 2cc2b95..a10a962 100644
--- a/packages/editor/src/shell.ts
+++ b/packages/editor/src/shell.ts
@@ -6,6 +6,7 @@
 // reads the instance store directly.
 export { EditorProvider } from "./state/provider";
 export type { EditorProviderProps } from "./state/provider";
+export type { PreparedPreviewDocument } from "./canvas/preview-document";
 export type { UserSelection } from "./state/store";
 export type { CheckItem, CheckSeverity } from "./state/types";
 export { EditorShell } from "./chrome/shell";
diff --git a/packages/editor/src/state/provider.tsx b/packages/editor/src/state/provider.tsx
index eddfd1f..4100656 100644
--- a/packages/editor/src/state/provider.tsx
+++ b/packages/editor/src/state/provider.tsx
@@ -1,6 +1,7 @@
 import type { AsyncEditorHost } from "@samva/editor/host";
 import { useEffect, useLayoutEffect, useMemo, useState, type ReactNode } from "react";
 
+import { PreviewDocumentContext, type PreparedPreviewDocument } from "../canvas/preview-document";
 import { EditorIconsProvider } from "../chrome/icon-context";
 import { DEFAULT_EDITOR_ICONS, type EditorIcons } from "../chrome/icon-set";
 import { EditorBundleContext } from "./context";
@@ -21,6 +22,12 @@ export interface EditorProviderProps {
    * selection was made in. A selection the editor rebinds to a newer render is not reported again.
    */
   readonly onSelectElement?: ((selection: UserSelection) => void) | undefined;
+  /**
+   * Pure, synchronous preparation of the original host HTML before any attached parser sees it.
+   * Applies to canvas and Preview; keep identity stable to retain mounted frames.
+   * Changing identity replaces frames without resetting the editor session.
+   */
+  readonly preparePreviewDocument?: ((html: string) => PreparedPreviewDocument) | undefined;
   readonly children: ReactNode;
 }
 
@@ -36,6 +43,7 @@ export function EditorProvider({
   checks = NO_CHECKS,
   icons,
   onSelectElement,
+  preparePreviewDocument,
   children,
 }: EditorProviderProps) {
   const [bundle, setBundle] = useState(() => createEditorBundle(host, { hostChecks: checks }));
@@ -68,7 +76,9 @@ export function EditorProvider({
 
   return (
     <EditorBundleContext.Provider value={bundle}>
-      <EditorIconsProvider value={iconSet}>{children}</EditorIconsProvider>
+      <PreviewDocumentContext.Provider value={preparePreviewDocument}>
+        <EditorIconsProvider value={iconSet}>{children}</EditorIconsProvider>
+      </PreviewDocumentContext.Provider>
     </EditorBundleContext.Provider>
   );
 }
diff --git a/packages/editor/tests/preview-document.test.tsx b/packages/editor/tests/preview-document.test.tsx
new file mode 100644
index 0000000..21e97e1
--- /dev/null
+++ b/packages/editor/tests/preview-document.test.tsx
@@ -0,0 +1,141 @@
+/**
+ * @vitest-environment happy-dom
+ * @jsxImportSource react
+ */
+import { afterEach, describe, expect, it, vi } from "@effect/vitest";
+import { cleanup, render } from "@testing-library/react";
+import { StrictMode } from "react";
+
+import { EmailFrame } from "../src/canvas/email-frame";
+import { EditorProvider, type PreparedPreviewDocument } from "../src/shell";
+import { mockEditor } from "./mock-host";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const HTML =
+  "<html><head><style>@media (prefers-color-scheme: dark){body{color:red}}</style></head><body><p>Original</p></body></html>";
+
+describe("preview document preparation", () => {
+  it("writes prepared HTML and mounts before the first frame measurement", async () => {
+    const { host } = await mockEditor();
+    const measured: string[] = [];
+    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function (
+      this: HTMLElement,
+    ) {
+      if (this.tagName === "BODY") measured.push(this.dataset.mounted ?? "missing");
+      return new DOMRect(0, 0, 600, 123);
+    });
+    const prepare = vi.fn((html: string): PreparedPreviewDocument => ({
+      html: html.replace("Original", "Prepared"),
+      mount: (document) => {
+        expect(document.body.textContent).toBe("Prepared");
+        document.body.dataset.mounted = "yes";
+        return () => delete document.body.dataset.mounted;
+      },
+    }));
+    const view = render(
+      <EditorProvider host={host} preparePreviewDocument={prepare}>
+        <EmailFrame html={HTML} width={600} />
+      </EditorProvider>,
+    );
+    expect(prepare).toHaveBeenCalledWith(HTML);
+    expect(measured).toEqual(["yes"]);
+    expect(view.container.querySelector("iframe")?.style.height).toBe("123px");
+  });
+
+  it("replaces resources for callback identity and original HTML even if preparation is identical", async () => {
+    const { host } = await mockEditor();
+    const mounted: Document[] = [];
+    const cleaned: Document[] = [];
+    const prepare = (_html: string): PreparedPreviewDocument => ({
+      html: "<html><body>Same prepared output</body></html>",
+      mount: (document) => {
+        mounted.push(document);
+        return () => {
+          cleaned.push(document);
+        };
+      },
+    });
+    const tree = (html: string, preparation = prepare, width = 600) => (
+      <EditorProvider host={host} preparePreviewDocument={preparation}>
+        <EmailFrame html={html} width={width} overlay={<span data-overlay="" />} />
+      </EditorProvider>
+    );
+    const view = render(tree(HTML));
+    const firstFrame = view.container.querySelector("iframe");
+    view.rerender(tree(HTML, prepare, 320));
+    expect(view.container.querySelector("iframe")).toBe(firstFrame);
+    expect(mounted).toHaveLength(1);
+    view.rerender(tree(`${HTML}<!-- another revision -->`));
+    expect(cleaned).toEqual([mounted[0]]);
+    expect(mounted[1]).not.toBe(mounted[0]);
+    view.rerender(tree(`${HTML}<!-- another revision -->`, (html) => prepare(html)));
+    expect(cleaned).toEqual(mounted.slice(0, 2));
+    expect(mounted[2]?.querySelector("[data-overlay]")).not.toBeNull();
+    view.unmount();
+    expect(cleaned).toEqual(mounted);
+  });
+
+  it("balances StrictMode replay and omission restores default HTML", async () => {
+    const { host } = await mockEditor();
+    const live = new Set<Document>();
+    const mounts = vi.fn((document: Document) => {
+      expect(live.has(document)).toBe(false);
+      live.add(document);
+      return () => {
+        expect(live.delete(document)).toBe(true);
+      };
+    });
+    const prepare = (_html: string): PreparedPreviewDocument => ({
+      html: "<html><body>Prepared</body></html>",
+      mount: mounts,
+    });
+    const tree = (preparation?: typeof prepare) => (
+      <StrictMode>
+        <EditorProvider host={host} preparePreviewDocument={preparation}>
+          <EmailFrame html={HTML} width={600} />
+        </EditorProvider>
+      </StrictMode>
+    );
+    const view = render(tree(prepare));
+    expect(mounts.mock.calls.length).toBeGreaterThanOrEqual(2);
+    expect(live.size).toBe(1);
+    view.rerender(tree());
+    expect(live.size).toBe(0);
+    expect(view.container.querySelector("iframe")?.contentDocument?.body.textContent).toBe(
+      "Original",
+    );
+    view.unmount();
+    expect(live.size).toBe(0);
+  });
+
+  it("prepares original HTML before forced schemes and cleans each scheme document", async () => {
+    const { host } = await mockEditor();
+    const cleaned: Document[] = [];
+    const prepare = vi.fn((html: string): PreparedPreviewDocument => ({
+      html,
+      mount: (document) => () => {
+        cleaned.push(document);
+      },
+    }));
+    const tree = (scheme: "light" | "dark") => (
+      <EditorProvider host={host} preparePreviewDocument={prepare}>
+        <EmailFrame html={HTML} forceColorScheme={scheme} width={600} />
+      </EditorProvider>
+    );
+    const view = render(tree("light"));
+    const light = view.container.querySelector("iframe")!.contentDocument!;
+    expect(light.head.textContent).toContain("@media not all");
+    view.rerender(tree("dark"));
+    const dark = view.container.querySelector("iframe")!.contentDocument!;
+    expect(dark.head.textContent).toContain("@media all");
+    expect(prepare).toHaveBeenCalledTimes(1);
+    expect(prepare).toHaveBeenCalledWith(HTML);
+    expect(cleaned).toEqual([light]);
+    view.unmount();
+    expect(cleaned).toEqual([light, dark]);
+  });
+});

From 5acc21edf27edaa0c78525f08badd16c05907728 Mon Sep 17 00:00:00 2001
From: Saatvik Arya <aryasaatvik@gmail.com>
Date: Mon, 5 Oct 2026 10:30:26 +0530
Subject: [PATCH 2/2] fix(editor): prepare forced schemes before parsing
 previews

---
 packages/editor/README.md                     |   6 +-
 .../browser-tests/preview-document.spec.ts    | 218 ++++++++++++++++++
 packages/editor/dev/preview-document.html     |  11 +
 packages/editor/dev/preview-document.tsx      | 188 +++++++++++++++
 packages/editor/src/canvas/email-frame.tsx    |   7 +-
 packages/editor/src/state/provider.tsx        |   5 +-
 .../editor/tests/preview-document.test.tsx    |   7 +-
 7 files changed, 430 insertions(+), 12 deletions(-)
 create mode 100644 packages/editor/browser-tests/preview-document.spec.ts
 create mode 100644 packages/editor/dev/preview-document.html
 create mode 100644 packages/editor/dev/preview-document.tsx

diff --git a/packages/editor/README.md b/packages/editor/README.md
index c6654f2..e7c5f31 100644
--- a/packages/editor/README.md
+++ b/packages/editor/README.md
@@ -76,9 +76,9 @@ leave the static profile is refused with its reason.
 ## Preparing preview documents
 
 `EditorProvider` accepts `preparePreviewDocument?: (html: string) => PreparedPreviewDocument`.
-Both the editing canvas and Preview call it with the original host HTML before writing to the
-attached iframe. Only the returned `html` reaches that parser. Preview applies its forced
-light/dark scheme to the prepared HTML.
+Both the editing canvas and Preview call it before writing to the attached iframe. Only the
+returned `html` reaches that parser. Canvas passes the original host HTML; Preview applies its
+forced light/dark scheme before calling preparation.
 
 ```tsx
 import { EditorProvider, EditorShell, type PreparedPreviewDocument } from "@samva/editor/shell";
diff --git a/packages/editor/browser-tests/preview-document.spec.ts b/packages/editor/browser-tests/preview-document.spec.ts
new file mode 100644
index 0000000..291f068
--- /dev/null
+++ b/packages/editor/browser-tests/preview-document.spec.ts
@@ -0,0 +1,218 @@
+import { expect, test, type Page } from "@playwright/test";
+
+declare global {
+  interface Window {
+    previewParser: {
+      writes: string[];
+      violations: string[];
+      stages: Array<{ kind: string; document: number; mounted: boolean }>;
+    };
+  }
+}
+
+const installParserProbe = async (page: Page) => {
+  await page.addInitScript(() => {
+    window.previewParser = { writes: [], violations: [], stages: [] };
+    const descriptor = Object.getOwnPropertyDescriptor(
+      HTMLIFrameElement.prototype,
+      "contentDocument",
+    )!;
+    const seen = new WeakSet<Document>();
+    let nextId = 0;
+    Object.defineProperty(HTMLIFrameElement.prototype, "contentDocument", {
+      ...descriptor,
+      get() {
+        const document: Document | null = descriptor.get!.call(this);
+        if (document !== null && !seen.has(document)) {
+          seen.add(document);
+          const id = ++nextId;
+          const write = document.write.bind(document);
+          const close = document.close.bind(document);
+          document.write = (...html) => {
+            document.addEventListener("securitypolicyviolation", (event) => {
+              window.previewParser.violations.push(event.violatedDirective);
+            });
+            window.previewParser.writes.push(html.join(""));
+            window.previewParser.stages.push({ kind: "write", document: id, mounted: false });
+            write(...html);
+            const body = document.body;
+            const measure = body.getBoundingClientRect.bind(body);
+            body.getBoundingClientRect = () => {
+              window.previewParser.stages.push({
+                kind: "measure",
+                document: id,
+                mounted: body.dataset.preparationPolicy !== undefined,
+              });
+              return measure();
+            };
+          };
+          document.close = () => {
+            close();
+            window.previewParser.stages.push({ kind: "close", document: id, mounted: false });
+          };
+        }
+        return document;
+      },
+    });
+  });
+};
+
+const settleFrames = async (page: Page) => {
+  await page.evaluate(async () => {
+    await Promise.all(
+      Array.from(
+        document.querySelectorAll("iframe"),
+        (frame) => frame.contentDocument!.fonts.ready,
+      ),
+    );
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    );
+  });
+};
+
+const openFixture = async (page: Page, prepare = true) => {
+  await installParserProbe(page);
+  await page.goto(`/preview-document.html${prepare ? "" : "?prepare=off"}`);
+  await expect(page.locator("iframe")).toHaveCount(1);
+  await expect(page.locator("iframe").contentFrame().locator("#preparation-target")).toBeVisible();
+};
+
+test("prewrite preparation prevents parser font requests and CSP events in canvas and both Preview schemes", async ({
+  page,
+}) => {
+  const requests: string[] = [];
+  page.on("request", (request) => {
+    if (request.url().includes("/preview-font")) requests.push(request.url());
+  });
+  await openFixture(page);
+  await expect(page.locator("iframe")).toHaveJSProperty("clientHeight", 240);
+  await page.getByTestId("topbar.preview").click();
+  await expect(page.locator("iframe")).toHaveCount(2);
+  await expect(
+    page.locator("iframe").nth(1).contentFrame().locator("#preparation-target"),
+  ).toHaveCSS("color", "rgb(255, 0, 0)");
+  await page.getByTestId("preview-overlay.scheme.dark").click();
+  await expect(
+    page.locator("iframe").nth(1).contentFrame().locator("#preparation-target"),
+  ).toHaveCSS("color", "rgb(0, 0, 255)");
+  await page.getByTestId("preview-overlay.scheme.light").click();
+  await expect(
+    page.locator("iframe").nth(1).contentFrame().locator("#preparation-target"),
+  ).toHaveCSS("color", "rgb(255, 0, 0)");
+  await settleFrames(page);
+  const evidence = await page.evaluate(() => ({
+    parser: window.previewParser,
+    lifecycle: window.previewLifecycle,
+  }));
+  expect(evidence.parser.writes.length).toBeGreaterThan(0);
+  expect(evidence.parser.writes.every((html) => !html.includes("/preview-font"))).toBe(true);
+  expect(requests).toEqual([]);
+  expect(evidence.parser.violations).toEqual([]);
+  expect(
+    evidence.parser.stages
+      .filter((stage) => stage.kind === "measure")
+      .every((stage) => stage.mounted),
+  ).toBe(true);
+  for (const stage of evidence.parser.stages.filter((candidate) => candidate.kind === "measure")) {
+    const stages = evidence.parser.stages.filter(
+      (candidate) => candidate.document === stage.document,
+    );
+    expect(stages.findIndex((candidate) => candidate.kind === "close")).toBeLessThan(
+      stages.indexOf(stage),
+    );
+  }
+  expect(
+    evidence.lifecycle.events
+      .filter((event) => event.kind === "mount")
+      .map((event) => event.scheme),
+  ).toEqual(expect.arrayContaining(["auto", "light", "dark"]));
+  expect(evidence.lifecycle.duplicates).toBe(0);
+});
+
+test("default parsing is a positive control for font network and CSP instrumentation", async ({
+  page,
+}) => {
+  const requests: string[] = [];
+  await page.route("**/preview-font-import.css", (route) =>
+    route.fulfill({
+      contentType: "text/css",
+      body: "@font-face{font-family:ImportedFont;src:url('/preview-font-imported.woff2')} h1{font-family:ImportedFont}",
+    }),
+  );
+  page.on("request", (request) => {
+    if (request.url().includes("/preview-font")) requests.push(request.url());
+  });
+  await openFixture(page, false);
+  await expect.poll(() => requests.length).toBeGreaterThan(0);
+  await expect
+    .poll(() => page.evaluate(() => window.previewParser.violations.length))
+    .toBeGreaterThan(0);
+  const evidence = await page.evaluate(() => window.previewParser);
+  expect(evidence.writes.some((html) => html.includes("/preview-font"))).toBe(true);
+  expect(evidence.violations).toContain("font-src");
+  expect(await page.evaluate(() => window.previewLifecycle.events)).toEqual([]);
+});
+
+test("StrictMode, selection overlays, revision changes, and callback identity preserve exact resource ownership", async ({
+  page,
+}) => {
+  await openFixture(page);
+  let events = await page.evaluate(() => window.previewLifecycle.events);
+  expect(events.filter((event) => event.kind === "cleanup").length).toBeGreaterThan(0);
+  expect(await page.evaluate(() => window.previewLifecycle.live)).toBe(1);
+  await page.locator("iframe").contentFrame().locator("#preparation-target").click();
+  await expect(page.locator("iframe").contentFrame().locator("[data-samva-chip]")).toBeVisible();
+  const before = events.length;
+  await page.getByTestId("preparation.unrelated").click();
+  await settleFrames(page);
+  expect(await page.evaluate(() => window.previewLifecycle.events.length)).toBe(before);
+  await page.getByTestId("preparation.revision").click();
+  await expect
+    .poll(() => page.evaluate(() => window.previewLifecycle.events.length))
+    .toBeGreaterThan(before);
+  events = await page.evaluate(() => window.previewLifecycle.events);
+  const revisionMount = events.findLast((event) => event.kind === "mount")!;
+  await page.getByTestId("preparation.policy").click();
+  await expect(page.locator("iframe").contentFrame().locator("body")).toHaveAttribute(
+    "data-preparation-policy",
+    "2",
+  );
+  events = await page.evaluate(() => window.previewLifecycle.events);
+  expect(events.findLast((event) => event.kind === "mount")!.document).not.toBe(
+    revisionMount.document,
+  );
+  expect(
+    events.some((event) => event.kind === "cleanup" && event.document === revisionMount.document),
+  ).toBe(true);
+  await page.getByTestId("topbar.preview").click();
+  await expect.poll(() => page.evaluate(() => window.previewLifecycle.live)).toBe(2);
+  await page.getByTestId("preview-overlay.close").click();
+  await expect.poll(() => page.evaluate(() => window.previewLifecycle.live)).toBe(1);
+  await page.getByTestId("preparation.unmount").click();
+  await expect(page.locator("iframe")).toHaveCount(0);
+  const lifecycle = await page.evaluate(() => window.previewLifecycle);
+  expect(lifecycle.live).toBe(0);
+  expect(lifecycle.duplicates).toBe(0);
+  expect(lifecycle.events.every((event) => event.intact)).toBe(true);
+  for (const id of new Set(lifecycle.events.map((event) => event.document))) {
+    const owned = lifecycle.events.filter((event) => event.document === id);
+    expect(owned.filter((event) => event.kind === "mount").length).toBe(
+      owned.filter((event) => event.kind === "cleanup").length,
+    );
+  }
+});
+
+test("removing preparation disposes resources and restores the original host HTML", async ({
+  page,
+}) => {
+  await openFixture(page);
+  await page.getByTestId("preparation.disable").click();
+  await expect(
+    page.locator("iframe").contentFrame().locator("style[data-test-fonts]"),
+  ).toBeAttached();
+  await expect.poll(() => page.evaluate(() => window.previewLifecycle.live)).toBe(0);
+  expect(
+    (await page.evaluate(() => window.previewLifecycle.events)).every((event) => event.intact),
+  ).toBe(true);
+});
diff --git a/packages/editor/dev/preview-document.html b/packages/editor/dev/preview-document.html
new file mode 100644
index 0000000..ca65f4f
--- /dev/null
+++ b/packages/editor/dev/preview-document.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Preview document contract</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./preview-document.tsx"></script>
+  </body>
+</html>
diff --git a/packages/editor/dev/preview-document.tsx b/packages/editor/dev/preview-document.tsx
new file mode 100644
index 0000000..4532748
--- /dev/null
+++ b/packages/editor/dev/preview-document.tsx
@@ -0,0 +1,188 @@
+import type { AsyncEditableEditorHost, EmailRender } from "@samva/editor/host";
+import { EditorProvider, EditorShell, type PreparedPreviewDocument } from "@samva/editor/shell";
+import { StrictMode, useMemo, useState } from "react";
+import { createRoot } from "react-dom/client";
+
+import { useEditorStoreApi } from "../src/state/context";
+import { createPromiseHost } from "./promise-host";
+
+// oxlint-disable-next-line import/no-unassigned-import -- The browser fixture uses the shell's real styles.
+import "./styles.css";
+
+interface LifecycleEvent {
+  readonly kind: "mount" | "cleanup";
+  readonly document: number;
+  readonly policy: number;
+  readonly intact: boolean;
+  readonly scheme: string;
+}
+
+declare global {
+  interface Window {
+    previewLifecycle: { events: LifecycleEvent[]; live: number; duplicates: number };
+  }
+}
+
+window.previewLifecycle = { events: [], live: 0, duplicates: 0 };
+const live = new Set<Document>();
+const documentIds = new WeakMap<Document, number>();
+let nextDocumentId = 0;
+
+const fixtureHtml = (revision: string) => `<!doctype html><html><head>
+<meta http-equiv="Content-Security-Policy" content="font-src 'none'; style-src 'unsafe-inline' 'self'">
+<style data-test-fonts>
+@import url('/preview-font-import.css');
+@font-face {font-family: ParserFont; src: url('/preview-font.woff2')}
+body {font-family: ParserFont}
+</style>
+<style>#preparation-target{color:rgb(255,0,0)}
+@media (prefers-color-scheme: dark){#preparation-target{color:rgb(0,0,255)}}</style>
+</head><body><h1 id="preparation-target" data-samva-instance="0.0.1">Prepared preview</h1>
+<!-- ${revision} --></body></html>`;
+
+const withFixture = (render: EmailRender | null): EmailRender | null =>
+  render === null ? null : { ...render, html: fixtureHtml(render.revision) };
+
+const createHost = (): AsyncEditableEditorHost => {
+  const host = createPromiseHost();
+  return {
+    ...host,
+    document: {
+      open: async (onChange) => {
+        const session = await host.document.open((change) =>
+          onChange(
+            change.channel === "email" ? { ...change, render: withFixture(change.render) } : change,
+          ),
+        );
+        return {
+          ...session,
+          initial:
+            session.initial.channel === "email"
+              ? { ...session.initial, render: withFixture(session.initial.render) }
+              : session.initial,
+        };
+      },
+    },
+  };
+};
+
+function RevisionButton() {
+  const store = useEditorStoreApi();
+  return (
+    <button
+      type="button"
+      data-testid="preparation.revision"
+      onClick={() => {
+        const { doc } = store.getState();
+        if (doc !== null && host.writer !== undefined) {
+          void host.writer.save({
+            kind: "authoredSource",
+            baseRev: doc.rev,
+            authoredSource: doc.origin.authoredSource,
+          });
+        }
+      }}
+    >
+      Change revision
+    </button>
+  );
+}
+
+const host = createHost();
+
+function PreviewDocumentFixture() {
+  const [policy, setPolicy] = useState(1);
+  const [mounted, setMounted] = useState(true);
+  const [unrelated, setUnrelated] = useState(0);
+  const [enabled, setEnabled] = useState(
+    new URLSearchParams(location.search).get("prepare") !== "off",
+  );
+  const prepare = useMemo(
+    () =>
+      (html: string): PreparedPreviewDocument => ({
+        html: html.replace(/<style data-test-fonts>[\s\S]*?<\/style>/, ""),
+        mount(document) {
+          const id = documentIds.get(document) ?? ++nextDocumentId;
+          documentIds.set(document, id);
+          if (live.has(document)) window.previewLifecycle.duplicates += 1;
+          live.add(document);
+          const body = document.body;
+          body.dataset.preparationPolicy = String(policy);
+          const style = document.createElement("style");
+          style.dataset.preparationResource = String(policy);
+          style.textContent = "body{min-height:240px}";
+          document.head.appendChild(style);
+          const scheme = html.includes("@media all")
+            ? "dark"
+            : html.includes("@media not all")
+              ? "light"
+              : "auto";
+          window.previewLifecycle.events.push({
+            kind: "mount",
+            document: id,
+            policy,
+            intact: body.isConnected,
+            scheme,
+          });
+          window.previewLifecycle.live = live.size;
+          return () => {
+            window.previewLifecycle.events.push({
+              kind: "cleanup",
+              document: id,
+              policy,
+              intact:
+                body.ownerDocument === document &&
+                body.dataset.preparationPolicy === String(policy),
+              scheme,
+            });
+            style.remove();
+            delete body.dataset.preparationPolicy;
+            live.delete(document);
+            window.previewLifecycle.live = live.size;
+          };
+        },
+      }),
+    [policy],
+  );
+  return (
+    <>
+      <div style={{ position: "fixed", top: 0, zIndex: 2147483647 }}>
+        <button
+          type="button"
+          data-testid="preparation.policy"
+          onClick={() => setPolicy(policy + 1)}
+        >
+          Change policy
+        </button>
+        <button
+          type="button"
+          data-testid="preparation.unrelated"
+          onClick={() => setUnrelated(unrelated + 1)}
+        >
+          Rerender {unrelated}
+        </button>
+        <button type="button" data-testid="preparation.disable" onClick={() => setEnabled(false)}>
+          Default HTML
+        </button>
+        <button type="button" data-testid="preparation.unmount" onClick={() => setMounted(false)}>
+          Unmount
+        </button>
+      </div>
+      {mounted && (
+        <EditorProvider host={host} preparePreviewDocument={enabled ? prepare : undefined}>
+          <EditorShell
+            contributions={[
+              { slot: "toolbar.actions", id: "revision", render: () => <RevisionButton /> },
+            ]}
+          />
+        </EditorProvider>
+      )}
+    </>
+  );
+}
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <PreviewDocumentFixture />
+  </StrictMode>,
+);
diff --git a/packages/editor/src/canvas/email-frame.tsx b/packages/editor/src/canvas/email-frame.tsx
index 5e87764..8dd9596 100644
--- a/packages/editor/src/canvas/email-frame.tsx
+++ b/packages/editor/src/canvas/email-frame.tsx
@@ -284,14 +284,13 @@ const FrameDocument = ({
 
 export const EmailFrame = ({ html, forceColorScheme, ...rest }: EmailFrameProps): ReactNode => {
   const prepare = useContext(PreviewDocumentContext);
-  const prepared = useMemo(() => prepare?.(html), [html, prepare]);
+  const schemeHtml = forceColorScheme === undefined ? html : forceScheme(html, forceColorScheme);
+  const prepared = useMemo(() => prepare?.(schemeHtml), [schemeHtml, prepare]);
   const [preparation, setPreparation] = useState({ prepare, generation: 0 });
   if (preparation.prepare !== prepare) {
     setPreparation({ prepare, generation: preparation.generation + 1 });
   }
-  const preparedHtml = prepared?.html ?? html;
-  const document_ =
-    forceColorScheme === undefined ? preparedHtml : forceScheme(preparedHtml, forceColorScheme);
+  const document_ = prepared?.html ?? schemeHtml;
   return (
     <FrameDocument
       // Original HTML remains part of identity even when preparation strips the changed content.
diff --git a/packages/editor/src/state/provider.tsx b/packages/editor/src/state/provider.tsx
index 4100656..91ebf1f 100644
--- a/packages/editor/src/state/provider.tsx
+++ b/packages/editor/src/state/provider.tsx
@@ -23,8 +23,9 @@ export interface EditorProviderProps {
    */
   readonly onSelectElement?: ((selection: UserSelection) => void) | undefined;
   /**
-   * Pure, synchronous preparation of the original host HTML before any attached parser sees it.
-   * Applies to canvas and Preview; keep identity stable to retain mounted frames.
+   * Pure, synchronous preparation before any attached parser sees the HTML.
+   * Preview applies its forced color scheme first; canvas passes the host HTML.
+   * Keep identity stable to retain mounted frames.
    * Changing identity replaces frames without resetting the editor session.
    */
   readonly preparePreviewDocument?: ((html: string) => PreparedPreviewDocument) | undefined;
diff --git a/packages/editor/tests/preview-document.test.tsx b/packages/editor/tests/preview-document.test.tsx
index 21e97e1..42fbf29 100644
--- a/packages/editor/tests/preview-document.test.tsx
+++ b/packages/editor/tests/preview-document.test.tsx
@@ -112,7 +112,7 @@ describe("preview document preparation", () => {
     expect(live.size).toBe(0);
   });
 
-  it("prepares original HTML before forced schemes and cleans each scheme document", async () => {
+  it("prepares each forced scheme before parsing and cleans each scheme document", async () => {
     const { host } = await mockEditor();
     const cleaned: Document[] = [];
     const prepare = vi.fn((html: string): PreparedPreviewDocument => ({
@@ -132,8 +132,9 @@ describe("preview document preparation", () => {
     view.rerender(tree("dark"));
     const dark = view.container.querySelector("iframe")!.contentDocument!;
     expect(dark.head.textContent).toContain("@media all");
-    expect(prepare).toHaveBeenCalledTimes(1);
-    expect(prepare).toHaveBeenCalledWith(HTML);
+    expect(prepare).toHaveBeenCalledTimes(2);
+    expect(prepare.mock.calls[0]?.[0]).toContain("@media not all");
+    expect(prepare.mock.calls[1]?.[0]).toContain("@media all");
     expect(cleaned).toEqual([light]);
     view.unmount();
     expect(cleaned).toEqual([light, dark]);