@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/merge.ts

@@ -15,8 +15,12 @@
 //    context's name is a fact about the estate that belongs on the Problems
 //    page, next to the other things that are true and unfortunate.
 
+import { deploymentBasis } from "./catalog-model.ts";
 import type {
   Aggregate,
+  Deployment,
+  DeploymentBasis,
+  DeploymentDrift,
   Alt,
   AltBranch,
   Block,
@@ -121,6 +125,8 @@ export function mergeCatalogs(sources: CatalogSource[]): MergeResult {
   const terms: NonNullable<Catalog["terms"]> = [];
   const repos: NonNullable<Catalog["repos"]> = [];
   const repoOrigin = new Map<string, string>();
+  const deployments: NonNullable<Catalog["deployments"]> = [];
+  const deploymentOrigin = new Map<string, Map<DeploymentBasis, string>>(); // id -> basis -> source path
   const externals = new Map<string, External>();
   const externalOrigin = new Map<string, string>();
   const seen = new Map<string, string>(); // flow/adr/store/module/term id -> source path
@@ -249,6 +255,15 @@ export function mergeCatalogs(sources: CatalogSource[]): MergeResult {
     for (const store of catalog.stores ?? []) {
       if (claim(seen, store.id, path, conflicts, "store")) stores.push(store);
     }
+    // Two sources may speak about one Application, and are meant to: the
+    // GitOps tree says what should run, the deployer says what does, and
+    // the row a reader sees is the two laid over each other with the
+    // difference kept as drift (portolan.0013). Two rows of the SAME basis
+    // for one id is the collision - two snapshots of one server, two trees
+    // declaring one name - and is reported like any other.
+    for (const deployment of catalog.deployments ?? []) {
+      foldDeployment(deployments, deploymentOrigin, deployment, path, conflicts);
+    }
     // Claimed by id like everything else at this level, and that is exactly why
     // a module's id is its registry-global name rather than one derived from an
     // owner: the producer and each consumer describe the same module from
@@ -324,6 +339,7 @@ export function mergeCatalogs(sources: CatalogSource[]): MergeResult {
   if (modules.length > 0) merged.modules = modules;
   if (terms.length > 0) merged.terms = terms;
   if (repos.length > 0) merged.repos = repos;
+  if (deployments.length > 0) merged.deployments = deployments;
   if (externals.size > 0) merged.externals = [...externals.values()];
 
   return { catalog: merged, sources: stamps, conflicts };
@@ -499,6 +515,8 @@ function mergeService(
       ...(incoming.commands
         ? { commands: incoming.commands.map((c) => ({ ...c })) }
         : {}),
+      ...(incoming.hosts ? { hosts: [...incoming.hosts] } : {}),
+      ...(incoming.dials ? { dials: [...incoming.dials] } : {}),
     });
     origin.set(incoming.id, path);
 
@@ -592,6 +610,18 @@ function mergeService(
     existing.commands = commands;
   }
 
+  // Unioned like owners: two manifest trees naming where a service answers,
+  // or what it dials, are two deployments of it, and the page shows both.
+  for (const field of ["hosts", "dials"] as const) {
+    const theirs = incoming[field];
+    if (!theirs?.length) continue;
+    const names = existing[field] ?? [];
+    for (const name of theirs) {
+      if (!names.includes(name)) names.push(name);
+    }
+    existing[field] = names;
+  }
+
   if (incoming.channels?.length) {
     // Keyed by address, because that is the whole of a channel's identity. Two
     // documents describing one channel is not a conflict worth reporting - a
@@ -930,26 +960,84 @@ function raise<T extends { status: Status; note?: string }>(
  *
  * Only `declared` is raised. `unresolved` means the far end is not in the
  * catalog, and a trace showing the hop does not put it there.
+ *
+ * The second declaration may also say more than the first: a hop it saw
+ * that the code does not declare, carried as a step with `seen` on it and
+ * an id the code never gave, sitting where the recording put it; a lane
+ * such a hop needed, added after the declared ones; and the recordings
+ * themselves, as examples. Each is taken as it comes - a recording is the
+ * one witness for it - and nothing already declared moves.
  */
 export function overlayFlow(existing: Flow, incoming: Flow): Flow | undefined {
-  const lanes = (flow: Flow) => flow.participants.map((p) => p.id).join(" ");
-  if (lanes(existing) !== lanes(incoming)) return undefined;
+  const mine = existing.participants.map((p) => p.id);
+  const theirs = incoming.participants.map((p) => p.id);
+  if (theirs.length < mine.length || mine.some((id, i) => theirs[i] !== id))
+    return undefined;
 
   const steps = overlayNodes(existing.steps, incoming.steps);
   if (!steps) return undefined;
 
-  return { ...existing, steps };
+  const out: Flow = { ...existing, steps };
+  if (theirs.length > mine.length) {
+    out.participants = [
+      ...existing.participants,
+      ...incoming.participants.slice(mine.length),
+    ];
+  }
+  const examples = [...(existing.examples ?? [])];
+  const held = new Set(examples.map((example) => example.id));
+  for (const example of incoming.examples ?? []) {
+    if (!held.has(example.id)) {
+      held.add(example.id);
+      examples.push(example);
+    }
+  }
+  if (examples.length) out.examples = examples;
+
+  return out;
+}
+
+/**
+ * A node the second declaration added: a step seen in a recording and
+ * unknown to the code, or a frame where the recordings parted - an `alt`
+ * whose every step carries `seen` and whose every branch is counted. Its
+ * id is not one the first declaration has, which is how it is told from a
+ * declared node that moved.
+ */
+function isSeenAddition(node: FlowNode, against: FlowNode | undefined): boolean {
+  if (against !== undefined && against.id === node.id) return false;
+  if (node.type === "step") return node.seen !== undefined;
+  if (node.type !== "alt") return false;
+  let steps = 0;
+  const allSeen = (nodes: FlowNode[]): boolean =>
+    nodes.every((inner) => {
+      if (inner.type === "step") {
+        steps += 1;
+
+        return inner.seen !== undefined;
+      }
+
+      return inner.type === "alt" && inner.branches.every((b) => b.seen !== undefined && allSeen(b.steps));
+    });
+
+  return node.branches.every((b) => b.seen !== undefined && allSeen(b.steps)) && steps > 0;
 }
 
 function overlayNodes(
   existing: FlowNode[],
   incoming: FlowNode[],
 ): FlowNode[] | undefined {
-  if (existing.length !== incoming.length) return undefined;
   const out: FlowNode[] = [];
-  for (let i = 0; i < existing.length; i++) {
-    const a = existing[i]!;
-    const b = incoming[i]!;
+  let i = 0;
+  for (const b of incoming) {
+    const a = existing[i];
+    if (isSeenAddition(b, a)) {
+      out.push(b);
+
+      continue;
+    }
+    if (a === undefined) return undefined;
+    i++;
     if (a.type !== b.type || a.id !== b.id) return undefined;
     switch (a.type) {
       case "step": {
@@ -961,10 +1049,11 @@ function overlayNodes(
           (a.ref ?? "") !== (step.ref ?? "")
         )
           return undefined;
+        const seen = step.seen ? { seen: step.seen } : {};
         if (step.status === "verified" && a.status === "declared") {
-          out.push({ ...a, status: "verified", note: a.note || step.note });
+          out.push({ ...a, ...seen, status: "verified", note: a.note || step.note });
         } else {
-          out.push(a);
+          out.push({ ...a, ...seen });
         }
         break;
       }
@@ -1006,6 +1095,8 @@ function overlayNodes(
     }
   }
 
+  if (i !== existing.length) return undefined;
+
   return out;
 }
 
@@ -1013,6 +1104,79 @@ function overlayNodes(
  * Records who owns an id. Returns false when somebody already did, which is
  * how a duplicate is skipped rather than appended twice.
  */
+/**
+ * Lays one deployment over what is already held for its id.
+ *
+ * A manifest row and an api row fold into one: the api row's shape - it is
+ * what runs, and carries the revision, the images and the link - with the
+ * manifest filling what the deployer did not say (a service the labels
+ * name, images the overlay pins when nothing runs yet), and the fields the
+ * two disagree on kept as the tree's word under `drift`. Whichever arrives
+ * first is held; the second folds onto it. Two rows of one basis are a
+ * collision and the first is kept, said out loud.
+ */
+function foldDeployment(
+  held: Deployment[],
+  origins: Map<string, Map<DeploymentBasis, string>>,
+  incoming: Deployment,
+  path: string,
+  conflicts: MergeConflict[],
+): void {
+  const basis = deploymentBasis(incoming);
+  const bases = origins.get(incoming.id) ?? new Map<DeploymentBasis, string>();
+  origins.set(incoming.id, bases);
+  const index = held.findIndex((d) => d.id === incoming.id);
+  if (index < 0) {
+    bases.set(basis, path);
+    held.push(incoming);
+    return;
+  }
+  const already = bases.get(basis);
+  if (already !== undefined || basis === "both") {
+    conflicts.push({
+      path,
+      where: incoming.id,
+      message: `deployment "${incoming.id}" is ${basis === "manifest" ? "declared" : "listed"} here and in ${already ?? "another source"}; the first one is used`,
+    });
+    return;
+  }
+  bases.set(basis, path);
+  const current = held[index]!;
+  const [manifest, api] = basis === "manifest" ? [incoming, current] : [current, incoming];
+  held[index] = laidOver(manifest, api);
+}
+
+/** The api row with the manifest laid under it, and their differences as drift. */
+function laidOver(manifest: Deployment, api: Deployment): Deployment {
+  const drift: DeploymentDrift = {};
+  if (manifest.project && manifest.project !== api.project) drift.project = manifest.project;
+  if (manifest.cluster && manifest.cluster !== api.cluster) drift.cluster = manifest.cluster;
+  if (manifest.namespace && manifest.namespace !== api.namespace) drift.namespace = manifest.namespace;
+  if (manifest.path && manifest.path !== api.path) drift.path = manifest.path;
+  if (manifest.targetRevision && manifest.targetRevision !== api.targetRevision) {
+    drift.targetRevision = manifest.targetRevision;
+  }
+  // The overlay pins some images; the cluster runs those and the base's.
+  // Drift is a pinned image that is not running, not a running image the
+  // overlay never mentioned.
+  const running = new Set(api.images ?? []);
+  const pinnedElsewhere = (manifest.images ?? []).filter((image) => !running.has(image));
+  if (pinnedElsewhere.length > 0 && (api.images?.length ?? 0) > 0) drift.images = pinnedElsewhere;
+
+  const folded: Deployment = {
+    ...api,
+    service: api.service ?? manifest.service,
+    tool: api.tool || manifest.tool,
+    images: api.images?.length ? api.images : manifest.images,
+    basis: "both",
+  };
+  if (folded.service === undefined) delete folded.service;
+  if (!folded.images?.length) delete folded.images;
+  if (Object.keys(drift).length > 0) folded.drift = drift;
+  else delete folded.drift;
+  return folded;
+}
+
 function claim(
   owners: Map<string, string>,
   id: string,

package/src/pages/AggregatePage.tsx

@@ -1,7 +1,7 @@
 import { useMemo } from "react";
 import { Link, useParams } from "react-router";
 import { catalog, index } from "../data";
-import { blockCounts, blockFields, enumsOf, rootEntity } from "../catalog";
+import { allRepos, blockCounts, blockFields, enumsOf, rootEntity } from "../catalog";
 import { isStatusEnum } from "../lib/shape";
 import type {
   Aggregate,
@@ -11,7 +11,7 @@ import type {
   Service,
   Enum,
 } from "../catalog";
-import { markdownOutline } from "../lib/derive";
+import { flowsRunning, markdownOutline } from "../lib/derive";
 import {
   redisKeyspacesPersisting,
   tablesPersisting,
@@ -33,6 +33,8 @@ import {
 } from "../routes";
 import { methodId } from "../lib/api";
 import { Markdown } from "../components/Markdown";
+import { SourcePreviewLink } from "../components/SourcePreview";
+import { sourceLocation, splitLine } from "../lib/source-link";
 import { Empty, PageHeader, SectionTitle } from "../components/PageHeader";
 import { Ident } from "../components/Ident";
 import { RowActions } from "../components/RowActions";
@@ -265,10 +267,12 @@ function OperationList({
   kind,
   operations,
   service,
+  aggregate,
 }: {
   kind: "command" | "query";
   operations: Operation[];
   service: Service;
+  aggregate: Aggregate;
 }) {
   // Whether this service records what exposes an operation at all. A catalog
   // written before anything read a transport layer says nothing either way,
@@ -277,10 +281,14 @@ function OperationList({
     aggregate.operations.some((operation) => operation.exposedBy?.length),
   );
   const to = servicePath(service.id);
+  const pins = allRepos(catalog);
 
   return (
     <ul className="flex flex-col gap-1">
-      {operations.map((op) => (
+      {operations.map((op) => {
+        const runs = flowsRunning(catalog, service, aggregate, op);
+        const location = op.source ? sourceLocation(op.source, service, pins) : null;
+        return (
         <li
           key={op.id}
           className={`flex items-start gap-2 border-l-2 px-2 py-1.5 bg-surface ${
@@ -290,7 +298,7 @@ function OperationList({
           <span className="mt-px shrink-0">
             <KindIcon kind={kind} />
           </span>
-          <div className="min-w-0">
+          <div className="min-w-0 flex-1">
             <span className="flex flex-wrap items-center gap-x-2">
               <Ident block value={op.id} className={op.deprecated ? "line-through" : undefined} />
               {op.deprecated ? (
@@ -298,8 +306,49 @@ function OperationList({
                   deprecated
                 </span>
               ) : null}
+              {op.source ? (
+                <SourcePreviewLink location={location} className="mono ml-auto text-muted hover:text-ink">
+                  {splitLine(op.source).path.split("/").pop()}
+                  {splitLine(op.source).line ? `:${splitLine(op.source).line}` : ""}
+                </SourcePreviewLink>
+              ) : null}
             </span>
             {op.doc ? <p className="mt-0.5 text-muted">{op.doc}</p> : null}
+            {/* What the caller hands in: the message's own shape. An empty
+                list is said out loud - a query that takes nothing is a fact
+                about the query, not a gap in the reading. */}
+            {op.fields ? (
+              op.fields.length ? (
+                <dl className="mono mt-1 grid grid-cols-[max-content_1fr] gap-x-3 gap-y-0.5 text-muted">
+                  {op.fields.map((field) => (
+                    <div key={field.name} className="contents">
+                      <dt className={field.deprecated ? "line-through" : undefined}>{field.name}</dt>
+                      <dd className="min-w-0 truncate">
+                        <span className="text-ink">{field.type}</span>
+                        {field.doc ? <span className="ml-2">{field.doc}</span> : null}
+                      </dd>
+                    </div>
+                  ))}
+                </dl>
+              ) : (
+                <p className="mono mt-1 text-muted">takes nothing</p>
+              )
+            ) : null}
+            {runs.length ? (
+              <p className="mono mt-1 flex flex-wrap items-center gap-x-2 text-muted">
+                <span>runs in</span>
+                {runs.map(({ flow, stepId }) => (
+                  <Link
+                    key={flow.slug}
+                    to={paths.flowStep(flow.slug, stepId)}
+                    className="rounded-control hover:text-ink"
+                    title={flow.name}
+                  >
+                    {flow.slug}
+                  </Link>
+                ))}
+              </p>
+            ) : null}
             {op.exposedBy?.length ? (
               <p className="mono mt-1 flex flex-wrap items-center gap-x-2 text-muted">
                 <span>exposed by</span>
@@ -328,7 +377,8 @@ function OperationList({
             ) : null}
           </div>
         </li>
-      ))}
+        );
+      })}
     </ul>
   );
 }
@@ -593,7 +643,7 @@ export function AggregatePage() {
               {commands.length === 0 ? (
                 <Empty>{aggregate.kind === "model-group" ? "no application commands discovered" : "nothing changes this aggregate from outside"}</Empty>
               ) : null}
-              <OperationList kind="command" operations={commands} service={service} />
+              <OperationList kind="command" operations={commands} service={service} aggregate={aggregate} />
             </div>
             <div id={AGGREGATE_ANCHOR.queries}>
               <SectionTitle
@@ -609,7 +659,7 @@ export function AggregatePage() {
               {queries.length === 0 ? (
                 <Empty>{aggregate.kind === "model-group" ? "no application queries discovered" : "nothing reads this aggregate by name"}</Empty>
               ) : null}
-              <OperationList kind="query" operations={queries} service={service} />
+              <OperationList kind="query" operations={queries} service={service} aggregate={aggregate} />
             </div>
           </div>
 

package/src/pages/ContextMap.tsx

@@ -17,6 +17,8 @@ import { Link, useSearchParams } from "react-router";
 import { ArrowRight, ArrowLeftRight, Boxes, Minus } from "lucide-react";
 import { catalog } from "../data";
 import { plural } from "../lib/format";
+import { narrowToEnvironments } from "../lib/environments";
+import { environmentsOf } from "../likec4/ids";
 import { PATTERN_LABEL, PATTERN_MEANING, contextMap } from "../lib/context-map";
 import type {
   ContextDependency,
@@ -439,7 +441,22 @@ export function ContextMap() {
   useDocumentTitle("Context map");
   const [search, setSearch] = useSearchParams();
   const [tour, setTour] = useState(() => search.get("tour") === "1");
-  const relations = useMemo(() => contextMap(catalog), []);
+  // The map of one environment is the same map over the services deployed
+  // there: a pair joined only through a service that is not in staging is
+  // not joined in staging. Empty means the whole estate, as every filter here.
+  const environmentChips = useMemo(() => environmentsOf(catalog), []);
+  const [environments, setEnvironments] = useState<Set<string>>(new Set());
+  const narrowed = useMemo(
+    () => narrowToEnvironments(catalog, environments),
+    [environments],
+  );
+  const relations = useMemo(() => contextMap(narrowed), [narrowed]);
+  const toggleEnvironment = (env: string) =>
+    setEnvironments((prev) => {
+      const next = new Set(prev);
+      if (!next.delete(env)) next.add(env);
+      return next;
+    });
   const joined = relations.filter(
     (r) => r.dependencies.length > 0 || r.shared.length > 0,
   );
@@ -457,9 +474,34 @@ export function ContextMap() {
       <div className="flex shrink-0 flex-wrap items-center gap-x-3 gap-y-2 border-b px-gutter py-3 border-line">
         <h1 className="text-lg font-semibold">Context map</h1>
         <span className="mono text-muted">
-          {catalog.contexts.length} {plural(catalog.contexts.length, "domain")} ·{" "}
+          {narrowed.contexts.length} {plural(narrowed.contexts.length, "domain")} ·{" "}
           {wired} of {relations.length} {plural(relations.length, "pair")} joined
         </span>
+        {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={() => toggleEnvironment(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}
 
         {/* Two legends, and they answer different questions: what the arrow
             means, and how far a word on a chip can be trusted. */}
@@ -505,7 +547,7 @@ export function ContextMap() {
             </SectionTitle>
             <div className="h-[340px] overflow-hidden rounded-card border border-line">
               <ContextMapPane
-                catalog={catalog}
+                catalog={narrowed}
                 relations={relations}
                 zoomOnScroll={false}
               />

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";
@@ -94,6 +95,7 @@ export function ContextPage() {
               </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

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