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

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

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

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{add as w,addScaled as L,cross as T,distance as y,dot as q,length as O,normalize as S,scale as o,sub as u}from"./vec.js";export const SAME_POINT=1e-9;const _=[[0,.5688888888888889],[-.5384693101056831,.4786286704993665],[.5384693101056831,.4786286704993665],[-.906179845938664,.2369268850561891],[.906179845938664,.2369268850561891]],I=16;function j(e,n,t,s){return{c0:e,c1:t,c2:w(w(o(e,-3),o(n,3)),w(o(t,-2),o(s,-1))),c3:w(w(o(e,2),o(n,-2)),w(t,s))}}const D=(e,n)=>{const t=n*n,s=t*n;return[e.c0[0]+e.c1[0]*n+e.c2[0]*t+e.c3[0]*s,e.c0[1]+e.c1[1]*n+e.c2[1]*t+e.c3[1]*s,e.c0[2]+e.c1[2]*n+e.c2[2]*t+e.c3[2]*s]},B=(e,n)=>{const t=n*n;return[e.c1[0]+2*e.c2[0]*n+3*e.c3[0]*t,e.c1[1]+2*e.c2[1]*n+3*e.c3[1]*t,e.c1[2]+2*e.c2[2]*n+3*e.c3[2]*t]};function N(e,n,t){const s=(t-n)/2,i=(n+t)/2;let d=0;for(const[g,p]of _)d+=p*O(B(e,i+s*g));return d*s}export class Curve{length;knots;segments;first;frames;constructor(n,t=.5){const s=n[0];if(!s)throw new Error("A curve needs at least one point.");this.first=s;const i=[],d=[];for(const c of n){const h=i.at(-1);(!h||y(h,c)>SAME_POINT)&&i.push(c),d.push(i.length-1)}this.segments=[];let g=0;const p=c=>{const h=i.length;if(c<0){const[r,l]=[i[0],i[1]];return r&&l?u(o(r,2),l):s}if(c>=h){const[r,l]=[i[h-1],i[h-2]];return r&&l?u(o(r,2),l):s}return i[c]??s};for(let c=0;c+1<i.length;c++){const[h,r,l,v]=[p(c-1),p(c),p(c+1),p(c+2)];let m=y(h,r)**t,a=y(r,l)**t,f=y(l,v)**t;a<1e-4&&(a=1),m<1e-4&&(m=a),f<1e-4&&(f=a);const A=o(w(u(o(u(r,h),1/m),o(u(l,h),1/(m+a))),o(u(l,r),1/a)),a),x=o(w(u(o(u(l,r),1/a),o(u(v,r),1/(a+f))),o(u(v,l),1/f)),a),k={...j(r,l,A,x),table:[0],start:g,length:0};let E=0;for(let M=0;M<I;M++)E+=N(k,M/I,(M+1)/I),k.table.push(E);k.length=E,this.segments.push(k),g+=E}this.length=g;const b=[0,...this.segments.map(c=>c.start+c.length)];this.knots=d.map(c=>b[c]??0)}locate(n){const t=this.segments;if(t.length===0)return;const s=Math.min(Math.max(n,0),this.length);let i=0,d=t.length-1;for(;i<d;){const a=i+d+1>>1;(t[a]?.start??0)<=s?i=a:d=a-1}const g=t[i];if(!g)return;const p=Math.min(Math.max(s-g.start,0),g.length);let b=0;for(;b<I-1&&(g.table[b+1]??1/0)<p;)b++;const c=b/I;let h=c,r=(b+1)/I;const l=g.table[b]??0,v=(g.table[b+1]??l)-l;let m=v>0?h+(p-l)/v*(r-h):h;for(let a=0;a<30;a++){const f=l+N(g,c,m)-p;if(Math.abs(f)<1e-12*Math.max(1,this.length))break;f>0?r=m:h=m;const A=O(B(g,m));let x=A>0?m-f/A:(h+r)/2;x>h&&x<r||(x=(h+r)/2),m=x}return{seg:g,u:m}}at(n){const t=this.locate(n);if(!t)return{point:this.first,tangent:[0,0,-1]};const s=B(t.seg,t.u),i=O(s)>0?S(s):[0,0,-1];return{point:D(t.seg,t.u),tangent:i}}extended(n){if(n<0){const{point:t,tangent:s}=this.at(0);return L(t,s,n)}if(n>this.length){const{point:t,tangent:s}=this.at(this.length);return L(t,s,n-this.length)}return this.at(n).point}upAt(n,t=[0,1,0]){if(this.length===0)return S(t);if(!this.frames){const v=Math.max(64,this.segments.length*32),m=this.length/v,a=this.at(0).tangent;let f=u(t,o(a,q(t,a)));O(f)<1e-9&&(f=Math.abs(a[2])<.9?[0,0,-1]:[1,0,0]),f=S(u(f,o(a,q(f,a))));const A=[f];let x=this.at(0);for(let k=1;k<=v;k++){const E=this.at(k*m),M=u(E.point,x.point),z=q(M,M);let C=f,G=x.tangent;z>0&&(C=u(f,o(M,2/z*q(M,f))),G=u(x.tangent,o(M,2/z*q(M,x.tangent))));const P=u(E.tangent,G),K=q(P,P);f=K>0?u(C,o(P,2/K*q(P,C))):C,A.push(f),x=E}this.frames={step:m,ups:A}}const{step:s,ups:i}=this.frames,d=Math.min(Math.max(n,0),this.length)/s,g=Math.min(Math.floor(d),i.length-2),p=i[g]??t,b=i[g+1]??p,c=d-g,h=w(o(p,1-c),o(b,c)),r=this.at(n).tangent,l=u(h,o(r,q(h,r)));return O(l)>0?S(l):S(T(r,[1,0,0]))}}

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

@@ -0,0 +1,164 @@
+import type { AnimationMixer, Group, Object3D, Scene, Texture, TextureDataType, WebGLRenderer } from "three";
+import type { WebGPURenderer } from "three/webgpu";
+import { type BakeOptions } from "./bake.js";
+import { type CameraState } from "./camera.js";
+import type { Move, ScreenFace } from "./move.js";
+import type { Vec3 } from "./vec.js";
+/** A media import or a project file's path. */
+export type AssetRef = string | {
+    readonly url: string;
+};
+/** A scenery's renderer defaults: the fastest drawing; a scenery asks for more. */
+export declare const SCENERY_RENDERER_DEFAULTS: {
+    antialias: boolean;
+    transmissionScale: number;
+    /** A camera's depth of field: samples per pixel, and the widest blur drawn (its radius, px of the picture as drawn). */
+    focus: {
+        samples: number;
+        maxRadius: number;
+    };
+};
+/** How AllyHub makes the renderer: what cannot change once it exists. */
+export interface SceneryRendererOptions {
+    /**
+     * "webgl" (default): three's WebGLRenderer. "webgpu": WebGPURenderer
+     * from three/webgpu, for node materials and TSL, drawn through its
+     * WebGL 2 back end (forceWebGL), which SwiftShader draws.
+     */
+    kind?: "webgl" | "webgpu";
+    /**
+     * Multisampled antialiasing (default false: the fastest drawing, edges
+     * stepped). True smooths edges at about a tenth more time; a scenery
+     * layer's quality.scale above 1 supersamples instead.
+     */
+    antialias?: boolean;
+    /**
+     * The size of the pass three.js draws the scene in once more for
+     * transmissive materials (glass), a share of the frame's (three's
+     * transmissionResolutionScale): default 0.25, the fastest; 1 draws
+     * what shows through glass sharp.
+     */
+    transmissionScale?: number;
+    /** The buffer effects draw into (three's outputBufferType: UnsignedByteType, HalfFloatType…). */
+    outputBufferType?: TextureDataType;
+    logarithmicDepthBuffer?: boolean;
+    reversedDepthBuffer?: boolean;
+    /**
+     * How a camera's depth of field (its aperture and focus) is drawn: the
+     * samples each pixel is gathered from (default 64; fewer is faster and
+     * grainier) and the widest blur drawn, as a radius in the picture's
+     * pixels as drawn (default 64; a wider circle of confusion is drawn
+     * this wide). `supersample` draws the scene that many times as wide and
+     * high (1 to 4) and averages each pixel's samples, as multisampling
+     * smooths edges without an aperture: default 2 with `antialias`, else
+     * 1 (each 2 is about four times the pass's time).
+     */
+    focus?: {
+        samples?: number;
+        maxRadius?: number;
+        supersample?: number;
+    };
+}
+/** A box in world space. */
+export interface Bounds {
+    min: Vec3;
+    max: Vec3;
+}
+/** What a scenery is given to build with and to pose itself. */
+export interface SceneryHost {
+    /** The scene the scenery builds into. */
+    readonly scene: Scene;
+    /** The renderer AllyHub made; set tone mapping, exposure, shadows, effects on it. */
+    readonly renderer: WebGLRenderer | WebGPURenderer;
+    /** A glTF or GLB's scene, with the lent decoders; its animations on userData.animations. The read is recorded. */
+    load(asset: AssetRef): Promise<Group>;
+    /**
+     * A picture as a texture. The read is recorded. Its colour space is sRGB
+     * (a colour picture, a diffuse map); `{ colorSpace: "linear" }` reads it
+     * as data (a normal, roughness, AO or displacement map).
+     */
+    texture(asset: AssetRef, opts?: {
+        colorSpace?: "srgb" | "linear";
+    }): Promise<Texture>;
+    /** An HDR or EXR as the scene's environment, and its background when asked. The read is recorded. */
+    environment(asset: AssetRef, opts?: {
+        background?: boolean;
+    }): Promise<Texture>;
+    /** Poses an animation mixer at t: every action reset, then setTime(t). */
+    seek(mixer: AnimationMixer, t: number): void;
+    /** An object by its name: undefined for none, an error for two. */
+    object(name: string): Object3D | undefined;
+    /** Where a named object is now: the centre of its box. */
+    positionOf(name: string): Vec3;
+    /** A named object's box now, from its vertices. */
+    boundsOf(name: string): Bounds;
+    /** A project file's URL. */
+    asset(path: string): string;
+    /**
+     * The scenery time, s, of a word or anchor reference ("@tap", "@tap+0.2",
+     * a word) of the part that draws the scenery (or the times its host was
+     * given), as a move's keys find theirs: in update, so the scenery's own
+     * objects keep to the words. Throws a NeedsTimeError where there is none
+     * (in build).
+     */
+    time(ref: string): number;
+    /**
+     * A screen's face as it is now (an object's first mesh, its +Z side):
+     * `point(x, y)` is a place on it from its content's top left, as shares
+     * of its width and height, in world space; undefined for no such object.
+     */
+    screen(name: string): ScreenFace | undefined;
+    /**
+     * The picture a screen drawn in the scenery shows (screen(…, { inScenery })),
+     * as a texture with its smaller levels: for a scenery's own materials, the
+     * light the screen casts on what is near it and what reflects it. Its
+     * (u, v) is a place on the screen's content from its top left. Undefined
+     * for a screen drawn over the scenery, or before its first moment.
+     */
+    screenPicture(name: string): Texture | undefined;
+}
+/**
+ * A prop a video brings into a scenery (`scenery(w, { props })`): a person's stand-in in the pose a shot needs, a
+ * pointer held to a screen. It is built once the scenery is built and its bake laid, so it is never part of
+ * the bake and never stops a bake from fitting the scene; it takes the light the scenery's unbaked things take
+ * (the bake's probe, where the bake has one); it is posed at each moment from t alone, after the scenery's own
+ * update; and it shows only in the layers that add it.
+ */
+export interface SceneryProp<O extends Object3D = Object3D> {
+    /** What it is called in the scenery (its object's name when it has none). */
+    name: string;
+    /** Makes it: with the scenery's host, to load a model, read a texture or find where a named object is. */
+    build(w: SceneryHost): O | Promise<O>;
+    /** Poses it at scenery time t (its place, its turn, a part of it), from t alone. */
+    update?(object: O, t: number, w: SceneryHost): void;
+}
+/** A scenery as an agent writes it. M is what build returns and update receives. */
+export interface SceneryDefinition<M = unknown> {
+    renderer?: SceneryRendererOptions;
+    /** Once, before anything is drawn. Awaited, with every load it starts. */
+    build(w: SceneryHost): M | Promise<M>;
+    /** Every moment, from t alone (seconds of scenery time). */
+    update?(made: M, t: number, w: SceneryHost): void;
+    /** Cameras by name, for the commands and for layers. */
+    cameras?: Readonly<Record<string, CameraState>>;
+    /** Moves by name (keys, path, orbit or the agent's own), for the commands and for layers. */
+    moves?: Readonly<Record<string, Move>>;
+    /**
+     * How the scenery's light is baked (every value has a default). A bake
+     * made for the scene as built is laid on it each time it is built,
+     * wherever it is drawn.
+     */
+    bake?: BakeOptions;
+}
+/** A scenery, as defineScenery returns it: its definition, frozen, marked by its kind. */
+export interface Scenery<M = unknown> extends SceneryDefinition<M> {
+    readonly kind: "scenery";
+}
+/** Whether a value is a scenery defineScenery made (also by another copy of this package). */
+export declare function isScenery(v: unknown): v is Scenery;
+/**
+ * A scenery: the default export of a scenery module. Checks what can be
+ * checked without drawing it (its cameras), and throws with every reason.
+ */
+export declare function defineScenery<M>(def: SceneryDefinition<M>): Scenery<M>;
+//# sourceMappingURL=define.d.ts.map

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

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{bakeProblems as c}from"./bake.js";import{cameraProblems as f}from"./camera.js";export const SCENERY_RENDERER_DEFAULTS={antialias:!1,transmissionScale:.25,focus:{samples:64,maxRadius:64}};export function isScenery(e){if(typeof e!="object"||e===null)return!1;const n=e;return n.kind==="scenery"&&typeof n.build=="function"}export function defineScenery(e){if(typeof e.build!="function")throw new Error("defineScenery needs build(w), the function that builds the scenery.");const n=e.renderer?.kind;if(n!==void 0&&n!=="webgl"&&n!=="webgpu")throw new Error(`defineScenery's renderer.kind is "webgl" or "webgpu", not ${JSON.stringify(n)}.`);const r=e.renderer?.transmissionScale;if(r!==void 0&&!(Number.isFinite(r)&&r>0&&r<=2))throw new Error(`defineScenery's renderer.transmissionScale is a share of the frame's size in (0, 2], not ${String(r)}.`);const i=[];for(const[o,t]of Object.entries(e.cameras??{}))for(const s of f(t))i.push(`camera "${o}": ${s}`);for(const[o,t]of Object.entries(e.moves??{}))typeof t!="function"&&i.push(`move "${o}" is not a function of time`);if(e.bake!==void 0&&i.push(...c(e.bake)),i.length>0)throw new Error(`defineScenery: ${i.join("; ")}.`);return Object.freeze({...e,kind:"scenery"})}

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

@@ -0,0 +1,64 @@
+import { type CameraState } from "./camera.js";
+import { type LensFrame } from "./lens.js";
+import { type Vec3 } from "./vec.js";
+/** A box by its corners. */
+export interface Box {
+    min: Vec3;
+    max: Vec3;
+}
+/** Shares of the frame's width (left, right) or height (top, bottom) kept clear at each side. */
+export interface Margins {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+export interface FitOptions {
+    /** What to frame: points, boxes (all eight corners count) or a sphere. */
+    points?: readonly Vec3[];
+    boxes?: readonly Box[];
+    sphere?: {
+        center: Vec3;
+        radius: number;
+    };
+    /** Width over height of the frame. */
+    aspect: number;
+    /** The view: a direction (from the camera toward the objects) or yaw and pitch; default yaw 0 (looking down −Z). */
+    direction?: Vec3;
+    yaw?: number;
+    pitch?: number;
+    /** The point aimed at; default the centre of the box round what is framed. */
+    aim?: Vec3;
+    /** The lens, or a vertical fov; with adjust "lens", the result's. */
+    lens?: number;
+    lensFrame?: LensFrame;
+    fov?: number;
+    /** How far toward the frame's edges what is framed may reach, 0–1; default 1. */
+    fill?: number;
+    margins?: Margins;
+    /** Which edges bound it: "both" (default), "width" or "height". */
+    axis?: "both" | "width" | "height";
+    /**
+     * "distance" (default): the camera moves along the view to fit. "lens":
+     * it stays at `position` and the lens is solved instead.
+     */
+    adjust?: "distance" | "lens";
+    /** With adjust "lens": where the camera is. */
+    position?: Vec3;
+    up?: Vec3;
+    roll?: number;
+    /** The camera's near plane, m: nothing framed may be nearer; default 0.05. */
+    near?: number;
+}
+export declare const FIT_DEFAULTS: {
+    fill: number;
+    axis: "both";
+    adjust: "distance";
+};
+/**
+ * A camera state that frames what it is given: its position (or, with
+ * adjust "lens", its lens), aimed at `aim`. Throws when the options leave
+ * no room or something framed is behind a camera that cannot move.
+ */
+export declare function fitCamera(opts: FitOptions): CameraState;
+//# sourceMappingURL=fit.d.ts.map

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

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{resolveCamera as E}from"./camera.js";import{lensForVertical as P}from"./lens.js";import{addScaled as $,dot as l,length as z,sub as I}from"./vec.js";export const FIT_DEFAULTS={fill:1,axis:"both",adjust:"distance"};function S(t){const o=[];for(const d of[t.min[0],t.max[0]])for(const f of[t.min[1],t.max[1]])for(const n of[t.min[2],t.max[2]])o.push([d,f,n]);return o}function q(t,o){const d={right:t-2*(o.right??0),left:t-2*(o.left??0),top:t-2*(o.top??0),bottom:t-2*(o.bottom??0)};for(const[f,n]of Object.entries(d))if(!(n>0))throw new Error(`fitCamera's fill and ${f} margin leave no room on that side (${n.toFixed(3)}).`);return d}export function fitCamera(t){const o=[...t.points??[],...(t.boxes??[]).flatMap(S)];if(o.length===0&&!t.sphere)throw new Error("fitCamera needs points, boxes or a sphere to frame.");const d=t.fill??FIT_DEFAULTS.fill,f=t.axis??FIT_DEFAULTS.axis,n=q(d,t.margins??{}),F=t.near??.05,g={...t.lensFrame!==void 0?{lensFrame:t.lensFrame}:{},...t.up!==void 0?{up:t.up}:{},...t.roll!==void 0?{roll:t.roll}:{},...t.near!==void 0?{near:t.near}:{}};let h=t.aim;if(!h)if(o.length>0){const i=[1/0,1/0,1/0],a=[-1/0,-1/0,-1/0];for(const r of o)for(let e=0;e<3;e++)i[e]=Math.min(i[e]??1/0,r[e]??0),a[e]=Math.max(a[e]??-1/0,r[e]??0);h=[(i[0]+a[0])/2,(i[1]+a[1])/2,(i[2]+a[2])/2]}else h=t.sphere?.center??[0,0,0];if((t.adjust??FIT_DEFAULTS.adjust)==="lens"){const i=t.position;if(!i)throw new Error(`fitCamera with adjust "lens" needs the camera's position.`);const a=E({position:i,target:h,...g,...t.fov!==void 0?{fov:t.fov}:{lens:t.lens??26}},t.aspect);let r=0,e=0;const u=[...o],x=t.sphere;for(const y of u){const M=I(y,i),m=l(M,a.forward);if(!(m>F))throw new Error(`fitCamera: a point framed is ${m.toFixed(3)} m along the view, nearer than the near plane (${String(F)} m); no lens can frame it.`);const b=l(M,a.right)/m,p=l(M,a.up)/m;r=Math.max(r,b>=0?b/n.right:-b/n.left),e=Math.max(e,p>=0?p/n.top:-p/n.bottom)}if(x){const y=z(I(x.center,i));if(!(y>x.radius))throw new Error("fitCamera: the camera is inside the sphere it frames.");const M=Math.asin(x.radius/y),m=Math.tan(M);r=Math.max(r,m/Math.min(n.left,n.right)),e=Math.max(e,m/Math.min(n.top,n.bottom))}const j=f==="width"?r/t.aspect:f==="height"?e:Math.max(e,r/t.aspect),C=2*Math.atan(j)*180/Math.PI;return{position:i,target:h,...g,...t.fov!==void 0?{fov:C}:{lens:P(C,t.aspect,t.lensFrame)}}}const c=E({position:[0,0,0],...t.direction!==void 0?{direction:t.direction}:{yaw:t.yaw??0,pitch:t.pitch??0},...g,...t.fov!==void 0?{fov:t.fov}:{lens:t.lens??26}},t.aspect),v=Math.tan(c.fov.horizontal*Math.PI/360),w=Math.tan(c.fov.vertical*Math.PI/360);let s=-1/0;for(const i of o){const a=I(i,h),r=l(a,c.right),e=l(a,c.up),u=l(a,c.forward);f!=="height"&&(s=Math.max(s,(r>=0?r/(v*n.right):-r/(v*n.left))-u)),f!=="width"&&(s=Math.max(s,(e>=0?e/(w*n.top):-e/(w*n.bottom))-u)),s=Math.max(s,F-u)}if(t.sphere){const{center:i,radius:a}=t.sphere,r=f==="width"?v*Math.min(n.left,n.right):f==="height"?w*Math.min(n.top,n.bottom):Math.min(v*Math.min(n.left,n.right),w*Math.min(n.top,n.bottom)),e=l(I(i,h),c.forward);s=Math.max(s,a/Math.sin(Math.atan(r))-e)}return{position:$(h,c.forward,-s),target:h,...g,...t.fov!==void 0?{fov:t.fov}:{lens:t.lens??26}}}

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

@@ -0,0 +1,34 @@
+export interface GlassOptions {
+    /**
+     * How much light the glass reflects looking straight at it (F0), 0 to
+     * 0.16: 0.04 is bare glass (an index of 1.5); an anti-reflective coating
+     * 0.005 to 0.01. More at a slant, by Fresnel.
+     */
+    reflectance?: number;
+    /**
+     * How rough its surface is (three.js's roughness), 0 to 1: 0 a mirror,
+     * about 0.05 a glossy screen, 0.3 to 0.5 a matte anti-glare one. Rough
+     * glass blurs what it reflects, the more the farther it is behind it,
+     * and spreads a lamp's highlight.
+     */
+    roughness?: number;
+    /** The reflection's pixels, as a share of the scenery layer's along each side, 0.05 to 1. */
+    scale?: number;
+}
+export declare const GLASS_DEFAULTS: {
+    reflectance: number;
+    roughness: number;
+    scale: number;
+};
+/** Every reason glass options cannot be drawn. */
+export declare function glassProblems(o: GlassOptions | undefined): string[];
+/**
+ * three.js's physical material makes a dielectric's reflectance from its
+ * index of refraction, ((ior − 1) / (ior + 1))², times a specular
+ * intensity of at most 1: the pair that gives `reflectance`.
+ */
+export declare function glassIor(reflectance: number): {
+    ior: number;
+    specularIntensity: number;
+};
+//# sourceMappingURL=glass.d.ts.map

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

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+export const GLASS_DEFAULTS={reflectance:.04,roughness:.05,scale:1};export function glassProblems(r){if(!r)return[];const t=[],n=(s,o,e,i)=>{s!==void 0&&!(Number.isFinite(s)&&s>=e&&s<=i)&&t.push(`glass.${o} is from ${String(e)} to ${String(i)}, not ${String(s)}.`)};return n(r.reflectance,"reflectance",0,.16),n(r.roughness,"roughness",0,1),n(r.scale,"scale",.05,1),t}export function glassIor(r){if(r<=.04)return{ior:1.5,specularIntensity:r/.04};const n=Math.sqrt(r);return{ior:(1+n)/(1-n),specularIntensity:1}}