feat: settle on the browser's wovenState, SDK-owned rect cover, same-task resize, double-attach warning, a frame every frame (1.38.0)

[dfattal]

Stacked on #146 (base is its branch; retarget to main once it merges). Five items from a kiosk demo that keeps one woven canvas across screens and hit black boxes after rect moves, a stretched last frame on resize, a stage attached twice, and covers released on timers. Browser side: DisplayXR/displayxr-browser-pvt#256 (join signal, draft PR #258), #255 (transparent frame weaves black).

A. firstWoven / rewoven() settle on XRDisplayLayer.wovenState where the browser reports it (core, additive). Feature-detected on the prototype; absent → the timer path, unchanged. Present → firstWoven settles { woven: true, confirmed: true, reason: 'woven' } on the first "woven" read after a stereo frame, no hold. rewoven() settles on a "woven" read after a "withheld"/"pending" read seen after the call, or three frames after a box change, never on a stale "woven" the frame the change is seen. Hold cap kept (4 holds, never under 4.8 s): a layer stuck "withheld" settles woven: false, confirmed: true, reason: <withheldReason>. New read-only TileHandle.wovenState / withheldReason, types WovenState, WovenWithheldReason.

B. rectCover on every add*(): 'auto' | 'off' | { color?, snapshot? }. A 2D sibling cover goes up when the canvas's CSS box changes (size, dpr, now also position: core rewoven() restarts on a pure move, since the browser re-registers a moved rect), with a one-time left-eye snapshot of the last frame, and comes down when rewoven() settles. Default 'off' in the core, 'auto' in ./splat and ./model (preview-tier default change, flagged in the CHANGELOG). Pages with their own cover set 'off'.

C. Resize and draw in the same task. The PlayCanvas viewer resizes its backing store and replays the last frame inside the ResizeObserver callback, before paint, with the projection corrected for the new aspect. Core addScene gains optional onResize({ width, height, dpr }) in the same callback for page-drawn windows.

D. Double-attach warning (warning only, no behavior change). add*() on a canvas still registered, including a second addSplat/addModel during the first one's load, warns once per canvas naming the method and the live registration, then proceeds as before.

E. A frame every session frame. Both viewers drew nothing on a bad frame before their first good one; they now draw the mono camera into both halves. Rules doc: page-drawn windows must draw every frame; a transparent frame weaving black is browser-pvt #255, listed as a known limitation.

Tests 849 → 887, pnpm api:check snapshots match, pnpm check:snippets passes. Nothing has run on a browser build with wovenState or on a panel; all against mocks. Panel checks to do: the WebGL snapshot in B reads back (else the cover is solid), the three-frame lag in A matches the browser, the one-frame move window in B is acceptable.

🤖 Generated with Claude Code

F. Display reads wait for the layer's first frame (core, additive, no new API; commit b7f463c). getDisplayInfo(), getRenderingModes() and requestRenderingMode() called before the layer has framed now wait for the first stereo frame (or the first non-pending wovenState read where the browser reports it), capped at the firstWoven cap (4.8 s by default), then ask the layer; null/empty is returned only as a real absence. Calls after the first frame pass straight through; no-session, failed-layer, removed and session-ended cases settle at once as today. Closes the bug behind the display-modes sample (#151) for every page. Tests 887 → 895.

Rebased onto main after #146 and #151 merged; changelog entries sit under Unreleased, no version bump in the PR.

Panel pass 1 (Chromium 156 dev build with wovenState, 9 Oct): confirmed: true path works (46/46 rewoven(), firstWoven 2.97 s vs 4.18 s hold-elapsed), Show fast-switching with the branch and rectCover: 'off' matches the shipped SDK, no double. Two defects found and fixed on the branch: display reads released on the first non-pending read ('withheld' right after layer creation) and answered null early (0748845: release only on 'woven', retry on empty until the cap); rewoven() fell to the 1200 ms steady-state hold when the rect changed before the call (9591a7d: settle on a 'woven' read three frames after the call). Tests 895 → 900. Second panel pass pending.