@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/pages/ContextPage.tsx

@@ -9,6 +9,7 @@ import { staggerStyle } from "../lib/motion";
 import { CONTEXT_ANCHOR, EVENT_ANCHOR, LINKS_HERE, paths } from "../routes";
 import { Empty, PageHeader, SectionTitle } from "../components/PageHeader";
 import { Ident } from "../components/Ident";
+import { DocsLinks } from "../components/DocsLinks";
 import { ClassificationBadge } from "../components/primitives";
 import { KindIcon } from "../components/kind";
 import { RowActions } from "../components/RowActions";
@@ -37,6 +38,7 @@ export function ContextPage() {
   );
   const neutral = groupKind(context) !== "bounded-context";
   const showDomain = !neutral || aggregates.length > 0;
+  const hasModelGroups = aggregates.some(({ aggregate }) => aggregate.kind === "model-group");
   const toc: TocItem[] = [
     { id: CONTEXT_ANCHOR.services, label: neutral ? "Components" : "Services" },
     ...(showDomain
@@ -86,13 +88,14 @@ export function ContextPage() {
           {showDomain ? (
             <>
               <a href={`#${CONTEXT_ANCHOR.aggregates}`} className="rounded-control hover:text-ink">
-                <span className="tnum">{stats.aggregates}</span>{" "}{plural(stats.aggregates, "aggregate")}
+                <span className="tnum">{stats.aggregates}</span>{" "}{plural(stats.aggregates, hasModelGroups ? "group" : "aggregate")}
               </a>
               <a href={`#${CONTEXT_ANCHOR.events}`} className="rounded-control hover:text-ink">
                 <span className="tnum">{stats.events}</span>{" "}{plural(stats.events, "event")}
               </a>
             </>
           ) : null}
+          <DocsLinks name={context.name} />
         </div>
         {/* Who to ask about the whole domain, folded up from what its
             services' CODEOWNERS say - the context itself names nobody. The
@@ -173,7 +176,7 @@ export function ContextPage() {
                   <div className="mono mt-4 flex flex-wrap gap-x-4 text-muted">
                     {service.aggregates.length > 0 || componentKind(service) === "service" ? (
                       <Link to={`${paths.service(context.id, service.slug)}#svc-aggregates`} className="rounded-control hover:text-ink">
-                        <span className="tnum">{service.aggregates.length}</span>{" "}{plural(service.aggregates.length, "aggregate")}
+                        <span className="tnum">{service.aggregates.length}</span>{" "}{plural(service.aggregates.length, service.aggregates.some((aggregate) => aggregate.kind === "model-group") ? "group" : "aggregate")}
                       </Link>
                     ) : null}
                     <Link
@@ -234,11 +237,11 @@ export function ContextPage() {
               anchor={CONTEXT_ANCHOR.aggregates}
               right={
                 <span>
-                  every aggregate this domain owns, whichever service holds it
+                  {hasModelGroups ? "models grouped by their source application or aggregate" : "every aggregate this domain owns, whichever service holds it"}
                 </span>
               }
             >
-              Aggregates
+              {hasModelGroups ? "Aggregates and model groups" : "Aggregates"}
             </SectionTitle>
             {aggregates.length === 0 ? (
               <Empty>this domain owns nothing yet — only services</Empty>
@@ -264,7 +267,7 @@ export function ContextPage() {
                       {aggregate.name}
                     </Link>
                     <span className="meta">{service.slug}</span>
-                    <span className="meta">root {aggregate.root}</span>
+                    <span className="meta">{aggregate.kind === "model-group" ? "model group · boundary not specified" : `root ${aggregate.root}`}</span>
                     <RowActions
                       copy={aggregate.id}
                       reveal={aggregate.id}

package/src/pages/EventPage.tsx

@@ -48,6 +48,8 @@ interface SchemaRow extends Field {
   change?: Change;
   /** The type the previous version gave the field, when this one changed it. */
   from?: string;
+  /** The rules the previous version gave the field, when this one changed them; "" for none. */
+  rulesFrom?: string;
 }
 
 /** What the change column says, and in what colour. */
@@ -60,7 +62,7 @@ const CHANGE: Record<Change, { label: string; className: string; title: string }
   changed: {
     label: "changed",
     className: "text-declared",
-    title: "type changed in this version",
+    title: "changed in this version",
   },
   removed: {
     label: "removed",
@@ -69,13 +71,21 @@ const CHANGE: Record<Change, { label: string; className: string; title: string }
   },
 };
 
+/**
+ * What the previous version had, for the tooltip of a changed row: the type
+ * when it moved, the rules when they did. What the row has now is the row.
+ */
+function wasBefore(row: SchemaRow): string | null {
+  const parts: string[] = [];
+  if (row.from) parts.push(`was ${row.from}`);
+  if (row.rulesFrom !== undefined) parts.push(`rules were ${row.rulesFrom || "none"}`);
+  return parts.length ? `${parts.join(", ")} in the previous version` : null;
+}
+
 function ChangeMark({ row }: { row: SchemaRow }) {
   if (!row.change) return null;
   const mark = CHANGE[row.change];
-  const title =
-    row.change === "changed" && row.from
-      ? `was ${row.from} in the previous version`
-      : mark.title;
+  const title = (row.change === "changed" && wasBefore(row)) || mark.title;
   return (
     <span
       className={`mono inline-flex items-center gap-1 ${mark.className}`}

package/src/pages/FlowDetail.tsx

@@ -30,6 +30,8 @@ import {
   isCrossContext,
 } from "../flow/cross-context";
 import { StepRail } from "../flow/StepRail";
+import { RecordingsChip } from "../flow/Recordings";
+import { stepsShownBy } from "../flow/examples";
 import { FlowTable } from "../flow/FlowTable";
 import { FlowToolbar } from "../flow/FlowToolbar";
 import { buildChapters, groupRows } from "../flow/chapters";
@@ -127,6 +129,8 @@ export function FlowDetail() {
   const [hoverStep, setHoverStep] = useState<string | null>(null);
   /** The step LikeC4's walkthrough is on, when it is running. */
   const [walkStep, setWalkStep] = useState<string | null>(null);
+  /** The recording whose steps are lit on the picture, when one is chosen. */
+  const [exampleId, setExampleId] = useState<string | null>(null);
 
   const canvas = useRef<CanvasHandle | null>(null);
 
@@ -264,6 +268,17 @@ export function FlowDetail() {
   // watching rather than pointing, and the rail's job is to follow.
   const activeId = walkStep ?? selectedStepId ?? focusedMatch;
 
+  /**
+   * The steps a chosen recording showed. A recording is a reading of the
+   * flow like a path is, and it lights the picture the same way, below
+   * whatever the reader is pointing at.
+   */
+  const exampleSteps = useMemo(() => {
+    const example = exampleId
+      ? flow?.examples?.find((e) => e.id === exampleId)
+      : undefined;
+    return example ? stepsShownBy(example) : [];
+  }, [flow, exampleId]);
   const litSteps = useMemo(
     () =>
       walkStep
@@ -272,8 +287,10 @@ export function FlowDetail() {
           ? [selectedStepId]
           : hoverStep
             ? [hoverStep]
-            : matches,
-    [walkStep, selectedStepId, hoverStep, matches],
+            : matches.length > 0
+              ? matches
+              : exampleSteps,
+    [walkStep, selectedStepId, hoverStep, matches, exampleSteps],
   );
 
   useEffect(() => {
@@ -511,6 +528,10 @@ export function FlowDetail() {
             </a>
           ) : null}
           <EditorLink location={flowSource} variant="text" />
+          {/* A recording is evidence too: the traces the flow was seen
+              running in, opened behind a chip rather than laid out in the
+              rail, which is for the steps. */}
+          <RecordingsChip flow={flow} exampleId={exampleId} onExample={setExampleId} />
           <WhatLinksHere
             target={{ kind: "flow", id: flow.slug }}
             variant="line"

package/src/pages/GraphPage.tsx

@@ -11,6 +11,8 @@ import {
   filterEventGraph,
 } from "../lib/event-graph";
 import { contextVar } from "../lib/context-color";
+import { narrowToEnvironments } from "../lib/environments";
+import { environmentsOf } from "../likec4/ids";
 import { statusColor, statusDash } from "../graph/theme";
 import { DependencyGraphPane } from "../graph/DependencyGraph";
 import type { GraphMode } from "../graph/dependency-layout";
@@ -28,8 +30,16 @@ export function GraphPage() {
   const [contexts, setContexts] = useState<Set<string>>(new Set());
   const [statuses, setStatuses] = useState<Set<Status>>(new Set());
   const [mode, setMode] = useState<GraphMode>("bipartite");
+  // Where the estate runs, when a snapshot says. Narrowing the catalog
+  // rather than the graph: a service not deployed in staging is not a node
+  // to fade but a service that is not there, and every count follows.
+  const environmentChips = useMemo(() => environmentsOf(catalog), []);
+  const [environments, setEnvironments] = useState<Set<string>>(new Set());
 
-  const whole = useMemo(() => eventGraph(catalog), []);
+  const whole = useMemo(
+    () => eventGraph(narrowToEnvironments(catalog, environments)),
+    [environments],
+  );
   const graph = useMemo(
     () => filterEventGraph(whole, { contexts, statuses }),
     [whole, contexts, statuses],
@@ -61,7 +71,8 @@ export function GraphPage() {
   // pills with no line between them reads as a rendering failure rather than
   // as an answer. Either the filters left no event - the common case, and the
   // reader wants the way back - or the catalog has none yet.
-  const filtered = contexts.size > 0 || statuses.size > 0;
+  const filtered =
+    contexts.size > 0 || statuses.size > 0 || environments.size > 0;
   const nothing = graph.events.length === 0;
 
   const toggle = <T,>(set: Set<T>, value: T): Set<T> => {
@@ -74,7 +85,7 @@ export function GraphPage() {
   // Filters and mode both replace the layout wholesale, so both refit. Nothing
   // else does: a selection or a focus leaves the viewport where the reader put
   // it.
-  const fitKey = `${[...contexts].sort().join(",")}|${[...statuses].sort().join(",")}|${mode}`;
+  const fitKey = `${[...contexts].sort().join(",")}|${[...statuses].sort().join(",")}|${[...environments].sort().join(",")}|${mode}`;
 
   return (
     <div className="flex h-full flex-col">
@@ -123,6 +134,32 @@ export function GraphPage() {
           })}
         </div>
 
+        {environmentChips.length > 0 ? (
+          <div className="seg" role="group" aria-label="Filter by environment">
+            {environmentChips.map((env) => {
+              const on = environments.has(env);
+              return (
+                <button
+                  key={env}
+                  type="button"
+                  onClick={() => setEnvironments((prev) => toggle(prev, env))}
+                  aria-pressed={on}
+                  title={`only the services the deployer places in ${env}`}
+                  className="flex items-center gap-1.5"
+                  style={{
+                    color: on ? "var(--accent)" : "var(--fg-muted)",
+                    background: on
+                      ? "color-mix(in srgb, var(--accent) 12%, transparent)"
+                      : undefined,
+                  }}
+                >
+                  {env}
+                </button>
+              );
+            })}
+          </div>
+        ) : null}
+
         <div className="mono ml-auto flex flex-wrap items-center gap-3">
           {/* The legend IS the filter. Three swatches that explain the three
               dashes and three buttons that turn them off are the same three

package/src/pages/Overview.tsx

@@ -2,18 +2,25 @@ import { useDocumentTitle } from "../app/title";
 import { useState } from "react";
 import { Link } from "react-router";
 import { AlertTriangle } from "lucide-react";
-import { activeCatalogProfile, CATALOG_PATH, catalog, index } from "../data";
+import { activeCatalogProfile, CATALOG_PATH, catalog } from "../data";
 import { contextOwners, contextStats, widestFlows } from "../lib/derive";
 import type { ContextOwner } from "../lib/derive";
-import { allProblems } from "../lib/all-problems";
+import { bridges } from "../lib/centrality";
+import { useProblems } from "../lib/use-problems";
 import { ctxStyle } from "../lib/context-color";
 import { middleTruncate, plural } from "../lib/format";
 import { useCountUp, staggerStyle } from "../lib/motion";
 import { usePhone } from "../app/responsive";
-import { CONTEXT_ANCHOR, OVERVIEW_ANCHOR, paths } from "../routes";
+import { CONTEXT_ANCHOR, OVERVIEW_ANCHOR, paths, servicePath } from "../routes";
 import { Blank, SectionTitle } from "../components/PageHeader";
 import { C4View } from "../likec4/C4View";
-import { profileContainersViewId, profileLandscapeViewId } from "../likec4/ids";
+import {
+  deploymentViewId,
+  environmentsOf,
+  profileContainersViewId,
+  profileLandscapeViewId,
+} from "../likec4/ids";
+import { servicesDeployedIn } from "../lib/environments";
 import { LevelSwitch } from "../likec4/levels";
 import type { C4Level } from "../likec4/levels";
 import { CatalogStamp } from "../components/CatalogStamp";
@@ -28,6 +35,9 @@ import {
 /** How many problems the overview lists before pointing at the page that lists them all. */
 const OVERVIEW_PROBLEMS = 4;
 
+/** How many bridges the overview lists. Past the first few the shares are small and the list is the graph. */
+const OVERVIEW_BRIDGES = 5;
+
 /**
  * A measurement that arrives rather than appears - 200ms, linear, once - and
  * then takes you to what it measured. A number that counts something the app
@@ -96,12 +106,23 @@ export function Overview() {
   useDocumentTitle("Overview");
   const phone = usePhone();
   const [level, setLevel] = useState<C4Level>(1);
+  // Where the estate runs, one environment at a time. Production first when
+  // there is one by that name: it is the environment a reader means by
+  // "deployed" until they say otherwise.
+  const environments = environmentsOf(catalog);
+  const [environment, setEnvironment] = useState<string>(
+    () =>
+      environments.find((e) => /^prod/i.test(e)) ?? environments[0] ?? "",
+  );
+  const deployedCount = (env: string) =>
+    servicesDeployedIn(catalog, new Set([env])).size;
   const reach = widestFlows(catalog);
+  const roads = bridges(catalog);
   const services = catalog.contexts.reduce(
     (count, context) => count + context.services.length,
     0,
   );
-  const issues = allProblems(catalog, index);
+  const issues = useProblems();
   const issueCount = issues.length;
   const errorCount = issues.filter((p) => p.severity === "error").length;
 
@@ -189,6 +210,44 @@ export function Overview() {
         />
       </section>
 
+      {/* Where the estate runs, from the deployer's snapshot: the services
+          standing in one environment, in their clusters and namespaces, and
+          between them what the model declares. Absent entirely when no
+          snapshot places anything - a heading over an empty canvas would
+          claim the estate runs nowhere, and nobody made that claim. */}
+      {environments.length > 0 ? (
+        <section id={OVERVIEW_ANCHOR.deployed} className="mt-section">
+          <SectionTitle
+            anchor={OVERVIEW_ANCHOR.deployed}
+            right={
+              <div className="seg" role="group" aria-label="Environment">
+                {environments.map((env) => (
+                  <button
+                    key={env}
+                    type="button"
+                    onClick={() => setEnvironment(env)}
+                    aria-pressed={env === environment}
+                    className="flex items-center gap-1.5"
+                    title={`${plural(deployedCount(env), "service")} of the estate in ${env}`}
+                  >
+                    {env}
+                    <span className="tnum">{deployedCount(env)}</span>
+                  </button>
+                ))}
+              </div>
+            }
+          >
+            Deployed
+          </SectionTitle>
+          <C4View
+            viewId={deploymentViewId(environment)}
+            height={phone ? 320 : 480}
+            controls={phone}
+            fitViewPadding={{ x: 8, y: 8 }}
+          />
+        </section>
+      ) : null}
+
       <section id={OVERVIEW_ANCHOR.contexts} className="mt-section">
         <SectionTitle anchor={OVERVIEW_ANCHOR.contexts}>Contexts</SectionTitle>
         <div
@@ -281,6 +340,85 @@ export function Overview() {
         </div>
       </section>
 
+      {/* The services the estate's paths run through: the share of shortest
+          paths between every other pair of services that pass through this
+          one, and the pairs of contexts it is the main road between. Degree
+          is not shown - a hub is visible on the graph, a bridge is not: the
+          service with three neighbours that is the only way from auth into
+          payments looks like nothing there. Nothing is shown for an estate
+          with no such service; a heading over "none" is a dead end. */}
+      {roads.length > 0 ? (
+        <section id={OVERVIEW_ANCHOR.bridges} className="mt-section">
+          <SectionTitle
+            anchor={OVERVIEW_ANCHOR.bridges}
+            right={
+              <span className="flex items-center gap-2">
+                {roads.length > OVERVIEW_BRIDGES ? (
+                  <span className="section-aside">
+                    {OVERVIEW_BRIDGES} of {roads.length}
+                  </span>
+                ) : null}
+                <Link
+                  to={paths.graph()}
+                  className="rounded-control px-1 text-accent hover:underline"
+                >
+                  the graph →
+                </Link>
+              </span>
+            }
+          >
+            Bridges
+          </SectionTitle>
+          <div className="flex flex-col gap-2" data-nav-list>
+            {roads.slice(0, OVERVIEW_BRIDGES).map((road, i) => {
+              const to = servicePath(road.id);
+              const percent = Math.round(road.betweenness * 100);
+              return (
+                <Link
+                  key={road.id}
+                  to={to ?? paths.graph()}
+                  data-nav-item
+                  className="row stagger-in flex-wrap"
+                  style={staggerStyle(i)}
+                  title={`${percent}% of the shortest paths between other services run through ${road.id}`}
+                >
+                  {/* The share, as a bar the width of the number, so the
+                      list reads as a ranking before any number is read. */}
+                  <span className="flex w-16 shrink-0 items-center gap-1.5">
+                    <span className="h-1.5 flex-1 overflow-hidden rounded-full bg-surface">
+                      <span
+                        className="block h-full bg-accent"
+                        style={{ width: `${Math.max(percent, 2)}%` }}
+                      />
+                    </span>
+                    <span className="mono tnum w-8 text-right text-muted">
+                      {percent}%
+                    </span>
+                  </span>
+                  <span className="font-semibold" title={road.id}>
+                    {road.id}
+                  </span>
+                  <span className="mono text-muted">between</span>
+                  <div className="flex flex-wrap items-center gap-1">
+                    {road.between.map((pair) => (
+                      <span
+                        key={`${pair.a}~${pair.b}`}
+                        className="flex items-center gap-1"
+                        title={`${Math.round(pair.share * 100)}% of the shortest paths from ${pair.a} to ${pair.b} run through ${road.id}`}
+                      >
+                        <ContextPill id={pair.a} />
+                        <span className="text-muted">↔</span>
+                        <ContextPill id={pair.b} />
+                      </span>
+                    ))}
+                  </div>
+                </Link>
+              );
+            })}
+          </div>
+        </section>
+      ) : null}
+
       <section id={OVERVIEW_ANCHOR.flows} className="mt-section">
         <SectionTitle
           anchor={OVERVIEW_ANCHOR.flows}
@@ -381,13 +519,15 @@ export function Overview() {
             Problems
           </SectionTitle>
           <div className="flex max-w-table flex-col gap-2" data-nav-list>
-            {issues.slice(0, OVERVIEW_PROBLEMS).map((problem, i) => (
-              <ProblemRow
-                key={`${problem.kind}:${problem.id}:${problem.peer}`}
-                problem={problem}
-                index={i}
-              />
-            ))}
+            <div className="divide-y divide-line overflow-hidden rounded-card border border-line shadow-xs">
+              {issues.slice(0, OVERVIEW_PROBLEMS).map((problem, i) => (
+                <ProblemRow
+                  key={`${problem.rule}:${problem.id}:${problem.peer}`}
+                  problem={problem}
+                  index={i}
+                />
+              ))}
+            </div>
             {issueCount > OVERVIEW_PROBLEMS ? (
               <Link
                 to={paths.problems()}

package/src/pages/PluginIndex.tsx

@@ -0,0 +1,190 @@
+import { useDocumentTitle } from "../app/title";
+import { useEffect, useState } from "react";
+import { Link, useLocation } from "react-router";
+import { ArrowUpRight, ShieldCheck, Terminal } from "lucide-react";
+import { CatIllustration } from "../components/CatIllustration";
+import { SectionTitle } from "../components/PageHeader";
+import { PluginIcon } from "../components/PluginIcon";
+import {
+  pluginsByCategory,
+  pluginIcon,
+  pluginLabel,
+  pluginSourceHref,
+  runtimeLabel,
+} from "../lib/plugins";
+import type { PluginEntry } from "../lib/plugins";
+import { PRODUCT_REPOSITORY } from "../lib/product";
+import { paths } from "../routes";
+
+const PHASE_LABEL = { extract: "extract", verify: "verify", generate: "generate" } as const;
+
+/** Every cat the site has drawn; any of them suits a page that is a list. */
+const CAT_SCENES = ["about", "clear", "unchanged", "onboarding", "search", "trial"] as const;
+
+/**
+ * Every plugin the package ships, grouped by what it reads or what it makes.
+ *
+ * Rendered from the index `npm run schema` writes, so this page says what the
+ * plugins say about themselves and nothing else: the summary each answers to
+ * `describe`, the category it sorts itself under, the options it can be told.
+ * The Settings page shows which of these a build ran; this one shows what a
+ * build could run.
+ */
+export function PluginIndex() {
+  useDocumentTitle("Plugins");
+  const groups = pluginsByCategory();
+  const total = groups.reduce((n, group) => n + group.plugins.length, 0);
+  const { hash } = useLocation();
+  const target = hash.startsWith("#plugin-") ? hash.slice("#plugin-".length) : null;
+  // A different cat each visit, the same one for the visit: picked once, not
+  // on every render, or a hash change would swap it mid-scroll.
+  const [cat] = useState(() => CAT_SCENES[Math.floor(Math.random() * CAT_SCENES.length)] ?? "about");
+
+  // A link from Settings names one plugin. The card grid settles a frame after
+  // the route commits, so the scroll waits for it rather than landing where
+  // the card was in a layout that no longer exists.
+  useEffect(() => {
+    if (!hash) return;
+    const id = hash.slice(1);
+    const frame = requestAnimationFrame(() => {
+      document.getElementById(id)?.scrollIntoView({ block: "start" });
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [hash]);
+
+  return (
+    <div className="h-full overflow-y-auto p-gutter">
+      {/* The intro is a paragraph wide; on a wide screen the rest of the row
+          was empty, and a cat is a better use of it than nothing. */}
+      <div className="grid gap-grid xl:grid-cols-[minmax(0,1fr)_auto] xl:items-center">
+      <div>
+      <div className="flex flex-wrap items-center gap-3">
+        <h1 className="text-lg font-semibold">Plugins</h1>
+        <span className="mono text-muted">{total} shipped</span>
+      </div>
+      <p className="mt-2 max-w-prose text-muted">
+        Every fact in the catalog was read by one of these. An extractor reads a
+        tree and answers with a fragment; a verifier checks the catalog against
+        evidence; a generator turns it into something else. Each describes
+        itself, and this page is that description. Which of them a build ran is
+        on the{" "}
+        <Link to={paths.settingsPipeline()} className="text-accent hover:underline">
+          pipeline settings
+        </Link>
+        ; how to write one is in the{" "}
+        <a
+          href={`${PRODUCT_REPOSITORY}/tree/main/plugins#readme`}
+          target="_blank"
+          rel="noreferrer"
+          className="text-accent hover:underline"
+        >
+          plugin protocol
+        </a>
+        .
+      </p>
+      </div>
+      <CatIllustration scene={cat} className="hidden xl:block h-[126px] w-[180px] justify-self-end" />
+      </div>
+
+      <nav aria-label="Categories" className="mt-4 flex flex-wrap gap-1.5">
+        {groups.map((group) => (
+          <a key={group.category} href={`#${group.category}`} className="chip inline-flex items-center gap-1.5 border-line-strong hover:border-accent hover:text-accent">
+            <PluginIcon icon={{ lucide: group.icon }} size={12} />
+            {group.title} <span className="text-muted/70">{group.plugins.length}</span>
+          </a>
+        ))}
+      </nav>
+
+      <div className="mt-section space-y-section">
+        {groups.map((group) => (
+          <section key={group.category} id={group.category} className="scroll-mt-4">
+            <SectionTitle anchor={group.category} right={<span className="mono text-muted">{group.plugins.length}</span>}>
+              <span className="inline-flex items-center gap-2">
+                <PluginIcon icon={{ lucide: group.icon }} className="text-muted" />
+                {group.title}
+              </span>
+            </SectionTitle>
+            <p className="mb-3 max-w-prose text-muted">{group.what}</p>
+            <div className="grid gap-grid grid-cols-[repeat(auto-fill,minmax(340px,1fr))]">
+              {group.plugins.map((entry) => (
+                <PluginCard key={entry.name} entry={entry} highlighted={entry.name === target} />
+              ))}
+            </div>
+          </section>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function PluginCard({ entry, highlighted }: { entry: PluginEntry; highlighted: boolean }) {
+  const options = Object.entries(entry.options.properties ?? {});
+  const required = new Set(entry.options.required ?? []);
+  const RuntimeIcon = entry.runtime === "wasm" ? ShieldCheck : Terminal;
+  const runtimeTone = entry.runtime === "wasm" ? "text-verified" : "text-declared";
+
+  return (
+    <article
+      id={`plugin-${entry.name}`}
+      // The margin clears the section head, which stays stuck to the top
+      // while its cards scroll under it.
+      className={`card card-static flex scroll-mt-14 flex-col gap-3 ${highlighted ? "border-accent" : ""}`}
+    >
+      <header className="flex flex-wrap items-center gap-x-2 gap-y-1">
+        <PluginIcon icon={pluginIcon(entry.name, entry.category)} size={16} className="text-ink" />
+        <h3 className="font-semibold text-ink">{pluginLabel(entry.name)}</h3>
+        <span className="mono text-muted" title="the name a manifest step uses">{entry.name}</span>
+        {entry.plugin !== entry.name ? (
+          <span className="mono text-faint" title="the plugin's own name">{entry.plugin}</span>
+        ) : null}
+      </header>
+
+      <p className="text-muted">{entry.summary}</p>
+
+      <div className="flex flex-wrap items-center gap-1.5">
+        {entry.phases.map((phase) => (
+          <span key={phase} className="chip border-line-strong">{PHASE_LABEL[phase]}</span>
+        ))}
+        <span className={`chip inline-flex items-center gap-1 border-line-strong ${runtimeTone}`}>
+          <RuntimeIcon size={12} aria-hidden /> {runtimeLabel(entry)}
+        </span>
+        {entry.needs?.map((need) => (
+          <span key={need} className="chip border-line-strong" title="asked of the host beyond the tree">
+            needs {need}
+          </span>
+        ))}
+      </div>
+
+      {options.length > 0 ? (
+        <details className="group">
+          <summary className="mono cursor-pointer list-none text-muted hover:text-ink">
+            {options.length} option{options.length === 1 ? "" : "s"}
+            <span className="ml-1 inline-block transition-transform group-open:rotate-90">›</span>
+          </summary>
+          <dl className="mt-2 space-y-2 border-l border-line pl-3">
+            {options.map(([key, option]) => (
+              <div key={key}>
+                <dt className="mono text-ink">
+                  {key}
+                  {required.has(key) ? <span className="ml-1 text-faint" title="required">*</span> : null}
+                </dt>
+                {option.description ? <dd className="text-muted">{option.description}</dd> : null}
+              </div>
+            ))}
+          </dl>
+        </details>
+      ) : (
+        <p className="mono text-faint">takes no options</p>
+      )}
+
+      <a
+        href={pluginSourceHref(entry)}
+        target="_blank"
+        rel="noreferrer"
+        className="mono mt-auto inline-flex items-center gap-1 text-accent hover:underline"
+      >
+        {entry.source} <ArrowUpRight size={12} aria-hidden />
+      </a>
+    </article>
+  );
+}