magus-cli 0.0.0-placeholder → 7.0.0

package/src/ui/renderers/pluginRenderers.tsx

@@ -0,0 +1,1089 @@
+import type React from "react";
+import { getMarketplaceVersion } from "../../services/marketplace-fetcher.js";
+import {
+	compareVersions,
+	isEnabledButNotInstalled,
+	isInstalledInScope,
+} from "../../services/plugin-manager.js";
+import type { ScopeStatus } from "../../services/plugin-manager.js";
+import type { PluginComponentKind } from "../../services/skills-manager.js";
+import type {
+	PluginUpdateAction,
+	PluginUpdateItem,
+} from "../../services/update-plan.js";
+import { isKnownVersion } from "../../services/version-snapshot.js";
+import type { PluginRelease } from "../../types/index.js";
+import { highlightMatches } from "../../utils/fuzzy-search.js";
+import type {
+	PluginBrowserItem,
+	PluginCategoryItem,
+	PluginComponentItem,
+	PluginContentsStatusItem,
+	PluginPluginItem,
+} from "../adapters/pluginsAdapter.js";
+import { CategoryHeader } from "../components/CategoryHeader.js";
+import {
+	ActionHints,
+	DetailSection,
+	KeyValueLine,
+	MetaText,
+	ScopeSquares,
+	SelectableRow,
+} from "../components/primitives/index.js";
+import type {
+	PluginContentsEntry,
+	PluginSkillDetailEntry,
+} from "../state/types.js";
+import { componentBadge as badgeColors } from "../theme-mode.js";
+import { type UiColor, theme } from "../theme.js";
+import { renderMarkdown } from "./markdownRenderer.js";
+import { type PluginRowSegment, pluginRowText } from "./pluginRowText.js";
+import { type StatusTone, pluginStatusText } from "./pluginStatusText.js";
+
+// ─── Category renderers ───────────────────────────────────────────────────────
+
+function categoryRow(
+	item: PluginCategoryItem,
+	isSelected: boolean,
+): React.ReactNode {
+	const mp = item.marketplace;
+	// Marketplaces that declare a `metadata.version` render "Name v8.0.0 (15)";
+	// those without keep the plain "Name (15)" form.
+	const version = getMarketplaceVersion(mp.name);
+
+	if (isSelected) {
+		const arrow = item.isExpanded ? "▼" : "▶";
+		const versionLabel = version ? ` v${version}` : "";
+		const count = item.pluginCount > 0 ? ` (${item.pluginCount})` : "";
+		return (
+			<SelectableRow selected={true}>
+				<strong>
+					{" "}
+					{arrow} {mp.displayName}
+					{versionLabel}
+					{count}{" "}
+				</strong>
+			</SelectableRow>
+		);
+	}
+
+	// Map tone to a statusColor for CategoryHeader (legacy component)
+	const statusColorMap: Record<PluginCategoryItem["tone"], UiColor> = {
+		yellow: theme.colors.warning,
+		gray: theme.colors.muted,
+		green: theme.colors.success,
+		red: theme.colors.danger,
+		purple: theme.colors.accent,
+		teal: theme.colors.info,
+		byline: theme.colors.byline,
+	};
+
+	return (
+		<CategoryHeader
+			title={mp.displayName}
+			version={version}
+			expanded={item.isExpanded}
+			count={item.pluginCount}
+			status={item.badge}
+			statusColor={statusColorMap[item.tone]}
+		/>
+	);
+}
+
+function categoryDetail(
+	item: PluginCategoryItem,
+	collapsedMarketplaces: Set<string>,
+): React.ReactNode {
+	const mp = item.marketplace;
+	const isEnabled = item.marketplaceEnabled;
+	const isCollapsed = collapsedMarketplaces.has(mp.name);
+	const hasPlugins = item.pluginCount > 0;
+
+	let actionHint = "Add";
+	if (isEnabled) {
+		if (isCollapsed) {
+			actionHint = "Expand";
+		} else if (hasPlugins) {
+			actionHint = "Collapse";
+		} else {
+			actionHint = "Remove";
+		}
+	}
+
+	return (
+		<box flexDirection="column">
+			<text fg={theme.colors.info}>
+				<strong>
+					{mp.displayName}
+					{item.badge ? ` ${item.badge}` : ""}
+				</strong>
+			</text>
+			<text fg={theme.colors.muted}>{mp.description || "No description"}</text>
+			<text fg={isEnabled ? theme.colors.success : theme.colors.muted}>
+				{isEnabled ? "● Added" : "○ Not added"}
+			</text>
+			<text fg={theme.colors.link}>github.com/{mp.source.repo}</text>
+			<text fg={theme.colors.text}>Plugins: {item.pluginCount}</text>
+			<ActionHints
+				hints={[
+					{
+						key: "Enter",
+						label: actionHint,
+						tone: isEnabled ? "primary" : "default",
+					},
+				]}
+			/>
+			{isEnabled ? (
+				<box>
+					<text fg={theme.colors.muted}>← → to expand/collapse</text>
+				</box>
+			) : null}
+		</box>
+	);
+}
+
+// ─── Plugin renderers ─────────────────────────────────────────────────────────
+
+/**
+ * The row's text after the name, drawn exactly as `pluginRowText` produced it.
+ *
+ * On a selected row the tone's hue is surrendered to the selection (see
+ * MetaText); the words are the same either way.
+ */
+function RowSegments({
+	segments,
+	selected,
+}: {
+	segments: PluginRowSegment[];
+	selected: boolean;
+}): React.ReactNode {
+	return (
+		<>
+			{segments.map((seg, i) => {
+				const key = `${i}:${seg.text}`;
+				if (seg.tone === "text") return <span key={key}>{seg.text}</span>;
+				if (seg.tone === "info") {
+					return (
+						<span
+							key={key}
+							fg={selected ? theme.selection.fg : theme.colors.info}
+						>
+							{seg.text}
+						</span>
+					);
+				}
+				return (
+					<MetaText
+						key={key}
+						text={seg.text}
+						tone={seg.tone}
+						selected={selected}
+					/>
+				);
+			})}
+		</>
+	);
+}
+
+function pluginRow(
+	item: PluginPluginItem,
+	isSelected: boolean,
+): React.ReactNode {
+	const { plugin } = item;
+	const hasUser = !!plugin.userScope?.enabled;
+	const hasProject = !!plugin.projectScope?.enabled;
+	const hasLocal = !!plugin.localScope?.enabled;
+	const hasAnyScope = hasUser || hasProject || hasLocal;
+
+	// Everything after the name — version, history badge, status — comes from
+	// ONE pure function over the classifier's answer, and is drawn verbatim in
+	// every branch below. No branch here decides plugin state.
+	const { segments } = pluginRowText(item);
+
+	// Same glyphs as a marketplace row, in a cell that is always two columns
+	// wide. Both halves matter: a different arrow at each level reads as a
+	// different kind of control, and drawing the cell only on the selected row
+	// shifted every plugin name two columns sideways as the cursor passed over
+	// it.
+	const arrow = item.isExpandable ? (item.isExpanded ? "▼ " : "▶ ") : "  ";
+
+	if (isSelected) {
+		return (
+			<text bg={theme.selection.bg} fg={theme.selection.fg}>
+				{" "}
+				<ScopeSquares
+					user={hasUser}
+					project={hasProject}
+					local={hasLocal}
+					selected={true}
+				/>{" "}
+				{arrow}
+				{plugin.name}
+				<RowSegments segments={segments} selected={true} />{" "}
+			</text>
+		);
+	}
+
+	// Fuzzy highlight
+	const nameSegments = item.matches
+		? highlightMatches(plugin.name, item.matches)
+		: null;
+	const displayName = nameSegments
+		? nameSegments.map((seg) => seg.text).join("")
+		: plugin.name;
+
+	if (plugin.isOrphaned) {
+		// The red squares are the presence marker for "published by no marketplace
+		// we read". WHAT is known about it — moved, withdrawn, or its marketplace
+		// was never read — is the status suffix, the same words the CLI prints.
+		return (
+			<text fg={theme.colors.text}>
+				<span fg={theme.colors.danger}> ■■■ </span>
+				{/* An orphan is never expandable, but it keeps the arrow cell so its
+				    name lands in the same column as every other plugin's. */}
+				<span>{"  "}</span>
+				<span fg={theme.colors.muted}>{displayName}</span>
+				<RowSegments segments={segments} selected={false} />
+			</text>
+		);
+	}
+
+	const installedSomewhere =
+		isInstalledInScope(plugin.userScope) ||
+		isInstalledInScope(plugin.projectScope) ||
+		isInstalledInScope(plugin.localScope);
+
+	return (
+		<text fg={theme.colors.text}>
+			<span> </span>
+			<ScopeSquares user={hasUser} project={hasProject} local={hasLocal} />
+			<span> </span>
+			<span fg={theme.colors.dim}>{arrow}</span>
+			<span
+				fg={
+					hasAnyScope && installedSomewhere
+						? theme.colors.text
+						: theme.colors.muted
+				}
+			>
+				{displayName}
+			</span>
+			<RowSegments segments={segments} selected={false} />
+		</text>
+	);
+}
+
+const ACTION_LABEL: Record<PluginUpdateAction, string> = {
+	install: "NOT INSTALLED",
+	update: "UPDATE AVAILABLE",
+	repair: "NEEDS REINSTALL",
+	current: "UP TO DATE",
+	unknown: "UNKNOWN",
+};
+
+/** Resolved at render time, so a theme switch is honoured. */
+function toneColor(tone: StatusTone): UiColor {
+	switch (tone) {
+		case "danger":
+			return theme.colors.danger;
+		case "warning":
+			return theme.colors.warning;
+		case "success":
+			return theme.colors.success;
+		case "info":
+			return theme.colors.info;
+		case "muted":
+			return theme.colors.muted;
+	}
+}
+
+/**
+ * The detail panel's `Status:` line: the classifier's action, and its note
+ * VERBATIM — the same words `magus update` prints for this plugin.
+ */
+function StatusLine({
+	status,
+}: {
+	status: PluginUpdateItem | null;
+}): React.ReactNode {
+	if (!status) return null;
+	const tone =
+		status.action === "current" ? "success" : pluginStatusText(status).tone;
+	const detail = status.note
+		? status.note
+		: status.action === "update" && status.target
+			? `→ v${status.target}`
+			: "";
+	return (
+		<KeyValueLine
+			label="Status"
+			value={
+				<span>
+					<span fg={toneColor(tone)}>{ACTION_LABEL[status.action]}</span>
+					{detail ? <span fg={theme.colors.text}> {detail}</span> : null}
+				</span>
+			}
+		/>
+	);
+}
+
+function pluginDetail(
+	item: PluginPluginItem,
+	fetched?: PluginContentsEntry,
+): React.ReactNode {
+	const { plugin, status } = item;
+	// "Installed" has to mean the same thing here as in the list row. Reading the
+	// `enabledPlugins` flag alone made this panel print "● Installed" for the
+	// exact plugin the row beside it was labelling "not installed".
+	const isInstalled =
+		isInstalledInScope(plugin.userScope) ||
+		isInstalledInScope(plugin.projectScope) ||
+		isInstalledInScope(plugin.localScope);
+	const brokenInstall = isEnabledButNotInstalled(plugin);
+	// The ⬆ marker and the U hint claim that pressing U does something. That is
+	// exactly the classifier's update/repair, and nothing else.
+	const needsWork = status?.action === "update" || status?.action === "repair";
+
+	// Published by no marketplace we read. The status line says which of the
+	// three things that means — moved, withdrawn, or its marketplace unread.
+	if (plugin.isOrphaned) {
+		return (
+			<box flexDirection="column">
+				<box justifyContent="center">
+					<text bg={theme.colors.warning} fg={theme.hints.fg}>
+						<strong> {plugin.name} — NOT LISTED </strong>
+					</text>
+				</box>
+				<box marginTop={1}>
+					<StatusLine status={status} />
+				</box>
+				<box marginTop={1}>
+					<text fg={theme.colors.warning}>
+						No marketplace magus read lists this plugin.
+					</text>
+				</box>
+				<box marginTop={1}>
+					<text fg={theme.colors.muted}>
+						It is still installed or referenced in your settings. Press d to
+						uninstall and clean up, or to migrate it if it moved.
+					</text>
+				</box>
+				<ActionHints
+					hints={[
+						{
+							key: "d",
+							label: isInstalled
+								? "Remove from all scopes"
+								: "Clean up stale reference",
+							tone: "danger",
+						},
+					]}
+				/>
+			</box>
+		);
+	}
+
+	// Component counts. A listing fetched from the repo tree wins over the
+	// manifest scan on every count it can supply: the scan only sees a
+	// marketplace that is cloned locally, a `featured` marketplace the user has
+	// not added has no clone at all, and the scan misses an MCP server declared
+	// in `.mcp.json` rather than an `mcp-servers/` directory — which is how 5 of
+	// this marketplace's 7 MCP plugins declare theirs, mnemex included.
+	const listed =
+		fetched?.status === "success" ? (fetched.components ?? null) : null;
+	const countOf = (kind: PluginComponentKind, fallback?: string[]) =>
+		listed
+			? listed.filter((c) => c.kind === kind).length
+			: (fallback?.length ?? 0);
+
+	const components: string[] = [];
+	const agentCount = countOf("agent", plugin.agents);
+	const commandCount = countOf("command", plugin.commands);
+	const skillCount = countOf("skill", plugin.skills);
+	const mcpCount = countOf("mcp", plugin.mcpServers);
+	/** "1 agent", "2 agents" — a count of one is common enough to read wrong. */
+	const plural = (n: number, noun: string) =>
+		`${n} ${noun}${n === 1 ? "" : "s"}`;
+	if (agentCount) components.push(plural(agentCount, "agent"));
+	if (commandCount) components.push(plural(commandCount, "command"));
+	if (skillCount) components.push(plural(skillCount, "skill"));
+	if (mcpCount) components.push(plural(mcpCount, "MCP server"));
+	if (plugin.lspServers && Object.keys(plugin.lspServers).length) {
+		components.push(`${Object.keys(plugin.lspServers).length} LSP`);
+	}
+
+	const showVersion = isKnownVersion(plugin.version ?? undefined);
+	// The shared comparator, not `!==`: "1.2" and "1.2.0" are the same version,
+	// and the classifier's `Status:` line right above says so. Raw inequality
+	// made this line contradict it. `null` (no shared ordering) is a genuine
+	// difference and shows.
+	const showInstalledVersion =
+		isInstalled &&
+		isKnownVersion(plugin.installedVersion) &&
+		plugin.installedVersion !== undefined &&
+		plugin.version !== null &&
+		compareVersions(plugin.version, plugin.installedVersion) !== 0;
+
+	return (
+		<box flexDirection="column">
+			{/* Plugin name header */}
+			<box justifyContent="center">
+				<text bg={theme.selection.bg} fg={theme.selection.fg}>
+					<strong>
+						{" "}
+						{plugin.name}
+						{needsWork ? " ⬆" : ""}{" "}
+					</strong>
+				</text>
+			</box>
+
+			{/* Status line */}
+			<box marginTop={1}>
+				<text
+					fg={
+						isInstalled
+							? theme.colors.success
+							: brokenInstall
+								? theme.colors.warning
+								: theme.colors.muted
+					}
+				>
+					{isInstalled
+						? "● Installed"
+						: brokenInstall
+							? "○ Not installed — enabled in settings, no files on disk"
+							: "○ Not installed"}
+				</text>
+			</box>
+			{brokenInstall ? (
+				<box>
+					<text fg={theme.colors.muted}>
+						Claude Code cannot load it in this state. Press the scope key to
+						repair.
+					</text>
+				</box>
+			) : null}
+
+			{/* Description */}
+			<box marginTop={1} marginBottom={1}>
+				<text fg={theme.colors.text}>{plugin.description}</text>
+			</box>
+
+			{/* Metadata */}
+			<StatusLine status={status} />
+			{showVersion ? (
+				<KeyValueLine
+					label="Version"
+					value={
+						<span>
+							<span fg={theme.colors.link}>v{plugin.version}</span>
+							{showInstalledVersion ? (
+								<span> (v{plugin.installedVersion} installed)</span>
+							) : null}
+						</span>
+					}
+				/>
+			) : null}
+			{/*
+			 * Name the source of the version above whenever it is not authoritative.
+			 * Without this the panel showed a version and an installed version that
+			 * happened to match, and the user reasonably read that as "current" —
+			 * when in fact GitHub was never reached and the number came off a clone
+			 * that had not moved in days.
+			 */}
+			{status?.reason === "catalog-unverified" ? (
+				<>
+					<KeyValueLine
+						label="Latest"
+						value={
+							<span fg={theme.colors.warning}>unverified — not checked</span>
+						}
+					/>
+					<box>
+						<text fg={theme.colors.muted}>
+							{"  "}
+							{plugin.catalogSource === "local-clone"
+								? "Version shown is from the pinned marketplace clone, so a newer release may exist. Press r to retry."
+								: "Press r to retry."}
+						</text>
+					</box>
+				</>
+			) : null}
+			{plugin.category ? (
+				<KeyValueLine
+					label="Category"
+					value={<span fg={theme.colors.accent}>{plugin.category}</span>}
+				/>
+			) : null}
+			{plugin.author ? (
+				<KeyValueLine
+					label="Author"
+					value={<span>{plugin.author.name}</span>}
+				/>
+			) : null}
+			{components.length > 0 ? (
+				<KeyValueLine
+					label="Contains"
+					value={
+						<span fg={theme.colors.warning}>{components.join(" · ")}</span>
+					}
+				/>
+			) : null}
+			{item.isExpandable ? (
+				<box>
+					<text fg={theme.colors.muted}>
+						← → to {item.isExpanded ? "hide" : "list"} what it contains
+					</text>
+				</box>
+			) : null}
+
+			{/* Scope Status */}
+			<DetailSection>
+				<text fg={theme.colors.text}>{"─".repeat(24)}</text>
+				<text fg={theme.colors.text}>
+					<strong>Scopes:</strong>
+				</text>
+				<box marginTop={1} flexDirection="column">
+					<ScopeLine
+						keyHint="u"
+						name="User"
+						qualifier="global"
+						color={theme.scopes.user}
+						scope={plugin.userScope}
+					/>
+					<ScopeLine
+						keyHint="p"
+						name="Project"
+						qualifier="team"
+						color={theme.scopes.project}
+						scope={plugin.projectScope}
+					/>
+					<ScopeLine
+						keyHint="l"
+						name="Local"
+						qualifier="private"
+						color={theme.scopes.local}
+						scope={plugin.localScope}
+					/>
+				</box>
+			</DetailSection>
+
+			{/* Recent releases */}
+			<ReleaseHistory
+				releases={plugin.releases}
+				installedVersion={plugin.installedVersion}
+			/>
+
+			{/* Update action */}
+			{needsWork ? (
+				<ActionHints
+					hints={[
+						{
+							key: "U",
+							label:
+								status?.action === "repair"
+									? "Reinstall (files changed)"
+									: status?.target
+										? `Update to v${status.target}`
+										: "Update",
+							tone: "primary",
+						},
+					]}
+				/>
+			) : null}
+		</box>
+	);
+}
+
+/**
+ * One line of the detail panel's scope breakdown.
+ *
+ * The filled dot means installed — registry-backed, same as everywhere else.
+ * A scope that is enabled with nothing installed is called out explicitly
+ * rather than shown as a plain empty dot, because those two states need
+ * different actions from the user and used to look identical.
+ */
+function ScopeLine({
+	keyHint,
+	name,
+	qualifier,
+	color,
+	scope,
+}: {
+	keyHint: string;
+	name: string;
+	qualifier: string;
+	color: UiColor;
+	scope?: ScopeStatus;
+}): React.ReactNode {
+	const installed = isInstalledInScope(scope);
+	return (
+		<text fg={theme.colors.text}>
+			<span bg={color} fg={theme.hints.fg}>
+				{" "}
+				{keyHint}{" "}
+			</span>
+			<span fg={installed ? color : theme.colors.muted}>
+				{installed ? " ● " : " ○ "}
+			</span>
+			<span fg={color}>{name}</span>
+			<span> {qualifier}</span>
+			{scope?.version ? <span fg={color}> v{scope.version}</span> : null}
+			{!installed && scope?.enabled ? (
+				<span fg={theme.colors.warning}> enabled, not installed</span>
+			) : null}
+		</text>
+	);
+}
+
+/**
+ * Recent release history, newest first.
+ *
+ * Releases the user does not have yet are marked and coloured; the installed one is
+ * flagged; older ones are dimmed. The list is already ordered newest-first, so the
+ * installed entry's index is all that's needed to tell those three groups apart —
+ * no version comparison, and no way for it to disagree with the published order.
+ * When the installed version isn't in the window (unknown "0.0.0", or older than the
+ * releases published), everything renders neutrally rather than guessing.
+ */
+function ReleaseHistory({
+	releases,
+	installedVersion,
+}: {
+	releases?: PluginRelease[];
+	installedVersion?: string;
+}): React.ReactNode {
+	if (!releases?.length) return null;
+
+	const installedAt = installedVersion
+		? releases.findIndex((r) => r.version === installedVersion)
+		: -1;
+
+	return (
+		<DetailSection>
+			<text fg={theme.colors.text}>{"─".repeat(24)}</text>
+			<text fg={theme.colors.text}>
+				<strong>Recent releases:</strong>
+			</text>
+			<box marginTop={1} flexDirection="column">
+				{releases.map((release, i) => {
+					const isNewer = installedAt > 0 && i < installedAt;
+					const isInstalled = installedAt >= 0 && i === installedAt;
+					const versionColor = isNewer
+						? theme.colors.warning
+						: isInstalled
+							? theme.colors.success
+							: theme.colors.link;
+
+					return (
+						<box key={release.version} flexDirection="column" marginBottom={1}>
+							<text fg={theme.colors.text}>
+								<span fg={versionColor}>
+									{isNewer ? "▲ " : isInstalled ? "● " : "  "}v{release.version}
+								</span>
+								{release.date ? (
+									<span fg={theme.colors.muted}> {release.date}</span>
+								) : null}
+								{release.kinds?.length ? (
+									<span fg={theme.colors.dim}>
+										{" "}
+										{release.kinds.join(" · ")}
+									</span>
+								) : null}
+								{isInstalled ? (
+									<span fg={theme.colors.success}> installed</span>
+								) : null}
+							</text>
+							<text fg={isNewer ? theme.colors.text : theme.colors.muted}>
+								{"  "}
+								{release.summary}
+							</text>
+						</box>
+					);
+				})}
+			</box>
+		</DetailSection>
+	);
+}
+
+// ─── Skill renderers ─────────────────────────────────────────────────────────
+
+/**
+ * Left padding for a component row.
+ *
+ * A plugin name starts at column 7: one leading space, three scope segments,
+ * one space, then the two-column arrow cell. A component's badge occupies
+ * columns 5-7 and its name starts at 9.
+ *
+ * Deliberately no tree glyph. An earlier version drew a `└` on every row, which
+ * introduced a second visual grammar halfway down the list — scope segments
+ * above, box-drawing below — and read as a broken tree, since a real one would
+ * branch with `├` on every row but the last. The badge anchors the row instead,
+ * and says what kind of thing it is at the same time.
+ */
+const COMPONENT_INDENT = " ".repeat(5);
+
+/**
+ * Width of the badge cell plus the gap after it, so status rows line their text
+ * up with the component names.
+ *
+ * The gap is outside the chip, not inside it. Widening the chip to four cells
+ * would have put the extra space on its coloured fill, which makes the chip
+ * bigger rather than separating it from the name.
+ */
+const BADGE_WIDTH = 3;
+const BADGE_GAP = 1;
+
+/**
+ * Type icons.
+ *
+ * Commands and agents take the glyph you address them with — `/name`, `@name` —
+ * so the badge and the thing you type match.
+ *
+ * The skill glyph follows the only convention the ecosystem has. There is no
+ * agreed terminal symbol for a skill: Anthropic ships none (its Skills write-up
+ * uses a folder metaphor in prose only), and the large community directories
+ * distinguish skills from plugins by section heading rather than by symbol. The
+ * two products that do mark them converged on the same idea — Cursor's docs say
+ * a skill badge "defaults to a lightning icon", and the community Skills
+ * sidebar for VS Code uses a sparkle.
+ *
+ * `✱` is the sparkle idea at single width. The canonical glyphs cannot be used:
+ * `⚡` (U+26A1) and `✨` (U+2728) are both East-Asian-Width Wide, i.e. two cells,
+ * which would shift every name on the row. An *asterisk* rather than a
+ * four-pointed star also keeps it clear of `◆` and `✦`, which read as a generic
+ * ornament next to `/` and `@`.
+ *
+ * `⬢` for an MCP server is ours; nobody has a convention there either.
+ *
+ * Every glyph here is single-width — check with `unicodedata.east_asian_width`
+ * before swapping one, and reject anything reporting W or F.
+ */
+export const COMPONENT_ICON: Record<PluginComponentKind, string> = {
+	skill: "✱",
+	command: "/",
+	agent: "@",
+	mcp: "⬢",
+};
+
+const COMPONENT_COLOR: Record<PluginComponentKind, UiColor> = {
+	skill: theme.colors.accent,
+	command: theme.colors.info,
+	agent: theme.colors.link,
+	mcp: theme.colors.warning,
+};
+
+const COMPONENT_NOUN: Record<PluginComponentKind, string> = {
+	skill: "Skill",
+	command: "Command",
+	agent: "Subagent",
+	mcp: "MCP server",
+};
+
+/**
+ * The type badge: one glyph in a padded, washed cell.
+ *
+ * Two states, and each exists for a reason.
+ *
+ * On a *selected* row the whole line is painted in the selection colour, so the
+ * badge drops its own fill — a chip of a third colour inside an inverted row is
+ * the noisiest thing on the screen, and the selection already says where you
+ * are.
+ *
+ * Otherwise: a wash of the kind's hue for the resolved mode, quiet enough to
+ * sit on hundreds of rows.
+ */
+function componentBadge(
+	kind: PluginComponentKind,
+	isSelected: boolean,
+): React.ReactNode {
+	const icon = COMPONENT_ICON[kind];
+	if (isSelected) return ` ${icon} `;
+
+	const chip = badgeColors(kind);
+	return <span bg={chip.bg} fg={chip.fg}>{` ${icon} `}</span>;
+}
+
+function componentRow(
+	item: PluginComponentItem,
+	isSelected: boolean,
+): React.ReactNode {
+	const { component } = item;
+	const label = component.group
+		? `${component.group}/${component.name}`
+		: component.name;
+
+	if (isSelected) {
+		return (
+			<text bg={theme.selection.bg} fg={theme.selection.fg}>
+				{COMPONENT_INDENT}
+				{componentBadge(component.kind, true)}
+				{`${" ".repeat(BADGE_GAP)}${label} `}
+			</text>
+		);
+	}
+	return (
+		<text fg={theme.colors.muted}>
+			{COMPONENT_INDENT}
+			{componentBadge(component.kind, false)}
+			{`${" ".repeat(BADGE_GAP)}${label}`}
+		</text>
+	);
+}
+
+function contentsStatusRow(
+	item: PluginContentsStatusItem,
+	isSelected: boolean,
+): React.ReactNode {
+	const pad = COMPONENT_INDENT + " ".repeat(BADGE_WIDTH + BADGE_GAP);
+	if (isSelected) {
+		return (
+			<text bg={theme.selection.bg} fg={theme.selection.fg}>
+				{`${pad}${item.label} `}
+			</text>
+		);
+	}
+	return (
+		<text
+			fg={item.status === "error" ? theme.colors.warning : theme.colors.dim}
+		>
+			{`${pad}${item.label}`}
+		</text>
+	);
+}
+
+/**
+ * How much of a component's file the panel prints.
+ *
+ * The detail pane is a scroll box (PgUp/PgDn, Ctrl+U/Ctrl+D), so this is a
+ * render-cost guard, not a reading limit — high enough that essentially every
+ * real file prints whole. When it does bite, the panel says how many lines it
+ * withheld: a body that simply stops reads as a truncated *file*, which is a
+ * different and more alarming claim than a truncated view.
+ */
+const BODY_LINES = 400;
+
+/** Frontmatter keys already shown in the header, so the table skips them. */
+const HEADER_KEYS = new Set(["name", "description"]);
+
+function componentDetail(
+	item: PluginComponentItem,
+	entry?: PluginSkillDetailEntry,
+	width = 80,
+): React.ReactNode {
+	const { component, plugin } = item;
+	const detail = entry?.status === "success" ? entry.detail : undefined;
+	const isMcp = component.kind === "mcp";
+
+	const described = detail?.frontmatter.find((f) => f.key === "description");
+	const titled = detail?.frontmatter.find((f) => f.key === "name");
+	const rest = (detail?.frontmatter ?? []).filter(
+		(f) => !HEADER_KEYS.has(f.key) && f.value,
+	);
+
+	const rendered = detail
+		? renderMarkdown(detail.body, { width, maxLines: BODY_LINES })
+		: null;
+
+	return (
+		<box flexDirection="column">
+			<box justifyContent="center">
+				<text bg={theme.selection.bg} fg={theme.selection.fg}>
+					<strong>
+						{" "}
+						{COMPONENT_ICON[component.kind]} {titled?.value ||
+							component.name}{" "}
+					</strong>
+				</text>
+			</box>
+
+			{described ? (
+				<box marginTop={1}>
+					<text fg={theme.colors.text}>{described.value}</text>
+				</box>
+			) : null}
+
+			<box marginTop={1} flexDirection="column">
+				<KeyValueLine
+					label="Kind"
+					value={
+						<span>
+							{componentBadge(component.kind, false)}
+							<span fg={COMPONENT_COLOR[component.kind]}>
+								{` ${COMPONENT_NOUN[component.kind]}`}
+							</span>
+						</span>
+					}
+				/>
+				<KeyValueLine
+					label="Plugin"
+					value={<span fg={theme.colors.accent}>{plugin.name}</span>}
+				/>
+				{component.group ? (
+					<KeyValueLine
+						label="Group"
+						value={<span fg={theme.colors.accent}>{component.group}</span>}
+					/>
+				) : null}
+				{component.mcpCommand ? (
+					<KeyValueLine
+						label="Runs"
+						value={<span fg={theme.colors.link}>{component.mcpCommand}</span>}
+					/>
+				) : null}
+				<KeyValueLine
+					label="Path"
+					value={<span fg={theme.colors.link}>{component.repoPath}</span>}
+				/>
+				{rest.map((field) => (
+					<KeyValueLine
+						key={field.key}
+						label={field.key}
+						value={<span fg={theme.colors.warning}>{field.value}</span>}
+					/>
+				))}
+			</box>
+
+			{/* An MCP server is declared in JSON, not a markdown document, so there
+			    is no body to fetch — the Runs line above is the whole of it. */}
+			{!isMcp && (entry?.status === "loading" || !entry) ? (
+				<box marginTop={1}>
+					<text fg={theme.colors.muted}>Reading {component.repoPath}…</text>
+				</box>
+			) : null}
+
+			{entry?.status === "error" ? (
+				<box marginTop={1} flexDirection="column">
+					<text fg={theme.colors.warning}>
+						Could not read it: {entry.error}
+					</text>
+					<text fg={theme.colors.muted}>
+						Set GITHUB_TOKEN to raise the 60-per-hour unauthenticated limit.
+					</text>
+				</box>
+			) : null}
+
+			{rendered && rendered.nodes.length > 0 ? (
+				<DetailSection>
+					<text fg={theme.colors.text}>{"─".repeat(24)}</text>
+					<box marginTop={1} flexDirection="column">
+						{rendered.nodes}
+					</box>
+					{rendered.withheld > 0 ? (
+						<box marginTop={1}>
+							<text fg={theme.colors.dim}>
+								… {rendered.withheld} more lines in the file
+							</text>
+						</box>
+					) : null}
+				</DetailSection>
+			) : null}
+
+			{detail && detail.body.length === 0 ? (
+				<box marginTop={1}>
+					<text fg={theme.colors.muted}>Frontmatter only — no body.</text>
+				</box>
+			) : null}
+
+			<box marginTop={1}>
+				<text fg={theme.colors.dim}>
+					Installing {plugin.name} installs this. Plugin components are not
+					installed one at a time.
+				</text>
+			</box>
+		</box>
+	);
+}
+
+function contentsStatusDetail(item: PluginContentsStatusItem): React.ReactNode {
+	if (item.status === "error") {
+		return (
+			<box flexDirection="column">
+				<text fg={theme.colors.warning}>
+					<strong>Could not read {item.plugin.name}</strong>
+				</text>
+				<box marginTop={1}>
+					<text fg={theme.colors.muted}>{item.error || "Unknown error."}</text>
+				</box>
+				<box marginTop={1}>
+					<text fg={theme.colors.muted}>
+						A marketplace you have added is read from its local clone and needs
+						no network. This one is not added, so its contents come from the
+						GitHub API — where an unauthenticated client gets 60 requests an
+						hour across every repo on screen combined.
+					</text>
+				</box>
+				<box marginTop={1}>
+					<text fg={theme.colors.muted}>
+						Add the marketplace to read it from disk instead, or set
+						GITHUB_TOKEN to raise the limit. Collapse and expand to retry — the
+						failure is not cached.
+					</text>
+				</box>
+			</box>
+		);
+	}
+	if (item.status === "empty") {
+		return (
+			<box flexDirection="column">
+				<text fg={theme.colors.text}>
+					<strong>{item.plugin.name} ships no components</strong>
+				</text>
+				<box marginTop={1}>
+					<text fg={theme.colors.muted}>
+						No skills, commands, subagents or MCP servers were found in its
+						directory. It may ship hooks, an output style, or nothing but
+						documentation.
+					</text>
+				</box>
+			</box>
+		);
+	}
+	return <text fg={theme.colors.muted}>Reading the repo tree…</text>;
+}
+
+// ─── Public dispatch functions ────────────────────────────────────────────────
+
+/**
+ * Render a plugin browser list row by item kind.
+ */
+export function renderPluginRow(
+	item: PluginBrowserItem,
+	_index: number,
+	isSelected: boolean,
+): React.ReactNode {
+	if (item.kind === "category") {
+		return categoryRow(item, isSelected);
+	}
+	if (item.kind === "component") {
+		return componentRow(item, isSelected);
+	}
+	if (item.kind === "contents-status") {
+		return contentsStatusRow(item, isSelected);
+	}
+	return pluginRow(item, isSelected);
+}
+
+/**
+ * Render the detail panel for a plugin browser item.
+ */
+export function renderPluginDetail(
+	item: PluginBrowserItem | undefined,
+	collapsedMarketplaces: Set<string>,
+	pluginContents?: Map<string, PluginContentsEntry>,
+	skillDetails?: Map<string, PluginSkillDetailEntry>,
+	/** Columns the detail pane has, so a markdown table can size its columns. */
+	width?: number,
+): React.ReactNode {
+	if (!item) return <text fg={theme.colors.muted}>Select an item</text>;
+	if (item.kind === "category") {
+		return categoryDetail(item, collapsedMarketplaces);
+	}
+	if (item.kind === "component") {
+		return componentDetail(item, skillDetails?.get(item.detailKey), width);
+	}
+	if (item.kind === "contents-status") {
+		return contentsStatusDetail(item);
+	}
+	return pluginDetail(item, pluginContents?.get(item.plugin.id));
+}