@geometra/renderer-three 0.1.3 → 1.3.1

package/dist/split-host.d.ts

@@ -1,38 +1,57 @@
 import * as THREE from 'three';
 import { type BrowserCanvasClientHandle, type BrowserCanvasClientOptions } from '@geometra/renderer-canvas';
-export interface ThreeGeometraSplitHostOptions extends Omit<BrowserCanvasClientOptions, 'canvas'> {
+import { type GeometraThreeSceneBasicsOptions } from './three-scene-basics.js';
+/**
+ * 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;
-    /** Clear color for the Three.js scene. Default: `0x000000`. */
-    threeBackground?: THREE.ColorRepresentation;
-    /** Perspective camera FOV in degrees. Default: 50. */
-    cameraFov?: number;
-    /** Near plane. Default: 0.1. */
-    cameraNear?: number;
-    /** Far plane. Default: 2000. */
-    cameraFar?: number;
-    /** Initial camera position. Default: `(0, 0, 5)`. */
-    cameraPosition?: THREE.Vector3Tuple;
+    /**
+     * 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.
+     * Add meshes, lights, controls, etc. 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`.
-     * 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;
     scene: THREE.Scene;
     camera: THREE.PerspectiveCamera;
     threeCanvas: HTMLCanvasElement;
+    /** Same as `ThreeGeometraSplitHostHandle.destroy` — idempotent full teardown. */
+    destroy(): void;
 }
 export interface ThreeFrameContext extends ThreeRuntimeContext {
     clock: THREE.Clock;
@@ -50,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;
 }
 /**
@@ -58,7 +82,24 @@ 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.
+ * 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. 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 declare function createThreeGeometraSplitHost(options: ThreeGeometraSplitHostOptions): ThreeGeometraSplitHostHandle;
 //# sourceMappingURL=split-host.d.ts.map

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;AAElC,MAAM,WAAW,6BAA8B,SAAQ,IAAI,CAAC,0BAA0B,EAAE,QAAQ,CAAC;IAC/F,8FAA8F;IAC9F,SAAS,EAAE,WAAW,CAAA;IACtB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gGAAgG;IAChG,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,KAAK,CAAC,mBAAmB,CAAA;IAC3C,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qDAAqD;IACrD,cAAc,CAAC,EAAE,KAAK,CAAC,YAAY,CAAA;IACnC;;;OAGG;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;CAC/B;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;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,6BAA6B,GACrC,4BAA4B,CAgJ9B"}
+{"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,5 +1,15 @@
-import * as THREE from 'three';
 import { createBrowserCanvasClient, } from '@geometra/renderer-canvas';
+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';
@@ -17,10 +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.
+ * 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. 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) {
@@ -52,72 +80,103 @@ 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 { renderer: glRenderer, scene, camera, clock } = createGeometraThreeWebGLWithSceneBasics(threeCanvas, {
+        threeBackground,
+        cameraFov,
+        cameraNear,
+        cameraFar,
+        cameraPosition,
     });
-    glRenderer.setPixelRatio(win.devicePixelRatio || 1);
-    const scene = new THREE.Scene();
-    scene.background = new THREE.Color(threeBackground);
-    const camera = new THREE.PerspectiveCamera(cameraFov, 1, cameraNear, cameraFar);
-    camera.position.set(cameraPosition[0], cameraPosition[1], cameraPosition[2]);
-    const clock = new THREE.Clock();
     const resizeThree = () => {
-        const w = Math.max(1, Math.floor(threePanel.clientWidth));
-        const h = Math.max(1, Math.floor(threePanel.clientHeight));
-        camera.aspect = w / h;
-        camera.updateProjectionMatrix();
-        glRenderer.setSize(w, h, false);
+        resizeGeometraThreePerspectiveView(glRenderer, camera, threePanel.clientWidth, threePanel.clientHeight, resolveHostDevicePixelRatio(win.devicePixelRatio || 1, maxDevicePixelRatio));
     };
-    resizeThree();
-    const geometraHandle = createBrowserCanvasClient({
-        ...browserOptions,
-        canvas: geometraCanvas,
-        window: win,
-    });
-    const triggerGeometraResize = () => {
-        win.requestAnimationFrame(() => {
+    let destroyed = false;
+    const layoutSync = createGeometraHostLayoutSyncRaf(win, {
+        isDestroyed: () => destroyed,
+        syncLayout: resizeThree,
+        dispatchGeometraResize: () => {
             win.dispatchEvent(new Event('resize'));
-        });
+        },
+    });
+    const onWindowResize = () => {
+        layoutSync.schedule(false);
     };
+    win.addEventListener('resize', onWindowResize, { passive: true });
+    resizeThree();
+    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;
+    const destroy = () => {
+        if (destroyed)
+            return;
+        destroyed = true;
+        if (rafId !== undefined) {
+            win.cancelAnimationFrame(rafId);
+            rafId = undefined;
+        }
+        layoutSync.cancel();
+        win.removeEventListener('resize', onWindowResize);
+        roContainer.disconnect();
+        geometraHandle.destroy();
+        disposeGeometraThreeWebGLWithSceneBasics({ renderer: glRenderer, clock });
+        root.remove();
+    };
     const ctxBase = {
         renderer: glRenderer,
         scene,
         camera,
         threeCanvas,
+        destroy,
     };
-    onThreeReady?.(ctxBase);
-    let raf = 0;
-    let destroyed = false;
+    try {
+        onThreeReady?.(ctxBase);
+    }
+    catch (err) {
+        destroy();
+        throw err;
+    }
     const loop = () => {
         if (destroyed)
             return;
-        raf = win.requestAnimationFrame(loop);
+        rafId = win.requestAnimationFrame(loop);
         const delta = clock.getDelta();
         const elapsed = clock.elapsedTime;
-        onThreeFrame?.({ ...ctxBase, clock, delta, elapsed });
-        glRenderer.render(scene, camera);
-    };
-    raf = win.requestAnimationFrame(loop);
-    const destroy = () => {
+        try {
+            if (onThreeFrame?.({ ...ctxBase, clock, delta, elapsed }) === false) {
+                return;
+            }
+        }
+        catch (err) {
+            destroy();
+            throw err;
+        }
         if (destroyed)
             return;
-        destroyed = true;
-        win.cancelAnimationFrame(raf);
-        roContainer.disconnect();
-        geometraHandle.destroy();
-        glRenderer.dispose();
-        if (root.parentNode === container) {
-            container.removeChild(root);
-        }
+        glRenderer.render(scene, camera);
     };
+    if (!destroyed) {
+        rafId = win.requestAnimationFrame(loop);
+    }
     return {
         root,
         threePanel,

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

@@ -0,0 +1,109 @@
+import * as THREE from 'three';
+import { type BrowserCanvasClientHandle } from '@geometra/renderer-canvas';
+import type { GeometraHostBrowserCanvasClientOptions, ThreeFrameContext, ThreeRuntimeContext } from './split-host.js';
+import { type GeometraThreeSceneBasicsOptions } from './three-scene-basics.js';
+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: {@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: {@link GEOMETRA_STACKED_HOST_LAYOUT_DEFAULTS.geometraHudHeight}.
+     * Non-finite or negative values fall back to the default.
+     */
+    geometraHudHeight?: number;
+    /**
+     * 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: {@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'`. 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 | false;
+}
+export interface ThreeGeometraStackedHostHandle {
+    root: HTMLDivElement;
+    /** Absolutely positioned wrapper around the Geometra canvas (stacked HUD). */
+    geometraHud: HTMLDivElement;
+    threeCanvas: HTMLCanvasElement;
+    geometraCanvas: HTMLCanvasElement;
+    renderer: THREE.WebGLRenderer;
+    scene: THREE.Scene;
+    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
+ * (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. 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

@@ -0,0 +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,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"}