@archie/devtools 0.0.4 → 0.0.6

package/README.md

@@ -1,22 +1,20 @@
 # @archie/devtools
 
-DevTools for Archie generated applications. Provides seamless communication between the generated app and the Archie editor.
+DevTools for Archie generated applications. Route sync with the editor and optional element inspector script.
 
 ## Installation
 
 ```bash
 npm install @archie/devtools
+# or
+pnpm add @archie/devtools
 ```
 
 ## Features
 
-### Route Synchronization
-
-Automatically syncs the current route from your app to the Archie editor, enabling real-time preview navigation.
-
-### Vite Plugin (Optional)
-
-Provides build-time integration for future features like component tagging and HMR overrides.
+- **Route synchronization** – Current route is sent to the Archie editor for live preview.
+- **Inspector script (optional)** – Injects the element inspector at runtime (no URL, bundled).
+- **Vite plugin (optional)** – Build-time hook for future features.
 
 ## Usage
 
@@ -32,20 +30,46 @@ export default defineConfig({
 });
 ```
 
-### 2. Initialize Route Listener (Required)
+### 2. Inspector script (optional)
+
+Injects the inspector when the client bundle runs. Safe in SSR (no-op on server). One line, no `useEffect`:
+
+```typescript
+// App root, e.g. layout.tsx or main.tsx
+import "@archie/devtools/client/inject-inspector/auto";
+```
+
+**¿Afecta que la función tenga opciones?** No. El auto-import llama `injectInspector()` sin argumentos. Por defecto se usan orígenes Archie + localhost en dev y el target desde el parent (iframe). Solo si quieres cambiar algo pasas opciones:
 
 ```typescript
-// src/main.tsx
+import { injectInspector } from "@archie/devtools/client";
+
+// Igual que el auto: sin argumentos, valores por defecto seguros
+injectInspector();
+
+// Opcional: incluir localhost explícitamente, o fijar orígenes/target
+injectInspector({ dev: true });
+injectInspector({ id: "my-inspector" });
+injectInspector({ allowedOrigins: ["https://app.archie.com"], targetOrigin: "https://app.archie.com" });
+```
+
+Paths:
+
+- `@archie/devtools/client` – route listener + `injectInspector`
+- `@archie/devtools/client/inject-inspector/auto` – side-effect only (import and it runs)
+
+### 3. Route listener (required for preview sync)
+
+```typescript
+// e.g. src/main.tsx
 import { setupArchieRouteListener } from "@archie/devtools/client";
 import App, { router } from "./App";
 
-// Initialize route synchronization
 setupArchieRouteListener(router);
-
 createRoot(document.getElementById("root")!).render(<App />);
 ```
 
-### 3. Export Router from App
+### 4. Export router from App
 
 ```typescript
 // src/App.tsx
@@ -81,6 +105,41 @@ interface ArchieRouteUpdateMessage {
 }
 ```
 
+## Host (editor) integration
+
+If your editor receives postMessage from the inspector iframe:
+
+1. **Validate origin with an allowlist (recommended)**  
+   In the **host**, allow the iframe’s origins (localhost for dev + your app URLs in production) so it works everywhere.
+   **Archie host origins:** `https://app.dev.archie-platform.com`, `https://app.staging.archie-platform.com`, `https://app.archie.com`. For local testing use `getAllowedOrigins(true)` (adds localhost). Example:
+   ```js
+   import { getAllowedOrigins } from "@archie/devtools/constants";
+   const ALLOWED_ORIGINS = getAllowedOrigins(true); // true = include localhost for local dev
+   window.addEventListener("message", (e) => {
+     if (!ALLOWED_ORIGINS.includes(e.origin)) return;
+     // handle e.data
+   });
+   ```
+2. **Inspector origins (iframe):** Only configured domains are allowed; **`"*"` is never used.** If you use `injectInspector()` (recommended), it sets Archie host origins + localhost in dev by default. You can override with `allowedOrigins` and `targetOrigin` (or set `window.__ARCHIE_INSPECTOR_ALLOWED_ORIGINS__` / `__ARCHIE_INSPECTOR_TARGET_ORIGIN__` before the script runs).
+
+4. **Globals (backward compatible)**  
+   The inspector still sets `window._inspectorDebug`, `window._inspectorSelectedElement`, `window._inspectorMessageHandler`, and `window._inspectorQuerySelectorProtected`.  
+   Prefer the namespace: `window.__ARCHIE_INSPECTOR__` with `debug`, `selectedElement`, `messageHandler` (same values, no DOM pollution on the namespace object).
+
+5. **Message types** (from iframe to parent)  
+   `INSPECTOR_SCRIPT_LOADED`, `ELEMENT_SELECTED`, `STOP_INSPECTION`, `INSPECTION_CANCELLED`, `ELEMENT_POSITION_UPDATE`, `STYLE_CHANGE_APPLIED` / `STYLE_CHANGE_FAILED`, `TEXT_CHANGE_APPLIED` / `TEXT_CHANGE_FAILED`, `ELEMENT_REMOVED` / `ELEMENT_REMOVAL_FAILED`.  
+   Payload shapes are unchanged; only the postMessage `targetOrigin` is configurable.
+
+To **activate the inspector from the parent** (the site that contains the iframe): you don't call `runInspector()` from the parent. The app inside the iframe already loads the inspector; from the parent send `iframe.contentWindow.postMessage({ type: "START_INSPECTION" }, iframeOrigin)` to start inspection. See [docs/HOST_INTEGRATION.md](docs/HOST_INTEGRATION.md) for full flow, local testing, and all commands.
+
+## Linking locally
+
+```bash
+# In the app repo
+pnpm add file:../archie-devtools
+# After changing the lib: run `pnpm run build` in archie-devtools
+```
+
 ## Requirements
 
 - React 18+

package/dist/chunk-6MYORGLK.mjs

@@ -0,0 +1,21 @@
+// src/constants/archieOrigins.ts
+var ARCHIE_HOST_ORIGINS = [
+  "https://app.dev.archie-platform.com",
+  "https://app.staging.archie-platform.com",
+  "https://app.archie.com"
+];
+var LOCAL_DEV_ORIGINS = [
+  "http://localhost:3000",
+  "http://localhost:3001"
+];
+function getAllowedOrigins(includeLocal = false) {
+  const list = [...ARCHIE_HOST_ORIGINS];
+  if (includeLocal) list.push(...LOCAL_DEV_ORIGINS);
+  return list;
+}
+
+export {
+  ARCHIE_HOST_ORIGINS,
+  LOCAL_DEV_ORIGINS,
+  getAllowedOrigins
+};

package/dist/{client.mjs → chunk-EQV632XF.mjs}

@@ -1,17 +1,4 @@
-// src/client.ts
-function setupArchieRouteListener(router) {
-  const target = window.parent !== window ? window.parent : window.opener;
-  if (!target) {
-    return () => {
-    };
-  }
-  broadcastRouteState(target, router.state, extractAllRoutes(router.routes));
-  const unsubscribe = router.subscribe((state) => {
-    const currentRoutes = extractAllRoutes(router.routes);
-    broadcastRouteState(target, state, currentRoutes);
-  });
-  return unsubscribe;
-}
+// src/client/route-listener/routeListener.ts
 function extractAllRoutes(routes, parentPath = "") {
   const result = [];
   for (const route of routes) {
@@ -50,6 +37,30 @@ function broadcastRouteState(target, state, allRoutes) {
   } catch {
   }
 }
+function setupArchieRouteListener(router) {
+  const target = window.parent !== window ? window.parent : window.opener;
+  if (!target) {
+    return () => {
+    };
+  }
+  broadcastRouteState(target, router.state, extractAllRoutes(router.routes));
+  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);
+    }
+  };
+  window.addEventListener("message", handleMessage);
+  return () => {
+    unsubscribe();
+    window.removeEventListener("message", handleMessage);
+  };
+}
+
 export {
   setupArchieRouteListener
 };

package/dist/chunk-NYVHR4QL.mjs

@@ -0,0 +1,74 @@
+import {
+  getAllowedOrigins
+} from "./chunk-6MYORGLK.mjs";
+
+// src/client/inject-inspector/injectInspector.ts
+var DEFAULT_SCRIPT_ID = "archie-inspector-script";
+function isLocalDev(referrer) {
+  if (!referrer) return true;
+  try {
+    const u = new URL(referrer);
+    return u.hostname === "localhost" || u.hostname === "127.0.0.1";
+  } catch {
+    return true;
+  }
+}
+function injectInspector(opts = {}) {
+  if (typeof document === "undefined") return null;
+  const id = opts.id ?? DEFAULT_SCRIPT_ID;
+  const existing = document.getElementById(id);
+  if (existing) return Promise.resolve(existing);
+  const win = typeof window !== "undefined" ? window : null;
+  if (win) {
+    const referrer = typeof document.referrer === "string" ? document.referrer : "";
+    const dev = opts.dev ?? isLocalDev(referrer);
+    let allowed;
+    if (opts.allowedOrigins !== void 0 && opts.allowedOrigins !== "*") {
+      const v = opts.allowedOrigins;
+      allowed = typeof v === "string" ? [v] : Array.isArray(v) ? v : [];
+    } else {
+      allowed = getAllowedOrigins(dev);
+    }
+    if (allowed.length > 0) {
+      win["__ARCHIE_INSPECTOR_ALLOWED_ORIGINS__"] = allowed;
+    }
+    let target;
+    if (opts.targetOrigin !== void 0 && opts.targetOrigin !== "*") {
+      target = opts.targetOrigin || void 0;
+    } else if (referrer) {
+      try {
+        target = new URL(referrer).origin;
+      } catch {
+        target = void 0;
+      }
+    } else {
+      target = void 0;
+    }
+    if (target) {
+      win["__ARCHIE_INSPECTOR_TARGET_ORIGIN__"] = target;
+    }
+  }
+  return import("./inspector-LTHUYUGW.mjs").then((m) => {
+    try {
+      m.default();
+    } catch (err) {
+      if (typeof console !== "undefined" && console.error) {
+        console.error("[Archie DevTools] Inspector failed to run:", err);
+      }
+      throw err;
+    }
+    const script = document.createElement("script");
+    script.id = id;
+    document.head.appendChild(script);
+    return script;
+  }).catch((err) => {
+    if (typeof console !== "undefined" && console.error) {
+      console.error("[Archie DevTools] Failed to load inspector:", err);
+    }
+    throw err;
+  });
+}
+
+export {
+  injectInspector
+};

package/dist/client/client.d.mts

@@ -0,0 +1,2 @@
+export { ArchieRouteUpdateMessage, RouteInfo, setupArchieRouteListener } from './route-listener/routeListener.mjs';
+import '@remix-run/router';

package/dist/client/client.d.ts

@@ -0,0 +1,2 @@
+export { ArchieRouteUpdateMessage, RouteInfo, setupArchieRouteListener } from './route-listener/routeListener.js';
+import '@remix-run/router';

package/dist/{client.js → client/client.js}

@@ -17,25 +17,14 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/client.ts
+// src/client/client.ts
 var client_exports = {};
 __export(client_exports, {
   setupArchieRouteListener: () => setupArchieRouteListener
 });
 module.exports = __toCommonJS(client_exports);
-function setupArchieRouteListener(router) {
-  const target = window.parent !== window ? window.parent : window.opener;
-  if (!target) {
-    return () => {
-    };
-  }
-  broadcastRouteState(target, router.state, extractAllRoutes(router.routes));
-  const unsubscribe = router.subscribe((state) => {
-    const currentRoutes = extractAllRoutes(router.routes);
-    broadcastRouteState(target, state, currentRoutes);
-  });
-  return unsubscribe;
-}
+
+// src/client/route-listener/routeListener.ts
 function extractAllRoutes(routes, parentPath = "") {
   const result = [];
   for (const route of routes) {
@@ -74,6 +63,29 @@ function broadcastRouteState(target, state, allRoutes) {
   } catch {
   }
 }
+function setupArchieRouteListener(router) {
+  const target = window.parent !== window ? window.parent : window.opener;
+  if (!target) {
+    return () => {
+    };
+  }
+  broadcastRouteState(target, router.state, extractAllRoutes(router.routes));
+  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);
+    }
+  };
+  window.addEventListener("message", handleMessage);
+  return () => {
+    unsubscribe();
+    window.removeEventListener("message", handleMessage);
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   setupArchieRouteListener

package/dist/client/client.mjs

@@ -0,0 +1,6 @@
+import {
+  setupArchieRouteListener
+} from "../chunk-EQV632XF.mjs";
+export {
+  setupArchieRouteListener
+};

package/dist/client/inject-inspector/auto.d.mts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/client/inject-inspector/auto.d.ts

@@ -0,0 +1,2 @@
+
+export {  }