@mosetta/editor 0.0.0-stage → 0.0.29

package/tiles/canvas/canvasTools.ts

@@ -0,0 +1,66 @@
+// EDITOR TOOLS (ADR-0062): a tool is a BLOCK placed in the workbench shell's `tools` slot. The
+// shell does not render it — it hands the canvases the list of tool nodes (EDITOR_TOOLS_TOKEN);
+// a canvas gives each a button on its bar and, pressed, mounts the node over its stage, in a DI
+// scope holding what the tool works on (CANVAS_TOOL_TOKEN). Both tokens are found by NAME: a tool
+// of another distribution declares them under the same names.
+//
+// A tool node is `lazy`: its module stays out of the workbench pages' preloads and loads when the
+// button is first pressed.
+import { SingleDiToken } from '@mosetta/di';
+import type { EditingSession } from '@mosetta/content';
+
+/** a tool as the shell holds it: a node of its `tools` slot */
+export interface IToolNode {
+  readonly id: string;
+  readonly reference: string;
+  readonly slot?: string;
+  readonly settings?: Record<string, unknown>;
+}
+
+/** the tools the workbench offers — the shell's `tools` slot, as nodes */
+export interface IEditorTools {
+  list(): readonly IToolNode[];
+}
+
+export const EDITOR_TOOLS_TOKEN = new SingleDiToken<IEditorTools>('MOSETTA_EDITOR_TOOLS');
+
+/** what a tool mounted over a canvas works on */
+export interface ICanvasToolContext {
+  /** the canvas's session: the draft (or revision) shown, its edits, undo */
+  readonly session: EditingSession;
+  /** the document as a reader gets it — the canvas's preview address without the editor's agent */
+  previewHref(): string;
+  /**
+   * the font faces the canvas's preview has loaded (its `document.fonts`) — which of the fonts a
+   * page declares its text actually uses — once the preview's document is in and its fonts are
+   * ready (a tool opened from the address comes before the preview); empty where the frame cannot
+   * be read or does not come in time
+   */
+  loadedFonts(): Promise<readonly { family: string; weight: string; style: string; unicodeRange: string }[]>;
+  /**
+   * what of the tool is open, in the tool's own words, as it said it last — the workbench keeps it
+   * in the address for the document in front, so a reload or a shared link opens the same; null:
+   * nothing said yet
+   */
+  readState(): string | null;
+  writeState(state: string | null): void;
+  /** put the tool away */
+  close(): void;
+}
+
+export const CANVAS_TOOL_TOKEN = new SingleDiToken<ICanvasToolContext>('MOSETTA_CANVAS_TOOL');
+
+/** the slot of the shell that holds the tools */
+export const TOOLS_SLOT = 'tools';
+
+/** the tool nodes among a block's children */
+export function toolNodesOf<T extends IToolNode>(children: readonly T[]): T[] {
+  return children.filter((child) => child.slot === TOOLS_SLOT);
+}
+
+/** what a tool's button says: its node's `label`, else its block's name */
+export function toolLabelOf(node: IToolNode): string {
+  const label = node.settings?.label;
+  if (typeof label === 'string' && label.trim()) return label.trim();
+  return /_n_(.+?)_v_/.exec(node.reference)?.[1] ?? node.reference;
+}

package/tiles/canvas/chromeNodes.ts

@@ -0,0 +1,35 @@
+// Which blocks bring a control to the canvas tools (providerChrome.tsx). A provider's control sets
+// the editor's view of that provider, kept by its ADDRESS (`i18n`, or `#prices` for one addressed
+// by id) — not by node: the i18n of a page and the one of its frame prefab are edited in one
+// language, and two controls of it would only move together. So one per address, the first in the
+// tree's order; a block that is no provider (a theme) brings its own.
+import { providerAddressOf } from '@mosetta/runtime/client';
+import type { IRefProviderDeclaration } from '@mosetta/runtime/client';
+
+export interface IChromeNode {
+  readonly id: string;
+  readonly reference: string;
+  readonly settings: Record<string, unknown>;
+}
+
+export interface IChromeDeclarations {
+  readonly provides?: IRefProviderDeclaration;
+  readonly editorChrome?: boolean;
+}
+
+export function chromeNodes(
+  nodes: readonly IChromeNode[],
+  declarationsOf: (reference: string) => IChromeDeclarations | null | undefined,
+  hasEditor: (reference: string) => boolean,
+): IChromeNode[] {
+  const addresses = new Set<string>();
+  return nodes.filter((node) => {
+    const declared = declarationsOf(node.reference);
+    if (!(declared?.provides || declared?.editorChrome) || !hasEditor(node.reference)) return false;
+    if (!declared.provides) return true;
+    const address = providerAddressOf(declared.provides, node.id);
+    if (addresses.has(address)) return false;
+    addresses.add(address);
+    return true;
+  });
+}

package/tiles/canvas/ghosts.ts

@@ -0,0 +1,33 @@
+// The overlay's GHOSTS — the places a block may go, tabs glued to the selected block's frame
+// (canvas.component.tsx): which edges they go on is read off the boxes the preview reports.
+
+/** a box on the overlay, in the preview's viewport coordinates */
+export interface IGhostRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** which way the blocks of a slot run: one under another, or side by side */
+export type TAxis = 'column' | 'row';
+
+/** the selection's corner tags stand this tall over its top edge (canvas.css, .canvas-view__tag) */
+export const TAG_HEIGHT = 18;
+
+/**
+ * Which way a block's slot runs, read off the blocks themselves: a neighbour standing BESIDE the
+ * block (sharing at least half its height) means a row. Styles are not read — the editor never
+ * reads them back (a jsdom page would hang on it) and the geometry already says it. A lone block
+ * has no neighbour to tell: it is taken to be in a column, the common case.
+ */
+export function axisAmong(boxes: readonly (IGhostRect | undefined)[], index: number): TAxis {
+  const self = boxes[index];
+  if (!self) return 'column';
+  const beside = (a: IGhostRect | undefined, b: IGhostRect | undefined): boolean => {
+    if (!a || !b) return false;
+    const overlap = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
+    return overlap >= Math.min(a.height, b.height) / 2;
+  };
+  return beside(boxes[index - 1], self) || beside(self, boxes[index + 1]) ? 'row' : 'column';
+}

package/tiles/canvas/insertPopover.tsx

@@ -0,0 +1,56 @@
+// The INSERT POPOVER: a "+" pressed in the preview names a place, and the blocks that can go there
+// open right beside it — search focused, ready to type. Before, the place was named in the preview
+// and the block picked in a palette tab elsewhere in the workbench; the link between the two was
+// a frame colour, and it was not obvious that the next step lived in another panel.
+//
+// The same picker the palette panel shows (content/blockPicker.tsx). Placed like the settings
+// popover (popoverPlacement.ts) — beside the "+" where there is room, never over it. A pick
+// inserts and spends the place, which closes the popover; Escape or × give the place back.
+import type { EditingSession, IInsertionPoint } from '@mosetta/content';
+import { BlockPicker } from '../content/blockPicker';
+import type { IPopoverPlacement } from './popoverPlacement';
+
+/** tall enough for a search and a screenful of blocks; the room there is caps it */
+const INSERT_POPOVER_HEIGHT = 420;
+
+export function InsertPopover({ session, point, placement }: {
+  session: EditingSession;
+  point: IInsertionPoint;
+  placement: IPopoverPlacement;
+}) {
+  const close = () => session.setInsertionPoint(null);
+  const style = {
+    left: `${placement.x}px`,
+    top: `${placement.y}px`,
+    width: `${placement.width}px`,
+    height: `${Math.min(INSERT_POPOVER_HEIGHT, placement.maxHeight)}px`,
+    ...(placement.fromBottom ? { transform: 'translateY(-100%)' } : {}),
+  };
+  return (
+    <div className="canvas-view__settings canvas-view__insert"
+         style={style}
+         data-test-id="canvas-insert-popover"
+         data-insert-side={placement.side}
+         // the canvas's own pointer and key handling is for the page, not for the picker
+         onMouseDown={(e) => e.stopPropagation()}>
+      <div className="canvas-view__settings-head">
+        {/* the place in the preview's own relative words ("add before heading") */}
+        <span className="canvas-view__settings-name">{point.label ?? `insert into ${point.parentId}`}</span>
+        <button type="button"
+                className="canvas-view__settings-action"
+                data-test-id="canvas-insert-close"
+                data-tooltip="Close — nothing is inserted"
+                aria-label="Close the block picker"
+                onClick={close}>
+          ×
+        </button>
+      </div>
+      <div className="canvas-view__insert-body">
+        <BlockPicker session={session}
+                     point={point}
+                     autoFocus
+                     onCancel={close} />
+      </div>
+    </div>
+  );
+}

package/tiles/canvas/popoverPlacement.ts

@@ -0,0 +1,104 @@
+// Where the settings popover goes: beside the selected block, on the side with the most room,
+// never over the block itself — the author types and watches the block change. When no side
+// fits (the page root, a block as wide as the page and as tall as the screen), it docks in the
+// top-right corner of the stage and covers what it must. Beside a block it grows to what its
+// content needs: a form taller than the room below the block's top moves up to fit, as far as
+// the stage allows. Plain geometry, in stage pixels.
+
+export interface IRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface IPopoverPlacement {
+  readonly x: number;
+  /** the popover's top edge — or, when `fromBottom`, its bottom edge */
+  readonly y: number;
+  readonly width: number;
+  readonly maxHeight: number;
+  readonly fromBottom: boolean;
+  readonly side: 'right' | 'left' | 'below' | 'above' | 'dock';
+}
+
+export interface IPlacementOptions {
+  readonly width?: number;
+  /** the distance from the block — negative laps over its frame, so the two join (see seamOf) */
+  readonly gap?: number;
+  /** the distance above the block, when it differs (the selection's corner tags stand there) */
+  readonly gapAbove?: number;
+  readonly margin?: number;
+  /** the least height worth opening a popover above or below a block */
+  readonly minHeight?: number;
+  /** stage pixels reserved at the top (the providers' chrome) */
+  readonly top?: number;
+  /** how tall the content would be with room enough — beside a block, it moves up to fit */
+  readonly contentHeight?: number;
+}
+
+const clamp = (value: number, low: number, high: number) => Math.max(low, Math.min(high, value));
+
+export function placePopover(box: IRect | null, stage: { width: number; height: number }, options: IPlacementOptions = {}): IPopoverPlacement {
+  const { gap = 8, margin = 8, minHeight = 220, top = margin, contentHeight = 0 } = options;
+  const gapAbove = options.gapAbove ?? gap;
+  const width = Math.max(200, Math.min(options.width ?? 340, stage.width - 2 * margin));
+  const bottomEdge = stage.height - margin;
+  const dock: IPopoverPlacement = {
+    x: stage.width - margin - width, y: top, width, maxHeight: Math.max(minHeight, bottomEdge - top), fromBottom: false, side: 'dock',
+  };
+  if (!box) return dock;
+
+  const roomRight = stage.width - margin - (box.x + box.width + gap);
+  const roomLeft = box.x - gap - margin;
+  const roomBelow = bottomEdge - (box.y + box.height + gap);
+  const roomAbove = box.y - gapAbove - top;
+  // beside: level with the block's top — or higher, as far as the content needs — inside the stage
+  const besideTop = clamp(Math.min(box.y, bottomEdge - contentHeight), top, Math.max(top, bottomEdge - minHeight));
+  if (roomRight >= width || roomLeft >= width) {
+    const right = roomRight >= roomLeft;
+    return {
+      x: right ? box.x + box.width + gap : box.x - gap - width,
+      y: besideTop,
+      width,
+      maxHeight: bottomEdge - besideTop,
+      fromBottom: false,
+      side: right ? 'right' : 'left',
+    };
+  }
+  // under or over the block, flush with its left edge — the stage's margin gives way to a block
+  // standing at the very edge, or the two would join with a step
+  const x = clamp(box.x, Math.min(margin, Math.max(0, box.x)), stage.width - margin - width);
+  if (Math.max(roomBelow, roomAbove) >= minHeight) {
+    return roomBelow >= roomAbove
+      ? { x, y: box.y + box.height + gap, width, maxHeight: roomBelow, fromBottom: false, side: 'below' }
+      : { x, y: box.y - gapAbove, width, maxHeight: roomAbove, fromBottom: true, side: 'above' };
+  }
+  return dock;
+}
+
+/**
+ * Where a popover laid against its block JOINS it: the stretch of the popover's own edge that
+ * runs along the block's frame — there the popover draws no border of its own, and its body covers
+ * the frame's, so frame and popover read as one piece. In the popover's own pixels along that edge;
+ * null when they do not touch (docked, above the block's corner tags).
+ */
+export interface ISeam {
+  readonly edge: 'top' | 'left' | 'right';
+  readonly from: number;
+  readonly to: number;
+}
+
+export function seamOf(place: IPopoverPlacement, box: IRect): ISeam | null {
+  if (place.side === 'below') {
+    const from = Math.max(box.x, place.x) - place.x;
+    const to = Math.min(box.x + box.width, place.x + place.width) - place.x;
+    return to > from ? { edge: 'top', from, to } : null;
+  }
+  if (place.side === 'right' || place.side === 'left') {
+    const from = Math.max(0, box.y - place.y);
+    const to = box.y + box.height - place.y;
+    return to > from ? { edge: place.side === 'right' ? 'left' : 'right', from, to } : null;
+  }
+  return null;
+}

package/tiles/canvas/popoverSize.ts

@@ -0,0 +1,87 @@
+// The settings popover's size is the author's: a grip in its free corner resizes it, and the
+// size they last asked for is remembered (localStorage) for every popover after. It is a WISH,
+// not a fixed box — placePopover still fits it beside the block, and a popover opened by a
+// screen edge or in the dock corner gets only the room there is. Plain geometry, stage pixels.
+import type { IPopoverPlacement } from './popoverPlacement';
+
+export interface IPopoverSize {
+  readonly width: number;
+  /** null — as tall as the form, up to the room there is */
+  readonly height: number | null;
+}
+
+export const DEFAULT_POPOVER_SIZE: IPopoverSize = { width: 340, height: null };
+export const MIN_POPOVER_WIDTH = 240;
+export const MIN_POPOVER_HEIGHT = 120;
+
+const STORAGE_KEY = 'mosetta:editor:settings-popover-size';
+
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+
+/** the remembered size; anything unreadable (no storage, a private window, junk) is the default */
+export function readPopoverSize(storage: Pick<Storage, 'getItem'> | null | undefined): IPopoverSize {
+  try {
+    const raw = storage?.getItem(STORAGE_KEY);
+    if (!raw) return DEFAULT_POPOVER_SIZE;
+    const parsed = JSON.parse(raw) as { width?: unknown; height?: unknown };
+    if (!finite(parsed.width)) return DEFAULT_POPOVER_SIZE;
+    return {
+      width: Math.max(MIN_POPOVER_WIDTH, parsed.width),
+      height: finite(parsed.height) ? Math.max(MIN_POPOVER_HEIGHT, parsed.height) : null,
+    };
+  } catch {
+    return DEFAULT_POPOVER_SIZE;
+  }
+}
+
+export function writePopoverSize(storage: Pick<Storage, 'setItem'> | null | undefined, size: IPopoverSize): void {
+  try {
+    storage?.setItem(STORAGE_KEY, JSON.stringify(size));
+  } catch {
+    // no storage (a private window, a quota) — the size lives until the page reloads
+  }
+}
+
+/** which corner is free to move: the one away from the block and from the stage edge it hugs */
+export interface IGripCorner {
+  readonly horizontal: 'left' | 'right';
+  readonly vertical: 'top' | 'bottom';
+}
+
+export function gripCornerOf(placement: IPopoverPlacement): IGripCorner {
+  return {
+    // left of the block, or docked to the right edge: the right edge stays, the left one moves.
+    // Above the block the grip rides the TOP edge, and its right end belongs to the close button
+    // — there the left edge moves (a popover above or below is only clamped sideways anyway)
+    horizontal: placement.side === 'left' || placement.side === 'dock' || placement.fromBottom ? 'left' : 'right',
+    // above the block the popover hangs from its bottom edge — the top one moves
+    vertical: placement.fromBottom ? 'top' : 'bottom',
+  };
+}
+
+export interface IResizedBox {
+  readonly x: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The box while its grip is dragged by (dx, dy) from where the drag started: the edges opposite
+ * the grip stay put, the size follows the pointer within the room the placement had.
+ */
+export function resizeBox(
+  placement: IPopoverPlacement,
+  start: { readonly width: number; readonly height: number },
+  delta: { readonly dx: number; readonly dy: number },
+  stage: { readonly width: number },
+  margin = 8,
+): IResizedBox {
+  const corner = gripCornerOf(placement);
+  const right = placement.x + placement.width; // the fixed edge when the grip is on the left
+  const maxWidth = corner.horizontal === 'right' ? stage.width - margin - placement.x : right - margin;
+  const wanted = start.width + (corner.horizontal === 'right' ? delta.dx : -delta.dx);
+  const width = Math.max(Math.min(MIN_POPOVER_WIDTH, maxWidth), Math.min(maxWidth, wanted));
+  const tall = start.height + (corner.vertical === 'bottom' ? delta.dy : -delta.dy);
+  const height = Math.max(Math.min(MIN_POPOVER_HEIGHT, placement.maxHeight), Math.min(placement.maxHeight, tall));
+  return { x: corner.horizontal === 'right' ? placement.x : right - width, width, height };
+}

package/tiles/canvas/providerChrome.tsx

@@ -0,0 +1,191 @@
+// The CANVAS CONTROLS: what the author may want at hand over the page — the page's own settings,
+// and the STANDING CONTROLS blocks bring (i18n's language being edited, a theme's pick for the
+// canvas) — each behind its own button of the canvas bar: pressed, the control's card opens in
+// the stage's corner; pressed again, it folds. The overlay belongs to the page.
+//
+// A block brings a control when its module says so (`editorChrome`, implied by `provides`) and its
+// editor facet exists: the facet is mounted here with `placement: chrome` and the node's settings
+// as `subject`, through the same mount the settings use for forms. The blocks of the project's
+// prefabs count too — the site's theme lives in its theme prefab. The canvas knows no provider.
+// A provider brings one control per address, not per node (chromeNodes.ts).
+import { ReactNode, useEffect, useMemo, useState } from 'react';
+import { DI_CONTAINER_TOKEN } from '@mosetta/di';
+import { useComponent, useDi } from '@mosetta/react';
+import { useServerAction } from '@mosetta/react/server-action';
+import type { ICatalogEntry, IBlueprintNodeDoc } from '@mosetta/content';
+import { listComponentsToken } from '../content/contentCommon';
+import { hostedPage, hostFallbackOf } from '../content/mountedTree';
+import { useMountedTree } from '../content/useMountedTree';
+import { formRootOf } from '../content/formRoot';
+import { ensureRefsEditing } from '../content/refsEditing';
+import { chromeNodes } from './chromeNodes';
+import type { IChromeNode } from './chromeNodes';
+import { useProjectPrefabs } from '../content/projectPrefabs';
+
+function ProviderChrome({ node, rootReference }: { node: IChromeNode; rootReference: string }) {
+  const fallback = hostFallbackOf(useComponent().reference);
+  // the node is rebuilt on every render of the tools: the mount follows what it IS
+  const subject = JSON.stringify(node.settings);
+  const spec = useMemo(() => ({
+    rootReference,
+    tree: hostedPage(rootReference, [{
+      id: `chrome-${node.id}`,
+      reference: node.reference.replace('_t_component_', '_t_editor_'),
+      settings: { placement: 'chrome', subject: node.settings, subjectId: node.id },
+      children: [],
+    }], fallback),
+  }), [node.id, node.reference, subject, rootReference, fallback]);
+  const { ref, failed } = useMountedTree(spec);
+  if (failed) return null;
+  return <div ref={ref}
+              className="canvas-view__chrome-item"
+              data-provider-chrome={node.id} />;
+}
+
+/** every node of the tree, the blocks of the prefabs it places included (with their expanded ids) */
+function nodesWithPrefabs(doc: IBlueprintNodeDoc, treeOf: (reference: string) => IBlueprintNodeDoc | null): IChromeNode[] {
+  const out: IChromeNode[] = [];
+  const walk = (node: IBlueprintNodeDoc, prefix: string) => {
+    out.push({ id: `${prefix}${node.id}`, reference: node.reference, settings: node.settings ?? {} });
+    const tree = prefix ? null : treeOf(node.reference);
+    for (const inner of tree?.children ?? []) walk(inner, `${node.id}/`);
+    for (const child of node.children ?? []) walk(child, prefix);
+  };
+  walk(doc, '');
+  return out;
+}
+
+const GlobeIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <circle cx="8"
+            cy="8"
+            r="5.8"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.4" />
+    <path d="M2.2 8h11.6M8 2.2c-2 2.2-2 9.4 0 11.6M8 2.2c2 2.2 2 9.4 0 11.6"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.2" />
+  </svg>
+);
+
+const PaletteIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <path d="M8 2.2a5.8 5.8 0 1 0 0 11.6c1 0 1.4-.6 1.1-1.3-.4-.9.2-1.7 1.2-1.7h1.2A2.3 2.3 0 0 0 13.8 8.5 5.8 5.8 0 0 0 8 2.2z"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.4"
+          strokeLinejoin="round" />
+    <circle cx="5.6"
+            cy="7"
+            r="1"
+            fill="currentColor" />
+    <circle cx="8"
+            cy="5.2"
+            r="1"
+            fill="currentColor" />
+    <circle cx="10.6"
+            cy="6.6"
+            r="1"
+            fill="currentColor" />
+  </svg>
+);
+
+const SlidersIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h11"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.4"
+          strokeLinecap="round" />
+    <circle cx="6"
+            cy="4.5"
+            r="1.5"
+            fill="#ffffff"
+            stroke="currentColor"
+            strokeWidth="1.3" />
+    <circle cx="10.5"
+            cy="8"
+            r="1.5"
+            fill="#ffffff"
+            stroke="currentColor"
+            strokeWidth="1.3" />
+    <circle cx="5"
+            cy="11.5"
+            r="1.5"
+            fill="#ffffff"
+            stroke="currentColor"
+            strokeWidth="1.3" />
+  </svg>
+);
+
+/** the page's own settings: a sheet with its lines */
+export const PageSettingsIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <path d="M4 2.5h5.5L12.5 5.5V13.5H4z"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.4"
+          strokeLinejoin="round" />
+    <path d="M9.5 2.5v3h3M6 8.5h4.5M6 10.8h4.5"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.3" />
+  </svg>
+);
+
+const shortName = (reference: string): string => /_n_(.+?)_v_/.exec(reference)?.[1] ?? reference;
+
+/**
+ * A control's glyph and words for the bar, by what its module is: the canvas knows no provider,
+ * but a language and a theme are what blocks bring today, and a globe and a palette read at
+ * once; anything else wears sliders and its own name.
+ */
+export function chromeFaceOf(node: IChromeNode): { icon: ReactNode; label: string } {
+  const name = shortName(node.reference);
+  if (/^(i18n|lang|languages?)$/i.test(name)) return { icon: GlobeIcon, label: 'The language being edited' };
+  if (/^theme/i.test(name)) return { icon: PaletteIcon, label: 'The theme shown on this canvas' };
+  return { icon: SlidersIcon, label: `The ${name} controls` };
+}
+
+/**
+ * The standing controls of the document's blocks (the prefabs it places included), each with the
+ * root to mount its facet under. Recomputed as modules arrive — a control may appear late.
+ */
+export function useChromeNodes(doc: IBlueprintNodeDoc | null): { chromes: readonly IChromeNode[]; rootOf: (node: IChromeNode) => string } {
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const self = useComponent().reference;
+  const [, setLoads] = useState(0);
+  const refs = ensureRefsEditing(di);
+  // a module the realm was loading arrived — a control may have appeared
+  useEffect(() => refs.subscribe(() => setLoads((n) => n + 1)), [refs]);
+  const project = useProjectPrefabs();
+  // shares the pages view's and the picker's cache entry — no extra request
+  const catalog = useServerAction({ token: listComponentsToken, input: {} });
+  const components: readonly ICatalogEntry[] = catalog.isSuccess() && catalog.serverData.ok ? catalog.serverData.components : [];
+  const chromes = doc
+    ? chromeNodes(
+      nodesWithPrefabs(doc, (reference) => project.treeOf(reference)?.doc ?? null),
+      (reference) => refs.declarations(reference),
+      (reference) => components.find((c) => c.id === reference)?.hasEditor === true,
+    )
+    : [];
+  return { chromes, rootOf: (node) => formRootOf(components, node.reference, self) };
+}
+
+/** the open control's card, in the stage's corner */
+export function ChromeCard({ node, rootReference }: { node: IChromeNode; rootReference: string }) {
+  return (
+    <div className="canvas-view__chrome"
+         data-test-id="canvas-provider-chrome"
+         data-chrome-open={node.id}>
+      <ProviderChrome node={node}
+                      rootReference={rootReference} />
+    </div>
+  );
+}

package/tiles/canvas/scrollWatch.ts

@@ -0,0 +1,43 @@
+// Whether the previewed page is being scrolled: from its first move until a fresh measurement
+// arrives (the preview's agent measures once the page settles) — or, should none come (a
+// cross-origin preview, a stalled agent), until a lull. It tells only the START and the END:
+// a scroll moves the page every frame, and a state change per frame is what makes an editor lag.
+export interface IScrollWatch {
+  /** the page moved */
+  moved(): void;
+  /** a fresh measurement arrived: the scroll is over */
+  settled(): void;
+  dispose(): void;
+}
+
+export function scrollWatch(onChange: (scrolling: boolean) => void, lullMs: number, timers: Pick<typeof globalThis, 'setTimeout' | 'clearTimeout'> = globalThis): IScrollWatch {
+  let moving = false;
+  let lull: ReturnType<typeof setTimeout> | null = null;
+  const settled = (): void => {
+    if (lull !== null) timers.clearTimeout(lull);
+    lull = null;
+    if (!moving) return;
+    moving = false;
+    onChange(false);
+  };
+  return {
+    moved() {
+      if (!moving) {
+        moving = true;
+        onChange(true);
+      }
+      if (lull !== null) timers.clearTimeout(lull);
+      lull = timers.setTimeout(settled, lullMs);
+    },
+    settled,
+    dispose() {
+      if (lull !== null) timers.clearTimeout(lull);
+      lull = null;
+    },
+  };
+}
+
+/** a box out of the stage's sight: wholly above, below or beside it */
+export function outOfSight(box: { x: number; y: number; width: number; height: number }, stage: { width: number; height: number }): boolean {
+  return box.y + box.height <= 0 || box.y >= stage.height || box.x + box.width <= 0 || box.x >= stage.width;
+}