Skip to content

♻️ refactor(graph): extract createScene and createLabelLayer - #122

Merged
JadRizk merged 11 commits into
mainfrom
refactor/112-scene-labels
Oct 11, 2026
Merged

JadRizk merged 11 commits into
mainfrom
refactor/112-scene-labels

Conversation

@JadRizk

@JadRizk JadRizk commented Oct 11, 2026

Copy link
Copy Markdown
Owner

⏸ Held until 2.0 ships (see #107)
Stacked on #121

Closes #112
Part of #107

What moved

All under packages/graph/src/. None of it is exported from the package.

File Holds
scene.ts createRenderer (the renderer, main Scene and Camera), createScene, resize, the post-process builders (createTargets, screenTriangle, buildPost), and the Track type
scene-meshes.ts the edge, pad, node and fade builders, shared edge attributes, FALLBACK_BG
label-layer.ts createLabelLayer: the label pool, the measured placer and the tooltip
GraphCanvas.tsx calls the three factories through track, and keeps the view state, the ResizeObserver, and its own resize (it sets viewWidth/viewHeight/viewport, then calls scene.ts's resize)

One change from the scope's file list: the post builders live in scene.ts, not scene-meshes.ts. With them included, scene-meshes.ts came to 377 code lines, over the 300-line file limit. They also make the render targets that resize sizes, so they sit next to it. Every material builder is under 60 lines, so no exception is needed.

Order kept by construction

  • createRenderer runs where the renderer was built before, then packBuffers, then createScene. Extract prepareGraph and packBuffers #111's rule that Math.random is drawn by the Scene and Camera uuids before any shader seed still holds.
  • Inside createScene, three objects are created in the same order as before: edge geometry → edge/live materials and meshes → pads → nodes → fade → render targets → screen geometry → blur and composite → screen quad → post scene and camera. Two allocations without a uuid moved: the six edge InstancedBufferAttributes are now created before the edge geometry rather than just after it, and the bufferSize scratch Vector2 is now created in createScene.
  • Disposal registers through track into the same 6 entries: renderer, targets, materials, geometries, labels, tooltip. The order inside each entry is unchanged, and each entry keeps its own try/catch in dispose.
  • Labels are appended before the tooltip. syncNodes reads GraphCanvas's nodeDepths/nodeMarks/nodeHidden by reference and still runs once during construction.

Evidence

All of this was run on this branch at its tip, with #121's branch at 3722de7 merged in.

  • Harness: vitest run passes without -u (338 graph tests). git diff --exit-code origin/refactor/111-prepare-pack -- packages/graph/src/__recordings__ browser is clean, so lifecycle.unmount's dispose order and boot.resize are unchanged.
  • browser/graph.spec.ts in the pinned Playwright container: 14 passed, baselines unchanged.
  • Types and pack: dist/index.d.ts and dist/index.d.cts are byte-identical (cmp) to a build of ♻️ refactor(graph): extract prepareGraph and packBuffers from boot #121's branch from a git archive copy. The npm pack --dry-run file list is identical (10 files).
  • Lint: packages/graph has 511 warnings and 0 errors, the same as ♻️ refactor(graph): extract prepareGraph and packBuffers from boot #121's branch. The new files contain only the 12 ! assertions that moved with the code. They add no size, complexity, params or depth warnings.
  • CI test job, every step: format:check, lint, typecheck, test, coverage, build, attw ×3, showcase build, preview/tokens/styles drift, check-docs, peer floor (three 0.170), check-consumer (React 18 and 19), check-changeset. Also node scripts/test-react.mjs 18. All pass.
  • New unit tests (scene.test.ts, label-layer.test.ts) cover what the recordings leave out to stay under their size cap: the renderer options, autoClear = false, frustumCulled = false with an infinite bounding sphere on every mesh, the count, grouping and inner order of the 6 track entries, resize's call order, syncNodes reading the caller's arrays, and the DOM order inside the label layer.
  • GraphCanvas.contrast.test.ts now reads the tooltip background from label-layer.ts, where its cssText now lives. This is a test-only change.

dist/index.js, prettier-formatted: relocation only

The diff is +518/−386. I paired every removed line against an added line after trimming whitespace. The lines left unpaired fall into four groups:

  1. Module wrappers for the new functions, and the input destructuring they need.
  2. Renames: opticsConfig.x becomes optics.x, POOL becomes LABEL_POOL_SIZE, and the bundler's own THREE→THREE2 and resize→resize2 aliases.
  3. Shared helpers: setEdgeInstances, used by the edge and pad geometries, and addMesh, which builds a mesh with frustumCulled = false, its renderOrder, and scene.add.
  4. The calls in boot, shown here:
-        const renderer = new THREE.WebGLRenderer({
-          antialias: true,
 ...
+        const stage = createRenderer(mountEl, track);
+        const { renderer, scene, camera } = stage;
 ...
-        } = packBuffers({
+        const buffers = packBuffers({
 ...
+        const sceneParts = createScene({
+          scene, buffers, nodeStates, positions, nodeCount, edgeCount,
+          optics: opticsConfig, track,
+        });
 ...
+        const { labels, owner, labelPlacer, tooltip } = createLabelLayer(labelEl, track);
 ...
-          renderer.setPixelRatio(Math.min(window.devicePixelRatio, MAX_DPR));
-          renderer.setSize(viewWidth, viewHeight);
 ...
+          resize(stage, sceneParts, viewWidth, viewHeight);

No other statement or literal changes.

🤖 Generated with Claude Code

JadRizk and others added 10 commits October 11, 2026 01:44
Validation, degree, displayed states, the layout seed and the solver's
graph now come from a pure prepareGraph. boot keeps writing idToIndexRef,
the dropped-edge warning, visualRandom and createPhysics/setParams.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
packNodes then packEdges, so every node seed is drawn before any edge
seed. boot still calls it after the Scene and Camera, whose uuids draw
from Math.random when the graph is unseeded. The iP2 slot constants and
EDGE_END_TRIM move with the code that writes them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Covers the orphan state, the three seed modes, dropped edges, the fray
encoding, the alternating bow sign and the order of random draws, plus
the patch changeset.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A second `* as THREE` namespace made the bundler rename GraphCanvas's to
THREE2, so dist/index.js changed far beyond the relocated code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tests

Split the shape/tier/colour and gain tests so each asserts one behaviour.
Add unit tests that fail if a node's category is looked up by position,
if the edge end trim drifts from 1.15, or if the iP2 slot constants move.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…Renderer

Releases register through a track callback on boot's disposal stack, so the
renderer entry stays first and drains last.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…reateScene

The edge, pad, node and fade builders live in scene-meshes.ts; the post-process
builders sit beside resize in scene.ts, which sizes the targets they make, and
keep scene-meshes.ts under the 300-line file limit. Every three object is
created in the same order as before, and the three releases are tracked at the
end, as the inline pushes were.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ayer

Labels are appended and tracked before the tooltip, so the tooltip still
paints over them and the two removals keep their places on the stack.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…teLabelLayer

Covers what the recordings leave out to stay under their size cap: renderer
options, autoClear, culling and infinite bounds, the six disposal entries and
their inner order, resize's call order, syncNodes reading the caller's arrays,
and the label layer's DOM order. Adds the patch changeset.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The tooltip's cssText moved there with createLabelLayer; the secondary text
colour is still read from GraphCanvas.tsx.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@JadRizk
JadRizk changed the base branch from refactor/111-prepare-pack to main October 11, 2026 00:29
main's tree is identical to #121's head, which this branch already
contains, so this branch's tree is kept unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@JadRizk
JadRizk merged commit 5fe4c49 into main Oct 11, 2026
4 checks passed
JadRizk added a commit that referenced this pull request Oct 11, 2026
#121 and #122 moved code out of GraphCanvas.tsx into prepare.ts, buffers.ts,
scene.ts, scene-meshes.ts and label-layer.ts, carrying 36 assertions the
compiler doesn't need. Drop them, and keep the 2d-context one in
label-layer.ts with the reason it had in GraphCanvas.tsx. Restore the reason
on the contrast test's kept assertion, lost when main's side of that hunk won.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
JadRizk added a commit that referenced this pull request Oct 11, 2026
…ed (#118)

* 🏷️ types(graph): drop the non-null assertions the compiler doesn't need

Graph builds under plain strict without noUncheckedIndexedAccess, so 371 of the 454 assertions inherited from qrntn's stricter config assert nothing: their operand's type already excludes null and undefined, or (one case) tsc accepts the nullable value as is. Each was removed as a single-character deletion; no other token changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* 🏷️ types(graph): justify the non-null assertions the compiler needs

83 assertions remain because their operand's type admits null or undefined and tsc rejects the code without them. Each holds by construction (a guard, a loop invariant, or a test's own setup), so each keeps its `!` with an eslint-disable-next-line that says why, as docs/code-style.md asks. The rest of the diff is prettier re-wrapping lines the first commit shortened.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* 📝 docs(changeset): empty changeset for the graph non-null clean-up

The built JS and .d.ts are byte-identical to main, so there is nothing to release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* 🏷️ types(graph): redo the non-null cleanup over the moved modules

#121 and #122 moved code out of GraphCanvas.tsx into prepare.ts, buffers.ts,
scene.ts, scene-meshes.ts and label-layer.ts, carrying 36 assertions the
compiler doesn't need. Drop them, and keep the 2d-context one in
label-layer.ts with the reason it had in GraphCanvas.tsx. Restore the reason
on the contrast test's kept assertion, lost when main's side of that hunk won.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Extract createScene and createLabelLayer

1 participant