Skip to content

101: renderer seam, versioned test facade, module api 2 (F3 F5 F6) + compile guard - #563

Open
AlexZ005 wants to merge 29 commits into
mainfrom
feat/101-seam
Open

AlexZ005 wants to merge 29 commits into
mainfrom
feat/101-seam

Conversation

@AlexZ005

Copy link
Copy Markdown
Collaborator

101-seam — evidence summary (roadmap 101 F3 F5 F6)

Branch feat/101-seam from v1.65.0 (777b164), v1.66.0 merged in (d6366d4). Forks (Q1-Q6) are recorded in the lane handover.

What landed

  • F3 renderer seam src/lib/render/: createMainRenderer (threlte 8.6.1 defaults in one place, <Canvas createRenderer> in App + PlayApp, PCF shadow constant, tone-mapping/exposure hooks, dpr, context-loss listeners, WebGL2 probe); renderTargets.js (one factory for the 19 targets, readPixels returns a Promise: 7 readbacks async, photoRender.cubeUvToEquirect stays sync because its caller swaps scene.environment in the middle of a synchronous render setup); one shared off-screen renderer for the 5 thumbnail renderers (lazy, disposed after 30 s idle, one-shot jobs free their throw-away scene); disposeRenderer() + recycleMainRenderer(); CI check:render-seam (v1.65.0: 24 hits outside the seam, HEAD: 0).
  • F5 test facade window.__tp.test.v1 (frozen __tp / __tp.test, read-only live Proxy over the hook table, loaded lazily with the hook rows), __stores alias kept for one release, h.t(page), codemod scripts/e2e-facade-codemod.cjs (16,031 refs in 1,061 files, 15 commits by bucket), battery.json gpu map (336 suites false), proof: backStackState renamed backStackSnapshot with 0 suite edits (phone-back 83/0).
  • L1a guard src/lib/render/compile.js: off-frame compiles go through the seam's compileAsync(renderer, object, camera, scene), which closes the scene render bracket three r186's WebGPU compileAsync opens and never closes (left open, lod.js reads every later frame as nested and LOD stops swapping: the roadmap 100 spike's frozen LOD). The water runtime, the one caller, uses it; check:render-seam also fails a .compileAsync( outside the seam (v1.66.0: 1, HEAD: 0). Unit test against the real lod.js hooks (counterfactual included) + render-seam e2e section 3b on the live main renderer.
  • F6 api.version = 2, MODULES.md + OPEN-CORE.md notice (the raw renderer handle stays for now, will leave the contract).

Gates (final HEAD b60801b, 2026-11-14)

Unit 439 files / 4,929 tests, check-ratchet 274/37 = v1.66.0 baseline, check:tokens clean, check:render-seam clean, build OK.

e2e

  • Earlier (on v1.65.0): smoke 21 suites, scene pixel A/B base vs lane (ab/diff.json, 5 of 6 scenes 0 px), lane-scoped GPU queue battery/diff-u1.txt.
  • u2 at c1e8673 (after the v1.66.0 merge + L1a, modules main 27d4cd4): 312 lane-scoped suites, 294 green, 10 flaky, 7 pre-existing reds (the same checks red on v1.66.0), 1 NEW, 0 gone (battery/diff-u2.txt). The 4 module-flight reds of u1 are gone (outdated modules checkout).
  • The NEW red, play-link-devices "C: Enter VR", A/B on the same Deck slot: base v1.66.0 2/2 green, lane 2/2 green (ab6/) = load on the 6-worker Deck run, not the lane.
  • render-seam flaked once in u2 on the threshold-0 frame count (both pairs max delta 6): b60801b bounds the max pixel delta instead; 2/2 green after, L1a section green in every run.

101-seam — what the docs and the changelog should say

Changelog (one line, for the int)

Renderer seam: every renderer and render target now comes from src/lib/render/ (one shared thumbnail renderer, async pixel readbacks, disposeRenderer()), e2e suites reach the app through a versioned window.__tp.test.v1 facade, and the module api reports api.version = 2 (no visible change).

Docs site

Nothing user-visible changed, so no page needs a screenshot or new text. Two developer-facing notes:

  • Modules / API reference: api.version is 2. A module can branch on it. The raw renderer handle a module can reach today stays for now and is due to leave the contract when the view switch (roadmap 100) lands; read the renderer through the documented api calls. (MODULES.md "Which api you have" carries this.)
  • Contributing / tests: e2e suites read the app through window.__tp.test.v1 (helpers: h.t(page).run(fn), .get(path), .call(path, ...args)). window.__stores stays as an alias for one release. An internal rename is absorbed by one row in src/lib/testFacade.js (TEST_V1_RENAMED_EXPORTS), not by editing suites. New renderers or render targets go through src/lib/render/; CI (npm run check:render-seam) fails a new WebGLRenderer / new WebGLRenderTarget( anywhere else, and a .compileAsync( call: off-frame compiles use the seam's compileAsync(renderer, object, camera, scene), which closes the scene render bracket a WebGPU compile leaves open (that bracket left open freezes LOD).

OPEN-CORE.md / MODULES.md

Already written in the lane (F6 note): api number 2, every renderer comes from src/lib/render/, the raw renderer handle stays for now and will leave the contract.

🤖 Generated with Claude Code

AlexZ005 and others added 29 commits November 11, 2026 10:16
…tice

The module api now carries its contract number from one constant (sdk/core.js
SDK_API_VERSION, re-exported by sdk/index.js). MODULES.md and OPEN-CORE.md note
that the raw renderer a module can reach stays for now and leaves the contract
once renderers can be swapped; modules use the look / post SDK calls.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
installDebugHooks publishes a read-only, live facade over the hook table beside
__stores (which stays as an alias). One row in testFacade.js keeps a v1 name
answering when an internal export or hook is renamed. helpers.cjs gains
h.t(page) (ready/run/get/call). scripts/e2e-facade-codemod.cjs moves suites
onto the facade mechanically, keeping pre-install semantics.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (no hand edits).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 942 reference(s) in 80 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 126 reference(s) in 10 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 1206 reference(s) in 70 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 403 reference(s) in 32 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 1660 reference(s) in 102 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 1389 reference(s) in 64 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 853 reference(s) in 57 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 1348 reference(s) in 87 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 584 reference(s) in 47 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 1574 reference(s) in 104 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 221 reference(s) in 22 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 2546 reference(s) in 131 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 1273 reference(s) in 88 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mechanical: scripts/e2e-facade-codemod.cjs --write (rewrote 1682 reference(s) in 134 file(s)).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- createMainRenderer (threlte <Canvas createRenderer>, threlte 8.6.1's own
  defaults) + MAIN_SHADOW_MAP on both Canvas lines; tone mapping / exposure /
  pixel ratio hooks; context-loss listeners attach through watchContextLoss;
  the WebGL 2 probe moved in (webglSupport re-exports it).
- renderTargets.js: one factory for all 19 render targets; readPixels returns
  a Promise (7 readbacks now await it; photoRender's cubeUvToEquirect keeps
  readPixelsSync because it swaps the live scene's environment around the
  read). captureThroughCamera is async.
- offscreen.js: ONE shared off-screen renderer for the 5 thumbnail / preview
  renderers (prefabs, sessions, explorer, ModelPreview, PeerProfileCard), made
  lazily, disposed after 30 s idle; live previews copy their frame into a 2D
  canvas from a grow-only shared buffer.
- index.js: disposeRenderer() releases everything the seam made;
  recycleMainRenderer() disposes and re-creates the main GPU state.
- CI: scripts/check-render-seam.cjs (no renderer / target outside the seam).
- e2e render-seam (facade + seam + dispose/recreate frame and memory check).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
scripts/ci/gpu-neutral-suites.cjs classifies conservatively (the suite and its
local requires never screenshot or read pixels): 336 of 631 suites. A later
two-view run (roadmap 100) runs those once. The unit test fails only on a
stale tag (a tagged suite that now takes a picture).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
backStack.js renames its debug view backStackState -> backStackSnapshot; one
row in testFacade.js keeps __tp.test.v1.backStack.backStackState answering, so
phone-back runs unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Each thumbnail renderer used to lose its whole context after one picture,
which freed every upload. The shared renderer lives on, so renderOffscreen
takes { release: scene } and disposes that subtree's geometries, materials
and textures after the job (prefabs, sessions, explorer).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
… (a leak bound, not equality)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Conflicts were all e2e suites: took the v1.66.0 versions (sidebar-lock deleted there), reran
the facade codemod over tests/e2e (284 member reads in 19 files, 0 left), regenerated the
battery.json gpu map (338 neutral) and kept the lane's render-seam suite entry.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…cene render bracket

three r186's WebGPU compileAsync calls targetScene.onBeforeRender and never onAfterRender;
lod.js counts that bracket, so an unclosed one freezes LOD swaps (pack pieces then serialize in
full and saves throw - roadmap 100 spike finding L1a, fixed there in be48fc4d). Not live on
WebGL 1.x (its compile touches the scene hooks only through a nodes handler 1.x never sets);
this is the guard for the next caller and the next renderer.

- src/lib/render/compile.js: compileAsync(renderer, object, camera, scene) counts the hooks
  the call made and closes only what stayed open; hooks are restored unless replaced meanwhile
- the water runtime's off-frame compile goes through it (the one caller)
- check:render-seam also fails a `.compileAsync(` outside src/lib/render/ (v1.66.0: 1, now 0)
- lodForTest.depth(): the bracket depth, read by the e2e
- unit renderCompile (real lod.js hooks: raw call freezes the pass, seam call does not;
  bracketed / WebGL / pending frames / rejecting compile); e2e render-seam 3b on the live
  main renderer with a WebGPU-shaped compileAsync (raw = depth stuck, seam = depth 0)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
… noise sample's count

u2 (2026-11-14) went red once on 250 vs 176 px changed at threshold 0, both pairs max delta 6,
green on the retry. The same-frame check now asks that no pixel moves further than the
untouched view's own grab-to-grab noise (floor 6 of 765).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
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