@supernovaio/prototyping-tooling 0.9.0

package/README.md

@@ -0,0 +1,193 @@
+# @supernovaio/prototyping-tooling
+
+Communication bridge for iframe-based design-to-code prototyping workflows. Enables a **host** (parent window) to control and interact with a **client** (child iframe) for element selection, design-mode editing, annotations, and live source-code updates.
+
+## Installation
+
+```bash
+npm install @supernovaio/prototyping-tooling
+```
+
+## Entry Points
+
+| Import path | Side | Description |
+|---|---|---|
+| `@supernovaio/prototyping-tooling/host` | Parent | `ForgeHost` — connects to the iframe, sends commands, receives events |
+| `@supernovaio/prototyping-tooling/client` | Child | `ForgeClient` — auto-initializes, handles messages, manages overlays |
+| `@supernovaio/prototyping-tooling/react` | Parent | React hooks: `useElementSelector`, `useDesignMode` |
+| `@supernovaio/prototyping-tooling/build` | Build | Vite plugin that injects `data-forge-id` attributes into JSX |
+| `@supernovaio/prototyping-tooling` | Either | Shared types, debug utilities, message constants |
+
+## Quick Start
+
+### Parent (host) app
+
+```typescript
+import { ForgeHost } from '@supernovaio/prototyping-tooling/host'
+
+const iframe = document.querySelector('iframe')!
+const host = new ForgeHost(iframe)
+
+await host.connect()
+
+host.on('element-selected', (selection) => {
+  console.log('Selected:', selection.componentName, selection.forgeId)
+})
+
+host.enableDesignMode(true)
+```
+
+### Child (client) app
+
+```typescript
+// Importing the client auto-initializes it
+import '@supernovaio/prototyping-tooling/client'
+```
+
+### Vite plugin (child build)
+
+```typescript
+// vite.config.ts
+import { supernovaDesignPlugin } from '@supernovaio/prototyping-tooling/build'
+
+export default defineConfig({
+  plugins: [react(), supernovaDesignPlugin()],
+})
+```
+
+## API Reference
+
+### `ForgeHost` (host)
+
+| Method | Description |
+|---|---|
+| `connect()` | Connects to the child iframe. Resolves on `CHILD_READY`. |
+| `enableSelectMode(enabled)` | Toggles XPath element-picking mode |
+| `enableDesignMode(enabled)` | Toggles design mode (click to select, edit props) |
+| `enableAnnotationMode(enabled)` | Toggles annotation mode (click/drag to annotate) |
+| `updateElementText(forgeId, text)` | Updates text content of a forge element |
+| `updateProperty(forgeId, prop, value)` | Updates any property via Babel AST |
+| `deselectElement()` | Clears the design-mode selection |
+| `deleteAnnotation(id)` | Removes an annotation dot |
+| `keepAnnotation(id, order)` | Confirms and numbers an annotation |
+| `updateAnnotationOrders(orders)` | Bulk-updates annotation order numbers |
+| `toggleMarkers()` | Toggles visibility of annotation marker badges |
+| `restoreAnnotations(annotations)` | Re-sends saved annotations to the child to recreate dots after reconnect |
+| `registerComponents(components)` | Sends component definitions to the child |
+| `on(event, handler)` | Subscribes to events; returns unsubscribe fn |
+| `getStatus()` | Returns `'connecting' \| 'connected' \| 'disconnected'` |
+| `disconnect()` | Cleans up listeners and resets state |
+
+#### Events
+
+| Event | Payload |
+|---|---|
+| `connected` | — |
+| `disconnected` | — |
+| `xpath-selected` | `xpath: string` |
+| `select-mode-disabled` | — |
+| `design-mode-disabled` | — |
+| `element-selected` | `ElementSelection` |
+| `annotation-created` | `AnnotationData` |
+| `annotation-dot-clicked` | `annotationId, dotX, dotY` |
+| `source-updated` | `forgeId, source, filePath` |
+
+### `ForgeClient` (client)
+
+Singleton that auto-initializes on import. Access via `ForgeClient.getInstance()`.
+
+Accepts an optional `ForgeClientOptions` with an `onError` callback for error handling.
+
+The client also exposes a public `enableAnnotationMode(enabled)` method for console-driven testing (see [Console Access](#console-access)).
+
+### React Hooks
+
+#### `useElementSelector(host)`
+
+Returns `{ selectMode, connectionStatus, selectedXPath, enableSelectMode, clearXPath }`.
+
+#### `useDesignMode(host)`
+
+Returns `{ designMode, selectedElement, enableDesignMode, updateText, updateProperty, deselectElement }`.
+
+### Annotations
+
+Annotation badges are anchored to their associated elements. When the page scrolls or the window resizes, badges automatically reposition to follow their elements.
+
+**Forge ID generation** is deterministic — IDs are derived from `filePath + line + column`, so the same source position always produces the same ID across rebuilds. Elements rendered inside loops (`.map()`) share the same forge-id; the system disambiguates them using a `forgeIdIndex`.
+
+**Restoring annotations** — the parent can call `host.restoreAnnotations(annotations)` after reconnecting to the child (e.g., after HMR reload) to recreate all annotation dots. The child resolves elements by `data-forge-id` first, falling back to XPath.
+
+### Keyboard Shortcuts
+
+The plugin does **not** handle keyboard events. The consuming parent application is responsible for binding its own shortcuts and calling the appropriate `ForgeHost` methods. Example implementation:
+
+```typescript
+useEffect(() => {
+  const handleKeyDown = (e: KeyboardEvent) => {
+    // Cmd/Ctrl + Shift + F → toggle annotation mode
+    if (e.shiftKey && (e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'f') {
+      e.preventDefault()
+      host.enableAnnotationMode(!annotationMode)
+    }
+    // Escape → close popup
+    if (e.key === 'Escape') {
+      closePopup()
+    }
+    // H → toggle annotation markers (skip when typing)
+    if (e.key.toLowerCase() === 'h' && !e.metaKey && !e.ctrlKey && !e.shiftKey && !e.altKey) {
+      const tag = (e.target as HTMLElement)?.tagName?.toLowerCase()
+      if (tag === 'input' || tag === 'textarea') return
+      host.toggleMarkers()
+    }
+  }
+  window.addEventListener('keydown', handleKeyDown)
+  return () => window.removeEventListener('keydown', handleKeyDown)
+}, [host, annotationMode])
+```
+
+### Console Access
+
+Both `ForgeHost` and `ForgeClient` expose themselves on the `window` for console-driven testing:
+
+```javascript
+// From the parent page's console:
+__forgeHost.enableAnnotationMode(true)   // activate annotation mode
+__forgeHost.enableAnnotationMode(false)  // deactivate
+__forgeHost.toggleMarkers()              // toggle marker visibility
+__forgeHost.restoreAnnotations([...])    // restore saved annotations
+
+// From the child iframe's console (switch iframe context in DevTools):
+__forgeClient.enableAnnotationMode(true)
+__forgeAnnotations.toggleMarkers()
+```
+
+### Debug
+
+```typescript
+import { enableDebug } from '@supernovaio/prototyping-tooling'
+
+enableDebug(true)  // Turns on timestamped console output
+enableDebug(false) // Silences all library logging
+```
+
+## Architecture
+
+```
+src/
+├── shared/          Constants, debug, events, messaging
+├── client/
+│   ├── general/     ForgeClient orchestrator, SourceCodeUpdater, types
+│   ├── annotation/  AnnotationOverlay
+│   ├── select-mode/ SelectModeController
+│   └── design-mode/ DesignModeController
+├── host/            ForgeHost, types
+├── react/           useElementSelector, useDesignMode
+└── build/           Vite plugin (supernovaDesignPlugin)
+```
+
+See [INTEGRATION.md](./INTEGRATION.md) for a detailed integration guide.
+
+## License
+
+MIT

package/dist/build/index.d.ts

@@ -0,0 +1,3 @@
+export { supernovaDesignPlugin } from "./vite-plugin-forge-ids.js";
+export type { ForgeIdPluginOptions } from "./vite-plugin-forge-ids.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAClE,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/build/index.js

@@ -0,0 +1,96 @@
+import { parse as P } from "@babel/parser";
+import y from "@babel/traverse";
+import S from "@babel/generator";
+import { relative as F } from "node:path";
+const E = typeof y == "function" ? y : y.default, M = typeof S == "function" ? S : S.default;
+function T(d) {
+  let r = 0;
+  for (let c = 0; c < d.length; c++) {
+    const s = d.charCodeAt(c);
+    r = (r << 5) - r + s, r = r & r;
+  }
+  return Math.abs(r).toString(36).substring(0, 8);
+}
+function B(d = {}) {
+  const { prefix: r = "forge" } = d, c = (s, i, u) => {
+    const a = T(`${s}:${i}:${u}`);
+    return `${r}-${a}-${i}-${u}`;
+  };
+  return { name: "forge-id-plugin", enforce: "pre", transform(s, i) {
+    if (!i.match(/\.(tsx?|jsx?)$/) || i.includes("node_modules"))
+      return null;
+    const u = F(process.cwd(), i).replace(/\\/g, "/");
+    try {
+      let a = function(e) {
+        const n = e.parent;
+        if (n.type === "VariableDeclarator" && n.id.type === "Identifier" && /^[A-Z]/.test(n.id.name))
+          return !0;
+        if (n.type === "CallExpression") {
+          const l = e.parentPath;
+          if (l) {
+            const f = l.parent;
+            if (f.type === "VariableDeclarator" && f.id.type === "Identifier" && /^[A-Z]/.test(f.id.name) || f.type === "ExportDefaultDeclaration")
+              return !0;
+            if (f.type === "CallExpression") {
+              const p = l.parentPath;
+              if (p) {
+                const t = p.parent;
+                if (t.type === "VariableDeclarator" && t.id.type === "Identifier" && /^[A-Z]/.test(t.id.name))
+                  return !0;
+              }
+            }
+          }
+        }
+        return !1;
+      };
+      const x = P(s, { sourceType: "module", plugins: ["jsx", "typescript"] }), J = /* @__PURE__ */ new Set();
+      let b = !1, o = 0;
+      if (E(x, { FunctionDeclaration: { enter(e) {
+        e.node.id && /^[A-Z]/.test(e.node.id.name) && o++;
+      }, exit(e) {
+        e.node.id && /^[A-Z]/.test(e.node.id.name) && o--;
+      } }, ArrowFunctionExpression: { enter(e) {
+        a(e) && o++;
+      }, exit(e) {
+        a(e) && o--;
+      } }, FunctionExpression: { enter(e) {
+        a(e) && o++;
+      }, exit(e) {
+        a(e) && o--;
+      } }, JSXOpeningElement(e) {
+        if (e.node.name.type === "JSXIdentifier") {
+          const n = e.node.name.name, l = /^[A-Z]/.test(n);
+          if (n === "Fragment" || n === "React.Fragment" || (/* @__PURE__ */ new Set(["path", "circle", "rect", "line", "polyline", "polygon", "ellipse", "g", "defs", "clipPath", "mask", "use", "text", "tspan", "textPath", "image", "pattern", "linearGradient", "radialGradient", "stop", "filter", "feBlend", "feColorMatrix", "feComponentTransfer", "feComposite", "feConvolveMatrix", "feDiffuseLighting", "feDisplacementMap", "feFlood", "feGaussianBlur", "feImage", "feMerge", "feMergeNode", "feMorphology", "feOffset", "feSpecularLighting", "feTile", "feTurbulence", "marker", "symbol", "foreignObject", "desc", "title", "metadata"])).has(n))
+            return;
+          if (l && o > 0) {
+            const t = e.scope.getBinding(n);
+            if (t && t.scope.path.type !== "Program")
+              return;
+          }
+          if (!e.node.attributes.some((t) => t.type === "JSXAttribute" && t.name.type === "JSXIdentifier" && t.name.name === "data-forge-id")) {
+            const t = e.node.loc?.start;
+            if (!t) return;
+            const I = e.parent, m = I.type === "JSXElement" ? I.loc?.end : e.node.loc?.end;
+            if (!m) return;
+            const A = c(i, t.line, t.column), v = { type: "JSXAttribute", name: { type: "JSXIdentifier", name: "data-forge-id" }, value: { type: "StringLiteral", value: A }, loc: e.node.loc }, h = { type: "JSXAttribute", name: { type: "JSXIdentifier", name: "data-component" }, value: { type: "StringLiteral", value: n }, loc: e.node.loc }, C = { type: "JSXAttribute", name: { type: "JSXIdentifier", name: "data-source-pos" }, value: { type: "StringLiteral", value: `${u}:${t.line}:${t.column}:${m.line}:${m.column}` }, loc: e.node.loc }, X = !l && o > 0, $ = e.node.attributes.some((g) => g.type === "JSXSpreadAttribute");
+            if (X && $) {
+              const g = e.node.attributes.findIndex((D) => D.type === "JSXSpreadAttribute");
+              e.node.attributes.splice(g, 0, v, h, C);
+            } else
+              e.node.attributes.push(v, h, C);
+            J.add(A), b = !0;
+          }
+        }
+      } }), b) {
+        const e = M(x, {}, s);
+        return { code: e.code, map: e.map };
+      }
+    } catch {
+      return null;
+    }
+    return null;
+  } };
+}
+export {
+  B as supernovaDesignPlugin
+};

package/dist/build/vite-plugin-forge-ids.d.ts

@@ -0,0 +1,7 @@
+import { Plugin } from "vite";
+export interface ForgeIdPluginOptions {
+    /** Prefix for forge IDs, defaults to 'forge' */
+    prefix?: string;
+}
+export declare function supernovaDesignPlugin(options?: ForgeIdPluginOptions): Plugin;
+//# sourceMappingURL=vite-plugin-forge-ids.d.ts.map

package/dist/build/vite-plugin-forge-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin-forge-ids.d.ts","sourceRoot":"","sources":["../../src/build/vite-plugin-forge-ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAW7B,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAaD,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAuRhF"}

package/dist/client/annotation/AnnotationOverlay.d.ts

@@ -0,0 +1,86 @@
+import type { ParentMessenger } from "../../shared/messaging.js";
+import type { RestoreAnnotationData } from "../../shared/events.js";
+/**
+ * Full-screen overlay for creating and managing annotations.
+ * Supports single-click (one element) and shift+drag (multi-element) selection.
+ */
+export declare class AnnotationOverlay {
+    private active;
+    private messenger;
+    private hoverOverlay;
+    private componentTooltip;
+    private hitTestOverlay;
+    private dragRect;
+    private dragHighlights;
+    private annotationHighlights;
+    private dots;
+    private isDragging;
+    private dragStartX;
+    private dragStartY;
+    private dragScopeParent;
+    private hoverSuppressed;
+    private activeHighlightDotId;
+    constructor(messenger: ParentMessenger);
+    /** Activates annotation mode: creates overlays and starts listening for events. */
+    activate(): void;
+    /** Deactivates annotation mode and cleans up overlays. */
+    deactivate(): void;
+    /** Removes a single annotation dot by ID. */
+    removeDot(annotationId: string): void;
+    /** Removes all annotation dots from the overlay. */
+    removeAllDots(): void;
+    /** Recreates dots from annotation data sent by the host. */
+    restoreDots(annotations: RestoreAnnotationData[]): void;
+    private markersVisible;
+    /** Toggles visibility of all annotation marker badges. */
+    toggleMarkers(): void;
+    /** Explicitly sets marker badge visibility. */
+    setMarkersVisible(visible: boolean): void;
+    /** Repositions all badge dots and visible highlights to follow their anchored elements. */
+    private repositionAll;
+    private createHitTestOverlay;
+    private removeHitTestOverlay;
+    private showHoverOverlay;
+    private removeHoverOverlay;
+    private highlightAnnotationElements;
+    private applySelectedStyle;
+    private applyDefaultStyle;
+    private resolveLocator;
+    private highlightLocators;
+    private clearAnnotationHighlights;
+    /** Computes the bounding rect encompassing all elements referenced by locators. */
+    private getAnchorRect;
+    private getComponentPath;
+    private showComponentTooltip;
+    private removeComponentTooltip;
+    private showDragRect;
+    private removeDragRect;
+    private showDragHighlights;
+    private clearDragHighlights;
+    private createDot;
+    private createDotAtPosition;
+    /** Updates the displayed order numbers on all badges. */
+    updateOrders(orders: Record<string, number>): void;
+    private elementAtPoint;
+    private escapeToSvgRoot;
+    private findTopmostWithSameForgeId;
+    private findForgeIdParent;
+    private elementsInRect;
+    private handleMouseMove;
+    private static DRAG_THRESHOLD;
+    private handleMouseDown;
+    private handleMouseUp;
+    private handleClick;
+    private handleKeyDown;
+    private handleKeyUp;
+    private pendingAnnotations;
+    /** Called by ForgeClient when the host confirms an annotation. */
+    confirmDot(annotationId: string, order: number): void;
+    /** Called by ForgeClient when the host cancels/deletes a pending annotation. */
+    cancelPending(annotationId: string): void;
+    private createAnnotationFromElements;
+    private handleDocumentLeave;
+    private addListeners;
+    private removeListeners;
+}
+//# sourceMappingURL=AnnotationOverlay.d.ts.map

package/dist/client/annotation/AnnotationOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnnotationOverlay.d.ts","sourceRoot":"","sources":["../../../src/client/annotation/AnnotationOverlay.ts"],"names":[],"mappings":"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"}

package/dist/client/design-mode/DesignModeController.d.ts

@@ -0,0 +1,35 @@
+import type { ParentMessenger } from "../../shared/messaging.js";
+import type { ComponentRegistry } from "../general/ComponentRegistry.js";
+import type { SelectModeController } from "../select-mode/SelectModeController.js";
+/**
+ * Manages design-mode interactions: element selection, prop extraction,
+ * visual highlighting, and source code updates via Babel AST.
+ */
+export declare class DesignModeController {
+    private messenger;
+    private componentRegistry;
+    private selectController;
+    private selectedElement;
+    private sourceCache;
+    constructor(messenger: ParentMessenger, componentRegistry: ComponentRegistry, selectController: SelectModeController);
+    getSelectedElement(): HTMLElement | null;
+    /** Removes the purple outline from the currently selected element. */
+    clearSelection(): void;
+    /**
+     * Handles a design-mode click on a target element.
+     * Selects the element, extracts props, and notifies the host.
+     */
+    handleClick(target: HTMLElement): void;
+    /** Updates the text content (children) of a forge element via source AST. */
+    updateText(forgeId: string, newText: string): void;
+    /**
+     * Updates a property on a forge element by modifying the source AST,
+     * writing back to the dev server, and triggering HMR.
+     */
+    updateProperty(forgeId: string, propName: string, newValue: any): Promise<void>;
+    private applyHighlight;
+    private removeHighlight;
+    private extractPropValues;
+    private getFiberFromElement;
+}
+//# sourceMappingURL=DesignModeController.d.ts.map

package/dist/client/design-mode/DesignModeController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DesignModeController.d.ts","sourceRoot":"","sources":["../../../src/client/design-mode/DesignModeController.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA;AACxE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAA;AAElF;;;GAGG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,iBAAiB,CAAmB;IAC5C,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,eAAe,CAA2B;IAClD,OAAO,CAAC,WAAW,CAA4B;gBAG7C,SAAS,EAAE,eAAe,EAC1B,iBAAiB,EAAE,iBAAiB,EACpC,gBAAgB,EAAE,oBAAoB;IAOxC,kBAAkB,IAAI,WAAW,GAAG,IAAI;IAIxC,sEAAsE;IACtE,cAAc,IAAI,IAAI;IAOtB;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAwCtC,6EAA6E;IAC7E,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIlD;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAmDrF,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,iBAAiB;IA4BzB,OAAO,CAAC,mBAAmB;CAM5B"}

package/dist/client/general/ComponentRegistry.d.ts

@@ -0,0 +1,15 @@
+export type PropDefinition = import("../../shared/events.js").PropDefinition;
+export type ComponentDefinition = import("../../shared/events.js").ComponentDefinition;
+export declare class ComponentRegistry {
+    private registry;
+    /** Registers a single component definition by name. */
+    register(name: string, definition: ComponentDefinition): void;
+    /** Registers multiple component definitions from a record. */
+    registerAll(definitions: Record<string, ComponentDefinition>): void;
+    /**
+     * Returns editable prop definitions for a component.
+     * Tries exact match, then case-insensitive, then HTML element mapping.
+     */
+    getEditableProps(componentName: string): PropDefinition[];
+}
+//# sourceMappingURL=ComponentRegistry.d.ts.map

package/dist/client/general/ComponentRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComponentRegistry.d.ts","sourceRoot":"","sources":["../../../src/client/general/ComponentRegistry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,OAAO,wBAAwB,EAAE,cAAc,CAAA;AAC5E,MAAM,MAAM,mBAAmB,GAAG,OAAO,wBAAwB,EAAE,mBAAmB,CAAA;AAEtF,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAyC;IAEzD,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,mBAAmB,GAAG,IAAI;IAI7D,8DAA8D;IAC9D,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,IAAI;IAMnE;;;OAGG;IACH,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,EAAE;CA+B1D"}

package/dist/client/general/ForgeClient.d.ts

@@ -0,0 +1,36 @@
+import type { ForgeClientOptions } from "./types.js";
+/**
+ * Core client-side orchestrator that runs inside the child iframe.
+ * Singleton — use `ForgeClient.getInstance()` to access.
+ *
+ * Coordinates between SelectModeController, DesignModeController,
+ * and AnnotationOverlay based on messages from the host.
+ */
+export declare class ForgeClient {
+    private static instance;
+    private messenger;
+    private selectMode;
+    private designMode;
+    private hoverDisabled;
+    private componentRegistry;
+    private annotationOverlay;
+    private selectController;
+    private designController;
+    private onError?;
+    private constructor();
+    /** Returns the singleton ForgeClient instance, creating it if necessary. */
+    static getInstance(options?: ForgeClientOptions): ForgeClient;
+    /** Enables or disables annotation mode. Useful for console-driven testing without a host. */
+    enableAnnotationMode(enabled: boolean): void;
+    private setupMessageListener;
+    private setSelectMode;
+    private setDesignMode;
+    private setAnnotationMode;
+    private handleSelectClick;
+    private handleDesignClick;
+    private sendReady;
+    private setupForgeIdPropagation;
+    private getFiberFromElement;
+    private propagateForgeIdFromFiber;
+}
+//# sourceMappingURL=ForgeClient.d.ts.map

package/dist/client/general/ForgeClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForgeClient.d.ts","sourceRoot":"","sources":["../../../src/client/general/ForgeClient.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2B;IAClD,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,iBAAiB,CAAmB;IAC5C,OAAO,CAAC,iBAAiB,CAAiC;IAC1D,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,OAAO,CAAC,CAAwB;IAExC,OAAO;IA4BP,4EAA4E;IAC5E,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW;IAO7D,6FAA6F;IAC7F,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAM5C,OAAO,CAAC,oBAAoB;IAgE5B,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,uBAAuB;IAkB/B,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,yBAAyB;CAkBlC"}

package/dist/client/general/SourceCodeUpdater.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Updates a JSX element's property in the source code using Babel AST traversal.
+ * Matches elements by `data-forge-id`, or falls back to source position.
+ * Returns the updated source string, or the original source if no changes were made.
+ */
+export declare function updateSourceAST(source: string, forgeId: string, propName: string, newValue: any, fallbackSourcePos?: string | null): string;
+/**
+ * Fetches source code from the dev server's read-source endpoint.
+ */
+export declare function fetchSource(filePath: string): Promise<string | null>;
+/**
+ * Writes updated source code back to the dev server, triggering HMR.
+ */
+export declare function writeSource(filePath: string, source: string): Promise<boolean>;
+//# sourceMappingURL=SourceCodeUpdater.d.ts.map

package/dist/client/general/SourceCodeUpdater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceCodeUpdater.d.ts","sourceRoot":"","sources":["../../../src/client/general/SourceCodeUpdater.ts"],"names":[],"mappings":"AA8CA;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,GAAG,EACb,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAChC,MAAM,CAqDR;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW1E;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYpF"}

package/dist/client/general/element-utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Gets the parent element, crossing shadow DOM boundaries.
+ */
+export declare function getParentElement(element: Element): Element | null;
+/**
+ * Finds the closest ancestor matching a selector, crossing shadow DOM boundaries.
+ */
+export declare function closestCrossingShadow(element: Element, selector: string): Element | null;
+/**
+ * Gets a readable CSS-selector-like path for an element (e.g., "article > section > p").
+ */
+export declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
+/**
+ * Identifies an element and returns a human-readable name + path.
+ */
+export declare function identifyElement(target: HTMLElement): {
+    name: string;
+    path: string;
+};
+//# sourceMappingURL=element-utils.d.ts.map

package/dist/client/general/element-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-utils.d.ts","sourceRoot":"","sources":["../../../src/client/general/element-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAKjE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAOxF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,SAAI,GAAG,MAAM,CAgCxE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA+FnF"}

package/dist/client/general/overlay.d.ts

@@ -0,0 +1,9 @@
+/** Creates a positioned overlay div suitable for element highlighting. */
+export declare function createOverlayElement(rect: DOMRect, borderColor: string, bgColor: string, borderStyle?: "solid" | "dashed"): HTMLDivElement;
+/** Shows a blue selection overlay around the given element. */
+export declare function showOverlay(element: HTMLElement): void;
+export declare function removeOverlay(): void;
+/** Returns the full-screen hit-test overlay (creates if needed). */
+export declare function createHitTestOverlay(): HTMLDivElement;
+export declare function removeHitTestOverlay(): void;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/client/general/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/client/general/overlay.ts"],"names":[],"mappings":"AAKA,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,WAAW,GAAE,OAAO,GAAG,QAAkB,GACxC,cAAc,CAehB;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAMtD;AAED,wBAAgB,aAAa,IAAI,IAAI,CAKpC;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,cAAc,CAkBrD;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C"}

package/dist/client/general/react-detection.d.ts

@@ -0,0 +1,49 @@
+interface ComponentType {
+    name?: string;
+    displayName?: string;
+    render?: {
+        name?: string;
+        displayName?: string;
+    };
+    type?: ComponentType;
+    _context?: {
+        displayName?: string;
+    };
+    _status?: number;
+    _result?: ComponentType;
+    $$typeof?: symbol;
+    prototype?: {
+        isReactComponent?: boolean;
+    };
+}
+interface ReactFiber {
+    tag: number;
+    type: ComponentType | string | null;
+    elementType: ComponentType | null;
+    return: ReactFiber | null;
+    child?: ReactFiber | null;
+    sibling?: ReactFiber | null;
+    _debugSource?: {
+        fileName: string;
+        lineNumber: number;
+        columnNumber?: number;
+    };
+    _debugOwner?: ReactFiber;
+    memoizedProps?: Record<string, unknown>;
+    stateNode?: unknown;
+}
+/** Detects whether the current page is a React application. */
+export declare function isReactPage(): boolean;
+/** Extracts the React fiber node from a DOM element. Works with React 16.8+ through 19.x. */
+export declare function getFiberFromElement(element: HTMLElement): ReactFiber | null;
+export interface ReactComponentInfo {
+    path: string | null;
+    components: string[];
+}
+/**
+ * Walks up the React fiber tree from a DOM element and collects component names.
+ * Returns an info object with the component path and individual names.
+ */
+export declare function getReactComponentName(element: HTMLElement, maxComponents?: number, maxDepth?: number): ReactComponentInfo;
+export {};
+//# sourceMappingURL=react-detection.d.ts.map

package/dist/client/general/react-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-detection.d.ts","sourceRoot":"","sources":["../../../src/client/general/react-detection.ts"],"names":[],"mappings":"AAKA,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAC3C;AAED,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAAA;IACnC,WAAW,EAAE,aAAa,GAAG,IAAI,CAAA;IACjC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;IACzB,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IACzB,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC3B,YAAY,CAAC,EAAE;QACb,QAAQ,EAAE,MAAM,CAAA;QAChB,UAAU,EAAE,MAAM,CAAA;QAClB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;IACD,WAAW,CAAC,EAAE,UAAU,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAmED,+DAA+D;AAC/D,wBAAgB,WAAW,IAAI,OAAO,CAmDrC;AAID,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,CA0B3E;AA0FD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,EACpB,aAAa,SAAiB,EAC9B,QAAQ,SAAsB,GAC7B,kBAAkB,CAoCpB"}

package/dist/client/general/types.d.ts

@@ -0,0 +1,26 @@
+import type { ParentMessenger } from "../../shared/messaging.js";
+import type { ComponentRegistry } from "./ComponentRegistry.js";
+import type { AnnotationOverlay } from "../annotation/AnnotationOverlay.js";
+/** Options for ForgeClient initialization. */
+export interface ForgeClientOptions {
+    /** Called when an internal error occurs in the client. */
+    onError?: (error: Error) => void;
+}
+/** Shared context passed to controllers by ForgeClient. */
+export interface ForgeClientContext {
+    messenger: ParentMessenger;
+    componentRegistry: ComponentRegistry;
+    annotationOverlay: AnnotationOverlay | null;
+    getSelectMode(): boolean;
+    getDesignMode(): boolean;
+}
+/** Callbacks required by SelectModeController to coordinate with ForgeClient. */
+export interface SelectModeCallbacks {
+    getSelectMode(): boolean;
+    getDesignMode(): boolean;
+    getHoverDisabled(): boolean;
+    getSelectedDesignElement(): HTMLElement | null;
+    onSelectClick(target: HTMLElement): void;
+    onDesignClick(target: HTMLElement): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/general/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/client/general/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAA;AAE3E,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CACjC;AAED,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,eAAe,CAAA;IAC1B,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,iBAAiB,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC3C,aAAa,IAAI,OAAO,CAAA;IACxB,aAAa,IAAI,OAAO,CAAA;CACzB;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,aAAa,IAAI,OAAO,CAAA;IACxB,aAAa,IAAI,OAAO,CAAA;IACxB,gBAAgB,IAAI,OAAO,CAAA;IAC3B,wBAAwB,IAAI,WAAW,GAAG,IAAI,CAAA;IAC9C,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACxC,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;CACzC"}