@principal-ai/subsystems-react 0.51.3 → 0.52.0

package/src/subsystem/c4Evidence.ts

@@ -1,57 +1,29 @@
 /**
- * C4 evidence — what an agent needs in order to propose elements.
+ * C4 evidence — the pure read-side of proposing and verifying C4 containers.
  *
- * This module does not decide anything. It answers "what is worth asking
- * about?" so an agent can go and read the source, then propose a
- * `C4Element` with a rationale. The questions come from the C4 notation
- * rules the document cannot satisfy on its own:
+ * This module does not decide anything. The proposing agent reads the
+ * subsystem diagrams, queries the existing containers, reasons, and writes
+ * its own rationale; what lives here is only the mechanical part of that
+ * loop:
  *
- *   - every container needs a technology
- *   - every element needs a description
- *   - a container is a runtime boundary, so a library is not one
- *   - a container cannot straddle two software systems
+ *   - `proposeElements` — the proposal scaffold: skip keys containers
+ *     already claim, skip boundaries no container can be discerned from
+ *     (no runtime code behind them)
+ *   - `verifyProcessBoundaries` — a boundary's verification status, read
+ *     off the claiming container
+ *   - `verificationIssues` — those statuses as dynamic-topology findings,
+ *     so verification surfaces through the standard diagnostics pipeline
+ *   - `findUnassigned` — runtime components no `process` names at all
  *
- * The output is a set of concerns. Resolving one is the agent's job, and the
- * answer lands in an element's `rationale`.
+ * Judgements — is this the same unit under a different name? is one function
+ * a deployable unit? — belong to the agent and the human, never to a
+ * matcher.
  */
 
 import type { C4Container, C4ContainerKind, C4Element, C4ElementSet } from './c4';
+import type { SubsystemIssue } from './IssueList';
 
-/** What a concern is about — a derived key, or an existing element id. */
-export interface C4Concern {
-  /** The process key, module path, or element id this concerns. */
-  target: string;
-  kind: C4ConcernKind;
-  message: string;
-  /** Aliases that triggered it. */
-  members?: string[];
-}
-
-/**
- * The questions worth a human's attention.
- *
- * Each maps to something an agent cannot settle by reading a string — it has
- * to open the source, or ask the user.
- */
-export type C4ConcernKind =
-  /** two or more process keys may be the same deployable unit */
-  | 'merge_candidate'
-  /** exactly one member — a lone function is not a deployable unit */
-  | 'singleton'
-  /** no member executes at runtime — a library is not a container */
-  | 'library_shaped'
-  /** a store whose storage kind was never decided */
-  | 'store_unclassified'
-  /** members claim more than one repo — a container cannot straddle systems */
-  | 'spans_repos'
-  /** an external with no resolvable identity */
-  | 'external_unidentified'
-  /** a runtime component with no process at all */
-  | 'unassigned'
-  /** C4 requires technology on every container */
-  | 'missing_technology';
-
-/** The fields a concern check reads off a component. */
+/** The fields the propose/verify gates read off a component. */
 export interface C4MemberView {
   alias: string;
   construct: string;
@@ -76,122 +48,6 @@ export function isRuntimeConstruct(construct: string): boolean {
   return RUNTIME_CONSTRUCTS.has(construct);
 }
 
-/**
- * Derive the questions worth asking about one candidate element.
- *
- * Pure over the rollup, so it runs identically against a single model, the 40
- * composed models, or a fixture. Pure *questions* — it never proposes an
- * answer, because the answers are architectural.
- */
-export function deriveConcerns(
-  key: string,
-  members: readonly C4MemberView[],
-  tech: { frameworks: readonly string[] } = { frameworks: [] },
-): C4Concern[] {
-  const out: C4Concern[] = [];
-  const aliases = members.map((m) => m.alias);
-  const runtime = members.filter((m) => isRuntimeConstruct(m.construct));
-
-  if (members.length === 1) {
-    out.push({
-      target: key,
-      kind: 'singleton',
-      message: `process "${key}" has exactly one member (${aliases[0]}) — a lone function is not a deployable unit`,
-      members: aliases,
-    });
-  }
-
-  // No member executes at runtime ⇒ this cannot be a deployable unit,
-  // regardless of how many members it has. A lone interface and a package of
-  // interfaces fail the same way.
-  if (members.length > 0 && runtime.length === 0) {
-    out.push({
-      target: key,
-      kind: 'library_shaped',
-      message: `process "${key}" has ${members.length} member(s) but none execute at runtime (${[...new Set(members.map((m) => m.construct))].join(', ')}) — this reads as a library, not a container`,
-      members: aliases,
-    });
-  }
-
-  if (runtime.length > 0 && tech.frameworks.length === 0) {
-    out.push({
-      target: key,
-      kind: 'missing_technology',
-      message: `container "${key}" has no framework signal — C4 requires a technology on every container`,
-      members: aliases,
-    });
-  }
-
-  const repos = new Set(
-    members
-      .map((m) => (m.purl ?? '').split('#')[0])
-      .filter((r) => r && !r.startsWith('external:')),
-  );
-  if (repos.size > 1) {
-    out.push({
-      target: key,
-      kind: 'spans_repos',
-      message: `process "${key}" spans ${repos.size} repo keys (${[...repos].join(', ')}) — a C4 container cannot straddle a system boundary`,
-      members: aliases,
-    });
-  }
-
-  const unclassified = members.filter((m) => m.construct === 'store' && !storageOf(m));
-  if (unclassified.length > 0) {
-    out.push({
-      target: key,
-      kind: 'store_unclassified',
-      message: `${unclassified.length} store(s) in "${key}" declare no storage kind (${unclassified.map((m) => m.alias).join(', ')}) — decide whether each is a C4 data store or an internal detail`,
-      members: unclassified.map((m) => m.alias),
-    });
-  }
-
-  const unidentified = members.filter(
-    (m) => m.construct === 'external' && (!m.purl || m.purl === 'external' || m.purl.startsWith('external:proposed')),
-  );
-  if (unidentified.length > 0) {
-    out.push({
-      target: key,
-      kind: 'external_unidentified',
-      message: `${unidentified.length} external(s) have no resolvable identity (${unidentified.map((m) => m.alias).join(', ')}) — a C4 box named "external" is not a diagram`,
-      members: unidentified.map((m) => m.alias),
-    });
-  }
-
-  return out;
-}
-
-/**
- * Suggest merges between keys that share a trailing role.
- *
- * `subsystems-studio/host` and `principal-studio/host` are the same role under
- * two app names. This is a *question*, never a merge — only the user knows
- * whether they are one process or two.
- */
-export function suggestMerges(
-  rollup: ReadonlyArray<{ key: string; memberCount: number }>,
-): Array<{ role: string; keys: string[]; reason: string }> {
-  const byRole = new Map<string, string[]>();
-  for (const { key } of rollup) {
-    const slash = key.lastIndexOf('/');
-    if (slash <= 0) continue; // a bare key has no app/role shape
-    const role = key.slice(slash + 1);
-    const list = byRole.get(role) ?? [];
-    list.push(key);
-    byRole.set(role, list);
-  }
-  const out: Array<{ role: string; keys: string[]; reason: string }> = [];
-  for (const [role, keys] of [...byRole].sort((a, b) => a[0].localeCompare(b[0]))) {
-    if (keys.length < 2) continue;
-    out.push({
-      role,
-      keys: [...keys].sort(),
-      reason: `${keys.length} process keys end in "/${role}" (${[...keys].sort().join(', ')}) — one deployable unit under two names, or two units?`,
-    });
-  }
-  return out;
-}
-
 /**
  * Runtime components that state no `process` at all.
  *
@@ -204,87 +60,158 @@ export function findUnassigned(members: readonly C4MemberView[]): C4MemberView[]
 }
 
 /**
- * Fold a decided merge into an element set.
+ * How far a process boundary has travelled toward being a container.
  *
- * Two process keys that are really one container become ONE element holding
- * both sets of members. The survivor keeps the id, label, and confirmed
- * attributes; the other disappears and its members move across.
+ * A boundary starts `unassigned` — no container claims it. Proposing an
+ * element for it (see `proposeElements`) assigns the boundary to a container,
+ * which reads as `proposed` until a human decides. `accepted` verifies the
+ * boundary: someone approved this run of code as one deployable unit.
+ * `rejected` means the proposal was wrong and the boundary should not be
+ * drawn as a box.
+ */
+export type C4ProcessVerification =
+  | 'unassigned'
+  | 'proposed'
+  | 'rejected'
+  | 'verified';
+
+/** One process boundary's assignment and its review state. */
+export interface C4ProcessBoundaryStatus {
+  /** The `process` key, e.g. `principal-studio/host`. */
+  key: string;
+  /** Aliases carrying this key in the model, when the caller supplied them. */
+  memberAliases: string[];
+  status: C4ProcessVerification;
+  /** The container whose state decided the status. Absent when `unassigned`. */
+  element?: C4Element;
+}
+
+/**
+ * Read a process boundary's verification off its container assignment.
  *
- * Which side survives is the **evidence-heavy** one — the element holding more
- * members — because folding the 113-member host into the 1-member one would
- * leave the box labelled after an almost-empty process and lose its confirmed
- * technology. Pass `preferId` to override.
+ * The claimant is the container whose `process` equals the boundary's key —
+ * a plain string match, no indirection. Two keys that are one deployable unit
+ * under two names are fixed in the model document (a consolidation proposal
+ * rewrites the components' `process` fields), so the reader never sees a
+ * discrepancy to resolve. When several containers claim one key (a
+ * hand-edited set can do this), the decided one wins: accepted over rejected
+ * over proposed, so one reviewer's yes outranks another's no.
  *
- * Returns a new set; the input is untouched. Idempotent.
+ * Pure: the same rollup and elements always read the same. `rollup` accepts
+ * `SubsystemProcessRegion`s directly — only `key` and `memberAliases` are read.
  */
-export function mergeElements(
-  elements: readonly C4Element[],
-  derivedFromKeys: readonly string[],
-  preferId?: string,
-  memberCountByKey?: ReadonlyMap<string, number>,
-): C4Element[] {
-  const wanted = new Set(derivedFromKeys.map((k) => k.trim()).filter(Boolean));
-  if (wanted.size < 2) return [...elements];
-
-  const involved = elements.filter((e) => e.derivedFrom?.some((k) => wanted.has(k)));
-  if (involved.length < 2) return [...elements];
-  // Only containers merge. A component has a required `container` field, and
-  // folding one into another would silently repoint it at a new parent.
-  if (involved.some((e) => e.kind !== 'container')) return [...elements];
+export function verifyProcessBoundaries(options: {
+  rollup: ReadonlyArray<{ key: string; memberAliases?: readonly string[] }>;
+  elements: readonly C4Element[];
+}): C4ProcessBoundaryStatus[] {
+  const byKey = new Map<string, C4Element[]>();
+  for (const e of options.elements) {
+    if (e.kind !== 'container' || !e.process) continue;
+    const list = byKey.get(e.process) ?? [];
+    list.push(e);
+    byKey.set(e.process, list);
+  }
 
-  const weight = (e: C4Element): number => {
-    if (memberCountByKey) {
-      let n = 0;
-      for (const k of e.derivedFrom ?? []) n += memberCountByKey.get(k) ?? 0;
-      return n;
+  const precedence = { accepted: 0, rejected: 1, proposed: 2 } as const;
+  return options.rollup.map(({ key, memberAliases }) => {
+    const aliases = [...(memberAliases ?? [])];
+    const claimants = byKey.get(key) ?? [];
+    if (claimants.length === 0) {
+      return { key, memberAliases: aliases, status: 'unassigned' as const };
     }
-    return e.members.length;
-  };
-
-  const survivor =
-    (preferId ? involved.find((e) => e.id === preferId) : undefined) ??
-    [...involved].sort((a, b) => weight(b) - weight(a) || a.id.localeCompare(b.id))[0]!;
-
-  const absorbed = involved.filter((e) => e.id !== survivor.id);
-  const absorbedIds = new Set(absorbed.map((e) => e.id));
-
-  const merged: C4Container = {
-    ...(survivor as C4Container),
-    members: [...new Set([...survivor.members, ...absorbed.flatMap((e) => e.members)])],
-    derivedFrom: [
-      ...new Set([...(survivor.derivedFrom ?? []), ...absorbed.flatMap((e) => e.derivedFrom ?? [])]),
-    ],
-    rationale:
-      [survivor.rationale, ...absorbed.map((e) => e.rationale)].filter(Boolean).join(' | ') ||
-      undefined,
-  };
+    const decided = [...claimants].sort(
+      (a, b) => precedence[a.state] - precedence[b.state] || a.id.localeCompare(b.id),
+    )[0]!;
+    const status = decided.state === 'accepted' ? ('verified' as const) : decided.state;
+    return { key, memberAliases: aliases, status, element: decided };
+  });
+}
 
-  return [...elements.filter((e) => e.id !== survivor.id && !absorbedIds.has(e.id)), merged].sort(
-    (a, b) => a.id.localeCompare(b.id),
-  );
+/**
+ * Verification statuses as diagnostics findings — the dynamic-topology layer
+ * of the issues list. One finding per boundary that is NOT verified: an
+ * unclaimed boundary is the absence a proposing agent run resolves, a
+ * `proposed` one awaits the human's decision, a `rejected` one records that
+ * the decision was no. `verified` reports nothing — the audit reports
+ * absence only, and silence is the good state.
+ *
+ * The findings ride the existing pipeline untouched: they badge the process
+ * frame (target kind `process`), list under Dynamic topology, focus their
+ * members on click, and carry the fix the decision needs. Pure over its
+ * input, like the rest of this module.
+ */
+export function verificationIssues(
+  statuses: readonly C4ProcessBoundaryStatus[],
+): SubsystemIssue[] {
+  const out: SubsystemIssue[] = [];
+  for (const { key, status, element } of statuses) {
+    if (status === 'verified') continue;
+    const label = element?.label ?? key;
+    out.push({
+      id: `process-verification:${key}`,
+      severity: 'info',
+      kind: `boundary_process_${status}`,
+      message:
+        status === 'unassigned'
+          ? `No C4 container claims this process boundary yet — a proposing agent run would scaffold one.`
+          : status === 'proposed'
+            ? `Container "${label}" claims this boundary and awaits a decision.`
+            : `Container "${label}" was rejected for this boundary — it stays unclaimed until a container is accepted.`,
+      target: { kind: 'process', id: key, label: key },
+      fix:
+        status === 'unassigned'
+          ? { label: 'Propose container' }
+          : status === 'proposed'
+            ? { label: 'Accept container' }
+            : undefined,
+    });
+  }
+  return out;
 }
 
 /**
- * A starting point for an agent: one proposed element per derived key, shaped
- * by the mechanical evidence, with the open questions in the rationale.
+ * A starting point for an agent, shaped by the two questions that matter when
+ * assessing a process boundary:
  *
- * Every element comes back `proposed`. This is a scaffold to edit and argue
- * with — not an answer, and never `accepted`.
+ *   1. **Does a container already exist for it?** (`elements`) — a key one
+ *      already claims is never re-proposed; proposing another would be
+ *      exactly the duplicate this module exists to prevent. The exact claim
+ *      is a fact and skipped here; whether a *similarly named* container is
+ *      the same unit is a judgement, so it belongs to the agent querying the
+ *      container list — the fix there is a consolidation proposal, not a
+ *      second box.
+ *   2. **Can the boundary be discerned into a container?** — code that never
+ *      runs cannot be, so a library-shaped group gets no proposal; that
+ *      fact is the agent's to report, not the scaffold's.
+ *
+ * For boundaries passing both, one `proposed` container per key. The
+ * rationale is the proposing agent's own reasoning, written on the proposal
+ * it POSTs — this scaffold does not fabricate one. A scaffold to edit and
+ * argue with — not an answer, and never `accepted`.
  */
-export function proposeElements(
-  options: {
-    repoKey: string;
-    rollup: ReadonlyArray<{ key: string; members: readonly C4MemberView[]; frameworks: readonly string[] }>;
-    author?: string;
-  },
-): C4ElementSet {
-  const elements = options.rollup.map(({ key, members, frameworks }) => {
-    const concerns = deriveConcerns(key, members, { frameworks });
-    return {
+export function proposeElements(options: {
+  repoKey: string;
+  rollup: ReadonlyArray<{
+    key: string;
+    members: readonly C4MemberView[];
+    frameworks: readonly string[];
+  }>;
+  /** Containers that already exist (from the element store), by `process` claim. */
+  elements?: readonly C4Element[];
+}): C4ElementSet {
+  const existing = options.elements ?? [];
+  const claimed = new Set(existing.flatMap((e) => (e.kind === 'container' && e.process ? [e.process] : [])));
+
+  const elements: C4Container[] = [];
+  for (const { key, members, frameworks } of options.rollup) {
+    if (claimed.has(key)) continue; // already covered — exact claim, a fact
+    const runtime = members.filter((m) => isRuntimeConstruct(m.construct));
+    if (members.length > 0 && runtime.length === 0) continue; // not discernible: code that never runs
+
+    elements.push({
       id: `container:${key}`,
-      kind: 'container' as const,
-      members: members.map((m) => m.alias),
-      derivedFrom: [key],
+      kind: 'container',
+      process: key,
       label: key,
       containerKind: suggestContainerKind(members),
       // C4 requires a technology on every container. With no framework signal
@@ -292,11 +219,9 @@ export function proposeElements(
       // inventing "TypeScript" here would be exactly the derivation this
       // module stopped doing.
       technology: frameworks.length > 0 ? frameworks.join(' + ') : '',
-      state: 'proposed' as const,
-      rationale: concerns.map((c) => c.message).join(' ') || undefined,
-      author: options.author,
-    };
-  });
+      state: 'proposed',
+    });
+  }
 
   return {
     repoKey: options.repoKey,

package/src/subsystem/model.ts

@@ -1429,6 +1429,12 @@ export interface SubsystemGraphEdgeData extends Record<string, unknown> {
   /** True while another edge is selected — render this edge (and its label)
    *  dimmed to focus the selected relationship. */
   dimmed?: boolean;
+  /**
+   * A backing trail step declares itself `proposed` — a planned seam between
+   * otherwise-real components. The SVG edge and its label draw dashed;
+   * distinct from a proposed ENDPOINT, which dashes the node instead.
+   */
+  proposedStep?: boolean;
   /** ELK-computed label midpoint (from the actual edge path, not node centers). */
   labelX?: number;
   labelY?: number;

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>
@@ -833,8 +833,11 @@ export function SubsystemEdge({
   const edgeRef = { mechanism, provenance: data?.provenance };
   const color = edgeColor(edgeRef);
   // Dash style encodes provenance (graphify) and relationship kind (dashed =
-  // inverted-control or observational: hierarchy, registration, watches).
-  const isDashed = edgeStrokeStyle(edgeRef) === 'dashed';
+  // inverted-control or observational: hierarchy, registration, watches). A
+  // step-proposed edge also dashes — the seam itself is planned — matching
+  // the dashed edge label and a proposed node's dashed border.
+  const isDashed =
+    edgeStrokeStyle(edgeRef) === 'dashed' || data?.proposedStep === true;
   const dimmed = data?.dimmed === true;
   // Dim the stroke by color, never via path `opacity`. SVG markers are shared
   // by id; opacity on the referencing path paints every arrowhead that uses

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.
  *