@geometra/renderer-three 0.1.3 → 1.3.1

package/dist/three-scene-basics.js

@@ -0,0 +1,435 @@
+import * as THREE from 'three';
+import { GEOMETRA_HEADLESS_RAW_DEVICE_PIXEL_RATIO, isPlainGeometraThreeViewSizingState, resizeGeometraThreePerspectiveView, resolveHostDevicePixelRatio, toPlainGeometraThreeViewSizingState, toPlainGeometraThreeViewSizingStateHeadless, } from './utils.js';
+const geometraDisposedWebGLRenderers = new WeakSet();
+/**
+ * Scene and camera defaults shared by {@link createThreeGeometraSplitHost},
+ * {@link createThreeGeometraStackedHost}, and {@link createGeometraThreeSceneBasics}.
+ * Use in headless or custom renderer setups so numbers stay aligned with those hosts
+ * without copying literals from the README.
+ */
+export const GEOMETRA_THREE_HOST_SCENE_DEFAULTS = {
+    threeBackground: 0x000000,
+    cameraFov: 50,
+    cameraNear: 0.1,
+    cameraFar: 2000,
+    cameraPosition: [0, 0, 5],
+};
+function coerceGeometraThreeSceneBasicsCamera(merged) {
+    const d = GEOMETRA_THREE_HOST_SCENE_DEFAULTS;
+    const cameraFov = Number.isFinite(merged.cameraFov) && merged.cameraFov > 0 && merged.cameraFov < 180
+        ? merged.cameraFov
+        : d.cameraFov;
+    let cameraNear = Number.isFinite(merged.cameraNear) && merged.cameraNear > 0 ? merged.cameraNear : d.cameraNear;
+    let cameraFar = merged.cameraFar;
+    if (!Number.isFinite(cameraFar) || cameraFar <= cameraNear) {
+        cameraFar = d.cameraFar > cameraNear ? d.cameraFar : cameraNear * 2;
+    }
+    const [px, py, pz] = merged.cameraPosition;
+    const [dx, dy, dz] = d.cameraPosition;
+    const cameraPosition = [
+        Number.isFinite(px) ? px : dx,
+        Number.isFinite(py) ? py : dy,
+        Number.isFinite(pz) ? pz : dz,
+    ];
+    return { cameraFov, cameraNear, cameraFar, cameraPosition };
+}
+/**
+ * Fully merged and coerced {@link GeometraThreeSceneBasicsOptions} using the same rules as
+ * {@link createGeometraThreeSceneBasics} (and split/stacked hosts).
+ *
+ * Use when you need host-aligned numbers for logging, tests, or agent-side protocol payloads without
+ * constructing a {@link THREE.Scene} or {@link THREE.PerspectiveCamera}.
+ */
+export function resolveGeometraThreeSceneBasicsOptions(options = {}) {
+    const merged = { ...GEOMETRA_THREE_HOST_SCENE_DEFAULTS, ...options };
+    const { cameraFov, cameraNear, cameraFar, cameraPosition } = coerceGeometraThreeSceneBasicsCamera(merged);
+    return {
+        threeBackground: merged.threeBackground,
+        cameraFov,
+        cameraNear,
+        cameraFar,
+        cameraPosition,
+    };
+}
+/**
+ * Same coercion as {@link resolveGeometraThreeSceneBasicsOptions}, plus a hex background for stable JSON.
+ */
+export function toPlainGeometraThreeSceneBasicsOptions(options = {}) {
+    const resolved = resolveGeometraThreeSceneBasicsOptions(options);
+    const threeBackgroundHex = new THREE.Color(resolved.threeBackground).getHex();
+    return {
+        threeBackgroundHex,
+        cameraFov: resolved.cameraFov,
+        cameraNear: resolved.cameraNear,
+        cameraFar: resolved.cameraFar,
+        cameraPosition: [...resolved.cameraPosition],
+    };
+}
+/**
+ * Build {@link GeometraThreeSceneBasics} from {@link PlainGeometraThreeSceneBasicsOptions} (for example
+ * `JSON.parse` of logs, tests, or agent payloads). Maps `threeBackgroundHex` to {@link GeometraThreeSceneBasicsOptions.threeBackground}
+ * and forwards camera fields through {@link createGeometraThreeSceneBasics}, so invalid numbers get the same
+ * coercion as split/stacked hosts and {@link toPlainGeometraThreeSceneBasicsOptions} output round-trips when
+ * re-applied here.
+ */
+export function createGeometraThreeSceneBasicsFromPlain(plain) {
+    return createGeometraThreeSceneBasics({
+        threeBackground: plain.threeBackgroundHex,
+        cameraFov: plain.cameraFov,
+        cameraNear: plain.cameraNear,
+        cameraFar: plain.cameraFar,
+        cameraPosition: [...plain.cameraPosition],
+    });
+}
+function isPlainCameraPosition(value) {
+    return (Array.isArray(value) &&
+        value.length === 3 &&
+        value.every((n) => typeof n === 'number' && Number.isFinite(n)));
+}
+function isPlainGeometraThreeSceneBasicsOptionsRecord(o) {
+    if (typeof o.threeBackgroundHex !== 'number' || !Number.isFinite(o.threeBackgroundHex)) {
+        return false;
+    }
+    const fov = o.cameraFov;
+    if (typeof fov !== 'number' || !Number.isFinite(fov) || fov <= 0 || fov >= 180) {
+        return false;
+    }
+    const near = o.cameraNear;
+    const far = o.cameraFar;
+    if (typeof near !== 'number' || !Number.isFinite(near) || near <= 0)
+        return false;
+    if (typeof far !== 'number' || !Number.isFinite(far) || far <= near)
+        return false;
+    return isPlainCameraPosition(o.cameraPosition);
+}
+/**
+ * Narrow `unknown` (e.g. `JSON.parse`) to {@link PlainGeometraThreeSceneBasicsOptions} — the scene/camera
+ * fields from {@link toPlainGeometraThreeSceneBasicsOptions} without viewport sizing. Extra keys are allowed.
+ * Pair with {@link isPlainGeometraThreeViewSizingState} when you need both slices before merging or calling
+ * {@link createGeometraThreeSceneBasicsFromPlain}.
+ */
+export function isPlainGeometraThreeSceneBasicsOptions(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    return isPlainGeometraThreeSceneBasicsOptionsRecord(value);
+}
+/**
+ * Narrow `unknown` (e.g. `JSON.parse`) to {@link PlainGeometraThreeHostSnapshot} when the object matches
+ * the shape from {@link toPlainGeometraThreeHostSnapshot} / {@link toPlainGeometraThreeHostSnapshotHeadless} /
+ * {@link toPlainGeometraThreeHostSnapshotFromViewSizing}. Extra keys (e.g. hybrid layout fields) are allowed.
+ * Composite payloads use {@link isPlainGeometraThreeSplitHostSnapshot} / {@link isPlainGeometraThreeStackedHostSnapshot}.
+ */
+export function isPlainGeometraThreeHostSnapshot(value) {
+    if (!isPlainGeometraThreeViewSizingState(value))
+        return false;
+    return isPlainGeometraThreeSceneBasicsOptionsRecord(value);
+}
+/**
+ * Merge host-aligned viewport sizing and scene/camera plain fields for stable JSON.
+ *
+ * @see PlainGeometraThreeHostSnapshot
+ */
+export function toPlainGeometraThreeHostSnapshot(cssWidth, cssHeight, rawDevicePixelRatio, maxDevicePixelRatio, sceneBasicsOptions = {}) {
+    return {
+        ...toPlainGeometraThreeViewSizingState(cssWidth, cssHeight, rawDevicePixelRatio, maxDevicePixelRatio),
+        ...toPlainGeometraThreeSceneBasicsOptions(sceneBasicsOptions),
+    };
+}
+/**
+ * Same plain snapshot as {@link toPlainGeometraThreeHostSnapshot} with raw device pixel ratio **1** —
+ * the baseline after `win.devicePixelRatio || 1` when the ratio is missing, and the same raw input as
+ * {@link resolveHeadlessHostDevicePixelRatio} when you only apply an optional cap.
+ *
+ * Viewport fields match {@link toPlainGeometraThreeViewSizingStateHeadless}; for sizing-only JSON, call
+ * that helper directly.
+ *
+ * For headless GL, Node, tests, or agent payloads without a browser `window`, call this instead of
+ * passing a literal `1` as `rawDevicePixelRatio` everywhere.
+ */
+export function toPlainGeometraThreeHostSnapshotHeadless(cssWidth, cssHeight, maxDevicePixelRatio, sceneBasicsOptions = {}) {
+    return {
+        ...toPlainGeometraThreeViewSizingStateHeadless(cssWidth, cssHeight, maxDevicePixelRatio),
+        ...toPlainGeometraThreeSceneBasicsOptions(sceneBasicsOptions),
+    };
+}
+/**
+ * Merge an existing {@link PlainGeometraThreeViewSizingState} (from {@link toPlainGeometraThreeViewSizingState}
+ * or your own pipeline) with {@link toPlainGeometraThreeSceneBasicsOptions} into one
+ * {@link PlainGeometraThreeHostSnapshot}.
+ *
+ * Use in headless loops, tests, or agent payloads when layout/DPR sizing is computed once and scene/camera
+ * options are added later, without re-running {@link toPlainGeometraThreeViewSizingState}.
+ */
+export function toPlainGeometraThreeHostSnapshotFromViewSizing(sizing, sceneBasicsOptions = {}) {
+    return {
+        ...sizing,
+        ...toPlainGeometraThreeSceneBasicsOptions(sceneBasicsOptions),
+    };
+}
+/**
+ * Combine an existing {@link PlainGeometraThreeViewSizingState} with an already-plain scene slice
+ * {@link PlainGeometraThreeSceneBasicsOptions} (for example after {@link isPlainGeometraThreeViewSizingState}
+ * and {@link isPlainGeometraThreeSceneBasicsOptions}) into one {@link PlainGeometraThreeHostSnapshot}.
+ *
+ * Same object shape as {@link toPlainGeometraThreeHostSnapshotFromViewSizing} when `scene` is the output of
+ * {@link toPlainGeometraThreeSceneBasicsOptions}, but skips a redundant {@link THREE.Color} round-trip when
+ * the scene fields are already JSON-stable.
+ */
+export function mergePlainGeometraThreeHostSnapshot(sizing, scene) {
+    return { ...sizing, ...scene };
+}
+/**
+ * `WebGLRenderer` constructor options (excluding `canvas`) used by
+ * {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost}.
+ *
+ * Typed as {@link WebGLRendererParameters} minus `canvas` so custom renderers stay compatible with
+ * Three’s constructor surface when you extend or mirror these flags.
+ *
+ * Spread into your own `new WebGLRenderer({ canvas, ...GEOMETRA_HOST_WEBGL_RENDERER_OPTIONS })` when
+ * you manage the renderer (headless GL, offscreen canvas, tests) so flags stay aligned with those hosts.
+ */
+export const GEOMETRA_HOST_WEBGL_RENDERER_OPTIONS = {
+    antialias: true,
+    alpha: false,
+};
+/**
+ * Full {@link WebGLRendererParameters} for `new WebGLRenderer(...)`, with the same flags as
+ * {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost} plus your `canvas`.
+ *
+ * Use in headless GL, offscreen canvas, or custom hosts so constructor input stays aligned with
+ * those packages without copying {@link GEOMETRA_HOST_WEBGL_RENDERER_OPTIONS} at every call site.
+ */
+export function createGeometraHostWebGLRendererParams(canvas) {
+    return { canvas, ...GEOMETRA_HOST_WEBGL_RENDERER_OPTIONS };
+}
+/**
+ * `new WebGLRenderer(createGeometraHostWebGLRendererParams(canvas))` with the same flags as
+ * {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost}.
+ *
+ * Use in the browser or any environment where Three can create a GL context (offscreen canvas,
+ * custom hosts). Prefer {@link createGeometraHostWebGLRendererParams} when you need to spread
+ * into a larger parameter object.
+ */
+export function createGeometraThreeWebGLRenderer(canvas) {
+    return new THREE.WebGLRenderer(createGeometraHostWebGLRendererParams(canvas));
+}
+/**
+ * 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).
+ *
+ * Non-finite or invalid perspective settings fall back to {@link GEOMETRA_THREE_HOST_SCENE_DEFAULTS}
+ * (or `far = max(default far, near × 2)` when the default far is not past a coerced near plane).
+ *
+ * @returns A {@link GeometraThreeSceneBasics} value aligned with split/stacked host defaults.
+ */
+export function createGeometraThreeSceneBasics(options = {}) {
+    const resolved = resolveGeometraThreeSceneBasicsOptions(options);
+    const { threeBackground, cameraFov, cameraNear, cameraFar, cameraPosition } = resolved;
+    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 };
+}
+/**
+ * Create a {@link THREE.WebGLRenderer} and {@link GeometraThreeSceneBasics} in one call, using the same
+ * constructor flags and scene defaults as {@link createThreeGeometraSplitHost} and
+ * {@link createThreeGeometraStackedHost}.
+ *
+ * Equivalent to {@link createGeometraThreeWebGLRenderer} on `canvas` plus
+ * {@link createGeometraThreeSceneBasics} with the same `options` — useful for offscreen canvas, custom hosts, or
+ * agent-side bootstrap where you want parity without duplicating the two factories.
+ *
+ * Requires a WebGL-capable environment (same as `new WebGLRenderer(...)`).
+ */
+export function createGeometraThreeWebGLWithSceneBasics(canvas, options = {}) {
+    const renderer = createGeometraThreeWebGLRenderer(canvas);
+    const { scene, camera, clock } = createGeometraThreeSceneBasics(options);
+    return { renderer, scene, camera, clock };
+}
+/**
+ * Same host-aligned renderer + scene bundle as {@link createGeometraThreeWebGLWithSceneBasics}, but scene and
+ * camera are built from {@link PlainGeometraThreeSceneBasicsOptions} (for example `JSON.parse` of logs, tests,
+ * or agent payloads) via {@link createGeometraThreeSceneBasicsFromPlain}, so invalid fields get the same coercion
+ * as split/stacked hosts without manually mapping `threeBackgroundHex` into {@link GeometraThreeSceneBasicsOptions}.
+ *
+ * Requires a WebGL-capable environment (same as `new WebGLRenderer(...)`).
+ */
+export function createGeometraThreeWebGLWithSceneBasicsFromPlain(canvas, plain) {
+    const renderer = createGeometraThreeWebGLRenderer(canvas);
+    const { scene, camera, clock } = createGeometraThreeSceneBasicsFromPlain(plain);
+    return { renderer, scene, camera, clock };
+}
+/**
+ * Tear down the {@link THREE.WebGLRenderer} from {@link createGeometraThreeWebGLWithSceneBasics}
+ * (or any bundle that shares the same `renderer` reference).
+ *
+ * When `clock` is passed (for example the same bundle from {@link createGeometraThreeWebGLWithSceneBasics}),
+ * calls {@link THREE.Clock.stop} before {@link THREE.WebGLRenderer.dispose} so `getDelta` / `elapsedTime`
+ * do not keep advancing after teardown in headless ticks or agent loops.
+ *
+ * Calls {@link THREE.WebGLRenderer.dispose}; it does not traverse the scene or dispose meshes,
+ * materials, or textures — keep that cleanup in app code or a future helper if you need it.
+ *
+ * Registers the renderer so {@link tickGeometraThreeWebGLWithSceneBasicsFrame} skips a subsequent
+ * `render` when teardown runs inside `onFrame`, matching split/stacked hosts after {@link ThreeRuntimeContext.destroy}.
+ */
+export function disposeGeometraThreeWebGLWithSceneBasics(bundle) {
+    bundle.clock?.stop();
+    geometraDisposedWebGLRenderers.add(bundle.renderer);
+    bundle.renderer.dispose();
+}
+/**
+ * Resize renderer and camera from {@link createGeometraThreeWebGLWithSceneBasics} using the same CSS layout,
+ * {@link resolveHostDevicePixelRatio} capping, and {@link resizeGeometraThreePerspectiveView} path as
+ * {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost}.
+ *
+ * Use in headless GL, offscreen canvas, or custom hosts when you already hold the bundle and a layout size
+ * (e.g. from your own layout pass). Pass `rawDevicePixelRatio` from `window.devicePixelRatio` in the browser
+ * or `1` when there is no window.
+ *
+ * Equivalent to calling {@link resizeGeometraThreePerspectiveView} on `bundle.renderer` and `bundle.camera` with
+ * `resolveHostDevicePixelRatio(rawDevicePixelRatio, maxDevicePixelRatio)`.
+ */
+export function resizeGeometraThreeWebGLWithSceneBasicsView(bundle, cssWidth, cssHeight, rawDevicePixelRatio, maxDevicePixelRatio) {
+    resizeGeometraThreePerspectiveView(bundle.renderer, bundle.camera, cssWidth, cssHeight, resolveHostDevicePixelRatio(rawDevicePixelRatio, maxDevicePixelRatio));
+}
+/**
+ * Same as {@link resizeGeometraThreeWebGLWithSceneBasicsView} with raw device pixel ratio fixed at **1** —
+ * parity with {@link resolveHeadlessHostDevicePixelRatio} and {@link toPlainGeometraThreeHostSnapshotHeadless}
+ * for headless GL, Node, tests, or agent loops without a browser `window`.
+ */
+export function resizeGeometraThreeWebGLWithSceneBasicsViewHeadless(bundle, cssWidth, cssHeight, maxDevicePixelRatio) {
+    resizeGeometraThreeWebGLWithSceneBasicsView(bundle, cssWidth, cssHeight, GEOMETRA_HEADLESS_RAW_DEVICE_PIXEL_RATIO, maxDevicePixelRatio);
+}
+/**
+ * Resize from {@link PlainGeometraThreeViewSizingState} using `layoutWidth`, `layoutHeight`, and
+ * `effectiveDevicePixelRatio` — equivalent to
+ * {@link resizeGeometraThreeWebGLWithSceneBasicsView} with those dimensions and the same effective ratio
+ * the plain helpers compute from raw DPR and optional cap.
+ *
+ * Accepts any object with those fields, including a full {@link PlainGeometraThreeHostSnapshot} or composite
+ * split/stacked snapshot (extra keys ignored). Use when logs, tests, or agents already validated viewport JSON
+ * via {@link isPlainGeometraThreeHostSnapshot} and should not re-derive {@link resolveHostDevicePixelRatio}
+ * from partial inputs.
+ */
+export function resizeGeometraThreeWebGLWithSceneBasicsViewFromPlainViewSizing(bundle, sizing) {
+    resizeGeometraThreePerspectiveView(bundle.renderer, bundle.camera, sizing.layoutWidth, sizing.layoutHeight, sizing.effectiveDevicePixelRatio);
+}
+/**
+ * One `renderer.render(scene, camera)` pass for a {@link GeometraThreeWebGLWithSceneBasics} bundle.
+ *
+ * Use in headless GL, tests, or agent-style loops after
+ * {@link resizeGeometraThreeWebGLWithSceneBasicsView} (or your own sizing) so a single frame matches
+ * the same scene/camera/renderer wiring as {@link createThreeGeometraSplitHost} /
+ * {@link createThreeGeometraStackedHost} without duplicating the render call.
+ *
+ * No-ops when the same `renderer` was already passed to {@link disposeGeometraThreeWebGLWithSceneBasics}
+ * — same skip-after-dispose registration as {@link tickGeometraThreeWebGLWithSceneBasicsFrame}.
+ */
+export function renderGeometraThreeWebGLWithSceneBasicsFrame(bundle) {
+    if (geometraDisposedWebGLRenderers.has(bundle.renderer)) {
+        return;
+    }
+    bundle.renderer.render(bundle.scene, bundle.camera);
+}
+/**
+ * Same per-frame ordering as {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost}:
+ * `clock.getDelta()` / `elapsedTime`, optional callback, then `renderer.render`.
+ *
+ * If `onFrame` returns **`false`**, `renderer.render` is skipped and this function returns **`false`** —
+ * parity with {@link ThreeGeometraSplitHostOptions.onThreeFrame} / stacked host `onThreeFrame` returning `false`.
+ * If `onFrame` calls {@link disposeGeometraThreeWebGLWithSceneBasics} on the same bundle (same idea as
+ * {@link ThreeRuntimeContext.destroy} in browser hosts), `render` is skipped and this returns **`false`** even when
+ * the callback does not return `false`. `undefined` and other return values still render when the renderer was not
+ * disposed through that helper, and the function returns **`true`** when `render` runs.
+ *
+ * If `onFrame` **throws**, the error propagates and `renderer.render` is not called — same ordering as browser
+ * hosts, which run the frame callback before `render`.
+ *
+ * Use in headless GL, tests, or agent loops when you want {@link THREE.Clock} timing parity with those hosts
+ * without duplicating the loop body. Omit the callback to match a tick that only advances the clock and renders.
+ *
+ * @returns `true` if `renderer.render` ran, `false` if `onFrame` returned `false` (draw skipped).
+ */
+export function tickGeometraThreeWebGLWithSceneBasicsFrame(bundle, onFrame) {
+    const { renderer, scene, camera, clock } = bundle;
+    const delta = clock.getDelta();
+    const elapsed = clock.elapsedTime;
+    if (onFrame?.({ renderer, scene, camera, clock, delta, elapsed }) === false) {
+        return false;
+    }
+    if (geometraDisposedWebGLRenderers.has(renderer)) {
+        return false;
+    }
+    renderer.render(scene, camera);
+    return true;
+}
+/**
+ * One-step frame: {@link resizeGeometraThreeWebGLWithSceneBasicsView}, then
+ * {@link tickGeometraThreeWebGLWithSceneBasicsFrame} — same as calling those two in sequence (resize
+ * before `clock.getDelta()` / `onFrame` / `render`).
+ *
+ * Use when you have an explicit raw device pixel ratio (for example `window.devicePixelRatio || 1` from a
+ * provided `window`, or a simulated value in tests and agent loops) and want the same resize + frame
+ * ordering as {@link createThreeGeometraSplitHost} / {@link createThreeGeometraStackedHost} without inlining
+ * both calls.
+ *
+ * For raw DPR **1** without repeating that literal, prefer {@link resizeTickGeometraThreeWebGLWithSceneBasicsHeadless}.
+ *
+ * @returns Same boolean as {@link tickGeometraThreeWebGLWithSceneBasicsFrame}.
+ */
+export function resizeTickGeometraThreeWebGLWithSceneBasics(bundle, cssWidth, cssHeight, rawDevicePixelRatio, maxDevicePixelRatio, onFrame) {
+    resizeGeometraThreeWebGLWithSceneBasicsView(bundle, cssWidth, cssHeight, rawDevicePixelRatio, maxDevicePixelRatio);
+    return tickGeometraThreeWebGLWithSceneBasicsFrame(bundle, onFrame);
+}
+/**
+ * Headless one-step frame: {@link resizeGeometraThreeWebGLWithSceneBasicsViewHeadless}, then
+ * {@link tickGeometraThreeWebGLWithSceneBasicsFrame} — same as calling those two in sequence (resize
+ * before `clock.getDelta()` / `onFrame` / `render`).
+ *
+ * Equivalent to {@link resizeTickGeometraThreeWebGLWithSceneBasics} with `rawDevicePixelRatio` **1** and
+ * the same optional `maxDevicePixelRatio` / `onFrame` arguments.
+ *
+ * For Node, headless WebGL, tests, or agent loops that need buffer + camera sync on every tick with raw
+ * DPR **1** and the same optional cap as the browser hosts, without repeating the pair at every call site.
+ *
+ * @returns Same boolean as {@link tickGeometraThreeWebGLWithSceneBasicsFrame}.
+ */
+export function resizeTickGeometraThreeWebGLWithSceneBasicsHeadless(bundle, cssWidth, cssHeight, maxDevicePixelRatio, onFrame) {
+    return resizeTickGeometraThreeWebGLWithSceneBasics(bundle, cssWidth, cssHeight, GEOMETRA_HEADLESS_RAW_DEVICE_PIXEL_RATIO, maxDevicePixelRatio, onFrame);
+}
+/**
+ * Resize from {@link PlainGeometraThreeViewSizingState}, then {@link tickGeometraThreeWebGLWithSceneBasicsFrame} —
+ * same as calling those two in sequence (resize before `clock.getDelta()` / `onFrame` / `render`).
+ *
+ * Use in headless GL, tests, or agent loops when viewport JSON is already validated (for example with
+ * {@link isPlainGeometraThreeHostSnapshot}) and you want the same one-step flow as
+ * {@link resizeTickGeometraThreeWebGLWithSceneBasics} without re-supplying raw DPR and `maxDevicePixelRatio` on
+ * every tick.
+ *
+ * @returns Same boolean as {@link tickGeometraThreeWebGLWithSceneBasicsFrame}.
+ */
+export function resizeTickGeometraThreeWebGLWithSceneBasicsFromPlainViewSizing(bundle, sizing, onFrame) {
+    resizeGeometraThreeWebGLWithSceneBasicsViewFromPlainViewSizing(bundle, sizing);
+    return tickGeometraThreeWebGLWithSceneBasicsFrame(bundle, onFrame);
+}
+/**
+ * Same as {@link resizeTickGeometraThreeWebGLWithSceneBasicsFromPlainViewSizing} but takes a full
+ * {@link PlainGeometraThreeHostSnapshot} (viewport + scene plain fields) — for example from
+ * {@link toPlainGeometraThreeHostSnapshot}, {@link toPlainGeometraThreeHostSnapshotHeadless},
+ * {@link toPlainGeometraThreeHostSnapshotFromViewSizing}, or composite split/stacked snapshots that
+ * include those keys. Only the {@link PlainGeometraThreeViewSizingState} slice is read for resize;
+ * extra fields (scene/camera hex, hybrid layout) are ignored here but often live on the same object
+ * you already validated with {@link isPlainGeometraThreeHostSnapshot}.
+ *
+ * @returns Same boolean as {@link tickGeometraThreeWebGLWithSceneBasicsFrame}.
+ */
+export function resizeTickGeometraThreeWebGLWithSceneBasicsFromPlainHostSnapshot(bundle, snapshot, onFrame) {
+    return resizeTickGeometraThreeWebGLWithSceneBasicsFromPlainViewSizing(bundle, snapshot, onFrame);
+}
+//# 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":"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"}

package/dist/utils.d.ts

@@ -1,7 +1,171 @@
-import type { WebGLRenderer } from 'three';
+import type { PerspectiveCamera, WebGLRenderer } from 'three';
+/**
+ * Same integer flooring and minimum size as {@link createThreeGeometraSplitHost} and
+ * {@link createThreeGeometraStackedHost} use for CSS layout sizes and drawing-buffer dimensions.
+ *
+ * Use in custom or headless `WebGLRenderer` setups so width/height math stays aligned with those hosts.
+ *
+ * @returns A positive integer width or height in layout pixels (at least 1).
+ */
+export declare function normalizeGeometraLayoutPixels(n: number): number;
+/**
+ * Perspective `aspect` value for the same CSS layout → camera path as
+ * {@link resizeGeometraThreePerspectiveView} and the built-in split/stacked hosts
+ * (`setPixelRatio` + `setSize` with layout pixels, not raw drawing-buffer dimensions).
+ *
+ * Use in headless or custom renderers when you resize the drawing buffer yourself but want
+ * projection to stay aligned with {@link createThreeGeometraSplitHost} /
+ * {@link createThreeGeometraStackedHost}. For buffer-sized projection, use
+ * {@link syncGeometraThreePerspectiveFromBuffer} instead — flooring differs when width and height
+ * are scaled to physical pixels separately.
+ */
+export declare function geometraHostPerspectiveAspectFromCss(cssWidth: number, cssHeight: number): number;
+/**
+ * Device pixel ratio for split/stacked hosts and custom renderers: full raw ratio, optionally capped.
+ * Use with {@link resizeGeometraThreePerspectiveView} or {@link setWebGLDrawingBufferSize} so headless
+ * or offscreen setups match the same `maxDevicePixelRatio` behavior as {@link createThreeGeometraSplitHost}
+ * and {@link createThreeGeometraStackedHost}.
+ *
+ * @returns A finite positive ratio, capped when `maxDevicePixelRatio` is a finite positive number.
+ */
+export declare function resolveHostDevicePixelRatio(rawDevicePixelRatio: number, maxDevicePixelRatio?: number): number;
+/**
+ * Raw device pixel ratio used by headless / no-`window` helpers that mirror browser hosts where
+ * `win.devicePixelRatio || 1` would apply, but the baseline is fixed at **1** (see
+ * {@link resolveHeadlessHostDevicePixelRatio}, {@link toPlainGeometraThreeViewSizingStateHeadless},
+ * {@link createGeometraThreePerspectiveResizeHandlerHeadless}). Prefer this export over a bare `1`
+ * in agent payloads, tests, or custom hosts so the baseline stays grep-stable and documented.
+ */
+export declare const GEOMETRA_HEADLESS_RAW_DEVICE_PIXEL_RATIO: 1;
+/**
+ * Same optional {@link maxDevicePixelRatio} cap as {@link createThreeGeometraSplitHost} and
+ * {@link createThreeGeometraStackedHost}, but with raw ratio **1** for environments without a
+ * browser `window` (headless WebGL, Node, tests).
+ *
+ * Equivalent to
+ * `resolveHostDevicePixelRatio(GEOMETRA_HEADLESS_RAW_DEVICE_PIXEL_RATIO, maxDevicePixelRatio)`.
+ */
+export declare function resolveHeadlessHostDevicePixelRatio(maxDevicePixelRatio?: number): number;
+/**
+ * JSON-friendly viewport sizing aligned with {@link resizeGeometraThreePerspectiveView} and the
+ * split/stacked hosts (floored CSS layout pixels, then × effective DPR for buffer dimensions).
+ *
+ * Use beside {@link toPlainGeometraThreeSceneBasicsOptions} for logs, tests, or agent payloads that
+ * describe the same numbers the hosts use without constructing a renderer.
+ */
+export interface PlainGeometraThreeViewSizingState {
+    /** Floored CSS layout width (at least 1), same as {@link normalizeGeometraLayoutPixels}. */
+    layoutWidth: number;
+    /** Floored CSS layout height (at least 1). */
+    layoutHeight: number;
+    /** `layoutWidth / layoutHeight` — same as {@link geometraHostPerspectiveAspectFromCss} for these inputs. */
+    perspectiveAspect: number;
+    /**
+     * Finite positive device pixel ratio before optional cap (invalid raw values become `1`, matching
+     * `win.devicePixelRatio || 1` behavior in the hosts).
+     */
+    sanitizedRawDevicePixelRatio: number;
+    /** Same as {@link resolveHostDevicePixelRatio}(raw, maxDevicePixelRatio). */
+    effectiveDevicePixelRatio: number;
+    /**
+     * Nominal drawing-buffer width: {@link normalizeGeometraLayoutPixels}(`layoutWidth` × `effectiveDevicePixelRatio`).
+     * Aligns with the buffer scale after {@link resizeGeometraThreePerspectiveView}, not the
+     * {@link setWebGLDrawingBufferSize} path (which floors CSS×DPR before separating axes).
+     */
+    drawingBufferWidth: number;
+    /** Nominal drawing-buffer height (same rules as {@link PlainGeometraThreeViewSizingState.drawingBufferWidth}). */
+    drawingBufferHeight: number;
+}
+/**
+ * Coerce CSS layout size and DPR into the same integers the built-in hosts use for perspective resize
+ * and nominal buffer dimensions (floored layout × effective DPR per axis).
+ */
+export declare function toPlainGeometraThreeViewSizingState(cssWidth: number, cssHeight: number, rawDevicePixelRatio: number, maxDevicePixelRatio?: number): PlainGeometraThreeViewSizingState;
+/**
+ * Same plain viewport sizing as {@link toPlainGeometraThreeViewSizingState} with raw device pixel ratio
+ * fixed at **1** — parity with {@link resolveHeadlessHostDevicePixelRatio},
+ * {@link toPlainGeometraThreeHostSnapshotHeadless}, and {@link resizeGeometraThreeWebGLWithSceneBasicsViewHeadless}
+ * for headless GL, Node, tests, or agent payloads without a browser `window`.
+ *
+ * Equivalent to
+ * `toPlainGeometraThreeViewSizingState(cssWidth, cssHeight, GEOMETRA_HEADLESS_RAW_DEVICE_PIXEL_RATIO, maxDevicePixelRatio)`.
+ */
+export declare function toPlainGeometraThreeViewSizingStateHeadless(cssWidth: number, cssHeight: number, maxDevicePixelRatio?: number): PlainGeometraThreeViewSizingState;
+/**
+ * Narrow `unknown` (e.g. `JSON.parse`) to {@link PlainGeometraThreeViewSizingState} when the object has the
+ * viewport fields produced by {@link toPlainGeometraThreeViewSizingState} and
+ * {@link toPlainGeometraThreeViewSizingStateHeadless}. Extra keys are allowed. Objects that also include scene
+ * fields may satisfy this guard; for the full viewport + scene shape use `isPlainGeometraThreeHostSnapshot`
+ * from this package’s entry (re-exported next to the host snapshot helpers).
+ */
+export declare function isPlainGeometraThreeViewSizingState(value: unknown): value is PlainGeometraThreeViewSizingState;
 /**
  * Resize drawing buffer to match CSS pixel size × device pixel ratio.
  * Use when you manage your own canvas layout (no `renderer.setSize`).
+ * Non-finite CSS sizes or products fall back to 1; non-finite or non-positive `pixelRatio` becomes 1.
  */
 export declare function setWebGLDrawingBufferSize(renderer: WebGLRenderer, cssWidth: number, cssHeight: number, pixelRatio?: number): void;
+/**
+ * Size the WebGL drawing buffer from CSS layout × pixel ratio and update the perspective camera aspect
+ * to match, in one step.
+ *
+ * Use this on the **drawing-buffer** path (with {@link setWebGLDrawingBufferSize}) instead of
+ * {@link resizeGeometraThreePerspectiveView} when you do not use `setPixelRatio` + `setSize` on the
+ * renderer — for example headless GL, offscreen canvas, or custom buffer management. Equivalent to calling
+ * {@link setWebGLDrawingBufferSize} then {@link syncGeometraThreePerspectiveFromBuffer} with the
+ * resulting buffer dimensions (read from {@link WebGLRenderer.domElement} after resize).
+ */
+export declare function resizeGeometraThreeDrawingBufferView(renderer: WebGLRenderer, camera: PerspectiveCamera, cssWidth: number, cssHeight: number, pixelRatio?: number): void;
+/**
+ * Same as {@link resizeGeometraThreeDrawingBufferView} with pixel ratio from
+ * {@link resolveHeadlessHostDevicePixelRatio} — raw ratio **1** and the same optional
+ * `maxDevicePixelRatio` cap as split/stacked hosts.
+ *
+ * Parity with {@link resizeGeometraThreeWebGLWithSceneBasicsViewHeadless} for the
+ * {@link setWebGLDrawingBufferSize} / drawing-buffer path (headless GL, offscreen canvas, Node tests).
+ *
+ * Equivalent to calling {@link resizeGeometraThreeDrawingBufferView} with
+ * `resolveHeadlessHostDevicePixelRatio(maxDevicePixelRatio)` as the pixel ratio argument.
+ */
+export declare function resizeGeometraThreeDrawingBufferViewHeadless(renderer: WebGLRenderer, camera: PerspectiveCamera, cssWidth: number, cssHeight: number, maxDevicePixelRatio?: 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.
+ * Non-finite or non-positive CSS sizes (including negative values) normalize to at least 1 layout
+ * pixel each, matching {@link normalizeGeometraLayoutPixels}; non-finite or non-positive `pixelRatio`
+ * becomes 1.
+ */
+export declare function resizeGeometraThreePerspectiveView(renderer: WebGLRenderer, camera: PerspectiveCamera, cssWidth: number, cssHeight: number, pixelRatio: number): void;
+/**
+ * Build a resize callback that applies the same CSS layout → DPR → `setPixelRatio` / `setSize` path as
+ * {@link createThreeGeometraSplitHost} and {@link createThreeGeometraStackedHost}.
+ *
+ * Use in headless GL, offscreen canvas, tests, or custom hosts where you resize on a timer or explicit
+ * layout pass instead of the built-in `ResizeObserver`, but want {@link resolveHostDevicePixelRatio}
+ * capping and layout-pixel normalization without duplicating that wiring at every call site.
+ *
+ * @param getRawDevicePixelRatio - e.g. `() => win.devicePixelRatio || 1` or `() => 1` when no `window`.
+ */
+export declare function createGeometraThreePerspectiveResizeHandler(renderer: WebGLRenderer, camera: PerspectiveCamera, getRawDevicePixelRatio: () => number, maxDevicePixelRatio?: number): (cssWidth: number, cssHeight: number) => void;
+/**
+ * Same as {@link createGeometraThreePerspectiveResizeHandler} with raw device pixel ratio fixed at **1** —
+ * parity with {@link resolveHeadlessHostDevicePixelRatio}, {@link resizeGeometraThreeWebGLWithSceneBasicsViewHeadless},
+ * {@link toPlainGeometraThreeViewSizingStateHeadless}, and {@link toPlainGeometraThreeHostSnapshotHeadless} for headless GL, Node, tests, or agent loops without a browser
+ * `window`.
+ *
+ * Equivalent to `createGeometraThreePerspectiveResizeHandler(renderer, camera, () => 1, maxDevicePixelRatio)`.
+ */
+export declare function createGeometraThreePerspectiveResizeHandlerHeadless(renderer: WebGLRenderer, camera: PerspectiveCamera, maxDevicePixelRatio?: number): (cssWidth: number, cssHeight: number) => void;
+/**
+ * Update perspective projection from **drawing-buffer** pixel dimensions (physical pixels), not CSS size.
+ *
+ * Use when you size WebGL with {@link setWebGLDrawingBufferSize} or `renderer.setDrawingBufferSize` directly
+ * (headless GL, offscreen canvas, tests) and still want the same aspect handling as
+ * {@link resizeGeometraThreePerspectiveView}. Does not touch the renderer — only the camera.
+ * Non-finite buffer dimensions fall back to 1.
+ */
+export declare function syncGeometraThreePerspectiveFromBuffer(camera: PerspectiveCamera, drawingBufferWidth: number, drawingBufferHeight: 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":"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"}