@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/content/blockPicker.tsx

@@ -0,0 +1,501 @@
+// The BLOCK PICKER: what can be inserted, and the insert itself. One component for the two places
+// that offer blocks — the canvas's insert popover (opened by a "+" in the preview) and the docked
+// palette panel.
+//
+// - the site's own published PREFABS first — placed LIVE (a node referencing the prefab: a change
+//   published to it reaches every page), first in a search too — then the REAL provider catalog
+//   (the `content` server module). A prefab being edited is offered no prefab: one level only;
+// - a SEARCH field on top: empty, the list is grouped by provider in folding branches; typed, it
+//   is one flat list ranked by fuzzySearch (typos and the other keyboard layout forgiven), the
+//   matched letters lit. Arrows walk the list, Enter inserts, Escape gives up;
+// - a pick INSERTS at the picked place: a block's module is loaded through the holder to seed its
+//   settings from defaultSettings() (copy-on-insert — the runtime never merges settings);
+// - holding a row shows the block in a preview bubble (componentPreview.tsx);
+// - a row wears its block's ICON, a branch its distribution's icon and name (ADR-0059): a shape
+//   and a colour are found before a word is read;
+// - the blocks inserted LAST lead the list (Recently used, five of them): the same few blocks —
+//   an image, a text — are what one reaches for again and again. Kept in this browser, per site.
+import { ReactNode, useEffect, useMemo, useRef, useState } from 'react';
+import { TILES_HOLDER_TOKEN } from '@mosetta/runtime/client';
+import { useDi, useLocalStorageKey } from '@mosetta/react';
+import { useServerAction } from '@mosetta/react/server-action';
+import { EServerActionStart } from '@mosetta/server-action/client';
+import { DI_CONTAINER_TOKEN } from '@mosetta/di';
+import { compareVersions, EditingSession, ICatalogEntry, IInsertionPoint, prefabReference } from '@mosetta/content';
+import type { IDistributionEntry, ILibraryPrefabEntry } from '@mosetta/content';
+import type { IBlueprintNode } from '@mosetta/core';
+import { listComponentsToken } from './contentCommon';
+import { publishVocabulary } from './blockVocabulary';
+import { ComponentPreview, IPreviewTarget } from './componentPreview';
+import { useProjectPrefabs } from './projectPrefabs';
+import type { IPrefabTree } from './contentCommon';
+import { rankFuzzy } from './fuzzySearch';
+import type { IPathMatch } from '../pagesPanel/pagesSearch';
+import './workbenchScale.css';
+import './blockPicker.css';
+import { SearchField } from './searchField';
+import { useDisabledDistributions } from './disconnected';
+import { catalogVersions } from './catalogVersions';
+
+interface IComponentModuleShape {
+  defaultSettings?: () => Record<string, unknown>;
+}
+
+/** which branches the user folded away — an arrangement, like the dock's; never content */
+export const COLLAPSED_KEY = 'mosetta-editor:palette-collapsed';
+
+/**
+ * How long a row must be held before its preview appears. Sweeping the list would otherwise mount
+ * a module tree per row it passed under — and fire whatever those modules ask their server for.
+ */
+const PREVIEW_DELAY_MS = 200;
+
+/** the branch the site's own prefabs fold under — first of all */
+const PREFABS_BRANCH = 'prefabs of this site';
+
+/** flat (a search) or among the recent, a row says where it comes from — and at which version */
+const tagOf = (item: { readonly branch: string; readonly component?: ICatalogEntry }): string => (item.component
+  ? `${item.component.reference.namespace}@${item.component.reference.version}`
+  : item.branch);
+
+/** the branch of the blocks inserted last — above everything */
+const RECENT_BRANCH = 'recently used';
+
+/** what was inserted last, newest first — a habit of this browser, never content */
+export const RECENT_BLOCKS_KEY = 'mosetta-editor:recent-blocks';
+const RECENT_BLOCKS = 5;
+
+/** one thing the picker offers */
+interface IPickItem {
+  readonly key: string;
+  readonly kind: 'prefab' | 'component';
+  /** what the row says */
+  readonly label: string;
+  /** what the search matches against */
+  readonly text: string;
+  /** the branch it folds under (the provider, or "layouts") */
+  readonly branch: string;
+  readonly component?: ICatalogEntry;
+  readonly prefab?: IPrefabTree;
+  /** a prefab a LIBRARY brings: placed live, in its distribution's branch */
+  readonly library?: ILibraryPrefabEntry;
+}
+
+/** the label with the matched letters lit */
+function Lit({ text, match }: { text: string; match: IPathMatch | null }) {
+  if (!match || match.indices.length === 0) return <>{text}</>;
+  const lit = new Set(match.indices);
+  const parts: ReactNode[] = [];
+  let run = '';
+  let runLit = lit.has(0);
+  const flush = (key: number) => {
+    if (run) parts.push(runLit ? <mark key={key}>{run}</mark> : run);
+    run = '';
+  };
+  for (let i = 0; i < text.length; i += 1) {
+    if (lit.has(i) !== runLit) {
+      flush(i);
+      runLit = lit.has(i);
+    }
+    run += text[i];
+  }
+  flush(text.length);
+  return <>{parts}</>;
+}
+
+const PrefabIcon = (
+  <svg viewBox="0 0 24 24"
+       aria-hidden="true">
+    <rect width="24"
+          height="24"
+          rx="6"
+          fill="#7c3aed" />
+    <path d="M6 7.5h12v4H6zM6 14h5v3.5H6zM13 14h5v3.5h-5z"
+          fill="none"
+          stroke="#fff"
+          strokeWidth="1.6"
+          strokeLinejoin="round" />
+  </svg>
+);
+
+/** a row's picture: the block's own icon, the prefab mark, or its initial on a quiet tile */
+function BlockIcon({ item }: { item: IPickItem }) {
+  if (item.kind === 'prefab') return <span className="block-picker__icon">{PrefabIcon}</span>;
+  const url = item.component?.iconUrl;
+  return url ? (
+    <img className="block-picker__icon"
+         src={url}
+         alt=""
+         loading="lazy"
+         draggable={false} />
+  ) : (
+    <span className="block-picker__icon block-picker__icon--initial"
+          aria-hidden="true">{item.label.slice(0, 1).toUpperCase()}</span>
+  );
+}
+
+/** a branch's words: its distribution's icon and title (its namespace and version beside), or the raw name */
+function BranchTitle({ branch, distribution }: { branch: string; distribution: IDistributionEntry | undefined }) {
+  if (!distribution) return <>{branch}</>;
+  return (
+    <>
+      {distribution.iconUrl ? <img className="block-picker__branch-icon"
+                                   src={distribution.iconUrl}
+                                   alt=""
+                                   draggable={false} /> : null}
+      <span>{distribution.title}</span>
+    </>
+  );
+}
+
+/**
+ * The version a branch offers (ADR-0061): the latest by default; with several deployed, a choice —
+ * a page may want a block at the version its others are at.
+ */
+function BranchVersion({ namespace, versions, chosen, onChoose }: {
+  namespace: string;
+  versions: readonly string[];
+  chosen: string | undefined;
+  onChoose: (version: string) => void;
+}) {
+  if (versions.length < 2) {
+    return <span className="block-picker__branch-id">{`${namespace}@${chosen ?? versions[0] ?? ''}`}</span>;
+  }
+  return (
+    <select className="block-picker__version"
+            data-test-id="palette-branch-version"
+            aria-label={`The version of ${namespace} to insert`}
+            value={chosen}
+            onClick={(e) => e.stopPropagation()}
+            onChange={(e) => onChoose(e.target.value)}>
+      {versions.map((version, i) => (
+        <option key={version}
+                value={version}>
+          {i === 0 ? `${version} · latest` : version}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+export interface IBlockPickerProps {
+  readonly session: EditingSession;
+  /** the place a pick inserts into; null — the rows only show, there is nowhere to put a block */
+  readonly point: IInsertionPoint | null;
+  /** the search takes the focus on mount (the popover opens to be typed into) */
+  readonly autoFocus?: boolean;
+  /** Escape in the search: the caller closes what it opened */
+  readonly onCancel?: () => void;
+  /** a specimen catalog instead of the server's (a palette preview); no layouts, nothing remembered */
+  readonly specimen?: readonly ICatalogEntry[];
+}
+
+export function BlockPicker({ session, point, autoFocus, onCancel, specimen }: IBlockPickerProps) {
+  const catalog = useServerAction({ token: listComponentsToken, input: {}, ...(specimen ? { start: EServerActionStart.START_MANUAL } : {}) });
+  const holder = useDi(TILES_HOLDER_TOKEN);
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const project = useProjectPrefabs(!specimen);
+  const editingPrefab = session.snapshot().kind === 'prefabs';
+  const collapsed = useLocalStorageKey<string[]>(COLLAPSED_KEY, []);
+  const recent = useLocalStorageKey<string[]>(RECENT_BLOCKS_KEY, []);
+  const [term, setTerm] = useState('');
+  const [active, setActive] = useState(0);
+  const [preview, setPreview] = useState<IPreviewTarget | null>(null);
+  const previewTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const searchRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLUListElement>(null);
+
+  // the catalog in hand names the blocks a TEXT paste builds with — told once, workbench-wide
+  useEffect(() => {
+    if (catalog.isSuccess() && catalog.serverData.ok) publishVocabulary(di, catalog.serverData.components);
+  }, [catalog, di]);
+  useEffect(() => {
+    if (autoFocus) searchRef.current?.focus();
+  }, [autoFocus]);
+  useEffect(() => () => {
+    if (previewTimer.current !== null) clearTimeout(previewTimer.current);
+  }, []);
+
+  // a distribution the project disconnected offers its blocks no more (ADR-0059)
+  const disabled = useDisabledDistributions();
+  const components: readonly ICatalogEntry[] = specimen
+    ?? (catalog.isSuccess() && catalog.serverData.ok
+      ? catalog.serverData.components.filter((c) => !disabled.includes(c.reference.namespace))
+      : []);
+  // what each provider calls itself — a branch shows its icon and title instead of its namespace
+  const distributions: readonly IDistributionEntry[] = !specimen && catalog.isSuccess() && catalog.serverData.ok
+    ? catalog.serverData.distributions ?? []
+    : [];
+  // the prefabs the libraries bring — one each, whatever versions of its distribution are deployed:
+  // a library prefab is LIVE, the page always takes its current form
+  // (a tool's own — the editor's workbench — is no prefab for authors)
+  const libraryPrefabs: readonly ILibraryPrefabEntry[] = useMemo(() => {
+    const all = !specimen && catalog.isSuccess() && catalog.serverData.ok ? catalog.serverData.prefabs ?? [] : [];
+    const internal = new Set(distributions.filter((d) => d.internal).map((d) => d.namespace));
+    const seen = new Set<string>();
+    return all.filter((p) => !disabled.includes(p.namespace) && !internal.has(p.namespace) && !seen.has(p.reference) && Boolean(seen.add(p.reference)));
+  }, [catalog, specimen, disabled, distributions]);
+  // every version deployed stays in the catalog: a branch is a distribution, offering ONE version
+  // of it — the latest, unless the author chose another (ADR-0061)
+  const versions = useMemo(() => catalogVersions(components, distributions), [components, distributions]);
+  const [chosen, setChosen] = useState<Readonly<Record<string, string>>>({});
+  const versionOf = (namespace: string) => chosen[namespace] ?? versions.latest(namespace);
+  const offered = (c: ICatalogEntry) => {
+    const version = versionOf(c.reference.namespace);
+    return version === undefined || compareVersions(c.reference.version, version) === 0;
+  };
+  const distributionOf = (branch: string) => {
+    const version = versionOf(branch);
+    return version === undefined ? undefined : versions.distribution(branch, version);
+  };
+
+  const items = useMemo((): IPickItem[] => [
+    ...(specimen || editingPrefab || !project.namespace ? [] : project.prefabs.map((prefab): IPickItem => ({
+      key: prefabReference(project.namespace!, prefab.name),
+      kind: 'prefab',
+      label: prefab.name,
+      text: prefab.name,
+      branch: PREFABS_BRANCH,
+      prefab,
+    }))),
+    // a page ROOT is not a block: it is what a page names as its own root, it takes the tree as a
+    // prop and can never be someone's child. Nor is an INTERNAL block — a tool's own (an editor
+    // panel, the editor's fallback: `markInternalTile`). The build marks both; the picker skips them.
+    ...components.filter((c) => !c.isRoot && !c.internal).map((c): IPickItem => ({
+      key: c.id,
+      kind: 'component',
+      label: c.reference.name,
+      text: c.reference.name,
+      branch: c.reference.namespace,
+      component: c,
+    })),
+    ...(editingPrefab ? [] : libraryPrefabs.map((p): IPickItem => ({
+      key: p.reference,
+      kind: 'prefab',
+      label: p.name,
+      text: p.name,
+      branch: p.namespace,
+      library: p,
+    }))),
+  ], [components, project, specimen, editingPrefab, libraryPrefabs]);
+  // the rows of the versions on offer — the recent list keeps a block at whatever version it was
+  const shown = useMemo(() => items.filter((item) => !item.component || offered(item.component)), [items, chosen, versions]);
+
+  const searching = term.trim() !== '';
+  // the site's own prefabs lead a search too: they are what this site is made of
+  const ranked = useMemo(() => {
+    if (!searching) return [];
+    const found = rankFuzzy(shown, term, (item) => item.text);
+    return [...found.filter((r) => r.item.kind === 'prefab'), ...found.filter((r) => r.item.kind !== 'prefab')];
+  }, [shown, term, searching]);
+
+  // a specimen shows every branch open and remembers nothing: the fold is the REAL workbench's
+  const isCollapsed = (branch: string) => !specimen && collapsed.value.includes(branch);
+  const groups = new Map<string, IPickItem[]>();
+  // the blocks used last first — those still offered (a block that left the catalog is skipped);
+  // each a row of its own here, beside its place in its provider's branch
+  const recentItems = specimen ? [] : recent.value
+    .map((key) => items.find((item) => item.key === key))
+    .filter((item): item is IPickItem => item !== undefined)
+    .map((item): IPickItem => ({ ...item, branch: RECENT_BRANCH }));
+  if (recentItems.length) groups.set(RECENT_BRANCH, recentItems);
+  for (const item of shown) groups.set(item.branch, [...(groups.get(item.branch) ?? []), item]);
+  // the rows the keyboard walks: the ranked list, or every row of an open branch
+  const visible: IPickItem[] = searching
+    ? ranked.map(({ item }) => item)
+    : [...groups].flatMap(([branch, list]) => (isCollapsed(branch) ? [] : list));
+  const activeIndex = Math.min(active, Math.max(0, visible.length - 1));
+  useEffect(() => setActive(0), [term]);
+
+  const dropPreview = () => {
+    if (previewTimer.current !== null) clearTimeout(previewTimer.current);
+    previewTimer.current = null;
+    setPreview(null);
+  };
+
+  // a block's OWN library may ship a root module (the catalog marks one), and that root is who
+  // knows how to render its blocks — a provider on another binding is hosted through it
+  const libraryRootOf = (component: ICatalogEntry) => components.find((entry) => entry.isRoot
+    && entry.reference.namespace === component.reference.namespace
+    && entry.reference.version === component.reference.version)?.id;
+
+  const armPreview = (item: IPickItem, row: HTMLElement) => {
+    if (previewTimer.current !== null) clearTimeout(previewTimer.current);
+    // a prefab is shown as it is: its own blocks under its own root
+    if (item.prefab) {
+      const { top, left, right } = row.getBoundingClientRect();
+      const { doc } = item.prefab;
+      previewTimer.current = setTimeout(() => setPreview({
+        reference: item.key,
+        hasEditor: true,
+        anchor: { top, left, right },
+        tree: { rootReference: doc.reference, children: doc.children as unknown as IBlueprintNode[] },
+      }), PREVIEW_DELAY_MS);
+      return;
+    }
+    // a preview is DECLARED on the editor facet; without one there is nothing to show
+    const component = item.component;
+    if (!component?.hasEditor) {
+      setPreview(null);
+      return;
+    }
+    const { top, left, right } = row.getBoundingClientRect();
+    previewTimer.current = setTimeout(() => setPreview({
+      reference: component.id,
+      hasEditor: component.hasEditor,
+      libraryRoot: libraryRootOf(component),
+      anchor: { top, left, right },
+    }), PREVIEW_DELAY_MS);
+  };
+
+  const pick = async (item: IPickItem | undefined) => {
+    if (!item || !point || !session.snapshot().doc) return;
+    dropPreview();
+    if (!specimen) recent.setValue([item.key, ...recent.value.filter((key) => key !== item.key)].slice(0, RECENT_BLOCKS));
+    // placed LIVE: the node names the prefab; its blocks come from its published revision
+    if (item.kind === 'prefab') {
+      session.insertNode(item.key, {});
+      return;
+    }
+    const loaded: { module?: unknown } | undefined = holder.loadModule
+      ? await holder.loadModule(item.key)
+      : holder.getModule(item.key);
+    const mod = loaded?.module as IComponentModuleShape | undefined;
+    session.insertNode(item.key, mod?.defaultSettings ? mod.defaultSettings() : {});
+  };
+
+  const toggleBranch = (branch: string) => {
+    dropPreview();
+    if (specimen) return;
+    collapsed.setValue(isCollapsed(branch)
+      ? collapsed.value.filter((name) => name !== branch)
+      : [...collapsed.value, branch]);
+  };
+
+  // the keyboard's row stays in sight
+  useEffect(() => {
+    listRef.current?.querySelector('[data-active]')?.scrollIntoView?.({ block: 'nearest' });
+  }, [activeIndex, term]);
+
+  const row = (item: IPickItem, match: IPathMatch | null) => {
+    const index = visible.indexOf(item);
+    return (
+      <li key={item.key}
+          className={`block-picker__item${index === activeIndex ? ' block-picker__item--active' : ''}${point ? '' : ' block-picker__item--inert'}`}
+          data-active={index === activeIndex || undefined}
+          data-recent={item.branch === RECENT_BRANCH || undefined}
+          {...(item.kind === 'prefab'
+            ? { 'data-test-id': 'palette-prefab-row', 'data-prefab': item.label }
+            : { 'data-test-id': 'palette-item-row', 'data-component': item.key, 'data-has-editor': item.component!.hasEditor })}
+          onMouseEnter={(e) => {
+            setActive(index);
+            armPreview(item, e.currentTarget);
+          }}
+          onMouseLeave={dropPreview}
+          onClick={point ? () => void pick(item) : undefined}>
+        <BlockIcon item={item} />
+        <span className="block-picker__name"><Lit text={item.label}
+                                                  match={match} /></span>
+        {/* a library's prefab is placed live — it says so beside its name */}
+        {item.library ? <span className="block-picker__branch-tag"
+                              title="Placed live: the page always takes this prefab's current form">live</span> : null}
+        {/* a search is flat; a recent block at another version than its branch offers says which */}
+        {searching || (item.branch === RECENT_BRANCH && item.component && !offered(item.component))
+          ? <span className="block-picker__branch-tag">{tagOf(item)}</span>
+          : null}
+      </li>
+    );
+  };
+
+  const loading = !specimen && catalog.isLoading();
+  const failure = specimen ? null
+    : catalog.isError() ? catalog.serverError.code
+      : catalog.isSuccess() && !catalog.serverData.ok ? catalog.serverData.code : null;
+
+  return (
+    <div className="block-picker"
+         data-test-id="block-picker"
+         onScroll={dropPreview}>
+      <SearchField className="block-picker__search-field">
+        <input ref={searchRef}
+               className="block-picker__search"
+               data-test-id="block-picker-search"
+               type="search"
+               placeholder="Search blocks — typos and the other keyboard layout are fine"
+               value={term}
+               spellCheck={false}
+               autoComplete="off"
+               onChange={(e) => setTerm(e.target.value)}
+               onKeyDown={(e) => {
+                 if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+                   e.preventDefault();
+                   dropPreview();
+                   const step = e.key === 'ArrowDown' ? 1 : -1;
+                   setActive((visible.length + activeIndex + step) % Math.max(1, visible.length));
+                 } else if (e.key === 'Enter') {
+                   e.preventDefault();
+                   void pick(visible[activeIndex]);
+                 } else if (e.key === 'Escape') {
+                   e.preventDefault();
+                   e.stopPropagation();
+                   if (term) setTerm('');
+                   else onCancel?.();
+                 }
+               }} />
+      </SearchField>
+      {loading ? <div className="block-picker__note">Loading blocks…</div> : null}
+      {failure ? <div className="block-picker__error">blocks failed to load: {failure}</div> : null}
+      <ul ref={listRef}
+          className="block-picker__list">
+        {searching ? (
+          ranked.length === 0
+            ? <li className="block-picker__note">Nothing matches “{term.trim()}”</li>
+            : ranked.map(({ item, match }) => row(item, match))
+        ) : [...groups].map(([branch, list]) => (
+          <li key={branch}
+              className="block-picker__branch"
+              data-branch={branch}
+              data-collapsed={isCollapsed(branch) || undefined}>
+            <div className="block-picker__branch-head">
+              <button type="button"
+                      className="block-picker__branch-title"
+                      data-test-id="palette-branch-toggle"
+                      data-action="toggle-branch"
+                      aria-expanded={!isCollapsed(branch)}
+                      onClick={() => toggleBranch(branch)}>
+                <span className="block-picker__chevron"
+                      aria-hidden="true">
+                  <svg viewBox="0 0 10 10">
+                    <path d="M3 1.5L6.5 5L3 8.5"
+                          fill="none"
+                          stroke="currentColor"
+                          strokeWidth="1.6" />
+                  </svg>
+                </span>
+                <BranchTitle branch={branch}
+                             distribution={distributionOf(branch)} />
+              </button>
+              {branch === RECENT_BRANCH || branch === PREFABS_BRANCH ? null : (
+                <BranchVersion namespace={branch}
+                               versions={versions.versions(branch)}
+                               chosen={versionOf(branch)}
+                               onChoose={(version) => {
+                                 dropPreview();
+                                 setChosen({ ...chosen, [branch]: version });
+                               }} />
+              )}
+            </div>
+            {!isCollapsed(branch) && (
+              <ul className="block-picker__leaves">
+                {list.map((item) => row(item, null))}
+              </ul>
+            )}
+          </li>
+        ))}
+      </ul>
+      {/* always rendered: the preview application lives as long as the picker, and a new row
+            only hands it a new tree (ADR-0034) */}
+      <ComponentPreview target={preview} />
+    </div>
+  );
+}

package/tiles/content/blockUpgrades.ts

@@ -0,0 +1,145 @@
+// UPDATING blocks to their newer versions (ADR-0061): a page names each block at the version it was
+// placed with, a newer one is never taken by itself — the author updates in a draft, sees the
+// preview, publishes. What is outdated, how a block's settings move to its new version, and the
+// hook every panel reads it through (the tree's marks, the settings' line, the toolbar's window).
+import { useMemo } from 'react';
+import { useServerAction } from '@mosetta/react/server-action';
+import { EServerActionStart } from '@mosetta/server-action/client';
+import type { ITilesHolder } from '@mosetta/runtime/client';
+import { compareVersions } from '@mosetta/content';
+import type { ICatalogEntry, IDistributionEntry, IBlueprintNodeDoc } from '@mosetta/content';
+import { listComponentsToken } from './contentCommon';
+import { catalogVersions } from './catalogVersions';
+import type { ICatalogVersions, IUpgrade } from './catalogVersions';
+import { disconnectedOf, useDisabledDistributions } from './disconnected';
+import { loadModule } from './mountedTree';
+
+/** a node of the document whose block has a newer version */
+export interface IOutdatedNode {
+  readonly nodeId: string;
+  readonly settings: Record<string, unknown>;
+  readonly upgrade: IUpgrade;
+}
+
+/**
+ * The document's outdated nodes, in document order — the root included (a page's root is a block
+ * too). A placed prefab names no version (it is live), a block of a disconnected distribution is
+ * left out by the site and offered nothing.
+ */
+export function outdatedNodes(doc: IBlueprintNodeDoc | null, versions: ICatalogVersions, disabled: readonly string[] = []): IOutdatedNode[] {
+  if (!doc) return [];
+  const found: IOutdatedNode[] = [];
+  // a tool's own blocks (the editor's page root) follow the framework the page runs on — no
+  // update to offer on every page whenever the tool is released
+  const tool = (reference: string) => {
+    const at = versions.upgradeOf(reference);
+    return at !== null && versions.distribution(at.namespace, at.toVersion)?.internal === true;
+  };
+  const walk = (node: IBlueprintNodeDoc) => {
+    const upgrade = disconnectedOf(node.reference, disabled) || tool(node.reference) ? null : versions.upgradeOf(node.reference);
+    if (upgrade) found.push({ nodeId: node.id, settings: node.settings ?? {}, upgrade });
+    for (const child of node.children ?? []) walk(child);
+  };
+  walk(doc);
+  return found;
+}
+
+/**
+ * The document with its TOOLS at their latest (ADR-0061) — what the server renders and so what a
+ * preview realm holds: the page names the editor's root at the version it was made with, the
+ * realm runs the latest. A document with nothing to lead comes back as it is.
+ */
+export function withLatestTools<T extends IBlueprintNodeDoc>(doc: T, versions: ICatalogVersions): T {
+  const visit = (node: IBlueprintNodeDoc): IBlueprintNodeDoc => {
+    const reference = versions.leadTool(node.reference);
+    const own = node as IBlueprintNodeDoc & { fallback?: unknown };
+    const fallback = typeof own.fallback === 'string' ? versions.leadTool(own.fallback) : own.fallback;
+    const children = node.children.map(visit);
+    if (reference === node.reference && fallback === own.fallback && children.every((child, i) => child === node.children[i])) return node;
+    return { ...node, reference, ...(typeof own.fallback === 'string' ? { fallback } : {}), children };
+  };
+  return visit(doc) as T;
+}
+
+/** what the updates window shows of one distribution: from which versions to which, and its blocks */
+export interface IUpgradeGroup {
+  readonly namespace: string;
+  readonly title: string;
+  readonly toVersion: string;
+  /** the versions the page's blocks are at now, the oldest first */
+  readonly fromVersions: readonly string[];
+  /** each block of it the page holds, with how many */
+  readonly blocks: readonly { readonly name: string; readonly count: number }[];
+  /** what each version on the way says it changed */
+  readonly changes: readonly { readonly version: string; readonly changes: string }[];
+}
+
+export function upgradeGroups(outdated: readonly IOutdatedNode[], versions: ICatalogVersions): IUpgradeGroup[] {
+  const byNamespace = new Map<string, IOutdatedNode[]>();
+  for (const node of outdated) byNamespace.set(node.upgrade.namespace, [...(byNamespace.get(node.upgrade.namespace) ?? []), node]);
+  return [...byNamespace].map(([namespace, nodes]) => {
+    const toVersion = versions.latest(namespace) ?? nodes[0].upgrade.toVersion;
+    const fromVersions = [...new Set(nodes.map((n) => n.upgrade.fromVersion))].sort(compareVersions);
+    const counts = new Map<string, number>();
+    for (const node of nodes) counts.set(node.upgrade.name, (counts.get(node.upgrade.name) ?? 0) + 1);
+    return {
+      namespace,
+      title: versions.distribution(namespace, toVersion)?.title ?? namespace,
+      toVersion,
+      fromVersions,
+      blocks: [...counts].map(([name, count]) => ({ name, count })),
+      changes: versions.changesBetween(namespace, fromVersions[0], toVersion),
+    };
+  });
+}
+
+interface IUpgradingFacet {
+  upgrade?: (settings: Record<string, unknown>, from: string) => Record<string, unknown>;
+}
+
+interface IDefaultsFacet {
+  defaultSettings?: () => Record<string, unknown>;
+}
+
+/**
+ * The settings a block takes at its new version: its new defaults, under what the page had set —
+ * moved through the new version's own `upgrade` when it declares one.
+ */
+export async function upgradedSettings(holder: ITilesHolder, node: IOutdatedNode, hasEditor: boolean): Promise<Record<string, unknown>> {
+  const [component, editor] = await Promise.all([
+    loadModule(holder, node.upgrade.to),
+    hasEditor ? loadModule(holder, node.upgrade.to.replace('_t_component_', '_t_editor_')) : Promise.resolve(undefined),
+  ]);
+  const defaults = (component?.module as IDefaultsFacet | undefined)?.defaultSettings?.() ?? {};
+  const upgrade = (editor?.module as IUpgradingFacet | undefined)?.upgrade;
+  const moved = upgrade ? upgrade(node.settings, node.upgrade.fromVersion) : node.settings;
+  return { ...defaults, ...moved };
+}
+
+/** the session's change for each node, settings migrated — what `upgradeNodes` takes in one step */
+export async function upgradeChanges(holder: ITilesHolder, nodes: readonly IOutdatedNode[], components: readonly ICatalogEntry[]) {
+  return Promise.all(nodes.map(async (node) => ({
+    nodeId: node.nodeId,
+    reference: node.upgrade.to,
+    settings: await upgradedSettings(holder, node, components.find((c) => c.id === node.upgrade.to)?.hasEditor ?? false),
+  })));
+}
+
+const NO_COMPONENTS: readonly ICatalogEntry[] = [];
+const NO_DISTRIBUTIONS: readonly IDistributionEntry[] = [];
+
+/** the catalog's versions, and the document's outdated nodes against them */
+export function useUpgrades(doc: IBlueprintNodeDoc | null, asking = true): {
+  versions: ICatalogVersions;
+  components: readonly ICatalogEntry[];
+  outdated: readonly IOutdatedNode[];
+} {
+  // shares the picker's cache entry (same token and input) — no extra request; a specimen asks nothing
+  const catalog = useServerAction({ token: listComponentsToken, input: {}, ...(asking ? {} : { start: EServerActionStart.START_MANUAL }) });
+  const disabled = useDisabledDistributions();
+  const components: readonly ICatalogEntry[] = catalog.isSuccess() && catalog.serverData.ok ? catalog.serverData.components : NO_COMPONENTS;
+  const distributions: readonly IDistributionEntry[] = catalog.isSuccess() && catalog.serverData.ok ? catalog.serverData.distributions ?? NO_DISTRIBUTIONS : NO_DISTRIBUTIONS;
+  const versions = useMemo(() => catalogVersions(components, distributions), [components, distributions]);
+  const outdated = useMemo(() => outdatedNodes(doc, versions, disabled), [doc, versions, disabled]);
+  return { versions, components, outdated };
+}