@north-light/api 0.3.580 → 0.3.588

package/dist/commands/pkg/browse/shell.js

@@ -0,0 +1,640 @@
+// The `crtr pkg browse` page: a grouped source rail, plugin list, and dossier.
+import { Input, matchesKey, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
+import { formatGesture, formatMovePair, matchesPiTuiInput, } from '../../../core/keybindings/index.js';
+import { runTuiPage } from '../../../core/tui/page-host.js';
+import { PAGE_CHROME_ROWS, columns, framed, padAnsi, pageFrame, theme, visibleRange, } from '../../../core/tui/panel.js';
+import { availableActions, presentAction, runAction } from './actions.js';
+import { loadCapability, loadCatalog } from './catalog.js';
+import { PkgDetailPanel } from './detail-panel.js';
+import { PkgListPanel } from './list-panel.js';
+import { INSTALLED_SOURCE_ID, marketplaceSourceId, plural, } from './model.js';
+const RAIL_WIDTH = 22;
+const LIST_WIDTH = 34;
+const RAIL_MIN_TOTAL_WIDTH = 84;
+const THREE_COLUMN_MIN_WIDTH = 108;
+/** Full-screen plugin browser. The data and mutation boundaries stay in the
+ * catalog/actions collaborators, leaving this class responsible for movement,
+ * disclosure, and the rendered page grammar. */
+export class PkgBrowseShell {
+    tui;
+    terminalRows;
+    bindings;
+    catalog;
+    sourceIndex = 0;
+    zone = "rail";
+    list;
+    detail = new PkgDetailPanel();
+    // `undefined` is an in-flight capability read; `null` is a completed read with
+    // no inspectable plugin directory. `Map.has()` distinguishes a request that
+    // has started from a row never selected in this browser session.
+    capabilities = new Map();
+    modal;
+    busy;
+    notice;
+    _focused = false;
+    onCancel;
+    constructor(tui, terminalRows, bindings) {
+        this.tui = tui;
+        this.terminalRows = terminalRows;
+        this.bindings = bindings;
+        this.catalog = loadCatalog();
+        this.list = new PkgListPanel(() => this.tui.requestRender());
+        this.syncSource();
+    }
+    /** The page follows the user's own `crtr.setup.*` navigation gestures, the
+     *  same ones `crtr sys settings` resolves, alongside its literal defaults —
+     *  a remap must not leave one full-screen page moving and the other stuck. */
+    matches(id, data) {
+        return matchesPiTuiInput(this.bindings, id, data, (input, gesture) => matchesKey(input, gesture));
+    }
+    /** The footer names keys, so it names the gestures actually bound. */
+    label(id, fallback) {
+        const gestures = this.bindings.gestures(id);
+        return gestures.length === 0 ? fallback : formatGesture(gestures[0].split(" > ").pop());
+    }
+    isDown(data) {
+        return matchesKey(data, "j") || matchesKey(data, "down") || this.matches("crtr.setup.list-down", data);
+    }
+    isUp(data) {
+        return matchesKey(data, "k") || matchesKey(data, "up") || this.matches("crtr.setup.list-up", data);
+    }
+    /** Move one zone to the right, or open the focused row. */
+    isDescend(data) {
+        return (matchesKey(data, "l") ||
+            matchesKey(data, "right") ||
+            matchesKey(data, "enter") ||
+            this.matches("crtr.setup.advance", data) ||
+            this.matches("crtr.setup.open", data));
+    }
+    /** Move one zone to the left. Escape is deliberately separate: in the dossier
+     *  it pops the whole view stack where `h` folds one branch. */
+    isAscend(data) {
+        return matchesKey(data, "h") || matchesKey(data, "left");
+    }
+    /** Tab cycles rail sources from anywhere. The resolved `tab-next` gesture
+     *  also carries the horizontal arrows, which mean "into the panel" here, so
+     *  those are excluded exactly as the settings shell excludes them. */
+    cyclesSource(data) {
+        const horizontal = matchesKey(data, "right") || matchesKey(data, "left");
+        if (matchesKey(data, "tab") || (!horizontal && this.matches("crtr.setup.tab-next", data)))
+            return 1;
+        if (matchesKey(data, "shift+tab") || (!horizontal && this.matches("crtr.setup.tab-previous", data)))
+            return -1;
+        return 0;
+    }
+    set focused(value) {
+        this._focused = value;
+    }
+    get focused() {
+        return this._focused;
+    }
+    /** Required by pi-tui's `Component`, and deliberately a no-op: this page
+     *  holds no render cache to drop. Every panel is recomputed each frame
+     *  because capability reads and action results land between input events. */
+    invalidate() { }
+    dispose() {
+        if (this.busy !== undefined)
+            clearInterval(this.busy.timer);
+    }
+    // model selection
+    sources() {
+        if (this.catalog.sources.length > 0)
+            return this.catalog.sources;
+        // A first run has no registered marketplace, but it still needs a Library
+        // row so the empty state has a home and `a` has an obvious invitation.
+        return [{ id: INSTALLED_SOURCE_ID, kind: "installed", label: "Installed", entries: [] }];
+    }
+    get source() {
+        const sources = this.sources();
+        this.sourceIndex = Math.max(0, Math.min(this.sourceIndex, sources.length - 1));
+        return sources[this.sourceIndex];
+    }
+    syncSource(selectedKey) {
+        this.list.setSource(this.source, selectedKey);
+        this.syncDetail();
+    }
+    syncDetail() {
+        const entry = this.list.selected;
+        let capability = null;
+        if (entry !== undefined) {
+            if (!this.capabilities.has(entry.key)) {
+                this.capabilities.set(entry.key, undefined);
+                // Capability validation is deliberately asynchronous: it asks the same
+                // command-path authority the install gate uses. Rendering stays cheap;
+                // the dossier shows its identity/provenance immediately, then redraws
+                // only when this selected row's capability surface arrives.
+                // A capability read that fails is a fact about one plugin, never a
+                // reason to take the page down with it: the dossier says the surface is
+                // unknowable and every other row keeps working.
+                void Promise.resolve(loadCapability(entry))
+                    .catch(() => null)
+                    .then((resolved) => {
+                    this.capabilities.set(entry.key, resolved);
+                    if (this.list.selected?.key !== entry.key)
+                        return;
+                    this.syncDetail();
+                    this.tui.requestRender();
+                });
+            }
+            capability = this.capabilities.get(entry.key);
+        }
+        // A catalog warning is page-level, not a fact about the focused plugin. The
+        // notice above the list carries the first and says how many others there
+        // are; the source dossier lists every one of them, so a second breakage is
+        // never silently dropped.
+        const warnings = this.catalog.warnings;
+        const first = warnings[0];
+        this.list.setNotice(first === undefined ? undefined : warnings.length > 1 ? `${first} · +${warnings.length - 1} more` : first);
+        this.list.setEmptyState(this.sources().some((source) => source.kind === "marketplace"));
+        this.detail.setWarnings(warnings);
+        this.detail.setEntry(entry, this.source, capability);
+    }
+    reload(selectedKey) {
+        const priorSource = this.source.id;
+        this.catalog = loadCatalog();
+        this.capabilities.clear();
+        const nextSource = this.sources().findIndex((source) => source.id === priorSource);
+        this.sourceIndex = nextSource >= 0 ? nextSource : 0;
+        this.syncSource(selectedKey);
+    }
+    goSource(delta) {
+        const sources = this.sources();
+        this.sourceIndex = (this.sourceIndex + delta + sources.length) % sources.length;
+        this.clearActionNotice();
+        this.syncSource();
+    }
+    moveList(delta) {
+        this.list.move(delta);
+        this.clearActionNotice();
+        this.syncDetail();
+    }
+    clearActionNotice() {
+        this.notice = undefined;
+    }
+    // input
+    /** A live filter, an open modal, or a running action holds every key — the
+     *  one predicate both `handleInput` and the footer consult, so the footer can
+     *  never advertise a key the filter is swallowing. */
+    panelOwnsKeyboard() {
+        return this.busy !== undefined || this.modal !== undefined || this.list.ownsKeyboard;
+    }
+    handleInput(data) {
+        if (this.busy !== undefined)
+            return;
+        if (this.modal !== undefined) {
+            this.handleModal(data);
+            return;
+        }
+        if (this.list.ownsKeyboard && this.list.handleInput(data)) {
+            this.clearActionNotice();
+            this.syncDetail();
+            return;
+        }
+        const cycle = this.cyclesSource(data);
+        if (cycle !== 0) {
+            this.goSource(cycle);
+            return;
+        }
+        if (matchesKey(data, "q") || this.matches("crtr.setup.cancel", data)) {
+            this.onCancel?.();
+            return;
+        }
+        if (this.zone === "rail") {
+            if (this.isDown(data))
+                this.goSource(1);
+            else if (this.isUp(data))
+                this.goSource(-1);
+            else if (this.isDescend(data))
+                this.enterList();
+            else if (matchesKey(data, "escape") || matchesKey(data, "left"))
+                this.onCancel?.();
+            else if (matchesKey(data, "a"))
+                this.openAdd();
+            else if (!this.triggerAction(data, undefined))
+                this.jumpToInitial(data);
+            return;
+        }
+        if (this.zone === "list") {
+            if (this.list.handleInput(data)) {
+                this.clearActionNotice();
+                this.syncDetail();
+                return;
+            }
+            if (this.isDown(data))
+                this.moveList(1);
+            else if (this.isUp(data))
+                this.moveList(-1);
+            else if (this.isDescend(data))
+                this.enterDetail();
+            else if (this.isAscend(data) || matchesKey(data, "escape"))
+                this.enterRail();
+            else
+                this.triggerAction(data, this.list.selected);
+            return;
+        }
+        // The dossier zone. Its own stack answers first — a row cursor and an open
+        // doc or command view — and only a key it does not use leaves for the list.
+        if (this.isDown(data))
+            this.detail.moveVertical(1);
+        else if (this.isUp(data))
+            this.detail.moveVertical(-1);
+        else if (matchesKey(data, "space") || this.matches("crtr.setup.toggle", data))
+            this.detail.toggleExpand();
+        else if (this.isDescend(data))
+            this.detail.open();
+        else if (this.isAscend(data)) {
+            if (!this.detail.collapseOrPop())
+                this.enterList();
+        }
+        else if (matchesKey(data, "escape")) {
+            if (!this.detail.escape())
+                this.enterList();
+        }
+        else
+            this.triggerAction(data, this.list.selected);
+    }
+    enterRail() {
+        this.zone = "rail";
+        this.clearActionNotice();
+    }
+    enterList() {
+        this.zone = "list";
+        this.clearActionNotice();
+        this.syncDetail();
+    }
+    enterDetail() {
+        if (this.list.selected === undefined && this.source.marketplace === undefined)
+            return;
+        this.zone = "detail";
+        this.clearActionNotice();
+        this.syncDetail();
+    }
+    jumpToInitial(data) {
+        if (data.length !== 1 || data.charCodeAt(0) < 32)
+            return;
+        const needle = data.toLowerCase();
+        const found = this.sources().findIndex((source, index) => index !== this.sourceIndex && source.label.toLowerCase().startsWith(needle));
+        if (found >= 0) {
+            this.sourceIndex = found;
+            this.syncSource();
+        }
+    }
+    // actions and modals
+    /** The focused rail row as an action subject. Carries the marketplace's scope
+     *  as well as its name: two marketplaces can share a name across the user and
+     *  project scopes, and without the scope `availableActions` cannot tell which
+     *  one a remove would destroy, so it offers nothing at all. */
+    marketplaceSubject() {
+        const marketplace = this.source.marketplace;
+        if (marketplace === undefined)
+            return {};
+        return { marketplace: marketplace.name, scope: marketplace.scope };
+    }
+    triggerAction(data, entry) {
+        const requests = availableActions(entry === undefined ? this.marketplaceSubject() : { entry });
+        const key = requests.find((request) => (request.kind === "install" && matchesKey(data, "i")) ||
+            ((request.kind === "enable" || request.kind === "disable") && matchesKey(data, "e")) ||
+            (request.kind === "remove" || request.kind === "market-remove" ? matchesKey(data, "x") : false) ||
+            (request.kind === "update" || request.kind === "market-update" ? matchesKey(data, "u") : false));
+        if (key === undefined)
+            return false;
+        const presentation = presentAction(key);
+        if (key.kind === "install" && this.catalog.installScopes.length > 1) {
+            this.modal = { kind: "scope", request: key, presentation, index: 0 };
+        }
+        else if (presentation.confirm) {
+            this.modal = { kind: "confirm", request: key, presentation };
+        }
+        else {
+            this.execute(key, presentation);
+        }
+        return true;
+    }
+    openAdd() {
+        const url = new Input();
+        const ref = new Input();
+        url.focused = true;
+        this.modal = { kind: "add", url, ref, field: "url" };
+    }
+    handleModal(data) {
+        const modal = this.modal;
+        if (modal === undefined)
+            return;
+        if (modal.kind === "scope") {
+            if (matchesKey(data, "escape"))
+                this.modal = undefined;
+            else if (matchesKey(data, "j") || matchesKey(data, "down"))
+                modal.index = Math.min(this.catalog.installScopes.length - 1, modal.index + 1);
+            else if (matchesKey(data, "k") || matchesKey(data, "up"))
+                modal.index = Math.max(0, modal.index - 1);
+            else if (matchesKey(data, "enter")) {
+                this.modal = undefined;
+                this.execute({ ...modal.request, scope: this.catalog.installScopes[modal.index] }, modal.presentation);
+            }
+        }
+        else if (modal.kind === "confirm") {
+            if (matchesKey(data, "y") || matchesKey(data, "enter")) {
+                this.modal = undefined;
+                this.execute(modal.request, modal.presentation);
+            }
+            else if (matchesKey(data, "n") || matchesKey(data, "escape"))
+                this.modal = undefined;
+        }
+        else {
+            if (matchesKey(data, "escape")) {
+                this.modal = undefined;
+            }
+            else if (matchesKey(data, "tab")) {
+                modal.field = modal.field === "url" ? "ref" : "url";
+                modal.url.focused = modal.field === "url";
+                modal.ref.focused = modal.field === "ref";
+            }
+            else if (matchesKey(data, "enter")) {
+                if (modal.field === "url") {
+                    modal.field = "ref";
+                    modal.url.focused = false;
+                    modal.ref.focused = true;
+                }
+                else
+                    this.submitAdd(modal);
+            }
+            else {
+                (modal.field === "url" ? modal.url : modal.ref).handleInput(data);
+            }
+        }
+    }
+    submitAdd(modal) {
+        const url = modal.url.getValue().trim();
+        if (url === "")
+            return;
+        const ref = modal.ref.getValue().trim();
+        this.modal = undefined;
+        const request = {
+            kind: "market-add",
+            url,
+            ...(ref === "" ? {} : { ref }),
+            scope: this.addScope(),
+        };
+        this.execute(request, presentAction(request));
+    }
+    /** Where `a` registers a marketplace. Named once so the modal can state
+     *  exactly what the action will do. */
+    addScope() {
+        return this.catalog.installScopes[0] ?? "user";
+    }
+    execute(request, presentation) {
+        // A marketplace's identity is its name AND its scope: one name can be
+        // registered in both, and a target resolved by name alone renders the
+        // project copy's outcome under the user copy's row.
+        const target = request.entry !== undefined
+            ? { kind: "plugin", key: request.entry.key }
+            : request.marketplace === undefined || request.scope === undefined
+                ? undefined
+                : { kind: "marketplace", sourceId: marketplaceSourceId(request.marketplace, request.scope) };
+        this.beginBusy(presentation.progress);
+        void runAction(request).then((outcome) => this.finishAction(target, outcome));
+    }
+    beginBusy(progress) {
+        const busy = {
+            progress,
+            frame: 0,
+            timer: setInterval(() => {
+                if (this.busy === undefined)
+                    return;
+                this.busy.frame = (this.busy.frame + 1) % 4;
+                this.tui.requestRender();
+            }, 125),
+        };
+        this.busy = busy;
+        this.tui.requestRender();
+    }
+    finishAction(target, outcome) {
+        if (this.busy !== undefined)
+            clearInterval(this.busy.timer);
+        this.busy = undefined;
+        this.notice = { text: outcome.message, ok: outcome.ok };
+        this.reload(target?.kind === "plugin" ? target.key : undefined);
+        this.syncDetail();
+        if (target?.kind === "plugin") {
+            const entry = this.sources().flatMap((source) => source.entries).find((candidate) => candidate.key === target.key);
+            this.detail.setPluginAction(entry, outcome);
+        }
+        else if (target?.kind === "marketplace") {
+            this.detail.setMarketplaceAction(target.sourceId, outcome);
+        }
+        this.tui.requestRender();
+    }
+    // rendering
+    /** The source rail. It scrolls like the list does: marketplace count is user
+     *  controlled, so a fixed slice would let the selection sit below the last
+     *  drawn row, moving invisibly while the badge the user is aiming for never
+     *  appears. Group headings scroll with their group. */
+    renderRail(width, height) {
+        const out = [];
+        let selectedLine = 0;
+        let marketplaceHeading = false;
+        for (const [index, source] of this.sources().entries()) {
+            if (source.kind === "installed") {
+                out.push(theme.fg("dim", " LIBRARY"));
+            }
+            else if (!marketplaceHeading) {
+                if (out.length > 0)
+                    out.push("");
+                out.push(theme.fg("dim", " MARKETPLACES"));
+                marketplaceHeading = true;
+            }
+            const badge = source.kind === "installed"
+                ? String(source.entries.length)
+                : `${source.marketplace?.installedCount ?? 0}/${source.marketplace?.pluginCount ?? source.entries.length}`;
+            const room = Math.max(1, width - visibleWidth(badge) - 3);
+            const label = padAnsi(truncateToWidth(source.label, room), room);
+            const body = ` ${label} ${badge}`;
+            if (index === this.sourceIndex)
+                selectedLine = out.length;
+            if (index === this.sourceIndex && this.zone === "rail")
+                out.push(theme.bg("selectedBg", padAnsi(body, width)));
+            else if (index === this.sourceIndex)
+                out.push(`${theme.fg("accent", "▌")}${padAnsi(theme.fg("accent", body.slice(1)), width - 1)}`);
+            else
+                out.push(padAnsi(` ${label} ${theme.fg("dim", badge)}`, width));
+        }
+        const range = visibleRange(out.length, selectedLine, height);
+        const window = out.slice(range.start, range.start + height);
+        while (window.length < height)
+            window.push("");
+        return window;
+    }
+    renderPanel(width, height, zone) {
+        if (this.modal !== undefined)
+            return this.renderModal(width, height);
+        if (zone === "detail")
+            return this.detail.render(width, height, true);
+        return this.list.render(width, height, zone === "list");
+    }
+    renderModal(width, height) {
+        const modal = this.modal;
+        if (modal === undefined)
+            return [];
+        let lines;
+        // No modal repeats its own keys: the footer is the single place this page
+        // names the currently-legal set, and it yields to an open modal.
+        if (modal.kind === "scope") {
+            lines = [theme.fg("accent", theme.bold("Install into")), "", ...this.catalog.installScopes.map((scope, index) => `${index === modal.index ? theme.fg("accent", "▶") : " "} ${scope}`)];
+        }
+        else if (modal.kind === "confirm") {
+            lines = [theme.fg("warning", theme.bold(modal.presentation.label)), "", ...this.wrapModal(modal.presentation.confirm ?? "Continue?", Math.max(1, width - 4))];
+        }
+        else {
+            const inputWidth = Math.max(1, width - 8);
+            // The scope is not offered as a choice here, so it is stated: a user who
+            // reads "Add marketplace" and gets a user-scope registration they never
+            // chose has been surprised by the page.
+            lines = [
+                theme.fg("accent", theme.bold("Add marketplace")),
+                theme.fg("dim", `Registers into ${this.addScope()} scope`),
+                "",
+                "Git URL",
+                modal.field === "url" ? modal.url.render(inputWidth)[0] ?? "" : modal.url.getValue(),
+                "",
+                "Ref (optional)",
+                modal.field === "ref" ? modal.ref.render(inputWidth)[0] ?? "" : modal.ref.getValue(),
+            ];
+        }
+        const framedLines = framed(lines, width);
+        while (framedLines.length < height)
+            framedLines.push("");
+        return framedLines.slice(0, height);
+    }
+    wrapModal(text, width) {
+        const words = text.trim().split(/\s+/);
+        const lines = [];
+        let line = "";
+        for (const word of words) {
+            const next = line === "" ? word : `${line} ${word}`;
+            if (visibleWidth(next) <= width)
+                line = next;
+            else {
+                if (line !== "")
+                    lines.push(line);
+                line = word;
+            }
+        }
+        if (line !== "")
+            lines.push(line);
+        return lines;
+    }
+    footer(width) {
+        if (this.busy !== undefined) {
+            const frame = ["◐", "◓", "◑", "◒"][this.busy.frame];
+            return theme.fg("warning", `${frame} ${this.busy.progress}`);
+        }
+        // A modal outranks a lingering notice: while one is open its keys are the
+        // only legal ones, and the last action's success line must not sit under a
+        // destructive confirm telling the user nothing about how to answer it.
+        if (this.modal?.kind === "scope")
+            return theme.fg("dim", "↑↓/jk choose · enter install · esc cancel");
+        if (this.modal?.kind === "confirm")
+            return theme.fg("dim", "y/enter confirm · n/esc cancel");
+        if (this.modal?.kind === "add")
+            return theme.fg("dim", "tab field · enter next/add · esc cancel");
+        // The open filter owns every key, `q` and `tab` included — naming them here
+        // would teach a shortcut that types a literal character into the filter.
+        if (this.list.ownsKeyboard)
+            return theme.fg("dim", "type to filter · enter keep · esc clear");
+        if (this.notice !== undefined)
+            return theme.fg(this.notice.ok ? "success" : "warning", this.notice.text);
+        const actionHints = this.availableActionHints();
+        const zone = this.zone;
+        const move = formatMovePair(this.bindings, "crtr.setup.list-down", "crtr.setup.list-up");
+        const open = this.label("crtr.setup.advance", "enter");
+        // Navigation is the half that must survive: a user who cannot read `q close`
+        // is stuck, while one who cannot read `x remove` has merely lost a shortcut.
+        // So the left side sheds its optional pieces — the letter-jump aside first,
+        // then the action hints — before anything truncates.
+        const navigation = zone === "rail"
+            ? `${move} source · a add`
+            : zone === "list"
+                ? `${move} row · / filter · ${open} dossier`
+                : this.detail.viewing
+                    ? `${move} scroll · esc back`
+                    : `${move} row · space expand · ${open} open · esc list`;
+        const aside = zone === "rail" ? "type a letter to jump" : "";
+        const right = `${this.label("crtr.setup.tab-next", "tab")} source · ${this.label("crtr.setup.cancel", "q")} close`;
+        const candidates = [
+            [navigation, actionHints, aside],
+            [navigation, actionHints],
+            [navigation],
+        ].map((parts) => parts.filter((part) => part !== "").join(" · "));
+        for (const left of candidates) {
+            const gap = width - visibleWidth(left) - visibleWidth(right);
+            if (gap >= 2)
+                return `${theme.fg("dim", left)}${" ".repeat(gap)}${theme.fg("dim", right)}`;
+        }
+        return theme.fg("dim", truncateToWidth(`${navigation} · ${this.label("crtr.setup.cancel", "q")} close`, width));
+    }
+    /** The footer names KEYS, not actions. An absent plugin offers a user-scope
+     *  and a project-scope install — two actions behind one `i`, which the scope
+     *  modal then chooses between — so the hints are deduped before joining. */
+    availableActionHints() {
+        const entry = this.zone === "rail" ? undefined : this.list.selected;
+        const hints = availableActions(entry === undefined ? this.marketplaceSubject() : { entry })
+            .map((request) => {
+            switch (request.kind) {
+                case "install": return "i install";
+                case "enable": return "e enable";
+                case "disable": return "e disable";
+                case "remove": return "x remove";
+                case "update": return "u update";
+                case "market-add": return "a add";
+                case "market-remove": return "x remove";
+                case "market-update": return "u update";
+            }
+        });
+        return [...new Set(hints)].join(" · ");
+    }
+    render(width) {
+        const height = this.terminalRows();
+        const bodyHeight = Math.max(1, height - PAGE_CHROME_ROWS);
+        const railVisible = width >= RAIL_MIN_TOTAL_WIDTH;
+        const threeColumns = width >= THREE_COLUMN_MIN_WIDTH;
+        let body;
+        if (threeColumns) {
+            const detailWidth = Math.max(1, width - RAIL_WIDTH - LIST_WIDTH - 6);
+            const middle = columns(this.list.render(LIST_WIDTH, bodyHeight, this.zone === "list"), LIST_WIDTH, this.modal === undefined ? this.detail.render(detailWidth, bodyHeight, this.zone === "detail") : this.renderModal(detailWidth, bodyHeight), detailWidth);
+            body = columns(this.renderRail(RAIL_WIDTH, bodyHeight), RAIL_WIDTH, middle, width - RAIL_WIDTH - 3);
+        }
+        else if (railVisible) {
+            const panelWidth = width - RAIL_WIDTH - 3;
+            const panelZone = this.zone === "detail" ? "detail" : "list";
+            body = columns(this.renderRail(RAIL_WIDTH, bodyHeight), RAIL_WIDTH, this.renderPanel(panelWidth, bodyHeight, panelZone), panelWidth);
+        }
+        else if (this.modal !== undefined) {
+            body = this.renderModal(width, bodyHeight);
+        }
+        else if (this.zone === "rail") {
+            // At 80 columns the rail costs more than it explains beside the list, so
+            // it becomes the whole panel when focused rather than disappearing: `a`,
+            // `u` and `x` are rail keys, and a hidden rail put every marketplace
+            // action out of reach at the narrowest supported width.
+            body = this.renderRail(width, bodyHeight);
+        }
+        else {
+            body = this.renderPanel(width, bodyHeight, this.zone === "detail" ? "detail" : "list");
+        }
+        const meta = railVisible
+            ? `${plural(this.sources().filter((source) => source.kind === "marketplace").length, "marketplace", "marketplaces")} · ${plural(this.sources().reduce((count, source) => count + source.entries.length, 0), "plugin", "plugins")}`
+            : `${this.source.label} · ${this.sourceIndex + 1}/${this.sources().length}`;
+        return pageFrame({ width, height, title: "crouter plugins", meta, body, footer: this.footer(width) });
+    }
+}
+export async function runPkgBrowse() {
+    if (!process.stdout.isTTY) {
+        process.stdout.write("crtr pkg browse needs a TTY. Run it in a terminal, or use `crtr pkg market browse` and `crtr pkg plugin list` for scriptable access.\n");
+        return;
+    }
+    await runTuiPage(({ tui, terminal, bindings }, control) => {
+        const shell = new PkgBrowseShell(tui, () => terminal.rows, bindings);
+        shell.onCancel = control.cancel;
+        return shell;
+    });
+}

package/dist/commands/pkg/browse.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const pkgBrowseLeaf: LeafDef;

package/dist/commands/pkg/browse.js

@@ -0,0 +1,27 @@
+// The `crtr pkg browse` leaf DEFINITION only. The shell itself lives in
+// browse/shell.ts and is loaded on demand, because it pulls pi's model runtime
+// and TUI components — an expensive module graph. Registering the `pkg`
+// subtree (every `crtr pkg …` invocation, and root `-h`, which builds the full
+// tree) needs the help metadata below and nothing else, so the shell must NOT
+// be reachable by a static import from here.
+import { defineLeaf } from '../../core/command.js';
+export const pkgBrowseLeaf = defineLeaf({
+    name: 'browse',
+    description: 'open the interactive plugin browser',
+    whenToUse: 'the user wants to browse registered marketplaces and inspect or manage plugins interactively. Agents should use pkg market browse or pkg plugin list, which are scriptable.',
+    help: {
+        name: 'pkg browse',
+        summary: 'open the interactive plugin browser',
+        inputNote: 'No input parameters.',
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Opens a pi-tui page for browsing registered marketplaces, inspecting plugin capability surfaces, and managing plugins.',
+            'Requires a TTY. Without one it prints a pointer to pkg market browse and pkg plugin list and exits.',
+        ],
+    },
+    run: async () => {
+        await (await import('./browse/shell.js')).runPkgBrowse();
+    },
+    render: () => '',
+});

package/dist/commands/pkg/market-inspect.d.ts

@@ -0,0 +1,2 @@
+export declare const marketList: import("../../core/command.js").LeafDef;
+export declare const marketBrowse: import("../../core/command.js").LeafDef;