@flighthq/camera-controls 0.2.1-next.451.d9a4a4e → 0.2.1-next.530.a223ca9

package/dist/flyCameraController.d.ts

@@ -1,6 +1,10 @@
 import type { Camera3D, FlyCameraController, FlyCameraControllerOptions } from '@flighthq/types';
+export declare function cloneFlyCameraController(source: Readonly<FlyCameraController>): FlyCameraController;
+export declare function copyFlyCameraController(out: FlyCameraController, source: Readonly<FlyCameraController>): void;
 export declare function createFlyCameraController(options?: Readonly<FlyCameraControllerOptions>): FlyCameraController;
 export declare function lookFlyCameraController(controller: FlyCameraController, deltaYaw: number, deltaPitch: number): void;
 export declare function moveFlyCameraController(controller: FlyCameraController, forward: number, right: number, up: number): void;
+export declare function resetFlyCameraController(controller: FlyCameraController, options?: Readonly<FlyCameraControllerOptions>): void;
+export declare function snapFlyCameraController(controller: FlyCameraController): void;
 export declare function updateFlyCameraController(controller: FlyCameraController, camera: Camera3D, deltaTime: number): void;
 //# sourceMappingURL=flyCameraController.d.ts.map

package/dist/flyCameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flyCameraController.d.ts","sourceRoot":"","sources":["../src/flyCameraController.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAKjG,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,0BAA0B,CAAC,GAAG,mBAAmB,CAc7G;AAKD,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAGnH;AAMD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GACT,IAAI,CAON;AAMD,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,mBAAmB,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAoBpH"}
+{"version":3,"file":"flyCameraController.d.ts","sourceRoot":"","sources":["../src/flyCameraController.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAGjG,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAInG;AAID,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,mBAAmB,EAAE,MAAM,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAW7G;AAKD,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,0BAA0B,CAAC,GAAG,mBAAmB,CAc7G;AAKD,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAGnH;AAMD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GACT,IAAI,CAON;AAID,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,mBAAmB,EAC/B,OAAO,CAAC,EAAE,QAAQ,CAAC,0BAA0B,CAAC,GAC7C,IAAI,CAcN;AAGD,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAG7E;AAMD,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,mBAAmB,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAqBpH"}

package/dist/flyCameraController.js

@@ -1,6 +1,27 @@
 import { setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
+import { createEntity } from '@flighthq/entity';
 import { createVector3 } from '@flighthq/geometry';
-import { clamp, damp } from '@flighthq/math';
+import { clamp, damp, deltaAngle } from '@flighthq/math';
+// Allocates an independent Entity containing the same controller value state.
+export function cloneFlyCameraController(source) {
+    const clone = createFlyCameraController();
+    copyFlyCameraController(clone, source);
+    return clone;
+}
+// Copies all controller state without sharing its mutable position. Entity runtime/binding state is
+// deliberately left on `out`; this is a value-state operation, not an ownership transfer.
+export function copyFlyCameraController(out, source) {
+    out.goalPitch = source.goalPitch;
+    out.goalYaw = source.goalYaw;
+    out.maxPitch = source.maxPitch;
+    out.minPitch = source.minPitch;
+    out.pitch = source.pitch;
+    out.position.x = source.position.x;
+    out.position.y = source.position.y;
+    out.position.z = source.position.z;
+    out.smoothTime = source.smoothTime;
+    out.yaw = source.yaw;
+}
 // Allocates a fly / first-person controller. `position` defaults to the origin, `yaw`/`pitch` to 0
 // (looking down -Z), `pitch` limits to just inside ±90° (no gimbal flip), and `smoothTime` to 0 (the
 // look angles snap to their goal each update). Current and goal angles start equal.
@@ -8,7 +29,7 @@ export function createFlyCameraController(options) {
     const yaw = options?.yaw ?? 0;
     const pitch = options?.pitch ?? 0;
     const position = options?.position;
-    return {
+    return createEntity({
         goalPitch: pitch,
         goalYaw: yaw,
         maxPitch: options?.maxPitch ?? DEFAULT_MAX_PITCH,
@@ -17,7 +38,7 @@ export function createFlyCameraController(options) {
         position: createVector3(position?.x ?? 0, position?.y ?? 0, position?.z ?? 0),
         smoothTime: options?.smoothTime ?? 0,
         yaw,
-    };
+    });
 }
 // Moves the goal look angles by the given radian deltas: `deltaYaw` turns horizontally (unbounded),
 // `deltaPitch` looks up/down (clamped to [minPitch, maxPitch]). The app maps a mouse-look delta to
@@ -38,6 +59,28 @@ export function moveFlyCameraController(controller, forward, right, up) {
     position.y += up;
     position.z += -cosYaw * forward + sinYaw * right;
 }
+// Restores the controller to constructor defaults or the supplied seed. Current and goal angles are
+// synchronized, which makes this suitable for scene changes without a one-frame eased transition.
+export function resetFlyCameraController(controller, options) {
+    const yaw = options?.yaw ?? 0;
+    const pitch = options?.pitch ?? 0;
+    const position = options?.position;
+    controller.goalPitch = pitch;
+    controller.goalYaw = yaw;
+    controller.maxPitch = options?.maxPitch ?? DEFAULT_MAX_PITCH;
+    controller.minPitch = options?.minPitch ?? DEFAULT_MIN_PITCH;
+    controller.pitch = pitch;
+    controller.position.x = position?.x ?? 0;
+    controller.position.y = position?.y ?? 0;
+    controller.position.z = position?.z ?? 0;
+    controller.smoothTime = options?.smoothTime ?? 0;
+    controller.yaw = yaw;
+}
+// Snaps current look state to the clamped goal without writing a camera.
+export function snapFlyCameraController(controller) {
+    controller.pitch = clamp(controller.goalPitch, controller.minPitch, controller.maxPitch);
+    controller.yaw = controller.goalYaw;
+}
 // Advances the controller one step and writes the resulting view into `camera` (in place). Eases the
 // current yaw/pitch toward their clamped goals with `@flighthq/math` `damp` (frame-rate independent;
 // `smoothTime` <= 0 or `deltaTime` <= 0 snaps), builds the forward direction from the angles, and
@@ -46,7 +89,8 @@ export function updateFlyCameraController(controller, camera, deltaTime) {
     const goalPitch = clamp(controller.goalPitch, controller.minPitch, controller.maxPitch);
     if (controller.smoothTime > 0 && deltaTime > 0) {
         const lambda = 1 / controller.smoothTime;
-        controller.yaw = damp(controller.yaw, controller.goalYaw, lambda, deltaTime);
+        const nearestGoalYaw = controller.yaw + deltaAngle(controller.yaw, controller.goalYaw);
+        controller.yaw = damp(controller.yaw, nearestGoalYaw, lambda, deltaTime);
         controller.pitch = damp(controller.pitch, goalPitch, lambda, deltaTime);
     }
     else {

package/dist/flyCameraController.js.map

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

package/dist/framing.d.ts

@@ -0,0 +1,5 @@
+import type { BoundingSphereLike, OrbitCameraController, OrthographicProjection, PerspectiveProjection, Projection } from '@flighthq/types';
+export declare function frameOrbitCameraControllerToSphere(controller: OrbitCameraController, projection: Projection, sphere: Readonly<BoundingSphereLike>, aspect: number, padding?: number): boolean;
+export declare function getPerspectiveFrameDistanceToSphere(projection: Readonly<PerspectiveProjection>, radius: number, aspect: number, padding?: number): number;
+export declare function setOrthographicProjectionFrameToSphere(projection: OrthographicProjection, radius: number, aspect: number, padding?: number): void;
+//# sourceMappingURL=framing.d.ts.map

package/dist/framing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framing.d.ts","sourceRoot":"","sources":["../src/framing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,UAAU,EACX,MAAM,iBAAiB,CAAC;AAOzB,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,qBAAqB,EACjC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACpC,MAAM,EAAE,MAAM,EACd,OAAO,SAAI,GACV,OAAO,CAeT;AAKD,wBAAgB,mCAAmC,CACjD,UAAU,EAAE,QAAQ,CAAC,qBAAqB,CAAC,EAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,SAAI,GACV,MAAM,CAKR;AAID,wBAAgB,sCAAsC,CACpD,UAAU,EAAE,sBAAsB,EAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,SAAI,GACV,IAAI,CASN"}

package/dist/framing.js

@@ -0,0 +1,46 @@
+import { clamp } from '@flighthq/math';
+// Frames a non-empty sphere with an orbit controller and active viewport aspect. The target moves to
+// the sphere center immediately. Perspective framing changes only `goalDistance`; orthographic
+// framing changes only projection half-extents because orbit distance does not affect its visible
+// size. Call `snapOrbitCameraController` separately when an immediate perspective dolly is desired.
+// Near/far clip planes are never changed. Returns false without mutation for invalid inputs.
+export function frameOrbitCameraControllerToSphere(controller, projection, sphere, aspect, padding = 1) {
+    if (!(sphere.radius >= 0) || !(aspect > 0) || !(padding > 0))
+        return false;
+    if (projection.kind === 'perspective') {
+        const distance = getPerspectiveFrameDistanceToSphere(projection, sphere.radius, aspect, padding);
+        if (!Number.isFinite(distance))
+            return false;
+        controller.goalDistance = clamp(distance, controller.minDistance, controller.maxDistance);
+    }
+    else {
+        setOrthographicProjectionFrameToSphere(projection, sphere.radius, aspect, padding);
+    }
+    controller.target.x = sphere.center.x;
+    controller.target.y = sphere.center.y;
+    controller.target.z = sphere.center.z;
+    return true;
+}
+// Computes the eye-to-center distance that contains a sphere in both dimensions of a perspective
+// viewport. `padding` is a radius multiplier (1 is tangent). Clip-plane policy remains with the
+// camera owner and is intentionally not hidden here.
+export function getPerspectiveFrameDistanceToSphere(projection, radius, aspect, padding = 1) {
+    const paddedRadius = radius * padding;
+    const verticalHalfFov = projection.fovY * 0.5;
+    const horizontalHalfFov = Math.atan(Math.tan(verticalHalfFov) * aspect);
+    return paddedRadius / Math.sin(Math.min(verticalHalfFov, horizontalHalfFov));
+}
+// Sets orthographic half-extents that contain a sphere without distortion at `aspect`. The tighter
+// viewport dimension touches the padded sphere; the other expands to preserve aspect.
+export function setOrthographicProjectionFrameToSphere(projection, radius, aspect, padding = 1) {
+    const paddedRadius = radius * padding;
+    if (aspect >= 1) {
+        projection.halfHeight = paddedRadius;
+        projection.halfWidth = paddedRadius * aspect;
+    }
+    else {
+        projection.halfHeight = paddedRadius / aspect;
+        projection.halfWidth = paddedRadius;
+    }
+}
+//# sourceMappingURL=framing.js.map

package/dist/framing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framing.js","sourceRoot":"","sources":["../src/framing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AASvC,qGAAqG;AACrG,+FAA+F;AAC/F,kGAAkG;AAClG,oGAAoG;AACpG,6FAA6F;AAC7F,MAAM,UAAU,kCAAkC,CAChD,UAAiC,EACjC,UAAsB,EACtB,MAAoC,EACpC,MAAc,EACd,OAAO,GAAG,CAAC;IAEX,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAE3E,IAAI,UAAU,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,mCAAmC,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACjG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7C,UAAU,CAAC,YAAY,GAAG,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAC5F,CAAC;SAAM,CAAC;QACN,sCAAsC,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACrF,CAAC;IAED,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACtC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACtC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iGAAiG;AACjG,gGAAgG;AAChG,qDAAqD;AACrD,MAAM,UAAU,mCAAmC,CACjD,UAA2C,EAC3C,MAAc,EACd,MAAc,EACd,OAAO,GAAG,CAAC;IAEX,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;IACtC,MAAM,eAAe,GAAG,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC;IAC9C,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,GAAG,MAAM,CAAC,CAAC;IACxE,OAAO,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,mGAAmG;AACnG,sFAAsF;AACtF,MAAM,UAAU,sCAAsC,CACpD,UAAkC,EAClC,MAAc,EACd,MAAc,EACd,OAAO,GAAG,CAAC;IAEX,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;IACtC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,UAAU,CAAC,UAAU,GAAG,YAAY,CAAC;QACrC,UAAU,CAAC,SAAS,GAAG,YAAY,GAAG,MAAM,CAAC;IAC/C,CAAC;SAAM,CAAC;QACN,UAAU,CAAC,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC;QAC9C,UAAU,CAAC,SAAS,GAAG,YAAY,CAAC;IACtC,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './flyCameraController';
 export * from './follow';
+export * from './framing';
 export * from './orbitCameraController';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,UAAU,CAAC;AACzB,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './flyCameraController';
 export * from './follow';
+export * from './framing';
 export * from './orbitCameraController';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,UAAU,CAAC;AACzB,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,yBAAyB,CAAC"}

package/dist/orbitCameraController.d.ts

@@ -1,7 +1,12 @@
 import type { Camera3D, OrbitCameraController, OrbitCameraControllerOptions } from '@flighthq/types';
+export declare function cloneOrbitCameraController(source: Readonly<OrbitCameraController>): OrbitCameraController;
+export declare function copyOrbitCameraController(out: OrbitCameraController, source: Readonly<OrbitCameraController>): void;
 export declare function createOrbitCameraController(options?: Readonly<OrbitCameraControllerOptions>): OrbitCameraController;
 export declare function dollyCameraController(controller: OrbitCameraController, deltaDistance: number): void;
 export declare function orbitCameraController(controller: OrbitCameraController, deltaAzimuth: number, deltaPolar: number): void;
 export declare function panCameraController(controller: OrbitCameraController, deltaRight: number, deltaUp: number): void;
+export declare function panOrbitCameraControllerInViewPlane(controller: OrbitCameraController, deltaRight: number, deltaUp: number): void;
+export declare function resetOrbitCameraController(controller: OrbitCameraController, options?: Readonly<OrbitCameraControllerOptions>): void;
+export declare function snapOrbitCameraController(controller: OrbitCameraController): void;
 export declare function updateOrbitCameraController(controller: OrbitCameraController, camera: Camera3D, deltaTime: number): void;
 //# sourceMappingURL=orbitCameraController.d.ts.map

package/dist/orbitCameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orbitCameraController.d.ts","sourceRoot":"","sources":["../src/orbitCameraController.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAMrG,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,4BAA4B,CAAC,GAAG,qBAAqB,CAmBnH;AAID,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAMpG;AAKD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EACjC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,IAAI,CAGN;AAMD,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAOhH;AAOD,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAuBN"}
+{"version":3,"file":"orbitCameraController.d.ts","sourceRoot":"","sources":["../src/orbitCameraController.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAGrG,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAIzG;AAID,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,qBAAqB,EAAE,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,IAAI,CAenH;AAMD,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,4BAA4B,CAAC,GAAG,qBAAqB,CAmBnH;AAID,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAMpG;AAKD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EACjC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,IAAI,CAGN;AAMD,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAOhH;AAID,wBAAgB,mCAAmC,CACjD,UAAU,EAAE,qBAAqB,EACjC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,IAAI,CASN;AAID,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,qBAAqB,EACjC,OAAO,CAAC,EAAE,QAAQ,CAAC,4BAA4B,CAAC,GAC/C,IAAI,CAmBN;AAGD,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAIjF;AAOD,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAwBN"}

package/dist/orbitCameraController.js

@@ -1,6 +1,31 @@
 import { setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
+import { createEntity } from '@flighthq/entity';
 import { createVector3 } from '@flighthq/geometry';
-import { clamp, damp } from '@flighthq/math';
+import { clamp, damp, deltaAngle } from '@flighthq/math';
+// Allocates an independent Entity containing the same controller value state.
+export function cloneOrbitCameraController(source) {
+    const clone = createOrbitCameraController();
+    copyOrbitCameraController(clone, source);
+    return clone;
+}
+// Copies all controller state without sharing its mutable target. Entity runtime/binding state is
+// deliberately left on `out`; this is a value-state operation, not an ownership transfer.
+export function copyOrbitCameraController(out, source) {
+    out.azimuth = source.azimuth;
+    out.distance = source.distance;
+    out.goalAzimuth = source.goalAzimuth;
+    out.goalDistance = source.goalDistance;
+    out.goalPolar = source.goalPolar;
+    out.maxDistance = source.maxDistance;
+    out.maxPolar = source.maxPolar;
+    out.minDistance = source.minDistance;
+    out.minPolar = source.minPolar;
+    out.polar = source.polar;
+    out.smoothTime = source.smoothTime;
+    out.target.x = source.target.x;
+    out.target.y = source.target.y;
+    out.target.z = source.target.z;
+}
 // Allocates an orbit controller. `target` defaults to the origin, `distance` to 10, angles to 0;
 // `polar` limits default to just inside ±90° so the look-at up vector never degenerates, `distance`
 // to (0.01, +∞), and `smoothTime` to 0 (no damping — the camera snaps to the goal each update). The
@@ -10,7 +35,7 @@ export function createOrbitCameraController(options) {
     const polar = options?.polar ?? 0;
     const distance = options?.distance ?? 10;
     const target = options?.target;
-    return {
+    return createEntity({
         azimuth,
         distance,
         goalAzimuth: azimuth,
@@ -23,7 +48,7 @@ export function createOrbitCameraController(options) {
         polar,
         smoothTime: options?.smoothTime ?? 0,
         target: createVector3(target?.x ?? 0, target?.y ?? 0, target?.z ?? 0),
-    };
+    });
 }
 // Moves the goal distance (dolly / zoom) by `deltaDistance`, clamped to [minDistance, maxDistance].
 // Negative moves the eye toward the target.
@@ -37,8 +62,8 @@ export function orbitCameraController(controller, deltaAzimuth, deltaPolar) {
     controller.goalAzimuth += deltaAzimuth;
     controller.goalPolar = clamp(controller.goalPolar + deltaPolar, controller.minPolar, controller.maxPolar);
 }
-// Slides the orbit `target` in the view plane: `deltaRight` along the camera's horizontal right axis
-// (at the current goal azimuth), `deltaUp` along world-up. Because the eye is derived from the target
+// Slides the orbit `target` in a world-up plane: `deltaRight` along the camera's horizontal right axis
+// (at the current goal azimuth), `deltaUp` along world Y. Because the eye is derived from the target
 // each update, panning the target pans the whole view. Reads the target into locals before writing so
 // aliasing is safe.
 export function panCameraController(controller, deltaRight, deltaUp) {
@@ -49,6 +74,46 @@ export function panCameraController(controller, deltaRight, deltaUp) {
     target.y += deltaUp;
     target.z += -sinAzimuth * deltaRight;
 }
+// Slides the orbit target in the actual camera view plane. Unlike `panCameraController`, `deltaUp`
+// follows screen-up at the goal polar angle, so it can change all three target coordinates.
+export function panOrbitCameraControllerInViewPlane(controller, deltaRight, deltaUp) {
+    const cosAzimuth = Math.cos(controller.goalAzimuth);
+    const sinAzimuth = Math.sin(controller.goalAzimuth);
+    const cosPolar = Math.cos(controller.goalPolar);
+    const sinPolar = Math.sin(controller.goalPolar);
+    const target = controller.target;
+    target.x += cosAzimuth * deltaRight - sinAzimuth * sinPolar * deltaUp;
+    target.y += cosPolar * deltaUp;
+    target.z += -sinAzimuth * deltaRight - cosAzimuth * sinPolar * deltaUp;
+}
+// Restores the controller to constructor defaults or the supplied seed. Current and goal spherical
+// coordinates are synchronized, which makes this suitable for scene changes without an eased tail.
+export function resetOrbitCameraController(controller, options) {
+    const azimuth = options?.azimuth ?? 0;
+    const polar = options?.polar ?? 0;
+    const distance = options?.distance ?? 10;
+    const target = options?.target;
+    controller.azimuth = azimuth;
+    controller.distance = distance;
+    controller.goalAzimuth = azimuth;
+    controller.goalDistance = distance;
+    controller.goalPolar = polar;
+    controller.maxDistance = options?.maxDistance ?? Number.POSITIVE_INFINITY;
+    controller.maxPolar = options?.maxPolar ?? DEFAULT_MAX_POLAR;
+    controller.minDistance = options?.minDistance ?? DEFAULT_MIN_DISTANCE;
+    controller.minPolar = options?.minPolar ?? DEFAULT_MIN_POLAR;
+    controller.polar = polar;
+    controller.smoothTime = options?.smoothTime ?? 0;
+    controller.target.x = target?.x ?? 0;
+    controller.target.y = target?.y ?? 0;
+    controller.target.z = target?.z ?? 0;
+}
+// Snaps current spherical state to the clamped goal without writing a camera.
+export function snapOrbitCameraController(controller) {
+    controller.azimuth = controller.goalAzimuth;
+    controller.distance = clamp(controller.goalDistance, controller.minDistance, controller.maxDistance);
+    controller.polar = clamp(controller.goalPolar, controller.minPolar, controller.maxPolar);
+}
 // Advances the controller one step and writes the resulting view into `camera` (in place). Eases the
 // current azimuth/polar/distance toward their clamped goals with `@flighthq/math` `damp`
 // (frame-rate independent; `smoothTime` <= 0 or `deltaTime` <= 0 snaps), places the eye on the sphere
@@ -59,7 +124,8 @@ export function updateOrbitCameraController(controller, camera, deltaTime) {
     const goalDistance = clamp(controller.goalDistance, controller.minDistance, controller.maxDistance);
     if (controller.smoothTime > 0 && deltaTime > 0) {
         const lambda = 1 / controller.smoothTime;
-        controller.azimuth = damp(controller.azimuth, controller.goalAzimuth, lambda, deltaTime);
+        const nearestGoalAzimuth = controller.azimuth + deltaAngle(controller.azimuth, controller.goalAzimuth);
+        controller.azimuth = damp(controller.azimuth, nearestGoalAzimuth, lambda, deltaTime);
         controller.polar = damp(controller.polar, goalPolar, lambda, deltaTime);
         controller.distance = damp(controller.distance, goalDistance, lambda, deltaTime);
     }

package/dist/orbitCameraController.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/camera-controls",
-  "version": "0.2.1-next.451.d9a4a4e",
+  "version": "0.2.1-next.530.a223ca9",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -32,14 +32,15 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/camera": "0.2.1-next.451.d9a4a4e",
-    "@flighthq/geometry": "0.2.1-next.451.d9a4a4e",
-    "@flighthq/math": "0.2.1-next.451.d9a4a4e",
-    "@flighthq/types": "0.2.1-next.451.d9a4a4e"
+    "@flighthq/camera": "0.2.1-next.530.a223ca9",
+    "@flighthq/entity": "0.2.1-next.530.a223ca9",
+    "@flighthq/geometry": "0.2.1-next.530.a223ca9",
+    "@flighthq/math": "0.2.1-next.530.a223ca9",
+    "@flighthq/types": "0.2.1-next.530.a223ca9"
   },
   "devDependencies": {
     "typescript": "^5.3.0"
   },
-  "description": "Subjective camera controllers: 2D follow and 3D orbit / fly over the pure camera",
+  "description": "Input-agnostic 2D follow and 3D orbit / fly camera-control primitives",
   "sideEffects": false
 }

package/src/flyCameraController.test.ts

@@ -1,11 +1,16 @@
 import { createCamera3D, createPerspectiveProjection, setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
 import { createVector3 } from '@flighthq/geometry';
+import { EntityRuntimeKey } from '@flighthq/types';
 import { describe, expect, it } from 'vitest';
 
 import {
+  cloneFlyCameraController,
+  copyFlyCameraController,
   createFlyCameraController,
   lookFlyCameraController,
   moveFlyCameraController,
+  resetFlyCameraController,
+  snapFlyCameraController,
   updateFlyCameraController,
 } from './flyCameraController';
 
@@ -13,6 +18,32 @@ function testCamera() {
   return createCamera3D({ far: 100, near: 0.1, projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }) });
 }
 
+describe('cloneFlyCameraController', () => {
+  it('creates an independent Entity with the same value state', () => {
+    const source = createFlyCameraController({ pitch: 0.2, position: createVector3(1, 2, 3), yaw: 0.4 });
+    const clone = cloneFlyCameraController(source);
+    expect(clone).toMatchObject({ pitch: 0.2, yaw: 0.4 });
+    expect(EntityRuntimeKey in clone).toBe(true);
+    expect(clone.position).not.toBe(source.position);
+    clone.position.x = 10;
+    expect(source.position.x).toBe(1);
+  });
+});
+
+describe('copyFlyCameraController', () => {
+  it('copies value state without sharing position or replacing runtime state', () => {
+    const source = createFlyCameraController({ pitch: 0.2, position: createVector3(1, 2, 3), yaw: 0.4 });
+    const out = createFlyCameraController();
+    const runtime = { binding: null };
+    out[EntityRuntimeKey] = runtime;
+    copyFlyCameraController(out, source);
+
+    expect(out).toMatchObject({ pitch: 0.2, yaw: 0.4 });
+    expect(out[EntityRuntimeKey]).toBe(runtime);
+    expect(out.position).not.toBe(source.position);
+  });
+});
+
 describe('createFlyCameraController', () => {
   it('applies documented defaults with current equal to goal', () => {
     const c = createFlyCameraController();
@@ -28,6 +59,10 @@ describe('createFlyCameraController', () => {
     expect(c.yaw).toBe(0.5);
     expect(c.position.z).toBe(3);
   });
+
+  it('produces an Entity', () => {
+    expect(EntityRuntimeKey in createFlyCameraController()).toBe(true);
+  });
 });
 
 describe('lookFlyCameraController', () => {
@@ -49,6 +84,26 @@ describe('moveFlyCameraController', () => {
   });
 });
 
+describe('resetFlyCameraController', () => {
+  it('resets all coupled state from a seed', () => {
+    const c = createFlyCameraController({ position: createVector3(1, 2, 3), yaw: 1 });
+    resetFlyCameraController(c, { maxPitch: 0.5, pitch: 0.25, position: createVector3(4, 5, 6), yaw: -1 });
+    expect(c).toMatchObject({ goalPitch: 0.25, goalYaw: -1, pitch: 0.25, yaw: -1 });
+    expect(c.position).toMatchObject({ x: 4, y: 5, z: 6 });
+  });
+});
+
+describe('snapFlyCameraController', () => {
+  it('snaps current angles to clamped goals', () => {
+    const c = createFlyCameraController({ maxPitch: 0.5 });
+    c.goalPitch = 2;
+    c.goalYaw = 3;
+    snapFlyCameraController(c);
+    expect(c.pitch).toBe(0.5);
+    expect(c.yaw).toBe(3);
+  });
+});
+
 describe('updateFlyCameraController', () => {
   it('snaps to the goal when smoothTime is 0 and writes the look-at view', () => {
     const c = createFlyCameraController({ position: createVector3(0, 0, 5) }); // yaw/pitch 0 => looks toward -Z
@@ -68,4 +123,12 @@ describe('updateFlyCameraController', () => {
     expect(c.yaw).toBeGreaterThan(0);
     expect(c.yaw).toBeLessThan(1);
   });
+
+  it('takes the shortest arc across the wrapped yaw seam', () => {
+    const c = createFlyCameraController({ smoothTime: 0.5, yaw: Math.PI - 0.05 });
+    c.goalYaw = -Math.PI + 0.05;
+    updateFlyCameraController(c, testCamera(), 0.016);
+    expect(c.yaw).toBeGreaterThan(Math.PI - 0.05);
+    expect(c.yaw).toBeLessThan(Math.PI + 0.05);
+  });
 });

package/src/framing.test.ts

@@ -0,0 +1,65 @@
+import { createOrthographicProjection, createPerspectiveProjection } from '@flighthq/camera';
+import { createBoundingSphere } from '@flighthq/geometry';
+import { describe, expect, it } from 'vitest';
+
+import {
+  frameOrbitCameraControllerToSphere,
+  getPerspectiveFrameDistanceToSphere,
+  setOrthographicProjectionFrameToSphere,
+} from './framing';
+import { createOrbitCameraController } from './orbitCameraController';
+
+describe('frameOrbitCameraControllerToSphere', () => {
+  it('targets the center and changes only goal distance for perspective', () => {
+    const controller = createOrbitCameraController({ distance: 10 });
+    const projection = createPerspectiveProjection({ aspect: 1, fovY: Math.PI / 2 });
+    const sphere = createBoundingSphere(1, 2, 3, 2);
+    expect(frameOrbitCameraControllerToSphere(controller, projection, sphere, 1)).toBe(true);
+    expect(controller.target).toMatchObject({ x: 1, y: 2, z: 3 });
+    expect(controller.distance).toBe(10);
+    expect(controller.goalDistance).toBeCloseTo(2 / Math.sin(Math.PI / 4));
+  });
+
+  it('targets the center and changes only projection extent for orthographic', () => {
+    const controller = createOrbitCameraController({ distance: 10 });
+    const projection = createOrthographicProjection({ halfHeight: 1, halfWidth: 1 });
+    const sphere = createBoundingSphere(1, 2, 3, 2);
+    expect(frameOrbitCameraControllerToSphere(controller, projection, sphere, 2)).toBe(true);
+    expect(controller.target).toMatchObject({ x: 1, y: 2, z: 3 });
+    expect(controller.goalDistance).toBe(10);
+    expect(projection).toMatchObject({ halfHeight: 2, halfWidth: 4 });
+  });
+
+  it('does not mutate for empty spheres or invalid viewport inputs', () => {
+    const controller = createOrbitCameraController({ target: { x: 1, y: 2, z: 3 } });
+    const projection = createPerspectiveProjection({ aspect: 1, fovY: Math.PI / 2 });
+    expect(frameOrbitCameraControllerToSphere(controller, projection, createBoundingSphere(), 1)).toBe(false);
+    expect(frameOrbitCameraControllerToSphere(controller, projection, createBoundingSphere(0, 0, 0, 2), 0)).toBe(false);
+    expect(controller.target).toMatchObject({ x: 1, y: 2, z: 3 });
+  });
+});
+
+describe('getPerspectiveFrameDistanceToSphere', () => {
+  it('uses the limiting vertical field for a wide viewport', () => {
+    const projection = createPerspectiveProjection({ aspect: 2, fovY: Math.PI / 2 });
+    expect(getPerspectiveFrameDistanceToSphere(projection, 2, 2)).toBeCloseTo(2 / Math.sin(Math.PI / 4));
+  });
+
+  it('uses the limiting horizontal field for a tall viewport', () => {
+    const projection = createPerspectiveProjection({ aspect: 0.5, fovY: Math.PI / 2 });
+    const horizontalHalfFov = Math.atan(0.5);
+    expect(getPerspectiveFrameDistanceToSphere(projection, 2, 0.5)).toBeCloseTo(2 / Math.sin(horizontalHalfFov));
+  });
+});
+
+describe('setOrthographicProjectionFrameToSphere', () => {
+  it('preserves wide and tall viewport aspect while containing the sphere', () => {
+    const wide = createOrthographicProjection({ halfHeight: 1, halfWidth: 1 });
+    setOrthographicProjectionFrameToSphere(wide, 2, 2, 1.5);
+    expect(wide).toMatchObject({ halfHeight: 3, halfWidth: 6 });
+
+    const tall = createOrthographicProjection({ halfHeight: 1, halfWidth: 1 });
+    setOrthographicProjectionFrameToSphere(tall, 2, 0.5, 1.5);
+    expect(tall).toMatchObject({ halfHeight: 6, halfWidth: 3 });
+  });
+});

package/src/orbitCameraController.test.ts

@@ -1,12 +1,18 @@
 import { createCamera3D, createPerspectiveProjection, setCamera3DViewMatrix4FromLookAt } from '@flighthq/camera';
-import { createMatrix4, createVector3 } from '@flighthq/geometry';
+import { createVector3 } from '@flighthq/geometry';
+import { EntityRuntimeKey } from '@flighthq/types';
 import { describe, expect, it } from 'vitest';
 
 import {
+  cloneOrbitCameraController,
+  copyOrbitCameraController,
   createOrbitCameraController,
   dollyCameraController,
   orbitCameraController,
   panCameraController,
+  panOrbitCameraControllerInViewPlane,
+  resetOrbitCameraController,
+  snapOrbitCameraController,
   updateOrbitCameraController,
 } from './orbitCameraController';
 
@@ -14,6 +20,32 @@ function testCamera() {
   return createCamera3D({ far: 100, near: 0.1, projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }) });
 }
 
+describe('cloneOrbitCameraController', () => {
+  it('creates an independent Entity with the same value state', () => {
+    const source = createOrbitCameraController({ azimuth: 0.2, distance: 4, target: createVector3(1, 2, 3) });
+    const clone = cloneOrbitCameraController(source);
+    expect(clone).toMatchObject({ azimuth: 0.2, distance: 4 });
+    expect(EntityRuntimeKey in clone).toBe(true);
+    expect(clone.target).not.toBe(source.target);
+    clone.target.x = 10;
+    expect(source.target.x).toBe(1);
+  });
+});
+
+describe('copyOrbitCameraController', () => {
+  it('copies value state without sharing target or replacing runtime state', () => {
+    const source = createOrbitCameraController({ azimuth: 0.2, distance: 4, target: createVector3(1, 2, 3) });
+    const out = createOrbitCameraController();
+    const runtime = { binding: null };
+    out[EntityRuntimeKey] = runtime;
+    copyOrbitCameraController(out, source);
+
+    expect(out).toMatchObject({ azimuth: 0.2, distance: 4 });
+    expect(out[EntityRuntimeKey]).toBe(runtime);
+    expect(out.target).not.toBe(source.target);
+  });
+});
+
 describe('createOrbitCameraController', () => {
   it('applies documented defaults with current equal to goal', () => {
     const c = createOrbitCameraController();
@@ -32,6 +64,10 @@ describe('createOrbitCameraController', () => {
     expect(c.target.x).toBe(1);
     expect(c.target.z).toBe(3);
   });
+
+  it('produces an Entity', () => {
+    expect(EntityRuntimeKey in createOrbitCameraController()).toBe(true);
+  });
 });
 
 describe('dollyCameraController', () => {
@@ -65,6 +101,43 @@ describe('panCameraController', () => {
   });
 });
 
+describe('panOrbitCameraControllerInViewPlane', () => {
+  it('follows screen-up at nonzero polar', () => {
+    const c = createOrbitCameraController({ polar: Math.PI / 4 });
+    panOrbitCameraControllerInViewPlane(c, 0, 2);
+    expect(c.target.x).toBeCloseTo(0);
+    expect(c.target.y).toBeCloseTo(Math.SQRT2);
+    expect(c.target.z).toBeCloseTo(-Math.SQRT2);
+  });
+});
+
+describe('resetOrbitCameraController', () => {
+  it('resets all coupled state from a seed', () => {
+    const c = createOrbitCameraController({ target: createVector3(1, 2, 3) });
+    resetOrbitCameraController(c, {
+      azimuth: 1,
+      distance: 4,
+      maxDistance: 6,
+      maxPolar: 0.5,
+      polar: 0.25,
+      target: createVector3(4, 5, 6),
+    });
+    expect(c).toMatchObject({ azimuth: 1, goalAzimuth: 1, distance: 4, goalDistance: 4, polar: 0.25 });
+    expect(c.target).toMatchObject({ x: 4, y: 5, z: 6 });
+  });
+});
+
+describe('snapOrbitCameraController', () => {
+  it('snaps current values to clamped goals', () => {
+    const c = createOrbitCameraController({ maxDistance: 6, maxPolar: 0.5 });
+    c.goalDistance = 20;
+    c.goalPolar = 2;
+    snapOrbitCameraController(c);
+    expect(c.distance).toBe(6);
+    expect(c.polar).toBe(0.5);
+  });
+});
+
 describe('updateOrbitCameraController', () => {
   it('snaps to the goal when smoothTime is 0 and writes the look-at view', () => {
     const c = createOrbitCameraController({ distance: 10 }); // azimuth 0, polar 0 => eye (0,0,10)
@@ -84,4 +157,12 @@ describe('updateOrbitCameraController', () => {
     expect(c.azimuth).toBeGreaterThan(0);
     expect(c.azimuth).toBeLessThan(1); // has not reached the goal in one small step
   });
+
+  it('takes the shortest arc across the wrapped azimuth seam', () => {
+    const c = createOrbitCameraController({ azimuth: Math.PI - 0.05, smoothTime: 0.5 });
+    c.goalAzimuth = -Math.PI + 0.05;
+    updateOrbitCameraController(c, testCamera(), 0.016);
+    expect(c.azimuth).toBeGreaterThan(Math.PI - 0.05);
+    expect(c.azimuth).toBeLessThan(Math.PI + 0.05);
+  });
 });