@faeyumbrea/lib-camera-api-types 1.14.1 → 1.14.2

package/api.d.ts

@@ -1,5 +1,5 @@
-import type { CameraView3D } from './camera-3d.js';
-import type { LocalConsumer } from './controller.js';
+import type { Camera3DStatus, CameraView3D } from './camera-3d.js';
+import type { CameraController, LocalConsumer } from './controller.js';
 import type { CameraBounds, FrameOptions } from './framing.js';
 import type { CameraPosition } from './movement.js';
 import type { ConsumerOptions } from './ownership.js';
@@ -11,6 +11,12 @@ export interface ModuleApi {
     set3DRemote: RemoteCamera['set3D'];
     observeUser: RemoteCamera['watch'];
     followUser: RemoteCamera['followUser'];
+    /** Observe a user’s native 3D viewport without taking camera ownership. */
+    observeUser3D: RemoteCamera['watch3D'];
+    /** Copy a user’s native 3D view while holding a libCamera claim. */
+    followUser3D: RemoteCamera['followUser3D'];
+    /** Fit the current scene using a registered consumer's camera ownership and movement options. */
+    fitScene: CameraController['fitScene'];
     /** Compute views without taking ownership or moving the camera. */
     frame: (bounds: readonly CameraBounds[], options?: FrameOptions) => CameraPosition | undefined;
     frameTokens: (tokenIds: readonly string[], options?: FrameOptions) => CameraPosition | undefined;
@@ -20,6 +26,8 @@ export interface ModuleApi {
     read: () => Readonly<CameraPosition> | undefined;
     /** Native 3D position and look-at target; absent unless 3D Canvas is active and ready. */
     read3D: () => Readonly<CameraView3D> | undefined;
+    /** Current 3D availability without inspecting the adapter or moving the camera. */
+    get3DStatus: () => Camera3DStatus;
     tokenPosition: (tokenId: string) => Readonly<{
         x: number;
         y: number;

package/camera-3d.d.ts

@@ -9,6 +9,8 @@ export interface CameraView3D {
     position: Readonly<Vector3D>;
     target: Readonly<Vector3D>;
 }
+/** Availability of native 3D camera control, reported to consuming modules. */
+export type Camera3DStatus = 'inactive' | 'unavailable' | 'unsupported-mode' | 'ready';
 export type CameraResult3D = {
     status: 'completed';
     view: Readonly<CameraView3D>;
@@ -50,6 +52,8 @@ export declare class Camera3D {
     readonly getCanvas: () => Canvas3D | undefined;
     constructor(getCanvas: () => Canvas3D | undefined);
     read(): Readonly<CameraView3D> | undefined;
+    /** Reports whether 3D Canvas is inactive, loading, in an unsupported mode or controllable. */
+    status(): Camera3DStatus;
     availability(): 'unavailable' | 'unsupported-mode' | undefined;
     /**
      * Immediate write through native orbit controls, which may constrain the result.

package/controller.d.ts

@@ -6,6 +6,8 @@ import { CameraCoordinator } from './ownership.js';
 export interface CameraSession extends CameraClaim {
     /** Replace this claim's current movement, continuing from the actual view. */
     retarget: (options: MoveOptions, signal?: AbortSignal) => Promise<MovementResult>;
+    /** Fit the full scene through this session, replacing its current movement. */
+    fitScene: (options?: Pick<MoveOptions, 'duration' | 'easing' | 'level' | 'bounds' | 'lockInput'>, signal?: AbortSignal) => Promise<MovementResult>;
     set3D: (view: CameraView3D) => CameraResult3D;
     move: (options: MoveOptions, signal?: AbortSignal) => Promise<MovementResult>;
 }
@@ -44,6 +46,8 @@ export declare class CameraController {
     readonly consumers: Map<string, LocalConsumer>;
     constructor(adapter: CameraAdapter, getUserId: () => string | undefined, camera3D?: Camera3D | undefined);
     read(): Readonly<CameraPosition> | undefined;
+    /** Fit the current scene through a registered consumer's normal ownership and movement checks. */
+    fitScene(consumerId: string, options?: Pick<MoveOptions, 'duration' | 'easing' | 'level' | 'bounds' | 'lockInput'>, signal?: AbortSignal): ReturnType<LocalConsumer['move']>;
     register(options: ConsumerOptions): LocalConsumer;
     releaseLocal(): void;
     panic(): void;

package/movement.d.ts

@@ -1,4 +1,4 @@
-import type { CameraBounds } from './framing.js';
+import type { CameraBounds, FrameOptions } from './framing.js';
 import type { CameraClaim, ReleaseReason } from './ownership.js';
 export interface CameraPosition {
     x: number;
@@ -31,6 +31,8 @@ export type MovementResult = {
 /** Boundary to Foundry. Adapters must stop writing synchronously when aborted. */
 export interface CameraAdapter {
     read: () => Readonly<CameraPosition> | undefined;
+    /** Compute the view fitting the current scene without moving the camera. */
+    frameScene?: (options?: FrameOptions) => CameraPosition | undefined;
     pan: (position: CameraPosition) => void;
     animate: (position: CameraPosition, options: Required<Pick<MoveOptions, 'duration' | 'easing'>>, signal: AbortSignal) => Promise<boolean>;
     lockInput: () => () => void;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@faeyumbrea/lib-camera-api-types",
-  "version": "1.14.1",
-  "description": "Public API declarations for libCamera 1.14.1 on Foundry 14.",
+  "version": "1.14.2",
+  "description": "Public API declarations for libCamera 1.14.2 on Foundry 14.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/FaeyUmbrea/foundry-lib-camera.git"
   },
-  "homepage": "https://docs.void.monster/lib-camera/public/1.14.1/dev/",
+  "homepage": "https://docs.void.monster/lib-camera/public/1.14.2/dev/",
   "types": "./public-api.d.ts",
   "exports": {
     ".": {

package/public-api.d.ts

@@ -1,10 +1,10 @@
 export type { ModuleApi } from './api.js';
-export type { CameraResult3D, CameraView3D, Vector3D } from './camera-3d.js';
+export type { Camera3DStatus, CameraResult3D, CameraView3D, Vector3D } from './camera-3d.js';
 export type { CameraSession, LocalConsumer, SessionResult } from './controller.js';
 export type { CameraFollow } from './follow.js';
 export type { CameraBounds, FrameOptions, ViewDimensions } from './framing.js';
 export type { CameraPosition, MovementResult, MoveOptions } from './movement.js';
 export type { CameraClaim, CameraConsumer, ClaimResult, ClaimSnapshot, ConsumerOptions, ConsumerSnapshot, Diagnostic, PriorityOverride, RejectionReason, ReleaseReason, } from './ownership.js';
 export type { CameraCoordinator } from './ownership.js';
-export type { RemoteOptions, RemoteOutcome, RemoteUserResult, ViewportSample, ViewportSubscription } from './remote.js';
+export type { RemoteOptions, RemoteOutcome, RemoteUserResult, ViewportSample, ViewportSample3D, ViewportSubscription } from './remote.js';
 export type { TrackingMode } from './viewport-filter.js';

package/remote-3d-follow.d.ts

@@ -0,0 +1,5 @@
+import type { CameraSession } from './controller.js';
+import type { CameraFollow } from './follow.js';
+import type { ViewportSample3D, ViewportSubscription } from './remote.js';
+/** Copy native 3D samples from the current scene, releasing the claim and subscription on stop. */
+export declare function followRemote3D(session: CameraSession, subscribe: (callback: (sample: ViewportSample3D) => void) => ViewportSubscription, sceneId: () => string | undefined): CameraFollow;

package/remote.d.ts

@@ -21,6 +21,12 @@ export interface ViewportSample {
     sceneId: string;
     position: Readonly<CameraPosition>;
 }
+/** Native 3D view from a responding user on a particular scene. */
+export interface ViewportSample3D {
+    userId: string;
+    sceneId: string;
+    view: Readonly<CameraView3D> | null;
+}
 export interface ViewportSubscription {
     stop: () => void;
 }
@@ -33,6 +39,7 @@ export interface RemoteEnvironment {
     }[];
     sceneId: () => string | undefined;
     read: () => Readonly<CameraPosition> | undefined;
+    read3D?: () => Readonly<CameraView3D> | undefined;
     emit: (packet: object, recipients: string[]) => void;
 }
 /** Foundry supplies sender identity as the second socket callback argument. Never read it from payloads. */
@@ -44,8 +51,18 @@ export declare class RemoteCamera {
     move(consumer: string, targets: string | readonly string[], options: MoveOptions, remote?: RemoteOptions): Promise<RemoteUserResult[]>;
     set3D(consumer: string, targets: string | readonly string[], view: CameraView3D, remote?: RemoteOptions): Promise<RemoteUserResult[]>;
     watch(userId: string, callback: (sample: ViewportSample) => void, mode?: TrackingMode): ViewportSubscription;
-    /** Follow the latest responding session of a user on this scene; all sessions remain addressable together. */
-    followUser(consumerId: string, userId: string, options?: Pick<MoveOptions, 'duration' | 'easing' | 'bounds' | 'lockInput'>, mode?: TrackingMode): {
+    /** Subscribe to native 3D samples; sender identity is checked before delivering each sample. */
+    watch3D(userId: string, callback: (sample: ViewportSample3D) => void): ViewportSubscription;
+    /** Acquire a camera claim and copy a user's native 3D samples until stopped or preempted. */
+    followUser3D(consumerId: string, userId: string): {
+        ok: false;
+        reason: import("./ownership.js").RejectionReason | "unavailable";
+    } | {
+        ok: true;
+        follow: import("./follow.js").CameraFollow;
+    };
+    /** Follow the most recently changed viewport among the consumer-selected users on this scene. */
+    followUser(consumerId: string, userId: string | readonly string[], options?: Pick<MoveOptions, 'duration' | 'easing' | 'bounds' | 'lockInput'>, mode?: TrackingMode): {
         ok: true;
         follow: import("./follow.js").CameraFollow;
     } | {