@archie/devtools 0.0.1

package/README.md

@@ -0,0 +1,92 @@
+# @archie/devtools
+
+DevTools for Archie generated applications. Provides seamless communication between the generated app and the Archie editor.
+
+## Installation
+
+```bash
+npm install @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.
+
+## Usage
+
+### 1. Configure Vite Plugin (Optional)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { archieDevTools } from "@archie/devtools";
+
+export default defineConfig({
+  plugins: [archieDevTools()],
+});
+```
+
+### 2. Initialize Route Listener (Required)
+
+```typescript
+// 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
+
+```typescript
+// src/App.tsx
+import { createBrowserRouter, RouterProvider } from "react-router-dom";
+
+export const router = createBrowserRouter([
+  // ... your routes
+]);
+
+export default function App() {
+  return <RouterProvider router={router} />;
+}
+```
+
+## 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;
+  };
+}
+```
+
+## Requirements
+
+- React 18+
+- React Router DOM 6.4+ (Data Router API)
+- Vite 5+ (for plugin)
+
+## License
+
+MIT

package/dist/client.d.mts

@@ -0,0 +1,49 @@
+import { Router } from '@remix-run/router';
+
+/**
+ * Archie Route Listener Setup
+ *
+ * Subscribes to the React Router instance to detect route changes
+ * and broadcast them to the host editor (iframe parent or popup opener).
+ *
+ * @param router - The React Router instance (from createBrowserRouter)
+ * @returns Unsubscribe function to stop listening
+ *
+ * @example
+ * ```typescript
+ * import { setupArchieRouteListener } from '@archie/devtools/client';
+ * import { router } from './App';
+ *
+ * const unsubscribe = setupArchieRouteListener(router);
+ * // Later: unsubscribe();
+ * ```
+ */
+declare function setupArchieRouteListener(router: Router): () => void;
+/**
+ * Route information for the sitemap
+ */
+interface RouteInfo {
+    id: string | undefined;
+    path: string;
+    hasChildren: boolean;
+}
+/**
+ * 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>;
+        }>;
+        allRoutes: RouteInfo[];
+        timestamp: number;
+    };
+}
+
+export { type ArchieRouteUpdateMessage, type RouteInfo, setupArchieRouteListener };

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import { Router } from '@remix-run/router';
+
+/**
+ * Archie Route Listener Setup
+ *
+ * Subscribes to the React Router instance to detect route changes
+ * and broadcast them to the host editor (iframe parent or popup opener).
+ *
+ * @param router - The React Router instance (from createBrowserRouter)
+ * @returns Unsubscribe function to stop listening
+ *
+ * @example
+ * ```typescript
+ * import { setupArchieRouteListener } from '@archie/devtools/client';
+ * import { router } from './App';
+ *
+ * const unsubscribe = setupArchieRouteListener(router);
+ * // Later: unsubscribe();
+ * ```
+ */
+declare function setupArchieRouteListener(router: Router): () => void;
+/**
+ * Route information for the sitemap
+ */
+interface RouteInfo {
+    id: string | undefined;
+    path: string;
+    hasChildren: boolean;
+}
+/**
+ * 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>;
+        }>;
+        allRoutes: RouteInfo[];
+        timestamp: number;
+    };
+}
+
+export { type ArchieRouteUpdateMessage, type RouteInfo, setupArchieRouteListener };

package/dist/client.js

@@ -0,0 +1,80 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/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 () => {
+    };
+  }
+  const allRoutes = extractAllRoutes(router.routes);
+  broadcastRouteState(target, router.state, allRoutes);
+  const unsubscribe = router.subscribe((state) => {
+    broadcastRouteState(target, state, allRoutes);
+  });
+  return unsubscribe;
+}
+function extractAllRoutes(routes, parentPath = "") {
+  const result = [];
+  for (const route of routes) {
+    const path = route.path ? (parentPath + "/" + route.path).replace(/\/+/g, "/") : parentPath || "/";
+    if (route.path !== void 0 || route.index) {
+      result.push({
+        id: route.id,
+        path: route.index ? parentPath || "/" : path,
+        hasChildren: !!(route.children && route.children.length > 0)
+      });
+    }
+    if (route.children) {
+      result.push(...extractAllRoutes(route.children, path));
+    }
+  }
+  return result;
+}
+function broadcastRouteState(target, state, allRoutes) {
+  try {
+    const message = {
+      type: "ARCHIE_ROUTE_UPDATE",
+      payload: {
+        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,
+        timestamp: Date.now()
+      }
+    };
+    target.postMessage(message, "*");
+  } catch {
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  setupArchieRouteListener
+});

package/dist/client.mjs

@@ -0,0 +1,55 @@
+// src/client.ts
+function setupArchieRouteListener(router) {
+  const target = window.parent !== window ? window.parent : window.opener;
+  if (!target) {
+    return () => {
+    };
+  }
+  const allRoutes = extractAllRoutes(router.routes);
+  broadcastRouteState(target, router.state, allRoutes);
+  const unsubscribe = router.subscribe((state) => {
+    broadcastRouteState(target, state, allRoutes);
+  });
+  return unsubscribe;
+}
+function extractAllRoutes(routes, parentPath = "") {
+  const result = [];
+  for (const route of routes) {
+    const path = route.path ? (parentPath + "/" + route.path).replace(/\/+/g, "/") : parentPath || "/";
+    if (route.path !== void 0 || route.index) {
+      result.push({
+        id: route.id,
+        path: route.index ? parentPath || "/" : path,
+        hasChildren: !!(route.children && route.children.length > 0)
+      });
+    }
+    if (route.children) {
+      result.push(...extractAllRoutes(route.children, path));
+    }
+  }
+  return result;
+}
+function broadcastRouteState(target, state, allRoutes) {
+  try {
+    const message = {
+      type: "ARCHIE_ROUTE_UPDATE",
+      payload: {
+        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,
+        timestamp: Date.now()
+      }
+    };
+    target.postMessage(message, "*");
+  } catch {
+  }
+}
+export {
+  setupArchieRouteListener
+};

package/dist/index.d.mts

@@ -0,0 +1,31 @@
+import { Plugin } from 'vite';
+
+interface ArchieDevToolsOptions {
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Archie DevTools Vite Plugin
+ *
+ * Provides build-time integration for Archie generated applications.
+ * Currently serves as an extensibility point for future features:
+ * - Component tagging (click-to-edit)
+ * - HMR overrides
+ * - Virtual file injection
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { archieDevTools } from '@archie/devtools';
+ *
+ * export default defineConfig({
+ *   plugins: [archieDevTools()]
+ * })
+ * ```
+ */
+declare function archieDevTools(options?: ArchieDevToolsOptions): Plugin;
+
+export { type ArchieDevToolsOptions, archieDevTools };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { Plugin } from 'vite';
+
+interface ArchieDevToolsOptions {
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Archie DevTools Vite Plugin
+ *
+ * Provides build-time integration for Archie generated applications.
+ * Currently serves as an extensibility point for future features:
+ * - Component tagging (click-to-edit)
+ * - HMR overrides
+ * - Virtual file injection
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { archieDevTools } from '@archie/devtools';
+ *
+ * export default defineConfig({
+ *   plugins: [archieDevTools()]
+ * })
+ * ```
+ */
+declare function archieDevTools(options?: ArchieDevToolsOptions): Plugin;
+
+export { type ArchieDevToolsOptions, archieDevTools };

package/dist/index.js

@@ -0,0 +1,47 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  archieDevTools: () => archieDevTools
+});
+module.exports = __toCommonJS(index_exports);
+function archieDevTools(options = {}) {
+  const { debug = false } = options;
+  const log = (...args) => {
+    if (debug) {
+      console.log("[Archie DevTools]", ...args);
+    }
+  };
+  return {
+    name: "vite-plugin-archie-devtools",
+    enforce: "pre",
+    configResolved(config) {
+      log("Plugin initialized for project:", config.root);
+    },
+    configureServer() {
+      log("Dev server configured");
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  archieDevTools
+});

package/dist/index.mjs

@@ -0,0 +1,22 @@
+// src/index.ts
+function archieDevTools(options = {}) {
+  const { debug = false } = options;
+  const log = (...args) => {
+    if (debug) {
+      console.log("[Archie DevTools]", ...args);
+    }
+  };
+  return {
+    name: "vite-plugin-archie-devtools",
+    enforce: "pre",
+    configResolved(config) {
+      log("Plugin initialized for project:", config.root);
+    },
+    configureServer() {
+      log("Dev server configured");
+    }
+  };
+}
+export {
+  archieDevTools
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@archie/devtools",
+  "version": "0.0.1",
+  "description": "DevTools for Archie generated applications - Route synchronization and editor communication",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/client.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/client.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "release": "node publish.js"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "keywords": [
+    "vite",
+    "plugin",
+    "archie",
+    "devtools",
+    "react-router"
+  ],
+  "author": "8base",
+  "license": "MIT",
+  "devDependencies": {
+    "@remix-run/router": "^1.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "react-router-dom": ">=6.4.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  }
+}