@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/content/settingsDraft.ts

@@ -0,0 +1,178 @@
+// THE DRAFT the workbench exposes to hosted settings forms — registered in the WORKBENCH's own
+// container under a named token; the form reads it through the parent-container door
+// (PARENT_DI_TOKEN → SETTINGS_DRAFT_TOKEN). One store for the workbench's lifetime, reading
+// whatever is selected when asked: selecting another node hands the same store a new subject.
+//
+// REFERENCES: the form sees VALUES. A setting bound to a provider (`{ "$ref": "i18n/k3" }`) is
+// shown as the provider hands it out in the author's current view, and an edit of it goes to the
+// provider's settings (refsEditing.ts) — one undoable step either way. A snapshot keeps its
+// identity while nothing it shows changed, as the store contract requires.
+import { DiContainer } from '@mosetta/di';
+import { editingSessionHubOf, EditingSession, findNodeDoc } from '@mosetta/content';
+import type { IPageMetaWords } from '@mosetta/content';
+import { isRefValue } from '@mosetta/runtime/client';
+import type { IRefTreeNode } from '@mosetta/runtime/client';
+import { EDITOR_VIEWS_TOKEN, SETTINGS_DRAFT_TOKEN } from '@mosetta/react';
+import type { IFieldBinding } from '@mosetta/react';
+import { ensureRefsEditing } from './refsEditing';
+import { ensurePrefabTrees, isPartId, prefabPartOf } from './prefabParts';
+
+/** the settings of a node that has none — one object, so a snapshot never changes identity */
+const NO_SETTINGS: Record<string, unknown> = {};
+
+interface IShown {
+  readonly settings: Record<string, unknown>;
+  readonly doc: unknown;
+  readonly views: unknown;
+  readonly result: Record<string, unknown>;
+}
+
+const sameValues = (a: Record<string, unknown>, b: Record<string, unknown>): boolean => {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => Object.is(a[key], b[key]));
+};
+
+/**
+ * Brought into being on first use, like the session — it belongs to the WORKBENCH, not to the
+ * host that happened to ask first. So it follows the hub's SELECTION facade — the session where
+ * the last pick happened — never the asking canvas's own session: with two canvases (a duplicate
+ * opens a second one), a draft bound to the first would show the first canvas's selection in the
+ * second one's popover and write the second one's edits into the first.
+ */
+export function ensureSettingsDraft(di: DiContainer, asking: EditingSession): void {
+  if (di.hasByToken(SETTINGS_DRAFT_TOKEN)) return;
+  const hub = editingSessionHubOf(di);
+  const session = hub?.selection ?? asking;
+  // a provider's chrome asks about the page in the canvas being worked in — the ACTIVE one; the
+  // last pick may live in another canvas, with another page
+  const working = hub?.active ?? asking;
+  const listeners = new Set<() => void>();
+  let shown: IShown | null = null;
+  const refs = ensureRefsEditing(di);
+  const trees = ensurePrefabTrees(di);
+  // a provider's module arrived, or a prefab's tree: what the form shows may resolve differently now
+  const changed = () => {
+    shown = null;
+    for (const listener of [...listeners]) listener();
+  };
+  refs.subscribe(changed);
+  trees.subscribe(changed);
+
+  /**
+   * The node the draft is about, in the document it lives in. A PREFAB's block selected on a page
+   * (prefabParts.ts) lives in the prefab's own document — its settings and the providers its
+   * references read are there — and is shown, never written (`part`).
+   */
+  const current = () => {
+    const now = session.snapshot();
+    const id = now.selectedNodeId;
+    const own = now.doc && id ? findNodeDoc(now.doc, id) : null;
+    const part = !own && now.doc && isPartId(id) ? prefabPartOf(now.doc, id, trees.treeOf) : null;
+    if (part) return { now, node: part.node, doc: part.prefab.doc as unknown as IRefTreeNode, part: true };
+    return { now, node: own, doc: now.doc as unknown as IRefTreeNode | null, part: false };
+  };
+  // the document a scope question is about: the selected node's, or — a provider named — the
+  // working canvas's, with the provider's id
+  const scopeOf = (providerId?: string): { doc: IRefTreeNode | null; id: string | null } => {
+    if (providerId) return { doc: working.snapshot().doc, id: providerId };
+    const { node, doc } = current();
+    return { doc, id: node?.id ?? null };
+  };
+
+  di.registerValueOfToken(SETTINGS_DRAFT_TOKEN, {
+    snapshot: () => {
+      const { now, node, doc } = current();
+      if (!node || !doc) return NO_SETTINGS;
+      const settings = node.settings ?? NO_SETTINGS;
+      if (!Object.values(settings).some(isRefValue)) return settings;
+      if (shown && shown.settings === settings && shown.doc === doc && shown.views === now.views) return shown.result;
+      const result = refs.resolve(doc, node.id, settings, now.views);
+      // another node's edit elsewhere must not hand the form a new object
+      if (shown && shown.settings === settings && sameValues(shown.result, result)) {
+        shown = { ...shown, doc, views: now.views };
+        return shown.result;
+      }
+      shown = { settings, doc, views: now.views, result };
+      return result;
+    },
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      const off = session.subscribe(listener);
+      // the working canvas too: a chrome follows its page, the form its selection
+      const offWorking = working !== session ? working.subscribe(listener) : () => undefined;
+      return () => {
+        listeners.delete(listener);
+        off();
+        offWorking();
+      };
+    },
+    update: (patch: Record<string, unknown>) => {
+      const { now, node, doc, part } = current();
+      if (!node || !doc || part) return;
+      session.updateNodesSettings(refs.writePatches(doc, node.id, node.settings ?? {}, patch, now.views));
+    },
+    binding: (field: string): IFieldBinding => {
+      const { node, doc } = current();
+      if (!node || !doc) return { provider: null, providers: [] };
+      const value = node.settings?.[field];
+      const provider = isRefValue(value) ? value.$ref.split('/')[0] : null;
+      return { provider, providers: refs.reachable(doc, node.id, field) };
+    },
+    bind: (field: string, provider: string, key?: string) => {
+      const { now, node, doc, part } = current();
+      if (!node || !doc || part) return;
+      session.updateNodesSettings(refs.bindPatches(doc, node.id, node.settings ?? {}, field, provider, now.views, key));
+    },
+    unbind: (field: string) => {
+      const { node, doc, part } = current();
+      if (!node || !doc || part) return;
+      session.updateNodesSettings(refs.unbindPatches(doc, node.id, node.settings ?? {}, field));
+    },
+    bindScope: async () => {
+      const start = current();
+      if (!start.node || !start.doc || start.part) return 0;
+      await refs.loadAll(start.doc);
+      // the author may have picked another node — or edited this document — meanwhile
+      const { now, node, doc } = current();
+      if (!node || !doc || node.id !== start.node.id) return 0;
+      const { patches, bound } = refs.bindScopePatches(doc, node.id, now.views);
+      session.updateNodesSettings(patches);
+      return bound;
+    },
+    // the provider asked about: the node selected — or another named (a provider's chrome)
+    usedKeys: (providerId?: string) => {
+      const { doc, id } = scopeOf(providerId);
+      return id && doc ? refs.usedKeys(doc, id) : [];
+    },
+    outline: (providerId?: string) => {
+      const { doc, id } = scopeOf(providerId);
+      return id && doc ? refs.outline(doc, id) : [];
+    },
+    hover: (nodeId: string | null) => session.hoverNode(nodeId),
+    pageMeta: (providerId?: string) => {
+      const now = providerId ? working.snapshot() : current().now;
+      // a prefab says nothing about itself — it has no meta to translate
+      return now.kind === 'pages' ? now.doc?.meta ?? {} : null;
+    },
+    setPageMetaWords: (byLang: Readonly<Record<string, IPageMetaWords>>) => {
+      if (current().now.kind === 'pages') session.setPageMetaWords(byLang);
+    },
+    node: () => current().node?.id ?? null,
+  });
+}
+
+/**
+ * The provider views, workbench-wide: a provider's chrome in the canvas corner sets them (i18n:
+ * the language being edited), forms read references through them, canvases preview them.
+ */
+export function ensureEditorViews(di: DiContainer, session: EditingSession): void {
+  if (di.hasByToken(EDITOR_VIEWS_TOKEN)) return;
+  const hub = editingSessionHubOf(di);
+  di.registerValueOfToken(EDITOR_VIEWS_TOKEN, hub
+    ? { snapshot: hub.viewsSnapshot, subscribe: hub.subscribeViews, set: (name: string, view: unknown) => hub.setView(name, view) }
+    : {
+      snapshot: () => session.snapshot().views,
+      subscribe: session.subscribe,
+      set: (name: string, view: unknown) => session.setView(name, view),
+    });
+}

package/tiles/content/settingsIssues.tsx

@@ -0,0 +1,124 @@
+// WHAT DOES NOT FIT, shown where it is edited. A block that describes its settings (its catalog
+// entry's settings schema, ADR-0066) has them checked as they are written: the form's fields that
+// hold a value the block does not take wear a red border, and a plaque above the form names every
+// issue — a click puts the caret in its field. The draft keeps saving as before (the form writes
+// through, nothing is held back); publishing is what refuses settings that do not fit.
+import { useEffect } from 'react';
+import type { RefObject } from 'react';
+import type { INodeSettingsIssue } from '@mosetta/settings/check';
+
+/** the form's field an issue is about: the field named by its path, or by a part of it (`values` for `values.t51`) */
+export function fieldOfIssue(path: string, fields: readonly string[]): string | null {
+  let best: string | null = null;
+  for (const field of fields) {
+    if (path !== field && !path.startsWith(`${field}.`)) continue;
+    if (!best || field.length > best.length) best = field;
+  }
+  return best;
+}
+
+const isPlain = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * The patch that takes the setting at `path` out of `settings` — the top key it lies under, with
+ * it gone (a key set to undefined is dropped when the draft is saved)
+ */
+export function removalPatch(settings: Readonly<Record<string, unknown>>, path: string): Record<string, unknown> {
+  const [top, ...rest] = path.split('.');
+  const without = (value: unknown, keys: readonly string[]): unknown => {
+    if (!keys.length || !isPlain(value)) return undefined;
+    const [key, ...deeper] = keys;
+    if (!(key in value)) return value;
+    const { [key]: inner, ...others } = value;
+    if (!deeper.length) return others;
+    return { ...others, [key]: without(inner, deeper) };
+  };
+  return { [top]: rest.length ? without(settings[top], rest) : undefined };
+}
+
+const fieldsIn = (root: HTMLElement): HTMLElement[] => [...root.querySelectorAll<HTMLElement>('[data-field]')];
+
+const INVALID = 'data-mosetta-invalid';
+
+export function SettingsIssues({ issues, container, onRemove }: {
+  issues: readonly INodeSettingsIssue[];
+  container: RefObject<HTMLElement | null>;
+  /** takes a setting the block does not have out of the node; absent — nothing may be changed */
+  onRemove?: (path: string) => void;
+}) {
+  // the fields an issue is about wear the mark — kept on them when the form renders anew. After the
+  // commit, not in its layout phase: the plaque stands BEFORE the form, and the form's element is
+  // not in `container` yet when an earlier sibling's layout effect runs
+  const paths = issues.map((issue) => issue.path).join('|');
+  useEffect(() => {
+    const root = container.current;
+    if (!root) return undefined;
+    const wrong = paths ? paths.split('|') : [];
+    const mark = () => {
+      const elements = fieldsIn(root);
+      const fields = elements.map((el) => el.getAttribute('data-field') ?? '');
+      const invalid = new Set(wrong.map((path) => fieldOfIssue(path, fields)).filter((field): field is string => field !== null));
+      for (const el of elements) {
+        const on = invalid.has(el.getAttribute('data-field') ?? '');
+        if (on !== el.hasAttribute(INVALID)) {
+          if (on) el.setAttribute(INVALID, '');
+          else el.removeAttribute(INVALID);
+        }
+      }
+    };
+    mark();
+    const view = root.ownerDocument.defaultView;
+    const watch = view?.MutationObserver ? new view.MutationObserver(mark) : null;
+    watch?.observe(root, { subtree: true, childList: true });
+    return () => {
+      watch?.disconnect();
+      for (const el of root.querySelectorAll(`[${INVALID}]`)) el.removeAttribute(INVALID);
+    };
+  }, [container, paths]);
+
+  if (!issues.length) return null;
+  const focus = (path: string) => {
+    const root = container.current;
+    if (!root) return;
+    const elements = fieldsIn(root);
+    const field = fieldOfIssue(path, elements.map((el) => el.getAttribute('data-field') ?? ''));
+    elements.find((el) => el.getAttribute('data-field') === field)?.focus();
+  };
+  const by = issues.find((issue) => issue.by)?.by;
+  return (
+    <div className="settings__issues"
+         data-test-id="settings-issues"
+         role="alert">
+      <div className="settings__issues-title">
+        {issues.length === 1 ? 'A setting does not fit this block' : `${issues.length} settings do not fit this block`}
+        {' '}— the page is not published until it does
+      </div>
+      <ul className="settings__issues-list">
+        {issues.map((issue) => (
+          <li key={`${issue.path}:${issue.message}`}
+              className="settings__issue-row">
+            <button type="button"
+                    className="settings__issue"
+                    data-test-id="settings-issue"
+                    data-issue-path={issue.path}
+                    data-issue-kind={issue.kind}
+                    onClick={() => focus(issue.path)}>
+              {issue.path ? <code>{issue.path}</code> : null}
+              {' '}
+              {issue.message}
+            </button>
+            {/* a setting the block does not have has no field to fix it in — it can only go */}
+            {issue.kind === 'unknown' && onRemove ? (
+              <button type="button"
+                      className="settings__issue-remove"
+                      data-test-id="settings-issue-remove"
+                      data-tooltip="Take this setting out — the block does not have it"
+                      onClick={() => onRemove(issue.path)}>Remove</button>
+            ) : null}
+          </li>
+        ))}
+      </ul>
+      {by ? <div className="settings__issues-note">Checked by the block's version {by}: its own version describes nothing.</div> : null}
+    </div>
+  );
+}

package/tiles/content/themeScope.ts

@@ -0,0 +1,72 @@
+// The THEMES AROUND a node, as the editor sees them — what the styler offers a block to name
+// (`var(--theme-accent)`) and what the canvas's theme control switches. A theme is any node whose
+// settings are theme settings (@mosetta/core theme.ts): a theme block on the node's path from the
+// root, or one a prefab on that path wraps its outlet in (the site's theme prefab around the page).
+import { cleanThemeSettings, themeVariable } from '@mosetta/core';
+import type { IStyleVariable, IThemeSettings, IThemeVariant } from '@mosetta/core';
+import { isOutletReference } from '@mosetta/content';
+import type { IBlueprintNodeDoc } from '@mosetta/content';
+
+/** the editor view a theme is previewed under: the canvas's pick, never the reader's */
+export const themeViewName = (storageKey: string): string => `theme:${storageKey}`;
+
+export interface IThemeView {
+  readonly id: string;
+}
+
+type TTreeOf = (reference: string) => IBlueprintNodeDoc | null;
+
+/** the nodes from the root down to the node's parent; empty when the node is not in the tree */
+function pathTo(root: IBlueprintNodeDoc, id: string): IBlueprintNodeDoc[] {
+  if (root.id === id) return [];
+  for (const child of root.children ?? []) {
+    const below = pathTo(child, id);
+    if (below.length || child.id === id) return [root, ...below];
+  }
+  return [];
+}
+
+/** the themes a prefab wraps its outlet in, outermost first */
+function themesAroundOutlet(root: IBlueprintNodeDoc): IThemeSettings[] {
+  const walk = (node: IBlueprintNodeDoc, around: IThemeSettings[]): IThemeSettings[] | null => {
+    if (isOutletReference(node.reference)) return around;
+    const own = cleanThemeSettings(node.settings);
+    const next = own ? [...around, own] : around;
+    for (const child of node.children ?? []) {
+      const found = walk(child, next);
+      if (found) return found;
+    }
+    return null;
+  };
+  return walk(root, []) ?? [];
+}
+
+/** every theme around the node, outermost first */
+export function themesAround(doc: IBlueprintNodeDoc, nodeId: string, treeOf: TTreeOf): IThemeSettings[] {
+  return pathTo(doc, nodeId).flatMap((node) => {
+    const own = cleanThemeSettings(node.settings);
+    const tree = treeOf(node.reference);
+    return [...(own ? [own] : []), ...(tree ? themesAroundOutlet(tree) : [])];
+  });
+}
+
+/** the theme the author is looking at: the canvas's pick for it, else its default */
+export function shownTheme(settings: IThemeSettings, views: Readonly<Record<string, unknown>>): IThemeVariant {
+  const view = views[themeViewName(settings.storageKey)] as IThemeView | null | undefined;
+  return settings.themes.find((t) => t.id === view?.id)
+    ?? settings.themes.find((t) => t.id === settings.defaultTheme)
+    ?? settings.themes[0];
+}
+
+/** the variables a style may name around the node — an inner theme overrides an outer one, key by key */
+export function themeVariablesAround(themes: readonly IThemeSettings[], views: Readonly<Record<string, unknown>>): IStyleVariable[] {
+  const byKey = new Map<string, IStyleVariable>();
+  for (const settings of themes) {
+    const shown = shownTheme(settings, views);
+    for (const v of settings.variables) {
+      const value = shown?.values[v.key];
+      byKey.set(v.key, { name: themeVariable(v.key), label: v.label, kind: v.kind, ...(value ? { value } : {}) });
+    }
+  }
+  return [...byKey.values()];
+}

package/tiles/content/themeVariables.ts

@@ -0,0 +1,47 @@
+// The theme variables around the selected node as the workbench exposes them to the forms it
+// mounts (EDITOR_THEME_VARIABLES_TOKEN): a store the settings host FEEDS from the document, the
+// project's prefabs and the author's views — a block's styler only reads it.
+import { useEffect, useMemo } from 'react';
+import { DI_CONTAINER_TOKEN, DiContainer } from '@mosetta/di';
+import { EDITOR_THEME_VARIABLES_TOKEN, useDi } from '@mosetta/react';
+import type { IThemeVariablesContract } from '@mosetta/react';
+import type { IStyleVariable } from '@mosetta/core';
+import type { IEditingState } from '@mosetta/content';
+import { useProjectPrefabs } from './projectPrefabs';
+import { themesAround, themeVariablesAround } from './themeScope';
+
+class ThemeVariablesStore implements IThemeVariablesContract {
+  private variables: readonly IStyleVariable[] = [];
+
+  private readonly listeners = new Set<() => void>();
+
+  readonly snapshot = () => this.variables;
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  set(variables: readonly IStyleVariable[]): void {
+    if (JSON.stringify(variables) === JSON.stringify(this.variables)) return;
+    this.variables = variables;
+    for (const listener of [...this.listeners]) listener();
+  }
+}
+
+function ensureThemeVariables(di: DiContainer): ThemeVariablesStore {
+  if (!di.hasByToken(EDITOR_THEME_VARIABLES_TOKEN)) di.registerValueOfToken(EDITOR_THEME_VARIABLES_TOKEN, new ThemeVariablesStore());
+  return di.getByToken(EDITOR_THEME_VARIABLES_TOKEN) as ThemeVariablesStore;
+}
+
+/** keeps the workbench's store fed with the variables around the node the settings are about */
+export function useFeedThemeVariables(state: IEditingState): void {
+  const store = ensureThemeVariables(useDi(DI_CONTAINER_TOKEN));
+  const project = useProjectPrefabs();
+  const variables = useMemo(() => (state.doc && state.selectedNodeId
+    ? themeVariablesAround(themesAround(state.doc, state.selectedNodeId, (reference) => project.treeOf(reference)?.doc ?? null), state.views)
+    : []), [state.doc, state.selectedNodeId, state.views, project]);
+  useEffect(() => store.set(variables), [store, variables]);
+}

package/tiles/content/tooltipPlacement.ts

@@ -0,0 +1,17 @@
+// Where a workbench tooltip goes (tooltips.tsx): below the element it explains, left edges
+// aligned; above it when there is no room below; always inside the window. Viewport pixels.
+
+/** the gap between the element and its bubble, and the least distance to the window's edge */
+const GAP = 6;
+const MARGIN = 8;
+
+export function placeTooltip(
+  anchor: { left: number; top: number; bottom: number },
+  bubble: { width: number; height: number },
+  view: { width: number; height: number },
+): { left: number; top: number } {
+  const below = anchor.bottom + GAP;
+  const top = below + bubble.height <= view.height - MARGIN ? below : Math.max(MARGIN, anchor.top - GAP - bubble.height);
+  const left = Math.max(MARGIN, Math.min(anchor.left, view.width - MARGIN - bubble.width));
+  return { left, top };
+}

package/tiles/content/tooltips.tsx

@@ -0,0 +1,131 @@
+// The workbench's TOOLTIPS: one mechanism for every panel. An element says what a click on it
+// will do in `data-tooltip`; the panel wraps its root in <TooltipHost>, which shows that text
+// the moment the pointer (or the keyboard focus) lands on the element — no delay, unlike the
+// browser's native `title`, which waits a second and looks like a different application.
+//
+// Delegated, not per element: the host listens once (React events bubble through portals too,
+// so a dialog a panel portals out still gets its tooltips) and the innermost `data-tooltip` wins —
+// a button inside a clickable row explains the button, the rest of the row explains the row.
+//
+// The bubble is portalled onto the document body, positioned `fixed` next to the element: the
+// panels scroll and clip, and a tooltip drawn inside them would be cut at their edge. Its look is
+// INLINE, not a stylesheet, so it is the same whichever module shows it (a fallback included).
+// Its text size is the workbench scale's (workbenchScale.css): the bubble is wrapped in the scope
+// class of the module around the element — a module's css reaches only inside that class, and
+// the scale's variables with it. No getComputedStyle: it is slow, and in a test DOM it can hang.
+import { CSSProperties, ReactNode, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { placeTooltip } from './tooltipPlacement';
+
+export const TOOLTIP_ATTR = 'data-tooltip';
+
+function tooltipTargetOf(node: EventTarget | null): HTMLElement | null {
+  const el = node && (node as Node).nodeType === 1 ? (node as Element) : (node as Node | null)?.parentElement ?? null;
+  const target = el?.closest(`[${TOOLTIP_ATTR}]`) ?? null;
+  return target && target.getAttribute(TOOLTIP_ATTR) ? (target as HTMLElement) : null;
+}
+
+const BUBBLE_STYLE: CSSProperties = {
+  position: 'fixed',
+  top: 0,
+  left: 0,
+  zIndex: 10000,
+  maxWidth: 320,
+  padding: '4px 8px',
+  borderRadius: 5,
+  background: '#27272a',
+  color: '#ffffff',
+  fontFamily: 'ui-sans-serif, system-ui, sans-serif',
+  fontSize: 'var(--mosetta-wb-font-xs, 12px)',
+  lineHeight: 1.4,
+  whiteSpace: 'normal',
+  overflowWrap: 'anywhere',
+  pointerEvents: 'none',
+  boxShadow: '0 4px 12px rgb(0 0 0 / 20%)',
+};
+
+/** the scope class of the nearest module around the element ('' outside every module) */
+function scopeClassOf(target: HTMLElement): string {
+  for (let el: Element | null = target; el; el = el.parentElement) {
+    for (const name of el.classList) {
+      if (name.startsWith('_ns_')) return name;
+    }
+  }
+  return '';
+}
+
+function Bubble({ target }: { target: HTMLElement }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [text, setText] = useState(() => target.getAttribute(TOOLTIP_ATTR) ?? '');
+  // the element may change what it says while it is pointed at (an armed trash asks again)
+  useEffect(() => {
+    const Observer = target.ownerDocument.defaultView?.MutationObserver;
+    setText(target.getAttribute(TOOLTIP_ATTR) ?? '');
+    if (!Observer) return undefined;
+    const observer = new Observer(() => setText(target.getAttribute(TOOLTIP_ATTR) ?? ''));
+    observer.observe(target, { attributes: true, attributeFilter: [TOOLTIP_ATTR] });
+    return () => observer.disconnect();
+  }, [target]);
+  // placed before paint, measured as rendered: no frame shows it anywhere else
+  useLayoutEffect(() => {
+    const el = ref.current;
+    const view = target.ownerDocument.defaultView;
+    if (!el || !view) return;
+    const at = placeTooltip(target.getBoundingClientRect(), el.getBoundingClientRect(), { width: view.innerWidth, height: view.innerHeight });
+    el.style.left = `${at.left}px`;
+    el.style.top = `${at.top}px`;
+  }, [target, text]);
+  if (!text) return null;
+  return createPortal(
+    <div className={scopeClassOf(target)}
+         style={{ display: 'contents' }}>
+      <div ref={ref}
+           style={BUBBLE_STYLE}
+           role="tooltip"
+           data-test-id="workbench-tooltip">
+        {text}
+      </div>
+    </div>,
+    target.ownerDocument.body,
+  );
+}
+
+/**
+ * Shows the `data-tooltip` of whatever element inside it is pointed at or focused. A layout-free
+ * wrapper (display: contents) — put it around a panel's root.
+ */
+export function TooltipHost({ children }: { children: ReactNode }) {
+  const [target, setTarget] = useState<HTMLElement | null>(null);
+  const follow = useCallback((node: EventTarget | null) => setTarget(tooltipTargetOf(node)), []);
+  // a target that leaves the document (its row was re-rendered away) takes its bubble along
+  useEffect(() => {
+    if (!target) return undefined;
+    const view = target.ownerDocument.defaultView;
+    const check = () => {
+      if (!target.isConnected) setTarget(null);
+    };
+    const hide = () => setTarget(null);
+    const timer = view?.setInterval(check, 300);
+    // anything that moves the element under the pointer makes the bubble lie about where it is
+    view?.addEventListener('scroll', hide, true);
+    view?.addEventListener('resize', hide);
+    return () => {
+      if (timer !== undefined) view?.clearInterval(timer);
+      view?.removeEventListener('scroll', hide, true);
+      view?.removeEventListener('resize', hide);
+    };
+  }, [target]);
+  return (
+    <div style={{ display: 'contents' }}
+         onPointerOver={(e) => follow(e.target)}
+         onPointerLeave={() => setTarget(null)}
+         onFocus={(e) => follow(e.target)}
+         onBlur={() => setTarget(null)}
+         // the click happens — what it will do is no longer news, and the bubble would cover
+         // whatever the click opens
+         onPointerDown={() => setTarget(null)}>
+      {children}
+      {target ? <Bubble target={target} /> : null}
+    </div>
+  );
+}

package/tiles/content/treeMounter.ts

@@ -0,0 +1,33 @@
+// The MOUNTER's DI face: the mechanism (mountedTree.ts) hung into the container, so that any
+// code with a DiContainer — a panel in any binding, a service, a test — can host someone else's
+// application. `useMountedTree` is merely the react adapter over this.
+//
+// Registered as a CLASS, not a prebuilt value: its one dependency is the modules holder, which
+// every application container carries — so construction is the container's job. (EditingAutosave
+// next door is built by hand for a reason this service does not have: it needs the caller's module
+// reference and a manual server-data handle, which a container cannot know by itself.)
+import { DI_CONTAINER_TOKEN, DiContainer, DiInject, DiService, SingleDiToken } from '@mosetta/di';
+import { TILES_HOLDER_TOKEN } from '@mosetta/runtime/client';
+import { MountedTree } from './mountedTree';
+
+export const TREE_MOUNTER_TOKEN = new SingleDiToken<TreeMounter>('TREE_MOUNTER_TOKEN');
+
+@DiService(TREE_MOUNTER_TOKEN)
+export class TreeMounter {
+  constructor(
+    @DiInject(TILES_HOLDER_TOKEN) private readonly holder: typeof TILES_HOLDER_TOKEN.tokenType,
+    // the mounter's own container IS the host application's — every mounted application gets it
+    // as its parent (IMountOptions.parentDi, the Unity door)
+    @DiInject(DI_CONTAINER_TOKEN) private readonly di: DiContainer,
+  ) {}
+
+  create(): MountedTree {
+    return new MountedTree(this.holder, this.di);
+  }
+}
+
+/** brought into being on first use, like the session — it belongs to the workbench, not a panel */
+export function ensureTreeMounter(di: DiContainer): TreeMounter {
+  if (!di.hasByToken(TREE_MOUNTER_TOKEN)) di.registerServices(TreeMounter);
+  return di.getByToken(TREE_MOUNTER_TOKEN);
+}