@contraagent/ui 0.0.0-stage → 0.1.0

package/src/controllers/stream.ts

@@ -0,0 +1,103 @@
+// A task's transcript as it arrives: a saved one folded at once, or one tailed
+// from the monitor's stream feed (`openStreamFeed`), page by page, with "load
+// earlier" through the client. The host re-renders on every page.
+import {
+  openStreamFeed,
+  type MonitorClient,
+  type StreamPage,
+  type TranscriptEvent,
+  type Unsubscribe,
+} from '@contraagent/api';
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { applyEvents, emptyTranscript, type Transcript } from '../adapters/transcript/model.js';
+
+/** How far back "load earlier" reaches, in transcript lines. */
+const EARLIER_LINES = 3000;
+
+/** What to load: a saved transcript, or the transcript of task `stream` in `run`, tailed from `baseUrl`. */
+export type StreamSource = { events: readonly TranscriptEvent[] } | { run: string; stream: string; baseUrl: string };
+
+export class StreamController implements ReactiveController {
+  model: Transcript = emptyTranscript();
+  /** Transcript lines before the first page that are not loaded. */
+  behind = 0;
+  /** The events shown so far: the pages' events that showed something. */
+  count = 0;
+  /** The first page has arrived (a saved transcript: at once). */
+  ready = false;
+  /** Changes with every page, and with every load. */
+  version = 0;
+  /** Changes with every load: a new transcript, or the same one after the host was attached again. */
+  generation = 0;
+  /** The key of what is loaded (`load`); '' after the host was detached. */
+  loaded = '';
+  private close: Unsubscribe | null = null;
+
+  constructor(private readonly host: ReactiveControllerHost) {
+    host.addController(this);
+  }
+
+  /** The feed is open: the transcript is being tailed. */
+  get tailing(): boolean {
+    return this.close !== null;
+  }
+
+  hostDisconnected(): void {
+    this.stop();
+    this.loaded = '';
+  }
+
+  private stop(): void {
+    this.close?.();
+    this.close = null;
+  }
+
+  /** Start over with `source` (none: an empty transcript); `key` names it for `loaded`. */
+  load(key: string, source: StreamSource | null): void {
+    this.stop();
+    this.loaded = key;
+    this.generation++;
+    this.version++;
+    this.model = emptyTranscript();
+    this.behind = 0;
+    this.count = 0;
+    this.ready = false;
+    if (source && 'events' in source) {
+      this.count = applyEvents(this.model, source.events);
+      this.ready = true;
+    } else if (source) {
+      const generation = this.generation;
+      this.close = openStreamFeed(source.run, source.stream, { message: (page) => this.onPage(page, generation) }, { baseUrl: source.baseUrl });
+    }
+  }
+
+  /** More events of the saved transcript loaded last: folded in after the others, the same transcript (no new `generation`). */
+  append(events: readonly TranscriptEvent[]): void {
+    if (!events.length) return;
+    this.count += applyEvents(this.model, events);
+    this.version++;
+  }
+
+  private onPage(page: StreamPage, generation: number): void {
+    if (generation !== this.generation) return;
+    if (!this.ready && page.behind) this.behind = page.behind;
+    this.count += applyEvents(this.model, page.events);
+    this.ready = true;
+    this.version++;
+    this.host.requestUpdate();
+  }
+
+  /** Load the transcript again from further back: the lines `behind` the first page, up to 3000. */
+  async loadEarlier(client: MonitorClient, run: string, stream: string): Promise<void> {
+    const generation = this.generation;
+    const back = Math.max(0, this.behind - EARLIER_LINES);
+    this.behind = 0;
+    this.host.requestUpdate();
+    const page = await client.stream(run, stream, back);
+    if (generation !== this.generation) return;
+    this.model = emptyTranscript();
+    applyEvents(this.model, page.events);
+    this.version++;
+    this.host.requestUpdate();
+  }
+}

package/src/controllers/task-detail.ts

@@ -0,0 +1,54 @@
+// One task's detail (`MonitorClient.task`), fetched for the element that shows
+// it: again whenever the run, the task or the client changes, and only the
+// latest request's answer is kept.
+import type { MonitorClient, TaskDetail } from '@contraagent/api';
+import type { ReactiveControllerHost } from 'lit';
+
+/** The detail of a task the server could not return: no attempts, no files, no definition. */
+export const emptyDetail = (key: string): TaskDetail => ({
+  key,
+  rows: [],
+  launches: [],
+  definition: null,
+  io: { params: {}, inputs: [], outputs: [], executor: 'agent', upstream: [], downstream: [] },
+  stream: null,
+});
+
+/**
+ * Holds `value`, the detail of the task `load` named last: null until it
+ * arrives, `emptyDetail` (and `error`) when the request failed. The host
+ * re-renders when it arrives.
+ */
+export class TaskDetailController {
+  /** The detail; null while it loads, or when there is no task to load. */
+  value: TaskDetail | null = null;
+  /** Why the last request failed; null when it did not. */
+  error: unknown = null;
+  private token = 0;
+
+  constructor(private readonly host: ReactiveControllerHost) {}
+
+  /** Load the detail of `key` in `run`; an earlier request still on its way is dropped. */
+  load(client: MonitorClient | undefined, run: string, key: string | null): void {
+    const token = ++this.token;
+    this.value = null;
+    this.error = null;
+    if (!run || !key || !client) return;
+    void this.fetch(token, client, run, key);
+  }
+
+  private async fetch(token: number, client: MonitorClient, run: string, key: string): Promise<void> {
+    let d: TaskDetail;
+    let error: unknown = null;
+    try {
+      d = await client.task(run, key);
+    } catch (e) {
+      d = emptyDetail(key);
+      error = e;
+    }
+    if (token !== this.token) return;
+    this.value = d;
+    this.error = error;
+    this.host.requestUpdate();
+  }
+}

package/src/controllers/theme.ts

@@ -0,0 +1,73 @@
+// The theme an element shows: the reader's choice, resolved against the
+// system's colour scheme, reflected as `data-ca-theme`.
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { isThemeChoice, preferredTheme, prefersLight, resolveTheme, type ThemeChoice, type ThemeName } from '@contraagent/elements/themes';
+
+export interface ThemeOptions {
+  /** The element's `theme` property: a choice, or '' for the choice remembered from an earlier visit. */
+  theme: () => ThemeChoice | '';
+  /** The element is the page: the theme goes on `<html>` too. */
+  pageWide: () => boolean;
+}
+
+/**
+ * Shows the theme on its host (and on `<html>` when the host is the page),
+ * after every update, and follows the system's colour scheme for `system`.
+ */
+export class ThemeController implements ReactiveController {
+  /** Whether the system asks for a light colour scheme (what `system` follows). */
+  light = prefersLight();
+  private stop: (() => void) | null = null;
+
+  constructor(
+    private readonly host: ReactiveControllerHost & HTMLElement,
+    private readonly opts: ThemeOptions,
+  ) {
+    host.addController(this);
+  }
+
+  /** The reader's choice: the `theme` property, else the choice remembered from an earlier visit. */
+  get choice(): ThemeChoice {
+    const t = this.opts.theme();
+    return isThemeChoice(t) ? t : preferredTheme();
+  }
+
+  /** The theme shown now. */
+  get shown(): ThemeName {
+    return resolveTheme(this.choice, this.light);
+  }
+
+  /** What `system` resolves to now. */
+  get system(): ThemeName {
+    return resolveTheme('system', this.light);
+  }
+
+  hostConnected(): void {
+    this.apply();
+    const scheme = globalThis.matchMedia?.('(prefers-color-scheme: light)');
+    if (!scheme) return;
+    const onScheme = (e: MediaQueryListEvent) => {
+      this.light = e.matches;
+      this.host.requestUpdate();
+    };
+    scheme.addEventListener('change', onScheme);
+    this.stop = () => scheme.removeEventListener('change', onScheme);
+  }
+
+  hostDisconnected(): void {
+    this.stop?.();
+    this.stop = null;
+  }
+
+  hostUpdated(): void {
+    this.apply();
+  }
+
+  /** Show the theme: on the host, and on the page when the host is the page. */
+  private apply(): void {
+    const name = this.shown;
+    if (this.host.getAttribute('data-ca-theme') !== name) this.host.setAttribute('data-ca-theme', name);
+    if (this.opts.pageWide() && document.documentElement.getAttribute('data-ca-theme') !== name)
+      document.documentElement.setAttribute('data-ca-theme', name);
+  }
+}

package/src/core/events.ts

@@ -0,0 +1,120 @@
+// The events the elements send up. Each crosses shadow roots (`composed`) and
+// all but `ca-rounds` bubble, so a host listens on any ancestor. An element
+// states what the reader asked for; whoever hosts it decides what happens (the
+// monitor changes its view route; another page may open its own view).
+import type { LaunchEvent } from '@contraagent/api';
+import type { ViewRoutePatch, TaskView } from './view-route.js';
+import type { ThemeChoice } from '@contraagent/elements/themes';
+
+export interface OpenTaskDetail {
+  /** A task key. */
+  key: string;
+  /** What to show of it; the host's choice when absent. */
+  view?: TaskView;
+}
+
+export interface SelectRunDetail {
+  run: string;
+}
+
+export interface FilterDetail {
+  kind?: string;
+  /** A journal stop, or 'bad' for every attempt that did not complete. */
+  stop?: string;
+  q?: string;
+}
+
+/** Where to go; `replace`: in place of where the reader is (a link that named nothing, set right), not a step back can return to. */
+export type NavigateDetail = ViewRoutePatch & { replace?: boolean };
+
+export interface ChooseThemeDetail {
+  /** The reader's choice: a theme, or `system`. */
+  theme: ThemeChoice;
+}
+
+/** What a journal row says about a try (the fields this needs). */
+export interface TryResult {
+  attempt?: number | null;
+  ok: boolean;
+  stop: string;
+  reason?: string | null;
+  /** The models this try went through, one per hop of the failover chain. */
+  hops?: readonly { model?: string | null; route?: string | null; stop?: string | null }[] | null;
+}
+
+export interface RoundInfo {
+  kind: 'try' | 'fixup' | 'switch';
+  /** 1-based try number. */
+  tryNo: number;
+  /** 0 for a try's first answer, else the fix-up's number within its try. */
+  fixupNo: number;
+  /** 0 for the try's first model, else the model switch's number within the try. */
+  hopNo: number;
+  /** The model of this round's hop, when the journal names it. */
+  model: string;
+  /**
+   * `ok`: this round's output passed (the try's last round, the try succeeded);
+   * `rejected`: a later fix-up in the same try followed it (its output failed its checks);
+   * `failed`: the try's last round, and the try failed;
+   * `switched`: a model switch followed it (its model stopped, e.g. rate limited);
+   * null: not known yet (running).
+   */
+  result: 'ok' | 'rejected' | 'failed' | 'switched' | null;
+  /** For a switched round: how its model's session ended (a stop value). */
+  switchedStop: string;
+  /** For a switched round: the model the next session ran on ('' when the journal names none). */
+  switchedTo: string;
+  /** For a rejected round: the errors the next round was sent back with. */
+  rejectedWith: string[];
+  /** For a failed round: the journal row of its try. */
+  row: TryResult | null;
+}
+
+export interface RoundsChangedDetail {
+  /** Each round's launch event (null for events before any launch). */
+  launches: (LaunchEvent | null)[];
+  /** The round shown, 0-based; -1 while there is none. */
+  shown: number;
+  /** Each round as a try or a fix-up, with its result when known. */
+  rounds: RoundInfo[];
+}
+
+/** Every event an element sends, by name. */
+export interface CaEventMap {
+  /** Open a task: its transcript, or `view` of it. */
+  'ca-open-task': OpenTaskDetail;
+  /** Switch to another run. */
+  'ca-select-run': SelectRunDetail;
+  /** Change a list filter. */
+  'ca-filter': FilterDetail;
+  /** Go elsewhere in the monitor (its own views use this). */
+  'ca-navigate': NavigateDetail;
+  /** Show another theme (the theme control). */
+  'ca-choose-theme': ChooseThemeDetail;
+  /** Close the element (the run picker). */
+  'ca-close': Record<string, never>;
+  /** A transcript's rounds or its shown round changed; does not bubble (`ca-transcript`). */
+  'ca-rounds': RoundsChangedDetail;
+}
+
+declare global {
+  interface HTMLElementEventMap {
+    'ca-open-task': CustomEvent<OpenTaskDetail>;
+    'ca-select-run': CustomEvent<SelectRunDetail>;
+    'ca-filter': CustomEvent<FilterDetail>;
+    'ca-navigate': CustomEvent<NavigateDetail>;
+    'ca-choose-theme': CustomEvent<ChooseThemeDetail>;
+    'ca-close': CustomEvent<Record<string, never>>;
+    'ca-rounds': CustomEvent<RoundsChangedDetail>;
+  }
+}
+
+/** Sends `name` from `from`; it bubbles unless `bubbles: false`. */
+export function emit<K extends keyof CaEventMap>(
+  from: EventTarget,
+  name: K,
+  detail: CaEventMap[K],
+  { bubbles = true }: { bubbles?: boolean } = {},
+): void {
+  from.dispatchEvent(new CustomEvent(name, { detail, bubbles, composed: true }));
+}

package/src/core/i18n.ts

@@ -0,0 +1,76 @@
+// The language the elements speak. English is written in the sources; other
+// locales are generated from xliff/<locale>.xlf by `pnpm i18n`
+// (lit-localize, runtime mode) into src/locales/<locale>.ts.
+//
+// Importing this module configures nothing: `configureLocales()` sets up Lit
+// Localize, once, when the page or `<ca-monitor>` calls it. Until then, and in
+// a page whose own code configured Lit Localize first, the elements speak
+// English. Every element is `@localized()`, so `setLocale` re-renders them in place.
+import { configureLocalization } from '@lit/localize';
+import { allLocales, sourceLocale, targetLocales } from '../locales/codes.js';
+
+export type Locale = (typeof allLocales)[number];
+export { allLocales };
+
+/** Each locale's name, written in itself (for a language switch). */
+export const LOCALE_NAMES: Record<Locale, string> = { en: 'English', ja: '日本語' };
+
+/** Each target locale's module, loaded when the locale is first chosen. */
+const LOADERS: Record<(typeof targetLocales)[number], () => Promise<typeof import('../locales/ja.js')>> = {
+  ja: () => import('../locales/ja.js'),
+};
+
+let localization: ReturnType<typeof configureLocalization> | null | undefined;
+
+/**
+ * Sets up Lit Localize for these elements, once; true when the elements can
+ * switch language. False when the page had already configured Lit Localize
+ * (it can be configured once per page): the elements then stay in English.
+ */
+export function configureLocales(): boolean {
+  if (localization === undefined) {
+    try {
+      localization = configureLocalization({ sourceLocale, targetLocales, loadLocale: (l) => LOADERS[l as keyof typeof LOADERS]() });
+    } catch {
+      localization = null;
+    }
+  }
+  return localization !== null;
+}
+
+/** The language shown now: English before `configureLocales()`. */
+export const getLocale = (): Locale => (localization?.getLocale() as Locale | undefined) ?? sourceLocale;
+
+/** Show every element in `locale`; it configures the locales first if nothing has. */
+export async function setLocale(locale: Locale): Promise<void> {
+  if (configureLocales()) await localization!.setLocale(locale);
+}
+
+const STORE_KEY = 'contraagent:locale';
+
+export const isLocale = (x: unknown): x is Locale => (allLocales as readonly unknown[]).includes(x);
+
+/** The reader's choice from an earlier visit, else the first of the browser's languages we have, else English. */
+export function preferredLocale(): Locale {
+  try {
+    const saved = globalThis.localStorage?.getItem(STORE_KEY);
+    if (isLocale(saved)) return saved;
+  } catch {
+    /* storage blocked: fall through */
+  }
+  for (const lang of globalThis.navigator?.languages ?? []) {
+    const base = lang.toLowerCase().split('-')[0];
+    if (isLocale(base)) return base;
+  }
+  return sourceLocale;
+}
+
+/** Switch every element to `locale`, and remember the choice for the next visit. */
+export async function chooseLocale(locale: Locale): Promise<void> {
+  try {
+    globalThis.localStorage?.setItem(STORE_KEY, locale);
+  } catch {
+    /* storage blocked: the choice lasts for this page */
+  }
+  await setLocale(locale);
+}

package/src/core/index.ts

@@ -0,0 +1,6 @@
+// `@contraagent/ui/core`: the events the elements send, the monitor's view route and
+// view router, and the languages. No element; nothing happens at import.
+export * from './events.js';
+export * from './view-route.js';
+export { ViewRouter, type ViewRouteCause, type ViewRouterMode } from './view-router.js';
+export { LOCALE_NAMES, allLocales, chooseLocale, configureLocales, getLocale, preferredLocale, setLocale, type Locale } from './i18n.js';

package/src/core/memory.ts

@@ -0,0 +1,177 @@
+// What the reader did on a page that the URL does not say: how far a list is
+// scrolled, which cards are open. Kept in the current history entry, so Back,
+// Forward and a reload return to it, and a new entry starts clean.
+//
+// Stored under one key of `history.state`, merged with whatever else a host
+// page keeps there (the host's own state survives). A monitor embedded with
+// `history="memory"` keeps its own instead (`LocalMemory`, `keepMemory`): it
+// leaves the page's history alone, and two monitors on a page do not share it.
+
+const NS = 'contraagent';
+const WRITE_MS = 200;
+
+type Bag = Record<string, unknown> & { entry?: string };
+
+let pending: Bag | null = null;
+/** The entry `pending` belongs to: after Back/Forward it must not land on another one. */
+let pendingEntry = '';
+let timer: ReturnType<typeof setTimeout> | null = null;
+/** Whether the page's `pagehide` writes what is pending: added on the first write, not on import. */
+let flushOnHide = false;
+
+function state(): Record<string, unknown> {
+  const s: unknown = globalThis.history?.state;
+  return s && typeof s === 'object' ? (s as Record<string, unknown>) : {};
+}
+
+function bag(): Bag {
+  const mine = state()[NS];
+  return mine && typeof mine === 'object' ? (mine as Bag) : {};
+}
+
+/** The current entry's id, given one on first use. */
+function entry(): string {
+  const id = bag().entry;
+  if (id) return id;
+  const fresh = Math.random().toString(36).slice(2);
+  history.replaceState({ ...state(), [NS]: { ...bag(), entry: fresh } }, '');
+  return fresh;
+}
+
+function write(): void {
+  if (timer) clearTimeout(timer);
+  timer = null;
+  const p = pending;
+  pending = null;
+  if (!p || !globalThis.history || bag().entry !== pendingEntry) return;
+  history.replaceState({ ...state(), [NS]: { ...bag(), ...p } }, '');
+}
+
+/** The value remembered under `id` in the current history entry. */
+export function recall<T>(id: string): T | undefined {
+  if (!globalThis.history) return undefined;
+  const fromPending = pending && pendingEntry === bag().entry && id in pending;
+  return (fromPending ? pending![id] : bag()[id]) as T | undefined;
+}
+
+/** Remember `value` under `id` in the current history entry (written shortly after, batched). */
+export function remember(id: string, value: unknown): void {
+  if (!globalThis.history) return;
+  const e = entry();
+  if (pending && pendingEntry !== e) pending = null;
+  pendingEntry = e;
+  (pending ??= {})[id] = value;
+  timer ??= setTimeout(write, WRITE_MS);
+  if (!flushOnHide) {
+    flushOnHide = true;
+    globalThis.addEventListener?.('pagehide', flushMemory);
+  }
+}
+
+/** Write what is pending now: before the page pushes a new entry, so it lands on the old one. */
+export function flushMemory(): void {
+  write();
+}
+
+/** Where values are remembered: the page's history entry, or one embedded monitor's own. */
+export interface Memory {
+  recall<T>(id: string): T | undefined;
+  remember(id: string, value: unknown): void;
+}
+
+/** The current history entry of the page (`recall`, `remember`). */
+export const pageMemory: Memory = { recall, remember };
+
+/** Values kept by one element for as long as it lives: the memory of a monitor with `history="memory"`. */
+export class LocalMemory implements Memory {
+  private readonly values = new Map<string, unknown>();
+  recall<T>(id: string): T | undefined {
+    return this.values.get(id) as T | undefined;
+  }
+  remember(id: string, value: unknown): void {
+    this.values.set(id, value);
+  }
+}
+
+const kept = new WeakMap<Node, Memory>();
+
+/** Make `memory` the memory of everything inside `root` (its light and shadow trees); null gives it back to the page. */
+export function keepMemory(root: Node, memory: Memory | null): void {
+  if (memory) kept.set(root, memory);
+  else kept.delete(root);
+}
+
+/** The memory `node` remembers in: that of the nearest root around it (across shadow roots) given one, else the page's. */
+export function memoryOf(node: Node | null | undefined): Memory {
+  for (let n: Node | null | undefined = node; n; n = n.parentNode ?? (n as Partial<ShadowRoot>).host) {
+    const m = kept.get(n);
+    if (m) return m;
+  }
+  return pageMemory;
+}
+
+/** A set of ids remembered under `id` (open cards, folds), in the memory of `from` (read on first use). */
+export class RememberedSet {
+  private items: Set<string> | null = null;
+  constructor(
+    private readonly id: string,
+    private readonly from?: Node,
+  ) {}
+  private get memory(): Memory {
+    return memoryOf(this.from);
+  }
+  private get loaded(): Set<string> {
+    return (this.items ??= new Set(this.memory.recall<string[]>(this.id) ?? []));
+  }
+  has(x: string): boolean {
+    return this.loaded.has(x);
+  }
+  set(x: string, on: boolean): void {
+    const items = this.loaded;
+    if (on === items.has(x)) return;
+    if (on) items.add(x);
+    else items.delete(x);
+    this.memory.remember(this.id, [...items]);
+  }
+  /** Every id in the set. */
+  values(): string[] {
+    return [...this.loaded];
+  }
+  /** Empty the set. */
+  clear(): void {
+    if (!this.loaded.size) return;
+    this.loaded.clear();
+    this.memory.remember(this.id, []);
+  }
+}
+
+/**
+ * A set of ids kept for this browser tab (sessionStorage) rather than one
+ * history entry: state that belongs to a thing shown on several entries, such
+ * as the tool cards open in a transcript. A reload keeps it.
+ */
+export class SessionSet {
+  private readonly items: Set<string>;
+  constructor(private readonly id: string) {
+    let saved: unknown = null;
+    try {
+      saved = JSON.parse(globalThis.sessionStorage?.getItem(`${NS}:${id}`) ?? 'null');
+    } catch {
+      /* storage blocked or corrupt: start empty */
+    }
+    this.items = new Set(Array.isArray(saved) ? saved.filter((x): x is string => typeof x === 'string') : []);
+  }
+  has(x: string): boolean {
+    return this.items.has(x);
+  }
+  set(x: string, on: boolean): void {
+    if (on === this.items.has(x)) return;
+    if (on) this.items.add(x);
+    else this.items.delete(x);
+    try {
+      globalThis.sessionStorage?.setItem(`${NS}:${this.id}`, JSON.stringify([...this.items]));
+    } catch {
+      /* storage blocked or full: the state lives until the page goes */
+    }
+  }
+}

package/src/core/scroll.ts

@@ -0,0 +1,73 @@
+// A scroller that comes back where the reader left it. The position is
+// remembered in a memory (`memory.ts`: the history entry, or an embedded
+// monitor's own); restoring waits until the content, which arrives over the
+// network, is tall enough to scroll there.
+import { pageMemory, type Memory } from './memory.js';
+
+const GIVE_UP_MS = 6000;
+const INPUT_EVENTS = ['wheel', 'touchstart', 'pointerdown', 'keydown'] as const;
+
+export class ScrollMemory {
+  private el: HTMLElement | null = null;
+  private frame = 0;
+  private restoring = false;
+
+  constructor(
+    private readonly id: string,
+    /** Where the position is remembered: read at each use. */
+    private readonly memory: () => Memory = () => pageMemory,
+  ) {}
+
+  attach(el: HTMLElement): void {
+    if (this.el === el) return;
+    this.detach();
+    this.el = el;
+    el.addEventListener('scroll', this.onScroll, { passive: true });
+  }
+
+  detach(): void {
+    this.cancel();
+    this.el?.removeEventListener('scroll', this.onScroll);
+    this.el = null;
+  }
+
+  /** Go back to the remembered position, as soon as the content allows; to the top when none is remembered. */
+  restore(): void {
+    const el = this.el;
+    if (!el) return;
+    this.cancel();
+    const target = this.memory().recall<number>(this.id) ?? 0;
+    if (target <= 0) {
+      el.scrollTop = 0;
+      return;
+    }
+    const until = performance.now() + GIVE_UP_MS;
+    this.restoring = true;
+    for (const t of INPUT_EVENTS) el.addEventListener(t, this.cancel, { passive: true, once: true });
+    const step = () => {
+      const max = el.scrollHeight - el.clientHeight;
+      el.scrollTop = Math.min(target, max);
+      if (max >= target || performance.now() > until) return this.cancel();
+      this.frame = requestAnimationFrame(step);
+    };
+    step();
+  }
+
+  /** Start at the top (a new place). */
+  reset(): void {
+    this.cancel();
+    if (this.el) this.el.scrollTop = 0;
+  }
+
+  private readonly cancel = (): void => {
+    cancelAnimationFrame(this.frame);
+    this.frame = 0;
+    if (!this.restoring) return;
+    this.restoring = false;
+    for (const t of INPUT_EVENTS) this.el?.removeEventListener(t, this.cancel);
+  };
+
+  private readonly onScroll = (): void => {
+    if (!this.restoring && this.el) this.memory().remember(this.id, Math.round(this.el.scrollTop));
+  };
+}