}

  }

}

/* ── Graph surface (SCV swarm) ────────────────────────────────────────────── */

/* Unit's visual language, expressed in the sanctioned palette. Status is

 * carried by ring STYLE as well as hue -- hairline, heavy, dashed, doubled --

 * so the taxonomy survives a colour-blind reader and a greyscale screenshot.

 * See docs/2026-08-20-scv-swarm-visualization-unit-audit.md. */

@layer components {

  .graph-surface {

    width: 100%;

    height: auto;

    overflow: visible;

    font-family: var(--font-sans);

  }

  .graph-node__body {

    fill: var(--ink-raised);

    stroke: var(--line-strong);

    stroke-width: 1;

    transition:

      fill var(--motion-fast) var(--ease),

      stroke var(--motion-fast) var(--ease),

      stroke-width var(--motion-fast) var(--ease);

  }

  .graph-node__label {

    fill: var(--text-muted);

    font-size: 9px;

    text-anchor: middle;

    pointer-events: none;

  }

  .graph-node[data-shape="circle"] {

    cursor: pointer;

  }

  /* SCV lifecycle. */

  .graph-node[data-status="idle"] .graph-node__body {

    stroke: var(--line);

  }

  .graph-node[data-status="running"] .graph-node__body {

    stroke: var(--accent);

    stroke-width: 2;

    fill: color-mix(in oklab, var(--accent) 12%, var(--ink-raised));

  }

  .graph-node[data-status="paused"] .graph-node__body {

    stroke: var(--warning);

    stroke-dasharray: 3 3;

  }

  .graph-node[data-status="circuit_open"] .graph-node__body {

    stroke: var(--danger);

    stroke-width: 2;

    fill: color-mix(in oklab, var(--danger) 10%, var(--ink-raised));

  }

  .graph-node[data-status="disabled"] .graph-node__body {

    stroke: var(--line-faint);

    fill: transparent;

  }

  .graph-node[data-status="disabled"] .graph-node__label {

    fill: var(--text-dim);

  }

  /* Work-item lifecycle, on rect nodes. */

  .graph-node[data-status="discovered"] .graph-node__body {

    stroke: var(--line-soft);

    stroke-dasharray: 2 2;

    fill: transparent;

  }

  .graph-node[data-status="admitted"] .graph-node__body {

    stroke: var(--line-strong);

  }

  .graph-node[data-status="completed"] .graph-node__body {

    stroke: var(--success);

    fill: color-mix(in oklab, var(--success) 12%, var(--ink-raised));

  }

  .graph-node[data-status="deferred"] .graph-node__body {

    stroke: var(--text-dim);

    stroke-dasharray: 4 2;

  }

  .graph-node[data-status="refused"] .graph-node__body {

    stroke: var(--warning);

  }

  .graph-node[data-status="failed"] .graph-node__body {

    stroke: var(--danger);

  }

  .graph-node--selected .graph-node__body {

    stroke: var(--text-primary);

    stroke-width: 2;

  }

  /* Links. Three coincident paths: hit area, visible stroke, text anchor. */

  .graph-link__hit {

    stroke: transparent;

    stroke-width: 12;

    fill: none;

    cursor: pointer;

  }

  .graph-link__base {

    stroke: var(--line-strong);

    stroke-width: 1;

    fill: none;

  }

  .graph-link__text-path {

    fill: none;

    stroke: none;

  }

  .graph-link__label {

    fill: var(--text-dim);

    font-size: 8px;

    text-anchor: middle;

  }

  .graph-link[data-kind="error"] .graph-link__base {

    stroke: var(--danger);

  }

  .graph-link[data-kind="data"] .graph-link__base {

    stroke: var(--line);

    stroke-dasharray: 2 2;

  }

  .graph-link[data-kind="type"] .graph-link__base {

    stroke: var(--line-soft);

  }

  .graph-link[data-kind="exposed"] .graph-link__base {

    stroke: var(--accent-bright);

  }

  .graph-link--active .graph-link__base {

    stroke: var(--accent);

  }

  .graph-link__pulse {

    fill: var(--accent);

  }

  .graph-arrow {

    fill: none;

    stroke: var(--line-strong);

    stroke-width: 1.5;

  }

  /* A step pulse is motion, and motion is the one channel that should mean

     something on this surface. Honour the reader's preference to stop it. */

  @media (prefers-reduced-motion: reduce) {

    .graph-link__pulse {

      display: none;

    }

  }

}

# SCV swarm visualization: porting Unit's visual language to Elixir

Date: 2026-08-20

Status: Proposed — audit and design, no implementation

Subject: how to render a live swarm of SCVs (15+ concurrently) in the visual

language of [Unit](https://github.com/samuelmtimbo/unit), implemented natively

in Elixir, Phoenix, HEEx, and LiveView rather than ported as TypeScript.

Reference read: `github.com/samuelmtimbo/unit` at revision `ea1b4d7e`, MIT

licensed (UNIT IO, Inc, 2021). 1,639 TypeScript files. Every line reference

below is to that revision; paths are repository-relative.

---

## 0. The claim

Unit's visual language is a good fit for the SCV swarm, and the reason is

structural rather than aesthetic.

Unit renders **MIMO finite state machines connected by typed links**. Its

README states that formally: "units are Multi Input Multi Output (MIMO) Finite

State Machines (FSM). A program in Unit is represented as a Graph."

An SCV is exactly that shape. `docs/scv-planning.md` defines an SCV as a durable

FSM with five states (`disabled`, `idle`, `running`, `paused`, `circuit_open`),

typed inputs (`scv_work_items`, themselves a state machine across `discovered`

→ `admitted` → `running` → `completed`/`deferred`/`refused`/`failed`), and typed

outputs (candidates handed to the Forge deployment pipeline). `scv_steps` is

specified to "store every provider and tool boundary in order" — an ordered

dataflow trace.

So a swarm view is not a metaphor laid over unrelated data. It is a faithful

rendering of the data model the SCV plan already specifies. That is the

difference between a visualization that stays true as the system evolves and a

dashboard that drifts into decoration.

**What we should take is the vocabulary, not the codebase.** §3 argues we

should deliberately *not* port Unit's force simulation, which is its single

largest visual subsystem.

## 1. Unit's visual language, distilled

Extracted from the source rather than the docs. The whole language is small,

which is what makes it portable.

### 1.1 Node shape carries type

`Editor/Component.ts:7468`:

```ts

borderRadius: is_component ? '0' : '50%'

```

**Units are circles. Components are squares.** One property, and the graph

becomes readable at a glance — you can see which nodes are live processes and

which are composed surfaces without reading a label. The `Shape` type is

exactly two values (`client/util/geometry/index.ts:575`):

```ts

export type Shape = 'circle' | 'rect'

```

### 1.2 Links attach to surfaces, not centers

This is the detail that makes Unit graphs look designed rather than generated.

A link is a straight segment between two points computed on the node

*boundaries* (`Editor/Component.ts:14188`):

```ts

const { x: x0, y: y0 } = pointInNode(source, u, padding_source)

const { x: x1, y: y1 } = pointInNode(target, nu, padding_target)

const path_d = `M ${x0} ${y0} L ${x1} ${y1}`

```

Naive graph renderers draw center-to-center and hide the overlap behind opaque

nodes. Unit computes the surface intersection, so link length encodes real

separation and the arrowhead sits flush against the node.

The geometry module supplies the primitives: `pointInNode`, `surfaceDistance`,

`centerToSurfaceDistance`, `unitVector`, `describeArc`, `describeCircle`,

`describeRect`, `describeArrowPolygon`, `catmullRomSpline`.

### 1.3 Arrowheads conform to the surface they touch

`Editor/Component.ts:856`:

```ts

export const describeArrowShape = (shape: Shape, r: number): string => {

  if (shape === 'circle') return describeArrowSemicircle(r)

  else return ARROW_FLAT

}

```

A link into a circle terminates in an arc that hugs the circumference; a link

into a rect terminates in a flat bar. The marker alphabet is four strings

(`Editor/Component.ts:925`):

```ts

export const ARROW_NONE   = ''

export const ARROW_MEMORY = 'M-6,4 L0,1 L-6,-2'

export const ARROW_NORMAL = 'M-0.25,2.25 L2,1 L-0.25,-0.25'

export const ARROW_FLAT   = 'M0,8 L0,-5.5'

```

Four path strings and one conditional carry the entire edge-termination

vocabulary. That is the level of economy worth copying.

### 1.4 Link labels ride the link

`Editor/Component.ts:14194` sets the same `d` on three overlaid paths: the

visible stroke, a wider invisible `link_base_area` for hit-testing, and

`link_base_text` used as a `textPath` anchor. When a link runs right-to-left the

component swaps in the inverted path so the label never renders upside down, and

flips the markers with `transform: scaleX(-1)`.

Three paths per link, one geometry calculation. The hit area being a separate

wider path is why Unit graphs are pleasant to click at any zoom.

### 1.5 Distance is typed

`src/constant/LINK_DISTANCE.ts` — link length is a semantic property, not a

layout constant:

```ts

export const LINK_DISTANCE          = 24

export const LINK_DISTANCE_TYPE     = LINK_DISTANCE / 2      // 12

export const LINK_DISTANCE_DATA     = LINK_DISTANCE / 2      // 12

export const LINK_DISTANCE_ERR      = LINK_DISTANCE * 7 / 8  // 21

export const LINK_DISTANCE_EXPOSED  = LINK_DISTANCE * 2 / 3  // 16

```

Type relationships sit closer than dataflow; errors sit closer than normal

links. Proximity encodes kind.

### 1.6 Layers, not z-index soup

Ten named layers (`Editor/Component.ts`): `LAYER_NORMAL`, `LAYER_COLLAPSE`,

`LAYER_SEARCH`, `LAYER_IGNORED`, `LAYER_EXPOSED`, `LAYER_DATA_LINKED`,

`LAYER_DATA`, `LAYER_ERR`, `LAYER_TYPE`, with

`LAYER_OPACITY_MULTIPLIER = 0.1`. Depth is a small enum and opacity is derived

from it, so nothing competes for arbitrary stacking values.

### 1.7 The palette is greyscale-first

`client/theme.ts` is a twelve-rung greyscale ramp (`COLOR_GRAYSCALE_BASE00`

`#FCFCFC` through `BASE11` `#080808`) plus a handful of named accents, each with

a paired darker "link" variant:

```ts

COLOR_RED   = '#ff6666'   COLOR_LINK_RED   = '#ff4d4d'

COLOR_GREEN = '#00aa11'   COLOR_LINK_GREEN = '#0b8e14'

COLOR_BLUE  = '#0066ff'   COLOR_LINK_BLUE  = '#1d62c9'

```

**This is directly compatible with the palette this repo just adopted.**

`assets/css/app.css` now carries Linear's neutral ramp (`#08090a` → `#f7f8f8`)

with a single indigo accent. Unit's structure — a long neutral ramp plus sparse

semantic accents, with links a shade darker than fills — maps onto our existing

tokens without introducing a third palette, which `UI-003` forbids

(`INVARIANTS.md:1520`: "not introduce a third palette").

The port should use `--ink-*`, `--text-*`, `--line-*`, `--wash-*` and the

existing `--success` / `--warning` / `--danger` / `--accent`, never Unit's hex

literals.

## 2. Mapping SCV state onto the language

| SCV concept | Visual |

| --- | --- |

| One SCV | Circle node. It is a live FSM, so it takes the circle. |

| Work item | Rect node. Composed, inert data, not a running process. |

| Candidate / Forge handoff | Rect node terminating the chain. |

| SCV status | Ring treatment: `idle` hairline, `running` accent ring, `paused` dashed, `circuit_open` danger ring, `disabled` faint. |

| Run phase | Node fill wash, stepped through `--wash-hover` → `--wash-selected`. |

| `scv_steps` | Pulse travelling along the outbound link, one per boundary. |

| Tool call vs provider call | Link kind, hence link distance (§1.5) and marker (§1.3). |

| Error / `error_event_count` | `LAYER_ERR` equivalent: danger stroke, shorter link distance so failures visibly cluster. |

| Token / cost / CPU usage | Node radius, bounded. Cheap runs stay small; expensive ones are visibly large. |

| Repository scope | Spatial grouping — one cluster per repository. |

The 15-agent view the request asks for is then: fifteen circles, each with a

short outbound chain to its current work item and candidate, sized by spend,

ringed by status, pulsing on each step. Clicking a circle drills into that

SCV's run.

## 3. Do not port the force simulation

`client/simulation.ts` is 355 self-contained lines implementing a Runge-Kutta

integrated force layout (RK1 through RK4, selectable via a `stability` option),

with no d3 dependency. It is genuinely nice code and it would port to Elixir

cleanly.

**We should still not use it, and this is the main design opinion in this

document.**

Unit needs a force simulation because its graphs are user-authored and

arbitrary: an author drops units anywhere and the simulation finds a readable

arrangement. Our graph is not arbitrary. The SCV pipeline has a known shape —

work item → SCV → run → candidate → Forge — which is a staged DAG with a fixed

number of stages.

For a known DAG, a force simulation is strictly worse:

- **It moves when nothing meaningful changed.** An operator watching 15 agents

  needs to notice *state* changes. A layout that drifts on every tick trains

  them to ignore motion, which is the one channel that should mean something.

- **Position stops being an identifier.** With a stable layout, "the third one

  down is stuck again" is a real observation. With a simulation, node identity

  has to be re-read from labels every time.

- **It costs continuously.** A simulation must tick to converge. A staged layout

  is computed once per topology change.

Use a deterministic staged layout: column per pipeline stage, stable vertical

ordering within a column (by SCV id, never by a mutable field like score, or

rows will swap under the operator's cursor). Keep Unit's *geometry* — surface

anchoring, conforming arrowheads, typed distances — which is what actually makes

it look like Unit.

Keep the simulation in mind for one later case: a free "swarm" view where

clustering by repository or failure mode is the point and exact position is not.

If we build that, port `simulation.ts` then, with measurements.

## 4. Elixir and Phoenix implementation

### 4.1 Render SVG server-side in HEEx

The geometry is arithmetic. Elixir does arithmetic. There is no reason for a

client-side graph library.

```elixir

defmodule OpenAgentsWeb.UI.Graph do

  @moduledoc """

  SVG graph primitives in Unit's visual language: circular unit nodes,

  rectangular data nodes, and links anchored to node surfaces with

  shape-conforming terminations.

  Ported from Unit (https://github.com/samuelmtimbo/unit), MIT licensed,

  UNIT IO Inc. Geometry reimplemented in Elixir; no Unit code is vendored.

  """

  @pin_radius 5

  @link_distance 24

  @doc "The point where a link meets a node's surface, per Unit's pointInNode."

  def surface_point(%{shape: :circle, x: x, y: y, r: r}, {ux, uy}, padding) do

    {x + ux * (r + padding), y + uy * (r + padding)}

  end

  def surface_point(%{shape: :rect} = node, {ux, uy}, padding) do

    # rect surface intersection along the unit vector

  end

  def unit_vector({x0, y0}, {x1, y1}) do

    dx = x1 - x0

    dy = y1 - y0

    case :math.sqrt(dx * dx + dy * dy) do

      0.0 -> {0.0, 0.0}

      d -> {dx / d, dy / d}

    end

  end

end

```

Nodes and links become function components rendering `<circle>`, `<rect>`,

`<path>`. State changes are ordinary LiveView assigns; Phoenix sends attribute

diffs, and CSS transitions animate them. For fifteen nodes this is far less data

over the wire than a JS graph library's state sync.

### 4.2 Animate in CSS, not in a render loop

Ring colour, fill wash, and radius are attributes. Give them a transition in the

style pack and every state change animates for free. Step pulses are a

`<circle>` on a `<path>` with SMIL `<animateMotion>`, or a CSS

`offset-path` animation — no JS, no timer.

This matters for a 15-agent view: a render loop for 15 animated nodes is a

render loop you pay for even when nothing is happening. Declarative animation

costs nothing while idle.

### 4.3 Reach for a colocated hook only for pan and zoom

Pan and zoom are pointer-rate interactions and must not round-trip. That is a

small colocated hook mutating one `viewBox` attribute — the pattern already used

in `chat_live.ex` (`phx-hook=".SidebarShell"`, `phx-hook=".TranscriptScroll"`).

Unit's `ZOOM_INTENSITY = 0.05` is a good starting constant.

Everything else — selection, drill-down, filtering — is a LiveView event.

### 4.4 The invariant constraints this must satisfy

- **`UI-003`** (`INVARIANTS.md:1499`): product surfaces render only through the

  sanctioned component library, with no third palette. So graph primitives go in

  the governed component module (`OpenAgentsWeb.UI` in

  `lib/openagents_web/components/ui.ex`, or a `UI.Graph` submodule beside it), styled from existing tokens.

- **The component catalog is enforced by test.** `ComponentCatalogTest` walks

  `__components__/0` for every documented module and fails when a public

  function component has no catalog entry. Every new graph primitive needs a

  `ComponentCatalog` entry and a `component_demo/1` clause, or the suite fails.

  That is a feature — the catalog stays honest — but it is work to budget.

- **No hosted CI** (`RELEASE-004`). Tests run on owned infrastructure.

- **Basecoat components are imported individually**; never

  `basecoat.css`/`basecoat-base.css`/`basecoat-components.css`.

### 4.5 Licensing

Unit is MIT (UNIT IO, Inc, 2021), which is compatible with this repo's AGPL-3.0.

The workspace contract says reference repos are read-only and "do not vendor or

copy large chunks of external code into our repos by default."

So: **reimplement the geometry in Elixir, attribute Unit in the module docs, do

not vendor TypeScript.** The values worth carrying verbatim are constants

(`PIN_RADIUS = 5`, `LINK_DISTANCE = 24` and its typed variants,

`ZOOM_INTENSITY = 0.05`) and the four arrow path strings, all of which are facts

about a visual language rather than substantial code.

## 5. What exists today

Honest current state, verified at `d247a8a`:

**The SCV runtime exists in embryo — 647 lines total:**

| module | lines |

| --- | --- |

| `lib/openagents/scv/worker.ex` | 213 |

| `lib/openagents/scv/open_code_events.ex` | 164 |

| `lib/openagents/scv/run.ex` | 146 |

| `lib/openagents/scv/environment.ex` | 42 |

| `lib/openagents/scv/resource_sampler.ex` | 33 |

| `lib/openagents/scv.ex` | 21 |

| `lib/openagents/scv/driver.ex`, `runner.ex` | 28 |

**There is no SCV web surface at all.** Nothing under `lib/openagents_web/`

references SCV. This proposal is the first.

**The durable tables are specified but unbuilt.** `docs/scv-planning.md`

specifies `scvs`, `scv_work_items`, `scv_runs`, `scv_steps`, and

`scv_worker_images`. None exist as migrations. `SCV.Run` is a plain struct, not

an Ecto schema.

**So bind to what is real today**, and widen later:

- `OpenAgents.SCV.OpenCodeEvents.summary/1` already returns `event_count`,

  `event_types`, `tool_calls`, `tool_outcomes`, `usage`, `error_event_count`,

  and `session_ids`. That is enough to drive node fill, radius, error state, and

  a step counter for a single run **now**.

- `OpenAgents.SCV.ResourceSampler.sample/1` supplies resource figures for radius.

- A multi-SCV view needs the `scvs` and `scv_runs` tables. Until they exist,

  a swarm view can only show runs the node itself is supervising — real, but not

  the fleet-wide picture the 15-agent view implies.

This ordering matters. Building the visualization against the planned schema

before the schema exists would produce a component that renders fixtures and

nothing else.

## 6. Suggested sequence

1. **`UI.Graph` geometry module + tests.** Pure functions: `unit_vector/2`,

   `surface_point/3` for circle and rect, `arrow_path/2`, `describe_arc/5`.

   Property-tested — a link must terminate on the boundary for every angle, and

   that is exactly the kind of thing property tests are good at.

2. **Static node and link components**, catalogued per §4.4, demoed with

   fixtures.

3. **Single-run view** bound to `OpenCodeEvents.summary/1` and

   `ResourceSampler.sample/1` — real data, one SCV, no new schema required.

4. **`scvs` / `scv_runs` schema** per the SCV plan, whenever that work is

   scheduled on its own merits.

5. **Swarm view** over that schema: N circles, staged layout, status rings.

6. **Pan/zoom hook**, only once the static view is worth navigating.

7. **Drill-down**: click an SCV → its run → its steps.

Steps 1–3 deliver something real without depending on unbuilt schema. Step 5 is

the deliverable the request describes, and it is gated on step 4, which is a

separate decision.

## 7. Risks and open questions

- **Fifteen is not the hard case; a hundred is.** A staged layout degrades

  gracefully to a scrollable column set; a force simulation degrades to a hairball.

  Another argument for §3, but the swarm view should still declare its bound.

- **Step pulses could become noise.** If every provider and tool boundary emits a

  visible pulse, a busy SCV is a strobe. Rate-limit at the projection, not in

  CSS — one pulse per N steps with a count, in the spirit of `LAYER_OPACITY_MULTIPLIER`.

- **`scv_steps` volume.** The plan says steps store "every provider and tool

  boundary in order." Fifteen concurrent SCVs will produce a high-rate stream. The

  swarm view must subscribe to a bounded projection, never the raw step table —

  the same rule `UI-002` already applies to tool activity.

- **Unit's language is monochrome-leaning by design.** It survives on shape,

  proximity, and opacity, using colour sparingly. That suits our palette but means

  status must be legible without colour — hence ring *style* (hairline, dashed,

  heavy) carrying status alongside hue, which also makes it colour-blind safe.

- **Naming.** Unit calls its nodes "units". We already use "unit" for other

  things and `SCV` is a fixed term per the SCV plan ("Use SCV consistently in

  code, documentation, configuration, and the interface. Do not introduce another

  name for this subsystem."). Call the primitives `graph_node` / `graph_link`,

  never `unit`.

        }

      ]

    },

    %{

      title: "SCV graph",

      items: [

        %{

          slug: "graph-node",

          title: "Graph node",

          icon: "circle",

          source: "OpenAgentsWeb.UI.Graph.graph_node/1",

          summary:

            "Circle for a live SCV, rect for inert data; ring style carries lifecycle state."

        },

        %{

          slug: "graph-link",

          title: "Graph link",

          icon: "compass",

          source: "OpenAgentsWeb.UI.Graph.graph_link/1",

          summary: "Surface-anchored link with a shape-conforming termination and a step pulse."

        },

        %{

          slug: "scv-swarm",

          title: "SCV swarm",

          icon: "grid",

          source: "OpenAgentsWeb.UI.Graph.scv_swarm/1",

          summary: "Many SCVs at once in a deterministic staged layout."

        }

      ]

    },

    %{

      title: "Forge",

      items: [

    %{

      OpenAgentsWeb.UI => [],

      OpenAgentsWeb.Layouts => [:app, :flash_group],

      # graph_defs/1 emits marker definitions into a parent graph surface; it

      # renders nothing on its own, so it has no demoable page. graph_surface/1

      # is the host element and is demoed through the components that use it.

      OpenAgentsWeb.UI.Graph => [:graph_defs, :graph_surface],

      OpenAgentsWeb.Components.RepoHeader => []

    }

  end

defmodule OpenAgentsWeb.UI.Graph do

  @moduledoc """

  SVG graph primitives for rendering live SCV work as a dataflow graph.

  The visual language is ported from [Unit](https://github.com/samuelmtimbo/unit)

  (MIT, UNIT IO Inc). The geometry is reimplemented in Elixir; no Unit code is

  vendored. The design rationale and the source citations for each rule live in

  `docs/2026-08-20-scv-swarm-visualization-unit-audit.md`.

  Four rules carry the whole language:

    1. **Shape carries kind.** A circle is a live finite state machine — an SCV.

       A rect is inert composed data — a work item, a candidate. You can read

       what a node *is* without reading its label.

    2. **Links meet surfaces, not centers.** A link terminates on the node

       boundary, so its drawn length is the real separation between two nodes

       rather than a segment hidden under an opaque fill.

    3. **Terminations conform to the surface they touch.** An arrow into a

       circle is an arc struck on that circle's circumference; an arrow into a

       rect is a flat bar.

    4. **Proximity encodes kind.** Link distance is a property of the link's

       type, not a global layout constant, so related things sit closer.

  Colour comes only from the sanctioned palette tokens (`UI-003`); no hex

  literal from Unit's theme appears here. Status is expressed by ring *style*

  as well as hue so the taxonomy stays legible without colour.

  """

  use Phoenix.Component

  # Unit's constants, carried verbatim as facts about the visual language.

  # src/constant/PIN_RADIUS.ts and src/constant/LINK_DISTANCE.ts.

  @pin_radius 5

  @link_distance 24

  @doc "Base link distance in user units. Typed variants derive from it."

  def link_distance, do: @link_distance

  @doc "Pin radius in user units."

  def pin_radius, do: @pin_radius

  @doc """

  Link distance for a link kind.

  Type and data relationships sit at half distance; errors sit slightly closer

  than a normal link so failures visibly cluster; exposed links sit at

  two-thirds. Same ratios as Unit's `LINK_DISTANCE.ts`.

  """

  def link_distance(:type), do: @link_distance / 2

  def link_distance(:data), do: @link_distance / 2

  def link_distance(:error), do: @link_distance * 7 / 8

  def link_distance(:exposed), do: @link_distance * 2 / 3

  def link_distance(_normal), do: @link_distance

  @doc """

  The unit vector from one point to another.

  Returns `{0.0, 0.0}` for coincident points rather than dividing by zero — two

  nodes at the same position have no meaningful direction between them.

  """

  def unit_vector({x0, y0}, {x1, y1}) do

    dx = x1 - x0

    dy = y1 - y0

    d = :math.sqrt(dx * dx + dy * dy)

    # `== 0` rather than a `0.0` pattern: it covers both signed zeros without

    # asserting which one sqrt produced.

    if d == 0, do: {0.0, 0.0}, else: {dx / d, dy / d}

  end

  @doc """

  The point where a link leaves a node's surface, travelling along `vector`.

  This is Unit's `pointInNode`. For a circle it is the centre pushed out by the

  radius; for a rect it is the intersection with whichever edge the vector

  actually crosses, found by scaling the vector to the nearer axis bound.

  """

  def surface_point(node, vector, padding \\ 0)

  def surface_point(%{shape: :circle, x: x, y: y, r: r}, {ux, uy}, padding) do

    {x + ux * (r + padding), y + uy * (r + padding)}

  end

  def surface_point(%{shape: :rect, x: x, y: y, width: w, height: h}, {ux, uy}, padding) do

    hw = w / 2 + padding

    hh = h / 2 + padding

    # Scale the unit vector until it first crosses a bound. The smaller ratio is

    # the edge it actually leaves through.

    tx = if ux == 0, do: :infinity, else: abs(hw / ux)

    ty = if uy == 0, do: :infinity, else: abs(hh / uy)

    t = min(tx, ty)

    case t do

      :infinity -> {x, y}

      t -> {x + ux * t, y + uy * t}

    end

  end

  @doc """

  An SVG arc path, used for circle-conforming arrow terminations.

  Angles are in degrees, measured as Unit measures them.

  """

  def describe_arc(cx, cy, r, start_angle, end_angle) do

    {sx, sy} = polar_to_cartesian(cx, cy, r, end_angle)

    {ex, ey} = polar_to_cartesian(cx, cy, r, start_angle)

    large_arc = if end_angle - start_angle <= 180, do: "0", else: "1"

    "M #{f(sx)} #{f(sy)} A #{f(r)} #{f(r)} 0 #{large_arc} 0 #{f(ex)} #{f(ey)}"

  end

  defp polar_to_cartesian(cx, cy, r, angle_degrees) do

    rad = (angle_degrees - 90) * :math.pi() / 180.0

    {cx + r * :math.cos(rad), cy + r * :math.sin(rad)}

  end

  defp f(n) when is_float(n), do: Float.round(n, 2)

  defp f(n), do: n

  @statuses ~w(idle running paused circuit_open disabled)a

  @item_statuses ~w(discovered admitted running completed deferred refused failed)a

  @link_kinds ~w(normal type data error exposed)a

  @doc "Every SCV status this component renders, in lifecycle order."

  def statuses, do: @statuses

  @doc "Every work-item status this component renders, in lifecycle order."

  def item_statuses, do: @item_statuses

  @doc "Every link kind this component renders."

  def link_kinds, do: @link_kinds

  @doc """

  One node in the graph.

  A `:circle` is a live SCV; a `:rect` is a work item or candidate. `status`

  drives the ring treatment and is validated against the SCV or work-item

  lifecycle depending on shape, so an impossible state cannot be rendered.

  """

  attr :id, :string, required: true

  attr :shape, :atom, values: [:circle, :rect], default: :circle

  attr :x, :float, required: true

  attr :y, :float, required: true

  attr :r, :float, default: 22.0, doc: "radius for a circle node"

  attr :width, :float, default: 44.0, doc: "width for a rect node"

  attr :height, :float, default: 32.0, doc: "height for a rect node"

  attr :status, :atom, default: :idle

  attr :label, :string, default: nil

  attr :selected, :boolean, default: false

  attr :class, :any, default: nil

  attr :rest, :global

  def graph_node(assigns) do

    ~H"""

    <g

      class={["graph-node", @selected && "graph-node--selected", @class]}

      data-status={@status}

      data-shape={@shape}

      role="img"

      aria-label={@label || @id}

      {@rest}

    >

      <circle :if={@shape == :circle} class="graph-node__body" cx={@x} cy={@y} r={@r} />

      <rect

        :if={@shape == :rect}

        class="graph-node__body"

        x={@x - @width / 2}

        y={@y - @height / 2}

        width={@width}

        height={@height}

        rx="2"

      />

      <text :if={@label} class="graph-node__label" x={@x} y={@y + label_offset(@shape, @r, @height)}>

        {@label}

      </text>

    </g>

    """

  end

  defp label_offset(:circle, r, _h), do: r + 12

  defp label_offset(:rect, _r, h), do: h / 2 + 12

  @doc """

  A link between two nodes, anchored to both surfaces.

  Renders three coincident paths, as Unit does: the visible stroke, a wider

  transparent hit area, and a text anchor. The hit area is why a one-pixel link

  is still clickable.

  """

  attr :id, :string, required: true

  attr :source, :map, required: true, doc: "node map with shape, x, y and r or width/height"

  attr :target, :map, required: true

  attr :kind, :atom, values: @link_kinds, default: :normal

  attr :active, :boolean, default: false, doc: "a step is currently traversing this link"

  attr :label, :string, default: nil

  attr :prefix, :string, default: "graph", doc: "marker namespace; must match graph_defs/1"

  attr :class, :any, default: nil

  def graph_link(assigns) do

    u = unit_vector({assigns.source.x, assigns.source.y}, {assigns.target.x, assigns.target.y})

    {nux, nuy} = u

    {x0, y0} = surface_point(assigns.source, u, 1)

    {x1, y1} = surface_point(assigns.target, {-nux, -nuy}, 1)

    assigns =

      assigns

      |> assign(:d, "M #{f(x0)} #{f(y0)} L #{f(x1)} #{f(y1)}")

      |> assign(:marker, "#{assigns.prefix}-#{marker_id(assigns.target)}")

    ~H"""

    <g class={["graph-link", @active && "graph-link--active", @class]} data-kind={@kind}>

      <path class="graph-link__hit" d={@d} />

      <path class="graph-link__base" d={@d} marker-end={"url(##{@marker})"} />

      <path :if={@label} id={"#{@id}-text"} class="graph-link__text-path" d={@d} />

      <text :if={@label} class="graph-link__label">

        <textPath href={"##{@id}-text"} startOffset="50%">{@label}</textPath>

      </text>

      <circle :if={@active} class="graph-link__pulse" r={pin_radius() / 2}>

        <animateMotion dur="1.1s" repeatCount="indefinite" path={@d} />

      </circle>

    </g>

    """

  end

  defp marker_id(%{shape: :circle}), do: "arrow-semicircle"

  defp marker_id(_rect), do: "arrow-flat"

  @doc """

  The marker and filter definitions every graph surface needs.

  SVG marker references resolve document-wide, not per `<svg>`, so one instance

  per page is normally enough. `prefix` exists so two independent graph surfaces

  on the same page can each own their markers rather than colliding — the

  failure mode a component with hardcoded ids always eventually hits.

  """

  attr :prefix, :string, default: "graph", doc: "marker namespace; must match graph_link/1"

  def graph_defs(assigns) do

    assigns = assign(assigns, :semicircle, describe_arc(6.0, 6.0, 5.0, 210, 330))

    ~H"""

    <defs>

      <marker

        id={"#{@prefix}-arrow-semicircle"}

        viewBox="0 0 12 12"

        refX="11"

        refY="6"

        markerWidth="7"

        markerHeight="7"

        orient="auto-start-reverse"

      >

        <path class="graph-arrow" d={@semicircle} />

      </marker>

      <marker

        id={"#{@prefix}-arrow-flat"}

        viewBox="0 0 12 12"

        refX="11"

        refY="6"

        markerWidth="7"

        markerHeight="7"

        orient="auto-start-reverse"

      >

        <path class="graph-arrow" d="M 11 1 L 11 11" />

      </marker>

    </defs>

    """

  end

  @doc """

  The host element for a graph.

  Callers should not hand-write the root element: it carries the marker

  definitions, the viewBox, and the accessible name, and getting any of those

  wrong is silent. `graph_surface/1` is also why no other module needs inline

  vector markup.

  """

  attr :id, :string, default: nil

  attr :view_box, :string, required: true

  attr :label, :string, required: true

  attr :prefix, :string, default: "graph"

  attr :class, :any, default: nil

  slot :inner_block, required: true

  def graph_surface(assigns) do

    ~H"""

    <svg

      id={@id}

      class={["graph-surface", @class]}

      viewBox={@view_box}

      role="img"

      aria-label={@label}

    >

      <.graph_defs prefix={@prefix} />

      {render_slot(@inner_block)}

    </svg>

    """

  end

  @doc """

  A swarm of SCVs in a deterministic staged layout.

  Position is stable and derived from the index, never from a mutable field

  like score — an operator watching fifteen agents needs "the third one down"

  to keep meaning the same agent. The audit argues at length for why this is a

  staged layout rather than Unit's force simulation.

  Each entry is a map with `:id`, `:status`, and optionally `:label`, `:weight`

  (0.0–1.0, scales the radius by spend) and `:item_status`.

  """

  attr :id, :string, default: "scv-swarm"

  attr :scvs, :list, required: true

  attr :columns, :integer, default: 5

  attr :selected_id, :string, default: nil

  attr :class, :any, default: nil

  def scv_swarm(assigns) do

    assigns = assign(assigns, :placed, place(assigns.scvs, assigns.columns))

    ~H"""

    <svg

      id={@id}

      class={["graph-surface", @class]}

      viewBox={"0 0 #{@columns * 96} #{ceil(length(@scvs) / @columns) * 96}"}

      role="group"

      aria-label={"#{length(@scvs)} SCVs"}

    >

      <.graph_defs />

      <.graph_link

        :for={p <- @placed}

        :if={p.item}

        id={"#{p.scv.id}-link"}

        source={p.node}

        target={p.item}

        kind={link_kind_for(p.scv)}

        active={p.scv.status == :running}

      />

      <.graph_node

        :for={p <- @placed}

        :if={p.item}

        id={"#{p.scv.id}-item"}

        shape={:rect}

        x={p.item.x}

        y={p.item.y}

        width={p.item.width}

        height={p.item.height}

        status={Map.get(p.scv, :item_status, :discovered)}

      />

      <.graph_node

        :for={p <- @placed}

        id={p.scv.id}

        shape={:circle}

        x={p.node.x}

        y={p.node.y}

        r={p.node.r}

        status={p.scv.status}

        label={Map.get(p.scv, :label)}

        selected={p.scv.id == @selected_id}

        phx-click="select_scv"

        phx-value-id={p.scv.id}

      />

    </svg>

    """

  end

  defp link_kind_for(%{status: :circuit_open}), do: :error

  defp link_kind_for(_), do: :normal

  # Deterministic placement: column-major grid, ordered by the caller's order.

  defp place(scvs, columns) do

    scvs

    |> Enum.with_index()

    |> Enum.map(fn {scv, i} ->

      cx = rem(i, columns) * 96 + 34.0

      cy = div(i, columns) * 96 + 34.0

      weight = Map.get(scv, :weight, 0.0)