tosijs-3d 0.7.0 → 0.7.2

package/dist/b3d-turret.js

@@ -25,7 +25,7 @@ keep up even when smart.
 
 ```js
 import { b3d, b3dTurret, b3dDestroyable, b3dLight, b3dSkybox, b3dGround, label3d, slider3d, sceneDelta } from 'tosijs-3d'
-import { orbitCam } from 'demo-utils'
+import { orbitCam } from 'tosijs-3d/demo-utils'
 import { tosi } from 'tosijs'
 
 const { s } = tosi({ s: { traverseRate: 2.5, range: 30, fireRate: 2, muzzleSpeed: 24, smart: 0 } })

package/dist/b3d-warhead.js

@@ -26,7 +26,7 @@ sight** off in the ⚙ panel and the wall stops mattering.
 
 ```js
 import { b3d, b3dController, b3dWarhead, b3dDestroyable, b3dLight, b3dSkybox, b3dGround, label3d, slider3d, toggle3d } from 'tosijs-3d'
-import { orbitCam } from 'demo-utils'
+import { orbitCam } from 'tosijs-3d/demo-utils'
 import { tosi } from 'tosijs'
 
 const { s } = tosi({ s: { damage: 20, fullRadius: 1.5, blastRadius: 5, los: true } })

package/dist/b3d-water.js

@@ -10,7 +10,7 @@ sky and the crates. Drag to orbit — dip the camera below the surface and the w
 
 ```js
 import { b3d, b3dSkybox, b3dWater, b3dReflections, b3dGround, sceneDelta } from 'tosijs-3d'
-import { demoSun, orbitCam, spinner } from 'demo-utils'
+import { demoSun, orbitCam, spinner } from 'tosijs-3d/demo-utils'
 
 const scene = b3d(
   {

package/dist/biome-chart.js

@@ -51,7 +51,7 @@ import {
   toggle3d, mesaProfile, beachProfile, cliffProfile, blendProfiles,
   profileField, LAVA_PALETTE, CRYOVOLCANIC_PALETTE, volcano,
 } from 'tosijs-3d'
-import { orbitCam } from 'demo-utils'
+import { orbitCam } from 'tosijs-3d/demo-utils'
 
 // PINNED showcase vista — seed + scales chosen so this exact terrain shows
 // every spec transition at once. Change DELIBERATELY, with the page open: the

package/dist/cloud-shadows.js

@@ -19,7 +19,7 @@ drift across the ground and the crates below. Drag to orbit; watch the dark patc
 
 ```js
 import { b3d, b3dClouds, b3dBox } from 'tosijs-3d'
-import { demoStage, orbitCam } from 'demo-utils'
+import { demoStage, orbitCam } from 'tosijs-3d/demo-utils'
 
 const scene = b3d(
   {
@@ -36,7 +36,7 @@ const scene = b3d(
   // On the stage — cloud shadows are DARKENING, so the scene needs a fill light
   // to darken FROM. Sun alone put every unlit face at zero and the demo read as
   // black boxes on a black floor.
-  ...demoStage({ size: 160, tiles: 26, pattern: true, timeOfDay: 11, sun: { x: -0.5, y: -1, z: -0.35 } }),
+  ...demoStage({ size: 160, tiles: 26, texture: '/tosi-warhol-testgrid.svg', timeOfDay: 11, sun: { x: -0.5, y: -1, z: -0.35 } }),
   b3dClouds({ model: '/cloud.glb', altitude: 115, thickness: 18, spread: 200, size: 38, coverage: 0.5, castShadows: true, shadowStrength: 0.7, seed: 3 }),
   ...Array.from({ length: 9 }, (_, i) =>
     b3dBox({ meshName: `crate-${i}`, size: 3, x: (i % 3) * 10 - 10, y: 1.5, z: Math.floor(i / 3) * 10 - 10, color: '#7a9b6e' })

package/dist/demo-utils.d.ts

@@ -0,0 +1,166 @@
+import * as BABYLON from '@babylonjs/core';
+/** The `<tosi-b3d>` element an example receives as `el` — just the parts these touch. */
+export type DemoHost = {
+    scene: BABYLON.Scene;
+    setActiveCamera(camera: BABYLON.Camera): void;
+    querySelector(selector: string): Element | null;
+    register?(additions: {
+        meshes?: BABYLON.AbstractMesh[];
+    }): void;
+};
+export interface DemoSunOptions {
+    intensity?: number;
+    /** `0` (default) = the device-tier budget. Set a size only to override it. */
+    shadowTextureSize?: number;
+    shadowCascading?: boolean;
+    shadowMaxZ?: number;
+    y?: number;
+}
+/**
+ * A sun that CASTS shadows — the "when in doubt, add a shadow light" default.
+ *
+ * `shadowTextureSize` defaults to the **auto sentinel `0`**, not a hard-wired
+ * 2048. A fixed size overrode the device-tier budget for every demo including
+ * on a headset, which is 4× the shadow VRAM on the tier least able to pay it.
+ * Acne is handled by `shadowNormalBias` instead, which costs nothing.
+ */
+export declare function demoSun(opts?: DemoSunOptions): import("./b3d-shadows").B3dSun;
+export interface PatternGroundOptions {
+    size?: number;
+    tiles?: number;
+    color?: string;
+    /**
+     * Texture URL. Omitted = a generated checker, which needs no asset and so
+     * works in any project. (This replaces the old `pattern: boolean`, which
+     * pointed at a file that exists only on the doc site.)
+     */
+    texture?: string;
+}
+/**
+ * A ground that RECEIVES shadows. A test pattern reads the light far better
+ * than a flat colour — a flat ground hides the lighting, the shadows and the UV
+ * mapping at once, which is how a scene ends up looking broken when it is
+ * merely bland.
+ */
+export declare function patternGround(opts?: PatternGroundOptions): import("./b3d-primitives").B3dGround;
+export interface DemoStageOptions extends PatternGroundOptions {
+    timeOfDay?: number;
+    sun?: DemoSunOptions;
+    /** Hemispheric fill. `0` turns it off for a hard, airless look. */
+    fill?: number;
+}
+/**
+ * The whole "make it not look like a test harness" setup in one spread: a sun
+ * that casts, a sky to light and reflect, and a ground that shows both.
+ *
+ * ```js
+ * b3d({ ... }, ...demoStage({ texture: '/my-grid.png' }), myThing)
+ * ```
+ *
+ * The fill light is not optional-by-taste: a directional sun alone leaves every
+ * unlit face at ZERO, so objects read as black silhouettes rather than objects.
+ * Real outdoor light has sky bounce; a hemispheric light is the cheap stand-in.
+ */
+export declare function demoStage(opts?: DemoStageOptions): (import("./b3d-primitives").B3dGround | import("./b3d-shadows").B3dSun | import("./b3d-skybox").B3dSkybox | import("./b3d-light").B3dLight)[];
+export interface OrbitCamOptions {
+    /** Orbit angle around Y, in DEGREES. Default −90 (facing −Z). */
+    alphaDeg?: number;
+    /** Tilt from vertical, in DEGREES. Default 60. */
+    betaDeg?: number;
+    radius?: number;
+    target?: [number, number, number];
+    /** Keep the camera at least this far above horizontal. `null` opts out. */
+    minElevationDeg?: number | null;
+    /** Stop it going exactly top-down. `null` opts out. */
+    maxElevationDeg?: number | null;
+    /** @deprecated pre-0.7.1 radians — use `alphaDeg`. Converted if given. */
+    alpha?: number;
+    /** @deprecated pre-0.7.1 radians — use `betaDeg`. Converted if given. */
+    beta?: number;
+}
+/**
+ * The standard `ArcRotateCamera` every demo sets up — one call instead of six
+ * lines. Call it in `sceneCreated`.
+ *
+ * Clamps the tilt by DEFAULT so you cannot drag the view below the horizon and
+ * see the world from underneath (an `ArcRotateCamera` happily orbits under the
+ * floor otherwise — a long-standing demo papercut).
+ *
+ * **Degrees**, per the framework rule that a bare angle name is already
+ * degrees. The old radian `alpha`/`beta` are still accepted and converted, so
+ * existing snippets keep working; they are the one place in this module where
+ * radians appear at all.
+ */
+export declare function orbitCam(el: DemoHost, opts?: OrbitCamOptions): BABYLON.ArcRotateCamera;
+export interface SpinnerOptions {
+    size?: number;
+    x?: number;
+    y?: number;
+    z?: number;
+    /** Revolutions per second. */
+    spin?: number;
+    /** Texture URL. Omitted = an untextured box. */
+    texture?: string;
+}
+/**
+ * A slowly-rotating box — the "non-static object so you can see the shadow
+ * move" prop. Registers itself as a shadow caster so `demoSun`/`b3dSun` picks
+ * it up. Call in `sceneCreated`.
+ */
+export declare function spinner(el: DemoHost, opts?: SpinnerOptions): BABYLON.Mesh;
+export interface FlightStageOptions {
+    /**
+     * Builds a FRESH aircraft. A factory, not an instance — respawn has to
+     * construct a new one, and a demo that passed an instance was unrecoverable
+     * after the first crash.
+     */
+    plane: () => any;
+    /** Ground extent. Default 4000 — an aircraft needs somewhere to go. */
+    size?: number;
+    timeOfDay?: number;
+    /** GLB holding the vehicle library, if the plane uses `library:`. */
+    library?: string;
+    libraryType?: string;
+    /** Distance fog. `false` for a hard, airless look. */
+    fog?: boolean;
+    groundColor?: string;
+    /** Heading on the death panel. */
+    title?: string;
+}
+/**
+ * A setting an aircraft can actually operate in — the flight equivalent of
+ * {@link demoStage}, and the fix for three demos that each forgot a different
+ * piece of it.
+ *
+ * What it includes, and why each is here rather than left to the caller:
+ *
+ * - **A `b3dDeath` with a working respawn.** Without one, `crash()` releases
+ *   input focus and leaves you holding nothing — no wreck to fly, no panel, no
+ *   way back. That reads as the demo seizing up rather than as dying, and it is
+ *   why `plane` is a factory.
+ * - **A sun configured for the ground it lights.** A 4000-unit ground with the
+ *   default single shadow map puts the aircraft's shadow in a coarse far
+ *   cascade where it is invisible, and `shadowMaxZ` at its default of 100 drops
+ *   shadows entirely once you climb.
+ * - **Ground, sky and fog at flight scale**, which every flight demo otherwise
+ *   retypes slightly differently.
+ *
+ * Returns an object rather than an array (unlike `demoStage`) because the stage
+ * owns an IDENTITY: the current aircraft changes on respawn, so a readout that
+ * captured the first one would go stale.
+ *
+ * ```js
+ * const stage = flightStage({
+ *   plane: () => b3dAircraft({ library: 'vehicles', meshName: 'scout', player: true, y: 40 }),
+ *   library: '/test-3.glb',
+ * })
+ * const scene = b3d({ gamepad: true }, ...stage.elements)
+ * // stage.aircraft is always the one you are flying NOW
+ * ```
+ */
+export declare function flightStage(opts: FlightStageOptions): {
+    elements: (import("./b3d-primitives").B3dGround | import("./b3d-input-focus").B3dInputFocus | import("./b3d-death").B3dDeath | import("./b3d-shadows").B3dSun | import("./b3d-skybox").B3dSkybox | import("./b3d-fog").B3dFog | import("./b3d-library").B3dLibrary | import("./b3d-light").B3dLight)[];
+    /** The aircraft you are flying NOW — changes on respawn. */
+    readonly aircraft: any;
+};
+//# sourceMappingURL=demo-utils.d.ts.map

package/dist/demo-utils.d.ts.map

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

package/dist/demo-utils.js

@@ -0,0 +1,232 @@
+/*#
+# demo-utils
+
+**Scene-setup helpers for examples and prototypes** — the "when in doubt" defaults
+that make a scene look like a scene instead of a test harness. Every live example
+on this site uses them, which is why they are published: the code you copy off a
+doc page should run in your project unchanged.
+
+> ## ⚠️ These are DEV HELPERS. Do not build on them.
+>
+> They exist so examples run, and they are **not** covered by the care the main
+> API gets:
+>
+> - **They can change or disappear in a patch release.** No deprecation period,
+>   no migration note.
+> - **They are tuned for looking good in a doc page**, not for your game — the
+>   numbers are chosen to flatter a cube on a grey ground.
+> - **They are not a design system.** `demoStage` is three components in a
+>   trench coat; when you outgrow it, inline what it does and delete the import.
+>
+> Production code should compose `b3dSun`/`b3dSkybox`/`b3dGround` directly. If
+> you find yourself wanting a helper to be *stable*, that is the signal it
+> belongs in the main API — open an issue rather than pinning a version.
+
+```js
+import { b3d, b3dBox } from 'tosijs-3d'
+import { demoStage, orbitCam } from 'tosijs-3d/demo-utils'
+
+const scene = b3d(
+  { sceneCreated: (el) => orbitCam(el, { radius: 8 }) },
+  ...demoStage({ texture: '/tosi-warhol-testgrid.svg' }),
+  b3dBox({ y: 1 }),
+)
+preview.append(scene)
+```
+
+## What's here
+
+| Helper | What it does |
+| --- | --- |
+| `demoStage(opts)` | Sun + fill + sky + ground, spread into a `b3d(...)` |
+| `demoSun(opts)` | A sun that casts shadows, at the device's shadow budget |
+| `patternGround(opts)` | A ground that RECEIVES shadows and shows the light |
+| `orbitCam(el, opts)` | The standard orbit camera, tilt-clamped, in `sceneCreated` |
+| `spinner(el, opts)` | A slowly-rotating textured box, so you can see shadows move |
+| `flightStage(opts)` | A setting an **aircraft** can operate in — stage, library, and a death panel that respawns you |
+
+## Angles are DEGREES
+
+`orbitCam` takes `alphaDeg`/`betaDeg`, per the framework rule: a bare angle name
+is already degrees, and radians appear only where the maths needs them (see
+CLAUDE.md → Angles). The pre-0.7.1 `alpha`/`beta` radian pair is still accepted
+and converted, so old snippets keep working.
+
+## Textures
+
+Helpers take a `texture` URL rather than exporting asset paths. The paths that
+used to be exported (`/tosi-test-pattern.svg`) resolve only on **this** site, so
+publishing them would have been a broken promise in your project. Pass your own,
+or omit it for a generated checker that needs no asset at all.
+*/
+/*{ "parent": "Utilities" }*/
+import * as BABYLON from '@babylonjs/core';
+import { b3dSun, b3dSkybox, b3dLight, b3dGround, b3dFog, b3dLibrary, b3dDeath, inputFocus, gameController, } from './index';
+const DEG = Math.PI / 180;
+/**
+ * A sun that CASTS shadows — the "when in doubt, add a shadow light" default.
+ *
+ * `shadowTextureSize` defaults to the **auto sentinel `0`**, not a hard-wired
+ * 2048. A fixed size overrode the device-tier budget for every demo including
+ * on a headset, which is 4× the shadow VRAM on the tier least able to pay it.
+ * Acne is handled by `shadowNormalBias` instead, which costs nothing.
+ */
+export function demoSun(opts = {}) {
+    return b3dSun({ intensity: 0.9, shadowTextureSize: 0, ...opts });
+}
+/**
+ * A ground that RECEIVES shadows. A test pattern reads the light far better
+ * than a flat colour — a flat ground hides the lighting, the shadows and the UV
+ * mapping at once, which is how a scene ends up looking broken when it is
+ * merely bland.
+ */
+export function patternGround(opts = {}) {
+    const { size = 40, tiles = 16, color = '#8a9b7e', texture } = opts;
+    return b3dGround({
+        width: size,
+        height: size,
+        texture: texture ?? 'checker',
+        textureTiles: texture ? Math.max(1, Math.round(tiles / 4)) : tiles,
+        color,
+    });
+}
+/**
+ * The whole "make it not look like a test harness" setup in one spread: a sun
+ * that casts, a sky to light and reflect, and a ground that shows both.
+ *
+ * ```js
+ * b3d({ ... }, ...demoStage({ texture: '/my-grid.png' }), myThing)
+ * ```
+ *
+ * The fill light is not optional-by-taste: a directional sun alone leaves every
+ * unlit face at ZERO, so objects read as black silhouettes rather than objects.
+ * Real outdoor light has sky bounce; a hemispheric light is the cheap stand-in.
+ */
+export function demoStage(opts = {}) {
+    const { timeOfDay = 11, sun = {}, fill = 0.35, ...ground } = opts;
+    return [
+        demoSun(sun),
+        ...(fill > 0 ? [b3dLight({ y: 1, intensity: fill })] : []),
+        b3dSkybox({ timeOfDay }),
+        patternGround(ground),
+    ];
+}
+/**
+ * The standard `ArcRotateCamera` every demo sets up — one call instead of six
+ * lines. Call it in `sceneCreated`.
+ *
+ * Clamps the tilt by DEFAULT so you cannot drag the view below the horizon and
+ * see the world from underneath (an `ArcRotateCamera` happily orbits under the
+ * floor otherwise — a long-standing demo papercut).
+ *
+ * **Degrees**, per the framework rule that a bare angle name is already
+ * degrees. The old radian `alpha`/`beta` are still accepted and converted, so
+ * existing snippets keep working; they are the one place in this module where
+ * radians appear at all.
+ */
+export function orbitCam(el, opts = {}) {
+    const { radius = 14, target = [0, 0.8, 0], minElevationDeg = 5, maxElevationDeg = 89, } = opts;
+    const alpha = opts.alpha ?? (opts.alphaDeg ?? -90) * DEG;
+    const beta = opts.beta ?? (opts.betaDeg ?? 60) * DEG;
+    const cam = new BABYLON.ArcRotateCamera('demo-cam', alpha, beta, radius, new BABYLON.Vector3(target[0], target[1], target[2]), el.scene);
+    cam.attachControl(el.querySelector('canvas'), true);
+    // beta is measured from straight-up (0) to straight-down (π); π/2 is level.
+    // Elevation ABOVE horizontal = π/2 − beta, so a MIN elevation is an UPPER
+    // beta limit.
+    if (minElevationDeg != null)
+        cam.upperBetaLimit = Math.PI / 2 - minElevationDeg * DEG;
+    if (maxElevationDeg != null)
+        cam.lowerBetaLimit = Math.PI / 2 - maxElevationDeg * DEG;
+    el.setActiveCamera(cam);
+    return cam;
+}
+/**
+ * A slowly-rotating box — the "non-static object so you can see the shadow
+ * move" prop. Registers itself as a shadow caster so `demoSun`/`b3dSun` picks
+ * it up. Call in `sceneCreated`.
+ */
+export function spinner(el, opts = {}) {
+    const { size = 2, x = 0, y = 1.2, z = 0, spin = 0.12, texture } = opts;
+    const box = BABYLON.MeshBuilder.CreateBox('spinner', { size }, el.scene);
+    box.position.set(x, y, z);
+    const mat = new BABYLON.StandardMaterial('spinner-mat', el.scene);
+    if (texture)
+        mat.diffuseTexture = new BABYLON.Texture(texture, el.scene);
+    box.material = mat;
+    el.register?.({ meshes: [box] });
+    el.scene.onBeforeRenderObservable.add(() => {
+        box.rotation.y += spin * 0.016 * Math.PI * 2;
+    });
+    return box;
+}
+/**
+ * A setting an aircraft can actually operate in — the flight equivalent of
+ * {@link demoStage}, and the fix for three demos that each forgot a different
+ * piece of it.
+ *
+ * What it includes, and why each is here rather than left to the caller:
+ *
+ * - **A `b3dDeath` with a working respawn.** Without one, `crash()` releases
+ *   input focus and leaves you holding nothing — no wreck to fly, no panel, no
+ *   way back. That reads as the demo seizing up rather than as dying, and it is
+ *   why `plane` is a factory.
+ * - **A sun configured for the ground it lights.** A 4000-unit ground with the
+ *   default single shadow map puts the aircraft's shadow in a coarse far
+ *   cascade where it is invisible, and `shadowMaxZ` at its default of 100 drops
+ *   shadows entirely once you climb.
+ * - **Ground, sky and fog at flight scale**, which every flight demo otherwise
+ *   retypes slightly differently.
+ *
+ * Returns an object rather than an array (unlike `demoStage`) because the stage
+ * owns an IDENTITY: the current aircraft changes on respawn, so a readout that
+ * captured the first one would go stale.
+ *
+ * ```js
+ * const stage = flightStage({
+ *   plane: () => b3dAircraft({ library: 'vehicles', meshName: 'scout', player: true, y: 40 }),
+ *   library: '/test-3.glb',
+ * })
+ * const scene = b3d({ gamepad: true }, ...stage.elements)
+ * // stage.aircraft is always the one you are flying NOW
+ * ```
+ */
+export function flightStage(opts) {
+    const { plane, size = 4000, timeOfDay = 10, library, libraryType = 'vehicles', fog = true, groundColor = '#6b7f5e', title = 'DOWN', } = opts;
+    let current = plane();
+    const focus = inputFocus(gameController(), current);
+    const elements = [
+        b3dLight({ y: 1, intensity: 0.6 }),
+        // Cascaded, with a shadowMaxZ that still reaches the ground from cruising
+        // altitude. `shadowTextureSize` stays on the auto sentinel so the device
+        // tier decides — a hard-wired size is 4x the VRAM on the tier least able to
+        // pay for it.
+        b3dSun({ intensity: 0.9, shadowCascading: true, shadowMaxZ: 600 }),
+        b3dSkybox({ timeOfDay }),
+        ...(fog
+            ? [b3dFog({ start: size / 10, end: size * 0.75, color: '#bfd9f2' })]
+            : []),
+        b3dGround({
+            meshName: 'ground_nocast',
+            width: size,
+            height: size,
+            color: groundColor,
+        }),
+        ...(library ? [b3dLibrary({ url: library, type: libraryType })] : []),
+        b3dDeath({
+            title,
+            respawn() {
+                current = plane();
+                focus.appendChild(current);
+            },
+        }),
+        focus,
+    ];
+    return {
+        elements,
+        /** The aircraft you are flying NOW — changes on respawn. */
+        get aircraft() {
+            return current;
+        },
+    };
+}
+//# sourceMappingURL=demo-utils.js.map

package/dist/demo-utils.js.map

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

package/dist/dialog-placement.d.ts

@@ -0,0 +1,68 @@
+/** Minimal vector — deliberately not Babylon's, so this module stays pure. */
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Unit vector, or `null` for a zero-length input (which has no direction). */
+export declare function normalize(v: Vec3): Vec3 | null;
+/**
+ * Angle in DEGREES between where the viewer looks and where the dialog is.
+ *
+ * Returns `0` when the dialog is exactly on the view axis and `180` when it is
+ * directly behind. A dialog at the viewer's own position has no direction, and
+ * is reported as `0` — on-axis — because "you are inside it" is not a reason to
+ * go and fetch it.
+ */
+export declare function gazeOffAxisDeg(eye: Vec3, forward: Vec3, dialog: Vec3): number;
+/** How long the dialog has been out of view, in seconds. */
+export interface GazeState {
+    offAxisSec: number;
+}
+export declare const newGazeState: () => GazeState;
+export interface GazeOptions {
+    /** Half-angle you may look away by before the clock starts. Default 55°. */
+    coneDeg?: number;
+    /** Seconds outside the cone before the dialog comes to you. Default 2. */
+    holdSec?: number;
+}
+/**
+ * Advance the look-away clock and say whether the dialog should re-place.
+ *
+ * The clock **resets** the moment the dialog is back inside the cone, so a
+ * glance away costs nothing — only sustained inattention moves it. Returns the
+ * next state alongside the decision rather than mutating, so the rule is
+ * testable and the caller owns the state.
+ */
+export declare function gazeStep(state: GazeState, offAxisDeg: number, dt: number, opts?: GazeOptions): {
+    state: GazeState;
+    recover: boolean;
+};
+/**
+ * Pick the best of several candidate distances — the results of casting a ray
+ * along each candidate direction.
+ *
+ * `Infinity` means nothing was hit, i.e. fully clear. The winner is the
+ * candidate with the most room, preferring EARLIER candidates on a tie so a
+ * caller can order them by desirability (straight ahead first). Returns `-1`
+ * when every candidate is too cramped to use.
+ */
+export declare function bestCandidate(clearances: number[], minClearance: number): number;
+/**
+ * How far along a candidate direction to actually sit.
+ *
+ * Short of the obstruction by `margin` so the panel is not coplanar with a wall,
+ * never past the distance you asked for, and never closer than `minZ` — a panel
+ * at arm's length is uncomfortable in a headset, which is why "just use the near
+ * clip plane" is the wrong version of this idea.
+ */
+export declare function placementDistance(clearance: number, desired: number, minZ?: number, margin?: number): number;
+/**
+ * Ease a position toward a target — frame-rate independent.
+ *
+ * `smoothing` is the fraction of the remaining distance left after one second,
+ * so the result does not change when the frame rate does (the naive
+ * `lerp(a, b, 0.1)` per frame moves twice as fast at 120fps as at 60).
+ */
+export declare function easeTo(current: Vec3, target: Vec3, dt: number, smoothing?: number): Vec3;
+//# sourceMappingURL=dialog-placement.d.ts.map

package/dist/dialog-placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog-placement.d.ts","sourceRoot":"","sources":["../src/dialog-placement.ts"],"names":[],"mappings":"AAiCA,8EAA8E;AAC9E,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AASD,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAI9C;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,MAAM,CAM7E;AAED,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,YAAY,QAAO,SAAgC,CAAA;AAEhE,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,WAAgB,GACrB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAMxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAAE,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CAYR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,SAAM,EACV,MAAM,SAAO,GACZ,MAAM,CAGR;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,IAAI,EACb,MAAM,EAAE,IAAI,EACZ,EAAE,EAAE,MAAM,EACV,SAAS,SAAQ,GAChB,IAAI,CAON"}