@textui/core 0.1.0 → 0.3.0

package/src/themes/registry.ts

@@ -2,13 +2,14 @@ import type {
   ResolvedTheme, ThemeDefinition, ThemeGlyphs, ThemeRegistry, ThemeSpacing,
 } from '../types/theme.js';
 import type { Color } from '../types/cells.js';
-import type { BorderChars, BorderStyle, ColorToken, Density, StyleColor } from '../types/style.js';
+import type { BorderChars, BorderStyle, ColorToken, CursorStyle, Density, DividerChars, DividerStyle, StyleColor, TableRules } from '../types/style.js';
 import type { Style } from '../types/style.js';
 import type { SyntaxScope } from '../types/syntax.js';
 import type { TerminalCapabilities } from '../types/capabilities.js';
 import type { Disposable } from '../types/disposable.js';
 import { toDisposable } from '../util/disposable.js';
 import { borderCharsFor } from './borders.js';
+import { dividerCharsFor } from './dividers.js';
 import { glyphsFor } from './glyphs.js';
 import { BUILTIN_THEMES } from './builtin.js';
 
@@ -16,7 +17,7 @@ const DEFAULT_SPACING: ThemeSpacing = { none: 0, xs: 0, sm: 1, md: 1, lg: 2, xl:
 
 const FALLBACK_COLORS: Record<ColorToken, Color> = {
   canvas: 'default', surface: 'default', surfaceAlt: 'default', overlay: 'default',
-  border: 'default', borderStrong: 'default', borderSubtle: 'default',
+  border: 'default', borderStrong: 'default', borderSubtle: 'default', divider: 'default',
   text: 'default', muted: 'default', subtle: 'default', inverted: 'default',
   accent: 'default', primary: 'default', secondary: 'default',
   success: 'default', warning: 'default', danger: 'default', info: 'default',
@@ -115,6 +116,14 @@ export class Themes implements ThemeRegistry {
     let spacing = { ...DEFAULT_SPACING };
     let glyphOverrides: Partial<ThemeGlyphs> = {};
     let border: BorderStyle = 'single';
+    let divider: DividerStyle = 'single';
+    // Undefined means "leave the terminal's own setting alone", which is the
+    // right default: a theme that says nothing should not restyle the caret.
+    let cursorStyle: CursorStyle | undefined;
+    // The quiet one. A rule between every pair of rows is right for a table of
+    // few, long rows and noise on a table of twenty short ones, so a theme
+    // opts in rather than out.
+    let tableRules: TableRules = 'header';
     let density: Density = 'normal';
     const components: Record<string, Record<string, Style>> = {};
     let syntaxOverrides: Partial<Record<SyntaxScope, StyleColor>> = {};
@@ -142,6 +151,9 @@ export class Themes implements ThemeRegistry {
       if (def.spacing) spacing = { ...spacing, ...def.spacing };
       if (def.glyphs) glyphOverrides = { ...glyphOverrides, ...def.glyphs };
       if (def.border) border = def.border;
+      if (def.divider) divider = def.divider;
+      if (def.cursor) cursorStyle = def.cursor;
+      if (def.tableRules) tableRules = def.tableRules;
       if (def.density) density = def.density;
       for (const [name, variants] of Object.entries(def.components ?? {})) {
         components[name] = { ...components[name], ...variants };
@@ -172,6 +184,7 @@ export class Themes implements ThemeRegistry {
 
     const glyphs: ThemeGlyphs = { ...glyphsFor(caps.unicode), ...glyphOverrides };
     const charCache = new Map<BorderStyle, BorderChars>();
+    const ruleCache = new Map<DividerStyle, DividerChars>();
 
     const resolved: ResolvedTheme = {
       id: leaf.id,
@@ -181,6 +194,9 @@ export class Themes implements ThemeRegistry {
       spacing,
       glyphs,
       border,
+      divider,
+      cursor: cursorStyle,
+      tableRules,
       density,
       components,
       syntax,
@@ -203,6 +219,18 @@ export class Themes implements ThemeRegistry {
         return chars;
       },
 
+      dividerChars(style?: DividerStyle): DividerChars {
+        const s = style ?? divider;
+        let chars = ruleCache.get(s);
+        if (!chars) {
+          const base = dividerCharsFor(s, caps.unicode);
+          const custom = leaf.dividerChars?.[s];
+          chars = custom ? { ...base, ...custom } : base;
+          ruleCache.set(s, chars);
+        }
+        return chars;
+      },
+
       styleFor(component: string, variants: string[] = []): Style {
         const entry = components[component];
         if (!entry) return {};

package/src/types/app.ts

@@ -69,6 +69,19 @@ export interface TextUIApp extends Disposable {
   stop(): Promise<void>;
   /** Force a frame now, outside the scheduler. Tests and screenshots use it. */
   flush(): void;
+  /**
+   * Render until nothing is left to render, and answer whether it went quiet.
+   *
+   * The question `flush` cannot answer. A frame settles in more than one pass -
+   * an effect marks something dirty, a measurement runs the layout again - so a
+   * program that wants one true frame has to wait rather than force one.
+   *
+   * It returns as soon as a pass finds nothing pending, so an animating
+   * application settles between its frames. `false` means the passes kept
+   * producing work until the limit ran out - a render loop that does not
+   * converge, rather than one that is merely busy.
+   */
+  settled(options?: { limit?: number }): Promise<boolean>;
   /** The last painted frame. */
   buffer(): CellBuffer;
 

package/src/types/command.ts

@@ -43,6 +43,16 @@ export interface ArgSpec {
   /** Fixed choices, or a resolver for a picker. */
   choices?: ArgChoices | (() => Promise<ArgChoices> | ArgChoices);
   default?: unknown;
+  /**
+   * How the picker should lay out each choice's `description`.
+   *
+   * The argument is what knows: a list of branch names has nothing to say
+   * under each one, and a list of approval modes is *only* told apart by what
+   * is under each one. `below` gives every choice a second line, which is the
+   * only place a sentence fits - inline it shares the width with the label and
+   * every answer shows the same truncated half.
+   */
+  descriptions?: 'inline' | 'below';
 
   /**
    * Show what a choice would do, before it is chosen.
@@ -75,6 +85,13 @@ export interface CommandDefinition {
   id: string;
   title: string;
   description?: string;
+  /**
+   * The group this belongs to. The palette names it once, above the group.
+   *
+   * It is not a per-row label: repeating it beside every row spends the width
+   * the rows need for saying what they do, and still does not say where one
+   * group ends and the next begins.
+   */
   category?: string;
   icon?: string;
   /**
@@ -86,7 +103,7 @@ export interface CommandDefinition {
    */
   keepOpen?: boolean;
   /**
-   * A short state word shown beside the row, in place of the category.
+   * A short state word shown beside the row, in place of its description.
    *
    * The icon is the row's identity and should not move under the reader as
    * state changes; this is where the state goes instead.

package/src/types/input.ts

@@ -52,6 +52,15 @@ export interface MouseEvent {
   ctrl: boolean;
   alt: boolean;
   shift: boolean;
+  /**
+   * When it happened, in milliseconds.
+   *
+   * A terminal reports presses and releases and never says "double click" -
+   * there is no such thing on the wire - so telling one gesture from two is
+   * arithmetic on when they arrived and where. Stamped by whatever produced
+   * the event, which is the only thing that knows.
+   */
+  at?: number;
   handled: boolean;
 }
 

package/src/types/markdown.ts

@@ -1,4 +1,4 @@
-import type { StyleColor } from './style.js';
+import type { StyleColor, TableRules } from './style.js';
 
 /**
  * Markdown, as rows a terminal can scroll.
@@ -14,6 +14,9 @@ import type { StyleColor } from './style.js';
  * put the visible ones back into one box.
  */
 
+/** Which edge a table column's text is pushed against. */
+export type MarkdownAlign = 'left' | 'center' | 'right';
+
 /** A run of text with one style. Inline emphasis is why rows are not strings. */
 export interface MarkdownRun {
   text: string;
@@ -28,7 +31,30 @@ export type MarkdownRow =
   | { kind: 'rule' }
   | { kind: 'heading'; runs: MarkdownRun[]; level: number }
   | { kind: 'text'; runs: MarkdownRun[]; prefix?: string; prefixFg?: StyleColor; fg?: StyleColor }
-  | { kind: 'fence'; fence: number; part: 'open' | 'code' | 'close'; text?: string; language?: string };
+  | { kind: 'fence'; fence: number; part: 'open' | 'code' | 'close'; text?: string; language?: string }
+  /**
+   * One line of a table, with its cells already fitted to their columns.
+   *
+   * The widths are decided once for the whole table and repeated on every row
+   * of it, because a column that is measured per row is not a column. Cells
+   * arrive padded and truncated to exactly `widths[i]`, so a painter only has
+   * to put the separators in - which is also what keeps the one-row-per-row
+   * invariant: a cell too long for its column is cut, never wrapped, or the
+   * table would be a different height than the document said it was.
+   *
+   * `top`, `rule` and `bottom` are edges and carry no cells; the painter draws
+   * them from the widths, in whatever the theme's border characters are. They
+   * are rows here for the same reason a fence's rules are: they take a line on
+   * the screen, so anything counting rows has to be able to count them.
+   */
+  | {
+    kind: 'table';
+    table: number;
+    part: 'top' | 'head' | 'rule' | 'body' | 'bottom';
+    cells: MarkdownRun[][];
+    widths: number[];
+    align: MarkdownAlign[];
+  };
 
 export interface MarkdownLayoutOptions {
   /** Cells to wrap to. Zero means "not measured yet" - nothing is wrapped. */
@@ -44,4 +70,14 @@ export interface MarkdownLayoutOptions {
    * rules nobody draws stops two rows short of the end of the document.
    */
   ruled?: boolean;
+  /**
+   * How much of a table gets ruled. The theme's `tableRules`, passed through.
+   *
+   * It has to be decided here rather than by whatever paints the rows,
+   * because a rule between two rows *is* a row - it takes a line on the
+   * screen. A painter that added them would be drawing more lines than the
+   * layout counted, and every viewer that scrolls by row index would land in
+   * the wrong place by one per table row.
+   */
+  tableRules?: TableRules;
 }

package/src/types/style.ts

@@ -16,7 +16,7 @@ export type ColorToken =
   | 'onAccent' | 'onPrimary' | 'onSecondary'
   | 'onSuccess' | 'onWarning' | 'onDanger' | 'onInfo'
   | 'hover' | 'active' | 'selected' | 'focus' | 'disabled'
-  | 'scrim' | 'cursor' | 'shadow';
+  | 'scrim' | 'cursor' | 'shadow' | 'divider';
 
 /** Anywhere a colour is accepted, a semantic token is accepted too. */
 export type StyleColor = ColorToken | Color;
@@ -45,6 +45,38 @@ export interface BorderChars {
   teeRight: string;
 }
 
+/**
+ * A rule that separates, rather than a frame that encloses.
+ *
+ * Kept apart from `BorderStyle` on purpose: a theme that draws no frames may
+ * still want a rule, and tying the two means choosing a divider glyph decides
+ * whether every bordered component reserves a ring.
+ */
+export type DividerStyle =
+  | 'none' | 'single' | 'double' | 'dashed' | 'thick' | 'ascii';
+
+/** A divider runs either way, so it names both. */
+export interface DividerChars {
+  horizontal: string;
+  vertical: string;
+}
+
+/**
+ * The shape of the caret.
+ *
+ * Named for DECSCUSR, which is what a terminal understands, so a theme value
+ * maps straight onto the escape sequence with nothing to translate.
+ */
+export type CursorStyle = 'block' | 'underline' | 'bar';
+
+/**
+ * How much of a table gets ruled: the header only, or between every row.
+ *
+ * Not a border style - it is a question about how many lines, not which
+ * glyphs. The glyphs are the theme's border set either way.
+ */
+export type TableRules = 'header' | 'all';
+
 export type BorderSides = {
   top?: boolean;
   right?: boolean;

package/src/types/terminal.ts

@@ -1,3 +1,4 @@
+import type { CursorStyle } from './style.js';
 import type { Disposable } from './disposable.js';
 import type { Size } from './geometry.js';
 import type { TerminalCapabilities, CapabilityOverrides } from './capabilities.js';
@@ -30,6 +31,8 @@ export interface AcquiredState {
   focusEvents: boolean;
   paste: boolean;
   cursorHidden: boolean;
+  /** Whether this session changed the caret shape, and so owes a reset. */
+  cursorShaped?: boolean;
   enhancedKeys: boolean;
   rawMode: boolean;
   titleSet: boolean;
@@ -55,4 +58,10 @@ export interface TerminalAdapter extends Disposable {
   /** OSC 52, when the terminal allows it. */
   writeClipboard?(text: string): void;
   setTitle?(title: string): void;
+  /**
+   * DECSCUSR. Session state rather than frame state - it survives until
+   * something changes it, so it is set when it changes and put back on
+   * teardown, the way the alt screen and raw mode are.
+   */
+  setCursorShape?(shape: CursorStyle): void;
 }

package/src/types/theme.ts

@@ -1,5 +1,8 @@
 import type { Color } from './cells.js';
-import type { BorderChars, BorderStyle, ColorToken, Density, Style, StyleColor } from './style.js';
+import type {
+  BorderChars, BorderStyle, ColorToken, CursorStyle, Density, DividerChars, DividerStyle,
+  Style, StyleColor, TableRules,
+} from './style.js';
 import type { SyntaxScope } from './syntax.js';
 import type { Disposable } from './disposable.js';
 import type { TerminalCapabilities } from './capabilities.js';
@@ -33,6 +36,8 @@ export interface ThemeGlyphs {
   chevronUp: string;
   arrowUp: string;
   arrowDown: string;
+  arrowLeft: string;
+  arrowRight: string;
   ellipsis: string;
   search: string;
   radioOn: string;
@@ -80,6 +85,25 @@ export interface ThemeDefinition {
   /** Default border style for chrome. `'none'` gives the borderless look. */
   border?: BorderStyle;
   borderChars?: Partial<Record<BorderStyle, BorderChars>>;
+  /**
+   * Default rule style. Independent of `border`, so a borderless theme can
+   * still separate with a line.
+   */
+  divider?: DividerStyle;
+  dividerChars?: Partial<Record<DividerStyle, DividerChars>>;
+  /** The caret's shape. The terminal's own setting is the default. */
+  cursor?: CursorStyle;
+  /**
+   * How much of a table gets ruled.
+   *
+   * `header` is the default and the quiet one: a box, and a rule under the
+   * header. `all` puts a rule between every pair of rows as well, which is
+   * what a table of few, long rows wants - a wrapped-looking cell beside a
+   * short one is ambiguous about which row it belongs to until something
+   * separates them. On a table of twenty short rows the same lines are noise,
+   * which is why it is the theme's call rather than the default.
+   */
+  tableRules?: TableRules;
   density?: Density;
   /** Per-component style overrides, keyed by component name then variant. */
   components?: Record<string, Record<string, Style>>;
@@ -100,6 +124,9 @@ export interface ResolvedTheme {
   spacing: ThemeSpacing;
   glyphs: ThemeGlyphs;
   border: BorderStyle;
+  divider: DividerStyle;
+  cursor: CursorStyle | undefined;
+  tableRules: TableRules;
   density: Density;
   components: Record<string, Record<string, Style>>;
   /** Every syntax scope, resolved to a colour. */
@@ -107,6 +134,7 @@ export interface ResolvedTheme {
   /** Resolve a token (or pass a literal colour through). */
   color(token: string): Color;
   borderChars(style?: BorderStyle): BorderChars;
+  dividerChars(style?: DividerStyle): DividerChars;
   /** Component style for a name + variant list, merged in order. */
   styleFor(component: string, variants?: string[]): Style;
 }

package/src/util/markdown.ts

@@ -1,4 +1,7 @@
-import type { MarkdownLayoutOptions, MarkdownRow, MarkdownRun } from '../types/markdown.js';
+import type {
+  MarkdownAlign, MarkdownLayoutOptions, MarkdownRow, MarkdownRun,
+} from '../types/markdown.js';
+import type { TableRules } from '../types/style.js';
 import type { StyleColor } from '../types/style.js';
 import { graphemes, stringWidth, wrapText } from './text.js';
 
@@ -141,14 +144,18 @@ export function layoutMarkdown(
   source: string | string[],
   options: MarkdownLayoutOptions,
 ): MarkdownRow[] {
-  const { width, bullet = '-', quoteBar = '|', ruled = true } = options;
+  const { width, bullet = '-', quoteBar = '|', ruled = true, tableRules = 'header' } = options;
   const lines = Array.isArray(source) ? source : source.replace(/\r\n/g, '\n').split('\n');
   const rows: MarkdownRow[] = [];
   let fence = 0;
   let inFence = false;
   let language = '';
+  let table = 0;
 
-  for (const line of lines) {
+  // By index rather than by value: a table is only a table because of the line
+  // *after* its header, so this loop has to be able to look at it.
+  for (let at = 0; at < lines.length; at++) {
+    const line = lines[at] as string;
     const marker = /^\s*```(\S*)\s*$/.exec(line);
     if (marker) {
       // An open fence is laid out as a fence from the moment it opens. A turn
@@ -166,6 +173,24 @@ export function layoutMarkdown(
       continue;
     }
 
+    // Before headings and lists, because a cell may contain either and the
+    // pipes are what decide. After fences, because inside one nothing is.
+    if (line.includes('|') && DIVIDER.test(lines[at + 1] ?? '')) {
+      const align = cellsOf(lines[at + 1] as string).map(alignOf);
+      const body: string[][] = [];
+      let end = at + 2;
+      while (end < lines.length) {
+        const next = lines[end] as string;
+        if (!next.includes('|') || next.trim() === '') break;
+        body.push(cellsOf(next));
+        end++;
+      }
+      rows.push(...tableRows(cellsOf(line), body, align, width, table, tableRules));
+      table++;
+      at = end - 1;
+      continue;
+    }
+
     const heading = /^(#{1,6})\s+(.*)$/.exec(line);
     if (heading) {
       const level = (heading[1] as string).length;
@@ -212,6 +237,180 @@ export function layoutMarkdown(
   return rows;
 }
 
+/**
+ * The `|---|:--:|---:|` line, which is what makes the line above it a header.
+ *
+ * A row of pipes on its own is a row of pipes - `a | b` is arithmetic or a
+ * shell pipeline far more often than it is a one-column table, and treating
+ * every line with a bar in it as a table is how prose ends up in a grid.
+ */
+const DIVIDER = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/;
+
+/**
+ * One line into its cells.
+ *
+ * The outer pipes are optional in every dialect anybody writes, so they are
+ * stripped rather than required. `\|` is an escaped bar inside a cell and not
+ * a boundary - which is the only way to put a bar in a table at all.
+ */
+function cellsOf(line: string): string[] {
+  const trimmed = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+  return trimmed
+    .split(/(?<!\\)\|/)
+    .map((cell) => cell.replace(/\\\|/g, '|').trim());
+}
+
+function alignOf(spec: string): MarkdownAlign {
+  const left = spec.startsWith(':');
+  const right = spec.endsWith(':');
+  if (left && right) return 'center';
+  return right ? 'right' : 'left';
+}
+
+/**
+ * Cut and pad one cell to exactly `width`, keeping the styles.
+ *
+ * Cut, never wrapped: a table row has to stay one row tall or the document's
+ * length stops being a count of rows, and every viewer that windows this
+ * scrolls to the wrong place.
+ */
+function fitRuns(runs: MarkdownRun[], width: number, align: MarkdownAlign): MarkdownRun[] {
+  const out: MarkdownRun[] = [];
+  let used = 0;
+  for (const run of runs) {
+    if (used >= width) break;
+    const room = width - used;
+    if (stringWidth(run.text) <= room) {
+      out.push(run);
+      used += stringWidth(run.text);
+      continue;
+    }
+    // The ellipsis costs a cell, so it is only worth it when there is a cell
+    // to spend: at a width of one, a bare glyph says less than the letter.
+    const keep = room > 1 ? room - 1 : room;
+    const cut: string[] = [];
+    let taken = 0;
+    for (const g of graphemes(run.text)) {
+      const w = stringWidth(g);
+      if (taken + w > keep) break;
+      cut.push(g);
+      taken += w;
+    }
+    out.push({ ...run, text: room > 1 ? `${cut.join('')}\u2026` : cut.join('') });
+    used = width;
+    break;
+  }
+
+  const slack = Math.max(0, width - used);
+  if (slack === 0) return out;
+  const before = align === 'right' ? slack : align === 'center' ? Math.floor(slack / 2) : 0;
+  const after = slack - before;
+  return [
+    ...(before ? [{ text: ' '.repeat(before) }] : []),
+    ...out,
+    ...(after ? [{ text: ' '.repeat(after) }] : []),
+  ];
+}
+
+/**
+ * A whole table, measured once.
+ *
+ * The columns are as wide as their widest cell wants, and when that is more
+ * than the space there is they give it back in proportion - the widest loses
+ * the most, because it is the one with the most to lose. Three cells is the
+ * floor: below that a column is an ellipsis and a space, which is narrower
+ * than saying nothing.
+ */
+function tableRows(
+  head: string[],
+  body: string[][],
+  align: MarkdownAlign[],
+  width: number,
+  table: number,
+  rules: TableRules,
+): MarkdownRow[] {
+  const columns = Math.max(head.length, align.length, ...body.map((r) => r.length));
+  const at = (row: string[], i: number): string => row[i] ?? '';
+  const runsFor = (text: string, bold: boolean): MarkdownRun[] =>
+    inlineRuns(text).map((run) => (bold ? { ...run, bold: true } : run));
+
+  const natural = Array.from({ length: columns }, (_, i) => Math.max(
+    stringWidth(at(head, i)),
+    ...body.map((row) => stringWidth(at(row, i))),
+    1,
+  ));
+
+  // A rule between every pair of columns, and a box around the lot. The box
+  // is what makes it read as a table rather than as text that happens to line
+  // up - which matters most on a theme that draws no borders anywhere else,
+  // because there a table with only its columns ruled has nothing to say it
+  // ended.
+  const gaps = (columns - 1) * SEPARATOR + OUTER;
+  const room = width > 0 ? Math.max(columns * MIN_COLUMN, width - gaps) : Infinity;
+  const wanted = natural.reduce((sum, n) => sum + n, 0);
+  const widths = wanted <= room
+    ? natural
+    : share(natural, room);
+
+  const line = (cells: string[], part: 'head' | 'body'): MarkdownRow => ({
+    kind: 'table',
+    table,
+    part,
+    widths,
+    align,
+    cells: widths.map((w, i) => fitRuns(
+      runsFor(at(cells, i), part === 'head'),
+      w,
+      align[i] ?? 'left',
+    )),
+  });
+
+  const edge = (part: 'top' | 'rule' | 'bottom'): MarkdownRow =>
+    ({ kind: 'table', table, part, cells: [], widths, align });
+
+  return [
+    edge('top'),
+    line(head, 'head'),
+    edge('rule'),
+    // A rule between every pair, when the theme asked for them. Between, not
+    // after: a rule under the last row and then the box's own bottom edge is
+    // two lines saying the same thing.
+    ...body.flatMap((row, i) => (rules === 'all' && i > 0
+      ? [edge('rule'), line(row, 'body')]
+      : [line(row, 'body')])),
+    edge('bottom'),
+  ];
+}
+
+/** Cells between two columns: a space, a rule, a space. */
+const SEPARATOR = 3;
+/** The box: a rule and a space at each end. */
+const OUTER = 4;
+const MIN_COLUMN = 3;
+
+/**
+ * Shrink columns into `room`, proportionally, without losing a cell to
+ * rounding.
+ *
+ * The remainder goes to the widest columns one at a time rather than to the
+ * first: handing every leftover cell to column one is what turns a five-column
+ * table into one wide column and four ellipses.
+ */
+function share(natural: number[], room: number): number[] {
+  const total = natural.reduce((sum, n) => sum + n, 0);
+  const scaled = natural.map((n) => Math.max(MIN_COLUMN, Math.floor((n / total) * room)));
+  let spare = room - scaled.reduce((sum, n) => sum + n, 0);
+  const order = natural
+    .map((n, i) => [n, i] as const)
+    .sort((a, b) => b[0] - a[0])
+    .map(([, i]) => i);
+  for (let i = 0; spare > 0; i = (i + 1) % order.length) {
+    scaled[order[i] as number] = (scaled[order[i] as number] as number) + 1;
+    spare--;
+  }
+  return scaled;
+}
+
 /** Every run's text, for a measurement or a test that does not care how it looks. */
 export function runsToText(runs: MarkdownRun[]): string {
   return runs.map((run) => run.text).join('');

package/src/util/paths.ts

@@ -51,7 +51,7 @@ export function segments(path: string): string[] {
  * Canonical map key for a path: segments joined, no sigil.
  *
  * The segments are re-escaped on the way out. Everything downstream - the
- * store's own walk, `ancestorKeys`, `matchKey` - splits a key on `/`, so a
+ * store's own walk, `keysTouch`, `matchKey` - splits a key on `/`, so a
  * segment that legitimately contains one (a URI used as a key, a filename with
  * a slash) has to stay escaped or it silently becomes several segments and the
  * value lands somewhere nobody looks.
@@ -98,25 +98,22 @@ export function parentKey(key: string): string | null {
   return i === -1 ? (key === '' ? null : '') : key.slice(0, i);
 }
 
-/** Every ancestor key of `key`, closest first, including `''` for the root. */
-export function ancestorKeys(key: string): string[] {
-  const out: string[] = [];
-  let cur = key;
-  for (;;) {
-    const p = parentKey(cur);
-    if (p === null) break;
-    out.push(p);
-    cur = p;
-    if (p === '') break;
-  }
-  return out;
-}
-
 export function isDescendantKey(key: string, ancestor: string): boolean {
   if (ancestor === '') return key !== '';
   return key.startsWith(ancestor + '/');
 }
 
+/**
+ * Whether two concrete keys can affect the same subscribed value.
+ *
+ * A write to a descendant changes the ancestor object a subscriber reads, and a
+ * write to an ancestor may replace the whole subtree below it. This relation is
+ * symmetric and avoids building ancestor lists in hot subscription checks.
+ */
+export function keysTouch(a: string, b: string): boolean {
+  return a === b || isDescendantKey(a, b) || isDescendantKey(b, a);
+}
+
 export function hasWildcard(path: string): boolean {
   return path.includes('*');
 }