@react-x11/components 0.1.0 → 0.2.1

package/src/internal/heights.ts

@@ -0,0 +1,222 @@
+// Where every row starts, when rows are not all the same height.
+//
+// **Shared between `<Tree>` and `<Table>`** — the first piece of machinery
+// both virtualizers stand on (`./timers.ts` and `./scroll.ts` are the other
+// two), promoted here from the vendored copy the table briefly carried
+// (docs/prd-table.md records the decision). "No component imports another
+// component" holds: this is shared code, not a component, and both import
+// it.
+//
+// **Deliberately not a shared *module*.** The directory has no `index.ts`,
+// so it has no subpath, no docs page, and is not public API — the repo's
+// guards (`test/docs.test.ts`, `scripts/check-package.ts`) key on
+// `src/<name>/index.ts`, and that is the seam this uses. The day an app
+// outside this package needs a height index of its own, the promotion is
+// mechanical: give the directory an `index.ts` and the full shared-module
+// treatment (subpath, page, barrel), the way `richtext` has it.
+//
+// The id-keying earns its place twice: in the tree a measured height
+// survives a collapse and re-expand, and in the table it survives a
+// **re-sort** — the permutation rebuilds offsets without remeasuring a
+// single row.
+//
+// A fixed-height list needs no structure at all: row `i` is at `i * h`, and
+// the row at offset `y` is `y / h`. That one multiplication is the whole
+// reason fixed-height virtualization is easy, and it is what this file
+// replaces — because a tree row wraps, carries two lines, or is whatever a
+// render seam returned, and demanding that they all match would be the
+// component telling the application what its data may look like.
+//
+// What replaces it has to answer three questions on every scroll, over a
+// list that may be a hundred thousand rows long:
+//
+//   - where does row `i` start?           `offsetAt`
+//   - which row is at offset `y`?         `indexAt`
+//   - how tall is the whole thing?        `total`
+//
+// A prefix-sum array answers the first and third in O(1) but costs O(n) per
+// measurement, and measurements arrive in bursts — every row that scrolls
+// into view is one. A Fenwick tree (binary indexed tree) answers all three in
+// O(log n) and updates in O(log n), which is what makes "measure the rows
+// that just appeared, then re-render" affordable at any size.
+
+/** What a row is keyed by. `TreeItemId` and `TableRowId` are both this
+ *  type; keeping it structural here is what lets each component keep its
+ *  own vocabulary. */
+export type RowKey = string | number;
+
+/** All this needs of a row. Taking the rows themselves rather than an array
+ *  of ids is what keeps `sync` free on a re-render: the component already
+ *  memoizes the row list, so identity alone says "nothing moved". */
+interface Keyed {
+  id: RowKey;
+}
+
+/**
+ * The heights of the rows, and where each one starts.
+ *
+ * Mutable and long-lived: one of these belongs to a component for as long
+ * as it is mounted, and `sync` re-points it at the rows a render is about
+ * to draw. It is deliberately **not** React state — a measurement pass
+ * touches it once per rendered row and the component re-renders once, on a
+ * version counter, and only when something actually moved.
+ */
+export class RowHeights {
+  /** Measured heights, by row id. Survives `sync`. */
+  private readonly measured = new Map<RowKey, number>();
+  /** The rows currently indexed, in draw order. */
+  private rows: readonly Keyed[] = [];
+  /** Fenwick tree over the heights, 1-based. */
+  private tree: number[] = [0];
+  /** What an unmeasured row is assumed to be. */
+  private estimate = 1;
+  /** Largest power of two <= n, for the O(log n) descent in `indexAt`. */
+  private power = 0;
+  /** Set when a measurement could not be applied in place, so the next
+   *  `sync` must rebuild even though the row list did not change. */
+  private dirty = false;
+
+  constructor(estimate: number) {
+    this.estimate = Math.max(1, estimate);
+  }
+
+  private heightOf(index: number): number {
+    const measured = this.measured.get(this.rows[index].id);
+    return measured === undefined ? this.estimate : measured;
+  }
+
+  /**
+   * Point the index at the rows about to be drawn.
+   *
+   * Rebuilt rather than patched, and cheap to call on every render: the row
+   * list is memoized, so the common case is an identity check. When it does
+   * rebuild it is O(n) — the rows change when a branch opens, when items
+   * arrive, when a sort flips, when a filter runs, all O(n) events already.
+   */
+  sync(rows: readonly Keyed[], estimate: number): void {
+    const next = Math.max(1, estimate);
+    if (!this.dirty && this.rows === rows && next === this.estimate) return;
+    this.dirty = false;
+    this.rows = rows;
+    this.estimate = next;
+    const n = rows.length;
+    // Build in O(n): write each height at its own slot, then push every slot
+    // into its parent. The textbook loop of point-updates is O(n log n) and
+    // arrives at the same tree.
+    const tree = new Array<number>(n + 1).fill(0);
+    for (let i = 0; i < n; i++) tree[i + 1] = this.heightOf(i);
+    for (let i = 1; i <= n; i++) {
+      const parent = i + (i & -i);
+      if (parent <= n) tree[parent] += tree[i];
+    }
+    this.tree = tree;
+    this.power = n > 0 ? 1 << Math.floor(Math.log2(n)) : 0;
+  }
+
+  /**
+   * Record what a row actually laid out at. Returns whether this changed
+   * anything — which is what tells the component whether to re-render, and
+   * the reason a measurement pass that finds nothing new costs nothing.
+   */
+  measure(id: RowKey, index: number, height: number): boolean {
+    if (!(height > 0)) return false;
+    const before = this.measured.get(id);
+    if (before === height) return false;
+    this.measured.set(id, height);
+    if (this.rows[index]?.id !== id) {
+      // The caller's index is stale — the rows moved under a measurement
+      // that was already in flight. Applying a delta at the wrong slot would
+      // corrupt every offset after it, so the tree is rebuilt instead.
+      this.dirty = true;
+      return true;
+    }
+    const delta = height - (before === undefined ? this.estimate : before);
+    if (delta === 0) return false;
+    for (let i = index + 1; i < this.tree.length; i += i & -i) {
+      this.tree[i] += delta;
+    }
+    return true;
+  }
+
+  /** What a row measured, or the estimate if it has not been seen. */
+  heightAt(index: number): number {
+    return index >= 0 && index < this.rows.length ? this.heightOf(index) : 0;
+  }
+
+  /** Whether this row has a real measurement rather than an estimate. */
+  isMeasured(index: number): boolean {
+    const row = this.rows[index];
+    return row !== undefined && this.measured.has(row.id);
+  }
+
+  /** Where row `index` starts. `offsetAt(rowCount)` is the total. */
+  offsetAt(index: number): number {
+    let sum = 0;
+    for (
+      let i = Math.max(0, Math.min(index, this.rows.length));
+      i > 0;
+      i -= i & -i
+    ) {
+      sum += this.tree[i];
+    }
+    return sum;
+  }
+
+  /** How tall the whole list is — what the scrollbar measures. */
+  total(): number {
+    return this.offsetAt(this.rows.length);
+  }
+
+  /**
+   * The row containing `offset`, clamped into the list.
+   *
+   * A descent down the tree rather than a binary search over `offsetAt`,
+   * which would be O(log² n) — this is the operation every scroll performs,
+   * twice.
+   */
+  indexAt(offset: number): number {
+    const n = this.rows.length;
+    if (n === 0) return 0;
+    let index = 0;
+    let remaining = offset;
+    for (let step = this.power; step > 0; step >>= 1) {
+      const next = index + step;
+      if (next <= n && this.tree[next] <= remaining) {
+        index = next;
+        remaining -= this.tree[next];
+      }
+    }
+    return Math.max(0, Math.min(n - 1, index));
+  }
+
+  /**
+   * Whether anything has ever been measured — O(1), and the question a
+   * component that may not measure at all has to ask before it waits on a
+   * measurement. `measuredCount` answers a different, costlier question:
+   * how many of the rows *currently indexed* have one.
+   */
+  hasMeasurements(): boolean {
+    return this.measured.size > 0;
+  }
+
+  /** How many of the current rows have a real measurement. */
+  measuredCount(): number {
+    let count = 0;
+    for (const row of this.rows) if (this.measured.has(row.id)) count++;
+    return count;
+  }
+
+  /**
+   * Forget every measurement, keeping the row list.
+   *
+   * For a change that invalidates heights wholesale rather than row by row.
+   * Nothing calls it for new items — their ids are simply not in the map yet
+   * — and nothing calls it on a resize either: rows re-measure as they are
+   * drawn, and throwing away the heights of rows whose content does not
+   * depend on the width would make the scrollbar worse, not better.
+   */
+  reset(): void {
+    this.measured.clear();
+    this.dirty = true;
+  }
+}

package/src/internal/hx.ts

@@ -0,0 +1,53 @@
+// `React.createElement`, typed against react-x11's host elements.
+//
+// The library writes `h(...)` rather than JSX — a convention inherited from
+// core, and worth keeping so moving code between the two repos stays a
+// rename. Shared by every composed widget out here (`<Calendar>`,
+// `<DatePicker>`, `<ColorPicker>`, `<ColorField>`), which is why it sits in
+// `src/internal/` rather than in one of them. But `React.createElement`'s own overloads are `@types/react`'s, and
+// they describe the DOM: a `<box onKeyDown>` handler is checked against
+// React's `KeyboardEvent`, not react-x11's, and the whole props object is
+// measured against `DOMAttributes`. Everything interesting fails.
+//
+// So the element name is looked up in react-x11's own element table instead.
+// `hx('box', …)` gets `<box>`'s real props — `ev.keysym` on a key handler,
+// `onDraw` on a `<canvas>` — and `hx('div', …)` is an error, which is the
+// same guarantee the JSX namespace gives `examples/` and `test/types/`.
+import React from 'react';
+import type { Key, ReactElement, ReactNode } from 'react';
+import type { ReactX11Elements, Theme } from 'react-x11';
+
+/** The host elements, by name. */
+export type Host = ReactX11Elements;
+
+/**
+ * What every element takes on top of its own props.
+ *
+ * `theme` is honoured by **every** node — `Node.theme` merges `props.theme`
+ * over the inherited palette, whatever the kind — but react-x11's element
+ * declarations only put it on `<window>`. A widget re-declares the theme it
+ * read from context onto its own root so that `$token` values still resolve
+ * inside a `<popup>`, which is a separate window and does not inherit the
+ * trigger's node tree. So the prop is real; only the declaration is narrow.
+ */
+interface CommonProps {
+  key?: Key;
+  /** `Theme` is listed alongside the record because it is an interface, and
+   *  an interface has no implicit index signature — so the palette `useTheme`
+   *  hands back is not assignable to the record react-x11 declares. */
+  theme?: Theme | Record<string, string | number>;
+}
+
+export function hx<K extends keyof Host>(
+  type: K,
+  // `theme` is dropped from the element's own props before the merge:
+  // `<window>` and `<popup>` already declare it, narrower, and intersecting
+  // the two would demand a value satisfying both.
+  props?: (Omit<Host[K], 'theme'> & CommonProps) | null,
+  ...children: ReactNode[]
+): ReactElement {
+  // The cast is the whole point of the wrapper: `createElement`'s string
+  // overload insists on DOM props, and the signature above has already
+  // checked these against the element that will actually receive them.
+  return React.createElement(type as string, props as never, ...children);
+}

package/src/internal/scroll.ts

@@ -0,0 +1,288 @@
+// Scrolling a row into view, when neither the row nor the scroll pane is
+// ready to be asked yet.
+//
+// **Shared between `<Tree>` and `<Table>`** — the third piece both
+// virtualizers stand on, beside `./heights.ts` and `./timers.ts`, and here
+// for the same reason: the logic is subtle, it is identical in both, and a
+// second copy of it is a second place for the bug below to come back.
+//
+// Two things a scroll pane does silently, both of them in the gap between a
+// commit and the layout it causes, and both of them enough on their own to
+// leave a virtualized list drawing rows the viewport is no longer looking at:
+//
+//   1. **`scrollTo` clamps against the content height the *last* layout
+//      measured.** A row appended in the commit now being laid out is past
+//      the bottom that clamp knows about, so the request lands short — and
+//      short *for good*, because nothing about it is retried. That is the
+//      live tail: a list that scrolls to its newest row on every update and
+//      settles one update behind, permanently. On mount, where no content
+//      has been laid out at all, the scroll simply never happens.
+//
+//   2. **The pane moves without saying so.** It resolves a queued
+//      `scrollIntoView` during layout, and it re-clamps an offset the
+//      content has outgrown or outshrunk — neither of which fires
+//      `onScroll`. A component that learns the offset only from that event
+//      keeps building its slice from where the pane *was*: the rows are
+//      drawn off-viewport, there is a blank band where they should be, and
+//      nothing puts it right until a scroll of your own re-syncs it by
+//      accident.
+//
+// So a reveal here is not a one-shot: it is a **debt**, kept by row id,
+// attempted at once and re-tried on the layout that makes the rest of the
+// move possible. It is dropped as soon as the row is in view, leaves the
+// list, or the user scrolls somewhere themselves — an owed scroll must never
+// yank the list back out from under a hand on the wheel.
+//
+// The offset is read back from the pane rather than trusted to the event;
+// `useReveal` does not do that itself, because what a component *does* with
+// the offset differs (a slice to rebuild, a header to shift), but it is the
+// other half of the same fix and both components run it on the same tick.
+
+import { useCallback, useEffect, useRef } from 'react';
+import type { DrawnNode, ScrollableNode } from 'react-x11';
+
+import type { RowHeights, RowKey } from './heights.js';
+import { afterLayout, cancelAfterLayout } from './timers.js';
+import type { LayoutTick } from './timers.js';
+
+/** All a reveal needs of a row: `<TreeRow>` and `<TableRow>` are both this. */
+interface Keyed {
+  id: RowKey;
+}
+
+/** A row on screen, and the index it was drawn at — the shape both
+ *  components already keep their mounted rows in. */
+interface Drawn {
+  node: DrawnNode;
+  at: number;
+}
+
+/** What the component lends the reveal: everything it already has, by ref,
+ *  so nothing here goes stale between a render and the tick after layout. */
+export interface RevealSources {
+  /** The scroll pane. `<Table>`'s body; `<Tree>`'s own root. */
+  box: { readonly current: ScrollableNode | null };
+  /** The rows in display order. */
+  rows: { readonly current: readonly Keyed[] };
+  /** The rows on screen, by id. */
+  nodes: { readonly current: ReadonlyMap<RowKey, Drawn> };
+  /** Where the rows that are *not* on screen are — and how tall a row that
+   *  has never been drawn is assumed to be. */
+  heights: RowHeights;
+}
+
+export interface Reveal {
+  /** Owe a scroll to this row, and try to pay it now. */
+  to(id: RowKey): void;
+  /**
+   * Try again: after a layout, or when the content changed size.
+   *
+   * Pass `provisional` on a pass where the height index just moved. The rows
+   * are still laid out at the heights it no longer believes, so a row that
+   * looks in view is not proof of anything yet — a row measured taller than
+   * the guess pushes everything after it down, and the row that was reached a
+   * moment ago ends up under the fold. The debt is kept until a pass that
+   * measured nothing new confirms it, which is exactly when the heights have
+   * converged.
+   */
+  retry(provisional?: boolean): void;
+  /** Scroll the pane, recording that this component is the one that asked. */
+  scrollTo(y: number): void;
+  /** An `onScroll` arrived. One this component did not ask for is the user
+   *  taking over, and it cancels whatever was owed. */
+  heard(scrollY: number): void;
+}
+
+/**
+ * The scroll a component owes a row, and the bookkeeping that pays it.
+ *
+ * Stable across renders — every method reads through the refs it was handed,
+ * so an event handler or a layout tick built in an earlier render still sees
+ * the current rows.
+ */
+export function useReveal(sources: RevealSources): Reveal {
+  const src = useRef(sources);
+  src.current = sources;
+  /** The row still owed a scroll, by id. */
+  const owed = useRef<RowKey | null>(null);
+  /**
+   * The row the last reveal settled on, kept for one reason: a measurement
+   * pass can move the heights that settlement was judged against. A row that
+   * was in view when the debt was paid is not in view any more once the rows
+   * around it turn out taller than the index believed, and the honest answer
+   * to "is that still true?" is to owe it again and look. Measurement
+   * converges, so this stops asking.
+   */
+  const settled = useRef<RowKey | null>(null);
+  /** The offset the last scroll *this component* asked for, so the
+   *  `onScroll` that answers it is not read as the user taking over. */
+  const asked = useRef<number | null>(null);
+  /**
+   * What the pane looked like at the last attempt that could not move.
+   *
+   * An attempt clamped by a content height that is a layout out of date has
+   * to be looked at again — and nothing else will schedule that look: the
+   * scroll that did not happen renders nothing, so the component's own tick
+   * after layout never comes. One is queued here instead, and only while the
+   * pane keeps changing under it: an attempt that finds the same offset and
+   * the same content as the last one has nothing new to try, and stops.
+   */
+  const stuck = useRef<{ y: number; content: number } | null>(null);
+  const look = useRef<LayoutTick>(null);
+  useEffect(() => () => cancelAfterLayout(look.current), []);
+
+  const scrollTo = useCallback((y: number): void => {
+    const box = src.current.box.current;
+    if (!box) return;
+    // Clamped here rather than left to the container, so what comes back on
+    // `onScroll` is the number that was asked for and can be recognised.
+    const to = Math.min(
+      Math.max(0, y),
+      Math.max(0, box.contentHeight - box.abs.height),
+    );
+    if (to === box.scrollY) return;
+    asked.current = to;
+    box.scrollTo({ y: to });
+  }, []);
+
+  const retry = useCallback(
+    (provisional?: boolean): void => {
+      const { box: boxRef, rows: rowsRef, nodes, heights } = src.current;
+      const box = boxRef.current;
+      // The heights just moved, so what the last reveal settled on was settled
+      // against numbers that have changed: owe it again until it can be
+      // confirmed at the new ones.
+      if (provisional && owed.current === null) owed.current = settled.current;
+      const id = owed.current;
+      if (!box || id === null) return;
+      const rows = rowsRef.current;
+      const at = rows.findIndex((r) => r.id === id);
+      if (at < 0) {
+        // the row left the list
+        owed.current = null;
+        settled.current = null;
+        return;
+      }
+      const viewport = box.abs.height;
+      if (viewport <= 0) return; // nothing laid out to scroll inside yet
+
+      // How far the row is outside the pane, in pixels of scrolling. The row's
+      // own rect answers when it is mounted — it knows what it really laid out
+      // at, and the arithmetic stays in screen coordinates, so a pane with
+      // padding on it needs no correction. The height index answers when the
+      // row is not mounted, which while virtualizing is the normal case.
+      const drawn = nodes.current.get(id);
+      const mounted =
+        drawn && drawn.node.abs.height > 0 && rows[drawn.at]?.id === id
+          ? drawn.node
+          : null;
+      const placed = mounted
+        ? {
+            above: box.abs.y - mounted.abs.y,
+            below: mounted.abs.y + mounted.abs.height - (box.abs.y + viewport),
+            height: mounted.abs.height,
+          }
+        : {
+            above: box.scrollY - heights.offsetAt(at),
+            below:
+              heights.offsetAt(at) +
+              heights.heightAt(at) -
+              (box.scrollY + viewport),
+            height: heights.heightAt(at),
+          };
+      /**
+       * Whether this is worth *settling* on, or only worth acting on.
+       *
+       * Two ways a row can look in view and not stay there. Its own placement
+       * may be a guess — the index's answer for a row nothing has measured —
+       * and "in view" judged from a guess is how a tail lands short of a bottom
+       * that has not been measured yet. Or a row *between* the viewport and it
+       * may still be a guess, and every one of those that turns out taller than
+       * the index believed pushes this row down by the difference, out of the
+       * view it had just been brought into.
+       *
+       * Both are settled by the same thing: measurement converges, so the rows
+       * that matter stop being guesses. A component that measures nothing at all
+       * has no guesses to wait on — `hasMeasurements` is how that is told
+       * apart, and it is what keeps a declared-uniform table from owing a debt
+       * for ever.
+       */
+      let certain = mounted !== null || heights.isMeasured(at);
+      if (certain && heights.hasMeasurements()) {
+        const from = Math.min(at, heights.indexAt(box.scrollY));
+        const to = Math.max(at, heights.indexAt(box.scrollY + viewport));
+        for (let i = from; i <= to && certain; i++) {
+          certain = heights.isMeasured(i);
+        }
+      }
+
+      let move = 0;
+      if (placed.height >= viewport) {
+        // A row taller than the pane is never *fully* in view, and asking for
+        // both its edges in turn is a debt that alternates for ever. Its top is
+        // the part worth showing — a wrapped row reads from its first line —
+        // and arriving there settles it.
+        move = -placed.above;
+      } else if (placed.above > 0) move = -placed.above;
+      else if (placed.below > 0) move = placed.below;
+
+      if (move === 0) {
+        // As far in view as it can be — settled, unless what that was judged
+        // against is still moving: a placement that came from a guess, or a
+        // pass that has just changed the heights under it.
+        if (certain && !provisional) {
+          settled.current = id;
+          owed.current = null;
+        }
+        return;
+      }
+      // A move the pane cannot make yet leaves the debt standing: the layout
+      // that admits the rows just appended is the one that will let it finish.
+      const was = box.scrollY;
+      scrollTo(was + move);
+      if (box.scrollY !== was) {
+        stuck.current = null; // it moved; the scroll it caused brings us back
+        return;
+      }
+      const seen = stuck.current;
+      const now = { y: box.scrollY, content: box.contentHeight };
+      stuck.current = now;
+      if (seen && seen.y === now.y && seen.content === now.content) return;
+      cancelAfterLayout(look.current);
+      look.current = afterLayout(() => {
+        look.current = null;
+        retryRef.current?.();
+      });
+    },
+    [scrollTo],
+  );
+
+  /** `retry` referring to itself through a ref, so the queued look calls the
+   *  current one rather than closing over the render that queued it. */
+  const retryRef = useRef<(() => void) | null>(null);
+  retryRef.current = retry;
+
+  const to = useCallback(
+    (id: RowKey): void => {
+      // Recorded before the attempt rather than after it, because the
+      // interesting case is the one that cannot succeed yet.
+      owed.current = id;
+      settled.current = null;
+      stuck.current = null;
+      retry();
+    },
+    [retry],
+  );
+
+  const heard = useCallback((scrollY: number): void => {
+    // A scroll this component did not ask for ends the whole chase, not just
+    // the outstanding half of it.
+    if (scrollY !== asked.current) {
+      owed.current = null;
+      settled.current = null;
+    }
+    asked.current = null;
+  }, []);
+
+  return { to, retry, scrollTo, heard };
+}

package/src/internal/text.ts

@@ -0,0 +1,44 @@
+// The bits `<richtext>` and `<Html>` need that react-x11 has but does not
+// export. Same situation, and the same shape, as `src/calendar/internal.ts` —
+// each is small and pure, and if core ever puts one on its exports map,
+// delete it from here and import it. `tint` was the first to go that way: it
+// is `react-x11/style`'s now, and the surfaces here import it from there.
+//
+// It sits in `src/internal/` rather than in `src/richtext/` because two
+// things share it now — the shared module and `src/html/`'s own layout — and
+// that is exactly what this directory is for (AGENTS.md, "the half-step below
+// a shared module").
+
+// --- code points vs code units ---------------------------------------------
+//
+// ntk's line runs report their extent in **code units** while its caret API
+// speaks **code points**, so anything reading run geometry has to translate.
+// Core has exactly these two functions in `src/textrange.js` (react-x11#291)
+// and its `<text>` uses them for the same purpose; they are copied rather
+// than imported because that module is not on core's exports map. Delete
+// them the day it is.
+
+/** Code point index -> UTF-16 offset, with one extra entry for the end. */
+export function codeUnitOffsets(text: string): number[] {
+  const offsets: number[] = [];
+  const s = text ?? '';
+  for (let i = 0; i < s.length;) {
+    offsets.push(i);
+    i += (s.codePointAt(i) ?? 0) > 0xffff ? 2 : 1;
+  }
+  offsets.push(s.length);
+  return offsets;
+}
+
+/** The code point index for a UTF-16 offset, rounded down to a whole
+ *  character. Binary search over `codeUnitOffsets`. */
+export function codePointAtOffset(offsets: number[], offset: number): number {
+  let lo = 0;
+  let hi = offsets.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (offsets[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+}

package/src/internal/timers.ts

@@ -0,0 +1,44 @@
+// "Run this once layout has happened", reached through `globalThis`.
+//
+// **Shared between `<Tree>` and `<Table>`** — promoted here with the height
+// index beside it; see `./heights.ts` for why this directory is internal
+// rather than a shared module with a subpath.
+//
+// The build compiles `src/` with `types: []` on purpose — a Node global that
+// wanders in must fail the build rather than become an implicit
+// `@types/node` dependency (AGENTS.md) — so the one timer virtualization
+// needs is typed here, structurally, the way `../code-language/timers.ts`
+// does it.
+//
+// **Why a tick and not an effect.** react-x11 lays out on a frame flush, not
+// in the commit, so a `useLayoutEffect` or a `useEffect` reads the geometry of
+// the *previous* pass: on the render that created a row, `node.abs.height` is
+// still 0. A macrotask scheduled from an effect lands after the flush, which
+// is the first moment a row can be asked how tall it turned out to be.
+interface Deferred {
+  setImmediate?(fn: () => void): unknown;
+  clearImmediate?(id: unknown): void;
+  setTimeout?(fn: () => void, ms: number): unknown;
+  clearTimeout?(id: unknown): void;
+}
+
+const g = globalThis as Deferred;
+
+export type LayoutTick = { immediate: boolean; id: unknown } | null;
+
+/** Run `fn` after the layout pass this commit will cause. */
+export function afterLayout(fn: () => void): LayoutTick {
+  // `setImmediate` is the check-phase callback, which runs after the frame
+  // work node has already queued. `setTimeout(0)` is the fallback for a host
+  // that has no `setImmediate` — a browser-shaped global object, or a
+  // stripped-down runtime — and lands in the same place for this purpose.
+  if (g.setImmediate) return { immediate: true, id: g.setImmediate(fn) };
+  if (g.setTimeout) return { immediate: false, id: g.setTimeout(fn, 0) };
+  return null;
+}
+
+export function cancelAfterLayout(tick: LayoutTick): void {
+  if (!tick) return;
+  if (tick.immediate) g.clearImmediate?.(tick.id);
+  else g.clearTimeout?.(tick.id);
+}