@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

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

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

// Importing the client auto-initializes it
import '@supernovaio/prototyping-tooling/client'

Vite plugin (child build)

// 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).

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:

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:

// 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

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 for a detailed integration guide.

License

MIT