@north-light/crouter 0.3.240 → 0.3.241

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

@@ -0,0 +1,53 @@
+import type { MemoryScope } from '../../../../core/memory-resolver.js';
+import type { DocKind, Rung, SurfaceEvent } from '../../../../core/substrate/schema.js';
+import type { DocRow } from './docs-panel.js';
+export type RungFacet = 'any' | Exclude<Rung, 'none'> | 'silent';
+export type OriginFacet = 'any' | MemoryScope;
+export type KindFacet = 'any' | DocKind;
+export type StateFacet = 'any' | 'delivering' | 'gated' | 'shadowed' | 'no-entry';
+/** 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 members add up to, so a collapsed
+ *  list still states where the corpus and its cost sit. */
+export type ListLine = {
+    kind: 'group';
+    key: string;
+    label: string;
+    docs: number;
+    rungs: Record<Exclude<Rung, 'none'>, number>;
+    cost: number;
+    expanded: boolean;
+    /** The first member, so the dossier has a document to describe while the
+     *  cursor rests on the header. */
+    first: DocRow;
+} | {
+    kind: 'doc';
+    key: string;
+    row: DocRow;
+    label: string;
+    cost: number;
+};
+export declare function groupKeyOf(name: string): string;
+/** Every group key the rows can produce, so collapse state can drop the keys a
+ *  re-plan removed instead of accumulating them. */
+export declare function groupKeysOf(rows: readonly DocRow[]): Set<string>;
+/** The lines to draw, in corpus order: the leading section, then each group in
+ *  order of first appearance. A live query force-expands every group holding a
+ *  match without touching `expanded`, so clearing it restores what the user
+ *  collapsed. */
+export declare function buildListView(rows: readonly DocRow[], filters: Filters, expanded: ReadonlySet<string>, event: SurfaceEvent): ListLine[];
+/** What the whole filtered set costs, split by the rung it arrives at. */
+export declare function costTotals(rows: readonly DocRow[], event: SurfaceEvent): {
+    total: number;
+    byRung: Record<Exclude<Rung, 'none'>, number>;
+};

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

@@ -0,0 +1,125 @@
+// The list's view model: which documents a question selects, how they group,
+// and what each group costs. Pure — no terminal, no colour, no width — so the
+// rail's counts and the list's rows are computed from the same call.
+import { fuzzyMatch } from '../../../../core/tui/fuzzy.js';
+import { deliveredCost, rungCostsOf } from './model.js';
+export const NO_FILTERS = { rung: 'any', origin: 'any', kind: 'any', state: 'any', query: '' };
+/** Documents whose canonical name carries no `/` share one leading section
+ *  rather than becoming a crowd of one-member groups. */
+const LEADING_KEY = '';
+const LEADING_LABEL = 'top level';
+export function groupKeyOf(name) {
+    const cut = name.indexOf('/');
+    return cut < 0 ? LEADING_KEY : name.slice(0, cut);
+}
+/** Every group key the rows can produce, so collapse state can drop the keys a
+ *  re-plan removed instead of accumulating them. */
+export function groupKeysOf(rows) {
+    return new Set(rows.map((row) => groupKeyOf(row.name)));
+}
+/** The lines to draw, in corpus order: the leading section, then each group in
+ *  order of first appearance. A live query force-expands every group holding a
+ *  match without touching `expanded`, so clearing it restores what the user
+ *  collapsed. */
+export function buildListView(rows, filters, expanded, event) {
+    const groups = new Map();
+    const order = [];
+    for (const row of rows) {
+        if (!passes(row, row.records.get(event), filters))
+            continue;
+        const key = groupKeyOf(row.name);
+        const held = groups.get(key);
+        if (held === undefined) {
+            groups.set(key, [row]);
+            order.push(key);
+        }
+        else
+            held.push(row);
+    }
+    if (groups.has(LEADING_KEY)) {
+        order.splice(order.indexOf(LEADING_KEY), 1);
+        order.unshift(LEADING_KEY);
+    }
+    const lines = [];
+    for (const key of order) {
+        const members = groups.get(key);
+        const rungs = { name: 0, preview: 0, content: 0 };
+        let cost = 0;
+        for (const row of members) {
+            const record = row.records.get(event);
+            if (record !== undefined && record.finalRung !== 'none')
+                rungs[record.finalRung] += 1;
+            cost += deliveredCost(record);
+        }
+        const open = filters.query !== '' || expanded.has(key);
+        lines.push({
+            kind: 'group',
+            key,
+            label: key === LEADING_KEY ? LEADING_LABEL : `${key}/`,
+            docs: members.length,
+            rungs,
+            cost,
+            expanded: open,
+            first: members[0],
+        });
+        if (!open)
+            continue;
+        for (const row of members) {
+            lines.push({
+                kind: 'doc',
+                key: row.key,
+                row,
+                label: key === LEADING_KEY ? row.name : row.name.slice(key.length + 1),
+                cost: deliveredCost(row.records.get(event)),
+            });
+        }
+    }
+    return lines;
+}
+/** What the whole filtered set costs, split by the rung it arrives at. */
+export function costTotals(rows, event) {
+    const byRung = { name: 0, preview: 0, content: 0 };
+    let total = 0;
+    for (const row of rows) {
+        const record = row.records.get(event);
+        if (record === undefined || record.finalRung === 'none')
+            continue;
+        const spend = rungCostsOf(record)[record.finalRung];
+        byRung[record.finalRung] += spend;
+        total += spend;
+    }
+    return { total, byRung };
+}
+function passes(row, record, filters) {
+    if (filters.rung !== 'any') {
+        const rung = record?.finalRung ?? 'none';
+        if (filters.rung === 'silent' ? rung !== 'none' : rung !== filters.rung)
+            return false;
+    }
+    if (filters.origin !== 'any' && row.anchor.scope !== filters.origin)
+        return false;
+    if (filters.kind !== 'any' && row.anchor.kind !== filters.kind)
+        return false;
+    if (filters.state !== 'any' && !inState(record, filters.state))
+        return false;
+    if (filters.query !== '' && !fuzzyMatch(filters.query, row.name))
+        return false;
+    return true;
+}
+/** `gated` is the document's own gate — the one predicate that can silence a
+ *  document in every event. An entry gate failure belongs to a single entry and
+ *  reads in the dossier's verdict, not here. */
+function inState(record, state) {
+    if (record === undefined)
+        return state === 'no-entry';
+    switch (state) {
+        case 'delivering':
+            return record.finalRung !== 'none';
+        case 'gated':
+            return !record.docGate.pass;
+        case 'shadowed':
+            return record.shadowedBy !== null;
+        case 'no-entry':
+            return record.authoredEntries.length === 0;
+    }
+}

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

@@ -73,3 +73,14 @@ export declare function surfaceEntryToFlag(entry: SurfaceEntry): string;
 /** One authored entry as a single readable row. */
 export declare function describeSurfaceEntry(entry: SurfaceEntry): string;
 export declare function plural(count: number, one: string, many: string): string;
+/** What one document would cost at each rung, in approximate tokens. The
+ *  renderers decide the payload: `content` emits the body, `preview` emits the
+ *  catalog entry plus the routing line, `name` emits the entry alone. The
+ *  estimate is characters ÷ 4 — it ranks documents correctly and totals
+ *  approximately, and every place it renders says so. */
+export type RungCosts = Record<Rung, number>;
+export declare function rungCostsOf(record: DeliveryRecord): RungCosts;
+/** What this document actually spends in the event the record belongs to. */
+export declare function deliveredCost(record: DeliveryRecord | undefined): number;
+/** Approximate tokens in at most six columns, always marked as an estimate. */
+export declare function formatCost(count: number): string;

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

@@ -5,7 +5,7 @@ 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, rungRank, } from '../../../../core/substrate/schema.js';
+import { RUNGS, SURFACE_EVENTS, previewLine, rungRank, } from '../../../../core/substrate/schema.js';
 import { scopeForCwd, profileNameFor } from '../../../../core/substrate/subject-fields.js';
 import { resolveMemoryDocForTarget } from '../../../../core/memory-resolver.js';
 export function subjectOf(snapshot) {
@@ -207,3 +207,30 @@ export function describeSurfaceEntry(entry) {
 export function plural(count, one, many) {
     return `${count} ${count === 1 ? one : many}`;
 }
+export function rungCostsOf(record) {
+    const entry = record.name.length;
+    const routing = previewLine(record.doc).length;
+    return {
+        none: 0,
+        name: tokens(entry),
+        preview: tokens(entry + routing),
+        content: tokens(record.doc.body.length),
+    };
+}
+/** What this document actually spends in the event the record belongs to. */
+export function deliveredCost(record) {
+    return record === undefined ? 0 : rungCostsOf(record)[record.finalRung];
+}
+function tokens(characters) {
+    return Math.ceil(characters / 4);
+}
+/** Approximate tokens in at most six columns, always marked as an estimate. */
+export function formatCost(count) {
+    if (count <= 0)
+        return '';
+    if (count < 1000)
+        return `~${count}`;
+    if (count < 10_000)
+        return `~${(count / 1000).toFixed(1)}k`;
+    return `~${Math.round(count / 1000)}k`;
+}

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

@@ -0,0 +1,46 @@
+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';
+export interface Axis {
+    id: AxisId;
+    label: string;
+    value: string;
+    /** Free-text axes open a field; the rest cycle in place. */
+    typed: boolean;
+}
+export type FacetId = 'rung' | 'origin' | 'kind' | 'state' | 'query';
+export interface Facet {
+    id: FacetId;
+    label: string;
+    value: string;
+    /** The query is typed; every other facet cycles through a closed set. */
+    typed: boolean;
+}
+/** The FILTERS rows for one filter value. `doc kind` is spelled out because the
+ *  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. */
+export declare function axesOf(snapshot: Snapshot, profileName: string): Axis[];
+/** 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;
+/** Apply a typed axis's submitted value. */
+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. */
+export declare function renderRail(opts: {
+    axes: Axis[];
+    facets: Facet[];
+    index: number;
+    width: number;
+    height: number;
+    focused: boolean;
+    /** Documents the filters select, out of the whole corpus. */
+    matched: number;
+    total: number;
+}): string[];

package/dist/commands/sys/context/admin/{axes-panel.js → rail-panel.js}

@@ -1,11 +1,45 @@
-// The snapshot rail: the configuration axes the page plans against. Every row
-// is a live control — an enum cycles in place, a free-text axis opens a field —
-// and every change re-plans the whole surface.
+// The rail: two sections in one row grammar. SNAPSHOT holds the configuration
+// axes the page plans against — changing one re-plans every event. FILTERS holds
+// the question asked of that plan — changing one only changes what is shown.
+// An enum cycles in place; a free-text row opens a field.
 import { truncateToWidth } from '@earendil-works/pi-tui';
-import { padAnsi, theme, visibleRange } from '../../../../core/tui/panel.js';
-import { SURFACE_EVENTS } from '../../../../core/substrate/schema.js';
+import { padAnsi, theme } from '../../../../core/tui/panel.js';
+import { KINDS, RUNGS, SURFACE_EVENTS } from '../../../../core/substrate/schema.js';
 import { listProfiles } from '../../../../core/profiles/manifest.js';
 import { payloadAxisFor } from './model.js';
+const RUNG_FACETS = ['any', ...RUNGS.filter((rung) => rung !== 'none'), 'silent'];
+const ORIGIN_FACETS = ['any', 'project', 'user', 'profile', 'builtin', 'node'];
+const KIND_FACETS = ['any', ...KINDS];
+const STATE_FACETS = ['any', 'delivering', 'gated', 'shadowed', 'no-entry'];
+/** The FILTERS rows for one filter value. `doc kind` is spelled out because the
+ *  snapshot above it dials the NODE's kind. */
+export function facetsOf(filters) {
+    return [
+        { id: 'rung', label: 'rung', value: filters.rung, typed: false },
+        { id: 'origin', label: 'origin', value: filters.origin, typed: false },
+        { id: 'kind', label: 'doc kind', value: filters.kind, typed: false },
+        { id: 'state', label: 'state', value: filters.state, typed: false },
+        { id: 'query', label: 'search', value: filters.query === '' ? 'any' : filters.query, typed: true },
+    ];
+}
+export function cycleFacet(filters, id, delta) {
+    const step = (values, current) => {
+        const at = values.indexOf(current);
+        return values[(Math.max(0, at) + delta + values.length) % values.length];
+    };
+    switch (id) {
+        case 'rung':
+            return { ...filters, rung: step(RUNG_FACETS, filters.rung) };
+        case 'origin':
+            return { ...filters, origin: step(ORIGIN_FACETS, filters.origin) };
+        case 'kind':
+            return { ...filters, kind: step(KIND_FACETS, filters.kind) };
+        case 'state':
+            return { ...filters, state: step(STATE_FACETS, filters.state) };
+        case 'query':
+            return filters;
+    }
+}
 function tildify(path) {
     const home = process.env['HOME'];
     return home !== undefined && home !== '' && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
@@ -92,26 +126,35 @@ export function typedAxisValue(snapshot, id) {
     return axis === 'file' ? snapshot.file : axis === 'docName' ? snapshot.docName : axis === 'command' ? snapshot.command : '';
 }
 const LABEL_WIDTH = 10;
-export function renderAxes(axes, index, width, height, focused) {
-    const out = [theme.fg('dim', ' SNAPSHOT'), ''];
-    const headerRows = out.length;
-    const rows = [];
-    for (const [at, axis] of axes.entries()) {
+/** 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. */
+export function renderRail(opts) {
+    const { axes, facets, index, width, height, focused, matched, total } = opts;
+    const lines = [];
+    let cursorLine = 0;
+    const push = (at, label, value) => {
         const room = Math.max(1, width - LABEL_WIDTH - 2);
-        const label = padAnsi(truncateToWidth(axis.label, LABEL_WIDTH), LABEL_WIDTH);
-        const value = truncateToWidth(axis.value, room);
-        const body = ` ${label} ${value}`;
+        const padded = padAnsi(truncateToWidth(label, LABEL_WIDTH), LABEL_WIDTH);
+        const shown = truncateToWidth(value, room);
+        const body = ` ${padded} ${shown}`;
+        if (at === index)
+            cursorLine = lines.length;
         if (at === index && focused)
-            rows.push(theme.bg('selectedBg', padAnsi(body, width)));
+            lines.push(theme.bg('selectedBg', padAnsi(body, width)));
         else if (at === index)
-            rows.push(`${theme.fg('accent', '▌')}${padAnsi(theme.fg('accent', body.slice(1)), width - 1)}`);
+            lines.push(`${theme.fg('accent', '▌')}${padAnsi(theme.fg('accent', body.slice(1)), width - 1)}`);
         else
-            rows.push(padAnsi(` ${theme.fg('dim', label)} ${value}`, width));
-    }
-    const capacity = Math.max(1, height - headerRows);
-    const range = visibleRange(rows.length, index, capacity);
-    out.push(...rows.slice(range.start, range.start + capacity));
+            lines.push(padAnsi(` ${theme.fg('dim', padded)} ${shown}`, width));
+    };
+    lines.push(theme.fg('dim', ' SNAPSHOT'), '');
+    axes.forEach((axis, at) => push(at, axis.label, axis.value));
+    lines.push('', theme.fg('dim', ` FILTERS · ${matched} of ${total}`), '');
+    facets.forEach((facet, at) => push(axes.length + at, facet.label, facet.value));
+    const maxStart = Math.max(0, lines.length - height);
+    const start = Math.min(Math.max(0, cursorLine - Math.floor(height / 2)), maxStart);
+    const out = lines.slice(start, start + height);
     while (out.length < height)
         out.push('');
-    return out.slice(0, height);
+    return out;
 }

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

@@ -14,7 +14,11 @@ export declare class ContextAdminShell implements Component, Focusable {
     private snapshot;
     private plans;
     private zone;
-    private axisIndex;
+    private railIndex;
+    private filters;
+    private rows;
+    /** The search field owns the keyboard while it is open. */
+    private searching;
     private readonly docs;
     private readonly detail;
     private modal;
@@ -35,6 +39,9 @@ export declare class ContextAdminShell implements Component, Focusable {
     /** Recompute the focused event's plan, refresh the panels from it, and let
      *  the remaining events fill in behind it. */
     private rebuild;
+    /** A filter never re-plans: it is a question about the plan already computed,
+     *  which is what keeps a facet change instant on a corpus this size. */
+    private setFilters;
     private syncDetail;
     private setSnapshot;
     private matches;
@@ -47,8 +54,14 @@ export declare class ContextAdminShell implements Component, Focusable {
      *  drawn against, so it earns the page-level gesture. */
     private cyclesEvent;
     handleInput(data: string): void;
-    private handleAxes;
+    /** The rail's rows are the snapshot axes followed by the filter facets, so
+     *  one cursor and one gesture drive both sections. */
+    private handleRail;
     private handleDocs;
+    private openSearch;
+    /** Typing filters live, so the field is the list's own heading rather than a
+     *  modal over the rows it is selecting. */
+    private handleSearch;
     private handleDetail;
     /** What the focused dossier row does when opened — the same write its letter
      *  key starts, so a user who never learns the letters can still edit. */
@@ -78,5 +91,9 @@ export declare class ContextAdminShell implements Component, Focusable {
     private renderModal;
     private footer;
     render(width: number): string[];
+    /** What the delivering documents spend on this event. An estimate, and a
+     *  floor on the rendered prompt: boot wraps these documents in its own intro
+     *  prose and catalog tree. */
+    private costMeta;
 }
 export declare function runContextAdmin(seed: Snapshot): Promise<AdminResult | undefined>;