@allyhub/sdk 0.1.0-alpha.8 → 0.2.0-next.0

package/node_modules/@allyhub-next/runtimes/schemas/runtimes.schema.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "type": "number",
+      "const": 1
+    },
+    "runtimes": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "about": {
+            "type": "string",
+            "minLength": 1
+          },
+          "version": {
+            "type": "string",
+            "minLength": 1
+          },
+          "license": {
+            "type": "string",
+            "minLength": 1
+          },
+          "homepage": {
+            "type": "string",
+            "format": "uri"
+          },
+          "platforms": {
+            "type": "object",
+            "propertyNames": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "enum": [
+                    "darwin-arm64",
+                    "darwin-x64",
+                    "linux-x64",
+                    "linux-arm64",
+                    "win32-x64"
+                  ]
+                },
+                {
+                  "type": "string",
+                  "const": "any"
+                }
+              ]
+            },
+            "additionalProperties": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "url": {
+                    "type": "string",
+                    "format": "uri"
+                  },
+                  "sha256": {
+                    "type": "string",
+                    "pattern": "^[0-9a-f]{64}$"
+                  },
+                  "size": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "unpack": {
+                    "default": "none",
+                    "type": "string",
+                    "enum": [
+                      "none",
+                      "zip",
+                      "tgz"
+                    ]
+                  },
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "check": {
+                    "default": [],
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "path": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "sha256": {
+                          "type": "string",
+                          "pattern": "^[0-9a-f]{64}$"
+                        }
+                      },
+                      "required": [
+                        "path",
+                        "sha256"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "executable": {
+                    "default": false,
+                    "type": "boolean"
+                  },
+                  "bins": {
+                    "default": {},
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string",
+                      "pattern": "^[a-z0-9][a-z0-9-]*$"
+                    },
+                    "additionalProperties": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                },
+                "required": [
+                  "url",
+                  "sha256",
+                  "size"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "required": [
+          "about",
+          "version",
+          "license",
+          "platforms"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "version",
+    "runtimes"
+  ],
+  "additionalProperties": false
+}

package/node_modules/@allyhub-next/scenery/NOTICE

@@ -0,0 +1,42 @@
+AllyHub
+Copyright (c) 2026 AllyHub, Inc. All rights reserved.
+
+This product is proprietary; see LICENSE.
+
+The centripetal Catmull-Rom tangents in src/curve.ts follow three.js's
+CatmullRomCurve3 (src/extras/curves/CatmullRomCurve3.js)
+(https://github.com/mrdoob/three.js),
+Copyright 2010-2026 three.js authors, under the MIT License:
+
+  Permission is hereby granted, free of charge, to any person obtaining a
+  copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to permit
+  persons to whom the Software is furnished to do so, subject to the
+  following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+  NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+  DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+  OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+  USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+The arc-length parametrisation (Gauss-Legendre quadrature per segment,
+inverted by Newton steps with a bisection fallback) and the timing of
+keyframes by a monotone cubic follow the approach of the splines library
+(https://github.com/AudioSceneDescriptionFormat/splines), Copyright (c)
+2018-2026 Matthias Geier, under the MIT License (the same terms as above).
+No code of it is copied.
+
+The moiré a sensor makes of a screen (src/moire.ts) follows
+the screen-capture simulation of UniDemoiré
+(https://github.com/4DVLab/UniDemoire, unidemoire/models/shooting), Copyright
+(c) 2024 4DVLab, under the MIT License: a screen's RGB subpixels, the
+projective transform, the sensor's Bayer filter. It is worked out in closed
+form per pixel; no code of it is copied.

package/node_modules/@allyhub-next/scenery/dist/aim.d.ts

@@ -0,0 +1,55 @@
+export interface AimOptions {
+    /**
+     * How far the primary movement goes past the target, as a share of the
+     * distance (negative: it falls short); the correction comes back.
+     */
+    overshoot?: number;
+    /** When the primary movement's speed peaks, as a share of its time: under a half is a quick start and a longer settle. */
+    peak?: number;
+    /** The share of the whole time the primary movement takes; the correction overlaps its end and takes the rest. */
+    primary?: number;
+    /**
+     * How much a seed changes each of these from move to move, as a share
+     * of its value (the overshoot's from none to twice it at 1, the peak's
+     * and the primary share's a tenth of that).
+     */
+    vary?: number;
+    /** Another seed or index is another move. */
+    seed?: number;
+    index?: number;
+}
+export declare const AIM_DEFAULTS: {
+    overshoot: number;
+    peak: number;
+    primary: number;
+    vary: number;
+    seed: number;
+    index: number;
+};
+/** Why aim options cannot be used, or undefined. */
+export declare function aimProblem(o: AimOptions, what?: string): string | undefined;
+/**
+ * The share of the way a movement has come, from 0 at its start to 1 at
+ * its end, over `s` from 0 to 1: a beta(3, b) distribution's cumulative,
+ * its speed peaking at `peak` (b = 2 / peak − 1), still at both ends.
+ */
+export declare function rise(s: number, peak: number): number;
+/** What a move is, drawn from its options: its overshoot, its primary movement's peak and share. */
+export interface AimShape {
+    overshoot: number;
+    peak: number;
+    primary: number;
+}
+/** A move's own shape: the options, each moved by its seed and index. */
+export declare function aimShape(opts?: AimOptions): AimShape;
+/**
+ * An aimed movement's progress over `x` from 0 to 1 (its share of the
+ * move's time): 0 at the start and 1 at the end, past 1 (or short of it)
+ * where the primary movement lands, still at both ends. Usable as an ease
+ * (blend's, keys'), and what handheld()'s reframes and the SDK's pointer
+ * moves are drawn with.
+ */
+export declare function aimed(opts?: AimOptions): (x: number) => number;
+/** aimed()'s progress for a shape already drawn. */
+export declare function aimAt(shape: AimShape, x: number): number;
+//# sourceMappingURL=aim.d.ts.map

package/node_modules/@allyhub-next/scenery/dist/aim.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{unit3 as u}from"./noise.js";export const AIM_DEFAULTS={overshoot:.08,peak:.38,primary:.72,vary:.5,seed:1,index:0};export function aimProblem(e,r="aim"){const t=(n,o,i,s)=>n!==void 0&&!(Number.isFinite(n)&&n>=i&&n<=s)?`${r}'s ${o} is from ${String(i)} to ${String(s)}, not ${String(n)}`:void 0;return t(e.overshoot,"overshoot",-.5,1)??t(e.peak,"peak",.15,.6)??t(e.primary,"primary",.3,1)??t(e.vary,"vary",0,1)??(e.seed!==void 0&&!Number.isInteger(e.seed)?`${r}'s seed is a whole number, not ${String(e.seed)}`:void 0)}export function rise(e,r){if(e<=0)return 0;if(e>=1)return 1;const t=2/r-1,n=1-e,o=n**t;return 1-t*(t+1)*(t+2)/2*(o/t-2*o*n/(t+1)+o*n*n/(t+2))}const a=(e,r,t)=>2*u(e,r,t)-1;export function aimShape(e={}){const r={...AIM_DEFAULTS,...e},t=r.vary;return{overshoot:r.overshoot*(1+2*t*a(r.seed,r.index,1)),peak:Math.min(.6,Math.max(.15,r.peak*(1+.2*t*a(r.seed,r.index,2)))),primary:Math.min(1,Math.max(.3,r.primary*(1+.2*t*a(r.seed,r.index,3))))}}export function aimed(e={}){const r=aimProblem(e);if(r)throw new Error(r);const t=aimShape(e);return n=>aimAt(t,n)}export function aimAt(e,r){if(r<=0)return 0;if(r>=1)return 1;const t=1+e.overshoot,n=e.primary;if(n>=1||Math.abs(e.overshoot)<1e-9)return rise(r,e.peak);const o=n*.8,i=t*rise(r/n,e.peak),s=(1-t)*rise((r-o)/(1-o),.45);return i+s}

package/node_modules/@allyhub-next/scenery/dist/bake.d.ts

@@ -0,0 +1,203 @@
+import type { Vec3 } from "./vec.js";
+/** What a bake can be told: every value has a default (BAKE_DEFAULTS). */
+export interface BakeOptions {
+    /**
+     * Texels per metre on a surface of weight 1 (default 40: a texel of
+     * 2.5 cm). The atlas's side follows from the surfaces' area.
+     */
+    density?: number;
+    /** The atlas's largest side, texels (default 2048): a denser bake is made coarser to fit. */
+    maxSize?: number;
+    /**
+     * The fewest texels a mesh gets (default 128): a mesh the density would
+     * give fewer (a key, a foot) gets more weight until it has about this many.
+     */
+    minTexels?: number;
+    /**
+     * The fewest texels a mesh's typical island gets (default 16): a mesh made
+     * of many small separate pieces (a keyboard's keys in one mesh) gets more
+     * weight until the island at the median of its area has about this many,
+     * so each piece takes its own light rather than a texel shared with its
+     * neighbours.
+     */
+    islandTexels?: number;
+    /**
+     * Use a mesh's own texture coordinates (uv) for its lightmap when they
+     * already lay it out without overlaps inside 0..1, as a model's baked
+     * textures need, instead of unwrapping it (default true: unwrapping a dense
+     * mesh takes minutes).
+     */
+    ownUv?: boolean;
+    /** Rays each texel gathers per round (default 16). */
+    samples?: number;
+    /** Light bounced from surface to surface, rounds after the direct light (default 4). */
+    bounces?: number;
+    /**
+     * An object's share of the atlas, by its name or an ancestor's: its
+     * texels per metre are multiplied by it (default 1). What the camera
+     * comes close to is worth more.
+     */
+    weight?: Readonly<Record<string, number>>;
+    /** Meshes, by their name or an ancestor's, left without a lightmap: they still cast shadows and bounce light, and stay lit by the scene's lights. */
+    skip?: readonly string[];
+    /** Meshes, by their name or an ancestor's, the bake does not see at all: no lightmap, no shadow, no bounce. */
+    ignore?: readonly string[];
+    /**
+     * Each round smoothed keeping edges: its radius in texels, and how much
+     * farther than their places in the atlas imply two texels may be, in
+     * metres beyond a texel's width, and still be averaged (defaults 3, 0.02).
+     */
+    denoise?: {
+        radius?: number;
+        distance?: number;
+    };
+    /** The most irradiance one sample may add, so a ray that grazes a light leaves no speck (default 40). */
+    clamp?: number;
+    /** Atlas texels a draw covers each way: smaller draws keep a GPU from timing out (default 256). */
+    tile?: number;
+    /**
+     * The moments, s of scenery time, the scenery is posed at to find what
+     * moves (default 0.5, 1, 2, 4, 8, 16, 32): a mesh that moves gets no
+     * lightmap and is left out of the bake's shadows, and a light that moves
+     * is not baked.
+     */
+    posedAt?: readonly number[];
+    /**
+     * A reflection probe: the baked scene seen all round from a point (some
+     * objects hidden, such as the one it sits in), made each time the bake
+     * is laid on and used as the scene's environment, so metal and glass
+     * reflect the lit room. Default none.
+     */
+    probe?: {
+        at: Vec3;
+        hide?: readonly string[];
+        size?: number;
+    };
+}
+/** A bake's settings with every default filled in. */
+export interface ResolvedBake {
+    density: number;
+    maxSize: number;
+    minTexels: number;
+    islandTexels: number;
+    ownUv: boolean;
+    samples: number;
+    bounces: number;
+    weight: Record<string, number>;
+    skip: string[];
+    ignore: string[];
+    denoise: {
+        radius: number;
+        distance: number;
+    };
+    clamp: number;
+    tile: number;
+    posedAt: number[];
+    probe: {
+        at: Vec3;
+        hide: string[];
+        size: number;
+    } | null;
+}
+export declare const BAKE_DEFAULTS: {
+    readonly density: 40;
+    readonly maxSize: 2048;
+    readonly minTexels: 128;
+    readonly islandTexels: 16;
+    readonly ownUv: true;
+    readonly samples: 16;
+    readonly bounces: 4;
+    readonly denoise: {
+        readonly radius: 3;
+        readonly distance: 0.02;
+    };
+    readonly clamp: 40;
+    readonly tile: 256;
+    readonly posedAt: readonly [0.5, 1, 2, 4, 8, 16, 32];
+    readonly probeSize: 256;
+};
+/** The smallest atlas side a bake makes, texels. */
+export declare const BAKE_MIN_SIZE = 64;
+/** What is wrong with a bake's settings, a line each. */
+export declare function bakeProblems(o: BakeOptions): string[];
+/** A bake's settings as the bake uses them: the defaults filled in, names sorted (so they digest the same). */
+export declare function resolveBake(o?: BakeOptions): ResolvedBake;
+/**
+ * The renderer a bake is made on and laid by, as a name for its file: a
+ * bake gathers the same texels each time on one renderer (its rays, their
+ * random numbers and the order they add up in are fixed), but another
+ * GPU's arithmetic (its sines, its rounding) sends the rays a little
+ * differently: most texels differ, by 0.3% at the median between a Mac's
+ * GPU and the CPU, one in a hundred by more than 10%, and the bounces
+ * carry it on. "cpu" for SwiftShader, which draws the same on every computer;
+ * else "gpu-" and a hash of the renderer WebGL names (the GPU and how
+ * Chrome drives it, such as "ANGLE Metal Renderer: Apple M2").
+ */
+export declare function bakeRenderer(gl: string): string;
+/** The renderer name of a bake made on the CPU (SwiftShader): laid by any renderer that has none of its own. */
+export declare const BAKE_CPU = "cpu";
+/** What `allyhub scenery bake` reports: the summary it prints is made from it, the whole of it is the report file. */
+export interface BakeReport {
+    /** The scene's digest: the bake is laid on a scene that digests the same. */
+    digest: string;
+    /** The renderer it was made on (bakeRenderer): a page lays the bake its own renderer made, else the CPU's. */
+    renderer: string;
+    /** The atlas's side, texels. */
+    size: number;
+    /** Texels per metre on a surface of weight 1, after fitting maxSize. */
+    density: number;
+    settings: ResolvedBake;
+    /** Meshes with a lightmap: name, texels per metre, the atlas's share. */
+    baked: {
+        name: string;
+        density: number;
+        share: number;
+        raised?: boolean;
+        triangles: number;
+        seconds: number;
+    }[];
+    /** Meshes left without one, and why. */
+    left: {
+        name: string;
+        why: string;
+    }[];
+    /** The lights baked, and the ones not, with why. */
+    lights: {
+        kind: string;
+        name: string;
+        baked: boolean;
+        why?: string;
+        /**
+         * A point or spot light: what its rays meet first within half a metre,
+         * each mesh with the share of 64 rays it stops (a bulb around the light
+         * stops nearly all: bake.ignore it, or move the light out of it).
+         */
+        around?: {
+            name: string;
+            share: number;
+        }[];
+    }[];
+    /** How the sky is baked: the environment, a hemisphere light, an ambient light, or why not. */
+    sky: string[];
+    /** Irradiance over the baked texels: the darkest tenth, the median, the brightest tenth, the largest. */
+    irradiance: {
+        p10: number;
+        median: number;
+        p90: number;
+        max: number;
+    };
+    /** The share of atlas texels a surface covers. */
+    covered: number;
+    /** Seconds each stage took. */
+    seconds: {
+        unwrap: number;
+        gather: number;
+        read: number;
+        total: number;
+    };
+    /** The bake file's bytes. */
+    bytes: number;
+    /** The GPU it drew on. */
+    gl: string;
+}
+//# sourceMappingURL=bake.d.ts.map

package/node_modules/@allyhub-next/scenery/dist/bake.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+export const BAKE_DEFAULTS={density:40,maxSize:2048,minTexels:128,islandTexels:16,ownUv:!0,samples:16,bounces:4,denoise:{radius:3,distance:.02},clamp:40,tile:256,posedAt:[.5,1,2,4,8,16,32],probeSize:256},BAKE_MIN_SIZE=64;export function bakeProblems(e){const t=[],n=(s,i,a)=>{i!==void 0&&(Number.isFinite(i)&&i>0&&(a===void 0||i<=a)||t.push(`bake.${s} is a number above 0${a===void 0?"":` and at most ${String(a)}`}, not ${String(i)}`))},r=(s,i,a,o)=>{i!==void 0&&(Number.isInteger(i)&&i>=a&&i<=o||t.push(`bake.${s} is a whole number from ${String(a)} to ${String(o)}, not ${String(i)}`))};n("density",e.density,4096),r("maxSize",e.maxSize,BAKE_MIN_SIZE,8192),r("minTexels",e.minTexels,0,1048576),r("islandTexels",e.islandTexels,0,65536),r("samples",e.samples,1,4096),r("bounces",e.bounces,0,16),r("tile",e.tile,16,8192),n("clamp",e.clamp),r("denoise.radius",e.denoise?.radius,0,16),n("denoise.distance",e.denoise?.distance);for(const[s,i]of Object.entries(e.weight??{}))n(`weight["${s}"]`,i,100);for(const s of e.posedAt??[])Number.isFinite(s)&&s>=0||t.push(`bake.posedAt holds moments of scenery time, 0 or later, not ${String(s)}`);if(e.probe){const s=e.probe.at;(!Array.isArray(s)||s.length!==3||!s.every(Number.isFinite))&&t.push("bake.probe.at is a point [x, y, z] in metres"),r("probe.size",e.probe.size,16,2048)}return t}export function resolveBake(e={}){const t={};for(const n of Object.keys(e.weight??{}).sort())t[n]=e.weight?.[n]??1;return{density:e.density??BAKE_DEFAULTS.density,maxSize:e.maxSize??BAKE_DEFAULTS.maxSize,minTexels:e.minTexels??BAKE_DEFAULTS.minTexels,islandTexels:e.islandTexels??BAKE_DEFAULTS.islandTexels,ownUv:e.ownUv??BAKE_DEFAULTS.ownUv,samples:e.samples??BAKE_DEFAULTS.samples,bounces:e.bounces??BAKE_DEFAULTS.bounces,weight:t,skip:[...e.skip??[]].sort(),ignore:[...e.ignore??[]].sort(),denoise:{radius:e.denoise?.radius??BAKE_DEFAULTS.denoise.radius,distance:e.denoise?.distance??BAKE_DEFAULTS.denoise.distance},clamp:e.clamp??BAKE_DEFAULTS.clamp,tile:e.tile??BAKE_DEFAULTS.tile,posedAt:[...e.posedAt??BAKE_DEFAULTS.posedAt],probe:e.probe?{at:[e.probe.at[0],e.probe.at[1],e.probe.at[2]],hide:[...e.probe.hide??[]].sort(),size:e.probe.size??BAKE_DEFAULTS.probeSize}:null}}export function bakeRenderer(e){if(/swiftshader/i.test(e))return BAKE_CPU;let t=2166136261;for(let n=0;n<e.length;n++)t=Math.imul(t^e.charCodeAt(n),16777619);return`gpu-${(t>>>0).toString(16).padStart(8,"0")}`}export const BAKE_CPU="cpu";

package/node_modules/@allyhub-next/scenery/dist/camera.d.ts

@@ -0,0 +1,150 @@
+import { type FieldOfView, type LensFrame } from "./lens.js";
+import { type Vec3 } from "./vec.js";
+/**
+ * A camera as an agent writes it. It points one of three ways: at a
+ * `target` (a point, or an object's name: it turns to keep it centred as
+ * it moves), along a `direction`, or by `yaw` and `pitch`. With none of
+ * them it looks down −Z, level.
+ */
+export interface CameraState {
+    /** The camera's place, m. */
+    position: Vec3;
+    /** A point, or an object's name (the centre of its box). */
+    target?: Vec3 | string;
+    /** A direction to look along, instead of a target. */
+    direction?: Vec3;
+    /** Degrees about +Y, instead of a target: 0 looks down −Z, 90 down −X (left). */
+    yaw?: number;
+    /** Degrees above the horizon (negative looks down), with or without yaw. */
+    pitch?: number;
+    /** Which way is up before roll; default [0, 1, 0]. */
+    up?: Vec3;
+    /** Degrees about the view: positive turns the camera counterclockwise, as three.js's rotation.z does. */
+    roll?: number;
+    /** 35 mm-equivalent focal length, mm; default 26. */
+    lens?: number;
+    /** What the lens is measured on; default "diagonal". */
+    lensFrame?: LensFrame;
+    /** The vertical angle in degrees, instead of a lens. */
+    fov?: number;
+    /** Near plane, m; default 0.05. */
+    near?: number;
+    /** Far plane, m; default 500. */
+    far?: number;
+    /**
+     * The aperture, an f-number in the same 35 mm-equivalent terms as `lens`
+     * (a lens's f-number times its crop factor: a phone's f/1.8 main camera
+     * is about f/8): with `focus`, how soft what is nearer or farther than
+     * the focus is drawn, as a thin lens makes it. Without it the camera is
+     * a pinhole and everything is sharp.
+     */
+    aperture?: number;
+    /**
+     * Where it is focused: a distance along its view, m; a point; or an
+     * object's name (the centre of its box, followed as it moves). Needed
+     * with `aperture`.
+     */
+    focus?: number | Vec3 | string;
+    /**
+     * Its exposure, EV at ISO 100: the scenery's light is scaled by
+     * 1 / (1.2 · 2^ev) before the tone curve while it draws (three.js's
+     * toneMappingExposure, exposureOf), as a camera exposes. Without it, the
+     * scenery's own renderer.toneMappingExposure. In a scenery whose lights are
+     * physical (lux, candela) and whose screens give out their nits, a phone
+     * indoors that keeps a laptop's screen from burning out is about 8 to 9.
+     */
+    ev?: number;
+}
+/** What three.js's toneMappingExposure is for a camera at `ev` (EV at ISO 100): 1 / (1.2 · 2^ev). */
+export declare function exposureOf(ev: number): number;
+export declare const CAMERA_DEFAULTS: {
+    lens: number;
+    lensFrame: LensFrame;
+    near: number;
+    far: number;
+    up: Vec3;
+    roll: number;
+};
+/** A camera ready to draw a frame: its basis, its angles, its planes. */
+export interface ResolvedCamera {
+    position: Vec3;
+    /** Unit vector the camera looks along (its local −Z). */
+    forward: Vec3;
+    /** Unit vector up in the picture (its local +Y), after roll. */
+    up: Vec3;
+    /** Unit vector right in the picture (its local +X), after roll. */
+    right: Vec3;
+    /** The point it was aimed at, when it was given a target. */
+    target?: Vec3;
+    /** Width over height of the frame. */
+    aspect: number;
+    fov: FieldOfView;
+    /** The lens in the default convention (the output frame's diagonal), mm. */
+    lens: number;
+    near: number;
+    far: number;
+    /** The rotation from the camera's local axes to the scenery's, as x, y, z, w. */
+    quaternion: readonly [number, number, number, number];
+    /**
+     * Depth of field, when the camera has an aperture: its f-number, the
+     * focus's distance along the view (m) and the 35 mm-equivalent lens
+     * (mm, in the convention the f-number is in).
+     */
+    dof?: {
+        aperture: number;
+        focus: number;
+        lens: number;
+    };
+    /** Its exposure, EV at ISO 100, when it has one (CameraState.ev). */
+    ev?: number;
+}
+/** A camera state that cannot be drawn, with every reason. */
+export declare class CameraError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/** How a name becomes a point: the host's scenery, or nothing. */
+export type PointOf = (name: string) => Vec3 | undefined;
+/** The direction yaw and pitch say, in degrees. */
+export declare function directionOf(yaw?: number, pitch?: number): Vec3;
+/** Yaw and pitch of a direction, in degrees: directionOf's inverse. */
+export declare function yawPitchOf(direction: Vec3): {
+    yaw: number;
+    pitch: number;
+};
+/**
+ * What is wrong with a camera state, whatever the frame: every reason it
+ * cannot be drawn, or none. A target given by name is checked by
+ * resolveCamera, which knows the scenery.
+ */
+export declare function cameraProblems(state: CameraState): string[];
+/**
+ * A camera state resolved for a frame of `aspect` (width over height):
+ * its basis, its angles and its planes. Throws CameraError with every
+ * reason when it cannot be drawn.
+ */
+export declare function resolveCamera(state: CameraState, aspect: number, pointOf?: PointOf): ResolvedCamera;
+/**
+ * The diameter, in frame pixels, of the circle a point `depth` m along a
+ * camera's view is drawn as on a frame `frameHeight` px tall: a thin lens
+ * of the camera's 35 mm-equivalent lens and f-number focused at its focus.
+ * 0 for a pinhole camera and at the focus.
+ *
+ * c = F · f / (N · (s − f)) · |d − s| / d, with F the focal length in frame
+ * pixels, f the lens and s the focus in metres, N the f-number, d the depth.
+ */
+export declare function blurDiameter(camera: ResolvedCamera, depth: number, frameHeight: number): number;
+/** Where a point lands in a camera's frame. */
+export interface Projection {
+    /** -1 at the frame's left edge, 1 at its right. */
+    x: number;
+    /** -1 at the frame's bottom edge, 1 at its top. */
+    y: number;
+    /** Distance along the view, m; at or below 0 the point is behind the camera. */
+    depth: number;
+    /** In front of the near plane, short of the far one, and inside the frame. */
+    inView: boolean;
+}
+/** A point projected by a resolved camera. */
+export declare function project(camera: ResolvedCamera, point: Vec3): Projection;
+//# sourceMappingURL=camera.d.ts.map

package/node_modules/@allyhub-next/scenery/dist/camera.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{diagonalLens as L,fieldOfView as V,fieldOfViewFromVertical as j,lensForVertical as k,lensFrameProblem as z}from"./lens.js";import{cross as N,DEG as g,dot as w,isFinite3 as y,length as $,normalize as M,rotate as E,scale as q,sub as x}from"./vec.js";export function exposureOf(n){return 1/(1.2*2**n)}export const CAMERA_DEFAULTS={lens:26,lensFrame:"diagonal",near:.05,far:500,up:[0,1,0],roll:0};export class CameraError extends Error{problems;constructor(i){super(`The camera cannot be drawn: ${i.join("; ")}.`),this.name="CameraError",this.problems=i}}const S=n=>n===void 0||Number.isFinite(n);export function directionOf(n=0,i=0){const u=n*g,e=i*g;return[-Math.sin(u)*Math.cos(e),Math.sin(e),-Math.cos(u)*Math.cos(e)]}export function yawPitchOf(n){const i=M(n);return{yaw:Math.atan2(-i[0],-i[2])/g,pitch:Math.asin(Math.max(-1,Math.min(1,i[1])))/g}}export function cameraProblems(n){const i=[],{position:u,target:e,direction:r,yaw:a,pitch:t,up:s,roll:l,lens:c,fov:h}=n;y(u)||i.push("its position is not three finite numbers");const p=[e!==void 0?"target":void 0,r!==void 0?"direction":void 0,a!==void 0||t!==void 0?"yaw/pitch":void 0].filter(f=>f!==void 0);if(p.length>1&&i.push(`it points ${String(p.length)} ways (${p.join(", ")}): give one`),Array.isArray(e)&&!y(e)&&i.push("its target is not three finite numbers"),r!==void 0&&(y(r)?$(r)===0&&i.push("its direction is zero"):i.push("its direction is not three finite numbers")),(!S(a)||!S(t))&&i.push("its yaw or pitch is not finite"),t!==void 0&&Math.abs(t)>=90&&i.push(`its pitch ${String(t)}° looks straight up or down, which leaves no way to turn it about its view: keep it within ±90°`),s!==void 0&&(!y(s)||$(s)===0)&&i.push("its up is not a non-zero vector"),S(l)||i.push("its roll is not finite"),c!==void 0&&h!==void 0&&i.push("it has both a lens and a fov: give one"),c!==void 0&&!(Number.isFinite(c)&&c>0)&&i.push(`its lens ${String(c)} is not a positive number of mm`),h!==void 0&&!(Number.isFinite(h)&&h>0&&h<180)&&i.push(`its fov ${String(h)}° is outside (0°, 180°)`),n.lensFrame!==void 0){const f=z(n.lensFrame);f&&i.push(f)}const{aperture:m,focus:d}=n;m!==void 0&&(Number.isFinite(m)&&m>0?d===void 0&&i.push("it has an aperture and no focus: give focus, a distance along its view (m), a point or an object's name"):i.push(`its aperture f/${String(m)} is not a positive f-number`)),n.ev!==void 0&&!Number.isFinite(n.ev)&&i.push(`its ev ${String(n.ev)} is not a number`),typeof d=="number"&&!(Number.isFinite(d)&&d>0)&&i.push(`its focus ${String(d)} m is not a distance in front of it`),Array.isArray(d)&&!y(d)&&i.push("its focus is not three finite numbers");const o=n.near??CAMERA_DEFAULTS.near,b=n.far??CAMERA_DEFAULTS.far;return Number.isFinite(o)&&o>0||i.push(`its near plane ${String(o)} m is not above 0`),Number.isFinite(b)&&b>o||i.push(`its far plane ${String(b)} m is not beyond its near plane ${String(o)} m`),i}function C(n,i,u){const[e,r,a]=n,[t,s,l]=i,[c,h,p]=u,m=e+s+p;if(m>0){const o=.5/Math.sqrt(m+1);return[(l-h)*o,(c-a)*o,(r-t)*o,.25/o]}if(e>s&&e>p){const o=2*Math.sqrt(1+e-s-p);return[.25*o,(t+r)/o,(c+a)/o,(l-h)/o]}if(s>p){const o=2*Math.sqrt(1+s-e-p);return[(t+r)/o,.25*o,(h+l)/o,(c-a)/o]}const d=2*Math.sqrt(1+p-e-s);return[(c+a)/d,(h+l)/d,.25*d,(r-t)/d]}const P=1-1e-9;export function resolveCamera(n,i,u){const e=cameraProblems(n);Number.isFinite(i)&&i>0||e.push(`the frame's aspect ${String(i)} is not a positive number`);let r;if(typeof n.target=="string"?(r=u?.(n.target),r||e.push(u?`its target "${n.target}" names nothing in the scenery`:`its target "${n.target}" is a name, and there is no scenery to find it in`)):r=n.target,e.length>0)throw new CameraError(e);const a=n.position;let t;if(r){const f=x(r,a);if($(f)===0)throw new CameraError(["its target is at its position"]);t=M(f)}else n.direction?t=M(n.direction):t=directionOf(n.yaw,n.pitch);const s=M(n.up??CAMERA_DEFAULTS.up);if(Math.abs(w(t,s))>P)throw new CameraError(["it looks straight along its up, which leaves no way to turn it about its view: move its target or give another up"]);let l=M(N(t,s)),c=N(l,t);const h=(n.roll??CAMERA_DEFAULTS.roll)*g;if(h!==0){const f=q(t,-1);l=E(l,f,h),c=E(c,f,h)}const p=n.lensFrame??CAMERA_DEFAULTS.lensFrame,m=n.fov!==void 0?j(n.fov,i):V(n.lens??CAMERA_DEFAULTS.lens,i,p),d=n.fov!==void 0?k(n.fov,i):L(n.lens??CAMERA_DEFAULTS.lens,i,p),o=n.near??CAMERA_DEFAULTS.near;let b;if(n.aperture!==void 0&&n.focus!==void 0){const f=n.focus;let v;if(typeof f=="number")v=f;else{const A=typeof f=="string"?u?.(f):f;if(!A)throw new CameraError([u?`its focus "${String(f)}" names nothing in the scenery`:`its focus "${String(f)}" is a name, and there is no scenery to find it in`]);v=w(x(A,a),t)}const F=n.fov!==void 0?d:n.lens??CAMERA_DEFAULTS.lens;if(!(v>Math.max(o,F/1e3)))throw new CameraError([`its focus is ${v.toFixed(3)} m along its view, which must be past its near plane (${String(o)} m) and its lens (${String(F)} mm)`]);b={aperture:n.aperture,focus:v,lens:F}}return{position:a,forward:t,up:c,right:l,...r?{target:r}:{},aspect:i,fov:m,lens:d,near:o,far:n.far??CAMERA_DEFAULTS.far,quaternion:C(l,c,q(t,-1)),...b?{dof:b}:{},...n.ev!==void 0?{ev:n.ev}:{}}}export function blurDiameter(n,i,u){const e=n.dof;if(!e)return 0;const r=u/2/Math.tan(n.fov.vertical*g/2),a=e.lens/1e3,t=e.focus,s=Math.max(i,n.near);return r*a/(e.aperture*(t-a))*(Math.abs(s-t)/s)}export function project(n,i){const u=x(i,n.position),e=w(u,n.forward),r=Math.tan(n.fov.horizontal*g/2),a=Math.tan(n.fov.vertical*g/2),t=w(u,n.right)/(e*r),s=w(u,n.up)/(e*a),l=e>=n.near&&e<=n.far&&Math.abs(t)<=1&&Math.abs(s)<=1;return{x:t,y:s,depth:e,inView:l}}

package/node_modules/@allyhub-next/scenery/dist/curve.d.ts

@@ -0,0 +1,40 @@
+import { type Vec3 } from "./vec.js";
+/** Points closer than this are one point, m. */
+export declare const SAME_POINT = 1e-9;
+/** A point on a curve, its unit tangent and where it is. */
+export interface CurvePoint {
+    point: Vec3;
+    /** Unit tangent; [0, 0, -1] on a curve with no length. */
+    tangent: Vec3;
+}
+/** A curve through points, walked by distance. */
+export declare class Curve {
+    /** The curve's length, m. */
+    readonly length: number;
+    /** The distance along the curve at each point it was given, in their order. */
+    readonly knots: readonly number[];
+    private readonly segments;
+    private readonly first;
+    private frames?;
+    /**
+     * A curve through `points`, with `alpha` 0.5 (centripetal; 0 uniform, 1
+     * chordal). A point that repeats the one before it adds nothing.
+     */
+    constructor(points: readonly Vec3[], alpha?: number);
+    /** The segment and its u at a distance along the curve, clamped to the curve. */
+    private locate;
+    /** The point and unit tangent at a distance along the curve (clamped). */
+    at(d: number): CurvePoint;
+    /**
+     * The point `d` m along the curve, past its ends along its end tangents:
+     * what a target some way ahead of a camera near the end looks at.
+     */
+    extended(d: number): Vec3;
+    /**
+     * Up at a distance along the curve in a frame that does not twist about
+     * it (rotation-minimizing), starting from `up` made square to the
+     * curve's first tangent.
+     */
+    upAt(d: number, up?: Vec3): Vec3;
+}
+//# sourceMappingURL=curve.d.ts.map