@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/c4/C4Diagram.svelte

@@ -0,0 +1,1511 @@
+<!--
+  C4Diagram.svelte — SvelteFlow + ELK.js C4 model diagram: all four levels
+  (Context, Container, Component, Code), pan/zoom, minimap, nested boundaries
+  and drill-down through `ondrilldown`.
+
+  Live layer (all optional; absent, the widget behaves as it always did):
+  `status` paints a node's state through a `data-c4-status` attribute on its
+  SvelteFlow wrapper (ring colours are ripple tokens; only `changing` moves;
+  `planned` draws a blueprint: dashed outline, no fill, content dimmed;
+  `future` the same blueprint dotted and fainter; `added` a heavier double
+  success ring (landed is a thin single one); `removed` a ghost: card kept,
+  content faded, dashed error-toned outline;
+  written straight to the wrappers, since a new nodes array makes SvelteFlow
+  re-lay every edge),
+  `markers` pins dots to nodes, `selectedId` controls selection, and
+  `focusId` + `follow` keep the camera on one node. A user pan or zoom (the
+  zoom buttons and the minimap included) calls `onmanualcamera`, so a host can
+  drop follow mode. Enter or Space on a focused node runs exactly what a click
+  on it runs (activate.ts), for every node type.
+
+  `highlight` dims (`data-c4-dim`, a DOM write like status) everything outside
+  one element's reach and animates the accent edges inside it (still under
+  reduced motion).
+
+  `flow` + a controlled `step` play a data flow over the map; while a step is current it
+  replaces `highlight`. A message lights its two ends and its relationship (the reach path),
+  shows its label in a port badge and runs a marker along the edge (C4Edge), or along a dashed
+  hop when no relationship carries it (markFlow); a process pulses its element; a note dims
+  nothing. The camera frames a step's elements only when one is off screen (C4LiveLayer). The
+  step is announced through a polite live region; the host draws the transport and the note
+  text, and a click on a connection asks for the next step on it (`onstep`). Stepping only
+  re-decorates the laid-out graph: no ELK.
+
+  Edges follow ELK's orthogonal routes (C4Edge), or curves with arrowheads
+  along them (`edgeShape: 'curved'`); every card fills its ELK box, so routes
+  meet card edges and labels sit in the space ELK reserved.
+
+  SvelteFlow stays mounted across diagram swaps: only the first layout shows
+  the loading state, and C4LiveLayer refits when the node set changes. Layout
+  is keyed on the diagram's content, so a host re-reading the same model (a new
+  object) runs no ELK and moves nothing. The layout spinner stops under
+  prefers-reduced-motion.
+
+  Semantic zoom (pass `expanded`): one canvas for the whole tree. An expanded
+  element opens in place as a boundary around its children (an expanded code
+  element with an excerpt opens as a code panel), `scopeId` ghosts what lies
+  outside it, edges lift onto drawn siblings with port badges and counts, and
+  markers on hidden elements roll up to their drawn ancestor (semantic.ts,
+  semantic-flow.ts). Every semantic node is one SvelteFlow type (C4ViewNode
+  draws data.view), so a node that opens or closes swaps its component without
+  SvelteFlow re-measuring the map. Between layouts nodes glide and resize with the ripple
+  ease, leaving nodes fade where they were (and stay, hidden, until the next
+  layout replaces them: removing them alone is another whole-map pass), edges
+  and markers sit out the move,
+  and the camera eases to the new frame; all instant under reduced motion.
+  Without `expanded` none of this runs and the widget renders as before.
+-->
+<script lang="ts">
+  import { SvelteFlow, Background, Controls, MiniMap } from '@xyflow/svelte';
+  import type { Node, Edge, NodeTypes, EdgeTypes } from '@xyflow/svelte';
+  import '@xyflow/svelte/dist/style.css';
+
+  import { C4_VIEWS } from './nodes/index.js';
+  import C4ViewNode from './nodes/C4ViewNode.svelte';
+  import C4LiveLayer from './C4LiveLayer.svelte';
+  import C4Edge from './C4Edge.svelte';
+  import { setContext, untrack } from 'svelte';
+  import { prefersReducedMotion } from 'svelte/motion';
+  import { computeElkGraph, edgeLabelText, getNodeType, isGroupNode, type LayoutPosition } from './elk-layout.js';
+  import {
+    bundleEdges,
+    decorateEdges,
+    decorateNodes,
+    litIds,
+    markResized,
+    reachSet,
+    presized,
+    nodeSetKey,
+    statusesPresent,
+    unionRect,
+    STATUS_LABELS,
+    EDGE_STROKE,
+    FIT_MIN_ZOOM,
+    edgeLook,
+    linkKey,
+    markFlow,
+    MOVE_MS,
+    type FlowMark,
+    type ReachSet,
+    type Rect,
+  } from './live.js';
+  import { liftMarkers, pathTo, representative, type C4Tree, type Visibility } from './semantic.js';
+  import { buildSemanticFlow, VIEW_NODE } from './semantic-flow.js';
+  import { activateNode } from './activate.js';
+  // From types.ts, NOT the barrel, and aliased: this component is itself named
+  // C4Diagram, and svelte-package emits `declare const C4Diagram` plus
+  // `type C4Diagram` in the .d.ts. An unaliased type import of the same name
+  // collided with both, so consumers saw the component as type-only.
+  import type {
+    C4Diagram as C4DiagramData,
+    C4Element,
+    C4System,
+    C4Container,
+    C4NodeData,
+    C4Status,
+    C4Marker,
+    C4Highlight,
+    C4EdgeShape,
+    C4Flow,
+  } from './types.js';
+
+  interface Props {
+    diagram: C4DiagramData;
+    class?: string;
+    onclick?: (elementId: string) => void;
+    ondrilldown?: (elementId: string, level: string) => void;
+    /** Live state per element id. */
+    status?: Record<string, C4Status>;
+    /** Dots per element id (who is working there). */
+    markers?: Record<string, C4Marker[]>;
+    /** The element the camera frames while `follow` is true. */
+    focusId?: string;
+    follow?: boolean;
+    /** Controlled selection; leave undefined to let clicks select. */
+    selectedId?: string;
+    /** A user pan, zoom or zoom-button press moved the camera. */
+    onmanualcamera?: () => void;
+    /** Semantic zoom: ids drawn open on one canvas. Passing it (even []) turns the mode on. */
+    expanded?: string[];
+    /** Semantic zoom: the element being looked inside; everything outside it is ghosted. */
+    scopeId?: string;
+    /** Light this element's reach (in, out or both, to `depth`, default both and 3); dim the rest. */
+    highlight?: C4Highlight;
+    /** How edges draw along ELK's routes. Default 'orthogonal'. */
+    edgeShape?: C4EdgeShape;
+    /** A data flow to play over the map, one step at a time. */
+    flow?: C4Flow;
+    /** Controlled: the index of the flow's current step. Out of range, no step is shown. */
+    step?: number;
+    /** A connection was clicked: the index of the next step that travels it. */
+    onstep?: (n: number) => void;
+  }
+
+  let {
+    diagram,
+    class: className = '',
+    onclick,
+    ondrilldown,
+    status,
+    markers,
+    focusId,
+    follow,
+    selectedId,
+    onmanualcamera,
+    expanded,
+    scopeId,
+    highlight,
+    edgeShape = 'orthogonal',
+    flow,
+    step,
+    onstep,
+  }: Props = $props();
+
+  // Every C4 view as a SvelteFlow node type (the legacy diagram), plus semantic zoom's one type.
+  const nodeTypes = { ...C4_VIEWS, [VIEW_NODE]: C4ViewNode } as unknown as NodeTypes;
+  /** How a node is drawn: its view under semantic zoom, else its type. */
+  const viewOf = (n: Node) => (n.data as unknown as C4NodeData).view ?? n.type;
+
+  const edgeTypes: EdgeTypes = { c4: C4Edge as any };
+
+  // Level badge labels
+  const levelLabels: Record<string, string> = {
+    context: 'System Context',
+    container: 'Container',
+    component: 'Component',
+    code: 'Code',
+  };
+
+  // Ripple tokens, so the canvas follows the host theme. Edges and the minimap
+  // take colours as strings, which is why these are constants, not CSS.
+  const MINIMAP_NODE = 'color-mix(in oklab, var(--ripple-muted-foreground) 45%, transparent)';
+  const MINIMAP_GROUP = 'color-mix(in oklab, var(--ripple-muted-foreground) 10%, transparent)';
+
+  const SHAPE_LEGEND = [
+    { shape: 'person', label: 'Person' },
+    { shape: 'system', label: 'System' },
+    { shape: 'container', label: 'Container' },
+    { shape: 'database', label: 'Database' },
+    { shape: 'queue', label: 'Queue' },
+    { shape: 'external', label: 'External' },
+  ];
+
+  // ---- ELK layout state ----
+  let flowNodes = $state.raw<Node[]>([]);
+  let flowEdges = $state.raw<Edge[]>([]);
+  let layoutReady = $state(false);
+  let layoutError = $state<string | null>(null);
+
+  // Helpers for classifying C4 elements
+  function isDatabase(el: C4Element): boolean {
+    return 'type' in el && (el as { type?: string }).type === 'database';
+  }
+
+  function isQueue(el: C4Element): boolean {
+    return 'type' in el && (el as { type?: string }).type === 'queue';
+  }
+
+  function hasDrillDown(el: C4Element): boolean {
+    if (el.drillable !== undefined) return el.drillable;
+    return (
+      ('containers' in el && Array.isArray((el as C4System).containers) && ((el as C4System).containers?.length ?? 0) > 0) ||
+      ('components' in el && Array.isArray((el as C4Container).components) && ((el as C4Container).components?.length ?? 0) > 0)
+    );
+  }
+
+  function getSubtype(el: C4Element): string | undefined {
+    if ('type' in el) return (el as { type?: string }).type;
+    return undefined;
+  }
+
+  /**
+   * Build the full flat list of C4 elements to layout, including nested
+   * containers/components that live inside parent system nodes.
+   */
+  function collectAllElements(diagram: C4DiagramData): C4Element[] {
+    const all: C4Element[] = [];
+    for (const el of diagram.elements) {
+      all.push(el);
+      // For context views, also add containers as children of systems
+      // so they appear in the group node layout
+      if ('containers' in el && Array.isArray((el as C4System).containers)) {
+        for (const c of (el as C4System).containers ?? []) {
+          all.push(c as C4Element);
+          if ('components' in c && Array.isArray(c.components)) {
+            for (const comp of c.components ?? []) {
+              all.push(comp as C4Element);
+            }
+          }
+        }
+      }
+      if ('components' in el && Array.isArray((el as C4Container).components)) {
+        for (const comp of (el as C4Container).components ?? []) {
+          all.push(comp as C4Element);
+        }
+      }
+    }
+    return all;
+  }
+
+  /**
+   * Convert the C4 diagram to SvelteFlow Node[] using ELK-computed positions.
+   */
+  async function buildFlowGraph(diagram: C4DiagramData): Promise<{ nodes: Node[]; edges: Edge[] }> {
+    const { positions, routes } = await computeElkGraph(diagram);
+
+    // Gather all elements (top-level and nested children for group nodes)
+    const allElements = collectAllElements(diagram);
+    const elementMap = new Map<string, C4Element>(allElements.map((e) => [e.id, e]));
+
+    // Build parent→children mapping for SvelteFlow node nesting
+    const parentOf = new Map<string, string>();
+    for (const el of diagram.elements) {
+      if ('containers' in el && Array.isArray((el as C4System).containers)) {
+        for (const c of (el as C4System).containers ?? []) {
+          parentOf.set(c.id, el.id);
+          if ('components' in c && Array.isArray(c.components)) {
+            for (const comp of c.components ?? []) {
+              parentOf.set(comp.id, c.id);
+            }
+          }
+        }
+      }
+      if ('components' in el && Array.isArray((el as C4Container).components)) {
+        for (const comp of (el as C4Container).components ?? []) {
+          parentOf.set(comp.id, el.id);
+        }
+      }
+    }
+
+    const nodes: Node[] = [];
+
+    for (const el of allElements) {
+      const pos = positions.get(el.id);
+      if (!pos) continue;
+
+      const nodeType = getNodeType(el);
+      const isGroup = isGroupNode(el);
+      const parentId = parentOf.get(el.id);
+
+      // Build the node data payload
+      const nodeData: C4NodeData = {
+        name: el.name,
+        description: el.description,
+        technology: 'technology' in el ? (el as { technology?: string }).technology : undefined,
+        external: 'external' in el ? (el as { external?: boolean }).external : false,
+        subtype: getSubtype(el),
+        drillable: hasDrillDown(el),
+        kb_article: 'kb_article' in el ? (el as { kb_article?: string }).kb_article : undefined,
+        tags: 'tags' in el ? (el as { tags?: string[] }).tags : undefined,
+        kind: el.kind,
+        element: el,
+        diagramLevel: diagram.level,
+        onclick: onclick ? (element: C4Element) => onclick(element.id) : undefined,
+        ondrilldown: ondrilldown
+          ? (element: C4Element, level: string) => ondrilldown(element.id, level)
+          : undefined,
+      };
+
+      // Compute position — SvelteFlow child node positions are relative to parent
+      let nodeX = pos.x;
+      let nodeY = pos.y;
+
+      if (parentId) {
+        const parentPos = positions.get(parentId);
+        if (parentPos) {
+          nodeX = pos.x - parentPos.x;
+          nodeY = pos.y - parentPos.y;
+        }
+      }
+
+      const node: Node = {
+        id: el.id,
+        type: nodeType,
+        position: { x: nodeX, y: nodeY },
+        data: nodeData as unknown as Record<string, unknown>,
+        draggable: false,
+        selectable: true,
+        // Every node takes its ELK box, so ELK's edge routes meet the card edges.
+        width: pos.width,
+        height: pos.height,
+        ...presized(pos),
+        // Group nodes need explicit dimensions for SvelteFlow to render the bounding box
+        ...(isGroup ? { style: `width: ${pos.width}px; height: ${pos.height}px;` } : {}),
+        ...(parentId ? { parentId } : {}),
+        // Group nodes must not be draggable out of the layout
+        ...(isGroup ? { draggable: false } : {}),
+      };
+
+      nodes.push(node);
+    }
+
+    // Build edges from relationships. An edge ELK routed draws its route (C4Edge);
+    // without one (ELK fell back to a grid) it stays a smoothstep.
+    const allElementIds = new Set(allElements.map((e) => e.id));
+    const edges: Edge[] = [];
+    diagram.relationships.forEach((r, i) => {
+      if (!allElementIds.has(r.from) || !allElementIds.has(r.to)) return;
+      const look = edgeLook(r.style);
+
+      const route = routes.get(i);
+      edges.push({
+        id: `edge-${i}-${r.from}-${r.to}`,
+        source: r.from,
+        target: r.to,
+        type: route ? 'c4' : 'smoothstep',
+        label: edgeLabelText(r) || undefined,
+        animated: look.animated,
+        style: look.style,
+        ...(route ? { data: { points: route.points, labelBox: route.label } } : {}),
+      });
+    });
+
+    return { nodes, edges };
+  }
+
+  // True once a layout has landed. Plain (not $state): only the effect reads it.
+  let hasLayout = false;
+
+  // ---- Semantic zoom state ----
+  /** The last semantic layout: what is drawn, and every element's absolute box. */
+  let semanticInfo = $state.raw<{ tree: C4Tree; vis: Visibility; rects: Map<string, LayoutPosition> } | null>(null);
+  /** Nodes that just left the map, fading where they were until the move settles. */
+  let leaving = $state.raw<Node[]>([]);
+  /** True while nodes glide between layouts: edges and markers sit it out. */
+  let moving = $state(false);
+  /** The layout inputs (diagram content, expanded, scope) of the last layout that landed or failed. */
+  let landedInputs = $state.raw<readonly unknown[] | null>(null);
+  /** Alternates the resize animation's name, so each move restarts it (markResized). */
+  let resizeTurn: 'a' | 'b' = 'a';
+  let settleTimer: ReturnType<typeof setTimeout> | undefined;
+
+  // Keyed on strings: a host deriving `expanded` per frame must not re-run ELK per frame, and a host
+  // that re-reads its model hands over a new `diagram` object with the same content, which must not
+  // re-run ELK or blank the edges for a move where nothing moves.
+  const diagramKey = $derived(JSON.stringify(diagram));
+  const expandedKey = $derived(expanded === undefined ? null : expanded.join('\n'));
+  const scopeKey = $derived(expandedKey === null ? undefined : scopeId);
+  /** True while a layout is computing: the camera holds until it lands, so it moves once. Derived
+   *  from the props, so the camera sees it in the same flush that changed them, whichever effect
+   *  runs first (set by the layout effect, a camera effect could still aim at the old layout). */
+  const laying = $derived.by(() => {
+    const inputs = [diagramKey, expandedKey, scopeKey];
+    return !landedInputs || inputs.some((v, i) => v !== landedInputs![i]);
+  });
+
+  function beginMove(prev: Node[], next: Node[], prevRects: Map<string, LayoutPosition> | undefined) {
+    clearTimeout(settleTimer);
+    if (prev.length === 0 || prefersReducedMotion.current) {
+      leaving = [];
+      moving = false;
+      return;
+    }
+    const nextIds = new Set(next.map((n) => n.id));
+    leaving = prev.flatMap((n) => {
+      const r = prevRects?.get(n.id);
+      if (nextIds.has(n.id) || !r) return [];
+      // Absolute and unparented: its parent may be gone or shrinking.
+      return [{ ...n, parentId: undefined, position: { x: r.x, y: r.y }, class: `${n.class ?? ''} c4-leaving`, selectable: false, focusable: false, zIndex: 1000, domAttributes: { 'aria-hidden': 'true' } }];
+    });
+    moving = true;
+    settleTimer = setTimeout(() => {
+      moving = false;
+    }, MOVE_MS + 60);
+  }
+
+  // Run ELK layout whenever the diagram's content (or, in semantic zoom, the
+  // expanded set or scope) changes. After the first layout the previous graph
+  // stays on screen until the next one is ready.
+  $effect(() => {
+    const dk = diagramKey;
+    const currentDiagram = untrack(() => diagram);
+    const ek = expandedKey;
+    const scope = scopeKey;
+    let cancelled = false;
+    if (!hasLayout) layoutReady = false;
+    layoutError = null;
+    const inputs = [dk, ek, scope];
+
+    // Handlers read the props when called, so the layout never tracks their identity. Without a
+    // host ondrilldown a drillable card clicks instead, as in the non-semantic path.
+    const handlers = {
+      onclick: (id: string) => onclick?.(id),
+      ondrilldown: untrack(() => ondrilldown) ? (id: string, level: string) => ondrilldown?.(id, level) : undefined,
+    };
+    const job =
+      ek === null
+        ? buildFlowGraph(currentDiagram).then((g) => ({ ...g, semantic: null }))
+        : buildSemanticFlow(currentDiagram, new Set(ek ? ek.split('\n') : []), scope, handlers).then((f) => ({
+            nodes: f.nodes,
+            edges: f.edges,
+            semantic: { tree: f.tree, vis: f.vis, rects: f.rects },
+          }));
+
+    job
+      .then(({ nodes, edges, semantic }) => {
+        if (cancelled) return;
+        if (semantic) {
+          const prevRects = semanticInfo?.rects;
+          if (prevRects && flowNodes.length > 0 && !prefersReducedMotion.current) {
+            resizeTurn = resizeTurn === 'a' ? 'b' : 'a';
+            nodes = markResized(nodes, prevRects, semantic.rects, resizeTurn);
+          }
+          beginMove(flowNodes, nodes, prevRects);
+        } else leaving = [];
+        flowNodes = nodes;
+        flowEdges = edges;
+        semanticInfo = semantic;
+        layoutReady = true;
+        hasLayout = true;
+        landedInputs = inputs;
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        console.error('[C4Diagram] Layout failed:', err);
+        layoutError = 'Diagram layout failed. Please check your data.';
+        layoutReady = true; // Show error state
+        landedInputs = inputs;
+      });
+
+    return () => { cancelled = true; };
+  });
+
+  // ---- Live layer ----
+  const shownNodes = $derived(
+    decorateNodes(leaving.length ? [...flowNodes, ...leaving] : flowNodes, { selectedId })
+  );
+  // SvelteFlow writes its nodes back (a re-measure, a fitView, a click selection). Into an unbound
+  // prop that write is kept as a deep $state proxy, so every node reads back as a new object and
+  // SvelteFlow rebuilds every node and edge. Bound, the write lands here raw, so only the nodes it
+  // changed are new. The next layout or decoration replaces it (a writable derived).
+  let boundNodes = $derived(shownNodes);
+  // Highlight: keyed on its fields, so a host passing a fresh object each render re-derives
+  // nothing. An element's path runs through the semantic tree (a hidden element lights its drawn
+  // ancestor), else up the drawn nodes' parents; an id with no path is not on the map.
+  const hlId = $derived(highlight?.id);
+  const hlReach = $derived(highlight?.reach);
+  const hlDepth = $derived(highlight?.depth);
+  const parentOf = $derived(new Map(flowNodes.map((n) => [n.id, n.parentId])));
+  function pathOf(id: string): string[] {
+    if (semanticInfo) return pathTo(semanticInfo.tree, id);
+    const out: string[] = [];
+    for (let at: string | undefined = id; at !== undefined && parentOf.has(at); at = parentOf.get(at)) out.unshift(at);
+    return out;
+  }
+  // Flow playback (see the header). A message rides the relationship the model draws; a reply's
+  // (`reverse`) runs `to` → `from`. An end that is not on the map shows no step.
+  const current = $derived(flow && step !== undefined ? flow.steps[step] : undefined);
+  const msg = $derived(current && 'from' in current ? current : undefined);
+  const rideKey = (m: { from: string; to: string; reverse?: boolean }) => (m.reverse ? linkKey(m.to, m.from) : linkKey(m.from, m.to));
+  const flowReach = $derived.by((): ReachSet | null => {
+    if (!current || 'note' in current) return null;
+    const ids = 'at' in current ? [current.at] : [current.from, current.to];
+    if (!ids.every((id) => pathOf(id).length > 0)) return null;
+    return { ids: new Set(ids), links: new Set(msg ? [rideKey(msg)] : []) };
+  });
+  const reach = $derived(
+    current
+      ? flowReach
+      : hlId !== undefined && pathOf(hlId).length > 0
+        ? reachSet(diagram.relationships, hlId, hlReach, hlDepth)
+        : null
+  );
+  const lit = $derived(reach ? litIds(reach.ids, pathOf) : null);
+  // Curved edges tighten a bend rather than cut a card: every drawn card's absolute box (not
+  // boundaries, which edges run inside).
+  const nodeById = $derived(new Map(flowNodes.map((n) => [n.id, n])));
+  /** A drawn node's absolute box. */
+  function boxOf(n: Node): Rect {
+    const p = n.parentId ? nodeById.get(n.parentId) : undefined;
+    const o = p ? boxOf(p) : { x: 0, y: 0 };
+    return { x: o.x + n.position.x, y: o.y + n.position.y, width: n.width ?? 0, height: n.height ?? 0 };
+  }
+  const cards = $derived(edgeShape === 'curved' ? flowNodes.filter((n) => viewOf(n) !== 'group').map(boxOf) : undefined);
+  /** The node an element is drawn as: itself, or under semantic zoom its drawn ancestor. */
+  const drawnOf = (id: string) => (semanticInfo ? representative(semanticInfo.tree, semanticInfo.vis, id) : id);
+  const nameOf = (id: string) =>
+    semanticInfo?.tree.byId.get(id)?.name ?? (nodeById.get(id)?.data as unknown as C4NodeData | undefined)?.name ?? id;
+  const flowMark = $derived<FlowMark | null>(
+    msg && flowReach
+      ? {
+          key: step!,
+          port: { text: msg.label, items: [{ from: nameOf(msg.from), to: nameOf(msg.to), label: msg.technology }] },
+          back: !!msg.reverse,
+          still: prefersReducedMotion.current,
+        }
+      : null
+  );
+  // The hop an implied message draws, between its two drawn ends (none when they are one node).
+  const hop = $derived.by(() => {
+    const [s, t] = msg ? [msg.from, msg.to].map((id) => nodeById.get(drawnOf(id) ?? '')) : [];
+    return s && t && s !== t ? { source: s.id, target: t.id, a: boxOf(s), b: boxOf(t) } : undefined;
+  });
+  const pulseId = $derived(current && 'at' in current && flowReach && !prefersReducedMotion.current ? drawnOf(current.at) : undefined);
+  const flowStep = $derived.by(() => {
+    if (!current || 'note' in current || !flowReach) return undefined;
+    const ends = 'at' in current ? [current.at] : [current.from, current.to];
+    return { key: `${flow!.id}:${step}`, ids: [...new Set(ends.map(drawnOf).filter((id): id is string => !!id))] };
+  });
+  const stepText = $derived(
+    !current
+      ? ''
+      : 'note' in current
+        ? current.note
+        : 'at' in current
+          ? `${nameOf(current.at)}: ${current.label}`
+          : `${nameOf(current.from)} to ${nameOf(current.to)}: ${current.label}`
+  );
+  function onEdgeClick({ edge }: { edge: Edge }) {
+    if (!flow || !onstep) return;
+    const keys = (edge.data?.links as string[] | undefined) ?? [linkKey(edge.source, edge.target)];
+    const n = flow.steps.length;
+    for (let k = 0; k < n; k++) {
+      const i = ((step ?? -1) + 1 + k) % n;
+      const s = flow.steps[i];
+      if ('from' in s && keys.includes(rideKey(s))) return onstep(i);
+    }
+  }
+  // Curved maps bundle a hub's edges; hovering a bundle's count opens it.
+  let openJoin = $state<string | null>(null);
+  setContext('c4-onjoin', (key: string | null) => (openJoin = key));
+  const shownEdges = $derived.by(() => {
+    const curved = edgeShape === 'curved';
+    const look = decorateEdges(flowEdges, { reach, curved, still: prefersReducedMotion.current, avoid: cards });
+    return markFlow(curved ? bundleEdges(look, openJoin) : look, flowMark, hop);
+  });
+  // Quiet (curved) maps: data-c4-hot (a DOM write) on an edge and label while it or an end is hovered.
+  let hot = $state<{ edge?: string; node?: string }>({});
+  $effect(() => {
+    const { edge, node } = hot;
+    const ends = new Map(shownEdges.map((e) => [e.id, [e.source, e.target]]));
+    if (!canvas) return;
+    for (const el of canvas.querySelectorAll<Element>('.svelte-flow__edge[data-id], [data-c4-edge]')) {
+      const id = el.getAttribute('data-c4-edge') ?? el.getAttribute('data-id') ?? '';
+      const on = id === edge || (!!node && !!ends.get(id)?.includes(node));
+      if (on !== el.hasAttribute('data-c4-hot')) el.toggleAttribute('data-c4-hot', on);
+    }
+  });
+
+  // Live status, the highlight's dim and a process step's pulse as data attributes on each node
+  // wrapper, written to the DOM: none may hand SvelteFlow a new nodes array (it re-lays every edge).
+  // Re-run when nodes mount.
+  let canvas = $state<HTMLElement>();
+  $effect(() => {
+    const st = status ?? {};
+    const on = lit;
+    const pulse = pulseId;
+    void shownNodes;
+    if (!canvas) return;
+    for (const el of canvas.querySelectorAll<HTMLElement>('.svelte-flow__node')) {
+      const s = el.dataset.id ? st[el.dataset.id] : undefined;
+      if (s) {
+        if (el.dataset.c4Status !== s) el.dataset.c4Status = s;
+      } else if (el.dataset.c4Status) delete el.dataset.c4Status;
+      const dim = !!on && !on.has(el.dataset.id ?? '');
+      if (dim !== el.hasAttribute('data-c4-dim')) el.toggleAttribute('data-c4-dim', dim);
+      const beat = !!pulse && el.dataset.id === pulse;
+      if (beat !== el.hasAttribute('data-c4-pulse')) el.toggleAttribute('data-c4-pulse', beat);
+    }
+  });
+  const nodeIds = $derived(nodeSetKey(flowNodes));
+  const legendStatuses = $derived(statusesPresent(status, nodeIds.split('\n')));
+  const shownMarkers = $derived(
+    semanticInfo && markers ? liftMarkers(semanticInfo.tree, semanticInfo.vis, markers) : markers
+  );
+
+  // Semantic camera: what to frame and the signature that decides when to move.
+  // Following, it frames the focus (its drawn ancestor if hidden) and refits when
+  // that box changes; manually, it frames the open code panel or the scope and
+  // refits only when what is drawn, the scope or the open panel changes.
+  // While a layout computes it holds the last frame: a new focus or scope read
+  // against the old layout would aim at a stale box, then move again on landing.
+  // Follow passes through: a drill that turns follow off lets go now, so the
+  // landing moves the camera to what the drill opened.
+  let lastFrame: { key: string; rect: LayoutPosition | null; follow: boolean } | undefined;
+  const frame = $derived.by(() => {
+    if (laying && lastFrame) return lastFrame.follow === !!follow ? lastFrame : { ...lastFrame, follow: !!follow };
+    if (!semanticInfo) return (lastFrame = undefined);
+    const { tree, vis, rects } = semanticInfo;
+    const panels = [...vis.panels];
+    const target =
+      follow && focusId
+        ? representative(tree, vis, focusId)
+        : (panels.at(-1) ?? (scopeId && rects.has(scopeId) ? scopeId : undefined));
+    let rect = target ? (rects.get(target) ?? null) : null;
+    // A code panel keeps its boundary's label row in view, so the nesting reads.
+    const box = target && vis.panels.has(target) ? rects.get(tree.parent.get(target) ?? '') : undefined;
+    if (rect && box) rect = unionRect([rect, { x: rect.x, y: box.y, width: rect.width, height: 1 }]);
+    rect ??= unionRect(rects.values());
+    const r = rect ? [rect.x, rect.y, rect.width, rect.height].map(Math.round).join(',') : '';
+    const key = follow ? `F|${target}|${r}` : `M|${nodeIds}|${scopeId ?? ''}|${panels.join(',')}`;
+    return (lastFrame = { key, rect, follow: !!follow });
+  });
+
+  // A user gesture carries its DOM event; programmatic moves (fitView, the
+  // follow camera) pass null. Report once per gesture.
+  let manualReported = false;
+  function onMoveStart() {
+    manualReported = false;
+  }
+  function onMove(event: MouseEvent | TouchEvent | null) {
+    if (!event || manualReported) return;
+    manualReported = true;
+    onmanualcamera?.();
+  }
+  // The zoom buttons and the minimap (pannable, zoomable) move the camera
+  // programmatically, so their gestures never reach onMove: catch them here.
+  function onCanvasGesture(event: Event) {
+    const t = event.target as Element | null;
+    if (t?.closest?.('.svelte-flow__controls, .svelte-flow__minimap')) onmanualcamera?.();
+  }
+
+  // Keyboard twin of a node click: SvelteFlow makes node wrappers focusable,
+  // and Enter or Space on one runs the same activateNode its click runs.
+  // Only on the wrapper itself: a control inside a node (a link, a panel's
+  // Before/After switch, a port badge) keeps its own keys.
+  function onCanvasKeydown(event: KeyboardEvent) {
+    if (event.key !== 'Enter' && event.key !== ' ') return;
+    const t = event.target as Element | null;
+    if (!t?.classList?.contains('svelte-flow__node')) return;
+    const id = t.getAttribute('data-id');
+    const node = id ? flowNodes.find((n) => n.id === id) : undefined;
+    if (!node) return;
+    event.preventDefault();
+    activateNode(viewOf(node), node.data as unknown as C4NodeData);
+  }
+</script>
+
+<div
+  class="c4-diagram {className}"
+  role="figure"
+  aria-label={diagram.title || (levelLabels[diagram.level] ?? diagram.level)}
+>
+  <!-- Header: a host that draws its own chrome passes an empty title. -->
+  {#if diagram.title}
+    <div class="c4-header">
+      <div class="c4-title-row">
+        <h3 class="c4-title">{diagram.title}</h3>
+        <span class="c4-level-badge">{levelLabels[diagram.level] ?? diagram.level}</span>
+      </div>
+      {#if diagram.description}
+        <p class="c4-description">{diagram.description}</p>
+      {/if}
+    </div>
+  {/if}
+
+  <!-- Flow canvas -->
+  <!-- svelte-ignore a11y_click_events_have_key_events -->
+  <!-- svelte-ignore a11y_no_static_element_interactions -->
+  <div
+    bind:this={canvas}
+    class={semanticInfo ? 'c4-canvas c4-semantic' : 'c4-canvas'}
+    data-c4-moving={moving ? '' : undefined}
+    data-c4-quiet={edgeShape === 'curved' ? '' : undefined}
+    onpointerdowncapture={onCanvasGesture}
+    onwheelcapture={onCanvasGesture}
+    onkeydown={onCanvasKeydown}
+  >
+    {#if !layoutReady}
+      <!-- Loading state -->
+      <div class="c4-loading" aria-live="polite">
+        <span class="c4-spinner" aria-hidden="true"></span>
+        <span>Computing layout&hellip;</span>
+      </div>
+    {:else if layoutError}
+      <!-- Error state -->
+      <div class="c4-error" role="alert">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
+          <circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/>
+        </svg>
+        <span>{layoutError}</span>
+      </div>
+    {:else}
+      <SvelteFlow
+        bind:nodes={() => boundNodes, (written) => (boundNodes = written)}
+        edges={shownEdges}
+        {nodeTypes}
+        {edgeTypes}
+        fitView
+        fitViewOptions={{ padding: 0.25, minZoom: FIT_MIN_ZOOM }}
+        colorMode="dark"
+        panOnDrag
+        zoomOnScroll
+        zoomOnPinch
+        zoomOnDoubleClick
+        nodesDraggable={false}
+        nodesConnectable={false}
+        elementsSelectable={selectedId === undefined}
+        minZoom={0.15}
+        maxZoom={4}
+        defaultMarkerColor={EDGE_STROKE}
+        proOptions={{ hideAttribution: true }}
+        onmovestart={onMoveStart}
+        onmove={onMove}
+        onedgepointerenter={({ edge }) => (hot = { edge: edge.id })}
+        onedgepointerleave={() => (hot = {})}
+        onnodepointerenter={({ node }) => (hot = { node: node.id })}
+        onnodepointerleave={() => (hot = {})}
+        onedgeclick={flow && onstep ? onEdgeClick : undefined}
+      >
+        <C4LiveLayer ids={nodeIds} {focusId} {follow} markers={shownMarkers} {frame} {flowStep} />
+        <Background
+          gap={24}
+        />
+        <Controls
+          showLock={false}
+          position="bottom-right"
+        />
+        <MiniMap
+          position="bottom-left"
+          width={160}
+          height={110}
+          nodeColor={(node) => (node.class?.includes('c4-leaving') ? 'transparent' : viewOf(node) === 'group' ? MINIMAP_GROUP : MINIMAP_NODE)}
+          nodeBorderRadius={4}
+        />
+      </SvelteFlow>
+    {/if}
+  </div>
+
+  <!-- Legend: the live statuses on the map when `status` is given, else the C4 shapes. -->
+  {#if layoutReady && !layoutError && status}
+    {#if legendStatuses.length > 0}
+      <div class="c4-legend" role="list" aria-label="Status legend">
+        {#each legendStatuses as st (st)}
+          <div class="c4-legend-item" role="listitem">
+            <span class="c4-status-swatch" data-c4-swatch={st}></span>
+            <span>{STATUS_LABELS[st]}</span>
+          </div>
+        {/each}
+      </div>
+    {/if}
+  {:else if layoutReady && !layoutError}
+    <div class="c4-legend" role="list" aria-label="Diagram legend">
+      {#each SHAPE_LEGEND as item (item.shape)}
+        <div class="c4-legend-item" role="listitem">
+          <span class="c4-legend-swatch" data-c4-shape={item.shape}></span>
+          <span>{item.label}</span>
+        </div>
+      {/each}
+    </div>
+  {/if}
+
+  {#if flow}
+    <p class="c4-flow-live" aria-live="polite">{stepText}</p>
+  {/if}
+</div>
+
+<style>
+  .c4-diagram {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    color: var(--ripple-surface-foreground);
+  }
+
+  /* ---- Header ---- */
+  .c4-header {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+
+  .c4-title-row {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+  }
+
+  .c4-title {
+    margin: 0;
+    font-size: 14px;
+    font-weight: 600;
+    letter-spacing: -0.005em;
+    color: var(--ripple-surface-foreground);
+  }
+
+  .c4-level-badge {
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: var(--ripple-accent);
+    background: color-mix(in oklab, var(--ripple-accent) 12%, transparent);
+    padding: 2px 8px;
+    border-radius: 9999px;
+  }
+
+  .c4-description {
+    margin: 0;
+    font-size: 12px;
+    color: var(--ripple-muted-foreground);
+  }
+
+  /* ---- Canvas ----
+     480px in an auto-height parent (the legacy size); fills a parent that
+     gives the diagram a height. SvelteFlow's theme variables are mapped to
+     ripple tokens here, so the canvas follows the host's light/dark theme. */
+  .c4-canvas {
+    width: 100%;
+    flex: 1 1 480px;
+    min-height: 0;
+    border-radius: 12px;
+    overflow: hidden;
+    position: relative;
+    border: 1px solid var(--ripple-border);
+    background: var(--ripple-surface);
+    /* An opaque ground for things that sit ON the map (node cards, edge
+       labels, controls). The host's surfaces may be translucent glass, which
+       lets edges and the grid read through; this inverts the ink's lightness
+       instead (dark ink -> near-white ground, light ink -> near-black), and
+       cards layer the host's card tint over it. */
+    --c4-ground: oklch(from var(--ripple-surface-foreground) calc(1.13 - l * 0.96) calc(c * 0.5) h);
+    --c4-card: linear-gradient(var(--ripple-surface) 0 0), var(--c4-ground);
+    --xy-background-pattern-color: var(--ripple-border);
+    --xy-edge-stroke: color-mix(in oklab, var(--ripple-muted-foreground) 55%, transparent);
+    --xy-edge-label-background-color: var(--ripple-surface);
+    --xy-edge-label-color: var(--ripple-muted-foreground);
+    --xy-controls-button-background-color: var(--ripple-surface);
+    --xy-controls-button-background-color-hover: var(--ripple-muted);
+    --xy-controls-button-color: var(--ripple-muted-foreground);
+    --xy-controls-button-color-hover: var(--ripple-surface-foreground);
+    --xy-controls-button-border-color: var(--ripple-border);
+    --xy-controls-box-shadow: none;
+    --xy-minimap-background-color: var(--ripple-surface);
+    --xy-minimap-mask-background-color: color-mix(in oklab, var(--ripple-surface-foreground) 7%, transparent);
+    --xy-minimap-mask-stroke-color: var(--ripple-border);
+    /* Everything else xyflow colours, so the fixed palette behind colorMode never shows. */
+    --xy-background-color: transparent;
+    --xy-attribution-background-color: transparent;
+    --xy-connectionline-stroke: var(--ripple-muted-foreground);
+    --xy-edge-stroke-selected: var(--ripple-accent);
+    --xy-node-color: var(--ripple-surface-foreground);
+    --xy-node-background-color: transparent;
+    --xy-node-border: none;
+    --xy-node-group-background-color: transparent;
+    --xy-node-boxshadow-hover: none;
+    --xy-node-boxshadow-selected: none;
+    --xy-handle-background-color: var(--ripple-muted-foreground);
+    --xy-handle-border-color: var(--ripple-surface);
+    --xy-selection-background-color: color-mix(in oklab, var(--ripple-accent) 8%, transparent);
+    --xy-selection-border: 1px dotted color-mix(in oklab, var(--ripple-accent) 60%, transparent);
+    --xy-minimap-node-background-color: color-mix(in oklab, var(--ripple-muted-foreground) 45%, transparent);
+    --xy-minimap-node-stroke-color: transparent;
+    --xy-resize-background-color: var(--ripple-accent);
+  }
+
+  /* ---- Loading / Error states ---- */
+  .c4-loading,
+  .c4-error {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 10px;
+    font-size: 13px;
+    color: var(--ripple-muted-foreground);
+  }
+
+  .c4-error {
+    color: var(--ripple-error-text);
+  }
+
+  .c4-spinner {
+    width: 16px;
+    height: 16px;
+    border: 2px solid var(--ripple-border);
+    border-top-color: var(--ripple-accent);
+    border-radius: 50%;
+    animation: c4-spin 0.7s linear infinite;
+    flex-shrink: 0;
+  }
+
+  @keyframes c4-spin {
+    to { transform: rotate(360deg); }
+  }
+
+  /* ---- Legend ---- */
+  .c4-legend {
+    display: flex;
+    gap: 14px;
+    flex-wrap: wrap;
+    padding: 2px 4px;
+  }
+
+  .c4-legend-item {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 11px;
+    color: var(--ripple-muted-foreground);
+  }
+
+  .c4-legend-swatch {
+    width: 10px;
+    height: 10px;
+    border-radius: 3px;
+    flex-shrink: 0;
+    border: 1px solid color-mix(in oklab, var(--ripple-surface-foreground) 30%, transparent);
+    background: var(--ripple-surface);
+  }
+  .c4-legend-swatch[data-c4-shape='person'] {
+    border-radius: 50%;
+    border-color: transparent;
+    background: color-mix(in oklab, var(--ripple-accent) 40%, transparent);
+  }
+  .c4-legend-swatch[data-c4-shape='container'] {
+    border-radius: 2px;
+  }
+  .c4-legend-swatch[data-c4-shape='database'] {
+    border-radius: 50% / 30%;
+    border-color: color-mix(in oklab, var(--ripple-info) 55%, transparent);
+    background: color-mix(in oklab, var(--ripple-info) 20%, transparent);
+  }
+  .c4-legend-swatch[data-c4-shape='queue'] {
+    border-color: transparent;
+    background: color-mix(in oklab, var(--ripple-warning) 35%, transparent);
+  }
+  .c4-legend-swatch[data-c4-shape='external'] {
+    border-style: dashed;
+    background: transparent;
+  }
+
+  /* ---- SvelteFlow overrides ---- */
+  .c4-canvas :global(.svelte-flow),
+  .c4-canvas :global(.svelte-flow__background) {
+    background: transparent !important;
+  }
+
+  .c4-canvas :global(.svelte-flow__node) {
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    padding: 0 !important;
+    border-radius: var(--c4-r);
+  }
+
+  /* Selection (and keyboard focus): an accent ring set off from the node, so
+     a status ring stays readable inside it. */
+  .c4-canvas :global(.svelte-flow__node:focus) {
+    outline: none;
+  }
+  .c4-canvas :global(.svelte-flow__node.selected),
+  .c4-canvas :global(.svelte-flow__node:focus-visible) {
+    outline: 2px solid var(--ripple-accent);
+    outline-offset: 3px;
+  }
+
+  /* Handles only anchor edges here (nothing is connectable), so hide them. */
+  .c4-canvas :global(.c4-handle) {
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  .c4-canvas :global(.svelte-flow__edge.animated .svelte-flow__edge-path) {
+    stroke-dasharray: 8 4;
+    animation: c4-dash 0.8s linear infinite;
+  }
+
+  .c4-canvas :global(.svelte-flow__edge.selected .svelte-flow__edge-path) {
+    stroke: var(--ripple-accent) !important;
+    stroke-width: 2px;
+  }
+
+  .c4-canvas :global(.svelte-flow__edge-label) {
+    font-size: calc(11px / clamp(0.6, var(--c4-zoom, 1), 1));
+    font-weight: 500;
+    line-height: 1.2;
+    padding: 2px 6px;
+    border-radius: 6px;
+    border: 1px solid var(--ripple-border);
+    background: var(--c4-card);
+  }
+
+  .c4-canvas :global(.svelte-flow__controls),
+  .c4-canvas :global(.svelte-flow__minimap) {
+    border: 1px solid var(--ripple-border);
+    border-radius: 8px;
+    overflow: hidden;
+    background: var(--c4-card);
+  }
+
+  /* Group node bounding box sizing — SvelteFlow requires explicit width/height on parent nodes */
+  .c4-canvas :global(.svelte-flow__node-group) {
+    background: transparent !important;
+    border: none !important;
+    padding: 0 !important;
+  }
+
+  @keyframes c4-dash {
+    to { stroke-dashoffset: -12; }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .c4-spinner {
+      animation: none;
+    }
+    .c4-canvas :global(.svelte-flow__edge.animated .svelte-flow__edge-path) {
+      animation: none;
+    }
+  }
+
+  /* ---- The shared node card ----
+     Every node component renders these classes; the rules live here once.
+     Names counter-scale with the zoom (C4LiveLayer writes --c4-zoom on the
+     flow root) so they stay legible when the map is zoomed out, and the
+     secondary lines drop away once it is far out (data-c4-far). */
+  .c4-canvas :global(.c4-node) {
+    position: relative;
+    box-sizing: border-box;
+    /* Fill the ELK box SvelteFlow sizes the wrapper to: routes end on this edge. */
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: safe center;
+    gap: 4px;
+    padding: 12px 14px;
+    border-radius: 10px;
+    border: 1px solid var(--ripple-border);
+    background: var(--c4-card);
+    color: var(--ripple-surface-foreground);
+    text-align: center;
+    cursor: pointer;
+    transition:
+      border-color 150ms var(--ripple-ease-out),
+      transform 150ms var(--ripple-ease-out);
+  }
+
+  .c4-canvas :global(.c4-node > *) {
+    flex-shrink: 0;
+  }
+
+  /* Per-type card overrides live here, after the shared rule they refine. */
+  .c4-canvas :global(.c4-person-node) {
+    border-radius: 12px;
+    gap: 6px;
+  }
+  .c4-canvas :global(.c4-component-node) {
+    border-radius: 8px;
+  }
+  .c4-canvas :global(.c4-component-node.is-code) {
+    padding-inline: 10px;
+  }
+  /* A file name is one long token: the host's mono face (font-mono on the
+     element) at a size that fits the box. */
+  .c4-canvas :global(.c4-component-node.is-code .c4-node-name) {
+    font-size: calc(12px / clamp(0.5, var(--c4-zoom, 1), 1));
+    font-weight: 500;
+    letter-spacing: 0;
+  }
+
+  .c4-canvas :global(.c4-node:hover) {
+    border-color: color-mix(in oklab, var(--ripple-surface-foreground) 24%, transparent);
+    transform: translateY(-1px);
+  }
+
+  .c4-canvas :global(.c4-node.is-external) {
+    border-style: dashed;
+    border-color: color-mix(in oklab, var(--ripple-surface-foreground) 20%, transparent);
+  }
+
+  .c4-canvas :global(.c4-node.is-external .c4-node-name) {
+    color: var(--ripple-muted-foreground);
+  }
+
+  .c4-canvas :global(.c4-node-kind) {
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: var(--ripple-muted-foreground);
+  }
+
+  .c4-canvas :global(.c4-node-name) {
+    font-size: calc(13px / clamp(0.5, var(--c4-zoom, 1), 1));
+    font-weight: 600;
+    line-height: 1.25;
+    letter-spacing: -0.005em;
+    text-align: center;
+    overflow-wrap: anywhere;
+  }
+
+  .c4-canvas :global(.c4-node-desc) {
+    font-size: 11px;
+    line-height: 1.35;
+    text-align: center;
+    color: var(--ripple-muted-foreground);
+    display: -webkit-box;
+    -webkit-box-orient: vertical;
+    -webkit-line-clamp: 2;
+    line-clamp: 2;
+    overflow: hidden;
+  }
+
+  .c4-canvas :global(.c4-node-tech) {
+    font-size: calc(11px / clamp(0.6, var(--c4-zoom, 1), 1));
+    line-height: 1.3;
+    color: var(--ripple-muted-foreground);
+    background: var(--ripple-muted);
+    padding: 1px 6px;
+    border-radius: 4px;
+  }
+
+  .c4-canvas :global(.c4-node-docs) {
+    display: inline-flex;
+    align-items: center;
+    gap: 3px;
+    font-size: 10px;
+    color: var(--ripple-accent);
+    text-decoration: none;
+  }
+
+  .c4-canvas :global(.c4-node-docs:hover) {
+    text-decoration: underline;
+  }
+
+  .c4-canvas :global(.c4-node-drill) {
+    position: absolute;
+    top: 8px;
+    right: 8px;
+    color: var(--ripple-muted-foreground);
+  }
+
+  .c4-canvas :global(.svelte-flow[data-c4-far] .c4-node-kind),
+  .c4-canvas :global(.svelte-flow[data-c4-far] .c4-node-desc),
+  .c4-canvas :global(.svelte-flow[data-c4-far] .c4-node-docs) {
+    display: none;
+  }
+
+  /* ---- Semantic zoom ----
+     Nodes glide and resize to their new layout on the ripple curve (the camera
+     eases on the same curve in C4LiveLayer), fade in where they first appear,
+     and fade out where they were when they leave. Edges and marker dots are
+     drawn for the final layout, so they sit the move out. Ghosts are context. */
+  .c4-semantic :global(.svelte-flow__node) {
+    transition:
+      transform 560ms var(--ripple-ease-out),
+      opacity 280ms var(--ripple-ease-out);
+    animation: c4-node-in 360ms var(--ripple-ease-out) 140ms backwards;
+  }
+
+  /* A node whose box changed size (markResized): the wrapper takes the new size
+     at once (resizing it per frame would re-measure it and re-lay every edge
+     per frame) while its card and status ring grow from the old size. Two
+     names, alternated per layout, so every move restarts the animation. */
+  .c4-semantic :global(.svelte-flow__node[data-c4-resized='a'] > :not(.c4-handle)) {
+    animation: c4-size-a 560ms var(--ripple-ease-out);
+  }
+  .c4-semantic :global(.svelte-flow__node[data-c4-resized='b'] > :not(.c4-handle)) {
+    animation: c4-size-b 560ms var(--ripple-ease-out);
+  }
+  .c4-semantic :global(.svelte-flow__node[data-c4-resized='a'])::after {
+    animation: c4-ring-a 560ms var(--ripple-ease-out);
+  }
+  .c4-semantic :global(.svelte-flow__node[data-c4-resized='b'])::after {
+    animation: c4-ring-b 560ms var(--ripple-ease-out);
+  }
+  .c4-semantic :global(.svelte-flow__node[data-c4-resized='a'][data-c4-status='changing'])::after {
+    animation: c4-ring-a 560ms var(--ripple-ease-out), c4-breathe 2.4s ease-in-out infinite;
+  }
+  .c4-semantic :global(.svelte-flow__node[data-c4-resized='b'][data-c4-status='changing'])::after {
+    animation: c4-ring-b 560ms var(--ripple-ease-out), c4-breathe 2.4s ease-in-out infinite;
+  }
+
+  @keyframes c4-size-a {
+    from { width: var(--c4-from-w); height: var(--c4-from-h); }
+  }
+  @keyframes c4-size-b {
+    from { width: var(--c4-from-w); height: var(--c4-from-h); }
+  }
+  @keyframes c4-ring-a {
+    from { width: calc(var(--c4-from-w) + 2px); height: calc(var(--c4-from-h) + 2px); }
+  }
+  @keyframes c4-ring-b {
+    from { width: calc(var(--c4-from-w) + 2px); height: calc(var(--c4-from-h) + 2px); }
+  }
+
+  @keyframes c4-node-in {
+    from { opacity: 0; }
+  }
+
+  .c4-semantic :global(.svelte-flow__node[data-c4-ghost]),
+  .c4-canvas :global(.svelte-flow__node[data-c4-dim]) {
+    opacity: 0.38;
+  }
+
+  .c4-semantic :global(.svelte-flow__node.c4-leaving) {
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  .c4-semantic :global(.svelte-flow__edges),
+  .c4-semantic :global(.svelte-flow__edge-labels),
+  .c4-semantic :global(.svelte-flow__node-toolbar) {
+    transition: opacity 240ms var(--ripple-ease-out);
+  }
+
+  .c4-semantic[data-c4-moving] :global(.svelte-flow__edges),
+  .c4-semantic[data-c4-moving] :global(.svelte-flow__edge-labels),
+  .c4-semantic[data-c4-moving] :global(.svelte-flow__node-toolbar) {
+    opacity: 0;
+    transition-duration: 120ms;
+  }
+
+  .c4-semantic :global(.svelte-flow__edge.c4-ghost),
+  .c4-canvas :global(.svelte-flow__edge[data-c4-dim]) {
+    opacity: 0.35;
+  }
+
+  /* A label wrapped on a dense level keeps its laid-out size (counter-scaled it would cover its
+     neighbours) and, like a card's secondary lines, is dropped when the map is far out. */
+  .c4-canvas :global(.svelte-flow__edge-label.c4-wrap-label) {
+    /* LABEL_CAP in elk-layout.ts: every wrapped label was laid out this wide. */
+    max-width: 180px;
+    font-size: 11px;
+    white-space: normal;
+    text-align: center;
+  }
+  .c4-canvas :global(.svelte-flow[data-c4-far] .c4-wrap-label:not([data-c4-hot], [data-c4-reach])) {
+    display: none;
+  }
+
+  /* Quiet edges (curved): out of the reach and unhovered, lighter and thinner, label shown near (1.2x+). */
+  .c4-canvas[data-c4-quiet] :global(.svelte-flow__edge:not(.c4-reach, [data-c4-hot], :hover)) {
+    opacity: 0.35;
+  }
+  .c4-canvas[data-c4-quiet] :global(.svelte-flow__edge:not(.c4-reach) .svelte-flow__edge-path) {
+    stroke-width: 1px !important;
+  }
+  .c4-canvas[data-c4-quiet] :global(.svelte-flow:not([data-c4-near]) .svelte-flow__edge-label[data-c4-edge]:not([data-c4-hot], [data-c4-reach])) {
+    display: none;
+  }
+
+  /* A bundle's count, where its edges join the trunk; hovering it opens the bundle. */
+  .c4-canvas :global(.c4-join-badge) {
+    display: inline-block;
+    padding: 1px 6px;
+    border-radius: 9999px;
+    border: 1px solid var(--ripple-border);
+    background: var(--c4-card);
+    color: var(--ripple-surface-foreground);
+    font-size: calc(10px / clamp(0.5, var(--c4-zoom, 1), 1));
+    font-weight: 600;
+  }
+
+  .c4-canvas :global(.svelte-flow__edge-label.c4-ghost-label),
+  .c4-canvas :global(.svelte-flow__edge-label[data-c4-dim]) {
+    opacity: 0.45;
+  }
+
+  /* A port badge is its own pill; its EdgeLabel wrapper draws nothing. */
+  .c4-canvas :global(.svelte-flow__edge-label.c4-badge-label) {
+    padding: 0;
+    border: none;
+    background: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .c4-semantic :global(.svelte-flow__node) {
+      transition: none;
+      animation: none;
+    }
+    .c4-semantic :global(.svelte-flow__edges),
+    .c4-semantic :global(.svelte-flow__edge-labels),
+    .c4-semantic :global(.svelte-flow__node-toolbar) {
+      transition: none;
+    }
+  }
+
+  /* ---- Live status: data-c4-status on the SvelteFlow node wrapper ----
+     One ring drawn over the node's own edge, so every node shape gets the same
+     treatment without each node component knowing about status. Tones are
+     ripple tokens; `changing` is the only one that moves. */
+  .c4-canvas :global(.svelte-flow__node) {
+    --c4-r: 10px;
+  }
+  .c4-canvas :global(.svelte-flow__node-person),
+  .c4-canvas :global(.svelte-flow__node-group) {
+    --c4-r: 12px;
+  }
+  .c4-canvas :global(.svelte-flow__node-component) {
+    --c4-r: 8px;
+  }
+
+  .c4-canvas :global(.svelte-flow__node[data-c4-status])::after {
+    content: '';
+    position: absolute;
+    /* inset: -1px, as a size the resize animation can grow from (c4-ring). */
+    top: -1px;
+    left: -1px;
+    width: calc(100% + 2px);
+    height: calc(100% + 2px);
+    border-radius: var(--c4-r);
+    border: 1.5px solid var(--c4-tone);
+    pointer-events: none;
+    transition: border-color 180ms var(--ripple-ease-out), box-shadow 180ms var(--ripple-ease-out);
+  }
+
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='changing']),
+  .c4-status-swatch[data-c4-swatch='changing'] {
+    --c4-tone: var(--ripple-accent);
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='changed']),
+  .c4-status-swatch[data-c4-swatch='changed'] {
+    --c4-tone: color-mix(in oklab, var(--ripple-accent) 55%, transparent);
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='landed']),
+  .c4-status-swatch[data-c4-swatch='landed'] {
+    --c4-tone: var(--ripple-success);
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='failed']),
+  .c4-status-swatch[data-c4-swatch='failed'] {
+    --c4-tone: var(--ripple-error);
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='drift']),
+  .c4-status-swatch[data-c4-swatch='drift'] {
+    --c4-tone: var(--ripple-warning);
+  }
+
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='drift'])::after {
+    border-style: dashed;
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='failed'])::after {
+    box-shadow: 0 0 0 4px color-mix(in oklab, var(--ripple-error) 16%, transparent);
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='changing'])::after {
+    animation: c4-breathe 2.4s ease-in-out infinite;
+  }
+
+  /* A process step's element pulses (C4Diagram sets data-c4-pulse; never under reduced motion). */
+  .c4-canvas :global(.svelte-flow__node[data-c4-pulse])::before {
+    content: '';
+    position: absolute;
+    inset: -1px;
+    border-radius: var(--c4-r);
+    pointer-events: none;
+    animation: c4-pulse 1.6s var(--ripple-ease-out) infinite;
+  }
+  @keyframes c4-pulse {
+    from { box-shadow: 0 0 0 0 color-mix(in oklab, var(--ripple-accent) 45%, transparent); }
+    to { box-shadow: 0 0 0 12px transparent; }
+  }
+
+  /* The current flow step, for assistive tech only: the host draws the transport. */
+  .c4-flow-live {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  @keyframes c4-breathe {
+    0%, 100% { box-shadow: 0 0 0 2px color-mix(in oklab, var(--ripple-accent) 10%, transparent); }
+    50% { box-shadow: 0 0 0 7px color-mix(in oklab, var(--ripple-accent) 22%, transparent); }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .c4-canvas :global(.svelte-flow__node[data-c4-status='changing'])::after {
+      animation: none;
+      box-shadow: 0 0 0 4px color-mix(in oklab, var(--ripple-accent) 18%, transparent);
+    }
+  }
+
+  .c4-status-swatch {
+    width: 10px;
+    height: 10px;
+    flex-shrink: 0;
+    border-radius: 3px;
+    border: 1.5px solid var(--c4-tone);
+    background: color-mix(in oklab, var(--c4-tone) 18%, transparent);
+  }
+  .c4-status-swatch[data-c4-swatch='drift'] {
+    border-style: dashed;
+  }
+
+  /* Planned: a node that does not exist in code yet, drawn as a blueprint. A
+     dashed muted outline over a card with no fill or border of its own, its
+     content dimmed. Distinct from the scope ghost (the whole node faded, its
+     outline unchanged) and from drift (a dashed warning ring on a full card).
+     The dim is on the content, not the wrapper, so it composes with the ghost's
+     wrapper opacity instead of fighting it; the handles stay hidden. */
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='planned']),
+  .c4-status-swatch[data-c4-swatch='planned'] {
+    --c4-tone: color-mix(in oklab, var(--ripple-muted-foreground) 75%, transparent);
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='planned'])::after {
+    border-style: dashed;
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='planned'] > :not(.c4-handle)) {
+    opacity: 0.6;
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='planned'] .c4-node) {
+    background: transparent;
+    border-color: transparent;
+  }
+  .c4-status-swatch[data-c4-swatch='planned'] {
+    border-style: dashed;
+    background: transparent;
+  }
+
+  /* Future: a blueprint further out than planned. The same no-fill card, but a
+     dotted outline and fainter content, so the two read apart side by side. */
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='future']),
+  .c4-status-swatch[data-c4-swatch='future'] {
+    --c4-tone: color-mix(in oklab, var(--ripple-muted-foreground) 55%, transparent);
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='future'])::after {
+    border-style: dotted;
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='future'] > :not(.c4-handle)) {
+    opacity: 0.45;
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='future'] .c4-node) {
+    background: transparent;
+    border-color: transparent;
+  }
+  .c4-status-swatch[data-c4-swatch='future'] {
+    border-style: dotted;
+    background: transparent;
+  }
+
+  /* Added: an element new since a comparison's base. Success-toned like landed,
+     but a heavier double outline, so it does not rest on colour alone (landed is
+     a thin single ring, changed a thin accent one). */
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='added']),
+  .c4-status-swatch[data-c4-swatch='added'] {
+    --c4-tone: var(--ripple-success);
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='added'])::after {
+    border-style: double;
+    border-width: 4px;
+  }
+  .c4-status-swatch[data-c4-swatch='added'] {
+    border-style: double;
+    border-width: 3px;
+  }
+
+  /* Removed: an element that is gone, kept on the map so a comparison can show
+     it. Unlike planned it keeps its card, so it reads as something that was
+     there; the content fades harder and the dashed outline takes the error tone
+     (drift's dash is warning-toned over a full-strength card). */
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='removed']),
+  .c4-status-swatch[data-c4-swatch='removed'] {
+    --c4-tone: color-mix(in oklab, var(--ripple-error) 60%, transparent);
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='removed'])::after {
+    border-style: dashed;
+  }
+  .c4-canvas :global(.svelte-flow__node[data-c4-status='removed'] > :not(.c4-handle)) {
+    opacity: 0.4;
+  }
+  .c4-status-swatch[data-c4-swatch='removed'] {
+    border-style: dashed;
+  }
+</style>