@north-light/api 0.3.580 → 0.3.587

package/dist/commands/pkg/browse/detail-panel.d.ts

@@ -0,0 +1,66 @@
+import type { ActionOutcome, CatalogSource, PluginCapability, PluginEntry } from './model.js';
+export declare class PkgDetailPanel {
+    private entry;
+    private source;
+    private capability;
+    private pluginAction;
+    private marketplaceAction;
+    /** Page-level catalog problems. The list's notice shows the first; this is
+     *  where the rest stay readable. */
+    private warnings;
+    private scroll;
+    /** Extra scrolling the user asked for past the last selectable row, so the
+     *  inert tail of the overview stays reachable. Reset whenever the cursor
+     *  moves or the view changes. */
+    private tailScroll;
+    private cursor;
+    private view;
+    /** Command branches the user has folded shut, by command path. Branches are
+     *  open by default: the explorer's whole point is that nothing is hidden. */
+    private collapsed;
+    /** Last render's geometry, so scrolling can clamp against real content
+     *  instead of running a counter nobody can see. */
+    private lastLines;
+    private lastHeight;
+    /** Where the cursor's row sits in the last built overview, in line numbers. */
+    private cursorRange;
+    setEntry(entry: PluginEntry | undefined, source: CatalogSource | undefined, capability: PluginCapability | null | undefined): void;
+    setPluginAction(entry: PluginEntry | undefined, outcome: ActionOutcome): void;
+    setMarketplaceAction(sourceId: string | undefined, outcome: ActionOutcome): void;
+    setWarnings(warnings: string[]): void;
+    /** True while an opened doc or command owns the pane, so the shell's footer
+     *  can teach `esc back` instead of `esc list`. */
+    get viewing(): boolean;
+    /** `j`/`k`: move the cursor between selectable rows on the overview, scroll a
+     *  line inside an opened view — and scroll the overview too when the plugin
+     *  has nothing selectable to move between. */
+    moveVertical(delta: number): void;
+    /** `space`: fold the focused command branch shut, or open it again. */
+    toggleExpand(): boolean;
+    /** `enter`/`l`: open the focused doc or command as its own view. */
+    open(): boolean;
+    /** `h`/`left`: pop an open view, else fold the focused branch. False means
+     *  the key was not used here and the shell should leave for the list. */
+    collapseOrPop(): boolean;
+    /** `esc`: pop an open view. False at the root, where the shell leaves. */
+    escape(): boolean;
+    private popView;
+    private toggleExpandShut;
+    /** Command rows in display order, skipping the children of folded branches. */
+    private commandRows;
+    /** Every row the cursor can land on, in the order the overview renders them.
+     *  The renderer walks the same two lists, so index N here is row N there. */
+    private targets;
+    render(width: number, height: number, focused: boolean): string[];
+    private lines;
+    private overviewLines;
+    private commandRowLines;
+    private status;
+    private transportLine;
+    private fromLines;
+    /** The dossier for a source rather than a plugin: what a marketplace is and
+     *  where it came from, or the library's own shape — plus every catalog
+     *  problem, which is page-level and has no other home with room for it. */
+    private sourceLines;
+    private size;
+}

package/dist/commands/pkg/browse/detail-panel.js

@@ -0,0 +1,402 @@
+// The right-hand dossier, and the explorer rooted in it.
+//
+// The dossier is a view stack: an overview of what the plugin adds, and — one
+// `enter` deeper — a whole memory doc or a whole command contract. The overview
+// is not a teaser: every command node and every memory doc it lists is a real
+// row a cursor can land on and open, and nothing is elided with `+N more`.
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { padAnsi, theme, wrapText } from '../../../core/tui/panel.js';
+import { renderCommandView } from './command-view.js';
+import { renderDocView } from './doc-view.js';
+import { commandLabel, displayVersion, plural } from './model.js';
+/** One labelled row and its explanation. Inline while both fit; otherwise the
+ *  explanation wraps underneath, hanging under the label rather than resetting
+ *  to the left margin. Nothing is ever truncated to make it fit. */
+function entryLines(indent, label, explanation, width, hangingIndent) {
+    const styled = `${indent}${theme.fg("accent", label)}`;
+    if (explanation === undefined || explanation.trim() === "")
+        return [styled];
+    const inline = `${indent}${label} — ${explanation}`;
+    if (visibleWidth(inline) <= width)
+        return [`${styled}${theme.fg("dim", ` — ${explanation}`)}`];
+    // The hanging indent is blank space, never a re-print of the prefix: an
+    // indent carrying a branch's ▾ would stamp that glyph down every wrapped
+    // line of its description, as though each were another branch.
+    const hanging = hangingIndent ?? " ".repeat(visibleWidth(indent) + 2);
+    return [
+        styled,
+        ...wrapText(explanation, Math.max(1, width - hanging.length)).map((line) => `${hanging}${theme.fg("dim", line)}`),
+    ];
+}
+/** `wrapText` trims, so wrapping an already-indented string silently loses its
+ *  indent on every line. Wrap the text, then indent each line. */
+function indented(indent, text, width, hangingIndent = indent) {
+    return wrapText(text, Math.max(1, width - indent.length)).map((line, index) => `${index === 0 ? indent : hangingIndent}${line}`);
+}
+export class PkgDetailPanel {
+    entry;
+    source;
+    capability;
+    pluginAction;
+    marketplaceAction;
+    /** Page-level catalog problems. The list's notice shows the first; this is
+     *  where the rest stay readable. */
+    warnings = [];
+    scroll = 0;
+    /** Extra scrolling the user asked for past the last selectable row, so the
+     *  inert tail of the overview stays reachable. Reset whenever the cursor
+     *  moves or the view changes. */
+    tailScroll = 0;
+    cursor = 0;
+    view = { kind: "overview" };
+    /** Command branches the user has folded shut, by command path. Branches are
+     *  open by default: the explorer's whole point is that nothing is hidden. */
+    collapsed = new Set();
+    /** Last render's geometry, so scrolling can clamp against real content
+     *  instead of running a counter nobody can see. */
+    lastLines = 0;
+    lastHeight = 1;
+    /** Where the cursor's row sits in the last built overview, in line numbers. */
+    cursorRange;
+    setEntry(entry, source, capability) {
+        const changedEntry = this.entry?.key !== entry?.key;
+        if (changedEntry || this.source?.id !== source?.id) {
+            this.scroll = 0;
+            this.tailScroll = 0;
+        }
+        if (changedEntry) {
+            this.pluginAction = undefined;
+            this.view = { kind: "overview" };
+            this.cursor = 0;
+            this.collapsed.clear();
+        }
+        if (this.source?.id !== source?.id)
+            this.marketplaceAction = undefined;
+        this.entry = entry;
+        this.source = source;
+        this.capability = capability;
+    }
+    setPluginAction(entry, outcome) {
+        this.pluginAction = entry === undefined ? undefined : { key: entry.key, outcome };
+    }
+    setMarketplaceAction(sourceId, outcome) {
+        this.marketplaceAction = sourceId === undefined ? undefined : { sourceId, outcome };
+    }
+    setWarnings(warnings) {
+        this.warnings = warnings;
+    }
+    /** True while an opened doc or command owns the pane, so the shell's footer
+     *  can teach `esc back` instead of `esc list`. */
+    get viewing() {
+        return this.view.kind !== "overview";
+    }
+    // navigation
+    /** `j`/`k`: move the cursor between selectable rows on the overview, scroll a
+     *  line inside an opened view — and scroll the overview too when the plugin
+     *  has nothing selectable to move between. */
+    moveVertical(delta) {
+        const targets = this.targets();
+        if (this.view.kind !== "overview" || targets.length === 0) {
+            this.scroll = Math.max(0, Math.min(this.scroll + delta, Math.max(0, this.lastLines - this.lastHeight)));
+            return;
+        }
+        const next = Math.max(0, Math.min(targets.length - 1, this.cursor + delta));
+        if (next !== this.cursor) {
+            this.cursor = next;
+            this.tailScroll = 0;
+            return;
+        }
+        // The cursor is already on the last row, but ON DISK and FROM sit below it
+        // as inert text. Keep scrolling so a plugin with 78 memory docs does not
+        // bury its own install path where nothing can reach it.
+        this.tailScroll = Math.max(0, this.tailScroll + delta);
+    }
+    /** `space`: fold the focused command branch shut, or open it again. */
+    toggleExpand() {
+        const target = this.targets()[this.cursor];
+        if (this.view.kind !== "overview" || target?.kind !== "command")
+            return false;
+        if (target.node.children.length === 0)
+            return false;
+        const key = target.node.path.join(" ");
+        if (this.collapsed.has(key))
+            this.collapsed.delete(key);
+        else {
+            this.collapsed.add(key);
+            // Folding removes rows below the cursor; the cursor itself stays on the
+            // branch it just folded, which is still row `this.cursor`.
+        }
+        return true;
+    }
+    /** `enter`/`l`: open the focused doc or command as its own view. */
+    open() {
+        if (this.view.kind !== "overview")
+            return false;
+        const target = this.targets()[this.cursor];
+        if (target === undefined)
+            return false;
+        this.view = target.kind === "command"
+            ? { kind: "command", node: target.node }
+            : { kind: "doc", doc: target.doc };
+        this.scroll = 0;
+        return true;
+    }
+    /** `h`/`left`: pop an open view, else fold the focused branch. False means
+     *  the key was not used here and the shell should leave for the list. */
+    collapseOrPop() {
+        if (this.view.kind !== "overview")
+            return this.popView();
+        return this.toggleExpandShut();
+    }
+    /** `esc`: pop an open view. False at the root, where the shell leaves. */
+    escape() {
+        return this.popView();
+    }
+    popView() {
+        if (this.view.kind === "overview")
+            return false;
+        this.view = { kind: "overview" };
+        this.scroll = 0;
+        this.tailScroll = 0;
+        return true;
+    }
+    toggleExpandShut() {
+        const target = this.targets()[this.cursor];
+        if (target?.kind !== "command" || target.node.children.length === 0)
+            return false;
+        const key = target.node.path.join(" ");
+        if (this.collapsed.has(key))
+            return false;
+        this.collapsed.add(key);
+        return true;
+    }
+    // the selectable model
+    /** Command rows in display order, skipping the children of folded branches. */
+    commandRows() {
+        const rows = [];
+        const walk = (nodes, depth) => {
+            for (const node of nodes) {
+                rows.push({ node, depth });
+                if (node.children.length > 0 && !this.collapsed.has(node.path.join(" ")))
+                    walk(node.children, depth + 1);
+            }
+        };
+        walk(this.capability?.commands ?? [], 0);
+        return rows;
+    }
+    /** Every row the cursor can land on, in the order the overview renders them.
+     *  The renderer walks the same two lists, so index N here is row N there. */
+    targets() {
+        const capability = this.capability;
+        if (capability === undefined || capability === null)
+            return [];
+        return [
+            ...this.commandRows().map((row) => ({ kind: "command", node: row.node })),
+            ...capability.docs.map((doc) => ({ kind: "doc", doc })),
+        ];
+    }
+    // rendering
+    render(width, height, focused) {
+        const lines = this.lines(width, focused);
+        this.lastLines = lines.length;
+        this.lastHeight = height;
+        let start = 0;
+        if (focused) {
+            const range = this.view.kind === "overview" ? this.cursorRange : undefined;
+            let cursorScroll;
+            if (range !== undefined) {
+                if (range.start < this.scroll)
+                    this.scroll = range.start;
+                if (range.start + range.count > this.scroll + height)
+                    this.scroll = range.start + range.count - height;
+                cursorScroll = this.scroll;
+                this.scroll += this.tailScroll;
+            }
+            // Clamping here is what keeps the last reachable position a full pane
+            // rather than one line of text above an empty one.
+            this.scroll = Math.max(0, Math.min(this.scroll, Math.max(0, lines.length - height)));
+            // Bank only the tail scrolling that actually landed, so one `k` walks
+            // back up instead of unwinding every keypress the clamp swallowed.
+            if (cursorScroll !== undefined)
+                this.tailScroll = Math.max(0, this.scroll - cursorScroll);
+            start = this.scroll;
+        }
+        const window = lines.slice(start, start + height).map((line) => truncateToWidth(line, width));
+        // Pad to the full height so the divider drawn beside this column runs the
+        // whole page rather than stopping where the dossier's text runs out.
+        while (window.length < height)
+            window.push("");
+        return window;
+    }
+    lines(width, focused) {
+        const entry = this.entry;
+        if (entry === undefined)
+            return this.sourceLines(this.source, width);
+        if (this.view.kind === "doc")
+            return renderDocView(this.view.doc, width);
+        if (this.view.kind === "command" && this.capability !== undefined && this.capability !== null)
+            return renderCommandView(this.view.node, this.capability, width);
+        return this.overviewLines(entry, width, focused);
+    }
+    overviewLines(entry, width, focused) {
+        const out = [];
+        const ranges = [];
+        const push = (lines, selectable = false) => {
+            if (selectable)
+                ranges.push({ start: out.length, count: lines.length });
+            out.push(...lines);
+        };
+        const version = displayVersion(entry) ?? "";
+        const identity = theme.fg("accent", theme.bold(entry.name));
+        const gap = width - visibleWidth(identity) - visibleWidth(version);
+        push([gap >= 2 ? `${identity}${" ".repeat(gap)}${theme.fg("dim", version)}` : identity]);
+        push([this.status(entry)]);
+        if (entry.description) {
+            push([""]);
+            push(wrapText(entry.description, width));
+        }
+        const capability = this.capability;
+        if (capability === undefined) {
+            push(["", theme.fg("dim", "ADDS TO CRTR"), theme.fg("dim", " Reading capability surface…")]);
+        }
+        else if (capability === null) {
+            push(["", theme.fg("warning", "Capability details are unavailable — plugin files are not on disk.")]);
+        }
+        else {
+            push(["", theme.fg("dim", "ADDS TO CRTR")]);
+            const transport = this.transportLine(capability);
+            if (transport !== undefined)
+                push([transport]);
+            push([
+                ` ${plural(this.commandRows().length, "command", "commands")} · ${plural(capability.docs.length, "document", "documents")}`,
+            ].map((line) => theme.fg("dim", line)));
+            const commandRows = this.commandRows();
+            if (commandRows.length > 0 || capability.commandIssues.length > 0) {
+                push(["", theme.fg("dim", "COMMANDS")]);
+                for (const row of commandRows)
+                    push(this.commandRowLines(row, width), true);
+                for (const issue of capability.commandIssues)
+                    push(indented(" ! ", `${issue.message}${issue.next ? ` — ${issue.next}` : ""}`, width, "   ").map((line) => theme.fg("warning", line)));
+            }
+            if (capability.docs.length > 0) {
+                push(["", theme.fg("dim", "DOCUMENTS")]);
+                for (const doc of capability.docs)
+                    // Correction 2: the description beside a doc is its short form —
+                    // what the doc SAYS. Its routing line is agent read-routing and
+                    // lives under the doc view's own heading, never here.
+                    push(entryLines("   ", doc.name, doc.shortForm, width), true);
+            }
+            if (entry.install.kind === "installed" && capability.sizeBytes !== undefined) {
+                push(["", theme.fg("dim", "ON DISK")]);
+                push([` ${theme.fg("accent", entry.install.path)}${theme.fg("dim", ` · ${this.size(capability.sizeBytes)}`)}`]);
+            }
+        }
+        push(this.fromLines(entry, width));
+        if (this.pluginAction?.key === entry.key && this.pluginAction.outcome.detail?.length) {
+            push(["", theme.fg("dim", "LAST ACTION")]);
+            for (const line of this.pluginAction.outcome.detail)
+                push(indented(" ", line, width));
+        }
+        this.cursor = ranges.length === 0 ? 0 : Math.min(this.cursor, ranges.length - 1);
+        this.cursorRange = ranges[this.cursor];
+        const range = this.cursorRange;
+        if (focused && range !== undefined)
+            for (let line = range.start; line < range.start + range.count; line += 1)
+                out[line] = theme.bg("selectedBg", padAnsi(out[line] ?? "", width));
+        return out;
+    }
+    commandRowLines(row, width) {
+        const indent = `   ${"  ".repeat(row.depth)}`;
+        const glyph = row.node.children.length === 0
+            ? "  "
+            : this.collapsed.has(row.node.path.join(" "))
+                ? `${theme.fg("dim", "▸")} `
+                : `${theme.fg("dim", "▾")} `;
+        const prefix = `${indent}${glyph}`;
+        // A leaf indents its wrapped description under its label, as a memory doc
+        // does. A branch cannot: that column is where its own children's labels
+        // start, so its description would read as one more subcommand. It hangs
+        // flush with the label instead, where only the glyph column sits.
+        const hanging = row.node.children.length === 0 ? undefined : " ".repeat(visibleWidth(prefix));
+        return entryLines(prefix, commandLabel(row.node), row.node.description, width, hanging);
+    }
+    status(entry) {
+        if (entry.install.kind === "absent")
+            return theme.fg("dim", "Not installed");
+        if (entry.install.scope === "builtin")
+            return `${theme.fg("muted", "Builtin")} · ships with crtr`;
+        // Enablement survives an update offer: a disabled plugin that happens to
+        // have a newer version is still disabled, and the status line is the one
+        // place that fact is spelled out.
+        const enablement = entry.install.enabled ? theme.fg("success", "enabled") : theme.fg("dim", "disabled");
+        if (entry.install.updateAvailable)
+            return `${theme.fg("warning", `Update available · ${entry.install.version ?? "?"} → ${entry.version ?? "?"}`)} · ${enablement}`;
+        return `Installed · ${entry.install.scope} · ${enablement}`;
+    }
+    transportLine(capability) {
+        if (capability.transport === null)
+            return undefined;
+        const target = capability.transportTarget === undefined ? "" : ` · ${capability.transportTarget}`;
+        return capability.transport === "http"
+            ? ` ${theme.fg("accent", "Transport")}  http${theme.fg("warning", target)}`
+            : ` ${theme.fg("accent", "Transport")}  exec${theme.fg("dim", target)}`;
+    }
+    fromLines(entry, width) {
+        if (!entry.marketplace && !entry.source && !entry.owner)
+            return [];
+        const out = ["", theme.fg("dim", "FROM")];
+        if (entry.marketplace) {
+            const revision = this.source?.marketplace?.revision;
+            // A short revision: this line says which clone the plugin came from, and
+            // a 40-character object name buys nothing a human reads here.
+            out.push(` ${theme.fg("accent", entry.marketplace)}${revision ? theme.fg("dim", ` @ ${revision.slice(0, 12)}`) : ""}`);
+        }
+        if (entry.source)
+            out.push(...indented(" ", entry.source, width));
+        if (entry.owner?.name || entry.owner?.email)
+            out.push(theme.fg("dim", ` owner · ${entry.owner.name ?? entry.owner.email}`));
+        return out;
+    }
+    /** The dossier for a source rather than a plugin: what a marketplace is and
+     *  where it came from, or the library's own shape — plus every catalog
+     *  problem, which is page-level and has no other home with room for it. */
+    sourceLines(source, width) {
+        const marketplace = source?.marketplace;
+        const out = [];
+        if (marketplace === undefined) {
+            out.push(theme.fg("accent", theme.bold(source?.label ?? "Library")));
+            out.push(theme.fg("dim", "Choose a marketplace or plugin to inspect it."));
+        }
+        else {
+            out.push(theme.fg("accent", theme.bold(marketplace.name)));
+            out.push(`Installed ${marketplace.installedCount}/${marketplace.pluginCount} plugins${theme.fg("dim", ` · ${plural(marketplace.updatableCount, "update", "updates")}`)}`);
+            out.push("", theme.fg("dim", "MARKETPLACE"));
+            out.push(` ${theme.fg("accent", marketplace.scope)} scope · ${marketplace.ref}`);
+            out.push(...indented(" ", marketplace.url, width));
+            out.push(` ${theme.fg("accent", marketplace.path)}`);
+            if (marketplace.revision)
+                out.push(` revision · ${marketplace.revision}${marketplace.revisionDate ? ` · ${marketplace.revisionDate}` : ""}`);
+            if (marketplace.owner?.name || marketplace.owner?.email)
+                out.push(` owner · ${marketplace.owner.name ?? marketplace.owner.email}`);
+        }
+        if (this.warnings.length > 0) {
+            out.push("", theme.fg("dim", "PROBLEMS"));
+            for (const warning of this.warnings)
+                out.push(...indented(" ", warning, width).map((line) => theme.fg("warning", line)));
+        }
+        const action = this.marketplaceAction;
+        if (action !== undefined && action.sourceId === source?.id && action.outcome.detail?.length) {
+            out.push("", theme.fg("dim", "LAST ACTION"));
+            for (const line of action.outcome.detail)
+                out.push(...indented(" ", line, width));
+        }
+        return out;
+    }
+    size(bytes) {
+        if (bytes < 1024)
+            return `${bytes} B`;
+        if (bytes < 1024 * 1024)
+            return `${Math.round(bytes / 1024)} KB`;
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    }
+}

package/dist/commands/pkg/browse/doc-view.d.ts

@@ -0,0 +1,3 @@
+import type { DocDetail } from './model.js';
+/** Every line of one memory doc's reader view, wrapped to `width`. */
+export declare function renderDocView(doc: DocDetail, width: number): string[];

package/dist/commands/pkg/browse/doc-view.js

@@ -0,0 +1,84 @@
+// The plugin browser's memory-doc reader: one doc rendered whole, for a human
+// deciding whether the agent reading it will do the right thing.
+//
+// Pure rendering. It receives a doc already read from disk and returns styled
+// lines already wrapped to `width`; the dossier owns scrolling and never
+// truncates what comes back.
+import { getMarkdownTheme } from '@earendil-works/pi-coding-agent';
+import { Markdown, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { theme, wrapText } from '../../../core/tui/panel.js';
+/** Every line of one memory doc's reader view, wrapped to `width`. */
+export function renderDocView(doc, width) {
+    const out = [];
+    const viewWidth = Math.max(1, width);
+    out.push(...wrapped(doc.name, viewWidth).map((line) => theme.fg("accent", theme.bold(line))));
+    out.push(theme.fg("dim", doc.kind));
+    if (doc.shortForm) {
+        out.push("");
+        out.push(...paragraph(doc.shortForm, viewWidth));
+    }
+    out.push("", theme.fg("dim", "READ WHEN"));
+    out.push(...paragraph(doc.routingLine || "Not declared.", viewWidth));
+    // One row per rule answers "will an agent ever see this?"; a doc with none
+    // is reachable through listings and explicit reads only.
+    out.push("", theme.fg("dim", "ROUTING"));
+    if (doc.rules.length === 0) {
+        out.push(...paragraph("No rules — reachable through directory listings and explicit reads only.", viewWidth));
+    }
+    for (const rule of doc.rules) {
+        const parts = [`deliver ${rule.deliver}`];
+        if (rule.match?.length)
+            parts.push(rule.match.join(", "));
+        if (rule.matchFrontmatter !== undefined)
+            parts.push(JSON.stringify(rule.matchFrontmatter));
+        if (rule.if !== undefined)
+            parts.push(`if ${JSON.stringify(rule.if)}`);
+        out.push(...field(rule.on, parts.join("  "), viewWidth));
+    }
+    if (doc.unlisted)
+        out.push(...field("unlisted", "suppressed from directory listings", viewWidth));
+    if (doc.rationale) {
+        out.push("", theme.fg("dim", "RATIONALE"));
+        out.push(...paragraph(doc.rationale, viewWidth));
+    }
+    out.push("", theme.fg("dim", "ON DISK"));
+    out.push(...field("path", doc.path, viewWidth));
+    out.push(...field("size", size(doc.sizeBytes), viewWidth));
+    out.push("", theme.fg("dim", "BODY"), "");
+    out.push(...new Markdown(doc.body, 0, 0, getMarkdownTheme()).render(viewWidth));
+    return out;
+}
+/** A prose block gets a quiet, stable left edge instead of reflowing raggedly
+ * against a section title. */
+function paragraph(text, width) {
+    const indent = "  ";
+    return wrapped(text, Math.max(1, width - indent.length)).map((line) => `${indent}${theme.fg("dim", line)}`);
+}
+/** A field's later rows line up under its value, not under its label. */
+function field(label, value, width) {
+    const prefix = `  ${label}  `;
+    const indent = " ".repeat(visibleWidth(prefix));
+    const valueWidth = Math.max(1, width - visibleWidth(prefix));
+    return wrapped(value, valueWidth).map((line, index) => index === 0
+        ? `${theme.fg("accent", prefix)}${theme.fg("dim", line)}`
+        : `${indent}${theme.fg("dim", line)}`);
+}
+/** `wrapText` is the page's ordinary prose wrapper. Its word-oriented contract
+ * deliberately leaves a filesystem path or compact JSON predicate intact, so
+ * use pi-tui's character-safe wrapper only for those over-wide tokens instead
+ * of turning a full value into an ellipsis. */
+function wrapped(text, width) {
+    const clean = text.trim();
+    return clean.split(/\s+/).some((word) => visibleWidth(word) > width)
+        ? wrapTextWithAnsi(clean, width)
+        : wrapText(clean, width);
+}
+function size(bytes) {
+    if (bytes === undefined)
+        return "unknown";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/dist/commands/pkg/browse/list-panel.d.ts

@@ -0,0 +1,28 @@
+import type { CatalogSource, PluginEntry } from './model.js';
+/** The middle column of the plugin browser. It owns filtering and row position;
+ * the shell owns horizontal navigation and actions. */
+export declare class PkgListPanel {
+    private readonly onChange;
+    private source;
+    private index;
+    private filter;
+    private filtering;
+    private notice;
+    private hasMarketplaces;
+    constructor(onChange: () => void);
+    get selected(): PluginEntry | undefined;
+    get ownsKeyboard(): boolean;
+    setSource(source: CatalogSource, selectedKey?: string): void;
+    setEmptyState(hasMarketplaces: boolean): void;
+    move(delta: number): void;
+    /** Returns true only when a live filter consumed the input. */
+    handleInput(data: string): boolean;
+    setNotice(notice: string | undefined): void;
+    private entries;
+    render(width: number, height: number, focused: boolean): string[];
+    /** Pad rather than trim: this column sets the length of the divider drawn
+     *  beside it, and a divider that stops where the content runs out makes the
+     *  page look half-drawn. */
+    private fit;
+    private stateGlyph;
+}