@protoboardai/views 0.0.0-stage → 0.2.1

package/src/inspector/SelectionInspector.tsx

@@ -0,0 +1,392 @@
+/**
+ * The Inspector's selection (PB-940; design A "Linear-tight", PB-1042, with
+ * expandable interface cards): one column, no boxes. The
+ * header is the shell's: the kind's icon, the name, what it is and which
+ * part, the part's status, and a summary row (the findings, the price, how
+ * many modules are below, the quick actions). Then sections, each a 28 px
+ * header row (chevron, title, count or summary) over its body, separated by
+ * 1 px dividers: the viewer's own (`SelectionDetails` of
+ * @deltarobotics/uhd-viewer: Parameters, Interfaces as slot cards that
+ * expand, Artifacts, and the secondary ones closed), then the shell's
+ * (Checks, Children, Links, Sourcing, Used in…). Arrow keys move through the
+ * section headers and the cards.
+ *
+ * The shell gives the card, the project's bundle and the files the page may
+ * load. Nothing is loaded that the card does not name: pictures are lazy, a
+ * model is drawn only when the shell marks it small enough.
+ */
+import { useCallback, useMemo, type CSSProperties } from "react";
+import {
+  ArtifactGrid,
+  DetailsSection,
+  HostContext,
+  Icon,
+  IconButton,
+  ScrollArea,
+  SECTION_LOOK,
+  SelectionDetails,
+  Sections,
+  cx,
+  useShowAll,
+  useTheme,
+  type ArtifactCardModel,
+  type HostActions,
+} from "@deltarobotics/uhd-viewer/components";
+import { PartStatusDot } from "../parts/PartStatus.js";
+import { PartsSurface } from "../parts/Surface.js";
+import { RowAction } from "../parts/ui.js";
+import type { InspectorActions, InspectorCard, InspectorChip, InspectorContent, InspectorRow, InspectorSection } from "./model.js";
+
+type Bundle = NonNullable<Parameters<typeof SelectionDetails>[0]["bundle"]>;
+type Definitions = NonNullable<Parameters<typeof SelectionDetails>[0]["definitions"]>;
+
+const TONE: Record<string, string> = { error: "text-error", warning: "text-warning", info: "text-info", ok: "text-ok" };
+const SEVERITY_ICON: Record<string, string> = { error: "circle-x", warning: "triangle-alert", info: "info" };
+
+/** The header's look (design A), in one place. */
+export const INSPECTOR_HEADER_LOOK = {
+  header: "border-b border-line-subtle px-3.5 pt-3 pb-2.5",
+  tile: "grid size-9 shrink-0 place-items-center rounded-[8px] border border-line bg-[color-mix(in_oklab,var(--uhd-text)_6%,transparent)] text-fg",
+  title: "truncate text-[14px] leading-[1.3] font-semibold text-fg",
+  subtitle: "truncate text-[11px] leading-[1.4] text-fg-muted",
+  status: "inline-flex h-[22px] shrink-0 items-center gap-1.5 rounded-full bg-[color-mix(in_oklab,var(--uhd-text)_8%,transparent)] px-2 text-[11px] leading-none text-fg",
+  summary: "mt-2.5 flex min-h-6 flex-wrap items-center gap-x-2.5 gap-y-1 text-[11.5px] leading-none text-fg-muted",
+  divider: "h-3.5 w-px shrink-0 bg-line",
+} as const;
+
+/** A small outlined label: the part's tier, its sync state, a quantity, stale outputs. */
+function Chip({ chip }: { chip: InspectorChip }) {
+  return (
+    <span
+      data-tooltip={chip.title}
+      data-tooltip-clamp={chip.title && chip.title.length > 40 ? "4" : undefined}
+      data-blank={chip.blank ? "" : undefined}
+      className={cx(
+        "inline-flex h-[18px] max-w-full shrink-0 items-center gap-1.5 rounded-full border px-1.5 text-[10.5px] leading-none whitespace-nowrap",
+        chip.tone && TONE[chip.tone] ? cx(TONE[chip.tone], "border-current") : "border-[var(--pb-control-border)] text-fg-muted",
+        chip.blank && "border-dashed border-fg-muted",
+        "outline-1 -outline-offset-1 outline-contrast",
+      )}
+    >
+      {chip.status && <PartStatusDot trust={chip.status} blank={chip.blank} size={7} />}
+      <span className="truncate">{chip.text}</span>
+    </span>
+  );
+}
+
+/** The part's status, at the title's right: its dot and its name (Local, Unverified, Verified, Official). */
+function StatusChip({ chip }: { chip: InspectorChip }) {
+  return (
+    <span data-status-chip="" data-tooltip={chip.title} data-tooltip-clamp="4" className={cx(INSPECTOR_HEADER_LOOK.status, chip.blank && "border border-dashed border-fg-muted bg-transparent")}>
+      {chip.status && <PartStatusDot trust={chip.status} blank={chip.blank} size={7} />}
+      <span className="truncate">{chip.text}</span>
+    </span>
+  );
+}
+
+/** The findings here and below, in the summary row: a count per severity with its icon, or "No findings". */
+function Counts({ counts }: { counts: InspectorCard["counts"] }) {
+  const total = counts.error + counts.warning + counts.info;
+  const label = `${counts.error} blocking, ${counts.warning} warnings, ${counts.info} info`;
+  if (!total)
+    return (
+      <span aria-label="No findings" className="inline-flex items-center gap-1 text-ok">
+        <Icon name="circle-check" size={13} strokeWidth={1.75} aria-hidden />
+        <span className="text-fg-muted">No findings</span>
+      </span>
+    );
+  return (
+    <span role="img" aria-label={`Findings here and below: ${label}`} data-tooltip={`Findings here and below: ${label}`} className="inline-flex items-center gap-2">
+      {(["error", "warning", "info"] as const).map((sev) =>
+        counts[sev] ? (
+          <span key={sev} className={cx("inline-flex items-center gap-1 tabular-nums", TONE[sev])}>
+            <Icon name={SEVERITY_ICON[sev]} size={13} strokeWidth={1.75} aria-hidden />
+            <span className="text-fg">{counts[sev]}</span>
+          </span>
+        ) : null,
+      )}
+    </span>
+  );
+}
+
+/** A row of a section: a module, a link's end, a finding (its message and its code under it), a fact. */
+function Row({ row, actions }: { row: InspectorRow; actions: InspectorActions }) {
+  const act = row.action;
+  const go = act ? () => (act.type === "focus" ? actions.focus(act.path) : actions.finding(act.key)) : undefined;
+  const finding = act?.type === "finding" || row.code;
+  return (
+    <div
+      role={go ? "button" : undefined}
+      tabIndex={go ? 0 : undefined}
+      data-tooltip={`${row.label}${row.detail ? ` · ${row.detail}` : ""}`}
+      data-tooltip-clamp="3"
+      data-tooltip-delay="600"
+      data-row-finding={row.code}
+      onClick={go}
+      onKeyDown={
+        go &&
+        ((e) => {
+          if (e.target === e.currentTarget && (e.key === "Enter" || e.key === " ")) {
+            e.preventDefault();
+            go();
+          }
+        })
+      }
+      className={cx(
+        "group/row -mx-1 flex gap-2 rounded-[4px] px-1 text-[11.5px] text-fg",
+        finding ? "items-start py-1" : "min-h-[24px] items-center",
+        go && "cursor-pointer hover:bg-hover focus-visible:outline focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-focus",
+      )}
+    >
+      <Icon name={row.icon} size={13} strokeWidth={1.75} className={cx("shrink-0", finding && "mt-px", row.tone && TONE[row.tone] ? TONE[row.tone] : "text-fg-muted")} aria-hidden />
+      {finding ? (
+        <span className="flex min-w-0 flex-1 flex-col gap-0.5">
+          <span className="leading-[1.4]">{row.label}</span>
+          {row.code && <span className="font-code text-[9.5px] leading-none text-fg-faint">{row.code}</span>}
+        </span>
+      ) : (
+        <>
+          <span className="min-w-0 flex-1 truncate">{row.label}</span>
+          {row.detail && <span className="max-w-[50%] min-w-0 shrink truncate text-[11px] text-fg-muted">{row.detail}</span>}
+        </>
+      )}
+      {(row.chips ?? []).map((c) => (
+        <Chip key={c.text} chip={c} />
+      ))}
+      {act?.type === "finding" && (
+        <span className="flex shrink-0 opacity-0 group-focus-within/row:opacity-100 group-hover/row:opacity-100">
+          <RowAction icon="circle-help" label={`Explain ${row.code ?? "this finding"}`} onClick={() => actions.explain(act.key)} />
+        </span>
+      )}
+    </div>
+  );
+}
+
+/** One of the shell's sections, in the details' look: a header row, closed when secondary, "Show all N" past its limit. */
+function HostSection({ section, actions }: { section: InspectorSection; actions: InspectorActions }) {
+  const showAll = useShowAll(section.rows.length, section.limit ?? Number.POSITIVE_INFINITY);
+  const rows = showAll.limit !== undefined ? section.rows.slice(0, showAll.limit) : section.rows;
+  return (
+    <DetailsSection id={`host:${section.title}`} title={section.title} count={section.count} summary={section.summary} aside={showAll.aside} defaultOpen={!section.collapsed}>
+      {rows.map((r, i) => (
+        <Row key={`${r.label}-${i}`} row={r} actions={actions} />
+      ))}
+    </DetailsSection>
+  );
+}
+
+/**
+ * The way to the code (the 2026-10-08 first builds, D7): the open-source
+ * action drawn with the name of the file it opens, so it is seen without
+ * hovering; the tooltip says the whole path. It comes first among the actions.
+ */
+function SourceAction({ source, onOpen }: { source: { file: string; line?: number }; onOpen: () => void }) {
+  const name = source.file.split("/").pop() ?? source.file;
+  const at = `${source.file}${source.line ? `:${source.line}` : ""}`;
+  return (
+    <button
+      type="button"
+      data-action="source"
+      aria-label={`Open source: ${at}`}
+      data-tooltip={`Open source: ${at}`}
+      data-tooltip-clamp={at.length > 40 ? "3" : undefined}
+      onClick={onOpen}
+      className={cx(
+        "inline-flex h-6 max-w-full min-w-0 cursor-pointer items-center gap-1.5 rounded-[4px] px-1.5 text-[11px] leading-none text-fg",
+        "hover:bg-hover focus-visible:outline focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-focus",
+      )}
+    >
+      <Icon name="file-code" size={14} strokeWidth={1.75} className="shrink-0 text-link" aria-hidden />
+      <span className="min-w-0 truncate font-code">
+        {name}
+        {source.line ? <span className="text-fg-muted">:{source.line}</span> : null}
+      </span>
+    </button>
+  );
+}
+
+/** Cards outside the viewer's details open through the same host actions. */
+function HostCards({ host, children }: { host: HostActions; children: React.ReactNode }) {
+  return <HostContext.Provider value={host}>{children}</HostContext.Provider>;
+}
+
+/**
+ * On a light page the viewer's details write in the link-state hues (a part's audit, its assumptions, a link's
+ * diagnostics), which are bright for dark pages: yellow on white is 1.4:1. They take the deeper shades the parts
+ * views' surface gives the severities there (PB-900), the same hue for the same meaning; dark pages keep the hues.
+ */
+const LIGHT_STATES = {
+  "--uhd-drc-configured": "var(--uhd-severity-ok)",
+  "--uhd-drc-partial": "var(--uhd-severity-warning)",
+  "--uhd-drc-incompatible": "var(--uhd-severity-error)",
+  // the grey of "not configured" as text: the muted text colour
+  "--uhd-drc-unconfigured": "var(--uhd-text-muted)",
+} as CSSProperties;
+
+export interface SelectionInspectorProps {
+  content: InspectorContent | undefined;
+  /** The project's bundle (loaded by the shell from `content.bundle`). */
+  bundle?: unknown;
+  actions: InspectorActions;
+}
+
+/** The header (design A): icon, name, what it is, the status at the right, then the summary row with the quick actions. */
+function Header({ card, actions }: { card: InspectorCard; actions: InspectorActions }) {
+  const a = card.actions;
+  const status = card.chips.find((c) => c.status);
+  // the kind is said in the subtitle; the other chips (tier, sync, quantity, stale outputs) stay small under it
+  const kindChip = !card.kindLabel ? card.chips.find((c) => !c.status && !c.tone && c === card.chips[0]) : undefined;
+  const kind = card.kindLabel ?? kindChip?.text;
+  const rest = card.chips.filter((c) => c !== status && c !== kindChip);
+  const subtitle = [kind, card.subtitle].filter(Boolean).join(" · ");
+  const findingsShown = (card.kind !== "part" && card.kind !== "interface") || card.counts.error + card.counts.warning + card.counts.info > 0;
+  const facts = [
+    ...(card.summary?.price ? [<span key="price" className="tabular-nums text-fg" data-summary="price">{card.summary.price}</span>] : []),
+    ...(card.summary?.children ? [<span key="children" data-summary="children">{`${card.summary.children} ${card.summary.children === 1 ? "child" : "children"}`}</span>] : []),
+  ];
+  return (
+    <header className={INSPECTOR_HEADER_LOOK.header}>
+      <div className="flex items-start gap-2.5">
+        <span aria-hidden className={INSPECTOR_HEADER_LOOK.tile}>
+          <Icon name={card.icon} size={18} strokeWidth={1.6} />
+        </span>
+        <div className="min-w-0 flex-1 pt-px">
+          <h1 data-tooltip={card.title} data-tooltip-clamp="3" className={cx("m-0", INSPECTOR_HEADER_LOOK.title)}>
+            {card.title}
+          </h1>
+          {subtitle && (
+            <div data-tooltip={subtitle} data-tooltip-clamp="3" className={INSPECTOR_HEADER_LOOK.subtitle}>
+              {subtitle}
+            </div>
+          )}
+        </div>
+        {status && <StatusChip chip={status} />}
+      </div>
+      {rest.length > 0 && (
+        <div className="mt-2 flex flex-wrap gap-1">
+          {rest.map((c) => (
+            <Chip key={c.text} chip={c} />
+          ))}
+        </div>
+      )}
+      <div className={INSPECTOR_HEADER_LOOK.summary}>
+        {findingsShown && <Counts counts={card.counts} />}
+        {facts.map((f, i) => (
+          <span key={i} className="inline-flex items-center gap-2.5">
+            {(findingsShown || i > 0) && <span aria-hidden className={INSPECTOR_HEADER_LOOK.divider} />}
+            {f}
+          </span>
+        ))}
+        {/* the quick actions, at the right; they wrap under the facts in a narrow side bar */}
+        <div role="toolbar" aria-label="Selection actions" className="ml-auto flex min-w-0 flex-wrap items-center justify-end gap-0.5 empty:hidden">
+          {a.source && card.source && <SourceAction source={card.source} onOpen={() => actions.action("source")} />}
+          {a.focus && <IconButton size="sm" icon="crosshair" label={card.kind === "link" ? "Show the link in the viewer" : "Focus in the viewer"} onClick={() => actions.action("focus")} />}
+          {a.pair && <IconButton size="sm" icon="git-compare-arrows" label="Open the pair view in a tab" onClick={() => actions.action("pair")} />}
+          {a.detail && <IconButton size="sm" icon="panel-top-open" label="Open the part's page" onClick={() => actions.action("detail")} />}
+          {a.source && !card.source && <IconButton size="sm" icon="file-code" label="Open source" onClick={() => actions.action("source")} />}
+          {a.artifacts && <IconButton size="sm" icon="folder-open" label="Open artifact…" onClick={() => actions.action("artifacts")} />}
+          {a.operation && <IconButton size="sm" icon="play" label="Run operation…" onClick={() => actions.action("operation")} />}
+        </div>
+      </div>
+    </header>
+  );
+}
+
+export function SelectionInspector({ content, bundle, actions }: SelectionInspectorProps) {
+  const card = content && "card" in content ? content.card : undefined;
+  const details = card?.details;
+  const light = useTheme().theme.scheme.includes("light");
+  const resolve = useCallback((defId: string, filePath: string) => details?.files[`${defId}\n${filePath}`], [details]);
+  const host = useMemo<HostActions>(
+    () => ({
+      openArtifact: actions.openArtifact,
+      openLink: actions.openLink,
+      // nothing is loaded for a 3D preview here: a model is a card, drawn small only when the shell says it may be
+      artifactModels: "cards",
+      artifactPreview: (def, artifact) => details?.previews[`${def.id}#${artifact.id}`],
+      ...(actions.drawModel ? { drawModel: actions.drawModel } : {}),
+      // pictures come from the shell's own files only
+      remoteImages: false,
+      evidence: (defId) => details?.evidence?.[defId] as ReturnType<NonNullable<HostActions["evidence"]>>,
+    }),
+    [actions, details],
+  );
+  if (!card)
+    return (
+      <PartsSurface place="sidebar" className="bg-transparent!">
+        <div className="grid size-full place-items-center px-6" data-inspector-empty="">
+          <div className="flex max-w-[260px] flex-col items-center gap-2 text-center font-ui">
+            <span aria-hidden className={cx(INSPECTOR_HEADER_LOOK.tile, "text-fg-muted")}>
+              <Icon name="mouse-pointer-click" size={18} strokeWidth={1.6} />
+            </span>
+            <h1 className="m-0 text-[13px] font-semibold text-fg">Nothing selected</h1>
+            <p className="m-0 text-[11.5px] leading-[1.5] text-fg-muted">{content && "empty" in content ? content.empty : "Open a Protoboard project."}</p>
+          </div>
+        </div>
+      </PartsSurface>
+    );
+  // a part's picture that is not an artifact of its definition (a library's thumbnail)
+  const picture: ArtifactCardModel[] = details?.picture
+    ? [{ key: "picture", defId: card.part?.partId ?? "", title: card.title, kind: "image", group: "images", kindLabel: "Picture", source: card.part?.library, icon: "image", preview: { kind: "image", src: details.picture }, remote: false }]
+    : [];
+  const own: ArtifactCardModel[] = (card.artifacts ?? []).map((x) => ({
+    key: `${x.defId}#${x.artifactId}`,
+    defId: x.defId,
+    artifactId: x.artifactId,
+    title: x.title,
+    kind: "model",
+    group: "data",
+    kindLabel: x.kindLabel,
+    ...(x.format ? { format: x.format } : {}),
+    ...(x.source ? { source: x.source } : {}),
+    icon: x.icon,
+    ...(x.preview ? { preview: x.preview } : {}),
+    remote: false,
+  }));
+  return (
+    <PartsSurface place="sidebar" className="bg-transparent!">
+      <div className="contents" style={light ? LIGHT_STATES : undefined}>
+        {/* a new selection starts at its top (the scroll is the selection's, not the view's) */}
+        <ScrollArea key={`${card.kind}:${card.path}:${card.linkId ?? card.part?.partId ?? ""}:${card.title}`} className="size-full" contentClassName="min-w-[188px] pb-4 font-ui">
+          <Header card={card} actions={actions} />
+          <Sections label={`${card.title}: details`} className="pb-inspector-sections">
+            {picture.length > 0 && (
+              <HostCards host={host}>
+                <DetailsSection id="picture" title="Picture">
+                  <ArtifactGrid cards={picture} />
+                </DetailsSection>
+              </HostCards>
+            )}
+            {details && (
+              <SelectionDetails
+                className="pb-inspector-details"
+                bundle={bundle as Bundle | undefined}
+                definitions={details.definitions as Definitions | undefined}
+                target={details.target}
+                resolveArtifact={resolve}
+                host={host}
+                onSelect={actions.select}
+                onPair={() => actions.action("pair")}
+                {...(details.findings ? { findings: details.findings } : {})}
+                onFinding={actions.finding}
+                {...(actions.interfaceSource ? { onInterfaceSource: actions.interfaceSource } : {})}
+                {...(actions.connect ? { onConnect: actions.connect } : {})}
+                missing={bundle || details.target.kind === "definition" ? null : <p className={cx(SECTION_LOOK.body, "m-0 py-2 text-[11.5px] text-fg-muted")}>Reading the build…</p>}
+              />
+            )}
+            {own.length > 0 && (
+              <HostCards host={host}>
+                <DetailsSection id="host:artifacts" title="Artifacts" count={own.length}>
+                  <ArtifactGrid cards={own} />
+                </DetailsSection>
+              </HostCards>
+            )}
+            {card.sections.map((s) => (
+              <HostSection key={s.title} section={s} actions={actions} />
+            ))}
+          </Sections>
+        </ScrollArea>
+      </div>
+    </PartsSurface>
+  );
+}

package/src/inspector/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The Inspector's selection and the DRC panel as components (PB-940, PB-901):
+ * data in (model.ts), actions out. The VS Code shell draws them in native
+ * views; the selection is built on the viewer's own details
+ * (@deltarobotics/uhd-viewer `SelectionDetails`).
+ */
+export type * from "./model.js";
+export { SelectionInspector, type SelectionInspectorProps } from "./SelectionInspector.js";
+export { DrcPanel, type DrcPanelProps } from "./DrcPanel.js";

package/src/inspector/model.ts

@@ -0,0 +1,224 @@
+/**
+ * What the Inspector and the DRC panel draw (PB-940, PB-901): plain data a
+ * shell computes and hands to the components, and the actions they call back
+ * with. No React and no host API here: the VS Code extension's Node side
+ * builds these models and imports only this file's types.
+ */
+import type { PartTrust } from "../parts/part-status.js";
+
+/** A small outlined label: the kind, the part's tier, its status, a sync state. */
+export interface InspectorChip {
+  text: string;
+  /** A part status (PB-932): the chip starts with the state's dot. */
+  status?: PartTrust;
+  /** The part is a blank block (no part chosen yet): the dot is a dashed ring and the chip stands out with a dashed outline. */
+  blank?: boolean;
+  /** A severity or "ok": the chip takes its colour. */
+  tone?: string;
+  title?: string;
+}
+
+export interface InspectorRow {
+  /** Lucide icon name. */
+  icon: string;
+  label: string;
+  detail?: string;
+  chips?: InspectorChip[];
+  /** A dot in the severity colour. */
+  tone?: string;
+  /** What a click does. */
+  action?: { type: "focus"; path: string } | { type: "finding"; key: string };
+  /** A finding's code, under its message. */
+  code?: string;
+}
+
+export interface InspectorSection {
+  title: string;
+  count?: number;
+  rows: InspectorRow[];
+  /** What it holds, said in its header, shown open or closed ("FC · ESC · cable", "DolphinRC · $69.99"). */
+  summary?: string;
+  /** A secondary section: it starts closed (design A, PB-1042). */
+  collapsed?: boolean;
+  /** Rows shown before "Show all N" (the rest wait behind it). */
+  limit?: number;
+}
+
+/** A finding the interface cards show (on an interface or its links), with the canonical ids it is about. */
+export interface InspectorFinding {
+  key: string;
+  code: string;
+  message: string;
+  severity: "error" | "warning" | "info";
+  /** Links as the viewer selects them (`owner/local`, `local` at the root; a derived link by its own id), interfaces as `path:id`. */
+  refs: string[];
+}
+
+/** An interface card's request: the module, the interface, and the links that end on it as their module declares them. */
+export interface InspectorInterfaceRequest {
+  path: string;
+  interfaceId: string;
+  owner: string;
+  links: string[];
+}
+
+/** A picture a card may show: an image file, or a model small enough to draw. `F` is how a file is named: a path on the host's side, a URL on the page's. */
+export interface InspectorPreview<F = string> {
+  kind: "image" | "model";
+  src: F;
+}
+
+/**
+ * What the viewer's own details show for the selection, and the files they
+ * may load. `target` is uhd-viewer's `DetailsTarget`.
+ */
+export interface InspectorDetails<F = string> {
+  target: { kind: "module"; path: string } | { kind: "link"; owner: string; ids: string[] } | { kind: "definition"; id: string };
+  /** Artifact files the page may load, by `<definition id>\n<file path>`. */
+  files: Record<string, F>;
+  /** Pictures for artifacts that are not images themselves (a model's exported preview, or a small model to draw), by `<definition id>#<artifact id>`. */
+  previews: Record<string, InspectorPreview<F>>;
+  /** Evidence files by definition id (sources.json, verification.json), as read. */
+  evidence?: Record<string, { sources?: unknown[]; verification?: unknown }>;
+  /** Definitions that are not in the project's bundle (a library part shown on its own). */
+  definitions?: unknown[];
+  /** A picture of the part that is not one of its definition's artifacts (a library's thumbnail). */
+  picture?: F;
+  /** Web addresses the page may ask the host to open (artifact and evidence links of what is shown). */
+  links?: string[];
+  /** The findings the interface cards show, with the keys the DRC panel knows them by. */
+  findings?: InspectorFinding[];
+}
+
+/** An artifact card the shell builds itself (an interface's geometry), drawn like the details' cards. */
+export interface InspectorArtifact<F = string> {
+  defId: string;
+  artifactId: string;
+  title: string;
+  /** "Interface geometry", "3D model". */
+  kindLabel: string;
+  format?: string;
+  /** Where it comes from: a file's name. */
+  source?: string;
+  /** Lucide icon name. */
+  icon: string;
+  preview?: InspectorPreview<F>;
+}
+
+export type InspectorAction = "focus" | "source" | "artifacts" | "operation" | "pair" | "detail";
+
+/** The selection as a card: its header, state and sections; the viewer's details fill the middle. */
+export interface InspectorCard<F = string> {
+  kind: "module" | "link" | "level" | "part" | "interface";
+  /** Lucide icon name. */
+  icon: string;
+  title: string;
+  subtitle?: string;
+  /** What it is, before the subtitle: "Module", "Assembly", "Part", "Link" (design A: "Module · DolphinRC F405 V3 stack"). */
+  kindLabel?: string;
+  /** The header's summary row (design A): its price and how many modules are below it. */
+  summary?: { price?: string; children?: number };
+  chips: InspectorChip[];
+  /** Findings here (and below a module): the worst first. */
+  counts: { error: number; warning: number; info: number };
+  /** Sections of rows after the details: where a part is used, the modules below, the links it declares, its findings. */
+  sections: InspectorSection[];
+  /** Which actions apply (icon buttons in the header). */
+  actions: { focus: boolean; source: boolean; artifacts: boolean; operation: boolean; pair?: boolean; detail?: boolean };
+  /** The file the source action opens (project-relative), and the line when it is known: the action is drawn with the file's name. */
+  source?: { file: string; line?: number };
+  /** The instance path the actions are about ("" the root), and a link id for a link. */
+  path: string;
+  linkId?: string;
+  /** A part's card: the part and the library it comes from (its page opens from the card). */
+  part?: { partId: string; library?: string };
+  details?: InspectorDetails<F>;
+  /** Artifact cards of the card's own (an interface's geometry), before the sections. */
+  artifacts?: InspectorArtifact<F>[];
+}
+
+/** The project's UHD bundle as the page loads it: a URL, and a version that changes with every build. */
+export interface InspectorBundle {
+  src: string;
+  version: string;
+}
+
+export type InspectorContent<F = string> = { card: InspectorCard<F>; project: string; bundle?: InspectorBundle } | { empty: string; project?: string };
+
+export interface InspectorActions {
+  action(action: InspectorAction): void;
+  /** Show a module in the viewer. */
+  focus(path: string): void;
+  /** Something picked inside the details: canonical ids from the root. */
+  select(selection: { kind: "node" | "link"; id: string }): void;
+  finding(key: string): void;
+  explain(key: string): void;
+  openArtifact(defId: string, artifactId: string): void;
+  openLink(url: string): void;
+  /** Draws a model small, as a picture's URL (the shell's three.js). */
+  drawModel?(src: string): Promise<string>;
+  /** An interface card's Open in source: the line of its link, else of the interface. */
+  interfaceSource?(request: InspectorInterfaceRequest): void;
+  /** An open slot's Connect…: where a link from it is written. */
+  connect?(request: InspectorInterfaceRequest): void;
+}
+
+// ---- the DRC panel
+
+export interface DrcRowModel {
+  key: string;
+  code: string;
+  summary: string;
+  message: string;
+  reasons: string[];
+  module: string;
+  means?: string;
+  todo?: string;
+  validator: string;
+  sourceKind: string;
+  sourceLabel?: string;
+  hasSource: boolean;
+  /** A fix the extension can run for this finding (B6: Fetch Parts for a library part that was not fetched). */
+  fix?: { label: string; icon?: string };
+}
+
+export interface DrcLaneModel {
+  id: "blocking" | "warnings" | "info";
+  title: string;
+  total: number;
+  shown: number;
+  groups: { key: string; label: string; items: DrcRowModel[] }[];
+}
+
+export interface DrcQueryModel {
+  groupBy: "module" | "rule" | "source";
+  text: string;
+  severity: "all" | "error" | "warning";
+  info: boolean;
+}
+
+export interface DrcPanelModel {
+  state: "none" | "idle" | "running" | "failed";
+  project: string;
+  /** When the findings were produced, as a time of day. */
+  at?: string;
+  query: DrcQueryModel;
+  model?: {
+    lanes: DrcLaneModel[];
+    counts: { error: number; warning: number; info: number };
+    configured: { links: number; linksTotal: number; checksRan: number; checksSkipped: number };
+  };
+}
+
+export interface DrcPanelActions {
+  query(query: DrcQueryModel): void;
+  locate(key: string): void;
+  openSource(key: string): void;
+  explain(key: string): void;
+  /** Run the row's fix (`DrcRowModel.fix`). */
+  fix?(key: string): void;
+  refresh(): void;
+  /** Which rows are open and which groups are closed, kept by the shell across reloads. */
+  saved?: { expanded?: string[]; collapsed?: string[] };
+  save?(state: { expanded: string[]; collapsed: string[] }): void;
+}