@archie/devtools 0.0.10 → 0.0.11

package/README.md

@@ -1,82 +1,54 @@
 # @archie/devtools
 
-DevTools for Archie generated applications. Route sync with the editor and optional element inspector script.
+Devtools runtime for Archie-generated applications.
 
-## Installation
+## Public API
 
-```bash
-npm install @archie/devtools
-# or
-pnpm add @archie/devtools
-```
+This package exposes only two supported entrypoints:
 
-## Features
+- `@archie/devtools` -> `archieDevTools`
+- `@archie/devtools/client` -> `ArchieDevToolProvider`, `ArchieDevToolProviderProps`
 
-- **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.
+Everything else is internal implementation detail.
 
 ## Usage
 
-### 1. Configure Vite Plugin (Optional)
+### 1. Configure the Vite plugin
 
-```typescript
-// vite.config.ts
-import { defineConfig } from "vite";
-import { archieDevTools } from "@archie/devtools";
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { archieDevTools } from '@archie/devtools';
 
 export default defineConfig({
-  plugins: [archieDevTools()],
+  plugins: [react(), archieDevTools()],
 });
 ```
 
-### 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
-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";
-
-setupArchieRouteListener(router);
-createRoot(document.getElementById("root")!).render(<App />);
+### 2. Bootstrap the app runtime
+
+```tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ArchieDevToolProvider } from '@archie/devtools/client';
+import App, { router } from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <ArchieDevToolProvider router={router}>
+      <App />
+    </ArchieDevToolProvider>
+  </StrictMode>,
+);
 ```
 
-### 4. Export router from App
+### 3. Export the router
 
-```typescript
-// src/App.tsx
-import { createBrowserRouter, RouterProvider } from "react-router-dom";
+```tsx
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
 
 export const router = createBrowserRouter([
-  // ... your routes
+  // routes
 ]);
 
 export default function App() {
@@ -84,68 +56,38 @@ export default function App() {
 }
 ```
 
-## Message Format
-
-The route listener broadcasts messages to the parent window with this structure:
-
-```typescript
-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>;
-    }>;
-    timestamp: number;
-  };
-}
-```
-
-## Host (editor) integration
+## Responsibilities
 
-If your editor receives postMessage from the inspector iframe:
+- `archieDevTools()` handles compile-time editor metadata and internal DnD scope injection.
+- `ArchieDevToolProvider` handles runtime bootstrap: DnD provider, route sync, sanitizer install, and inspector initialization.
 
-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).
+## Requirements
 
-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).
+- React 18+
+- React Router DOM 6.4+
+- Vite 5+
 
-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.
+## Local linking
 
-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.
+```bash
+pnpm add file:../archie-devtools
+```
 
-## Linking locally
+After changing the library:
 
 ```bash
-# In the app repo
-pnpm add file:../archie-devtools
-# After changing the lib: run `pnpm run build` in archie-devtools
+pnpm build
 ```
 
-## Requirements
+## Development
 
-- React 18+
-- React Router DOM 6.4+ (Data Router API)
-- Vite 5+ (for plugin)
+```bash
+pnpm test
+pnpm typecheck
+```
 
-## License
+Tests follow a colocated-by-feature convention:
 
-MIT
+- small modules keep `*.test.ts(x)` beside the source file
+- larger subsystems may use a local `__tests__/` folder next to the feature
+- `src/client/dnd/design-mode/__tests__/` is the reference pattern for multi-file feature coverage

package/dist/chunk-QZ7TP4HQ.mjs

@@ -0,0 +1,7 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+export {
+  __publicField
+};

package/dist/client/client.d.mts

@@ -1,2 +1,41 @@
-export { ArchieRouteUpdateMessage, RouteInfo, setupArchieRouteListener } from './route-listener/routeListener.mjs';
-import '@remix-run/router';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface ArchieRouteObjectLike {
+    id?: string;
+    path?: string;
+    index?: boolean;
+    children?: readonly ArchieRouteObjectLike[];
+}
+interface ArchieRouteMatchLike {
+    route: {
+        id?: string;
+    };
+    pathname: string;
+    params: Record<string, string | undefined>;
+}
+interface ArchieRouterStateLike {
+    location: {
+        pathname: string;
+        search: string;
+        hash: string;
+    };
+    matches: readonly ArchieRouteMatchLike[];
+}
+interface ArchieRouterLike {
+    routes: readonly ArchieRouteObjectLike[];
+    state: ArchieRouterStateLike;
+    subscribe(listener: (state: ArchieRouterStateLike) => void): () => void;
+}
+
+interface ArchieDevToolsRuntimeOptions {
+    router: ArchieRouterLike;
+    inspector?: boolean;
+}
+
+interface ArchieDevToolProviderProps extends ArchieDevToolsRuntimeOptions {
+    children: ReactNode;
+}
+declare function ArchieDevToolProvider({ children, router, inspector, }: ArchieDevToolProviderProps): react_jsx_runtime.JSX.Element;
+
+export { ArchieDevToolProvider, type ArchieDevToolProviderProps };

package/dist/client/client.d.ts

@@ -1,2 +1,41 @@
-export { ArchieRouteUpdateMessage, RouteInfo, setupArchieRouteListener } from './route-listener/routeListener.js';
-import '@remix-run/router';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface ArchieRouteObjectLike {
+    id?: string;
+    path?: string;
+    index?: boolean;
+    children?: readonly ArchieRouteObjectLike[];
+}
+interface ArchieRouteMatchLike {
+    route: {
+        id?: string;
+    };
+    pathname: string;
+    params: Record<string, string | undefined>;
+}
+interface ArchieRouterStateLike {
+    location: {
+        pathname: string;
+        search: string;
+        hash: string;
+    };
+    matches: readonly ArchieRouteMatchLike[];
+}
+interface ArchieRouterLike {
+    routes: readonly ArchieRouteObjectLike[];
+    state: ArchieRouterStateLike;
+    subscribe(listener: (state: ArchieRouterStateLike) => void): () => void;
+}
+
+interface ArchieDevToolsRuntimeOptions {
+    router: ArchieRouterLike;
+    inspector?: boolean;
+}
+
+interface ArchieDevToolProviderProps extends ArchieDevToolsRuntimeOptions {
+    children: ReactNode;
+}
+declare function ArchieDevToolProvider({ children, router, inspector, }: ArchieDevToolProviderProps): react_jsx_runtime.JSX.Element;
+
+export { ArchieDevToolProvider, type ArchieDevToolProviderProps };