Frame Bridge

Iframe communication library for Uniweb. Provides a bidirectional, promise-based messaging protocol between parent and child frames with origin validation, dimension reporting, URL synchronization, and custom action handlers.

Two Use Cases

Editor (primary) — Rich bidirectional protocol between the Uniweb editor and the dynamic-runtime preview iframe. Messengers are constructed programmatically with all embedding features off (the defaults), and handlers are registered dynamically via setHandler/setHandlers.

Embedding (secondary) — A non-Uniweb parent page hosts a Uniweb site in an iframe. Auto-init <script> tags opt into embedding features (URL sync, auto-resize, JSON-LD injection) for a drop-in experience.

Installation

npm install @uniweb/frame-bridge

Or use auto-init scripts via CDN for the embedding use case:

<!-- Parent page -->
<script src="https://cdn.jsdelivr.net/npm/@uniweb/frame-bridge/dist/auto/parent.min.js"></script>

<!-- Child iframe -->
<script src="https://cdn.jsdelivr.net/npm/@uniweb/frame-bridge/dist/auto/child.min.js"></script>

Programmatic Usage

Parent

import { ParentMessenger } from '@uniweb/frame-bridge/parent'

const messenger = new ParentMessenger({
  allowedOrigins: ['https://app.example.com'],

  // Embedding features — all default to false
  autoResize: true,
  urlSync: true,
  jsonLD: true,

  // Callbacks
  onIframeReady: (id, { origin, route, dimensions, metadata }) => {
    console.log(`Iframe ${id} ready at ${route.path}`)
  },
  onRouteChange: (id, { path, title }) => {
    console.log(`Iframe navigated to ${path}`)
  },
  onDimensionUpdate: (id, { width, height }) => {
    console.log(`Iframe resized to ${height}px`)
  },

  // Custom action handlers
  actionHandlers: {
    userSelected: (iframeId, { userId }) => {
      return { success: true }
    },
  },
})

// Send messages
messenger.sendToChild('iframe-id', 'navigate', { path: '/users/123' })
messenger.sendToAllChildren('setTheme', { theme: 'dark' })

// Query iframe state
messenger.getIframe('iframe-id')   // { origin, dimensions, route, metadata }
messenger.getAllIframes()

// Update handlers after construction
messenger.setHandler('userSelected', (id, params) => { /* ... */ })
messenger.setHandlers({ action1: fn1, action2: fn2 })

// Cleanup
messenger.destroy()

Child

import { ChildMessenger } from '@uniweb/frame-bridge/child'

const messenger = new ChildMessenger({
  allowedOrigins: ['https://parent.example.com'],

  // Reporting features — all default to false
  dimensionReporting: true,
  routeReporting: true,

  // Custom route getter (for SPAs)
  getRoute: () => ({
    path: window.location.pathname,
    title: document.title,
  }),

  // Callbacks
  onParentReady: (response) => {
    console.log('Connected to parent')
  },
  onNavigate: ({ path }) => {
    window.history.pushState({}, '', path)
  },

  // Custom action handlers
  actionHandlers: {
    loadUser: ({ userId }) => {
      return { user: { id: userId, name: 'John' } }
    },
  },

  // Extra data sent with announce
  metadata: { version: '1.0' },
})

// Manual updates
messenger.updateRoute('/search/results', 'Search Results')
messenger.updateDimensions()
messenger.updateJSONLD({ '@context': 'https://schema.org', '@type': 'WebPage' })

// Send messages
const result = await messenger.sendToParent('userSelected', { userId: 123 })

// Update handlers after construction
messenger.setHandlers({
  myAction: (params) => { /* can access current state */ },
})

// Cleanup
messenger.destroy()

React Pattern

Construct the messenger once in useState, register handlers in useEffect so they can access current React state:

import { useState, useEffect } from 'react'
import { ChildMessenger } from '@uniweb/frame-bridge/child'

function App() {
  const [count, setCount] = useState(0)
  const [messenger] = useState(() => new ChildMessenger({
    allowedOrigins: ['https://parent.example.com'],
  }))

  useEffect(() => {
    messenger.setHandlers({
      getCount: () => ({ count }),  // always reads current state
      navigate: ({ path }) => {
        window.history.pushState({}, '', path)
      },
    })
    return () => messenger.destroy()
  }, [messenger, count])

  return <div>{/* ... */}</div>
}

Embedding with Auto-Init Scripts

The auto-init scripts create a window.FrameBridge object with all embedding features enabled. No imports needed.

Parent page:

<iframe src="https://app.example.com" data-messenger-id="main"></iframe>
<script src="https://cdn.../parent.min.js"></script>
<script>
  window.FrameBridge.on('routeChange', (id, { path, title }) => {
    console.log('Iframe navigated to:', path)
  })

  window.FrameBridge.on('iframeReady', (id, info) => {
    console.log('Iframe registered:', id)
  })
</script>

Child iframe:

<script src="https://cdn.../child.min.js"></script>
<script>
  window.FrameBridge.on('parentReady', (response) => {
    console.log('Connected to parent')
  })
</script>

The auto-init parent enables autoResize, urlSync, and jsonLD. The auto-init child enables dimensionReporting and routeReporting.

Architecture

The library is split into parent and child messengers that communicate via postMessage.

Parent-side (src/parent/):

• ParentMessenger.js — Main parent frame messenger
• IframeRegistry.js — Tracks registered iframe metadata (origin, dimensions, route)
• URLSyncManager.js — Syncs parent URL with iframe routes, handles browser navigation
• JSONLDInjector.js — Injects structured data from iframes into parent <head>
• auto-init.js — Self-initializing IIFE for CDN usage

Child-side (src/child/):

• ChildMessenger.js — Main iframe messenger
• DimensionReporter.js — ResizeObserver-based dimension reporting (accounts for body margin/padding)
• RouteReporter.js — Watches for route changes via pushState/replaceState patching
• auto-init.js — Self-initializing IIFE for CDN usage

Shared (src/shared/):

• BaseMessenger.js — Abstract base class with promise-based postMessage wrapper
• OriginValidator.js — Validates message origins (supports wildcards like https://*.example.com)
• constants.js — Action types, defaults, error messages
• utils.js — Logger, debounce, iframe detection utilities

Message Flow

1. Initialization — Child announces itself to parent (ANNOUNCE). Parent responds with iframe ID and optional initial route. Child starts reporters if enabled.

2. Route updates (opt-in) — Child navigates internally and sends UPDATE_ROUTE. The onRouteChange callback always fires. If urlSync is enabled, parent also updates the URL query param. Browser back/forward sends NAVIGATE to child.

3. Dimension updates (opt-in) — ResizeObserver detects changes. Child sends UPDATE_DIMENSIONS. Parent auto-resizes iframe if autoResize is enabled.

4. Custom actions — Both sides can register actionHandlers for bidirectional RPC. All messages return promises.

Build Outputs

Rollup generates multiple formats in dist/:

• ESM (dist/esm/) — For modern bundlers
• UMD (dist/umd/) — For universal module systems
• IIFE (dist/auto/) — Auto-initializing scripts for <script> tags (minified and unminified)

Each format has separate bundles for the full library (index), parent-only (parent), and child-only (child).

API Reference

ParentMessenger

Constructor Options

Option	Type	Default	Description
allowedOrigins	string[]	Same-origin only	Allowed child origins
autoResize	boolean	false	Auto-resize iframes to content
urlSync	boolean	false	Sync parent URL with iframe routes
urlParamKey	string	'path'	Query param key for routes
preserveOtherParams	boolean	true	Keep other query params when syncing
jsonLD	boolean	false	Inject JSON-LD from iframes into <head>
onIframeReady	function	-	(iframeId, { origin, dimensions, route, metadata })
onRouteChange	function	-	(iframeId, { path, title })
onDimensionUpdate	function	-	(iframeId, { width, height })
actionHandlers	object	{}	Custom action handlers
timeout	number	5000	Message timeout (ms)
logLevel	number|string	3 ('INFO')	Logging verbosity

Methods

Method	Returns	Description
sendToChild(iframeId, action, params)	Promise	Send message to specific iframe
sendToAllChildren(action, params)	Promise	Send message to all iframes
getIframe(iframeId)	object|null	Get iframe metadata
getAllIframes()	object[]	Get all iframe metadata
setHandler(action, fn)	void	Set/replace single action handler
setHandlers(handlers)	void	Set/replace multiple action handlers
setLogLevel(level)	void	Change log level
destroy()	void	Cleanup and remove listeners

ChildMessenger

Constructor Options

Option	Type	Default	Description
allowedOrigins	string[]	Same-origin only	Allowed parent origins
dimensionReporting	boolean	false	Auto-report dimensions on resize
dimensionThreshold	number	1	Min px change to trigger report
routeReporting	boolean	false	Auto-report route changes
getRoute	function	Default getter	Returns { path, title }
onParentReady	function	-	(response)
onNavigate	function	-	({ path })
actionHandlers	object	{}	Custom action handlers
metadata	object	{}	Extra data sent with announce
timeout	number	5000	Message timeout (ms)
logLevel	number|string	3 ('INFO')	Logging verbosity

Methods

Method	Returns	Description
sendToParent(action, params)	Promise	Send message to parent
updateRoute(path, title?)	void	Manually report route change
updateDimensions()	void	Manually trigger dimension report
updateJSONLD(jsonld)	void	Send JSON-LD structured data
setHandler(action, fn)	void	Set/replace single action handler
setHandlers(handlers)	void	Set/replace multiple action handlers
setLogLevel(level)	void	Change log level
destroy()	void	Cleanup and remove listeners

If ChildMessenger is constructed outside an iframe, it creates a no-op instance (isActive = false) with a console warning.

License

MIT