llm-wiki/docs/graph/performance/2026-06-18-phase-2-4-global-renderer-trial-matrix.md

Phase 2.4 Global Renderer Trial Matrix

Date: 2026-06-18 Branch: codex/large-graph-performance-experience Task: 2.4

Purpose

This note defines the trial boundary before any global large-graph renderer candidate is installed, measured, or wired into the product. The project will compare WebGL, Canvas, and no-new-dependency aggregation with the same data, semantics, graph shapes, and performance records. It will ship at most one production global graph route.

Current DOM/SVG remains the known route for small graphs, community reading, offline detail, and UI-rich cards. It is not assumed to be the final 10000+ global route.

Non-Negotiable Route Rule

Only one production global large-graph route may survive the decision phase.

• Candidate trials may coexist only in isolated harness code and measurement artifacts.
• The workbench must not expose multiple global graph experiences as parallel product modes.
• Aggregation-first may be selected as a staged production route if it wins the decision, but it must not become a permanent second route next to a WebGL or Canvas global renderer.
• DOM/SVG can remain for community/detail surfaces even if a different route wins for the global map.

Shared Trial Inputs

Every candidate must consume the Phase 2 shared renderer adapter contract before product-specific behavior is evaluated.

Required semantic inputs:

• Object ids: node id, community id, aggregation id.
• State: selected object, search hits, Pin hints, focused community, filters.
• Aggregation metadata: contained node ids, selected internal node ids, search-hit ids, pinned ids, total count.
• Drawer targets: node summary, community summary, excluded aggregation object.
• Commands: enter community, show object, clear temporary object, open detail/read, set fixed position.

Required graph shapes:

Shape	Nodes	Edge cap	Required in Phase 6?	Purpose
real-snapshot-proxy	1000	1600	yes	Proxy for a realistic medium wiki graph.
nodes-1000-sparse	1000	1400	yes	Baseline interaction and correctness.
nodes-1000-dense	1000	12000	yes	Dense local relation pressure.
nodes-5000-sparse	5000	6500	yes	First large global target.
nodes-5000-dense	5000	60000	yes	Edge-heavy 5000-node pressure.
nodes-10000-aggregation	10000	14000	yes	Primary 10000+ global target.
nodes-10000-high-edge	10000	90000	yes	Extreme edge pressure for the renderer decision.
oversized-community	3000	7000	yes	One huge community without full-card rendering.
many-small-communities	5000	6000	yes	Many tiny communities and legend/container pressure.
many-search-hits	5000	7000	yes	Search highlight pressure.
many-pin-nodes	5000	7000	yes	Pin/selected preservation pressure.

Candidate Matrix

Candidate	Technology	Trial role	Strength to prove	Main rejection reasons	Dependency status
Sigma/Graphology	WebGL + graph model	First global renderer candidate	5000/10000 point map remains smooth while preserving llm-wiki selection/search/Pin/drawer semantics	Semantic contract cannot be preserved, desktop webview risk is too high, memory grows across cycles, integration forces a second product logic path, performance does not beat aggregation enough	Requires explicit trial dependency approval before package changes.
vis-network	Canvas	Strong comparison candidate	Canvas path handles large global interactions with less integration cost than WebGL	Built-in interaction model fights llm-wiki drawer/community/search semantics, layout ownership becomes opaque, Pin/fixed-position behavior is unstable, performance or memory falls below WebGL/aggregation	Requires explicit trial dependency approval before package changes.
Aggregation fallback	Current stack, no new dependency	No-new-dependency fallback or staged route	10000+ global map is useful by showing communities, skeleton edges, selected/search/Pin markers, and overflow lists without full node detail	Users lose too much spatial context, search/Pin/selected objects are not discoverable, container interactions feel like a separate product, oversized communities remain slow	No dependency approval required.

Required Metrics

Every measured candidate must produce fixed-schema artifacts comparable to the Phase 1 DOM/SVG baseline.

Required action records:

• initial render
• wheel zoom FPS and p95 frame time
• pan
• hover or nearest-object inspect
• search highlight
• point select
• container select
• drawer open
• enter community
• return global
• repeated cycle memory growth for every required shape

Required metadata fields:

• renderer id
• candidate version and package versions, if any
• graph shape
• node count
• edge count
• community count
• largest community size
• search hit count
• Pin count
• visible object count
• browser environment
• artifact path
• pass/fail
• failure class and detail

Provisional Acceptance Table

These thresholds are comparison gates, not final product promises.

Metric	1000 nodes	5000 nodes	10000 nodes	Notes
Initial render	<= 1500 ms	<= 5000 ms	<= 8000 ms	Current DOM/SVG exceeded the 10000 target.
Wheel zoom	>= 30 FPS	>= 30 FPS	>= 30 FPS	Lower result must record fps_below_floor.
Pan	<= 300 ms	<= 500 ms	<= 800 ms	Timeout is a blocking failure for a candidate route.
Search highlight	<= 500 ms	<= 800 ms	<= 1200 ms	Search must update highlight/markers without full graph relayout.
Point select	<= 800 ms	<= 1500 ms	<= 2000 ms	Must open lightweight summary target, not full reading by default.
Container select	<= 1000 ms	<= 2000 ms	<= 2500 ms	Community/aggregation selection must keep global context.
Drawer open	<= 1000 ms	<= 2500 ms	<= 3000 ms	Long content rendering is not part of global lightweight drawer.
Return global	<= 3500 ms	<= 5000 ms	<= 5000 ms	Route must not rebuild unnecessary detail.
Repeated cycle memory growth	<= 50 MB	<= 75 MB	<= 100 MB	If the browser cannot expose memory, record that explicitly instead of silently passing.

Browser Verification Boundary

Scripted browser trials remain the route-decision evidence because they generate repeatable JSON artifacts across all graph shapes and actions.

The Codex Browser plugin is an approved fallback for human-like visual and interaction checks when a local Playwright package or Chrome path is unavailable. It can validate that a page opens, visible graph controls respond, and the lightweight drawer flow matches user expectations. It must not replace the fixed-schema performance artifacts for renderer selection, because route decisions need comparable records across WebGL, Canvas, and aggregation fallback candidates.

Desktop-App Compatibility Checks

The later desktop app direction means a candidate cannot win by hiding product logic in browser-only surfaces.

Required checks:

• Graph meaning remains in graph-engine data, not DOM attributes or renderer internals.
• Host integration can be driven by ids, serializable state, and commands.
• Pin/layout state remains portable and wiki-relative.
• Candidate-specific event handling does not own product decisions such as open detail, enter community, or selected object policy.
• The route can run inside a desktop webview or be wrapped behind a native shell bridge without rewriting graph semantics.

Trial Harness Boundary

Allowed in Phase 6:

• Isolated candidate harness modules.
• Temporary renderer pages or browser fixtures under tests/browser/.
• Measurement reports under docs/graph/performance/.
• Trial dependencies after explicit approval is recorded.

Not allowed before the route decision:

• Switching the workbench production global view to a candidate renderer.
• Adding a production dependency for the final app route.
• Leaving multiple candidate renderers active as user-facing modes.
• Recomputing graph product semantics inside candidate-specific code.

Dependency Approval Record Needed

If Phase 6 needs trial packages, the progress decision log must record exact approval before package changes land.

Expected approval entry format:

Task 6.x dependency approval: install <package names and versions> only for isolated renderer trial harness; no production adoption until Phase 6.4 route decision.

Expected package classes:

• Sigma/Graphology trial: sigma, graphology, and any narrowly required layout/helper package.
• vis-network trial: vis-network or the maintained package name selected at trial time.
• Aggregation fallback: no package expected.

Decision Output

Phase 6.4 must produce one of these outcomes:

• Integrate Sigma/Graphology as the single global large-graph route in a future implementation plan.
• Integrate vis-network as the single global large-graph route in a future implementation plan.
• Ship aggregation-first as the single staged global route, with explicit limits and follow-up research.
• Reject all candidates and continue renderer research with recorded failure reasons.

The decision report must include accepted route, rejected alternatives, evidence artifact paths, unresolved risks, and whether community/detail DOM/SVG remains unchanged.