@accelerated-agency/visual-editor 0.1.1

package/README.md

@@ -0,0 +1,264 @@
+# @conversion/visual-editor
+
+Reusable visual editor package for embedding Conversion's editing UI inside a host React app.
+
+## Exports
+
+This package exports:
+
+- `PlatformVisualEditor` (recommended host wrapper)
+- `EditorShell` (low-level editor shell UI)
+- `ToastProvider`, `useToast`
+- `visualEditorProxyPlugin` (Vite dev-server plugin for `/api/proxy` and optional AI API route)
+- Types: `PlatformVisualEditorProps`, `VisualEditorExperiment`, `VisualEditorVariation`, `VisualEditorTab`, plus mutation/message types
+
+## Install
+
+```bash
+yarn add @conversion/visual-editor
+```
+
+## Local development (package + consumer app)
+
+Use this setup so changes in this package reflect in your consumer app immediately.
+
+### 1) Consumer app dependency
+
+In consumer app `package.json`:
+
+```json
+"@conversion/visual-editor": "file:../conversion-visual-editor"
+```
+
+Run:
+
+```bash
+yarn install
+```
+
+### 2) Run package in watch mode
+
+In `conversion-visual-editor` terminal:
+
+```bash
+npm run watch
+```
+
+### 3) Consumer app Vite config (local-dev only)
+
+```ts
+import { defineConfig } from "vite";
+import path from "path";
+
+export default defineConfig({
+  resolve: {
+    preserveSymlinks: true, // local-dev only
+  },
+  optimizeDeps: {
+    exclude: ["@conversion/visual-editor"], // local-dev only
+  },
+  server: {
+    fs: {
+      allow: [path.resolve(__dirname, "..")], // local-dev only
+    },
+    watch: {
+      ignored: ["!**/node_modules/@conversion/visual-editor/**"], // local-dev only
+    },
+  },
+});
+```
+
+Start consumer app:
+
+```bash
+yarn dev --force
+```
+
+If one update is stale, clear cache once:
+
+```bash
+rm -rf node_modules/.vite
+```
+
+### Remove these before/after npm publish
+
+When you move from local `file:` development to npm package usage, remove/revert in consumer app:
+
+- `file:../conversion-visual-editor` dependency (replace with npm version)
+- `resolve.preserveSymlinks: true`
+- `optimizeDeps.exclude: ["@conversion/visual-editor"]` (if no longer needed)
+- `server.fs.allow` override used for local package path
+- `server.watch.ignored` override for package path
+
+## Required host setup
+
+`PlatformVisualEditor` is designed to run in embedded mode and expects a proxied page-loading flow.
+
+### 1) Add the Vite plugin (recommended)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { visualEditorProxyPlugin } from "@conversion/visual-editor";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    visualEditorProxyPlugin({
+      // optional, only needed for AI test generation endpoint
+      anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+      // optional, defaults to true
+      enableGenerateTestApi: true,
+    }),
+  ],
+});
+```
+
+What this plugin provides:
+
+- `GET/POST /api/proxy` for loading target storefront pages through your app origin
+- HTML rewriting for proxied pages (asset/action rewriting, popup suppression, bridge script injection)
+- `POST /api/generate-test` endpoint (optional; used by AI panel)
+
+### 2) Ensure `/bridge.js` is served by your app
+
+The proxy injects:
+
+```html
+<script src="/bridge.js"></script>
+```
+
+Your host app must serve this file at `/bridge.js` for iframe/editor communication to work correctly.
+
+### 3) Mount `PlatformVisualEditor` in your route/page
+
+```tsx
+import { PlatformVisualEditor } from "@conversion/visual-editor";
+
+export function VisualEditorPage() {
+  return (
+    <PlatformVisualEditor
+      experiment={{
+        experimentId: "exp_1",
+        name: "Homepage Hero Test",
+        status: "draft",
+        pageUrl: "https://store.example.com",
+        editorPassword: "",
+        variations: [
+          {
+            _id: "control",
+            iid: 0,
+            name: "Control",
+            baseline: true,
+            traffic_allocation: 50,
+            changesets: "[]",
+            csscode: "",
+            jscode: "",
+          },
+        ],
+      }}
+      onRequestSave={async ({ experimentId, variations, hash }) => {
+        // Save to your backend
+        // hash is set for save-and-navigate requests (for example "#code-editor")
+      }}
+      onNavigateRequested={(hash) => {
+        // Move to host tab/route after successful save-and-navigate
+      }}
+      onEditorUrlChanged={async ({ url, password }) => {
+        // Optional: persist latest URL/password selection
+      }}
+      onClose={() => {
+        // Close editor page/modal
+      }}
+    />
+  );
+}
+```
+
+## Environment variables
+
+### Required
+
+- None for core visual-editor functionality.
+
+### Optional
+
+- `ANTHROPIC_API_KEY`: required only if you use AI test generation (`/api/generate-test`).
+  - If missing and AI route is enabled, AI generation requests will fail with a server error.
+  - You can disable the route with `visualEditorProxyPlugin({ enableGenerateTestApi: false })`.
+
+## Data contracts
+
+### `VisualEditorExperiment`
+
+- `experimentId?: string`
+- `name?: string`
+- `status?: string`
+- `pageUrl?: string`
+- `editorPassword?: string`
+- `variations?: VisualEditorVariation[]`
+
+### `VisualEditorVariation`
+
+- `_id: string`
+- `iid?: number`
+- `name: string`
+- `baseline?: boolean`
+- `traffic_allocation?: number`
+- `csscode?: string`
+- `jscode?: string`
+- `changesets?: string` (JSON string)
+
+## Save and navigation flow
+
+When users click save/finalize in the editor:
+
+1. Editor emits `save-experiment` or `save-and-navigate`
+2. `PlatformVisualEditor` calls your `onRequestSave(payload)`
+3. On success:
+   - dirty state resets
+   - `onSaveSuccess` is called
+   - for `save-and-navigate`, `onNavigateRequested(hash)` is called
+4. On failure:
+   - `onSaveError(error)` is called
+
+## Main props reference (`PlatformVisualEditor`)
+
+- `channel?: string` postMessage channel name, default `conversion-platform`
+- `embeddedGlobalKey?: string` global embedded marker, default `__CONVERSION_EMBEDDED__`
+- `className?: string` outer wrapper classes
+- `editorClassName?: string` editor content wrapper classes
+- `showHeader?: boolean` show default header
+- `title?: string` header title override
+- `status?: string` header status badge
+- `tabs?: VisualEditorTab[]` tabs to render in default header
+- `activeTab?: string` active tab label in default header
+- `loading?: boolean` loading state
+- `error?: string | null` error state
+- `showCloseButton?: boolean` toggle default close button
+- `closeLabel?: string` close button text
+- `loadingText?: string` loading text
+- `saveDebounceSkips?: number` mutation-change events to ignore before setting dirty
+- `experiment?: VisualEditorExperiment` input experiment payload
+- `onClose?: () => void` close handler
+- `onTabChange?: (tab: VisualEditorTab) => void` tab click handler
+- `onDirtyChange?: (dirty: boolean) => void` dirty-state callback
+- `onEditorReady?: () => void` called after editor bootstraps
+- `onSaveSuccess?: (payload) => void` called after successful save
+- `onSaveError?: (error: unknown) => void` called on save failure
+- `onRequestSave?: (payload) => Promise<void> | void` required to persist changes
+- `onEditorUrlChanged?: (payload) => Promise<void> | void` URL/password change callback
+- `onNavigateRequested?: (hash: string) => void` post-save navigation callback
+- `onRestoreVersion?: (payload) => void` restore callback
+- `onDiscardDirty?: () => boolean | Promise<boolean>` custom unsaved-changes guard
+- `renderHeader?: (...) => ReactNode` custom header renderer
+- `renderLoading?: () => ReactNode` custom loading renderer
+- `renderError?: (message) => ReactNode` custom error renderer
+
+## Known integration notes
+
+- Keep the editor component mounted while async save is running.
+- The editor loads target pages via `/api/proxy`; cross-origin requests made by the target page may still need proxying/server-side handling.
+- If you customize `channel`, keep the same value on both host and editor surfaces.
+

package/dist/bridge-channel-ISTPKGMY.js

@@ -0,0 +1,10 @@
+import {
+  capturePageSnapshot,
+  sendToBridge,
+  setIframeRef
+} from "./chunk-WCSTG2IY.js";
+export {
+  capturePageSnapshot,
+  sendToBridge,
+  setIframeRef
+};

package/dist/chunk-WCSTG2IY.js

@@ -0,0 +1,41 @@
+// src/lib/bridge-channel.ts
+var CHANNEL = "conversion-editor";
+var iframeRef = null;
+function setIframeRef(el) {
+  iframeRef = el;
+}
+function sendToBridge(message) {
+  if (!iframeRef?.contentWindow) return;
+  iframeRef.contentWindow.postMessage(
+    { channel: CHANNEL, payload: message },
+    "*"
+  );
+}
+function capturePageSnapshot(timeoutMs = 5e3) {
+  return new Promise((resolve, reject) => {
+    if (!iframeRef?.contentWindow) {
+      reject(new Error("Bridge iframe not available"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      window.removeEventListener("message", handler);
+      reject(new Error("Snapshot capture timed out"));
+    }, timeoutMs);
+    function handler(e) {
+      const msg = e.data;
+      if (!msg || msg.channel !== CHANNEL) return;
+      if (msg.payload?.type !== "snapshotCaptured") return;
+      clearTimeout(timer);
+      window.removeEventListener("message", handler);
+      resolve(msg.payload.snapshot);
+    }
+    window.addEventListener("message", handler);
+    sendToBridge({ type: "captureSnapshot" });
+  });
+}
+
+export {
+  setIframeRef,
+  sendToBridge,
+  capturePageSnapshot
+};