@geometra/renderer-three 0.2.0 → 1.3.1

package/dist/split-host.d.ts

@@ -1,24 +1,49 @@
 import * as THREE from 'three';
 import { type BrowserCanvasClientHandle, type BrowserCanvasClientOptions } from '@geometra/renderer-canvas';
 import { type GeometraThreeSceneBasicsOptions } from './three-scene-basics.js';
-export interface ThreeGeometraSplitHostOptions extends Omit<BrowserCanvasClientOptions, 'canvas'>, GeometraThreeSceneBasicsOptions {
+/**
+ * Every {@link createBrowserCanvasClient} option except `canvas`, which split/stacked hosts create
+ * internally. Includes `url`, `binaryFraming`, optional explicit `window` for tests/iframes, and
+ * the rest of {@link BrowserCanvasClientOptions}.
+ */
+export type GeometraHostBrowserCanvasClientOptions = Omit<BrowserCanvasClientOptions, 'canvas'>;
+/**
+ * Default Geometra column width for {@link createThreeGeometraSplitHost}; same value as the
+ * `geometraWidth` option fallback and README.
+ */
+export declare const GEOMETRA_SPLIT_HOST_LAYOUT_DEFAULTS: {
+    readonly geometraWidth: 420;
+};
+export interface ThreeGeometraSplitHostOptions extends GeometraHostBrowserCanvasClientOptions, GeometraThreeSceneBasicsOptions {
     /** Host element; a flex row is appended as a child (existing children are left untouched). */
     container: HTMLElement;
-    /** Geometra column width in CSS pixels. Default: 420. */
+    /**
+     * Geometra column width in CSS pixels. Default: 420 ({@link GEOMETRA_SPLIT_HOST_LAYOUT_DEFAULTS}).
+     * Non-finite or negative values fall back to the default so layout does not emit invalid `px` styles.
+     */
     geometraWidth?: number;
     /** When true, Geometra panel is on the left. Default: false (Three.js left, Geometra right). */
     geometraOnLeft?: boolean;
+    /**
+     * Upper bound for `window.devicePixelRatio` when sizing the WebGL drawing buffer (e.g. `2` on retina
+     * to cut memory and fragment cost). When omitted, the full device pixel ratio is used.
+     */
+    maxDevicePixelRatio?: number;
     /**
      * Called once after scene, camera, and renderer are created.
      * Add meshes, lights, controls, etc. Call `ctx.destroy()` to tear down immediately; the render loop
-     * will not start if the host is already destroyed.
+     * will not start if the host is already destroyed. If this callback throws, the host is fully torn
+     * down and the error is rethrown.
      */
     onThreeReady?: (ctx: ThreeRuntimeContext) => void;
     /**
      * Called every frame before `renderer.render`.
-     * Use for animations; return nothing.
+     * Use for animations. Return **`false`** to skip `render` for this frame only (same idea as
+     * {@link tickGeometraThreeWebGLWithSceneBasicsFrame}). If you call {@link ThreeRuntimeContext.destroy} here,
+     * teardown runs and this frame’s `render` is skipped (avoids rendering after WebGL dispose).
+     * If this callback throws, the host is fully torn down and the error is rethrown (same as {@link onThreeReady}).
      */
-    onThreeFrame?: (ctx: ThreeFrameContext) => void;
+    onThreeFrame?: (ctx: ThreeFrameContext) => void | false;
 }
 export interface ThreeRuntimeContext {
     renderer: THREE.WebGLRenderer;
@@ -44,7 +69,12 @@ export interface ThreeGeometraSplitHostHandle {
     camera: THREE.PerspectiveCamera;
     clock: THREE.Clock;
     geometra: BrowserCanvasClientHandle;
-    /** Stops the render loop, disconnects observers, disposes WebGL, and tears down the Geometra client. */
+    /**
+     * Stops the render loop, tears down WebGL via {@link disposeGeometraThreeWebGLWithSceneBasics} (clock stop +
+     * the same renderer registration headless {@link renderGeometraThreeWebGLWithSceneBasicsFrame} /
+     * {@link tickGeometraThreeWebGLWithSceneBasicsFrame} use to skip draws after dispose), disconnects observers,
+     * and tears down the Geometra client.
+     */
     destroy(): void;
 }
 /**
@@ -52,11 +82,20 @@ export interface ThreeGeometraSplitHostHandle {
  *
  * This is the recommended **hybrid** layout: 3D stays in Three; chrome and data panes stay in Geometra’s protocol.
  * Geometra’s client still uses `resizeTarget: window` by default; when only the Geometra column changes size,
- * a `ResizeObserver` dispatches a synthetic `resize` on `window` so layout width/height track the panel
- * (coalesced to at most once per animation frame when both panes notify in the same frame).
+ * a `ResizeObserver` schedules a synthetic `resize` on `window` so layout width/height track the panel.
+ * The host `root` and both flex panes are observed (same idea as {@link createThreeGeometraStackedHost} observing
+ * its `root`) so container-driven root box changes still coalesce into the same rAF pass even if a panel callback
+ * ordering quirk would otherwise miss a tick.
+ * Panel-driven updates coalesce to at most **one** animation frame per burst: a single `requestAnimationFrame`
+ * pass runs the Three.js buffer resize and (when needed) that synthetic `resize`, so both flex panes firing
+ * in the same frame do not call `renderer.setSize` twice.
+ *
+ * Real `window` `resize` events schedule the same coalesced Three.js pass **without** an extra synthetic
+ * `resize`, so the thin client is not double-notified when the browser already fired `resize`.
  *
  * The Three.js pane listens to `window` `resize` as well so `devicePixelRatio` updates (zoom / display changes)
- * refresh the WebGL drawing buffer without relying on panel `ResizeObserver` alone.
+ * refresh the WebGL drawing buffer without relying on panel `ResizeObserver` alone. Optional
+ * {@link ThreeGeometraSplitHostOptions.maxDevicePixelRatio} caps the ratio used for the WebGL buffer.
  *
  * Pass through {@link BrowserCanvasClientOptions} from `@geometra/renderer-canvas` / `@geometra/client`
  * (for example `binaryFraming`, `onError`, `onFrameMetrics`, `onData` for JSON side-channels on the same

package/dist/split-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"split-host.d.ts","sourceRoot":"","sources":["../src/split-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAChC,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAkC,KAAK,+BAA+B,EAAE,MAAM,yBAAyB,CAAA;AAG9G,MAAM,WAAW,6BACf,SAAQ,IAAI,CAAC,0BAA0B,EAAE,QAAQ,CAAC,EAChD,+BAA+B;IACjC,8FAA8F;IAC9F,SAAS,EAAE,WAAW,CAAA;IACtB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gGAAgG;IAChG,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACjD;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAA;IAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAA;IAC/B,WAAW,EAAE,iBAAiB,CAAA;IAC9B,iFAAiF;IACjF,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,cAAc,CAAA;IACpB,UAAU,EAAE,cAAc,CAAA;IAC1B,aAAa,EAAE,cAAc,CAAA;IAC7B,WAAW,EAAE,iBAAiB,CAAA;IAC9B,cAAc,EAAE,iBAAiB,CAAA;IACjC,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAA;IAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAA;IAC/B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,QAAQ,EAAE,yBAAyB,CAAA;IACnC,wGAAwG;IACxG,OAAO,IAAI,IAAI,CAAA;CAChB;AAgBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,6BAA6B,GACrC,4BAA4B,CAkK9B"}
+{"version":3,"file":"split-host.d.ts","sourceRoot":"","sources":["../src/split-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAChC,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAIL,KAAK,+BAA+B,EACrC,MAAM,yBAAyB,CAAA;AAKhC;;;;GAIG;AACH,MAAM,MAAM,sCAAsC,GAAG,IAAI,CAAC,0BAA0B,EAAE,QAAQ,CAAC,CAAA;AAE/F;;;GAGG;AACH,eAAO,MAAM,mCAAmC;;CAEtC,CAAA;AAEV,MAAM,WAAW,6BACf,SAAQ,sCAAsC,EAC5C,+BAA+B;IACjC,8FAA8F;IAC9F,SAAS,EAAE,WAAW,CAAA;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gGAAgG;IAChG,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACjD;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,KAAK,CAAA;CACxD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAA;IAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAA;IAC/B,WAAW,EAAE,iBAAiB,CAAA;IAC9B,iFAAiF;IACjF,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,cAAc,CAAA;IACpB,UAAU,EAAE,cAAc,CAAA;IAC1B,aAAa,EAAE,cAAc,CAAA;IAC7B,WAAW,EAAE,iBAAiB,CAAA;IAC9B,cAAc,EAAE,iBAAiB,CAAA;IACjC,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAA;IAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAA;IAC/B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,QAAQ,EAAE,yBAAyB,CAAA;IACnC;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,6BAA6B,GACrC,4BAA4B,CA0L9B"}

package/dist/split-host.js

@@ -1,7 +1,15 @@
-import * as THREE from 'three';
 import { createBrowserCanvasClient, } from '@geometra/renderer-canvas';
-import { createGeometraThreeSceneBasics } from './three-scene-basics.js';
-import { resizeGeometraThreePerspectiveView } from './utils.js';
+import { GEOMETRA_THREE_HOST_SCENE_DEFAULTS, createGeometraThreeWebGLWithSceneBasics, disposeGeometraThreeWebGLWithSceneBasics, } from './three-scene-basics.js';
+import { createGeometraHostLayoutSyncRaf } from './layout-sync.js';
+import { coerceHostNonNegativeCssPx } from './host-css-coerce.js';
+import { resizeGeometraThreePerspectiveView, resolveHostDevicePixelRatio } from './utils.js';
+/**
+ * Default Geometra column width for {@link createThreeGeometraSplitHost}; same value as the
+ * `geometraWidth` option fallback and README.
+ */
+export const GEOMETRA_SPLIT_HOST_LAYOUT_DEFAULTS = {
+    geometraWidth: 420,
+};
 function panelStyle(el, flex) {
     el.style.flex = flex;
     el.style.minWidth = '0';
@@ -19,18 +27,28 @@ function fullSizeCanvas(canvas) {
  *
  * This is the recommended **hybrid** layout: 3D stays in Three; chrome and data panes stay in Geometra’s protocol.
  * Geometra’s client still uses `resizeTarget: window` by default; when only the Geometra column changes size,
- * a `ResizeObserver` dispatches a synthetic `resize` on `window` so layout width/height track the panel
- * (coalesced to at most once per animation frame when both panes notify in the same frame).
+ * a `ResizeObserver` schedules a synthetic `resize` on `window` so layout width/height track the panel.
+ * The host `root` and both flex panes are observed (same idea as {@link createThreeGeometraStackedHost} observing
+ * its `root`) so container-driven root box changes still coalesce into the same rAF pass even if a panel callback
+ * ordering quirk would otherwise miss a tick.
+ * Panel-driven updates coalesce to at most **one** animation frame per burst: a single `requestAnimationFrame`
+ * pass runs the Three.js buffer resize and (when needed) that synthetic `resize`, so both flex panes firing
+ * in the same frame do not call `renderer.setSize` twice.
+ *
+ * Real `window` `resize` events schedule the same coalesced Three.js pass **without** an extra synthetic
+ * `resize`, so the thin client is not double-notified when the browser already fired `resize`.
  *
  * The Three.js pane listens to `window` `resize` as well so `devicePixelRatio` updates (zoom / display changes)
- * refresh the WebGL drawing buffer without relying on panel `ResizeObserver` alone.
+ * refresh the WebGL drawing buffer without relying on panel `ResizeObserver` alone. Optional
+ * {@link ThreeGeometraSplitHostOptions.maxDevicePixelRatio} caps the ratio used for the WebGL buffer.
  *
  * Pass through {@link BrowserCanvasClientOptions} from `@geometra/renderer-canvas` / `@geometra/client`
  * (for example `binaryFraming`, `onError`, `onFrameMetrics`, `onData` for JSON side-channels on the same
  * socket as layout; channel names are defined by your app and the Geometra server).
  */
 export function createThreeGeometraSplitHost(options) {
-    const { container, geometraWidth = 420, geometraOnLeft = false, threeBackground = 0x000000, cameraFov = 50, cameraNear = 0.1, cameraFar = 2000, cameraPosition = [0, 0, 5], onThreeReady, onThreeFrame, window: providedWindow, ...browserOptions } = options;
+    const { container, geometraWidth: geometraWidthOpt = GEOMETRA_SPLIT_HOST_LAYOUT_DEFAULTS.geometraWidth, geometraOnLeft = false, maxDevicePixelRatio, threeBackground = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.threeBackground, cameraFov = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.cameraFov, cameraNear = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.cameraNear, cameraFar = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.cameraFar, cameraPosition = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.cameraPosition, onThreeReady, onThreeFrame, window: providedWindow, ...browserOptions } = options;
+    const geometraWidth = coerceHostNonNegativeCssPx(geometraWidthOpt, GEOMETRA_SPLIT_HOST_LAYOUT_DEFAULTS.geometraWidth);
     const doc = container.ownerDocument;
     const win = providedWindow ?? doc.defaultView;
     if (!win) {
@@ -62,12 +80,7 @@ export function createThreeGeometraSplitHost(options) {
     const geometraCanvas = doc.createElement('canvas');
     fullSizeCanvas(geometraCanvas);
     geometraPanel.appendChild(geometraCanvas);
-    const glRenderer = new THREE.WebGLRenderer({
-        canvas: threeCanvas,
-        antialias: true,
-        alpha: false,
-    });
-    const { scene, camera, clock } = createGeometraThreeSceneBasics({
+    const { renderer: glRenderer, scene, camera, clock } = createGeometraThreeWebGLWithSceneBasics(threeCanvas, {
         threeBackground,
         cameraFov,
         cameraNear,
@@ -75,35 +88,44 @@ export function createThreeGeometraSplitHost(options) {
         cameraPosition,
     });
     const resizeThree = () => {
-        resizeGeometraThreePerspectiveView(glRenderer, camera, threePanel.clientWidth, threePanel.clientHeight, win.devicePixelRatio || 1);
+        resizeGeometraThreePerspectiveView(glRenderer, camera, threePanel.clientWidth, threePanel.clientHeight, resolveHostDevicePixelRatio(win.devicePixelRatio || 1, maxDevicePixelRatio));
     };
+    let destroyed = false;
+    const layoutSync = createGeometraHostLayoutSyncRaf(win, {
+        isDestroyed: () => destroyed,
+        syncLayout: resizeThree,
+        dispatchGeometraResize: () => {
+            win.dispatchEvent(new Event('resize'));
+        },
+    });
     const onWindowResize = () => {
-        resizeThree();
+        layoutSync.schedule(false);
     };
     win.addEventListener('resize', onWindowResize, { passive: true });
     resizeThree();
-    const geometraHandle = createBrowserCanvasClient({
-        ...browserOptions,
-        canvas: geometraCanvas,
-        window: win,
-    });
-    let geometraResizeRafId;
-    const triggerGeometraResize = () => {
-        if (geometraResizeRafId !== undefined)
-            return;
-        geometraResizeRafId = win.requestAnimationFrame(() => {
-            geometraResizeRafId = undefined;
-            win.dispatchEvent(new Event('resize'));
-        });
-    };
+    const geometraHandle = (() => {
+        try {
+            return createBrowserCanvasClient({
+                ...browserOptions,
+                canvas: geometraCanvas,
+                window: win,
+            });
+        }
+        catch (err) {
+            layoutSync.cancel();
+            win.removeEventListener('resize', onWindowResize);
+            disposeGeometraThreeWebGLWithSceneBasics({ renderer: glRenderer, clock });
+            root.remove();
+            throw err;
+        }
+    })();
     const roContainer = new ResizeObserver(() => {
-        resizeThree();
-        triggerGeometraResize();
+        layoutSync.schedule(true);
     });
+    roContainer.observe(root);
     roContainer.observe(threePanel);
     roContainer.observe(geometraPanel);
     let rafId;
-    let destroyed = false;
     const destroy = () => {
         if (destroyed)
             return;
@@ -112,14 +134,11 @@ export function createThreeGeometraSplitHost(options) {
             win.cancelAnimationFrame(rafId);
             rafId = undefined;
         }
-        if (geometraResizeRafId !== undefined) {
-            win.cancelAnimationFrame(geometraResizeRafId);
-            geometraResizeRafId = undefined;
-        }
+        layoutSync.cancel();
         win.removeEventListener('resize', onWindowResize);
         roContainer.disconnect();
         geometraHandle.destroy();
-        glRenderer.dispose();
+        disposeGeometraThreeWebGLWithSceneBasics({ renderer: glRenderer, clock });
         root.remove();
     };
     const ctxBase = {
@@ -129,14 +148,30 @@ export function createThreeGeometraSplitHost(options) {
         threeCanvas,
         destroy,
     };
-    onThreeReady?.(ctxBase);
+    try {
+        onThreeReady?.(ctxBase);
+    }
+    catch (err) {
+        destroy();
+        throw err;
+    }
     const loop = () => {
         if (destroyed)
             return;
         rafId = win.requestAnimationFrame(loop);
         const delta = clock.getDelta();
         const elapsed = clock.elapsedTime;
-        onThreeFrame?.({ ...ctxBase, clock, delta, elapsed });
+        try {
+            if (onThreeFrame?.({ ...ctxBase, clock, delta, elapsed }) === false) {
+                return;
+            }
+        }
+        catch (err) {
+            destroy();
+            throw err;
+        }
+        if (destroyed)
+            return;
         glRenderer.render(scene, camera);
     };
     if (!destroyed) {

package/dist/split-host.js.map

@@ -1 +1 @@
-{"version":3,"file":"split-host.js","sourceRoot":"","sources":["../src/split-host.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"split-host.js","sourceRoot":"","sources":["../src/split-host.ts"],"names":[],"mappings":"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"}

package/dist/stacked-host.d.ts

@@ -1,34 +1,74 @@
 import * as THREE from 'three';
-import { type BrowserCanvasClientHandle, type BrowserCanvasClientOptions } from '@geometra/renderer-canvas';
-import type { ThreeFrameContext, ThreeRuntimeContext } from './split-host.js';
+import { type BrowserCanvasClientHandle } from '@geometra/renderer-canvas';
+import type { GeometraHostBrowserCanvasClientOptions, ThreeFrameContext, ThreeRuntimeContext } from './split-host.js';
 import { type GeometraThreeSceneBasicsOptions } from './three-scene-basics.js';
-/** Corner anchor for the Geometra HUD overlay (CSS `position: absolute` on the host). */
-export type GeometraHudPlacement = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-export interface ThreeGeometraStackedHostOptions extends Omit<BrowserCanvasClientOptions, 'canvas'>, GeometraThreeSceneBasicsOptions {
+import { type GeometraHudPlacement } from './host-css-coerce.js';
+export type { GeometraHudPlacement } from './host-css-coerce.js';
+/**
+ * Default HUD width, height, corner, and margin for {@link createThreeGeometraStackedHost}; same as
+ * those option fallbacks and README.
+ */
+export declare const GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS: {
+    readonly geometraHudWidth: 420;
+    readonly geometraHudHeight: 320;
+    readonly geometraHudPlacement: "bottom-right";
+    readonly geometraHudMargin: 12;
+};
+export interface ThreeGeometraStackedHostOptions extends GeometraHostBrowserCanvasClientOptions, GeometraThreeSceneBasicsOptions {
     /** Host element; a full-size stacking context is appended (existing children are left untouched). */
     container: HTMLElement;
-    /** HUD width in CSS pixels. Default: 420. */
+    /**
+     * HUD width in CSS pixels. Default: {@link GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudWidth}.
+     * Non-finite or negative values fall back to the default so layout does not emit invalid `px` styles.
+     */
     geometraHudWidth?: number;
-    /** HUD height in CSS pixels. Default: 320. */
+    /**
+     * HUD height in CSS pixels. Default: {@link GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudHeight}.
+     * Non-finite or negative values fall back to the default.
+     */
     geometraHudHeight?: number;
-    /** HUD corner. Default: `bottom-right`. */
+    /**
+     * HUD corner. Default: {@link GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudPlacement}.
+     * Runtime strings (e.g. from JSON or agents) are normalized with {@link coerceGeometraHudPlacement}
+     * (trim + case-insensitive match for the four literals; anything else uses the default).
+     */
     geometraHudPlacement?: GeometraHudPlacement;
-    /** Inset from the chosen corner in CSS pixels. Default: 12. */
+    /**
+     * Inset from the chosen corner in CSS pixels. Default: {@link GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudMargin}.
+     * Non-finite or negative values fall back to the default.
+     */
     geometraHudMargin?: number;
     /**
      * CSS `pointer-events` on the HUD wrapper (e.g. `'none'` so input falls through to the WebGL canvas).
-     * Default: `'auto'`.
+     * Default: `'auto'`. Blank or whitespace-only strings fall back to the default; use
+     * {@link coerceGeometraHudPointerEvents} in custom layouts for the same rules.
      */
     geometraHudPointerEvents?: string;
+    /**
+     * CSS `z-index` on the HUD wrapper when you stack other siblings in {@link ThreeGeometraStackedHostOptions.container}
+     * or need a fixed order above the WebGL layer (Three canvas uses `0`). Default: `1`.
+     * Non-finite numbers and blank/whitespace-only strings fall back to the default so the HUD keeps a predictable stack order.
+     */
+    geometraHudZIndex?: string | number;
+    /**
+     * Upper bound for `window.devicePixelRatio` when sizing the WebGL drawing buffer (e.g. `2` on retina
+     * to cut memory and fragment cost). When omitted, the full device pixel ratio is used.
+     */
+    maxDevicePixelRatio?: number;
     /**
      * Called once after scene, camera, and renderer are created.
      * Call `ctx.destroy()` to tear down immediately; the render loop will not start if the host is already destroyed.
+     * If this callback throws, the host is fully torn down and the error is rethrown.
      */
     onThreeReady?: (ctx: ThreeRuntimeContext) => void;
     /**
      * Called every frame before `renderer.render`.
+     * Return **`false`** to skip `render` for this frame only (same idea as
+     * {@link tickGeometraThreeWebGLWithSceneBasicsFrame}). If you call {@link ThreeRuntimeContext.destroy} here,
+     * teardown runs and this frame’s `render` is skipped.
+     * If this callback throws, the host is fully torn down and the error is rethrown (same as {@link onThreeReady}).
      */
-    onThreeFrame?: (ctx: ThreeFrameContext) => void;
+    onThreeFrame?: (ctx: ThreeFrameContext) => void | false;
 }
 export interface ThreeGeometraStackedHostHandle {
     root: HTMLDivElement;
@@ -41,19 +81,29 @@ export interface ThreeGeometraStackedHostHandle {
     camera: THREE.PerspectiveCamera;
     clock: THREE.Clock;
     geometra: BrowserCanvasClientHandle;
+    /**
+     * Stops the render loop, tears down WebGL via {@link disposeGeometraThreeWebGLWithSceneBasics} (clock stop +
+     * the same renderer registration headless {@link renderGeometraThreeWebGLWithSceneBasicsFrame} /
+     * {@link tickGeometraThreeWebGLWithSceneBasicsFrame} use to skip draws after dispose), disconnects observers,
+     * and tears down the Geometra client.
+     */
     destroy(): void;
 }
 /**
  * Stacked host: full-viewport Three.js `WebGLRenderer` with a positioned Geometra canvas **HUD** on top.
  *
  * Pointer routing follows normal hit-testing: events hit the Geometra canvas where it overlaps the WebGL layer
- * (`z-index` above the Three canvas); elsewhere, the Three canvas receives input. Override with
- * {@link ThreeGeometraStackedHostOptions.geometraHudPointerEvents} (e.g. `'none'` for a click-through HUD).
+ * (HUD `z-index` above the Three canvas, which uses `0`); elsewhere, the Three canvas receives input. Override with
+ * {@link ThreeGeometraStackedHostOptions.geometraHudPointerEvents} (e.g. `'none'` for a click-through HUD) or
+ * {@link ThreeGeometraStackedHostOptions.geometraHudZIndex} when you add other positioned siblings.
  *
  * Geometra’s client still uses `resizeTarget: window` by default; when only the HUD box changes size,
  * a coalesced synthetic `resize` is dispatched on `window` (same pattern as {@link createThreeGeometraSplitHost}).
+ * `ResizeObserver` callbacks and real `window` `resize` share one rAF-coalesced Three.js buffer pass; the
+ * synthetic `resize` is emitted only from observer-driven layout changes, not from real window resizes.
  * The Three.js layer listens to `window` `resize` for `devicePixelRatio` changes and uses the host `root` size
- * for the drawing buffer.
+ * for the drawing buffer. Optional {@link ThreeGeometraStackedHostOptions.maxDevicePixelRatio} caps the ratio
+ * used for the WebGL buffer.
  */
 export declare function createThreeGeometraStackedHost(options: ThreeGeometraStackedHostOptions): ThreeGeometraStackedHostHandle;
 //# sourceMappingURL=stacked-host.d.ts.map

package/dist/stacked-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stacked-host.d.ts","sourceRoot":"","sources":["../src/stacked-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAChC,MAAM,2BAA2B,CAAA;AAClC,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EAAkC,KAAK,+BAA+B,EAAE,MAAM,yBAAyB,CAAA;AAG9G,yFAAyF;AACzF,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAA;AAE5F,MAAM,WAAW,+BACf,SAAQ,IAAI,CAAC,0BAA0B,EAAE,QAAQ,CAAC,EAChD,+BAA+B;IACjC,qGAAqG;IACrG,SAAS,EAAE,WAAW,CAAA;IACtB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,2CAA2C;IAC3C,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;IAC3C,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACjD;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAChD;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,cAAc,CAAA;IACpB,8EAA8E;IAC9E,WAAW,EAAE,cAAc,CAAA;IAC3B,WAAW,EAAE,iBAAiB,CAAA;IAC9B,cAAc,EAAE,iBAAiB,CAAA;IACjC,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAA;IAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAA;IAC/B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,QAAQ,EAAE,yBAAyB,CAAA;IACnC,OAAO,IAAI,IAAI,CAAA;CAChB;AAsCD;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,8BAA8B,CA6KhC"}
+{"version":3,"file":"stacked-host.d.ts","sourceRoot":"","sources":["../src/stacked-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,2BAA2B,CAAA;AAClC,OAAO,KAAK,EACV,sCAAsC,EACtC,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAIL,KAAK,+BAA+B,EACrC,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAA;AAG7B,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAEhE;;;GAGG;AACH,eAAO,MAAM,qCAAqC;;;;;CAUjD,CAAA;AAED,MAAM,WAAW,+BACf,SAAQ,sCAAsC,EAC5C,+BAA+B;IACjC,qGAAqG;IACrG,SAAS,EAAE,WAAW,CAAA;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;IAC3C;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACnC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACjD;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,KAAK,CAAA;CACxD;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,cAAc,CAAA;IACpB,8EAA8E;IAC9E,WAAW,EAAE,cAAc,CAAA;IAC3B,WAAW,EAAE,iBAAiB,CAAA;IAC9B,cAAc,EAAE,iBAAiB,CAAA;IACjC,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAA;IAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAA;IAC/B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,QAAQ,EAAE,yBAAyB,CAAA;IACnC;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAsCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,8BAA8B,CAkNhC"}

package/dist/stacked-host.js

@@ -1,7 +1,18 @@
-import * as THREE from 'three';
 import { createBrowserCanvasClient, } from '@geometra/renderer-canvas';
-import { createGeometraThreeSceneBasics } from './three-scene-basics.js';
-import { resizeGeometraThreePerspectiveView } from './utils.js';
+import { GEOMETRA_THREE_HOST_SCENE_DEFAULTS, createGeometraThreeWebGLWithSceneBasics, disposeGeometraThreeWebGLWithSceneBasics, } from './three-scene-basics.js';
+import { createGeometraHostLayoutSyncRaf } from './layout-sync.js';
+import { coerceGeometraHudPlacement, coerceGeometraHudPointerEvents, coerceHostNonNegativeCssPx, coerceHostStackingZIndexCss, } from './host-css-coerce.js';
+import { resizeGeometraThreePerspectiveView, resolveHostDevicePixelRatio } from './utils.js';
+/**
+ * Default HUD width, height, corner, and margin for {@link createThreeGeometraStackedHost}; same as
+ * those option fallbacks and README.
+ */
+export const GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS = {
+    geometraHudWidth: 420,
+    geometraHudHeight: 320,
+    geometraHudPlacement: 'bottom-right',
+    geometraHudMargin: 12,
+};
 function fullSizeCanvas(canvas) {
     canvas.style.display = 'block';
     canvas.style.width = '100%';
@@ -36,16 +47,25 @@ function applyHudPlacement(wrap, placement, marginPx) {
  * Stacked host: full-viewport Three.js `WebGLRenderer` with a positioned Geometra canvas **HUD** on top.
  *
  * Pointer routing follows normal hit-testing: events hit the Geometra canvas where it overlaps the WebGL layer
- * (`z-index` above the Three canvas); elsewhere, the Three canvas receives input. Override with
- * {@link ThreeGeometraStackedHostOptions.geometraHudPointerEvents} (e.g. `'none'` for a click-through HUD).
+ * (HUD `z-index` above the Three canvas, which uses `0`); elsewhere, the Three canvas receives input. Override with
+ * {@link ThreeGeometraStackedHostOptions.geometraHudPointerEvents} (e.g. `'none'` for a click-through HUD) or
+ * {@link ThreeGeometraStackedHostOptions.geometraHudZIndex} when you add other positioned siblings.
  *
  * Geometra’s client still uses `resizeTarget: window` by default; when only the HUD box changes size,
  * a coalesced synthetic `resize` is dispatched on `window` (same pattern as {@link createThreeGeometraSplitHost}).
+ * `ResizeObserver` callbacks and real `window` `resize` share one rAF-coalesced Three.js buffer pass; the
+ * synthetic `resize` is emitted only from observer-driven layout changes, not from real window resizes.
  * The Three.js layer listens to `window` `resize` for `devicePixelRatio` changes and uses the host `root` size
- * for the drawing buffer.
+ * for the drawing buffer. Optional {@link ThreeGeometraStackedHostOptions.maxDevicePixelRatio} caps the ratio
+ * used for the WebGL buffer.
  */
 export function createThreeGeometraStackedHost(options) {
-    const { container, geometraHudWidth = 420, geometraHudHeight = 320, geometraHudPlacement = 'bottom-right', geometraHudMargin = 12, geometraHudPointerEvents = 'auto', threeBackground = 0x000000, cameraFov = 50, cameraNear = 0.1, cameraFar = 2000, cameraPosition = [0, 0, 5], onThreeReady, onThreeFrame, window: providedWindow, ...browserOptions } = options;
+    const { container, geometraHudWidth: geometraHudWidthOpt = GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudWidth, geometraHudHeight: geometraHudHeightOpt = GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudHeight, geometraHudPlacement: geometraHudPlacementOpt = GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudPlacement, geometraHudMargin: geometraHudMarginOpt = GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudMargin, geometraHudPointerEvents: geometraHudPointerEventsOpt = 'auto', geometraHudZIndex = 1, maxDevicePixelRatio, threeBackground = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.threeBackground, cameraFov = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.cameraFov, cameraNear = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.cameraNear, cameraFar = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.cameraFar, cameraPosition = GEOMETRA_THREE_HOST_SCENE_DEFAULTS.cameraPosition, onThreeReady, onThreeFrame, window: providedWindow, ...browserOptions } = options;
+    const geometraHudWidth = coerceHostNonNegativeCssPx(geometraHudWidthOpt, GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudWidth);
+    const geometraHudHeight = coerceHostNonNegativeCssPx(geometraHudHeightOpt, GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudHeight);
+    const geometraHudMargin = coerceHostNonNegativeCssPx(geometraHudMarginOpt, GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudMargin);
+    const geometraHudPlacement = coerceGeometraHudPlacement(geometraHudPlacementOpt, GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudPlacement);
+    const geometraHudPointerEvents = coerceGeometraHudPointerEvents(geometraHudPointerEventsOpt, 'auto');
     const doc = container.ownerDocument;
     const win = providedWindow ?? doc.defaultView;
     if (!win) {
@@ -70,7 +90,7 @@ export function createThreeGeometraStackedHost(options) {
     root.appendChild(threeCanvas);
     const geometraHud = doc.createElement('div');
     geometraHud.style.position = 'absolute';
-    geometraHud.style.zIndex = '1';
+    geometraHud.style.zIndex = coerceHostStackingZIndexCss(geometraHudZIndex, 1);
     geometraHud.style.width = `${geometraHudWidth}px`;
     geometraHud.style.height = `${geometraHudHeight}px`;
     geometraHud.style.minWidth = '0';
@@ -82,12 +102,7 @@ export function createThreeGeometraStackedHost(options) {
     const geometraCanvas = doc.createElement('canvas');
     fullSizeCanvas(geometraCanvas);
     geometraHud.appendChild(geometraCanvas);
-    const glRenderer = new THREE.WebGLRenderer({
-        canvas: threeCanvas,
-        antialias: true,
-        alpha: false,
-    });
-    const { scene, camera, clock } = createGeometraThreeSceneBasics({
+    const { renderer: glRenderer, scene, camera, clock } = createGeometraThreeWebGLWithSceneBasics(threeCanvas, {
         threeBackground,
         cameraFov,
         cameraNear,
@@ -95,38 +110,46 @@ export function createThreeGeometraStackedHost(options) {
         cameraPosition,
     });
     const resizeThree = () => {
-        resizeGeometraThreePerspectiveView(glRenderer, camera, root.clientWidth, root.clientHeight, win.devicePixelRatio || 1);
+        resizeGeometraThreePerspectiveView(glRenderer, camera, root.clientWidth, root.clientHeight, resolveHostDevicePixelRatio(win.devicePixelRatio || 1, maxDevicePixelRatio));
     };
+    let destroyed = false;
+    const layoutSync = createGeometraHostLayoutSyncRaf(win, {
+        isDestroyed: () => destroyed,
+        syncLayout: resizeThree,
+        dispatchGeometraResize: () => {
+            win.dispatchEvent(new Event('resize'));
+        },
+    });
     const onWindowResize = () => {
-        resizeThree();
+        layoutSync.schedule(false);
     };
     win.addEventListener('resize', onWindowResize, { passive: true });
     resizeThree();
-    const geometraHandle = createBrowserCanvasClient({
-        ...browserOptions,
-        canvas: geometraCanvas,
-        window: win,
-    });
-    let geometraResizeRafId;
-    const triggerGeometraResize = () => {
-        if (geometraResizeRafId !== undefined)
-            return;
-        geometraResizeRafId = win.requestAnimationFrame(() => {
-            geometraResizeRafId = undefined;
-            win.dispatchEvent(new Event('resize'));
-        });
-    };
+    const geometraHandle = (() => {
+        try {
+            return createBrowserCanvasClient({
+                ...browserOptions,
+                canvas: geometraCanvas,
+                window: win,
+            });
+        }
+        catch (err) {
+            layoutSync.cancel();
+            win.removeEventListener('resize', onWindowResize);
+            disposeGeometraThreeWebGLWithSceneBasics({ renderer: glRenderer, clock });
+            root.remove();
+            throw err;
+        }
+    })();
     const roRoot = new ResizeObserver(() => {
-        resizeThree();
-        triggerGeometraResize();
+        layoutSync.schedule(true);
     });
     roRoot.observe(root);
     const roHud = new ResizeObserver(() => {
-        triggerGeometraResize();
+        layoutSync.schedule(true);
     });
     roHud.observe(geometraHud);
     let rafId;
-    let destroyed = false;
     const destroy = () => {
         if (destroyed)
             return;
@@ -135,15 +158,12 @@ export function createThreeGeometraStackedHost(options) {
             win.cancelAnimationFrame(rafId);
             rafId = undefined;
         }
-        if (geometraResizeRafId !== undefined) {
-            win.cancelAnimationFrame(geometraResizeRafId);
-            geometraResizeRafId = undefined;
-        }
+        layoutSync.cancel();
         win.removeEventListener('resize', onWindowResize);
         roRoot.disconnect();
         roHud.disconnect();
         geometraHandle.destroy();
-        glRenderer.dispose();
+        disposeGeometraThreeWebGLWithSceneBasics({ renderer: glRenderer, clock });
         root.remove();
     };
     const ctxBase = {
@@ -153,14 +173,30 @@ export function createThreeGeometraStackedHost(options) {
         threeCanvas,
         destroy,
     };
-    onThreeReady?.(ctxBase);
+    try {
+        onThreeReady?.(ctxBase);
+    }
+    catch (err) {
+        destroy();
+        throw err;
+    }
     const loop = () => {
         if (destroyed)
             return;
         rafId = win.requestAnimationFrame(loop);
         const delta = clock.getDelta();
         const elapsed = clock.elapsedTime;
-        onThreeFrame?.({ ...ctxBase, clock, delta, elapsed });
+        try {
+            if (onThreeFrame?.({ ...ctxBase, clock, delta, elapsed }) === false) {
+                return;
+            }
+        }
+        catch (err) {
+            destroy();
+            throw err;
+        }
+        if (destroyed)
+            return;
         glRenderer.render(scene, camera);
     };
     if (!destroyed) {