+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| webgl-layer-framework.ts | +
+
+ |
+ 85.13% | +126/148 | +70.73% | +58/82 | +84.21% | +16/19 | +91.26% | +115/126 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 | + + + + + + + + + + + + + + + + + + + + + + + + + +11x + + + + + + + + + + + + + +8x +8x +8x +6x +6x +8x + + + + + + + + + + + + + +4x +3x +3x + +4x + +4x + + + + + + + + + + + + + + + + + + + + + + +26x +26x +26x +26x +26x +26x +26x +26x +26x + + + + +26x + + +2x + + + + + +5x +5x + +4x +4x +1x + + +1x + + + +3x +3x +3x +3x +3x +3x + + +3x +3x +3x +3x +3x +3x +3x +3x +5x +5x +5x + + +5x + + + + +5x +5x +5x + + + + + + + + +5x + + +5x +1x +1x +1x +1x +1x + +3x + +3x + +3x + + + +4x + +4x +4x + + + + + + + + + + +2x +2x +2x +2x +2x +2x +2x +2x +2x + + + +4x +4x +4x +4x +5x +4x +4x + + + +3x +3x +3x +3x + + + +10x +10x +6x +3x +3x + + + + +3x +3x +3x +3x +3x +3x +3x +3x + + + + + + +3x +3x +3x +3x +3x + + + + + + +3x + + + + +3x +3x + + + + + + +3x + + + +3x +2x +2x +2x +2x +2x +2x +1x + + +2x + + + + + + + + + +1x + | import { Group, OrthographicCamera, Scene, WebGLRenderer } from "three";
+
+// ─── Pure exports (testable without DOM or WebGL) ────────────────────────────
+
+/**
+ * Converts a D3 zoom transform into orthographic camera bounds.
+ *
+ * D3 applies: screen = map * scale + (viewX, viewY)
+ * Inverting: map = (screen - (viewX, viewY)) / scale
+ *
+ * Orthographic bounds (visible map region at current zoom/pan):
+ * left = -viewX / scale
+ * right = (graphWidth - viewX) / scale
+ * top = -viewY / scale
+ * bottom = (graphHeight - viewY) / scale
+ *
+ * top < bottom: Y-down matches SVG; origin at top-left of map.
+ * Do NOT swap top/bottom or negate — this is correct Three.js Y-down config.
+ */
+export function buildCameraBounds(
+ viewX: number,
+ viewY: number,
+ scale: number,
+ graphWidth: number,
+ graphHeight: number,
+): { left: number; right: number; top: number; bottom: number } {
+ return {
+ left: (0 - viewX) / scale,
+ right: (graphWidth - viewX) / scale,
+ top: (0 - viewY) / scale,
+ bottom: (graphHeight - viewY) / scale,
+ };
+}
+
+/**
+ * Detects WebGL2 support by probing canvas.getContext("webgl2").
+ * Accepts an optional injectable probe canvas for testability (avoids DOM access in tests).
+ * Immediately releases the probed context via WEBGL_lose_context if available.
+ */
+export function detectWebGL2(probe?: HTMLCanvasElement): boolean {
+ const canvas = probe ?? document.createElement("canvas");
+ const ctx = canvas.getContext("webgl2");
+ if (!ctx) return false;
+ const ext = ctx.getExtension("WEBGL_lose_context");
+ ext?.loseContext();
+ return true;
+}
+
+/**
+ * Returns the CSS z-index for a canvas layer anchored to the given SVG element id.
+ * Phase 2 forward-compatible: derives index from DOM sibling position (+1 offset).
+ * Falls back to 2 (above #map SVG at z-index 1) when element is absent or document
+ * is unavailable (e.g. Node.js test environment).
+ *
+ * MVP note: #terrain is a <g> inside <svg#map>, not a sibling of #map-container,
+ * so this always resolves to the fallback 2 in MVP. Phase 2 (DOM-split) will give
+ * true per-layer interleaving values automatically.
+ */
+export function getLayerZIndex(anchorLayerId: string): number {
+ if (typeof document === "undefined") return 2;
+ const anchor = document.getElementById(anchorLayerId);
+ Eif (!anchor) return 2;
+ const siblings = Array.from(anchor.parentElement?.children ?? []);
+ const idx = siblings.indexOf(anchor);
+ // +1 so Phase 2 callers get a correct interleaving value automatically
+ return idx > 0 ? idx + 1 : 2;
+}
+
+// ─── Interfaces ──────────────────────────────────────────────────────────────
+
+export interface WebGLLayerConfig {
+ id: string;
+ anchorLayerId: string; // SVG <g> id; canvas id derived as `${id}Canvas`
+ renderOrder: number; // Three.js renderOrder for this layer's Group
+ setup: (group: Group) => void; // called once after WebGL2 confirmed; add meshes to group
+ render: (group: Group) => void; // called each frame before renderer.render(); update uniforms/geometry
+ dispose: (group: Group) => void; // called on unregister(); dispose all GPU objects in group
+}
+
+// Not exported — internal framework bookkeeping only
+interface RegisteredLayer {
+ config: WebGLLayerConfig;
+ group: Group; // framework-owned; passed to all callbacks — abstraction boundary
+}
+
+// ─── Class ───────────────────────────────────────────────────────────────────
+
+export class WebGL2LayerFrameworkClass {
+ private canvas: HTMLCanvasElement | null = null;
+ private renderer: WebGLRenderer | null = null;
+ private camera: OrthographicCamera | null = null;
+ private scene: Scene | null = null;
+ private layers: Map<string, RegisteredLayer> = new Map();
+ private pendingConfigs: WebGLLayerConfig[] = []; // queue for register() before init()
+ private resizeObserver: ResizeObserver | null = null;
+ private rafId: number | null = null;
+ private container: HTMLElement | null = null;
+
+ // Backing field — MUST NOT be declared readonly.
+ // readonly fields can only be assigned in the constructor; init() sets _fallback
+ // post-construction, which would cause a TypeScript type error with readonly.
+ private _fallback = false;
+
+ get hasFallback(): boolean {
+ return this._fallback;
+ }
+
+ // ─── Public API ────────────────────────────────────────────────────────────
+
+ init(): boolean {
+ this._fallback = !detectWebGL2();
+ if (this._fallback) return false;
+
+ const mapEl = document.getElementById("map");
+ if (!mapEl) {
+ console.warn(
+ "WebGL2LayerFramework: #map element not found — init() aborted",
+ );
+ return false;
+ }
+
+ // Wrap #map in a positioned container so the canvas can be a sibling with z-index
+ const container = document.createElement("div");
+ container.id = "map-container";
+ container.style.position = "relative";
+ mapEl.parentElement!.insertBefore(container, mapEl);
+ container.appendChild(mapEl);
+ this.container = container;
+
+ // Canvas: sibling to #map, pointerless, z-index above SVG (AC1)
+ const canvas = document.createElement("canvas");
+ canvas.id = "terrainCanvas";
+ canvas.style.position = "absolute";
+ canvas.style.inset = "0";
+ canvas.style.pointerEvents = "none";
+ canvas.setAttribute("aria-hidden", "true");
+ canvas.style.zIndex = String(getLayerZIndex("terrain"));
+ canvas.width = container.clientWidth || 960;
+ canvas.height = container.clientHeight || 540;
+ container.appendChild(canvas);
+ this.canvas = canvas;
+
+ // Three.js core objects (AC4)
+ this.renderer = new WebGLRenderer({
+ canvas,
+ antialias: false,
+ alpha: true,
+ });
+ this.renderer.setSize(canvas.width, canvas.height);
+ this.scene = new Scene();
+ this.camera = new OrthographicCamera(
+ 0,
+ canvas.width,
+ 0,
+ canvas.height,
+ -1,
+ 1,
+ );
+
+ this.subscribeD3Zoom();
+
+ // Process pre-init registrations (register() before init() is explicitly safe)
+ for (const config of this.pendingConfigs) {
+ const group = new Group();
+ group.renderOrder = config.renderOrder;
+ config.setup(group);
+ this.scene.add(group);
+ this.layers.set(config.id, { config, group });
+ }
+ this.pendingConfigs = [];
+
+ this.observeResize();
+
+ return true;
+ }
+
+ register(config: WebGLLayerConfig): void {
+ Eif (!this.scene) {
+ // init() has not been called yet — queue for processing in init()
+ this.pendingConfigs.push(config);
+ return;
+ }
+ // Post-init registration: create group immediately
+ const group = new Group();
+ group.renderOrder = config.renderOrder;
+ config.setup(group);
+ this.scene.add(group);
+ this.layers.set(config.id, { config, group });
+ }
+
+ unregister(id: string): void {
+ Iif (this._fallback) return;
+ const layer = this.layers.get(id);
+ Iif (!layer || !this.scene) return;
+ const scene = this.scene;
+ layer.config.dispose(layer.group);
+ scene.remove(layer.group);
+ this.layers.delete(id);
+ const anyVisible = [...this.layers.values()].some((l) => l.group.visible);
+ Eif (this.canvas && !anyVisible) this.canvas.style.display = "none";
+ }
+
+ setVisible(id: string, visible: boolean): void {
+ Iif (this._fallback) return;
+ const layer = this.layers.get(id);
+ Iif (!layer) return;
+ layer.group.visible = visible;
+ const anyVisible = [...this.layers.values()].some((l) => l.group.visible);
+ Eif (this.canvas) this.canvas.style.display = anyVisible ? "block" : "none";
+ if (visible) this.requestRender();
+ }
+
+ clearLayer(id: string): void {
+ Iif (this._fallback) return;
+ const layer = this.layers.get(id);
+ Iif (!layer) return;
+ layer.group.clear();
+ }
+
+ requestRender(): void {
+ Iif (this._fallback) return;
+ if (this.rafId !== null) return;
+ this.rafId = requestAnimationFrame(() => {
+ this.rafId = null;
+ this.render();
+ });
+ }
+
+ syncTransform(): void {
+ Iif (this._fallback || !this.camera) return;
+ const camera = this.camera;
+ const viewX = (globalThis as any).viewX ?? 0;
+ const viewY = (globalThis as any).viewY ?? 0;
+ const scale = (globalThis as any).scale ?? 1;
+ const graphWidth = (globalThis as any).graphWidth ?? 960;
+ const graphHeight = (globalThis as any).graphHeight ?? 540;
+ const bounds = buildCameraBounds(
+ viewX,
+ viewY,
+ scale,
+ graphWidth,
+ graphHeight,
+ );
+ camera.left = bounds.left;
+ camera.right = bounds.right;
+ camera.top = bounds.top;
+ camera.bottom = bounds.bottom;
+ camera.updateProjectionMatrix();
+ }
+
+ // ─── Private helpers ───────────────────────────────────────────────────────
+
+ private subscribeD3Zoom(): void {
+ // viewbox is a D3 selection global available in the browser; guard for Node test env
+ Eif (typeof (globalThis as any).viewbox === "undefined") return;
+ (globalThis as any).viewbox.on("zoom.webgl", () => this.requestRender());
+ }
+
+ private observeResize(): void {
+ Iif (!this.container || !this.renderer) return;
+ this.resizeObserver = new ResizeObserver((entries) => {
+ const { width, height } = entries[0].contentRect;
+ if (this.renderer && this.canvas) {
+ this.renderer.setSize(width, height);
+ this.requestRender();
+ }
+ });
+ this.resizeObserver.observe(this.container);
+ }
+
+ private render(): void {
+ if (this._fallback || !this.renderer || !this.scene || !this.camera) return;
+ const renderer = this.renderer;
+ const scene = this.scene;
+ const camera = this.camera;
+ this.syncTransform();
+ for (const layer of this.layers.values()) {
+ if (layer.group.visible) {
+ layer.config.render(layer.group);
+ }
+ }
+ renderer.render(scene, camera);
+ }
+}
+
+// ─── Global registration (MUST be last line) ─────────────────────────────────
+// Uses globalThis (≡ window in browsers) to support both browser runtime and
+// Node.js test environments without a ReferenceError.
+declare global {
+ var WebGL2LayerFramework: WebGL2LayerFrameworkClass;
+}
+globalThis.WebGL2LayerFramework = new WebGL2LayerFrameworkClass();
+ |