adaptar-vite-plugin 1.0.7 → 1.0.8

package/dist/html-tags.js

@@ -1,4 +1,5 @@
 import { ERROR_BRIDGE_SCRIPT } from "./scripts/error-bridge.js";
+import { NAVIGATION_BRIDGE_SCRIPT } from "./scripts/navigation-bridge.js";
 import { SELECTION_BRIDGE_SCRIPT } from "./scripts/selection-bridge.js";
 /**
  * The inline module that subscribes to the `adaptar:error` custom HMR event
@@ -72,6 +73,12 @@ export function buildHtmlTags() {
             attrs: { "data-adaptar": "error-bridge" },
             children: ERROR_BRIDGE_SCRIPT,
         },
+        {
+            tag: "script",
+            injectTo: "head-prepend",
+            attrs: { "data-adaptar": "navigation-bridge" },
+            children: NAVIGATION_BRIDGE_SCRIPT,
+        },
         {
             tag: "script",
             injectTo: "head-prepend",

package/dist/index.d.ts

@@ -1,13 +1,11 @@
 /**
  * Adaptar Vite Plugin
  *
- * Provides three layers of error and selection bridging between the
- * sandboxed preview iframe and the Adaptar host editor:
+ * Provides four preview bridges between the sandboxed iframe and the host:
  *
- * 1. `error-bridge`     — catches runtime JS errors, resource failures,
- *                          unhandled rejections, and blank-screen scenarios.
- * 2. `selection-bridge` — powers element inspect / edit mode in the preview.
- * 3. `hmr-interceptor`  — intercepts Vite's internal WebSocket to surface
- *                          build/HMR errors as structured `adaptar:error` events.
+ * 1. `error-bridge` - reports blocking runtime and compilation failures.
+ * 2. `navigation-bridge` - reports document and History API navigation.
+ * 3. `selection-bridge` - powers element inspection and edit mode.
+ * 4. `hmr-interceptor` - reports Vite build and HMR failures.
  */
 export declare function adaptar(): any;

package/dist/index.js

@@ -3,14 +3,12 @@ import { buildHtmlTags } from "./html-tags.js";
 /**
  * Adaptar Vite Plugin
  *
- * Provides three layers of error and selection bridging between the
- * sandboxed preview iframe and the Adaptar host editor:
+ * Provides four preview bridges between the sandboxed iframe and the host:
  *
- * 1. `error-bridge`     — catches runtime JS errors, resource failures,
- *                          unhandled rejections, and blank-screen scenarios.
- * 2. `selection-bridge` — powers element inspect / edit mode in the preview.
- * 3. `hmr-interceptor`  — intercepts Vite's internal WebSocket to surface
- *                          build/HMR errors as structured `adaptar:error` events.
+ * 1. `error-bridge` - reports blocking runtime and compilation failures.
+ * 2. `navigation-bridge` - reports document and History API navigation.
+ * 3. `selection-bridge` - powers element inspection and edit mode.
+ * 4. `hmr-interceptor` - reports Vite build and HMR failures.
  */
 export function adaptar() {
     return {
@@ -20,7 +18,7 @@ export function adaptar() {
             return {
                 server: {
                     hmr: {
-                        // Disable Vite's default error overlay — Adaptar renders its own.
+                        // Adaptar renders its own error surface.
                         overlay: false,
                     },
                 },

package/dist/scripts/navigation-bridge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reports the preview's browser location to the Adaptar host.
+ *
+ * The preview runs on a different origin, so the host cannot read
+ * `iframe.contentWindow.location`. Intercepting the History API also covers
+ * client-side routers, whose navigation does not trigger an iframe load.
+ */
+export declare const NAVIGATION_BRIDGE_SCRIPT = "(function() {\n  if (window.__ADAPTAR_NAVIGATION_BRIDGE__) return;\n  window.__ADAPTAR_NAVIGATION_BRIDGE__ = true;\n\n  var INTERNAL_OPERATION_PARAM = '__adaptarOperation';\n  var operationId = new URL(window.location.href).searchParams.get(INTERNAL_OPERATION_PARAM) || undefined;\n  var lastLocation = '';\n\n  function readLocation() {\n    var url = new URL(window.location.href);\n    url.searchParams.delete(INTERNAL_OPERATION_PARAM);\n\n    return {\n      pathname: url.pathname || '/',\n      search: url.search,\n      hash: url.hash\n    };\n  }\n\n  function reportLocation(reason) {\n    try {\n      var location = readLocation();\n      var signature = location.pathname + location.search + location.hash;\n      if (signature === lastLocation) return;\n      lastLocation = signature;\n\n      window.parent.postMessage({\n        source: 'adaptar-preview',\n        type: 'preview-navigation',\n        operationId: operationId,\n        reason: reason,\n        location: location\n      }, '*');\n    } catch (_) {}\n  }\n\n  function scheduleReport(reason) {\n    if (typeof queueMicrotask === 'function') {\n      queueMicrotask(function() {\n        reportLocation(reason);\n      });\n      return;\n    }\n\n    Promise.resolve().then(function() {\n      reportLocation(reason);\n    });\n  }\n\n  function instrumentHistory(method) {\n    try {\n      var original = window.history[method];\n      if (typeof original !== 'function') return;\n\n      window.history[method] = function() {\n        var result = original.apply(this, arguments);\n        scheduleReport(method);\n        return result;\n      };\n    } catch (_) {}\n  }\n\n  instrumentHistory('pushState');\n  instrumentHistory('replaceState');\n\n  window.addEventListener('popstate', function() {\n    scheduleReport('popstate');\n  });\n  window.addEventListener('hashchange', function() {\n    scheduleReport('hashchange');\n  });\n  window.addEventListener('pageshow', function() {\n    scheduleReport('pageshow');\n  });\n\n  reportLocation('initial');\n})();";

package/dist/scripts/navigation-bridge.js

@@ -0,0 +1,84 @@
+/**
+ * Reports the preview's browser location to the Adaptar host.
+ *
+ * The preview runs on a different origin, so the host cannot read
+ * `iframe.contentWindow.location`. Intercepting the History API also covers
+ * client-side routers, whose navigation does not trigger an iframe load.
+ */
+export const NAVIGATION_BRIDGE_SCRIPT = /* js */ `(function() {
+  if (window.__ADAPTAR_NAVIGATION_BRIDGE__) return;
+  window.__ADAPTAR_NAVIGATION_BRIDGE__ = true;
+
+  var INTERNAL_OPERATION_PARAM = '__adaptarOperation';
+  var operationId = new URL(window.location.href).searchParams.get(INTERNAL_OPERATION_PARAM) || undefined;
+  var lastLocation = '';
+
+  function readLocation() {
+    var url = new URL(window.location.href);
+    url.searchParams.delete(INTERNAL_OPERATION_PARAM);
+
+    return {
+      pathname: url.pathname || '/',
+      search: url.search,
+      hash: url.hash
+    };
+  }
+
+  function reportLocation(reason) {
+    try {
+      var location = readLocation();
+      var signature = location.pathname + location.search + location.hash;
+      if (signature === lastLocation) return;
+      lastLocation = signature;
+
+      window.parent.postMessage({
+        source: 'adaptar-preview',
+        type: 'preview-navigation',
+        operationId: operationId,
+        reason: reason,
+        location: location
+      }, '*');
+    } catch (_) {}
+  }
+
+  function scheduleReport(reason) {
+    if (typeof queueMicrotask === 'function') {
+      queueMicrotask(function() {
+        reportLocation(reason);
+      });
+      return;
+    }
+
+    Promise.resolve().then(function() {
+      reportLocation(reason);
+    });
+  }
+
+  function instrumentHistory(method) {
+    try {
+      var original = window.history[method];
+      if (typeof original !== 'function') return;
+
+      window.history[method] = function() {
+        var result = original.apply(this, arguments);
+        scheduleReport(method);
+        return result;
+      };
+    } catch (_) {}
+  }
+
+  instrumentHistory('pushState');
+  instrumentHistory('replaceState');
+
+  window.addEventListener('popstate', function() {
+    scheduleReport('popstate');
+  });
+  window.addEventListener('hashchange', function() {
+    scheduleReport('hashchange');
+  });
+  window.addEventListener('pageshow', function() {
+    scheduleReport('pageshow');
+  });
+
+  reportLocation('initial');
+})();`;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "adaptar-vite-plugin",
-  "version": "1.0.7",
-  "description": "Vite plugin for Adaptar preview error and selection bridging",
+  "version": "1.0.8",
+  "description": "Vite plugin for Adaptar preview error, navigation, and selection bridging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "scripts": {
     "build": "tsc",
-    "dev": "tsc -w"
+    "dev": "tsc -w",
+    "test": "npm run build && node --test test/*.test.mjs"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/html-tags.ts

@@ -1,6 +1,7 @@
-import type { HtmlTagDescriptor } from "vite";
-import { ERROR_BRIDGE_SCRIPT } from "./scripts/error-bridge.js";
-import { SELECTION_BRIDGE_SCRIPT } from "./scripts/selection-bridge.js";
+import type { HtmlTagDescriptor } from "vite";
+import { ERROR_BRIDGE_SCRIPT } from "./scripts/error-bridge.js";
+import { NAVIGATION_BRIDGE_SCRIPT } from "./scripts/navigation-bridge.js";
+import { SELECTION_BRIDGE_SCRIPT } from "./scripts/selection-bridge.js";
 
 /**
  * The inline module that subscribes to the `adaptar:error` custom HMR event
@@ -75,11 +76,17 @@ export function buildHtmlTags(): HtmlTagDescriptor[] {
       attrs: { "data-adaptar": "error-bridge" },
       children: ERROR_BRIDGE_SCRIPT,
     },
-    {
-      tag: "script",
-      injectTo: "head-prepend",
-      attrs: { "data-adaptar": "selection-bridge" },
-      children: SELECTION_BRIDGE_SCRIPT,
+    {
+      tag: "script",
+      injectTo: "head-prepend",
+      attrs: { "data-adaptar": "navigation-bridge" },
+      children: NAVIGATION_BRIDGE_SCRIPT,
+    },
+    {
+      tag: "script",
+      injectTo: "head-prepend",
+      attrs: { "data-adaptar": "selection-bridge" },
+      children: SELECTION_BRIDGE_SCRIPT,
     },
     {
       tag: "script",

package/src/index.ts

@@ -4,14 +4,12 @@ import { buildHtmlTags } from "./html-tags.js";
 /**
  * Adaptar Vite Plugin
  *
- * Provides three layers of error and selection bridging between the
- * sandboxed preview iframe and the Adaptar host editor:
+ * Provides four preview bridges between the sandboxed iframe and the host:
  *
- * 1. `error-bridge`     — catches runtime JS errors, resource failures,
- *                          unhandled rejections, and blank-screen scenarios.
- * 2. `selection-bridge` — powers element inspect / edit mode in the preview.
- * 3. `hmr-interceptor`  — intercepts Vite's internal WebSocket to surface
- *                          build/HMR errors as structured `adaptar:error` events.
+ * 1. `error-bridge` - reports blocking runtime and compilation failures.
+ * 2. `navigation-bridge` - reports document and History API navigation.
+ * 3. `selection-bridge` - powers element inspection and edit mode.
+ * 4. `hmr-interceptor` - reports Vite build and HMR failures.
  */
 export function adaptar(): any {
   return {
@@ -22,7 +20,7 @@ export function adaptar(): any {
       return {
         server: {
           hmr: {
-            // Disable Vite's default error overlay — Adaptar renders its own.
+            // Adaptar renders its own error surface.
             overlay: false,
           },
         },

package/src/scripts/navigation-bridge.ts

@@ -0,0 +1,84 @@
+/**
+ * Reports the preview's browser location to the Adaptar host.
+ *
+ * The preview runs on a different origin, so the host cannot read
+ * `iframe.contentWindow.location`. Intercepting the History API also covers
+ * client-side routers, whose navigation does not trigger an iframe load.
+ */
+export const NAVIGATION_BRIDGE_SCRIPT = /* js */ `(function() {
+  if (window.__ADAPTAR_NAVIGATION_BRIDGE__) return;
+  window.__ADAPTAR_NAVIGATION_BRIDGE__ = true;
+
+  var INTERNAL_OPERATION_PARAM = '__adaptarOperation';
+  var operationId = new URL(window.location.href).searchParams.get(INTERNAL_OPERATION_PARAM) || undefined;
+  var lastLocation = '';
+
+  function readLocation() {
+    var url = new URL(window.location.href);
+    url.searchParams.delete(INTERNAL_OPERATION_PARAM);
+
+    return {
+      pathname: url.pathname || '/',
+      search: url.search,
+      hash: url.hash
+    };
+  }
+
+  function reportLocation(reason) {
+    try {
+      var location = readLocation();
+      var signature = location.pathname + location.search + location.hash;
+      if (signature === lastLocation) return;
+      lastLocation = signature;
+
+      window.parent.postMessage({
+        source: 'adaptar-preview',
+        type: 'preview-navigation',
+        operationId: operationId,
+        reason: reason,
+        location: location
+      }, '*');
+    } catch (_) {}
+  }
+
+  function scheduleReport(reason) {
+    if (typeof queueMicrotask === 'function') {
+      queueMicrotask(function() {
+        reportLocation(reason);
+      });
+      return;
+    }
+
+    Promise.resolve().then(function() {
+      reportLocation(reason);
+    });
+  }
+
+  function instrumentHistory(method) {
+    try {
+      var original = window.history[method];
+      if (typeof original !== 'function') return;
+
+      window.history[method] = function() {
+        var result = original.apply(this, arguments);
+        scheduleReport(method);
+        return result;
+      };
+    } catch (_) {}
+  }
+
+  instrumentHistory('pushState');
+  instrumentHistory('replaceState');
+
+  window.addEventListener('popstate', function() {
+    scheduleReport('popstate');
+  });
+  window.addEventListener('hashchange', function() {
+    scheduleReport('hashchange');
+  });
+  window.addEventListener('pageshow', function() {
+    scheduleReport('pageshow');
+  });
+
+  reportLocation('initial');
+})();`;

package/test/navigation-bridge.test.mjs

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import vm from "node:vm";
+import { NAVIGATION_BRIDGE_SCRIPT } from "../dist/scripts/navigation-bridge.js";
+
+function createPreviewRuntime(initialUrl) {
+  const messages = [];
+  const listeners = new Map();
+  const location = { href: initialUrl };
+  const parent = {
+    postMessage(message) {
+      messages.push(JSON.parse(JSON.stringify(message)));
+    },
+  };
+  const history = {
+    pushState(_state, _unused, nextUrl) {
+      location.href = new URL(String(nextUrl), location.href).toString();
+    },
+    replaceState(_state, _unused, nextUrl) {
+      location.href = new URL(String(nextUrl), location.href).toString();
+    },
+  };
+  const window = {
+    location,
+    parent,
+    history,
+    addEventListener(type, listener) {
+      const registered = listeners.get(type) || [];
+      registered.push(listener);
+      listeners.set(type, registered);
+    },
+  };
+  window.window = window;
+
+  vm.runInNewContext(NAVIGATION_BRIDGE_SCRIPT, {
+    Promise,
+    URL,
+    queueMicrotask(callback) {
+      callback();
+    },
+    window,
+  });
+
+  return {
+    history,
+    messages,
+    navigateByBrowser(nextUrl, eventType) {
+      location.href = new URL(nextUrl, location.href).toString();
+      for (const listener of listeners.get(eventType) || []) {
+        listener();
+      }
+    },
+  };
+}
+
+test("reports initial and History API navigation without internal query state", () => {
+  const runtime = createPreviewRuntime(
+    "https://workspace.preview.adaptar.dev/?__adaptarOperation=operation-1",
+  );
+
+  assert.deepEqual(runtime.messages[0], {
+    source: "adaptar-preview",
+    type: "preview-navigation",
+    operationId: "operation-1",
+    reason: "initial",
+    location: {
+      pathname: "/",
+      search: "",
+      hash: "",
+    },
+  });
+
+  runtime.history.pushState({}, "", "/work?filter=featured#project");
+
+  assert.deepEqual(runtime.messages[1], {
+    source: "adaptar-preview",
+    type: "preview-navigation",
+    operationId: "operation-1",
+    reason: "pushState",
+    location: {
+      pathname: "/work",
+      search: "?filter=featured",
+      hash: "#project",
+    },
+  });
+});
+
+test("reports browser history and suppresses duplicate locations", () => {
+  const runtime = createPreviewRuntime(
+    "https://workspace.preview.adaptar.dev/studio",
+  );
+
+  runtime.history.replaceState({}, "", "/studio");
+  assert.equal(runtime.messages.length, 1);
+
+  runtime.navigateByBrowser("/contact", "popstate");
+  assert.equal(runtime.messages.length, 2);
+  assert.equal(runtime.messages[1].location.pathname, "/contact");
+  assert.equal(runtime.messages[1].reason, "popstate");
+});