@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/previewBridge/previewAgent.ts

@@ -0,0 +1,457 @@
+// The editor's AGENT inside the preview realm. Draws nothing (the overlay lives in the editor's
+// own document, where it cannot collide with the application's UI) — it measures, hit-tests, and
+// reports over the channel described in previewBridgeCommon.
+//
+// Why an agent is needed at all: geometry and hit-testing only exist inside the iframe. The editor
+// knows the page TREE; the iframe knows where that tree landed on screen.
+//
+// While armed it also SWALLOWS the application's pointer handling: inside the editor a click on a
+// block means "select this block", not "follow the link". Suppression happens in the capture phase
+// at the document root, above react's root container, so the application's handlers never run —
+// nothing to undo afterwards.
+import { NODE_ID_ATTRIBUTE, previewSlots, SLOT_ATTRIBUTE, slotKey } from '@mosetta/react';
+import type { IBlueprintNode, IBlueprint } from '@mosetta/core';
+import { expandUnitsFrom, isOutletReference, unitOwnerOf } from '@mosetta/content/units';
+import type { IBlueprintNodeDoc } from '@mosetta/content/units';
+import {
+  ILandingPlace,
+  INodeBox,
+  isPreviewPortOffer,
+  ISlotBox,
+  PREVIEW_HELLO,
+  PREVIEW_PROTOCOL_VERSION,
+  STAND_IN_ATTRIBUTE,
+  TPreviewCommand,
+  TPreviewEvent,
+} from './previewBridgeCommon';
+
+const NODE_SELECTOR = `[${NODE_ID_ATTRIBUTE}]`;
+
+// the greeting repeats until the embedder answers: the agent may well mount before the editor
+// side is listening (a reloaded iframe races the overlay's own effects)
+const HELLO_INTERVAL_MS = 300;
+const HELLO_ATTEMPTS = 20;
+
+// events the agent eats while armed. Pointer and touch events stay untouched on purpose —
+// swallowing them would take native scrolling and hovering with them.
+const SUPPRESSED_EVENTS = ['click', 'auxclick', 'dblclick', 'mousedown', 'mouseup', 'submit'] as const;
+
+/** how long after the last scroll event the page is considered still, and worth measuring again */
+const SCROLL_SETTLE_MS = 150;
+
+// a block of an expanded PREFAB carries `<prefabNode>/<inner>` as its id: to the editor it IS the
+// prefab node — hovering or picking the prefab's blocks addresses the prefab, never its insides
+const ownerOf = (id: string): string => unitOwnerOf(id) ?? id;
+
+function nodeIdOf(target: EventTarget | null): string | null {
+  const host = target instanceof Element ? target.closest(NODE_SELECTOR) : null;
+  const id = host?.getAttribute(NODE_ID_ATTRIBUTE) ?? null;
+  return id === null ? null : ownerOf(id);
+}
+
+/**
+ * …and WHICH of the prefab's own blocks it was — its expanded id, for the editor to show it
+ * (read-only); null over the page's own block. A prefab's outlet is the page's place, not a block
+ * of the prefab: the search goes on to the block around it.
+ */
+function partOf(target: EventTarget | null): string | null {
+  let host = target instanceof Element ? target.closest(NODE_SELECTOR) : null;
+  while (host) {
+    const id = host.getAttribute(NODE_ID_ATTRIBUTE) ?? '';
+    if (unitOwnerOf(id) === null) return null;
+    if (!isOutletReference(host.className)) return id;
+    host = host.parentElement?.closest(NODE_SELECTOR) ?? null;
+  }
+  return null;
+}
+
+function depthOf(element: Element): number {
+  let depth = 0;
+  for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+    if (parent.hasAttribute(NODE_ID_ATTRIBUTE)) depth++;
+  }
+  return depth;
+}
+
+/**
+ * Where a node's contents landed. The scope host is `display: contents`, so it generates no box of
+ * its own — the union of what it CONTAINS is measured instead; an element that does produce a box
+ * still answers directly.
+ */
+function boxOf(element: Element, range: Range): INodeBox | null {
+  const id = element.getAttribute(NODE_ID_ATTRIBUTE);
+  if (!id) return null;
+  range.selectNodeContents(element);
+  let rect = range.getBoundingClientRect();
+  if (!rect.width && !rect.height) rect = element.getBoundingClientRect();
+  if (!rect.width && !rect.height) return null; // renders nothing — nothing to outline
+  return {
+    id,
+    // a stand-in (standIn.ts) is the agent's own module, but to the editor it is the block it
+    // stands for — the outline names that one
+    reference: element.firstElementChild?.getAttribute(STAND_IN_ATTRIBUTE) ?? element.className.trim(),
+    depth: depthOf(element),
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+/**
+ * The tree to render after a live update. The editor's document knows nothing of the agent — the
+ * node was attached on the way out, by the render runtime — so an incoming tree would quietly
+ * unmount the very module that received it. What the realm already holds wins twice here: the
+ * agent's own node is carried over, and so is everything the boot envelope added on top of the
+ * document (the catalog slice, the host base, the ssr stamp), which no editor ever sees.
+ */
+export function withAgentNode(current: IBlueprint, next: IBlueprint, agentReference: string): IBlueprint {
+  const arriving = new Set((next.children ?? []).map((child) => child.id));
+  const mine = (current.children ?? []).filter(
+    (child) => child.reference === agentReference && !arriving.has(child.id),
+  );
+  const children: IBlueprintNode[] = mine.length ? [...(next.children ?? []), ...mine] : (next.children ?? []);
+  // prefabs the realm already shows expand from their rendered blocks — the editor's document
+  // names them raw, and a raw prefab node has no module to render
+  const merged = { ...current, ...next, children } as unknown as IBlueprintNodeDoc;
+  return expandUnitsFrom(current, merged) as unknown as IBlueprint;
+}
+
+export interface IPreviewAgentOptions {
+  /** what a live tree update does in this realm — in practice the page manager's setCurrentPage */
+  readonly applyPage?: (page: IBlueprint) => void;
+  /** where a block is about to go, or nowhere — the landing space follows (withLanding) */
+  readonly applyLanding?: (at: ILandingPlace | null) => void;
+  /** what new provider views do in this realm — in practice the application's views store */
+  readonly applyViews?: (views: Readonly<Record<string, unknown>>) => void;
+}
+
+export class PreviewAgent {
+  private port: MessagePort | null = null;
+
+  private armed = true;
+
+  private helloTimer: ReturnType<typeof setInterval> | null = null;
+
+  private frame: number | null = null;
+
+  private hovered: string | null = null;
+
+  /** the prefab's own block under the pointer, when it is over one */
+  private hoveredPart: string | null = null;
+
+  private hoveredCtrl = false;
+
+  /** the pointer's latest position, sent at most once a frame */
+  private pointer: { x: number; y: number } | null = null;
+
+  private pointerFrame: number | null = null;
+
+  private readonly range = document.createRange();
+
+  private resizeObserver: ResizeObserver | null = null;
+
+  /** elements currently under the size observer — see watchSizes */
+  private readonly watched = new Set<Element>();
+
+  private settleTimer: ReturnType<typeof setTimeout> | null = null;
+
+  private readonly mutationObserver = new MutationObserver(() => this.schedule());
+
+  private unwatchSlots: (() => void) | null = null;
+
+  constructor(private readonly options: IPreviewAgentOptions = {}) {}
+
+  start(): void {
+    // not embedded → nobody to talk to (a preview URL opened directly, for instance)
+    if (window.parent === window) return;
+    window.addEventListener('message', this.onWindowMessage);
+    let attempts = 0;
+    const greet = (): void => {
+      if (this.port || attempts++ >= HELLO_ATTEMPTS) return this.stopGreeting();
+      // the greeting carries no page data, so an unknown embedder learns nothing from it; the
+      // channel that follows is what actually opens the conversation
+      window.parent.postMessage({ mosetta: PREVIEW_HELLO, protocol: PREVIEW_PROTOCOL_VERSION }, '*');
+    };
+    greet();
+    this.helloTimer = setInterval(greet, HELLO_INTERVAL_MS);
+  }
+
+  stop(): void {
+    this.stopGreeting();
+    window.removeEventListener('message', this.onWindowMessage);
+    this.unwatchSlots?.();
+    this.unwatchSlots = null;
+    this.detachDocument();
+    if (this.frame !== null) cancelAnimationFrame(this.frame);
+    if (this.pointerFrame !== null) cancelAnimationFrame(this.pointerFrame);
+    this.port?.close();
+    this.port = null;
+  }
+
+  private stopGreeting(): void {
+    if (this.helloTimer !== null) clearInterval(this.helloTimer);
+    this.helloTimer = null;
+  }
+
+  private readonly onWindowMessage = (event: MessageEvent): void => {
+    if (this.port || !isPreviewPortOffer(event.data)) return;
+    const port = event.ports[0];
+    if (!port) return;
+    this.port = port;
+    this.stopGreeting();
+    port.onmessage = (message: MessageEvent) => this.onCommand(message.data as TPreviewCommand);
+    port.start();
+    this.attachDocument();
+    // arming happens HERE and not a moment earlier: markers appearing during the first client
+    // render would disagree with the server's HTML and break hydration. The channel being open
+    // means the app is mounted.
+    this.unwatchSlots = previewSlots.subscribe(this.schedule);
+    previewSlots.arm();
+    this.schedule();
+  };
+
+  private onCommand(command: TPreviewCommand): void {
+    if (command.t === 'armed') this.armed = command.armed;
+    else if (command.t === 'measure') this.schedule();
+    else if (command.t === 'views') {
+      this.options.applyViews?.(command.views);
+      this.schedule();
+    } else if (command.t === 'page') {
+      // the re-render lands after this turn, so the measurement worth reporting is the one the
+      // mutation observer takes then; this one keeps a layout-only change from going unnoticed
+      this.options.applyPage?.(command.page);
+      this.schedule();
+    } else if (command.t === 'landing') {
+      this.options.applyLanding?.(command.at);
+      this.schedule();
+    } else if (command.t === 'reveal') {
+      // scanned rather than selected: node ids come from a content document — any string at all,
+      // and a selector built out of one is a quoting accident waiting to happen
+      for (const element of document.querySelectorAll(NODE_SELECTOR)) {
+        if (element.getAttribute(NODE_ID_ATTRIBUTE) !== command.nodeId) continue;
+        element.firstElementChild?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+        break;
+      }
+    }
+  }
+
+  private attachDocument(): void {
+    for (const type of SUPPRESSED_EVENTS) {
+      document.addEventListener(type, this.onSuppressed, true);
+    }
+    document.addEventListener('pointermove', this.onPointerMove, { capture: true, passive: true });
+    // on the ROOT element and without capture: leaving any nested element would otherwise read as
+    // leaving the preview altogether
+    document.documentElement.addEventListener('pointerleave', this.onPointerLeave, { passive: true });
+    // anything that can move a box: the viewport, scrolling of ANY container (capture — scroll
+    // does not bubble), layout changes, and late-arriving images and fonts
+    window.addEventListener('resize', this.schedule, { passive: true });
+    window.addEventListener('load', this.schedule, { passive: true });
+    document.addEventListener('scroll', this.onScroll, { capture: true, passive: true });
+    if (typeof ResizeObserver !== 'undefined') {
+      this.resizeObserver = new ResizeObserver(() => this.schedule());
+      this.resizeObserver.observe(document.documentElement);
+    }
+    this.mutationObserver.observe(document.documentElement, {
+      subtree: true, childList: true, attributes: true, characterData: true,
+    });
+  }
+
+  private detachDocument(): void {
+    for (const type of SUPPRESSED_EVENTS) {
+      document.removeEventListener(type, this.onSuppressed, true);
+    }
+    document.removeEventListener('pointermove', this.onPointerMove, true);
+    document.documentElement.removeEventListener('pointerleave', this.onPointerLeave);
+    window.removeEventListener('resize', this.schedule);
+    window.removeEventListener('load', this.schedule);
+    document.removeEventListener('scroll', this.onScroll, true);
+    if (this.settleTimer !== null) clearTimeout(this.settleTimer);
+    this.settleTimer = null;
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = null;
+    this.watched.clear();
+    this.mutationObserver.disconnect();
+  }
+
+  private readonly onSuppressed = (event: Event): void => {
+    if (!this.armed) return;
+    event.preventDefault();
+    event.stopPropagation();
+    if (event.type === 'click') {
+      const { ctrlKey, metaKey } = event as MouseEvent;
+      this.send({ t: 'pick', nodeId: nodeIdOf(event.target), part: partOf(event.target), ctrl: ctrlKey || metaKey });
+    }
+  };
+
+  private readonly onPointerMove = (event: Event): void => {
+    if (!this.armed) return;
+    const { clientX, clientY } = event as PointerEvent;
+    this.pointer = { x: clientX, y: clientY };
+    // the position goes out once a frame, however many moves arrive in it
+    this.pointerFrame ??= requestAnimationFrame(() => {
+      this.pointerFrame = null;
+      if (this.pointer) this.send({ t: 'pointer', ...this.pointer, scroll: { x: window.scrollX, y: window.scrollY } });
+    });
+    const nodeId = nodeIdOf(event.target);
+    const part = partOf(event.target);
+    const { ctrlKey, metaKey } = event as PointerEvent;
+    const ctrl = ctrlKey || metaKey;
+    // the modifier changing is worth a report too — the first move after Ctrl goes down re-sends
+    // the same node with the new colouring (a STATIONARY press is the editor realm's to notice:
+    // its key listeners cover that, since suppressed mousedowns keep focus on the editor side)
+    if (nodeId === this.hovered && part === this.hoveredPart && ctrl === this.hoveredCtrl) return;
+    this.hovered = nodeId;
+    this.hoveredPart = part;
+    this.hoveredCtrl = ctrl;
+    this.send({ t: 'hover', nodeId, part, ctrl });
+  };
+
+  private readonly onPointerLeave = (): void => {
+    if (this.hovered === null) return;
+    this.hovered = null;
+    this.hoveredPart = null;
+    this.hoveredCtrl = false;
+    this.send({ t: 'hover', nodeId: null });
+  };
+
+  /**
+   * The page scrolled. Nothing about the layout changed — every block moved by exactly the same
+   * amount — so the editor is told the new POSITION and slides its overlay by the difference. A
+   * full re-measurement here is what made the outlines trail the page by a visible step.
+   *
+   * An inner scroller is a different matter: it moves its own contents and nothing else, so that
+   * one is measured as usual. And once the page settles, one honest measurement follows anyway —
+   * anything fixed or sticky did NOT move with the rest.
+   */
+  private readonly onScroll = (event: Event): void => {
+    const target = event.target;
+    const isPage = target === document || target === document.scrollingElement || target === document.documentElement;
+    if (!isPage) {
+      this.schedule();
+      return;
+    }
+    this.send({ t: 'scroll', x: window.scrollX, y: window.scrollY });
+    if (this.settleTimer !== null) clearTimeout(this.settleTimer);
+    this.settleTimer = setTimeout(this.schedule, SCROLL_SETTLE_MS);
+  };
+
+  /** one measurement per frame however many signals arrive */
+  private readonly schedule = (): void => {
+    if (this.frame !== null) return;
+    this.frame = requestAnimationFrame(() => {
+      this.frame = null;
+      this.measure();
+    });
+  };
+
+  private measure(): void {
+    // A measurement taken while the frame has no viewport is not a measurement: every rect comes
+    // back zero, blocks vanish from the report and the editor's outlines go with them. That is
+    // what a hidden or mid-relayout iframe looks like — the editor re-asks once it is on screen.
+    if (!window.innerWidth || !window.innerHeight) return;
+    const boxes: INodeBox[] = [];
+    // a prefab's blocks report ONE box — their union — under the prefab node's id
+    const unions = new Map<string, INodeBox>();
+    // every prefab whose blocks stand in the DOM — a box or not — is one the realm can re-expand
+    const units = new Set<string>();
+    // …and each of those blocks on its own, for the editor to frame one picked to be seen
+    const parts: INodeBox[] = [];
+    for (const element of document.querySelectorAll(NODE_SELECTOR)) {
+      const shownOwner = unitOwnerOf(element.getAttribute(NODE_ID_ATTRIBUTE) ?? '');
+      if (shownOwner !== null) units.add(shownOwner);
+      const box = boxOf(element, this.range);
+      if (!box) continue;
+      const owner = unitOwnerOf(box.id);
+      if (owner === null) {
+        boxes.push(box);
+        continue;
+      }
+      if (!isOutletReference(element.className)) parts.push(box);
+      const known = unions.get(owner);
+      if (!known) {
+        unions.set(owner, { ...box, id: owner, reference: 'prefab' });
+      } else {
+        const right = Math.max(known.x + known.width, box.x + box.width);
+        const bottom = Math.max(known.y + known.height, box.y + box.height);
+        const x = Math.min(known.x, box.x);
+        const y = Math.min(known.y, box.y);
+        unions.set(owner, { ...known, x, y, width: right - x, height: bottom - y, depth: Math.min(known.depth, box.depth) });
+      }
+    }
+    boxes.push(...unions.values());
+    this.send({
+      t: 'geometry',
+      boxes,
+      units: [...units],
+      parts,
+      slots: this.measureSlots(),
+      viewport: { width: window.innerWidth, height: window.innerHeight },
+      scroll: { x: window.scrollX, y: window.scrollY },
+    });
+  }
+
+  /**
+   * The insertion points, from the slots registered RIGHT NOW. A declaration whose marker is not in
+   * the document is dropped: it belongs to a render that has already been replaced, and an
+   * insertion point nobody can see is worse than none.
+   */
+  private measureSlots(): ISlotBox[] {
+    const markers = new Map<string, Element>();
+    for (const element of document.querySelectorAll(`[${SLOT_ATTRIBUTE}]`)) {
+      markers.set(element.getAttribute(SLOT_ATTRIBUTE)!, element);
+    }
+    const slots: ISlotBox[] = [];
+    const containers = new Set<Element>();
+    for (const raw of previewSlots.list()) {
+      const marker = markers.get(slotKey(raw.ownerId, raw.slot));
+      if (!marker) continue;
+      // inside an expanded layout only the OUTLET is a place for the page's blocks — and that
+      // place belongs to the layout node (its children are what the outlet shows)
+      const owner = unitOwnerOf(raw.ownerId);
+      let declaration = raw;
+      if (owner !== null) {
+        const host = marker.closest(NODE_SELECTOR);
+        if (!host || !isOutletReference(host.className)) continue;
+        declaration = { ...raw, ownerId: owner };
+      }
+      if (marker.parentElement) containers.add(marker.parentElement);
+      const point = marker.getBoundingClientRect();
+      // the marker is sizeless — for an empty slot the area worth highlighting is what encloses it
+      const parent = marker.parentElement?.getBoundingClientRect();
+      slots.push({
+        ...declaration,
+        x: point.x,
+        y: point.y,
+        area: parent ? { x: parent.x, y: parent.y, width: parent.width, height: parent.height } : null,
+      });
+    }
+    this.watchSizes(containers);
+    return slots;
+  }
+
+  /**
+   * Keep an eye on the containers a slot lives in. A container grows the moment a block lands in
+   * it, and that growth is often pure layout — no mutation to notice, no scroll, nothing the other
+   * signals would catch. Only NEW elements are observed: re-observing on every measurement would
+   * make the observer fire on its own output, forever.
+   */
+  private watchSizes(containers: Set<Element>): void {
+    if (!this.resizeObserver) return;
+    for (const element of containers) {
+      if (this.watched.has(element)) continue;
+      this.watched.add(element);
+      this.resizeObserver.observe(element);
+    }
+    for (const element of this.watched) {
+      if (containers.has(element)) continue; // gone from the page, or its slot no longer rendered
+      this.resizeObserver.unobserve(element);
+      this.watched.delete(element);
+    }
+  }
+
+  private send(event: TPreviewEvent): void {
+    this.port?.postMessage(event);
+  }
+}

package/tiles/previewBridge/previewBridge.component.tsx

@@ -0,0 +1,137 @@
+// The editor's agent inside the preview realm, as a MODULE: the render runtime attaches this node
+// under the page root when the canvas asks for an editable preview (see the agent itself in
+// previewAgent.ts). It renders nothing — everything visible is drawn by the editor's overlay, in
+// the editor's own document.
+//
+// A component facet, not a page-level script, on purpose: the agent then arrives, loads and dies
+// through the very protocol it serves — one code path for every module of a page.
+import { defineComponentSide, markInternalTile } from '@mosetta/react';
+import { useComponent, usePreviewType, PALETTE_PREVIEW, useSettings, parseReference } from '@mosetta/react';
+import { useDi } from '@mosetta/react';
+import { PAGE_MANAGER_TOKEN, REF_VIEWS_TOKEN } from '@mosetta/runtime/client';
+import { useEffect, useRef } from 'react';
+import { PreviewAgent, withAgentNode } from './previewAgent';
+import { withLanding } from './landing';
+import { withStandIns } from './standIn';
+import { previewBridgeIdOf, STAND_IN_ATTRIBUTE } from './previewBridgeCommon';
+import type { ILandingPlace } from './previewBridgeCommon';
+
+/**
+ * What a SERVICE module shows as its preview: not its representation (it has none), but what it
+ * is for — the rule for every distribution component without a face.
+ */
+function BridgeAbout() {
+  return (
+    <div style={{ padding: '4px 2px', maxWidth: '260px', color: '#71717a', fontSize: '13px', lineHeight: 1.5 }}>
+      Service module: the editor’s agent inside the live page preview. It connects the page realm
+      to the workbench overlay — geometry, selection, live tree updates — and draws nothing itself.
+    </div>
+  );
+}
+
+function BridgeLive({ disconnected }: { disconnected: readonly string[] }) {
+  // the page MANAGER is how a new tree reaches a mounted application: the editor sends the tree
+  // it holds, this puts it where the root component reads from, and react does the rest
+  const pageManager = useDi(PAGE_MANAGER_TOKEN);
+  // the editor's views of reference providers land in the store every application is born with
+  const views = useDi(REF_VIEWS_TOKEN);
+  // this module's own full name — the node to carry over every incoming tree
+  const self = previewBridgeIdOf(useComponent().reference);
+  // where a block is about to go: every tree that arrives meanwhile gets the landing space too
+  const landing = useRef<ILandingPlace | null>(null);
+
+  useEffect(() => {
+    const agent = new PreviewAgent({
+      // the editor's tree names a disconnected distribution's blocks as they are: here they stand
+      // in, as in the server's first render (standIn.ts)
+      applyPage: (page) => pageManager.setCurrentPage(
+        withLanding(withStandIns(withAgentNode(pageManager.getCurrentPage(), page, self), disconnected, self), landing.current, self),
+      ),
+      applyLanding: (at) => {
+        landing.current = at;
+        pageManager.setCurrentPage(withLanding(pageManager.getCurrentPage(), at, self));
+      },
+      applyViews: (next) => views.set(next),
+    });
+    agent.start();
+    return () => agent.stop();
+  }, [pageManager, views, self, disconnected]);
+  return null;
+}
+
+/**
+ * A STAND-IN for a block whose distribution the project disconnected (standIn.ts): the site shows
+ * nothing there, the editor shows this — the block's name and why it is not on the site. Which
+ * distribution it was, by its title, the editor's settings say (the realm knows no titles).
+ */
+function StandIn({ reference }: { reference: string }) {
+  let name = reference;
+  try {
+    ({ name } = parseReference(reference));
+  } catch {
+    // a reference that is no module's (a prefab's): shown as it is
+  }
+  return (
+    <div {...{ [STAND_IN_ATTRIBUTE]: reference }}
+         style={{
+           display: 'flex',
+           flexDirection: 'column',
+           gap: '4px',
+           boxSizing: 'border-box',
+           minHeight: '64px',
+           padding: '12px 16px',
+           border: '1px dashed #a1a1aa',
+           borderRadius: '6px',
+           background: 'repeating-linear-gradient(135deg, #fafafa 0 8px, #f4f4f5 8px 16px)',
+           color: '#52525b',
+           font: '13px/1.45 ui-sans-serif, system-ui, sans-serif',
+           justifyContent: 'center',
+         }}>
+      <strong style={{ color: '#27272a', fontWeight: 600 }}>{name}</strong>
+      <span>Its tile palette is disconnected from this project — the site does not show this block.</span>
+    </div>
+  );
+}
+
+/**
+ * The LANDING SPACE: a little emptiness where a block is about to go, so the editor can frame the
+ * very spot (the overlay draws on it, this draws nothing). It does not know the layout around it,
+ * and does not need to: a block in flow takes the whole width, a flex row gives it its least width
+ * and stretches it to the row's height, a column or a grid stretches it across.
+ */
+function LandingSpace() {
+  return (
+    <div data-mosetta-landing
+         aria-hidden="true"
+         style={{
+           display: 'block',
+           boxSizing: 'border-box',
+           minWidth: '96px',
+           minHeight: '48px',
+           flex: '0 0 auto',
+           alignSelf: 'stretch',
+           justifySelf: 'stretch',
+           pointerEvents: 'none',
+         }} />
+  );
+}
+
+const NONE: readonly string[] = [];
+
+// By the preview's TYPE, never the flag: a FULL-APP preview (the canvas realm) is exactly where
+// this module WORKS — branching on useIsPreviewMode() would turn the agent into a description
+// card at its own workplace. Only a palette specimen means there is no realm to serve.
+function BridgeComponent() {
+  const { landing, standIn, disconnected } = useSettings<{ landing?: boolean; standIn?: string; disconnected?: readonly string[] }>();
+  const type = usePreviewType();
+  if (landing) return <LandingSpace />;
+  if (standIn) return <StandIn reference={standIn} />;
+  return type === PALETTE_PREVIEW ? <BridgeAbout /> : <BridgeLive disconnected={disconnected ?? NONE} />;
+}
+
+export default markInternalTile(defineComponentSide({
+  Component: BridgeComponent,
+  defaultSettings() {
+    return {};
+  },
+}));

package/tiles/previewBridge/previewBridge.editor.tsx

@@ -0,0 +1,10 @@
+import { defineEditorSide } from '@mosetta/react';
+
+export default defineEditorSide({
+  // a service module previews as a card that says what it is FOR (the component branches on the
+  // host's preview contract) — its working self renders nothing at all
+  preview: 'self',
+  Component() {
+    return <div data-no-settings>This block has no settings.</div>;
+  },
+});