@mosetta/editor 0.0.0-stage → 0.0.29

package/tiles/previewBridge/previewBridgeCommon.ts

@@ -0,0 +1,172 @@
+// The editor ↔ preview contract. Shared by the two halves that speak it: the agent module riding
+// inside the canvas iframe (previewBridge.component.tsx) and the overlay drawing on top of that
+// iframe (modules/canvas).
+//
+// TRANSPORT — a MessageChannel, not bare window.postMessage in both directions. The agent
+// announces itself to whoever embeds it (a greeting carrying nothing but "a mosetta preview is
+// here"), and the editor answers by handing over one end of a fresh channel. From then on the
+// port IS the permission to talk: nothing to forge, no origin to re-check on every message, and
+// the same code works once previews move to a tenant's own subdomain.
+//
+// COORDINATES — every box is viewport-relative, measured inside the iframe. The iframe element in
+// the editor spans exactly that viewport, so the overlay draws the numbers as they arrive: no
+// scroll arithmetic, and no way for the two sides to disagree about the origin of the axes.
+import type { ITileReference, IBlueprint } from '@mosetta/core';
+
+/** bumped when the shape below changes incompatibly — an older agent is ignored, not crashed */
+export const PREVIEW_PROTOCOL_VERSION = 1;
+
+/** the agent's module name — the one thing about it that is a constant */
+const PREVIEW_BRIDGE_NAME = 'previewBridge';
+
+/**
+ * The agent's full id, derived from ANY reference of the same editor build (in practice: the
+ * canvas's own, through useComponent). Namespace and version are shared — only the name differs —
+ * so the agent that rides into the preview is exactly the build that will talk to it, and the two
+ * halves of the protocol can never drift apart in version.
+ *
+ * The editor naming its own module is also what keeps the render runtime free of any knowledge
+ * about the editor: it is told which entity to attach, it does not go looking for one.
+ */
+export function previewBridgeIdOf({ namespace, version }: ITileReference): string {
+  return `_ns_${namespace}_t_component_n_${PREVIEW_BRIDGE_NAME}_v_${version}`;
+}
+
+/**
+ * The id of the LANDING SPACE: a little emptiness the agent puts into its own copy of the page
+ * where a block is about to go, so the overlay can frame the very spot (`landing` below). Outside
+ * the `node-<n>` space the editor hands out, like the agent's own node; no document ever holds it.
+ */
+export const LANDING_NODE_ID = '__mosettaLanding';
+
+/** what a stand-in (standIn.ts) carries: the reference of the block it stands for */
+export const STAND_IN_ATTRIBUTE = 'data-mosetta-stand-in';
+
+/** where a block is about to go: the node, its slot, the position among that slot's children */
+export interface ILandingPlace {
+  readonly parentId: string;
+  readonly slot: string;
+  readonly index: number;
+}
+
+/** the agent's greeting (window-level, iframe → embedder) */
+export const PREVIEW_HELLO = 'mosetta:preview-hello';
+
+/** the editor's answer (window-level, embedder → iframe), carrying the channel port */
+export const PREVIEW_PORT = 'mosetta:preview-port';
+
+export interface IPreviewHello {
+  readonly mosetta: typeof PREVIEW_HELLO;
+  readonly protocol: number;
+}
+
+export interface IPreviewPortOffer {
+  readonly mosetta: typeof PREVIEW_PORT;
+  readonly protocol: number;
+}
+
+export function isPreviewHello(data: unknown): data is IPreviewHello {
+  const message = data as IPreviewHello | null;
+  return !!message && message.mosetta === PREVIEW_HELLO && message.protocol === PREVIEW_PROTOCOL_VERSION;
+}
+
+export function isPreviewPortOffer(data: unknown): data is IPreviewPortOffer {
+  const message = data as IPreviewPortOffer | null;
+  return !!message && message.mosetta === PREVIEW_PORT && message.protocol === PREVIEW_PROTOCOL_VERSION;
+}
+
+/** where a tree node landed on screen; `depth` breaks ties when boxes nest exactly */
+export interface INodeBox {
+  readonly id: string;
+  readonly reference: string;
+  readonly depth: number;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface IPreviewViewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * A place a block can go, as the preview currently renders it: the module opened this slot, and
+ * this is where the next child would land. `area` is the box of whatever encloses the marker —
+ * for an empty slot that is the region to highlight, since a bare insertion point has no size.
+ */
+export interface ISlotBox {
+  readonly ownerId: string;
+  readonly slot: string;
+  readonly max: number | 'many';
+  readonly min: number;
+  readonly filled: number;
+  readonly x: number;
+  readonly y: number;
+  readonly area: { readonly x: number; readonly y: number; readonly width: number; readonly height: number } | null;
+}
+
+/** agent → editor */
+export type TPreviewEvent
+  = | {
+    readonly t: 'geometry';
+    readonly boxes: readonly INodeBox[];
+    readonly slots: readonly ISlotBox[];
+    /**
+     * The PREFAB nodes the realm shows EXPANDED right now (by node id): a live tree can only
+     * re-expand a prefab from blocks already rendered, so a prefab node absent here needs the
+     * server's render — the editor rebuilds the frame instead of pushing the tree. An agent that
+     * does not say (older) leaves the editor to its own guess.
+     */
+    readonly units?: readonly string[];
+    /**
+     * The PREFABS' own blocks, each under its expanded id (`<prefabNode>/<block>`) — `boxes`
+     * carries a prefab as ONE box, their union, under the prefab node; these are for the editor to
+     * frame one of them, picked to be seen (read-only). Outlets are left out: they are the page's
+     * place, not the prefab's block.
+     */
+    readonly parts?: readonly INodeBox[];
+    readonly viewport: IPreviewViewport;
+    /** where the page stood when this was measured — the baseline for every 'scroll' after it */
+    readonly scroll: { readonly x: number; readonly y: number };
+  }
+  // Scrolling the page moves everything by the same amount and changes no layout, so it is
+  // reported as a POSITION, not as new geometry: the editor slides its whole overlay by the
+  // difference. Re-measuring every block on every scroll event is what put the outlines a
+  // visible step behind the page.
+  | { readonly t: 'scroll'; readonly x: number; readonly y: number }
+  // ctrl carries Ctrl-or-Cmd from the source event: keyboard focus may live in EITHER realm, so
+  // the editor cannot read the modifier itself for events born inside the preview
+  // `nodeId` names a block of the PAGE — a prefab's block reads as its prefab node; `part` adds
+  // which of the prefab's own blocks it was (`<prefabNode>/<block>`), null on the page's own
+  | { readonly t: 'hover'; readonly nodeId: string | null; readonly part?: string | null; readonly ctrl?: boolean }
+  | { readonly t: 'pick'; readonly nodeId: string | null; readonly part?: string | null; readonly ctrl?: boolean }
+  /**
+   * Where the pointer is over the page, at most once a frame while armed: the overlay offers a
+   * place on the side of the selected block the pointer is on. Viewport coordinates, with the
+   * page's scroll at that moment — the editor reads them against the measurement's own baseline.
+   */
+  | { readonly t: 'pointer'; readonly x: number; readonly y: number; readonly scroll: { readonly x: number; readonly y: number } };
+
+/** editor → agent */
+export type TPreviewCommand
+  // suppression of the application's own click handling, so a click means "select this block"
+  // instead of following a link. Off = the preview behaves like the live page.
+  = | { readonly t: 'armed'; readonly armed: boolean }
+  | { readonly t: 'measure' }
+  | { readonly t: 'reveal'; readonly nodeId: string }
+  /** the views the editor chose for reference providers (i18n: the language being edited) */
+  | { readonly t: 'views'; readonly views: Readonly<Record<string, unknown>> }
+  /**
+   * The tree as the editor now holds it, rendered in place of the one the preview booted with.
+   * Only ever sent while the MODULE SET is unchanged: a block of a type this realm never loaded
+   * cannot appear by re-rendering, and that case rebuilds the frame instead.
+   */
+  | { readonly t: 'page'; readonly page: IBlueprint }
+  /**
+   * Make room where a block is about to go — or take the room away (null). The agent splices its
+   * landing space into the tree it renders (and into every tree that arrives while the place
+   * stands); the measurement after reports it like any node, under LANDING_NODE_ID.
+   */
+  | { readonly t: 'landing'; readonly at: ILandingPlace | null };

package/tiles/previewBridge/standIn.ts

@@ -0,0 +1,22 @@
+// The STAND-IN in the preview's own copy of the page: where a block of a distribution the project
+// disconnected stands, the agent shows a placeholder of its own module instead (ADR-0059). The site
+// renders nothing there; the editor shows the author what it leaves out, under the block's very id,
+// so the overlay frames it, a click selects it and the tree's ✕ takes it away. The server's editable
+// preview does the same to the first render (editorStandIn in @mosetta/server) — this keeps every
+// tree the editor sends after it alike. Pure tree surgery, like the landing space.
+import type { IBlueprint } from '@mosetta/core';
+import { withoutDistributions } from '@mosetta/content/units';
+import type { IBlueprintNodeDoc } from '@mosetta/content/units';
+
+/** the page with a stand-in for every block of the `disconnected` distributions, or the very page */
+export function withStandIns(page: IBlueprint, disconnected: readonly string[], agentReference: string): IBlueprint {
+  if (!disconnected.length) return page;
+  return withoutDistributions(page as unknown as IBlueprintNodeDoc, disconnected, (node) => ({
+    id: node.id,
+    reference: agentReference,
+    ...(node.slot !== undefined ? { slot: node.slot } : {}),
+    settings: { standIn: node.reference },
+    children: [],
+    ssr: false,
+  })) as unknown as IBlueprint;
+}