@north-light/crouter 0.3.244 → 0.3.246

package/dist/commands/sys/context/admin/detail-panel.d.ts

@@ -1,5 +1,6 @@
 import type { SurfaceEvent } from '../../../../core/substrate/schema.js';
 import type { DeliveryRecord } from '../../../../core/substrate/plan.js';
+import type { NodeConfigSubject } from '../../../../core/substrate/subject-fields.js';
 import { type CapOwner } from './read-view.js';
 import type { DocRow } from './docs-panel.js';
 export type { CapOwner } from './read-view.js';
@@ -33,6 +34,7 @@ export declare class ContextDetailPanel {
     private event;
     private capOwner;
     private readOnly;
+    private subject;
     private rows;
     private index;
     private face;
@@ -42,7 +44,7 @@ export declare class ContextDetailPanel {
      *  measure against real content rather than a counter nobody can see. */
     private lastLines;
     private lastHeight;
-    setContext(row: DocRow | undefined, event: SurfaceEvent, capOwner: CapOwner | null, readOnly: string | null): void;
+    setContext(row: DocRow | undefined, event: SurfaceEvent, capOwner: CapOwner | null, readOnly: string | null, subject: NodeConfigSubject | null): void;
     /** True while the field list owns the pane, so the shell routes the write
      *  letters and teaches them in the footer. */
     get editing(): boolean;

package/dist/commands/sys/context/admin/detail-panel.js

@@ -14,6 +14,7 @@ export class ContextDetailPanel {
     event = 'boot';
     capOwner = null;
     readOnly = null;
+    subject = null;
     rows = [];
     index = 0;
     face = 'read';
@@ -23,12 +24,13 @@ export class ContextDetailPanel {
      *  measure against real content rather than a counter nobody can see. */
     lastLines = 1;
     lastHeight = 1;
-    setContext(row, event, capOwner, readOnly) {
+    setContext(row, event, capOwner, readOnly, subject) {
         const changed = row?.key !== this.row?.key;
         this.row = row;
         this.event = event;
         this.capOwner = capOwner;
         this.readOnly = readOnly;
+        this.subject = subject;
         this.rows = row === undefined ? [] : buildDetailRows(row.anchor);
         if (changed) {
             this.index = 0;
@@ -124,6 +126,7 @@ export class ContextDetailPanel {
             records: this.row?.records ?? new Map(),
             capOwner: this.capOwner,
             readOnly: this.readOnly !== null,
+            subject: this.subject,
         };
     }
     // rendering

package/dist/commands/sys/context/admin/docs-panel.d.ts

@@ -38,25 +38,22 @@ export declare class ContextDocsPanel {
      *  rollups, which partition the corpus, so a fully collapsed list still
      *  reports its size and a nested rollup is never counted twice. */
     get visibleCount(): number;
-    setRows(rows: DocRow[], event: SurfaceEvent, selectedKey?: string): void;
+    /** Documents that actually load on the dialled event, counted the same way —
+     *  the numerator of the heading's `N of M`. */
+    get loadedCount(): number;
+    setRows(rows: DocRow[], event: SurfaceEvent): void;
     setFilters(filters: Filters): void;
     move(delta: number): void;
     /** True when the focused line can be opened — a directory header. */
     get onGroup(): boolean;
-    /** True when the focused line IS a document rather than merely standing for
-     *  one. A directory that is also a document is both, which is why the two
-     *  gestures split there: space opens it, enter edits it. */
-    get onDocument(): boolean;
     toggleGroup(): void;
-    /** Rebuild the drawn lines, keeping the cursor on the same document (or the
-     *  same directory), and clamping when what it was on is gone. A document that
-     *  owns a directory is drawn as that directory's header, so a held document
-     *  key matches there too. */
+    /** Rebuild the drawn lines, keeping the cursor on whatever it holds — the
+     *  same document, or the same directory header, which a collapsed group draws
+     *  no document row for — and clamping when what it was on is gone. */
     private relayout;
-    render(width: number, height: number, focused: boolean, plans: PlanSet): string[];
-    /** A directory header. Its stats and cost are the whole subtree's; the matrix
-     *  is drawn only when the directory is itself a document, which is what marks
-     *  the one row as both a document and a directory. */
+    render(width: number, height: number, focused: boolean): string[];
+    /** A directory header: a pure rollup of its whole subtree — how many of its
+     *  documents load, and what they cost together. */
     private groupLine;
     private docLine;
     /** Pad rather than trim: this column sets the length of the divider drawn

package/dist/commands/sys/context/admin/docs-panel.js

@@ -1,11 +1,12 @@
 // The middle column: every document the snapshot can see, grouped recursively
-// by the directories its canonical name names, and each carrying its own
-// six-event matrix. One row is one physical document, so two stores answering
-// to the same canonical name stay two rows and the shadowed one is visible.
+// by the directories its canonical name names, each stating in one word what it
+// does on the dialled event and what that costs. One row is one physical
+// document, so two stores answering to the same canonical name stay two rows
+// and the shadowed one is visible.
 import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
 import { padAnsi, theme, visibleRange } from '../../../../core/tui/panel.js';
 import { SURFACE_EVENTS } from '../../../../core/substrate/schema.js';
-import { EVENT_INITIALS, cellGlyph, cellStateOf, formatCost, plural } from './model.js';
+import { deliveryStateOf, formatCost, plural, stateLabel } from './model.js';
 import { NO_FILTERS, buildListView, groupKeysOf } from './list-view.js';
 /** The union of every planned event's corpus, ordered by the focused event's
  *  precedence order with the documents only other events see appended. */
@@ -43,13 +44,10 @@ export function buildRows(plans, event) {
             absorb(other);
     return order.map((key) => rows.get(key));
 }
-/** Cells and their width, so the shell's legend and the list agree. */
-const CELL_COUNT = SURFACE_EVENTS.length;
-const MATRIX_WIDTH = CELL_COUNT * 2 - 1;
+/** The word a row's state prints in, wide enough for `shadowed` and for the
+ *  `N of M` a group rolls its subtree up to. */
+const STATE_WIDTH = 10;
 const COST_WIDTH = 6;
-/** The glyphs a group header counts its members with — the matrix vocabulary,
- *  so a rung reads the same in both columns. */
-const RUNG_MARK = { content: '█', preview: '▄', name: '▁' };
 /** Columns one nesting level spends, so a doc sits under its directory's label
  *  and the truncator sees the indent as part of the name it is eliding. */
 const INDENT = 2;
@@ -81,18 +79,24 @@ export class ContextDocsPanel {
     get visibleCount() {
         return this.lines.reduce((count, line) => count + (line.kind === 'group' && line.depth === 0 ? line.docs : 0), 0);
     }
-    setRows(rows, event, selectedKey) {
+    /** Documents that actually load on the dialled event, counted the same way —
+     *  the numerator of the heading's `N of M`. */
+    get loadedCount() {
+        return this.lines.reduce((count, line) => count +
+            (line.kind === 'group' && line.depth === 0 ? line.rungs.content + line.rungs.preview + line.rungs.name : 0), 0);
+    }
+    setRows(rows, event) {
         this.rows = rows;
         this.event = event;
         const live = groupKeysOf(rows);
         for (const key of this.expanded)
             if (!live.has(key))
                 this.expanded.delete(key);
-        this.relayout(selectedKey);
+        this.relayout();
     }
     setFilters(filters) {
         this.filters = filters;
-        this.relayout(this.selected?.key);
+        this.relayout();
     }
     move(delta) {
         if (this.lines.length === 0)
@@ -104,13 +108,6 @@ export class ContextDocsPanel {
     get onGroup() {
         return this.lines[this.index]?.kind === 'group';
     }
-    /** True when the focused line IS a document rather than merely standing for
-     *  one. A directory that is also a document is both, which is why the two
-     *  gestures split there: space opens it, enter edits it. */
-    get onDocument() {
-        const line = this.lines[this.index];
-        return line !== undefined && (line.kind === 'doc' || line.isDoc);
-    }
     toggleGroup() {
         const line = this.lines[this.index];
         if (line?.kind !== 'group')
@@ -119,32 +116,28 @@ export class ContextDocsPanel {
             this.expanded.delete(line.key);
         else
             this.expanded.add(line.key);
-        this.relayout(undefined, line.key);
+        this.relayout();
         this.onChange();
     }
-    /** Rebuild the drawn lines, keeping the cursor on the same document (or the
-     *  same directory), and clamping when what it was on is gone. A document that
-     *  owns a directory is drawn as that directory's header, so a held document
-     *  key matches there too. */
-    relayout(selectedKey, groupKey) {
-        const held = selectedKey ?? (this.lines[this.index]?.kind === 'doc' ? this.lines[this.index].key : undefined);
+    /** Rebuild the drawn lines, keeping the cursor on whatever it holds — the
+     *  same document, or the same directory header, which a collapsed group draws
+     *  no document row for — and clamping when what it was on is gone. */
+    relayout() {
+        const held = this.lines[this.index];
         this.lines = buildListView(this.rows, this.filters, this.expanded, this.event);
-        const wanted = groupKey !== undefined
-            ? this.lines.findIndex((line) => line.kind === 'group' && line.key === groupKey)
-            : held === undefined
-                ? -1
-                : this.lines.findIndex((line) => (line.kind === 'doc' && line.key === held) || (line.kind === 'group' && line.isDoc && line.first.key === held));
+        const wanted = held === undefined ? -1 : this.lines.findIndex((line) => line.kind === held.kind && line.key === held.key);
         this.index = wanted >= 0 ? wanted : Math.max(0, Math.min(this.index, this.lines.length - 1));
     }
-    render(width, height, focused, plans) {
+    render(width, height, focused) {
         const out = [];
-        const nameRoom = Math.max(1, width - MATRIX_WIDTH - COST_WIDTH - 3);
+        const nameRoom = Math.max(1, width - STATE_WIDTH - COST_WIDTH - 3);
         const heading = this.filters.query === '' ? 'DOCUMENTS' : `/${this.filters.query}`;
+        // The question the page is asking, in the terms the rows answer it in.
         const count = this.filters.query === ''
-            ? plural(this.visibleCount, 'doc', 'docs')
+            ? `${this.loadedCount} of ${this.visibleCount} load on ${this.event}`
             : plural(this.visibleCount, 'match', 'matches');
-        const matrixHead = SURFACE_EVENTS.map((event) => EVENT_INITIALS[event]).join(' ');
-        out.push(truncateToWidth(` ${padAnsi(`${theme.fg('accent', theme.bold(heading))} ${theme.fg('dim', count)}`, nameRoom + COST_WIDTH + 1)} ${theme.fg('dim', matrixHead)}`, width));
+        const title = `${theme.fg('accent', theme.bold(heading))} ${theme.fg('dim', count)}`;
+        out.push(` ${padAnsi(truncateToWidth(title, nameRoom), nameRoom)} ${field(theme.fg('dim', 'loads'), STATE_WIDTH)} ${field(theme.fg('dim', 'tokens'), COST_WIDTH)}`);
         if (this.lines.length === 0) {
             out.push('', theme.fg('dim', ' Nothing matches this question — cycle a facet back to "any".'));
             return this.fit(out, height);
@@ -153,7 +146,7 @@ export class ContextDocsPanel {
         const range = visibleRange(this.lines.length, this.index, capacity);
         for (let at = range.start; at < range.end; at += 1) {
             const line = this.lines[at];
-            const body = line.kind === 'group' ? this.groupLine(line, nameRoom, plans) : this.docLine(line, nameRoom, plans);
+            const body = line.kind === 'group' ? this.groupLine(line, nameRoom) : this.docLine(line, nameRoom);
             out.push(at === this.index && focused
                 ? theme.bg('selectedBg', padAnsi(body, width))
                 : at === this.index
@@ -162,25 +155,21 @@ export class ContextDocsPanel {
         }
         return this.fit(out, height);
     }
-    /** A directory header. Its stats and cost are the whole subtree's; the matrix
-     *  is drawn only when the directory is itself a document, which is what marks
-     *  the one row as both a document and a directory. */
-    groupLine(line, nameRoom, plans) {
+    /** A directory header: a pure rollup of its whole subtree — how many of its
+     *  documents load, and what they cost together. */
+    groupLine(line, nameRoom) {
         const marker = line.expanded ? '▾' : '▸';
         const label = `${' '.repeat(line.depth * INDENT)}${marker} ${theme.bold(line.label)}`;
-        const marks = ['content', 'preview', 'name']
-            .filter((rung) => line.rungs[rung] > 0)
-            .map((rung) => `${line.rungs[rung]}${RUNG_MARK[rung]}`)
-            .join(' ');
-        const stats = theme.fg('dim', marks === '' ? plural(line.docs, 'doc', 'docs') : `${line.docs} · ${marks}`);
-        const room = Math.max(1, nameRoom - visibleWidth(stats) - 1);
-        const field = `${padAnsi(truncateToWidth(label, room), room)} ${stats}`;
-        const matrix = line.isDoc ? matrixOf(line.first, plans) : ' '.repeat(MATRIX_WIDTH);
-        return ` ${padAnsi(field, nameRoom)} ${cost(line.cost)} ${matrix}`;
+        const loads = line.rungs.content + line.rungs.preview + line.rungs.name;
+        const rollup = theme.fg(loads > 0 ? 'success' : 'dim', `${loads} of ${line.docs}`);
+        return ` ${padAnsi(truncateToWidth(label, nameRoom), nameRoom)} ${field(rollup, STATE_WIDTH)} ${cost(line.cost)}`;
     }
-    docLine(line, nameRoom, plans) {
+    docLine(line, nameRoom) {
         const label = truncateToWidth(`${' '.repeat(line.depth * INDENT)}${line.label}`, nameRoom);
-        return ` ${padAnsi(label, nameRoom)} ${cost(line.cost)} ${matrixOf(line.row, plans)}`;
+        const record = line.row.records.get(this.event);
+        const state = stateLabel(record, deliveryStateOf(record));
+        const word = state.text === '' ? '' : theme.fg(state.tone, state.text);
+        return ` ${padAnsi(label, nameRoom)} ${field(word, STATE_WIDTH)} ${cost(line.cost)}`;
     }
     /** Pad rather than trim: this column sets the length of the divider drawn
      *  beside it. */
@@ -190,15 +179,13 @@ export class ContextDocsPanel {
         return lines.slice(0, height).map((line) => (visibleWidth(line) === 0 ? '' : line));
     }
 }
-/** One document's six events, in the order the heading names them. */
-function matrixOf(row, plans) {
-    return SURFACE_EVENTS.map((event) => {
-        const state = plans.peek(event) === undefined ? 'pending' : cellStateOf(row.records.get(event));
-        return cellGlyph(row.records.get(event), state);
-    }).join(' ');
+/** Right-flushed into a fixed column, so the state and cost fields read as one
+ *  block against the pane's right edge. */
+function field(text, width) {
+    const used = visibleWidth(text);
+    return used >= width ? truncateToWidth(text, width) : `${' '.repeat(width - used)}${text}`;
 }
 /** Right-flushed into the cost column, dim because it is an estimate. */
 function cost(count) {
-    const text = formatCost(count);
-    return theme.fg('dim', ' '.repeat(Math.max(0, COST_WIDTH - text.length)) + text);
+    return field(theme.fg('dim', formatCost(count)), COST_WIDTH);
 }

package/dist/commands/sys/context/admin/list-view.d.ts

@@ -32,11 +32,9 @@ export type ListLine = {
     expanded: boolean;
     /** The document the dossier describes while the cursor rests on the
      *  header: this directory's own document when it has one, else the first
-     *  document in its subtree. */
+     *  document in its subtree. A header never stands in for that document's
+     *  own row — it only keeps the dossier from going blank. */
     first: DocRow;
-    /** True when the directory is itself a document — `first` is that
-     *  document, and the one row is both selectable and expandable. */
-    isDoc: boolean;
 } | {
     kind: 'doc';
     key: string;

package/dist/commands/sys/context/admin/list-view.js

@@ -75,7 +75,6 @@ export function buildListView(rows, filters, expanded, event) {
             ...rollup(leading, event),
             expanded: open,
             first: leading[0],
-            isDoc: false,
         });
         if (open)
             for (const row of leading)
@@ -110,14 +109,14 @@ function emit(dir, filters, expanded, event, lines) {
         ...rollup(members, event),
         expanded: open,
         first: members[0],
-        isDoc: dir.selves.length > 0,
     });
     if (!open)
         return;
-    // The header already stands for the first document named exactly this path;
-    // a second store answering the same name still needs its own row.
-    for (const shadowed of dir.selves.slice(1))
-        lines.push(docLine(shadowed, dir.segment, dir.depth + 1, event));
+    // A directory that is also a document is a header plus a row, never one row
+    // doing both: the header is a pure rollup that expands, and the document sits
+    // inside it under its own name — no trailing slash — like any other member.
+    for (const self of dir.selves)
+        lines.push(docLine(self, dir.segment, dir.depth + 1, event));
     for (const child of dir.children.values())
         emit(child, filters, expanded, event, lines);
 }

package/dist/commands/sys/context/admin/model.d.ts

@@ -46,24 +46,28 @@ export declare class PlanSet {
     dispose(): void;
     /** The plan for one event, computing it now. */
     plan(event: SurfaceEvent): DeliveryPlan;
-    /** The plan for one event only if it is already computed — what the matrix
-     *  reads, so an uncomputed column draws as pending instead of stalling the
+    /** The plan for one event only if it is already computed — what the rail's
+     *  EVENTS counts read, so an unwarmed event draws `…` instead of stalling the
      *  frame on five extra corpus loads. */
     peek(event: SurfaceEvent): DeliveryPlan | undefined;
     /** Compute one pending event per macrotask, calling back after each so the
-     *  matrix fills in column by column. */
+     *  rail's counts fill in row by row. */
     warm(onProgress: () => void): void;
     private payload;
 }
-/** How one document reads in one event's cell. */
-export type CellState = 'pending' | 'delivers' | 'capped' | 'gated' | 'shadowed' | 'silent';
-export declare function cellStateOf(record: DeliveryRecord | undefined): CellState;
-/** One matrix cell: the delivered rung as a filled bar, or the mark that says
- *  why nothing is delivered. Colour separates a clean delivery from one the
- *  profile cap trimmed, so a capped `content` never reads as an authored one. */
-export declare function cellGlyph(record: DeliveryRecord | undefined, state: CellState): string;
-/** The one-letter column heads over the matrix, in `SURFACE_EVENTS` order. */
-export declare const EVENT_INITIALS: Record<SurfaceEvent, string>;
+/** What one document does in one event. */
+export type DeliveryState = 'delivers' | 'capped' | 'gated' | 'shadowed' | 'silent';
+export declare function deliveryStateOf(record: DeliveryRecord | undefined): DeliveryState;
+/** The word the list prints for one document's state, and the tone it prints it
+ *  in. The vocabulary is the one the author already writes in frontmatter
+ *  (`at: content`), so the column needs no legend: a delivery names the rung it
+ *  arrives at, warning-toned when the profile ceiling trimmed it below what the
+ *  entry authored. A document that does not load renders nothing at all unless
+ *  its silence has a name the page can act on — `gated` or `shadowed`. */
+export declare function stateLabel(record: DeliveryRecord | undefined, state: DeliveryState): {
+    text: string;
+    tone: 'success' | 'warning' | 'muted';
+};
 export declare function nextRung(rung: Rung, delta: number): Rung;
 /** A parsed entry back in the shape `memory edit --surface` accepts. The parsed
  *  form always carries `match` as a list and spells its frontmatter key

package/dist/commands/sys/context/admin/model.js

@@ -1,8 +1,7 @@
 // The read model behind `crtr sys context admin`: the configuration snapshot
 // the page dials, the per-event delivery plans it resolves from, and the
-// vocabulary both the matrix and the dossier read from.
+// vocabulary both the list and the dossier read from.
 import { resolve as resolvePath } from 'node:path';
-import { theme } from '../../../../core/tui/panel.js';
 import { realpathOrSelf } from '../../../../core/fs-utils.js';
 import { planDelivery, } from '../../../../core/substrate/plan.js';
 import { RUNGS, SURFACE_EVENTS, previewLine, rungRank, } from '../../../../core/substrate/schema.js';
@@ -76,14 +75,14 @@ export class PlanSet {
         this.plans.set(event, computed);
         return computed;
     }
-    /** The plan for one event only if it is already computed — what the matrix
-     *  reads, so an uncomputed column draws as pending instead of stalling the
+    /** The plan for one event only if it is already computed — what the rail's
+     *  EVENTS counts read, so an unwarmed event draws `…` instead of stalling the
      *  frame on five extra corpus loads. */
     peek(event) {
         return this.plans.get(event);
     }
     /** Compute one pending event per macrotask, calling back after each so the
-     *  matrix fills in column by column. */
+     *  rail's counts fill in row by row. */
     warm(onProgress) {
         if (this.warming !== undefined)
             return;
@@ -130,7 +129,7 @@ function resolvedDocRealpath(name, target) {
         return '';
     }
 }
-export function cellStateOf(record) {
+export function deliveryStateOf(record) {
     if (record === undefined)
         return 'silent';
     if (!record.docGate.pass)
@@ -146,33 +145,21 @@ export function cellStateOf(record) {
         return 'gated';
     return 'silent';
 }
-const RUNG_GLYPH = { none: '·', name: '▁', preview: '▄', content: '█' };
-/** One matrix cell: the delivered rung as a filled bar, or the mark that says
- *  why nothing is delivered. Colour separates a clean delivery from one the
- *  profile cap trimmed, so a capped `content` never reads as an authored one. */
-export function cellGlyph(record, state) {
-    if (state === 'pending')
-        return theme.fg('dim', '…');
+/** The word the list prints for one document's state, and the tone it prints it
+ *  in. The vocabulary is the one the author already writes in frontmatter
+ *  (`at: content`), so the column needs no legend: a delivery names the rung it
+ *  arrives at, warning-toned when the profile ceiling trimmed it below what the
+ *  entry authored. A document that does not load renders nothing at all unless
+ *  its silence has a name the page can act on — `gated` or `shadowed`. */
+export function stateLabel(record, state) {
     if (state === 'gated')
-        return theme.fg('warning', '×');
+        return { text: 'gated', tone: 'muted' };
     if (state === 'shadowed')
-        return theme.fg('muted', '∅');
-    if (record === undefined || state === 'silent')
-        return theme.fg('dim', RUNG_GLYPH.none);
-    const glyph = RUNG_GLYPH[record.finalRung];
-    if (state === 'capped')
-        return theme.fg('warning', record.finalRung === 'none' ? '⌐' : glyph);
-    return theme.fg('success', glyph);
+        return { text: 'shadowed', tone: 'muted' };
+    if (record === undefined || record.finalRung === 'none')
+        return { text: '', tone: 'muted' };
+    return { text: record.finalRung, tone: state === 'capped' ? 'warning' : 'success' };
 }
-/** The one-letter column heads over the matrix, in `SURFACE_EVENTS` order. */
-export const EVENT_INITIALS = {
-    boot: 'b',
-    'workspace-open': 'w',
-    read: 'r',
-    'memory-read': 'm',
-    command: 'c',
-    'pre-command': 'p',
-};
 export function nextRung(rung, delta) {
     const at = (rungRank(rung) + delta + RUNGS.length) % RUNGS.length;
     return RUNGS[at];

package/dist/commands/sys/context/admin/rail-panel.d.ts

@@ -1,3 +1,4 @@
+import { type SurfaceEvent } from '../../../../core/substrate/schema.js';
 import { type Snapshot } from './model.js';
 import type { Filters } from './list-view.js';
 export type AxisId = 'event' | 'payload' | 'kind' | 'mode' | 'lifecycle' | 'manager' | 'depth' | 'profile' | 'cwd';
@@ -20,9 +21,14 @@ export interface Facet {
  *  snapshot above it dials the NODE's kind. */
 export declare function facetsOf(filters: Filters): Facet[];
 export declare function cycleFacet(filters: Filters, id: FacetId, delta: number): Filters;
-/** The rail's rows for a snapshot. The payload row appears only for the events
- *  that read one, because on boot there is nothing it could change. */
+/** The configuration rows for a snapshot. The event and its payload are not
+ *  here — they belong to the EVENTS section, where the payload sits under the
+ *  count it explains. */
 export declare function axesOf(snapshot: Snapshot, profileName: string): Axis[];
+/** The payload field for the dialled event, or nothing when the event reads no
+ *  payload — on boot there is nothing it could change. It renders inside the
+ *  EVENTS section, directly under the count it explains. */
+export declare function payloadRowOf(snapshot: Snapshot): Axis | undefined;
 /** Cycle one enum axis, returning the changed snapshot. A typed axis is never
  *  cycled — the shell opens a field for it instead. */
 export declare function cycleAxis(snapshot: Snapshot, id: AxisId, delta: number): Snapshot;
@@ -30,12 +36,42 @@ export declare function cycleAxis(snapshot: Snapshot, id: AxisId, delta: number)
 export declare function setTypedAxis(snapshot: Snapshot, id: AxisId, value: string): Snapshot;
 /** The value a typed axis's field is seeded with. */
 export declare function typedAxisValue(snapshot: Snapshot, id: AxisId): string;
-/** Both sections as one column. `index` runs over the axes and then the facets
- *  — the order the shell routes a cycle in — while the section headings and the
- *  blank rows between them are drawn but never selectable. */
+/** One surface event as the rail states it: how many documents it delivers, and
+ *  whether it is the one the page is planning. `delivers` is undefined while
+ *  that event's plan is still warming. */
+export interface EventRow {
+    event: SurfaceEvent;
+    delivers: number | undefined;
+    dialled: boolean;
+}
+/** Every selectable rail row in drawn order: the events, the dialled event's
+ *  payload field directly under it, the configuration axes, then the filter
+ *  facets. One list, so the shell's single index is also the reading order. */
+export type RailRow = {
+    kind: 'event';
+    event: EventRow;
+} | {
+    kind: 'axis';
+    axis: Axis;
+    indent: boolean;
+} | {
+    kind: 'facet';
+    facet: Facet;
+};
+/** A rail row's identity, which the shell holds the cursor by. The list's
+ *  composition changes whenever the dialled event moves the payload row, so an
+ *  offset kept across that change points at a different row. */
+export declare function railRowKey(row: RailRow): string;
+/** What enter does on a rail row: an event dials it, a typed row opens its
+ *  field, and every other row hands the keyboard to the documents. Space does
+ *  the same thing on the first two and cycles the value on the last. */
+export declare function railEnter(row: RailRow | undefined): 'dial' | 'edit' | 'documents';
+export declare function railRowsOf(events: EventRow[], payload: Axis | undefined, axes: Axis[], facets: Facet[]): RailRow[];
+/** All three sections as one column. `index` runs over `rows`, while the
+ *  section headings and the blank rows between them are drawn but never
+ *  selectable. */
 export declare function renderRail(opts: {
-    axes: Axis[];
-    facets: Facet[];
+    rows: RailRow[];
     index: number;
     width: number;
     height: number;