@medicine-wheel/app 0.6.4 → 0.7.0

package/app/graph/page.tsx

@@ -98,10 +98,34 @@ export default function GraphPage() {
   const [graph, setGraph] = useState<MWGraphData>({ nodes: [], links: [] });
   const [selectedNode, setSelectedNode] = useState<MWGraphNode | null>(null);
   const [focusedNodeId, setFocusedNodeId] = useState<string | undefined>(undefined);
+  /**
+   * Scope is not focus.
+   *
+   * `focusedNodeId` zooms the viewport at a node and leaves all 205 mounted —
+   * useful, and not an answer to "I cannot navigate", because the field is still
+   * there behind the zoom. `scopeId` replaces the graph with one node's
+   * neighbourhood, so the canvas holds only what was asked for. Two names
+   * because they are two questions; collapsing them would make the control
+   * silently mean different things depending on how the page was entered.
+   */
+  const [scopeId, setScopeId] = useState<string | null>(null);
+  // 1, not 2. With the chronicle root at degree 82, depth 2 from any episode
+  // used to return the whole corpus — see the route's DEFAULT_DEPTH.
+  const [scopeDepth, setScopeDepth] = useState(1);
+  const [scopeMeta, setScopeMeta] = useState<{
+    count: number;
+    truncated: boolean;
+    hubs: { id: string; name: string; degree: number; reason: string; unexpanded: number }[];
+    rootName: string | null;
+  } | null>(null);
+  const [storeTotal, setStoreTotal] = useState<number | null>(null);
   const [highlightDirection, setHighlightDirection] = useState<DirectionParam | undefined>(undefined);
   const [radialSnap, setRadialSnap] = useState<"off" | "ring" | "sector">("off");
   const [loading, setLoading] = useState(true);
-  const [showLabels, setShowLabels] = useState(true);
+  // `null` means "nobody has chosen" — the default then follows the crowding
+  // (see labelsAutoSuppressed). Once the user touches the toggle their choice
+  // sticks, including across a scope change.
+  const [showLabels, setShowLabels] = useState<boolean | null>(null);
   const [animationsEnabled, setAnimationsEnabled] = useState(
     DEFAULT_GRAPH_ANIMATION_ENABLED,
   );
@@ -166,22 +190,54 @@ export default function GraphPage() {
 
   const loadData = useCallback(async () => {
     try {
-      const [nodesRes, edgesRes] = await Promise.all([fetch("/api/nodes"), fetch("/api/edges")]);
+      // Scoped and whole-wheel are different questions, not the same question
+      // with a filter. `focusedNodeId` already existed and only zooms the
+      // viewport — every one of the 205 nodes stays mounted, so "focus" was
+      // never a way to look at less. Scope replaces the data.
+      if (scopeId) {
+        const res = await fetch(
+          `/api/nodes/${encodeURIComponent(scopeId)}/web?depth=${scopeDepth}`,
+        );
+        if (!res.ok) {
+          toast.error(
+            res.status === 404
+              ? "That node is not in the wheel."
+              : "Could not read that neighbourhood.",
+          );
+          setScopeId(null);
+          return;
+        }
+        const web = await res.json();
+        setGraph(buildGraphData(web.nodes ?? [], web.edges ?? []));
+        setScopeMeta({
+          count: web.count ?? 0,
+          truncated: Boolean(web.truncated),
+          hubs: web.hubs ?? [],
+          rootName: web.root?.name ?? null,
+        });
+        return;
+      }
+
+      const [nodesRes, edgesRes] = await Promise.all([fetch("/api/nodes?limit=all"), fetch("/api/edges?limit=all")]);
       const nodesResponse = await nodesRes.json();
       const edgesData: RelationalEdge[] = await edgesRes.json();
 
-      // API returns { nodes: [...], provider: '...', count: N }
+      // API returns { nodes: [...], provider: '...', count: N, total, truncated }
       const nodesData: RelationalNode[] = Array.isArray(nodesResponse)
         ? nodesResponse
         : nodesResponse.nodes || [];
 
       setGraph(buildGraphData(nodesData, edgesData));
+      setScopeMeta(null);
+      setStoreTotal(
+        Array.isArray(nodesResponse) ? nodesData.length : (nodesResponse.total ?? nodesData.length),
+      );
     } catch {
       toast.error("Failed to load graph data");
     } finally {
       setLoading(false);
     }
-  }, []);
+  }, [scopeId, scopeDepth]);
 
   useEffect(() => {
     loadData();
@@ -204,12 +260,31 @@ export default function GraphPage() {
     const params = new URLSearchParams(window.location.search);
     const node = params.get("node");
     if (node) setFocusedNodeId(node);
+    // ?scope=<id> arrives from an episode page's "Open in graph" and means
+    // "show me this and its neighbours", not "zoom at this".
+    const scope = params.get("scope");
+    if (scope) {
+      setScopeId(scope);
+      setFocusedNodeId(scope);
+    }
     const direction = params.get("direction");
     if (direction && (DIRECTION_NAMES as readonly string[]).includes(direction)) {
       setHighlightDirection(direction as DirectionParam);
     }
   }, []);
 
+  // Escape leaves the neighbourhood and returns the whole wheel. It is the only
+  // way out that needs no aiming, which matters when the reason you scoped was
+  // that you could not find anything.
+  useEffect(() => {
+    if (!scopeId) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setScopeId(null);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [scopeId]);
+
   // Surface the deep-linked node in the side panel once data arrives.
   useEffect(() => {
     if (!focusedNodeId || graph.nodes.length === 0) return;
@@ -217,10 +292,58 @@ export default function GraphPage() {
     if (node) setSelectedNode(node);
   }, [focusedNodeId, graph.nodes]);
 
-  const graphData = useMemo<MWGraphData>(
-    () => (focusedNodeId ? { ...graph, focusedNodeId } : graph),
-    [graph, focusedNodeId],
-  );
+  /**
+   * The node you asked about must be findable in the picture.
+   *
+   * Before this, arriving from an episode page put your episode somewhere in a
+   * field of identical dots — the graph knew which node you meant (it zoomed at
+   * it) and gave you no way to see which one it was once you panned. Marking is
+   * done here rather than in `graph-viz` because `MedicineWheelNode` already
+   * reads `size`, `color` and `opacity` off each node; the renderer needs no
+   * new concept, only better data.
+   *
+   * Hubs are dimmed rather than hidden. The chronicle root genuinely is in your
+   * neighbourhood — every episode belongs to it — but it is context, not the
+   * subject, and drawing it at full weight makes the one true container compete
+   * with the thing you were looking at.
+   */
+  const graphData = useMemo<MWGraphData>(() => {
+    const hubIds = new Set((scopeMeta?.hubs ?? []).map((h) => h.id));
+    const marked =
+      scopeId || hubIds.size > 0
+        ? {
+            ...graph,
+            nodes: graph.nodes.map((n) => {
+              if (n.id === scopeId) {
+                return {
+                  ...n,
+                  size: (n.size ?? 8) * 1.9,
+                  color: "#ffd75e",
+                  opacity: 1,
+                };
+              }
+              if (hubIds.has(n.id)) {
+                return { ...n, size: (n.size ?? 8) * 1.25, opacity: 0.45 };
+              }
+              return n;
+            }),
+          }
+        : graph;
+
+    return focusedNodeId ? { ...marked, focusedNodeId } : marked;
+  }, [graph, focusedNodeId, scopeId, scopeMeta]);
+
+  /**
+   * Labels are legible up to a point and then they are texture.
+   *
+   * At 83 nodes crushed into one quadrant the labels stacked into unreadable
+   * bands — worse than absent, because they cost the whole canvas its clarity
+   * while conveying nothing. Off past the threshold, and the existing toggle
+   * still wins: this sets the default, it does not take the control away.
+   */
+  const LABEL_LEGIBLE_UP_TO = 35;
+  const labelsAutoSuppressed = graph.nodes.length > LABEL_LEGIBLE_UP_TO;
+  const labelsVisible = showLabels ?? !labelsAutoSuppressed;
 
   useEffect(() => {
     layoutStoreRef.current = layoutStore;
@@ -430,10 +553,15 @@ export default function GraphPage() {
           </div>
           <div className="flex flex-wrap gap-2">
             <button
-              onClick={() => setShowLabels(!showLabels)}
-              className={`min-h-11 px-3 py-1.5 rounded text-sm ${showLabels ? "bg-white/10" : "bg-white/5"}`}
+              onClick={() => setShowLabels(!labelsVisible)}
+              className={`min-h-11 px-3 py-1.5 rounded text-sm ${labelsVisible ? "bg-white/10" : "bg-white/5"}`}
+              title={
+                showLabels === null && labelsAutoSuppressed
+                  ? `Off by default above ${LABEL_LEGIBLE_UP_TO} nodes — they overlap into bands`
+                  : undefined
+              }
             >
-              Labels {showLabels ? "ON" : "OFF"}
+              Labels {labelsVisible ? "ON" : "OFF"}
             </button>
             <button
               onClick={() =>
@@ -450,6 +578,64 @@ export default function GraphPage() {
           </div>
         </div>
 
+        {scopeId && (
+          <div className="mb-3 rounded-xl border border-yellow-400/30 bg-yellow-400/5 px-3 py-2 text-sm">
+            {/* min-w-0 on the growing child, so a long chronicle id truncates
+                instead of pushing the depth control and the exit off-screen —
+                the banner clipped its own warning at this width before. */}
+            <div className="flex flex-wrap items-center gap-x-3 gap-y-2">
+              <span className="min-w-0 flex-1 text-gray-300">
+                <strong className="text-yellow-300">
+                  {scopeMeta?.count ?? graph.nodes.length}
+                </strong>{" "}
+                nodes, {scopeDepth} {scopeDepth === 1 ? "hop" : "hops"} from{" "}
+                <span className="text-gray-100">{scopeMeta?.rootName ?? scopeId}</span>
+              </span>
+              <label className="inline-flex shrink-0 items-center gap-1.5 text-xs text-gray-400">
+                Depth
+                <select
+                  value={scopeDepth}
+                  onChange={(e) => setScopeDepth(Number(e.target.value))}
+                  className="rounded bg-white/5 px-1.5 py-0.5 text-gray-200"
+                  aria-label="Neighbourhood depth"
+                >
+                  {[1, 2, 3, 4, 5, 6].map((d) => (
+                    <option key={d} value={d}>
+                      {d}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <button
+                onClick={() => setScopeId(null)}
+                className="min-h-8 shrink-0 rounded bg-white/5 px-2 py-1 text-xs hover:bg-white/10 inline-flex items-center gap-1.5"
+              >
+                <X className="h-3.5 w-3.5" /> Whole wheel
+                <span className="text-gray-500">(Esc)</span>
+              </button>
+            </div>
+
+            {/* Say what was held back. A neighbourhood that quietly stopped at a
+                container is the same class of lie as a list that quietly
+                stopped at 100 rows. */}
+            {(scopeMeta?.hubs?.length ?? 0) > 0 && (
+              <p className="mt-1.5 text-xs text-gray-500">
+                {scopeMeta!.hubs.map((h) => (
+                  <span key={h.id} className="mr-3 inline-block">
+                    <span className="text-gray-400">{h.name}</span> holds {h.degree} relations —
+                    shown, not expanded{h.unexpanded > 0 ? ` (${h.unexpanded} beyond it)` : ""}
+                  </span>
+                ))}
+              </p>
+            )}
+            {scopeMeta?.truncated && (
+              <p className="mt-1 text-xs text-gray-500">
+                stopped at the depth limit — there is more further out
+              </p>
+            )}
+          </div>
+        )}
+
         <div className="flex flex-col lg:flex-row gap-4 lg:gap-6">
           <div className="relative flex-1 rounded-xl border border-white/10 overflow-hidden">
             {!loading && graph.nodes.length > 0 && (
@@ -477,7 +663,7 @@ export default function GraphPage() {
                 data={graphData}
                 height={graphHeight}
                 darkMode
-                showNodeLabels={showLabels}
+                showNodeLabels={labelsVisible}
                 showMiniMap={!isMobile}
                 animationsEnabled={animationsEnabled}
                 nodePositions={activeLayout.positions}
@@ -633,6 +819,14 @@ export default function GraphPage() {
                   <div><span className="text-xs text-gray-500">Type</span><p className="capitalize">{selectedNode.type}</p></div>
                   {selectedNode.direction && <div><span className="text-xs text-gray-500">Direction</span><p className="capitalize">{selectedNode.direction}</p></div>}
                   <div><span className="text-xs text-gray-500">ID</span><p className="text-xs text-gray-400 font-mono break-all">{selectedNode.id}</p></div>
+                  {scopeId !== selectedNode.id && (
+                    <button
+                      onClick={() => setScopeId(selectedNode.id)}
+                      className="inline-flex w-full items-center justify-center gap-2 rounded-md bg-yellow-400/15 px-3 py-2 text-sm text-yellow-200 hover:bg-yellow-400/25"
+                    >
+                      <Route className="h-4 w-4" /> Show only its neighbourhood
+                    </button>
+                  )}
                   <Link
                     href={`/nodes?node=${encodeURIComponent(selectedNode.id)}`}
                     className="inline-flex w-full items-center justify-center gap-2 rounded-md bg-white/10 px-3 py-2 text-sm text-white hover:bg-white/15"
@@ -644,9 +838,25 @@ export default function GraphPage() {
             )}
 
             <div className="rounded-xl border border-white/10 p-4">
-              <h3 className="text-sm font-semibold text-gray-400 mb-3">Graph Stats</h3>
+              <h3 className="text-sm font-semibold text-gray-400 mb-3">
+                Graph Stats
+                {/* This panel read "100 Nodes / 100 Relations" against a store of
+                    205 and 191 until 2026-09-03, because the page fetched without
+                    a limit and took the provider's default page in silence. A
+                    count with nothing to compare it to cannot be doubted, which
+                    is what made it a lie rather than a number. */}
+                {scopeId && <span className="ml-2 font-normal text-yellow-300/80">scoped</span>}
+              </h3>
               <div className="grid grid-cols-2 gap-3 text-center">
-                <div><p className="text-2xl font-bold">{graph.nodes.length}</p><p className="text-xs text-gray-500">Nodes</p></div>
+                <div>
+                  <p className="text-2xl font-bold">{graph.nodes.length}</p>
+                  <p className="text-xs text-gray-500">
+                    Nodes
+                    {storeTotal !== null && graph.nodes.length < storeTotal && (
+                      <span className="text-gray-600"> of {storeTotal}</span>
+                    )}
+                  </p>
+                </div>
                 <div><p className="text-2xl font-bold">{graph.links.length}</p><p className="text-xs text-gray-500">Relations</p></div>
                 <div><p className="text-2xl font-bold">{ceremoniedCount}</p><p className="text-xs text-gray-500">Ceremonied</p></div>
                 <div><p className="text-2xl font-bold">{directionCount}</p><p className="text-xs text-gray-500">Directions</p></div>

package/app/nodes/page.tsx

@@ -50,13 +50,16 @@ export default function NodesPage() {
   const loadNodes = useCallback(async () => {
     setLoading(true);
     try {
-      const params = new URLSearchParams();
+      // The list is client-side paginated below, so it needs the whole store.
+      // Without this the route applies its 100-row default and the table silently
+      // ends at 100 of 205 with no page control to reveal the rest.
+      const params = new URLSearchParams({ limit: "all" });
       if (filterType !== "all") params.set("type", filterType);
       if (filterDirection !== "all") params.set("direction", filterDirection);
 
       const [nodesRes, edgesRes] = await Promise.all([
         fetch(`/api/nodes?${params.toString()}`),
-        fetch("/api/edges"),
+        fetch("/api/edges?limit=all"),
       ]);
       const nodesResponse = await nodesRes.json();
       const edgesData: RelationalEdge[] = edgesRes.ok ? await edgesRes.json() : [];

package/app/relations/page.tsx

@@ -64,7 +64,7 @@ export default function RelationsPage() {
   const loadData = useCallback(async () => {
     setLoading(true);
     try {
-      const [nodesRes, edgesRes] = await Promise.all([fetch("/api/nodes"), fetch("/api/edges")]);
+      const [nodesRes, edgesRes] = await Promise.all([fetch("/api/nodes?limit=all"), fetch("/api/edges?limit=all")]);
       const nodesResponse = await nodesRes.json();
       const edgesData = await edgesRes.json();
       const nodesData: NodeRecord[] = Array.isArray(nodesResponse) ? nodesResponse : (nodesResponse.nodes || []);

package/components/navigation.tsx

@@ -13,6 +13,7 @@ import { WorkspacesPanel, WORKSPACES, type Workspace } from "@/components/worksp
 const NAV_ITEMS = [
   { href: "/", label: "Wheel", color: "var(--mw-east)" },
   { href: "/graph", label: "Graph", color: "var(--mw-primary)" },
+  { href: "/episodes", label: "Episodes", color: "var(--mw-node-ancestor)" },
   { href: "/nodes", label: "Nodes", color: "var(--mw-node-land)" },
   { href: "/relations", label: "Relations", color: "var(--mw-node-future)" },
   { href: "/ceremonies", label: "Ceremonies", color: "var(--mw-south)" },

package/lib/api-paging.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared paging contract for the wheel's read routes.
+ *
+ * The provider's `getAllNodes()` / `getAllEdges()` default to 100 rows. A bare
+ * `GET /api/nodes` therefore returned 100 of the store's 205 nodes, and the graph
+ * page — which sends no parameters — drew that window while its own panel read
+ * "100 Nodes / 100 Relations". Of the 100 it drew, 53 had no drawable edge,
+ * because 27 of the 100 delivered edges pointed at nodes that were never sent.
+ *
+ * Nothing was broken. Every layer did what it was told. The lie was that no layer
+ * ever said how much it had left out.
+ *
+ * So both routes accept the same `limit`, and both report enough for a caller to
+ * know it holds a page: `?limit=all` for the whole store, `?limit=<n>` for n.
+ * This lives in `lib/` rather than in either route because a second hand-written
+ * copy of a validation rule is how the two drift apart — the same defect this
+ * repo just removed from `PersonRole`.
+ */
+import { NextResponse } from "next/server";
+
+/** The provider's own default page size, restated so a route can report honestly. */
+export const DEFAULT_PAGE_SIZE = 100;
+
+/** Sentinel meaning "the whole store", distinct from "no limit given". */
+export const LIMIT_ALL = "all";
+
+/**
+ * Returns the requested page size, `null` for "everything", or a 400 response.
+ *
+ * An unparseable limit is refused rather than coerced. Falling back to the
+ * default on bad input would reintroduce the silent truncation this parameter
+ * exists to close, and would do it precisely when a caller had tried to ask.
+ */
+export function parseLimit(raw: string | null): number | null | NextResponse {
+  if (raw === null || raw === "") return DEFAULT_PAGE_SIZE;
+  if (raw === LIMIT_ALL) return null;
+
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return NextResponse.json(
+      {
+        error: `Invalid limit: ${raw} — nothing was returned.`,
+        hint: `limit must be a positive integer, or "${LIMIT_ALL}" for the whole store.`,
+      },
+      { status: 400 },
+    );
+  }
+  return parsed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/app",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Medicine Wheel — Interactive visual layer for Indigenous relational research with Four Directions, ceremonies, and narrative arcs",
   "bin": {
     "mw": "dist/cli/mw.js",
@@ -85,29 +85,29 @@
     "release:major": "npm run version:major && npm run publish:all && npm run release:commit"
   },
   "dependencies": {
-    "@medicine-wheel/ceremonial-diary": "^0.6.4",
-    "@medicine-wheel/ceremony-protocol": "^0.6.4",
-    "@medicine-wheel/community-review": "^0.6.4",
-    "@medicine-wheel/consent-lifecycle": "^0.6.4",
-    "@medicine-wheel/creative-orientation": "^0.6.4",
-    "@medicine-wheel/data-store": "^0.6.4",
-    "@medicine-wheel/data-store-postgres": "^0.6.4",
-    "@medicine-wheel/fire-keeper": "^0.6.4",
-    "@medicine-wheel/github-ceremony": "^0.6.4",
-    "@medicine-wheel/graph-viz": "^0.6.4",
-    "@medicine-wheel/importance-unit": "^0.6.4",
-    "@medicine-wheel/mcp": "^4.6.4",
-    "@medicine-wheel/narrative-cluster": "^0.6.4",
-    "@medicine-wheel/narrative-engine": "^0.6.4",
-    "@medicine-wheel/ontology-core": "^0.6.4",
-    "@medicine-wheel/perception-layer": "^0.6.4",
-    "@medicine-wheel/prompt-decomposition": "^0.6.4",
-    "@medicine-wheel/relational-index": "^0.6.4",
-    "@medicine-wheel/relational-query": "^0.6.4",
-    "@medicine-wheel/session-reader": "^0.6.4",
-    "@medicine-wheel/storage-provider": "^0.6.4",
-    "@medicine-wheel/transformation-tracker": "^0.6.4",
-    "@medicine-wheel/ui-components": "^0.6.4",
+    "@medicine-wheel/ceremonial-diary": "^0.7.0",
+    "@medicine-wheel/ceremony-protocol": "^0.7.0",
+    "@medicine-wheel/community-review": "^0.7.0",
+    "@medicine-wheel/consent-lifecycle": "^0.7.0",
+    "@medicine-wheel/creative-orientation": "^0.7.0",
+    "@medicine-wheel/data-store": "^0.7.0",
+    "@medicine-wheel/data-store-postgres": "^0.7.0",
+    "@medicine-wheel/fire-keeper": "^0.7.0",
+    "@medicine-wheel/github-ceremony": "^0.7.0",
+    "@medicine-wheel/graph-viz": "^0.7.0",
+    "@medicine-wheel/importance-unit": "^0.7.0",
+    "@medicine-wheel/mcp": "^4.7.0",
+    "@medicine-wheel/narrative-cluster": "^0.7.0",
+    "@medicine-wheel/narrative-engine": "^0.7.0",
+    "@medicine-wheel/ontology-core": "^0.7.0",
+    "@medicine-wheel/perception-layer": "^0.7.0",
+    "@medicine-wheel/prompt-decomposition": "^0.7.0",
+    "@medicine-wheel/relational-index": "^0.7.0",
+    "@medicine-wheel/relational-query": "^0.7.0",
+    "@medicine-wheel/session-reader": "^0.7.0",
+    "@medicine-wheel/storage-provider": "^0.7.0",
+    "@medicine-wheel/transformation-tracker": "^0.7.0",
+    "@medicine-wheel/ui-components": "^0.7.0",
     "@neondatabase/serverless": "^0.10.0",
     "@xyflow/react": "^12.3.0",
     "clsx": "^2.1.1",