@glossarist/concept-browser 0.7.97 → 0.7.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.97",
+  "version": "0.7.99",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {

package/src/__tests__/components/pipe-bundles.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest';
+import { drawGenericPipes } from '../../components/relation-sphere/pipe-bundles';
+import type { GenericRelationWire } from '../../adapters/types';
+
+/**
+ * Renderer tests for the generic-relation pipe-and-thread bundle.
+ *
+ * Pins the visual contract the user specified:
+ *   1. NO rake shape — no perpendicular spine, no right-angle teeth.
+ *      All segments are direct lines from comp→middle and middle→members.
+ *   2. Thick/thin hierarchy — the parent pipe is THICKER than the child
+ *      threads (reversed from the previous "isDelimiting=true" hack
+ *      that made children thicker than the parent).
+ *   3. Per-member delimiting characteristic is labeled along each thread.
+ */
+function makeSvg(): SVGSVGElement {
+  return document.createElementNS('http://www.w3.org/2000/svg', 'svg') as unknown as SVGSVGElement;
+}
+
+function makeRelation(): GenericRelationWire {
+  return {
+    source: 'https://example.org/vim-2012/concept/1.9',
+    comprehensive: 'https://example.org/vim-2012/concept/1.9',
+    completeness: 'partial',
+    criterion: { eng: 'by magnitude relationship' },
+    register: 'vim-2012',
+    members: [
+      { uri: 'https://example.org/vim-2012/concept/1.17', presence: 'required', count: 'at_least_one',
+        delimitingCharacteristic: { eng: 'multiple of a unit' } },
+      { uri: 'https://example.org/vim-2012/concept/1.18', presence: 'required', count: 'at_least_one',
+        delimitingCharacteristic: { eng: 'submultiple of a unit' } },
+      { uri: 'https://example.org/vim-2012/concept/1.12', presence: 'required', count: 'at_least_one',
+        delimitingCharacteristic: { eng: 'coherent derived unit' } },
+    ],
+  };
+}
+
+describe('drawGenericPipes — pipe-and-thread contract', () => {
+  const pos = new Map<string, { x: number; y: number }>([
+    ['vim-2012/1.9', { x: 0, y: 0 }],
+    ['vim-2012/1.17', { x: 100, y: -50 }],
+    ['vim-2012/1.18', { x: 100, y: 50 }],
+    ['vim-2012/1.12', { x: 100, y: 0 }],
+  ]);
+
+  it('renders nothing when muted', () => {
+    const svg = makeSvg();
+    drawGenericPipes(svg, pos, {
+      isDark: false,
+      color: '#b45309',
+      isMuted: true,
+      relations: [makeRelation()],
+      locale: 'eng',
+    });
+    expect(svg.children.length).toBe(0);
+  });
+
+  it('renders exactly one thick pipe (comp → middle) and three thin threads', () => {
+    const svg = makeSvg();
+    drawGenericPipes(svg, pos, {
+      isDark: false,
+      color: '#b45309',
+      isMuted: false,
+      relations: [makeRelation()],
+      locale: 'eng',
+    });
+    const segs = svg.querySelectorAll('line.pipe-seg');
+    /* 1 pipe + 3 threads = 4 segments total */
+    expect(segs.length).toBe(4);
+
+    /* Identify the pipe: it's the segment originating at the comp position (0,0). */
+    const pipe = Array.from(segs).find(s =>
+      s.getAttribute('x1') === '0' && s.getAttribute('y1') === '0');
+    expect(pipe).toBeDefined();
+    const pipeWidth = parseFloat(pipe!.getAttribute('stroke-width')!);
+
+    /* Threads: every other segment. Their width must be LESS than the pipe. */
+    const threads = Array.from(segs).filter(s => s !== pipe);
+    expect(threads.length).toBe(3);
+    for (const t of threads) {
+      const w = parseFloat(t.getAttribute('stroke-width')!);
+      expect(w).toBeLessThan(pipeWidth);
+    }
+  });
+
+  it('does NOT emit perpendicular spine or right-angle teeth artifacts', () => {
+    const svg = makeSvg();
+    drawGenericPipes(svg, pos, {
+      isDark: false,
+      color: '#b45309',
+      isMuted: false,
+      relations: [makeRelation()],
+      locale: 'eng',
+    });
+    /* The rake emits circle.rake-junction for its right-angle corner.
+       The pipe-and-thread emits rect.pipe-junction (square) instead —
+       a different shape so the two are visually distinguishable. */
+    expect(svg.querySelectorAll('circle.rake-junction').length).toBe(0);
+    expect(svg.querySelectorAll('rect.pipe-junction').length).toBe(1);
+  });
+
+  it('renders ONE characteristic label (the criterion) — no per-thread labels', () => {
+    const svg = makeSvg();
+    drawGenericPipes(svg, pos, {
+      isDark: false,
+      color: '#b45309',
+      isMuted: false,
+      relations: [makeRelation()],
+      locale: 'eng',
+    });
+    const labels = Array.from(svg.querySelectorAll('text.pipe-label')).map(t => t.textContent);
+    /* Exactly one label — the hyperedge-level criterion. Per-member
+       delimitingCharacteristic values are NOT rendered. */
+    expect(labels).toEqual(['by magnitude relationship']);
+  });
+
+  it('renders NO label when the criterion is absent', () => {
+    const svg = makeSvg();
+    const rel = makeRelation();
+    delete rel.criterion;
+    drawGenericPipes(svg, pos, {
+      isDark: false,
+      color: '#b45309',
+      isMuted: false,
+      relations: [rel],
+      locale: 'eng',
+    });
+    /* Pipe + threads + junction + diamond still render, but zero labels. */
+    expect(svg.querySelectorAll('text.pipe-label').length).toBe(0);
+    expect(svg.querySelectorAll('line.pipe-seg').length).toBe(4);
+    expect(svg.querySelectorAll('rect.pipe-junction').length).toBe(1);
+  });
+
+  it('renders a diamond at the comprehensive end (origin marker)', () => {
+    const svg = makeSvg();
+    drawGenericPipes(svg, pos, {
+      isDark: false,
+      color: '#b45309',
+      isMuted: false,
+      relations: [makeRelation()],
+      locale: 'eng',
+    });
+    /* Diamond is the only <path> element produced by the renderer. */
+    const paths = svg.querySelectorAll('path');
+    expect(paths.length).toBe(1);
+    const d = paths[0].getAttribute('d') ?? '';
+    /* Diamond path starts at (cx, cy - half) — centered on comp (0,0). */
+    expect(d.startsWith('M 0 -')).toBe(true);
+  });
+
+  it('skips a relation when fewer than 2 members have positions in the map', () => {
+    const svg = makeSvg();
+    const sparsePos = new Map([
+      ['vim-2012/1.9', { x: 0, y: 0 }],
+      ['vim-2012/1.17', { x: 100, y: 0 }],
+      /* 1.18 and 1.12 not in the map */
+    ]);
+    drawGenericPipes(svg, sparsePos, {
+      isDark: false,
+      color: '#b45309',
+      isMuted: false,
+      relations: [makeRelation()],
+      locale: 'eng',
+    });
+    /* Single-member layout is rejected (computePipeLayout requires ≥2),
+       so no pipe or thread segments should be drawn. */
+    expect(svg.querySelectorAll('line.pipe-seg').length).toBe(0);
+  });
+});

package/src/__tests__/sphere-math.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { hashSeed, expandParams, portSide, portPoint, idToUriGet, visibleNodeIds } from '../utils/sphere-math';
+import { hashSeed, expandParams, portSide, portPoint, idToUriGet, visibleNodeIds, computePipeLayout } from '../utils/sphere-math';
 import type { SphereHyperedgeLike } from '../utils/sphere-math';
 
 describe('sphere-math', () => {
@@ -185,4 +185,74 @@ describe('sphere-math', () => {
       expect([...visible].sort()).toEqual(['a', 'b', 'c', 'd', 'focus']);
     });
   });
+
+  describe('computePipeLayout', () => {
+    it('returns null for fewer than 2 members', () => {
+      expect(computePipeLayout({ x: 0, y: 0 }, [])).toBeNull();
+      expect(computePipeLayout({ x: 0, y: 0 }, [{ pos: { x: 1, y: 0 } }])).toBeNull();
+    });
+
+    it('places the middle node at the default 50% split between comp and centroid', () => {
+      const comp = { x: 0, y: 0 };
+      const members = [
+        { pos: { x: 10, y: 0 } },
+        { pos: { x: -10, y: 0 } },
+      ];
+      const layout = computePipeLayout(comp, members)!;
+      /* Centroid is (0,0); midpoint between (0,0) and (0,0) is (0,0) */
+      expect(layout.middleNode).toEqual({ x: 0, y: 0 });
+      expect(layout.pipeStart).toEqual(comp);
+      expect(layout.pipeEnd).toEqual(layout.middleNode);
+      expect(layout.threads).toHaveLength(2);
+    });
+
+    it('middle node tracks the member centroid', () => {
+      const comp = { x: 0, y: 0 };
+      const members = [
+        { pos: { x: 10, y: 0 } },
+        { pos: { x: 10, y: 10 } },
+        { pos: { x: 10, y: -10 } },
+      ];
+      const layout = computePipeLayout(comp, members)!;
+      /* Centroid is (10, 0); splitFraction=0.5 → middle at (5, 0) */
+      expect(layout.middleNode).toEqual({ x: 5, y: 0 });
+    });
+
+    it('respects a custom split fraction', () => {
+      const comp = { x: 0, y: 0 };
+      const members = [
+        { pos: { x: 10, y: 0 } },
+        { pos: { x: 10, y: 10 } },
+        { pos: { x: 10, y: -10 } },
+      ];
+      /* splitFraction=0.8 → middle near centroid: (8, 0) */
+      const layout = computePipeLayout(comp, members, 0.8)!;
+      expect(layout.middleNode).toEqual({ x: 8, y: 0 });
+    });
+
+    it('threads connect the middle node to each member', () => {
+      const comp = { x: 0, y: 0 };
+      const members = [
+        { pos: { x: 10, y: 0 } },
+        { pos: { x: -10, y: 0 } },
+      ];
+      const layout = computePipeLayout(comp, members)!;
+      const mid = layout.middleNode;
+      expect(layout.threads[0].start).toEqual(mid);
+      expect(layout.threads[0].end).toEqual(members[0].pos);
+      expect(layout.threads[1].start).toEqual(mid);
+      expect(layout.threads[1].end).toEqual(members[1].pos);
+    });
+
+    it('carries delimitingCharacteristic through to threads', () => {
+      const dc1 = { eng: 'multiple of a unit' };
+      const dc2 = { eng: 'submultiple of a unit' };
+      const layout = computePipeLayout({ x: 0, y: 0 }, [
+        { pos: { x: 10, y: 0 }, delimitingCharacteristic: dc1 },
+        { pos: { x: -10, y: 0 }, delimitingCharacteristic: dc2 },
+      ])!;
+      expect(layout.threads[0].member.delimitingCharacteristic).toBe(dc1);
+      expect(layout.threads[1].member.delimitingCharacteristic).toBe(dc2);
+    });
+  });
 });

package/src/components/RelationSphere.vue

@@ -28,6 +28,7 @@ const { t, locale } = useI18n();
 import type { Concept, Manifest, GraphEdge, PartitiveRelationWire, PartitiveMemberWire, GenericRelationWire } from '../adapters/types';
 import { rakeStrokeStyle } from '../utils/partitive-multiplicity';
 import { drawRakeBundles } from './relation-sphere/rake-bundles';
+import { drawGenericPipes } from './relation-sphere/pipe-bundles';
 import { ensureMarkers, ensureTypeMarker } from './relation-sphere/svg-markers';
 import {
   sphereConstraint,
@@ -584,7 +585,7 @@ function drawEdges(cx: number, cy: number) {
   /* Remove only path + text + rect (edges), keep defs (markers).
      Also remove <line> elements (rake-bundle segments) and <circle>
      (rake junction markers). */
-  svg.querySelectorAll('path:not(defs path), line.rake-seg, circle.rake-junction, text.edge-label, rect.edge-label-bg').forEach(el => el.remove());
+  svg.querySelectorAll('path:not(defs path), line.rake-seg, line.pipe-seg, circle.rake-junction, rect.pipe-junction, text.edge-label, text.pipe-label, rect.edge-label-bg, rect.pipe-label-bg').forEach(el => el.remove());
   if (!svg.querySelector('defs')) ensureMarkers(svg);
 
   /* Compute visible node positions */
@@ -706,28 +707,17 @@ function drawEdges(cx: number, cy: number) {
     relations: props.partitiveRelations ?? [],
   });
 
-  /* Generic relations render as rake bundles in a distinct hue (amber).
-     Member shape differs (delimitingCharacteristic instead of isDelimiting),
-     so normalize to the partitive-shaped input the renderer expects. */
-  const genericNormalized: PartitiveRelationWire[] = (props.genericRelations ?? []).map(rel => ({
-    source: rel.source,
-    comprehensive: rel.comprehensive,
-    completeness: rel.completeness,
-    register: rel.register,
-    partitives: rel.members.map(m => ({
-      uri: m.uri,
-      presence: m.presence,
-      count: m.count,
-      /* Every generic member is delimiting by definition (each carries
-         its own delimiting characteristic per ISO 704 §5.5.4.2.1). */
-      isDelimiting: true,
-    })),
-  }));
-  drawRakeBundles(svg, pos, {
+  /* Generic relations render as tree-branch pipe-and-thread bundles
+     (NOT rakes): thick parent pipe from comprehensive to a middle
+     node, then thin direct threads from there to each member. The
+     per-member delimiting characteristic (ISO 704 §5.5.4.2.1) is
+     labeled along each thread; the group criterion at the middle. */
+  drawGenericPipes(svg, pos, {
     isDark: uiStore.isDark,
     color: uiStore.isDark ? '#fbbf24' : '#b45309',
     isMuted: mutedTypes.value.has('__generic__'),
-    relations: genericNormalized,
+    relations: props.genericRelations ?? [],
+    locale: locale.value,
   });
 }
 

package/src/components/relation-sphere/pipe-bundles.ts

@@ -0,0 +1,218 @@
+/**
+ * Pipe-and-thread rendering for GenericRelation hyperedges.
+ *
+ * Visual contract (ISO 704:2022 §5.5.4 generic relations, "tree branch"):
+ *
+ *     comprehensive ─── thick pipe ───▶ ◼ middle node
+ *                                       ├─ thin thread ──▶ member 1
+ *                                       ├─ thin thread ──▶ member 2
+ *                                       └─ thin thread ──▶ member N
+ *
+ * Distinct from the partitive rake (drawRakeBundles) in three ways:
+ *
+ *   1. No right-angle fork. The pipe is a single straight line from
+ *      comprehensive to a middle node; threads radiate from there to
+ *      each member. No perpendicular spine, no teeth.
+ *
+ *   2. Thick → thin hierarchy. The parent pipe uses PIPE_WIDTH; child
+ *      threads use THREAD_WIDTH. The parent visually dominates, like a
+ *      tree trunk vs its twigs. (The previous generic rendering reused
+ *      the rake code with isDelimiting=true on all members, which made
+ *      the children THICKER than the parent — backwards.)
+ *
+ *   3. Characteristic label — the criterion is a single hyperedge-level
+ *      field shared by all members (the dimension along which they
+ *      differ), rendered once on the pipe body. Optional: when the
+ *      criterion is absent, no label is shown at all. Per-member
+ *      delimitingCharacteristic is NOT labeled here — those values
+ *      distinguish each member but are not "the characteristic of
+ *      the hyperedge".
+ *
+ * Pure DOM/geometry — no Vue reactivity, no d3 state. The caller passes
+ * the generic relations, position map, and rendering context.
+ */
+import type { GenericRelationWire } from '../../adapters/types';
+import { computePipeLayout, type PipeLayoutMember } from '../../utils/sphere-math';
+import { UriRouter } from '../../adapters/UriRouter';
+
+const PIPE_WIDTH = 3.2;
+const THREAD_WIDTH = 1.0;
+const JUNCTION_RADIUS = 4;
+const DIAMOND_HALF = 5;
+
+export interface PipeBundleOptions {
+  /** Light/dark mode controls the contrast stroke around markers. */
+  isDark: boolean;
+  /** Relation color (light or dark variant of the generic amber). */
+  color: string;
+  /** Skip every bundle when the user mutes generic relations. */
+  isMuted: boolean;
+  /** Relations to draw. */
+  relations: readonly GenericRelationWire[];
+  /** UI locale, used to pick the delimiting-characteristic text. */
+  locale: string;
+}
+
+interface NodePos { x: number; y: number }
+
+/**
+ * Draw every pipe-and-thread bundle for the current concept's generic
+ * relations.
+ *
+ * Each relation produces: 1 thick pipe (comp → middle), N thin threads
+ * (middle → each member), 1 junction square at the middle node, 1
+ * diamond at the comp end, and — only when the hyperedge has a
+ * criterion — 1 characteristic label on the pipe body.
+ */
+export function drawGenericPipes(
+  svg: SVGSVGElement,
+  pos: Map<string, NodePos>,
+  opts: PipeBundleOptions,
+): void {
+  if (opts.isMuted) return;
+  const contrastStroke = opts.isDark ? '#1a1208' : '#ffffff';
+
+  for (const rel of opts.relations) {
+    const compParsed = UriRouter.parseUri(rel.comprehensive);
+    if (!compParsed) continue;
+    const compNodeId = `${compParsed.registerId}/${compParsed.conceptId}`;
+    const compPos = pos.get(compNodeId);
+    if (!compPos) continue;
+
+    const memberPositions: PipeLayoutMember[] = [];
+    for (const m of rel.members) {
+      const parsed = UriRouter.parseUri(m.uri);
+      if (!parsed) continue;
+      const nid = `${parsed.registerId}/${parsed.conceptId}`;
+      const p = pos.get(nid);
+      if (!p) continue;
+      memberPositions.push({ pos: p, delimitingCharacteristic: m.delimitingCharacteristic });
+    }
+
+    const layout = computePipeLayout(compPos, memberPositions);
+    if (!layout) continue;
+
+    /* 1. Thick parent pipe: comp → middle node. The characteristic
+          label (criterion) sits on the pipe body — see step 4. */
+    drawSegment(svg, opts.color, layout.pipeStart, layout.pipeEnd, PIPE_WIDTH);
+
+    /* 2. Thin threads: middle → each member. No per-thread labels —
+          the characteristic is a single hyperedge-level field shared
+          by all members, rendered once on the pipe body. */
+    for (const thread of layout.threads) {
+      drawSegment(svg, opts.color, thread.start, thread.end, THREAD_WIDTH);
+    }
+
+    /* 3. Square junction at the middle node (distinct from the rake's
+          circular junction — gives a visual cue: square = generic,
+          circle = partitive). */
+    drawSquare(svg, layout.middleNode.x, layout.middleNode.y, JUNCTION_RADIUS, opts.color, contrastStroke);
+
+    /* 4. Characteristic label — single, hyperedge-level, optional.
+          Drawn on the pipe body (midpoint between comp and middle node).
+          When criterion is absent, no label is rendered at all. */
+    const critText = pickLocalized(rel.criterion, opts.locale);
+    if (critText) {
+      const midX = (layout.pipeStart.x + layout.pipeEnd.x) / 2;
+      const midY = (layout.pipeStart.y + layout.pipeEnd.y) / 2;
+      drawLabel(svg, midX, midY, critText, opts.color, {
+        fontSize: 9.5,
+        weight: '600',
+        bg: true,
+        isDark: opts.isDark,
+      });
+    }
+
+    /* 5. Diamond at the comprehensive end (origin marker shared with
+          the rake — both are hyperedges emanating from one concept). */
+    drawDiamond(svg, compPos.x, compPos.y, DIAMOND_HALF, opts.color, contrastStroke);
+  }
+}
+
+function drawSegment(svg: SVGSVGElement, color: string, from: NodePos, to: NodePos, width: number): void {
+  const line = document.createElementNS('http://www.w3.org/2000/svg', 'line');
+  line.setAttribute('class', 'pipe-seg');
+  line.setAttribute('x1', String(from.x));
+  line.setAttribute('y1', String(from.y));
+  line.setAttribute('x2', String(to.x));
+  line.setAttribute('y2', String(to.y));
+  line.setAttribute('stroke', color);
+  line.setAttribute('stroke-width', String(width));
+  line.setAttribute('stroke-linecap', 'round');
+  line.setAttribute('opacity', '0.9');
+  svg.appendChild(line);
+}
+
+function drawSquare(svg: SVGSVGElement, cx: number, cy: number, half: number, fill: string, stroke: string): void {
+  const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+  rect.setAttribute('class', 'pipe-junction');
+  rect.setAttribute('x', String(cx - half));
+  rect.setAttribute('y', String(cy - half));
+  rect.setAttribute('width', String(half * 2));
+  rect.setAttribute('height', String(half * 2));
+  rect.setAttribute('fill', fill);
+  rect.setAttribute('opacity', '0.9');
+  rect.setAttribute('stroke', stroke);
+  rect.setAttribute('stroke-width', '1');
+  svg.appendChild(rect);
+}
+
+function drawDiamond(svg: SVGSVGElement, cx: number, cy: number, half: number, fill: string, stroke: string): void {
+  const d = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+  d.setAttribute('d',
+    `M ${cx} ${cy - half} L ${cx + half} ${cy} L ${cx} ${cy + half} L ${cx - half} ${cy} Z`);
+  d.setAttribute('fill', fill);
+  d.setAttribute('opacity', '0.9');
+  d.setAttribute('stroke', stroke);
+  d.setAttribute('stroke-width', '1');
+  svg.appendChild(d);
+}
+
+interface LabelOpts {
+  fontSize?: number;
+  weight?: string;
+  italic?: boolean;
+  bg?: boolean;
+  isDark?: boolean;
+}
+
+function drawLabel(
+  svg: SVGSVGElement,
+  x: number,
+  y: number,
+  text: string,
+  color: string,
+  opts: LabelOpts,
+): void {
+  const fontSize = opts.fontSize ?? 9;
+  const w = text.length * (fontSize * 0.55) + 8;
+  if (opts.bg) {
+    const bg = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+    bg.setAttribute('class', 'pipe-label-bg');
+    bg.setAttribute('x', String(x - w / 2));
+    bg.setAttribute('y', String(y - fontSize));
+    bg.setAttribute('width', String(w));
+    bg.setAttribute('height', String(fontSize + 4));
+    bg.setAttribute('fill', opts.isDark ? '#1c1e32' : '#ffffff');
+    bg.setAttribute('opacity', '0.88');
+    bg.setAttribute('rx', '2');
+    svg.appendChild(bg);
+  }
+  const label = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+  label.setAttribute('class', 'pipe-label');
+  label.setAttribute('x', String(x));
+  label.setAttribute('y', String(y + 1));
+  label.setAttribute('text-anchor', 'middle');
+  label.setAttribute('fill', color);
+  label.setAttribute('font-size', String(fontSize));
+  label.setAttribute('font-family', 'JetBrains Mono, monospace');
+  if (opts.weight) label.setAttribute('font-weight', opts.weight);
+  if (opts.italic) label.setAttribute('font-style', 'italic');
+  label.textContent = text;
+  svg.appendChild(label);
+}
+
+function pickLocalized(ls: Record<string, string> | undefined, locale: string): string | undefined {
+  if (!ls) return undefined;
+  return ls[locale] ?? ls.eng ?? ls.default ?? Object.values(ls)[0];
+}

package/src/utils/sphere-math.ts

@@ -74,6 +74,65 @@ export interface SphereHyperedgeLike {
   muteKey?: string;
 }
 
+/**
+ * Layout for the generic-relation "pipe-and-thread" bundle.
+ *
+ * Visual contract (ISO 704 generic relations):
+ *   parent ── thick pipe ──▶ middle node
+ *                              ├── thin thread ──▶ child 1
+ *                              ├── thin thread ──▶ child 2
+ *                              └── thin thread ──▶ child N
+ *
+ * Unlike the partitive rake (right-angle fork notation), this is a
+ * direct tree-branch: straight pipe from comprehensive to a middle
+ * node, then straight threads radiating to each member. The middle
+ * node sits at `splitFraction` along the line from comprehensive to
+ * the member centroid.
+ *
+ * Thick/thin hierarchy: the caller draws `pipeStart → pipeEnd` with a
+ * thick stroke and each thread with a thin stroke — the parent is
+ * visually heavier than the children, matching the tree-branch
+ * metaphor (trunk thicker than twigs).
+ */
+export interface PipeLayoutMember {
+  pos: { x: number; y: number };
+  /** Per-member delimiting characteristic (carried through so the
+   * renderer can label each thread without re-resolving the member). */
+  delimitingCharacteristic?: Record<string, string>;
+}
+
+export interface PipeLayout {
+  middleNode: { x: number; y: number };
+  pipeStart: { x: number; y: number };
+  pipeEnd: { x: number; y: number };
+  threads: Array<{
+    start: { x: number; y: number };
+    end: { x: number; y: number };
+    member: PipeLayoutMember;
+  }>;
+}
+
+export function computePipeLayout(
+  compPos: { x: number; y: number },
+  members: readonly PipeLayoutMember[],
+  splitFraction = 0.5,
+): PipeLayout | null {
+  if (members.length < 2) return null;
+  const sumX = members.reduce((s, m) => s + m.pos.x, 0);
+  const sumY = members.reduce((s, m) => s + m.pos.y, 0);
+  const cx = sumX / members.length;
+  const cy = sumY / members.length;
+  const midX = compPos.x + (cx - compPos.x) * splitFraction;
+  const midY = compPos.y + (cy - compPos.y) * splitFraction;
+  const middleNode = { x: midX, y: midY };
+  return {
+    middleNode,
+    pipeStart: compPos,
+    pipeEnd: middleNode,
+    threads: members.map(m => ({ start: middleNode, end: m.pos, member: m })),
+  };
+}
+
 /**
  * IDs of nodes that should render given the current mute state.
  *