@protoboardai/views 0.0.0-stage → 0.2.0

package/src/parts/ProjectPartsPage.tsx

@@ -0,0 +1,264 @@
+/**
+ * The Project Parts page (PB-945, decision D3 of beta test 1): the project's
+ * parts in the editor area, looking like the library: the same cards with
+ * their pictures (PartCard), grouped by tier (from libraries, researched,
+ * designed), each carrying its sync status with the library (in sync, update
+ * available with the revision, diverged, local only) and its part status
+ * (PB-932). The "Project parts" breadcrumb of a part's detail returns here,
+ * and the side bar's heading opens it. The same page in VS Code (an editor
+ * tab) and in the web viewer.
+ */
+import { useMemo, useState } from "react";
+import { EmptyState, Icon, IconButton, ScrollArea, cx } from "@deltarobotics/uhd-viewer/components";
+import { partSync, projectCard, tierGroups, type PartSync, type PartSyncKind } from "./library-data.js";
+import type { ProjectPartModel, ProjectPartsActions, ProjectPartsModel } from "./model.js";
+import { CARD_HEIGHT, PartCard } from "./PartCard.js";
+import { LinkPagesToggle, PagerProvider, PagesProvider, useNewPagerStore } from "./carousel.js";
+import { Windowed } from "./Windowed.js";
+import { PartStatusDot } from "./PartStatus.js";
+import { PART_TRUST_STATES, PART_TRUST_TEXT } from "./part-status.js";
+import { UPDATE_EXPLAINED, partIcon } from "./ProjectParts.js";
+import { rev } from "./revision.js";
+import { PartsSurface } from "./Surface.js";
+import { BODY, Button, FoldHeading, RowAction, SearchField, SectionLabel, useFolded, type FoldedGroups } from "./ui.js";
+
+export interface ProjectPartsPageProps {
+  /** The groups folded away, kept by the host (PB-1039). */
+  folded?: FoldedGroups;
+  model: ProjectPartsModel;
+  actions: ProjectPartsActions;
+  /** The project's name, beside the heading. */
+  project?: string;
+  /** The part whose detail is open (its card is outlined). */
+  selected?: string;
+}
+
+const SYNC_TEXT: Record<PartSync["tone"], string> = { ok: "text-ok", info: "text-info", warning: "text-warning", neutral: "text-fg-muted" };
+
+/** A part's sync status as a pill: its icon and words in the state's tone, on the card's own surface so it reads over a picture. */
+export function SyncPill({ sync, onClick, disabled }: { sync: PartSync; /** An update's pill updates the part. */ onClick?: () => void; disabled?: boolean }) {
+  const tip = `${sync.label}. ${sync.meaning}`;
+  const pill = (
+    <span
+      {...(onClick ? {} : { role: "img", "aria-label": tip, "data-tooltip": tip })}
+      className={cx(
+        "inline-flex h-5 shrink-0 items-center gap-1 rounded-full border border-current bg-[var(--pb-card)] px-2 text-[11px] leading-none whitespace-nowrap outline-1 -outline-offset-1 outline-contrast",
+        SYNC_TEXT[sync.tone],
+      )}
+    >
+      <Icon name={sync.icon} size={11} strokeWidth={2} aria-hidden />
+      {sync.label}
+    </span>
+  );
+  if (!onClick) return pill;
+  return (
+    <button
+      type="button"
+      aria-label={tip}
+      data-tooltip={tip}
+      disabled={disabled}
+      onClick={(e) => {
+        e.stopPropagation();
+        onClick();
+      }}
+      className="cursor-pointer rounded-full focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-1 focus-visible:outline-focus disabled:cursor-default"
+    >
+      {pill}
+    </button>
+  );
+}
+
+type Filter = "all" | PartSyncKind;
+
+function CardActions({ part, actions }: { part: ProjectPartModel; actions: ProjectPartsActions }) {
+  const busy = !!part.busy;
+  return (
+    <div className="flex shrink-0 items-center gap-0.5">
+      {part.status === "update-available" && actions.update && <RowAction icon="download" label={`Update to ${rev(part.recommended)}`} disabled={busy} onClick={() => actions.update!(part.id)} />}
+      {part.status === "diverged" && actions.restore && <RowAction icon="undo-2" label={`Restore ${rev(part.revision)}`} disabled={busy} onClick={() => actions.restore!(part.id)} />}
+      {part.tier === "catalog" && actions.compare && <RowAction icon="git-compare-arrows" label="Compare with the library" onClick={() => actions.compare!(part.id)} />}
+      {part.tier === "project-researched" && actions.publish && <RowAction icon="upload" label="Submit for verification" onClick={() => actions.publish!(part.id)} />}
+      {actions.openSource && <RowAction icon="file-code" label="Open source" onClick={() => actions.openSource!(part.id)} />}
+    </div>
+  );
+}
+
+export function ProjectPartsPage({ model, actions, project, selected, folded }: ProjectPartsPageProps) {
+  const [layout, setLayout] = useState<"grid" | "list">("grid");
+  const [text, setText] = useState("");
+  const [filter, setFilter] = useState<Filter>("all");
+  const pager = useNewPagerStore();
+  const synced = useMemo(() => model.parts.map((p) => ({ part: p, sync: partSync(p) })), [model.parts]);
+  const count = (k: PartSyncKind) => synced.filter((x) => x.sync.kind === k).length;
+  const shown = useMemo(() => {
+    const words = text.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    return synced.filter(({ part, sync }) => (filter === "all" || sync.kind === filter) && words.every((w) => `${part.name} ${part.id} ${part.manufacturer ?? ""} ${part.partNumber ?? ""}`.toLowerCase().includes(w)));
+  }, [synced, text, filter]);
+  const syncOf = useMemo(() => new Map(shown.map((x) => [x.part.id, x.sync])), [shown]);
+  const groups = useMemo(() => tierGroups(shown.map((x) => x.part)), [shown]);
+  const { closed, toggle, setAll } = useFolded(folded);
+  const allClosed = groups.length > 0 && groups.every((g) => closed.has(g.id));
+  const c = model.counts;
+  // the filters offered: every sync state the project has parts in (never one that would show nothing)
+  const every: { id: Filter; label: string; icon: string; n: number; tone: PartSync["tone"] }[] = [
+    { id: "all", label: "All", icon: "layout-grid", n: c.total, tone: "neutral" },
+    { id: "update", label: "Updates", icon: "download", n: count("update"), tone: "info" },
+    { id: "diverged", label: "Diverged", icon: "git-compare-arrows", n: count("diverged"), tone: "warning" },
+    { id: "in-sync", label: "In sync", icon: "check", n: count("in-sync"), tone: "ok" },
+    { id: "pinned", label: "Not checked", icon: "pin", n: count("pinned"), tone: "neutral" },
+    { id: "local", label: "Local only", icon: "hard-drive", n: count("local"), tone: "neutral" },
+  ];
+  const filters = every.filter((f) => f.id === "all" || f.n > 0);
+  const checked = model.checked ? `Checked ${model.checked.at.slice(0, 16).replace("T", " ")} UTC` : undefined;
+  return (
+    <PartsSurface place="editor">
+      <div className="flex size-full min-w-[320px] flex-col">
+        <header className={cx(BODY, "flex shrink-0 flex-col gap-3 px-6 pt-5 pb-3 max-[640px]:px-4")}>
+          <div className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-2">
+            <span className="flex min-w-0 flex-1 items-baseline gap-2">
+              <Icon name="package" size={17} strokeWidth={1.75} className="shrink-0 self-center text-fg" aria-hidden />
+              <h1 className="shrink-0 text-[17px] font-semibold text-fg">Project parts</h1>
+              <span className="min-w-0 truncate text-[12.5px] text-fg-muted">
+                {project ? `${project} · ` : ""}
+                {c.total} part{c.total === 1 ? "" : "s"}: {c.library} from libraries, {c.researched} researched, {c.designed} designed
+              </span>
+            </span>
+            <span className="flex shrink-0 items-center gap-2">
+              {actions.check && (
+                <Button icon={model.loading ? "loader" : "refresh-cw"} disabled={model.loading} onClick={actions.check} data-tooltip={checked ?? "Ask the libraries which parts have a newer recommended revision"}>
+                  {model.loading ? "Checking…" : "Check for updates"}
+                </Button>
+              )}
+              {actions.openLibrary && (
+                <Button icon="library-big" onClick={actions.openLibrary}>
+                  Library
+                </Button>
+              )}
+            </span>
+          </div>
+          <div className="flex min-w-0 flex-wrap items-center gap-2">
+            <SearchField className="min-w-[160px] flex-1" value={text} placeholder="Filter the project's parts by name, id or MPN…" onChange={setText} />
+            {actions.pages && <LinkPagesToggle store={pager} />}
+            <span className="flex items-center gap-1">
+              {groups.length > 1 && <IconButton icon={allClosed ? "chevrons-up-down" : "chevrons-down-up"} label={allClosed ? "Expand all groups" : "Collapse all groups"} onClick={() => setAll(allClosed ? [] : groups.map((g) => g.id))} />}
+              <IconButton icon="layout-grid" label="Grid" pressed={layout === "grid"} onClick={() => setLayout("grid")} />
+              <IconButton icon="list" label="List" pressed={layout === "list"} onClick={() => setLayout("list")} />
+            </span>
+          </div>
+          <ScrollArea axis="horizontal" className="-mx-1 shrink-0" contentClassName="flex gap-1.5 px-1 py-0.5">
+            <div role="radiogroup" aria-label="Show parts by sync status" className="flex gap-1.5">
+              {filters.map((f) => (
+                <button
+                  key={f.id}
+                  type="button"
+                  role="radio"
+                  aria-checked={filter === f.id}
+                  onClick={() => setFilter(f.id)}
+                  className={cx(
+                    "inline-flex h-7 shrink-0 cursor-pointer items-center gap-1.5 rounded-[4px] border px-2.5 text-[12px] whitespace-nowrap transition-colors",
+                    filter === f.id ? "border-focus bg-active text-fg outline outline-1 -outline-offset-1 outline-contrast-active" : "border-[var(--pb-control-border)] text-fg hover:bg-hover",
+                    "focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-1 focus-visible:outline-focus",
+                  )}
+                >
+                  <Icon name={f.icon} size={13} strokeWidth={1.75} className={SYNC_TEXT[f.tone]} aria-hidden />
+                  {f.label}
+                  <span className="font-ui text-[11px] text-fg-muted tabular-nums">{f.n}</span>
+                </button>
+              ))}
+            </div>
+          </ScrollArea>
+          {model.error && (
+            <p role="status" className="flex items-start gap-2 rounded-[4px] border border-line px-2.5 py-2 text-[12px] text-fg">
+              <Icon name="triangle-alert" size={14} className="mt-px shrink-0 text-warning" aria-hidden />
+              {model.error}
+            </p>
+          )}
+          {(model.checked?.problems ?? []).map((m) => (
+            <p key={m} role="status" className="flex items-start gap-2 text-[12px] text-fg-muted">
+              <Icon name="triangle-alert" size={14} className="mt-px shrink-0 text-warning" aria-hidden />
+              Not checked: {m}
+            </p>
+          ))}
+        </header>
+        <ScrollArea className="min-h-0 flex-1" contentClassName="flex flex-col gap-7 px-6 pt-1 pb-8 max-[640px]:px-4">
+          <PagesProvider loader={actions.pages}>
+            <PagerProvider store={pager}>
+              {groups.map((g, gi) => (
+                <section key={g.id} aria-label={g.title} data-group={g.id}>
+                  <FoldHeading open={!closed.has(g.id)} onToggle={() => toggle(g.id)} className="-ml-1.5 h-7 px-1.5" right={<span className="font-ui text-[11px] text-fg-muted">{g.parts.length}</span>}>
+                    {g.title}
+                  </FoldHeading>
+                  {!closed.has(g.id) && <p className={cx(BODY, "pt-0.5 pb-2.5 text-[12px] leading-snug text-fg-muted")}>{g.hint}</p>}
+                  {!closed.has(g.id) && (
+                  <div className={layout === "grid" ? "grid grid-cols-[repeat(auto-fill,minmax(220px,1fr))] gap-4" : "flex flex-col gap-2"}>
+                    {g.parts.map((p, i) => {
+                      const sync = syncOf.get(p.id)!;
+                      return (
+                      <Windowed key={p.id} height={CARD_HEIGHT[layout === "grid" ? "tile" : "row"]} eager={gi === 0 && i < 24}>
+                          <PartCard
+                            item={projectCard(p)}
+                            variant={layout === "grid" ? "tile" : "row"}
+                            selected={p.id === selected}
+                            icon={partIcon(p)}
+                            onOpen={() => actions.open(p.id)}
+                            onAdd={() => undefined}
+                            onUpdate={() => undefined}
+                            pill={p.busy ? undefined : <SyncPill sync={sync} {...(sync.kind === "update" && actions.update ? { onClick: () => actions.update!(p.id) } : {})} />}
+                            status={p.trust ? <PartStatusDot trust={p.trust} basis={p.trustBasis} label /> : undefined}
+                            actions={<CardActions part={p} actions={actions} />}
+                          />
+                      </Windowed>
+                      );
+                    })}
+                  </div>
+                  )}
+                </section>
+              ))}
+            </PagerProvider>
+          </PagesProvider>
+          {model.loading && !model.parts.length && (
+            <div className="grid grid-cols-[repeat(auto-fill,minmax(220px,1fr))] gap-4" aria-hidden>
+              {[0, 1, 2, 3].map((i) => (
+                <div key={i} className="h-[300px] animate-pulse rounded-[6px] border border-line bg-[var(--pb-card)]" />
+              ))}
+            </div>
+          )}
+          {!groups.length && !model.loading && (
+            <div className="py-16">
+              {model.parts.length ? (
+                <EmptyState icon={<Icon name="search-x" size={28} strokeWidth={1.25} />} title="No parts match">
+                  Try other words, or show every sync status.
+                </EmptyState>
+              ) : (
+                <EmptyState icon={<Icon name="package" size={28} strokeWidth={1.25} />} title="No parts yet">
+                  Parts you add from the library, research or design in the project are listed here.
+                </EmptyState>
+              )}
+            </div>
+          )}
+          {model.parts.length > 0 && (
+            <footer className={cx(BODY, "flex flex-col gap-3 border-t border-line-subtle pt-4 text-[12px] leading-snug text-fg-muted")}>
+              <div>
+                <SectionLabel>Part status</SectionLabel>
+                <dl className="mt-1 grid grid-cols-[max-content_minmax(0,1fr)] gap-x-3 gap-y-1.5">
+                  {PART_TRUST_STATES.map((t) => (
+                    <div key={t} className="contents">
+                      <dt className="flex items-center">
+                        <PartStatusDot trust={t} label />
+                      </dt>
+                      <dd>{PART_TRUST_TEXT[t].meaning}</dd>
+                    </div>
+                  ))}
+                </dl>
+              </div>
+              <div>
+                <SectionLabel>Updates</SectionLabel>
+                <p className="mt-1 max-w-[80ch]">{UPDATE_EXPLAINED}</p>
+              </div>
+            </footer>
+          )}
+        </ScrollArea>
+      </div>
+    </PartsSurface>
+  );
+}

package/src/parts/SettingsPage.tsx

@@ -0,0 +1,268 @@
+/**
+ * Protoboard's settings, as a page in its own tab (PB-930): the account, the
+ * version in use, the agents on this machine with Connect and Disconnect, the
+ * entry for any other MCP client, and a way into VS Code's own settings (they
+ * are linked, not repeated). A list of sections, so it can grow.
+ */
+import { useState, type ReactNode } from "react";
+import { Icon, ScrollArea, cx } from "@deltarobotics/uhd-viewer/components";
+import { AccountCard } from "./LibrariesManager.js";
+import type { AgentRowModel, SettingsActions, SettingsModel } from "./model.js";
+import { PartsSurface } from "./Surface.js";
+import { BODY, Button, Card, RowAction, StatusText, type Tone } from "./ui.js";
+
+const STATUS: Record<AgentRowModel["status"], { tone: Tone; label: string }> = {
+  connected: { tone: "ok", label: "Connected" },
+  outdated: { tone: "warning", label: "Update needed" },
+  "not-connected": { tone: "neutral", label: "Not connected" },
+  unreadable: { tone: "error", label: "Cannot read its file" },
+};
+
+const DETAIL: Record<NonNullable<AgentRowModel["detailTone"]>, string> = { neutral: "text-fg-muted", ok: "text-ok", warning: "text-warning", error: "text-error" };
+
+/** A section: its heading, a line about it, then its content. */
+function Section({ title, note, right, children }: { title: string; note?: ReactNode; right?: ReactNode; children: ReactNode }) {
+  return (
+    <section className="flex flex-col gap-2" aria-label={title}>
+      <div className={cx(BODY, "flex items-end gap-3")}>
+        <div className="min-w-0 flex-1">
+          <h2 className="text-[15px] font-semibold text-fg">{title}</h2>
+          {note && <p className="mt-0.5 text-[12.5px] leading-snug text-fg-muted">{note}</p>}
+        </div>
+        {right}
+      </div>
+      {children}
+    </section>
+  );
+}
+
+const ROW = "grid grid-cols-[minmax(150px,1.2fr)_minmax(150px,0.9fr)_minmax(160px,2fr)_184px] items-center gap-3 max-[720px]:grid-cols-[minmax(0,1fr)_auto]";
+
+function AgentRow({ agent, actions }: { agent: AgentRowModel; actions: SettingsActions }) {
+  const s = STATUS[agent.status];
+  const connected = agent.status === "connected";
+  return (
+    <div className={cx(BODY, "border-t border-line-subtle px-4 py-2 text-[13px]")} data-agent={agent.id} data-status={agent.status}>
+      <div className={cx(ROW, "min-h-8")}>
+        <div className="flex min-w-0 flex-col gap-0.5">
+          <span className="flex min-w-0 items-center gap-2">
+            <Icon name="bot" size={15} strokeWidth={1.75} className="shrink-0 text-fg-muted" aria-hidden />
+            <span className="truncate text-fg">{agent.name}</span>
+          </span>
+          <span className="hidden max-[720px]:block">
+            <StatusText tone={s.tone} plain>
+              {s.label}
+            </StatusText>
+          </span>
+          <span className="hidden min-w-0 items-center gap-1 max-[720px]:flex">
+            <span className="truncate font-ui text-[11.5px] text-fg-muted" title={agent.file}>
+              {agent.file}
+            </span>
+            <RowAction icon="file-braces" label="Open the configuration file" onClick={() => actions.openFile(agent.id)} />
+          </span>
+        </div>
+        <span className="min-w-0 truncate max-[720px]:hidden">
+          <StatusText tone={s.tone} plain>
+            {s.label}
+          </StatusText>
+        </span>
+        <span className="flex min-w-0 items-center gap-1 max-[720px]:hidden">
+          <span className="truncate font-ui text-[12px] text-fg-muted" title={agent.file}>
+            {agent.file}
+          </span>
+          <RowAction icon="file-braces" label="Open the configuration file" onClick={() => actions.openFile(agent.id)} />
+        </span>
+        <span className="flex items-center justify-end gap-1.5">
+          {agent.status === "outdated" && (
+            <Button size="sm" kind="primary" icon={agent.working ? "loader" : "refresh-cw"} disabled={agent.working} onClick={() => actions.connect(agent.id)}>
+              Update
+            </Button>
+          )}
+          {agent.status === "not-connected" && agent.manual && (
+            <Button size="sm" icon="copy" onClick={() => actions.copy(agent.manual!, "command")}>
+              Copy command
+            </Button>
+          )}
+          {agent.status === "not-connected" && !agent.manual && (
+            <Button size="sm" kind="primary" icon={agent.working ? "loader" : "plug"} disabled={agent.working} onClick={() => actions.connect(agent.id)}>
+              Connect
+            </Button>
+          )}
+          {(connected || agent.status === "outdated") && (
+            <Button size="sm" icon={agent.working && connected ? "loader" : undefined} disabled={agent.working} onClick={() => actions.disconnect(agent.id)}>
+              Disconnect
+            </Button>
+          )}
+          {agent.status === "unreadable" && (
+            <Button size="sm" icon="file-braces" onClick={() => actions.openFile(agent.id)}>
+              Open file
+            </Button>
+          )}
+        </span>
+      </div>
+      {agent.detail && <p className={cx("pt-0.5 pb-1 pl-[23px] text-[12px] leading-snug break-words", DETAIL[agent.detailTone ?? "neutral"])}>{agent.detail}</p>}
+    </div>
+  );
+}
+
+/** The entry for another client: the form picked, as text to copy. */
+function OtherClients({ model, actions }: { model: NonNullable<SettingsModel["other"]>; actions: SettingsActions }) {
+  const [form, setForm] = useState(model.forms[0]?.id);
+  const shown = model.forms.find((f) => f.id === form) ?? model.forms[0];
+  return (
+    <Card className={cx(BODY, "flex flex-col gap-3 px-4 py-3 text-[13px] text-fg")}>
+      <ol className="flex flex-col gap-1 text-[12.5px] leading-snug text-fg-muted">
+        {model.steps.map((s, i) => (
+          <li key={s} className="flex gap-2">
+            <span className="shrink-0 font-ui text-fg-faint">{i + 1}</span>
+            <span>{s}</span>
+          </li>
+        ))}
+      </ol>
+      {shown && (
+        <div className="flex flex-col gap-1.5">
+          <div className="flex flex-wrap items-center gap-1.5">
+            <div role="tablist" aria-label="Format" className="flex flex-wrap items-center gap-1">
+              {model.forms.map((f) => (
+                <button
+                  key={f.id}
+                  type="button"
+                  role="tab"
+                  aria-selected={f.id === shown.id}
+                  onClick={() => setForm(f.id)}
+                  className={cx(
+                    "h-6 cursor-pointer rounded-[4px] border px-2 text-[12px] whitespace-nowrap",
+                    f.id === shown.id ? "border-[var(--pb-control-border)] bg-active text-fg" : "border-transparent text-fg-muted hover:bg-hover hover:text-fg",
+                    "outline-1 -outline-offset-1 outline-contrast focus-visible:outline focus-visible:outline-focus",
+                  )}
+                >
+                  {f.label}
+                </button>
+              ))}
+            </div>
+            <span className="ml-auto">
+              <RowAction icon="copy" label={`Copy the ${shown.label}`} onClick={() => actions.copy(shown.text, shown.label)} />
+            </span>
+          </div>
+          <ScrollArea className="max-h-[260px] rounded-[4px] border border-line bg-sunken" contentClassName="p-3">
+            <pre className="m-0 font-ui text-[12px] leading-relaxed whitespace-pre text-fg" data-form={shown.id}>
+              {shown.text}
+            </pre>
+          </ScrollArea>
+        </div>
+      )}
+    </Card>
+  );
+}
+
+export function SettingsPage({ model, actions }: { model: SettingsModel; actions: SettingsActions }) {
+  const a = model.agents;
+  return (
+    <PartsSurface place="editor">
+      <ScrollArea className="size-full" contentClassName="mx-auto flex max-w-[980px] min-w-[300px] flex-col gap-7 px-10 pt-7 pb-12 max-[640px]:px-4">
+        <header className={BODY}>
+          <h1 className="text-[22px] font-semibold text-fg">Protoboard settings</h1>
+        </header>
+
+        <Section title="Account">
+          <AccountCard account={model.account} actions={actions} />
+        </Section>
+
+        <Section title="Protoboard">
+          <Card className={cx(BODY, "flex flex-col text-[13px] text-fg")}>
+            <div className="flex min-h-10 items-center gap-3 px-4 py-2">
+              <span className="w-[88px] shrink-0 text-fg-muted">Version</span>
+              <span className="min-w-0 flex-1">
+                <span className="font-ui">{model.about.version}</span>
+              </span>
+            </div>
+            <div className="flex min-h-10 items-center gap-3 border-t border-line-subtle px-4 py-2">
+              <span className="w-[88px] shrink-0 text-fg-muted">CLI</span>
+              <span className="min-w-0 flex-1">
+                {model.about.problem ? (
+                  <span className="text-warning">{model.about.problem}</span>
+                ) : (
+                  <>
+                    <span className="font-ui text-[12px] break-all">{model.about.cli ?? "—"}</span>
+                    {model.about.cliFrom && <span className="text-fg-muted"> · {model.about.cliFrom}</span>}
+                  </>
+                )}
+              </span>
+              {actions.showLog && <RowAction icon="scroll-text" label="Show the Protoboard log" onClick={actions.showLog} />}
+            </div>
+          </Card>
+        </Section>
+
+        <Section
+          title="Agents"
+          note="Connect an agent to give it Protoboard's tools."
+          right={<RowAction icon="refresh-cw" label="Look for agents again" onClick={actions.refresh} />}
+        >
+          <Card className="overflow-hidden">
+            <div className={cx(ROW, BODY, "h-9 px-4 text-[12px] font-medium text-fg-muted")}>
+              <span>Agent</span>
+              <span className="max-[720px]:hidden">Protoboard</span>
+              <span className="max-[720px]:hidden">Configuration</span>
+              <span />
+            </div>
+            {a.rows.map((r) => (
+              <AgentRow key={r.id} agent={r} actions={actions} />
+            ))}
+            {!a.rows.length && (
+              <p className={cx(BODY, "border-t border-line-subtle px-4 py-3 text-[13px]", a.state === "failed" ? "text-warning" : "text-fg-muted")}>
+                {a.state === "loading" ? "Looking for agents…" : a.state === "failed" ? (a.problem ?? "The agents could not be listed.") : "No agents found. Use the entry below."}
+              </p>
+            )}
+          </Card>
+          {a.notFound.length > 0 && <p className={cx(BODY, "text-[12px] leading-snug text-fg-muted")}>Not found on this machine: {a.notFound.join(", ")}.</p>}
+        </Section>
+
+        {model.other && (
+          <Section title="Other MCP clients" note="Add this entry to any other agent's MCP configuration.">
+            <OtherClients model={model.other} actions={actions} />
+          </Section>
+        )}
+
+        <Section title="More settings">
+          <Card className={cx(BODY, "flex flex-col text-[13px] text-fg")}>
+            <div className="flex min-h-11 items-center gap-3 px-4 py-2">
+              <Icon name="settings" size={15} strokeWidth={1.75} className="shrink-0 text-fg-muted" aria-hidden />
+              <span className="min-w-0 flex-1">
+                VS Code settings
+                <span className="block text-[12px] text-fg-muted">CLI and Node.js paths, dev server port, check on save</span>
+              </span>
+              <Button size="sm" icon="external-link" onClick={actions.openVsCodeSettings}>
+                Open
+              </Button>
+            </div>
+            {actions.openLibraries && (
+              <div className="flex min-h-11 items-center gap-3 border-t border-line-subtle px-4 py-2">
+                <Icon name="library-big" size={15} strokeWidth={1.75} className="shrink-0 text-fg-muted" aria-hidden />
+                <span className="min-w-0 flex-1">
+                  Libraries
+                  <span className="block text-[12px] text-fg-muted">Where parts come from, in search order</span>
+                </span>
+                <Button size="sm" icon="external-link" onClick={actions.openLibraries}>
+                  Open
+                </Button>
+              </div>
+            )}
+            {actions.run &&
+              (model.links ?? []).map((l) => (
+                <div key={l.id} data-settings-link={l.id} className="flex min-h-11 items-center gap-3 border-t border-line-subtle px-4 py-2">
+                  <Icon name={l.icon} size={15} strokeWidth={1.75} className="shrink-0 text-fg-muted" aria-hidden />
+                  <span className="min-w-0 flex-1">
+                    {l.label}
+                    <span className="block text-[12px] break-words text-fg-muted">{l.note}</span>
+                  </span>
+                  <Button size="sm" icon="external-link" className="shrink-0" onClick={() => actions.run!(l.id)}>
+                    {l.action}
+                  </Button>
+                </div>
+              ))}
+          </Card>
+        </Section>
+      </ScrollArea>
+    </PartsSurface>
+  );
+}

package/src/parts/Surface.tsx

@@ -0,0 +1,51 @@
+/**
+ * The page a parts view draws on: its background (the sidebar's or the
+ * editor's), the card surface, the body face and the picture matte, all from
+ * the theme's tokens. High contrast draws no washes: cards are the page with
+ * an outline.
+ */
+import type { CSSProperties, ReactNode } from "react";
+import { cx, useTheme } from "@deltarobotics/uhd-viewer/components";
+import { CarouselStyles } from "./carousel.js";
+import { PartStatusStyles } from "./PartStatus.js";
+
+export type Place = "sidebar" | "editor";
+
+export function PartsSurface({ place, children, className }: { place: Place; children: ReactNode; className?: string }) {
+  const { theme } = useTheme();
+  const hc = theme.scheme.startsWith("high-contrast");
+  const light = theme.scheme.includes("light");
+  // Protoboard's themes have their own card and sidebar shades (Alpha's); a VS Code theme gives the sidebar's colour,
+  // and cards are a light wash of the text over the editor's background
+  const own = theme.id.startsWith("protoboard");
+  const sidebar = own ? "color-mix(in oklab, var(--uhd-text) 2.5%, var(--uhd-background))" : "var(--uhd-surface)";
+  const bg = place === "sidebar" ? sidebar : "var(--uhd-background)";
+  const card = own ? "var(--uhd-surface)" : "color-mix(in oklab, var(--uhd-text) 7%, var(--uhd-background))";
+  const style = {
+    "--pb-bg": bg,
+    "--pb-card": hc ? bg : card,
+    "--pb-row-head": hc ? bg : `color-mix(in oklab, var(--uhd-text) 5%, ${card})`,
+    // the outline of buttons, chips and inputs: a quiet line in every theme, the contrast border in high contrast
+    "--pb-control-border": hc ? "var(--uhd-contrast-border)" : "color-mix(in oklab, var(--uhd-text) 22%, transparent)",
+    // pictures (PB-917): a render with a transparent background on the page's own surface, a little lifted; a photo
+    // shot on white on a light tile it melts into (multiply), white in light themes, a soft grey in dark ones;
+    // high contrast keeps white tiles, outlined by the card
+    "--pb-thumb-clear": hc ? bg : `color-mix(in oklab, var(--uhd-text) ${light ? 3 : 6}%, ${card})`,
+    "--pb-thumb-tile": hc || light ? "#ffffff" : "color-mix(in srgb, #ffffff 86%, var(--uhd-background))",
+    "--pb-thumb-blend": hc ? "normal" : "multiply",
+    "--pb-thumb-fg": "#8a8a8a",
+    "--pb-font-body": `var(--vscode-font-family, "Inter", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif)`,
+    // the severity hues are bright for dark pages; as text on a light page they need the deeper shade of the same hue (WCAG AA on white)
+    ...(light ? { "--uhd-severity-warning": "#a16207", "--uhd-severity-info": "#0369a1", "--uhd-severity-ok": "#15803d", "--uhd-severity-error": "#dc2626" } : {}),
+    background: bg,
+  } as CSSProperties;
+  return (
+    <div className={cx("pb-parts relative size-full min-h-0 min-w-0 overflow-hidden text-fg", className)} style={style}>
+      {/* the part status colours (PB-932), for every dot drawn on this page */}
+      <PartStatusStyles />
+      {/* the carousels' fade and hover-revealed controls (PB-918) */}
+      <CarouselStyles />
+      {children}
+    </div>
+  );
+}

package/src/parts/Windowed.tsx

@@ -0,0 +1,70 @@
+/**
+ * A list's window (PB-918): a card far from what is on screen is kept as an
+ * empty box of its own size, and drawn again when the list scrolls near it,
+ * so a list of several hundred parts scrolls like a short one. It works in a
+ * grid, a column and a grouped page alike, since each card decides for
+ * itself; the list's scroll position and height never change, because the
+ * box keeps the size the card had.
+ *
+ * Where there is no IntersectionObserver (a test's DOM), every card is drawn.
+ */
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { cx } from "@deltarobotics/uhd-viewer/components";
+
+/** How far beyond the visible part of the list cards stay drawn. */
+const MARGIN = "700px 0px";
+
+type Seen = (visible: boolean) => void;
+const observers = new WeakMap<Element | Document, { io: IntersectionObserver; seen: WeakMap<Element, Seen> }>();
+
+/** One observer per scrolling list, shared by its cards. */
+function observe(el: Element, fn: Seen): () => void {
+  // the list scrolls inside a Radix viewport: the margin has to be measured against it, not the page
+  const root = el.closest("[data-radix-scroll-area-viewport]");
+  const key = root ?? document;
+  let o = observers.get(key);
+  if (!o) {
+    const seen = new WeakMap<Element, Seen>();
+    const io = new IntersectionObserver((entries) => entries.forEach((e) => seen.get(e.target)?.(e.isIntersecting)), { root, rootMargin: MARGIN });
+    o = { io, seen };
+    observers.set(key, o);
+  }
+  o.seen.set(el, fn);
+  o.io.observe(el);
+  return () => {
+    o.io.unobserve(el);
+    o.seen.delete(el);
+  };
+}
+
+export interface WindowedProps {
+  /** The card's height before it has been drawn once. */
+  height: number;
+  /** Drawn from the start (the first screenful), so the list does not open on empty boxes. */
+  eager?: boolean;
+  className?: string;
+  children: ReactNode;
+}
+
+export function Windowed({ height, eager, className, children }: WindowedProps) {
+  const can = typeof IntersectionObserver !== "undefined";
+  const ref = useRef<HTMLDivElement>(null);
+  const [shown, setShown] = useState(!can || !!eager);
+  const size = useRef(height);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || !can) return;
+    return observe(el, (visible) => {
+      // a card that holds the keyboard focus stays drawn, wherever the list is scrolled to
+      if (!visible && el.contains(document.activeElement)) return;
+      // remember the card's size as it leaves, so its box holds the same room
+      if (!visible && el.firstElementChild) size.current = el.offsetHeight || size.current;
+      setShown(visible);
+    });
+  }, [can]);
+  return (
+    <div ref={ref} data-windowed={shown ? "shown" : "away"} className={cx("min-w-0", className)} style={shown ? undefined : { height: size.current }}>
+      {shown ? children : null}
+    </div>
+  );
+}