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.

perf(wiki): a memory map nobody is watching stops drawing

Harald78368be0a86b
diff --git a/jarvis/ui/web/frontend/src/components/ultrawiki/EntityGraph3D.tsx b/jarvis/ui/web/frontend/src/components/ultrawiki/EntityGraph3D.tsx
index 757b7617da..6d2e9abb3e 100644
--- a/jarvis/ui/web/frontend/src/components/ultrawiki/EntityGraph3D.tsx
+++ b/jarvis/ui/web/frontend/src/components/ultrawiki/EntityGraph3D.tsx
@@ -32,6 +32,7 @@ import { CENTRING_STRENGTH, createCentringForce } from "@/lib/graphForces";
import { endpointId as endpointKey } from "@/lib/wikiGraph";
import type { Vec3 } from "@/lib/graphCamera";
import { useGraphOrbit, type GraphCameraApi } from "@/hooks/useGraphOrbit";
+import { useGraphAwake, type GraphEngineApi } from "@/hooks/useGraphAwake";
import { useWebglSurface } from "@/hooks/useWebglSurface";
/** Node shape the Explore map renders — mirrors EntityGraph's RenderNode. */
@@ -216,6 +217,10 @@ export function EntityGraph3D({
frameSignal,
});
+ // This layout does cool down, but the drift keeps drawing after it — and an
+ // unwatched window should draw nothing at all. Same gate as the wiki map.
+ useGraphAwake(graphRef as unknown as RefObject<GraphEngineApi | undefined>);
+
/*
* Framing has to be repeated, not done once.
*
diff --git a/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.tsx b/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.tsx
index 1f2f7f4b6a..28ff6c71c1 100644
--- a/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.tsx
+++ b/jarvis/ui/web/frontend/src/components/wiki/WikiGraph3D.tsx
@@ -57,6 +57,7 @@ import {
} from "@/lib/orbitalLayout";
import type { Vec3 } from "@/lib/graphCamera";
import { useGraphOrbit, type GraphCameraApi } from "@/hooks/useGraphOrbit";
+import { useGraphAwake, type GraphEngineApi } from "@/hooks/useGraphAwake";
import { useWebglSurface } from "@/hooks/useWebglSurface";
import { useThemeValue } from "@/hooks/useTheme";
import { buildSunObject, sunPalette, syncSystemDecor } from "@/components/wiki/wikiSystem";
@@ -368,6 +369,11 @@ export function WikiGraph3D({
frameSignal,
});
+ // This engine never cools (see `cooldownTicks` below), so it is the gate
+ // below — not the layout settling — that stops the map costing a core once
+ // the window is behind something else.
+ useGraphAwake(graphRef as unknown as RefObject<GraphEngineApi | undefined>);
+
/*
* The host asked for a reset, or the data changed under us — and framing has
* to be repeated rather than done once. The camera is placed from where the
diff --git a/jarvis/ui/web/frontend/src/hooks/useGraphAwake.test.ts b/jarvis/ui/web/frontend/src/hooks/useGraphAwake.test.ts
new file mode 100644
index 0000000000..a90f9adcad
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/hooks/useGraphAwake.test.ts
@@ -0,0 +1,142 @@
+import { renderHook, act } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useGraphAwake, type GraphEngineApi } from "./useGraphAwake";
+
+/**
+ * jsdom reports the document as focused and visible by default, which is the
+ * watched state. These push it the other way and back.
+ */
+let hidden = false;
+let focused = true;
+
+function pretend(state: { hidden?: boolean; focused?: boolean }): void {
+ if (state.hidden !== undefined) hidden = state.hidden;
+ if (state.focused !== undefined) focused = state.focused;
+ vi.spyOn(document, "hidden", "get").mockReturnValue(hidden);
+ vi.spyOn(document, "hasFocus").mockReturnValue(focused);
+}
+
+function engine(): GraphEngineApi & {
+ pauseAnimation: ReturnType<typeof vi.fn>;
+ resumeAnimation: ReturnType<typeof vi.fn>;
+} {
+ return { pauseAnimation: vi.fn(), resumeAnimation: vi.fn() };
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ hidden = false;
+ focused = true;
+});
+
+describe("useGraphAwake", () => {
+ it("leaves a watched map running", () => {
+ const graph = engine();
+ pretend({ hidden: false, focused: true });
+
+ renderHook(() => useGraphAwake({ current: graph }));
+
+ expect(graph.pauseAnimation).not.toHaveBeenCalled();
+ expect(graph.resumeAnimation).not.toHaveBeenCalled();
+ });
+
+ it("pauses the engine when the window loses focus", () => {
+ const graph = engine();
+ pretend({ focused: true });
+ renderHook(() => useGraphAwake({ current: graph }));
+
+ act(() => {
+ pretend({ focused: false });
+ window.dispatchEvent(new Event("blur"));
+ });
+
+ expect(graph.pauseAnimation).toHaveBeenCalledTimes(1);
+ });
+
+ it("pauses the engine when the document is hidden", () => {
+ const graph = engine();
+ pretend({ hidden: false });
+ renderHook(() => useGraphAwake({ current: graph }));
+
+ act(() => {
+ pretend({ hidden: true });
+ document.dispatchEvent(new Event("visibilitychange"));
+ });
+
+ expect(graph.pauseAnimation).toHaveBeenCalledTimes(1);
+ });
+
+ it("resumes when the window comes back", () => {
+ const graph = engine();
+ pretend({ focused: true });
+ renderHook(() => useGraphAwake({ current: graph }));
+
+ act(() => {
+ pretend({ focused: false });
+ window.dispatchEvent(new Event("blur"));
+ });
+ act(() => {
+ pretend({ focused: true });
+ window.dispatchEvent(new Event("focus"));
+ });
+
+ expect(graph.pauseAnimation).toHaveBeenCalledTimes(1);
+ expect(graph.resumeAnimation).toHaveBeenCalledTimes(1);
+ });
+
+ it("does not pause an already paused engine", () => {
+ const graph = engine();
+ pretend({ focused: true });
+ renderHook(() => useGraphAwake({ current: graph }));
+
+ act(() => {
+ pretend({ focused: false });
+ window.dispatchEvent(new Event("blur"));
+ window.dispatchEvent(new Event("blur"));
+ document.dispatchEvent(new Event("visibilitychange"));
+ });
+
+ expect(graph.pauseAnimation).toHaveBeenCalledTimes(1);
+ });
+
+ it("never hands the scene back paused", () => {
+ const graph = engine();
+ pretend({ focused: true });
+ const view = renderHook(() => useGraphAwake({ current: graph }));
+
+ act(() => {
+ pretend({ focused: false });
+ window.dispatchEvent(new Event("blur"));
+ });
+ view.unmount();
+
+ expect(graph.resumeAnimation).toHaveBeenCalledTimes(1);
+ });
+
+ it("stays out of the way when disabled", () => {
+ const graph = engine();
+ pretend({ focused: true });
+ renderHook(() => useGraphAwake({ current: graph }, false));
+
+ act(() => {
+ pretend({ focused: false });
+ window.dispatchEvent(new Event("blur"));
+ });
+
+ expect(graph.pauseAnimation).not.toHaveBeenCalled();
+ });
+
+ it("survives a ref that has no instance yet", () => {
+ const ref: { current: GraphEngineApi | undefined } = { current: undefined };
+ pretend({ focused: true });
+
+ expect(() => {
+ const view = renderHook(() => useGraphAwake(ref));
+ act(() => {
+ window.dispatchEvent(new Event("blur"));
+ });
+ view.unmount();
+ }).not.toThrow();
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/hooks/useGraphAwake.ts b/jarvis/ui/web/frontend/src/hooks/useGraphAwake.ts
new file mode 100644
index 0000000000..4f09d79d44
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/hooks/useGraphAwake.ts
@@ -0,0 +1,95 @@
+/**
+ * Stop a 3D memory map's engine while nobody is watching it.
+ *
+ * The force engine behind the maps keeps ticking so the liveliness force has
+ * a frame to write into, and every tick pushes node and link positions
+ * through the scene graph: a matrix update and a draw call per node, sixty
+ * times a second. That is the price of a map that lives, and it is worth
+ * paying while someone is looking at it.
+ *
+ * Nobody looking is the other half, and `document.hidden` does not cover it.
+ * A desktop window sitting behind another window is not hidden — it is simply
+ * not being watched, and it kept the full frame rate. Measured on a 4-core
+ * laptop (2026-08-21): with the deck covered by another app, the board's map
+ * alone held one core at 93 % and its GPU process another two thirds of one,
+ * about a quarter of the whole machine, indefinitely.
+ *
+ * So the gate is hidden OR unfocused. Resuming picks up where it left off:
+ * the layout is state, not animation, so nothing jumps when you come back —
+ * which is why this pauses the engine rather than unmounting the scene.
+ *
+ * Deliberately NOT here: throttling the rate while someone IS watching. The
+ * liveliness reads as alive at sixty and as a stutter below it, so the frame
+ * rate someone sees stays untouched. This only removes frames nobody sees.
+ */
+import { useEffect, type RefObject } from "react";
+
+/** The slice of a force-graph instance this gate drives. */
+export interface GraphEngineApi {
+ pauseAnimation: () => unknown;
+ resumeAnimation: () => unknown;
+}
+
+/**
+ * The instance lands on the ref a frame or two after mount, so the first
+ * read can miss it. Bounded, for the same reason `useWebglSurface` bounds its
+ * attach: a map that never mounts must not leave a retry loop running.
+ */
+const MAX_ATTACH_FRAMES = 120;
+
+/** Is anyone actually looking at this document right now? */
+function isWatched(): boolean {
+ if (typeof document === "undefined") return true;
+ if (document.hidden) return false;
+ // jsdom and older embedders can be missing `hasFocus`; absent, assume the
+ // window is watched rather than pausing a map the user is looking at.
+ if (typeof document.hasFocus !== "function") return true;
+ return document.hasFocus();
+}
+
+export function useGraphAwake(
+ graphRef: RefObject<GraphEngineApi | undefined>,
+ enabled = true,
+): void {
+ useEffect(() => {
+ if (!enabled) return;
+
+ let frame = 0;
+ let attempts = 0;
+ // The engine starts running, so that is what this gate believes until it
+ // sees otherwise. Tracking it avoids pausing an already paused engine on
+ // every focus event the window happens to fire.
+ let awake = true;
+
+ const apply = () => {
+ const graph = graphRef.current;
+ if (!graph) {
+ if (attempts++ < MAX_ATTACH_FRAMES) {
+ frame = requestAnimationFrame(apply);
+ }
+ return;
+ }
+ const next = isWatched();
+ if (next === awake) return;
+ awake = next;
+ if (next) graph.resumeAnimation();
+ else graph.pauseAnimation();
+ };
+
+ apply();
+ document.addEventListener("visibilitychange", apply);
+ window.addEventListener("focus", apply);
+ window.addEventListener("blur", apply);
+
+ return () => {
+ cancelAnimationFrame(frame);
+ document.removeEventListener("visibilitychange", apply);
+ window.removeEventListener("focus", apply);
+ window.removeEventListener("blur", apply);
+ // Never hand the scene back paused. The gate going away — the map being
+ // torn down, or the caller turning it off — must not leave a still map
+ // behind for whoever mounts next.
+ if (!awake) graphRef.current?.resumeAnimation();
+ };
+ }, [graphRef, enabled]);
+}