@smartmemory/wiki-components 0.5.0 → 0.6.0

package/src/graph/components/wiki/GraphDocPane.jsx

@@ -0,0 +1,56 @@
+// WIKI-GRAPH-DOC-PANE-1: the right-hand read-only doc pane of the Graph page. The page owns which doc it shows (`doc=` in the URL)
+// and whether it is collapsed; this draws the note (the same markdown pieces NotePage uses) and a real link to the full page.
+import React from "react";
+import ReactMarkdown from "react-markdown";
+import { ChevronsLeft, ChevronsRight, X } from "lucide-react";
+import { Link, useNote } from "../../host";
+import ErrorBox from "../../../parts/ErrorBox";
+import Loading from "../../../parts/Loading";
+import TypeBadge from "../../../parts/TypeBadge";
+import { MD, MD_PLUGINS } from "../../../parts/Markdown";
+import { fmtDate, noteUrl } from "../../../lib";
+
+const ICON = "rounded-md border border-neutral-300 p-1 text-ink2 hover:text-ink";
+
+/** The doc `id` of `workspace`, read-only. `collapsed` leaves a thin rail with the show button. */
+export default function GraphDocPane({ workspace, id, collapsed, onToggle, onClose }) {
+  const q = useNote(workspace, id);
+  if (collapsed) {
+    return (
+      <aside aria-label="Doc" data-collapsed="1" className="pointer-events-auto flex w-10 shrink-0 flex-col items-center gap-2 border-l border-neutral-200 bg-ground py-3">
+        <button type="button" aria-label="Show doc" onClick={onToggle} className={ICON}><ChevronsLeft className="h-4 w-4" /></button>
+        <button type="button" aria-label="Close doc" onClick={onClose} className={ICON}><X className="h-4 w-4" /></button>
+      </aside>
+    );
+  }
+  const n = q.data?.note;
+  return (
+    <aside aria-label="Doc" data-collapsed="0" className="flex min-h-0 min-w-0 flex-1 flex-col border-l border-neutral-200 bg-ground">
+      <div className="flex items-center gap-2 border-b border-neutral-200 px-4 py-2">
+        <Link to={noteUrl(workspace, id)} className="text-[13px] text-blue-600 hover:underline">Open doc</Link>
+        <button type="button" aria-label="Hide doc" onClick={onToggle} className={`${ICON} ml-auto`}><ChevronsRight className="h-4 w-4" /></button>
+        <button type="button" aria-label="Close doc" onClick={onClose} className={ICON}><X className="h-4 w-4" /></button>
+      </div>
+      <div className="min-h-0 flex-1 overflow-y-auto px-4 py-4">
+        {q.isLoading && <Loading />}
+        {q.error && <ErrorBox error={q.error} />}
+        {n && (
+          <article>
+            <h2 className="text-xl font-bold tracking-tight text-ink">{n.title}</h2>
+            <div className="mt-2 flex flex-wrap items-center gap-3 text-xs text-ink2">
+              <TypeBadge type={n.kind} />
+              <span className="break-all font-mono text-neutral-500">{n.path}</span>
+              {n.mtime && <span>updated {fmtDate(n.mtime)}</span>}
+            </div>
+            <div className="mt-5">
+              {n.text == null
+                ? <p className="text-sm text-neutral-500">Only this note&apos;s title and place are indexed; its text is not.</p>
+                : <div className="note-body"><ReactMarkdown skipHtml remarkPlugins={MD_PLUGINS} components={MD}>{n.text}</ReactMarkdown></div>}
+              {n.text_truncated && <p className="mt-6 text-xs text-neutral-500">This note is long; the rest is not shown here.</p>}
+            </div>
+          </article>
+        )}
+      </div>
+    </aside>
+  );
+}

package/src/graph/components/wiki/GraphLegend.jsx

@@ -0,0 +1,119 @@
+import React, { useState } from "react";
+import { OTHER, OUTSIDE } from "../../lib/wikiGraph";
+import { UNMAPPED } from "../../lib/areaFamilies";
+import { graphTheme, hueFor } from "../../lib/graphTheme";
+
+// WIKI-GRAPH-3D-COLOR-SPHERES-1: the legend is the colour key, the filter and the drill control, for the 3D and the 2D view. A row
+// is a colour swatch, the group's name and doc count (one button: hide / show it, `aria-pressed`), and for a child folder an
+// "open" button that drills into it. Groups past the palette share the grey and are one "other: N areas" row, which a disclosure opens into one row per area.
+// WIKI-GRAPH-AREA-FAMILIES-1: groups that carry a `family` (colour by area) are rolled up instead: one row per family (swatch, name, "N areas", count) and
+// one "unmapped: N areas" row, each toggling all its areas and opening into one row per area. The groups stay per area, so `hide=` keeps area names.
+// State lives in the URL (`hide=`, `lv=`), never here, except whether the panel is folded and which disclosures are open.
+const LOOSE = new Set(["(no area)", "(root)"]);
+const PANEL = "pointer-events-auto rounded-lg border border-neutral-200/70 bg-ground/85 backdrop-blur";
+const LINK = "text-xs text-blue-600 hover:underline";
+
+/** `groups`: [{name, label?, count, color, path?}]; `hidden`: Set of group names; `onToggle(names[])` flips those names
+ *  (all hidden -> shown, else hidden); `onDrill(path)` opens a child folder; `onAll()` / `onNone()` the bulk commands. */
+export default function GraphLegend({ groups, hidden, scope = null, onToggle, onDrill, onAll, onNone }) {
+  const [open, setOpen] = useState(true);
+  const [showMore, setShowMore] = useState(false);
+  const [openFamilies, setOpenFamilies] = useState(() => new Set());
+  const byFamily = groups.some((g) => g.family);
+  const families = byFamily ? rollUp(groups) : [];
+  const rows = byFamily ? groups.filter((g) => LOOSE.has(g.name)) : groups.filter((g) => g.color !== OTHER || LOOSE.has(g.name));
+  const more = byFamily ? [] : groups.filter((g) => g.color === OTHER && !LOOSE.has(g.name)).sort((a, b) => b.count - a.count);
+  const moreCount = more.reduce((t, g) => t + g.count, 0);
+  const moreOff = more.length > 0 && more.every((g) => hidden.has(g.name));
+  const Swatch = ({ color: data, off }) => {
+    const color = hueFor(data); // the swatch is the node's colour in the mode in force (WIKI-GRAPH-LIGHT-HUES-1)
+    return <span className="inline-block h-2.5 w-2.5 shrink-0 rounded-full" style={{ background: off ? "transparent" : color, border: `1px solid ${color}` }} />;
+  };
+  const row = (g) => {
+    const off = hidden.has(g.name);
+    return (
+      <li key={g.name} className="flex items-center gap-1">
+        <button type="button" aria-pressed={!off} title={off ? "Show this group" : "Hide this group"} onClick={() => onToggle([g.name])}
+          className={`flex min-w-0 flex-1 items-center gap-2 text-left text-xs ${off ? "text-neutral-400 line-through" : "text-ink2 hover:text-ink"}`}>
+          <Swatch color={g.color} off={off} />
+          <span className="truncate">{g.label ?? g.name}</span><span className="ml-auto text-neutral-400">{g.count}</span>
+        </button>
+        {g.path != null && onDrill && (
+          <button type="button" aria-label={`Open ${g.label ?? g.name}`} title="Open this folder" onClick={() => onDrill(g.path)} className="text-xs text-neutral-500 hover:text-ink">›</button>
+        )}
+      </li>
+    );
+  };
+  const familyRow = (f) => {
+    const off = f.areas.every((g) => hidden.has(g.name)), isOpen = openFamilies.has(f.name);
+    const label = f.unmapped ? `unmapped: ${f.areas.length} ${f.areas.length === 1 ? "area" : "areas"}` : f.name;
+    return (
+      <li key={f.name}>
+        <div className="flex items-center gap-1">
+          <button type="button" aria-pressed={!off} title={off ? "Show this family" : "Hide this family"} onClick={() => onToggle(f.areas.map((g) => g.name))}
+            className={`flex min-w-0 flex-1 items-center gap-2 text-left text-xs ${off ? "text-neutral-400 line-through" : "text-ink2 hover:text-ink"}`}>
+            <Swatch color={f.color} off={off} />
+            <span className="truncate">{label}</span>
+            {!f.unmapped && <span className="text-neutral-400">{f.areas.length} {f.areas.length === 1 ? "area" : "areas"}</span>}
+            <span className="ml-auto text-neutral-400">{f.count}</span>
+          </button>
+          <button type="button" aria-expanded={isOpen} aria-label={`${isOpen ? "Hide" : "Show"} the areas of ${f.unmapped ? "unmapped" : f.name}`}
+            onClick={() => setOpenFamilies(new Set(isOpen ? [...openFamilies].filter((n) => n !== f.name) : [...openFamilies, f.name]))}
+            className="text-xs text-neutral-500 hover:text-ink">{isOpen ? "▾" : "▸"}</button>
+        </div>
+        {isOpen && <ul className="mt-0.5 space-y-0.5 pl-4" aria-label={`Areas of ${f.unmapped ? "unmapped" : f.name}`}>{f.areas.map(row)}</ul>}
+      </li>
+    );
+  };
+  return (
+    <section className={`${PANEL} absolute bottom-10 left-3 flex max-h-[45%] w-60 max-w-[60%] flex-col`} aria-label="Colour legend" data-testid="graph-legend">
+      <div className="flex items-center gap-2 px-3 py-2">
+        <h2 className="text-xs font-semibold uppercase tracking-wide text-neutral-500">{scope ? `In ${scope}` : "Legend"}</h2>
+        <button type="button" onClick={onAll} className={`${LINK} ml-auto`}>all</button>
+        <button type="button" onClick={onNone} className={LINK}>none</button>
+        <button type="button" aria-expanded={open} aria-label={open ? "Fold legend" : "Unfold legend"} onClick={() => setOpen(!open)} className="text-xs text-neutral-500 hover:text-ink">{open ? "–" : "+"}</button>
+      </div>
+      {open && (
+        <div className="min-h-0 overflow-y-auto border-t border-neutral-200/70 px-3 py-2">
+          <ul className="space-y-0.5" aria-label="Legend">
+            {families.map(familyRow)}
+            {rows.map(row)}
+            {more.length > 0 && (
+              <li>
+                <div className="flex items-center gap-1">
+                  <button type="button" aria-pressed={!moreOff} onClick={() => onToggle(more.map((g) => g.name))}
+                    className={`flex min-w-0 flex-1 items-center gap-2 text-left text-xs ${moreOff ? "text-neutral-400 line-through" : "text-ink2 hover:text-ink"}`}>
+                    <Swatch color={OTHER} off={moreOff} />
+                    <span className="truncate">other: {more.length} {more.length === 1 ? "area" : "areas"}</span><span className="ml-auto text-neutral-400">{moreCount}</span>
+                  </button>
+                  <button type="button" aria-expanded={showMore} aria-label={showMore ? "Hide the other areas" : "Show the other areas"} onClick={() => setShowMore(!showMore)}
+                    className="text-xs text-neutral-500 hover:text-ink">{showMore ? "▾" : "▸"}</button>
+                </div>
+                {showMore && <ul className="mt-0.5 space-y-0.5 pl-4" aria-label="Other areas">{more.map(row)}</ul>}
+              </li>
+            )}
+          </ul>
+          <dl className="mt-2 space-y-0.5 border-t border-neutral-200/70 pt-2 text-[11px] text-neutral-500" aria-label="Shapes">
+            <div className="flex items-center gap-2"><dt className="inline-block h-2.5 w-2.5 rounded-full bg-neutral-400" /><dd>doc</dd></div>
+            <div className="flex items-center gap-2"><dt className="inline-block h-2.5 w-2.5 rounded-full border border-neutral-400" style={{ background: "rgba(148,163,184,0.3)" }} /><dd>folder (glass shell)</dd></div>
+            <div className="flex items-center gap-2"><dt className="inline-block h-2.5 w-2.5 rounded-full bg-neutral-400" style={{ boxShadow: `0 0 0 2px ${graphTheme().halo}` }} /><dd>hub (halo)</dd></div>
+            {groups.some((g) => g.color === OUTSIDE) && <div className="flex items-center gap-2"><dt className="inline-block h-2.5 w-2.5 rounded-full" style={{ background: hueFor(OUTSIDE) }} /><dd>outside this folder</dd></div>}
+          </dl>
+        </div>
+      )}
+    </section>
+  );
+}
+
+/** Groups carrying a `family` as one entry per family, biggest first, the unmapped one last: `{name, color, count, areas (biggest first), unmapped}`. */
+function rollUp(groups) {
+  const by = new Map();
+  for (const g of groups) {
+    if (!g.family) continue;
+    const f = by.get(g.family) || { name: g.family, color: g.color, count: 0, areas: [], unmapped: g.family === UNMAPPED };
+    f.count += g.count; f.areas.push(g);
+    by.set(g.family, f);
+  }
+  for (const f of by.values()) f.areas.sort((a, b) => b.count - a.count || String(a.name).localeCompare(String(b.name)));
+  return [...by.values()].sort((a, b) => a.unmapped - b.unmapped || b.count - a.count || a.name.localeCompare(b.name));
+}

package/src/graph/components/wiki/GraphLevelPicker.jsx

@@ -0,0 +1,35 @@
+import React, { useState } from "react";
+import { formatRange, toggleLevel } from "../../lib/graphLevels";
+
+const CHIP = "rounded-md border px-2 py-1 text-[13px] hover:text-ink";
+const on = "border-blue-500 text-ink", off = "border-neutral-300 text-ink2";
+
+/** WIKI-GRAPH-LEVELS-3D-1: the level picker. One chip per level (1..`max`) that shows a depth RANGE, plus "All docs" (the flat
+ *  graph). `range` is [from, to] (the `lr=` value); `flat` means "All docs" is on, and then no level chip is pressed. A level
+ *  chip toggles that level in the range (`toggleLevel`): a click that would leave a gap snaps to the covering range and says
+ *  so. `onRange([from, to])` is told the new range (and leaves the flat graph); `onAll()` turns "All docs" on. A page-level
+ *  component, so the later command palette can absorb it. */
+export default function GraphLevelPicker({ range, max, flat, onRange, onAll }) {
+  const [note, setNote] = useState("");
+  if (!(max >= 1)) return null;
+  const pick = (k) => {
+    if (flat) { setNote(""); onRange([k, k]); return; }
+    const r = toggleLevel(range, k);
+    setNote(r.snapped ? `Levels show as a range: snapped to ${formatRange(r.range)}.` : "");
+    onRange(r.range);
+  };
+  return (
+    <div role="group" aria-label="Graph levels" className="flex flex-wrap items-center gap-1.5">
+      <span className="text-xs text-neutral-500">Levels</span>
+      {Array.from({ length: max }, (_, i) => i + 1).map((k) => {
+        const pressed = !flat && k >= range[0] && k <= range[1];
+        return (
+          <button key={k} type="button" aria-pressed={pressed} aria-label={`Level ${k}`} onClick={() => pick(k)} className={`${CHIP} ${pressed ? on : off}`}>{k}</button>
+        );
+      })}
+      <button type="button" aria-pressed={flat} onClick={() => { setNote(""); onAll(); }} className={`${CHIP} ${flat ? on : off}`}>All docs</button>
+      <span className="sr-only" role="status" aria-live="polite">{note}</span>
+      {note && <span aria-hidden="true" className="text-xs text-neutral-500">{note}</span>}
+    </div>
+  );
+}

package/src/graph/components/wiki/graph/FilterChips.jsx

@@ -0,0 +1,45 @@
+// WIKI-GRAPH-EXPLORE-1b-SHELL (part A): the filter chips under the omnibox: one pill per step, the count, the "ignored" notice and
+// the hint when the stack leaves nothing. Controlled: the page passes the explore state and its run and does the removing. Not wired in yet.
+import { emptyHint, ignoredNotice, sentenceOf } from "../../../lib/graphExplore";
+
+const PILL = "inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs";
+const X = "rounded-full px-1 text-neutral-500 hover:bg-neutral-200 hover:text-ink";
+
+/** Props: `state` (explore state), `run` (explorer.run result or null), `idx` + `explorer` (names, the empty hint), `ignored`
+ *  (count dropped from a newer link), `onRemove(i)`, `onClear()`, `onRemoveLens(i)`. A path lens is drawn (the page lights it) and has a remove
+ *  button; a highlight lens is decoded and round-trips but nothing draws it: an outlined pill titled "not drawn yet". Renders nothing when there is nothing to show. */
+export default function FilterChips({ state, run = null, idx = null, explorer = null, ignored = 0, onRemove, onClear, onRemoveLens }) {
+  const { chips, lenses, countText } = sentenceOf(state, run, idx);
+  const notice = ignoredNotice(ignored);
+  if (!chips.length && !lenses.length && !notice) return null;
+  const hint = explorer && chips.length ? emptyHint(explorer, state) : null;
+  return (
+    <div className="mt-2 space-y-1" data-testid="graph-chips">
+      {(chips.length > 0 || lenses.length > 0) && (
+        <div className="flex flex-wrap items-center gap-1">
+          {chips.map((c, i) => (
+            <span key={`${i}:${c.text}`} className={`${PILL} border-neutral-300 bg-neutral-100 text-ink`} title={c.unsupported ? "This filter is not supported yet" : undefined} data-unsupported={c.unsupported || undefined}>
+              {c.text}
+              <button type="button" aria-label={`Remove filter "${c.text}"`} onClick={() => onRemove(i)} className={X}>×</button>
+            </span>
+          ))}
+          {lenses.map((l, i) => (
+            <span key={`lens:${i}:${l.text}`} className={`${PILL} border-dashed border-neutral-400 bg-white text-neutral-600`} title={l.path ? "Shortest path, lit on the graph" : "not drawn yet"} data-lens data-path={l.path || undefined} data-no-path={l.path && l.text.startsWith("no path") ? "" : undefined}>
+              {l.text}
+              {l.path && onRemoveLens && <button type="button" aria-label={`Remove lens "${l.text}"`} onClick={() => onRemoveLens(i)} className={X}>×</button>}
+            </span>
+          ))}
+          {chips.length > 0 && <button type="button" onClick={onClear} className="text-xs text-neutral-500 underline hover:text-ink">Clear filters</button>}
+        </div>
+      )}
+      {countText && chips.length > 0 && <p className="text-xs text-neutral-500" data-testid="graph-chip-count">{countText}</p>}
+      {notice && <p className="text-xs text-amber-700" role="status">{notice}</p>}
+      {hint && (
+        <p className="text-xs text-neutral-600" data-testid="graph-empty-hint">
+          {hint.text}{" "}
+          <button type="button" aria-label={`Remove filter "${chips[hint.index].text}" (hint)`} onClick={() => onRemove(hint.index)} className="underline hover:text-ink">Remove it</button>
+        </p>
+      )}
+    </div>
+  );
+}

package/src/graph/components/wiki/graph/Omnibox.jsx

@@ -0,0 +1,74 @@
+// WIKI-GRAPH-EXPLORE-1b-SHELL (part A): the Graph page's find box as an omnibox. Controlled: the page owns the text, the rows
+// (graphShell omniRows) and what a row does; this draws the combobox, runs the keys and the active row. Not wired in yet.
+import { useEffect, useId, useRef, useState } from "react";
+import { moveCursor } from "../../../lib/graphShell";
+
+const FALLBACK_INPUT = "rounded-md border border-neutral-300 bg-white px-2 py-1 text-[13px] text-ink";
+
+/** Props: `term` / `onTerm(text)`; `rows` (omniRows); `open` / `onOpenChange(bool)` (the list); `countText` + `foundCount` (the live
+ *  match line under the box); `onAction(row)` for fly / step / clear rows (a verb row fills the box itself and keeps focus);
+ *  `onBackspaceEmpty()` (remove the last chip); `inputClassName`. Keys: Up/Down move the active row; Enter picks it, else the
+ *  first row that has an action; Esc with text clears the text and closes the list (and stops there); Backspace on an empty box
+ *  calls `onBackspaceEmpty`. `focusSignal`: a counter, each bump focuses the box. */
+export default function Omnibox({ term, onTerm, rows, open, onOpenChange, countText = "", foundCount = null, onAction, onBackspaceEmpty, focusSignal = 0, inputClassName = FALLBACK_INPUT }) {
+  const [cursor, setCursor] = useState(-1);
+  const input = useRef(null);
+  const listId = useId();
+  const rowsKey = rows.map((r) => r.key).join("|");
+  useEffect(() => setCursor(-1), [rowsKey]);
+  useEffect(() => { if (focusSignal) input.current?.focus(); }, [focusSignal]); // the page asks for focus (the doc card's Path to…)
+  const shown = open && rows.length > 0;
+
+  const pick = (row) => {
+    if (!row?.action) return;
+    if (row.action.type === "verb") { onTerm(row.action.fill); onOpenChange(true); input.current?.focus(); return; }
+    onAction(row);
+  };
+  const onKeyDown = (e) => {
+    if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+      if (!rows.length) return;
+      e.preventDefault();
+      onOpenChange(true);
+      setCursor(moveCursor(rows, cursor, e.key === "ArrowDown" ? 1 : -1));
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      pick(rows[cursor]?.action ? rows[cursor] : rows.find((r) => r.action)); // the live rows: row 0 is the top title match for the live term
+    } else if (e.key === "Escape" && term) {
+      e.preventDefault(); e.stopPropagation();
+      onTerm(""); onOpenChange(false);
+    } else if (e.key === "Backspace" && term === "") {
+      onBackspaceEmpty?.();
+    }
+  };
+
+  return (
+    <div className="relative">
+      <input
+        ref={input} role="combobox" aria-expanded={shown} aria-controls={listId} aria-autocomplete="list"
+        aria-activedescendant={shown && cursor >= 0 ? `${listId}-${cursor}` : undefined}
+        value={term} onChange={(e) => { onTerm(e.target.value); onOpenChange(true); }} onKeyDown={onKeyDown}
+        placeholder="Find a doc by title" aria-label="Find a doc by title" className={`${inputClassName} w-full`}
+      />
+      <p className="mt-1 min-h-[1.25rem] text-xs text-neutral-500" aria-live="polite" data-testid="graph-find-count" data-graph-find-count={foundCount === null ? "" : foundCount}>
+        {countText}
+      </p>
+      {shown && (
+        <ul id={listId} role="listbox" aria-label="Matching docs and filters" className="mt-1 overflow-hidden rounded-md border border-neutral-200 bg-white shadow-lg">
+          {rows.map((r, i) => (
+            <li key={r.key} id={`${listId}-${i}`} role="option" aria-selected={i === cursor} data-kind={r.kind}>
+              {r.action ? (
+                <button type="button" aria-label={r.label} onClick={() => pick(r)}
+                  className={`flex w-full items-baseline justify-between gap-2 px-3 py-1.5 text-left text-[13px] text-ink hover:bg-neutral-100 ${i === cursor ? "bg-neutral-100" : ""}`}>
+                  <span className="truncate">{r.label}</span>
+                  {r.detail && <span className="shrink-0 text-xs text-neutral-500">{r.detail}</span>}
+                </button>
+              ) : (
+                <p className="px-3 py-1.5 text-[13px] text-neutral-500">{r.label}</p>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/graph/components/wiki/graph/badges.js

@@ -0,0 +1,46 @@
+// WIKI-GRAPH-FOCUS-HOPS-1: the hub guard's "+N" badges on the overlay, shared by both canvases. A lit node whose hop ring
+// was capped (layoutEngine hopRings `capped`) gets a small pill beside it naming how many neighbours it hides; a click on
+// the pill expands that node alone (the canvas's `onBadge`). Positions are CSS pixels; the boxes come back for picking.
+export const BADGE_H = 16;
+const FONT = "600 11px ui-sans-serif, system-ui, sans-serif";
+const FILL = "#1f2937", TEXT = "#f9fafb", EDGE = "#f59e0b";
+
+/** Where each badge goes: `items` [{i, n, x, y, r}] (node index, hidden count, screen centre, drawn radius in px) ->
+ *  [{i, n, text, x, y, w, h}] boxes, left edge just right of the node. `measure(text)` gives a text width in px. */
+export function badgeBoxes(items, measure = (t) => 7 * t.length) {
+  return items.map(({ i, n, x, y, r }) => {
+    const text = `+${n}`, w = Math.ceil(measure(text)) + 10;
+    return { i, n, text, x: x + r + 3, y: y - BADGE_H / 2, w, h: BADGE_H };
+  });
+}
+
+/** The node index whose badge box holds (x, y), or -1. */
+export function badgeAt(boxes, x, y) {
+  for (const b of boxes || []) if (x >= b.x && x <= b.x + b.w && y >= b.y && y <= b.y + b.h) return b.i;
+  return -1;
+}
+
+/** Draw the badges for `items` on the overlay context (after drawOverlay, which clears it). Returns their boxes. */
+export function drawBadges(ctx, items, dpr) {
+  if (!items.length) return [];
+  if (!ctx) return badgeBoxes(items);
+  ctx.save();
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  ctx.font = FONT;
+  const boxes = badgeBoxes(items, (t) => ctx.measureText?.(t)?.width || 7 * t.length);
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+  for (const b of boxes) {
+    ctx.fillStyle = FILL;
+    ctx.strokeStyle = EDGE;
+    ctx.lineWidth = 1.5;
+    ctx.beginPath();
+    if (ctx.roundRect) ctx.roundRect(b.x, b.y, b.w, b.h, b.h / 2); else ctx.rect(b.x, b.y, b.w, b.h);
+    ctx.fill();
+    ctx.stroke();
+    ctx.fillStyle = TEXT;
+    ctx.fillText(b.text, b.x + b.w / 2, b.y + b.h / 2 + 0.5);
+  }
+  ctx.restore();
+  return boxes;
+}

package/src/graph/components/wiki/graph/bubbles3d.js

@@ -0,0 +1,95 @@
+// WIKI-GRAPH-CLUSTER-NORELAYOUT-1, restyled by WIKI-GRAPH-CLUSTER-REGROUP-1 (owner 2026-10-21): the 3D group outlines, drawn
+// only with the "Group outlines" toggle. One InstancedMesh of spheres, FrontSide only (one flat layer a bubble, no stacked
+// inner volume), at OUTLINE_STYLE.fill with no depth write, so the docs in a bubble stay sharp; the thin ring is drawn on the
+// 2D overlay (drawBubbleLabels `outlines`) at the bubble's projected silhouette, with the group's name above it. Fed by
+// groupBubbles (lib/groupBubbles.js); nothing here touches the layout.
+import { Color, DynamicDrawUsage, FrontSide, IcosahedronGeometry, InstancedMesh, MeshBasicMaterial } from "three";
+import { project } from "../../../lib/graph3d";
+import { OUTLINE_STYLE } from "../../../lib/groupBubbles";
+import { graphTheme } from "../../../lib/graphTheme";
+
+/** Bubbles in `scene`. update(bubbles) with [{centre, radius, color}] (colour as 0xRRGGBB); clear(); dispose(). */
+export function createBubbles3d(scene) {
+  const geo = new IcosahedronGeometry(1, 2);
+  const face = new MeshBasicMaterial({ color: 0xffffff, transparent: true, opacity: OUTLINE_STYLE.fill, depthWrite: false, side: FrontSide });
+  const tint = new Color();
+  let cap = 0, meshes = [];
+  const make = (n) => {
+    for (const m of meshes) { scene.remove(m); m.dispose(); }
+    cap = Math.max(8, n);
+    meshes = [face].map((mat) => {
+      const m = new InstancedMesh(geo, mat, cap);
+      m.instanceMatrix.setUsage(DynamicDrawUsage);
+      m.count = 0;
+      m.frustumCulled = false;
+      m.renderOrder = -1; // before the edges and arrowheads among the see-through objects
+      m.userData.bubbles = true;
+      scene.add(m);
+      return m;
+    });
+  };
+  make(0);
+  return {
+    get count() { return meshes[0].count; },
+    meshes: () => meshes,
+    update(bubbles) {
+      if (bubbles.length > cap) make(bubbles.length);
+      for (const m of meshes) {
+        const a = m.instanceMatrix.array;
+        bubbles.forEach((b, k) => {
+          const o = 16 * k, r = b.radius;
+          a.fill(0, o, o + 16);
+          a[o] = a[o + 5] = a[o + 10] = r;
+          a[o + 12] = b.centre[0]; a[o + 13] = b.centre[1]; a[o + 14] = b.centre[2]; a[o + 15] = 1;
+          m.setColorAt(k, tint.setHex(b.color));
+        });
+        m.count = bubbles.length;
+        m.instanceMatrix.needsUpdate = true;
+        if (m.instanceColor) m.instanceColor.needsUpdate = true;
+      }
+    },
+    clear() { for (const m of meshes) m.count = 0; },
+    dispose() {
+      for (const m of meshes) { scene.remove(m); m.dispose(); }
+      geo.dispose(); face.dispose();
+    },
+  };
+}
+
+/** Where each bubble's name goes this frame: [{text, x, y, cx, cy, r, color}] in CSS px: the name above the bubble's projected
+ *  top, the projected centre and silhouette radius for the outline ring; bubbles behind the camera are skipped. `frame` is
+ *  the base's frame() ({vp, focal}). */
+export function bubbleLabels(bubbles, frame, w, h) {
+  const n = bubbles.length;
+  if (!n) return [];
+  const xyz = new Float32Array(3 * n), rad = new Float32Array(n), scr = new Float32Array(3 * n), rpx = new Float32Array(n);
+  bubbles.forEach((b, k) => { xyz.set(b.centre, 3 * k); rad[k] = b.radius; });
+  project(xyz, rad, n, frame.vp, frame.focal, w, h, scr, rpx);
+  const out = [];
+  for (let k = 0; k < n; k++) if (scr[3 * k + 2] > 1e-6) out.push({ text: bubbles[k].group, x: scr[3 * k], y: scr[3 * k + 1] - rpx[k] - 4, cx: scr[3 * k], cy: scr[3 * k + 1], r: rpx[k], color: bubbles[k].color });
+  return out;
+}
+
+/** The bubble names on the overlay context (after drawOverlay, which clears it); with `outlines`, each bubble's thin ring too. */
+export function drawBubbleLabels(ctx, labels, dpr, { outlines = false } = {}) {
+  if (!ctx || !labels.length) return;
+  ctx.save();
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  if (outlines) {
+    ctx.lineWidth = OUTLINE_STYLE.width;
+    for (const l of labels) {
+      if (!(l.r > 0)) continue;
+      const c = l.color ?? 0xffffff;
+      ctx.strokeStyle = `rgba(${(c >> 16) & 255},${(c >> 8) & 255},${c & 255},${OUTLINE_STYLE.line})`;
+      ctx.beginPath();
+      ctx.arc(l.cx, l.cy, l.r, 0, 2 * Math.PI);
+      ctx.stroke();
+    }
+  }
+  ctx.font = "600 12px ui-sans-serif, system-ui, sans-serif";
+  ctx.textAlign = "center";
+  ctx.textBaseline = "bottom";
+  ctx.fillStyle = graphTheme().bubbleLabel;
+  for (const l of labels) ctx.fillText(l.text, l.x, l.y);
+  ctx.restore();
+}

package/src/graph/components/wiki/graph/canvasBase.js

@@ -0,0 +1,138 @@
+// WIKI-GRAPH-OBSIDIAN-1: the base layer without WebGL, on Canvas2D: the same edges and nodes as pixiBase.js, over the same
+// worker layout and under the same overlay, so every interaction works the same. Chosen over Pixi's own Canvas renderer
+// (build-report.md "fallback decision"): no second Pixi renderer chunk, no dependence on Pixi's GPU detection, and this
+// drawing (edges as one path, nodes batched by colour, culled to the view) is today's, proven at 5k docs. The cost is a
+// full redraw on every changed frame, so a pan on a large graph is slower than on the GPU.
+import { ARROW_CAP, arrowsFor, fillArrows } from "../../../lib/graphArrows";
+import { CORE, HALO, LOOK, SHELL_ALPHA, drawRadius } from "../../../lib/graphView";
+import { edgeAlphaFor, linksInView } from "../../../lib/wikiGraph";
+import { LINK_BUCKETS, linkBuckets } from "../../../lib/linkWeight";
+import { graphTheme } from "../../../lib/graphTheme";
+
+const ARROW_ALPHA = 0.75;
+const ARROW_MARGIN = 200; // heads are culled to the view grown by this many px, so a small pan reuses the path
+
+const hex = (c) => `#${c.toString(16).padStart(6, "0")}`;
+
+export function createCanvasBase(canvas, { w, h, dpr, background }) {
+  let ctx = null;
+  try { ctx = canvas.getContext("2d"); } catch { ctx = null; } // jsdom has no canvas: nothing is drawn, nothing breaks
+  let size = { w, h, dpr }, sc = null, byColour = [];
+  const tris = new Float32Array(6 * ARROW_CAP);
+  let arrowPath = null, arrowAt = null, arrowStale = true;
+  let alphaAt = null, alphaStale = true, alphaNow = 0.1; // edge alpha from the links in view, redone on stale or a real move
+
+  const restyle = (s) => {
+    const lists = new Map();
+    for (let i = 0; i < s.n; i++) {
+      let l = lists.get(s.colors[i]);
+      if (!l) lists.set(s.colors[i], (l = []));
+      l.push(i);
+    }
+    byColour = [...lists.entries()].map(([c, l]) => [hex(c), Uint32Array.from(l)]);
+  };
+  const place = () => {
+    canvas.width = Math.round(size.w * size.dpr);
+    canvas.height = Math.round(size.h * size.dpr);
+    canvas.style.width = `${size.w}px`;
+    canvas.style.height = `${size.h}px`;
+  };
+  place();
+
+  return {
+    kind: "canvas",
+    setData(s) { sc = s; restyle(s); arrowStale = true; alphaStale = true; },
+    setStyle(s) { sc = s; restyle(s); arrowStale = true; alphaStale = true; },
+    setVisible(s) { sc = s; arrowStale = true; alphaStale = true; },
+    setPositions(s) { sc = s; arrowStale = true; alphaStale = true; },
+    setView(s) { sc = s; },
+    resize(w2, h2, dpr2) { size = { w: w2, h: h2, dpr: dpr2 }; arrowStale = true; alphaStale = true; place(); },
+    render() {
+      if (!ctx || !sc) return false;
+      const { w: W, h: H, dpr: D } = size;
+      const { pos, view: v, mask, sizes, big, visPairs, visCount } = sc;
+      ctx.setTransform(D, 0, 0, D, 0, 0);
+      ctx.fillStyle = background;
+      ctx.fillRect(0, 0, W, H);
+      ctx.setTransform(D * v.k, 0, 0, D * v.k, D * v.x, D * v.y);
+      if (alphaStale || !alphaAt || alphaAt.k !== v.k || Math.abs(alphaAt.x - v.x) > ARROW_MARGIN / 2 || Math.abs(alphaAt.y - v.y) > ARROW_MARGIN / 2) {
+        alphaStale = false;
+        alphaAt = { x: v.x, y: v.y, k: v.k };
+        alphaNow = edgeAlphaFor(linksInView(pos, visPairs, visCount, v, W, H), W, H);
+      }
+      ctx.strokeStyle = `rgba(${graphTheme().linkRgb},${alphaNow})`;
+      const bk = sc.visBuckets || linkBuckets(null, visCount); // one pass a width bucket, 1 px up to LINK_BUCKETS px (linkWeight.js)
+      for (let w = 1; w <= LINK_BUCKETS; w++) {
+        if (bk.start[w] === bk.start[w + 1]) continue;
+        ctx.lineWidth = w / v.k;
+        ctx.beginPath();
+        for (let j = bk.start[w]; j < bk.start[w + 1]; j++) {
+          const e = 2 * bk.idx[j], a = visPairs[e], b = visPairs[e + 1];
+          ctx.moveTo(pos[2 * a], pos[2 * a + 1]);
+          ctx.lineTo(pos[2 * b], pos[2 * b + 1]);
+        }
+        ctx.stroke();
+      }
+      if (arrowsFor(sc.visibleN ?? sc.n, v.k, big)) { // heads: one cached path of triangles in world units (graphArrows.js)
+        const moved = !arrowAt || arrowAt.k !== v.k || Math.abs(arrowAt.x - v.x) > ARROW_MARGIN / 2 || Math.abs(arrowAt.y - v.y) > ARROW_MARGIN / 2;
+        if (arrowStale || moved) {
+          arrowStale = false;
+          arrowAt = { x: v.x, y: v.y, k: v.k };
+          const t = fillArrows(sc, v, W, H, tris, ARROW_MARGIN);
+          arrowPath = t ? new Path2D() : null;
+          for (let i = 0; i < 6 * t; i += 6) {
+            arrowPath.moveTo(tris[i], tris[i + 1]);
+            arrowPath.lineTo(tris[i + 2], tris[i + 3]);
+            arrowPath.lineTo(tris[i + 4], tris[i + 5]);
+            arrowPath.closePath();
+          }
+        }
+        if (arrowPath) { ctx.fillStyle = `rgba(${graphTheme().linkRgb},${ARROW_ALPHA})`; ctx.fill(arrowPath); }
+      }
+      const x0 = -v.x / v.k, y0 = -v.y / v.k, x1 = (W - v.x) / v.k, y1 = (H - v.y) / v.k, m = 25 / v.k;
+      // Looks (graphView LOOK, the same as 3D): a hub gets a white disc a little bigger than itself (its halo rim), a folder is a
+      // translucent shell at full radius round a solid core.
+      const looks = sc.looks;
+      const visible = (i, x, y) => mask[i] && x >= x0 - m && x <= x1 + m && y >= y0 - m && y <= y1 + m;
+      if (looks) {
+        ctx.fillStyle = graphTheme().halo;
+        ctx.beginPath();
+        for (let i = 0; i < sc.n; i++) {
+          if (looks[i] !== LOOK.HUB) continue;
+          const x = pos[2 * i], y = pos[2 * i + 1];
+          if (!visible(i, x, y)) continue;
+          const r = HALO * drawRadius(sizes[i], v.k, big);
+          ctx.moveTo(x + r, y); ctx.arc(x, y, r, 0, 2 * Math.PI);
+        }
+        ctx.fill();
+      }
+      for (const [colour, list] of byColour) {
+        ctx.fillStyle = colour;
+        if (looks) {
+          ctx.globalAlpha = SHELL_ALPHA;
+          ctx.beginPath();
+          for (const i of list) {
+            if (looks[i] !== LOOK.FOLDER) continue;
+            const x = pos[2 * i], y = pos[2 * i + 1];
+            if (!visible(i, x, y)) continue;
+            const r = drawRadius(sizes[i], v.k, big);
+            ctx.moveTo(x + r, y); ctx.arc(x, y, r, 0, 2 * Math.PI);
+          }
+          ctx.fill();
+          ctx.globalAlpha = 1;
+        }
+        ctx.beginPath();
+        for (const i of list) {
+          const x = pos[2 * i], y = pos[2 * i + 1];
+          if (!visible(i, x, y)) continue;
+          const r = drawRadius(sizes[i], v.k, big) * (looks && looks[i] === LOOK.FOLDER ? CORE : 1);
+          if (r * v.k < 2.5) ctx.rect(x - r, y - r, 2 * r, 2 * r); // a square that small reads as a dot and is cheaper
+          else { ctx.moveTo(x + r, y); ctx.arc(x, y, r, 0, 2 * Math.PI); }
+        }
+        ctx.fill();
+      }
+      return true;
+    },
+    destroy() { sc = null; },
+  };
+}