diff --git a/.changeset/crisp-plums-roll.md b/.changeset/crisp-plums-roll.md
new file mode 100644
index 0000000..535f005
--- /dev/null
+++ b/.changeset/crisp-plums-roll.md
@@ -0,0 +1,5 @@
+---
+"virtual-frame": patch
+---
+
+Support native dialog/popover elements
diff --git a/examples/shared/dialog.html b/examples/shared/dialog.html
new file mode 100644
index 0000000..5041139
--- /dev/null
+++ b/examples/shared/dialog.html
@@ -0,0 +1,381 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Dialog / Popover projection</title>
+    <style>
+      :root {
+        --bg: #0f1117;
+        --surface: #1a1d27;
+        --surface-2: #232733;
+        --border: #2d3140;
+        --text: #e4e6ef;
+        --text-muted: #8b8fa3;
+        --accent: #6366f1;
+        --accent-hover: #818cf8;
+        --green: #22c55e;
+        --red: #ef4444;
+        --amber: #f59e0b;
+        --radius: 12px;
+        --radius-sm: 8px;
+      }
+
+      *,
+      *::before,
+      *::after {
+        box-sizing: border-box;
+      }
+
+      /* Scoped reset — do NOT blanket-zero margin/padding,
+         that would override UA `margin: auto` on `dialog[open]` and `[popover]`,
+         which is how the browser centers them in the viewport top layer. */
+      body,
+      h1,
+      h2,
+      h3,
+      p {
+        margin: 0;
+        padding: 0;
+      }
+
+      body {
+        font-family:
+          "Inter",
+          system-ui,
+          -apple-system,
+          sans-serif;
+        background: var(--bg);
+        color: var(--text);
+        line-height: 1.5;
+        padding: 24px;
+        min-height: 100vh;
+      }
+
+      h1 {
+        font-size: 18px;
+        font-weight: 600;
+        margin-bottom: 4px;
+      }
+
+      .sub {
+        font-size: 13px;
+        color: var(--text-muted);
+        margin-bottom: 20px;
+      }
+
+      .grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+        gap: 16px;
+        margin-bottom: 20px;
+      }
+
+      .card {
+        background: var(--surface);
+        border: 1px solid var(--border);
+        border-radius: var(--radius);
+        padding: 16px;
+      }
+
+      .card h2 {
+        font-size: 13px;
+        font-weight: 600;
+        margin-bottom: 6px;
+      }
+
+      .card p {
+        font-size: 12px;
+        color: var(--text-muted);
+        margin-bottom: 12px;
+      }
+
+      button {
+        background: var(--accent);
+        color: white;
+        border: none;
+        padding: 8px 14px;
+        border-radius: var(--radius-sm);
+        font-size: 13px;
+        font-weight: 500;
+        cursor: pointer;
+        font-family: inherit;
+        transition: background 0.15s;
+      }
+
+      button:hover {
+        background: var(--accent-hover);
+      }
+
+      button.secondary {
+        background: var(--surface-2);
+        color: var(--text);
+        border: 1px solid var(--border);
+      }
+
+      button.danger {
+        background: var(--red);
+      }
+
+      .log {
+        font-family: "SF Mono", "Cascadia Code", monospace;
+        font-size: 11px;
+        background: var(--bg);
+        border: 1px solid var(--border);
+        border-radius: var(--radius-sm);
+        padding: 10px 12px;
+        max-height: 120px;
+        overflow-y: auto;
+        color: var(--text-muted);
+        line-height: 1.7;
+      }
+
+      .log .ok {
+        color: var(--green);
+      }
+
+      .log .info {
+        color: var(--accent-hover);
+      }
+
+      /* ── Native <dialog> ───────────────────────── */
+      dialog {
+        background: var(--surface);
+        color: var(--text);
+        border: 1px solid var(--border);
+        border-radius: var(--radius);
+        padding: 24px;
+        min-width: 320px;
+        max-width: 480px;
+        box-shadow: 0 24px 48px rgba(0, 0, 0, 0.4);
+      }
+
+      dialog::backdrop {
+        background: rgba(15, 17, 23, 0.7);
+        backdrop-filter: blur(4px);
+      }
+
+      dialog h3 {
+        font-size: 16px;
+        font-weight: 600;
+        margin-bottom: 8px;
+      }
+
+      dialog p {
+        font-size: 13px;
+        color: var(--text-muted);
+        margin-bottom: 16px;
+      }
+
+      dialog form {
+        display: flex;
+        flex-direction: column;
+        gap: 10px;
+        margin-bottom: 16px;
+      }
+
+      dialog label {
+        font-size: 12px;
+        color: var(--text-muted);
+      }
+
+      dialog input[type="text"],
+      dialog input[type="email"] {
+        background: var(--surface-2);
+        border: 1px solid var(--border);
+        color: var(--text);
+        padding: 8px 10px;
+        border-radius: var(--radius-sm);
+        font-size: 13px;
+        font-family: inherit;
+        width: 100%;
+      }
+
+      dialog input:focus {
+        outline: 2px solid var(--accent);
+        outline-offset: 1px;
+      }
+
+      .dialog-actions {
+        display: flex;
+        justify-content: flex-end;
+        gap: 8px;
+      }
+
+      /* ── Popover ──────────────────────────────── */
+      [popover] {
+        background: var(--surface);
+        color: var(--text);
+        border: 1px solid var(--border);
+        border-radius: var(--radius);
+        padding: 16px;
+        min-width: 240px;
+        box-shadow: 0 12px 32px rgba(0, 0, 0, 0.4);
+      }
+
+      [popover]::backdrop {
+        background: rgba(15, 17, 23, 0.4);
+      }
+
+      [popover] h3 {
+        font-size: 14px;
+        font-weight: 600;
+        margin-bottom: 6px;
+      }
+
+      [popover] p {
+        font-size: 12px;
+        color: var(--text-muted);
+        margin-bottom: 10px;
+      }
+
+      /* ── Deliberate visual clue: clipping parent ─── */
+      .clip-test {
+        background: var(--surface);
+        border: 1px solid var(--border);
+        border-radius: var(--radius);
+        padding: 16px;
+        overflow: hidden;
+        position: relative;
+        height: 120px;
+      }
+
+      .clip-test .inner {
+        position: absolute;
+        inset: 0;
+        display: grid;
+        place-items: center;
+        background: repeating-linear-gradient(
+          45deg,
+          var(--surface),
+          var(--surface) 10px,
+          var(--surface-2) 10px,
+          var(--surface-2) 20px
+        );
+      }
+
+      .clip-test p {
+        font-size: 11px;
+        color: var(--text-muted);
+        text-align: center;
+        max-width: 240px;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Top-layer projection test</h1>
+    <p class="sub">
+      Verifies that <code>&lt;dialog&gt;.showModal()</code> and the <code>popover</code> API escape
+      the &lt;virtual-frame&gt; stacking / clipping context via the browser's top layer.
+    </p>
+
+    <div class="grid">
+      <div class="card">
+        <h2>Native &lt;dialog&gt;</h2>
+        <p>Modal. Should cover the entire host viewport — not just the frame.</p>
+        <button id="openDialog">Open dialog</button>
+      </div>
+
+      <div class="card">
+        <h2>Popover API</h2>
+        <p>Non-modal. Should appear above everything with no manual z-index.</p>
+        <button popovertarget="pop1">Toggle popover</button>
+      </div>
+
+      <div class="card">
+        <h2>Nested in clipped parent</h2>
+        <p>
+          Dialog triggered from inside an <code>overflow: hidden</code> ancestor. The top layer
+          should still let it escape.
+        </p>
+        <div class="clip-test">
+          <div class="inner">
+            <button id="openDialogClipped" class="secondary">Open from here</button>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div class="card">
+      <h2>Event log</h2>
+      <p>Events fire on the source iframe — interactions on the projection are proxied.</p>
+      <div class="log" id="log">Waiting for events…</div>
+    </div>
+
+    <!-- ── Modal dialog ─────────────────────────── -->
+    <dialog id="demoDialog">
+      <h3>Sign-in required</h3>
+      <p>
+        This dialog was opened via <code>showModal()</code>. If you're reading this inside the
+        projection and it covers the whole page, top-layer escape works.
+      </p>
+      <form id="dialogForm">
+        <label>
+          Email
+          <input type="email" name="email" placeholder="you@example.com" required />
+        </label>
+        <label>
+          Code
+          <input type="text" name="code" placeholder="000000" required />
+        </label>
+      </form>
+      <div class="dialog-actions">
+        <button type="button" class="secondary" id="cancelDialog">Cancel</button>
+        <button type="submit" form="dialogForm">Submit</button>
+      </div>
+    </dialog>
+
+    <!-- ── Popover ──────────────────────────────── -->
+    <div popover id="pop1">
+      <h3>I'm a popover</h3>
+      <p>Opened via the <code>popovertarget</code> attribute. ESC or click-outside closes me.</p>
+      <button popovertarget="pop1" popovertargetaction="hide" class="secondary">Dismiss</button>
+    </div>
+
+    <script>
+      const log = document.getElementById("log");
+      let firstEvent = true;
+      function note(msg, cls = "info") {
+        if (firstEvent) {
+          log.textContent = "";
+          firstEvent = false;
+        }
+        const line = document.createElement("div");
+        line.className = cls;
+        line.textContent = `[${new Date().toLocaleTimeString()}] ${msg}`;
+        log.appendChild(line);
+        log.scrollTop = log.scrollHeight;
+      }
+
+      const dialog = document.getElementById("demoDialog");
+      document.getElementById("openDialog").addEventListener("click", () => {
+        dialog.showModal();
+        note("dialog.showModal() called");
+      });
+      document.getElementById("openDialogClipped").addEventListener("click", () => {
+        dialog.showModal();
+        note("dialog.showModal() called from clipped parent", "ok");
+      });
+      document.getElementById("cancelDialog").addEventListener("click", () => {
+        dialog.close("cancel");
+      });
+      document.getElementById("dialogForm").addEventListener("submit", (e) => {
+        e.preventDefault();
+        const fd = new FormData(e.target);
+        note(`form submit → email=${fd.get("email")} code=${fd.get("code")}`, "ok");
+        dialog.close("submit");
+      });
+      dialog.addEventListener("close", () => {
+        note(`dialog closed (returnValue=${dialog.returnValue || "none"})`, "ok");
+      });
+      dialog.addEventListener("cancel", () => {
+        note("dialog cancelled (ESC)");
+      });
+
+      const pop = document.getElementById("pop1");
+      pop.addEventListener("toggle", (e) => {
+        note(`popover toggled → ${e.newState}`);
+      });
+    </script>
+  </body>
+</html>
diff --git a/examples/vanilla/index.html b/examples/vanilla/index.html
index 88e0c26..a8cbaaf 100644
--- a/examples/vanilla/index.html
+++ b/examples/vanilla/index.html
@@ -174,6 +174,7 @@ <h3>How it works</h3>
         <button data-page="forms">Forms</button>
         <button data-page="media">Media</button>
         <button data-page="svg">SVG</button>
+        <button data-page="dialog">Dialog</button>
       </div>
       <button id="toggleIframe" onclick="toggleIframeVisibility()">Show Source</button>
       <button onclick="document.querySelector('virtual-frame')?.refresh()">
@@ -216,6 +217,7 @@ <h2>Projected via &lt;virtual-frame&gt;</h2>
         forms: "/forms.html",
         media: "/media.html",
         svg: "/svg.html",
+        dialog: "/dialog.html",
       };
 
       const tabs = document.getElementById("pageTabs");
diff --git a/packages/core/src/bridge.ts b/packages/core/src/bridge.ts
index 5a0cac4..4e5a085 100644
--- a/packages/core/src/bridge.ts
+++ b/packages/core/src/bridge.ts
@@ -486,6 +486,9 @@ export function createBridge(config: BridgeConfig = {}) {
       case "vf:navigate":
         window.location.href = d.url;
         break;
+      case "vf:invokeMethod":
+        invokeMethodOnSource(d);
+        break;
       case "vf:requestSnapshot":
         waitForReady().then(sendSnapshot);
         break;
@@ -703,6 +706,89 @@ export function createBridge(config: BridgeConfig = {}) {
     document.addEventListener("scroll", _scrollHandler, true);
   }
 
+  // ------------------------------------------------------------------
+  // Top-layer method interception  (bridge ⇄ host)
+  //
+  // showModal / show / close on <dialog> and showPopover / hidePopover /
+  // togglePopover on popover elements are imperative calls.  The browser
+  // only promotes the element to the document's top layer for the specific
+  // element the method was called on — mirroring the `open` attribute via
+  // MutationObserver is not enough.  To make the projected clone appear in
+  // the host's top layer (with real `::backdrop`, `:modal`, focus trap and
+  // correct `position: fixed` centering) we mirror the call itself:
+  //
+  //   source.showModal() → send vf:invokeMethod → host calls clone.showModal()
+  //
+  // The reverse direction is handled by the host re-sending vf:invokeMethod
+  // on the clone's `close` / `toggle` events — handled in the switch below.
+  // The _suppressInvoke flag prevents an echo loop when we call the
+  // original method in response to a host-origin invocation.
+  // ------------------------------------------------------------------
+
+  const TOP_LAYER_DIALOG_METHODS = ["showModal", "show", "close"] as const;
+  const TOP_LAYER_POPOVER_METHODS = ["showPopover", "hidePopover", "togglePopover"] as const;
+  let _suppressInvoke = 0;
+
+  function setupTopLayerInterception() {
+    if (typeof HTMLDialogElement !== "undefined") {
+      for (const method of TOP_LAYER_DIALOG_METHODS) {
+        const proto = HTMLDialogElement.prototype as any;
+        const original = proto[method];
+        if (typeof original !== "function") continue;
+        proto[method] = function (...args: unknown[]) {
+          const result = original.apply(this, args);
+          if (_suppressInvoke === 0) {
+            const id = getId(this);
+            if (id != null) {
+              send("vf:invokeMethod", {
+                targetId: id,
+                method,
+                args: args.length > 0 ? [args[0]] : [],
+              });
+            }
+          }
+          return result;
+        };
+      }
+    }
+
+    if (typeof HTMLElement !== "undefined") {
+      for (const method of TOP_LAYER_POPOVER_METHODS) {
+        const proto = HTMLElement.prototype as any;
+        const original = proto[method];
+        if (typeof original !== "function") continue;
+        proto[method] = function (...args: unknown[]) {
+          const result = original.apply(this, args);
+          if (_suppressInvoke === 0) {
+            const id = getId(this);
+            if (id != null) {
+              send("vf:invokeMethod", {
+                targetId: id,
+                method,
+                args: args.length > 0 ? [args[0]] : [],
+              });
+            }
+          }
+          return result;
+        };
+      }
+    }
+  }
+
+  function invokeMethodOnSource(d: { targetId: number; method: string; args?: unknown[] }) {
+    const el: any = idToNode.get(d.targetId);
+    if (!el || typeof el[d.method] !== "function") return;
+    _suppressInvoke++;
+    try {
+      el[d.method](...(d.args || []));
+    } catch {
+      // e.g. showModal() on an already-open dialog throws InvalidStateError.
+      // Swallow — the source is already in the requested state, no-op.
+    } finally {
+      _suppressInvoke--;
+    }
+  }
+
   // ------------------------------------------------------------------
   // Boot
   // ------------------------------------------------------------------
@@ -783,6 +869,7 @@ export function createBridge(config: BridgeConfig = {}) {
       setupObserver();
       setupFormListeners();
       setupScrollListeners();
+      setupTopLayerInterception();
     });
   }
 
@@ -860,6 +947,8 @@ export function createBridge(config: BridgeConfig = {}) {
     syncScroll,
     setupScrollListeners,
     setupFormListeners,
+    setupTopLayerInterception,
+    invokeMethodOnSource,
     waitForReady,
     boot,
     start,
diff --git a/packages/core/src/core.ts b/packages/core/src/core.ts
index 1cb79e7..f6764fe 100644
--- a/packages/core/src/core.ts
+++ b/packages/core/src/core.ts
@@ -689,6 +689,12 @@ export class VirtualFrame {
     this.setupMutationObserver();
     _vflog("_initSameOrigin() observer set up, calling mirrorContent");
 
+    // Patch top-layer methods in the iframe's realm so showModal / show /
+    // close / showPopover / hidePopover / togglePopover on a source node
+    // also fire on its mirror in the host shadow root.  Must run inside
+    // the iframe's window so the prototypes patched are the source's own.
+    this._installSameOriginTopLayerInterception();
+
     // Mirror whatever content is available now - mutation observer will handle the rest
     await this.mirrorContent();
 
@@ -696,6 +702,119 @@ export class VirtualFrame {
     _vflog("_initSameOrigin() DONE, isInitialized=true");
   }
 
+  /**
+   * Same-origin equivalent of the bridge's setupTopLayerInterception().
+   *
+   * The cross-origin path patches prototypes from inside the iframe (the
+   * bridge runs there).  For same-origin, the host has direct access to
+   * the iframe's window and can wrap the prototypes itself, avoiding a
+   * postMessage round-trip and any node-identity serialisation — the
+   * wrapper closure captures the source node reference and looks up the
+   * mirror via `this.elementMap` directly.
+   *
+   * Idempotent per iframe window: the first install tags the window via
+   * `__vfTopLayerPatched` so subsequent calls (e.g. after an MPA reload
+   * that reuses the same window) are no-ops.  For a fresh window the flag
+   * isn't present and we patch anew.
+   */
+  _installSameOriginTopLayerInterception() {
+    const win = this.iframe?.contentWindow as any;
+    if (!win || win.__vfTopLayerPatched) return;
+
+    const DIALOG_METHODS = ["showModal", "show", "close"] as const;
+    const POPOVER_METHODS = ["showPopover", "hidePopover", "togglePopover"] as const;
+    const SUPPRESS = Symbol.for("__vfTopLayerSuppress");
+    // WeakSet-style token stored per mirror node to prevent re-entry:
+    // when we call mirror.close() in response to source.close(), the
+    // mirror's own close listener must not echo back to the source.
+    const suppressed = new WeakSet<object>();
+    const elementMap = this.elementMap;
+    const attachCloseMirror = this._attachSameOriginCloseMirror.bind(this);
+
+    const wrap = (proto: any, method: string, isOpener: boolean) => {
+      const original = proto[method];
+      if (typeof original !== "function") return;
+      proto[method] = function (...args: unknown[]) {
+        const result = original.apply(this, args);
+        if (!(this as any)[SUPPRESS]) {
+          const mirror = elementMap.get(this as Node) as any;
+          if (mirror && typeof mirror[method] === "function") {
+            suppressed.add(mirror);
+            try {
+              mirror[method](...args);
+            } catch {
+              // Source and mirror out of sync — ignore.
+            } finally {
+              suppressed.delete(mirror);
+            }
+            if (isOpener) attachCloseMirror(mirror, this as Node, method);
+          }
+        }
+        return result;
+      };
+    };
+
+    const HTMLDialogElement = win.HTMLDialogElement;
+    if (HTMLDialogElement) {
+      for (const m of DIALOG_METHODS) {
+        wrap(HTMLDialogElement.prototype, m, m === "showModal" || m === "show");
+      }
+    }
+    const HTMLElement = win.HTMLElement;
+    if (HTMLElement) {
+      for (const m of POPOVER_METHODS) {
+        wrap(HTMLElement.prototype, m, m === "showPopover" || m === "togglePopover");
+      }
+    }
+
+    // Store so the close-mirror can flip the suppress flag on sources.
+    (this as any)._topLayerSuppressSymbol = SUPPRESS;
+    (this as any)._topLayerSuppressSet = suppressed;
+    win.__vfTopLayerPatched = true;
+  }
+
+  /**
+   * Same-origin reverse direction: when the user dismisses the mirror
+   * (ESC, backdrop click, declarative `popovertarget` hide), fire the
+   * corresponding close on the source so both sides stay in sync.
+   */
+  _attachSameOriginCloseMirror(mirror: any, source: Node, method: string) {
+    const SUPPRESS = (this as any)._topLayerSuppressSymbol;
+    const suppressed = (this as any)._topLayerSuppressSet as WeakSet<object>;
+    const isDialog = method === "showModal" || method === "show";
+
+    if (isDialog) {
+      const onClose = () => {
+        mirror.removeEventListener("close", onClose);
+        if (suppressed.has(mirror)) return;
+        (source as any)[SUPPRESS] = true;
+        try {
+          (source as any).close(mirror.returnValue);
+        } catch {
+          // ignore
+        } finally {
+          (source as any)[SUPPRESS] = false;
+        }
+      };
+      mirror.addEventListener("close", onClose);
+    } else {
+      const onToggle = (e: any) => {
+        if (e.newState !== "closed") return;
+        mirror.removeEventListener("toggle", onToggle);
+        if (suppressed.has(mirror)) return;
+        (source as any)[SUPPRESS] = true;
+        try {
+          (source as any).hidePopover();
+        } catch {
+          // ignore
+        } finally {
+          (source as any)[SUPPRESS] = false;
+        }
+      };
+      mirror.addEventListener("toggle", onToggle);
+    }
+  }
+
   // ---------------------------------------------------------------
   // Cross-origin mode: communicate with bridge.js via postMessage
   // ---------------------------------------------------------------
@@ -813,12 +932,71 @@ export class VirtualFrame {
           }
           case "vf:eventResult":
             break;
+          case "vf:invokeMethod": {
+            // Mirror a top-layer method call from the source onto the
+            // projected clone.  This is how the clone actually enters the
+            // host document's top layer (showModal, showPopover etc.) —
+            // setting the `open` attribute alone would not promote it.
+            const el = this._remoteIdToNode.get(d.targetId) as any;
+            if (!el || typeof el[d.method] !== "function") break;
+            try {
+              el[d.method](...(d.args || []));
+            } catch {
+              // InvalidStateError etc. — source and clone are out of sync;
+              // swallow rather than throw in the message handler.
+              break;
+            }
+            // For "open" methods, wire the reverse direction so that
+            // closing the clone (ESC, backdrop click, close button proxied
+            // through event replay that didn't close the source) keeps
+            // the source in sync.  Without this, the source stays open
+            // and the next showModal() throws InvalidStateError.
+            this._attachTopLayerCloseMirror(el, d.targetId, d.method);
+            break;
+          }
         }
       };
       window.addEventListener("message", this._onMessage);
     });
   }
 
+  /**
+   * After the clone has been promoted to the top layer, attach one-shot
+   * listeners that echo a close back to the source when the user dismisses
+   * the clone from the host side.
+   *
+   *   <dialog>:  `close` event  → source.close(returnValue)
+   *   popover:   `toggle` event → source.hidePopover() when newState = "closed"
+   */
+  _attachTopLayerCloseMirror(el: any, targetId: number, method: string) {
+    const isDialogOpen = method === "showModal" || method === "show";
+    const isPopoverOpen = method === "showPopover" || method === "togglePopover";
+    if (!isDialogOpen && !isPopoverOpen) return;
+
+    if (isDialogOpen) {
+      const onClose = () => {
+        el.removeEventListener("close", onClose);
+        this._sendToBridge("vf:invokeMethod", {
+          targetId,
+          method: "close",
+          args: el.returnValue != null ? [el.returnValue] : [],
+        });
+      };
+      el.addEventListener("close", onClose);
+    } else {
+      const onToggle = (e: any) => {
+        if (e.newState !== "closed") return;
+        el.removeEventListener("toggle", onToggle);
+        this._sendToBridge("vf:invokeMethod", {
+          targetId,
+          method: "hidePopover",
+          args: [],
+        });
+      };
+      el.addEventListener("toggle", onToggle);
+    }
+  }
+
   _sendToBridge(type: string, payload: Record<string, unknown> = {}) {
     if (!this._bridgeChannel) return;
     this.iframe.contentWindow?.postMessage(
@@ -3674,6 +3852,10 @@ export class VirtualFrame {
       try {
         _vflog("_reinitOnNavigation() setting up observer + mirrorContent");
         this.setupMutationObserver();
+        // Re-patch the iframe's top-layer methods.  A fresh document may
+        // have a fresh realm (new HTMLDialogElement.prototype); if the
+        // window object is the same we early-out via __vfTopLayerPatched.
+        this._installSameOriginTopLayerInterception();
         await this.mirrorContent();
         _vflog("_reinitOnNavigation() mirrorContent DONE");
       } catch (e) {
diff --git a/packages/core/test/cross-origin-dialog.test.ts b/packages/core/test/cross-origin-dialog.test.ts
new file mode 100644
index 0000000..f584ddf
--- /dev/null
+++ b/packages/core/test/cross-origin-dialog.test.ts
@@ -0,0 +1,303 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { cleanup, delay } from "./helpers.js";
+import { setupCrossOrigin, bridgeSend, performHandshake } from "./cross-origin-helpers.js";
+
+/**
+ * Cross-origin top-layer projection: <dialog>.showModal() and the
+ * Popover API plumbed through the bridge ↔ host postMessage protocol.
+ *
+ * Inbound  (bridge → host): vf:invokeMethod with {targetId, method, args}
+ *   triggers the matching call on the mirrored element so the clone is
+ *   actually promoted to the host's top layer.
+ * Outbound (host → bridge): when the mirror is dismissed (close /
+ *   toggle→closed), the host posts vf:invokeMethod back so the source
+ *   dialog/popover stays in sync.
+ */
+
+const dialogSnapshot = {
+  body: {
+    type: "element",
+    id: 1,
+    tag: "body",
+    attrs: {},
+    children: [
+      {
+        type: "element",
+        id: 2,
+        tag: "dialog",
+        attrs: { id: "dlg" },
+        children: [
+          {
+            type: "element",
+            id: 3,
+            tag: "p",
+            attrs: {},
+            children: [{ type: "text", id: 4, data: "Hello dialog" }],
+          },
+        ],
+      },
+      {
+        type: "element",
+        id: 5,
+        tag: "div",
+        attrs: { id: "pop", popover: "auto" },
+        children: [{ type: "text", id: 6, data: "Hello popover" }],
+      },
+    ],
+  },
+  css: [],
+};
+
+/** Spy on host → bridge postMessages going through _sendToBridge. */
+function spyOutbound(vf) {
+  const messages: any[] = [];
+  const orig = vf._sendToBridge.bind(vf);
+  vf._sendToBridge = function (type: string, payload: Record<string, unknown> = {}) {
+    messages.push({ type, ...payload });
+    orig(type, payload);
+  };
+  return messages;
+}
+
+describe("VirtualFrame — dialog & popover top-layer projection (cross-origin)", () => {
+  let iframe: HTMLIFrameElement | undefined;
+  let vf: any;
+  let host: HTMLElement | undefined;
+  let channel: string;
+
+  afterEach(() => {
+    if (vf) {
+      try {
+        vf.destroy();
+      } catch {}
+      vf = null;
+    }
+    cleanup();
+  });
+
+  // ── Inbound: bridge → host ───────────────────────────────────
+
+  describe("inbound vf:invokeMethod", () => {
+    it("calls showModal() on the mirrored dialog and promotes it to top layer", async () => {
+      ({ iframe, vf, host, channel } = await setupCrossOrigin());
+      await performHandshake(iframe, vf, channel, dialogSnapshot);
+
+      const mirror = host!.shadowRoot!.querySelector("#dlg") as HTMLDialogElement;
+      expect(mirror).toBeTruthy();
+      expect(mirror.open).toBe(false);
+
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 2,
+        method: "showModal",
+        args: [],
+      });
+      await delay(50);
+
+      expect(mirror.open).toBe(true);
+      expect(mirror.matches(":modal")).toBe(true);
+    });
+
+    it("calls close() on the mirrored dialog", async () => {
+      ({ iframe, vf, host, channel } = await setupCrossOrigin());
+      await performHandshake(iframe, vf, channel, dialogSnapshot);
+
+      const mirror = host!.shadowRoot!.querySelector("#dlg") as HTMLDialogElement;
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 2,
+        method: "showModal",
+        args: [],
+      });
+      await delay(50);
+      expect(mirror.open).toBe(true);
+
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 2,
+        method: "close",
+        args: ["done"],
+      });
+      await delay(50);
+
+      expect(mirror.open).toBe(false);
+      expect(mirror.returnValue).toBe("done");
+    });
+
+    it("calls showPopover() / hidePopover() on the mirrored popover", async () => {
+      ({ iframe, vf, host, channel } = await setupCrossOrigin());
+      await performHandshake(iframe, vf, channel, dialogSnapshot);
+
+      const mirror = host!.shadowRoot!.querySelector("#pop") as HTMLElement;
+      expect(mirror).toBeTruthy();
+      expect(mirror.matches(":popover-open")).toBe(false);
+
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 5,
+        method: "showPopover",
+        args: [],
+      });
+      await delay(50);
+      expect(mirror.matches(":popover-open")).toBe(true);
+
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 5,
+        method: "hidePopover",
+        args: [],
+      });
+      await delay(50);
+      expect(mirror.matches(":popover-open")).toBe(false);
+    });
+
+    it("ignores invokeMethod for an unknown targetId", async () => {
+      ({ iframe, vf, host, channel } = await setupCrossOrigin());
+      await performHandshake(iframe, vf, channel, dialogSnapshot);
+
+      // Should not throw — handler must silently ignore unmapped ids.
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 9999,
+        method: "showModal",
+        args: [],
+      });
+      await delay(50);
+
+      const mirror = host!.shadowRoot!.querySelector("#dlg") as HTMLDialogElement;
+      expect(mirror.open).toBe(false);
+    });
+
+    it("swallows InvalidStateError when method throws (e.g. double showModal)", async () => {
+      ({ iframe, vf, host, channel } = await setupCrossOrigin());
+      await performHandshake(iframe, vf, channel, dialogSnapshot);
+
+      const mirror = host!.shadowRoot!.querySelector("#dlg") as HTMLDialogElement;
+
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 2,
+        method: "showModal",
+        args: [],
+      });
+      await delay(50);
+      expect(mirror.open).toBe(true);
+
+      // Second showModal on an already-open dialog throws InvalidStateError.
+      // The handler must catch and not crash.
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 2,
+        method: "showModal",
+        args: [],
+      });
+      await delay(50);
+
+      expect(mirror.open).toBe(true);
+    });
+
+    it("ignores invokeMethod when method is not a function on the target", async () => {
+      ({ iframe, vf, host, channel } = await setupCrossOrigin());
+      await performHandshake(iframe, vf, channel, dialogSnapshot);
+
+      // p element (id=3) has no showModal — must no-op cleanly.
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 3,
+        method: "showModal",
+        args: [],
+      });
+      await delay(50);
+
+      // Nothing to assert beyond "did not throw"; the handler must guard.
+      expect(true).toBe(true);
+    });
+  });
+
+  // ── Outbound: host → bridge ──────────────────────────────────
+
+  describe("outbound vf:invokeMethod (mirror dismissal echoes back)", () => {
+    it("echoes close() back to the bridge when user dismisses the dialog", async () => {
+      ({ iframe, vf, host, channel } = await setupCrossOrigin());
+      await performHandshake(iframe, vf, channel, dialogSnapshot);
+
+      const messages = spyOutbound(vf);
+      const mirror = host!.shadowRoot!.querySelector("#dlg") as HTMLDialogElement;
+
+      // Open via inbound, which also wires the close-echo listener.
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 2,
+        method: "showModal",
+        args: [],
+      });
+      await delay(50);
+
+      // User dismisses the projected dialog (ESC, backdrop, in-content close)
+      mirror.close("from-host");
+      await delay(50);
+
+      const echo = messages.find(
+        (m) => m.type === "vf:invokeMethod" && m.method === "close" && m.targetId === 2,
+      );
+      expect(echo).toBeTruthy();
+      expect(echo.args).toEqual(["from-host"]);
+    });
+
+    it("echoes hidePopover() back when the mirror popover is dismissed", async () => {
+      ({ iframe, vf, host, channel } = await setupCrossOrigin());
+      await performHandshake(iframe, vf, channel, dialogSnapshot);
+
+      const messages = spyOutbound(vf);
+      const mirror = host!.shadowRoot!.querySelector("#pop") as HTMLElement;
+
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 5,
+        method: "showPopover",
+        args: [],
+      });
+      await delay(50);
+      expect(mirror.matches(":popover-open")).toBe(true);
+
+      mirror.hidePopover();
+      await delay(50);
+
+      const echo = messages.find(
+        (m) => m.type === "vf:invokeMethod" && m.method === "hidePopover" && m.targetId === 5,
+      );
+      expect(echo).toBeTruthy();
+    });
+
+    it("does not echo close for non-opener methods (e.g. inbound close itself)", async () => {
+      ({ iframe, vf, host, channel } = await setupCrossOrigin());
+      await performHandshake(iframe, vf, channel, dialogSnapshot);
+
+      const mirror = host!.shadowRoot!.querySelector("#dlg") as HTMLDialogElement;
+
+      // Open first (this will wire one close listener).
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 2,
+        method: "showModal",
+        args: [],
+      });
+      await delay(50);
+
+      // Now spy *after* the inbound close — we want to verify the close
+      // handler itself does not also wire a fresh close-echo listener.
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 2,
+        method: "close",
+        args: [],
+      });
+      await delay(50);
+      expect(mirror.open).toBe(false);
+
+      // Re-open and confirm exactly one echo fires on the next dismissal,
+      // not two (which would happen if both showModal AND close wired listeners).
+      const messages = spyOutbound(vf);
+      bridgeSend(iframe!, channel, "vf:invokeMethod", {
+        targetId: 2,
+        method: "showModal",
+        args: [],
+      });
+      await delay(50);
+      mirror.close();
+      await delay(50);
+
+      const closeEchoes = messages.filter(
+        (m) => m.type === "vf:invokeMethod" && m.method === "close" && m.targetId === 2,
+      );
+      expect(closeEchoes.length).toBe(1);
+    });
+  });
+});
diff --git a/packages/core/test/dialog.test.ts b/packages/core/test/dialog.test.ts
new file mode 100644
index 0000000..e5e2e86
--- /dev/null
+++ b/packages/core/test/dialog.test.ts
@@ -0,0 +1,268 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { VirtualFrame } from "../src/core.js";
+import { createIframe, createHost, waitForInit, delay, cleanup } from "./helpers.js";
+
+/**
+ * Top-layer projection: <dialog>.showModal() and the Popover API.
+ *
+ * The interception layer patches HTMLDialogElement.prototype and
+ * HTMLElement.prototype inside the iframe's realm. When the source calls
+ * showModal()/showPopover(), the same call is forwarded onto the mirror
+ * in the host's shadow root so the clone is actually promoted to the host
+ * document's top layer (which is what makes :modal match, ::backdrop paint,
+ * and the element escape ancestor stacking/overflow contexts).
+ *
+ * The reverse direction (close/dismiss on the mirror) is mirrored back via
+ * a one-shot listener so source state stays in sync.
+ */
+
+describe("VirtualFrame — dialog & popover top-layer projection (same-origin)", () => {
+  let iframe;
+  let host;
+  let vf;
+
+  afterEach(() => {
+    if (vf) {
+      try {
+        vf.destroy();
+      } catch {}
+      vf = null;
+    }
+    cleanup();
+  });
+
+  // ── Dialog ───────────────────────────────────────────────────
+
+  describe("<dialog>", () => {
+    it("promotes the mirror to top layer when source calls showModal()", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourceDialog = iframe.contentDocument.getElementById("dlg");
+      const mirrorDialog = host.shadowRoot.querySelector("#dlg");
+      expect(mirrorDialog).toBeTruthy();
+      expect(mirrorDialog).not.toBe(sourceDialog);
+
+      sourceDialog.showModal();
+      await delay(20);
+
+      // Both ends should be open and in the modal/top-layer state
+      expect(sourceDialog.open).toBe(true);
+      expect(mirrorDialog.open).toBe(true);
+      expect(mirrorDialog.matches(":modal")).toBe(true);
+    });
+
+    it("closes the mirror when the source calls close()", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourceDialog = iframe.contentDocument.getElementById("dlg");
+      const mirrorDialog = host.shadowRoot.querySelector("#dlg");
+
+      sourceDialog.showModal();
+      await delay(20);
+      expect(mirrorDialog.open).toBe(true);
+
+      sourceDialog.close("done");
+      await delay(20);
+
+      expect(sourceDialog.open).toBe(false);
+      expect(mirrorDialog.open).toBe(false);
+    });
+
+    it("mirrors close from the host side back to the source", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourceDialog = iframe.contentDocument.getElementById("dlg");
+      const mirrorDialog = host.shadowRoot.querySelector("#dlg");
+
+      sourceDialog.showModal();
+      await delay(20);
+      expect(mirrorDialog.open).toBe(true);
+
+      // User dismisses the projected dialog (e.g. ESC, backdrop click, in-content close button)
+      mirrorDialog.close("from-host");
+      await delay(20);
+
+      expect(mirrorDialog.open).toBe(false);
+      expect(sourceDialog.open).toBe(false);
+    });
+
+    it("does not echo or loop when the source closes its own dialog", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourceDialog = iframe.contentDocument.getElementById("dlg");
+      const mirrorDialog = host.shadowRoot.querySelector("#dlg");
+
+      let sourceCloseCount = 0;
+      sourceDialog.addEventListener("close", () => sourceCloseCount++);
+
+      sourceDialog.showModal();
+      await delay(20);
+      sourceDialog.close("ok");
+      await delay(50);
+
+      expect(sourceDialog.open).toBe(false);
+      expect(mirrorDialog.open).toBe(false);
+      // Exactly one close — not amplified by mirror echoing back
+      expect(sourceCloseCount).toBe(1);
+    });
+
+    it("supports re-opening after close()", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourceDialog = iframe.contentDocument.getElementById("dlg");
+      const mirrorDialog = host.shadowRoot.querySelector("#dlg");
+
+      sourceDialog.showModal();
+      await delay(20);
+      sourceDialog.close();
+      await delay(20);
+
+      // showModal() on an already-open dialog throws InvalidStateError,
+      // so this is a real test that the sync didn't get stuck.
+      sourceDialog.showModal();
+      await delay(20);
+
+      expect(sourceDialog.open).toBe(true);
+      expect(mirrorDialog.open).toBe(true);
+      expect(mirrorDialog.matches(":modal")).toBe(true);
+    });
+
+    it("supports non-modal show()", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourceDialog = iframe.contentDocument.getElementById("dlg");
+      const mirrorDialog = host.shadowRoot.querySelector("#dlg");
+
+      sourceDialog.show();
+      await delay(20);
+
+      expect(sourceDialog.open).toBe(true);
+      expect(mirrorDialog.open).toBe(true);
+      // show() does NOT promote to top layer — :modal must not match
+      expect(mirrorDialog.matches(":modal")).toBe(false);
+    });
+  });
+
+  // ── Popover ──────────────────────────────────────────────────
+
+  describe("[popover]", () => {
+    it("opens the mirror popover when source calls showPopover()", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourcePop = iframe.contentDocument.getElementById("pop");
+      const mirrorPop = host.shadowRoot.querySelector("#pop");
+      expect(mirrorPop).toBeTruthy();
+
+      sourcePop.showPopover();
+      await delay(20);
+
+      expect(sourcePop.matches(":popover-open")).toBe(true);
+      expect(mirrorPop.matches(":popover-open")).toBe(true);
+    });
+
+    it("hides the mirror when source calls hidePopover()", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourcePop = iframe.contentDocument.getElementById("pop");
+      const mirrorPop = host.shadowRoot.querySelector("#pop");
+
+      sourcePop.showPopover();
+      await delay(20);
+      expect(mirrorPop.matches(":popover-open")).toBe(true);
+
+      sourcePop.hidePopover();
+      await delay(20);
+
+      expect(sourcePop.matches(":popover-open")).toBe(false);
+      expect(mirrorPop.matches(":popover-open")).toBe(false);
+    });
+
+    it("mirrors host-side dismissal back to the source", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourcePop = iframe.contentDocument.getElementById("pop");
+      const mirrorPop = host.shadowRoot.querySelector("#pop");
+
+      sourcePop.showPopover();
+      await delay(20);
+      expect(mirrorPop.matches(":popover-open")).toBe(true);
+
+      mirrorPop.hidePopover();
+      await delay(20);
+
+      expect(mirrorPop.matches(":popover-open")).toBe(false);
+      expect(sourcePop.matches(":popover-open")).toBe(false);
+    });
+
+    it("togglePopover() on source toggles the mirror", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      const sourcePop = iframe.contentDocument.getElementById("pop");
+      const mirrorPop = host.shadowRoot.querySelector("#pop");
+
+      sourcePop.togglePopover();
+      await delay(20);
+      expect(mirrorPop.matches(":popover-open")).toBe(true);
+
+      sourcePop.togglePopover();
+      await delay(20);
+      expect(mirrorPop.matches(":popover-open")).toBe(false);
+    });
+  });
+
+  // ── Patch hygiene ────────────────────────────────────────────
+
+  describe("patch hygiene", () => {
+    it("marks the iframe window as patched (idempotent)", async () => {
+      iframe = await createIframe("dialog.html");
+      host = createHost();
+      vf = new VirtualFrame(iframe, host, { isolate: "open" });
+      await waitForInit(vf);
+
+      expect(iframe.contentWindow.__vfTopLayerPatched).toBe(true);
+
+      // Calling install again must not double-wrap
+      const dlg = iframe.contentDocument.getElementById("dlg");
+      const showModalBefore = iframe.contentWindow.HTMLDialogElement.prototype.showModal;
+      vf._installSameOriginTopLayerInterception();
+      const showModalAfter = iframe.contentWindow.HTMLDialogElement.prototype.showModal;
+      expect(showModalBefore).toBe(showModalAfter);
+
+      // And dialog still functions
+      dlg.showModal();
+      await delay(20);
+      const mirror = host.shadowRoot.querySelector("#dlg");
+      expect(mirror.open).toBe(true);
+    });
+  });
+});
diff --git a/packages/core/test/fixtures/dialog.html b/packages/core/test/fixtures/dialog.html
new file mode 100644
index 0000000..5fe2d95
--- /dev/null
+++ b/packages/core/test/fixtures/dialog.html
@@ -0,0 +1,40 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      body {
+        margin: 0;
+        font-family: sans-serif;
+      }
+      dialog {
+        padding: 16px;
+      }
+      [popover] {
+        padding: 8px;
+      }
+    </style>
+  </head>
+  <body>
+    <button id="open-dialog">Open dialog</button>
+    <button id="open-popover" popovertarget="pop">Toggle popover</button>
+
+    <dialog id="dlg">
+      <p>Hello dialog</p>
+      <button id="close-dialog">Close</button>
+    </dialog>
+
+    <div id="pop" popover="auto">
+      <p>Hello popover</p>
+    </div>
+
+    <script>
+      document.getElementById("open-dialog").addEventListener("click", () => {
+        document.getElementById("dlg").showModal();
+      });
+      document.getElementById("close-dialog").addEventListener("click", () => {
+        document.getElementById("dlg").close("ok");
+      });
+    </script>
+  </body>
+</html>
