@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/pagesPanel/pagesPanel.component.tsx

@@ -0,0 +1,1645 @@
+import { defineComponentSide, markInternalTile } from '@mosetta/react';
+import { ensureQueryParams } from '@mosetta/runtime/dom';
+import { useServerAction } from '@mosetta/react/server-action';
+import { Link, tileScopeClass, useComponent, useDi, useDiOptional, useRoute, useSettings } from '@mosetta/react';
+import { ROUTER_TOKEN } from '@mosetta/runtime/client';
+import { DI_CONTAINER_TOKEN } from '@mosetta/di';
+import '../content/workbenchScale.css';
+import './pagesPanel.css';
+import { createContext, ReactNode, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { EServerActionStart } from '@mosetta/server-action/client';
+import { ContentKind, EditingSession, editingSessionHubOf, ENTITY_NAME_RE, IPageDoc, PREFAB_CANVAS_PATTERN } from '@mosetta/content';
+import type { ITileReference } from '@mosetta/core';
+import {
+  createPageDraftToken,
+  createPageToken,
+  deletePageToken,
+  discardPageDraftToken,
+  forkPageDraftToken,
+  IPageDraftListItem,
+  IPageListEntry,
+  listComponentsToken,
+  listPagesToken,
+  loadPageDraftToken,
+  loadPageToken,
+  publishPageToken,
+  refreshLiveSiteToken,
+} from '../content/contentCommon';
+import { useEditingSession } from '../content/useEditingSession';
+import { TooltipHost } from '../content/tooltips';
+import { SearchField } from '../content/searchField';
+import { noticesOf } from '../content/editingNotices';
+import { PublishModal } from '../content/publishModal';
+import { WORKSPACE_TOKEN } from '../workbench/workspace';
+import { basePathOf, DISTRIBUTIONS_SEGMENT, IOpenDoc, kindOfSegment, parseWorkbenchPath, pathOfView } from '../workbench/workbenchAddress';
+import { DistributionsView } from '../content/distributions';
+import { fittingTags, groupKeyOf, IPathMatch, nameFromPattern, rankPaths } from './pagesSearch';
+import { buildRouteTree, IRouteTreeNode } from './routeTree';
+
+/** the search term rides the address like the open tabs do */
+export const PAGES_SEARCH_PARAM = 'pagesSearch';
+
+/**
+ * What the panel lists — the site's PAGES, or its PREFABS — and the words it uses for them. One
+ * panel for both: the same versions, drafts, publishing and canvases; a prefab is named, not
+ * routed, and opens in a canvas as a page whose root is its own.
+ */
+interface IEntityWords {
+  readonly kind: ContentKind;
+  readonly noun: string;
+  readonly title: string;
+  readonly searchParam: string;
+}
+
+const PAGE_WORDS: IEntityWords = { kind: 'pages', noun: 'page', title: 'Pages', searchParam: PAGES_SEARCH_PARAM };
+const PREFAB_WORDS: IEntityWords = { kind: 'prefabs', noun: 'prefab', title: 'Prefabs', searchParam: 'prefabsSearch' };
+
+const EntityWords = createContext<IEntityWords>(PAGE_WORDS);
+
+interface IPagesPanelSettings {
+  /** what the panel lists: the pages (the default), or the prefabs */
+  readonly kind?: ContentKind;
+  /**
+   * The COMPACT list: routes grouped by their first segment, one row each — the quick picker a
+   * popover shows beside the editor. Without it, the pages stand as a TREE of their routes, the
+   * way the Pages view of the workbench shows them (a prefab has no route: its list is flat
+   * either way).
+   */
+  readonly compact?: boolean;
+  /**
+   * The list's kind read from a parameter of the page's ROUTE (`/workbench/{kind}` names it
+   * `kind`): one list page of the workbench shows the pages or the prefabs by its address
+   * (ADR-0051 §4). A parameter naming neither says so instead of a list.
+   */
+  readonly kindParam?: string;
+}
+
+/** a page as the panel presents it: the ROUTE is the identity on screen, the name stays the key */
+interface IRouteVm {
+  readonly entity: IPageListEntry;
+  /** what the row shows: the live route, or the first draft's route while nothing is published */
+  readonly pattern: string;
+}
+
+function routeVmOf(entity: IPageListEntry, kind: ContentKind): IRouteVm {
+  // a prefab has no route: its name is what the row shows
+  if (kind === 'prefabs') return { entity, pattern: entity.name };
+  const draftPattern = entity.drafts.find((draft) => draft.pattern !== null)?.pattern ?? null;
+  return { entity, pattern: entity.livePattern ?? draftPattern ?? `/${entity.name}` };
+}
+
+/**
+ * The one way ANY document reaches a canvas from this panel: the WORKSPACE opens it — the tab
+ * already showing it comes forward, or a fresh tab loads it. Drafts open for editing; published
+ * revisions open read-only. Without a workspace (the panel standing alone, a specimen), the
+ * document opens into the shared session the way it always could.
+ */
+function useDocOpener() {
+  const load = useServerAction({ token: loadPageDraftToken, start: EServerActionStart.START_MANUAL });
+  const loadRev = useServerAction({ token: loadPageToken, start: EServerActionStart.START_MANUAL });
+  const { kind } = useContext(EntityWords);
+  const { session } = useEditingSession();
+  const hub = editingSessionHubOf(useDi(DI_CONTAINER_TOKEN));
+  const workspace = useDiOptional(WORKSPACE_TOKEN);
+  const router = useDiOptional(ROUTER_TOKEN);
+  const route = useRoute();
+  // without a workspace — the Pages page of the workbench — a document opens by a MOVE to the
+  // editor's page (ADR-0051 §4), in place through the client router; a realm with neither
+  // (a specimen, a page of its own) opens into the shared session, the way it always could
+  const moveToEditor = (route && router?.active) ? (doc: IOpenDoc): void => {
+    const base = basePathOf(route.pattern ?? null, route.path ?? '/');
+    const { pathname, version } = pathOfView(base, { view: 'editor', ...doc });
+    const query = new URLSearchParams(version).toString();
+    void router.navigate(query ? `${pathname}?${query}` : pathname);
+  } : null;
+
+  /** a draft with its doc already in hand (a fresh duplicate) — opened without a load */
+  const openWithDoc = (name: string, draftId: string, doc: IPageDoc): void => {
+    if (workspace) workspace.open({ kind, page: name, draftId }, doc);
+    else if (moveToEditor) moveToEditor({ kind, page: name, draftId });
+    else session.openPage(name, draftId, doc, kind);
+  };
+
+  const openDraft = (name: string, draftId: string): void => {
+    if (workspace) {
+      workspace.open({ kind, page: name, draftId });
+      return;
+    }
+    if (moveToEditor) {
+      moveToEditor({ kind, page: name, draftId });
+      return;
+    }
+    if (session.snapshot().draftId === draftId) return;
+    const loaded = load.isSuccess() && load.serverData.ok ? load.serverData.draft : null;
+    // a cached answer will not re-run the effect below — open it here instead of waiting
+    if (loaded && loaded.name === name && loaded.id === draftId) session.openPage(loaded.name, loaded.id, loaded.doc, kind);
+    else load.start!({ name, draftId, kind });
+  };
+
+  /** a published revision, read-only: the session opens it in the inspect mode */
+  const openRevision = (name: string, rev: number): void => {
+    if (workspace) {
+      workspace.open({ kind, page: name, revision: rev });
+      return;
+    }
+    if (moveToEditor) {
+      moveToEditor({ kind, page: name, revision: rev });
+      return;
+    }
+    const held = session.snapshot();
+    if (held.kind === kind && held.pageName === name && held.revision === rev) return;
+    const loaded = loadRev.isSuccess() && loadRev.serverData.ok ? loadRev.serverData.page : null;
+    if (loaded && loaded.name === name && loaded.rev === rev) session.openRevision(loaded.name, loaded.rev, loaded.doc, kind);
+    else loadRev.start!({ name, rev, kind });
+  };
+
+  /**
+   * The page is GONE (deleted whole): every session holding one of its documents — a draft or a
+   * read-only revision — lets go. A workspace closes the tab whose session went empty.
+   */
+  const closeDocsOf = (name: string): void => {
+    const held = hub ? hub.keys().map((key) => hub.peek(key)).filter((s): s is EditingSession => s !== null) : [session];
+    for (const s of held) {
+      const state = s.snapshot();
+      if (state.kind === kind && state.pageName === name) s.closePage();
+    }
+    // …and it leaves the recent list: a way to a page that is no longer there is no way
+    workspace?.forget({ kind, page: name });
+  };
+
+  /**
+   * A DRAFT is gone from the store — discarded, or published (it became revision `live`). Every
+   * session still holding it lets go: a discarded draft leaves its tab closing, a published one
+   * reopens there as the read-only revision it became. A session that kept the draft would
+   * autosave the next edit into a draft that no longer exists.
+   */
+  const retireDraft = (name: string, draftId: string, live?: number): void => {
+    const held = hub ? hub.keys().map((key) => hub.peek(key)).filter((s): s is EditingSession => s !== null) : [session];
+    for (const s of held) {
+      const state = s.snapshot();
+      if (state.kind !== kind || state.pageName !== name || state.draftId !== draftId) continue;
+      if (live !== undefined && state.doc) s.openRevision(name, live, state.doc, kind);
+      else s.closePage();
+    }
+  };
+
+  useEffect(() => {
+    if (workspace) return;
+    if (load.isSuccess() && load.serverData.ok) {
+      const { draft } = load.serverData;
+      session.openPage(draft.name, draft.id, draft.doc, kind);
+    }
+  }, [load, session]);
+  useEffect(() => {
+    if (workspace) return;
+    if (loadRev.isSuccess() && loadRev.serverData.ok) {
+      const { page } = loadRev.serverData;
+      session.openRevision(page.name, page.rev, page.doc, kind);
+    }
+  }, [loadRev, session]);
+
+  return { openDraft, openWithDoc, openRevision, closeDocsOf, retireDraft };
+}
+
+/** the matched characters lit inside the text — what the search found is what the eye finds */
+function Lit({ text, indices }: { text: string; indices: readonly number[] }) {
+  if (indices.length === 0) return <>{text}</>;
+  const lit = new Set(indices);
+  const parts: ReactNode[] = [];
+  let run = '';
+  let runLit = lit.has(0);
+  const flush = (key: number) => {
+    if (!run) return;
+    parts.push(runLit ? <mark key={key}>{run}</mark> : run);
+    run = '';
+  };
+  for (let i = 0; i < text.length; i += 1) {
+    const isLit = lit.has(i);
+    if (isLit !== runLit) {
+      flush(i);
+      runLit = isLit;
+    }
+    run += text[i];
+  }
+  flush(text.length);
+  return <>{parts}</>;
+}
+
+function HighlightedPath({ path, match }: { path: string; match: IPathMatch | null }) {
+  return <Lit text={path}
+              indices={match?.indices ?? []} />;
+}
+
+const ChevronIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <path d="M6 3.5L10.5 8 6 12.5"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.6"
+          strokeLinecap="round"
+          strokeLinejoin="round" />
+  </svg>
+);
+
+// stacked sheets: the versions of one page, kept behind the row
+const VersionsIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <rect x="2.5"
+          y="5.5"
+          width="8"
+          height="8"
+          rx="1.2"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.3" />
+    <path d="M5.5 5.5V3.7A1.2 1.2 0 0 1 6.7 2.5h5.6a1.2 1.2 0 0 1 1.2 1.2v5.6a1.2 1.2 0 0 1-1.2 1.2h-1.8"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.3" />
+  </svg>
+);
+
+// a BRANCH, not two sheets: "a new draft grows from this version" — two stacked sheets read as
+// "copy to the clipboard"
+const NewDraftIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <circle cx="5"
+            cy="3.6"
+            r="1.6"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.4" />
+    <circle cx="5"
+            cy="12.4"
+            r="1.6"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.4" />
+    <circle cx="11.2"
+            cy="5.6"
+            r="1.6"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.4" />
+    <path d="M5 5.2v5.6M11.2 7.2c0 2.6-6.2 1.8-6.2 3.6"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.4" />
+  </svg>
+);
+
+const EditIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <path d="M3 13l.8-3.2L10.6 3a1.4 1.4 0 0 1 2 0l.4.4a1.4 1.4 0 0 1 0 2L6.2 12.2 3 13z"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.4"
+          strokeLinejoin="round" />
+    <path d="M9.6 4l2.4 2.4"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.4" />
+  </svg>
+);
+
+const OpenOutIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <path d="M6.5 3.5H3.5v9h9V9.5M9 3.5h3.5V7M12.5 3.5L7.5 8.5"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round" />
+  </svg>
+);
+
+const DeleteIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <path d="M3 4.5h10M6.5 4.5V3h3v1.5M4.5 4.5l.7 8.5h5.6l.7-8.5M6.7 7v3.7M9.3 7v3.7"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.3" />
+  </svg>
+);
+
+// a padlock: the page is the platform's, frozen
+const LockIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <rect x="3.5"
+          y="7"
+          width="9"
+          height="6.5"
+          rx="1.2"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.3" />
+    <path d="M5.5 7V5.2a2.5 2.5 0 0 1 5 0V7"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.3" />
+  </svg>
+);
+
+const LOCKED_TOOLTIP = 'The platform\'s page: it updates with the platform, so it cannot be edited, republished or deleted here';
+
+const PublishIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <path d="M8 12.6V4M4.6 7.2L8 3.6l3.4 3.6"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5" />
+    <path d="M3 13.6h10"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5" />
+  </svg>
+);
+
+/**
+ * The panel's FREEZE: an action on a row (publish, discard, duplicate, delete) and the listing's
+ * refetch after it are one operation to the author — the old list stays on screen until the new
+ * one arrives, and a second click on a row that is about to disappear does damage. So the whole
+ * list is frozen from the moment an action starts until the listing it changed has come back.
+ */
+interface IPanelBusy {
+  begin(): void;
+  /** `changed`: the action landed and changed the listing — the freeze holds until it is refetched */
+  end(changed: boolean): void;
+}
+
+/** how long the freeze waits for the refetched listing before letting go anyway */
+const LISTING_WAIT_MS = 5000;
+
+/** a page's versions as the panel shows them: revisions oldest first, drafts oldest first */
+function versionsOf(entity: IPageListEntry) {
+  const revisions = Object.entries(entity.meta.versions)
+    .map(([rev, status]) => ({ rev: Number(rev), status }))
+    .sort((a, b) => a.rev - b.rev);
+  const drafts = [...entity.drafts].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  return { revisions, drafts };
+}
+
+const draftLabel = (draft: IPageDraftListItem): string => draft.title ?? draft.id.slice(0, 8);
+
+/**
+ * How many tags fit the collapsed row: the live tag always shows, then as many drafts as the row
+ * has room for, and a "…" when some are left out. Every tag is RENDERED (the ones that do not fit
+ * sit out of the flow, invisible), so their widths are known before deciding — the row re-decides
+ * whenever its width changes.
+ */
+/** the gap between tags — `.pages-panel__tags { gap }` (a constant, not read back: getComputedStyle
+ *  is slow, and in a test DOM it can hang) */
+const TAG_GAP = 4;
+
+function useFittingTags(labels: readonly string[]): { ref: (el: HTMLDivElement | null) => void; shown: number } {
+  const [el, setEl] = useState<HTMLDivElement | null>(null);
+  const [shown, setShown] = useState(labels.length);
+  const key = labels.join('\n');
+  const [width, setWidth] = useState(0);
+  useEffect(() => {
+    const Observer = el?.ownerDocument.defaultView?.ResizeObserver;
+    if (!el || !Observer) return undefined;
+    const observer = new Observer(() => setWidth(el.clientWidth));
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [el]);
+  useLayoutEffect(() => {
+    if (!el) return;
+    const widthOf = (selector: string) => [...el.querySelectorAll<HTMLElement>(selector)].map((tag) => tag.offsetWidth);
+    const [live = 0] = widthOf('[data-tag-kind="live"]');
+    // the padlock of a frozen page sits before the live tag and takes its room from the drafts
+    const [lock = 0] = widthOf('[data-tag-kind="locked"]');
+    const drafts = widthOf('[data-tag-kind="draft"]');
+    const [more = 0] = widthOf('[data-tag-kind="more"]');
+    setShown(fittingTags({ room: el.clientWidth - (lock ? lock + TAG_GAP : 0), gap: TAG_GAP, live, drafts, more }));
+  }, [el, width, key]);
+  return { ref: setEl, shown };
+}
+
+/**
+ * A row's action with a glyph AND a word (the tree has the room): a button, or a link that opens
+ * in a new tab when `href` is given. Clicks never reach the row behind it.
+ */
+function RouteButton({ testId, action, tooltip, disabled, danger, href, icon, children, onClick }: {
+  testId: string;
+  action: string;
+  tooltip: string;
+  disabled?: boolean;
+  danger?: boolean;
+  href?: string;
+  icon: ReactNode;
+  children: ReactNode;
+  onClick?: () => void;
+}) {
+  const className = `pages-panel__route-button${danger ? ' pages-panel__route-button--danger' : ''}`;
+  if (href !== undefined) {
+    return (
+      <a className={className}
+         href={href}
+         target="_blank"
+         rel="noopener noreferrer"
+         data-test-id={testId}
+         data-action={action}
+         data-tooltip={tooltip}
+         onClick={(e) => e.stopPropagation()}>
+        {icon}
+        <span>{children}</span>
+      </a>
+    );
+  }
+  return (
+    <button type="button"
+            className={className}
+            data-test-id={testId}
+            data-action={action}
+            data-tooltip={tooltip}
+            disabled={disabled}
+            onClick={(e) => {
+              e.stopPropagation();
+              onClick?.();
+            }}>
+      {icon}
+      <span>{children}</span>
+    </button>
+  );
+}
+
+/** the address a version previews at: the page's own path with the version's token (no bridge) */
+function previewHrefOf(kind: ContentKind, pattern: string, name: string, token: string): string {
+  return `${pattern}?previewToken=${kind === 'prefabs' ? `prefab.${name}` : name}.${token}`;
+}
+
+/** a route an address can name: no parameters to fill in */
+const isConcreteRoute = (pattern: string): boolean => !pattern.includes('{');
+
+function ActionIcon({ testId, action, label, tooltip, disabled, onClick, children }: {
+  testId: string;
+  action: string;
+  /** the name a screen reader says */
+  label: string;
+  /** what a click will do — shown on hover (TooltipHost) */
+  tooltip: string;
+  disabled?: boolean;
+  onClick: () => void;
+  children: ReactNode;
+}) {
+  return (
+    <button type="button"
+            className="pages-panel__icon"
+            data-test-id={testId}
+            data-action={action}
+            data-tooltip={tooltip}
+            aria-label={label}
+            disabled={disabled}
+            onClick={(e) => {
+              e.stopPropagation(); // the row behind the icon opens a version — an action is not that
+              onClick();
+            }}>
+      {children}
+    </button>
+  );
+}
+
+// ---- the delete-page confirmation ----------------------------------------------------------------
+
+/**
+ * "Delete this page?" — asked in a modal that shows WHAT goes: the page's route and every
+ * revision and draft it holds, the way the panel lists them. Portalled to the document body: the
+ * panel freezes while the delete runs, and a frozen panel takes no clicks — the dialog must.
+ */
+function DeletePageModal({ host, route, deleting, error, onCancel, onConfirm }: {
+  /** the document the dialog goes into — the panel's own */
+  host: Document;
+  route: IRouteVm;
+  deleting: boolean;
+  error: string | null;
+  onCancel: () => void;
+  onConfirm: () => void;
+}) {
+  const { revisions, drafts } = versionsOf(route.entity);
+  const { noun } = useContext(EntityWords);
+  const self = useComponent().reference;
+  const confirmRef = useRef<HTMLButtonElement>(null);
+  useEffect(() => confirmRef.current?.focus(), []);
+  // wrapped in the module's scope host: the panel's css is built under that class, and markup
+  // portalled onto the body would otherwise arrive unstyled
+  return createPortal(
+    <div className={tileScopeClass(self)}
+         style={{ display: 'contents' }}>
+      <div className="pages-panel__modal-overlay"
+           data-test-id="pages-delete-modal"
+           onClick={() => {
+             if (!deleting) onCancel();
+           }}
+           onKeyDown={(e) => {
+             if (e.key === 'Escape' && !deleting) onCancel();
+           }}>
+        <div className="pages-panel__modal pages-panel__delete"
+             role="alertdialog"
+             aria-label={`Delete this ${noun}`}
+             onClick={(e) => e.stopPropagation()}>
+          <div className="pages-panel__delete-title">Delete this {noun}?</div>
+          <div className="pages-panel__delete-text">
+            Do you really want to delete this {noun}? It goes with every version below, and this
+            cannot be undone.
+            {noun === 'prefab' ? ' Pages that show it keep their own blocks and lose its.' : ''}
+          </div>
+          <div className="pages-panel__delete-page"
+               data-test-id="pages-delete-summary">
+            <div className="pages-panel__delete-path">{route.pattern}</div>
+            {revisions.length > 0 ? (
+              <div className="pages-panel__delete-versions">
+                {revisions.map(({ rev, status }) => (
+                  <span key={rev}
+                        className={`pages-panel__tag pages-panel__tag--${status}`}
+                        data-rev={rev}>
+                    r{rev} · {status}
+                  </span>
+                ))}
+              </div>
+            ) : null}
+            {drafts.length > 0 ? (
+              <div className="pages-panel__delete-versions">
+                {drafts.map((draft) => (
+                  <span key={draft.id}
+                        className="pages-panel__tag pages-panel__tag--draft"
+                        data-draft-id={draft.id}>
+                    {draftLabel(draft)}
+                  </span>
+                ))}
+              </div>
+            ) : null}
+          </div>
+          {error ? <div className="pages-panel__error">{error}</div> : null}
+          <div className="pages-panel__delete-buttons">
+            <button type="button"
+                    className="pages-panel__button"
+                    data-test-id="pages-delete-cancel"
+                    disabled={deleting}
+                    onClick={onCancel}>
+              Cancel
+            </button>
+            <button ref={confirmRef}
+                    type="button"
+                    className="pages-panel__button pages-panel__button--danger"
+                    data-test-id="pages-delete-confirm"
+                    disabled={deleting}
+                    onClick={onConfirm}>
+              {deleting ? 'Deleting…' : `Delete ${noun}`}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>,
+    host.body,
+  );
+}
+
+// ---- one route -----------------------------------------------------------------------------------
+
+interface IRouteItemProps {
+  readonly busyPanel: IPanelBusy;
+  readonly route: IRouteVm;
+  /** the words on the row: the whole route (the compact list), or this level's segment (the tree) */
+  readonly text: string;
+  /** the matched characters inside `text` */
+  readonly lit: readonly number[];
+  /** the tree: how deep the row sits */
+  readonly tree: boolean;
+  readonly depth: number;
+  readonly expanded: boolean;
+  readonly highlighted: boolean;
+  readonly onToggle: () => void;
+  readonly onExpand: () => void;
+  readonly opener: ReturnType<typeof useDocOpener>;
+  readonly registerEl: (name: string, el: HTMLLIElement | null) => void;
+}
+
+/**
+ * A route of the panel. In the TREE a click on the row unfolds its versions one level down (the
+ * chevron on the left does the same), and the canvas is reached by words: "Edit" on the row (the
+ * newest draft, else the live revision read-only), "Clone" and "Open" (a preview in a new tab) on
+ * every version row, "Open" on the row for the live page itself. In the COMPACT list — a picker —
+ * the row OPENS the page: its live revision, or its newest draft while nothing is published, and
+ * the versions sit behind a button at the row's end. Every version row opens that version. Folded,
+ * the row still names its versions as tags: the live one, then drafts as far as the row has room,
+ * then "…" (which unfolds). A tag opens its version too. The pages UNDER a page stay in view —
+ * only a folder (a path without a page of its own) folds its branch.
+ */
+function RouteItem({ busyPanel, route, text, lit, tree, depth, expanded, highlighted, onToggle, onExpand, opener, registerEl }: IRouteItemProps) {
+  const { entity, pattern } = route;
+  const { kind, noun } = useContext(EntityWords);
+  const notices = noticesOf(useDi(DI_CONTAINER_TOKEN));
+  const createDraft = useServerAction({ token: createPageDraftToken, start: EServerActionStart.START_MANUAL });
+  const publish = useServerAction({ token: publishPageToken, start: EServerActionStart.START_MANUAL });
+  const discard = useServerAction({ token: discardPageDraftToken, start: EServerActionStart.START_MANUAL });
+  const loadForFork = useServerAction({ token: loadPageDraftToken, start: EServerActionStart.START_MANUAL });
+  const fork = useServerAction({ token: forkPageDraftToken, start: EServerActionStart.START_MANUAL });
+  const remove = useServerAction({ token: deletePageToken, start: EServerActionStart.START_MANUAL });
+  const busy = createDraft.isLoading() || publish.isLoading() || discard.isLoading() || fork.isLoading()
+    || remove.isLoading();
+  // the panel freezes while any of this row's actions runs, and until the listing it changed
+  // is back: which actions were in flight is remembered so their outcome decides the wait
+  const actions = [createDraft, publish, discard, fork, remove];
+  const inFlight = useRef(new Set<number>());
+  useEffect(() => {
+    const wasBusy = inFlight.current.size > 0;
+    actions.forEach((action, i) => {
+      if (action.isLoading()) inFlight.current.add(i);
+    });
+    if (!wasBusy && busy) busyPanel.begin();
+    if (wasBusy && !busy) {
+      const changed = [...inFlight.current].some((i) => {
+        const done = actions[i];
+        return done.isSuccess() && done.serverData.ok;
+      });
+      inFlight.current.clear();
+      busyPanel.end(changed);
+    }
+  });
+  // a row that leaves mid-action (its page was deleted elsewhere) must not keep the panel frozen
+  useEffect(() => () => {
+    if (inFlight.current.size > 0) busyPanel.end(false);
+  }, []);
+  /** discarding a draft asks twice: the first click arms THIS draft's trash, the second one fires */
+  const [deleteArmed, setDeleteArmed] = useState<string | null>(null);
+  /** the whole page is deleted through a confirmation dialog that shows what goes */
+  const [confirmingDelete, setConfirmingDelete] = useState(false);
+  /** the draft being published — the dialog asks the publication's name first */
+  const [publishingDraft, setPublishingDraft] = useState<IPageDraftListItem | null>(null);
+  /** duplicating a draft loads its doc first — this remembers which duplicate is in flight */
+  const forkingRef = useRef<string | null>(null);
+  /** the draft a discard or a publish is about — the canvases holding it let go when it lands */
+  const retiringRef = useRef<string | null>(null);
+
+  // a fresh draft duplicated from a REVISION is the start of editing — it opens where a draft opens
+  useEffect(() => {
+    if (createDraft.isSuccess() && createDraft.serverData.ok) {
+      const { draftId, page } = createDraft.serverData;
+      opener.openWithDoc(entity.name, draftId, page);
+    }
+  }, [createDraft]);
+  // a duplicate of a DRAFT just appears as a row: the fork lands, the listing refetches itself
+  useEffect(() => {
+    if (loadForFork.isSuccess() && loadForFork.serverData.ok && forkingRef.current !== null) {
+      const { draft } = loadForFork.serverData;
+      if (draft.id === forkingRef.current) {
+        forkingRef.current = null;
+        fork.start!({ name: entity.name, page: draft.doc, kind });
+      }
+    }
+  }, [loadForFork]);
+
+  // the page is gone with its whole history: whatever canvas showed a piece of it goes vacant;
+  // the listing refetches itself (the action invalidates 'pages') and the row leaves with it
+  useEffect(() => {
+    if (remove.isSuccess() && remove.serverData.ok) {
+      setConfirmingDelete(false);
+      opener.closeDocsOf(entity.name);
+      notices?.show('delete', `Deleted the ${noun} ${pattern} with every revision and draft`);
+    }
+  }, [remove]);
+  // a discarded draft is gone; a published one became a revision — the canvases holding it let go
+  useEffect(() => {
+    if (!retiringRef.current || !discard.isSuccess() || !discard.serverData.ok) return;
+    const gone = entity.drafts.find((draft) => draft.id === retiringRef.current);
+    opener.retireDraft(entity.name, retiringRef.current);
+    retiringRef.current = null;
+    notices?.show('delete', `Discarded the draft ${gone ? draftLabel(gone) : ''} of ${pattern}`.replace('  ', ' '));
+  }, [discard]);
+  useEffect(() => {
+    if (!retiringRef.current || !publish.isSuccess() || !publish.serverData.ok) return;
+    opener.retireDraft(entity.name, retiringRef.current, publish.serverData.live);
+    retiringRef.current = null;
+    setPublishingDraft(null);
+  }, [publish]);
+
+  const { revisions, drafts } = versionsOf(entity);
+  const live = entity.meta.live ?? null;
+  // a FROZEN page belongs to the platform (the workbench): it is opened and read, never changed
+  const locked = entity.meta.locked === true;
+  // the folded row names the NEWEST drafts first — the ones most likely to be worked on
+  const tagDrafts = [...drafts].reverse();
+  const tags = useFittingTags(tagDrafts.map(draftLabel));
+  // the row's element: a STABLE ref callback — a fresh one per render would be called with null
+  // and the element again on every commit, and the state inside it would never settle
+  const [itemEl, setItemEl] = useState<HTMLLIElement | null>(null);
+  const itemRef = useCallback((el: HTMLLIElement | null) => {
+    registerEl(entity.name, el);
+    setItemEl(el);
+  }, [entity.name]);
+
+  /** the page itself: its live revision, or its newest draft while nothing is published */
+  const openPage = (): void => {
+    if (live !== null) opener.openRevision(entity.name, live);
+    else if (tagDrafts.length > 0) opener.openDraft(entity.name, tagDrafts[0].id);
+    else onExpand();
+  };
+  /** EDIT: the newest draft when there is one, else the live revision (read-only) */
+  const editPage = (): void => {
+    if (tagDrafts.length > 0) opener.openDraft(entity.name, tagDrafts[0].id);
+    else if (live !== null) opener.openRevision(entity.name, live);
+  };
+  // the tree: a click on the row unfolds its versions (the chevron's job too); the compact list's
+  // row opens the page — it is a picker
+  const rowAction = tree ? onToggle : openPage;
+  const rowTooltip = tree
+    ? (expanded ? `Hide the versions of ${pattern}` : `Show every version of ${pattern} — its revisions and drafts`)
+    : live !== null
+      ? `Open ${pattern} in a canvas — its live revision r${live}, read-only`
+      : tagDrafts.length > 0
+        ? `Open ${pattern} in a canvas — its newest draft ${draftLabel(tagDrafts[0])}, for editing`
+        : `Show the versions of ${pattern}`;
+
+  const removeError = remove.isError()
+    ? remove.serverError.code
+    : remove.isSuccess() && !remove.serverData.ok ? remove.serverData.code : null;
+
+  return (
+    <li className={`pages-panel__route-item${highlighted ? ' pages-panel__route-item--flash' : ''}`}
+        ref={itemRef}
+        data-test-id="pages-route"
+        data-page={entity.name}
+        data-pattern={pattern}
+        data-depth={tree ? depth : undefined}
+        data-expanded={expanded || undefined}>
+      <div className="pages-panel__route"
+           role="button"
+           tabIndex={0}
+           style={tree ? { paddingLeft: `${4 + depth * 18}px` } : undefined}
+           data-action={tree ? 'toggle-versions' : 'open-page'}
+           data-tooltip={rowTooltip}
+           onClick={rowAction}
+           onKeyDown={(e) => {
+             if (e.target === e.currentTarget && (e.key === 'Enter' || e.key === ' ')) {
+               e.preventDefault();
+               rowAction();
+             }
+           }}>
+        {/* the tree: the chevron unfolds the page's VERSIONS one level down — a nesting of the
+            tree, not a button at the row's end */}
+        {tree ? (
+          <button type="button"
+                  className="pages-panel__chevron"
+                  data-action="toggle"
+                  data-folded={expanded ? undefined : true}
+                  aria-expanded={expanded}
+                  aria-label={expanded ? 'Hide the versions' : 'Show the versions'}
+                  data-tooltip={expanded
+                    ? `Hide the versions of this ${noun}`
+                    : `Show every version of this ${noun} — its revisions and drafts`}
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    onToggle();
+                  }}>
+            {ChevronIcon}
+          </button>
+        ) : null}
+        <span className="pages-panel__path">
+          <Lit text={text}
+               indices={lit} />
+        </span>
+        {expanded ? null : (
+          <div className="pages-panel__tags"
+               ref={tags.ref}
+               data-test-id="pages-route-tags">
+            {locked ? (
+              <span className="pages-panel__tag pages-panel__tag--locked"
+                    data-tag-kind="locked"
+                    data-tooltip={LOCKED_TOOLTIP}>
+                {LockIcon}
+              </span>
+            ) : null}
+            {live !== null ? (
+              <button type="button"
+                      className="pages-panel__tag pages-panel__tag--published"
+                      data-tag-kind="live"
+                      data-rev={live}
+                      data-tooltip={`Open r${live}, the live revision, in a canvas — read-only`}
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        opener.openRevision(entity.name, live);
+                      }}>
+                r{live}
+              </button>
+            ) : null}
+            {tagDrafts.map((draft, i) => (
+              <button key={draft.id}
+                      type="button"
+                      className={`pages-panel__tag pages-panel__tag--draft${i < tags.shown ? '' : ' pages-panel__tag--unfit'}`}
+                      data-tag-kind="draft"
+                      data-draft-id={draft.id}
+                      tabIndex={i < tags.shown ? 0 : -1}
+                      aria-hidden={i < tags.shown ? undefined : true}
+                      data-tooltip={`Open the draft ${draftLabel(draft)} in a canvas, for editing`}
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        opener.openDraft(entity.name, draft.id);
+                      }}>
+                {draftLabel(draft)}
+              </button>
+            ))}
+            {tagDrafts.length > 0 ? (
+              <button type="button"
+                      className={`pages-panel__tag pages-panel__tag--more${tags.shown < tagDrafts.length ? '' : ' pages-panel__tag--unfit'}`}
+                      data-tag-kind="more"
+                      tabIndex={tags.shown < tagDrafts.length ? 0 : -1}
+                      aria-hidden={tags.shown < tagDrafts.length ? undefined : true}
+                      data-tooltip={`Show every version — ${tagDrafts.length - tags.shown} more draft(s) do not fit here`}
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        onExpand();
+                      }}>
+                …
+              </button>
+            ) : null}
+          </div>
+        )}
+        {tree ? (
+          <span className="pages-panel__route-actions"
+                data-test-id="pages-route-actions">
+            {live !== null || tagDrafts.length > 0 ? (
+              <RouteButton testId="pages-route-edit"
+                           action="edit"
+                           tooltip={tagDrafts.length > 0
+                             ? `Open the newest draft, ${draftLabel(tagDrafts[0])}, in a canvas for editing`
+                             : `Open r${live}, the live revision, in a canvas — read-only (make a new draft to change it)`}
+                           disabled={busy}
+                           icon={EditIcon}
+                           onClick={editPage}>
+                Edit
+              </RouteButton>
+            ) : null}
+            {live !== null && isConcreteRoute(pattern) && kind === 'pages' ? (
+              <RouteButton testId="pages-route-open"
+                           action="open-live"
+                           tooltip={`Open the live page ${pattern} in a new tab, as a reader sees it`}
+                           href={pattern}
+                           icon={OpenOutIcon}>
+                Open
+              </RouteButton>
+            ) : null}
+            {live !== null && !locked ? (
+              <RouteButton testId="pages-route-new-draft"
+                           action="duplicate"
+                           tooltip={`New draft from r${live}, the live revision — it opens in the editor`}
+                           disabled={busy}
+                           icon={NewDraftIcon}
+                           onClick={() => createDraft.start!({ name: entity.name, fromRev: live, kind })}>
+                New draft
+              </RouteButton>
+            ) : null}
+            {locked ? null : (
+              <RouteButton testId="pages-route-delete"
+                           action="delete-page"
+                           tooltip={`Delete the whole ${noun} with every revision and draft — asks to confirm first`}
+                           disabled={busy}
+                           danger
+                           icon={DeleteIcon}
+                           onClick={() => setConfirmingDelete(true)}>
+                Delete
+              </RouteButton>
+            )}
+          </span>
+        ) : null}
+        {tree ? null : (
+          <button type="button"
+                  className={`pages-panel__versions${expanded ? ' pages-panel__versions--open' : ''}`}
+                  data-action="toggle"
+                  aria-expanded={expanded}
+                  aria-label={expanded ? 'Hide versions' : 'Show versions'}
+                  data-tooltip={expanded
+                    ? `Hide the versions of this ${noun}`
+                    : `Show every version of this ${noun} — its revisions and drafts`}
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    onToggle();
+                  }}>
+            {VersionsIcon}
+          </button>
+        )}
+      </div>
+      {expanded ? (
+        <div className={`pages-panel__expander${tree ? ' pages-panel__expander--nested' : ''}`}
+             style={tree ? {
+               // the rail under the centre of the next level's chevron; the rows at that level's words
+               marginLeft: `calc(${4 + (depth + 1) * 18}px + var(--mosetta-wb-icon-box) / 2)`,
+               paddingLeft: 'calc(var(--mosetta-wb-icon-box) / 2 + 4px)',
+             } : undefined}
+             data-test-id="pages-expander">
+          {revisions.map(({ rev, status }) => (
+            <div key={`r${rev}`}
+                 className={`pages-panel__row pages-panel__publish-row pages-panel__publish-row--${status}`}
+                 data-test-id="pages-publish-row"
+                 data-rev={rev}
+                 data-status={status}>
+              <button type="button"
+                      className="pages-panel__row-open"
+                      data-action="open"
+                      data-tooltip={status === 'published'
+                        ? `Open r${rev}, the live revision, in a canvas — read-only (make a new draft from it to change it)`
+                        : `Open r${rev}, an earlier revision, in a canvas — read-only (make a new draft from it to bring it back)`}
+                      onClick={() => opener.openRevision(entity.name, rev)}>
+                <span className={`pages-panel__tag pages-panel__tag--${status}`}>r{rev}</span>
+                {entity.meta.names?.[String(rev)] ? (
+                  <span className="pages-panel__row-name"
+                        data-test-id="pages-revision-name">{entity.meta.names[String(rev)]}</span>
+                ) : null}
+                <span className="pages-panel__row-note">{status}</span>
+              </button>
+              <span className="pages-panel__row-actions"
+                    data-test-id="pages-row-actions">
+                {locked || !tree ? null : (
+                  <RouteButton testId="pages-row-actions-duplicate"
+                               action="duplicate"
+                               tooltip={`Clone r${rev} into a new draft — it opens in a canvas for editing`}
+                               disabled={busy}
+                               icon={NewDraftIcon}
+                               onClick={() => createDraft.start!({ name: entity.name, fromRev: rev, kind })}>
+                    Clone
+                  </RouteButton>
+                )}
+                {tree ? (
+                  <RouteButton testId="pages-row-actions-open-new"
+                               action="open-new"
+                               tooltip={`Open r${rev} in a new tab, as a preview`}
+                               href={previewHrefOf(kind, pattern, entity.name, `r${rev}`)}
+                               icon={OpenOutIcon}>
+                    Open
+                  </RouteButton>
+                ) : null}
+                {locked || tree ? null : (
+                  <ActionIcon testId="pages-row-actions-duplicate"
+                              action="duplicate"
+                              label={`New draft from r${rev}`}
+                              tooltip={`New draft from r${rev} — it opens in a canvas for editing`}
+                              disabled={busy}
+                              onClick={() => createDraft.start!({ name: entity.name, fromRev: rev, kind })}>
+                    {NewDraftIcon}
+                  </ActionIcon>
+                )}
+              </span>
+            </div>
+          ))}
+          {drafts.map((draft) => (
+            <div key={draft.id}
+                 className="pages-panel__row pages-panel__draft-row"
+                 data-test-id="pages-draft-row"
+                 data-draft-id={draft.id}
+                 data-base-rev={draft.baseRev}>
+              <button type="button"
+                      className="pages-panel__row-open"
+                      data-action="open"
+                      data-tooltip={`Open the draft ${draftLabel(draft)} in a canvas, for editing`}
+                      onClick={() => opener.openDraft(entity.name, draft.id)}>
+                <span className="pages-panel__tag pages-panel__tag--draft">{draftLabel(draft)}</span>
+                {draft.baseRev != null ? <span className="pages-panel__row-note">from r{draft.baseRev}</span> : null}
+                {draft.pattern !== null && draft.pattern !== pattern ? (
+                  <span className="pages-panel__row-note pages-panel__row-note--moved"
+                        data-tooltip={`Publishing this draft moves the page to ${draft.pattern}`}>
+                    → {draft.pattern}
+                  </span>
+                ) : null}
+              </button>
+              <span className="pages-panel__row-actions"
+                    data-test-id="pages-row-actions">
+                {tree ? (
+                  <>
+                    <RouteButton testId="pages-row-actions-duplicate"
+                                 action="duplicate"
+                                 tooltip="Clone this draft — a copy appears in this list"
+                                 disabled={busy}
+                                 icon={NewDraftIcon}
+                                 onClick={() => {
+                                   forkingRef.current = draft.id;
+                                   loadForFork.start!({ name: entity.name, draftId: draft.id, kind });
+                                 }}>
+                      Clone
+                    </RouteButton>
+                    <RouteButton testId="pages-row-actions-open-new"
+                                 action="open-new"
+                                 tooltip={`Open the draft ${draftLabel(draft)} in a new tab, as a preview`}
+                                 href={previewHrefOf(kind, pattern, entity.name, draft.id)}
+                                 icon={OpenOutIcon}>
+                      Open
+                    </RouteButton>
+                  </>
+                ) : (
+                  <ActionIcon testId="pages-row-actions-duplicate"
+                              action="duplicate"
+                              label="New draft from this draft"
+                              tooltip="New draft from this draft — a copy appears in this list"
+                              disabled={busy}
+                              onClick={() => {
+                                forkingRef.current = draft.id;
+                                loadForFork.start!({ name: entity.name, draftId: draft.id, kind });
+                              }}>
+                    {NewDraftIcon}
+                  </ActionIcon>
+                )}
+                <ActionIcon testId="pages-row-actions-publish"
+                            action="publish"
+                            label="Publish this draft"
+                            tooltip={live !== null
+                              ? `Publish this draft — it becomes the live revision in place of r${live}`
+                              : 'Publish this draft — it becomes the live revision'}
+                            disabled={busy}
+                            onClick={() => setPublishingDraft(draft)}>
+                  {PublishIcon}
+                </ActionIcon>
+                <ActionIcon testId="pages-row-actions-delete"
+                            action="delete"
+                            label="Discard this draft"
+                            tooltip={deleteArmed === draft.id
+                              ? 'Click again to discard this draft for good'
+                              : 'Discard this draft — a second click confirms'}
+                            disabled={busy}
+                            onClick={() => {
+                              if (deleteArmed === draft.id) {
+                                setDeleteArmed(null);
+                                retiringRef.current = draft.id;
+                                discard.start!({ name: entity.name, draftId: draft.id, kind });
+                              } else {
+                                setDeleteArmed(draft.id);
+                              }
+                            }}>
+                  {deleteArmed === draft.id
+                    ? <span className="pages-panel__confirm"
+                            aria-hidden="true">?</span>
+                    : DeleteIcon}
+                </ActionIcon>
+              </span>
+            </div>
+          ))}
+          {tree && !locked ? null : (
+            <div className="pages-panel__row pages-panel__page-row"
+                 data-test-id="pages-page-row">
+              <span className="pages-panel__row-label">
+                {locked
+                  ? <span className="pages-panel__row-note"
+                          data-tooltip={LOCKED_TOOLTIP}>the platform's page — updates with the platform</span>
+                  : <span className="pages-panel__row-note">whole {noun}</span>}
+              </span>
+              {locked ? null : (
+                <span className="pages-panel__row-actions"
+                      data-test-id="pages-row-actions">
+                  <ActionIcon testId="pages-row-actions-delete-page"
+                              action="delete-page"
+                              label={`Delete this ${noun}`}
+                              tooltip={`Delete the whole ${noun} with every revision and draft — asks to confirm first`}
+                              disabled={busy}
+                              onClick={() => setConfirmingDelete(true)}>
+                    {DeleteIcon}
+                  </ActionIcon>
+                </span>
+              )}
+            </div>
+          )}
+          {publish.isError() && <div className="pages-panel__error">{publish.serverError.code}</div>}
+          {publish.isSuccess() && !publish.serverData.ok && (
+            <div className="pages-panel__error"
+                 data-publish-error={publish.serverData.code}>
+              {publish.serverData.code}
+            </div>
+          )}
+        </div>
+      ) : null}
+      {publishingDraft && itemEl ? (
+        <PublishModal host={itemEl.ownerDocument}
+                      noun={noun}
+                      route={pattern}
+                      suggested={publishingDraft.title ?? publishingDraft.id.slice(0, 8)}
+                      live={live}
+                      publishing={publish.isLoading()}
+                      error={publish.isError()
+                        ? publish.serverError.code
+                        : publish.isSuccess() && !publish.serverData.ok && retiringRef.current === null
+                          ? [publish.serverData.code, ...(publish.serverData.issues ?? [])].join('\n')
+                          : null}
+                      onCancel={() => setPublishingDraft(null)}
+                      onConfirm={(title) => {
+                        retiringRef.current = publishingDraft.id;
+                        publish.start!({ name: entity.name, draftId: publishingDraft.id, kind, title });
+                      }} />
+      ) : null}
+      {confirmingDelete && itemEl ? (
+        <DeletePageModal host={itemEl.ownerDocument}
+                         route={route}
+                         deleting={remove.isLoading()}
+                         error={removeError}
+                         onCancel={() => setConfirmingDelete(false)}
+                         onConfirm={() => remove.start!({ name: entity.name, kind })} />
+      ) : null}
+    </li>
+  );
+}
+
+// ---- the create modal --------------------------------------------------------------------------
+
+interface ICreateModalProps {
+  readonly routes: readonly IRouteVm[];
+  readonly own: ITileReference;
+  readonly onClose: () => void;
+  /** the typed path already exists — the panel reveals it */
+  readonly onJump: (name: string) => void;
+  /** a page was created: reveal + open its first draft */
+  readonly onCreated: (name: string, draftId: string) => void;
+}
+
+/** a route pattern the create input accepts: absolute, no spaces (parameters like {id} are fine) */
+const CREATABLE_PATTERN_RE = /^\/\S*$/;
+/** what a path can never hold: whitespace, and `#` (a fragment never reaches a route) */
+const PATH_REFUSED_RE = /[\s#]/;
+/** what a name can never hold: anything but letters and digits (ENTITY_NAME_RE) */
+const NAME_REFUSED_RE = /[^A-Za-z0-9]/;
+
+function CreateModal({ routes, own, onClose, onJump, onCreated }: ICreateModalProps) {
+  const { kind, noun } = useContext(EntityWords);
+  // a page is created at a PATH (its name derived from it); a prefab by its NAME
+  const byName = kind === 'prefabs';
+  const [value, setValue] = useState(byName ? '' : '/');
+  const components = useServerAction({ token: listComponentsToken, input: {} });
+  const create = useServerAction({ token: createPageToken, start: EServerActionStart.START_MANUAL });
+  const inputRef = useRef<HTMLInputElement>(null);
+  const createdRef = useRef<string | null>(null);
+  useEffect(() => inputRef.current?.focus(), []);
+  const notices = noticesOf(useDi(DI_CONTAINER_TOKEN));
+  // letters the field cannot carry never get in: typed ones are refused in silence, a PASTE with
+  // them is refused with a word — the author is told why nothing happened
+  const refuse = (e: React.FormEvent<HTMLInputElement>): void => {
+    const native = e.nativeEvent as InputEvent;
+    const data = native.data;
+    if (data == null || !(byName ? NAME_REFUSED_RE : PATH_REFUSED_RE).test(data)) return;
+    e.preventDefault();
+    if (native.inputType === 'insertFromPaste') {
+      notices?.show('refuse', byName
+        ? 'That cannot be a prefab name: letters and digits only'
+        : 'That cannot be a page path: no spaces, no #');
+    }
+  };
+
+  const trimmed = value.trim();
+  const existing = useMemo(() => rankPaths(routes, trimmed, (route) => route.pattern), [routes, trimmed]);
+  const exact = routes.find((route) => route.pattern === trimmed) ?? null;
+  const creatable = !exact && (byName ? ENTITY_NAME_RE.test(trimmed) : CREATABLE_PATTERN_RE.test(trimmed));
+  // the NAME the entity gets — its address in the workbench — said as the path is typed
+  const taken = useMemo(() => new Set(routes.map((route) => route.entity.name)), [routes]);
+  const name = creatable ? (byName ? trimmed : nameFromPattern(trimmed, taken)) : null;
+
+  // the ROOT the new page starts with: the project's own page root when its catalog has one,
+  // else the editor's generic root. Not asked here — what a root component is makes sense with
+  // the page in front of one; it is changed in the page's settings
+  const rootId = useMemo(() => {
+    const listed = components.isSuccess() && components.serverData.ok
+      ? components.serverData.components.filter((c) => c.isRoot).map((c) => c.id)
+      : [];
+    const fallback = `_ns_${own.namespace}_t_component_n_page_v_${own.version}`;
+    return listed.find((id) => !id.startsWith(`_ns_${own.namespace}_`)) ?? listed[0] ?? fallback;
+  }, [components, own.namespace, own.version]);
+
+  useEffect(() => {
+    if (create.isSuccess() && create.serverData.ok && createdRef.current !== null) {
+      const created = createdRef.current;
+      createdRef.current = null;
+      onCreated(created, create.serverData.draftId);
+    }
+  }, [create]);
+
+  const submit = (): void => {
+    if (!name || create.isLoading()) return;
+    createdRef.current = name;
+    create.start!({ name, page: { id: name, reference: rootId, pattern: byName ? PREFAB_CANVAS_PATTERN : trimmed, children: [] }, kind });
+  };
+
+  return (
+    <div className="pages-panel__modal-overlay"
+         data-test-id="pages-create-modal"
+         onClick={onClose}>
+      <div className="pages-panel__modal"
+           role="dialog"
+           aria-label={`Create a ${noun}`}
+           onClick={(e) => e.stopPropagation()}>
+        <div className="pages-panel__modal-title">Create a {noun}</div>
+        <input ref={inputRef}
+               className="pages-panel__modal-input"
+               data-test-id="pages-create-input"
+               type="text"
+               placeholder={byName ? 'nameOfTheNewPrefab' : '/path/of/the/new/page'}
+               value={value}
+               spellCheck={false}
+               onBeforeInput={refuse}
+               onChange={(e) => setValue(e.target.value)}
+               onKeyDown={(e) => {
+                 if (e.key === 'Escape') onClose();
+                 if (e.key === 'Enter') submit();
+               }} />
+        {exact ? (
+          <button type="button"
+                  className="pages-panel__modal-hint"
+                  data-test-id="pages-create-exists"
+                  onClick={() => onJump(exact.entity.name)}>
+            {exact.pattern} already exists — go to it
+          </button>
+        ) : null}
+        {!exact && existing.length > 0 ? (
+          <ul className="pages-panel__modal-list"
+              data-test-id="pages-create-suggestions">
+            {existing.slice(0, 6).map(({ item, match }) => (
+              <li key={item.entity.name}>
+                <button type="button"
+                        className="pages-panel__modal-item"
+                        data-page={item.entity.name}
+                        onClick={() => onJump(item.entity.name)}>
+                  <HighlightedPath path={item.pattern}
+                                   match={match} />
+                </button>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+        {name ? (
+          <div className="pages-panel__modal-name"
+               data-test-id="pages-create-name"
+               data-name={name}>
+            {byName ? 'The prefab goes by ' : 'The page will be named '}
+            <code>{name}</code>
+            {byName ? ' — its address in the workbench' : ' — its address in the workbench; the route is what readers see'}
+          </div>
+        ) : null}
+        {byName && trimmed && !exact && !creatable ? (
+          <div className="pages-panel__modal-hint"
+               data-test-id="pages-create-name-hint">
+            A prefab's name: a lowercase letter first, then letters and digits — blogFrame, buyButton
+          </div>
+        ) : null}
+        <button type="button"
+                className="pages-panel__button pages-panel__button--primary pages-panel__modal-submit"
+                data-test-id="pages-create-submit"
+                disabled={!creatable || create.isLoading()}
+                onClick={submit}>
+          {create.isLoading() ? 'Creating…' : `Create the ${noun}`}
+        </button>
+        {create.isError() && <div className="pages-panel__error">create failed: {create.serverError.code}</div>}
+        {create.isSuccess() && !create.serverData.ok && (
+          <div className="pages-panel__error">create failed: {create.serverData.code}</div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ---- the panel ---------------------------------------------------------------------------------
+
+/**
+ * Everything the live site kept — a page's render, a router's verdict, the route table — is read
+ * anew: the remedy for a change made to the store by hand, which no publish announced. Says what
+ * happened for a moment; a store that keeps nothing (dev) says so.
+ */
+function RefreshSiteButton() {
+  const refresh = useServerAction({ token: refreshLiveSiteToken, start: EServerActionStart.START_MANUAL });
+  const [said, setSaid] = useState<string | null>(null);
+  useEffect(() => {
+    if (!refresh.isSuccess() && !refresh.isError()) return undefined;
+    const ok = refresh.isSuccess() && refresh.serverData.ok;
+    setSaid(!ok ? 'Could not refresh' : refresh.serverData.refreshed ? 'The live site reads anew' : 'Nothing is kept here');
+    const timer = setTimeout(() => setSaid(null), 2500);
+    return () => clearTimeout(timer);
+  }, [refresh]);
+  return (
+    <>
+      {said ? <span className="pages-panel__working"
+                    data-test-id="pages-panel-refreshed">{said}</span> : null}
+      <button type="button"
+              className="pages-panel__create"
+              data-test-id="pages-panel-refresh-site"
+              disabled={refresh.isLoading()}
+              data-tooltip="Refresh the live site: what readers get is read anew from what is stored — after a change made to the store by hand"
+              aria-label="Refresh the live site"
+              onClick={() => refresh.start!({})}>
+        <svg viewBox="0 0 16 16"
+             aria-hidden="true">
+          <path d="M12.6 6.2A5 5 0 1 0 13 9.4M12.8 2.8v3.6H9.2"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+                strokeLinejoin="round" />
+        </svg>
+      </button>
+    </>
+  );
+}
+
+/** a prefix no page owns (`/docs` under `/docs/api/{name}`): a row that only folds what is under it */
+function FolderRow({ node, depth, folded, onFold }: { node: IRouteTreeNode<IRouteVm>; depth: number; folded: boolean; onFold: () => void }) {
+  return (
+    <li className="pages-panel__route-item pages-panel__route-item--folder"
+        data-test-id="pages-folder"
+        data-path={node.path}
+        data-depth={depth}>
+      <div className="pages-panel__route pages-panel__route--folder"
+           role="button"
+           tabIndex={0}
+           style={{ paddingLeft: `${4 + depth * 18}px` }}
+           data-action="fold"
+           data-folded={folded || undefined}
+           data-tooltip={folded ? 'Show the pages under this path' : 'Hide the pages under this path'}
+           onClick={onFold}
+           onKeyDown={(e) => {
+             if (e.target === e.currentTarget && (e.key === 'Enter' || e.key === ' ')) {
+               e.preventDefault();
+               onFold();
+             }
+           }}>
+        <span className="pages-panel__chevron"
+              data-folded={folded || undefined}
+              aria-hidden="true">
+          {ChevronIcon}
+        </span>
+        <span className="pages-panel__path">
+          <Lit text={node.segment}
+               indices={node.lit} />
+        </span>
+      </div>
+    </li>
+  );
+}
+
+/** the panel's body: the listing of whichever entities the words name */
+function EntityPanel({ compact }: { compact: boolean }) {
+  const words = useContext(EntityWords);
+  const pages = useServerAction({ token: listPagesToken, input: { kind: words.kind } });
+  const own = useComponent().reference;
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const query = useMemo(() => ensureQueryParams(di), [di]);
+
+  const [term, setTerm] = useState<string>(() => query?.get(words.searchParam) ?? '');
+  useEffect(() => {
+    query?.set(words.searchParam, term.trim() ? term : null);
+  }, [query, term, words.searchParam]);
+
+  const [expanded, setExpanded] = useState<ReadonlySet<string>>(() => new Set());
+  /** the tree's folded branches, by node path — unfolded unless folded, and a search unfolds all */
+  const [folded, setFolded] = useState<ReadonlySet<string>>(() => new Set());
+  const [flash, setFlash] = useState<{ name: string; stamp: number } | null>(null);
+  const [creating, setCreating] = useState(false);
+  const routeEls = useRef(new Map<string, HTMLLIElement>());
+  const registerEl = (name: string, el: HTMLLIElement | null): void => {
+    if (el) routeEls.current.set(name, el);
+    else routeEls.current.delete(name);
+  };
+
+  const opener = useDocOpener();
+
+  // the freeze (see IPanelBusy): actions in flight, then the wait for the listing they changed
+  const [actionsInFlight, setActionsInFlight] = useState(0);
+  const [awaitingListing, setAwaitingListing] = useState(false);
+  const listing = pages.isSuccess() ? pages.serverData : null;
+  useEffect(() => setAwaitingListing(false), [listing]);
+  useEffect(() => {
+    if (!awaitingListing) return undefined;
+    const timer = setTimeout(() => setAwaitingListing(false), LISTING_WAIT_MS);
+    return () => clearTimeout(timer);
+  }, [awaitingListing]);
+  const busyPanel = useMemo<IPanelBusy>(() => ({
+    begin: () => setActionsInFlight((n) => n + 1),
+    end: (changed) => {
+      setActionsInFlight((n) => Math.max(0, n - 1));
+      if (changed) setAwaitingListing(true);
+    },
+  }), []);
+  const frozen = actionsInFlight > 0 || awaitingListing;
+
+  const toggleIn = (set: (update: (prev: ReadonlySet<string>) => ReadonlySet<string>) => void) => (key: string): void => set((prev) => {
+    const next = new Set(prev);
+    if (next.has(key)) next.delete(key);
+    else next.add(key);
+    return next;
+  });
+  const toggle = toggleIn(setExpanded);
+  const toggleFold = toggleIn(setFolded);
+
+  /** expand + flash + scroll a route into view — the "go to it" of search and creation */
+  const reveal = (name: string): void => {
+    setTerm('');
+    setFolded(new Set()); // wherever it sits, the branch above it opens
+    setExpanded((prev) => new Set(prev).add(name));
+    setFlash({ name, stamp: Date.now() });
+    // after the re-render that unhides the row (the search reset may have been filtering it out)
+    setTimeout(() => routeEls.current.get(name)?.scrollIntoView({ block: 'nearest', behavior: 'smooth' }), 0);
+  };
+
+  const routes = useMemo((): IRouteVm[] => (
+    pages.isSuccess() && pages.serverData.ok ? pages.serverData.pages.map((entity) => routeVmOf(entity, words.kind)) : []
+  ), [pages, words.kind]);
+
+  // ranked (the empty term ranks everything equal → alphabetical): the compact list groups the
+  // matches by their first path segment, keeping the rank order of each group's best entry, so a
+  // search re-orders groups too; the tree is rebuilt from the matches alone, the lit characters
+  // carried down its branches
+  const ranked = useMemo(() => rankPaths(routes, term, (route) => route.pattern), [routes, term]);
+  const searching = term.trim() !== '';
+  const groups = useMemo(() => {
+    const byKey = new Map<string, Array<{ item: IRouteVm; match: IPathMatch }>>();
+    for (const entry of ranked) {
+      // prefabs are named, not routed: one group
+      const key = words.kind === 'prefabs' ? '' : groupKeyOf(entry.item.pattern);
+      const bucket = byKey.get(key);
+      if (bucket) bucket.push(entry);
+      else byKey.set(key, [entry]);
+    }
+    return [...byKey.entries()];
+  }, [ranked, words.kind]);
+  const tree = useMemo(() => {
+    const matches = new Map(ranked.map(({ item, match }) => [item, match]));
+    return buildRouteTree(ranked.map(({ item }) => item), (route) => route.pattern, searching ? (route) => matches.get(route) ?? null : undefined);
+  }, [ranked, searching]);
+  /** the tree's rows, depth-first, folded branches left out (a search unfolds everything) */
+  const treeRows = useMemo(() => {
+    const rows: Array<{ node: IRouteTreeNode<IRouteVm>; depth: number }> = [];
+    const walk = (nodes: readonly IRouteTreeNode<IRouteVm>[], depth: number): void => {
+      for (const node of nodes) {
+        rows.push({ node, depth });
+        // a FOLDER folds its branch; a page's children stay in view (its chevron is for the versions)
+        if (searching || node.route || !folded.has(node.path)) walk(node.children, depth + 1);
+      }
+    };
+    walk(tree, 0);
+    return rows;
+  }, [tree, folded, searching]);
+
+  const listed = words.title.toLowerCase();
+  if (pages.isLoading()) return <div className="pages-panel pages-panel__loading">Loading {listed}…</div>;
+  if (pages.isError()) {
+    return <div className="pages-panel pages-panel__error">{listed} failed: {pages.serverError.code}</div>;
+  }
+  if (!pages.isSuccess()) return null;
+  const result = pages.serverData;
+  if (!result.ok) return <div className="pages-panel pages-panel__error">{listed} failed: {result.code}</div>;
+
+  return (
+    <TooltipHost>
+      <div className={`pages-panel${frozen ? ' pages-panel--frozen' : ''}${compact ? ' pages-panel--compact' : ' pages-panel--tree'}`}
+           data-test-id="pages-panel"
+           data-kind={words.kind}
+           data-layout={compact ? 'compact' : 'tree'}
+           data-frozen={frozen || undefined}
+           aria-busy={frozen || undefined}>
+        <div className="pages-panel__bar">
+          <SearchField>
+            <input className="pages-panel__search"
+                   data-test-id="pages-search-bar"
+                   type="search"
+                   placeholder={words.kind === 'prefabs' ? 'Search prefabs by name' : 'Search routes — /path, initials (ags), anything'}
+                   value={term}
+                   spellCheck={false}
+                   onChange={(e) => setTerm(e.target.value)} />
+          </SearchField>
+          {frozen ? <span className="pages-panel__working"
+                          data-test-id="pages-panel-working">Working…</span> : null}
+          {words.kind === 'pages' ? <RefreshSiteButton /> : null}
+          <button type="button"
+                  className="pages-panel__create"
+                  data-test-id="pages-panel-create"
+                  disabled={frozen}
+                  data-tooltip={words.kind === 'prefabs' ? 'Create a prefab: blocks to place on many pages, kept in one place' : 'Create a page at a new path'}
+                  aria-label={`Create a ${words.noun}`}
+                  onClick={() => setCreating(true)}>
+            <svg viewBox="0 0 16 16"
+                 aria-hidden="true">
+              <path d="M8 3.2v9.6M3.2 8h9.6"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="1.7" />
+            </svg>
+          </button>
+        </div>
+        {ranked.length === 0 ? (
+          <div className="pages-panel__empty">{searching ? 'Nothing matches' : `No ${listed} yet`}</div>
+        ) : compact ? (
+          <div className="pages-panel__groups">
+            {groups.map(([key, entries]) => (
+              <ul key={key}
+                  className="pages-panel__group"
+                  data-group={key}>
+                {entries.map(({ item, match }) => (
+                  <RouteItem key={item.entity.name}
+                             busyPanel={busyPanel}
+                             route={item}
+                             text={item.pattern}
+                             lit={searching ? match.indices : []}
+                             tree={false}
+                             depth={0}
+                             expanded={expanded.has(item.entity.name)}
+                             highlighted={flash?.name === item.entity.name}
+                             onToggle={() => toggle(item.entity.name)}
+                             onExpand={() => setExpanded((prev) => new Set(prev).add(item.entity.name))}
+                             opener={opener}
+                             registerEl={registerEl} />
+                ))}
+              </ul>
+            ))}
+          </div>
+        ) : (
+          <div className="pages-panel__groups">
+            <ul className="pages-panel__group pages-panel__tree"
+                data-test-id="pages-tree">
+              {treeRows.map(({ node, depth }) => (node.route ? (
+                <RouteItem key={node.path}
+                           busyPanel={busyPanel}
+                           route={node.route}
+                           text={node.segment}
+                           lit={node.lit}
+                           tree
+                           depth={depth}
+                           expanded={expanded.has(node.route.entity.name)}
+                           highlighted={flash?.name === node.route.entity.name}
+                           onToggle={() => toggle(node.route!.entity.name)}
+                           onExpand={() => setExpanded((prev) => new Set(prev).add(node.route!.entity.name))}
+                           opener={opener}
+                           registerEl={registerEl} />
+              ) : (
+                <FolderRow key={node.path}
+                           node={node}
+                           depth={depth}
+                           folded={!searching && folded.has(node.path)}
+                           onFold={() => toggleFold(node.path)} />
+              )))}
+            </ul>
+          </div>
+        )}
+        {creating ? (
+          <CreateModal routes={routes}
+                       own={own}
+                       onClose={() => setCreating(false)}
+                       onJump={(name) => {
+                         setCreating(false);
+                         reveal(name);
+                       }}
+                       onCreated={(name, draftId) => {
+                         setCreating(false);
+                         reveal(name);
+                         opener.openDraft(name, draftId);
+                       }} />
+        ) : null}
+      </div>
+    </TooltipHost>
+  );
+}
+
+/** the list page of the workbench asked for a list that does not exist: say so, offer the way back */
+function NoSuchList({ asked }: { asked: string }) {
+  const route = useRoute();
+  const base = basePathOf(route?.pattern ?? null, route?.path ?? '/');
+  return (
+    <div className="pages-panel pages-panel--none"
+         data-test-id="pages-panel-none">
+      <p>There is no list called “{asked}” — the workbench has pages, prefabs and tile palettes.</p>
+      <p>
+        <Link href={`${base}/pages`}>The pages</Link>
+        {' · '}
+        <Link href={`${base}/prefabs`}>The prefabs</Link>
+      </p>
+    </div>
+  );
+}
+
+// a function DECLARATION, not an arrow in the module literal: the component carries its own name
+function PagesPanel() {
+  const { kind: ownKind, compact = false, kindParam } = useSettings<IPagesPanelSettings>();
+  const route = useRoute();
+  // the kind: the setting, else the page's route parameter the setting names (the list page) —
+  // read off the location where no route was stamped (a document mounted by hand)
+  const named = kindParam ? route?.params[kindParam] : undefined;
+  const located = kindParam && !route && typeof window !== 'undefined'
+    ? parseWorkbenchPath(window.location.pathname, basePathOf(null, window.location.pathname), new URLSearchParams(window.location.search))
+    : null;
+  const asked = typeof named === 'string' ? named : Array.isArray(named) ? named.join('/')
+    : located && (located.view === 'list' || located.view === 'editor') ? located.kind
+      : located?.view === 'distributions' ? DISTRIBUTIONS_SEGMENT : undefined;
+  // the list page also shows where the blocks come from (ADR-0059): `/workbench/distributions`
+  if (!ownKind && asked === DISTRIBUTIONS_SEGMENT) return <DistributionsView />;
+  const kind: ContentKind | null = ownKind ?? (asked === undefined ? 'pages' : kindOfSegment(asked));
+  if (kind === null) return <NoSuchList asked={asked ?? ''} />;
+  const words = kind === 'prefabs' ? PREFAB_WORDS : PAGE_WORDS;
+  return (
+    <EntityWords.Provider value={words}>
+      <EntityPanel compact={compact} />
+    </EntityWords.Provider>
+  );
+}
+
+export default markInternalTile(defineComponentSide<IPagesPanelSettings>({
+  Component: PagesPanel,
+  defaultSettings() {
+    return { compact: false };
+  },
+}));