@principal-ai/subsystems-react 0.53.6 → 0.55.0

package/src/subsystem/C4Graph.tsx

@@ -12,6 +12,7 @@
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { ComponentType, CSSProperties, ReactNode } from 'react';
 import {
   Edge,
   EdgeProps,
@@ -33,6 +34,9 @@ import { EDGE_LABEL_FONT_SIZE, EDGE_LABEL_HEIGHT, C4_LABEL_WIDTH, estimateEdgeLa
 import { deriveC4Groups, protocolColor, type C4Group } from './c4';
 import {
   C4NodeCard,
+  COMPONENT_FOOTER_PAD,
+  COMPONENT_HEADER_PAD,
+  COMPONENT_W,
   NODE_H,
   NODE_W,
   OPEN_FOOTER_PAD,
@@ -44,12 +48,131 @@ import {
 import { TechMark, technologyBrand } from './techIcons';
 import type { TechBrand } from './techIcons';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
-import type { C4Element, C4Model } from './c4';
+import type { C4Component, C4Edge, C4Element, C4Model, C4TrailRef } from './c4';
 import { openContainerSet, openStateKey } from './c4';
+import {
+  EDGE_DIM_ALPHA,
+  hexWithAlpha,
+  SubsystemCallbacksProvider,
+  SubsystemComponentNode,
+  SubsystemEdge,
+} from './nodes';
+import { FileDrawer, FILE_DRAWER_HEIGHT_MS } from './FileDrawer';
+import {
+  constructBadgeLabel,
+  convertSubsystemToEdges,
+  convertSubsystemToNodes,
+  deriveNameFromSymbol,
+  edgeColor,
+  MECHANISM_DESCRIPTIONS,
+  rightBadgeLabel,
+} from './model';
+import type { SubsystemComponent, SubsystemEdgeProvenance, SubsystemTrail } from './model';
+import { generateDeclarationString } from './formatDeclaration';
+import { componentColor } from '../pierre/constructColors';
+import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
+
+/**
+ * The construct-level subgraph a C4 container hosts when it is opened — the
+ * component graph's own material (subsystem components + trail steps), so the
+ * constructs render as real `subsystem-component` nodes and `subsystem-edge`
+ * edges rather than a summary. Host-resolved and keyed by container id, so the
+ * C4 view stays free of the document.
+ *
+ * The hierarchy it expresses is container → C4 component → construct: a
+ * construct whose alias an authored component claims nests under that
+ * component (which grows into an ELK parent); one no component claims nests
+ * directly under the container.
+ */
+export interface C4ConstructGraph {
+  /** The document components to draw inside this container. */
+  components: readonly SubsystemComponent[];
+  /** The trails whose steps become the construct edges (restrict to this container). */
+  trails: readonly SubsystemTrail[];
+  /** Construct alias → the authored C4 component element id that claims it. */
+  componentOf?: ReadonlyMap<string, string>;
+}
 
 export interface C4GraphProps {
   model: C4Model;
   onSelectNode?: (id: string | null) => void;
+  /**
+   * Click an edge. Fires with the rolled-up line (and its `trailRefs`
+   * provenance when a builder supplied it), or `null` when the selection is
+   * cleared — pane click, or clicking a node. This is the drill-down
+   * affordance: the host switches the component graph to the contributing
+   * trails.
+   */
+  onSelectEdge?: (edge: C4Edge | null) => void;
+  /**
+   * Click a trail row in the edge inspector. Hands the ref back so the host
+   * can deep-link the component graph to that trail — e.g. via
+   * `SubsystemComponentGraph.initialTrailId`. Without this the refs render
+   * inert.
+   */
+  onTrailClick?: (ref: C4TrailRef) => void;
+  /**
+   * Element ids to fade — everything the focused trail does NOT touch. The
+   * host computes the set (trail step aliases → owning element via its
+   * membership map); this graph renders the named elements (and the lines
+   * between them) at low opacity so the players in the trail stay bright.
+   * `null` (or absent) renders everything at full weight.
+   */
+  dimmedElementIds?: ReadonlySet<string> | null;
+  /**
+   * Edge ids to fade beyond the endpoint rule — the host's line-level
+   * relevance set (edges that do NOT carry the focused trail / hovered step).
+   * A step entirely internal to a container folds into no line, so the host
+   * can dim every edge even though lit containers remain. Unioned with the
+   * own both-endpoints-dimmed rule; the selected edge never dims.
+   */
+  dimmedEdgeIds?: ReadonlySet<string> | null;
+  /**
+   * Element ids to remove from the canvas entirely — the focused trail's cast,
+   * the C4 analogue of the component graph's opened-flow hide. Unlike
+   * `dimmedElementIds` (faded but still drawn), these boxes are not rendered at
+   * all, and a line touching one is hidden with it. `null`/absent draws
+   * everything. Hover previews dim; an expanded trail hides non-members.
+   */
+  hiddenElementIds?: ReadonlySet<string> | null;
+  /** Edge ids to remove entirely — lines the focused trail does not fold. */
+  hiddenEdgeIds?: ReadonlySet<string> | null;
+  /**
+   * Subsystem-component aliases to fade beyond the container rule — the
+   * construct-level spotlight for a hovered step. A construct whose alias is in
+   * the set dims even when its container is lit. Absent → constructs dim only
+   * with their container.
+   */
+  dimmedConstructIds?: ReadonlySet<string> | null;
+  /** Subsystem edge ids to fade — the construct-level counterpart of `dimmedEdgeIds`. */
+  dimmedConstructEdgeIds?: ReadonlySet<string> | null;
+  /**
+   * The construct-level subgraph to draw inside each opened container — the
+   * component graph's subsystem nodes and edges, nested container → C4
+   * component → construct. The host resolves it from the model document and the
+   * focused trail (restricting edges to the container; a construct edge that
+   * crosses containers stays a C4 container-level line). Absent → the container
+   * opens as before, with no constructs.
+   */
+  constructGraphByContainer?: ReadonlyMap<string, C4ConstructGraph>;
+  /**
+   * The step under persistent focus — the host sets it from a trails-panel step
+   * click. The C4 canvas opens a code drawer showing that step's implementation
+   * (the trail viewer when supplied, else the file at its line). `null` → no
+   * drawer.
+   */
+  focusedStep?: { trailId: string; stepIndex: number } | null;
+  /** Close the step drawer — the host clears `focusedStep`. */
+  onCloseStep?: () => void;
+  /** Host code viewer for a step's file — the drawer's content. */
+  renderFileViewer?: (
+    file: string,
+    opts?: { startLine?: number; endLine?: number },
+  ) => ReactNode;
+  /** Host trail viewer; when supplied it replaces the file viewer for a step. */
+  renderTrailViewer?: (ctx: { trail: SubsystemTrail; stepIndex: number | null }) => ReactNode;
+  /** Suppress the drawer entirely (embeds). */
+  hideDrawer?: boolean;
   /**
    * Drill-down: add `id` to `model.openContainerIds`, or remove it if it is
    * already open. One verb for both directions, because with several containers
@@ -102,11 +225,35 @@ function C4NodeView(
       /** FLIP: absolute flow rects — where this card was, and where it now is. */
       growFrom?: FlowRect;
       frameRect?: FlowRect;
+      /**
+       * True while the host's focused trail does not touch this element — the
+       * "players stay bright, the rest fades" emphasis layer. Applied to the
+       * whole card (badges and all), never to a single badge on it.
+       */
+      dimmed?: boolean;
+      /** Arriving in this layout — fades in. */
+      entering?: boolean;
+      /** Gone from this layout — kept for the morph, fades out. */
+      leaving?: boolean;
+      /** The move/grow waits this long for the fade to finish, in ms. */
+      moveDelayMs?: number;
     }>
   >,
 ) {
-  const { element, selected, componentCount, onExpand, open, settled, growFrom, frameRect } =
-    props.data;
+  const {
+    element,
+    selected,
+    componentCount,
+    onExpand,
+    open,
+    settled,
+    growFrom,
+    frameRect,
+    dimmed,
+    entering,
+    leaving,
+    moveDelayMs = 0,
+  } = props.data;
   const grown = open === true;
 
   // Position-only FLIP. The card resizes through its own `width`/`height`
@@ -115,6 +262,11 @@ function C4NodeView(
   // transition, so its resize is the card's own and nothing competes with it.
   const { flipping, placed, dx, dy } = useFlip(growFrom, frameRect);
   const sliding = flipping && (dx !== 0 || dy !== 0);
+  const fade = useFade(entering, leaving);
+  const transitions = [
+    ...(fade.transition ? [fade.transition] : []),
+    ...(sliding && placed ? [`transform ${MORPH_MS}ms ease-out ${moveDelayMs}ms`] : []),
+  ];
   // The card takes its box from the React Flow node rather than from its own
   // `nodeSize`, so on the opened container ELK's fitted size drives it — and
   // because the element persists across the swap, the card's own width/height
@@ -133,24 +285,37 @@ function C4NodeView(
         // compose without either fighting the other.
         transformOrigin: 'top left',
         transform: sliding && !placed ? `translate(${dx}px, ${dy}px)` : 'none',
-        transition: sliding && placed ? `transform ${MORPH_MS}ms ease-out` : 'none',
+        transition: transitions.length > 0 ? transitions.join(', ') : 'none',
+        opacity: fade.opacity,
       }}
     >
-      <C4NodeCard
-        node={element}
-        selected={selected}
-        componentCount={componentCount ?? 0}
-        onExpand={onExpand}
-        width={props.width}
-        height={props.height}
-        showDescription={showDescriptionFor(open, settled)}
-        handles={
-          <>
-            <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
-            <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
-          </>
-        }
-      />
+      <div
+        style={{
+          // The dim is a view concern, deliberately below the FLIP transform
+          // (which owns position) so the two never fight. The whole card fades —
+          // if we ever want to keep a badge lit, that is a different element.
+          opacity: dimmed ? 0.22 : 1,
+          transition: 'opacity 220ms ease',
+        }}
+      >
+        <C4NodeCard
+          node={element}
+          selected={selected}
+          componentCount={componentCount ?? 0}
+          onExpand={onExpand}
+          width={props.width}
+          height={props.height}
+          showDescription={showDescriptionFor(open, settled)}
+          transitionDelayMs={moveDelayMs}
+          sizeTransitionMs={MORPH_MS}
+          handles={
+            <>
+              <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
+              <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
+            </>
+          }
+        />
+      </div>
     </div>
   );
 }
@@ -166,9 +331,15 @@ function C4NodeView(
 function C4EdgeLabels({
   positions,
   edges,
+  selectedEdgeId,
+  dimmedEdgeIds,
+  hiddenEdgeIds,
 }: {
   positions: Map<string, { x: number; y: number }>;
   edges: C4Model['edges'];
+  selectedEdgeId?: string | null;
+  dimmedEdgeIds?: ReadonlySet<string> | null;
+  hiddenEdgeIds?: ReadonlySet<string> | null;
 }) {
   const { theme } = useTheme();
   const viewport = useViewport();
@@ -188,8 +359,11 @@ function C4EdgeLabels({
       {[...positions].map(([id, p]) => {
         const edge = byId.get(id);
         if (!edge) return null;
+        if (hiddenEdgeIds?.has(edge.id)) return null;
         const color = protocolColor(edge.protocol);
         const text = edge.protocol ?? edge.label;
+        const selected = edge.id === selectedEdgeId;
+        const dimmed = dimmedEdgeIds?.has(edge.id) === true;
         return (
           <div
             key={id}
@@ -206,6 +380,145 @@ function C4EdgeLabels({
               height: EDGE_LABEL_HEIGHT,
               boxSizing: 'border-box',
               padding: '7px 8px',
+              // Fades with its line, on the same beat.
+              opacity: dimmed ? 0.25 : 1,
+              transition: 'opacity 220ms ease',
+            }}
+          >
+            <span
+              aria-hidden
+              style={{
+                position: 'absolute',
+                inset: 0,
+                borderRadius: 4,
+                border: `0.5px solid ${color}`,
+                background: surface,
+                // The selected chip echoes the edge's heavier stroke.
+                outline: selected ? `1.5px solid ${color}` : 'none',
+              }}
+            />
+            <span
+              style={{
+                position: 'relative',
+                maxWidth: '100%',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+                fontSize: EDGE_LABEL_FONT_SIZE,
+                lineHeight: 1,
+                fontFamily: theme.fonts.monospace,
+                fontWeight: selected ? 700 : 500,
+                color,
+              }}
+            >
+              {text}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * Fallback drawer body when the host supplies no file/trail viewer: the step's
+ * seam — `from → to`, mechanism, site, symbol, and any annotation. A host with a
+ * real code viewer passes `renderFileViewer` / `renderTrailViewer` instead.
+ */
+function StepDrawerFallback({ step }: { step: SubsystemTrail['steps'][number] }) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  return (
+    <div
+      style={{
+        padding: 12,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 6,
+        fontFamily: theme.fonts.monospace,
+        fontSize: theme.fontSizes[0],
+      }}
+    >
+      <div style={{ color: theme.colors.text }}>
+        {step.from} → {step.to}
+      </div>
+      <div style={{ color: muted }}>
+        {step.mechanism} · {step.file}:{step.span?.startLine ?? '?'}
+      </div>
+      {step.symbol && <div style={{ color: muted }}>{step.symbol}</div>}
+      {step.annotation && (
+        <div style={{ color: theme.colors.text, fontFamily: theme.fonts.body, marginTop: 4 }}>
+          {step.annotation}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Construct-edge label overlay — the mechanism chips for the reused subsystem
+ * edges.
+ *
+ * `SubsystemEdge` draws only the line; the component graph renders its mechanism
+ * labels in a separate overlay. So the C4 canvas supplies one too, from the ELK
+ * label anchors stamped onto each edge's data (`labelX/labelY`).
+ */
+function SubsystemEdgeLabels({ edges }: { edges: Edge[] }) {
+  const { theme } = useTheme();
+  const viewport = useViewport();
+  const surface = theme.colors.backgroundSecondary ?? theme.colors.background;
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        inset: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+        zIndex: 5,
+      }}
+    >
+      {edges.map((e) => {
+        const d = e.data as
+          | {
+              mechanism?: string;
+              provenance?: SubsystemEdgeProvenance;
+              labelX?: number;
+              labelY?: number;
+              dimmed?: boolean;
+            }
+          | undefined;
+        if (d?.labelX == null || d?.labelY == null) return null;
+        const mechanism = d.mechanism ?? 'uses';
+        const text = mechanism;
+        // The same hue the component graph gives its mechanism chips, so a verb
+        // reads the same colour on either canvas.
+        const color = edgeColor({ mechanism, provenance: d.provenance });
+        const labelTitle =
+          d.provenance === 'graphify'
+            ? 'Derived from graphify (static symbol graph)'
+            : MECHANISM_DESCRIPTIONS.find(([m]) => m === mechanism)?.[2] === false
+              ? 'Not directly verifiable with graphify'
+              : undefined;
+        return (
+          <div
+            key={e.id}
+            title={labelTitle}
+            style={{
+              position: 'absolute',
+              left: d.labelX * viewport.zoom + viewport.x,
+              top: d.labelY * viewport.zoom + viewport.y,
+              transform: `translate(-50%, -50%) scale(${viewport.zoom})`,
+              transformOrigin: 'center center',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: estimateEdgeLabelWidth(text),
+              height: EDGE_LABEL_HEIGHT,
+              boxSizing: 'border-box',
+              padding: '7px 8px',
+              // Fades with its line, on the same beat.
+              opacity: d.dimmed === true ? 0.15 : 1,
+              transition: 'opacity 220ms ease',
             }}
           >
             <span
@@ -248,20 +561,38 @@ function C4EdgeLabels({
  * the same `elkPathPoints` this renders. React Flow's built-in edge would curve
  * between handles while the chip sat on ELK's orthogonal route, which is why
  * labels read as "off the line".
+ *
+ * Two strokes: an invisible wide hit path (the drawn line is 1px, hopeless to
+ * click) and the visible one. The selection emphasis is a heavier stroke on
+ * the same geometry, so the selected line reads without redrawing the route.
  */
-function C4EdgeView({ data, markerEnd }: EdgeProps<Edge<{ path?: string; color?: string }>>) {
+function C4EdgeView({
+  data,
+  markerEnd,
+}: EdgeProps<Edge<{ path?: string; color?: string; selected?: boolean; dimmed?: boolean }>>) {
   const path = data?.path ?? '';
   if (!path) return null;
+  const selected = data?.selected === true;
+  const dimmed = data?.dimmed === true;
   return (
-    <path
-      d={path}
-      fill="none"
-      stroke={data?.color}
-      strokeWidth={1}
-      strokeDasharray="6 4"
-      markerEnd={markerEnd}
-      style={{ pointerEvents: 'none' }}
-    />
+    <>
+      <path
+        d={path}
+        fill="none"
+        stroke="transparent"
+        strokeWidth={14}
+        style={{ pointerEvents: 'auto', cursor: 'pointer' }}
+      />
+      <path
+        d={path}
+        fill="none"
+        stroke={data?.color}
+        strokeWidth={selected ? 2.5 : 1}
+        strokeDasharray="6 4"
+        markerEnd={markerEnd}
+        style={{ pointerEvents: 'none', opacity: dimmed ? 0.18 : 1, transition: 'opacity 220ms ease' }}
+      />
+    </>
   );
 }
 
@@ -276,6 +607,12 @@ function C4GroupView(
       /** FLIP: absolute flow rects — where to grow from, and the frame's own. */
       growFrom?: FlowRect;
       frameRect?: FlowRect;
+      /** Arriving in this layout — fades in. */
+      entering?: boolean;
+      /** Gone from this layout — kept for the morph, fades out. */
+      leaving?: boolean;
+      /** The move/grow waits this long for the fade to finish, in ms. */
+      moveDelayMs?: number;
     }>
   >,
 ) {
@@ -284,7 +621,7 @@ function C4GroupView(
   const isSystem = props.data.kind === 'system';
   const onCollapse = props.data.onCollapse;
   const brand = props.data.brand;
-  const { growFrom, frameRect } = props.data;
+  const { growFrom, frameRect, entering, leaving, moveDelayMs = 0 } = props.data;
 
   // Position-only FLIP, same as the cards. The frame resizes through its own
   // width/height transition below, so scaling here would fight it *and* distort
@@ -292,6 +629,7 @@ function C4GroupView(
   // label chip's border and text scale with it.
   const { flipping, placed, dx, dy } = useFlip(growFrom, frameRect);
   const sliding = flipping && (dx !== 0 || dy !== 0);
+  const fade = useFade(entering, leaving);
 
   // A container frame shows its technology mark (React/Bun/Node…) so the
   // boundary says what it is built with, same as the node it wraps. The system
@@ -310,10 +648,12 @@ function C4GroupView(
         // Size is always transitioned; the transform only while sliding, and
         // `transform: none` needs no transition.
         transition: [
-          'width 420ms ease-out',
-          'height 420ms ease-out',
-          ...(sliding && placed ? [`transform ${MORPH_MS}ms ease-out`] : []),
+          `width ${MORPH_MS}ms ease-out ${moveDelayMs}ms`,
+          `height ${MORPH_MS}ms ease-out ${moveDelayMs}ms`,
+          ...(fade.transition ? [fade.transition] : []),
+          ...(sliding && placed ? [`transform ${MORPH_MS}ms ease-out ${moveDelayMs}ms`] : []),
         ].join(', '),
+        opacity: fade.opacity,
         boxSizing: 'border-box',
         borderRadius: 12,
         border: `2px dashed ${color}`,
@@ -387,19 +727,68 @@ function C4GroupView(
   );
 }
 
+/**
+ * The component graph's own node, wrapped in the C4 canvas's FLIP so a construct
+ * glides to its new slot when the layout reflows. On its own it would only mount
+ * at the destination — a jump. Position-only, matching the C4 cards.
+ */
+const SubsystemNode = SubsystemComponentNode as unknown as ComponentType<NodeProps>;
+
+function C4SubsystemNodeView(props: NodeProps) {
+  const { growFrom, frameRect, entering, leaving, moveDelayMs = 0 } = props.data as {
+    growFrom?: FlowRect;
+    frameRect?: FlowRect;
+    entering?: boolean;
+    leaving?: boolean;
+    moveDelayMs?: number;
+  };
+  const { flipping, placed, dx, dy } = useFlip(growFrom, frameRect);
+  const sliding = flipping && (dx !== 0 || dy !== 0);
+  const fade = useFade(entering, leaving);
+  const transitions = [
+    ...(fade.transition ? [fade.transition] : []),
+    ...(sliding && placed ? [`transform ${MORPH_MS}ms ease-out ${moveDelayMs}ms`] : []),
+  ];
+  return (
+    <div
+      style={{
+        transformOrigin: 'top left',
+        transform: sliding && !placed ? `translate(${dx}px, ${dy}px)` : 'none',
+        transition: transitions.length > 0 ? transitions.join(', ') : 'none',
+        opacity: fade.opacity,
+      }}
+    >
+      <SubsystemNode {...props} />
+    </div>
+  );
+}
+
 const nodeTypes = {
   'c4-node': C4NodeView,
   'c4-group': C4GroupView,
+  // The component graph's own renderers, reused for the constructs a container
+  // hosts. They are context-light (ThemeProvider + a React Flow ancestor), which
+  // is why they can ride this canvas instead of a nested one.
+  'subsystem-component': C4SubsystemNodeView as never,
 };
 const edgeTypes = {
   'c4-edge': C4EdgeView,
+  'subsystem-edge': SubsystemEdge as never,
 };
 
 /** Drill-down animation durations, in ms. */
 const MORPH_MS = 420;
 const CAMERA_MS = 520;
 /**
- * When to re-frame the camera after a drill-down: the morph, plus a beat.
+ * How long cards arriving or leaving take to fade, in ms. The morph is
+ * sequenced: the fade runs first, and the surviving cards wait it out before
+ * they move and grow (`moveDelayMs` below). So the reveal clock is
+ * `FADE_MS + MORPH_MS`, not just `MORPH_MS`.
+ */
+const FADE_MS = 200;
+/**
+ * When to re-frame the camera after a drill-down: the sequenced morph (fade,
+ * then move), plus a beat.
  *
  * The extra 60ms is not padding for looks. `fitView` reads the system frame's
  * *measured* size, and that frame's own height transition runs on the same
@@ -407,7 +796,7 @@ const CAMERA_MS = 520;
  * height that never existed. The beat is for React Flow's resize observer to
  * report the final geometry.
  */
-const CAMERA_AFTER_MORPH_MS = MORPH_MS + 60;
+const CAMERA_AFTER_MORPH_MS = FADE_MS + MORPH_MS + 60;
 
 /** A fully laid-out open state: the RF nodes/edges and label anchors. */
 interface Rendered {
@@ -418,10 +807,50 @@ interface Rendered {
 }
 
 /** Flow-space rect of a box node or a frame, for the drill-down morph. */
-interface FlowRect { x: number; y: number; width: number; height: number }
+export interface FlowRect { x: number; y: number; width: number; height: number }
 
 /** A frame's growth for the drill-down morph: its flow rect before → after. */
-interface FrameGrow { from: FlowRect; to: FlowRect }
+export interface FrameGrow { from: FlowRect; to: FlowRect }
+
+/**
+ * A node's rect in **absolute** flow space, walking the parent chain.
+ *
+ * `groupBounds` is already absolute; a leaf's `position` is relative to its
+ * parent, so each ancestor's origin is added in turn.
+ *
+ * The FLIP needs absolute rects, not parent-relative ones. React Flow places a
+ * node at its new absolute position (parent origin + relative position) and
+ * moves children along with the parent's *wrapper* — while our FLIP transform
+ * lives on the node's inner div, which the children do not inherit. So a node's
+ * own transform must cover its full absolute delta; rebasing it to the parent
+ * would leave it short by exactly the parent's movement (the "subtle drift"
+ * before a leaving box disappears).
+ */
+export function absoluteRectOf(
+  layout: {
+    nodes: ReadonlyArray<{
+      id: string;
+      position: { x: number; y: number };
+      parentId?: string;
+      width?: number | null;
+      height?: number | null;
+    }>;
+    groupBounds: Map<string, { x: number; y: number; width: number; height: number }>;
+  },
+  id: string,
+): FlowRect | null {
+  const frame = layout.groupBounds.get(id);
+  if (frame) return { x: frame.x, y: frame.y, width: frame.width, height: frame.height };
+  const node = layout.nodes.find((n) => n.id === id);
+  if (!node) return null;
+  const origin = node.parentId ? absoluteRectOf(layout, node.parentId) : null;
+  return {
+    x: (origin?.x ?? 0) + node.position.x,
+    y: (origin?.y ?? 0) + node.position.y,
+    width: node.width ?? 0,
+    height: node.height ?? 0,
+  };
+}
 
 /**
  * Whether committing a layout should also move the camera.
@@ -473,9 +902,9 @@ export function showDescriptionFor(open: boolean | undefined, settled: boolean |
  * `result.groupBounds` is absolute for a root-level group and *parent-relative*
  * for a nested one — two spaces in one map, which is the same trap as
  * `result.nodes`. The opened container is nested (inside the system frame), and
- * `containerRect` reads this map before the node box, so an unrebased entry would
- * be handed to the morph offset by the frame's origin: the container would glide
- * to a place it was never drawn.
+ * `absoluteRectOf` reads this map before the node box, so an unrebased entry
+ * would be handed to the morph offset by the frame's origin: the container would
+ * glide to a place it was never drawn.
  */
 export function rebaseGroupBoundsAbsolute(
   result: Pick<ElkLayoutResult, 'absoluteRects' | 'groupBounds'>,
@@ -509,6 +938,7 @@ export function rebaseGroupBoundsAbsolute(
 export function c4GroupDefs(
   model: C4Model,
   openIds?: readonly string[],
+  constructGraphByContainer?: ReadonlyMap<string, C4ConstructGraph>,
 ): { frames: C4Group[]; groups: CompoundGroupDef[] } {
   // Normalized here rather than trusted from the caller. This function's output is
   // cached under the open *set*, so a repeated id would emit the same group twice
@@ -542,10 +972,26 @@ export function c4GroupDefs(
       const openMembers = model.nodes
         .filter((n) => n.kind === 'component' && (n.container ?? n.parentId) === openId)
         .map((n) => n.id);
-      if (openMembers.length === 0) continue;
+      // The constructs this container hosts, grouped under the authored component
+      // that claims each (which grows into its own ELK parent below); a construct
+      // no component claims nests directly under the container.
+      const cg = constructGraphByContainer?.get(openId);
+      const byComponent = new Map<string, string[]>();
+      const orphans: string[] = [];
+      for (const c of cg?.components ?? []) {
+        const owner = cg?.componentOf?.get(c.alias);
+        if (owner) {
+          const list = byComponent.get(owner) ?? [];
+          list.push(c.alias);
+          byComponent.set(owner, list);
+        } else {
+          orphans.push(c.alias);
+        }
+      }
+      if (openMembers.length === 0 && orphans.length === 0) continue;
       groups.push({
         id: openId,
-        memberIds: openMembers,
+        memberIds: [...openMembers, ...orphans],
         // INSIDE the system frame, not beside it. The boundary *is* the system, so
         // a sibling here would draw the opened container outside the very boundary
         // it belongs to.
@@ -565,27 +1011,30 @@ export function c4GroupDefs(
         // knows which one a bare member id means.
         drawnAsCard: true,
       });
+      // A component that claims constructs grows into an ELK parent as well, so
+      // its constructs nest inside it (container → component → construct) rather
+      // than sitting beside it.
+      for (const [componentId, memberIds] of byComponent) {
+        if (memberIds.length === 0) continue;
+        groups.push({
+          id: componentId,
+          memberIds,
+          parentId: openId,
+          minWidth: COMPONENT_W,
+          // A component card's header is its label slot + padding; it has no
+          // technology row and no collapse affordance.
+          padTop: COMPONENT_HEADER_PAD,
+          padBottom: COMPONENT_FOOTER_PAD,
+          padX: OPEN_SIDE_PAD,
+          drawnAsCard: true,
+        });
+      }
     }
   }
 
   return { frames, groups };
 }
 
-/** The container's rect in a laid-out state: its box node, or its frame bounds. */
-function containerRect(layout: Rendered | undefined, id: string): FlowRect | null {
-  if (!layout) return null;
-  const frame = layout.groupBounds.get(id);
-  if (frame) return { x: frame.x, y: frame.y, width: frame.width, height: frame.height };
-  const node = layout.nodes.find((n) => n.id === id);
-  if (!node) return null;
-  return {
-    x: node.position.x,
-    y: node.position.y,
-    width: node.width ?? 0,
-    height: node.height ?? 0,
-  };
-}
-
 /**
  * FLIP between two absolute flow rects: render transformed back onto `from`,
  * then release onto `to`.
@@ -621,6 +1070,23 @@ function useFlip(from: FlowRect | undefined, to: FlowRect | undefined) {
   };
 }
 
+/**
+ * Opacity for a card arriving or leaving the layout. An arriving card mounts
+ * hidden and fades in; a leaving card is kept (out of the new layout) for the
+ * morph, then fades out — a removal reads as a fade, not a pop.
+ */
+function useFade(entering?: boolean, leaving?: boolean) {
+  const animate = entering === true || leaving === true;
+  const [shown, setShown] = useState(entering !== true);
+  useEffect(() => {
+    if (!animate) return;
+    const raf = requestAnimationFrame(() => setShown(leaving !== true));
+    return () => cancelAnimationFrame(raf);
+  }, [animate, entering, leaving]);
+  if (!animate) return { opacity: 1, transition: undefined as string | undefined };
+  return { opacity: shown ? 1 : 0, transition: `opacity ${FADE_MS}ms ease` };
+}
+
 /**
  * Whether a nested component is withheld while the diagram is mid-morph.
  *
@@ -646,14 +1112,23 @@ export function hidesComponentDuringMorph(
   return morphTargets.has(owner);
 }
 
-function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onCloseContainer, gutter = 28 }: C4GraphProps) {
-  const { theme } = useTheme();
-  const { fitView } = useReactFlow();
+function Inner({ model, onSelectNode, onSelectEdge, onTrailClick, onToggleContainer, onOpenContainer, onCloseContainer, gutter = 28, dimmedElementIds, dimmedEdgeIds, hiddenElementIds, hiddenEdgeIds, dimmedConstructIds, dimmedConstructEdgeIds, constructGraphByContainer, focusedStep, onCloseStep, renderFileViewer, renderTrailViewer, hideDrawer = false }: C4GraphProps) {
+  const { theme, mode } = useTheme();
+  const { fitView, fitBounds } = useReactFlow();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const [nodes, setNodes] = useState<Node[]>([]);
+  /** Latest rendered nodes, for the step-focus camera fit without re-firing on
+   *  every layout change. */
+  const nodesRef = useRef<Node[]>([]);
+  nodesRef.current = nodes;
   const [rfEdges, setRfEdges] = useState<Edge[]>([]);
   const [ready, setReady] = useState(false);
   const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [selectedEdgeId, setSelectedEdgeId] = useState<string | null>(null);
+  // The construct (subsystem component alias) whose functionality (declaration
+  // + purpose) is open. Its own panel, so opening a construct never disturbs the
+  // node/edge inspector.
+  const [selectedConstructAlias, setSelectedConstructAlias] = useState<string | null>(null);
   const [labelPositions, setLabelPositions] = useState<Map<string, { x: number; y: number }>>(
     () => new Map(),
   );
@@ -682,7 +1157,7 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
       if (cache.size <= LAYOUT_CACHE_MAX) break;
       // Never evict what is on screen: a re-layout of the current state mid-morph
       // would swap the geometry out from under the transition.
-      if (oldest === openStateKey(openIds)) continue;
+      if (oldest === currentCacheKeyRef.current) continue;
       cache.delete(oldest);
     }
   };
@@ -704,12 +1179,29 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
   const settleTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   /** The post-morph re-frame; see `CAMERA_AFTER_MORPH_MS`. */
   const cameraTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  /** Drops cards that were kept only to fade out. */
+  const leaverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  /**
+   * The dim set of the *previous* render, read when a card starts leaving so it
+   * fades from the opacity it actually had. A hover preview dims the non-cast
+   * boxes; clicking the trail clears the hover, so without this a leaving box
+   * would brighten to full before fading.
+   */
+  const prevDimmedRef = useRef<ReadonlySet<string> | null>(null);
   /**
    * The open set rendered last, so a change can morph between the two layouts.
    * The array, not just its key, because the morph needs to know *which*
    * containers changed — see `morphTargetsRef`.
    */
   const prevOpenRef = useRef<string[]>([]);
+  /**
+   * The layout-cache key rendered last, and the one on screen now. The key
+   * carries the construct counts too (a card's box grows with its rows), so a
+   * focus change that keeps the same containers open still misses the cache and
+   * recomputes — and the morph reads the previous entry by its own key.
+   */
+  const prevCacheKeyRef = useRef('');
+  const currentCacheKeyRef = useRef('');
   /**
    * Containers whose open state is changing *right now* — the symmetric
    * difference of the previous and next open sets.
@@ -787,16 +1279,44 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
   const openIds = useMemo(() => openContainerSet(model), [model]);
   const openKey = openStateKey(openIds);
 
-  const layoutKey = useMemo(
+  // The constructs a container hosts change its layout, so a focus shift that
+  // swaps them (same containers open) must recompute — keyed here or the stale
+  // box would stand.
+  const constructKey = useMemo(
+    () =>
+      constructGraphByContainer
+        ? [...constructGraphByContainer.entries()]
+            .map(
+              ([id, cg]) =>
+                `${id}\0${cg.components.map((c) => c.alias).sort().join(',')}`,
+            )
+            .sort()
+            .join('\n')
+        : '',
+    [constructGraphByContainer],
+  );
+
+  // The model's own shape — which boxes and lines exist. Part of the cache key
+  // so a host that filters the model (e.g. down to a focused trail's cast)
+  // re-lays-out instead of hitting a stale layout for the same open set.
+  const modelKey = useMemo(
     () =>
       [
         ...model.nodes.map((n) => `${n.id}\0${n.parentId ?? ''}\0${n.label}`).sort(),
         ...model.edges.map((e) => `${e.id}\0${e.count}`).sort(),
-        `open:${openKey}`,
       ].join('\n'),
-    [model, openKey],
+    [model],
+  );
+
+  const layoutKey = useMemo(
+    () => `${modelKey}\nopen:${openKey}\nconstructs:${constructKey}`,
+    [modelKey, openKey, constructKey],
   );
 
+  /** The identity of one laid-out state — open set + constructs + model shape. */
+  const stateKey = (ids: readonly string[]) =>
+    `${openStateKey(ids)}|${constructKey}|${modelKey}`;
+
   /**
    * Build the React Flow inputs for a given open state — everything ELK needs,
    * independent of whether a layout has been run yet. Pure over `openIds`, so it
@@ -822,6 +1342,21 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
       if (parent) childComponentCount.set(parent, (childComponentCount.get(parent) ?? 0) + 1);
     }
 
+    // Authored components that claim constructs grow into ELK parents too, so
+    // they are drawn as grown cards (absolute box, no description) exactly like
+    // an opened container.
+    const groupedComponentIds = new Set<string>();
+    if (model.view === 'container') {
+      for (const openId of openIds) {
+        const cg = constructGraphByContainer?.get(openId);
+        if (!cg) continue;
+        for (const c of cg.components) {
+          const owner = cg.componentOf?.get(c.alias);
+          if (owner) groupedComponentIds.add(owner);
+        }
+      }
+    }
+
     const rfNodes: Node[] = model.nodes.filter(inView).map((n, i) => {
       const size = nodeSize(n);
       // A component of an opened container nests under *its own* container (a
@@ -853,11 +1388,44 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
           ...(n.kind === 'container' && (childComponentCount.get(n.id) ?? 0) > 0 && canToggle
             ? { onExpand: () => toggle(n.id), open: opened.has(n.id) }
             : {}),
+          // A component grown to hold its constructs is a drawn-as-card group:
+          // no description, absolute box, sized by ELK.
+          ...(n.kind === 'component' && groupedComponentIds.has(n.id) ? { open: true } : {}),
         },
       };
     });
 
-    const { frames, groups } = c4GroupDefs(model, openIds);
+    // Constructs: the component graph's own nodes and edges, nested inside their
+    // opened container (under the authored component that claims each). Built
+    // per container so an edge never crosses containers — a construct edge that
+    // would is left to the C4 container-level line.
+    const constructEdges: Edge[] = [];
+    if (model.view === 'container') {
+      for (const openId of openIds) {
+        const cg = constructGraphByContainer?.get(openId);
+        if (!cg || cg.components.length === 0) continue;
+        const subNodes = convertSubsystemToNodes({
+          components: [...cg.components],
+          trails: [...cg.trails],
+        });
+        for (const sn of subNodes) {
+          const owner = cg.componentOf?.get(sn.id) ?? openId;
+          rfNodes.push({
+            ...sn,
+            parentId: owner,
+            zIndex: 3,
+            // `c4Owner` is the container this construct belongs to, read by the
+            // morph/dim pass; it is not part of the node's own render.
+            data: { ...sn.data, c4Owner: openId },
+          });
+        }
+        constructEdges.push(
+          ...convertSubsystemToEdges({ components: [...cg.components], trails: [...cg.trails] }),
+        );
+      }
+    }
+
+    const { frames, groups } = c4GroupDefs(model, openIds, constructGraphByContainer);
 
     // Bands come from the *frames* only. The opened container is an ELK parent,
     // not a band — treating it as one would push it into its own layer, away from
@@ -888,6 +1456,12 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
           data: { edge: e, color, path: '' },
         };
       });
+    // Construct edges attach only when both endpoints are drawn — a step to an
+    // external, or to a construct in another container, is dropped here and left
+    // to the C4 container-level line.
+    for (const e of constructEdges) {
+      if (drawnIds.has(e.source) && drawnIds.has(e.target)) rfEdges.push(e);
+    }
 
     return { rfNodes, rfEdges, groups, partitionByNode, frames };
   };
@@ -936,20 +1510,30 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
     const withPaths = rfEdges.map((e) => {
       const pts = result.edgePathPoints?.get(e.id);
       if (!pts || pts.length === 0) return e;
+      const path = pointsToSmoothPath(pts, 12);
+      // The component graph's edge renderer reads `elkPath` (and its label
+      // overlay reads `labelX/labelY`); the C4 renderer reads `path`. Set each
+      // so the right renderer draws its own route and its own label anchor.
+      if (e.type === 'subsystem-edge') {
+        const mid = pointAlongPath(pts, 0.5);
+        return { ...e, data: { ...e.data, elkPath: path, labelX: mid.x, labelY: mid.y } };
+      }
       labelPositions.set(e.id, pointAlongPath(pts, 0.5));
-      return { ...e, data: { ...e.data, path: pointsToSmoothPath(pts, 12) } };
+      return { ...e, data: { ...e.data, path } };
     });
 
     // `result.groupBounds` mixes coordinate spaces; everything downstream here
     // reads it as absolute, so normalize it once at the boundary.
     const groupBounds = rebaseGroupBoundsAbsolute(result);
     const builtGroups = new Set(groupBounds.keys());
-    // The opened containers come back from ELK as parents, so they land in
-    // `groupBounds` — but each is drawn as a grown *card*, not a frame. Drop them
-    // all from the shells; keep them in `groupBounds` so their nested children can
+    // Every group drawn as a grown *card* (opened containers, and components
+    // grown to hold their constructs) comes back from ELK as a parent, so it
+    // lands in `groupBounds` — but it is drawn as a card, not a frame. Drop each
+    // from the shells; keep them in `groupBounds` so their nested children can
     // take their coordinates relative to them.
+    const drawnAsCardIds = new Set(groups.filter((g) => g.drawnAsCard).map((g) => g.id));
     const shellBounds = new Map(groupBounds);
-    for (const openId of openIds) shellBounds.delete(openId);
+    for (const id of drawnAsCardIds) shellBounds.delete(id);
 
     const groupById = new Map(frames.map((g) => [g.id, g]));
     const depthOf = (id: string): number => {
@@ -1013,28 +1597,22 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
       });
 
     const leaves = rfNodes.map((n) => {
+      // The parent is whatever `buildInputs` already stamped on the node — a
+      // component's container, or a construct's component/container — kept only
+      // when ELK actually built that group (a closed container is not one). This
+      // covers the construct nodes too, whose data carries no `element`.
       let parentId: string | undefined;
-      if (n.data && typeof n.data === 'object') {
-        const modelNode = (n.data as { element?: C4Element }).element;
-        // A component nests under its own container when that container is open —
-        // the sibling containers and out-of-boundary nodes in the same layout must
-        // not. Reads the component's own owner rather than a single open id,
-        // because several containers can be open at once.
-        const owner =
-          modelNode?.kind === 'component' ? (modelNode.container ?? modelNode.parentId) : undefined;
-        const nested = owner && opened.has(owner) ? owner : undefined;
-        const candidate = nested ?? modelNode?.parentId;
-        if (candidate && builtGroups.has(candidate)) parentId = candidate;
-      }
+      if (n.parentId && builtGroups.has(n.parentId)) parentId = n.parentId;
       // `flowPositionOf` covers every node ELK placed; the fallback is for the
       // pathological case of a node ELK did not return at all.
       const abs =
         flowPositionOf(result, n.id, parentId) ??
         positioned.get(n.id)?.position ??
         n.position;
-      // An opened container is an ELK parent, so its box is whatever ELK fitted
-      // to the nested components — `nodeSize` only knows the closed card.
-      const fitted = opened.has(n.id) ? groupBounds.get(n.id) : undefined;
+      // A grown card (an opened container, or a component holding its
+      // constructs) is an ELK parent, so its box is whatever ELK fitted to its
+      // nested children — `nodeSize` only knows the closed card.
+      const fitted = drawnAsCardIds.has(n.id) ? groupBounds.get(n.id) : undefined;
       const node = {
         ...n,
         position: { x: abs.x, y: abs.y },
@@ -1056,17 +1634,40 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
     if (!grows || grows.size === 0) return nodes;
     return nodes.map((n) => {
       const g = grows.get(n.id);
-      // A child is hidden until the morph settles, and its absolute position also
-      // moves with its parent — one transform on the parent covers both.
-      if (!g || n.parentId) return n;
-      return n.type === 'c4-group' || n.type === 'c4-node'
-        ? { ...n, data: { ...n.data, growFrom: g.from, frameRect: g.to } }
-        : n;
+      if (!g) return n;
+      if (n.type !== 'c4-group' && n.type !== 'c4-node' && n.type !== 'subsystem-component') {
+        return n;
+      }
+      // Absolute rects for every node — root or nested. `useFlip` turns them into
+      // the absolute delta the node's inner div must travel; React Flow has
+      // already moved the wrapper (and its children) to the new absolute slot.
+      return { ...n, data: { ...n.data, growFrom: g.from, frameRect: g.to } };
     });
   };
 
-  const renderLayout = (r: Rendered, grows: Map<string, FrameGrow> | null) => {
-    setNodes(injectGrow(r.nodes, grows));
+  const renderLayout = (
+    r: Rendered,
+    grows: Map<string, FrameGrow> | null,
+    morph?: { prevNodeIds: Set<string>; leavers: Node[]; moveDelayMs: number },
+  ) => {
+    // Mark cards that were not in the previous layout so they fade in; keep the
+    // previous layout's orphans (leavers) so they fade out instead of popping.
+    // Every card also carries the move delay, so the survivors' glide and grow
+    // wait for the fade to finish (the sequenced morph).
+    const moveDelayMs = morph?.moveDelayMs ?? 0;
+    const marked = morph
+      ? r.nodes.map((n) => {
+          const base = morph.prevNodeIds.has(n.id)
+            ? n
+            : { ...n, data: { ...n.data, entering: true } };
+          return { ...base, data: { ...base.data, moveDelayMs } };
+        })
+      : r.nodes;
+    const leavers = (morph?.leavers ?? []).map((n) => ({
+      ...n,
+      data: { ...n.data, moveDelayMs },
+    }));
+    setNodes([...injectGrow(marked, grows), ...leavers]);
     setRfEdges(r.edges);
     setLabelPositions(r.labelPositions);
     setReady(true);
@@ -1077,33 +1678,34 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
   // (instant swap), else computes it now.
   useEffect(() => {
     let alive = true;
-    setReady(false);
+    // Blank the canvas only for the very first paint. A relayout keeps the
+    // previous layout on screen until the new one lands — otherwise every trail
+    // pick (which changes the open set and the construct graph, so the cache
+    // misses) flashed the "Laying out…" overlay.
+    if (!paintedRef.current) setReady(false);
     setSelectedId(null);
     const openKeyNow = openStateKey(openIds);
+    const cacheKeyNow = stateKey(openIds);
+    currentCacheKeyRef.current = cacheKeyNow;
     const prevOpen = prevOpenRef.current;
+    const prevCacheKey = prevCacheKeyRef.current;
+    // Captured now, not inside `applyLayout`: the layout may compute async, and
+    // the tracking effect below clears the ref before that runs. This is the dim
+    // set of the render just gone (the hover preview).
+    const prevDimmed = prevDimmedRef.current;
     const inputs = buildInputs(openIds);
 
-    // Only a real open-state change animates; the first paint is already at rest.
+    // The containers whose open state changed *this* tick — the only ones whose
+    // components genuinely arrive or leave. Recorded as a ref rather than state:
+    // it is read during the next render (to decide what to hide) but must not
+    // itself schedule a render.
     if (paintedRef.current && openStateKey(prevOpen) !== openKeyNow) {
-      // The containers in one set and not the other are the ones whose components
-      // actually arrive or leave. Recorded as a ref rather than state: it is read
-      // during the next render (to decide what to hide) but must not itself
-      // schedule a render.
       const before = new Set(prevOpen);
       const after = new Set(openIds);
       morphTargetsRef.current = new Set([
         ...prevOpen.filter((id) => !after.has(id)),
         ...openIds.filter((id) => !before.has(id)),
       ]);
-      setSettled(false);
-      if (settleTimer.current) clearTimeout(settleTimer.current);
-      settleTimer.current = setTimeout(() => {
-        setSettled(true);
-        // The morph is over. Clearing the targets matters: an unrelated re-render
-        // afterwards must not find a container still marked mid-morph and hide
-        // components that are merely sitting still.
-        morphTargetsRef.current = new Set();
-      }, MORPH_MS);
       // Re-frame once the grow has landed, not while it is running. The drill-down
       // more than doubles the boundary, so the extent the camera was fitted to no
       // longer contains the content — but moving *during* the morph compounds with
@@ -1112,6 +1714,8 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
       // out the morph is the honest way to get both.
       if (cameraTimer.current) clearTimeout(cameraTimer.current);
       cameraTimer.current = setTimeout(fitSystem, CAMERA_AFTER_MORPH_MS);
+    } else {
+      morphTargetsRef.current = new Set();
     }
     paintedRef.current = true;
 
@@ -1120,28 +1724,28 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
      * boundaries *and* cards grow/shrink and slide together. Empty when nothing
      * changed (e.g. the initial paint).
      *
-     * Frames alone are not enough: ELK re-lays out the whole diagram, so every
-     * root card moves too. Without a card in this set it keeps its new slot the
-     * instant the layout swaps — a teleport, which is the most visible part of a
-     * bad morph. Child nodes are excluded: a transform on them would only fight
-     * the parent's, which carries the same movement.
+     * This covers *nested* cards too (a container inside the system frame, a
+     * component inside a grown container). They are React Flow children, so the
+     * FLIP rects are rebased to their parent's origin in `injectGrow` — a
+     * transform on a child then composes with the parent's instead of fighting
+     * it. Without this, filtering the model to a trail's cast reflowed the
+     * surviving containers and they teleported to their new slots.
      */
     const growsFor = (next: Rendered): Map<string, FrameGrow> | null => {
-      if (openStateKey(prevOpen) === openKeyNow) return null;
-      const prevLayout = layoutCache.current.get(openStateKey(prevOpen));
+      if (!paintedRef.current) return null;
+      const prevLayout = layoutCache.current.get(prevCacheKey);
       if (!prevLayout) return null;
       const grows = new Map<string, FrameGrow>();
-      const rootCardIds = (l: Rendered) =>
-        l.nodes.filter((n) => !n.parentId).map((n) => n.id);
+      const cardIds = (l: Rendered) => l.nodes.map((n) => n.id);
       const ids = new Set([
         ...prevLayout.groupBounds.keys(),
         ...next.groupBounds.keys(),
-        ...rootCardIds(prevLayout),
-        ...rootCardIds(next),
+        ...cardIds(prevLayout),
+        ...cardIds(next),
       ]);
       for (const id of ids) {
-        const fromRect = containerRect(prevLayout, id);
-        const to = containerRect(next, id);
+        const fromRect = absoluteRectOf(prevLayout, id);
+        const to = absoluteRectOf(next, id);
         if (!fromRect || !to) continue;
         if (
           fromRect.x === to.x &&
@@ -1156,10 +1760,77 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
       return grows.size > 0 ? grows : null;
     };
 
-    const cached = layoutCache.current.get(openKeyNow);
-    if (cached) {
+    // Commit a new layout: keep the survivors gliding (FLIP), fade in cards the
+    // previous layout did not have, and hold the previous layout's orphans for
+    // one morph so they fade out rather than pop. Then advance the refs.
+    const applyLayout = (r: Rendered) => {
+      const prevLayout = layoutCache.current.get(prevCacheKey);
+      const span = growsFor(r);
+      const prevNodeIds = new Set((prevLayout?.nodes ?? []).map((n) => n.id));
+      const nextIds = new Set(r.nodes.map((n) => n.id));
+      // A leaving card is rendered as a *root* node pinned to its old absolute
+      // rect. Nested under its old parent it would ride that parent's React Flow
+      // wrapper — which moves the instant the new layout commits — and drift
+      // before it faded. As a root it stays put and just fades.
+      const leavers: Node[] = prevLayout
+        ? prevLayout.nodes
+            .filter((n) => !nextIds.has(n.id))
+            .map((n) => {
+              const rect = absoluteRectOf(prevLayout, n.id);
+              // Keep the dim it had while hovered, so the fade starts from the
+              // faded opacity instead of flashing back to full first.
+              const el = (n.data as { element?: C4Element } | undefined)?.element;
+              const wasDimmed = el ? prevDimmed?.has(el.id) === true : false;
+              return {
+                ...n,
+                parentId: undefined,
+                position: rect ? { x: rect.x, y: rect.y } : n.position,
+                ...(rect ? { width: rect.width, height: rect.height } : {}),
+                data: { ...n.data, leaving: true, ...(wasDimmed ? { dimmed: true } : {}) },
+              };
+            })
+        : [];
+      // Only *root* fades (a container arriving or leaving) sequence the move.
+      // Nested cards (components, constructs) are withheld by the morph gate
+      // while their container grows, so their entering/leaving is not a fade the
+      // reader sees — delaying the grow for them would just add a pause.
+      const rootEntering = prevLayout
+        ? r.nodes.filter((n) => !n.parentId && !prevNodeIds.has(n.id)).length
+        : 0;
+      const rootLeaving = leavers.filter((n) => !n.parentId).length;
+      const moveDelayMs = rootEntering > 0 || rootLeaving > 0 ? FADE_MS : 0;
+      // The edges are withheld for the whole sequenced morph — fade, then move,
+      // then content. The morphing containers' components are withheld too (see
+      // `morphTargetsRef`).
+      if (span) {
+        setSettled(false);
+        if (settleTimer.current) clearTimeout(settleTimer.current);
+        settleTimer.current = setTimeout(() => {
+          setSettled(true);
+          morphTargetsRef.current = new Set();
+        }, moveDelayMs + MORPH_MS);
+      }
+      if (leaverTimer.current) clearTimeout(leaverTimer.current);
+      if (leavers.length > 0) {
+        const leavingIds = new Set(leavers.map((n) => n.id));
+        // A leaver only fades; it does not move, so it is dropped when the fade
+        // ends, just before the survivors start to glide.
+        leaverTimer.current = setTimeout(() => {
+          setNodes((prev) => prev.filter((n) => !leavingIds.has(n.id)));
+        }, FADE_MS + 40);
+      }
       prevOpenRef.current = openIds;
-      renderLayout(cached, growsFor(cached));
+      prevCacheKeyRef.current = cacheKeyNow;
+      renderLayout(
+        r,
+        span,
+        prevLayout ? { prevNodeIds, leavers, moveDelayMs } : undefined,
+      );
+    };
+
+    const cached = layoutCache.current.get(cacheKeyNow);
+    if (cached) {
+      applyLayout(cached);
       return () => {
         alive = false;
       };
@@ -1167,10 +1838,8 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
     void layoutFor(openIds, inputs)
       .then((r) => {
         if (!alive) return;
-        cacheLayout(openKeyNow, r);
-        const span = growsFor(r);
-        prevOpenRef.current = openIds;
-        renderLayout(r, span);
+        cacheLayout(cacheKeyNow, r);
+        applyLayout(r);
       })
       .catch((err) => {
         if (!alive) return;
@@ -1194,10 +1863,22 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
         clearTimeout(cameraTimer.current);
         cameraTimer.current = null;
       }
+      if (leaverTimer.current) {
+        clearTimeout(leaverTimer.current);
+        leaverTimer.current = null;
+      }
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [layoutKey]);
 
+  // Remember this render's dim set for the *next* commit's leavers. Declared
+  // after the layout effect so it runs after it: the layout effect reads the
+  // value the previous render left here (a hover dim), before this overwrites
+  // it with the now-cleared set.
+  useEffect(() => {
+    prevDimmedRef.current = dimmedElementIds ?? null;
+  });
+
   // After the first paint, prefetch the opened layout for every container, so a
   // click swaps to a cached result instead of waiting on ELK.
   useEffect(() => {
@@ -1222,7 +1903,7 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
     void (async () => {
       for (const target of targets) {
         if (!alive) return;
-        const key = openStateKey(target);
+        const key = stateKey(target);
         if (layoutCache.current.has(key)) continue;
         try {
           const r = await layoutFor(target, buildInputs(target));
@@ -1239,11 +1920,93 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [layoutKey, model.view]);
 
+  /** Open a construct's functionality, or close it when re-clicked. */
+  const selectConstruct = useCallback((alias: string) => {
+    setSelectedConstructAlias((cur) => (cur === alias ? null : alias));
+  }, []);
+
+  // Scoped to this canvas so the reused component nodes dispatch into this
+  // graph's selection instead of a mounted component graph's module callbacks.
+  const subsystemCallbacks = useMemo(() => ({ onSelect: selectConstruct }), [selectConstruct]);
+
   const selected = useMemo(
     () => model.nodes.find((n) => n.id === selectedId) ?? null,
     [model, selectedId],
   );
 
+  /** The rolled-up line under selection, when it is an edge. */
+  const selectedEdge = useMemo(
+    () => model.edges.find((e) => e.id === selectedEdgeId) ?? null,
+    [model, selectedEdgeId],
+  );
+
+  /**
+   * The step under persistent focus, resolved from the construct graph's trails
+   * (the drawer shows its implementation). The host owns the selection.
+   */
+  const focusedStepInfo = useMemo(() => {
+    if (!focusedStep) return null;
+    for (const cg of constructGraphByContainer?.values() ?? []) {
+      const trail = cg.trails.find((t) => t.id === focusedStep.trailId);
+      if (!trail) continue;
+      const step = trail.steps[focusedStep.stepIndex];
+      if (!step) continue;
+      return { trail, step, stepIndex: focusedStep.stepIndex };
+    }
+    return null;
+  }, [focusedStep, constructGraphByContainer]);
+
+  // Frame the focused step's constructs, the way the component graph frames a
+  // focused step's edge: box the `from`/`to` node rects (absolute) and fit.
+  // Waits out the drawer's height transition so the fit uses the reduced canvas.
+  useEffect(() => {
+    if (!focusedStepInfo) return;
+    const rects: FlowRect[] = [];
+    for (const id of [focusedStepInfo.step.from, focusedStepInfo.step.to]) {
+      const r = absoluteRectOf({ nodes: nodesRef.current, groupBounds: new Map() }, id);
+      if (r) rects.push(r);
+    }
+    if (rects.length === 0) return;
+    const minX = Math.min(...rects.map((r) => r.x));
+    const minY = Math.min(...rects.map((r) => r.y));
+    const maxX = Math.max(...rects.map((r) => r.x + r.width));
+    const maxY = Math.max(...rects.map((r) => r.y + r.height));
+    const bounds = {
+      x: minX,
+      y: minY,
+      width: Math.max(1, maxX - minX),
+      height: Math.max(1, maxY - minY),
+    };
+    const timer = setTimeout(() => {
+      requestAnimationFrame(() => fitBounds(bounds, { padding: 0.2, duration: MORPH_MS }));
+    }, FILE_DRAWER_HEIGHT_MS + 20);
+    return () => clearTimeout(timer);
+    // `nodesRef` is a ref; `settled` re-fires once the constructs have landed.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [focusedStepInfo, settled, fitBounds]);
+
+  /**
+   * The construct under selection, folded to what the functionality panel
+   * shows. Resolved across every container's construct graph (aliases are unique
+   * in the document, so at most one matches).
+   */
+  const selectedConstruct = useMemo(() => {
+    if (!selectedConstructAlias) return null;
+    for (const cg of constructGraphByContainer?.values() ?? []) {
+      const c = cg.components.find((x) => x.alias === selectedConstructAlias);
+      if (!c) continue;
+      return {
+        component: c,
+        name: deriveNameFromSymbol(c.symbol, c.construct, c.name, c.file, c.stereotype),
+        badge: constructBadgeLabel(c),
+        color: componentColor(c, resolvePierreSyntaxThemeName(mode)),
+        role: rightBadgeLabel(c),
+        declaration: generateDeclarationString(c),
+      };
+    }
+    return null;
+  }, [selectedConstructAlias, constructGraphByContainer, mode]);
+
   /**
    * The components authored inside the selected element, if it is a container.
    * These are `C4Component`s whose `container` names the selected id (or, once
@@ -1254,7 +2017,7 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
     () =>
       selected
         ? model.nodes.filter(
-            (n) =>
+            (n): n is C4Component =>
               n.kind === 'component' &&
               (n.container === selected.id || n.parentId === selected.id),
           )
@@ -1262,33 +2025,93 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
     [model, selected],
   );
 
+  /**
+   * A selected container's member aliases, resolved from the construct graph
+   * (a container's members are derived, not stored — see `C4ElementBase`). Only
+   * populated when the container hosts focused constructs.
+   */
+  const selectedContainerMembers = useMemo(
+    () =>
+      selected?.kind === 'container'
+        ? (constructGraphByContainer?.get(selected.id)?.components ?? []).map((c) => c.alias)
+        : [],
+    [selected, constructGraphByContainer],
+  );
+
   /** The containers open for drill-down, normalized. */
   const openContainerIds = useMemo(() => new Set(openIds), [openIds]);
 
   const displayNodes = useMemo(
     () =>
       nodes.map((n) => {
+        // A card kept only to fade out is never hidden or dimmed — it is on its
+        // way off screen and must stay visible for the fade.
+        if ((n.data as { leaving?: boolean } | undefined)?.leaving) return n;
+        // Constructs are the component graph's own nodes. They ride the morph
+        // gate of the container that hosts them (they arrive with its grow) and
+        // dim with it; the node reads `isSelected` from data because it stops
+        // its own click propagation.
+        if (n.type === 'subsystem-component') {
+          const owner = (n.data as { c4Owner?: string } | undefined)?.c4Owner;
+          const hidden = hidesComponentDuringMorph(
+            owner,
+            openContainerIds,
+            morphTargetsRef.current,
+            settled,
+          );
+          // Dim with its container, or on its own when the host spotlights a
+          // step's constructs (the component graph's per-component behaviour).
+          const ownerDimmed = dimmedElementIds && owner ? dimmedElementIds.has(owner) : false;
+          const stepDimmed = dimmedConstructIds?.has(n.id) === true;
+          return {
+            ...n,
+            ...(hidden ? { hidden: true } : {}),
+            data: {
+              ...n.data,
+              dimmed: ownerDimmed || stepDimmed,
+              isSelected: n.id === selectedConstructAlias,
+            },
+          };
+        }
         if (n.type !== 'c4-node') return n;
         const element = (n.data as { element?: C4Element } | undefined)?.element;
         const owner = element?.kind === 'component' ? (element.container ?? element.parentId) : undefined;
-        // `hidesComponentDuringMorph` owns the rule; see there for why it is
-        // per-container rather than global.
-        const hidden = hidesComponentDuringMorph(
-          owner,
-          openContainerIds,
-          morphTargetsRef.current,
-          settled,
-        );
+        // `hidesComponentDuringMorph` owns the morph rule; see there for why it
+        // is per-container rather than global. A host `hiddenElementIds` (the
+        // focused-trail cast) removes the box outright.
+        const hidden =
+          hidesComponentDuringMorph(
+            owner,
+            openContainerIds,
+            morphTargetsRef.current,
+            settled,
+          ) || (element ? hiddenElementIds?.has(element.id) === true : false);
         return {
           ...n,
           ...(hidden ? { hidden: true } : {}),
-          data: { ...n.data, selected: n.id === selectedId, settled },
+          data: {
+            ...n.data,
+            selected: n.id === selectedId,
+            settled,
+            dimmed: dimmedElementIds
+              ? (element ? dimmedElementIds.has(element.id) : false)
+              : false,
+          },
         };
       }),
     // `morphTargetsRef` is a ref, so it cannot be a dependency; `settled` covers
     // it, because the two always change together — targets are written in the same
     // tick that clears `settled`, and cleared in the same tick that restores it.
-    [nodes, selectedId, settled, openContainerIds],
+    [
+      nodes,
+      selectedId,
+      settled,
+      openContainerIds,
+      dimmedElementIds,
+      dimmedConstructIds,
+      hiddenElementIds,
+      selectedConstructAlias,
+    ],
   );
 
   /**
@@ -1296,15 +2119,112 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
    * gliding between the two slots the old lines would visibly point at the wrong
    * boxes. Hiding them for the morph is honest and cheap; interpolating the
    * polylines to match is not.
+   *
+   * The dim set is the union of
+   *   (a) the own endpoint rule — a line between two dimmed boxes fades with
+   *       them, a line into a lit container stays bright on its own; and
+   *   (b) the host's line-relevance set — edges that don't carry the focused
+   *       trail / hovered step (a step internal to a container folds into no
+   *       line at all, so even lines out of the lit container fade).
+   *
+   * The selected edge never dims: it is the inspector's subject.
    */
+  const dimmedEdgeIdSet = useMemo(() => {
+    if (!dimmedElementIds && !dimmedEdgeIds) return null;
+    const out = new Set<string>();
+    if (dimmedElementIds) {
+      for (const e of rfEdges) {
+        if (dimmedElementIds.has(e.source) && dimmedElementIds.has(e.target)) out.add(e.id);
+      }
+    }
+    if (dimmedEdgeIds) for (const id of dimmedEdgeIds) out.add(id);
+    if (selectedEdgeId) out.delete(selectedEdgeId);
+    return out;
+  }, [dimmedElementIds, dimmedEdgeIds, rfEdges, selectedEdgeId]);
+
+  const hiddenEdgeIdSet = useMemo(() => {
+    if (!hiddenElementIds && !hiddenEdgeIds) return null;
+    const out = new Set<string>();
+    if (hiddenElementIds) {
+      // Either endpoint gone → the line has nothing to attach to, so it goes
+      // with the box (unlike the dim rule, which needs both endpoints dimmed).
+      for (const e of rfEdges) {
+        if (hiddenElementIds.has(e.source) || hiddenElementIds.has(e.target)) out.add(e.id);
+      }
+    }
+    if (hiddenEdgeIds) for (const id of hiddenEdgeIds) out.add(id);
+    return out;
+  }, [hiddenElementIds, hiddenEdgeIds, rfEdges]);
+
   const displayEdges = useMemo(
-    () => (settled ? rfEdges : rfEdges.map((e) => ({ ...e, hidden: true }))),
-    [rfEdges, settled],
+    () =>
+      rfEdges.map((e) => {
+        const hidden = !settled || hiddenEdgeIdSet?.has(e.id) === true;
+        const dimmed =
+          dimmedEdgeIdSet?.has(e.id) === true ||
+          dimmedConstructEdgeIds?.has(e.id) === true;
+        // The arrowhead is a shared SVG marker: dimming the stroke (path opacity
+        // or colour alpha) leaves it at full colour. Clone the marker with a
+        // dimmed colour, as the component graph does.
+        const markerEnd = e.markerEnd;
+        const nextMarker =
+          dimmed && markerEnd && typeof markerEnd === 'object' && typeof markerEnd.color === 'string'
+            ? { ...markerEnd, color: hexWithAlpha(markerEnd.color, EDGE_DIM_ALPHA) }
+            : markerEnd;
+        return {
+          ...e,
+          ...(hidden ? { hidden: true } : {}),
+          markerEnd: nextMarker,
+          data: {
+            ...e.data,
+            selected: e.id === selectedEdgeId,
+            dimmed,
+          },
+        };
+      }),
+    [rfEdges, settled, selectedEdgeId, dimmedEdgeIdSet, hiddenEdgeIdSet, dimmedConstructEdgeIds],
   );
 
-  return (
-    <div style={{ position: 'relative', width: '100%', height: '100%', background: theme.colors.background }}>
+  /** The construct edges, for their mechanism-label overlay (carries the dim flag). */
+  const subsystemLabelEdges = useMemo(
+    () => displayEdges.filter((e) => e.type === 'subsystem-edge'),
+    [displayEdges],
+  );
+
+  // The step drawer: open while a step is focused and a viewer is not hidden.
+  const drawerOpen = focusedStepInfo != null && !hideDrawer;
+  const drawerTitle = focusedStepInfo
+    ? renderTrailViewer
+      ? focusedStepInfo.trail.title
+      : focusedStepInfo.step.file
+    : null;
+  const drawerProgress =
+    focusedStepInfo && focusedStepInfo.trail.steps.length > 1
+      ? { index: focusedStepInfo.stepIndex, total: focusedStepInfo.trail.steps.length }
+      : null;
+
+  // The selection panel floats over the canvas in the top-right corner. A host
+  // that wants the panel (or anything else) beside the graph wraps the graph in
+  // `GraphWithSidebar` itself, so the graph stays overlay-only.
+  const selectionPanelStyle: CSSProperties = {
+    position: 'absolute',
+    top: 12,
+    right: 12,
+    // Above the edge-label overlay (zIndex 5), or chips paint over the panel.
+    zIndex: 10,
+    width: 280,
+    maxHeight: 'calc(100% - 24px)',
+    overflowY: 'auto',
+    background: theme.colors.backgroundSecondary ?? theme.colors.background,
+    border: `1px solid ${theme.colors.border ?? '#333'}`,
+    borderRadius: 8,
+    padding: '10px 12px',
+  };
+
+  const canvasRoot = (
+    <>
       <GraphLayerStyle />
+      <SubsystemCallbacksProvider value={subsystemCallbacks}>
       <ReactFlow
         nodes={displayNodes}
         edges={displayEdges}
@@ -1316,11 +2236,27 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
           if (node.type !== 'c4-node') return;
           const next = node.id === selectedId ? null : node.id;
           setSelectedId(next);
+          setSelectedEdgeId(null);
+          setSelectedConstructAlias(null);
           onSelectNode?.(next);
+          onSelectEdge?.(null);
+        }}
+        onEdgeClick={(_e, edge) => {
+          const next = edge.id === selectedEdgeId ? null : edge.id;
+          setSelectedEdgeId(next);
+          // An edge selection replaces the node panel — the two inspectors
+          // sharing the corner would fight for it.
+          setSelectedId(null);
+          setSelectedConstructAlias(null);
+          onSelectNode?.(null);
+          onSelectEdge?.(next ? (model.edges.find((e) => e.id === next) ?? null) : null);
         }}
         onPaneClick={() => {
           setSelectedId(null);
+          setSelectedEdgeId(null);
+          setSelectedConstructAlias(null);
           onSelectNode?.(null);
+          onSelectEdge?.(null);
         }}
         proOptions={{ hideAttribution: true }}
         // Pin the flow to its container. The label overlay is a sibling sized
@@ -1330,12 +2266,16 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
       >
         <GraphChrome />
       </ReactFlow>
+      </SubsystemCallbacksProvider>
       {/* Gated on `settled`, like the edges themselves: a chip is anchored to the
           *settled* midpoint of its edge, so showing one while the cards glide leaves
           it pointing at the space between two layouts. It rejoins them, the nested
           components and the descriptions in one reveal. */}
       {ready && settled && labelPositions.size > 0 && (
-        <C4EdgeLabels positions={labelPositions} edges={model.edges} />
+        <C4EdgeLabels positions={labelPositions} edges={model.edges} selectedEdgeId={selectedEdgeId} dimmedEdgeIds={dimmedEdgeIdSet} hiddenEdgeIds={hiddenEdgeIdSet} />
+      )}
+      {ready && settled && subsystemLabelEdges.length > 0 && (
+        <SubsystemEdgeLabels edges={subsystemLabelEdges} />
       )}
       {!ready && (
         <div
@@ -1354,24 +2294,12 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
           Laying out C4 view…
         </div>
       )}
+    </>
+  );
+  const selectionPanels = (
+    <>
       {selected && (
-        <div
-          style={{
-            position: 'absolute',
-            top: 12,
-            right: 12,
-            // Above the edge-label overlay (zIndex 5), or chips paint over the
-            // panel.
-            zIndex: 10,
-            width: 280,
-            maxHeight: 'calc(100% - 24px)',
-            overflowY: 'auto',
-            background: theme.colors.backgroundSecondary ?? theme.colors.background,
-            border: `1px solid ${theme.colors.border ?? '#333'}`,
-            borderRadius: 8,
-            padding: '10px 12px',
-          }}
-        >
+        <div style={selectionPanelStyle}>
           <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
             <span style={{ fontFamily: theme.fonts.monospace, fontWeight: 600, color: theme.colors.text, flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
               {selected.label}
@@ -1476,7 +2404,7 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
                       whiteSpace: 'nowrap',
                     }}
                   >
-                    {'technology' in c && c.technology ? c.technology : c.kind}
+                    {c.technology || c.kind}
                     {(c.members ?? []).length > 0 ? ` · ${(c.members ?? []).length} member${(c.members ?? []).length === 1 ? '' : 's'}` : ''}
                   </span>
                 </div>
@@ -1508,8 +2436,8 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
               >
                 Components
               </span>
-              {(selected.members ?? []).length > 0 ? (
-                (selected.members ?? []).map((alias) => (
+              {selectedContainerMembers.length > 0 ? (
+                selectedContainerMembers.map((alias) => (
                   <span
                     key={alias}
                     title={alias}
@@ -1540,6 +2468,290 @@ function Inner({ model, onSelectNode, onToggleContainer, onOpenContainer, onClos
           )}
         </div>
       )}
+
+      {selectedEdge && ready && (
+        <div style={selectionPanelStyle}>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+            <span
+              aria-hidden
+              style={{
+                width: 8,
+                height: 8,
+                borderRadius: '50%',
+                background: protocolColor(selectedEdge.protocol),
+                flexShrink: 0,
+              }}
+            />
+            <span
+              style={{
+                fontFamily: theme.fonts.monospace,
+                fontWeight: 600,
+                color: theme.colors.text,
+                flex: 1,
+                minWidth: 0,
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+              }}
+            >
+              {selectedEdge.label}
+            </span>
+            <button
+              type="button"
+              onClick={() => {
+                setSelectedEdgeId(null);
+                onSelectEdge?.(null);
+              }}
+              aria-label="Clear selection"
+              style={{ border: 'none', background: 'transparent', color: muted, cursor: 'pointer', fontSize: theme.fontSizes[2], lineHeight: 1 }}
+            >
+              ×
+            </button>
+          </div>
+
+          {/* The rollup row: what this line folded up. The protocol color the
+              card already carries is enough — this is the count + verbs. */}
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: 6,
+              flexWrap: 'wrap',
+              marginTop: 6,
+              borderTop: `1px solid ${theme.colors.border ?? '#333'}`,
+              paddingTop: 6,
+            }}
+          >
+            {selectedEdge.mechanisms.map((m) => (
+              <span
+                key={m}
+                style={{
+                  fontFamily: theme.fonts.monospace,
+                  fontSize: theme.fontSizes[0],
+                  color: theme.colors.text,
+                  border: `1px solid ${theme.colors.border ?? '#333'}`,
+                  borderRadius: 4,
+                  padding: '1px 6px',
+                }}
+              >
+                {m}
+              </span>
+            ))}
+            <span style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[0], color: muted }}>
+              {selectedEdge.count} {selectedEdge.count === 1 ? 'step' : 'steps'}
+            </span>
+          </div>
+
+          {/* The drill-down list: the trails this line rolls up, each handed to
+              the host for a deep-link into the component graph. */}
+          <div
+            style={{
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 4,
+              borderTop: `1px solid ${theme.colors.border ?? '#333'}`,
+              paddingTop: 6,
+              marginTop: 6,
+            }}
+          >
+            <span
+              style={{
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[0],
+                color: muted,
+                textTransform: 'uppercase',
+                letterSpacing: 0.5,
+              }}
+            >
+              Backed by trails
+            </span>
+            {(selectedEdge.trailRefs ?? []).length > 0 ? (
+              (selectedEdge.trailRefs ?? []).map((ref) => (
+                <button
+                  key={ref.trailId}
+                  type="button"
+                  onClick={() => onTrailClick?.(ref)}
+                  disabled={!onTrailClick}
+                  title={
+                    onTrailClick
+                      ? `Focus this trail in the component graph`
+                      : 'Trail drill-down needs onTrailClick'
+                  }
+                  style={{
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 6,
+                    textAlign: 'left',
+                    border: 'none',
+                    background: 'transparent',
+                    padding: 0,
+                    cursor: onTrailClick ? 'pointer' : 'default',
+                    fontFamily: theme.fonts.monospace,
+                    fontSize: theme.fontSizes[0],
+                  }}
+                >
+                  <span style={{ color: theme.colors.text, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                    {ref.trailId}
+                  </span>
+                  <span style={{ color: muted, flexShrink: 0 }}>
+                    {ref.stepIndices.length} {ref.stepIndices.length === 1 ? 'step' : 'steps'}
+                    {ref.stepIndices.length > 0 ? ` · #${ref.stepIndices.map((i) => i + 1).join(', #')}` : ''}
+                  </span>
+                </button>
+              ))
+            ) : (
+              <span style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[0], color: muted }}>
+                Authored line — no trail provenance yet
+              </span>
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Construct functionality — a construct row's declaration + purpose,
+          opened from a card. Its own bottom-left panel so it never fights the
+          top-right node/edge inspector for the corner. */}
+      {selectedConstruct && (
+        <div
+          style={{
+            ...selectionPanelStyle,
+            top: 'auto',
+            bottom: 12,
+            left: 12,
+            right: 'auto',
+            width: 320,
+            maxHeight: 'calc(50% - 18px)',
+          }}
+        >
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+            <span
+              aria-hidden
+              style={{
+                width: 8,
+                height: 8,
+                borderRadius: '50%',
+                background: selectedConstruct.color,
+                flexShrink: 0,
+              }}
+            />
+            <span
+              style={{
+                fontFamily: theme.fonts.monospace,
+                fontWeight: 600,
+                color: theme.colors.text,
+                flex: 1,
+                minWidth: 0,
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+              }}
+            >
+              {selectedConstruct.name}
+            </span>
+            <span
+              style={{
+                flexShrink: 0,
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[0],
+                color: muted,
+                textTransform: 'uppercase',
+                letterSpacing: 0.4,
+              }}
+            >
+              {selectedConstruct.badge}
+            </span>
+            <button
+              type="button"
+              onClick={() => setSelectedConstructAlias(null)}
+              aria-label="Clear construct"
+              style={{ border: 'none', background: 'transparent', color: muted, cursor: 'pointer', fontSize: theme.fontSizes[2], lineHeight: 1 }}
+            >
+              ×
+            </button>
+          </div>
+          {selectedConstruct.component.purpose && (
+            <div
+              style={{
+                marginTop: 6,
+                fontFamily: theme.fonts.body,
+                fontSize: theme.fontSizes[0],
+                color: theme.colors.text,
+                lineHeight: 1.4,
+              }}
+            >
+              {selectedConstruct.component.purpose}
+            </div>
+          )}
+          {selectedConstruct.declaration && (
+            <pre
+              style={{
+                marginTop: 6,
+                marginBottom: 0,
+                padding: '6px 8px',
+                borderTop: `1px solid ${theme.colors.border ?? '#333'}`,
+                background: theme.colors.background ?? 'transparent',
+                color: theme.colors.text,
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[0],
+                lineHeight: 1.45,
+                whiteSpace: 'pre-wrap',
+                overflowWrap: 'anywhere',
+              }}
+            >
+              {selectedConstruct.declaration}
+            </pre>
+          )}
+          <div
+            style={{
+              marginTop: 6,
+              fontFamily: theme.fonts.monospace,
+              fontSize: theme.fontSizes[0],
+              color: muted,
+            }}
+          >
+            {selectedConstruct.component.alias}
+            {selectedConstruct.role ? ` · ${selectedConstruct.role}` : ''}
+            {selectedConstruct.component.proposed ? ' · proposed' : ''}
+          </div>
+        </div>
+      )}
+    </>
+  );
+  return (
+    <div
+      style={{
+        position: 'relative',
+        width: '100%',
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        background: theme.colors.background,
+      }}
+    >
+      <div style={{ position: 'relative', flex: 1, minHeight: 0 }}>
+        {canvasRoot}
+        {selectionPanels}
+      </div>
+      <FileDrawer
+        title={drawerOpen ? drawerTitle : null}
+        onClose={() => onCloseStep?.()}
+        hidden={hideDrawer}
+        progress={drawerProgress}
+      >
+        {drawerOpen && focusedStepInfo
+          ? renderTrailViewer
+            ? renderTrailViewer({
+                trail: focusedStepInfo.trail,
+                stepIndex: focusedStepInfo.stepIndex,
+              })
+            : renderFileViewer
+              ? renderFileViewer(focusedStepInfo.step.file, {
+                  startLine: focusedStepInfo.step.span?.startLine,
+                  endLine: focusedStepInfo.step.span?.endLine,
+                })
+              : <StepDrawerFallback step={focusedStepInfo.step} />
+          : null}
+      </FileDrawer>
     </div>
   );
 }