@displayxr/inline3d 1.30.0 → 1.32.0

package/index.d.ts

@@ -123,6 +123,35 @@ export interface XRDisplayInfo {
   nominalViewerPosition?: DOMPointReadOnly;
 }
 
+/** {@link TileHandle.displayMetrics}: a window in physical units. Metres throughout. */
+export interface DisplayMetrics {
+  /** The canvas's CSS box on the panel, [width, height]. */
+  canvasSizeM: [number, number];
+  /** One CSS px on the panel (physical pixel pitch × devicePixelRatio). */
+  metersPerCssPx: number;
+  displaySizeM: [number, number];
+  /** `nominalViewerPosition.z`, else the default. */
+  nominalViewerM: number;
+  /** Always the default today: no browser or runtime surface reports one. */
+  eyeSeparationM: number;
+  source: { size: 'display' | 'default'; viewer: 'display' | 'default'; eyeSeparation: 'default' };
+}
+
+/** What {@link TileHandle.displayMetrics} fills in when the display cannot say. */
+export const DISPLAY_METRICS_DEFAULTS: Readonly<{
+  displaySizeM: readonly [number, number];
+  displayPixels: readonly [number, number];
+  nominalViewerM: number;
+  eyeSeparationM: number;
+}>;
+
+/** {@link TileHandle.displayMetrics} as a pure function of an XRDisplayInfo, a client rect and devicePixelRatio. */
+export function displayMetricsFrom(
+  info: XRDisplayInfo | null,
+  rect: { width: number; height: number } | null,
+  dpr?: number,
+): DisplayMetrics;
+
 /**
  * One rendering mode the DISPLAY can be put in, as reported by the runtime.
  *
@@ -310,6 +339,13 @@ export interface TileHandle {
    * tile off screen).
    */
   getDisplayInfo(): Promise<XRDisplayInfo | null>;
+  /**
+   * This window in physical units — canvas size in metres, metres per CSS px, the panel, the
+   * nominal viewer distance, the eye separation — from {@link getDisplayInfo}, with anything not
+   * measurable filled from {@link DISPLAY_METRICS_DEFAULTS} and flagged in `source`. Never rejects.
+   * The canvas size is read at the call: call again after a resize.
+   */
+  displayMetrics(): Promise<DisplayMetrics>;
   /** Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}. */
   getRenderingModes(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
   /**
@@ -555,7 +591,63 @@ export interface CreateInline3DOptions {
    * `trackingstatechange` and do the same for a scene.
    */
   untrackedFallback?: 'none' | 'mono';
+  /**
+   * The TRACKING EASE, as the default for every SDK renderer drawing through this session
+   * (`./viewer`'s SceneViewer, `./splat` and `./model` on both engines). When a viewer is
+   * acquired — the views jump from the runtime's nominal viewer to the tracked eyes — or lost,
+   * the eye cameras glide from where they were drawn to the new views over `durationMs` instead
+   * of snapping in one frame; everything parented to the views (parallax, display-rig layers)
+   * follows. Triggered by a jump in the views around a `trackingState` edge (or, where the browser
+   * reports no state, by a large one-frame jump); a no-op when the vendor already animates the eyes. On by default; `false` restores
+   * the snap; a renderer's own `viewerEase` option overrides this. A page rendering its own
+   * `addScene` can use the exported {@link ViewerEase}.
+   */
+  viewerEase?: ViewerEaseOption;
+}
+
+/** `true`/unset = on with defaults, `false` = off, or tune it. */
+export type ViewerEaseOption =
+  | boolean
+  | {
+      /** Default true. */
+      enabled?: boolean;
+      /** The glide, in ms (default 300). 0 disables. */
+      durationMs?: number;
+      /** 'smoothstep' (default) | 'linear' | 'easeOutCubic'. */
+      easing?: 'smoothstep' | 'linear' | 'easeOutCubic' | string;
+    };
+
+/** One frame's matrices as an SDK renderer copies them out of an XRView (column-major). */
+export interface ViewerEaseEntry {
+  proj: Float32Array | Float64Array | number[];
+  pose: Float32Array | Float64Array | number[];
+}
+
+/**
+ * The tracking ease on its own, for a page that renders its own `addScene`: copy each view's
+ * `projectionMatrix` and `transform.matrix` into an entry, call `apply(entries,
+ * frame.session.trackingState)` once per LIVE frame, and render from the entries (keep using the
+ * real XRView for `layer.getViewport`). It rewrites the entries only while an ease is running.
+ */
+export declare class ViewerEase {
+  constructor(opts?: ViewerEaseOption & object);
+  readonly enabled: boolean;
+  readonly durationMs: number;
+  readonly easing: string;
+  /** Is an ease running right now? */
+  readonly active: boolean;
+  /** What the last apply() did: the weight of the old views (0 = passed through), the trigger, the jump (eye separations). */
+  readonly last: { weight: number; reason: null | 'armed-jump' | 'jump' | 'easing'; jump: number };
+  apply(entries: ViewerEaseEntry[], trackingState?: XRTrackingState | string | null, timeMs?: number): number;
+  configure(opts?: ViewerEaseOption): void;
+  /** Forget the previous frame (call after a resize or a view-count change you handle yourself). */
+  reset(): void;
 }
+export function resolveViewerEaseOption(opt?: ViewerEaseOption): { enabled: boolean; durationMs: number; easing: string };
+/** `frame.session.trackingState`, or null when the browser does not report one. */
+export function frameTrackingState(frame: unknown): XRTrackingState | null;
+/** 300. */
+export const VIEWER_EASE_DEFAULT_MS: number;
 
 /**
  * The eased 2D<->3D transition — on by default, and the same sequencer (and the same defaults)

package/js/call/signaling.js

@@ -53,6 +53,18 @@ export async function roomKey(room) {
  */
 export const DXR_SIGNAL_DEFAULT = 'wss://dxr-signal.displayxr.workers.dev';
 
+/**
+ * Every host the hosted server answers on. The SAME Worker serves all of them (rooms are shared),
+ * so the adapter fails over between them when one cannot be reached: the first entry is tried
+ * first. `signal.displayxr.org` is the target of the domain move (RFC 0003 §5g); the workers.dev
+ * host stays an alias through the transition. Only applies to the hosted default — a self-hosted
+ * URL is tried as given (pass `aliases` to add your own fallbacks).
+ */
+export const DXR_SIGNAL_ALIASES = Object.freeze([DXR_SIGNAL_DEFAULT, 'wss://signal.displayxr.org']);
+
+/** Join-time error codes from the server that mean "do not retry with the same inputs". */
+const FATAL_JOIN_CODES = ['bad-room', 'bad-id', 'bad-version', 'bad-key', 'origin-not-allowed', 'blocked'];
+
 export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
   if (!url || typeof url !== 'string') {
     throw codedError(
@@ -60,16 +72,21 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
       'dxrSignaling(url): url must be a ws:// or wss:// string (omit it for the hosted DisplayXR server)'
     );
   }
-  const base = url.replace(/\/+$/, '');
+  const strip = (u) => String(u).replace(/\/+$/, '');
+  const base = strip(url);
   const WS = opts.WebSocket || globalThis.WebSocket;
   const pingMs = opts.pingMs || 20000;
+  const extra = Array.isArray(opts.aliases) ? opts.aliases.filter((a) => typeof a === 'string' && a).map(strip) : DXR_SIGNAL_ALIASES.includes(base) ? [...DXR_SIGNAL_ALIASES] : [];
+  const bases = [base, ...extra.filter((b) => b !== base)];
+  let baseIdx = 0;
 
   return {
     name: 'dxr',
     url: base,
     async join(room, hooks) {
       const key = await roomKey(room);
-      const endpoint = `${base}/v1/connect?k=${key}${typeof opts.key === 'string' && opts.key ? `&key=${encodeURIComponent(opts.key)}` : ''}`;
+      const query = `k=${key}${typeof opts.key === 'string' && opts.key ? `&key=${encodeURIComponent(opts.key)}` : ''}`;
+      const endpointAt = (i) => `${bases[i]}/v1/connect?${query}`;
       let ws = null;
       let left = false;
       let attempt = 0;
@@ -77,11 +94,15 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
       let known = new Set();
       let queue = [];
 
-      const open = (isReconnect) =>
+      // One open() tries every alias once (in order from the last one that worked) before it
+      // reports `signaling-unreachable`; a host that cannot be reached is skipped, not waited on.
+      const open = (isReconnect) => openAt(isReconnect, bases.length);
+      const openAt = (isReconnect, triesLeft) =>
         new Promise((resolve, reject) => {
           let settled = false;
           let joined = false;
-          const sock = new WS(endpoint);
+          let opened = false;
+          const sock = new WS(endpointAt(baseIdx));
           ws = sock;
           const fail = (err) => {
             if (!settled) {
@@ -95,6 +116,7 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
             }
           };
           sock.onopen = () => {
+            opened = true;
             sock.send(JSON.stringify({ t: 'join', v: 1, room, id: hooks.id, max: hooks.maxPeers }));
           };
           sock.onmessage = (ev) => {
@@ -121,17 +143,42 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
                 } else known = new Set(peers);
                 settled = true;
                 joined = true;
-                resolve({ id: msg.id, peers, iceServers: Array.isArray(msg.iceServers) ? msg.iceServers : undefined, max: msg.max });
+                resolve({
+                  id: msg.id,
+                  peers,
+                  iceServers: Array.isArray(msg.iceServers) ? msg.iceServers : undefined,
+                  max: msg.max,
+                  // Hosted-service fields (RFC 0003 §5): the tier this session was admitted as,
+                  // its key id, and the TURN decision — `turn.reason === 'cap'` is the SDK's
+                  // `turn-cap`. A server that predates them sends none; nothing here is required.
+                  tier: msg.tier === 'key' ? 'key' : 'anon',
+                  key: typeof msg.key === 'string' ? msg.key : undefined,
+                  turn: msg.turn && typeof msg.turn === 'object' ? msg.turn : undefined,
+                });
                 break;
               }
               case 'full':
                 left = true;
                 fail(codedError('room-full', `this call is full (${msg.max} participants)`));
                 break;
+              case 'expired': {
+                // The room's lifetime is up (hosted limits): no reconnect — the call reports it.
+                left = true;
+                clearInterval(pingTimer);
+                const e = codedError('expired', 'this room has reached its lifetime on the signalling server');
+                if (!settled) fail(e);
+                else hooks.onDisconnect?.(e);
+                break;
+              }
               case 'error':
-                if (!settled && ['bad-room', 'bad-id', 'bad-version'].includes(msg.code)) {
+                if (!settled && FATAL_JOIN_CODES.includes(msg.code)) {
                   left = true;
                   fail(codedError(msg.code, msg.message || msg.code));
+                } else if (!settled && (msg.code === 'rate-limited' || msg.code === 'quota')) {
+                  // Refused by a limit, not by the inputs: a reconnect may retry after `retryMs`.
+                  const e = codedError(msg.code, msg.message || msg.code);
+                  /** @type {any} */ (e).retryMs = msg.retryMs > 0 ? msg.retryMs : 0;
+                  fail(e);
                 } else if (!settled && msg.code === 'id-taken') {
                   // A reconnect raced the server noticing the old socket close: retry shortly.
                   fail(codedError('id-taken', 'peer id still held; retrying'));
@@ -154,7 +201,16 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
                 break;
             }
           };
-          sock.onerror = () => fail(codedError('signaling-unreachable', `cannot reach ${base}`));
+          sock.onerror = () => {
+            if (!opened && !settled && triesLeft > 1) {
+              // This host is unreachable: fail over to the next alias right away.
+              settled = true;
+              baseIdx = (baseIdx + 1) % bases.length;
+              openAt(isReconnect, triesLeft - 1).then(resolve, reject);
+              return;
+            }
+            fail(codedError('signaling-unreachable', `cannot reach ${bases[baseIdx]}`));
+          };
           sock.onclose = () => {
             clearInterval(pingTimer);
             fail(codedError('signaling-closed', 'signalling closed before joining'));
@@ -172,11 +228,12 @@ export function dxrSignaling(url = DXR_SIGNAL_DEFAULT, opts = {}) {
         const tryAgain = () => {
           if (left) return;
           open(true).catch((err) => {
-            if (left || (err && err.code === 'room-full')) {
+            if (left || (err && (err.code === 'room-full' || FATAL_JOIN_CODES.includes(err.code)))) {
               hooks.onDisconnect?.(err);
               return;
             }
-            setTimeout(tryAgain, backoffMs(attempt++, { baseMs: 500, maxMs: 15000 }));
+            // A `rate-limited` / `quota` refusal says when to come back; never sooner.
+            setTimeout(tryAgain, Math.max(backoffMs(attempt++, { baseMs: 500, maxMs: 15000 }), (err && err.retryMs) || 0));
           });
         };
         setTimeout(tryAgain, backoffMs(attempt++, { baseMs: 300, maxMs: 15000 }));

package/js/inline3d-call.js

@@ -362,8 +362,9 @@ class Call {
       log: (tag, obj) => this.log(tag, obj),
     });
     this.transport = t;
+    let session = null;
     try {
-      await t.start({
+      session = await t.start({
         room: this.room,
         localStream: this.local.stream,
         sendFormat: this.local.format,
@@ -410,9 +411,38 @@ class Call {
     globalThis.addEventListener?.('pagehide', this._pagehide);
     this.log('joined', { id: this.id, peers: this.tiles.size });
     this.emit('joined', { room: this.room, id: this.id });
+    // The TURN decision is reported on the next task, after join() / mountCall() have resolved:
+    // a page (or <dxr-call>) subscribes once it has the handle, and an event raised mid-join
+    // would reach nobody.
+    setTimeout(() => {
+      if (this.transport === t) this._reportTurn(session);
+    }, 0);
     return this.handle;
   }
 
+  /**
+   * The signalling server's TURN decision for this session (hosted service, RFC 0003 §5c), once
+   * per join. `turn-cap` (an `error`): the service's monthly relay budget is spent, nobody gets
+   * TURN — direct connections still work. `turn-shed` (a `warning`): only THIS session has no
+   * TURN (an anonymous session near the budget, or too many credential requests from this
+   * address). A server with no TURN at all (self-hosted) says nothing here: that is a setup
+   * choice, documented in docs/call.md.
+   */
+  _reportTurn(session) {
+    const turn = session && session.turn;
+    if (!turn || typeof turn !== 'object') return;
+    if (turn.status === 'off' && turn.reason === 'cap') {
+      this.error('turn-cap', 'relay (TURN) capacity for this month is used up; direct connections still work, but a participant behind a strict NAT may be unreachable', null);
+    } else if (turn.reason === 'budget' || turn.reason === 'rate') {
+      this.warning(
+        'turn-shed',
+        turn.reason === 'rate'
+          ? 'no relay (TURN) for this session: too many credential requests from this address this hour'
+          : 'no relay (TURN) for this anonymous session: the hosted service is near its monthly relay budget (a publishable key keeps TURN)'
+      );
+    }
+  }
+
   _onPeer(id) {
     if (this.tiles.has(id)) return;
     const tile = new Tile(this, id);

package/js/inline3d-display-metrics.js

@@ -0,0 +1,51 @@
+// inline3d-display-metrics.js — a tile in PHYSICAL units, from XRDisplayInfo.
+//
+// What TileHandle.displayMetrics() resolves, as a pure function, so ./splat's depth envelope (and
+// a page) can share it without pulling in the core. Dependency-free; re-exported by ./inline3d.js.
+
+/**
+ * The defaults displayMetrics() fills in what the display cannot report: a 15.6" 16:9 panel at
+ * 1920x1080 CSS px, the viewer at 650 mm, eyes 63 mm apart. EYE SEPARATION IS ALWAYS A DEFAULT —
+ * no browser or runtime surface reports one (the runtime tracks eye POSITIONS; a page cannot read
+ * them) — so `source.eyeSeparation` is always 'default' today.
+ */
+export const DISPLAY_METRICS_DEFAULTS = Object.freeze({
+  displaySizeM: Object.freeze([0.3456, 0.1944]),
+  displayPixels: Object.freeze([1920, 1080]),
+  nominalViewerM: 0.65,
+  eyeSeparationM: 0.063,
+});
+
+/**
+ * displayMetrics() as a pure function: `info` an XRDisplayInfo (or null), `rect` the canvas's
+ * client rect (CSS px), `dpr` window.devicePixelRatio. Physical px pitch = displayWidthMeters /
+ * displayPixelWidth (the same per axis), and one CSS px is `dpr` physical px — exact when the
+ * browser window is on the panel at its native resolution, which is the only place a woven tile
+ * draws in 3D.
+ */
+export function displayMetricsFrom(info, rect, dpr = 1) {
+  const D = DISPLAY_METRICS_DEFAULTS;
+  const ok =
+    !!info &&
+    info.displayWidthMeters > 0 &&
+    info.displayHeightMeters > 0 &&
+    info.displayPixelWidth > 0 &&
+    info.displayPixelHeight > 0;
+  const displaySizeM = ok ? [info.displayWidthMeters, info.displayHeightMeters] : [...D.displaySizeM];
+  const px = ok ? [info.displayPixelWidth, info.displayPixelHeight] : [...D.displayPixels];
+  // Per axis, then their mean: a panel's pixels are square to well under a percent, and one
+  // number per CSS px is what a page converting a DOM rect wants.
+  const pitch = ((displaySizeM[0] / px[0]) + (displaySizeM[1] / px[1])) / 2;
+  const d = dpr > 0 ? dpr : 1;
+  const metersPerCssPx = ok ? pitch * d : pitch * (px[1] / Math.max(1, globalThis.innerHeight || px[1]));
+  const z = info?.nominalViewerPosition?.z;
+  const viewerOk = Number.isFinite(z) && z > 0.1;
+  return {
+    canvasSizeM: [(rect?.width || 0) * metersPerCssPx, (rect?.height || 0) * metersPerCssPx],
+    metersPerCssPx,
+    displaySizeM,
+    nominalViewerM: viewerOk ? z : D.nominalViewerM,
+    eyeSeparationM: D.eyeSeparationM,
+    source: { size: ok ? 'display' : 'default', viewer: viewerOk ? 'display' : 'default', eyeSeparation: 'default' },
+  };
+}

package/js/inline3d-model-playcanvas.js

@@ -464,6 +464,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     nearClip: opts.nearClip,
     farClip: opts.farClip,
     sky: false,
+    viewerEase: opts.viewerEase,
     // Each environment's own look: 'room' is three's (untonemapped), the rest the Sample Viewer's.
     toneMapping: envMap ? 'neutral' : ENVIRONMENT_TONE_MAPPING[environment] || 'neutral',
   });

package/js/inline3d-model.js

@@ -380,6 +380,7 @@ export function addModel(wall, canvas, src, opts = {}) {
     renderScale,
     feather,
     logTag: '[inline3d/model]',
+    viewerEase: opts.viewerEase,
   }).useEyeCamera(EyeCamera, EdgeFeather);
 
   if (envMap) viewer.scene.environment = envMap;

package/js/inline3d-splat-deferred.js

@@ -91,6 +91,18 @@ export function addSplatDeferred(wall, canvas, src, opts) {
           validateSetRigArgs(type, o);
           return out.ready.then(() => out.setRig(type, o));
         },
+    // Stereo strength / the depth envelope before the adapter has loaded: queued, replayed in
+    // order once it has (both are sticky handle state, applied to the first asset from its first
+    // frame). Validated by the adapter at replay.
+    setStereo: (...args) => {
+      pending.push(['setStereo', args]);
+      return out;
+    },
+    setDepthEnvelope: (...args) => {
+      pending.push(['setDepthEnvelope', args]);
+      return out;
+    },
+    displayMetrics: () => out.ready.then(() => out.displayMetrics()),
     // A video before the first asset has landed: controls:'page' throws at the call's own line,
     // the rest is validated by the adapter's setVideo, which runs once the asset is on screen.
     setVideo: page ? pageOnly('setVideo') : (src, o) => out.ready.then(() => out.setVideo(src, o)),

package/js/inline3d-splat-effects.js

@@ -23,7 +23,7 @@
 //
 // The SDK owns the chunk: every active effect of a scope is ONE function body with its own
 // uniform prefix, and the chunk calls them in a FIXED order, STAGE_ORDER: grade → clip → reveal →
-// pulse → custom. Removing the last effect deletes the chunk (tile) or the modifier (entity),
+// pulse → custom → envelope (→ cull). Removing the last effect deletes the chunk (tile) or the modifier (entity),
 // which restores the engine's own default — the exact baseline, not a no-op look-alike.
 //
 // Adding an effect = one GLSL body + one registry entry in EFFECTS below: `glsl(P, opts)` defines
@@ -47,7 +47,16 @@
 import { coverageExponent, FADE_TRANSMITTANCE_FLOOR } from './inline3d-splat-shared.js';
 
 /** The fixed composition order of a generated chunk. */
-export const STAGE_ORDER = Object.freeze(['grade', 'clip', 'reveal', 'pulse', 'custom', 'cull']);
+export const STAGE_ORDER = Object.freeze(['grade', 'clip', 'reveal', 'pulse', 'custom', 'envelope', 'cull']);
+
+/** handle.setDepthEnvelope's flat rects the shader takes (the largest-weight first beyond it). */
+export const ENVELOPE_MAX_RECTS = 8;
+const ENVELOPE_NO_RECT = Object.freeze([1, -1, 1, -1]);
+const ENVELOPE_OFF = (() => {
+  const o = { on: 0, O: [0, 0, 0], A: [0, 0, -1], R: [1, 0, 0], U: [0, 1, 0], T: [1, 1, 1, 1], K: [0, 1, 1, 0], S: [-1, 1, -1, 1], E: [1, 0, 0, 0], W0: [0, 0, 0, 0], W1: [0, 0, 0, 0] };
+  for (let i = 0; i < ENVELOPE_MAX_RECTS; i++) o['F' + i] = ENVELOPE_NO_RECT;
+  return Object.freeze(o);
+})();
 
 /** The most eye views setSource's wavefront culls for (more: every gaussian is drawn). */
 export const WIPE_CULL_MAX_VIEWS = 4;
@@ -603,6 +612,87 @@ void ${P}color(vec3 c, inout vec4 col) { if (${P}cut) col.a = 0.0; }
     },
   },
 
+  // Internal: handle.setDepthEnvelope — THE FRAME ENVELOPE. Content may come OUT of the glass only
+  // well inside the frame: a gaussian whose panel depth would exceed the cap at its screen spot
+  //   F(x, y) = edge + (maxFront − edge) · e,  e = smoothstep(0, band, distance to the stage edge or
+  //             to a flat rect (weighted)), in metres on the panel,
+  // slides back ALONG ITS OWN RAY from the declared camera rig's centre (centre and scale × λ), so
+  // the rig's mono picture is unchanged and the engine's sort order stays valid. On a camera rig a
+  // point at depth d has panel disparity  k·e·f_p·(1/D − 1/d)  (k = ipdFactor·metersToVirtual per
+  // world unit, f_p = canvas height / (2·tan(vfov/2)), D the convergence), and F metres out needs
+  // −e·F/(n − F) — so the deepest-out allowed depth is  1/d_env = 1/D + F / (k·f_p·(n − F)); the
+  // viewer's eye separation e cancels. Behind the glass is never touched. Keyed on world position
+  // and the RIG (not the tracked eyes), so both eyes and every head position agree. The adapter
+  // supplies everything per tick through opts.state() (null = off); world space throughout.
+  envelope: {
+    stage: 'envelope',
+    kind: 'persistent',
+    internal: true,
+    defaults: {},
+    glsl: (P) => `
+uniform float ${P}on;
+uniform vec3 ${P}O;
+uniform vec3 ${P}A;
+uniform vec3 ${P}R;
+uniform vec3 ${P}U;
+uniform vec4 ${P}T;   // tan half-fov x, y; canvas half-size x, y (m)
+uniform vec4 ${P}K;   // 1/D (world), k·f_p (world·m), viewer n (m), maxFront (m)
+uniform vec4 ${P}S;   // stage l, r, b, t (canvas-normalised, y up)
+uniform vec4 ${P}E;   // band (m), edge (m), rect count, -
+${[0, 1, 2, 3, 4, 5, 6, 7].map((i) => `uniform vec4 ${P}F${i};`).join('\n')}
+uniform vec4 ${P}W0;
+uniform vec4 ${P}W1;
+float ${P}lambda;
+float ${P}flat(vec2 f, vec4 C, float w) {
+  if (w <= 0.0 || C.x >= C.y || C.z >= C.w) return 1.0;
+  vec2 o = max(vec2(max(C.x - f.x, f.x - C.y) * ${P}T.z, max(C.z - f.y, f.y - C.w) * ${P}T.w), vec2(0.0));
+  return mix(1.0, smoothstep(0.0, ${P}E.x, length(o)), w);
+}
+void ${P}center(inout vec3 c) {
+  ${P}lambda = 1.0;
+  if (${P}on < 0.5) return;
+  vec3 v = c - ${P}O;
+  float d = dot(v, ${P}A);
+  if (d <= 1e-4) return;
+  vec2 f = vec2(dot(v, ${P}R) / (d * ${P}T.x), dot(v, ${P}U) / (d * ${P}T.y));
+  vec4 S = ${P}S;
+  float inside = min(min(f.x - S.x, S.y - f.x) * ${P}T.z, min(f.y - S.z, S.w - f.y) * ${P}T.w);
+  float e = smoothstep(0.0, ${P}E.x, inside);
+${[0, 1, 2, 3, 4, 5, 6, 7].map((i) => `  e = min(e, ${P}flat(f, ${P}F${i}, ${P}W${i >> 2}.${'xyzw'[i & 3]}));`).join('\n')}
+  float F = ${P}E.y + max(${P}K.w - ${P}E.y, 0.0) * e;
+  float invEnv = ${P}K.x + F / (${P}K.y * max(${P}K.z - F, 1e-3));
+  if (1.0 / d <= invEnv) return;
+  ${P}lambda = 1.0 / (invEnv * d);
+  c = ${P}O + v * ${P}lambda;
+}
+void ${P}rs(vec3 oc, vec3 mc, inout vec4 r, inout vec3 sc) { sc *= ${P}lambda; }
+void ${P}color(vec3 c, inout vec4 col) {}
+`,
+    uniforms: (ctx, inst) => {
+      const st = typeof inst.opts.state === 'function' ? inst.opts.state() : null;
+      if (!st) return ENVELOPE_OFF;
+      const out = {
+        on: 1,
+        O: st.origin,
+        A: st.axis,
+        R: st.right,
+        U: st.up,
+        T: [st.tanX, st.tanY, st.halfW, st.halfH],
+        K: [st.invD, st.kfp, st.viewer, st.maxFront],
+        S: st.stage,
+        E: [st.band, st.edge, st.rects.length, 0],
+        W0: [0, 0, 0, 0],
+        W1: [0, 0, 0, 0],
+      };
+      for (let i = 0; i < ENVELOPE_MAX_RECTS; i++) {
+        const r = st.rects[i];
+        out['F' + i] = r ? r.f : ENVELOPE_NO_RECT;
+        if (r) out[i < 4 ? 'W0' : 'W1'][i & 3] = r.weight;
+      }
+      return out;
+    },
+  },
+
   // Internal: setSource's crossfade FALLBACK (no frame snapshot) — the coverage remap on one
   // entity, driven by the adapter.
   xfade: {