adaptar-vite-plugin 1.0.7 → 1.0.10

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/error-bridge.d.ts

@@ -1 +1 @@
-export declare const ERROR_BRIDGE_SCRIPT = "(function(){\n  if (window.__ADAPTAR_ERROR_BRIDGE__) return;\n  window.__ADAPTAR_ERROR_BRIDGE__ = true;\n\n  var operationId = new URL(window.location.href).searchParams.get('__adaptarOperation') || undefined;\n  var activeBlockingSources = Object.create(null);\n  var blankCheckStartedAt = 0;\n  var blankCheckTimer;\n  var blankFailureReported = false;\n  var BLANK_CONFIRMATION_MS = 8000;\n  var ROOT_CHECK_INTERVAL_MS = 500;\n\n  function readRootHealth() {\n    var root = document.getElementById('root');\n    var hasRootContent = Boolean(\n      root && (root.children.length || (root.textContent || '').trim())\n    );\n\n    return {\n      state: !root ? 'missing' : (hasRootContent ? 'healthy' : 'empty'),\n      hasRootContent: hasRootContent,\n      readyState: document.readyState\n    };\n  }\n\n  function sendRendered(heartbeat) {\n    try {\n      var rootHealth = readRootHealth();\n      window.parent.postMessage({\n        source: 'adaptar-preview',\n        type: heartbeat ? 'render-heartbeat' : 'preview-rendered',\n        operationId: operationId,\n        renderedAt: Date.now(),\n        hasRootContent: rootHealth.hasRootContent,\n        rootHealth: rootHealth\n      }, '*');\n    } catch (_) {}\n  }\n\n  function classifyResource(target, url) {\n    var tag = String((target && target.tagName) || '').toLowerCase();\n    var rel = String((target && target.rel) || '').toLowerCase();\n    var as = String((target && target.as) || '').toLowerCase();\n    var type = String((target && target.type) || '').toLowerCase();\n    var value = String(url || '').split(/[?#]/)[0].toLowerCase();\n\n    if (\n      as === 'font' ||\n      type.indexOf('font/') === 0 ||\n      /\\.(woff2?|ttf|otf|eot)$/.test(value)\n    ) return 'font';\n    if (\n      tag === 'img' ||\n      as === 'image' ||\n      /\\.(avif|bmp|gif|ico|jpe?g|png|svg|webp)$/.test(value)\n    ) return 'image';\n    if (\n      tag === 'audio' || tag === 'video' || tag === 'source' || tag === 'track' ||\n      as === 'audio' || as === 'video' ||\n      /\\.(aac|flac|m4a|m4v|mov|mp3|mp4|ogg|ogv|wav|webm|vtt)$/.test(value)\n    ) return 'media';\n    if (\n      tag === 'script' ||\n      as === 'script' ||\n      rel === 'modulepreload' ||\n      type === 'module' ||\n      /\\.(c|m)?(j|t)sx?$/.test(value)\n    ) return 'module';\n    if (\n      (tag === 'link' && rel === 'stylesheet') ||\n      as === 'style' ||\n      type === 'text/css' ||\n      /\\.(css|less|sass|scss|styl)$/.test(value)\n    ) return 'stylesheet';\n    return 'unknown';\n  }\n\n  function resourceFailureMessage(resourceKind, url) {\n    var labels = {\n      font: 'Failed to load font: ',\n      image: 'Failed to load image: ',\n      media: 'Failed to load media: ',\n      module: 'Failed to load module: ',\n      stylesheet: 'Failed to load stylesheet: ',\n      unknown: 'Failed to load resource: '\n    };\n    return (labels[resourceKind] || labels.unknown) + url;\n  }\n\n  function send(message, stack, filename, lineno, colno, source, plugin, metadata) {\n    try {\n      var details = metadata || {};\n      var rootHealth = readRootHealth();\n      var renderBlocking = details.renderBlocking === true || (\n        details.blockWhenRootEmpty === true && !rootHealth.hasRootContent\n      );\n      var errorSource = source || 'unknown';\n\n      if (renderBlocking) {\n        activeBlockingSources[errorSource] = true;\n      }\n\n      window.parent.postMessage({\n        source: 'adaptar-preview',\n        type: 'error',\n        operationId: operationId,\n        error: {\n          message: message || 'Unknown error',\n          stack: stack || '',\n          filename: filename,\n          lineno: lineno,\n          colno: colno,\n          source: source,\n          plugin: plugin,\n          classification: renderBlocking ? 'render-blocking' : 'diagnostic',\n          category: details.category || 'runtime',\n          severity: renderBlocking ? 'error' : 'advisory',\n          resourceKind: details.resourceKind || 'unknown',\n          renderBlocking: renderBlocking,\n          rootHealth: rootHealth\n        }\n      }, '*');\n    } catch (_) {}\n  }\n\n  function recoverBlockingErrorsIfRendered(reason) {\n    try {\n      var rootHealth = readRootHealth();\n      var resolvedSources = Object.keys(activeBlockingSources);\n      if (!rootHealth.hasRootContent || resolvedSources.length === 0) return;\n\n      activeBlockingSources = Object.create(null);\n      window.parent.postMessage({\n        source: 'adaptar-preview',\n        type: 'preview-recovered',\n        operationId: operationId,\n        recoveredAt: Date.now(),\n        reason: reason || 'root-healthy',\n        resolvedSources: resolvedSources,\n        hasRootContent: true,\n        rootHealth: rootHealth\n      }, '*');\n    } catch (_) {}\n  }\n\n  // Resource failures remain observable, but only a module required before\n  // the application mounts can be classified as render-blocking. Images,\n  // fonts, media, and stylesheets are quality diagnostics.\n  window.addEventListener('error', function(e) {\n    var target = e.target || e.srcElement;\n    if (target && target !== window && target.tagName) {\n      var url = target.src || target.href || target.currentSrc;\n      var resourceKind = classifyResource(target, url);\n      if (url || resourceKind !== 'unknown') {\n        send(\n          resourceFailureMessage(resourceKind, url || '(unknown resource URL)'),\n          '', url, undefined, undefined, 'resource-load', undefined,\n          {\n            category: 'resource',\n            resourceKind: resourceKind,\n            blockWhenRootEmpty: resourceKind === 'module'\n          }\n        );\n        return;\n      }\n    }\n\n    send(\n      e.message || (e.error && e.error.message) || 'Runtime error occurred',\n      e.error ? e.error.stack : '',\n      e.filename, e.lineno, e.colno, 'runtime', undefined,\n      { category: 'runtime', resourceKind: 'module', blockWhenRootEmpty: true }\n    );\n  }, true);\n\n  // An async failure is blocking only when the application has no rendered\n  // root. Interaction failures in an otherwise-rendered page remain visible\n  // diagnostics and never invalidate the candidate by themselves.\n  window.addEventListener('unhandledrejection', function(e) {\n    var r = e.reason;\n    send(\n      r && r.message ? r.message : String(r || 'Unhandled Promise Rejection'),\n      r && r.stack,\n      r && r.fileName,\n      r && r.lineNumber,\n      r && r.columnNumber,\n      'unhandledrejection', undefined,\n      { category: 'runtime', resourceKind: 'module', blockWhenRootEmpty: true }\n    );\n  });\n\n  // Intercept only errors that indicate a Vite/module compilation failure.\n  // Their render-blocking status is still tied to an empty application root;\n  // Vite HMR compile failures are classified separately by the server bridge.\n  var nativeConsoleError = console.error;\n  console.error = function() {\n    var args = Array.prototype.slice.call(arguments);\n    var msg = args.map(function(a) {\n      return typeof a === 'string' ? a : (a && a.message ? a.message : String(a));\n    }).join(' ');\n    if (/Failed to load module|Internal Server Error|Syntax Error/i.test(msg)) {\n      send(\n        msg, '', undefined, undefined, undefined, 'console.error', undefined,\n        { category: 'compile', resourceKind: 'module', blockWhenRootEmpty: true }\n      );\n    }\n    return nativeConsoleError.apply(console, args);\n  };\n\n  function sendStable(rootHealth) {\n    var images = Array.prototype.slice.call(document.querySelectorAll('img'));\n    var controls = Array.prototype.slice.call(\n      document.querySelectorAll('button, a[href], input, select, textarea')\n    );\n    var checks = {\n      viewportWidth: document.documentElement.clientWidth || window.innerWidth || 0,\n      horizontalOverflow:\n        document.documentElement.scrollWidth >\n        (document.documentElement.clientWidth || window.innerWidth || 0) + 2,\n      brokenImages: images.filter(function(img) {\n        return img.complete && img.naturalWidth === 0;\n      }).length,\n      missingImageAlt: images.filter(function(img) {\n        return !img.hasAttribute('alt');\n      }).length,\n      unlabeledControls: controls.filter(function(control) {\n        var label = (\n          control.getAttribute('aria-label') ||\n          control.getAttribute('title') ||\n          control.textContent ||\n          control.value ||\n          ''\n        ).trim();\n        return !label;\n      }).length\n    };\n    var diagnostics = [];\n\n    if (checks.horizontalOverflow) {\n      diagnostics.push({\n        code: 'horizontal-overflow',\n        classification: 'diagnostic',\n        category: 'layout',\n        severity: 'advisory',\n        resourceKind: 'quality',\n        renderBlocking: false,\n        message: 'The preview has horizontal overflow.'\n      });\n    }\n    if (checks.brokenImages > 0) {\n      diagnostics.push({\n        code: 'broken-images',\n        classification: 'diagnostic',\n        category: 'asset',\n        severity: 'advisory',\n        resourceKind: 'image',\n        renderBlocking: false,\n        message: 'One or more images could not be displayed.',\n        count: checks.brokenImages\n      });\n    }\n    if (checks.missingImageAlt > 0) {\n      diagnostics.push({\n        code: 'missing-image-alt',\n        classification: 'diagnostic',\n        category: 'accessibility',\n        severity: 'advisory',\n        resourceKind: 'image',\n        renderBlocking: false,\n        message: 'One or more images are missing alternative text.',\n        count: checks.missingImageAlt\n      });\n    }\n    if (checks.unlabeledControls > 0) {\n      diagnostics.push({\n        code: 'unlabeled-controls',\n        classification: 'diagnostic',\n        category: 'accessibility',\n        severity: 'advisory',\n        resourceKind: 'control',\n        renderBlocking: false,\n        message: 'One or more controls do not have an accessible label.',\n        count: checks.unlabeledControls\n      });\n    }\n\n    window.parent.postMessage({\n      source: 'adaptar-preview',\n      type: 'preview-stable',\n      operationId: operationId,\n      stableAt: Date.now(),\n      hasRootContent: rootHealth.hasRootContent,\n      rootHealth: rootHealth,\n      checks: checks,\n      diagnostics: diagnostics\n    }, '*');\n  }\n\n  function confirmPreviewHealth() {\n    var rootHealth = readRootHealth();\n    if (rootHealth.hasRootContent) {\n      if (blankCheckTimer) {\n        clearTimeout(blankCheckTimer);\n        blankCheckTimer = undefined;\n      }\n      blankCheckStartedAt = 0;\n      blankFailureReported = false;\n      recoverBlockingErrorsIfRendered('root-recovered');\n      sendStable(rootHealth);\n      return;\n    }\n\n    if (!blankCheckStartedAt) blankCheckStartedAt = Date.now();\n    if (Date.now() - blankCheckStartedAt >= BLANK_CONFIRMATION_MS) {\n      if (!blankFailureReported) {\n        blankFailureReported = true;\n        send(\n          'Runtime error: Preview failed to render; a component or import may have failed silently.',\n          '', location.href, undefined, undefined, 'blank-screen', undefined,\n          { category: 'render', resourceKind: 'document', renderBlocking: true }\n        );\n      }\n      blankCheckTimer = setTimeout(confirmPreviewHealth, ROOT_CHECK_INTERVAL_MS);\n      return;\n    }\n\n    blankCheckTimer = setTimeout(confirmPreviewHealth, ROOT_CHECK_INTERVAL_MS);\n  }\n\n  // A blank root is blocking only when it remains blank across a sustained\n  // observation window. Normal React mounting and Vite reloads are transient.\n  window.addEventListener('load', function() {\n    blankCheckStartedAt = Date.now();\n    requestAnimationFrame(function() {\n      requestAnimationFrame(function() {\n        sendRendered(false);\n      });\n    });\n\n    setTimeout(confirmPreviewHealth, 3000);\n  });\n\n  window.setInterval(function() {\n    sendRendered(true);\n  }, 20000);\n  window.setInterval(function() {\n    recoverBlockingErrorsIfRendered('root-health-monitor');\n  }, 1000);\n})();";
+export declare const ERROR_BRIDGE_SCRIPT = "(function(){\n  if (window.__ADAPTAR_ERROR_BRIDGE__) return;\n  window.__ADAPTAR_ERROR_BRIDGE__ = true;\n\n  var operationId = new URL(window.location.href).searchParams.get('__adaptarOperation') || undefined;\n  var activeBlockingSources = Object.create(null);\n  var blankCheckStartedAt = 0;\n  var blankCheckTimer;\n  var blankFailureReported = false;\n  var BLANK_CONFIRMATION_MS = 8000;\n  var ROOT_CHECK_INTERVAL_MS = 500;\n\n  function readRootHealth() {\n    var root = document.getElementById('root');\n    var hasRootContent = Boolean(\n      root && (root.children.length || (root.textContent || '').trim())\n    );\n\n    return {\n      state: !root ? 'missing' : (hasRootContent ? 'healthy' : 'empty'),\n      hasRootContent: hasRootContent,\n      readyState: document.readyState\n    };\n  }\n\n  function sendRendered(heartbeat) {\n    try {\n      var rootHealth = readRootHealth();\n      window.parent.postMessage({\n        source: 'adaptar-preview',\n        type: heartbeat ? 'render-heartbeat' : 'preview-rendered',\n        operationId: operationId,\n        renderedAt: Date.now(),\n        hasRootContent: rootHealth.hasRootContent,\n        rootHealth: rootHealth\n      }, '*');\n    } catch (_) {}\n  }\n\n  function classifyResource(target, url) {\n    var tag = String((target && target.tagName) || '').toLowerCase();\n    var rel = String((target && target.rel) || '').toLowerCase();\n    var as = String((target && target.as) || '').toLowerCase();\n    var type = String((target && target.type) || '').toLowerCase();\n    var value = String(url || '').split(/[?#]/)[0].toLowerCase();\n\n    if (\n      as === 'font' ||\n      type.indexOf('font/') === 0 ||\n      /\\.(woff2?|ttf|otf|eot)$/.test(value)\n    ) return 'font';\n    if (\n      tag === 'img' ||\n      as === 'image' ||\n      /\\.(avif|bmp|gif|ico|jpe?g|png|svg|webp)$/.test(value)\n    ) return 'image';\n    if (\n      tag === 'audio' || tag === 'video' || tag === 'source' || tag === 'track' ||\n      as === 'audio' || as === 'video' ||\n      /\\.(aac|flac|m4a|m4v|mov|mp3|mp4|ogg|ogv|wav|webm|vtt)$/.test(value)\n    ) return 'media';\n    if (\n      tag === 'script' ||\n      as === 'script' ||\n      rel === 'modulepreload' ||\n      type === 'module' ||\n      /\\.(c|m)?(j|t)sx?$/.test(value)\n    ) return 'module';\n    if (\n      (tag === 'link' && rel === 'stylesheet') ||\n      as === 'style' ||\n      type === 'text/css' ||\n      /\\.(css|less|sass|scss|styl)$/.test(value)\n    ) return 'stylesheet';\n    return 'unknown';\n  }\n\n  function resourceFailureMessage(resourceKind, url) {\n    var labels = {\n      font: 'Failed to load font: ',\n      image: 'Failed to load image: ',\n      media: 'Failed to load media: ',\n      module: 'Failed to load module: ',\n      stylesheet: 'Failed to load stylesheet: ',\n      unknown: 'Failed to load resource: '\n    };\n    return (labels[resourceKind] || labels.unknown) + url;\n  }\n\n  function send(message, stack, filename, lineno, colno, source, plugin, metadata) {\n    try {\n      var details = metadata || {};\n      var rootHealth = readRootHealth();\n      var renderBlocking = details.renderBlocking === true || (\n        details.blockWhenRootEmpty === true && !rootHealth.hasRootContent\n      );\n      var errorSource = source || 'unknown';\n\n      if (renderBlocking) {\n        activeBlockingSources[errorSource] = true;\n      }\n\n      window.parent.postMessage({\n        source: 'adaptar-preview',\n        type: 'error',\n        operationId: operationId,\n        error: {\n          message: message || 'Unknown error',\n          stack: stack || '',\n          filename: filename,\n          lineno: lineno,\n          colno: colno,\n          source: source,\n          plugin: plugin,\n          classification: renderBlocking ? 'render-blocking' : 'diagnostic',\n          category: details.category || 'runtime',\n          severity: renderBlocking ? 'error' : 'advisory',\n          resourceKind: details.resourceKind || 'unknown',\n          renderBlocking: renderBlocking,\n          rootHealth: rootHealth\n        }\n      }, '*');\n    } catch (_) {}\n  }\n\n  function recoverBlockingErrorsIfRendered(reason) {\n    try {\n      var rootHealth = readRootHealth();\n      var resolvedSources = Object.keys(activeBlockingSources);\n      if (!rootHealth.hasRootContent || resolvedSources.length === 0) return;\n\n      activeBlockingSources = Object.create(null);\n      window.parent.postMessage({\n        source: 'adaptar-preview',\n        type: 'preview-recovered',\n        operationId: operationId,\n        recoveredAt: Date.now(),\n        reason: reason || 'root-healthy',\n        resolvedSources: resolvedSources,\n        hasRootContent: true,\n        rootHealth: rootHealth\n      }, '*');\n    } catch (_) {}\n  }\n\n  // Resource failures remain observable, but only a module required before\n  // the application mounts can be classified as render-blocking. Images,\n  // fonts, media, and stylesheets are quality diagnostics.\n  window.addEventListener('error', function(e) {\n    var target = e.target || e.srcElement;\n    if (target && target !== window && target.tagName) {\n      var url = target.src || target.href || target.currentSrc;\n      var resourceKind = classifyResource(target, url);\n      // Inline/module wrapper elements have no actionable resource URL. Vite's\n      // HMR bridge and the sustained blank-root monitor report real compile or\n      // render failures with useful evidence, so do not manufacture an\n      // \"unknown resource URL\" module error here.\n      if (!url) return;\n      if (url || resourceKind !== 'unknown') {\n        send(\n          resourceFailureMessage(resourceKind, url),\n          '', url, undefined, undefined, 'resource-load', undefined,\n          {\n            category: 'resource',\n            resourceKind: resourceKind,\n            blockWhenRootEmpty: resourceKind === 'module'\n          }\n        );\n        return;\n      }\n    }\n\n    send(\n      e.message || (e.error && e.error.message) || 'Runtime error occurred',\n      e.error ? e.error.stack : '',\n      e.filename, e.lineno, e.colno, 'runtime', undefined,\n      { category: 'runtime', resourceKind: 'module', blockWhenRootEmpty: true }\n    );\n  }, true);\n\n  // An async failure is blocking only when the application has no rendered\n  // root. Interaction failures in an otherwise-rendered page remain visible\n  // diagnostics and never invalidate the candidate by themselves.\n  window.addEventListener('unhandledrejection', function(e) {\n    var r = e.reason;\n    send(\n      r && r.message ? r.message : String(r || 'Unhandled Promise Rejection'),\n      r && r.stack,\n      r && r.fileName,\n      r && r.lineNumber,\n      r && r.columnNumber,\n      'unhandledrejection', undefined,\n      { category: 'runtime', resourceKind: 'module', blockWhenRootEmpty: true }\n    );\n  });\n\n  // Intercept only errors that indicate a Vite/module compilation failure.\n  // Their render-blocking status is still tied to an empty application root;\n  // Vite HMR compile failures are classified separately by the server bridge.\n  var nativeConsoleError = console.error;\n  console.error = function() {\n    var args = Array.prototype.slice.call(arguments);\n    var msg = args.map(function(a) {\n      return typeof a === 'string' ? a : (a && a.message ? a.message : String(a));\n    }).join(' ');\n    if (/Failed to load module|Internal Server Error|Syntax Error/i.test(msg)) {\n      send(\n        msg, '', undefined, undefined, undefined, 'console.error', undefined,\n        { category: 'compile', resourceKind: 'module', blockWhenRootEmpty: true }\n      );\n    }\n    return nativeConsoleError.apply(console, args);\n  };\n\n  function sendStable(rootHealth) {\n    var images = Array.prototype.slice.call(document.querySelectorAll('img'));\n    var controls = Array.prototype.slice.call(\n      document.querySelectorAll('button, a[href], input, select, textarea')\n    );\n    var checks = {\n      viewportWidth: document.documentElement.clientWidth || window.innerWidth || 0,\n      horizontalOverflow:\n        document.documentElement.scrollWidth >\n        (document.documentElement.clientWidth || window.innerWidth || 0) + 2,\n      brokenImages: images.filter(function(img) {\n        return img.complete && img.naturalWidth === 0;\n      }).length,\n      missingImageAlt: images.filter(function(img) {\n        return !img.hasAttribute('alt');\n      }).length,\n      unlabeledControls: controls.filter(function(control) {\n        var label = (\n          control.getAttribute('aria-label') ||\n          control.getAttribute('title') ||\n          control.textContent ||\n          control.value ||\n          ''\n        ).trim();\n        return !label;\n      }).length\n    };\n    var diagnostics = [];\n\n    if (checks.horizontalOverflow) {\n      diagnostics.push({\n        code: 'horizontal-overflow',\n        classification: 'diagnostic',\n        category: 'layout',\n        severity: 'advisory',\n        resourceKind: 'quality',\n        renderBlocking: false,\n        message: 'The preview has horizontal overflow.'\n      });\n    }\n    if (checks.brokenImages > 0) {\n      diagnostics.push({\n        code: 'broken-images',\n        classification: 'diagnostic',\n        category: 'asset',\n        severity: 'advisory',\n        resourceKind: 'image',\n        renderBlocking: false,\n        message: 'One or more images could not be displayed.',\n        count: checks.brokenImages\n      });\n    }\n    if (checks.missingImageAlt > 0) {\n      diagnostics.push({\n        code: 'missing-image-alt',\n        classification: 'diagnostic',\n        category: 'accessibility',\n        severity: 'advisory',\n        resourceKind: 'image',\n        renderBlocking: false,\n        message: 'One or more images are missing alternative text.',\n        count: checks.missingImageAlt\n      });\n    }\n    if (checks.unlabeledControls > 0) {\n      diagnostics.push({\n        code: 'unlabeled-controls',\n        classification: 'diagnostic',\n        category: 'accessibility',\n        severity: 'advisory',\n        resourceKind: 'control',\n        renderBlocking: false,\n        message: 'One or more controls do not have an accessible label.',\n        count: checks.unlabeledControls\n      });\n    }\n\n    window.parent.postMessage({\n      source: 'adaptar-preview',\n      type: 'preview-stable',\n      operationId: operationId,\n      stableAt: Date.now(),\n      hasRootContent: rootHealth.hasRootContent,\n      rootHealth: rootHealth,\n      checks: checks,\n      diagnostics: diagnostics\n    }, '*');\n  }\n\n  function confirmPreviewHealth() {\n    var rootHealth = readRootHealth();\n    if (rootHealth.hasRootContent) {\n      if (blankCheckTimer) {\n        clearTimeout(blankCheckTimer);\n        blankCheckTimer = undefined;\n      }\n      blankCheckStartedAt = 0;\n      blankFailureReported = false;\n      recoverBlockingErrorsIfRendered('root-recovered');\n      sendStable(rootHealth);\n      return;\n    }\n\n    if (!blankCheckStartedAt) blankCheckStartedAt = Date.now();\n    if (Date.now() - blankCheckStartedAt >= BLANK_CONFIRMATION_MS) {\n      if (!blankFailureReported) {\n        blankFailureReported = true;\n        send(\n          'Runtime error: Preview failed to render; a component or import may have failed silently.',\n          '', location.href, undefined, undefined, 'blank-screen', undefined,\n          { category: 'render', resourceKind: 'document', renderBlocking: true }\n        );\n      }\n      blankCheckTimer = setTimeout(confirmPreviewHealth, ROOT_CHECK_INTERVAL_MS);\n      return;\n    }\n\n    blankCheckTimer = setTimeout(confirmPreviewHealth, ROOT_CHECK_INTERVAL_MS);\n  }\n\n  // A blank root is blocking only when it remains blank across a sustained\n  // observation window. Normal React mounting and Vite reloads are transient.\n  window.addEventListener('load', function() {\n    blankCheckStartedAt = Date.now();\n    requestAnimationFrame(function() {\n      requestAnimationFrame(function() {\n        sendRendered(false);\n      });\n    });\n\n    setTimeout(confirmPreviewHealth, 3000);\n  });\n\n  window.setInterval(function() {\n    sendRendered(true);\n  }, 20000);\n  window.setInterval(function() {\n    recoverBlockingErrorsIfRendered('root-health-monitor');\n  }, 1000);\n})();";

package/dist/scripts/error-bridge.js

@@ -151,9 +151,14 @@ export const ERROR_BRIDGE_SCRIPT = /* js */ `(function(){
     if (target && target !== window && target.tagName) {
       var url = target.src || target.href || target.currentSrc;
       var resourceKind = classifyResource(target, url);
+      // Inline/module wrapper elements have no actionable resource URL. Vite's
+      // HMR bridge and the sustained blank-root monitor report real compile or
+      // render failures with useful evidence, so do not manufacture an
+      // "unknown resource URL" module error here.
+      if (!url) return;
       if (url || resourceKind !== 'unknown') {
         send(
-          resourceFailureMessage(resourceKind, url || '(unknown resource URL)'),
+          resourceFailureMessage(resourceKind, url),
           '', url, undefined, undefined, 'resource-load', undefined,
           {
             category: 'resource',

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  // Older generations occasionally interpreted \"return to the top\" as a\n  // route and emitted href=\"/top\". Treat that legacy value as a scroll\n  // action so it cannot replace the working preview document with a route\n  // that does not exist. New generations should use href=\"#top\" instead.\n  function normalizeLegacyTopLink(event) {\n    if (!event || event.defaultPrevented) return;\n    if (event.button != null && event.button !== 0) return;\n    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;\n\n    var target = event.target;\n    var anchor = target && typeof target.closest === 'function'\n      ? target.closest('a[href]')\n      : null;\n    if (!anchor || typeof anchor.getAttribute !== 'function') return;\n\n    var href = anchor.getAttribute('href');\n    if (href !== '/top' && href !== '/top/') return;\n\n    event.preventDefault();\n    try {\n      window.history.replaceState({}, '', '/');\n    } catch (_) {}\n\n    try {\n      var root = window.document && window.document.getElementById\n        ? window.document.getElementById('top')\n        : null;\n      if (root && typeof root.scrollIntoView === 'function') {\n        root.scrollIntoView({ behavior: 'smooth', block: 'start' });\n      } else if (typeof window.scrollTo === 'function') {\n        window.scrollTo({ top: 0, behavior: 'smooth' });\n      }\n    } catch (_) {}\n\n    scheduleReport('legacy-top-link');\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  if (window.document && typeof window.document.addEventListener === 'function') {\n    window.document.addEventListener('click', normalizeLegacyTopLink);\n  }\n\n  reportLocation('initial');\n})();";

package/dist/scripts/navigation-bridge.js

@@ -0,0 +1,125 @@
+/**
+ * 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 (_) {}
+  }
+
+  // Older generations occasionally interpreted "return to the top" as a
+  // route and emitted href="/top". Treat that legacy value as a scroll
+  // action so it cannot replace the working preview document with a route
+  // that does not exist. New generations should use href="#top" instead.
+  function normalizeLegacyTopLink(event) {
+    if (!event || event.defaultPrevented) return;
+    if (event.button != null && event.button !== 0) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+
+    var target = event.target;
+    var anchor = target && typeof target.closest === 'function'
+      ? target.closest('a[href]')
+      : null;
+    if (!anchor || typeof anchor.getAttribute !== 'function') return;
+
+    var href = anchor.getAttribute('href');
+    if (href !== '/top' && href !== '/top/') return;
+
+    event.preventDefault();
+    try {
+      window.history.replaceState({}, '', '/');
+    } catch (_) {}
+
+    try {
+      var root = window.document && window.document.getElementById
+        ? window.document.getElementById('top')
+        : null;
+      if (root && typeof root.scrollIntoView === 'function') {
+        root.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      } else if (typeof window.scrollTo === 'function') {
+        window.scrollTo({ top: 0, behavior: 'smooth' });
+      }
+    } catch (_) {}
+
+    scheduleReport('legacy-top-link');
+  }
+
+  instrumentHistory('pushState');
+  instrumentHistory('replaceState');
+
+  window.addEventListener('popstate', function() {
+    scheduleReport('popstate');
+  });
+  window.addEventListener('hashchange', function() {
+    scheduleReport('hashchange');
+  });
+  window.addEventListener('pageshow', function() {
+    scheduleReport('pageshow');
+  });
+
+  if (window.document && typeof window.document.addEventListener === 'function') {
+    window.document.addEventListener('click', normalizeLegacyTopLink);
+  }
+
+  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.10",
+  "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/error-bridge.ts

@@ -151,9 +151,14 @@ export const ERROR_BRIDGE_SCRIPT = /* js */ `(function(){
     if (target && target !== window && target.tagName) {
       var url = target.src || target.href || target.currentSrc;
       var resourceKind = classifyResource(target, url);
+      // Inline/module wrapper elements have no actionable resource URL. Vite's
+      // HMR bridge and the sustained blank-root monitor report real compile or
+      // render failures with useful evidence, so do not manufacture an
+      // "unknown resource URL" module error here.
+      if (!url) return;
       if (url || resourceKind !== 'unknown') {
         send(
-          resourceFailureMessage(resourceKind, url || '(unknown resource URL)'),
+          resourceFailureMessage(resourceKind, url),
           '', url, undefined, undefined, 'resource-load', undefined,
           {
             category: 'resource',

package/src/scripts/navigation-bridge.ts

@@ -0,0 +1,125 @@
+/**
+ * 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 (_) {}
+  }
+
+  // Older generations occasionally interpreted "return to the top" as a
+  // route and emitted href="/top". Treat that legacy value as a scroll
+  // action so it cannot replace the working preview document with a route
+  // that does not exist. New generations should use href="#top" instead.
+  function normalizeLegacyTopLink(event) {
+    if (!event || event.defaultPrevented) return;
+    if (event.button != null && event.button !== 0) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+
+    var target = event.target;
+    var anchor = target && typeof target.closest === 'function'
+      ? target.closest('a[href]')
+      : null;
+    if (!anchor || typeof anchor.getAttribute !== 'function') return;
+
+    var href = anchor.getAttribute('href');
+    if (href !== '/top' && href !== '/top/') return;
+
+    event.preventDefault();
+    try {
+      window.history.replaceState({}, '', '/');
+    } catch (_) {}
+
+    try {
+      var root = window.document && window.document.getElementById
+        ? window.document.getElementById('top')
+        : null;
+      if (root && typeof root.scrollIntoView === 'function') {
+        root.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      } else if (typeof window.scrollTo === 'function') {
+        window.scrollTo({ top: 0, behavior: 'smooth' });
+      }
+    } catch (_) {}
+
+    scheduleReport('legacy-top-link');
+  }
+
+  instrumentHistory('pushState');
+  instrumentHistory('replaceState');
+
+  window.addEventListener('popstate', function() {
+    scheduleReport('popstate');
+  });
+  window.addEventListener('hashchange', function() {
+    scheduleReport('hashchange');
+  });
+  window.addEventListener('pageshow', function() {
+    scheduleReport('pageshow');
+  });
+
+  if (window.document && typeof window.document.addEventListener === 'function') {
+    window.document.addEventListener('click', normalizeLegacyTopLink);
+  }
+
+  reportLocation('initial');
+})();`;

package/test/error-bridge.test.mjs

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import vm from "node:vm";
+import { ERROR_BRIDGE_SCRIPT } from "../dist/scripts/error-bridge.js";
+
+function createErrorBridgeRuntime() {
+  const listeners = new Map();
+  const messages = [];
+  const root = { children: [], textContent: "" };
+  const location = {
+    href: "https://workspace.preview.adaptar.dev/?__adaptarOperation=op-1",
+  };
+  const document = {
+    documentElement: { clientWidth: 1280, scrollWidth: 1280 },
+    getElementById(id) {
+      return id === "root" ? root : null;
+    },
+    querySelectorAll() {
+      return [];
+    },
+  };
+  const window = {
+    location,
+    innerWidth: 1280,
+    parent: {
+      postMessage(message) {
+        messages.push(JSON.parse(JSON.stringify(message)));
+      },
+    },
+    addEventListener(type, listener) {
+      const registered = listeners.get(type) || [];
+      registered.push(listener);
+      listeners.set(type, registered);
+    },
+    setInterval() {
+      return 1;
+    },
+  };
+  window.window = window;
+
+  vm.runInNewContext(ERROR_BRIDGE_SCRIPT, {
+    URL,
+    clearTimeout() {},
+    console: { error() {} },
+    document,
+    location,
+    requestAnimationFrame() {},
+    setTimeout() {
+      return 1;
+    },
+    window,
+  });
+
+  return {
+    messages,
+    dispatchResourceError(target) {
+      for (const listener of listeners.get("error") || []) {
+        listener({ target, srcElement: target });
+      }
+    },
+  };
+}
+
+test("ignores URL-less inline module resource events", () => {
+  const runtime = createErrorBridgeRuntime();
+
+  runtime.dispatchResourceError({
+    tagName: "SCRIPT",
+    type: "module",
+    src: "",
+    href: "",
+    currentSrc: "",
+  });
+
+  assert.deepEqual(runtime.messages, []);
+});
+
+test("still reports an external module resource failure with its URL", () => {
+  const runtime = createErrorBridgeRuntime();
+  const src = "https://workspace.preview.adaptar.dev/src/main.tsx";
+
+  runtime.dispatchResourceError({
+    tagName: "SCRIPT",
+    type: "module",
+    src,
+    href: "",
+    currentSrc: src,
+  });
+
+  assert.equal(runtime.messages.length, 1);
+  assert.equal(runtime.messages[0].type, "error");
+  assert.equal(runtime.messages[0].error.message, `Failed to load module: ${src}`);
+  assert.equal(runtime.messages[0].error.resourceKind, "module");
+});

package/test/navigation-bridge.test.mjs

@@ -0,0 +1,147 @@
+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 documentListeners = 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 document = {
+    addEventListener(type, listener) {
+      const registered = documentListeners.get(type) || [];
+      registered.push(listener);
+      documentListeners.set(type, registered);
+    },
+    getElementById() {
+      return null;
+    },
+  };
+  const scrollCalls = [];
+  const window = {
+    location,
+    parent,
+    history,
+    document,
+    scrollTo(options) {
+      scrollCalls.push(options);
+    },
+    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();
+      }
+    },
+    clickLegacyTopLink() {
+      let prevented = false;
+      const anchor = {
+        getAttribute(name) {
+          return name === "href" ? "/top" : null;
+        },
+      };
+      anchor.closest = () => anchor;
+      for (const listener of documentListeners.get("click") || []) {
+        listener({
+          target: anchor,
+          button: 0,
+          preventDefault() {
+            prevented = true;
+          },
+        });
+      }
+      return { prevented, scrollCalls };
+    },
+  };
+}
+
+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");
+});
+
+test("normalizes legacy /top logo links into a scroll-to-root action", () => {
+  const runtime = createPreviewRuntime(
+    "https://workspace.preview.adaptar.dev/work?__adaptarOperation=operation-1",
+  );
+
+  const result = runtime.clickLegacyTopLink();
+
+  assert.equal(result.prevented, true);
+  assert.equal(new URL(runtime.messages.at(-1).location.pathname, "https://preview").pathname, "/");
+  assert.equal(runtime.messages.at(-1).reason, "replaceState");
+});