Digital Energy Factory — performance profile and ranked bottleneck report

2026-09-19. Measurement only; no renderer change was made. Instrumentation added to the app (all default-off, no visual effect): object names on the scene layers, runtime.perf timing accumulators, a ?profile=1 flag that pins the resolution, ?ui=off, and a runtime post-processing mask mirroring the existing ?fx= parameter.

Machine: the development MacBook (Apple GPU, ANGLE/Metal), headless Chrome. Viewport 1920×1200 CSS at device pixel ratio 1.5, which the app caps to a 2880×1800 drawing buffer — the same pixel count as the Retina window in the stutter screenshot. A second set at dpr 1.0 (1920×1200) is included for comparison.

Tools (kept in the repo): scripts/profile.mjs (per-config page loads + Chrome trace), scripts/profile2.mjs (single session, features toggled at runtime, paired R→T→R→T against the full scene), CDP CPU sampling, and a frame-time recorder. Raw results are in factory/.build/profile/.

1. Headline

The stutter has one dominant cause, and it is not scene complexity. One scanned CC0 model (portable_generator, Poly Haven) ships a glass material with KHR_materials_transmission (portable_generator_glass, transmission = 1). three.js therefore runs renderTransmissionPass every frame: it re-renders the entire opaque scene into a full-resolution half-float render target and generates its mipmap chain, so that the glass can refract it. That happens whether or not the generator is on screen (its instance count is zero from the overview) because the trigger is "a visible object with a transmissive material" — and the instanced mesh is visible with count 0.

Under vsync at the same resolution: 24 fps moving with 197 frames over 33 ms in 10 s (as shipped) → 40.6 fps with 5 such frames (transmission off). At dpr 1.0 with transmission off the full scene holds 60 fps with zero hitches.

Everything else measured below is real but second-order: shadows ≈ 4–6 ms, N8AO ≈ 4–5 ms, PV ≈ 5–7 ms, depth-of-field in facility view ≈ 8 ms, PBR maps ≈ 2.7 ms. Vegetation, workers, vehicles, decals, HUD, simulation, flows, GC and React are each under 1 ms or zero.

2. Method and what had to be corrected

• Average FPS was discarded as the metric. Every configuration reports mean, p50, p95, p99, 1 % low, 0.1 % low, worst frame, hitch counts (> 33 ms, > 50 ms), coefficient of variation and frame-to-frame jitter, separately for a static camera and for a scripted 6–10 s orbit that also dips through the 110 m vegetation LOD boundary.
• Run-to-run drift was measured before anything was ranked. Sequential single-shot configurations differed by up to 2× for identical settings (stage B: 137 fps cold, 68 fps after five minutes of load) — GPU clock and thermal state. The stage ladder was therefore measured up and down and averaged, and every feature toggle was measured as reference → toggle → reference → toggle inside one page session, reporting the delta against the adjacent references. Reference drift across the 16-toggle series stayed within 20.3–21.2 ms post-fix (35.8–36.8 ms pre-fix), so the paired deltas are reliable to about ±0.5 ms.
• The headless frame-rate cap was removed (--disable-frame-rate-limit --disable-gpu-vsync) so raw cost is measurable; capped runs were repeated for pacing.
• The adaptive-dpr fallback added yesterday had to be pinned (?profile=1), because it silently halved the pixel count for any configuration slower than 42 fps and made the first ladder inconsistent.
• A texture-memory hypothesis was tested and rejected (capping every texture to 256 px, 784 MB → 36 MB, changed nothing).
• The CPU profile settled it. With the transmission pass active, 83 % of sampled time is inside renderTransmissionPass → upload/setTexture2D (target upload and mipmap generation). Without it, self-time is 61 % drawElements, 18 % bindVertexArray, 3 % uniformMatrix4fv: the main thread is blocked inside GL calls, i.e. waiting on the GPU queue. JavaScript logic (projectObject, setProgram, React jsxDEV) totals under 5 %. The "main thread 120 % busy" in the Chrome trace is GPU back-pressure, not script.

3. Inventory (full scene)

4. Stage ladder A → K (2880×1800, uncapped, mean of ascending and descending passes)

As shipped (transmission pass active from stage B onward, because the generator is part of the props layer)

* the 2.2 s worst frame in stage A is the material recompile caused by the toggle itself (shadows and maps restored on 606 materials), not scene cost.

Transmission = 0 (same ladder, same session type)

Reading the post-fix ladder in milliseconds (static): geometry 6.2 → +2.2 PBR maps → +4.8 PV → +0.1 vegetation → +3.4 shadows → +2.9 AO → +0.4 agents → 0 simulation → 0 HUD → +1.4 decals/bloom/vignette/SMAA = 20.4 ms. The as-shipped ladder is the same shape with every opaque layer roughly doubled, which is exactly what a second full-scene render does.

5. Feature toggles on the full scene (paired, 2880×1800, uncapped)

As shipped

The non-linearity is the tell: hiding the props layer saves 16–25 ms, hiding any single model saves nothing, and every big "layer" saving (PV racking, ground, buildings) is about twice that layer's post-fix cost. All of it is the second render.

Transmission = 0

6. Frame pacing (vsync 60 Hz, 10 s scripted orbit, full scene)

Frame-time graph (10 s orbit, vsync, 2880×1800): docs/factory-frametime-graph.png (copy of factory/.build/profile/frametime-graph.png) — as shipped (red) sits around 40–55 ms with a 5 ms band of jitter; transmission off (green) sits around 24 ms.

Pacing findings:

• The perceived stutter at Retina resolution is sustained 40–56 ms frames, not isolated spikes: coefficient of variation 0.19, worst frame only 1.5× the mean. It reads as "juddery 20 fps", which matches the complaint better than a 60/18/60 pattern would.
• No GC problem. 6–7 minor collections in 10 s, longest 1.3 ms. (One run showed 383 collections during its first seconds, still 2.2 ms max.)
• No React/DOM problem. Layout + paint + style ≈ 7–9 ms per 10 s; unmounting the HUD saves 0.4 ms per frame; the store publishes every 7 frames.
• No steady-state shader compile stalls: zero new programs during any measured pass. Cold-start stalls do exist: the first sight of a PV field cost 0.9–1.1 s and vegetation 0.7–0.8 s in cold runs (first draw of their shader variants). They occur once per session; a warm-up render at load would remove them.
• Camera movement adds 4–5 ms over static at the Retina buffer (24 vs 20 ms), of which vegetation LOD churn is ≈ 2 ms and PV ≈ 1.8 ms.

7. Ranked bottleneck report (Retina buffer, full scene; costs are paired deltas)

Cold-start (once per session): first-sight shader compiles for PV (≈ 1 s) and vegetation (≈ 0.8 s) — not steady-state, but the first orbit of a session will hitch on them.

8. Answer to "which layer collapses"

Pre-fix ladder in the requested form (static, 2880×1800):

The visible "collapse" is at +PV (79 → 39), but the ladder is misleading on its own: the generator's transmissive material sits in the geometry stage from B onward, so every row is paying for a second render of everything above it. Post-fix the same rows read 161 → 119 → 77 → 77 → 64 → 54 → 53 → 52 → 49, and the single largest step is still PV (−42 fps ≈ 4.8 ms), followed by shadows and AO.

9. Engine question

Nothing measured points at Three.js/WebGL as the limit. Post-fix the full scene at 1920×1200 holds vsync with 0 hitches, and at 2880×1800 the remaining 20 ms is ordinary, attributable work (PV racking, shadows, AO, DoF) that responds to ordinary Three.js measures. JavaScript, React, GC and draw-call count are all in the noise. A WebGPU or engine change would not have found or fixed the transmission pass; it is a content/import problem.

Recommended order, for a later optimisation pass (not done here): fix #1 on import and in the asset pipeline → re-profile → decide DoF resolution and PV racking LOD → then shadows/AO quality per dpr.

8. Fix applied (2026-09-19)

Transmission regression closed at three layers.

1. Runtime loader (factory/src/scene/assets.ts, guardTransmission): every material of every loaded GLB is inspected; any MeshPhysicalMaterial with transmission, thickness or their maps is downgraded unless "<model>/<material>" is approved in tools/asset-policy.json. Glass-like names become ordinary alpha-blended decorative glass (opacity 0.42, roughness ≤ 0.12); anything else stays opaque. The downgrade is logged and recorded in transmissionAudit.
2. Optimizer (factory/tools/optimize-models.mjs, auditRefraction): every imported glTF is scanned for KHR_materials_transmission, KHR_materials_volume and KHR_materials_dispersion; offenders are printed with model and material name, stripped (glass-like materials converted to alpha-blended glass) unless approved, and --strict rejects the asset instead. Unused extension declarations are removed from the output.
3. Regression test (factory/tools/check-assets.mjs, npm run test:assets, also the first step of npm run build): FAILS if any optimised runtime asset contains an unapproved refraction material or a dangling refraction extension declaration. portable_generator.glb was re-optimised: its glass no longer carries the extension.

Acceptance (vsync, same harness as §6, .build/profile/vsync-fixed-one.md, vsync-fixed-dpr1-one.md):

The overview at 2880×1800 matches the measured transmission-0 baseline within the ±1 fps run-to-run drift documented in §2; triangle counts confirm the second scene render is gone (12.0 M vs 15.3 M as shipped).

Adaptive depth of field (Scene.tsx Effects): the DoF pass stays mounted in facility/tour view, but its internal update (circle-of-confusion + bokeh blur chain) is skipped while the camera moves. On the transition to "moving" one last update is flushed with the whole depth range in focus, so the merged post shader mixes in nothing; after the camera has been still for 350 ms the bokeh fades back in over 0.3 s. See the rows appended below for the measured effect.

Adaptive DoF measurement (.build/profile/vsync-dof-one.md, run immediately after the verify suite and two profile sessions, i.e. in the thermally depressed GPU state described in §2 — absolute numbers are ~20 % below the cool session above, so only the within-session pairs are comparable):

Before the change the facility view cost ≈ 8 ms more than the overview while the camera moved (29.4 vs 39.4 fps in the cool session above; 30.7 vs 40.6 in §6). With the adaptive pass the facility view now moves at the same frame time as the overview (31.7 vs 32.0 fps in the same session), and the blur is only computed once the camera has been still for 350 ms. Functional suite: 31/31.