@wizestudio/canvas-bridge

The versioned, framework-neutral postMessage protocol between the WizeStudio editor and a rendered canvas.

Where this sits

WizeStudio is a visual page builder for headless CMS platforms. Its editor runs inside the CMS admin; the widgets it edits live in the developer's own application — a different bundle, a different React instance, in production a different origin. The editor therefore cannot import those components. Rather than shipping approximations of them, which is how a builder's canvas quietly stops resembling the real site, WizeStudio frames the developer's own application at an edit-mode route and drives it over this protocol.

That makes this package the framework-agnosticism boundary. A Vue, Svelte or Angular SDK means implementing this contract plus a recursive renderer, and changing nothing else in the system. @wizestudio/editor holds the host end; @wizestudio/renderer-react's WizeCanvas holds the client end.

Install

npm install @wizestudio/canvas-bridge

Usage

Editor side:

import { createBridgeHost, createWindowTransport } from '@wizestudio/canvas-bridge';

const transport = createWindowTransport({
  target: iframe.contentWindow!,
  targetOrigin: 'https://preview.example.com',
  allowedOrigins: ['https://preview.example.com'],
});

const host = createBridgeHost(transport, {
  onClick: (id) => selection.select(id!),
  onGeometry: (nodes) => overlay.reposition(nodes),
});

host.connect();
host.sendDocument(document);

Canvas side:

import { createBridgeClient } from '@wizestudio/canvas-bridge';

const client = createBridgeClient(transport, { renderer: 'react' }, {
  onDocument: (doc) => setDocument(doc),
  onMeasure: () => client.reportGeometry(measureAll(), currentScroll()),
});

targetOrigin and allowedOrigins are the security boundary, never "*". Posting to a wildcard leaks the page being edited to whatever happens to be framed; accepting from one lets anything rewrite it.

Design

The editor never touches the canvas DOM — in production it cannot, since the two are different origins. All hit-testing and measurement happen on the canvas side and travel back as geometry; overlays are drawn in the parent document. That restriction is not a limitation to work around, it is what keeps a non-React canvas viable later.

Messages carry PROTOCOL_VERSION. An incompatible peer is reported through onIncompatible rather than silently misinterpreted.

Key exports

| Area | Exports | |---|---| | Protocol | HostMessage, ClientMessage, Envelope, PROTOCOL_VERSION, PROTOCOL_NAMESPACE, envelope, isEnvelope, isCompatible, isHostMessage, isClientMessage | | Transports | createWindowTransport, createMemoryTransportPair, Transport | | Host end | createBridgeHost, BridgeHost, HostHandlers | | Client end | createBridgeClient, BridgeClient, ClientHandlers, BridgeClientOptions | | Geometry | NodeGeometry, Rect, Modifiers, ClientCapabilities |

createMemoryTransportPair connects both ends in-process, which is how the protocol is tested without a browser.

Licence

MIT.

WizeStudio is open core, and this package is on the production render path — the canvas client ships inside the customer's own frontend. It is MIT deliberately and contains no licensing code of any kind, which is what makes "a lapsed subscription cannot break your live site" a property of the build rather than a promise. schema, core, renderer-react, renderer-next and cli are MIT for the same reason; the authoring side — editor, plugin-strapi, components, cms-strapi — is commercial.

wizestudio.wizeb.com