cindel 1.0.4 → 1.0.5

package/README.md

@@ -32,6 +32,7 @@
 - No runtime dependencies, so it works in any modern browser
 - Event system with `on`, `once`, and `off` for connect, disconnect, reload, add, remove, etc.
 - IIFE build compatible with userscript managers (Tampermonkey, Greasemonkey) via `@require`
+- Iframe injection via `postMessage` for Private Network Access restricted environments
 
 ---
 
@@ -408,6 +409,10 @@ process.on("SIGINT", () => server.stop().then(() => process.exit(0)));
 | `onFileLoaded`      | `(file) => void`                     |               | Called after each file is loaded or reloaded                      |
 | `loadOrder`         | `Stage[]`                            |               | Extra stages prepended before the built-in sorting                |
 | `sortFiles`         | `(files) => string[]`                |               | Fully replaces the default sort. When set, `loadOrder` is ignored |
+| `iframe`            | `boolean \| Object`                  |               | Forward files to an iframe via `postMessage`                      |
+| `iframe.target`     | `Window \| HTMLIFrameElement`        |               | Target a specific same-origin iframe, skips auto-discovery        |
+| `iframe.origin`     | `string`                             | `'*'`         | Validates incoming handshake responses                            |
+| `iframe.css`        | `'iframe' \| 'parent' \| 'both'`     | `'iframe'`    | Where CSS files are loaded when `iframe` is set                   |
 
 ### Methods
 
@@ -552,6 +557,38 @@ new HMRClient({
 
 ---
 
+### Iframe Injection
+
+When your project runs inside an `<iframe>` on a third-party domain, the browser's Private Network Access policy blocks the iframe from reaching `localhost` directly. The `iframe` option works around this by fetching files in the parent page and forwarding them to the iframe via `postMessage`.
+
+Call `stub()` once inside the iframe via a userscript or existing inline script:
+
+```js
+HMR.stub();
+```
+
+Then configure the client in the parent:
+
+```js
+new HMR.HMRClient({
+  port: 1338,
+  iframe: true,
+});
+```
+
+The client listens for the stub's ready signal and attaches automatically. Reattachment is automatic if the iframe reloads or is replaced. In the rare case of multiple same-origin iframes all running stub, pass `iframe.target` to target a specific one, but reattachment is then your responsibility.
+
+```js
+iframe: {
+  target: document.querySelector('iframe#html5game'),
+  css: 'both', // 'iframe' (default) | 'parent' | 'both'
+}
+```
+
+> `.mjs` files are forwarded as `<script type="module">` blocks, preserving ES module semantics. Bare specifiers and relative imports will not resolve, only self-contained modules are supported.
+
+---
+
 ### Override Detection
 
 Override detection lets you maintain a parallel directory of replacement files that shadow originals without modifying them. When an override changes, the client unloads the original before loading the override.
@@ -592,7 +629,7 @@ new HMRClient({
 | Import path                           | Environment | Description          |
 | ------------------------------------- | ----------- | -------------------- |
 | `cindel` or `cindel/server`           | Node / Bun  | `HMRServer`          |
-| `cindel/client`                       | Browser ESM | `HMRClient`          |
+| `cindel/client`                       | Browser ESM | `HMRClient`, `stub`  |
 | `https://cdn.jsdelivr.net/npm/cindel` | Browser CDN | Exposes `window.HMR` |
 
 ---

package/dist/client/file-loader.d.ts

@@ -1,7 +1,28 @@
 /** Handles loading and hot reloading of JavaScript and CSS files via blob URLs. */
 export class FileLoader {
-    constructor(httpUrl: any);
+    constructor(httpUrl: any, { iframeTarget, iframeOrigin, css }?: {
+        iframeTarget?: any;
+        iframeOrigin?: string;
+        css?: string;
+    });
     httpUrl: any;
+    /**
+     * When set, JS and module files are fetched in the parent context and forwarded
+     * to this window via postMessage instead of being injected as DOM elements.
+     * CSS routing is controlled separately by the `css` option.
+     * @type {Window | null}
+     */
+    iframeTarget: Window | null;
+    /** @type {string} */
+    iframeOrigin: string;
+    /**
+     * Controls where CSS files go when `iframeTarget` is set.
+     * - `'iframe'` -> forward only, skip parent injection (default)
+     * - `'parent'` -> load normally in parent, do not forward
+     * - `'both'`   -> load in parent via `<link>` and forward to iframe
+     * @type {'iframe' | 'parent' | 'both'}
+     */
+    css: "iframe" | "parent" | "both";
     /**
      * Debounce state per file. Stores { timeout, resolvers[] } so that
      * when a rapid second change clears the first timeout, the first
@@ -20,12 +41,15 @@ export class FileLoader {
      */
     versions: Map<string, number>;
     loadFile(path: any): Promise<any>;
-    loadCSS(path: any): Promise<any>;
+    loadCSS(path: any): Promise<boolean>;
+    _loadCSSInParent(path: any, url: any): Promise<any>;
     loadModule(path: any): Promise<boolean>;
     loadScript(path: any): Promise<any>;
     reloadFile(path: any): Promise<any>;
     _flushReload(path: any): Promise<void>;
     removeFile(path: any): Promise<void>;
     makeUrl(path: any): string;
+    _post(message: any): void;
+    _inject(kind: any, code: any, file: any): void;
 }
 //# sourceMappingURL=file-loader.d.ts.map

package/dist/client/file-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-loader.d.ts","sourceRoot":"","sources":["../../src/client/file-loader.js"],"names":[],"mappings":"AAAA,mFAAmF;AACnF;IACE,0BAgBC;IAfC,aAAsB;IACtB;;;;;OAKG;IACH,WAFU,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,UAAU,CAAA;KAAE,CAAC,CAEvC;IAC1B;;;;;OAKG;IACH,UAFU,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAEJ;IAG3B,kCAOC;IAKD,iCAoBC;IAED,wCAIC;IAED,oCAeC;IAKD,oCAeC;IAED,uCAUC;IAED,qCAiBC;IAGD,2BAIC;CACF"}
+{"version":3,"file":"file-loader.d.ts","sourceRoot":"","sources":["../../src/client/file-loader.js"],"names":[],"mappings":"AAAA,mFAAmF;AACnF;IACE;;;;OAiCC;IAhCC,aAAsB;IACtB;;;;;OAKG;IACH,cAFU,MAAM,GAAG,IAAI,CAES;IAChC,qBAAqB;IACrB,cADW,MAAM,CACe;IAChC;;;;;;OAMG;IACH,KAFU,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAExB;IACd;;;;;OAKG;IACH,WAFU,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,UAAU,CAAA;KAAE,CAAC,CAEvC;IAC1B;;;;;OAKG;IACH,UAFU,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAEJ;IAG3B,kCAOC;IAKD,qCAwBC;IAED,oDAmBC;IAED,wCAcC;IAED,oCAwBC;IAKD,oCAeC;IAED,uCAUC;IAED,qCAsBC;IAGD,2BAIC;IAGD,0BAEC;IAGD,+CAEC;CACF"}

package/dist/client/hmr-client.d.ts

@@ -48,6 +48,10 @@ export class HMRClient {
      * @param {function(string): void} [options.onFileLoaded] - Called after each file loads or reloads. Receives `(filePath)`.
      * @param {function(string[]): string[]} [options.sortFiles] - Custom sort for the initial file load order. When provided, replaces `defaultSortFiles` entirely and `loadOrder` is ignored.
      * @param {Array<Function>} [options.loadOrder] - Stages prepended before the built-in sort (CSS-first, cold-first, alphabetical). One argument: return true to load that file first. Two arguments: works like a normal sort callback.
+     * @param {boolean | Object} [options.iframe] - Forward files to an iframe via `postMessage` (for Private Network Access restricted environments). Pass `true` for defaults.
+     * @param {Window | HTMLIFrameElement} [options.iframe.target] - Target a specific same-origin iframe directly, skipping auto-discovery. Reattachment is not automatic.
+     * @param {string} [options.iframe.origin] - The iframe's origin used to validate incoming handshake responses. Defaults to `'*'`.
+     * @param {'iframe'|'parent'|'both'} [options.iframe.css='iframe'] - Where CSS files are loaded when `iframe` is set.
      */
     constructor(options: {
         wsUrl?: string;
@@ -68,6 +72,7 @@ export class HMRClient {
         onFileLoaded?: (arg0: string) => void;
         sortFiles?: (arg0: string[]) => string[];
         loadOrder?: Array<Function>;
+        iframe?: boolean | any;
     });
     wsUrl: any;
     httpUrl: any;
@@ -93,6 +98,10 @@ export class HMRClient {
     _reconnectTimer: NodeJS.Timeout;
     _messageQueue: any[];
     _processingMessages: boolean;
+    _iframeTarget: any;
+    _iframeOrigin: any;
+    _stubManaged: boolean;
+    _onReattach: (e: any) => Promise<void>;
     fileLoader: FileLoader;
     /** @type {Map<string, string>} - Maps override file -> original file */
     overrideMap: Map<string, string>;
@@ -177,6 +186,8 @@ export class HMRClient {
     emit(event: any, ...args: any[]): void;
     _enqueueMessage(data: any): void;
     _drainMessageQueue(): Promise<void>;
+    _waitForStub(): Promise<any>;
+    _listenForReattach(): void;
     /**
      * Connect to the HMR server
      * @returns {Promise<void>}

package/dist/client/hmr-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hmr-client.d.ts","sourceRoot":"","sources":["../../src/client/hmr-client.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IACE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,qBAnBG;QAAyB,KAAK,GAAtB,MAAM;QACW,OAAO,GAAxB,MAAM;QACY,UAAU,GAA5B,OAAO;QACU,IAAI,GAArB,MAAM;QACW,IAAI,GAArB,MAAM;QACY,MAAM,GAAxB,OAAO;QACW,aAAa,GAA/B,OAAO;QACU,cAAc,GAA/B,MAAM;QACW,iBAAiB,GAAlC,MAAM;QACY,eAAe,GAAjC,OAAO;QACY,IAAI,GAAvB,MAAM,EAAE;QACsC,UAAU,GAAxD,CAAS,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,OAAO;QAChB,IAAI,GAAvB,MAAM,EAAE;QAC4B,UAAU,GAA9C,CAAS,IAAM,EAAN,MAAM,KAAG,OAAO;QACyB,iBAAiB,GAAnE,CAAS,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,MAAM,GAAC,IAAI;QACN,YAAY,GAA7C,CAAS,IAAM,EAAN,MAAM,KAAG,IAAI;QACiB,SAAS,GAAhD,CAAS,IAAQ,EAAR,MAAM,EAAE,KAAG,MAAM,EAAE;QACF,SAAS,GAAnC,KAAK,UAAU;KACzB,EAgEA;IAzDC,WAAkB;IAClB,aAAsB;IACtB,oBAAsB;IAEtB,+BAAyD;IACzD,uBAA+C;IAC/C,uBAAiD;IACjD,0BAAwD;IACxD,yBAAqD;IAGrD,wBAAsC;IACtC,oBAxBkB,MAAM,KAAG,OAAO,CAwBQ;IAG1C,oBAAiF;IACjF,gBAAuE;IAGvE,gBAAkB;IAElB,0BAhCkB,MAAM,QAAE,MAAM,EAAE,KAAG,MAAM,GAAC,IAAI,CAgCO;IACvD,qBAhCkB,MAAM,KAAG,IAAI,CAgCc;IAC7C,sBAAqC;IACrC,eAAmE;IAEnE,kBAAkB;IAClB,0BAA0B;IAC1B,qBAAwB;IACxB,6BAA8B;IAC9B,gCAA2B;IAI3B,qBAAuB;IACvB,6BAAgC;IAEhC,uBAA8C;IAE9C,wEAAwE;IACxE,aADW,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CACF;IAC5B,uFAAuF;IACvF,qBADW,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CACC;IAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAYC;IAGH,oCAkBC;IAED,8CAcC;IAED,mCAIC;IAED,sEAoDC;IAED,kCA0BC;IAED,4CAgDC;IAED,8EAkEC;IAED,2CA4CC;IAED,wCA6CC;IAED;;;;;OAKG;IACH,UAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CAQrB;IAED;;;;;OAKG;IACH,YAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CASrB;IAED;;;;;OAKG;IACH,WAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CAoBrB;IAED,uCAQC;IAMD,iCAGC;IAED,oCAWC;IAED;;;OAGG;IACH,WAFa,OAAO,CAAC,IAAI,CAAC,CAuFzB;IAED;;OAEG;IACH,mBAUC;CACF;2BAvoB0B,kBAAkB"}
+{"version":3,"file":"hmr-client.d.ts","sourceRoot":"","sources":["../../src/client/hmr-client.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IACE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,qBAvBG;QAAyB,KAAK,GAAtB,MAAM;QACW,OAAO,GAAxB,MAAM;QACY,UAAU,GAA5B,OAAO;QACU,IAAI,GAArB,MAAM;QACW,IAAI,GAArB,MAAM;QACY,MAAM,GAAxB,OAAO;QACW,aAAa,GAA/B,OAAO;QACU,cAAc,GAA/B,MAAM;QACW,iBAAiB,GAAlC,MAAM;QACY,eAAe,GAAjC,OAAO;QACY,IAAI,GAAvB,MAAM,EAAE;QACsC,UAAU,GAAxD,CAAS,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,OAAO;QAChB,IAAI,GAAvB,MAAM,EAAE;QAC4B,UAAU,GAA9C,CAAS,IAAM,EAAN,MAAM,KAAG,OAAO;QACyB,iBAAiB,GAAnE,CAAS,IAAM,EAAN,MAAM,EAAE,IAAQ,EAAR,MAAM,EAAE,KAAG,MAAM,GAAC,IAAI;QACN,YAAY,GAA7C,CAAS,IAAM,EAAN,MAAM,KAAG,IAAI;QACiB,SAAS,GAAhD,CAAS,IAAQ,EAAR,MAAM,EAAE,KAAG,MAAM,EAAE;QACF,SAAS,GAAnC,KAAK,UAAU;QACY,MAAM,GAAjC,OAAO,MAAS;KACxB,EAwFF;IA9EC,WAAkB;IAClB,aAAsB;IACtB,oBAAsB;IAEtB,+BAAyD;IACzD,uBAA+C;IAC/C,uBAAiD;IACjD,0BAAwD;IACxD,yBAAqD;IAGrD,wBAAsC;IACtC,oBA5BkB,MAAM,KAAG,OAAO,CA4BQ;IAG1C,oBAAiF;IACjF,gBAAuE;IAGvE,gBAAkB;IAElB,0BApCkB,MAAM,QAAE,MAAM,EAAE,KAAG,MAAM,GAAC,IAAI,CAoCO;IACvD,qBApCkB,MAAM,KAAG,IAAI,CAoCc;IAC7C,sBAAqC;IACrC,eAAmE;IAEnE,kBAAkB;IAClB,0BAA0B;IAC1B,qBAAwB;IACxB,6BAA8B;IAC9B,gCAA2B;IAI3B,qBAAuB;IACvB,6BAAgC;IAShC,mBAAiC;IACjC,mBAAiC;IAIjC,sBAAiD;IAGjD,uCAAuB;IAEvB,uBAIE;IAEF,wEAAwE;IACxE,aADW,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CACF;IAC5B,uFAAuF;IACvF,qBADW,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CACC;IAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAYC;IAGH,oCAkBC;IAED,8CAcC;IAED,mCAIC;IAED,sEAoDC;IAED,kCA0BC;IAED,4CAgDC;IAED,8EAkEC;IAED,2CA4CC;IAED,wCA6CC;IAED;;;;;OAKG;IACH,UAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CAQrB;IAED;;;;;OAKG;IACH,YAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CASrB;IAED;;;;;OAKG;IACH,WAJW,MAAM,GAAC,QAAQ,GAAC,KAAK,GAAC,QAAQ,GAAC,MAAM,GAAC,SAAS,GAAC,YAAY,GAAC,OAAO,sBAElE,SAAS,CAoBrB;IAED,uCAQC;IAMD,iCAGC;IAED,oCAWC;IAID,6BAsBC;IAKD,2BAoBC;IAED;;;OAGG;IACH,WAFa,OAAO,CAAC,IAAI,CAAC,CAwGzB;IAED;;OAEG;IACH,mBAgBC;CACF;2BA1uB0B,kBAAkB"}

package/dist/client/stub.d.ts

@@ -0,0 +1,2 @@
+export function stub(): void;
+//# sourceMappingURL=stub.d.ts.map

package/dist/client/stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.d.ts","sourceRoot":"","sources":["../../src/client/stub.js"],"names":[],"mappings":"AAAA,6BAmCC"}

package/dist/client.d.ts

@@ -1,3 +1,3 @@
-export { FileLoader } from "./client/file-loader.js";
+export { stub } from "./client/stub.js";
 export { HMRClient as default, HMRClient } from "./client/hmr-client.js";
 //# sourceMappingURL=client.d.ts.map

package/dist/client.iife.js

@@ -1551,15 +1551,18 @@ var HMR = (() => {
   // src/client.js
   var client_exports = {};
   __export(client_exports, {
-    FileLoader: () => FileLoader,
     HMRClient: () => HMRClient,
-    default: () => HMRClient
+    default: () => HMRClient,
+    stub: () => stub
   });
 
   // src/client/file-loader.js
   var FileLoader = class {
-    constructor(httpUrl) {
+    constructor(httpUrl, { iframeTarget = null, iframeOrigin = "*", css = "iframe" } = {}) {
       this.httpUrl = httpUrl;
+      this.iframeTarget = iframeTarget;
+      this.iframeOrigin = iframeOrigin;
+      this.css = css;
       this.loadQueue = /* @__PURE__ */ new Map();
       this.versions = /* @__PURE__ */ new Map();
     }
@@ -1574,8 +1577,28 @@ var HMR = (() => {
     // the old one. This fixes the brief flash of unstyled content that
     // happens when you remove the old sheet before the new one is parsed.
     async loadCSS(path) {
-      const existing = document.querySelector(`link[data-file="${path}"]`);
       const url = this.makeUrl(path);
+      const toIframe = this.iframeTarget && this.css !== "parent";
+      const toParent = !this.iframeTarget || this.css !== "iframe";
+      const ops = [];
+      if (toIframe) {
+        ops.push(
+          fetch(url).then((r) => {
+            if (!r.ok) throw new Error(`Failed to fetch CSS: ${path} (${r.status})`);
+            return r.text();
+          }).then((code) => {
+            this._inject("css", code, path);
+          })
+        );
+      }
+      if (toParent) {
+        ops.push(this._loadCSSInParent(path, url));
+      }
+      await Promise.all(ops);
+      return true;
+    }
+    _loadCSSInParent(path, url) {
+      const existing = document.querySelector(`link[data-file="${path}"]`);
       const link = document.createElement("link");
       link.rel = "stylesheet";
       link.href = url;
@@ -1594,6 +1617,14 @@ var HMR = (() => {
     }
     async loadModule(path) {
       const url = this.makeUrl(path);
+      if (this.iframeTarget) {
+        const code = await fetch(url).then((r) => {
+          if (!r.ok) throw new Error(`Failed to fetch module: ${path} (${r.status})`);
+          return r.text();
+        });
+        this._inject("module", code, path);
+        return true;
+      }
       await import(url);
       return true;
     }
@@ -1601,6 +1632,14 @@ var HMR = (() => {
       const url = this.makeUrl(path);
       const existing = document.querySelector(`script[data-file="${path}"]`);
       if (existing) existing.remove();
+      if (this.iframeTarget) {
+        const code = await fetch(url).then((r) => {
+          if (!r.ok) throw new Error(`Failed to fetch script: ${path} (${r.status})`);
+          return r.text();
+        });
+        this._inject("script", code, path);
+        return true;
+      }
       const script = document.createElement("script");
       script.src = url;
       script.setAttribute("data-file", path);
@@ -1646,10 +1685,15 @@ var HMR = (() => {
         for (const { reject } of entry.resolvers) reject(new Error(`File removed: ${path}`));
         this.loadQueue.delete(path);
       }
-      const el = document.querySelector(`[data-file="${path}"]`);
-      if (el) {
-        el.remove();
-        await new Promise((r) => setTimeout(r, 0));
+      if (this.iframeTarget) {
+        this._post({ type: "hmr:remove", file: path });
+        await Promise.resolve();
+      } else {
+        const el = document.querySelector(`[data-file="${path}"]`);
+        if (el) {
+          el.remove();
+          await Promise.resolve();
+        }
       }
       this.versions.delete(path);
     }
@@ -1659,6 +1703,14 @@ var HMR = (() => {
       this.versions.set(path, v);
       return `${this.httpUrl}${path}?v=${v}`;
     }
+    // Send a raw postMessage to the iframe target
+    _post(message) {
+      this.iframeTarget.postMessage(message, this.iframeOrigin);
+    }
+    // Forward a file payload to the iframe target
+    _inject(kind, code, file) {
+      this._post({ type: "hmr:inject", kind, code, file });
+    }
   };
 
   // src/shared/constants.js
@@ -1764,6 +1816,10 @@ var HMR = (() => {
      * @param {function(string): void} [options.onFileLoaded] - Called after each file loads or reloads. Receives `(filePath)`.
      * @param {function(string[]): string[]} [options.sortFiles] - Custom sort for the initial file load order. When provided, replaces `defaultSortFiles` entirely and `loadOrder` is ignored.
      * @param {Array<Function>} [options.loadOrder] - Stages prepended before the built-in sort (CSS-first, cold-first, alphabetical). One argument: return true to load that file first. Two arguments: works like a normal sort callback.
+     * @param {boolean | Object} [options.iframe] - Forward files to an iframe via `postMessage` (for Private Network Access restricted environments). Pass `true` for defaults.
+     * @param {Window | HTMLIFrameElement} [options.iframe.target] - Target a specific same-origin iframe directly, skipping auto-discovery. Reattachment is not automatic.
+     * @param {string} [options.iframe.origin] - The iframe's origin used to validate incoming handshake responses. Defaults to `'*'`.
+     * @param {'iframe'|'parent'|'both'} [options.iframe.css='iframe'] - Where CSS files are loaded when `iframe` is set.
      */
     constructor(options) {
       const opts = typeof options === "object" && !Array.isArray(options) ? options : {};
@@ -1793,7 +1849,18 @@ var HMR = (() => {
       this._reconnectTimer = null;
       this._messageQueue = [];
       this._processingMessages = false;
-      this.fileLoader = new FileLoader(this.httpUrl);
+      const iframeOpts = opts.iframe === true ? {} : opts.iframe;
+      const iframeTarget = iframeOpts?.target ? iframeOpts.target?.contentWindow ?? null : null;
+      const iframeOrigin = iframeOpts?.origin ?? "*";
+      this._iframeTarget = iframeTarget;
+      this._iframeOrigin = iframeOrigin;
+      this._stubManaged = !!iframeOpts && !iframeTarget;
+      this._onReattach = null;
+      this.fileLoader = new FileLoader(this.httpUrl, {
+        iframeTarget,
+        iframeOrigin,
+        css: iframeOpts?.css ?? "iframe"
+      });
       this.overrideMap = /* @__PURE__ */ new Map();
       this._reverseOverrideMap = /* @__PURE__ */ new Map();
       this.logStyles = {
@@ -1940,13 +2007,13 @@ var HMR = (() => {
         }
       }
       const withOverrides = this.buildOverrideMap(toLoad);
-      const sorted2 = this.sortFiles(withOverrides);
-      this.logInitFileGroup(sorted2, this.overrideMap, this.isColdFile.bind(this));
-      for (const file of sorted2) {
+      const sorted = this.sortFiles(withOverrides);
+      this.logInitFileGroup(sorted, this.overrideMap, this.isColdFile.bind(this));
+      for (const file of sorted) {
         await this.fileLoader.loadFile(file);
         if (this.onFileLoaded) this.onFileLoaded(file);
       }
-      this.log("success", `HMR client ready (${sorted2.length} files loaded)`);
+      this.log("success", `HMR client ready (${sorted.length} files loaded)`);
     }
     async handleFileChange(file, action, serverCold = false) {
       if (this.shouldSkipFile(file, this.allFiles)) {
@@ -2050,7 +2117,7 @@ var HMR = (() => {
           await this.processInitFiles(data.files);
         } else {
           const modeLabel = this.watchFiles ? "HMR ready" : "Static snapshot ready";
-          this.log("success", `${modeLabel} (${sorted.length} files loaded)`);
+          this.log("success", `${modeLabel} (0 files loaded)`);
         }
         return;
       }
@@ -2145,6 +2212,48 @@ var HMR = (() => {
       }
       this._processingMessages = false;
     }
+    // Wait for stub's hmr:ready signal. Stub fires it proactively on run.
+    // Times out after 5s if stub was never injected.
+    _waitForStub() {
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          window.removeEventListener("message", onReady);
+          reject(new Error("Timed out waiting for hmr:ready. Was HMR.stub() called in the iframe?"));
+        }, 5e3);
+        const onReady = (e) => {
+          if (e.data?.type !== "hmr:ready") return;
+          const originOk = this._iframeOrigin === "*" || e.origin === this._iframeOrigin;
+          if (!originOk) return;
+          clearTimeout(timer);
+          window.removeEventListener("message", onReady);
+          if (this._stubManaged) {
+            this._iframeTarget = e.source;
+            this.fileLoader.iframeTarget = e.source;
+          }
+          resolve();
+        };
+        window.addEventListener("message", onReady);
+      });
+    }
+    // Persistent listener for hmr:ready that handles iframe reattachment. If the
+    // iframe reloads or is replaced, the stub fires hmr:ready again so we can
+    // update the target and re-inject all currently loaded files.
+    _listenForReattach() {
+      if (this._onReattach) return;
+      this._onReattach = async (e) => {
+        if (e.data?.type !== "hmr:ready") return;
+        const originOk = this._iframeOrigin === "*" || e.origin === this._iframeOrigin;
+        if (!originOk) return;
+        if (e.source === this._iframeTarget) return;
+        this._iframeTarget = e.source;
+        this.fileLoader.iframeTarget = e.source;
+        this.log("success", "HMR reattached to new iframe");
+        for (const path of this.fileLoader.versions.keys()) {
+          await this.fileLoader.loadFile(path);
+        }
+      };
+      window.addEventListener("message", this._onReattach);
+    }
     /**
      * Connect to the HMR server
      * @returns {Promise<void>}
@@ -2167,14 +2276,27 @@ var HMR = (() => {
         let settled = false;
         try {
           this.socket = new WebSocket(this.wsUrl);
-          this.socket.onopen = () => {
+          this.socket.onopen = async () => {
             settled = true;
             this.isConnected = true;
             this.reconnectAttempts = 0;
-            this._messageQueue = [];
-            this._processingMessages = false;
             this.log("success", "HMR connected");
             this.emit("connect");
+            this._messageQueue = [];
+            this._processingMessages = true;
+            if (this._iframeTarget || this._stubManaged) {
+              try {
+                await this._waitForStub();
+                if (this._stubManaged) this._listenForReattach();
+              } catch (e) {
+                this.log("error", e.message);
+                this._processingMessages = false;
+                reject(e);
+                return;
+              }
+            }
+            this._processingMessages = false;
+            if (this._messageQueue.length > 0) this._drainMessageQueue();
             resolve();
           };
           this.socket.onclose = () => {
@@ -2230,12 +2352,54 @@ var HMR = (() => {
       this.isConnected = false;
       clearTimeout(this._reconnectTimer);
       this._reconnectTimer = null;
+      if (this._onReattach) {
+        window.removeEventListener("message", this._onReattach);
+        this._onReattach = null;
+      }
       if (this.socket) {
         this.socket.close();
         this.socket = null;
       }
     }
   };
+
+  // src/client/stub.js
+  function stub() {
+    const byFile = (tag, file) => document.querySelector(`${tag}[data-file="${CSS.escape(file)}"]`);
+    const removeIfExists = (el) => {
+      if (el) el.remove();
+    };
+    const injectScript = (kind, code, file) => {
+      removeIfExists(byFile("script", file));
+      const script = document.createElement("script");
+      if (kind === "module") script.type = "module";
+      script.textContent = code;
+      script.dataset.file = file;
+      document.documentElement.appendChild(script);
+      script.remove();
+    };
+    const injectStyle = (code, file) => {
+      const existing = byFile("style", file);
+      const style = document.createElement("style");
+      style.textContent = code;
+      style.dataset.file = file;
+      document.head.appendChild(style);
+      removeIfExists(existing);
+    };
+    window.addEventListener("message", (e) => {
+      const data = e.data;
+      if (!data?.type) return;
+      if (data.type === "hmr:remove") {
+        removeIfExists(document.querySelector(`[data-file="${CSS.escape(data.file)}"]`));
+        return;
+      }
+      if (data.type !== "hmr:inject") return;
+      const { kind, code, file } = data;
+      if (kind === "script" || kind === "module") injectScript(kind, code, file);
+      else if (kind === "css") injectStyle(code, file);
+    });
+    window.parent.postMessage({ type: "hmr:ready" }, "*");
+  }
   return __toCommonJS(client_exports);
 })();
 //# sourceMappingURL=client.iife.js.map