pi-weave 0.1.19 → 0.1.21

package/src/web/client/graph/groups.ts

@@ -0,0 +1,353 @@
+/**
+ * Group identity as colour (weave-workspace §7.4, §15.8).
+ *
+ * The forces separate the graph into blobs; this decides what each blob is
+ * *called* in colour. The two must agree on what a group is, or the picture
+ * says one thing and the physics another — so a group here is exactly what
+ * `FORCES` pulls apart: a **depth-1 containment branch**.
+ *
+ * ```text
+ * vault                      ← a root: its own group
+ * ├── vfolder:sessions       ← group A, with all 323 descendants
+ * ├── vfolder:manager-digest ← group B, with all 159
+ * └── note:loose             ← no branch of its own: joins the root's group
+ * ```
+ *
+ * Depth 1 exactly, for the reason the retired `bigBranches` used it: deeper
+ * groupings shred a nested module tree into a rainbow, and the tangle a reader
+ * actually needs help with is always *sibling* blobs sharing a centre.
+ *
+ * ## One colour per group, a ramp inside it
+ *
+ * Each group takes **one** Catppuccin accent — its primary — and every member
+ * draws a shade of that single hue. Depth in the containment tree drives the
+ * ramp: the branch anchor at full strength, its children a step toward the
+ * ground, their children a step further. A group therefore reads as one colour
+ * family with its own internal structure, rather than as a set of unrelated
+ * swatches that merely happen to sit together.
+ *
+ * Depth rather than kind drives the ramp because kind does not vary inside a
+ * real group. Measured on this vault: colouring by kind gave every folder
+ * exactly **two** distinct fills (the folder, and 300-odd identical notes),
+ * which is why the result read as flat-but-arbitrary.
+ *
+ * ## A node that bridges groups shows both
+ *
+ * A note linking into another group is the interesting node on the canvas, and
+ * painting it purely in its own colour hides that. {@link bridgeBlend} mixes a
+ * measured share of each foreign group's primary into such a node, so a bridge
+ * is visibly part-way between the two families it joins. Containment is
+ * excluded — that is what put it in its group in the first place — so only
+ * genuine `links-to` / `mentions` associations tint.
+ *
+ * ## Why these hexes are not in the stylesheet
+ *
+ * Every other colour in `graph.model.ts` is mirrored from `THEME_CSS` and
+ * guarded by a drift test, because the sheet paints the same thing in CSS.
+ * Nothing in the sheet paints a graph group, so there is nothing to mirror and
+ * a mirror test would be theatre. The guarantee that matters here is
+ * *contrast*, and that is asserted directly: every hue, at every depth of the
+ * ramp, clears 3:1 against its scheme's ground (the WCAG non-text minimum).
+ *
+ * ## Tier rules (§2)
+ *
+ * `src/web/client/**`, no DOM, no npm — compiles under the root
+ * `tsconfig.json` so its tests are ordinary ones.
+ */
+
+import type { WireEdgeKind, WireGraphEdge, WireGraphNode } from "../../shared/wire";
+import type { ColorScheme } from "./graph.model";
+import { GRAPH_PALETTE, blendHex } from "./graph.model";
+
+function isContainment(kind: WireEdgeKind): boolean {
+  return kind === "contains" || kind === "anchored-at";
+}
+
+/** First-containment-parent map, the spine every walk below shares. */
+function parents(nodes: readonly WireGraphNode[], edges: readonly WireGraphEdge[]): Map<string, string> {
+  const known = new Set(nodes.map((node) => node.id));
+  const parent = new Map<string, string>();
+  for (const edge of edges) {
+    if (!isContainment(edge.kind)) continue;
+    if (edge.source === edge.target) continue;
+    if (!known.has(edge.source) || !known.has(edge.target)) continue;
+    // A second containment parent (a cycle, a hand-edited index) must not turn
+    // the walk into a diamond: first edge wins, like `layout.ts`'s `analyse`.
+    if (parent.has(edge.target)) continue;
+    parent.set(edge.target, edge.source);
+  }
+  return parent;
+}
+
+// --- which group a node belongs to, and how deep inside it ------------------------
+
+/** Where a node sits: which group, and how far below that group's anchor. */
+export interface GroupPlace {
+  /** The depth-1 branch id this node hangs from — its group. */
+  readonly key: string;
+  /** 0 for the group's anchor, 1 for its children, and so on. */
+  readonly depth: number;
+}
+
+/**
+ * Node id → its group and depth, for every node.
+ *
+ * The key is the id of the depth-1 branch the node sits under, or the node's
+ * own id when there is no branch between it and the top (a root itself, a
+ * loose note, an isolated island). Every node gets a place, so a caller never
+ * has to decide what an absent one means.
+ *
+ * The walk is bounded by a `seen` set, so a containment cycle terminates
+ * rather than hanging the column.
+ */
+export function groupPlaces(
+  nodes: readonly WireGraphNode[],
+  edges: readonly WireGraphEdge[],
+): Map<string, GroupPlace> {
+  const parent = parents(nodes, edges);
+  const out = new Map<string, GroupPlace>();
+  for (const node of nodes) {
+    // Walk to the root, remembering the last step before it: that step is the
+    // depth-1 branch, and it is the group. Distance travelled past it is the
+    // node's depth inside the group.
+    let current = node.id;
+    let previous = node.id;
+    let steps = 0;
+    const seen = new Set<string>([current]);
+    for (;;) {
+      const next = parent.get(current);
+      if (next === undefined || seen.has(next)) break;
+      seen.add(next);
+      previous = current;
+      current = next;
+      steps++;
+    }
+    // `steps` counts hops to the root; the group anchor is one hop below it,
+    // so depth inside the group is one less. A root itself is depth 0.
+    out.set(node.id, { key: previous, depth: Math.max(0, steps - 1) });
+  }
+  return out;
+}
+
+/** Node id → group key. The projection most callers want. */
+export function groupKeys(
+  nodes: readonly WireGraphNode[],
+  edges: readonly WireGraphEdge[],
+): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const [id, place] of groupPlaces(nodes, edges)) out.set(id, place.key);
+  return out;
+}
+
+/** Group key → how many nodes it holds. Biggest groups get the first hues. */
+export function groupSizes(keys: ReadonlyMap<string, string>): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const key of keys.values()) out.set(key, (out.get(key) ?? 0) + 1);
+  return out;
+}
+
+// --- the hues ---------------------------------------------------------------------
+
+/**
+ * The hue ring: Catppuccin's named accents, **in hue-wheel order**.
+ *
+ * Dark is **Macchiato** and light is **Latte**, the two flavours `THEME_CSS`
+ * is already built from, so the graph reads as the same product even though
+ * these particular swatches appear nowhere else in the sheet.
+ *
+ * Wheel order (pink → mauve → red → peach → yellow → green → teal → sapphire
+ * → blue → lavender) is what makes the *walk* across it meaningful: the ring
+ * is stepped by {@link HUE_STRIDE} rather than one at a time, so consecutive
+ * groups land on opposite sides of the wheel and two adjacent blobs are never
+ * two neighbouring blues. An arbitrary hand-ordered list gave no such
+ * guarantee, which is what made the previous assignment look random.
+ *
+ * The light row is *deepened* from stock Latte, exactly as the stylesheet
+ * deepens its own status colours (`--weave-ok:#28641b` is not Latte green).
+ * Stock Latte accents sit at 2.3–3.0:1 on `#eff1f5`, under the 3:1 non-text
+ * floor — pretty on a marketing page, invisible as a 6-pixel disc. Each was
+ * darkened along its own hue until the **deepest step of the ramp** still
+ * cleared 3:1, which is a stronger condition than the hue alone clearing it.
+ */
+export const GROUP_HUES: Readonly<Record<ColorScheme, readonly string[]>> = {
+  dark: [
+    "#f5bde6", // pink
+    "#c6a0f6", // mauve — the shell's own accent
+    "#ed8796", // red
+    "#f5a97f", // peach
+    "#eed49f", // yellow
+    "#a6da95", // green
+    "#8bd5ca", // teal
+    "#7dc4e4", // sapphire
+    "#8aadf4", // blue
+    "#b7bdf8", // lavender
+  ],
+  light: [
+    "#824171", // pink
+    "#7832d4", // mauve
+    "#d20f39", // red
+    "#9f3e07", // peach
+    "#7b4e10", // yellow
+    "#28641b", // green
+    "#106368", // teal
+    "#14616e", // sapphire
+    "#1853c8", // blue
+    "#445198", // lavender
+  ],
+};
+
+/**
+ * How far to step along the hue wheel between consecutive groups.
+ *
+ * 3 against a 10-entry ring visits every slot before repeating (3 and 10 are
+ * coprime) while putting roughly a third of the wheel between one group and
+ * the next — so the two largest blobs, which is what the eye lands on first,
+ * are always strongly separated in hue. A stride of 1 would hand the two
+ * biggest groups adjacent, easily-confused colours.
+ */
+export const HUE_STRIDE = 3;
+
+/**
+ * Group key → its one primary hue, assigned **biggest group first**.
+ *
+ * Size order rather than id order, because the biggest blob is the one a
+ * reader orients by and it should get the most distinct colours first. Ties
+ * break on the key, so the assignment is a pure function of the graph and
+ * never of insertion order.
+ *
+ * More groups than hues wraps the ring. Two groups then share a colour, which
+ * is honest: at eleven simultaneous groups the colour channel is saturated and
+ * position is doing the work anyway.
+ */
+export function groupColors(keys: ReadonlyMap<string, string>, scheme: ColorScheme): Map<string, string> {
+  const ring = GROUP_HUES[scheme];
+  const sizes = groupSizes(keys);
+  const ordered = [...sizes.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  const out = new Map<string, string>();
+  ordered.forEach(([key], index) => out.set(key, ring[(index * HUE_STRIDE) % ring.length]!));
+  return out;
+}
+
+// --- the ramp inside one group ------------------------------------------------------
+
+/**
+ * How far one level of depth steps the hue toward the ground.
+ *
+ * Small, and capped by {@link MAX_SHADE}: the ramp exists to show structure
+ * *within* one colour family, and a step big enough to read as a different
+ * colour would undo the grouping it is meant to express.
+ */
+export const DEPTH_SHADE = 0.11;
+
+/**
+ * The deepest any member may be shaded.
+ *
+ * This is the number the light ring is deepened against — every hue must still
+ * clear 3:1 on its ground *at this shade*, which the contrast test asserts for
+ * every hue at every depth.
+ */
+export const MAX_SHADE = 0.34;
+
+/** A member's fill: its group's one hue, stepped back by its depth. */
+export function shadeFor(hue: string, depth: number, scheme: ColorScheme): string {
+  const steps = Number.isFinite(depth) && depth > 0 ? depth : 0;
+  return blendHex(hue, GRAPH_PALETTE[scheme].ground, Math.min(MAX_SHADE, steps * DEPTH_SHADE));
+}
+
+// --- bridges between groups ----------------------------------------------------------
+
+/**
+ * How much of a foreign group's colour a bridging node takes on, per group it
+ * reaches.
+ *
+ * Enough to be visible against its siblings, small enough that the node still
+ * reads as a member of its own group rather than as a defector. Two foreign
+ * groups tint twice, which is the intent — a node joining three families
+ * should look like it.
+ */
+export const BRIDGE_SHARE = 0.26;
+
+/** Total foreign tint, however many groups a node bridges. */
+export const MAX_BRIDGE = 0.55;
+
+/**
+ * Mix the foreign groups' primaries into a node's own colour.
+ *
+ * Each foreign hue is blended in at {@link BRIDGE_SHARE}, in a fixed order
+ * (the caller sorts), so the result is deterministic rather than dependent on
+ * edge iteration order. The total is capped at {@link MAX_BRIDGE} so a
+ * promiscuously-linked hub does not end up painted entirely in other people's
+ * colours.
+ */
+export function bridgeBlend(own: string, foreign: readonly string[], scheme: ColorScheme): string {
+  if (foreign.length === 0) return own;
+  let out = own;
+  let spent = 0;
+  for (const hue of foreign) {
+    const share = Math.min(BRIDGE_SHARE, MAX_BRIDGE - spent);
+    if (share <= 0) break;
+    spent += share;
+    // Blend into the running colour, not into `own`: successive mixes
+    // compound, which is what makes a three-way bridge read differently from
+    // a two-way one. `scheme` is unused by the arithmetic but kept in the
+    // signature so a future scheme-aware mix does not change every caller.
+    out = blendHex(out, hue, share);
+  }
+  return out;
+}
+
+// --- the whole assignment --------------------------------------------------------------
+
+/**
+ * Node id → fill: group hue, depth shade, and any bridge tint.
+ *
+ * One call for the caller, and the only place the three steps are composed —
+ * so a renderer cannot apply the ramp twice or skip the tint for one kind.
+ */
+export function groupNodeColors(
+  nodes: readonly WireGraphNode[],
+  edges: readonly WireGraphEdge[],
+  scheme: ColorScheme,
+): Map<string, string> {
+  const places = groupPlaces(nodes, edges);
+  const keys = new Map<string, string>();
+  for (const [id, place] of places) keys.set(id, place.key);
+  const hues = groupColors(keys, scheme);
+
+  // Which foreign groups each node associates with. Containment is excluded:
+  // it is what put the node in its group, so it can never be a bridge.
+  const known = new Set(nodes.map((node) => node.id));
+  const reaches = new Map<string, Set<string>>();
+  const note = (from: string, to: string): void => {
+    const here = places.get(from)?.key;
+    const there = places.get(to)?.key;
+    if (here === undefined || there === undefined || here === there) return;
+    const set = reaches.get(from);
+    if (set === undefined) reaches.set(from, new Set([there]));
+    else set.add(there);
+  };
+  for (const edge of edges) {
+    if (isContainment(edge.kind)) continue;
+    if (edge.source === edge.target) continue;
+    if (!known.has(edge.source) || !known.has(edge.target)) continue;
+    note(edge.source, edge.target);
+    note(edge.target, edge.source);
+  }
+
+  const out = new Map<string, string>();
+  for (const node of nodes) {
+    const place = places.get(node.id);
+    if (place === undefined) continue;
+    const hue = hues.get(place.key);
+    if (hue === undefined) continue;
+    const mine = shadeFor(hue, place.depth, scheme);
+    // Sorted, so the blend order — and therefore the exact hex — is a function
+    // of the graph rather than of the order edges happened to arrive in.
+    const foreign = [...(reaches.get(node.id) ?? [])]
+      .sort()
+      .map((key) => hues.get(key))
+      .filter((value): value is string => value !== undefined);
+    out.set(node.id, bridgeBlend(mine, foreign, scheme));
+  }
+  return out;
+}

package/src/web/client/graph/positions.ts

@@ -203,14 +203,15 @@ export interface PositionStorage {
 /**
  * The `localStorage` key. Namespaced and versioned, like the layout's.
  *
- * `v3` is the Tier 6 gravity/size change: stronger centre gravity, shorter
- * relation springs and degree-sized collision discs moved every resting
- * position the old recipe settled to. A v2 entry is a valid layout of the
- * *old* physics, and the shape key has no way to know that — so the version
- * does what it did for the branch-anchor change: one whole generation of
- * stored arrangements is a miss rather than a half-forgotten map.
+ * `v4` is the frozen force constants (§15.7): the tuner's chosen values move
+ * every resting position the previous recipe settled to. A v3 entry is a valid
+ * layout of the *old* physics, and the shape key has no way to know that — it
+ * digests which nodes and edges exist, and a force change touches neither. So
+ * the version does what it did for `v3`'s gravity change and the branch-anchor
+ * change before it: one whole generation of stored arrangements is a clean
+ * miss rather than a half-forgotten map.
  */
-export const POSITIONS_STORAGE_KEY = "pi-weave.graph.positions.v3";
+export const POSITIONS_STORAGE_KEY = "pi-weave.graph.positions.v4";
 
 /**
  * Coordinates are rounded to **one** decimal before storage.
@@ -237,11 +238,11 @@ function round1(value: number): number {
 export function serializePositions(key: string, positions: ReadonlyMap<string, Point>): string {
   const at: Record<string, [number, number]> = {};
   for (const [id, point] of positions) at[id] = [round1(point.x), round1(point.y)];
-  // `v: 3` — the Tier 6 gravity/size recipe. A v2 entry is an arrangement from
-  // the previous force constants, and the shape key cannot tell the two
-  // recipes apart because they changed under the same node and edge set. The
-  // version can, exactly as it did for the branch-anchor change before it.
-  return JSON.stringify({ v: 3, key, at });
+  // `v: 4` — the frozen force constants. A v3 entry is an arrangement from the
+  // previous constants, and the shape key cannot tell the two recipes apart
+  // because they changed under the same node and edge set. The version can,
+  // exactly as it did for the gravity change before it.
+  return JSON.stringify({ v: 4, key, at });
 }
 
 /**
@@ -273,7 +274,7 @@ export function deserializePositions(raw: string | null, key: string): Map<strin
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
 
   const record = parsed as Record<string, unknown>;
-  if (record["v"] !== 3) return null;
+  if (record["v"] !== 4) return null;
   if (record["key"] !== key) return null;
 
   const at = record["at"];

package/src/web/client/graph/renderer.ts

@@ -90,6 +90,8 @@ export function sigmaRenderer(
   let sigma: SigmaLike | null = null;
   let graph: ProjectedGraph = project({ nodes: [], edges: [] });
   let highlight: ReadonlySet<string> | null = null;
+  /** The selection inside that neighbourhood — see `nodeReducer`. */
+  let selected: string | null = null;
   let select: (id: string | null) => void = () => {};
   let dragStart: (id: string) => void = () => {};
   let dragMove: (id: string, at: Point) => void = () => {};
@@ -119,8 +121,8 @@ export function sigmaRenderer(
    * until the next unrelated frame.
    */
   const applyReducers = (instance: SigmaLike): void => {
-    const nodes = nodeReducer(highlight);
-    const edges = edgeReducer(highlight);
+    const nodes = nodeReducer(highlight, selected);
+    const edges = edgeReducer(highlight, selected);
     instance.setSetting("nodeReducer", (id, data) => ({ ...data, ...nodes(id, data, scheme) }));
     instance.setSetting("edgeReducer", (key, data) => ({ ...data, ...edges(key, data, scheme) }));
   };
@@ -177,8 +179,9 @@ export function sigmaRenderer(
       sigma?.refresh();
     },
 
-    setHighlight(next: ReadonlySet<string> | null) {
+    setHighlight(next: ReadonlySet<string> | null, selectedId: string | null = null) {
       highlight = next;
+      selected = selectedId;
       if (sigma !== null) applyReducers(sigma);
     },
 

package/src/web/client/graph/tuner.model.ts

@@ -0,0 +1,210 @@
+/**
+ * The hidden force tuner's logic (docs/weave-workspace.md §15.7).
+ *
+ * The graph's arrangement is decided by six numbers in `shared/layout.ts`, and
+ * the difference between "one hairball" and "legible groups" is a *ratio*
+ * between them that is far easier to see than to derive. So there is a panel
+ * of sliders behind a URL flag, and everything about it that is not a DOM node
+ * lives here — §10's rule, the same split `Graph.tsx` / `column.model.ts`
+ * already uses.
+ *
+ * ## Why a query flag and not a setting
+ *
+ * The tuner is a *developer* affordance with a human in the loop; it is not a
+ * feature and must not read as one. A URL string is the cheapest gate that is
+ * genuinely hidden (no menu entry, no chord to collide with §11 P4's
+ * keymap, no persisted state to leak into a normal session) while staying
+ * reachable on a running workspace with no rebuild. A build-time `define`
+ * would have been more hidden still and was rejected: it breaks the
+ * byte-reproducible `build:web:check` contract for a panel that is already
+ * unreachable without the flag.
+ *
+ * ## Tier rules (§2)
+ *
+ * `src/web/client/**`, but nothing here touches the DOM or npm — the flag
+ * arrives as a `location.search` *string*, so this module compiles under the
+ * root `tsconfig.json` and its tests are ordinary ones.
+ */
+
+import type { ForceConstants } from "../../shared/layout";
+import { FORCE_DEFAULTS } from "../../shared/layout";
+
+// --- the gate ----------------------------------------------------------------------
+
+/** The query parameter that opens the panel. Documented in §15.7. */
+export const SLIDERS_FLAG = "sliders";
+
+/**
+ * Whether `location.search` asks for the tuner.
+ *
+ * `?sliders`, `?sliders=1` and `?sliders=true` all open it; `?sliders=0` and
+ * `?sliders=false` do not, so a bookmarked URL can carry the parameter in the
+ * off position. Anything unparseable is off — a typo must not silently put a
+ * debug panel over a user's graph.
+ *
+ * Hand-parsed rather than via `URLSearchParams`, which is a DOM/Node global
+ * this tier's `tsconfig` does not provide.
+ */
+export function slidersFlag(search: string): boolean {
+  for (const pair of search.replace(/^\?/, "").split("&")) {
+    const eq = pair.indexOf("=");
+    const name = eq === -1 ? pair : pair.slice(0, eq);
+    if (name !== SLIDERS_FLAG) continue;
+    const value = eq === -1 ? "" : pair.slice(eq + 1).toLowerCase();
+    return value !== "0" && value !== "false";
+  }
+  return false;
+}
+
+// --- the sliders --------------------------------------------------------------------
+
+/** One slider: which constant it drives, and the range it may drive it over. */
+export interface SliderSpec {
+  readonly key: keyof ForceConstants;
+  readonly label: string;
+  /** One line under the label saying what moving it does. */
+  readonly hint: string;
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
+}
+
+/**
+ * The panel, in the order the forces actually fight each other: cohesion
+ * first (what holds a group together), then repulsion (what pushes groups
+ * apart), then gravity (what pulls everything back in). Reading top to bottom
+ * is reading the tug-of-war.
+ *
+ * Ranges are generous on purpose — the point of the exercise is that the
+ * shipped values are in the wrong region, so a range hugging them would hide
+ * the answer. `chargeMax` tops out at 4000, which is past any useful value on
+ * a graph that spans a few thousand units; that top of the range is
+ * effectively "uncapped".
+ */
+export const FORCE_SLIDERS: readonly SliderSpec[] = [
+  { key: "containsStrength", label: "contains strength", hint: "how hard a parent holds its children — group cohesion", min: 0, max: 1, step: 0.01 },
+  { key: "containsRest", label: "contains rest", hint: "how far children sit from their parent — rosette radius", min: 10, max: 300, step: 5 },
+  { key: "relationStrength", label: "relation strength", hint: "pull of links-to / mentions across groups", min: 0, max: 1, step: 0.01 },
+  { key: "relationDistance", label: "relation distance", hint: "how long those cross-group springs are", min: 20, max: 600, step: 10 },
+  { key: "charge", label: "charge", hint: "node-to-node repulsion — more negative pushes harder", min: -1200, max: 0, step: 10 },
+  { key: "chargeMax", label: "charge range", hint: "distance past which repulsion stops — caps overall spread", min: 100, max: 4000, step: 50 },
+  { key: "center", label: "centre gravity", hint: "pull toward the origin — too much makes one blob", min: 0, max: 0.3, step: 0.005 },
+];
+
+/**
+ * The arrangement this whole exercise replaced, kept as a **comparison**.
+ *
+ * Not a suggestion any more — `FORCE_DEFAULTS` is now the chosen answer, found
+ * through these sliders and frozen in `shared/layout.ts`. This is the *before*
+ * picture, one button press away, so the next person to open the panel can see
+ * in one click what the constants are for rather than reading a changelog.
+ *
+ * Measured at 300 ticks, worst-case gap between the big branches' bounding
+ * boxes (negative = the branches interleave, which is the hairball):
+ * `siblingBlobsGraph` **−312** here against **+39** shipped, `repoLikeGraph`
+ * **−274** against **+133**.
+ */
+export const HAIRBALL: Readonly<ForceConstants> = {
+  containsRest: 90,
+  containsStrength: 0.02,
+  relationDistance: 170,
+  relationStrength: 0.05,
+  charge: -50,
+  chargeMax: Infinity,
+  center: 0.09,
+};
+
+/**
+ * A slider's value for `<input type="range">`.
+ *
+ * `chargeMax` defaults to `Infinity`, which is not a number a range input can
+ * hold, so it reads as the top of its range — the position that means "no
+ * meaningful cap", which is what `Infinity` is.
+ */
+export function sliderValue(forces: ForceConstants, spec: SliderSpec): number {
+  const raw = forces[spec.key];
+  if (!Number.isFinite(raw)) return spec.max;
+  return Math.min(spec.max, Math.max(spec.min, raw));
+}
+
+/**
+ * Parse and clamp what a slider reported.
+ *
+ * An `<input>`'s `value` is a string, and a non-numeric one (which the
+ * platform should never produce, but a synthetic event can) falls back to the
+ * shipped default rather than poisoning the simulation with a `NaN` that would
+ * propagate to every node position in one tick.
+ */
+export function parseSlider(spec: SliderSpec, raw: string): number {
+  const parsed = Number.parseFloat(raw);
+  if (!Number.isFinite(parsed)) return FORCE_DEFAULTS[spec.key];
+  return Math.min(spec.max, Math.max(spec.min, parsed));
+}
+
+/** A slider's readout. Short, and never `0.8500000000000001`. */
+export function formatValue(value: number): string {
+  if (!Number.isFinite(value)) return "∞";
+  return Number.isInteger(value) ? String(value) : value.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+// --- handing the numbers back ----------------------------------------------------------
+
+/**
+ * The current constants as the literal that belongs in `shared/layout.ts`.
+ *
+ * The whole point of the tuner is that a human finds the values and they then
+ * get *frozen into the source*, so the last step of the loop is transcription
+ * — and transcribing seven floats by eye off a panel is exactly where a digit
+ * gets dropped. The Copy button emits the block verbatim.
+ */
+export function forcesSnippet(forces: ForceConstants): string {
+  const line = (key: keyof ForceConstants): string => `  ${key}: ${Number.isFinite(forces[key]) ? forces[key] : "Infinity"},`;
+  return ["export const FORCES: ForceConstants = {", ...FORCE_SLIDERS.map((spec) => line(spec.key)), "};"].join("\n");
+}
+
+/** True when nothing has been moved off the shipped values. Drives "Reset". */
+export function isDefault(forces: ForceConstants): boolean {
+  return FORCE_SLIDERS.every((spec) => Object.is(forces[spec.key], FORCE_DEFAULTS[spec.key]));
+}
+
+// --- the group-colour setting (§15.8) ------------------------------------------------
+
+/**
+ * Where the group-colour choice is remembered.
+ *
+ * Versioned like the position cache, and stored separately from it: a palette
+ * preference must survive the layout invalidation that a force change causes,
+ * or tuning the physics would silently reset the user's colours.
+ */
+export const GROUP_COLORS_STORAGE_KEY = "pi-weave.graph.groupColors.v1";
+
+/** The two-method storage port, same shape as `PositionStorage`. */
+export interface SettingStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+/**
+ * Whether to colour by group. Defaults to **on**.
+ *
+ * On by default because the forces go to real trouble to separate the groups
+ * and leaving them one colour wastes that. A throwing `getItem` (Safari
+ * private browsing, partitioned storage) is a default, not an error — the
+ * same answer `loadPositions` gives.
+ */
+export function loadGroupColors(storage: SettingStorage): boolean {
+  try {
+    return storage.getItem(GROUP_COLORS_STORAGE_KEY) !== "off";
+  } catch {
+    return true;
+  }
+}
+
+/** Persist the choice, best-effort. A full or refusing quota is not an error. */
+export function saveGroupColors(storage: SettingStorage, on: boolean): void {
+  try {
+    storage.setItem(GROUP_COLORS_STORAGE_KEY, on ? "on" : "off");
+  } catch {
+    // A preference that does not survive a reload still works this session.
+  }
+}

package/src/web/client/main.tsx

@@ -13,6 +13,7 @@
 import { render } from "preact";
 import { BOOTSTRAP_ELEMENT_ID } from "../shared/wire";
 import { readBootstrap } from "./bootstrap";
+import { slidersFlag } from "./graph/tuner.model";
 import { Shell } from "./shell/Shell";
 import { installTheme } from "./shell/theme";
 import { loadTheme, themeAttr } from "./shell/theme.model";
@@ -28,7 +29,17 @@ if (host !== null) {
   // writes nothing — the media query already answered.
   applyPrePaintTheme();
   const boot = readBootstrap(document.getElementById(BOOTSTRAP_ELEMENT_ID)?.textContent ?? null);
-  render(<Shell cwd={boot.cwd} initialWidth={window.innerWidth} platform={navigator.platform} />, host);
+  render(
+    <Shell
+      cwd={boot.cwd}
+      initialWidth={window.innerWidth}
+      platform={navigator.platform}
+      // The fourth DOM read that cannot be injected further up. `slidersFlag`
+      // owns the parsing, so this stays a read and the decision stays tested.
+      tuner={slidersFlag(window.location.search)}
+    />,
+    host,
+  );
 }
 
 /** Apply the stored theme choice to `<html>` synchronously, pre-render. */