components/system-map/system-map-data.ts

Functions

Imports

It imports no other module of this repo. Imported by components/system-map/system-map-circles.ts, components/system-map/system-map-html.ts, components/system-map/system-map-inside.ts, components/system-map/system-map.ts.

Source

1// The system map's data shape, its hexagonal layout and the arrow keys' neighbours (system-map.ts).
2
3// ---------------------------------------------------------------------------------------
4// Data. The shape of Capsid's public model (capsid/system/model.json through toPublic),
5// narrowed to what the map draws; a host maps its own data onto it.
6
7export type MapRing = "core" | "shared" | "used";
8
9export interface MapSystem {
10  id: string;
11  name: string;
12  // The capsomer's label: a capsomer is about 90 px across on a phone.
13  short?: string;
14  ring: MapRing;
15  private?: boolean;
16  // A word under the label (tool, site, product); a private system shows "private".
17  tag?: string;
18  // What it is for (Websites, Apps): the systems people use are drawn in groups, each
19  // together and named, apart from the others. The order the groups first appear in is
20  // the order they go round the map in.
21  group?: string;
22  description?: string;
23  domain?: string;
24  // Where "Open" goes: the explorer's page for this system.
25  href?: string;
26}
27
28export interface MapLink {
29  from: string;
30  to: string;
31  kind: string;
32}
33
34export interface MapContainer {
35  id: string;
36  system: string;
37  name: string;
38  kind: string;
39  technology?: string;
40}
41
42// A flow: ordered steps over the core's lines, each moving toward one end with a sentence,
43// lighting the parts it touches (design section 4, animated flows). A step names a line
44// the data already holds, so a flow can never show a connection the map does not.
45export interface MapFlowStep {
46  from: string;
47  to: string;
48  toward: string;
49  text: string;
50  lights?: readonly string[];
51}
52
53export interface MapFlow {
54  id: string;
55  name: string;
56  description?: string;
57  steps: readonly MapFlowStep[];
58}
59
60export interface SystemMapData {
61  systems: readonly MapSystem[];
62  relationships?: readonly MapLink[];
63  containers?: readonly MapContainer[];
64  flows?: readonly MapFlow[];
65}
66
67// Capsid's public model as it is served, before the map's narrowing: each system carries its
68// family (what kind of thing it is), which the map turns into a group and a word.
69export interface ModelSystem {
70  id: string;
71  name: string;
72  short?: string;
73  ring: MapRing;
74  private?: boolean;
75  family: string;
76  description?: string;
77  domain?: string;
78}
79
80export interface SystemModel {
81  systems: readonly ModelSystem[];
82  relationships: readonly MapLink[];
83  containers: readonly MapContainer[];
84}
85
86// The word under a system and the group it is drawn in, in a stranger's words (Dustin,
87// 2026-10-23: like goes with like, and the map should explain itself). An admin MCP sits in
88// its app's group and says so.
89const FAMILY_WORD: Record<string, string> = { system: "tool", writing: "writing", product: "app", plumbing: "tool", site: "site" };
90const FAMILY_GROUP: Record<string, string> = { system: "Tools", writing: "Writing", product: "Apps", plumbing: "Tools", site: "Websites" };
91
92/**
93 * What the map draws from Capsid's public model, the same on every host: each system with its
94 * word and, for what people use, its group, every line, and the parts with their kind (the box
95 * under a part's name is sized for a word). `href` is where a system's "Open" goes.
96 */
97export function modelMapData(model: SystemModel, href?: (id: string) => string): SystemMapData {
98  return {
99    systems: model.systems.map((s) => ({
100      id: s.id,
101      name: s.name,
102      short: s.short,
103      ring: s.ring,
104      private: s.private,
105      tag: s.ring === "core" ? undefined : s.ring === "shared" ? "shared" : s.id.endsWith("-mcp") ? "admin" : (FAMILY_WORD[s.family] ?? s.family),
106      group: s.ring === "used" ? FAMILY_GROUP[s.family] : undefined,
107      description: s.description,
108      domain: s.domain || undefined,
109      href: href?.(s.id),
110    })),
111    relationships: model.relationships.map(({ from, to, kind }) => ({ from, to, kind })),
112    containers: model.containers.map(({ id, system, name, kind }) => ({ id, system, name, kind })),
113  };
114}
115
116export interface SystemMapOptions {
117  // Unique on the page; prefixes every id the map writes.
118  id?: string;
119  label?: string;
120  caption?: string;
121  ringNames?: Partial<Record<MapRing, string>>;
122  headingLevel?: 2 | 3 | 4 | 5 | 6;
123  openLabel?: string;
124  // Every system's inside, from circleLayers (system-map-circles.ts): one tap on any capsomer
125  // zooms into its circle. `layers` are put in the markup, `src` is the address of all of them
126  // as one JSON object by id, which the script fetches once the page has loaded, and `chosen`
127  // is drawn zoomed into, with no script.
128  circles?: { layers?: Readonly<Record<string, string>>; src?: string; chosen?: string };
129}
130
131// ---------------------------------------------------------------------------------------
132// Geometry. Flat-top hexagons in axial coordinates, ring by ring: ring 0 is one cell,
133// ring k has 6k. A capsid seen down its three-fold axis has a hexagonal outline, which is
134// why the disc reads as a shell.
135
136export const R = 46;
137const SQRT3 = Math.sqrt(3);
138// Kinds drawn dashed: a line that coordinates or watches rather than carries.
139export const LOOSE_KINDS = new Set(["coordinates", "watches"]);
140export const STORE_KINDS = new Set(["database", "bucket", "kv", "queue"]);
141export const EXTERNAL = "external";
142export const BOX_W = 104;
143
144export function ringCells(k: number): Array<[number, number]> {
145  if (k === 0) return [[0, 0]];
146  const dirs: Array<[number, number]> = [[1, 0], [1, -1], [0, -1], [-1, 0], [-1, 1], [0, 1]];
147  const out: Array<[number, number]> = [];
148  let q = -k;
149  let r = k;
150  for (const [dq, dr] of dirs) {
151    for (let j = 0; j < k; j++) {
152      out.push([q, r]);
153      q += dq;
154      r += dr;
155    }
156  }
157  return out;
158}
159
160export interface Cell {
161  id: string | null;
162  ring: number;
163  x: number;
164  y: number;
165}
166
167export interface Layout {
168  cells: Cell[];
169  // The outermost ring drawn.
170  rings: number;
171  viewBox: [number, number, number, number];
172  // Each group's name and where it is written, when the systems people use are grouped.
173  labels: Array<{ text: string; x: number; y: number }>;
174  // Grouped, the empty cells are gaps between groups and are not drawn.
175  grouped: boolean;
176}
177
178const toXY = (q: number, r: number): [number, number] => [Math.round(1.5 * R * q * 100) / 100, Math.round(SQRT3 * R * (r + q / 2) * 100) / 100];
179
180const NEIGHBOURS: Array<[number, number]> = [[1, 0], [1, -1], [0, -1], [-1, 0], [-1, 1], [0, 1]];
181const ringOf = (q: number, r: number) => Math.max(Math.abs(q), Math.abs(r), Math.abs(q + r));
182const key = (q: number, r: number) => `${q},${r}`;
183// The size of a group's name, for room around the map: 11 px capitals, spaced.
184const LABEL_CHAR = 8.4;
185const LABEL_GAP = R + 12;
186
187/**
188 * The systems people use, in groups (Dustin, 2026-10-23: like goes with like, and a
189 * stranger reads named groups, not rings): from the ring after the shared ones, each group
190 * grows from its own direction, as near the middle as it can, its systems chained in the
191 * order given, so each touches the one before it (a site beside its admin). No cell of
192 * one group touches another group's, so the gaps say where a group ends. The groups go
193 * round in the order they first appear, each given an arc in proportion to its size.
194 */
195function placeGroups(outer: readonly MapSystem[], start: number, taken: Map<string, string>): Map<string, [number, number]> {
196  const names = [...new Set(outer.map((s) => s.group ?? ""))];
197  const total = outer.length;
198  const owner = new Map<string, number>();
199  const out = new Map<string, [number, number]>();
200  let before = 0;
201  names.forEach((name, gi) => {
202    const members = outer.filter((s) => (s.group ?? "") === name);
203    // The middle of its arc, from the lower left round, as a reader's eye goes.
204    const angle = (3 * Math.PI) / 4 - (2 * Math.PI * (before + members.length / 2)) / total;
205    before += members.length;
206    const [ax, ay] = [Math.cos(angle) * (start + 0.6) * 1.5 * R, Math.sin(angle) * (start + 0.6) * 1.5 * R];
207    let last: [number, number] | null = null;
208    for (const s of members) {
209      const candidates: Array<{ q: number; r: number; score: number }> = [];
210      const reach = start + members.length;
211      for (let q = -reach; q <= reach; q++) {
212        for (let r = -reach; r <= reach; r++) {
213          if (ringOf(q, r) < start || taken.has(key(q, r))) continue;
214          const near = NEIGHBOURS.map(([dq, dr]) => [q + dq, r + dr] as [number, number]);
215          if (near.some(([nq, nr]) => owner.has(key(nq, nr)) && owner.get(key(nq, nr)) !== gi)) continue;
216          const mine = near.filter(([nq, nr]) => owner.get(key(nq, nr)) === gi).length;
217          const touchesLast = last !== null && near.some(([nq, nr]) => nq === last![0] && nr === last![1]);
218          if (last !== null && mine === 0) continue;
219          const [x, y] = toXY(q, r);
220          // Beside the one before it first, then near the group's direction and the middle,
221          // then among more of its own.
222          const score = (touchesLast || last === null ? 0 : 1e4) + Math.hypot(x - ax, y - ay) + ringOf(q, r) * 20 - mine * 10;
223          candidates.push({ q, r, score });
224        }
225      }
226      candidates.sort((a, b) => a.score - b.score || a.q - b.q || a.r - b.r);
227      const best = candidates[0];
228      if (!best) throw new Error(`no room for ${s.id} in its group`);
229      out.set(s.id, [best.q, best.r]);
230      owner.set(key(best.q, best.r), gi);
231      taken.set(key(best.q, best.r), s.id);
232      last = [best.q, best.r];
233    }
234  });
235  return out;
236}
237
238/**
239 * Places the systems: the first core system in the middle; shared parts from ring 1,
240 * spilling outward if there are more than fit; what people use from the ring after the
241 * last shared one, or in their groups when they have them (placeGroups). Ungrouped,
242 * every cell of every ring up to the last filled one is drawn, the unused ones as empty
243 * shell. Systems keep the order they are given in.
244 */
245export function layoutMap(systems: readonly MapSystem[]): Layout {
246  const core = systems.filter((s) => s.ring === "core");
247  const inner = [...core.slice(1), ...systems.filter((s) => s.ring === "shared")];
248  const outer = systems.filter((s) => s.ring === "used");
249  const placed: Array<{ id: string | null; ring: number; q: number; r: number }> = [];
250  const fill = (ids: Array<string | null>, startRing: number): number => {
251    let ring = startRing;
252    let i = 0;
253    while (i < ids.length) {
254      for (const [q, r] of ringCells(ring)) placed.push({ id: i < ids.length ? ids[i++]! : null, ring, q, r });
255      if (i < ids.length) ring++;
256    }
257    return ring;
258  };
259  placed.push({ id: core[0]?.id ?? null, ring: 0, q: 0, r: 0 });
260  const lastInner = inner.length ? fill(inner.map((s) => s.id), 1) : 0;
261  const grouped = outer.some((s) => s.group);
262  if (!grouped) {
263    const rings = outer.length ? fill(outer.map((s) => s.id), lastInner + 1) : lastInner;
264    const cells = placed.map(({ id, ring, q, r }) => {
265      const [x, y] = toXY(q, r);
266      return { id, ring, x, y };
267    });
268    const halfW = 1.5 * R * rings + R + 6;
269    const halfH = SQRT3 * R * rings + (SQRT3 * R) / 2 + 6;
270    return { cells, rings, viewBox: [-halfW, -halfH, halfW * 2, halfH * 2], labels: [], grouped: false };
271  }
272  // The inner rings' leftover cells stay empty: the groups start outside them.
273  const taken = new Map(placed.filter((p) => p.id).map((p) => [key(p.q, p.r), p.id!]));
274  const at = placeGroups(outer, lastInner + 1, taken);
275  const rings = Math.max(lastInner, ...[...at.values()].map(([q, r]) => ringOf(q, r)));
276  // Every cell to the outermost ring is in the layout, empty or not, as the lines walk
277  // the seams of the gaps too; grouped, the empty ones are not drawn.
278  const byCell = new Map([...at].map(([id, [q, r]]) => [key(q, r), id]));
279  const cells: Cell[] = [];
280  for (let k = 0; k <= rings; k++) {
281    for (const [q, r] of ringCells(k)) {
282      const [x, y] = toXY(q, r);
283      const id = k <= lastInner ? (placed.find((p) => p.q === q && p.r === r)?.id ?? null) : (byCell.get(key(q, r)) ?? null);
284      cells.push({ id, ring: k, x, y });
285    }
286  }
287  // Each group's name just outside it, on the line from the middle through the group.
288  const where = new Map(cells.filter((c) => c.id).map((c) => [c.id!, c]));
289  const labels: Layout["labels"] = [...new Set(outer.map((s) => s.group ?? ""))].filter(Boolean).map((text) => {
290    const pts = outer.filter((s) => s.group === text).map((s) => where.get(s.id)!);
291    const cx = pts.reduce((n, p) => n + p.x, 0) / pts.length;
292    const cy = pts.reduce((n, p) => n + p.y, 0) / pts.length;
293    const len = Math.hypot(cx, cy) || 1;
294    const far = Math.max(...pts.map((p) => (p.x * cx + p.y * cy) / len));
295    // Clear of the outermost hexagon, and of it sideways by half the name.
296    const d = far + LABEL_GAP + ((text.length * LABEL_CHAR) / 2) * Math.abs(cx / len);
297    return { text, x: Math.round(((cx / len) * d) * 10) / 10, y: Math.round(((cy / len) * d + 4) * 10) / 10 };
298  });
299  let halfW = 1.5 * R * rings + R + 6;
300  let halfH = SQRT3 * R * rings + (SQRT3 * R) / 2 + 6;
301  for (const l of labels) {
302    halfW = Math.max(halfW, Math.abs(l.x) + (l.text.length * LABEL_CHAR) / 2 + 6);
303    halfH = Math.max(halfH, Math.abs(l.y) + 12);
304  }
305  return { cells, rings, viewBox: [-halfW, -halfH, halfW * 2, halfH * 2], labels, grouped: true };
306}
307
308export type Direction = "up" | "down" | "left" | "right";
309const VECTORS: Record<Direction, [number, number]> = { up: [0, -1], down: [0, 1], left: [-1, 0], right: [1, 0] };
310
311/** The capsomer an arrow key moves to: the nearest one within 60 degrees of the arrow's
312 *  direction, preferring the straight line; null at the edge of the map. */
313export function spatialNext(tiles: ReadonlyArray<{ id: string; x: number; y: number }>, from: string, dir: Direction): string | null {
314  const here = tiles.find((t) => t.id === from);
315  if (!here) return null;
316  const [dx, dy] = VECTORS[dir];
317  let best: { id: string; score: number } | null = null;
318  for (const t of tiles) {
319    if (t.id === from) continue;
320    const vx = t.x - here.x;
321    const vy = t.y - here.y;
322    const along = vx * dx + vy * dy;
323    if (along <= 0) continue;
324    const across = Math.abs(vx * dy - vy * dx);
325    if (across > along * SQRT3) continue;
326    const score = along + 2 * across;
327    if (!best || score < best.score) best = { id: t.id, score };
328  }
329  return best?.id ?? null;
330}
331
332/** The lines a chosen capsomer shows: every relationship touching it whose other end is
333 *  on the map. */
334export function linksOf(links: readonly MapLink[], id: string, onMap: ReadonlySet<string>): MapLink[] {
335  return links.filter((l) => (l.from === id || l.to === id) && onMap.has(l.from) && onMap.has(l.to) && l.from !== l.to);
336}
337
338/** The words the detail line ends with. */
339export function connectionText(n: number): string {
340  return n === 0 ? "No connections drawn" : n === 1 ? "1 connection drawn" : `${n} connections drawn`;
341}