@geometra/renderer-three 0.1.2 → 0.2.0

package/README.md

@@ -2,7 +2,9 @@
 
 **Three.js helpers alongside Geometra** — not a replacement for `@geometra/renderer-canvas`. Geometra’s WebSocket geometry protocol still drives the 2D canvas; Three.js owns WebGL for meshes, scenes, and cameras.
 
-This package ships the **split-view host** pattern (Three.js pane + Geometra pane) as one bootstrap, plus small WebGL sizing utilities.
+This package ships the **split-view host** pattern (Three.js pane + Geometra pane) and a **stacked HUD** host (full-viewport WebGL + corner Geometra overlay) as bootstrap helpers, plus small WebGL sizing utilities.
+
+For the long-term goal — Three.js and Geometra in one **native**, protocol-first, DOM-free space — see [docs/GEOMETRA_NATIVE_SPACE.md](docs/GEOMETRA_NATIVE_SPACE.md). To drive the Cursor Agent CLI in a loop (like the main Geometra repo), use [`scripts/cursor-agent-loop.sh`](scripts/cursor-agent-loop.sh) after installing the [`agent` CLI](https://cursor.com/install); each iteration should pass `npm run release:gate`.
 
 ## Install
 
@@ -39,17 +41,45 @@ const host = createThreeGeometraSplitHost({
 host.destroy()
 ```
 
-`createThreeGeometraSplitHost` forwards all [`createBrowserCanvasClient`](https://github.com/razroo/geometra/tree/main/packages/renderer-canvas) options except `canvas` (it creates the Geometra canvas for you).
+### Stacked HUD (WebGL + overlay)
+
+```ts
+import * as THREE from 'three'
+import { createThreeGeometraStackedHost } from '@geometra/renderer-three'
+
+const stacked = createThreeGeometraStackedHost({
+  container: document.getElementById('app')!,
+  geometraHudWidth: 400,
+  geometraHudHeight: 280,
+  geometraHudPlacement: 'bottom-right',
+  geometraHudMargin: 16,
+  url: 'ws://localhost:8080/geometra-ws',
+  binaryFraming: true,
+  onThreeReady: ({ scene, camera }) => {
+    scene.add(new THREE.AmbientLight(0xffffff, 0.55))
+    camera.position.set(0, 1.5, 6)
+  },
+})
+stacked.destroy()
+```
+
+Use `geometraHudPointerEvents` (CSS `pointer-events`, default `'auto'`) when you want the HUD to ignore input — for example `'none'` so pointer events reach the full-viewport Three.js canvas underneath.
+
+`createThreeGeometraSplitHost` and `createThreeGeometraStackedHost` each forward all [`createBrowserCanvasClient`](https://github.com/razroo/geometra/tree/main/packages/renderer-canvas) options except `canvas` (the host creates the Geometra canvas for you).
 
 ### Geometra resize
 
 The Geometra thin client listens to `window` resize by default. When only the Geometra column changes size, this host dispatches a synthetic `window` `resize` after layout so server layout width/height stay in sync.
 
+### Shared scene / camera defaults (headless-friendly)
+
+`createGeometraThreeSceneBasics` builds a `Scene`, `PerspectiveCamera`, and `Clock` with the same defaults as the split and stacked hosts. Pair it with your own `WebGLRenderer` (or a headless GL context) and `resizeGeometraThreePerspectiveView` so buffer size and camera aspect match those hosts, or use `setWebGLDrawingBufferSize` alone when you already manage aspect and `setPixelRatio` yourself.
+
 ## Roadmap (not in v0)
 
 - Optional **scene-graph extension** to the GEOM protocol (headless + WebGL from the same JSON).
-- **Stacked** overlay (full-viewport WebGL + partial Geometra HUD) with explicit pointer routing.
-- **Node / headless Three** helpers for parity with “AI talks the same protocol” stories.
+- **Stacked** overlay: v0 ships a corner HUD layout; richer stacking (custom regions, explicit `pointer-events` policies) may follow.
+- **Node / headless Three** helpers for parity with “AI talks the same protocol” stories (`createGeometraThreeSceneBasics` is a small shared baseline; richer helpers may follow).
 
 ## Releasing (GitHub + npm)
 

package/dist/index.d.ts

@@ -1,3 +1,7 @@
 export { createThreeGeometraSplitHost, type ThreeGeometraSplitHostHandle, type ThreeGeometraSplitHostOptions, type ThreeFrameContext, type ThreeRuntimeContext, } from './split-host.js';
-export { setWebGLDrawingBufferSize } from './utils.js';
+export { createThreeGeometraStackedHost, type GeometraHudPlacement, type ThreeGeometraStackedHostHandle, type ThreeGeometraStackedHostOptions, } from './stacked-host.js';
+export { resizeGeometraThreePerspectiveView, setWebGLDrawingBufferSize } from './utils.js';
+export { createGeometraThreeSceneBasics, type GeometraThreeSceneBasicsOptions, } from './three-scene-basics.js';
+/** Re-export for hybrid apps using {@link createThreeGeometraSplitHost} with `onData`. */
+export { GEOM_DATA_CHANNEL_TRACKER_SNAPSHOT } from '@geometra/client';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,8BAA8B,EAC9B,KAAK,oBAAoB,EACzB,KAAK,8BAA8B,EACnC,KAAK,+BAA+B,GACrC,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,kCAAkC,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAC1F,OAAO,EACL,8BAA8B,EAC9B,KAAK,+BAA+B,GACrC,MAAM,yBAAyB,CAAA;AAEhC,0FAA0F;AAC1F,OAAO,EAAE,kCAAkC,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -1,3 +1,7 @@
 export { createThreeGeometraSplitHost, } from './split-host.js';
-export { setWebGLDrawingBufferSize } from './utils.js';
+export { createThreeGeometraStackedHost, } from './stacked-host.js';
+export { resizeGeometraThreePerspectiveView, setWebGLDrawingBufferSize } from './utils.js';
+export { createGeometraThreeSceneBasics, } from './three-scene-basics.js';
+/** Re-export for hybrid apps using {@link createThreeGeometraSplitHost} with `onData`. */
+export { GEOM_DATA_CHANNEL_TRACKER_SNAPSHOT } from '@geometra/client';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,GAK7B,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,GAK7B,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,8BAA8B,GAI/B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,kCAAkC,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAC1F,OAAO,EACL,8BAA8B,GAE/B,MAAM,yBAAyB,CAAA;AAEhC,0FAA0F;AAC1F,OAAO,EAAE,kCAAkC,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/split-host.d.ts

@@ -1,25 +1,17 @@
 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';
+export interface ThreeGeometraSplitHostOptions extends Omit<BrowserCanvasClientOptions, 'canvas'>, 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. */
     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;
     /**
      * 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.
      */
     onThreeReady?: (ctx: ThreeRuntimeContext) => void;
     /**
@@ -33,6 +25,8 @@ export interface ThreeRuntimeContext {
     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;
@@ -58,7 +52,15 @@ 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` 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).
+ *
+ * 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.
+ *
+ * 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,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"}

package/dist/split-host.js

@@ -1,5 +1,7 @@
 import * as THREE from 'three';
 import { createBrowserCanvasClient, } from '@geometra/renderer-canvas';
+import { createGeometraThreeSceneBasics } from './three-scene-basics.js';
+import { resizeGeometraThreePerspectiveView } from './utils.js';
 function panelStyle(el, flex) {
     el.style.flex = flex;
     el.style.minWidth = '0';
@@ -17,7 +19,15 @@ 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` 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).
+ *
+ * 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.
+ *
+ * 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;
@@ -57,27 +67,32 @@ export function createThreeGeometraSplitHost(options) {
         antialias: true,
         alpha: false,
     });
-    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 { scene, camera, clock } = createGeometraThreeSceneBasics({
+        threeBackground,
+        cameraFov,
+        cameraNear,
+        cameraFar,
+        cameraPosition,
+    });
     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, win.devicePixelRatio || 1);
+    };
+    const onWindowResize = () => {
+        resizeThree();
     };
+    win.addEventListener('resize', onWindowResize, { passive: true });
     resizeThree();
     const geometraHandle = createBrowserCanvasClient({
         ...browserOptions,
         canvas: geometraCanvas,
         window: win,
     });
+    let geometraResizeRafId;
     const triggerGeometraResize = () => {
-        win.requestAnimationFrame(() => {
+        if (geometraResizeRafId !== undefined)
+            return;
+        geometraResizeRafId = win.requestAnimationFrame(() => {
+            geometraResizeRafId = undefined;
             win.dispatchEvent(new Event('resize'));
         });
     };
@@ -87,37 +102,46 @@ export function createThreeGeometraSplitHost(options) {
     });
     roContainer.observe(threePanel);
     roContainer.observe(geometraPanel);
+    let rafId;
+    let destroyed = false;
+    const destroy = () => {
+        if (destroyed)
+            return;
+        destroyed = true;
+        if (rafId !== undefined) {
+            win.cancelAnimationFrame(rafId);
+            rafId = undefined;
+        }
+        if (geometraResizeRafId !== undefined) {
+            win.cancelAnimationFrame(geometraResizeRafId);
+            geometraResizeRafId = undefined;
+        }
+        win.removeEventListener('resize', onWindowResize);
+        roContainer.disconnect();
+        geometraHandle.destroy();
+        glRenderer.dispose();
+        root.remove();
+    };
     const ctxBase = {
         renderer: glRenderer,
         scene,
         camera,
         threeCanvas,
+        destroy,
     };
     onThreeReady?.(ctxBase);
-    let raf = 0;
-    let destroyed = false;
     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 = () => {
-        if (destroyed)
-            return;
-        destroyed = true;
-        win.cancelAnimationFrame(raf);
-        roContainer.disconnect();
-        geometraHandle.destroy();
-        glRenderer.dispose();
-        if (root.parentNode === container) {
-            container.removeChild(root);
-        }
-    };
+    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":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EACL,yBAAyB,GAG1B,MAAM,2BAA2B,CAAA;AA2DlC,SAAS,UAAU,CAAC,EAAe,EAAE,IAAY;IAC/C,EAAE,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAA;IACpB,EAAE,CAAC,KAAK,CAAC,QAAQ,GAAG,GAAG,CAAA;IACvB,EAAE,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAA;IACxB,EAAE,CAAC,KAAK,CAAC,QAAQ,GAAG,UAAU,CAAA;IAC9B,EAAE,CAAC,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAA;AAC9B,CAAC;AAED,SAAS,cAAc,CAAC,MAAyB;IAC/C,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,OAAO,CAAA;IAC9B,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAA;IAC3B,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAA;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAC1C,OAAsC;IAEtC,MAAM,EACJ,SAAS,EACT,aAAa,GAAG,GAAG,EACnB,cAAc,GAAG,KAAK,EACtB,eAAe,GAAG,QAAQ,EAC1B,SAAS,GAAG,EAAE,EACd,UAAU,GAAG,GAAG,EAChB,SAAS,GAAG,IAAI,EAChB,cAAc,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC1B,YAAY,EACZ,YAAY,EACZ,MAAM,EAAE,cAAc,EACtB,GAAG,cAAc,EAClB,GAAG,OAAO,CAAA;IAEX,MAAM,GAAG,GAAG,SAAS,CAAC,aAAa,CAAA;IACnC,MAAM,GAAG,GAAG,cAAc,IAAI,GAAG,CAAC,WAAW,CAAA;IAC7C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC3E,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;IACrC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,MAAM,CAAA;IAC3B,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAA;IAChC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAA;IACzB,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAA;IAC1B,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAA;IAC1B,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,GAAG,CAAA;IACzB,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;IAE3B,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;IAC3C,UAAU,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;IAEhC,MAAM,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;IAC9C,UAAU,CAAC,aAAa,EAAE,UAAU,CAAC,CAAA;IACrC,aAAa,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,aAAa,IAAI,CAAA;IAChD,aAAa,CAAC,KAAK,CAAC,UAAU,GAAG,GAAG,CAAA;IAEpC,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,UAAU,CAAC,CAAA;IACxC,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAA;IACxC,CAAC;IAED,MAAM,WAAW,GAAG,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAA;IAC/C,cAAc,CAAC,WAAW,CAAC,CAAA;IAC3B,UAAU,CAAC,WAAW,CAAC,WAAW,CAAC,CAAA;IAEnC,MAAM,cAAc,GAAG,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAA;IAClD,cAAc,CAAC,cAAc,CAAC,CAAA;IAC9B,aAAa,CAAC,WAAW,CAAC,cAAc,CAAC,CAAA;IAEzC,MAAM,UAAU,GAAG,IAAI,KAAK,CAAC,aAAa,CAAC;QACzC,MAAM,EAAE,WAAW;QACnB,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,KAAK;KACb,CAAC,CAAA;IACF,UAAU,CAAC,aAAa,CAAC,GAAG,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAA;IAEnD,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,CAAA;IAC/B,KAAK,CAAC,UAAU,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,eAAe,CAAC,CAAA;IAEnD,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,iBAAiB,CAAC,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,CAAA;IAC/E,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAE,EAAE,cAAc,CAAC,CAAC,CAAE,EAAE,cAAc,CAAC,CAAC,CAAE,CAAC,CAAA;IAE/E,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,CAAA;IAE/B,MAAM,WAAW,GAAG,GAAG,EAAE;QACvB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAA;QACzD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAA;QAC1D,MAAM,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAA;QACrB,MAAM,CAAC,sBAAsB,EAAE,CAAA;QAC/B,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAA;IACjC,CAAC,CAAA;IAED,WAAW,EAAE,CAAA;IAEb,MAAM,cAAc,GAAG,yBAAyB,CAAC;QAC/C,GAAG,cAAc;QACjB,MAAM,EAAE,cAAc;QACtB,MAAM,EAAE,GAAG;KACZ,CAAC,CAAA;IAEF,MAAM,qBAAqB,GAAG,GAAG,EAAE;QACjC,GAAG,CAAC,qBAAqB,CAAC,GAAG,EAAE;YAC7B,GAAG,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAA;QACxC,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,MAAM,WAAW,GAAG,IAAI,cAAc,CAAC,GAAG,EAAE;QAC1C,WAAW,EAAE,CAAA;QACb,qBAAqB,EAAE,CAAA;IACzB,CAAC,CAAC,CAAA;IACF,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;IAC/B,WAAW,CAAC,OAAO,CAAC,aAAa,CAAC,CAAA;IAElC,MAAM,OAAO,GAAwB;QACnC,QAAQ,EAAE,UAAU;QACpB,KAAK;QACL,MAAM;QACN,WAAW;KACZ,CAAA;IAED,YAAY,EAAE,CAAC,OAAO,CAAC,CAAA;IAEvB,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,IAAI,SAAS,GAAG,KAAK,CAAA;IAErB,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,IAAI,SAAS;YAAE,OAAM;QACrB,GAAG,GAAG,GAAG,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAA;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAA;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,CAAA;QACjC,YAAY,EAAE,CAAC,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;QACrD,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAClC,CAAC,CAAA;IACD,GAAG,GAAG,GAAG,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAA;IAErC,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,IAAI,SAAS;YAAE,OAAM;QACrB,SAAS,GAAG,IAAI,CAAA;QAChB,GAAG,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAA;QAC7B,WAAW,CAAC,UAAU,EAAE,CAAA;QACxB,cAAc,CAAC,OAAO,EAAE,CAAA;QACxB,UAAU,CAAC,OAAO,EAAE,CAAA;QACpB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;QAC7B,CAAC;IACH,CAAC,CAAA;IAED,OAAO;QACL,IAAI;QACJ,UAAU;QACV,aAAa;QACb,WAAW;QACX,cAAc;QACd,QAAQ,EAAE,UAAU;QACpB,KAAK;QACL,MAAM;QACN,KAAK;QACL,QAAQ,EAAE,cAAc;QACxB,OAAO;KACR,CAAA;AACH,CAAC"}
+{"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,59 @@
+import * as THREE from 'three';
+import { type BrowserCanvasClientHandle, type BrowserCanvasClientOptions } from '@geometra/renderer-canvas';
+import type { 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 {
+    /** Host element; a full-size stacking context is appended (existing children are left untouched). */
+    container: HTMLElement;
+    /** HUD width in CSS pixels. Default: 420. */
+    geometraHudWidth?: number;
+    /** HUD height in CSS pixels. Default: 320. */
+    geometraHudHeight?: number;
+    /** HUD corner. Default: `bottom-right`. */
+    geometraHudPlacement?: GeometraHudPlacement;
+    /** Inset from the chosen corner in CSS pixels. Default: 12. */
+    geometraHudMargin?: number;
+    /**
+     * CSS `pointer-events` on the HUD wrapper (e.g. `'none'` so input falls through to the WebGL canvas).
+     * Default: `'auto'`.
+     */
+    geometraHudPointerEvents?: string;
+    /**
+     * 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.
+     */
+    onThreeReady?: (ctx: ThreeRuntimeContext) => void;
+    /**
+     * Called every frame before `renderer.render`.
+     */
+    onThreeFrame?: (ctx: ThreeFrameContext) => void;
+}
+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;
+    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).
+ *
+ * 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}).
+ * The Three.js layer listens to `window` `resize` for `devicePixelRatio` changes and uses the host `root` size
+ * for the drawing 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,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"}

package/dist/stacked-host.js

@@ -0,0 +1,182 @@
+import * as THREE from 'three';
+import { createBrowserCanvasClient, } from '@geometra/renderer-canvas';
+import { createGeometraThreeSceneBasics } from './three-scene-basics.js';
+import { resizeGeometraThreePerspectiveView } from './utils.js';
+function fullSizeCanvas(canvas) {
+    canvas.style.display = 'block';
+    canvas.style.width = '100%';
+    canvas.style.height = '100%';
+}
+function applyHudPlacement(wrap, placement, marginPx) {
+    const m = `${marginPx}px`;
+    wrap.style.left = '';
+    wrap.style.right = '';
+    wrap.style.top = '';
+    wrap.style.bottom = '';
+    switch (placement) {
+        case 'bottom-right':
+            wrap.style.right = m;
+            wrap.style.bottom = m;
+            break;
+        case 'bottom-left':
+            wrap.style.left = m;
+            wrap.style.bottom = m;
+            break;
+        case 'top-right':
+            wrap.style.right = m;
+            wrap.style.top = m;
+            break;
+        case 'top-left':
+            wrap.style.left = m;
+            wrap.style.top = m;
+            break;
+    }
+}
+/**
+ * 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).
+ *
+ * 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}).
+ * The Three.js layer listens to `window` `resize` for `devicePixelRatio` changes and uses the host `root` size
+ * for the drawing 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 doc = container.ownerDocument;
+    const win = providedWindow ?? doc.defaultView;
+    if (!win) {
+        throw new Error('createThreeGeometraStackedHost requires a browser window');
+    }
+    const root = doc.createElement('div');
+    root.style.position = 'relative';
+    root.style.width = '100%';
+    root.style.height = '100%';
+    root.style.minHeight = '0';
+    root.style.minWidth = '0';
+    root.style.overflow = 'hidden';
+    container.appendChild(root);
+    const threeCanvas = doc.createElement('canvas');
+    fullSizeCanvas(threeCanvas);
+    threeCanvas.style.position = 'absolute';
+    threeCanvas.style.left = '0';
+    threeCanvas.style.top = '0';
+    threeCanvas.style.width = '100%';
+    threeCanvas.style.height = '100%';
+    threeCanvas.style.zIndex = '0';
+    root.appendChild(threeCanvas);
+    const geometraHud = doc.createElement('div');
+    geometraHud.style.position = 'absolute';
+    geometraHud.style.zIndex = '1';
+    geometraHud.style.width = `${geometraHudWidth}px`;
+    geometraHud.style.height = `${geometraHudHeight}px`;
+    geometraHud.style.minWidth = '0';
+    geometraHud.style.minHeight = '0';
+    geometraHud.style.overflow = 'hidden';
+    geometraHud.style.pointerEvents = geometraHudPointerEvents;
+    applyHudPlacement(geometraHud, geometraHudPlacement, geometraHudMargin);
+    root.appendChild(geometraHud);
+    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({
+        threeBackground,
+        cameraFov,
+        cameraNear,
+        cameraFar,
+        cameraPosition,
+    });
+    const resizeThree = () => {
+        resizeGeometraThreePerspectiveView(glRenderer, camera, root.clientWidth, root.clientHeight, win.devicePixelRatio || 1);
+    };
+    const onWindowResize = () => {
+        resizeThree();
+    };
+    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 roRoot = new ResizeObserver(() => {
+        resizeThree();
+        triggerGeometraResize();
+    });
+    roRoot.observe(root);
+    const roHud = new ResizeObserver(() => {
+        triggerGeometraResize();
+    });
+    roHud.observe(geometraHud);
+    let rafId;
+    let destroyed = false;
+    const destroy = () => {
+        if (destroyed)
+            return;
+        destroyed = true;
+        if (rafId !== undefined) {
+            win.cancelAnimationFrame(rafId);
+            rafId = undefined;
+        }
+        if (geometraResizeRafId !== undefined) {
+            win.cancelAnimationFrame(geometraResizeRafId);
+            geometraResizeRafId = undefined;
+        }
+        win.removeEventListener('resize', onWindowResize);
+        roRoot.disconnect();
+        roHud.disconnect();
+        geometraHandle.destroy();
+        glRenderer.dispose();
+        root.remove();
+    };
+    const ctxBase = {
+        renderer: glRenderer,
+        scene,
+        camera,
+        threeCanvas,
+        destroy,
+    };
+    onThreeReady?.(ctxBase);
+    const loop = () => {
+        if (destroyed)
+            return;
+        rafId = win.requestAnimationFrame(loop);
+        const delta = clock.getDelta();
+        const elapsed = clock.elapsedTime;
+        onThreeFrame?.({ ...ctxBase, clock, delta, elapsed });
+        glRenderer.render(scene, camera);
+    };
+    if (!destroyed) {
+        rafId = win.requestAnimationFrame(loop);
+    }
+    return {
+        root,
+        geometraHud,
+        threeCanvas,
+        geometraCanvas,
+        renderer: glRenderer,
+        scene,
+        camera,
+        clock,
+        geometra: geometraHandle,
+        destroy,
+    };
+}
+//# sourceMappingURL=stacked-host.js.map

package/dist/stacked-host.js.map

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

package/dist/three-scene-basics.d.ts

@@ -0,0 +1,27 @@
+import * as THREE from 'three';
+/** Options shared by split/stacked hosts and {@link createGeometraThreeSceneBasics}. */
+export interface GeometraThreeSceneBasicsOptions {
+    /** 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;
+}
+/**
+ * Create a scene, perspective camera, and clock with the same defaults as
+ * {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost}.
+ *
+ * Use this when you want Three.js state aligned with those hosts but manage your own
+ * `WebGLRenderer` (for example headless GL, offscreen canvas, or custom render targets).
+ */
+export declare function createGeometraThreeSceneBasics(options?: GeometraThreeSceneBasicsOptions): {
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    clock: THREE.Clock;
+};
+//# sourceMappingURL=three-scene-basics.d.ts.map

package/dist/three-scene-basics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"three-scene-basics.d.ts","sourceRoot":"","sources":["../src/three-scene-basics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,wFAAwF;AACxF,MAAM,WAAW,+BAA+B;IAC9C,+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;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,+BAAoC,GAC5C;IACD,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;IAClB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAA;IAC/B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAA;CACnB,CAkBA"}

package/dist/three-scene-basics.js

@@ -0,0 +1,18 @@
+import * as THREE from 'three';
+/**
+ * Create a scene, perspective camera, and clock with the same defaults as
+ * {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost}.
+ *
+ * Use this when you want Three.js state aligned with those hosts but manage your own
+ * `WebGLRenderer` (for example headless GL, offscreen canvas, or custom render targets).
+ */
+export function createGeometraThreeSceneBasics(options = {}) {
+    const { threeBackground = 0x000000, cameraFov = 50, cameraNear = 0.1, cameraFar = 2000, cameraPosition = [0, 0, 5], } = options;
+    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();
+    return { scene, camera, clock };
+}
+//# sourceMappingURL=three-scene-basics.js.map

package/dist/three-scene-basics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"three-scene-basics.js","sourceRoot":"","sources":["../src/three-scene-basics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAgB9B;;;;;;GAMG;AACH,MAAM,UAAU,8BAA8B,CAC5C,UAA2C,EAAE;IAM7C,MAAM,EACJ,eAAe,GAAG,QAAQ,EAC1B,SAAS,GAAG,EAAE,EACd,UAAU,GAAG,GAAG,EAChB,SAAS,GAAG,IAAI,EAChB,cAAc,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAC3B,GAAG,OAAO,CAAA;IAEX,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,CAAA;IAC/B,KAAK,CAAC,UAAU,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,eAAe,CAAC,CAAA;IAEnD,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,iBAAiB,CAAC,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,CAAA;IAC/E,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAE,EAAE,cAAc,CAAC,CAAC,CAAE,EAAE,cAAc,CAAC,CAAC,CAAE,CAAC,CAAA;IAE/E,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,CAAA;IAE/B,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC"}

package/dist/utils.d.ts

@@ -1,7 +1,15 @@
-import type { WebGLRenderer } from 'three';
+import type { PerspectiveCamera, WebGLRenderer } from 'three';
 /**
  * Resize drawing buffer to match CSS pixel size × device pixel ratio.
  * Use when you manage your own canvas layout (no `renderer.setSize`).
  */
 export declare function setWebGLDrawingBufferSize(renderer: WebGLRenderer, cssWidth: number, cssHeight: number, pixelRatio?: number): void;
+/**
+ * Apply the same CSS-size → aspect ratio → WebGL buffer sizing path as
+ * {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost}.
+ *
+ * Use with {@link createGeometraThreeSceneBasics} when you own the `WebGLRenderer` (headless GL,
+ * offscreen canvas, tests) but want buffer dimensions and projection to stay aligned with those hosts.
+ */
+export declare function resizeGeometraThreePerspectiveView(renderer: WebGLRenderer, camera: PerspectiveCamera, cssWidth: number, cssHeight: number, pixelRatio: number): void;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI,CAKN"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE7D;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI,CAKN;AAED;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,IAAI,CAON"}

package/dist/utils.js

@@ -8,4 +8,19 @@ export function setWebGLDrawingBufferSize(renderer, cssWidth, cssHeight, pixelRa
     const h = Math.max(1, Math.floor(cssHeight * pr));
     renderer.setDrawingBufferSize(w, h, pr);
 }
+/**
+ * Apply the same CSS-size → aspect ratio → WebGL buffer sizing path as
+ * {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost}.
+ *
+ * Use with {@link createGeometraThreeSceneBasics} when you own the `WebGLRenderer` (headless GL,
+ * offscreen canvas, tests) but want buffer dimensions and projection to stay aligned with those hosts.
+ */
+export function resizeGeometraThreePerspectiveView(renderer, camera, cssWidth, cssHeight, pixelRatio) {
+    renderer.setPixelRatio(pixelRatio);
+    const w = Math.max(1, Math.floor(cssWidth));
+    const h = Math.max(1, Math.floor(cssHeight));
+    camera.aspect = w / h;
+    camera.updateProjectionMatrix();
+    renderer.setSize(w, h, false);
+}
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAuB,EACvB,QAAgB,EAChB,SAAiB,EACjB,UAAmB;IAEnB,MAAM,EAAE,GAAG,UAAU,IAAI,CAAC,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3F,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAA;IAChD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC,CAAC,CAAA;IACjD,QAAQ,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;AACzC,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAuB,EACvB,QAAgB,EAChB,SAAiB,EACjB,UAAmB;IAEnB,MAAM,EAAE,GAAG,UAAU,IAAI,CAAC,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3F,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAA;IAChD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC,CAAC,CAAA;IACjD,QAAQ,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kCAAkC,CAChD,QAAuB,EACvB,MAAyB,EACzB,QAAgB,EAChB,SAAiB,EACjB,UAAkB;IAElB,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAAA;IAClC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC3C,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAA;IAC5C,MAAM,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAA;IACrB,MAAM,CAAC,sBAAsB,EAAE,CAAA;IAC/B,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAA;AAC/B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/renderer-three",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Three.js render target helpers for Geometra — stack WebGL with the geometry-streamed canvas client",
   "license": "MIT",
   "type": "module",
@@ -33,24 +33,21 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "check": "tsc --noEmit -p tsconfig.json",
-    "release:gate": "npm run check && npm run build",
+    "verify:exports": "node scripts/verify-exports.mjs",
+    "verify:utils": "node scripts/verify-utils.mjs",
+    "release:gate": "npm run check && npm run build && npm run verify:exports && npm run verify:utils",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "@geometra/renderer-canvas": "^1.2.1",
+    "@geometra/renderer-canvas": "^1.2.2",
     "three": ">=0.160.0 <0.180.0"
   },
   "devDependencies": {
-    "@geometra/client": "^1.2.1",
-    "@geometra/renderer-canvas": "^1.2.1",
+    "@geometra/client": "^1.2.2",
+    "@geometra/renderer-canvas": "^1.2.2",
     "@types/three": "^0.170.0",
     "three": "^0.170.0",
     "typescript": "^6.0.2"
-  },
-  "overrides": {
-    "@geometra/renderer-canvas": {
-      "@geometra/client": "^1.2.1"
-    }
   }
 }