@archie/devtools 0.1.12 → 0.1.14

package/dist/client/client.d.mts

@@ -46,15 +46,33 @@ type InjectOptions = {
     localScriptUrl?: string;
 };
 
+type ArchieRouteFrame = 'phone' | 'tablet' | 'desktop';
+/**
+ * Whitelisted subset of a React Router `handle` that is forwarded in
+ * ARCHIE_ROUTE_UPDATE. The router's `handle` is free-form (functions, React
+ * elements...) and is NOT structured-cloneable in general, so only `surface`
+ * (non-empty string) and `frame` ('phone' | 'tablet' | 'desktop') are copied;
+ * any other key and any invalid value is dropped. When neither survives the
+ * `handle` key is omitted from the entry entirely.
+ */
+type ArchieRouteHandle = {
+    surface?: string;
+    frame?: ArchieRouteFrame;
+};
 interface ArchieRouteObjectLike {
     id?: string;
+    handle?: unknown;
     path?: string;
     index?: boolean;
+    Component?: unknown;
+    element?: unknown;
+    lazy?: unknown;
     children?: readonly ArchieRouteObjectLike[];
 }
 interface ArchieRouteMatchLike {
     route: {
         id?: string;
+        handle?: unknown;
     };
     pathname: string;
     params: Record<string, string | undefined>;
@@ -66,27 +84,78 @@ interface ArchieRouterStateLike {
         hash: string;
     };
     matches: readonly ArchieRouteMatchLike[];
+    navigation?: {
+        state: string;
+    };
+    fetchers?: ReadonlyMap<string, {
+        state: string;
+    }>;
 }
 interface ArchieRouterLike {
     routes: readonly ArchieRouteObjectLike[];
     state: ArchieRouterStateLike;
+    navigate?(to: string, opts?: {
+        replace?: boolean;
+    }): Promise<void> | void;
     subscribe(listener: (state: ArchieRouterStateLike) => void): () => void;
 }
+/**
+ * Route information for the sitemap
+ */
+interface ArchieGuardEvidence {
+    componentName: string;
+    roles?: string[];
+    source: 'self' | 'ancestor';
+    ancestorId?: string;
+}
+interface RouteInfo {
+    id: string | undefined;
+    path: string;
+    handle?: ArchieRouteHandle;
+    hasChildren: boolean;
+    parentId: string | null;
+    index: boolean;
+    isLayout: boolean;
+    componentName: string | null;
+    guardEvidence: ArchieGuardEvidence[];
+}
+/**
+ * Type definition for the route update message
+ */
+interface ArchieRouteUpdateMessage {
+    type: 'ARCHIE_ROUTE_UPDATE';
+    payload: {
+        path: string;
+        search: string;
+        hash: string;
+        matches: Array<{
+            id: string | undefined;
+            pathname: string;
+            params: Record<string, string | undefined>;
+            handle?: ArchieRouteHandle;
+        }>;
+        allRoutes: RouteInfo[];
+        layoutRoutes: RouteInfo[];
+        timestamp: number;
+    };
+}
 
 interface ArchieDevToolsRuntimeOptions {
     router: ArchieRouterLike;
     inspector?: boolean;
     inspectorOptions?: InjectOptions;
+    /** Origins allowed to send NAVIGATE / SNAPSHOT_DOM to the route listener. */
+    routeListenerOrigins?: readonly string[];
 }
 
 interface ArchieDevToolProviderProps extends ArchieDevToolsRuntimeOptions {
     children: ReactNode;
 }
-declare function ArchieDevToolProvider({ children, router, inspector, inspectorOptions, }: ArchieDevToolProviderProps): react_jsx_runtime.JSX.Element;
+declare function ArchieDevToolProvider({ children, router, inspector, inspectorOptions, routeListenerOrigins, }: ArchieDevToolProviderProps): react_jsx_runtime.JSX.Element;
 
 interface DndProviderProps {
     children: React.ReactNode;
 }
 declare function DndProvider({ children }: DndProviderProps): react_jsx_runtime.JSX.Element;
 
-export { ArchieDevToolProvider, type ArchieDevToolProviderProps, DndProvider };
+export { ArchieDevToolProvider, type ArchieDevToolProviderProps, type ArchieRouteFrame, type ArchieRouteHandle, type ArchieRouteUpdateMessage, DndProvider, type RouteInfo };

package/dist/client/client.d.ts

@@ -46,15 +46,33 @@ type InjectOptions = {
     localScriptUrl?: string;
 };
 
+type ArchieRouteFrame = 'phone' | 'tablet' | 'desktop';
+/**
+ * Whitelisted subset of a React Router `handle` that is forwarded in
+ * ARCHIE_ROUTE_UPDATE. The router's `handle` is free-form (functions, React
+ * elements...) and is NOT structured-cloneable in general, so only `surface`
+ * (non-empty string) and `frame` ('phone' | 'tablet' | 'desktop') are copied;
+ * any other key and any invalid value is dropped. When neither survives the
+ * `handle` key is omitted from the entry entirely.
+ */
+type ArchieRouteHandle = {
+    surface?: string;
+    frame?: ArchieRouteFrame;
+};
 interface ArchieRouteObjectLike {
     id?: string;
+    handle?: unknown;
     path?: string;
     index?: boolean;
+    Component?: unknown;
+    element?: unknown;
+    lazy?: unknown;
     children?: readonly ArchieRouteObjectLike[];
 }
 interface ArchieRouteMatchLike {
     route: {
         id?: string;
+        handle?: unknown;
     };
     pathname: string;
     params: Record<string, string | undefined>;
@@ -66,27 +84,78 @@ interface ArchieRouterStateLike {
         hash: string;
     };
     matches: readonly ArchieRouteMatchLike[];
+    navigation?: {
+        state: string;
+    };
+    fetchers?: ReadonlyMap<string, {
+        state: string;
+    }>;
 }
 interface ArchieRouterLike {
     routes: readonly ArchieRouteObjectLike[];
     state: ArchieRouterStateLike;
+    navigate?(to: string, opts?: {
+        replace?: boolean;
+    }): Promise<void> | void;
     subscribe(listener: (state: ArchieRouterStateLike) => void): () => void;
 }
+/**
+ * Route information for the sitemap
+ */
+interface ArchieGuardEvidence {
+    componentName: string;
+    roles?: string[];
+    source: 'self' | 'ancestor';
+    ancestorId?: string;
+}
+interface RouteInfo {
+    id: string | undefined;
+    path: string;
+    handle?: ArchieRouteHandle;
+    hasChildren: boolean;
+    parentId: string | null;
+    index: boolean;
+    isLayout: boolean;
+    componentName: string | null;
+    guardEvidence: ArchieGuardEvidence[];
+}
+/**
+ * Type definition for the route update message
+ */
+interface ArchieRouteUpdateMessage {
+    type: 'ARCHIE_ROUTE_UPDATE';
+    payload: {
+        path: string;
+        search: string;
+        hash: string;
+        matches: Array<{
+            id: string | undefined;
+            pathname: string;
+            params: Record<string, string | undefined>;
+            handle?: ArchieRouteHandle;
+        }>;
+        allRoutes: RouteInfo[];
+        layoutRoutes: RouteInfo[];
+        timestamp: number;
+    };
+}
 
 interface ArchieDevToolsRuntimeOptions {
     router: ArchieRouterLike;
     inspector?: boolean;
     inspectorOptions?: InjectOptions;
+    /** Origins allowed to send NAVIGATE / SNAPSHOT_DOM to the route listener. */
+    routeListenerOrigins?: readonly string[];
 }
 
 interface ArchieDevToolProviderProps extends ArchieDevToolsRuntimeOptions {
     children: ReactNode;
 }
-declare function ArchieDevToolProvider({ children, router, inspector, inspectorOptions, }: ArchieDevToolProviderProps): react_jsx_runtime.JSX.Element;
+declare function ArchieDevToolProvider({ children, router, inspector, inspectorOptions, routeListenerOrigins, }: ArchieDevToolProviderProps): react_jsx_runtime.JSX.Element;
 
 interface DndProviderProps {
     children: React.ReactNode;
 }
 declare function DndProvider({ children }: DndProviderProps): react_jsx_runtime.JSX.Element;
 
-export { ArchieDevToolProvider, type ArchieDevToolProviderProps, DndProvider };
+export { ArchieDevToolProvider, type ArchieDevToolProviderProps, type ArchieRouteFrame, type ArchieRouteHandle, type ArchieRouteUpdateMessage, DndProvider, type RouteInfo };

package/dist/client/client.js

@@ -10271,7 +10271,7 @@ function isPreviewOrigin(origin) {
 var DEFAULT_SCRIPT_ID = "archie-inspector-script";
 var R2_INSPECTOR_BASE_URL = "https://pub-bf238c278d9644b39ec34ecaca1d315c.r2.dev";
 function readBuildVersion() {
-  return "0.1.12" ? "0.1.12" : null;
+  return "0.1.14" ? "0.1.14" : null;
 }
 var REMOTE_INSPECTOR_VERSION = readBuildVersion();
 var isRemoteInspectorUrlVersioned = REMOTE_INSPECTOR_VERSION !== null;
@@ -10351,25 +10351,257 @@ function injectInspector(opts = {}) {
   document.head.appendChild(script);
 }
 
+// src/client/route-listener/domSnapshot.ts
+var STRIP_SELECTOR = [
+  "script",
+  "noscript",
+  "iframe",
+  "[data-inspector-badge]",
+  "[data-inspector-context-menu]",
+  "#archie-inspector-styles"
+].join(",");
+var PALETTE_SELECTOR = "#archie-design-palette";
+var CSS_FETCH_TIMEOUT_MS = 2e3;
+var IDLE_TIMEOUT_MS = 500;
+var CSS_URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+function absolutizeCssUrls(css, baseHref) {
+  return css.replace(CSS_URL_RE, (full, _quote, raw) => {
+    if (!raw || raw.startsWith("data:") || raw.startsWith("#")) return full;
+    try {
+      return `url(${new URL(raw, baseHref).href})`;
+    } catch {
+      return full;
+    }
+  });
+}
+function isExcludedSheet(sheet) {
+  const owner = sheet.ownerNode;
+  return !!owner?.matches?.(`${STRIP_SELECTOR},${PALETTE_SELECTOR}`);
+}
+async function fetchCssText(href) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), CSS_FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(href, {
+      mode: "cors",
+      signal: controller.signal
+    });
+    return response.ok ? await response.text() : "";
+  } catch {
+    return "";
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function collectSheetCss(sheet, inlinedHrefs) {
+  if (sheet.disabled || isExcludedSheet(sheet)) return "";
+  const baseHref = sheet.href || document.baseURI;
+  let css = "";
+  try {
+    css = Array.from(sheet.cssRules, (rule) => rule.cssText).join("\n");
+  } catch {
+    css = sheet.href ? await fetchCssText(sheet.href) : "";
+  }
+  if (!css) {
+    const owner = sheet.ownerNode;
+    if (owner?.tagName === "STYLE") css = owner.textContent ?? "";
+  }
+  if (!css) return "";
+  if (sheet.href) inlinedHrefs.add(sheet.href);
+  css = absolutizeCssUrls(css, baseHref);
+  const media = sheet.media?.mediaText;
+  return media && media !== "all" ? `@media ${media}{${css}}` : css;
+}
+async function collectDocumentCss(inlinedHrefs) {
+  const sheets = Array.from(document.styleSheets);
+  const parts = await Promise.all(
+    sheets.map((sheet) => collectSheetCss(sheet, inlinedHrefs))
+  );
+  return parts.filter(Boolean).join("\n");
+}
+function waitForIdle() {
+  return new Promise((resolve) => {
+    const w = window;
+    if (typeof w.requestIdleCallback === "function") {
+      w.requestIdleCallback(() => resolve(), { timeout: IDLE_TIMEOUT_MS });
+    } else {
+      setTimeout(resolve, 50);
+    }
+  });
+}
+async function captureDomSnapshot() {
+  if (document.fonts?.ready) {
+    await document.fonts.ready;
+  }
+  await waitForIdle();
+  const inlinedHrefs = /* @__PURE__ */ new Set();
+  const css = await collectDocumentCss(inlinedHrefs);
+  const clone = document.documentElement.cloneNode(true);
+  clone.querySelectorAll(`${STRIP_SELECTOR}, style:not(${PALETTE_SELECTOR})`).forEach((el) => el.remove());
+  clone.querySelectorAll('link[rel~="stylesheet"]').forEach((link) => {
+    const href = link.href;
+    if (inlinedHrefs.has(href)) {
+      link.remove();
+    } else {
+      link.setAttribute("href", href);
+    }
+  });
+  for (const el of [clone, ...Array.from(clone.querySelectorAll("*"))]) {
+    for (const attr of Array.from(el.attributes)) {
+      if (/^on[a-z]+$/i.test(attr.name)) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+  let head = clone.querySelector("head");
+  if (!head) {
+    head = document.createElement("head");
+    clone.insertBefore(head, clone.firstChild);
+  }
+  const style = document.createElement("style");
+  style.textContent = css;
+  head.insertBefore(style, head.firstChild);
+  if (!head.querySelector("base")) {
+    const base = document.createElement("base");
+    base.setAttribute("href", document.baseURI);
+    head.insertBefore(base, head.firstChild);
+  }
+  return {
+    html: "<!doctype html>" + clone.outerHTML,
+    path: location.pathname + location.search + location.hash,
+    viewport: { width: window.innerWidth, height: window.innerHeight },
+    capturedAt: Date.now()
+  };
+}
+
 // src/client/route-listener/routeListener.ts
-function extractAllRoutes(routes, parentPath = "") {
+var ROUTE_FRAMES = ["phone", "tablet", "desktop"];
+function pickRouteHandle(h) {
+  try {
+    if (typeof h !== "object" || h === null) return void 0;
+    const raw = h;
+    const surface = raw.surface;
+    const frame = raw.frame;
+    const out = {};
+    if (typeof surface === "string" && surface !== "") out.surface = surface;
+    if (typeof frame === "string" && ROUTE_FRAMES.includes(frame)) {
+      out.frame = frame;
+    }
+    return out.surface !== void 0 || out.frame !== void 0 ? out : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var GUARD_NAME_RE = /guard|protect|require|auth(?!or)/i;
+var GUARD_PRIVATE_RE = /\bprivate|Private(?=[A-Z]|$)/;
+var NON_GUARD_SUFFIX_RE = /(Layout|Provider|Context|Page|Form|Screen|View)$/;
+function isGuardName(name) {
+  return !NON_GUARD_SUFFIX_RE.test(name) && (GUARD_NAME_RE.test(name) || GUARD_PRIVATE_RE.test(name));
+}
+var GUARD_PROP_NAMES = [
+  "roles",
+  "allowedRoles",
+  "requiredRoles",
+  "permission",
+  "permissions"
+];
+var MAX_ELEMENT_DEPTH = 6;
+function typeName(type) {
+  if (typeof type === "string") return type;
+  if (typeof type === "function") {
+    const fn = type;
+    return fn.displayName || fn.name || null;
+  }
+  if (type && typeof type === "object") {
+    const obj = type;
+    return obj.displayName || typeName(obj.render) || typeName(obj.type);
+  }
+  return null;
+}
+function isElementLike(node) {
+  return !!node && typeof node === "object" && "type" in node && "props" in node;
+}
+function literalRoles(value) {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+    return value;
+  }
+  return void 0;
+}
+function collectGuards(node, depth, out) {
+  if (depth > MAX_ELEMENT_DEPTH || node == null) return;
+  if (Array.isArray(node)) {
+    for (const child of node) collectGuards(child, depth, out);
+    return;
+  }
+  if (!isElementLike(node)) return;
+  const props = node.props ?? {};
+  const name = typeName(node.type);
+  const roleProps = GUARD_PROP_NAMES.filter((p) => p in props);
+  const isNamedGuard = typeof node.type !== "string" && !!name && isGuardName(name);
+  if (isNamedGuard || roleProps.length > 0) {
+    const roles = roleProps.flatMap((p) => literalRoles(props[p]) ?? []);
+    out.push({
+      componentName: name ?? "Anonymous",
+      ...roles.length > 0 ? { roles } : {}
+    });
+  }
+  collectGuards(props.children, depth + 1, out);
+}
+function routeComponentName(route) {
+  if (route.Component) return typeName(route.Component);
+  if (isElementLike(route.element)) return typeName(route.element.type);
+  return null;
+}
+function extractAllRoutes(routes, parentPath = "", parentId = null, inheritedGuards = []) {
   const result = [];
   for (const route of routes) {
     const path = route.path ? (parentPath + "/" + route.path).replace(/\/+/g, "/") : parentPath || "/";
-    if (route.path !== void 0 || route.index) {
+    const hasChildren = !!(route.children && route.children.length > 0);
+    const isLayout = !route.path && !route.index && hasChildren;
+    const own = [];
+    collectGuards(route.element, 0, own);
+    const handle = pickRouteHandle(route.handle);
+    if (route.path !== void 0 || route.index || isLayout) {
       result.push({
         id: route.id,
         path: route.index ? parentPath || "/" : path,
-        hasChildren: !!(route.children && route.children.length > 0)
+        ...handle ? { handle } : {},
+        hasChildren,
+        parentId,
+        index: !!route.index,
+        isLayout,
+        componentName: routeComponentName(route),
+        guardEvidence: [
+          ...own.map((g) => ({ ...g, source: "self" })),
+          ...inheritedGuards
+        ]
       });
     }
     if (route.children) {
-      result.push(...extractAllRoutes(route.children, path));
+      const forChildren = [
+        ...own.map(
+          (g) => ({
+            ...g,
+            source: "ancestor",
+            ...route.id !== void 0 ? { ancestorId: route.id } : {}
+          })
+        ),
+        ...inheritedGuards
+      ];
+      result.push(
+        ...extractAllRoutes(
+          route.children,
+          path,
+          route.id ?? parentId,
+          forChildren
+        )
+      );
     }
   }
   return result;
 }
-function broadcastRouteState(target, state, allRoutes) {
+function broadcastRouteState(target, state, routes) {
   try {
     const message = {
       type: "ARCHIE_ROUTE_UPDATE",
@@ -10377,12 +10609,18 @@ function broadcastRouteState(target, state, allRoutes) {
         path: state.location.pathname,
         search: state.location.search,
         hash: state.location.hash,
-        matches: state.matches.map((m) => ({
-          id: m.route.id,
-          pathname: m.pathname,
-          params: m.params
-        })),
-        allRoutes,
+        matches: state.matches.map((m) => {
+          const handle = pickRouteHandle(m.route.handle);
+          return {
+            id: m.route.id,
+            pathname: m.pathname,
+            params: m.params,
+            ...handle ? { handle } : {}
+          };
+        }),
+        // Layouts stay out of allRoutes so consumers that predate them don't list duplicates.
+        allRoutes: routes.filter((r) => !r.isLayout),
+        layoutRoutes: routes.filter((r) => r.isLayout),
         timestamp: Date.now()
       }
     };
@@ -10390,21 +10628,174 @@ function broadcastRouteState(target, state, allRoutes) {
   } catch {
   }
 }
-function setupArchieRouteListener(router) {
+var SETTLE_QUIET_MS = 400;
+var SETTLE_TIMEOUT_MS = 8e3;
+var SETTLE_POLL_MS = 50;
+function readPackageVersion() {
+  return true ? "0.1.14" : "unknown";
+}
+var DEFAULT_ARCHIE_COMMAND_ORIGINS = getAllowedOrigins(true);
+function originPatternToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/:\*$/, ":\\d+").replace(/\*/g, "[a-z0-9.-]+");
+  return new RegExp(`^${escaped}$`, "i");
+}
+function isAllowedCommandOrigin(origin, allowed) {
+  return allowed.some((pattern) => originPatternToRegExp(pattern).test(origin));
+}
+function postToTarget(target, message, targetOrigin = "*") {
+  try {
+    target.postMessage(message, targetOrigin);
+  } catch {
+  }
+}
+function isRouterBusy(router) {
+  const { navigation, fetchers } = router.state;
+  if (navigation && navigation.state !== "idle") return true;
+  if (fetchers) {
+    for (const fetcher of fetchers.values()) {
+      if (fetcher.state !== "idle") return true;
+    }
+  }
+  return false;
+}
+function waitForSettled(router, navigation) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    let lastMutationAt = Date.now();
+    let navigationDone = false;
+    const observer = new MutationObserver(() => {
+      lastMutationAt = Date.now();
+    });
+    observer.observe(document, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      characterData: true
+    });
+    navigation.then(
+      () => {
+        navigationDone = true;
+      },
+      () => {
+        navigationDone = true;
+      }
+    );
+    const finish = (settled) => {
+      clearInterval(timer);
+      observer.disconnect();
+      resolve(settled);
+    };
+    const timer = setInterval(() => {
+      const now = Date.now();
+      if (navigationDone && !isRouterBusy(router) && now - lastMutationAt >= SETTLE_QUIET_MS) {
+        finish(true);
+      } else if (now - startedAt >= SETTLE_TIMEOUT_MS) {
+        finish(false);
+      }
+    }, SETTLE_POLL_MS);
+  });
+}
+function pathnameOf(path) {
+  return path.split(/[?#]/, 1)[0];
+}
+async function handleNavigate(router, target, targetOrigin, data) {
+  if (typeof router.navigate !== "function") {
+    const { location: location3 } = router.state;
+    postToTarget(target, {
+      type: "ARCHIE_NAVIGATE_RESULT",
+      requestId: data.requestId,
+      requestedPath: data.path,
+      finalPath: location3.pathname + location3.search + location3.hash,
+      matchedRouteIds: [],
+      redirected: false,
+      settled: false
+    }, targetOrigin);
+    return;
+  }
+  let navigation = Promise.resolve();
+  try {
+    navigation = Promise.resolve(
+      router.navigate(data.path, { replace: data.replace })
+    );
+  } catch {
+    navigation = Promise.resolve();
+  }
+  const settled = await waitForSettled(router, navigation);
+  const { location: location2, matches } = router.state;
+  postToTarget(target, {
+    type: "ARCHIE_NAVIGATE_RESULT",
+    requestId: data.requestId,
+    requestedPath: data.path,
+    finalPath: location2.pathname + location2.search + location2.hash,
+    matchedRouteIds: matches.map((m) => m.route.id).filter((id) => typeof id === "string"),
+    redirected: location2.pathname !== pathnameOf(data.path),
+    settled
+  }, targetOrigin);
+}
+async function handleSnapshot(target, targetOrigin, requestId) {
+  try {
+    const snapshot = await captureDomSnapshot();
+    postToTarget(target, {
+      type: "ARCHIE_SNAPSHOT_DOM_RESULT",
+      requestId,
+      ...snapshot
+    }, targetOrigin);
+  } catch (error) {
+    postToTarget(target, {
+      type: "ARCHIE_SNAPSHOT_DOM_FAILED",
+      requestId,
+      error: error instanceof Error ? error.message : String(error)
+    }, targetOrigin);
+  }
+}
+function broadcastCapabilities(router, target) {
+  postToTarget(target, {
+    type: "ARCHIE_CAPABILITIES",
+    version: readPackageVersion(),
+    capabilities: {
+      navigate: typeof router.navigate === "function",
+      snapshot: true,
+      identityOverride: false
+    }
+  });
+}
+function setupArchieRouteListener(router, options = {}) {
+  const allowedOrigins = options.allowedOrigins ?? DEFAULT_ARCHIE_COMMAND_ORIGINS;
   const target = window.parent !== window ? window.parent : window.opener;
   if (!target) {
     return () => {
     };
   }
   broadcastRouteState(target, router.state, extractAllRoutes(router.routes));
+  broadcastCapabilities(router, target);
   const unsubscribe = router.subscribe((state) => {
     const currentRoutes = extractAllRoutes(router.routes);
     broadcastRouteState(target, state, currentRoutes);
   });
   const handleMessage = (event) => {
-    if (event.data?.type === "ARCHIE_QUERY_ROUTES") {
-      const currentRoutes = extractAllRoutes(router.routes);
-      broadcastRouteState(target, router.state, currentRoutes);
+    if (event.source !== target) return;
+    const data = event.data;
+    switch (data?.type) {
+      case "ARCHIE_QUERY_ROUTES":
+        broadcastRouteState(
+          target,
+          router.state,
+          extractAllRoutes(router.routes)
+        );
+        break;
+      case "ARCHIE_QUERY_CAPABILITIES":
+        broadcastCapabilities(router, target);
+        break;
+      case "ARCHIE_NAVIGATE":
+        if (isAllowedCommandOrigin(event.origin, allowedOrigins) && typeof data.requestId === "string" && typeof data.path === "string") {
+          void handleNavigate(router, target, event.origin, data);
+        }
+        break;
+      case "ARCHIE_SNAPSHOT_DOM":
+        if (isAllowedCommandOrigin(event.origin, allowedOrigins) && typeof data.requestId === "string") {
+          void handleSnapshot(target, event.origin, data.requestId);
+        }
+        break;
     }
   };
   window.addEventListener("message", handleMessage);
@@ -10444,7 +10835,8 @@ function installDomMetaSanitizer() {
 function useArchieDevToolsRuntime({
   router,
   inspector,
-  inspectorOptions
+  inspectorOptions,
+  routeListenerOrigins
 }) {
   installDomMetaSanitizer();
   const stableOptionsKey = JSON.stringify(inspectorOptions ?? null);
@@ -10454,7 +10846,9 @@ function useArchieDevToolsRuntime({
     if (process.env.NODE_ENV !== "development") {
       return;
     }
-    const unsubscribe = setupArchieRouteListener(router);
+    const unsubscribe = setupArchieRouteListener(router, {
+      allowedOrigins: routeListenerOrigins
+    });
     if (inspector !== false) {
       const useLocalInspector = readArchieLocalInspectorFlag();
       injectInspector({
@@ -10472,9 +10866,15 @@ function ArchieDevToolProvider({
   children,
   router,
   inspector,
-  inspectorOptions
+  inspectorOptions,
+  routeListenerOrigins
 }) {
-  useArchieDevToolsRuntime({ router, inspector, inspectorOptions });
+  useArchieDevToolsRuntime({
+    router,
+    inspector,
+    inspectorOptions,
+    routeListenerOrigins
+  });
   return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(DndProvider, { children });
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/client/client.mjs

@@ -10236,7 +10236,7 @@ function isPreviewOrigin(origin) {
 var DEFAULT_SCRIPT_ID = "archie-inspector-script";
 var R2_INSPECTOR_BASE_URL = "https://pub-bf238c278d9644b39ec34ecaca1d315c.r2.dev";
 function readBuildVersion() {
-  return "0.1.12" ? "0.1.12" : null;
+  return "0.1.14" ? "0.1.14" : null;
 }
 var REMOTE_INSPECTOR_VERSION = readBuildVersion();
 var isRemoteInspectorUrlVersioned = REMOTE_INSPECTOR_VERSION !== null;
@@ -10316,25 +10316,257 @@ function injectInspector(opts = {}) {
   document.head.appendChild(script);
 }
 
+// src/client/route-listener/domSnapshot.ts
+var STRIP_SELECTOR = [
+  "script",
+  "noscript",
+  "iframe",
+  "[data-inspector-badge]",
+  "[data-inspector-context-menu]",
+  "#archie-inspector-styles"
+].join(",");
+var PALETTE_SELECTOR = "#archie-design-palette";
+var CSS_FETCH_TIMEOUT_MS = 2e3;
+var IDLE_TIMEOUT_MS = 500;
+var CSS_URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+function absolutizeCssUrls(css, baseHref) {
+  return css.replace(CSS_URL_RE, (full, _quote, raw) => {
+    if (!raw || raw.startsWith("data:") || raw.startsWith("#")) return full;
+    try {
+      return `url(${new URL(raw, baseHref).href})`;
+    } catch {
+      return full;
+    }
+  });
+}
+function isExcludedSheet(sheet) {
+  const owner = sheet.ownerNode;
+  return !!owner?.matches?.(`${STRIP_SELECTOR},${PALETTE_SELECTOR}`);
+}
+async function fetchCssText(href) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), CSS_FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(href, {
+      mode: "cors",
+      signal: controller.signal
+    });
+    return response.ok ? await response.text() : "";
+  } catch {
+    return "";
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function collectSheetCss(sheet, inlinedHrefs) {
+  if (sheet.disabled || isExcludedSheet(sheet)) return "";
+  const baseHref = sheet.href || document.baseURI;
+  let css = "";
+  try {
+    css = Array.from(sheet.cssRules, (rule) => rule.cssText).join("\n");
+  } catch {
+    css = sheet.href ? await fetchCssText(sheet.href) : "";
+  }
+  if (!css) {
+    const owner = sheet.ownerNode;
+    if (owner?.tagName === "STYLE") css = owner.textContent ?? "";
+  }
+  if (!css) return "";
+  if (sheet.href) inlinedHrefs.add(sheet.href);
+  css = absolutizeCssUrls(css, baseHref);
+  const media = sheet.media?.mediaText;
+  return media && media !== "all" ? `@media ${media}{${css}}` : css;
+}
+async function collectDocumentCss(inlinedHrefs) {
+  const sheets = Array.from(document.styleSheets);
+  const parts = await Promise.all(
+    sheets.map((sheet) => collectSheetCss(sheet, inlinedHrefs))
+  );
+  return parts.filter(Boolean).join("\n");
+}
+function waitForIdle() {
+  return new Promise((resolve) => {
+    const w = window;
+    if (typeof w.requestIdleCallback === "function") {
+      w.requestIdleCallback(() => resolve(), { timeout: IDLE_TIMEOUT_MS });
+    } else {
+      setTimeout(resolve, 50);
+    }
+  });
+}
+async function captureDomSnapshot() {
+  if (document.fonts?.ready) {
+    await document.fonts.ready;
+  }
+  await waitForIdle();
+  const inlinedHrefs = /* @__PURE__ */ new Set();
+  const css = await collectDocumentCss(inlinedHrefs);
+  const clone = document.documentElement.cloneNode(true);
+  clone.querySelectorAll(`${STRIP_SELECTOR}, style:not(${PALETTE_SELECTOR})`).forEach((el) => el.remove());
+  clone.querySelectorAll('link[rel~="stylesheet"]').forEach((link) => {
+    const href = link.href;
+    if (inlinedHrefs.has(href)) {
+      link.remove();
+    } else {
+      link.setAttribute("href", href);
+    }
+  });
+  for (const el of [clone, ...Array.from(clone.querySelectorAll("*"))]) {
+    for (const attr of Array.from(el.attributes)) {
+      if (/^on[a-z]+$/i.test(attr.name)) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+  let head = clone.querySelector("head");
+  if (!head) {
+    head = document.createElement("head");
+    clone.insertBefore(head, clone.firstChild);
+  }
+  const style = document.createElement("style");
+  style.textContent = css;
+  head.insertBefore(style, head.firstChild);
+  if (!head.querySelector("base")) {
+    const base = document.createElement("base");
+    base.setAttribute("href", document.baseURI);
+    head.insertBefore(base, head.firstChild);
+  }
+  return {
+    html: "<!doctype html>" + clone.outerHTML,
+    path: location.pathname + location.search + location.hash,
+    viewport: { width: window.innerWidth, height: window.innerHeight },
+    capturedAt: Date.now()
+  };
+}
+
 // src/client/route-listener/routeListener.ts
-function extractAllRoutes(routes, parentPath = "") {
+var ROUTE_FRAMES = ["phone", "tablet", "desktop"];
+function pickRouteHandle(h) {
+  try {
+    if (typeof h !== "object" || h === null) return void 0;
+    const raw = h;
+    const surface = raw.surface;
+    const frame = raw.frame;
+    const out = {};
+    if (typeof surface === "string" && surface !== "") out.surface = surface;
+    if (typeof frame === "string" && ROUTE_FRAMES.includes(frame)) {
+      out.frame = frame;
+    }
+    return out.surface !== void 0 || out.frame !== void 0 ? out : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var GUARD_NAME_RE = /guard|protect|require|auth(?!or)/i;
+var GUARD_PRIVATE_RE = /\bprivate|Private(?=[A-Z]|$)/;
+var NON_GUARD_SUFFIX_RE = /(Layout|Provider|Context|Page|Form|Screen|View)$/;
+function isGuardName(name) {
+  return !NON_GUARD_SUFFIX_RE.test(name) && (GUARD_NAME_RE.test(name) || GUARD_PRIVATE_RE.test(name));
+}
+var GUARD_PROP_NAMES = [
+  "roles",
+  "allowedRoles",
+  "requiredRoles",
+  "permission",
+  "permissions"
+];
+var MAX_ELEMENT_DEPTH = 6;
+function typeName(type) {
+  if (typeof type === "string") return type;
+  if (typeof type === "function") {
+    const fn = type;
+    return fn.displayName || fn.name || null;
+  }
+  if (type && typeof type === "object") {
+    const obj = type;
+    return obj.displayName || typeName(obj.render) || typeName(obj.type);
+  }
+  return null;
+}
+function isElementLike(node) {
+  return !!node && typeof node === "object" && "type" in node && "props" in node;
+}
+function literalRoles(value) {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+    return value;
+  }
+  return void 0;
+}
+function collectGuards(node, depth, out) {
+  if (depth > MAX_ELEMENT_DEPTH || node == null) return;
+  if (Array.isArray(node)) {
+    for (const child of node) collectGuards(child, depth, out);
+    return;
+  }
+  if (!isElementLike(node)) return;
+  const props = node.props ?? {};
+  const name = typeName(node.type);
+  const roleProps = GUARD_PROP_NAMES.filter((p) => p in props);
+  const isNamedGuard = typeof node.type !== "string" && !!name && isGuardName(name);
+  if (isNamedGuard || roleProps.length > 0) {
+    const roles = roleProps.flatMap((p) => literalRoles(props[p]) ?? []);
+    out.push({
+      componentName: name ?? "Anonymous",
+      ...roles.length > 0 ? { roles } : {}
+    });
+  }
+  collectGuards(props.children, depth + 1, out);
+}
+function routeComponentName(route) {
+  if (route.Component) return typeName(route.Component);
+  if (isElementLike(route.element)) return typeName(route.element.type);
+  return null;
+}
+function extractAllRoutes(routes, parentPath = "", parentId = null, inheritedGuards = []) {
   const result = [];
   for (const route of routes) {
     const path = route.path ? (parentPath + "/" + route.path).replace(/\/+/g, "/") : parentPath || "/";
-    if (route.path !== void 0 || route.index) {
+    const hasChildren = !!(route.children && route.children.length > 0);
+    const isLayout = !route.path && !route.index && hasChildren;
+    const own = [];
+    collectGuards(route.element, 0, own);
+    const handle = pickRouteHandle(route.handle);
+    if (route.path !== void 0 || route.index || isLayout) {
       result.push({
         id: route.id,
         path: route.index ? parentPath || "/" : path,
-        hasChildren: !!(route.children && route.children.length > 0)
+        ...handle ? { handle } : {},
+        hasChildren,
+        parentId,
+        index: !!route.index,
+        isLayout,
+        componentName: routeComponentName(route),
+        guardEvidence: [
+          ...own.map((g) => ({ ...g, source: "self" })),
+          ...inheritedGuards
+        ]
       });
     }
     if (route.children) {
-      result.push(...extractAllRoutes(route.children, path));
+      const forChildren = [
+        ...own.map(
+          (g) => ({
+            ...g,
+            source: "ancestor",
+            ...route.id !== void 0 ? { ancestorId: route.id } : {}
+          })
+        ),
+        ...inheritedGuards
+      ];
+      result.push(
+        ...extractAllRoutes(
+          route.children,
+          path,
+          route.id ?? parentId,
+          forChildren
+        )
+      );
     }
   }
   return result;
 }
-function broadcastRouteState(target, state, allRoutes) {
+function broadcastRouteState(target, state, routes) {
   try {
     const message = {
       type: "ARCHIE_ROUTE_UPDATE",
@@ -10342,12 +10574,18 @@ function broadcastRouteState(target, state, allRoutes) {
         path: state.location.pathname,
         search: state.location.search,
         hash: state.location.hash,
-        matches: state.matches.map((m) => ({
-          id: m.route.id,
-          pathname: m.pathname,
-          params: m.params
-        })),
-        allRoutes,
+        matches: state.matches.map((m) => {
+          const handle = pickRouteHandle(m.route.handle);
+          return {
+            id: m.route.id,
+            pathname: m.pathname,
+            params: m.params,
+            ...handle ? { handle } : {}
+          };
+        }),
+        // Layouts stay out of allRoutes so consumers that predate them don't list duplicates.
+        allRoutes: routes.filter((r) => !r.isLayout),
+        layoutRoutes: routes.filter((r) => r.isLayout),
         timestamp: Date.now()
       }
     };
@@ -10355,21 +10593,174 @@ function broadcastRouteState(target, state, allRoutes) {
   } catch {
   }
 }
-function setupArchieRouteListener(router) {
+var SETTLE_QUIET_MS = 400;
+var SETTLE_TIMEOUT_MS = 8e3;
+var SETTLE_POLL_MS = 50;
+function readPackageVersion() {
+  return true ? "0.1.14" : "unknown";
+}
+var DEFAULT_ARCHIE_COMMAND_ORIGINS = getAllowedOrigins(true);
+function originPatternToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/:\*$/, ":\\d+").replace(/\*/g, "[a-z0-9.-]+");
+  return new RegExp(`^${escaped}$`, "i");
+}
+function isAllowedCommandOrigin(origin, allowed) {
+  return allowed.some((pattern) => originPatternToRegExp(pattern).test(origin));
+}
+function postToTarget(target, message, targetOrigin = "*") {
+  try {
+    target.postMessage(message, targetOrigin);
+  } catch {
+  }
+}
+function isRouterBusy(router) {
+  const { navigation, fetchers } = router.state;
+  if (navigation && navigation.state !== "idle") return true;
+  if (fetchers) {
+    for (const fetcher of fetchers.values()) {
+      if (fetcher.state !== "idle") return true;
+    }
+  }
+  return false;
+}
+function waitForSettled(router, navigation) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    let lastMutationAt = Date.now();
+    let navigationDone = false;
+    const observer = new MutationObserver(() => {
+      lastMutationAt = Date.now();
+    });
+    observer.observe(document, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      characterData: true
+    });
+    navigation.then(
+      () => {
+        navigationDone = true;
+      },
+      () => {
+        navigationDone = true;
+      }
+    );
+    const finish = (settled) => {
+      clearInterval(timer);
+      observer.disconnect();
+      resolve(settled);
+    };
+    const timer = setInterval(() => {
+      const now = Date.now();
+      if (navigationDone && !isRouterBusy(router) && now - lastMutationAt >= SETTLE_QUIET_MS) {
+        finish(true);
+      } else if (now - startedAt >= SETTLE_TIMEOUT_MS) {
+        finish(false);
+      }
+    }, SETTLE_POLL_MS);
+  });
+}
+function pathnameOf(path) {
+  return path.split(/[?#]/, 1)[0];
+}
+async function handleNavigate(router, target, targetOrigin, data) {
+  if (typeof router.navigate !== "function") {
+    const { location: location3 } = router.state;
+    postToTarget(target, {
+      type: "ARCHIE_NAVIGATE_RESULT",
+      requestId: data.requestId,
+      requestedPath: data.path,
+      finalPath: location3.pathname + location3.search + location3.hash,
+      matchedRouteIds: [],
+      redirected: false,
+      settled: false
+    }, targetOrigin);
+    return;
+  }
+  let navigation = Promise.resolve();
+  try {
+    navigation = Promise.resolve(
+      router.navigate(data.path, { replace: data.replace })
+    );
+  } catch {
+    navigation = Promise.resolve();
+  }
+  const settled = await waitForSettled(router, navigation);
+  const { location: location2, matches } = router.state;
+  postToTarget(target, {
+    type: "ARCHIE_NAVIGATE_RESULT",
+    requestId: data.requestId,
+    requestedPath: data.path,
+    finalPath: location2.pathname + location2.search + location2.hash,
+    matchedRouteIds: matches.map((m) => m.route.id).filter((id) => typeof id === "string"),
+    redirected: location2.pathname !== pathnameOf(data.path),
+    settled
+  }, targetOrigin);
+}
+async function handleSnapshot(target, targetOrigin, requestId) {
+  try {
+    const snapshot = await captureDomSnapshot();
+    postToTarget(target, {
+      type: "ARCHIE_SNAPSHOT_DOM_RESULT",
+      requestId,
+      ...snapshot
+    }, targetOrigin);
+  } catch (error) {
+    postToTarget(target, {
+      type: "ARCHIE_SNAPSHOT_DOM_FAILED",
+      requestId,
+      error: error instanceof Error ? error.message : String(error)
+    }, targetOrigin);
+  }
+}
+function broadcastCapabilities(router, target) {
+  postToTarget(target, {
+    type: "ARCHIE_CAPABILITIES",
+    version: readPackageVersion(),
+    capabilities: {
+      navigate: typeof router.navigate === "function",
+      snapshot: true,
+      identityOverride: false
+    }
+  });
+}
+function setupArchieRouteListener(router, options = {}) {
+  const allowedOrigins = options.allowedOrigins ?? DEFAULT_ARCHIE_COMMAND_ORIGINS;
   const target = window.parent !== window ? window.parent : window.opener;
   if (!target) {
     return () => {
     };
   }
   broadcastRouteState(target, router.state, extractAllRoutes(router.routes));
+  broadcastCapabilities(router, target);
   const unsubscribe = router.subscribe((state) => {
     const currentRoutes = extractAllRoutes(router.routes);
     broadcastRouteState(target, state, currentRoutes);
   });
   const handleMessage = (event) => {
-    if (event.data?.type === "ARCHIE_QUERY_ROUTES") {
-      const currentRoutes = extractAllRoutes(router.routes);
-      broadcastRouteState(target, router.state, currentRoutes);
+    if (event.source !== target) return;
+    const data = event.data;
+    switch (data?.type) {
+      case "ARCHIE_QUERY_ROUTES":
+        broadcastRouteState(
+          target,
+          router.state,
+          extractAllRoutes(router.routes)
+        );
+        break;
+      case "ARCHIE_QUERY_CAPABILITIES":
+        broadcastCapabilities(router, target);
+        break;
+      case "ARCHIE_NAVIGATE":
+        if (isAllowedCommandOrigin(event.origin, allowedOrigins) && typeof data.requestId === "string" && typeof data.path === "string") {
+          void handleNavigate(router, target, event.origin, data);
+        }
+        break;
+      case "ARCHIE_SNAPSHOT_DOM":
+        if (isAllowedCommandOrigin(event.origin, allowedOrigins) && typeof data.requestId === "string") {
+          void handleSnapshot(target, event.origin, data.requestId);
+        }
+        break;
     }
   };
   window.addEventListener("message", handleMessage);
@@ -10409,7 +10800,8 @@ function installDomMetaSanitizer() {
 function useArchieDevToolsRuntime({
   router,
   inspector,
-  inspectorOptions
+  inspectorOptions,
+  routeListenerOrigins
 }) {
   installDomMetaSanitizer();
   const stableOptionsKey = JSON.stringify(inspectorOptions ?? null);
@@ -10419,7 +10811,9 @@ function useArchieDevToolsRuntime({
     if (process.env.NODE_ENV !== "development") {
       return;
     }
-    const unsubscribe = setupArchieRouteListener(router);
+    const unsubscribe = setupArchieRouteListener(router, {
+      allowedOrigins: routeListenerOrigins
+    });
     if (inspector !== false) {
       const useLocalInspector = readArchieLocalInspectorFlag();
       injectInspector({
@@ -10437,9 +10831,15 @@ function ArchieDevToolProvider({
   children,
   router,
   inspector,
-  inspectorOptions
+  inspectorOptions,
+  routeListenerOrigins
 }) {
-  useArchieDevToolsRuntime({ router, inspector, inspectorOptions });
+  useArchieDevToolsRuntime({
+    router,
+    inspector,
+    inspectorOptions,
+    routeListenerOrigins
+  });
   return /* @__PURE__ */ jsx6(DndProvider, { children });
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archie/devtools",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "DevTools for Archie generated applications - Route synchronization and editor communication",
   "sideEffects": false,
   "repository": {