Skip to content

Add opt-in bounded render density to Canvas viewers - #286

Merged
nekomario28 merged 8 commits into
mainfrom
feat/canvas-render-density-p4
Aug 26, 2026
Merged

Add opt-in bounded render density to Canvas viewers#286
nekomario28 merged 8 commits into
mainfrom
feat/canvas-render-density-p4

Conversation

@nekomario28

Copy link
Copy Markdown
Owner

Summary

Starts #276 P4 / #285 by donating the Three.js render-density policy to Canvas2D without changing current 2D defaults.

Compatibility boundary

  • no render query (or an unknown value) keeps the existing native devicePixelRatio exactly;
  • the new modes are URL-only experimental controls, not a new visible UI or a new transferable semantic state;
  • layout, hit testing, pan/zoom, labels and renderer semantics remain in CSS-pixel coordinates; only the Canvas backing-store ratio changes when explicitly opted in.

Experimental modes

  • render=auto: mobile <= 1x, desktop <= 1.45x
  • render=high: mobile <= 1.25x, desktop <= 1.8x
  • render=low: <= 0.85x

These mirror the established Three.js donor policy.

Shared implementation

  • one render-density.js browser helper owns the policy;
  • one build postprocessor patches the eight Canvas runtimes that currently use direct DPR:
    • shared viewer.js
    • Radial / Tree / Treemap / Timeline / Cluster / Sunburst
    • shared tree-router.js resize synchronization
  • the policy bootstrap is attached only to the seven pages that host those Canvas runtimes;
  • the postprocessor fails closed unless each target still has exactly one native DPR assignment.

Evidence / gates

  • unit tests prove native compatibility, Auto/High/Low caps, invalid-value fallback, all-eight-runtime coverage and idempotence;
  • DPR3 Chromium evidence compares native vs explicit Auto on the shared 2D viewer, checks dedicated Radial, and verifies mobile Auto at 1x;
  • Auto must preserve CSS canvas geometry while reducing DPR3 desktop backing-store area to less than one quarter of native;
  • full existing 2D/3D browser regression remains enabled.

This PR intentionally does not make Auto the default. A default/UI decision stays blocked on visual/readability/performance evidence.

Refs #285 #276.

Copy link
Copy Markdown
Owner Author

Final exact-head evidence for cbafb0f2f5dcf74fdf4fe57bdb50e290f764c144:

  • Verify: success
  • Chromium browser E2E: success
  • iPhone WebKit smoke: success
  • artifact: browser-e2e, id 9610330557, sha256 57269172db709e3d867274f0f55ff5a68de4deb6c4ecf74aed7c2ef6efc4ea26

Persisted DPR3 Canvas evidence:

  • shared desktop native: CSS 1280×553, backing 3840×1659, ratio 3×
  • shared desktop render=auto: CSS 1280×553 unchanged, backing 1856×802, policy 1.45×
  • measured backing-store area ratio: 0.2336548121 (76.6345% reduction)
  • Radial desktop Auto: CSS 1280×571, backing 1856×828, ~1.45×
  • shared mobile DPR3 Auto: CSS 390×421.609, backing 390×422, ~1×; document scroll width = viewport width = 390

This remains opt-in only; native DPR stays the default. Default/user-facing Auto remains blocked on visual/readability/performance evidence.

@nekomario28
nekomario28 marked this pull request as ready for review August 26, 2026 14:08
@nekomario28
nekomario28 merged commit 92c20c9 into main Aug 26, 2026
2 checks passed
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.

1 participant