@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,73 @@
+import type { NodeConfigSubject } from '../../../../core/substrate/subject-fields.js';
+import type { PlannedEvent } from '../resolve.js';
+import { type AdminRecord } from './model.js';
+import type { DocRow } from './docs-panel.js';
+type SurfaceEvent = PlannedEvent;
+/** A field of the focused document the shell can write. `rule` carries an
+ *  index into the document's whole rule list, not the focused event's subset,
+ *  because that list is what a write replaces. */
+export type DetailRow = {
+    kind: 'rule';
+    at: number;
+} | {
+    kind: 'add-rule';
+} | {
+    kind: 'preview';
+} | {
+    kind: 'unlisted';
+} | {
+    kind: 'body';
+} | {
+    kind: 'move';
+};
+export declare class ContextDetailPanel {
+    private row;
+    private event;
+    private body;
+    private readOnly;
+    private subject;
+    private rows;
+    private index;
+    private face;
+    private open;
+    private scroll;
+    /** Last render's geometry, so a half-pane jump and the end-of-content clamp
+     *  measure against real content rather than a counter nobody can see. */
+    private lastLines;
+    private lastHeight;
+    setContext(row: DocRow | undefined, event: SurfaceEvent, readOnly: string | null, subject: NodeConfigSubject | null, body: string | undefined): 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;
+    get bodyOpen(): boolean;
+    get selected(): DetailRow | undefined;
+    /** The rule index a level cycle or a removal would act on. */
+    get selectedRule(): number | undefined;
+    /** `j`/`k`: a line of the read face, a field of the edit face. */
+    move(delta: number): void;
+    /** `ctrl-d`/`ctrl-u`: half a pane, so a long body is crossed in jumps a
+     *  reader can still follow. */
+    page(direction: 1 | -1): void;
+    /** `g`/`G`. */
+    jump(to: 'top' | 'bottom'): void;
+    /** `enter`: the document's own text, in place. The body is not in the plan,
+     *  so the shell fetches it and hands it over through `setContext`. */
+    openBody(): boolean;
+    /** `e`: the field list. */
+    edit(): void;
+    /** `esc`/`h`: leave the edit face, else collapse the body. False means the
+     *  read face is already at rest and the shell should leave the dossier. */
+    back(): boolean;
+    private scrollBy;
+    private maxScroll;
+    private record;
+    private context;
+    render(width: number, height: number, focused: boolean): string[];
+    /** Today's field list, under the identity and delivery it is being edited
+     *  against. A row's clarifying tail renders only while that row is focused:
+     *  unfocused, twelve explanations are twelve lines of noise. */
+    private editLines;
+}
+/** The editable rows for one document, in the order the panel draws them. */
+export declare function buildDetailRows(record: AdminRecord): DetailRow[];
+export {};

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

@@ -0,0 +1,233 @@
+// The dossier: one memory document, read first.
+//
+// Two faces over one pane. The read face is the resting state — who this
+// document is, when an agent reads it, what it says, and whether it loads on
+// this event — and `enter` opens its body in place. The edit face is the field
+// list every write still starts from, one `e` away. The panel owns which face
+// is showing and how far it is scrolled; it owns no text layout.
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { padAnsi, theme, wrapText } from '../../../../core/tui/panel.js';
+import { describeRule, plural } from './model.js';
+import { renderDossierDelivery, renderDossierHeader, renderDossierRead } from './read-view.js';
+export class ContextDetailPanel {
+    row;
+    event = 'boot';
+    body;
+    readOnly = null;
+    subject = null;
+    rows = [];
+    index = 0;
+    face = 'read';
+    open = false;
+    scroll = 0;
+    /** Last render's geometry, so a half-pane jump and the end-of-content clamp
+     *  measure against real content rather than a counter nobody can see. */
+    lastLines = 1;
+    lastHeight = 1;
+    setContext(row, event, readOnly, subject, body) {
+        const changed = row?.key !== this.row?.key;
+        this.row = row;
+        this.event = event;
+        this.body = body;
+        this.readOnly = readOnly;
+        this.subject = subject;
+        this.rows = row === undefined ? [] : buildDetailRows(row.anchor);
+        if (changed) {
+            this.index = 0;
+            this.scroll = 0;
+            this.open = false;
+            this.face = 'read';
+        }
+        this.index = Math.max(0, Math.min(this.index, this.rows.length - 1));
+    }
+    /** True while the field list owns the pane, so the shell routes the write
+     *  letters and teaches them in the footer. */
+    get editing() {
+        return this.face === 'edit';
+    }
+    get bodyOpen() {
+        return this.open;
+    }
+    get selected() {
+        return this.face === 'edit' ? this.rows[this.index] : undefined;
+    }
+    /** The rule index a level cycle or a removal would act on. */
+    get selectedRule() {
+        const row = this.selected;
+        return row?.kind === 'rule' ? row.at : undefined;
+    }
+    // navigation
+    /** `j`/`k`: a line of the read face, a field of the edit face. */
+    move(delta) {
+        if (this.face === 'edit') {
+            this.index = Math.max(0, Math.min(this.rows.length - 1, this.index + delta));
+            return;
+        }
+        this.scrollBy(delta);
+    }
+    /** `ctrl-d`/`ctrl-u`: half a pane, so a long body is crossed in jumps a
+     *  reader can still follow. */
+    page(direction) {
+        if (this.face === 'edit')
+            return;
+        this.scrollBy(direction * Math.max(1, Math.floor(this.lastHeight / 2)));
+    }
+    /** `g`/`G`. */
+    jump(to) {
+        if (this.face === 'edit')
+            return;
+        this.scroll = to === 'top' ? 0 : this.maxScroll();
+    }
+    /** `enter`: the document's own text, in place. The body is not in the plan,
+     *  so the shell fetches it and hands it over through `setContext`. */
+    openBody() {
+        if (this.face === 'edit' || this.row === undefined)
+            return false;
+        this.open = true;
+        this.scroll = 0;
+        return true;
+    }
+    /** `e`: the field list. */
+    edit() {
+        if (this.row === undefined)
+            return;
+        this.face = 'edit';
+        this.scroll = 0;
+    }
+    /** `esc`/`h`: leave the edit face, else collapse the body. False means the
+     *  read face is already at rest and the shell should leave the dossier. */
+    back() {
+        if (this.face === 'edit') {
+            this.face = 'read';
+            this.scroll = 0;
+            return true;
+        }
+        if (!this.open)
+            return false;
+        this.open = false;
+        this.scroll = 0;
+        return true;
+    }
+    scrollBy(delta) {
+        this.scroll = Math.max(0, Math.min(this.scroll + delta, this.maxScroll()));
+    }
+    maxScroll() {
+        return Math.max(0, this.lastLines - this.lastHeight);
+    }
+    record() {
+        const row = this.row;
+        return row.records.get(this.event) ?? row.anchor;
+    }
+    context() {
+        return {
+            event: this.event,
+            records: this.row?.records ?? new Map(),
+            readOnly: this.readOnly !== null,
+            body: this.body,
+            subject: this.subject,
+        };
+    }
+    // rendering
+    render(width, height, focused) {
+        if (this.row === undefined) {
+            this.lastLines = 1;
+            this.lastHeight = height;
+            return fit([theme.fg('dim', ' Select a document.')], height);
+        }
+        const record = this.record();
+        const built = this.face === 'read'
+            ? { lines: renderDossierRead(record, this.context(), width, this.open), cursor: undefined }
+            : this.editLines(record, width, focused);
+        const lines = built.lines;
+        // The badge is the pane's last row, so it costs a line of content only
+        // while there is content it cannot show anyway.
+        const overflows = lines.length > height;
+        const viewport = Math.max(1, overflows ? height - 1 : height);
+        this.lastLines = lines.length;
+        this.lastHeight = viewport;
+        let start;
+        if (built.cursor === undefined) {
+            this.scroll = Math.max(0, Math.min(this.scroll, Math.max(0, lines.length - viewport)));
+            start = this.scroll;
+        }
+        else {
+            start = Math.min(Math.max(0, built.cursor - Math.floor(viewport / 3)), Math.max(0, lines.length - viewport));
+        }
+        const window = fit(lines.slice(start, start + viewport), viewport);
+        if (!overflows)
+            return window;
+        window.push(badge(start + 1, Math.min(lines.length, start + viewport), lines.length, width));
+        return window;
+    }
+    /** Today's field list, under the identity and delivery it is being edited
+     *  against. A row's clarifying tail renders only while that row is focused:
+     *  unfocused, twelve explanations are twelve lines of noise. */
+    editLines(record, width, focused) {
+        const context = this.context();
+        const lines = [...renderDossierHeader(record, context, width), ...renderDossierDelivery(record, context, width), ''];
+        let cursor = 0;
+        const push = (at, body, tail) => {
+            const own = [body, ...(at === this.index && tail !== undefined ? tailLines(tail, width) : [])];
+            if (at === this.index)
+                cursor = lines.length;
+            for (const line of own) {
+                lines.push(at === this.index && focused
+                    ? theme.bg('selectedBg', padAnsi(truncateToWidth(line, width), width))
+                    : at === this.index
+                        ? `${theme.fg('accent', '\u258c')}${truncateToWidth(line, Math.max(0, width - 1))}`
+                        : ` ${truncateToWidth(line, Math.max(0, width - 1))}`);
+            }
+        };
+        let at = 0;
+        lines.push(theme.fg('dim', ' RULES'));
+        const rules = record.doc.rules;
+        if (rules.length === 0) {
+            lines.push(theme.fg('dim', ' no rules — this document only appears in its listing'));
+        }
+        for (const rule of rules) {
+            const text = describeRule(rule);
+            push(at++, rule.on === this.event ? text : theme.fg('dim', text));
+        }
+        push(at++, theme.fg('success', '+ add a delivery rule'));
+        lines.push('');
+        lines.push(theme.fg('dim', ' DOCUMENT'));
+        push(at++, field('preview', record.doc.preview === '' ? theme.fg('dim', 'none') : record.doc.preview, width));
+        push(at++, field('unlisted', record.doc.unlisted ? 'yes' : theme.fg('dim', 'no'), width));
+        push(at++, field('body', theme.fg('dim', this.body === undefined ? 'not read yet' : plural(bodyLines(this.body), 'line', 'lines')), width), 'opens in $EDITOR');
+        push(at++, field('name', record.doc.displayName, width), 'renames the document under its own owner');
+        lines.push(` ${field('owner', theme.fg('dim', record.doc.ownerHandle), Math.max(0, width - 1))}`);
+        lines.push(` ${field('object', theme.fg('dim', record.doc.object.id), Math.max(0, width - 1))}`);
+        return { lines, cursor };
+    }
+}
+/** The editable rows for one document, in the order the panel draws them. */
+export function buildDetailRows(record) {
+    const rules = record.doc.rules.map((_rule, at) => ({ kind: 'rule', at }));
+    return [...rules, { kind: 'add-rule' }, { kind: 'preview' }, { kind: 'unlisted' }, { kind: 'body' }, { kind: 'move' }];
+}
+function bodyLines(body) {
+    const trimmed = body.replace(/\n+$/, '');
+    return trimmed === '' ? 0 : trimmed.split('\n').length;
+}
+const FIELD_WIDTH = 15;
+function field(label, value, width) {
+    const room = Math.max(1, width - FIELD_WIDTH - 2);
+    return `${padAnsi(theme.fg('dim', label), FIELD_WIDTH)} ${truncateToWidth(value, room)}`;
+}
+/** A focused row's explanation, hanging under its value rather than its label. */
+function tailLines(text, width) {
+    const room = Math.max(1, width - FIELD_WIDTH - 2);
+    return wrapText(`\u2014 ${text}`, room).map((line) => `${' '.repeat(FIELD_WIDTH + 1)}${theme.fg('dim', line)}`);
+}
+/** Where the visible window sits in the whole document, drawn only while there
+ *  is something outside it. */
+function badge(from, to, total, width) {
+    const text = `${from}\u2013${to} / ${total}`;
+    return theme.fg('dim', `${' '.repeat(Math.max(0, width - text.length))}${text}`);
+}
+function fit(lines, height) {
+    const out = [...lines];
+    while (out.length < height)
+        out.push('');
+    return out.slice(0, height).map((line) => (visibleWidth(line) === 0 ? '' : line));
+}

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

@@ -0,0 +1,63 @@
+import { type PlannedEvent } from '../resolve.js';
+import { PlanSet, type AdminRecord } from './model.js';
+type SurfaceEvent = PlannedEvent;
+import { type Filters } from './list-view.js';
+/** One physical document across every event. `records` is sparse: an event
+ *  whose corpus never reaches this document has no record for it, and an event
+ *  still being planned has none yet either. */
+export interface DocRow {
+    key: string;
+    name: string;
+    /** The record for the focused event, or the first one any event carries —
+     *  every panel needs a document to describe even when the focused event's
+     *  corpus excludes it. */
+    anchor: AdminRecord;
+    records: Map<SurfaceEvent, AdminRecord>;
+    /** Present only in an event other than the focused one. */
+    offEvent: boolean;
+}
+/** The union of every planned event's corpus, ordered by the focused event's
+ *  precedence order with the documents only other events see appended. */
+export declare function buildRows(plans: PlanSet, event: SurfaceEvent): DocRow[];
+export declare class ContextDocsPanel {
+    private readonly onChange;
+    private rows;
+    private filters;
+    private event;
+    private lines;
+    private index;
+    /** Directories the user opened, by full name prefix. Empty means every level
+     *  is collapsed, which is how the page opens: ~25 rows that name the whole
+     *  corpus. */
+    private readonly expanded;
+    constructor(onChange: () => void);
+    /** The document the dossier describes: the focused row, or the first member
+     *  of the focused group so the dossier is never blank. */
+    get selected(): DocRow | undefined;
+    /** Documents the current question selects — counted from the top-level
+     *  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;
+    /** 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;
+    toggleGroup(): void;
+    /** 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): string[];
+    /** A directory header: a pure rollup of its whole subtree — how many of its
+     *  documents load. */
+    private groupLine;
+    private docLine;
+    /** Pad rather than trim: this column sets the length of the divider drawn
+     *  beside it. */
+    private fit;
+}
+export {};

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

@@ -0,0 +1,185 @@
+// The middle column: every document with a rule for some activity in the
+// snapshot's view, grouped recursively by the segments of its name, each stating
+// in one word what it does on the dialled activity. One row is one document
+// object, so two owners' documents answering to the same 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 { PLANNED_EVENTS } from '../resolve.js';
+import { deliveryStateOf, 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. */
+export function buildRows(plans, event) {
+    const rows = new Map();
+    const order = [];
+    const absorb = (planEvent) => {
+        const plan = plans.peek(planEvent);
+        if (plan === undefined)
+            return;
+        for (const record of plan.docs) {
+            const key = record.doc.object.id;
+            const held = rows.get(key);
+            if (held === undefined) {
+                rows.set(key, {
+                    key,
+                    name: record.doc.displayName,
+                    anchor: record,
+                    records: new Map([[planEvent, record]]),
+                    offEvent: planEvent !== event,
+                });
+                order.push(key);
+                continue;
+            }
+            held.records.set(planEvent, record);
+            if (planEvent === event) {
+                held.anchor = record;
+                held.offEvent = false;
+            }
+        }
+    };
+    absorb(event);
+    for (const other of PLANNED_EVENTS)
+        if (other !== event)
+            absorb(other);
+    return order.map((key) => rows.get(key));
+}
+/** 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;
+/** 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;
+export class ContextDocsPanel {
+    onChange;
+    rows = [];
+    filters = NO_FILTERS;
+    event = 'boot';
+    lines = [];
+    index = 0;
+    /** Directories the user opened, by full name prefix. Empty means every level
+     *  is collapsed, which is how the page opens: ~25 rows that name the whole
+     *  corpus. */
+    expanded = new Set();
+    constructor(onChange) {
+        this.onChange = onChange;
+    }
+    /** The document the dossier describes: the focused row, or the first member
+     *  of the focused group so the dossier is never blank. */
+    get selected() {
+        const line = this.lines[this.index];
+        if (line === undefined)
+            return undefined;
+        return line.kind === 'doc' ? line.row : line.first;
+    }
+    /** Documents the current question selects — counted from the top-level
+     *  rollups, which partition the corpus, so a fully collapsed list still
+     *  reports its size and a nested rollup is never counted twice. */
+    get visibleCount() {
+        return this.lines.reduce((count, line) => count + (line.kind === 'group' && line.depth === 0 ? line.docs : 0), 0);
+    }
+    /** 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();
+    }
+    setFilters(filters) {
+        this.filters = filters;
+        this.relayout();
+    }
+    move(delta) {
+        if (this.lines.length === 0)
+            return;
+        this.index = Math.max(0, Math.min(this.lines.length - 1, this.index + delta));
+        this.onChange();
+    }
+    /** True when the focused line can be opened — a directory header. */
+    get onGroup() {
+        return this.lines[this.index]?.kind === 'group';
+    }
+    toggleGroup() {
+        const line = this.lines[this.index];
+        if (line?.kind !== 'group')
+            return;
+        if (this.expanded.has(line.key))
+            this.expanded.delete(line.key);
+        else
+            this.expanded.add(line.key);
+        this.relayout();
+        this.onChange();
+    }
+    /** 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 = 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) {
+        const out = [];
+        const nameRoom = Math.max(1, width - STATE_WIDTH - 2);
+        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 === ''
+            ? `${this.loadedCount} of ${this.visibleCount} load on ${this.event}`
+            : plural(this.visibleCount, 'match', 'matches');
+        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)}`);
+        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);
+        }
+        const capacity = Math.max(1, height - out.length);
+        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) : this.docLine(line, nameRoom);
+            out.push(at === this.index && focused
+                ? theme.bg('selectedBg', padAnsi(body, width))
+                : at === this.index
+                    ? `${theme.fg('accent', '▌')}${truncateToWidth(body.slice(1), Math.max(0, width - 1))}`
+                    : body);
+        }
+        return this.fit(out, height);
+    }
+    /** A directory header: a pure rollup of its whole subtree — how many of its
+     *  documents load. */
+    groupLine(line, nameRoom) {
+        const marker = line.expanded ? '▾' : '▸';
+        const label = `${' '.repeat(line.depth * INDENT)}${marker} ${theme.bold(line.label)}`;
+        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)}`;
+    }
+    docLine(line, nameRoom) {
+        const label = truncateToWidth(`${' '.repeat(line.depth * INDENT)}${line.label}`, nameRoom);
+        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)}`;
+    }
+    /** Pad rather than trim: this column sets the length of the divider drawn
+     *  beside it. */
+    fit(lines, height) {
+        while (lines.length < height)
+            lines.push('');
+        return lines.slice(0, height).map((line) => (visibleWidth(line) === 0 ? '' : line));
+    }
+}
+/** Right-flushed into a fixed column against the pane's right edge. */
+function field(text, width) {
+    const used = visibleWidth(text);
+    return used >= width ? truncateToWidth(text, width) : `${' '.repeat(width - used)}${text}`;
+}

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

@@ -0,0 +1,62 @@
+import type { DocKind, Rung } from '../../../../core/substrate/schema.js';
+import type { PlannedEvent } from '../resolve.js';
+import type { DocRow } from './docs-panel.js';
+import type { AdminRecord } from './model.js';
+type SurfaceEvent = PlannedEvent;
+/** The owner types a document can belong to. */
+export declare const OWNER_TYPES: readonly ["node", "user", "profile", "repo", "app"];
+export type RungFacet = 'any' | Exclude<Rung, 'none'> | 'silent';
+export type OriginFacet = 'any' | (typeof OWNER_TYPES)[number];
+export type KindFacet = 'any' | DocKind;
+export type StateFacet = 'any' | 'delivering' | 'gated' | 'shadowed' | 'no-rule';
+/** The question the page is asking. Rung asks what arrives, state asks why it
+ *  does not, and the two compose. Every facet is "any" by default, so the page
+ *  opens on the whole corpus. */
+export interface Filters {
+    rung: RungFacet;
+    origin: OriginFacet;
+    kind: KindFacet;
+    state: StateFacet;
+    /** Fuzzy subsequence over the canonical name only. */
+    query: string;
+}
+export declare const NO_FILTERS: Filters;
+/** One drawn line. A group carries what its whole subtree adds up to, so a
+ *  collapsed list still states where the corpus and its deliveries sit. `depth` is
+ *  how many name segments sit above the line, which the renderer spends on
+ *  indent. */
+export type ListLine = {
+    kind: 'group';
+    key: string;
+    label: string;
+    depth: number;
+    docs: number;
+    rungs: Record<Exclude<Rung, 'none'>, number>;
+    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. A header never stands in for that document's
+     *  own row — it only keeps the dossier from going blank. */
+    first: DocRow;
+} | {
+    kind: 'doc';
+    key: string;
+    row: DocRow;
+    label: string;
+    depth: number;
+};
+/** Every group key the rows can produce — one per proper name prefix, since a
+ *  prefix exists only because something sits under it — so collapse state can
+ *  drop the keys a re-plan removed instead of accumulating them. The leading
+ *  section is a key only when a name with no `/` owns no directory, which is
+ *  exactly when it is not itself one of those prefixes. */
+export declare function groupKeysOf(rows: readonly DocRow[]): Set<string>;
+/** The lines to draw, in corpus order: the leading section, then each directory
+ *  in order of first appearance, each recursing into its own members only when
+ *  it is open. A live query force-expands every directory, which is exactly the
+ *  ancestor chain of every surviving match, without touching `expanded` — so
+ *  clearing the query restores what the user collapsed. */
+export declare function buildListView(rows: readonly DocRow[], filters: Filters, expanded: ReadonlySet<string>, event: SurfaceEvent): ListLine[];
+/** `user` is the person owner; every other facet is the owner object's type. */
+export declare function ownerTypeOf(record: AdminRecord): string;
+export {};