Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

fix(wiki): keep the hub locked in the centre of the memory map

Harald45a4ac2a69d1
diff --git a/jarvis/ui/web/frontend/src/components/wiki/WikiGraph.tsx b/jarvis/ui/web/frontend/src/components/wiki/WikiGraph.tsx
index 6d7c31064e..6c9af8a662 100644
--- a/jarvis/ui/web/frontend/src/components/wiki/WikiGraph.tsx
+++ b/jarvis/ui/web/frontend/src/components/wiki/WikiGraph.tsx
@@ -815,6 +815,7 @@ export function WikiGraph({ onNodeClick, highlightSlug }: WikiGraphProps): JSX.E
width={winSize.w}
height={winSize.h}
highlightSlug={highlightSlug}
+ pivotSlug={data?.hub ?? null}
onNodeClick={selectNode}
resetSignal={resetTick}
nodeLabel={nodeLabel}
diff --git a/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.pin.test.tsx b/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.pin.test.tsx
new file mode 100644
index 0000000000..9bf0f51c73
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.pin.test.tsx
@@ -0,0 +1,82 @@
+/**
+ * The hub stays nailed to the origin so the map turns around a point that
+ * does not move. The camera looks at that origin; other pages orbit it.
+ */
+import { render } from "@testing-library/react";
+import type { ForwardedRef } from "react";
+import { forwardRef } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("react-force-graph-3d", () => ({
+ default: forwardRef(function ForceGraph3DStub(
+ _props: Record<string, unknown>,
+ _ref: ForwardedRef<unknown>,
+ ) {
+ return <canvas data-testid="force-graph-3d" />;
+ }),
+}));
+
+vi.mock("@/hooks/useGraphOrbit", () => ({
+ useGraphOrbit: vi.fn(),
+}));
+
+import { WikiGraph3D } from "@/components/wiki/WikiGraph3D";
+import type { RenderNode } from "@/lib/wikiGraph";
+
+function node(id: string, pos: { x: number; y: number; z: number }): RenderNode {
+ return {
+ id,
+ kind: "entity",
+ title: id,
+ backlinkCount: 0,
+ radius: 2,
+ colour: "#fff",
+ ...pos,
+ };
+}
+
+describe("WikiGraph3D hub pin", () => {
+ it("nails the hub to the origin and translates the rest with it", () => {
+ const nodes = [
+ node("me", { x: 40, y: -10, z: 20 }),
+ node("spotify", { x: 140, y: -10, z: 20 }),
+ ];
+
+ render(
+ <WikiGraph3D
+ graphData={{ nodes, links: [] }}
+ width={400}
+ height={300}
+ pivotSlug="me"
+ onNodeClick={vi.fn()}
+ resetSignal={0}
+ nodeLabel={() => ""}
+ linkLabel={() => ""}
+ />,
+ );
+
+ expect(nodes[0]).toMatchObject({
+ x: 0, y: 0, z: 0, fx: 0, fy: 0, fz: 0,
+ });
+ expect(nodes[1]).toMatchObject({ x: 100, y: 0, z: 0 });
+ });
+
+ it("leaves every page free when the vault has no hub", () => {
+ const nodes = [node("a", { x: 8, y: 9, z: 10 })];
+
+ render(
+ <WikiGraph3D
+ graphData={{ nodes, links: [] }}
+ width={400}
+ height={300}
+ onNodeClick={vi.fn()}
+ resetSignal={0}
+ nodeLabel={() => ""}
+ linkLabel={() => ""}
+ />,
+ );
+
+ expect(nodes[0]).toMatchObject({ x: 8, y: 9, z: 10 });
+ expect(nodes[0].fx).toBeUndefined();
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.tsx b/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.tsx
index 0e5e959773..0c3c8c0810 100644
--- a/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.tsx
+++ b/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.tsx
@@ -46,10 +46,13 @@ import {
createLivelinessForce,
type LivelyNode,
} from "@/lib/graphForces";
-import { carryOverPositions } from "@/lib/graphContinuity";
+import { carryOverPositions, pinPivotAtOrigin } from "@/lib/graphContinuity";
import type { Vec3 } from "@/lib/graphCamera";
import { useGraphOrbit, type GraphCameraApi } from "@/hooks/useGraphOrbit";
+/** The hub is nailed here; the camera looks here. Never a live, moving node. */
+const PINNED_ORIGIN: Vec3 = { x: 0, y: 0, z: 0 };
+
/** Sphere radius in graph units for a node whose size score is 1.0. */
const NODE_REL_SIZE = 3;
@@ -268,8 +271,9 @@ export function WikiGraph3D({
const [frameSignal, setFrameSignal] = useState(0);
const reframe = useCallback(() => setFrameSignal((tick) => tick + 1), []);
- // The live node object for the pivot: the simulation writes its position
- // onto this very object, so handing it to the orbit lets the camera follow.
+ // The live node object for the hub — liveliness and drag-lock read it.
+ // The camera does not: it looks at the origin the hub is pinned to, so a
+ // settling layout cannot walk the main page off the middle of the panel.
const pivotNode = useMemo(
() => (pivotSlug ? (graphData.nodes.find((n) => n.id === pivotSlug) ?? null) : null),
[graphData.nodes, pivotSlug],
@@ -280,7 +284,7 @@ export function WikiGraph3D({
graphRef: graphRef as RefObject<GraphCameraApi | undefined>,
hostRef,
nodes: graphData.nodes as Array<Partial<Vec3>>,
- pivot: pivotNode as Partial<Vec3> | null,
+ pivot: pivotSlug ? PINNED_ORIGIN : null,
frameSignal,
});
@@ -411,12 +415,29 @@ export function WikiGraph3D({
const data = useMemo(() => {
const previous = previousNodesRef.current;
if (previous !== graphData.nodes) {
- const pivot = previous.find((n) => n.id === pivotSlugRef.current);
+ const pivot = previous.find((n) => n.id === pivotSlug);
carryOverPositions(previous, graphData.nodes, graphData.links, pivot ?? {});
previousNodesRef.current = graphData.nodes;
}
+ // First generation, every refresh, and a late-arriving hub: the main
+ // page sits at the origin and stays there. The rest of the cloud is
+ // translated with it so the layout they already have is not torn up.
+ pinPivotAtOrigin(graphData.nodes, pivotSlug);
return graphData;
- }, [graphData]);
+ }, [graphData, pivotSlug]);
+
+ const holdHub = useCallback((node: NodeObject<RenderNode>): void => {
+ if (node.id !== pivotSlugRef.current) return;
+ node.fx = 0;
+ node.fy = 0;
+ node.fz = 0;
+ node.x = 0;
+ node.y = 0;
+ node.z = 0;
+ node.vx = 0;
+ node.vy = 0;
+ node.vz = 0;
+ }, []);
return (
// The renderer paints into its own canvas; this wrapper is what the camera
@@ -458,6 +479,8 @@ export function WikiGraph3D({
linkDirectionalParticleColor={() => PARTICLE_COLOUR}
onNodeClick={handleNodeClick}
onNodeHover={handleNodeHover}
+ onNodeDrag={holdHub}
+ onNodeDragEnd={holdHub}
// Drag to rotate, wheel to zoom, right-drag to pan — the mapping people
// already know from every other 3D viewer.
controlType="orbit"
diff --git a/jarvis/ui/web/frontend/src/hooks/useGraphOrbit.ts b/jarvis/ui/web/frontend/src/hooks/useGraphOrbit.ts
index a5b8a8160e..43ea5c28b5 100644
--- a/jarvis/ui/web/frontend/src/hooks/useGraphOrbit.ts
+++ b/jarvis/ui/web/frontend/src/hooks/useGraphOrbit.ts
@@ -106,10 +106,10 @@ export interface GraphOrbitOptions {
/** Live node array; the simulation writes x/y/z onto these objects. */
nodes: readonly Partial<Vec3>[];
/**
- * The node to turn around, when the map has one — the user's own page. The
- * simulation keeps moving it, so the object is read fresh every frame and
- * the camera follows; absent, the orbit turns around the network's trimmed
- * mean as before.
+ * The point to turn around, when the map has one — the user's own page,
+ * pinned at the origin. The camera looks at this point directly (no ease)
+ * so the hub stays dead-centre of the panel while everything else sweeps
+ * past. Absent, the orbit turns around the network's trimmed mean.
*/
pivot?: Partial<Vec3> | null;
/** Bump to re-frame: new data, a settled layout, the Center button. */
@@ -249,15 +249,20 @@ export function useGraphOrbit({
resyncRef.current = false;
}
- // Where the turn is centred: the pivot page, read live because the
- // layout keeps moving it (settling, new data), else the framed middle.
- // Eased, never set — a re-frame or a settling pivot glides the view.
+ // Where the turn is centred. A pinned hub is looked at directly so it
+ // stays dead-centre of the panel — easing after it is what let it
+ // wander last time. Without a hub, a re-frame still glides.
const pivotNode = pivotRef.current;
- const wanted: Vec3 =
- pivotNode && Number.isFinite(pivotNode.x)
- ? { x: pivotNode.x ?? 0, y: pivotNode.y ?? 0, z: pivotNode.z ?? 0 }
- : (targetRef.current?.centre ?? centreRef.current);
- centreRef.current = approachPoint(centreRef.current, wanted, elapsed, CENTRE_TAU_MS);
+ if (pivotNode && Number.isFinite(pivotNode.x)) {
+ centreRef.current = {
+ x: pivotNode.x ?? 0,
+ y: pivotNode.y ?? 0,
+ z: pivotNode.z ?? 0,
+ };
+ } else {
+ const wanted = targetRef.current?.centre ?? centreRef.current;
+ centreRef.current = approachPoint(centreRef.current, wanted, elapsed, CENTRE_TAU_MS);
+ }
const orbit = orbitRef.current;
if (targetRef.current) {
diff --git a/jarvis/ui/web/frontend/src/lib/graphContinuity.test.ts b/jarvis/ui/web/frontend/src/lib/graphContinuity.test.ts
index a1ba167a00..f7750d5bd3 100644
--- a/jarvis/ui/web/frontend/src/lib/graphContinuity.test.ts
+++ b/jarvis/ui/web/frontend/src/lib/graphContinuity.test.ts
@@ -4,7 +4,7 @@
*/
import { describe, expect, it } from "vitest";
-import { carryOverPositions, type ContinuityNode } from "@/lib/graphContinuity";
+import { carryOverPositions, pinPivotAtOrigin, type ContinuityNode } from "@/lib/graphContinuity";
describe("carryOverPositions", () => {
it("keeps every page that was already placed exactly where it was", () => {
@@ -60,3 +60,36 @@ describe("carryOverPositions", () => {
expect(next[0].x).toBeUndefined();
});
});
+
+describe("pinPivotAtOrigin", () => {
+ it("nails the hub to the origin and translates the rest with it", () => {
+ const nodes: ContinuityNode[] = [
+ { id: "me", x: 40, y: -10, z: 20, vx: 1, vy: 2, vz: 3 },
+ { id: "spotify", x: 140, y: -10, z: 20 },
+ { id: "calendar", x: 40, y: 90, z: 20 },
+ ];
+ expect(pinPivotAtOrigin(nodes, "me")).toBe(true);
+ expect(nodes[0]).toMatchObject({
+ x: 0, y: 0, z: 0, vx: 0, vy: 0, vz: 0, fx: 0, fy: 0, fz: 0,
+ });
+ expect(nodes[1]).toMatchObject({ x: 100, y: 0, z: 0 });
+ expect(nodes[2]).toMatchObject({ x: 0, y: 100, z: 0 });
+ });
+
+ it("pins a hub that has no position yet, and leaves the others unset", () => {
+ const nodes: ContinuityNode[] = [{ id: "me" }, { id: "a" }];
+ expect(pinPivotAtOrigin(nodes, "me")).toBe(true);
+ expect(nodes[0]).toMatchObject({
+ x: 0, y: 0, z: 0, fx: 0, fy: 0, fz: 0,
+ });
+ expect(nodes[1].x).toBeUndefined();
+ });
+
+ it("does nothing when there is no hub, or the hub is not on the map", () => {
+ const nodes: ContinuityNode[] = [{ id: "a", x: 5, y: 6, z: 7 }];
+ expect(pinPivotAtOrigin(nodes, null)).toBe(false);
+ expect(pinPivotAtOrigin(nodes, "missing")).toBe(false);
+ expect(nodes[0]).toMatchObject({ x: 5, y: 6, z: 7 });
+ expect(nodes[0].fx).toBeUndefined();
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/lib/graphContinuity.ts b/jarvis/ui/web/frontend/src/lib/graphContinuity.ts
index c1c2e8ab30..3b3bf80c22 100644
--- a/jarvis/ui/web/frontend/src/lib/graphContinuity.ts
+++ b/jarvis/ui/web/frontend/src/lib/graphContinuity.ts
@@ -24,6 +24,13 @@ export interface ContinuityNode {
vx?: number;
vy?: number;
vz?: number;
+ /**
+ * d3-force pin. When set, the simulation writes `x = fx` (and the same
+ * for y/z) every tick and zeroes the velocity — the node cannot drift.
+ */
+ fx?: number;
+ fy?: number;
+ fz?: number;
/** The liveliness force's applied offset — travels with the position. */
__lively?: { x: number; y: number; z: number };
}
@@ -121,3 +128,46 @@ export function carryOverPositions(
}
return { kept, seated: newcomers.length };
}
+
+/**
+ * Nail the hub to the origin so the map turns around a point that does not
+ * move. Other pages are translated with it, so a layout they already have is
+ * kept; d3-force's `fx`/`fy`/`fz` then holds the hub there every tick.
+ *
+ * Without this the charge and link forces keep shoving the hub around, the
+ * camera eases after it, and the main page wanders off the middle of the
+ * panel — the opposite of what the orbit is for.
+ *
+ * @returns true when a hub was found and pinned
+ */
+export function pinPivotAtOrigin(
+ nodes: ContinuityNode[],
+ pivotId: string | null | undefined,
+): boolean {
+ if (!pivotId) return false;
+ const pivot = nodes.find((node) => node.id === pivotId);
+ if (!pivot) return false;
+
+ const dx = Number.isFinite(pivot.x) ? (pivot.x as number) : 0;
+ const dy = Number.isFinite(pivot.y) ? (pivot.y as number) : 0;
+ const dz = Number.isFinite(pivot.z) ? (pivot.z as number) : 0;
+
+ if (dx !== 0 || dy !== 0 || dz !== 0) {
+ for (const node of nodes) {
+ if (Number.isFinite(node.x)) node.x = (node.x as number) - dx;
+ if (Number.isFinite(node.y)) node.y = (node.y as number) - dy;
+ if (Number.isFinite(node.z)) node.z = (node.z as number) - dz;
+ }
+ }
+
+ pivot.x = 0;
+ pivot.y = 0;
+ pivot.z = 0;
+ pivot.vx = 0;
+ pivot.vy = 0;
+ pivot.vz = 0;
+ pivot.fx = 0;
+ pivot.fy = 0;
+ pivot.fz = 0;
+ return true;
+}
diff --git a/jarvis/ui/web/frontend/src/lib/wikiGraph.ts b/jarvis/ui/web/frontend/src/lib/wikiGraph.ts
index c4b8038f2b..8963613b1a 100644
--- a/jarvis/ui/web/frontend/src/lib/wikiGraph.ts
+++ b/jarvis/ui/web/frontend/src/lib/wikiGraph.ts
@@ -55,8 +55,14 @@ export interface RenderNode extends WikiGraphNode {
colour: string;
x?: number;
y?: number;
+ z?: number;
vx?: number;
vy?: number;
+ vz?: number;
+ /** d3-force pin — the hub is nailed to the origin so the map turns around it. */
+ fx?: number;
+ fy?: number;
+ fz?: number;
}
/**