@principal-ai/subsystems-react 0.51.4 → 0.53.0

package/src/subsystem/model.ts

@@ -8,8 +8,9 @@
  * subgraphs, only cross-package edges leave the box, and shared seams
  * (registries/barrels/facades) are edge targets, never member nodes.
  *
- * Self-contained in this package (not yet promoted to `@principal-ai/core`), so
- * we can iterate on the UI + story without publishing a dependency.
+ * Document types come from `@principal-ai/subsystems-core` (the portable
+ * standard's home); react layers display concerns (edges, regions, layout)
+ * on top.
  */
 
 import {
@@ -22,9 +23,7 @@ import { EDGE_LABEL_SIDE_PADDING, EDGE_ARROW_INSET } from '../utils/edgeLabel';
 import type { GraphifyComponentDetail } from '../graphify';
 import type {
   SubsystemConstructDeclaration,
-  SubsystemComponentRemoval,
 } from '@principal-ai/subsystems-core';
-import type { SubsystemDeclarationRef } from './declarationRef';
 import { purlOwnerName, purlRepoKey } from './paths';
 
 /**
@@ -55,7 +54,6 @@ export type { SubsystemConstructDeclaration } from '@principal-ai/subsystems-cor
 export type AnyComponentDetail =
   | SubsystemConstructDeclaration
   | GraphifyComponentDetail;
-export type SubsystemDeclarationProvenance = 'verified' | 'authored';
 
 /** One declared parameter in an agent-extracted (augmented) signature. */
 export interface SubsystemSignatureParameter {
@@ -78,84 +76,60 @@ export interface SubsystemSignatureClaim {
   returnType?: string;
 }
 
-export type SubsystemComponentConstruct =
-  | 'class'
-  | 'function'
-  | 'method'
-  | 'interface'
-  | 'type_alias'
-  | 'enum'
-  | 'store'
-  | 'external'
-  | 'custom_entity';
-
-/**
- * Semantic role — where the node sits in the topology, orthogonal to
- * `construct` (what it is). Roles have *inherited* anatomy: an entry renders
- * as its real code shape (function dispatcher, type contract); a service has
- * no source at all (`construct: 'external'` + purl identity). Contrast with
- * `construct: 'store'`, which introduces its own anatomy (the state block) —
- * that is why store is a construct and not a role. Role nodes must stay anchored to real code: an
- * `entry` is a boundary element (route dispatcher, message contract) carrying
- * the wire address as identity; a `service` is an external system the process
- * calls out to (identity via purl, no `process` — it belongs to no region).
- */
-export type SubsystemComponentRole = 'entry' | 'service';
-
 /**
- * Framework that owns a stereotype vocabulary (open string).
- * Examples: `react`, `vue`, `nestjs`, `django`, `spring`.
- * Empty when the node is language-only / framework-agnostic.
+ * Document vocabulary — imported from `@principal-ai/subsystems-core`, the
+ * portable standard's home. This package used to define a parallel copy
+ * ("self-contained until promoted"); core owns the types now, so react
+ * re-exports them by construction instead of hand-mirroring.
  */
-export type SubsystemFramework = string;
+import type {
+  SubsystemModelDocument,
+  SubsystemTrail,
+  SubsystemTrailStep,
+  SubsystemComponentRole,
+  SubsystemTrailMechanism,
+  SubsystemEdgeMechanism,
+  SubsystemConstruct as SubsystemComponentConstruct,
+  SubsystemComponent as CoreSubsystemComponent,
+} from '@principal-ai/subsystems-core';
+import {
+  getSubsystemProcessRegions as coreGetSubsystemProcessRegions,
+  getSubsystemModuleRegions as coreGetSubsystemModuleRegions,
+} from '@principal-ai/subsystems-core';
 
+export type {
+  SubsystemModelDocument,
+  SubsystemTrail,
+  SubsystemTrailStep,
+  SubsystemComponentRole,
+  SubsystemFramework,
+  SubsystemStereotype,
+  SubsystemEntityKind,
+  SubsystemTrailMechanism,
+  SubsystemEdgeMechanism,
+  SubsystemDeclToken,
+  SubsystemDeclTokenKind,
+  SubsystemDeclarationProvenance,
+} from '@principal-ai/subsystems-core';
+export type { SubsystemComponentConstruct };
 /**
- * Framework-level pattern stamped on a language construct (open string).
- * Examples: `component`, `hook`, `middleware`, `controller`, `guard`.
- * Empty when no framework pattern applies. Pair with `framework` when set —
- * a React component stays `construct: 'function'` with
- * `framework: 'react'` + `stereotype: 'component'`.
+ * A component node — the named unit, construct-tagged; `file` is its location.
+ * Core's portable shape plus the one field a model document never carries:
+ * `signatureAugmentation` is host-enrichment (populated when serving an
+ * enriched graph), never persisted.
  */
-export type SubsystemStereotype = string;
-
-// ---------------------------------------------------------------------------
-// Declaration tokens — structured source representation
-// ---------------------------------------------------------------------------
-
-export type SubsystemDeclTokenKind =
-  | 'keyword'
-  | 'name'
-  | 'member'
-  | 'type'
-  | 'punctuation'
-  | 'string'
-  | 'newline';
-
-export interface SubsystemDeclToken {
-  text: string;
-  kind: SubsystemDeclTokenKind;
-  /** Shiki/Pierre foreground when tokenized client-side; omitted on legacy wire tokens. */
-  color?: string;
+export interface SubsystemComponent extends CoreSubsystemComponent {
+  /**
+   * Accepted agent-extracted signature (from the graphify augmentation store)
+   * confirming this function/method when Graphify has no usable signature
+   * edges. Populated by the host when serving an enriched graph — never
+   * persisted in the model document. Rendered as the declaration when the
+   * component has no own `declaration`; no marker distinguishes the source.
+   */
+  signatureAugmentation?: SubsystemSignatureClaim;
 }
 
-/**
- * Trail step mechanism — runtime seams with a `file:line` site.
- */
-export type SubsystemTrailMechanism =
-  | 'calls'
-  | 'uses'
-  | 'feeds'
-  | 'produces'
-  | 'writes'
-  | 'reads'
-  | 'watches'
-  | 'registers-into';
-
-/** Union for derived graph-edge styling — the trail step mechanism. */
-export type SubsystemEdgeMechanism = SubsystemTrailMechanism;
-
-/**
- * Which edge source the canvas draws. The two sources are disjoint; a view
+/** Which edge source the canvas draws. The two sources are disjoint; a view
  * shows only edges (and their labels) from the selected source.
  * - `graphify`: only graphify-native static edges (`imports`, `contains`, …)
  * - `trails`: only trail step edges (`calls`, `feeds`, …)
@@ -203,155 +177,10 @@ export interface SubsystemGraphifyRelation {
   context?: string;
 }
 
-/** A component node — the named unit, construct-tagged; `file` is its location. */
-export interface SubsystemComponent {
-  /**
-   * Model-local stable alias, unique per model. Referenced by trail
-   * `from` / `to`; edges point at the alias, not the location.
-   * Code identity (for composed multi-model views) lives on
-   * `purl` + `file` + `symbol`, not here.
-   */
-  alias: string;
-  name: string;
-  /**
-   * The node's construct — what it IS as a declaration (class, function,
-   * method, interface, type alias, enum, store, external), driving node
-   * anatomy, color, badge, and the verification strategy. Every construct
-   * anchors to a definition; runtime occurrences (variables, activations,
-   * instances) are NOT constructs — they belong to a future execution-mode
-   * graph whose occurrence nodes reference these definitions. Ontology:
-   * construct = what it is, framework + stereotype = which framework pattern
-   * it plays, role = where it sits, process = where it runs. Prefer
-   * `framework` + `stereotype` over inventing framework-specific constructs
-   * (a React component is still `construct: 'function'`).
-   */
-  construct: SubsystemComponentConstruct;
-  /** Source location the component lives in (repo-root-relative path). */
-  file: string;
-  /** PURL identifying the repo or package this component lives in (for subgraph grouping). */
-  purl: string;
-  /**
-   * App/repo logo shown on the declaration card in place of the GitHub owner
-   * avatar (any image URL or data URI). Optional; typically one image stamped
-   * across the components of a repo.
-   */
-  logo?: string;
-  /** One-line purpose shown on the node. */
-  purpose?: string;
-  /**
-   * Design / migration placeholder — participates in edges and flows but is
-   * not a live source declaration yet. Verification skips source checks until
-   * promoted (`proposed` cleared, `file` + `symbol` filled). Orthogonal to
-   * `construct` (intended shape) and `role` (topology).
-   */
-  proposed?: boolean;
-  /**
-   * The claim was real but its source is gone upstream — deleted or renamed.
-   * The inverse of `proposed`; verification skips source checks the same way.
-   * Renders with a slate border and a `deprecated` badge that opens the removal
-   * provenance. Transitional — a cleanup pass removes the node.
-   */
-  deprecated?: boolean;
-  /** Which commit removed this claim's source, and why. Present when deprecated. */
-  removedIn?: SubsystemComponentRemoval;
-  /**
-   * Semantic role — where the node sits in the topology (boundary element,
-   * external system), orthogonal to `construct` (what it is). Drives the
-   * glyph and the edge-pairing rules: boundary-crossing edges must terminate
-   * at an entry or a service. Retained state is NOT a role — it is
-   * `construct: 'store'` (state-block anatomy, `writes`/`reads`/`watches`
-   * inbound, `produces` outbound).
-   */
-  role?: SubsystemComponentRole;
-  /**
-   * Framework that owns the stereotype vocabulary (e.g. `react`, `nestjs`).
-   * Orthogonal to `construct` — leave empty for language-only units.
-   */
-  framework?: SubsystemFramework;
-  /**
-   * Framework pattern this declaration plays (e.g. `component`, `hook`).
-   * When set, the node badge prefers this label over the construct name so
-   * a React UI unit reads as "component" rather than "function".
-   */
-  stereotype?: SubsystemStereotype;
-  /**
-   * Open-string entity kind for `construct: 'custom_entity'` nodes — what the
-   * actor/entity is (e.g. `Person`, `agent`, `queue`). Not code; there is no
-   * graphify anchor. Contrast with `construct` (what the declaration is) and
-   * `role` (where it sits topologically). Empty/unset for code constructs.
-   */
-  entityKind?: string;
-  /**
-   * Authored color override for the node border + badges, when the themed
-   * construct color isn't wanted. Primarily for `construct: 'custom_entity'`
-   * (an author picks a fitting hue for a Person/agent/queue) — but usable on
-   * any construct. Any `#rrggbb` string; when set it wins over the
-   * construct-derived color, mirrors in the declaration panel. Leave unset to
-   * inherit the Pierre construct palette.
-   */
-  color?: string;
-  /**
-   * Runtime process membership — which deployment unit this node is a
-   * member of (e.g. `principal-studio/host`, `principal-studio/renderer`). Nodes
-   * sharing a `process` are drawn inside one boundary region; nodes without
-   * one sit outside every process boundary (external actors, services,
-   * libraries). Orthogonal to `module` (source-file frame).
-   */
-  process?: string;
-  /**
-   * Source-module membership — which file/module this export belongs to
-   * (e.g. `src/session/transcript.ts`). Nodes sharing a `module` are drawn
-   * inside one boundary frame. Prefer this over inventing a module construct:
-   * each export keeps its real construct (`function` / `class` / …) and the
-   * file reads as a frame. Orthogonal to `process` (runtime deployment).
-   * When both are set, the module frame is the component's parent (finer
-   * grain); process framing still groups siblings that share a process.
-   */
-  module?: string;
-  /** A symbol this component exposes / is (the node's identity). */
-  symbol?: string;
-  /**
-   * Semantic layer/phase for the layout (e.g. `1` = input, `2` = processing,
-   * `3` = output). When set, ELK places the component in this layer so the
-   * graph reads as a left-to-right pipeline and *conveys the idea* rather than
-   * letting ELK guess the order.
-   */
-  layer?: number;
-  /**
-   * Structured declaration shape of the construct (params, members, type
-   * buckets, …). Single source of truth for the click panel — authored by
-   * agents/CLI or filled by verified graphify capture. Discriminated by kind.
-   */
-  declaration?: SubsystemConstructDeclaration;
-  /**
-   * @deprecated No longer used — verification now tracks at the model level
-   * via `verifiedAtCommits`. Keeping the field temporarily for migration.
-   */
-  declarationProvenance?: SubsystemDeclarationProvenance;
-  /**
-   * Pre-tokenized declaration for the detail panel. When present, the
-   * renderer skips client-side tokenization. Tokens are language-agnostic;
-   * a different language just needs a different tokenizer and text joiner.
-   */
-  tokens?: SubsystemDeclToken[];
-  /**
-   * Accepted agent-extracted signature (from the graphify augmentation store)
-   * confirming this function/method when Graphify has no usable signature
-   * edges. Populated by the host when serving an enriched graph — never
-   * persisted in the model document. Rendered as the declaration when the
-   * component has no own `declaration`; no marker distinguishes the source.
-   */
-  signatureAugmentation?: SubsystemSignatureClaim;
-  /**
-   * Anchored declaration location: graphify start line + hash of that line's
-   * content at capture time. Populated by verify when an exact anchor resolves.
-   */
-  declarationRef?: SubsystemDeclarationRef;
-}
-
 /**
  * Derived / display graph edge used by renderers. Built from trail steps
  * (and graphify-native relations) — not authored as its own document field.
+ * Richer than core's minimal edge: this is the canvas's drawing shape.
  */
 export interface SubsystemComponentEdge {
   id: string;
@@ -359,7 +188,7 @@ export interface SubsystemComponentEdge {
   to: string; // component alias or external target label
   /**
    * The edge verb. For `provenance: 'subsystem'` (the default) this is a
-   * `SubsystemEdgeMechanism`; for `provenance: 'graphify'` it is the raw
+   * `SubsystemTrailMechanism`; for `provenance: 'graphify'` it is the raw
    * graphify relation. Typed as `string` because the display edge is a derived
    * structure and graphify's verb set is open — the trail vocabulary
    * (`SubsystemTrailMechanism`) stays closed.
@@ -381,60 +210,6 @@ export interface SubsystemComponentEdge {
   context?: string;
 }
 
-/**
- * A single runtime step — `from`/`to`/`mechanism` plus the exact `file:line`
- * where that seam fires for a trail.
- */
-export interface SubsystemTrailStep {
-  from: string;
-  to: string;
-  mechanism: SubsystemTrailMechanism;
-  /** Repo-root-relative path of the file where the seam fires. */
-  file: string;
-  /** 1-based line of the site within `file`. */
-  line: number;
-  /**
-   * File-anchored purl of the seam site (e.g.
-   * `pkg:github/owner/name#path/to/file.ts`), mirroring component `purl`.
-   * Required: readers resolve the checkout from this instead of guessing
-   * the repo from the step's endpoint components.
-   */
-  purl: string;
-  /**
-   * Frame name for this step — the function/method on the stack at the site.
-   * Required; the Trails list shows this instead of a bare
-   * mechanism + filename fallback.
-   */
-  symbol: string;
-  /**
-   * Planned seam — the step describes intended behavior through code that is
-   * not written yet. Orthogonal to (and redundant with) the endpoints' own
-   * `proposed` flags: a step is proposed when it says so OR either endpoint
-   * is proposed. Verification skips source checks either way, and viewers
-   * tint it exactly like a proposed node.
-   */
-  proposed?: boolean;
-  /**
-   * Free-text note anchored to this step's site line. Optional — informative
-   * only, never verified against source; the Pierre trail code view
-   * surfaces it in the annotation column next to the highlighted line.
-   */
-  annotation?: string;
-}
-
-/** An ordered runtime trail — one named behavior story. */
-export interface SubsystemTrail {
-  id: string;
-  title: string;
-  steps: SubsystemTrailStep[];
-}
-
-export interface SubsystemModelDocument {
-  components: SubsystemComponent[];
-  /** Ordered runtime trails (one per named behavior). */
-  trails?: SubsystemTrail[];
-}
-
 /** Stable id for a derived graph edge from a trail step. */
 export function derivedGraphEdgeId(
   from: string,
@@ -819,47 +594,29 @@ function packageRegionLabel(packageKey: string): string {
 
 /**
  * Derive process boundary regions — one per distinct non-empty `process`
- * value, in first-appearance order.
+ * value, in first-appearance order. Wraps core's rollup, adding the frame
+ * `kind` the canvas reads.
  */
 export function getSubsystemRegions(
   doc: Pick<SubsystemModelDocument, 'components'>,
 ): SubsystemProcessRegion[] {
-  const byProcess = new Map<string, string[]>();
-  for (const c of doc.components) {
-    const p = c.process?.trim();
-    if (!p) continue;
-    const list = byProcess.get(p) ?? [];
-    list.push(c.alias);
-    byProcess.set(p, list);
-  }
-  return [...byProcess.entries()].map(([key, memberAliases]) => ({
+  return coreGetSubsystemProcessRegions(doc).map((r) => ({
+    ...r,
     kind: 'process' as const,
-    key,
-    label: key,
-    memberAliases,
   }));
 }
 
 /**
  * Derive module boundary regions — one per distinct non-empty `module`
  * value, in first-appearance order. Label is the module path (file).
+ * Wraps core's rollup, adding the frame `kind` the canvas reads.
  */
 export function getSubsystemModuleRegions(
   doc: Pick<SubsystemModelDocument, 'components'>,
 ): SubsystemProcessRegion[] {
-  const byModule = new Map<string, string[]>();
-  for (const c of doc.components) {
-    const m = c.module?.trim();
-    if (!m) continue;
-    const list = byModule.get(m) ?? [];
-    list.push(c.alias);
-    byModule.set(m, list);
-  }
-  return [...byModule.entries()].map(([key, memberAliases]) => ({
+  return coreGetSubsystemModuleRegions(doc).map((r) => ({
+    ...r,
     kind: 'module' as const,
-    key,
-    label: key,
-    memberAliases,
   }));
 }
 
@@ -1933,7 +1690,7 @@ export function nodeMinWidthForBadges(component: {
  * then refines with compound layout.
  */
 export function convertSubsystemToNodes(
-  doc: SubsystemModelDocument,
+  doc: Pick<SubsystemModelDocument, 'components' | 'trails'>,
   opts: { maxNodeWidth?: number } = {},
 ): SubsystemGraphNode[] {
   const { maxNodeWidth } = opts;
@@ -2024,7 +1781,7 @@ export function convertSubsystemToGroups(
  * relationship is visible without a member node.
  */
 export function convertSubsystemToEdges(
-  doc: SubsystemModelDocument,
+  doc: Pick<SubsystemModelDocument, 'components' | 'trails'>,
   graphifyRelations: readonly SubsystemGraphifyRelation[] = [],
 ): SubsystemGraphEdge[] {
   const compAliases = new Set(doc.components.map((c) => c.alias));
@@ -2086,7 +1843,7 @@ export function subsystemGraphLayoutKey(
  * layered with minimized crossings.
  */
 export async function buildSubsystemGraph(
-  doc: SubsystemModelDocument,
+  doc: Pick<SubsystemModelDocument, 'components' | 'trails'>,
   opts: {
     maxNodeWidth?: number;
     showEdgeLabels?: boolean;

package/src/subsystem/nodes.group.test.tsx

@@ -113,4 +113,19 @@ describe('SubsystemGroupNode boundary badge', () => {
     });
     expect(container.textContent).toContain('3');
   });
+
+  test('a process verification finding badges the process frame too', () => {
+    // Dynamic-topology findings target kind `process`; the frame badge is the
+    // same mechanism as a module finding — the boundary's state is the fault.
+    const { container } = renderGroup({
+      region,
+      issue: {
+        severity: 'info',
+        kind: 'boundary_process_unassigned',
+        count: 1,
+      },
+    });
+    // The kind has a dedicated frame icon, so the lucide icon carries the class.
+    expect(container.querySelector('.lucide-circle-ellipsis')).not.toBeNull();
+  });
 });

package/src/subsystem/nodes.tsx

@@ -146,10 +146,10 @@ function NodeIssueOverlay({ issue }: { issue: SubsystemNodeIssue }) {
 
 /**
  * The shared severity chip: a severity-colored ring around the finding's icon,
- * with a count when there is more than one. Component nodes anchor it to the
- * bottom-right corner; a region frame anchors it to the top-right so it never
- * collides with the frame's own name badge. `aria-hidden` and inert — the
- * canvas badge never competes with the sidebar card for the interaction.
+ * with a count when there is more than one. Component nodes and region frames
+ * both anchor it overhanging the bottom-right corner — the issues convention.
+ * `aria-hidden` and inert — the canvas badge never competes with the sidebar
+ * card for the interaction.
  */
 function IssueChip({
   color,
@@ -709,8 +709,8 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
           label
         )}
       </div>
-      {/* Boundary diagnostics badge — top-right, opposite the name badge, so the
-          two never collide however long the module path grows. */}
+      {/* Boundary diagnostics badge — overhanging the bottom-right corner, the
+          same anchor component chips wear. */}
       {data.issue && ISSUE_KIND_ICON[data.issue.kind] && (
         <IssueChip
           color={
@@ -720,7 +720,7 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
           }
           Icon={ISSUE_KIND_ICON[data.issue.kind]!}
           count={data.issue.count}
-          anchor={{ right: 12, top: 0, transform: 'translateY(-50%)' }}
+          anchor={{ right: -9, bottom: -8 }}
         />
       )}
     </div>

package/src/subsystem/techIcons/index.tsx

@@ -24,6 +24,11 @@ export interface TechBrand {
   svg: string;
   /** Matched against the technology string. First match in `TECH_BRANDS` wins. */
   match: RegExp;
+  /**
+   * Representative brand hue, for the card border. The dominant colour of the
+   * mark, chosen to stay legible as a thin line.
+   */
+  color: string;
 }
 
 /**
@@ -36,12 +41,14 @@ export const TECH_BRANDS: readonly TechBrand[] = [
     source: 'https://react.dev',
     svg: reactSvg,
     match: /\breact\b/i,
+    color: '#61dafb',
   },
   {
     name: 'Bun',
     source: 'https://bun.sh/logo.svg',
     svg: bunSvg,
     match: /\bbun\b/i,
+    color: '#fbf0df',
   },
   {
     name: 'Node.js',
@@ -50,6 +57,7 @@ export const TECH_BRANDS: readonly TechBrand[] = [
     // Matches "Node" and "Node.js"; "Electrobun" has no word boundary before
     // "bun" and never reaches here.
     match: /\bnode(\.js)?\b/i,
+    color: '#5fa04e',
   },
 ];
 

package/src/utils/edgeLabel.test.ts

@@ -11,13 +11,32 @@ import {
   EDGE_LABEL_WIDTH,
   EDGE_LABEL_SIDE_PADDING,
   EDGE_LABEL_EDGE_GAP,
+  estimateEdgeLabelWidth,
 } from './edgeLabel';
 
+describe('estimateEdgeLabelWidth', () => {
+  test('grows with the text', () => {
+    expect(estimateEdgeLabelWidth('file I/O')).toBeGreaterThan(estimateEdgeLabelWidth('RPC'));
+  });
+
+  test('clamps a very short label to a readable minimum', () => {
+    expect(estimateEdgeLabelWidth('')).toBe(48);
+    expect(estimateEdgeLabelWidth('a')).toBe(48);
+  });
+
+  test('fits the longest C4 protocol we render', () => {
+    // A rough sanity ceiling: 'file I/O' plus chip padding must sit under the
+    // shared fixed width, or C4 would be wider than the box it replaced.
+    expect(estimateEdgeLabelWidth('file I/O')).toBeLessThan(EDGE_LABEL_WIDTH);
+  });
+});
+
 describe('edge-label geometry', () => {
-  test('the labelled-edge gap is the box plus clearance on both sides', () => {
+  test('the reserved run is the chip plus clearance on both sides', () => {
+    // The reserved label box carries the chip width plus the side padding,
+    // because ELK's CENTER_LAYER adds no clearance of its own.
     expect(EDGE_LABEL_EDGE_GAP).toBe(
       EDGE_LABEL_WIDTH + EDGE_LABEL_SIDE_PADDING * 2,
     );
-    expect(EDGE_LABEL_EDGE_GAP).toBeGreaterThan(EDGE_LABEL_WIDTH);
   });
 });

package/src/utils/edgeLabel.ts

@@ -19,6 +19,34 @@ export const EDGE_LABEL_HEIGHT = 40;
 /** Label font size. Fixed so every label renders at the same text size. */
 export const EDGE_LABEL_FONT_SIZE = 14;
 
+/**
+ * Approx monospace advance at `EDGE_LABEL_FONT_SIZE` (14px), incl. the tiny
+ * letter-spacing. Fira Code / SF Mono / Courier sit at ~0.6em (8.4px); rounded
+ * up so a width estimate never undershoots and clips the label.
+ */
+const LABEL_CHAR_WIDTH = 8.5;
+
+/** Chip chrome: horizontal padding is 8+8 in the overlay (see C4EdgeLabels). */
+const LABEL_CHIP_CHROME = 16;
+
+/**
+ * Estimated rendered width of an edge label's chip, from its text. Both the
+ * overlay and the ELK reservation must use this same number, or the reserved
+ * run drifts from what renders. Clamped to a minimum so a one-word protocol
+ * still reads as a chip.
+ */
+export function estimateEdgeLabelWidth(text: string): number {
+  return Math.max(48, (text?.length ?? 0) * LABEL_CHAR_WIDTH + LABEL_CHIP_CHROME);
+}
+
+/**
+ * Reserved label width for C4's own edges, used as the fallback/max when a
+ * caller doesn't size per-label. C4's lines carry short protocols (`RPC`,
+ * `HTTP`, `file I/O`), so the shared 140 (sized for the component graph's
+ * `registers-into`) is wider than needed and inflates the run between boxes.
+ */
+export const C4_LABEL_WIDTH = 90;
+
 /**
  * Clear space we want on each side of a label box.
  *
@@ -33,7 +61,7 @@ export const EDGE_LABEL_FONT_SIZE = 14;
  * "min edge length" here double-counts (it is applied twice), which is how the
  * gap silently ballooned before.
  */
-export const EDGE_LABEL_SIDE_PADDING = 8;
+export const EDGE_LABEL_SIDE_PADDING = 32;
 
 /** Actual end-to-end gap ELK leaves for a labelled edge (box + both clearances). */
 export const EDGE_LABEL_EDGE_GAP =

package/src/utils/elkLayout.test.ts

@@ -15,8 +15,10 @@ import {
   pointAlongPath,
   fractionAlongPath,
   planCompoundGroups,
+  getElkOptions,
   type Point,
 } from './elkLayout';
+import { EDGE_LABEL_WIDTH, EDGE_LABEL_SIDE_PADDING } from './edgeLabel';
 
 describe('planCompoundGroups', () => {
   test('drops a single-leaf group by default and promotes its member', () => {
@@ -131,6 +133,20 @@ describe('planCompoundGroups', () => {
 });
 
 describe('elkLayout helper functions', () => {
+  describe('getElkOptions — label-aware between-layer spacing', () => {
+    test('does not stack spacing on top of ELK’s reserved label layer', () => {
+      // CENTER_LAYER already reserves the label; adding the box width here
+      // double-counts and balloons the run (measured 548px for 140 + 204).
+      const opts = getElkOptions({ edgeLabels: { enabled: true, placement: 'CENTER' } });
+      expect(opts['elk.layered.spacing.nodeNodeBetweenLayers']).toBe('0');
+    });
+
+    test('an explicit interLayerSpacing still wins', () => {
+      const opts = getElkOptions({ interLayerSpacing: 120, edgeLabels: { enabled: true } });
+      expect(opts['elk.layered.spacing.nodeNodeBetweenLayers']).toBe('120');
+    });
+  });
+
   describe('pointAlongPath / fractionAlongPath', () => {
     const bent: Point[] = [
       { x: 0, y: 0 },