pi-weave 0.1.19 → 0.1.21

package/src/web/client/shell/Columns.tsx

@@ -65,6 +65,8 @@ export interface ColumnsProps {
   bootFailed: boolean;
   /** Slot the graph column fills with its `fit`, for the global `g` key. */
   fit: { current: (() => void) | null };
+  /** `?sliders=1` — the hidden force tuner (docs/weave-workspace.md §15.7). */
+  tuner: boolean;
 }
 
 /** One column: a titled region and whichever surface fills it. */
@@ -95,6 +97,7 @@ function Column({ id, props }: { id: ColumnId; props: ColumnsProps }) {
           scheme={props.scheme}
           bootFailed={props.bootFailed}
           fit={props.fit}
+          tuner={props.tuner}
         />
       ) : null}
       {id === "graph" ? <ContextRail graph={props.graph} selectedId={props.selectedId} onSelect={props.onSelect} /> : null}

package/src/web/client/shell/Shell.tsx

@@ -60,6 +60,12 @@ export interface ShellProps {
   initialWidth: number;
   /** `navigator.platform`, for the `⌘K` vs `Ctrl K` hint. */
   platform: string;
+  /**
+   * `location.search` carried `?sliders=1` — open the hidden force tuner over
+   * the graph column (docs/weave-workspace.md §15.7). Resolved by `slidersFlag`
+   * in `main.tsx`; optional so every existing caller and test keeps its shape.
+   */
+  tuner?: boolean;
 }
 
 export function Shell(props: ShellProps) {
@@ -206,6 +212,7 @@ export function Shell(props: ShellProps) {
         storage={localStorage}
         host={window}
         fit={fit}
+        tuner={props.tuner === true}
       />
       {/*
         `model.generatedAt`, not `stamp`. The two used to be the same string;

package/src/web/client/shell/theme.ts

@@ -297,6 +297,9 @@ body{font-size:var(--weave-px-base)}
   border:1px solid var(--weave-line-strong);border-radius:var(--weave-radius);
 }
 .weave-chip:hover{color:var(--weave-fg);border-color:var(--weave-accent)}
+/* A chip that is a toggle, while it is on: the accent states it without a
+   second control or an icon. */
+.weave-chip-on{color:var(--weave-accent);border-color:var(--weave-accent)}
 .weave-rows{
   flex:1;min-height:0;overflow:auto;margin:0;padding:3px 0;list-style:none;
 }
@@ -511,7 +514,7 @@ body{font-size:var(--weave-px-base)}
    the \`1fr\` row from \`.weave-col-graph\` above — a zero-height container makes
    sigma refuse to render (we pass \`allowInvalidContainer\`, so it degrades to
    blank rather than throwing). */
-.weave-graph{display:grid;grid-template-rows:1fr auto auto;min-height:0;overflow:hidden}
+.weave-graph{display:grid;grid-template-rows:1fr auto auto;min-height:0;overflow:hidden;position:relative}
 .weave-graph-canvas{min-height:120px;min-width:0;position:relative;overflow:hidden}
 /* A barely-there vignette, so the stage reads as a lit surface rather than a
    flat void. Sigma clears its WebGL layers transparent (no background colour
@@ -560,6 +563,32 @@ body{font-size:var(--weave-px-base)}
   border-top:1px solid var(--weave-line);
 }
 
+/* the hidden force tuner (?sliders=1, docs/weave-workspace.md 15.7) --------- */
+/* Absolutely positioned over the canvas rather than given a grid row: the
+   panel is a debug overlay and must not change the layout the graph is being
+   judged in — moving the canvas while tuning it would falsify the very thing
+   being looked at. */
+.weave-tuner{
+  position:absolute;top:8px;right:8px;z-index:3;width:232px;max-height:calc(100% - 16px);
+  overflow:auto;display:flex;flex-direction:column;gap:6px;padding:9px 10px;
+  font-size:var(--weave-px-caption);color:var(--weave-fg);
+  background:var(--weave-panel);border:1px solid var(--weave-line-strong);
+  border-radius:var(--weave-radius);
+}
+.weave-tuner-title{margin:0;color:var(--weave-faint);letter-spacing:.04em;text-transform:uppercase}
+.weave-tuner-row{display:flex;flex-direction:column;gap:2px;cursor:pointer}
+.weave-tuner-label{display:flex;justify-content:space-between;gap:8px;color:var(--weave-dim)}
+.weave-tuner-label b{color:var(--weave-accent);font-weight:600;font-variant-numeric:tabular-nums}
+.weave-tuner-row input{width:100%;margin:0;accent-color:var(--weave-accent)}
+.weave-tuner-toggle{display:flex;align-items:center;gap:6px;cursor:pointer;color:var(--weave-dim)}
+.weave-tuner-toggle input{margin:0;accent-color:var(--weave-accent)}
+.weave-tuner-actions{display:flex;gap:6px;margin-top:2px;flex-wrap:wrap}
+.weave-tuner-snippet{
+  margin:0;padding:6px;overflow:auto;white-space:pre;color:var(--weave-faint);
+  background:var(--weave-bg);border:1px solid var(--weave-line);border-radius:var(--weave-radius);
+  font-size:var(--weave-px-prov);line-height:1.45;
+}
+
 /* context rail ---------------------------------------------------------- */
 /* The \`.weave-empty\` block that used to sit above went with \`EmptyState.tsx\`
    in P3: every column now has its own empty state (\`treeEmptyMessage\`,

package/src/web/client/tree/Tree.tsx

@@ -1,6 +1,6 @@
 /** The vault and repository tree column. */
 
-import { useState } from "preact/hooks";
+import { useLayoutEffect, useRef, useState } from "preact/hooks";
 import { createFolder, deleteFolder, deleteNote, moveNote, renameFolder, renameNote } from "../api";
 import { fetchJson } from "../api.dom";
 import { isTextEntry, type KeyTarget } from "../shell/keys.model";
@@ -8,6 +8,8 @@ import { ICON_BOX, ICON_STROKE, ICONS } from "../shell/icons.model";
 import type { IconName } from "../shell/icons.model";
 import type { GraphPayload } from "../../shared/wire";
 import {
+  DRAFT_FOLDER_ID,
+  deleteItemLabel,
   FILTER_HINT,
   FILTER_LABEL,
   FILTER_PLACEHOLDER,
@@ -20,6 +22,9 @@ import {
   dropFolder,
   expand,
   initialTreeView,
+  newFolderParent,
+  newFolderPath,
+  withDraftRow,
   internalsHint,
   internalsLabel,
   mutableTreeRow,
@@ -80,6 +85,7 @@ function Row({ view, recentIds, edit, onEdit, onRename, onSelect, onToggle, onMe
       style={depthVar(view.depth)}
       onClick={onSelect}
       draggable={view.id.startsWith("note:")}
+      aria-label={view.id === DRAFT_FOLDER_ID ? "New folder" : undefined}
       onDragStart={(event) => event.dataTransfer?.setData("text/plain", view.id)}
       onDragOver={folder === undefined ? undefined : (event) => event.preventDefault()}
       onDrop={folder === undefined ? undefined : (event) => { event.preventDefault(); onDrop(event.dataTransfer?.getData("text/plain") ?? ""); }}
@@ -90,17 +96,75 @@ function Row({ view, recentIds, edit, onEdit, onRename, onSelect, onToggle, onMe
       </span>
       <span class="weave-kind" aria-hidden="true"><Icon name={view.kindIcon} class="weave-icon" /></span>
       <span class={`weave-prov weave-prov-${view.provenance ?? "none"}`} title={view.provenanceTitle}>{view.provenanceGlyph}</span>
-      {edit === null ? <span class="weave-label">{view.label}</span> : <input class="weave-tree-rename" value={edit} autoFocus onClick={(event) => event.stopPropagation()} onInput={(event) => onEdit(event.currentTarget.value)} onBlur={(event) => onRename(event.currentTarget.value)} onKeyDown={(event) => { event.stopPropagation(); if (event.key === "Enter") event.currentTarget.blur(); else if (event.key === "Escape") onRename(null); }} />}
+      {edit === null ? <span class="weave-label">{view.label}</span> : <RenameInput value={edit} draft={view.id === DRAFT_FOLDER_ID} onEdit={onEdit} onCommit={onRename} />}
       <span class="weave-meta">{view.meta}</span>
     </li>
   );
 }
 
+/**
+ * The inline editor, as its own component so it **mounts** when an edit
+ * starts.
+ *
+ * That is the whole reason it is not an `<input>` inline in {@link Row}: the
+ * existing name has to be selected once, when the editor opens, and neither
+ * obvious spelling does that. An inline `ref={(el) => el?.select()}` re-runs
+ * on every render — preact's children diff fires a ref whenever its
+ * *identity* changes (`oldVNode.ref != childVNode.ref` in
+ * `diff/children.js`), and an arrow literal is a new identity each time — so
+ * every keystroke would re-select the text being typed. `onFocus` re-selects
+ * whenever the tab regains focus mid-edit. A mount effect fires exactly once,
+ * which is the actual requirement.
+ *
+ * `useLayoutEffect`, not `useEffect`, so the selection is in place before
+ * paint — otherwise the fix itself flashes unselected text for a frame.
+ */
+function RenameInput({ value, draft, onEdit, onCommit }: { value: string; draft: boolean; onEdit: (value: string) => void; onCommit: (value: string | null) => void }) {
+  const input = useRef<HTMLInputElement | null>(null);
+  useLayoutEffect(() => {
+    const element = input.current;
+    if (element === null) return;
+    element.focus();
+    // A draft folder has no name yet, and `select()` on an empty input is a
+    // no-op — so this needs no branch.
+    element.select();
+  }, []);
+  return (
+    <input
+      ref={input}
+      class="weave-tree-rename"
+      value={value}
+      placeholder={draft ? "New folder name…" : undefined}
+      onClick={(event) => event.stopPropagation()}
+      onInput={(event) => onEdit(event.currentTarget.value)}
+      onBlur={(event) => onCommit(event.currentTarget.value)}
+      onKeyDown={(event) => {
+        event.stopPropagation();
+        if (event.key === "Enter") event.currentTarget.blur();
+        else if (event.key === "Escape") onCommit(null);
+      }}
+    />
+  );
+}
+
 export function Tree(props: TreeProps) {
   const [state, setState] = useState(initialTreeView);
-  const [menu, setMenu] = useState<{ id: string; label: string; x: number; y: number } | null>(null);
+  /**
+   * The open context menu. `armed` is the folder-delete confirmation: the
+   * first click on `Delete…` sets it, and only then does the item delete —
+   * see `deleteItemLabel`. Held on the menu so closing it disarms, which is
+   * what makes a mis-click cheap.
+   */
+  const [menu, setMenu] = useState<{ id: string; label: string; x: number; y: number; armed?: boolean } | null>(null);
   const [editing, setEditing] = useState<{ id: string; label: string; value: string } | null>(null);
-  const rows = rowsFor(props.graph, state);
+  /**
+   * The parent path a pending "New folder" will be created under, or `null`.
+   *
+   * The folder is not created until the name is committed — see
+   * {@link withDraftRow}. Escaping leaves nothing behind.
+   */
+  const [draft, setDraft] = useState<string | null>(null);
+  const rows = withDraftRow(rowsFor(props.graph, state), draft);
   const empty = treeEmptyMessage(props.graph, rows, state);
   const run = async (pending: ReturnType<typeof deleteNote>, select?: string): Promise<void> => {
     const result = await pending;
@@ -117,18 +181,67 @@ export function Tree(props: TreeProps) {
     setMenu(null);
     if (target === null) return;
     if (action === "newFolder") {
-      const name = window.prompt("Folder name:")?.trim();
-      if (!name) return;
-      const parent = target.type === "vault" ? "" : target.type === "folder" ? target.path : target.path.split("/").slice(0, -1).join("/");
-      const targetPath = parent ? `${parent}/${name}` : name;
-      if (parent) setState((current) => expand(current, `vfolder:${parent}`));
-      await run(createFolder(fetchJson, targetPath));
+      // A draft row with the cursor in it, not a modal: the same inline
+      // gesture `rename` already uses, and it shows *where* the folder will
+      // land, which a prompt cannot.
+      const parent = newFolderParent(target);
+      if (parent !== "") setState((current) => expand(current, `vfolder:${parent}`));
+      setDraft(parent);
+      setEditing({ id: DRAFT_FOLDER_ID, label: "", value: "" });
     } else if (action === "rename") {
       setEditing({ id: menu.id, label: menu.label, value: menu.label });
-    } else if (target.type !== "vault" && (!deleteNeedsConfirmation(target) || window.confirm(`Permanently delete folder “${menu.label}” and everything inside it?`))) {
+    } else if (target.type !== "vault") {
       await run(target.type === "note" ? deleteNote(fetchJson, target.path) : deleteFolder(fetchJson, target.path), deletesSelection(props.selectedId, target) ? "vault" : undefined);
     }
   };
+
+  /**
+   * The delete item was clicked. Arms first for a folder, deletes second.
+   *
+   * A note deletes on the first click (§#37): it is one file whose name the
+   * user just read off the row. A folder is `fs.rm(recursive)` over a subtree
+   * the row shows no count for, so it takes two — and the second click's label
+   * names the folder, which is the chance to notice the wrong row was hit.
+   */
+  const clickDelete = (target: { type: "note" | "folder" | "vault" }): void => {
+    if (menu === null) return;
+    if (deleteNeedsConfirmation(target) && menu.armed !== true) {
+      setMenu({ ...menu, armed: true });
+      return;
+    }
+    void act("delete");
+  };
+  /**
+   * The inline editor was committed (Enter or blur) or abandoned (Escape).
+   *
+   * Two gestures share one input, so this is where they part: the draft row
+   * creates a folder, every other row renames. Both clear the editor first,
+   * so an abandoned edit and a failed request leave the same clean state.
+   */
+  const commitEdit = (value: string | null): void => {
+    const current = editing;
+    const parent = draft;
+    setEditing(null);
+    setDraft(null);
+    if (current === null) return;
+    const name = value?.trim();
+    if (current.id === DRAFT_FOLDER_ID) {
+      // Escape, or an empty name: the draft simply disappears. Nothing was
+      // created, so there is nothing to undo.
+      const path = parent === null || !name ? null : newFolderPath(parent, name);
+      if (path !== null) void run(createFolder(fetchJson, path));
+      return;
+    }
+    const target = mutableTreeRow(current.id);
+    // No confirmation. A rename can break wiki-links, but the warning was
+    // unactionable — it named no link and offered no way to see them — and it
+    // fired on the *commit* of an edit the user had already typed out, which
+    // is the least useful moment to ask. Renaming back is one more rename.
+    if (target !== null && name && name !== current.label) {
+      void run(target.type === "note" ? renameNote(fetchJson, target.path, name) : renameFolder(fetchJson, target.path, name));
+    }
+  };
+
   return (
     <div class="weave-tree" onKeyDown={(event) => {
       const target = event.target as KeyTarget;
@@ -155,7 +268,7 @@ export function Tree(props: TreeProps) {
             setMenu({ id: "vault", label: "Vault", x: event.clientX, y: event.clientY });
           }}
         >
-          {rowViews(rows, props.selectedId, props.now).map((view) => <Row key={view.id} view={view} recentIds={props.recentIds} edit={editing?.id === view.id ? editing.value : null} onEdit={(value) => setEditing((current) => current === null ? null : { ...current, value })} onRename={(value) => { const current = editing; setEditing(null); const target = current === null ? null : mutableTreeRow(current.id); const name = value?.trim(); const label = current?.label; if (target !== null && name && label !== undefined && name !== label && window.confirm(`Rename “${label}”? Existing links to it may break.`)) void run(target.type === "note" ? renameNote(fetchJson, target.path, name) : renameFolder(fetchJson, target.path, name)); }} onSelect={() => { props.onSelect(view.id); if (view.hasKids) setState((current) => toggleExpanded(current, view.id)); }} onToggle={() => setState(toggleExpanded(state, view.id))} onMenu={(x, y) => setMenu({ id: view.id, label: view.label, x, y })} onDrop={(dragged) => { const folder = dropFolder(view.id); if (dragged.startsWith("note:") && folder !== undefined) void run(moveNote(fetchJson, dragged.slice("note:".length), folder)); }} />)}
+          {rowViews(rows, props.selectedId, props.now).map((view) => <Row key={view.id} view={view} recentIds={props.recentIds} edit={editing?.id === view.id ? editing.value : null} onEdit={(value) => setEditing((current) => current === null ? null : { ...current, value })} onRename={commitEdit} onSelect={() => { props.onSelect(view.id); if (view.hasKids) setState((current) => toggleExpanded(current, view.id)); }} onToggle={() => setState(toggleExpanded(state, view.id))} onMenu={(x, y) => setMenu({ id: view.id, label: view.label, x, y })} onDrop={(dragged) => { const folder = dropFolder(view.id); if (dragged.startsWith("note:") && folder !== undefined) void run(moveNote(fetchJson, dragged.slice("note:".length), folder)); }} />)}
         </ul>
       ) : <p class="weave-tree-empty">{empty}</p>}
       <p class="weave-tree-count">{rowCountLabel(rows)}</p>
@@ -169,7 +282,7 @@ export function Tree(props: TreeProps) {
               {target.type !== "vault" ? (
                 <>
                   <button type="button" role="menuitem" onClick={() => void act("rename")}>Rename…</button>
-                  <button type="button" role="menuitem" class="weave-menu-danger" onClick={() => void act("delete")}>Delete</button>
+                  <button type="button" role="menuitem" class="weave-menu-danger" onClick={() => clickDelete(target)}>{deleteItemLabel(target, menu.label, menu.armed === true)}</button>
                 </>
               ) : null}
             </div>

package/src/web/client/tree/tree.model.ts

@@ -104,6 +104,80 @@ export function rowsFor(payload: GraphPayload | null, state: TreeViewState): Tre
   return treeRows(viewModel(payload), state);
 }
 
+// --- the draft folder row ------------------------------------------------------------
+
+/**
+ * The id of the placeholder row a pending "New folder" occupies.
+ *
+ * A real id from the same namespace as the rest of the tree, so the row is an
+ * ordinary `TreeRow` that renders, indents and takes the rename input with no
+ * special-casing anywhere below {@link withDraftRow}. It cannot collide with a
+ * folder the vault holds, because `slugify` strips the leading `\u0000`.
+ */
+export const DRAFT_FOLDER_ID = "vfolder:\u0000draft";
+
+/**
+ * Where a new folder created from `target` would go.
+ *
+ * A right-click on the vault makes a top-level folder; on a folder, a child of
+ * it; on a *note*, a sibling of that note — which is what "new folder here"
+ * means when "here" is a file. Returns the parent path, `""` for the root.
+ */
+export function newFolderParent(target: { type: "note" | "folder" | "vault"; path: string }): string {
+  if (target.type === "vault") return "";
+  if (target.type === "folder") return target.path;
+  return target.path.split("/").slice(0, -1).join("/");
+}
+
+/** The path `createFolder` should be asked for, given a parent and a typed name. */
+export function newFolderPath(parent: string, name: string): string | null {
+  const trimmed = name.trim();
+  if (trimmed === "") return null;
+  return parent === "" ? trimmed : `${parent}/${trimmed}`;
+}
+
+/**
+ * Splice a draft folder row into the list, under its parent.
+ *
+ * This is what replaces the `window.prompt`. Renaming is already inline (click
+ * a row, type, Enter) and a modal for the adjacent gesture was the odd one
+ * out — it also blocks the thread, cannot be styled, and on a folder deep in
+ * the tree gives no clue *where* the folder will land. A draft row shows the
+ * answer: it sits at the position the real folder will occupy, indented under
+ * the right parent, with the cursor in it.
+ *
+ * Created only after the name is committed, so an abandoned draft leaves
+ * nothing behind — the alternative (create "untitled", then rename) litters
+ * the vault on Escape and fires two requests for one gesture.
+ *
+ * The draft goes **last among its parent's subtree** rather than in sort
+ * position, because it has no name yet to sort by and a row that jumps as you
+ * type is worse than one that appears at a predictable place.
+ */
+export function withDraftRow(rows: readonly TreeRow[], parent: string | null): TreeRow[] {
+  if (parent === null) return [...rows];
+  const draft: TreeRow = {
+    id: DRAFT_FOLDER_ID,
+    depth: parent === "" ? 1 : parent.split("/").length + 1,
+    hasKids: false,
+    expanded: false,
+    label: "",
+    kind: "module",
+    provenance: null,
+    meta: null,
+  };
+  // The root's draft goes after the whole tree; a folder's goes after the last
+  // row that is still inside that folder. `treeRows` emits a subtree
+  // contiguously, so "the last row at greater depth after the parent" is the
+  // end of it.
+  if (parent === "") return [...rows, draft];
+  const at = rows.findIndex((row) => row.id === `vfolder:${parent}`);
+  if (at === -1) return [...rows, draft];
+  let end = at + 1;
+  while (end < rows.length && (rows[end] as TreeRow).depth > (rows[at] as TreeRow).depth) end++;
+  return [...rows.slice(0, end), draft, ...rows.slice(end)];
+}
+
 // --- reducers -----------------------------------------------------------------------
 
 /**
@@ -157,11 +231,38 @@ export function deletesSelection(selectedId: string | null, target: { type: "not
   return false;
 }
 
-/** Notes delete directly; folders retain confirmation because they may contain many notes. */
+/**
+ * Notes delete directly; folders ask once, **in the menu**.
+ *
+ * Not a `window.confirm` — no gesture in this workspace opens a browser
+ * dialog any more. But not nothing either: `deleteFolder` is
+ * `fs.rm(recursive: true)` on a directory that may hold hundreds of notes,
+ * there is no undo, and the tree row shows no count, so a single stray click
+ * on a 300-note folder is unrecoverable. A note is one file the user can see
+ * the name of, which is why §#37 dropped its confirmation and this keeps one.
+ *
+ * The confirmation is {@link deleteItemLabel}: the same menu item, clicked
+ * twice, with the second click's label saying exactly what it will destroy.
+ */
 export function deleteNeedsConfirmation(target: { type: "note" | "folder" | "vault" }): boolean {
   return target.type === "folder";
 }
 
+/**
+ * The delete menu item's label — what pressing it *now* will do.
+ *
+ * One function so the label and the action cannot disagree: `Tree.tsx` reads
+ * the same `armed` flag to decide whether the next click deletes, and a menu
+ * item that says "Delete" but arms instead (or the reverse) is the classic
+ * version of this bug. Naming the folder in the armed state is the whole
+ * safety mechanism — it is the user's chance to notice they right-clicked the
+ * wrong row.
+ */
+export function deleteItemLabel(target: { type: "note" | "folder" | "vault" }, label: string, armed: boolean): string {
+  if (!deleteNeedsConfirmation(target)) return "Delete";
+  return armed ? `Delete “${label}” and everything in it` : "Delete…";
+}
+
 /**
  * Set the substring filter.
  *

package/src/web/shared/layout.ts

@@ -34,12 +34,75 @@ export function collideRadius(drawnSize: number): number {
 const DEFAULT_TICKS = 300;
 const DEFAULT_SEED = 1;
 const ALPHA_MIN = 0.001;
-const CONTAINS_REST = 90;
-const CONTAINS_STRENGTH = 0.02;
-const RELATION_DISTANCE = 170;
-const RELATION_STRENGTH = 0.05;
-const CHARGE_STRENGTH = -50;
-const CENTER_STRENGTH = 0.09;
+
+/**
+ * The force constants, as one **mutable** record.
+ *
+ * Mutable because picking these numbers is an act of taste, not of
+ * derivation: the difference between "one hairball" and "legible groups" is a
+ * ratio between containment cohesion, charge and centre gravity that is far
+ * easier to *see* than to reason about. The hidden tuner (`?sliders=1`, see
+ * `client/graph/tuner.model.ts` and docs/weave-workspace.md §15.7) writes here
+ * and re-lays out live, so a human can find the values by eye and they then
+ * get frozen back into {@link FORCE_DEFAULTS}.
+ *
+ * Determinism is untouched: every production and test path only ever *reads*
+ * this, so `computeLayout(model, { seed })` stays byte-identical. The tuner is
+ * the one writer, and it is unreachable without the query flag.
+ *
+ * ponytail: module-level mutable state, fine at one graph per page — thread it
+ * as a `LayoutOptions` field if a second concurrent consumer ever appears.
+ */
+export interface ForceConstants {
+  /** Rest length of a `contains` / `anchored-at` spring: a rosette's radius. */
+  containsRest: number;
+  /** Stiffness of that spring. This is what makes a group *be* a group. */
+  containsStrength: number;
+  /** Rest length of a `links-to` / `mentions` spring: the inter-group reach. */
+  relationDistance: number;
+  /** Stiffness of that spring. Weak, so associations bend without merging. */
+  relationStrength: number;
+  /** `forceManyBody` strength. Negative is repulsion. */
+  charge: number;
+  /**
+   * Distance past which charge is ignored (`forceManyBody.distanceMax`).
+   *
+   * A cap rather than `Infinity` is what keeps a strong charge from simply
+   * inflating the whole graph uniformly: beyond it, neighbours stop pushing
+   * and only the springs and centre gravity speak, so groups separate at
+   * local scale without the picture growing without bound.
+   */
+  chargeMax: number;
+  /** `forceX`/`forceY` pull toward the origin. The no-escape guarantee. */
+  center: number;
+}
+
+/**
+ * The live constants. See {@link ForceConstants} for why this is mutable.
+ *
+ * These values were **found by eye** through the `?sliders=1` tuner and then
+ * frozen here, which is the loop §15.7 describes working as intended. They are
+ * not derived and should not be "corrected" toward rounder numbers: the
+ * previous set (`containsStrength: 0.02`, `charge: -50`, `center: 0.09`) was
+ * defensible on paper and produced a single hairball on screen.
+ */
+export const FORCES: ForceConstants = {
+  containsRest: 55,
+  containsStrength: 0.12,
+  relationDistance: 50,
+  relationStrength: 0.07,
+  charge: -200,
+  chargeMax: 800,
+  center: 0.05,
+};
+
+/** The shipped values, for the tuner's reset and for a test to restore from. */
+export const FORCE_DEFAULTS: Readonly<ForceConstants> = { ...FORCES };
+
+/** Overwrite the live constants in place. The tuner's one write. */
+export function setForces(next: Partial<ForceConstants>): void {
+  Object.assign(FORCES, next);
+}
 
 export function isContainment(kind: EdgeKind): boolean {
   return kind === "contains" || kind === "anchored-at";
@@ -94,17 +157,19 @@ export function createForceSimulation<N extends SimulationNodeDatum & { id: stri
 ): Simulation<N, undefined> {
   const link = forceLink<N, { source: string | N; target: string | N; kind: EdgeKind }>(opts.links)
     .id((node) => node.id)
-    .distance((edge) => (isContainment(edge.kind) ? CONTAINS_REST : RELATION_DISTANCE))
-    .strength((edge) => (isContainment(edge.kind) ? CONTAINS_STRENGTH : RELATION_STRENGTH))
+    .distance((edge) => (isContainment(edge.kind) ? FORCES.containsRest : FORCES.relationDistance))
+    .strength((edge) => (isContainment(edge.kind) ? FORCES.containsStrength : FORCES.relationStrength))
     .iterations(2);
 
+  // Read out of `FORCES` here, at construction: a simulation is built fresh
+  // per layout run and per live mount, so a tuner write lands on the next one.
   return forceSimulation<N>(opts.nodes)
     .randomSource(lcg(opts.seed ?? DEFAULT_SEED))
-    .force("charge", forceManyBody<N>().strength(CHARGE_STRENGTH))
+    .force("charge", forceManyBody<N>().strength(FORCES.charge).distanceMax(FORCES.chargeMax))
     .force("link", link)
     .force("collide", forceCollide<N>((node) => node.r ?? COLLIDE_RADIUS).strength(1))
-    .force("x", forceX<N>(0).strength(CENTER_STRENGTH))
-    .force("y", forceY<N>(0).strength(CENTER_STRENGTH))
+    .force("x", forceX<N>(0).strength(FORCES.center))
+    .force("y", forceY<N>(0).strength(FORCES.center))
     .stop();
 }