@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/workbench/workspace.ts

@@ -0,0 +1,775 @@
+// The WORKSPACE: the editor page's state as one service — the open tabs and the one in front,
+// whether the tree column shows and how wide — and the address bar as its persistent form
+// (workbenchAddress). The editor is one page of the workbench (`/workbench/{kind}/{name}`,
+// ADR-0051 §4): a document coming to the front is a SHALLOW move of the client router (the
+// address changes, the document of the page does not); leaving for a list or Home is a move to
+// another page. The address speaks first on a load: every `open` entry gets a tab, its session
+// keyed before any canvas mounts, its document loaded straight into it; without entries, the
+// tabs this browser tab remembered (sessionStorage) come back — a visit to a list loses nothing.
+//
+// Documents live in the editing sessions (one per tab, keyed by the tab id — the canvas picks its
+// session up by that key); the workspace reads what a tab shows from its session, never from a
+// copy: a draft that was published reopens as the revision it became, a page deleted leaves its
+// tab closing, and the tab's title follows.
+//
+// Created by the editor block and registered in the DI so the other blocks — the quick picker
+// opening a document, the canvas toggling the tree — find it optionally: outside the editor they
+// simply do without (the pages list moves to the editor's address instead).
+import { DiContainer, SingleDiToken } from '@mosetta/di';
+import {
+  ContentKind,
+  EditingSession,
+  EditingSessionHub,
+  ILoadedContent,
+  ILoadedDraft,
+  IPageDoc,
+} from '@mosetta/content';
+import { fullServerTileId } from '@mosetta/server-action/core';
+import {
+  ensureServerActionClient,
+  IServerDataHandle,
+  SERVER_DATA_MANAGER,
+} from '@mosetta/server-action/client';
+import type { ITileReference } from '@mosetta/core';
+import type { IRouter } from '@mosetta/runtime/client';
+import {
+  ContentActionResult,
+  IPageListEntry,
+  listPagesToken,
+  loadPageDraftToken,
+  loadPageToken,
+} from '../content/contentCommon';
+import {
+  DRAFT_PARAM,
+  IEditorAddress,
+  IOpenDoc,
+  isUnversioned,
+  OPEN_PARAM,
+  parseEditorAddress,
+  parseOpenDocs,
+  pathOfView,
+  REVISION_PARAM,
+  sameDoc,
+  serializeOpenDocs,
+  TABS_MEMORY_KEY,
+  TOOL_PARAM,
+  TOOL_STATE_PARAM,
+  TREE_PARAM,
+} from './workbenchAddress';
+import type { IToolAddress } from './workbenchAddress';
+import { forgetRecent, noteRecent } from './recent';
+import { noticesOf } from '../content/editingNotices';
+
+export interface IWorkspaceTab {
+  readonly id: string;
+  /** the document the tab shows — its session's word once the load landed */
+  readonly doc: IOpenDoc;
+  /** the words on the tab: the route (or the prefab's name) and the version */
+  readonly label: string;
+  readonly title: string;
+  readonly loading: boolean;
+}
+
+export interface IWorkspaceState {
+  readonly tabs: readonly IWorkspaceTab[];
+  /** the tab in front (its canvas shows); null with no tabs */
+  readonly front: string | null;
+  readonly treeShown: boolean;
+  /** the tree column's width for the document in front */
+  readonly treeWidth: number;
+  /** the quick picker showing, with which list */
+  readonly picker: ContentKind | null;
+}
+
+export abstract class Workspace {
+  /** the path the workbench lives under (`/workbench`) */
+  abstract readonly base: string;
+
+  abstract readonly snapshot: () => IWorkspaceState;
+
+  abstract readonly subscribe: (listener: () => void) => () => void;
+
+  /** leave the editor for Home or a list — a move to another page of the workbench */
+  abstract go(view: 'home' | ContentKind): void;
+
+  /**
+   * Show a document in the editor: the tab already showing it comes to the front, otherwise a
+   * fresh tab opens and the document loads into it (`loaded` spares the load when the caller
+   * holds the document already — a draft just created). A document named without a version
+   * opens its live revision, or its newest draft while nothing is published.
+   */
+  abstract open(doc: IOpenDoc, loaded?: IPageDoc): void;
+
+  /** bring an open tab to the front */
+  abstract activate(tabId: string): void;
+
+  abstract close(tabId: string): void;
+
+  abstract setTreeShown(shown: boolean): void;
+
+  /** the tree column's width for the document in front — remembered for that document */
+  abstract setTreeWidth(width: number): void;
+
+  /** show the quick picker with this list — or close it when it shows this list already */
+  abstract togglePicker(kind: ContentKind): void;
+
+  abstract closePicker(): void;
+
+  /** fires when the tab comes to the front; returns the unsubscribe */
+  abstract onDidActivate(tabId: string, listener: () => void): () => void;
+
+  /** the editor tool open over a tab's document, and its state — the address carries the front one's */
+  abstract toolOf(tabId: string): IToolAddress | null;
+
+  /** a tab's canvas opened a tool, closed it, or the tool's state moved */
+  abstract setTool(tabId: string, tool: IToolAddress | null): void;
+
+  /** the front tab's session takes the focus — after the canvases mounted (each claims it) */
+  abstract focusFront(): void;
+
+  /** a page (or prefab) that is gone leaves the recent list; `tell` says so in a notice */
+  abstract forget(doc: Pick<IOpenDoc, 'kind' | 'page'>, tell?: boolean): void;
+
+  /** the address moved under the editor (Back, a link): the tabs follow it */
+  abstract locate(address: IEditorAddress): void;
+}
+
+export const WORKSPACE_TOKEN = new SingleDiToken<Workspace>('WORKSPACE_TOKEN');
+
+/** which column shows the tree — a preference of this browser, not content */
+const TREE_SHOWN_KEY = 'mosetta-workbench-tree';
+/** the tree's width per document (`kind/page` → px) — this browser's, the address carries the front one */
+const TREE_WIDTHS_KEY = 'mosetta-workbench-tree-widths';
+export const TREE_WIDTH_DEFAULT = 280;
+export const TREE_WIDTH_MIN = 180;
+export const TREE_WIDTH_MAX = 1200;
+
+/** a width the column can take: an integer between the bounds, or null for anything else */
+export function treeWidthOf(value: string | number | null | undefined): number | null {
+  const width = typeof value === 'string' ? Number(value) : value;
+  if (width === null || width === undefined || !Number.isInteger(width)) return null;
+  return width >= TREE_WIDTH_MIN && width <= TREE_WIDTH_MAX ? width : null;
+}
+
+type TDraftInput = { name: string; draftId: string; kind?: ContentKind };
+type TDraftOutput = ContentActionResult<{ draft: ILoadedDraft<IPageDoc> }>;
+type TRevisionInput = { name: string; rev: number; kind?: ContentKind };
+type TRevisionOutput = ContentActionResult<{ page: ILoadedContent<IPageDoc> }>;
+type TListInput = { kind?: ContentKind };
+type TListOutput = ContentActionResult<{ pages: IPageListEntry[] }>;
+
+interface ITabRecord {
+  readonly id: string;
+  /** what was asked for — the session says what is actually shown once the load landed */
+  wanted: IOpenDoc;
+  /** the drafts this tab held that BECAME revisions: an address naming one still finds the tab */
+  retired: IOpenDoc[];
+  /** the document reached the session once: an empty session after that means the page is gone */
+  loaded: boolean;
+  loading: boolean;
+  unsubscribe: () => void;
+}
+
+/** the version to show when the address names the page alone */
+export function defaultVersionOf(entry: IPageListEntry): IOpenDoc | null {
+  const doc = { kind: 'pages' as ContentKind, page: entry.name };
+  if (entry.meta.live != null) return { ...doc, revision: entry.meta.live };
+  const newest = [...entry.drafts].sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0];
+  return newest ? { ...doc, draftId: newest.id } : null;
+}
+
+/** the tab's words: the route (a prefab's name) and the version it shows */
+export function tabLabelOf(doc: IOpenDoc, page: IPageDoc | null): { title: string; label: string } {
+  const title = doc.kind === 'prefabs' ? doc.page : page?.pattern ?? doc.page;
+  const version = doc.revision !== undefined
+    ? `r${doc.revision}`
+    : doc.draftId !== undefined ? page?.title ?? doc.draftId.slice(0, 8) : '';
+  return { title, label: version ? `${title} · ${version}` : title };
+}
+
+/** the document a session shows, in the address's shape */
+function docOfSession(held: { kind: ContentKind; pageName: string | null; draftId: string | null; revision: number | null }): IOpenDoc {
+  return {
+    kind: held.kind,
+    page: held.pageName ?? '',
+    ...(held.draftId !== null ? { draftId: held.draftId } : held.revision !== null ? { revision: held.revision } : {}),
+  };
+}
+
+/** the minimal query encoder of @mosetta/runtime: the address stays readable (ADR-0038) */
+function queryText(part: string): string {
+  return encodeURIComponent(part)
+    .replace(/%2C/gi, ',')
+    .replace(/%3A/gi, ':')
+    .replace(/%3B/gi, ';')
+    .replace(/%40/gi, '@')
+    .replace(/%2F/gi, '/')
+    .replace(/%7E/gi, '~');
+}
+
+/** a width's key: the document, whichever version of it is open */
+const docKeyOf = (doc: IOpenDoc): string => `${doc.kind}/${doc.page}`;
+
+function readWidths(host: Pick<Window, 'localStorage'>): Map<string, number> {
+  try {
+    const parsed: unknown = JSON.parse(host.localStorage.getItem(TREE_WIDTHS_KEY) ?? '{}');
+    const widths = new Map<string, number>();
+    if (parsed && typeof parsed === 'object') {
+      for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+        const width = treeWidthOf(typeof value === 'number' ? value : null);
+        if (width !== null) widths.set(key, width);
+      }
+    }
+    return widths;
+  } catch {
+    return new Map();
+  }
+}
+
+function writeWidths(host: Pick<Window, 'localStorage'>, widths: ReadonlyMap<string, number>): void {
+  try {
+    host.localStorage.setItem(TREE_WIDTHS_KEY, JSON.stringify(Object.fromEntries(widths)));
+  } catch {
+    // a document that denies storage: the widths live for the page only
+  }
+}
+
+function readFlag(host: Pick<Window, 'localStorage'>, key: string, fallback: boolean): boolean {
+  try {
+    const raw = host.localStorage.getItem(key);
+    return raw === null ? fallback : raw === '1';
+  } catch {
+    return fallback;
+  }
+}
+
+function writeFlag(host: Pick<Window, 'localStorage'>, key: string, value: boolean): void {
+  try {
+    host.localStorage.setItem(key, value ? '1' : '0');
+  } catch {
+    // a document that denies storage: the preference lives for the page only
+  }
+}
+
+/** the tabs this browser tab remembers, for a return from a list without `?open=` */
+function readRememberedTabs(host: Pick<Window, 'sessionStorage'>): IOpenDoc[] {
+  try {
+    return parseOpenDocs(host.sessionStorage.getItem(TABS_MEMORY_KEY));
+  } catch {
+    return [];
+  }
+}
+
+function rememberTabs(host: Pick<Window, 'sessionStorage'>, open: string | null): void {
+  try {
+    if (open === null) host.sessionStorage.removeItem(TABS_MEMORY_KEY);
+    else host.sessionStorage.setItem(TABS_MEMORY_KEY, open);
+  } catch {
+    // a document that denies storage: the tabs live in the address only
+  }
+}
+
+/** a history entry the client router made — its pops are the router's, not ours */
+const isRouterEntry = (state: unknown): boolean => typeof state === 'object' && state !== null && 'mosetta' in state;
+
+export class AddressWorkspace extends Workspace {
+  readonly base: string;
+
+  private readonly listeners = new Set<() => void>();
+
+  private readonly activations = new Map<string, Set<() => void>>();
+
+  private readonly tabs: ITabRecord[] = [];
+
+  private front: string | null = null;
+
+  private treeShown: boolean;
+
+  private readonly treeWidths: Map<string, number>;
+
+  /** the tool open over each document (`kind/page`), as the address names it for the one in front */
+  private readonly tools = new Map<string, IToolAddress>();
+
+  private picker: ContentKind | null = null;
+
+  private state: IWorkspaceState | null = null;
+
+  private counter = 0;
+
+  /** the listing is asked once per unversioned open — remembered while it is in the air */
+  private listing: IServerDataHandle<TListOutput, TListInput> | null = null;
+
+  constructor(
+    private readonly di: DiContainer,
+    private readonly hub: EditingSessionHub,
+    private readonly reference: ITileReference,
+    private readonly host: Window & typeof globalThis,
+    base: string,
+    private readonly router: IRouter | null,
+  ) {
+    super();
+    this.base = base;
+    this.treeShown = readFlag(host, TREE_SHOWN_KEY, true);
+    this.treeWidths = readWidths(host);
+    this.restore();
+  }
+
+  /**
+   * Follow the browser's Back and Forward while the editor is mounted — for the entries the
+   * client router did not make (its own it answers itself, and the route change reaches
+   * `locate` through the editor block); returns the detach.
+   */
+  attach(): () => void {
+    this.host.addEventListener('popstate', this.onPopState);
+    return () => this.host.removeEventListener('popstate', this.onPopState);
+  }
+
+  // ---- the state ------------------------------------------------------------------------------
+
+  readonly snapshot = (): IWorkspaceState => {
+    if (!this.state) {
+      this.state = {
+        front: this.front,
+        treeShown: this.treeShown,
+        treeWidth: this.treeWidthOfFront(),
+        picker: this.picker,
+        tabs: this.tabs.map((tab) => {
+          const held = this.hub.peek(tab.id)?.snapshot() ?? null;
+          const doc = held?.pageName ? docOfSession(held) : tab.wanted;
+          return { id: tab.id, doc, loading: tab.loading, ...tabLabelOf(doc, held?.doc ?? null) };
+        }),
+      };
+    }
+    return this.state;
+  };
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  private emit(): void {
+    this.state = null;
+    for (const listener of [...this.listeners]) listener();
+  }
+
+  // ---- navigation -----------------------------------------------------------------------------
+
+  go(view: 'home' | ContentKind): void {
+    this.picker = null;
+    this.emit();
+    const { pathname } = pathOfView(this.base, view === 'home' ? { view: 'home' } : { view: 'list', kind: view });
+    this.moveTo(pathname);
+  }
+
+  open(doc: IOpenDoc, loaded?: IPageDoc): void {
+    this.picker = null;
+    if (isUnversioned(doc)) {
+      this.resolveVersion(doc);
+      return;
+    }
+    const tab = this.findTab(doc) ?? this.openTab(doc, loaded);
+    this.bringFront(tab);
+    this.record(true);
+    this.emit();
+  }
+
+  activate(tabId: string): void {
+    const tab = this.tabs.find((candidate) => candidate.id === tabId);
+    if (!tab) return;
+    this.bringFront(tab);
+    this.record(true);
+    this.emit();
+  }
+
+  close(tabId: string): void {
+    const at = this.tabs.findIndex((tab) => tab.id === tabId);
+    if (at < 0) return;
+    const [closed] = this.tabs.splice(at, 1);
+    closed.unsubscribe();
+    this.activations.delete(closed.id);
+    this.hub.retire(closed.id);
+    if (this.front === closed.id) {
+      // the neighbour to the right takes the front, else the one to the left; the last tab
+      // closing leaves for the list the document came from
+      const next = this.tabs[at] ?? this.tabs[at - 1] ?? null;
+      this.front = next?.id ?? null;
+      if (!next) {
+        this.picker = null;
+        rememberTabs(this.host, null);
+        this.emit();
+        this.go(closed.wanted.kind);
+        return;
+      }
+      this.focusFront();
+      this.record(true);
+    } else {
+      this.record(false);
+    }
+    this.emit();
+  }
+
+  setTreeShown(shown: boolean): void {
+    this.treeShown = shown;
+    writeFlag(this.host, TREE_SHOWN_KEY, shown);
+    this.emit();
+  }
+
+  setTreeWidth(width: number): void {
+    const key = this.frontDocKey();
+    const fitted = treeWidthOf(Math.round(width));
+    if (!key || fitted === null) return;
+    this.treeWidths.set(key, fitted);
+    writeWidths(this.host, this.treeWidths);
+    this.record(false);
+    this.emit();
+  }
+
+  togglePicker(kind: ContentKind): void {
+    this.picker = this.picker === kind ? null : kind;
+    this.emit();
+  }
+
+  closePicker(): void {
+    if (this.picker === null) return;
+    this.picker = null;
+    this.emit();
+  }
+
+  onDidActivate(tabId: string, listener: () => void): () => void {
+    let set = this.activations.get(tabId);
+    if (!set) {
+      set = new Set();
+      this.activations.set(tabId, set);
+    }
+    set.add(listener);
+    return () => {
+      set.delete(listener);
+    };
+  }
+
+  focusFront(): void {
+    if (this.front && this.tabs.some((tab) => tab.id === this.front)) this.hub.focus(this.front);
+  }
+
+  forget(doc: Pick<IOpenDoc, 'kind' | 'page'>, tell = false): void {
+    const known = forgetRecent(this.host, doc);
+    // the author reached for it — from the recent list, or through the address — and found it
+    // gone: said in a notice, since nothing else on screen explains the empty-handed return
+    if (tell) {
+      const what = known?.title ?? doc.page;
+      noticesOf(this.di)?.show('refuse', `${doc.kind === 'prefabs' ? 'The prefab' : 'The page'} ${what} is gone${known ? ' — it left the recent list' : ''}`);
+    }
+  }
+
+  /**
+   * The address under the editor changed (a Back, a link into the editor): the tabs it names
+   * are opened if this workspace lacks them, the document it names comes to the front — nothing
+   * when it is in front already (the workspace's own move coming back as a route change).
+   */
+  locate(address: IEditorAddress): void {
+    for (const doc of address.open) {
+      if (!this.findTab(doc)) this.openTab(doc);
+    }
+    if (address.tool) this.tools.set(docKeyOf(address.doc), address.tool);
+    else this.tools.delete(docKeyOf(address.doc));
+    if (address.tree !== null) {
+      const width = treeWidthOf(address.tree);
+      if (width !== null) {
+        this.treeWidths.set(docKeyOf(address.doc), width);
+        writeWidths(this.host, this.treeWidths);
+      }
+    }
+    if (isUnversioned(address.doc)) {
+      this.resolveVersion(address.doc);
+      return;
+    }
+    const tab = this.findTab(address.doc) ?? this.openTab(address.doc);
+    this.bringFront(tab);
+    this.record(false);
+    this.emit();
+  }
+
+  /** the tab comes to the front: its listeners are told, its session takes the focus */
+  private bringFront(tab: ITabRecord): void {
+    if (this.front === tab.id) return;
+    this.front = tab.id;
+    for (const listener of [...(this.activations.get(tab.id) ?? [])]) listener();
+    this.focusFront();
+  }
+
+  private readonly onPopState = (event: PopStateEvent): void => {
+    if (isRouterEntry(event.state)) return; // the router's own: it re-reads the route, the editor block locates
+    const address = parseEditorAddress(this.host.location.pathname, this.base, new this.host.URLSearchParams(this.host.location.search));
+    if (address) this.locate(address);
+  };
+
+  /** a move to another page of the workbench: the router's, or the browser's where there is none */
+  private moveTo(pathname: string): void {
+    const fallback = (): void => this.host.location.assign(pathname);
+    if (!this.router) {
+      fallback();
+      return;
+    }
+    void this.router.navigate(pathname).then((taken) => {
+      if (!taken) fallback();
+    });
+  }
+
+  // ---- the address ----------------------------------------------------------------------------
+
+  /**
+   * The address from the state; other parameters (a search term) stay as they were. A SHALLOW
+   * move of the router — the same page, a new address — and the history API where the router has
+   * no say (a realm with no route stamped).
+   */
+  private record(push: boolean): void {
+    const url = new this.host.URL(this.host.location.href);
+    const params = new this.host.URLSearchParams(url.search);
+    for (const owned of [OPEN_PARAM, DRAFT_PARAM, REVISION_PARAM, TREE_PARAM, TOOL_PARAM, TOOL_STATE_PARAM]) params.delete(owned);
+    const front = this.tabs.find((tab) => tab.id === this.front);
+    if (!front) return;
+    // the workspace outlives the editor page (its tabs wait for the way back): while another
+    // page of the workbench shows, a document OPENED here means a move to the editor's page,
+    // and anything else (a load landing behind the scenes) leaves the address alone
+    const onEditor = parseEditorAddress(url.pathname, this.base, params) !== null;
+    if (!onEditor) {
+      if (!push) return;
+      const doc = this.docOf(front);
+      const { pathname, version } = pathOfView(this.base, { view: 'editor', ...doc });
+      const query = new this.host.URLSearchParams(version).toString();
+      rememberTabs(this.host, serializeOpenDocs(this.tabs.map((tab) => this.docOf(tab))));
+      this.moveTo(query ? `${pathname}?${query}` : pathname);
+      return;
+    }
+    const doc = this.docOf(front);
+    const { pathname, version } = pathOfView(this.base, { view: 'editor', ...doc });
+    for (const [name, value] of Object.entries(version)) params.set(name, value);
+    const open = serializeOpenDocs(this.tabs.map((tab) => this.docOf(tab)));
+    if (open !== null) params.set(OPEN_PARAM, open);
+    rememberTabs(this.host, open);
+    // the tree's width rides with the document in front, when it is not the default one
+    const width = this.treeWidths.get(docKeyOf(doc));
+    if (width !== undefined && width !== TREE_WIDTH_DEFAULT) params.set(TREE_PARAM, String(width));
+    // …and so does the tool open over it, with what of the tool is open
+    const tool = this.tools.get(docKeyOf(doc));
+    if (tool) {
+      params.set(TOOL_PARAM, tool.tool);
+      if (tool.state) params.set(TOOL_STATE_PARAM, tool.state);
+    }
+    url.pathname = pathname;
+    url.search = [...params].map(([key, item]) => `${queryText(key)}=${queryText(item)}`).join('&');
+    if (url.href === this.host.location.href) return;
+    const write = (): void => {
+      try {
+        if (push) this.host.history.pushState(null, '', url.href);
+        else this.host.history.replaceState(this.host.history.state, '', url.href);
+      } catch {
+        // browsers throttle history writes (Safari: ~100 per 30s) and THROW past the limit — the
+        // address is the state's mirror, not the state; a dropped write is caught up by the next
+      }
+    };
+    if (!this.router) {
+      write();
+      return;
+    }
+    void this.router.navigate(url.href, { shallow: true, replace: !push, scroll: false }).then((taken) => {
+      if (!taken) write();
+    });
+  }
+
+  /**
+   * The address speaks first: every `open` entry gets a tab with its document loading, the
+   * document in the path gets the front — opened too when the entries left it out. Without
+   * entries, the tabs this browser tab remembered come back. A page named without a version is
+   * looked up in the listing first.
+   */
+  private restore(): void {
+    const address = parseEditorAddress(this.host.location.pathname, this.base, new this.host.URLSearchParams(this.host.location.search));
+    if (!address) return;
+    const open = address.open.length > 0 ? address.open : readRememberedTabs(this.host);
+    this.locate({ ...address, open });
+  }
+
+  // ---- the tools ------------------------------------------------------------------------------
+
+  toolOf(tabId: string): IToolAddress | null {
+    const tab = this.tabs.find((candidate) => candidate.id === tabId);
+    return tab ? this.tools.get(docKeyOf(this.docOf(tab))) ?? null : null;
+  }
+
+  setTool(tabId: string, tool: IToolAddress | null): void {
+    const tab = this.tabs.find((candidate) => candidate.id === tabId);
+    if (!tab) return;
+    const key = docKeyOf(this.docOf(tab));
+    const was = this.tools.get(key);
+    if (tool ? was?.tool === tool.tool && was.state === tool.state : !was) return;
+    if (tool) this.tools.set(key, tool);
+    else this.tools.delete(key);
+    if (this.front === tabId) this.record(false);
+  }
+
+  // ---- the tabs -------------------------------------------------------------------------------
+
+  /** the document in front, as the widths are keyed: `kind/page` — a prefab and a page apart */
+  private frontDocKey(): string | null {
+    const tab = this.tabs.find((candidate) => candidate.id === this.front);
+    return tab ? docKeyOf(this.docOf(tab)) : null;
+  }
+
+  private treeWidthOfFront(): number {
+    const key = this.frontDocKey();
+    return (key ? this.treeWidths.get(key) : undefined) ?? TREE_WIDTH_DEFAULT;
+  }
+
+  private findTab(doc: IOpenDoc): ITabRecord | null {
+    return this.tabs.find((tab) => sameDoc(this.docOf(tab), doc))
+      ?? this.tabs.find((tab) => tab.retired.some((was) => sameDoc(was, doc)))
+      ?? null;
+  }
+
+  private docOf(tab: ITabRecord): IOpenDoc {
+    const held = this.hub.peek(tab.id)?.snapshot();
+    return held?.pageName ? docOfSession(held) : tab.wanted;
+  }
+
+  private openTab(doc: IOpenDoc, loaded?: IPageDoc): ITabRecord {
+    this.counter += 1;
+    const id = `c${this.counter}`;
+    const session = this.hub.sessionFor(id);
+    const tab: ITabRecord = { id, wanted: doc, retired: [], loaded: false, loading: false, unsubscribe: () => undefined };
+    tab.unsubscribe = session.subscribe(() => this.onSessionChange(tab));
+    this.tabs.push(tab);
+    // the session may hold the document already: the default session, adopted with the work
+    // started before any tab existed (a draft created from the list)
+    if (sameDoc(docOfSession(session.snapshot()), doc) && session.snapshot().doc) {
+      tab.loaded = true;
+      this.noteRecent(tab);
+    } else if (loaded && doc.draftId !== undefined) {
+      session.openPage(doc.page, doc.draftId, loaded, doc.kind);
+    } else {
+      this.load(tab, session);
+    }
+    return tab;
+  }
+
+  private load(tab: ITabRecord, session: EditingSession): void {
+    const { wanted } = tab;
+    tab.loading = true;
+    let settled = false;
+    const settle = (): void => {
+      settled = true;
+      tab.loading = false;
+      // a document landing in a session is an act of selection there (the anchor moves to it):
+      // the tab in front keeps the focus — a restored tab behind it must not pull the tree over
+      this.focusFront();
+      this.record(false);
+      this.emit();
+    };
+    if (wanted.revision !== undefined) {
+      const handle = this.handleOf<TRevisionInput, TRevisionOutput>(loadPageToken);
+      handle.subscribe(() => {
+        const data = handle.snapshot();
+        if (data.isLoading() || settled) return;
+        if (data.isSuccess() && data.serverData.ok) {
+          const { page } = data.serverData;
+          session.openRevision(page.name, page.rev, page.doc, wanted.kind);
+        } else {
+          // the revision is gone from the store: nothing to show — and when the store itself
+          // said so (not a transport failure), the page has no place in the recent list either
+          if (data.isSuccess()) this.forget(wanted, true);
+          this.dropTab(tab);
+        }
+        settle();
+      });
+      handle.snapshot().start!({ name: wanted.page, rev: wanted.revision, kind: wanted.kind });
+    } else {
+      const handle = this.handleOf<TDraftInput, TDraftOutput>(loadPageDraftToken);
+      handle.subscribe(() => {
+        const data = handle.snapshot();
+        if (data.isLoading() || settled) return;
+        if (data.isSuccess() && data.serverData.ok) {
+          const { draft } = data.serverData;
+          session.openPage(draft.name, draft.id, draft.doc, wanted.kind);
+        } else {
+          if (data.isSuccess()) this.forget(wanted, true);
+          this.dropTab(tab);
+        }
+        settle();
+      });
+      handle.snapshot().start!({ name: wanted.page, draftId: wanted.draftId!, kind: wanted.kind });
+    }
+  }
+
+  /** the page named without a version: the listing says which version stands for it */
+  private resolveVersion(doc: IOpenDoc): void {
+    const listing = this.listing ?? this.handleOf<TListInput, TListOutput>(listPagesToken);
+    this.listing = listing;
+    let settled = false;
+    listing.subscribe(() => {
+      const data = listing.snapshot();
+      if (data.isLoading() || settled) return;
+      settled = true;
+      this.listing = null;
+      const entry = data.isSuccess() && data.serverData.ok ? data.serverData.pages.find((page) => page.name === doc.page) : undefined;
+      const resolved = entry ? defaultVersionOf(entry) : null;
+      if (resolved) this.open({ ...resolved, kind: doc.kind });
+      else {
+        // a page with no versions at all (or none at all) cannot be shown: the list it was
+        // named in — and a page the listing does not know leaves the recent list
+        if (data.isSuccess() && data.serverData.ok && !entry) this.forget(doc, true);
+        if (this.tabs.length === 0) this.go(doc.kind);
+      }
+    });
+    listing.snapshot().start!({ kind: doc.kind });
+  }
+
+  /** the session changed: a page gone closes its tab; a landed document names it and the recent */
+  private onSessionChange(tab: ITabRecord): void {
+    const held = this.hub.peek(tab.id)?.snapshot();
+    if (!held) return;
+    if (held.pageName && held.doc) {
+      const landed = !tab.loaded;
+      tab.loaded = true;
+      if (landed || !sameDoc(tab.wanted, docOfSession(held))) {
+        const next = docOfSession(held);
+        // a draft published from elsewhere reopens here as the revision it became: the address
+        // that still names the draft must find this tab, not open a second one for a draft gone
+        if (!landed && tab.wanted.draftId !== undefined && next.revision !== undefined) tab.retired.push(tab.wanted);
+        tab.wanted = next;
+        this.noteRecent(tab);
+      }
+    } else if (tab.loaded) {
+      this.dropTab(tab);
+      return;
+    }
+    this.record(false);
+    this.emit();
+  }
+
+  private dropTab(tab: ITabRecord): void {
+    if (this.tabs.includes(tab)) this.close(tab.id);
+  }
+
+  private noteRecent(tab: ITabRecord): void {
+    const held = this.hub.peek(tab.id)?.snapshot();
+    const doc = this.docOf(tab);
+    const { title } = tabLabelOf(doc, held?.doc ?? null);
+    noteRecent(this.host, { kind: doc.kind, page: doc.page, title, at: Date.now() });
+  }
+
+  private handleOf<TIn, TOut>(token: typeof loadPageDraftToken | typeof loadPageToken | typeof listPagesToken): IServerDataHandle<TOut, TIn> {
+    ensureServerActionClient(this.di);
+    return this.di.getByToken(SERVER_DATA_MANAGER).createManual<TIn, TOut>({
+      fullId: fullServerTileId({
+        namespace: this.reference.namespace,
+        version: this.reference.version,
+        name: token.serverModuleName ?? this.reference.name,
+      }),
+      actionName: token.actionName,
+      invalidates: token.invalidates ?? [],
+    });
+  }
+}