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.

feat(ci): a WebGL scene that never gives its context back fails the build

Harald06ebee83ec3e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8891d5f0f6..eddd7fd850 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -393,6 +393,13 @@ jobs:
# fails only when a file GAINS one. Mirrors pre-push.
run: python scripts/ci/check_silent_exception_handlers.py
+ - name: WebGL-context gate (every 3D surface gives its context back)
+ # Static + stdlib-only: a browser allows ~16 live WebGL contexts and
+ # kills the OLDEST to make room, and three.js `dispose()` never returns
+ # one — so a scene that mounts without releasing eventually kills a
+ # different, innocent scene on the page (AP-32).
+ run: python scripts/ci/check_webgl_contexts_released.py
+
- name: CLI reference drift gate (docs in sync with command tree)
# Fails if a curated command was added/changed without regenerating
# docs/jarvis-cli-reference.md. Mirrors the pre-push docgen gate.
diff --git a/AGENTS.md b/AGENTS.md
index f998ce47ac..fbb602a9ba 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -85,7 +85,7 @@ kill-on-crash + tool broker (ADR-0025/26); UTF-8 + `NO_WINDOW_CREATIONFLAGS`
on every subprocess. Safety tiers safe/monitor/ask/block, blacklist >
whitelist > default; only `ToolExecutor.execute()`; skills stay `draft`.
-## 7. Anti-patterns AP-1..31 (BINDING)
+## 7. Anti-patterns AP-1..32 (BINDING)
Full register: `docs/agent-contract.md` §7; §8 there reads it backward
(symptom → cause) when you are debugging. Essence: no keys via voice/chat;
enum strings in ALL five layers; no spawn tools in worker sets; atomic TOML
@@ -94,7 +94,8 @@ the boot critical path; no LLM in the voice scrubber; native inference = lock
+ fresh-model recover; GPU wake gates ONLY on the inference probe; wake
verification word-agnostic, never transcript content; no `isinstance` gates
on unpinned libs; signing private keys ONLY in GH Actions secrets; no silent
-`except`; no unread config switch.
+`except`; no unread config switch; a WebGL scene releases its context and
+survives losing it.
## 9. Operational reality & git
Working tree is SHARED: stage only YOUR files (`git add -p`/pathspec, never
diff --git a/CLAUDE.md b/CLAUDE.md
index f998ce47ac..fbb602a9ba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -85,7 +85,7 @@ kill-on-crash + tool broker (ADR-0025/26); UTF-8 + `NO_WINDOW_CREATIONFLAGS`
on every subprocess. Safety tiers safe/monitor/ask/block, blacklist >
whitelist > default; only `ToolExecutor.execute()`; skills stay `draft`.
-## 7. Anti-patterns AP-1..31 (BINDING)
+## 7. Anti-patterns AP-1..32 (BINDING)
Full register: `docs/agent-contract.md` §7; §8 there reads it backward
(symptom → cause) when you are debugging. Essence: no keys via voice/chat;
enum strings in ALL five layers; no spawn tools in worker sets; atomic TOML
@@ -94,7 +94,8 @@ the boot critical path; no LLM in the voice scrubber; native inference = lock
+ fresh-model recover; GPU wake gates ONLY on the inference probe; wake
verification word-agnostic, never transcript content; no `isinstance` gates
on unpinned libs; signing private keys ONLY in GH Actions secrets; no silent
-`except`; no unread config switch.
+`except`; no unread config switch; a WebGL scene releases its context and
+survives losing it.
## 9. Operational reality & git
Working tree is SHARED: stage only YOUR files (`git add -p`/pathspec, never
diff --git a/docs/agent-contract.md b/docs/agent-contract.md
index b557dbbabe..e0e4b2462d 100644
--- a/docs/agent-contract.md
+++ b/docs/agent-contract.md
@@ -492,6 +492,33 @@ downgrades to `safe` (anti-confirmation-fatigue contract). Direct
| AP-23 | Build or test only against the maintainer's config/keys/OS and claim done | Whole surface bricked for every other downloader; verify §3's paths |
| AP-30 | Catch an exception and neither log, re-raise, nor say why silence is right | The feature just does nothing and nobody can tell it failed — the single largest source of "it only half works" (gate: `check_silent_exception_handlers.py`) |
| AP-31 | Add a config field nothing reads, or leave a switch whose value is ignored | `jarvis.toml` and the settings screen promise behaviour that does not exist (gate: `check_config_switches_wired.py`) |
+| AP-32 | Mount a WebGL renderer without giving the context back | A browser allows ~16 live contexts and kills the OLDEST to make room, so the leak kills a DIFFERENT, innocent scene — and the browser paints its broken-canvas placeholder there (gate: `check_webgl_contexts_released.py`) |
+
+### AP-32 — Never mount a WebGL renderer without a release path
+
+A browser gives a page a small, fixed number of live WebGL contexts (Chromium:
+16) and enforces the cap by silently taking the OLDEST one away. `dispose()`
+does not return a context — only `WEBGL_lose_context` / `forceContextLoss()`
+does. So the component that leaks is never the one that breaks: the scene that
+dies is whichever has been running longest, and the browser paints its own
+broken-canvas placeholder there — a white rectangle with a small sad face —
+while the app carries on believing everything is fine. Measured 2026-08-21:
+fourteen trips into the Wiki section and back left fifteen live contexts behind
+ONE canvas, and the deck's memory map (mounted since boot) went white.
+
+Two obligations, and the second is as binding as the first, because a GPU reset
+takes every context no matter how clean the release path is:
+
+1. **Give it back.** On unmount, hand the context to the browser.
+2. **Survive losing it.** `webglcontextlost` must call `preventDefault()` —
+ without it the browser never fires `webglcontextrestored` — and the scene
+ must be rebuilt on a fresh canvas. When rebuilding fails repeatedly, degrade
+ honestly (the flat map) with the REAL reason, never a dead canvas.
+
+Both live in `jarvis/ui/web/frontend/src/hooks/useWebglSurface.ts`; use it
+rather than re-deriving them. Note the trap it documents: React commits the
+rebuilt child BEFORE running the old effect's cleanup, so touching the graph
+ref in that cleanup reaches the NEW scene and pauses it.
### AP-24 — Never share a native inference engine between concurrent callers
@@ -594,6 +621,7 @@ adds no rules of its own. Detail in [`docs/BUGS.md`](BUGS.md).
| Wake fires on silence, or goes deaf on its own word | Wake transcript trap (BUG-037) | One root, not two: word-agnostic verification only (AP-27) |
| A feature "half works" and nothing is logged | Silent handler | Log, re-raise, or say why silence is right (AP-30) |
| A settings switch changes nothing | Unwired config | Read the value or delete the field (AP-31) |
+| A white rectangle with a small sad face where a 3D view was | Lost WebGL context | Release the context on unmount and rebuild on loss — `useWebglSurface` (AP-32) |
---
diff --git a/scripts/ci/check_webgl_contexts_released.py b/scripts/ci/check_webgl_contexts_released.py
new file mode 100644
index 0000000000..d633efaa21
--- /dev/null
+++ b/scripts/ci/check_webgl_contexts_released.py
@@ -0,0 +1,115 @@
+"""WebGL-context gate.
+
+A browser hands a page a small, fixed number of live WebGL contexts —
+Chromium's cap is 16 — and it enforces the cap by silently taking the OLDEST
+context away when a new one is asked for. Nothing in three.js gives one back:
+``WebGLRenderer.dispose()`` frees buffers and textures, not the context. Only
+``WEBGL_lose_context.loseContext()`` (three's ``forceContextLoss()``) does.
+
+So a component that mounts a WebGL renderer and never releases it spends one
+of those sixteen slots per mount, for the lifetime of the page. On 2026-08-21
+fourteen trips into the Wiki section and back left FIFTEEN live contexts behind
+one canvas, and the browser killed the longest-running scene on the page — the
+deck's memory map — leaving Chromium's own broken-canvas placeholder there: a
+white rectangle with a small sad face. Nothing in the app noticed, because
+without a ``webglcontextlost`` handler that calls ``preventDefault()`` the
+browser never offers the context back either.
+
+This gate enforces the invariant: **every frontend module that mounts a WebGL
+renderer must also give the context back and survive losing it.** In practice
+that means using ``hooks/useWebglSurface.ts``, which does both; a module that
+calls ``WEBGL_lose_context`` itself (the capability probe in
+``lib/graphDimension.ts``) also satisfies it.
+
+Static analysis only — it never runs a bundler, so it is cheap and
+dependency-free. Run from CI and covered by
+``tests/unit/ui/test_webgl_contexts_released.py``.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parents[2]
+_FRONTEND = _REPO / "jarvis" / "ui" / "web" / "frontend" / "src"
+
+#: An import of the 3D graph renderer, a hand-rolled three.js renderer, or a
+#: raw WebGL context. Type-only imports are excluded at the call site: a module
+#: that merely names `NodeObject` never owns a context.
+_MOUNTS: tuple[tuple[str, re.Pattern[str]], ...] = (
+ ("react-force-graph-3d", re.compile(r"^\s*import\s+(?!type\b)[^\n]*react-force-graph-3d", re.M)),
+ ("new WebGLRenderer", re.compile(r"\bnew\s+(?:THREE\.)?WebGLRenderer\b")),
+ ("@react-three/fiber", re.compile(r"^\s*import\s+(?!type\b)[^\n]*@react-three/fiber", re.M)),
+ ("getContext(\"webgl\")", re.compile(r"""getContext\(\s*['"]webgl2?['"]""")),
+)
+
+#: Proof that the module hands the context back. `useWebglSurface` is the
+#: shared way; the other three are what it (or an equivalent) calls.
+_RELEASES: tuple[str, ...] = (
+ "useWebglSurface",
+ "releaseWebglContext",
+ "WEBGL_lose_context",
+ "forceContextLoss",
+)
+
+#: Files whose WebGL use is a test double or a fixture, never a live scene.
+_TEST_SUFFIXES = (".test.ts", ".test.tsx", ".spec.ts", ".spec.tsx")
+
+
+def _is_test(path: Path) -> bool:
+ return path.name.endswith(_TEST_SUFFIXES) or "__tests__" in path.parts
+
+
+def offenders(root: Path | None = None) -> list[tuple[str, str]]:
+ """Return (repo-relative path, what it mounts) for every unreleased scene."""
+ base = root or _FRONTEND
+ found: list[tuple[str, str]] = []
+ for path in sorted(base.rglob("*.ts*")):
+ if _is_test(path):
+ continue
+ try:
+ text = path.read_text(encoding="utf-8")
+ except (OSError, UnicodeDecodeError):
+ continue
+ mounted = next((label for label, rx in _MOUNTS if rx.search(text)), None)
+ if not mounted:
+ continue
+ if any(token in text for token in _RELEASES):
+ continue
+ found.append((_label(path), mounted))
+ return found
+
+
+def _label(path: Path) -> str:
+ """Repo-relative where possible; the tests scan a tmp tree of their own."""
+ try:
+ return path.relative_to(_REPO).as_posix()
+ except ValueError:
+ return path.as_posix()
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.parse_args(argv)
+ bad = offenders()
+ if not bad:
+ print("WebGL-context gate: every 3D surface releases its context.")
+ return 0
+ print("WebGL contexts that are taken and never given back:\n", file=sys.stderr)
+ for path, mounted in bad:
+ print(f" {path} (mounts: {mounted})", file=sys.stderr)
+ print(
+ "\nUse `useWebglSurface(hostRef)` from @/hooks/useWebglSurface and put its\n"
+ "`generation` on the renderer as a `key`. It releases the context on\n"
+ "unmount and rebuilds the scene when the browser takes one away — without\n"
+ "it the sixteenth mount kills the oldest scene on the page and the browser\n"
+ "paints a white canvas with a sad face over it (AP-32).",
+ file=sys.stderr,
+ )
+ return 1
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tests/unit/ui/test_webgl_contexts_released.py b/tests/unit/ui/test_webgl_contexts_released.py
new file mode 100644
index 0000000000..ac35585bb5
--- /dev/null
+++ b/tests/unit/ui/test_webgl_contexts_released.py
@@ -0,0 +1,76 @@
+"""The WebGL-context gate must hold: no 3D surface keeps a context forever.
+
+A browser gives a page ~16 live WebGL contexts and takes the OLDEST away to
+make room for a seventeenth. Since `WebGLRenderer.dispose()` does not return
+one, a scene that mounts without releasing spends a slot per mount — and the
+scene that dies is not the greedy one, it is the longest-running one on the
+page. That is how the deck's memory map turned into the browser's own
+broken-canvas placeholder on 2026-08-21 (AP-32).
+
+These tests protect the mechanism, not one component: the gate has to stay
+green on the shipped tree AND still catch a fresh offender.
+"""
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parents[3]
+_GATE = _REPO / "scripts" / "ci" / "check_webgl_contexts_released.py"
+
+
+def _load_gate():
+ spec = importlib.util.spec_from_file_location("check_webgl_contexts_released", _GATE)
+ mod = importlib.util.module_from_spec(spec)
+ assert spec and spec.loader
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def test_every_shipped_3d_surface_releases_its_context():
+ gate = _load_gate()
+ bad = gate.offenders()
+ assert bad == [], (
+ "these modules mount a WebGL renderer and never hand the context back: "
+ f"{bad}. Use useWebglSurface(hostRef) and key the renderer on its generation."
+ )
+
+
+def test_the_gate_catches_a_scene_that_never_releases(tmp_path: Path):
+ """A new 3D view added without the hook must fail, or the gate is decoration."""
+ gate = _load_gate()
+ offender = tmp_path / "NewSpaceView.tsx"
+ offender.write_text(
+ 'import ForceGraph3D from "react-force-graph-3d";\n'
+ "export const NewSpaceView = () => <ForceGraph3D graphData={{nodes: [], links: []}} />;\n",
+ encoding="utf-8",
+ )
+
+ found = gate.offenders(tmp_path)
+
+ assert [name for name, _ in found], "the gate did not notice an unreleased context"
+ assert found[0][1] == "react-force-graph-3d"
+
+
+def test_a_type_only_import_is_not_a_mounted_scene(tmp_path: Path):
+ """The deck card names the library's types without ever owning a context."""
+ gate = _load_gate()
+ (tmp_path / "TypesOnly.tsx").write_text(
+ 'import type { NodeObject } from "react-force-graph-3d";\n'
+ "export type N = NodeObject;\n",
+ encoding="utf-8",
+ )
+
+ assert gate.offenders(tmp_path) == []
+
+
+def test_releasing_by_hand_also_passes(tmp_path: Path):
+ """The capability probe returns its context directly; that counts."""
+ gate = _load_gate()
+ (tmp_path / "probe.ts").write_text(
+ 'const gl = canvas.getContext("webgl2");\n'
+ 'gl?.getExtension("WEBGL_lose_context")?.loseContext();\n',
+ encoding="utf-8",
+ )
+
+ assert gate.offenders(tmp_path) == []