@snaptrude/plugin-core 0.9.16 → 0.9.18-networks-20261016.1

package/src/api/core/camera/index.ts

@@ -1,667 +1,696 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { Vec3Components, Vec3Handle } from "../../../handles"
-
-/**
- * Camera controls.
- *
- * Position the viewport camera, snap it to a standard orthographic/isometric
- * view, and toggle between the 2D (plan) and 3D modelling modes — mirrors the
- * canvas view menu and the 2D/3D toggle. Like {@linkcode PluginZoomApi}, these
- * are transient VIEW-STATE changes: they are not model edits, so they are not
- * write-gated and are not undoable. Accessed via `snaptrude.core.camera`.
- *
- * Read and set the full camera pose (`getPose`/`setPose`), walk and turn it the
- * way the arrow keys do (`move`/`rotate`), and read or change the arrow-key
- * navigation settings (`getNavigationSettings`/`updateNavigationSettings`).
- * Positions are world coordinates in internal `babylon` units (1 unit =
- * 0.254 m, Y up); yaw is degrees clockwise from +z seen from above, pitch is
- * degrees above level.
- */
-export abstract class PluginCameraApi {
-  constructor() {}
-
-  /**
-   * Point the camera: place its eye at `eye` looking toward `target` (world
-   * coordinates, internal `babylon` units). View-state only — not undoable.
-   *
-   * @param eye - Camera position as a {@linkcode Vec3Handle}
-   * @param target - Point the camera looks at as a {@linkcode Vec3Handle}
-   * @returns `true` once the camera has been positioned.
-   *
-   * @examplePrompt Look at the model from above the north-east corner
-   * @examplePrompt Position the camera at (50, 30, 50) looking at the origin
-   * @examplePrompt Point the camera at the centre of the building from the side
-   * @examplePrompt Set the eye to this point and aim it at that point
-   *
-   * # Example
-   * ```ts
-   * const { vec3 } = snaptrude.core.math
-   * await snaptrude.core.camera.lookFrom(vec3.new(50, 30, 50), vec3.new(0, 0, 0))
-   * ```
-   */
-  public abstract lookFrom(
-    eye: Vec3Handle,
-    target: Vec3Handle,
-  ): PluginApiReturn<boolean>
-
-  /**
-   * Snap the camera to a standard view — the five orthographic elevations
-   * (`top` / `front` / `back` / `left` / `right`) or the 3D `iso` (isometric
-   * perspective) view. Mirrors the canvas view menu. View-state only — not
-   * undoable. The orthographic presets exit 2D mode first if needed.
-   *
-   * @param view - The standard view to snap to ({@linkcode PluginStandardView})
-   * @returns `true` once the view has been applied.
-   *
-   * @examplePrompt Switch to the top view
-   * @examplePrompt Show me the front elevation
-   * @examplePrompt Go to the isometric view
-   * @examplePrompt Look at the model from the left
-   * @examplePrompt Give me a plan view from the top
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.camera.setStandardView("top")
-   * ```
-   */
-  public abstract setStandardView(
-    view: PluginStandardView,
-  ): PluginApiReturn<boolean>
-
-  /**
-   * Get the current camera mode. Paired with {@linkcode PluginCameraApi.setMode}.
-   *
-   * @returns `"2d"` when the editor is in plan view, `"3d"` otherwise.
-   *
-   * @examplePrompt Am I in 2D or 3D?
-   * @examplePrompt What view mode is the editor in?
-   *
-   * # Example
-   * ```ts
-   * if ((await snaptrude.core.camera.getMode()) === "2d") {
-   *   await snaptrude.core.camera.setMode("3d")
-   * }
-   * ```
-   */
-  public abstract getMode(): PluginApiReturn<PluginCameraMode>
-
-  /**
-   * Toggle the modelling mode between `2d` (plan) and `3d`. Mirrors the canvas
-   * 2D/3D toggle: `3d` enters the isometric perspective view, `2d` drops to the
-   * orthographic plan of the active storey. View-state only — not undoable.
-   *
-   * @param mode - `"2d"` or `"3d"` ({@linkcode PluginCameraMode})
-   * @returns `true` once the mode switch has been requested.
-   *
-   * @examplePrompt Switch to 3D view
-   * @examplePrompt Drop into 2D plan mode
-   * @examplePrompt Go back to 3D
-   * @examplePrompt Show the floor plan in 2D
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.camera.setMode("3d")
-   * ```
-   */
-  public abstract setMode(mode: PluginCameraMode): PluginApiReturn<boolean>
-
-  /**
-   * Read the camera's current projection: `"perspective"` (the default 3D
-   * view) or `"orthographic"`. In 2D (plan) mode this always reports
-   * `"orthographic"` — a plan is an orthographic projection.
-   *
-   * @returns The current {@linkcode PluginCameraProjection}.
-   *
-   * @examplePrompt Is the camera in perspective or orthographic?
-   * @examplePrompt What projection is the 3D view using?
-   * @examplePrompt Check whether perspective is on
-   *
-   * # Example
-   * ```ts
-   * const projection = await snaptrude.core.camera.getProjection()
-   * console.log(projection) // "perspective" | "orthographic"
-   * ```
-   */
-  public abstract getProjection(): PluginApiReturn<PluginCameraProjection>
-
-  /**
-   * Switch the 3D camera between `"perspective"` and `"orthographic"`
-   * projection — the Perspective/Orthographic control in the Design tab's
-   * View Settings panel. Like {@linkcode PluginCameraApi.setMode}, this is a
-   * transient view-state change: not write-gated, not undoable.
-   *
-   * In 2D (plan) mode the canvas is always an orthographic plan:
-   * `"orthographic"` is accepted as a no-op, while `"perspective"` is
-   * rejected — switch to 3D first via `setMode("3d")`.
-   *
-   * @param projection - `"perspective"` or `"orthographic"` ({@linkcode PluginCameraProjection})
-   * @returns `true` once the projection has been applied.
-   *
-   * @examplePrompt Switch the camera to orthographic
-   * @examplePrompt Turn perspective off
-   * @examplePrompt Give me a perspective view of the model
-   * @examplePrompt Make the 3D view orthographic like an axonometric drawing
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.camera.setProjection("orthographic")
-   * const projection = await snaptrude.core.camera.getProjection() // "orthographic"
-   * ```
-   */
-  public abstract setProjection(
-    projection: PluginCameraProjection,
-  ): PluginApiReturn<boolean>
-
-  /**
-   * Zoom (fit) the camera to all geometry in the scene — the "zoom extents"
-   * action. View-state only — not undoable. Canonical home of the zoom-extents
-   * read (the deprecated `core.zoom.extents`).
-   *
-   * @returns `true` once the camera has been framed to the scene.
-   *
-   * @examplePrompt Zoom out so I can see the whole model
-   * @examplePrompt Fit everything in the view
-   * @examplePrompt Frame the entire building in the viewport
-   * @examplePrompt Do a zoom extents on the canvas
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.camera.zoomExtents()
-   * ```
-   */
-  public abstract zoomExtents(): PluginApiReturn<boolean>
-
-  /**
-   * Zoom (fit) the camera to the current selection. View-state only — not
-   * undoable. Canonical home of the zoom-to-selection read (the deprecated
-   * `core.zoom.selection`).
-   *
-   * @returns `true` if there was a selection to frame; `false` if nothing is
-   *   selected (no-op).
-   *
-   * @examplePrompt Zoom in on what I have selected
-   * @examplePrompt Frame the selected walls in the view
-   * @examplePrompt Focus the camera on my current selection
-   * @examplePrompt Fit the view to the selected room
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.camera.zoomSelection()
-   * ```
-   */
-  public abstract zoomSelection(): PluginApiReturn<boolean>
-
-  /**
-   * Read where the camera is and where it looks: the eye and target positions
-   * (world coordinates, internal `babylon` units), the view direction as yaw
-   * and pitch, the vertical field of view, the projection and the 2D/3D mode.
-   * Paired with {@linkcode PluginCameraApi.setPose}.
-   *
-   * @returns The current {@linkcode PluginCameraPose}.
-   * @throws PRECONDITION_FAILED when there is no active camera.
-   *
-   * @examplePrompt Where is the camera right now?
-   * @examplePrompt Remember this viewpoint so we can come back to it
-   * @examplePrompt Which way is the camera facing?
-   * @examplePrompt How high above the ground is the camera?
-   *
-   * # Example
-   * ```ts
-   * const pose = await snaptrude.core.camera.getPose()
-   * console.log(pose.eye, pose.yawInDegrees, pose.pitchInDegrees)
-   * ```
-   */
-  public abstract getPose(): PluginApiReturn<PluginCameraPose>
-
-  /**
-   * Place the camera, optionally easing there over `options.durationInSeconds`,
-   * and resolve once the new view has been drawn, so a capture that follows sees
-   * it without a fixed wait. `pose` is one of:
-   *
-   * - `{ eye, target }`: stand at `eye` looking at `target`, as
-   *   {@linkcode PluginCameraApi.lookFrom} does with handles;
-   * - `{ eye, yawInDegrees, pitchInDegrees }`: stand at `eye` looking along a
-   *   direction;
-   * - `{ standAt, yawInDegrees? }`: stand on the floor, stair, terrain or
-   *   ground at or below `standAt`, at the user's eye height above it (the `I`
-   *   key), facing `yawInDegrees` (the current yaw when omitted).
-   *
-   * Stops a playing walkthrough and switches from 2D plan view to 3D first.
-   * View-state only: not write-gated, not undoable.
-   *
-   * @param pose - Where to put the camera ({@linkcode PluginCameraPoseInput})
-   * @param options - `durationInSeconds`: ease over this long (0 to 10, default 0 jumps)
-   * @returns The camera's {@linkcode PluginCameraPose} once it has arrived.
-   * @throws PRECONDITION_FAILED when there is no active camera, while a
-   *   walkthrough export is recording, or when `standAt` lies below the ground
-   *   with nothing under it. VALIDATION when `eye` and `target` coincide or a
-   *   pitch is beyond ±89°.
-   *
-   * @examplePrompt Stand in the living room at eye level facing the window
-   * @examplePrompt Move the camera to (40, 12, 30) looking at the entrance
-   * @examplePrompt Fly the camera smoothly over to the courtyard
-   * @examplePrompt Put me back at the viewpoint we saved earlier
-   *
-   * # Example
-   * ```ts
-   * const { camera } = snaptrude.core
-   * await camera.setPose({ standAt: { x: 20, y: 0, z: 35 }, yawInDegrees: 90 })
-   * await camera.setPose(
-   *   { eye: { x: 60, y: 25, z: 60 }, target: { x: 0, y: 5, z: 0 } },
-   *   { durationInSeconds: 1.5 },
-   * )
-   * ```
-   */
-  public abstract setPose(
-    pose: PluginCameraPoseInput,
-    options?: PluginCameraSetPoseOptions,
-  ): PluginApiReturn<PluginCameraPose>
-
-  /**
-   * Walk or fly the camera by a displacement in its own frame: `forward` along
-   * the level view direction, `right` to its side and `up` vertically, in
-   * internal `babylon` units. The view direction does not change. With
-   * `options.followsFloor` the camera keeps its height above the floor as it
-   * goes, climbing and descending stairs and ramps the way the arrow keys do.
-   * Stops a playing walkthrough and switches from 2D plan view to 3D first.
-   * View-state only: not write-gated, not undoable.
-   *
-   * @param displacement - {@linkcode PluginCameraMoveDisplacement}; omitted components are 0
-   * @param options - `followsFloor` (default `false`) and `durationInSeconds` (0 to 10, default 0)
-   * @returns The camera's {@linkcode PluginCameraPose} after the move.
-   * @throws PRECONDITION_FAILED when there is no active camera, or while a
-   *   walkthrough export is recording.
-   *
-   * @examplePrompt Walk forward 3 metres
-   * @examplePrompt Step to the right a little
-   * @examplePrompt Walk up the stairs ahead
-   * @examplePrompt Raise the camera by 2 metres
-   *
-   * # Example
-   * ```ts
-   * const metre = 1 / 0.254
-   * await snaptrude.core.camera.move(
-   *   { forward: 3 * metre },
-   *   { followsFloor: true, durationInSeconds: 2 },
-   * )
-   * ```
-   */
-  public abstract move(
-    displacement: PluginCameraMoveDisplacement,
-    options?: PluginCameraMoveOptions,
-  ): PluginApiReturn<PluginCameraPose>
-
-  /**
-   * Turn the camera in place by signed angles: `yawInDegrees` to the right
-   * (clockwise seen from above) and `pitchInDegrees` up. The eye does not move;
-   * the resulting pitch is kept within ±89°. Stops a playing walkthrough and
-   * switches from 2D plan view to 3D first. View-state only: not write-gated,
-   * not undoable.
-   *
-   * @param yawInDegrees - Turn to the right by this much (negative turns left)
-   * @param pitchInDegrees - Tilt up by this much (negative tilts down; default 0)
-   * @param options - `durationInSeconds` (0 to 10, default 0)
-   * @returns The camera's {@linkcode PluginCameraPose} after turning.
-   * @throws PRECONDITION_FAILED when there is no active camera, or while a
-   *   walkthrough export is recording.
-   *
-   * @examplePrompt Turn around
-   * @examplePrompt Look 45 degrees to the left
-   * @examplePrompt Tilt the camera down a bit
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.camera.rotate(180, 0, { durationInSeconds: 1 })
-   * ```
-   */
-  public abstract rotate(
-    yawInDegrees: number,
-    pitchInDegrees?: number,
-    options?: PluginCameraRotateOptions,
-  ): PluginApiReturn<PluginCameraPose>
-
-  /**
-   * Read the arrow-key navigation settings: whether the arrow keys walk the
-   * camera, the eye height used by `setPose`'s `standAt` and by walkthroughs
-   * that follow the floor, the walking speed, and whether walking stops at
-   * walls. Paired with {@linkcode PluginCameraApi.updateNavigationSettings}.
-   *
-   * @returns The current {@linkcode PluginCameraNavigationSettings}.
-   *
-   * @examplePrompt Is arrow-key navigation on?
-   * @examplePrompt What eye height does the camera use?
-   *
-   * # Example
-   * ```ts
-   * const { isKeyboardNavigationEnabled } =
-   *   await snaptrude.core.camera.getNavigationSettings()
-   * ```
-   */
-  public abstract getNavigationSettings(): PluginApiReturn<PluginCameraNavigationSettings>
-
-  /**
-   * Change arrow-key navigation settings; only the fields given change.
-   * `isKeyboardNavigationEnabled` is the user's Project Settings switch and is
-   * saved on this device; the other settings last for the session.
-   * Write-gated: this changes the user's preferences, not just the view.
-   *
-   * @param patch - The settings to change ({@linkcode PluginCameraNavigationSettingsPatch})
-   * @returns The {@linkcode PluginCameraNavigationSettings} after the change.
-   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled.
-   *
-   * @examplePrompt Turn off arrow-key navigation
-   * @examplePrompt Use a 1.6 m eye height
-   * @examplePrompt Make walking stop at walls
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.camera.updateNavigationSettings({
-   *   eyeHeight: 1.6 / 0.254,
-   *   isCollisionEnabled: true,
-   * })
-   * ```
-   */
-  public abstract updateNavigationSettings(
-    patch: PluginCameraNavigationSettingsPatch,
-  ): PluginApiReturn<PluginCameraNavigationSettings>
-}
-
-/**
- * A standard camera view: the five orthographic elevations (`top`/`front`/
- * `back`/`left`/`right`) or the 3D isometric perspective (`iso`).
- */
-export const PluginStandardView = z.enum([
-  "top",
-  "front",
-  "back",
-  "left",
-  "right",
-  "iso",
-])
-export type PluginStandardView = z.infer<typeof PluginStandardView>
-
-/**
- * The modelling mode: `2d` (orthographic plan) or `3d` (isometric perspective).
- */
-export const PluginCameraMode = z.enum(["2d", "3d"])
-export type PluginCameraMode = z.infer<typeof PluginCameraMode>
-
-/**
- * The 3D camera projection: `perspective` (the default) or `orthographic` —
- * the Perspective/Orthographic control in the Design tab's View Settings panel.
- */
-export const PluginCameraProjection = z.enum(["perspective", "orthographic"])
-export type PluginCameraProjection = z.infer<typeof PluginCameraProjection>
-
-/**
- * Arguments for {@linkcode PluginCameraApi.lookFrom}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `eye` | {@linkcode Vec3Handle} | Camera position (world, `babylon` units) |
- * | `target` | {@linkcode Vec3Handle} | Point the camera looks at |
- */
-export const PluginCameraLookFromArgs = z.object({
-  eye: Vec3Handle,
-  target: Vec3Handle,
-})
-export type PluginCameraLookFromArgs = z.infer<typeof PluginCameraLookFromArgs>
-
-/**
- * Arguments for {@linkcode PluginCameraApi.setStandardView}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `view` | {@linkcode PluginStandardView} | The standard view to snap to |
- */
-export const PluginCameraSetStandardViewArgs = z.object({
-  view: PluginStandardView,
-})
-export type PluginCameraSetStandardViewArgs = z.infer<
-  typeof PluginCameraSetStandardViewArgs
->
-
-/**
- * Arguments for {@linkcode PluginCameraApi.setMode}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `mode` | {@linkcode PluginCameraMode} | `"2d"` or `"3d"` |
- */
-export const PluginCameraSetModeArgs = z.object({
-  mode: PluginCameraMode,
-})
-export type PluginCameraSetModeArgs = z.infer<typeof PluginCameraSetModeArgs>
-
-/**
- * Arguments for {@linkcode PluginCameraApi.setProjection}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `projection` | {@linkcode PluginCameraProjection} | `"perspective"` or `"orthographic"` |
- */
-export const PluginCameraSetProjectionArgs = z.object({
-  projection: PluginCameraProjection,
-})
-export type PluginCameraSetProjectionArgs = z.infer<
-  typeof PluginCameraSetProjectionArgs
->
-
-// Plain {x, y, z} record with finite components (the brepFromRevolution `axisOrigin` pattern).
-const FiniteVec3Components = z.object({
-  x: z.number().finite(),
-  y: z.number().finite(),
-  z: z.number().finite(),
-})
-
-/** Pitch is kept off the vertical, where yaw has no meaning. */
-const PitchInDegrees = z.number().finite().min(-89).max(89)
-
-/** How long a camera move eases for; 0 jumps. */
-const DurationInSeconds = z.number().finite().min(0).max(10)
-
-/**
- * The camera's pose — result of {@linkcode PluginCameraApi.getPose},
- * {@linkcode PluginCameraApi.setPose}, {@linkcode PluginCameraApi.move} and
- * {@linkcode PluginCameraApi.rotate}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `eye` | `{ x, y, z }` | Camera position (world, `babylon` units) |
- * | `target` | `{ x, y, z }` | Point the camera looks at |
- * | `yawInDegrees` | `number` | View direction, degrees clockwise from +z seen from above (-180 to 180) |
- * | `pitchInDegrees` | `number` | View direction, degrees above level (negative looks down) |
- * | `fieldOfViewInDegrees` | `number` | Vertical field of view |
- * | `projection` | {@linkcode PluginCameraProjection} | `"perspective"` or `"orthographic"` |
- * | `mode` | {@linkcode PluginCameraMode} | `"2d"` or `"3d"` |
- */
-export const PluginCameraPose = z.object({
-  eye: Vec3Components,
-  target: Vec3Components,
-  yawInDegrees: z.number(),
-  pitchInDegrees: z.number(),
-  fieldOfViewInDegrees: z.number(),
-  projection: PluginCameraProjection,
-  mode: PluginCameraMode,
-})
-export type PluginCameraPose = z.infer<typeof PluginCameraPose>
-
-/**
- * Where {@linkcode PluginCameraApi.setPose} puts the camera — exactly one of:
- *
- * | Shape | Meaning |
- * |---|---|
- * | `{ eye, target }` | Stand at `eye` looking at `target` |
- * | `{ eye, yawInDegrees, pitchInDegrees }` | Stand at `eye` looking along a direction (pitch within ±89°) |
- * | `{ standAt, yawInDegrees? }` | Stand at eye height on the floor, stair, terrain or ground at or below `standAt`, facing `yawInDegrees` (default: current yaw) |
- *
- * Points are plain `{ x, y, z }` world coordinates in `babylon` units.
- */
-export const PluginCameraPoseInput = z.union([
-  z
-    .object({ eye: FiniteVec3Components, target: FiniteVec3Components })
-    .strict(),
-  z
-    .object({
-      eye: FiniteVec3Components,
-      yawInDegrees: z.number().finite(),
-      pitchInDegrees: PitchInDegrees,
-    })
-    .strict(),
-  z
-    .object({
-      standAt: FiniteVec3Components,
-      yawInDegrees: z.number().finite().optional(),
-    })
-    .strict(),
-])
-export type PluginCameraPoseInput = z.infer<typeof PluginCameraPoseInput>
-
-/**
- * Options for {@linkcode PluginCameraApi.setPose}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `durationInSeconds` | `number \| undefined` | Ease to the pose over this long (0 to 10; default 0 jumps) |
- */
-export const PluginCameraSetPoseOptions = z
-  .object({ durationInSeconds: DurationInSeconds.optional() })
-  .strict()
-export type PluginCameraSetPoseOptions = z.infer<
-  typeof PluginCameraSetPoseOptions
->
-
-/**
- * Arguments for {@linkcode PluginCameraApi.setPose}.
- */
-export const PluginCameraSetPoseArgs = z.object({
-  pose: PluginCameraPoseInput,
-  options: PluginCameraSetPoseOptions.optional(),
-})
-export type PluginCameraSetPoseArgs = z.infer<typeof PluginCameraSetPoseArgs>
-
-/**
- * A displacement in the camera's own frame, for {@linkcode PluginCameraApi.move}
- * (`babylon` units; omitted components are 0).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `forward` | `number \| undefined` | Along the level view direction (negative walks back) |
- * | `right` | `number \| undefined` | To the camera's right (negative steps left) |
- * | `up` | `number \| undefined` | Vertically (negative descends) |
- */
-export const PluginCameraMoveDisplacement = z
-  .object({
-    forward: z.number().finite().optional(),
-    right: z.number().finite().optional(),
-    up: z.number().finite().optional(),
-  })
-  .strict()
-export type PluginCameraMoveDisplacement = z.infer<
-  typeof PluginCameraMoveDisplacement
->
-
-/**
- * Options for {@linkcode PluginCameraApi.move}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `followsFloor` | `boolean \| undefined` | Keep the height above the floor, climbing stairs and ramps (default `false`) |
- * | `durationInSeconds` | `number \| undefined` | Walk over this long (0 to 10; default 0 jumps) |
- */
-export const PluginCameraMoveOptions = z
-  .object({
-    followsFloor: z.boolean().optional(),
-    durationInSeconds: DurationInSeconds.optional(),
-  })
-  .strict()
-export type PluginCameraMoveOptions = z.infer<typeof PluginCameraMoveOptions>
-
-/**
- * Arguments for {@linkcode PluginCameraApi.move}.
- */
-export const PluginCameraMoveArgs = z.object({
-  displacement: PluginCameraMoveDisplacement,
-  options: PluginCameraMoveOptions.optional(),
-})
-export type PluginCameraMoveArgs = z.infer<typeof PluginCameraMoveArgs>
-
-/**
- * Options for {@linkcode PluginCameraApi.rotate}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `durationInSeconds` | `number \| undefined` | Turn over this long (0 to 10; default 0 jumps) |
- */
-export const PluginCameraRotateOptions = z
-  .object({ durationInSeconds: DurationInSeconds.optional() })
-  .strict()
-export type PluginCameraRotateOptions = z.infer<
-  typeof PluginCameraRotateOptions
->
-
-/**
- * Arguments for {@linkcode PluginCameraApi.rotate}.
- */
-export const PluginCameraRotateArgs = z.object({
-  yawInDegrees: z.number().finite(),
-  pitchInDegrees: z.number().finite().optional(),
-  options: PluginCameraRotateOptions.optional(),
-})
-export type PluginCameraRotateArgs = z.infer<typeof PluginCameraRotateArgs>
-
-/**
- * How fast the arrow keys walk: the Slow / Normal / Fast navigation setting.
- */
-export const PluginCameraWalkSpeed = z.enum(["slow", "normal", "fast"])
-export type PluginCameraWalkSpeed = z.infer<typeof PluginCameraWalkSpeed>
-
-/**
- * The arrow-key navigation settings — result of
- * {@linkcode PluginCameraApi.getNavigationSettings} and
- * {@linkcode PluginCameraApi.updateNavigationSettings}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `isKeyboardNavigationEnabled` | `boolean` | Whether the arrow keys walk the camera (Project Settings) |
- * | `eyeHeight` | `number` | Eye height above the floor, `babylon` units |
- * | `walkSpeed` | {@linkcode PluginCameraWalkSpeed} | Arrow-key walking speed |
- * | `isCollisionEnabled` | `boolean` | Whether walking stops at walls |
- */
-export const PluginCameraNavigationSettings = z.object({
-  isKeyboardNavigationEnabled: z.boolean(),
-  eyeHeight: z.number(),
-  walkSpeed: PluginCameraWalkSpeed,
-  isCollisionEnabled: z.boolean(),
-})
-export type PluginCameraNavigationSettings = z.infer<
-  typeof PluginCameraNavigationSettings
->
-
-/**
- * The settings to change in {@linkcode PluginCameraApi.updateNavigationSettings};
- * omitted fields keep their value. `eyeHeight` is in `babylon` units, between
- * 0.8 m and 2.5 m (3.15 to 9.84 units).
- */
-export const PluginCameraNavigationSettingsPatch = z
-  .object({
-    isKeyboardNavigationEnabled: z.boolean().optional(),
-    eyeHeight: z.number().finite().min(3.15).max(9.84).optional(),
-    walkSpeed: PluginCameraWalkSpeed.optional(),
-    isCollisionEnabled: z.boolean().optional(),
-  })
-  .strict()
-export type PluginCameraNavigationSettingsPatch = z.infer<
-  typeof PluginCameraNavigationSettingsPatch
->
-
-/**
- * Arguments for {@linkcode PluginCameraApi.updateNavigationSettings}.
- */
-export const PluginCameraUpdateNavigationSettingsArgs = z.object({
-  patch: PluginCameraNavigationSettingsPatch,
-})
-export type PluginCameraUpdateNavigationSettingsArgs = z.infer<
-  typeof PluginCameraUpdateNavigationSettingsArgs
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { Vec3Components, Vec3Handle } from "../../../handles"
+
+/**
+ * Camera controls.
+ *
+ * Position the viewport camera, snap it to a standard orthographic/isometric
+ * view, and toggle between the 2D (plan) and 3D modelling modes — mirrors the
+ * canvas view menu and the 2D/3D toggle. Like {@linkcode PluginZoomApi}, these
+ * are transient VIEW-STATE changes: they are not model edits, so they are not
+ * write-gated and are not undoable. Accessed via `snaptrude.core.camera`.
+ *
+ * Read and set the full camera pose (`getPose`/`setPose`), walk and turn it the
+ * way the arrow keys do (`move`/`rotate`), and read or change the arrow-key
+ * navigation settings (`getNavigationSettings`/`updateNavigationSettings`).
+ * Positions are world coordinates in internal `babylon` units (1 unit =
+ * 0.254 m, Y up); yaw is degrees clockwise from +z seen from above, pitch is
+ * degrees above level.
+ *
+ * While Present mode is open these calls set the Design frame a view saved in
+ * Present (`presentation.views.create`) is taken from; they never move the
+ * Present sheet canvas. To pan, zoom or screenshot the Present canvas, use
+ * {@linkcode PluginPresentationCameraApi} (`presentation.camera`).
+ */
+export abstract class PluginCameraApi {
+  constructor() {}
+
+  /**
+   * Point the camera: place its eye at `eye` looking toward `target` (world
+   * coordinates, internal `babylon` units). View-state only — not undoable.
+   *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @param eye - Camera position as a {@linkcode Vec3Handle}
+   * @param target - Point the camera looks at as a {@linkcode Vec3Handle}
+   * @returns `true` once the camera has been positioned.
+   *
+   * @examplePrompt Look at the model from above the north-east corner
+   * @examplePrompt Position the camera at (50, 30, 50) looking at the origin
+   * @examplePrompt Point the camera at the centre of the building from the side
+   * @examplePrompt Set the eye to this point and aim it at that point
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   * await snaptrude.core.camera.lookFrom(vec3.new(50, 30, 50), vec3.new(0, 0, 0))
+   * ```
+   */
+  public abstract lookFrom(
+    eye: Vec3Handle,
+    target: Vec3Handle,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Snap the camera to a standard view — the five orthographic elevations
+   * (`top` / `front` / `back` / `left` / `right`) or the 3D `iso` (isometric
+   * perspective) view. Mirrors the canvas view menu. View-state only — not
+   * undoable. The orthographic presets exit 2D mode first if needed.
+   *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @param view - The standard view to snap to ({@linkcode PluginStandardView})
+   * @returns `true` once the view has been applied.
+   *
+   * @examplePrompt Switch to the top view
+   * @examplePrompt Show me the front elevation
+   * @examplePrompt Go to the isometric view
+   * @examplePrompt Look at the model from the left
+   * @examplePrompt Give me a plan view from the top
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.setStandardView("top")
+   * ```
+   */
+  public abstract setStandardView(
+    view: PluginStandardView,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Get the current camera mode. Paired with {@linkcode PluginCameraApi.setMode}.
+   *
+   * @returns `"2d"` when the editor is in plan view, `"3d"` otherwise.
+   *
+   * @examplePrompt Am I in 2D or 3D?
+   * @examplePrompt What view mode is the editor in?
+   *
+   * # Example
+   * ```ts
+   * if ((await snaptrude.core.camera.getMode()) === "2d") {
+   *   await snaptrude.core.camera.setMode("3d")
+   * }
+   * ```
+   */
+  public abstract getMode(): PluginApiReturn<PluginCameraMode>
+
+  /**
+   * Toggle the modelling mode between `2d` (plan) and `3d`. Mirrors the canvas
+   * 2D/3D toggle: `3d` enters the isometric perspective view, `2d` drops to the
+   * orthographic plan of the active storey. View-state only — not undoable.
+   *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @param mode - `"2d"` or `"3d"` ({@linkcode PluginCameraMode})
+   * @returns `true` once the mode switch has been requested.
+   *
+   * @examplePrompt Switch to 3D view
+   * @examplePrompt Drop into 2D plan mode
+   * @examplePrompt Go back to 3D
+   * @examplePrompt Show the floor plan in 2D
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.setMode("3d")
+   * ```
+   */
+  public abstract setMode(mode: PluginCameraMode): PluginApiReturn<boolean>
+
+  /**
+   * Read the camera's current projection: `"perspective"` (the default 3D
+   * view) or `"orthographic"`. In 2D (plan) mode this always reports
+   * `"orthographic"` — a plan is an orthographic projection.
+   *
+   * @returns The current {@linkcode PluginCameraProjection}.
+   *
+   * @examplePrompt Is the camera in perspective or orthographic?
+   * @examplePrompt What projection is the 3D view using?
+   * @examplePrompt Check whether perspective is on
+   *
+   * # Example
+   * ```ts
+   * const projection = await snaptrude.core.camera.getProjection()
+   * console.log(projection) // "perspective" | "orthographic"
+   * ```
+   */
+  public abstract getProjection(): PluginApiReturn<PluginCameraProjection>
+
+  /**
+   * Switch the 3D camera between `"perspective"` and `"orthographic"`
+   * projection — the Perspective/Orthographic control in the Design tab's
+   * View Settings panel. Like {@linkcode PluginCameraApi.setMode}, this is a
+   * transient view-state change: not write-gated, not undoable.
+   *
+   * In 2D (plan) mode the canvas is always an orthographic plan:
+   * `"orthographic"` is accepted as a no-op, while `"perspective"` is
+   * rejected — switch to 3D first via `setMode("3d")`.
+   *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @param projection - `"perspective"` or `"orthographic"` ({@linkcode PluginCameraProjection})
+   * @returns `true` once the projection has been applied.
+   *
+   * @examplePrompt Switch the camera to orthographic
+   * @examplePrompt Turn perspective off
+   * @examplePrompt Give me a perspective view of the model
+   * @examplePrompt Make the 3D view orthographic like an axonometric drawing
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.setProjection("orthographic")
+   * const projection = await snaptrude.core.camera.getProjection() // "orthographic"
+   * ```
+   */
+  public abstract setProjection(
+    projection: PluginCameraProjection,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Zoom (fit) the camera to all geometry in the scene — the "zoom extents"
+   * action. View-state only — not undoable. Canonical home of the zoom-extents
+   * read (the deprecated `core.zoom.extents`).
+   *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @returns `true` once the camera has been framed to the scene.
+   *
+   * @examplePrompt Zoom out so I can see the whole model
+   * @examplePrompt Fit everything in the view
+   * @examplePrompt Frame the entire building in the viewport
+   * @examplePrompt Do a zoom extents on the canvas
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.zoomExtents()
+   * ```
+   */
+  public abstract zoomExtents(): PluginApiReturn<boolean>
+
+  /**
+   * Zoom (fit) the camera to the current selection. View-state only — not
+   * undoable. Canonical home of the zoom-to-selection read (the deprecated
+   * `core.zoom.selection`).
+   *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
+   * @returns `true` if there was a selection to frame; `false` if nothing is
+   *   selected (no-op).
+   *
+   * @examplePrompt Zoom in on what I have selected
+   * @examplePrompt Frame the selected walls in the view
+   * @examplePrompt Focus the camera on my current selection
+   * @examplePrompt Fit the view to the selected room
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.zoomSelection()
+   * ```
+   */
+  public abstract zoomSelection(): PluginApiReturn<boolean>
+
+  /**
+   * Read where the camera is and where it looks: the eye and target positions
+   * (world coordinates, internal `babylon` units), the view direction as yaw
+   * and pitch, the vertical field of view, the projection and the 2D/3D mode.
+   * Paired with {@linkcode PluginCameraApi.setPose}.
+   *
+   * @returns The current {@linkcode PluginCameraPose}.
+   * @throws PRECONDITION_FAILED when there is no active camera.
+   *
+   * @examplePrompt Where is the camera right now?
+   * @examplePrompt Remember this viewpoint so we can come back to it
+   * @examplePrompt Which way is the camera facing?
+   * @examplePrompt How high above the ground is the camera?
+   *
+   * # Example
+   * ```ts
+   * const pose = await snaptrude.core.camera.getPose()
+   * console.log(pose.eye, pose.yawInDegrees, pose.pitchInDegrees)
+   * ```
+   */
+  public abstract getPose(): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Place the camera, optionally easing there over `options.durationInSeconds`,
+   * and resolve once the new view has been drawn, so a capture that follows sees
+   * it without a fixed wait. `pose` is one of:
+   *
+   * - `{ eye, target }`: stand at `eye` looking at `target`, as
+   *   {@linkcode PluginCameraApi.lookFrom} does with handles;
+   * - `{ eye, yawInDegrees, pitchInDegrees }`: stand at `eye` looking along a
+   *   direction;
+   * - `{ standAt, yawInDegrees? }`: stand on the floor, stair, terrain or
+   *   ground at or below `standAt`, at the user's eye height above it (the `I`
+   *   key), facing `yawInDegrees` (the current yaw when omitted).
+   *
+   * Stops a playing walkthrough and switches from 2D plan view to 3D first.
+   * View-state only: not write-gated, not undoable.
+   *
+   * @param pose - Where to put the camera ({@linkcode PluginCameraPoseInput})
+   * @param options - `durationInSeconds`: ease over this long (0 to 10, default 0 jumps)
+   * @returns The camera's {@linkcode PluginCameraPose} once it has arrived.
+   * @throws PRECONDITION_FAILED when there is no active camera, while a
+   *   walkthrough export is recording, or when `standAt` lies below the ground
+   *   with nothing under it. VALIDATION when `eye` and `target` coincide or a
+   *   pitch is beyond ±89°.
+   *
+   * @examplePrompt Stand in the living room at eye level facing the window
+   * @examplePrompt Move the camera to (40, 12, 30) looking at the entrance
+   * @examplePrompt Fly the camera smoothly over to the courtyard
+   * @examplePrompt Put me back at the viewpoint we saved earlier
+   *
+   * # Example
+   * ```ts
+   * const { camera } = snaptrude.core
+   * await camera.setPose({ standAt: { x: 20, y: 0, z: 35 }, yawInDegrees: 90 })
+   * await camera.setPose(
+   *   { eye: { x: 60, y: 25, z: 60 }, target: { x: 0, y: 5, z: 0 } },
+   *   { durationInSeconds: 1.5 },
+   * )
+   * ```
+   */
+  public abstract setPose(
+    pose: PluginCameraPoseInput,
+    options?: PluginCameraSetPoseOptions,
+  ): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Walk or fly the camera by a displacement in its own frame: `forward` along
+   * the level view direction, `right` to its side and `up` vertically, in
+   * internal `babylon` units. The view direction does not change. With
+   * `options.followsFloor` the camera keeps its height above the floor as it
+   * goes, climbing and descending stairs and ramps the way the arrow keys do.
+   * Stops a playing walkthrough and switches from 2D plan view to 3D first.
+   * View-state only: not write-gated, not undoable.
+   *
+   * @param displacement - {@linkcode PluginCameraMoveDisplacement}; omitted components are 0
+   * @param options - `followsFloor` (default `false`) and `durationInSeconds` (0 to 10, default 0)
+   * @returns The camera's {@linkcode PluginCameraPose} after the move.
+   * @throws PRECONDITION_FAILED when there is no active camera, or while a
+   *   walkthrough export is recording.
+   *
+   * @examplePrompt Walk forward 3 metres
+   * @examplePrompt Step to the right a little
+   * @examplePrompt Walk up the stairs ahead
+   * @examplePrompt Raise the camera by 2 metres
+   *
+   * # Example
+   * ```ts
+   * const metre = 1 / 0.254
+   * await snaptrude.core.camera.move(
+   *   { forward: 3 * metre },
+   *   { followsFloor: true, durationInSeconds: 2 },
+   * )
+   * ```
+   */
+  public abstract move(
+    displacement: PluginCameraMoveDisplacement,
+    options?: PluginCameraMoveOptions,
+  ): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Turn the camera in place by signed angles: `yawInDegrees` to the right
+   * (clockwise seen from above) and `pitchInDegrees` up. The eye does not move;
+   * the resulting pitch is kept within ±89°. Stops a playing walkthrough and
+   * switches from 2D plan view to 3D first. View-state only: not write-gated,
+   * not undoable.
+   *
+   * @param yawInDegrees - Turn to the right by this much (negative turns left)
+   * @param pitchInDegrees - Tilt up by this much (negative tilts down; default 0)
+   * @param options - `durationInSeconds` (0 to 10, default 0)
+   * @returns The camera's {@linkcode PluginCameraPose} after turning.
+   * @throws PRECONDITION_FAILED when there is no active camera, or while a
+   *   walkthrough export is recording.
+   *
+   * @examplePrompt Turn around
+   * @examplePrompt Look 45 degrees to the left
+   * @examplePrompt Tilt the camera down a bit
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.rotate(180, 0, { durationInSeconds: 1 })
+   * ```
+   */
+  public abstract rotate(
+    yawInDegrees: number,
+    pitchInDegrees?: number,
+    options?: PluginCameraRotateOptions,
+  ): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Read the arrow-key navigation settings: whether the arrow keys walk the
+   * camera, the eye height used by `setPose`'s `standAt` and by walkthroughs
+   * that follow the floor, the walking speed, and whether walking stops at
+   * walls. Paired with {@linkcode PluginCameraApi.updateNavigationSettings}.
+   *
+   * @returns The current {@linkcode PluginCameraNavigationSettings}.
+   *
+   * @examplePrompt Is arrow-key navigation on?
+   * @examplePrompt What eye height does the camera use?
+   *
+   * # Example
+   * ```ts
+   * const { isKeyboardNavigationEnabled } =
+   *   await snaptrude.core.camera.getNavigationSettings()
+   * ```
+   */
+  public abstract getNavigationSettings(): PluginApiReturn<PluginCameraNavigationSettings>
+
+  /**
+   * Change arrow-key navigation settings; only the fields given change.
+   * `isKeyboardNavigationEnabled` is the user's Project Settings switch and is
+   * saved on this device; the other settings last for the session.
+   * Write-gated: this changes the user's preferences, not just the view.
+   *
+   * @param patch - The settings to change ({@linkcode PluginCameraNavigationSettingsPatch})
+   * @returns The {@linkcode PluginCameraNavigationSettings} after the change.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled.
+   *
+   * @examplePrompt Turn off arrow-key navigation
+   * @examplePrompt Use a 1.6 m eye height
+   * @examplePrompt Make walking stop at walls
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.updateNavigationSettings({
+   *   eyeHeight: 1.6 / 0.254,
+   *   isCollisionEnabled: true,
+   * })
+   * ```
+   */
+  public abstract updateNavigationSettings(
+    patch: PluginCameraNavigationSettingsPatch,
+  ): PluginApiReturn<PluginCameraNavigationSettings>
+}
+
+/**
+ * A standard camera view: the five orthographic elevations (`top`/`front`/
+ * `back`/`left`/`right`) or the 3D isometric perspective (`iso`).
+ */
+export const PluginStandardView = z.enum([
+  "top",
+  "front",
+  "back",
+  "left",
+  "right",
+  "iso",
+])
+export type PluginStandardView = z.infer<typeof PluginStandardView>
+
+/**
+ * The modelling mode: `2d` (orthographic plan) or `3d` (isometric perspective).
+ */
+export const PluginCameraMode = z.enum(["2d", "3d"])
+export type PluginCameraMode = z.infer<typeof PluginCameraMode>
+
+/**
+ * The 3D camera projection: `perspective` (the default) or `orthographic` —
+ * the Perspective/Orthographic control in the Design tab's View Settings panel.
+ */
+export const PluginCameraProjection = z.enum(["perspective", "orthographic"])
+export type PluginCameraProjection = z.infer<typeof PluginCameraProjection>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.lookFrom}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `eye` | {@linkcode Vec3Handle} | Camera position (world, `babylon` units) |
+ * | `target` | {@linkcode Vec3Handle} | Point the camera looks at |
+ */
+export const PluginCameraLookFromArgs = z.object({
+  eye: Vec3Handle,
+  target: Vec3Handle,
+})
+export type PluginCameraLookFromArgs = z.infer<typeof PluginCameraLookFromArgs>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.setStandardView}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `view` | {@linkcode PluginStandardView} | The standard view to snap to |
+ */
+export const PluginCameraSetStandardViewArgs = z.object({
+  view: PluginStandardView,
+})
+export type PluginCameraSetStandardViewArgs = z.infer<
+  typeof PluginCameraSetStandardViewArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.setMode}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `mode` | {@linkcode PluginCameraMode} | `"2d"` or `"3d"` |
+ */
+export const PluginCameraSetModeArgs = z.object({
+  mode: PluginCameraMode,
+})
+export type PluginCameraSetModeArgs = z.infer<typeof PluginCameraSetModeArgs>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.setProjection}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projection` | {@linkcode PluginCameraProjection} | `"perspective"` or `"orthographic"` |
+ */
+export const PluginCameraSetProjectionArgs = z.object({
+  projection: PluginCameraProjection,
+})
+export type PluginCameraSetProjectionArgs = z.infer<
+  typeof PluginCameraSetProjectionArgs
+>
+
+// Plain {x, y, z} record with finite components (the brepFromRevolution `axisOrigin` pattern).
+const FiniteVec3Components = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  z: z.number().finite(),
+})
+
+/** Pitch is kept off the vertical, where yaw has no meaning. */
+const PitchInDegrees = z.number().finite().min(-89).max(89)
+
+/** How long a camera move eases for; 0 jumps. */
+const DurationInSeconds = z.number().finite().min(0).max(10)
+
+/**
+ * The camera's pose — result of {@linkcode PluginCameraApi.getPose},
+ * {@linkcode PluginCameraApi.setPose}, {@linkcode PluginCameraApi.move} and
+ * {@linkcode PluginCameraApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `eye` | `{ x, y, z }` | Camera position (world, `babylon` units) |
+ * | `target` | `{ x, y, z }` | Point the camera looks at |
+ * | `yawInDegrees` | `number` | View direction, degrees clockwise from +z seen from above (-180 to 180) |
+ * | `pitchInDegrees` | `number` | View direction, degrees above level (negative looks down) |
+ * | `fieldOfViewInDegrees` | `number` | Vertical field of view |
+ * | `projection` | {@linkcode PluginCameraProjection} | `"perspective"` or `"orthographic"` |
+ * | `mode` | {@linkcode PluginCameraMode} | `"2d"` or `"3d"` |
+ */
+export const PluginCameraPose = z.object({
+  eye: Vec3Components,
+  target: Vec3Components,
+  yawInDegrees: z.number(),
+  pitchInDegrees: z.number(),
+  fieldOfViewInDegrees: z.number(),
+  projection: PluginCameraProjection,
+  mode: PluginCameraMode,
+})
+export type PluginCameraPose = z.infer<typeof PluginCameraPose>
+
+/**
+ * Where {@linkcode PluginCameraApi.setPose} puts the camera — exactly one of:
+ *
+ * | Shape | Meaning |
+ * |---|---|
+ * | `{ eye, target }` | Stand at `eye` looking at `target` |
+ * | `{ eye, yawInDegrees, pitchInDegrees }` | Stand at `eye` looking along a direction (pitch within ±89°) |
+ * | `{ standAt, yawInDegrees? }` | Stand at eye height on the floor, stair, terrain or ground at or below `standAt`, facing `yawInDegrees` (default: current yaw) |
+ *
+ * Points are plain `{ x, y, z }` world coordinates in `babylon` units.
+ */
+export const PluginCameraPoseInput = z.union([
+  z
+    .object({ eye: FiniteVec3Components, target: FiniteVec3Components })
+    .strict(),
+  z
+    .object({
+      eye: FiniteVec3Components,
+      yawInDegrees: z.number().finite(),
+      pitchInDegrees: PitchInDegrees,
+    })
+    .strict(),
+  z
+    .object({
+      standAt: FiniteVec3Components,
+      yawInDegrees: z.number().finite().optional(),
+    })
+    .strict(),
+])
+export type PluginCameraPoseInput = z.infer<typeof PluginCameraPoseInput>
+
+/**
+ * Options for {@linkcode PluginCameraApi.setPose}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `durationInSeconds` | `number \| undefined` | Ease to the pose over this long (0 to 10; default 0 jumps) |
+ */
+export const PluginCameraSetPoseOptions = z
+  .object({ durationInSeconds: DurationInSeconds.optional() })
+  .strict()
+export type PluginCameraSetPoseOptions = z.infer<
+  typeof PluginCameraSetPoseOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.setPose}.
+ */
+export const PluginCameraSetPoseArgs = z.object({
+  pose: PluginCameraPoseInput,
+  options: PluginCameraSetPoseOptions.optional(),
+})
+export type PluginCameraSetPoseArgs = z.infer<typeof PluginCameraSetPoseArgs>
+
+/**
+ * A displacement in the camera's own frame, for {@linkcode PluginCameraApi.move}
+ * (`babylon` units; omitted components are 0).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `forward` | `number \| undefined` | Along the level view direction (negative walks back) |
+ * | `right` | `number \| undefined` | To the camera's right (negative steps left) |
+ * | `up` | `number \| undefined` | Vertically (negative descends) |
+ */
+export const PluginCameraMoveDisplacement = z
+  .object({
+    forward: z.number().finite().optional(),
+    right: z.number().finite().optional(),
+    up: z.number().finite().optional(),
+  })
+  .strict()
+export type PluginCameraMoveDisplacement = z.infer<
+  typeof PluginCameraMoveDisplacement
+>
+
+/**
+ * Options for {@linkcode PluginCameraApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `followsFloor` | `boolean \| undefined` | Keep the height above the floor, climbing stairs and ramps (default `false`) |
+ * | `durationInSeconds` | `number \| undefined` | Walk over this long (0 to 10; default 0 jumps) |
+ */
+export const PluginCameraMoveOptions = z
+  .object({
+    followsFloor: z.boolean().optional(),
+    durationInSeconds: DurationInSeconds.optional(),
+  })
+  .strict()
+export type PluginCameraMoveOptions = z.infer<typeof PluginCameraMoveOptions>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.move}.
+ */
+export const PluginCameraMoveArgs = z.object({
+  displacement: PluginCameraMoveDisplacement,
+  options: PluginCameraMoveOptions.optional(),
+})
+export type PluginCameraMoveArgs = z.infer<typeof PluginCameraMoveArgs>
+
+/**
+ * Options for {@linkcode PluginCameraApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `durationInSeconds` | `number \| undefined` | Turn over this long (0 to 10; default 0 jumps) |
+ */
+export const PluginCameraRotateOptions = z
+  .object({ durationInSeconds: DurationInSeconds.optional() })
+  .strict()
+export type PluginCameraRotateOptions = z.infer<
+  typeof PluginCameraRotateOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.rotate}.
+ */
+export const PluginCameraRotateArgs = z.object({
+  yawInDegrees: z.number().finite(),
+  pitchInDegrees: z.number().finite().optional(),
+  options: PluginCameraRotateOptions.optional(),
+})
+export type PluginCameraRotateArgs = z.infer<typeof PluginCameraRotateArgs>
+
+/**
+ * How fast the arrow keys walk: the Slow / Normal / Fast navigation setting.
+ */
+export const PluginCameraWalkSpeed = z.enum(["slow", "normal", "fast"])
+export type PluginCameraWalkSpeed = z.infer<typeof PluginCameraWalkSpeed>
+
+/**
+ * The arrow-key navigation settings — result of
+ * {@linkcode PluginCameraApi.getNavigationSettings} and
+ * {@linkcode PluginCameraApi.updateNavigationSettings}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `isKeyboardNavigationEnabled` | `boolean` | Whether the arrow keys walk the camera (Project Settings) |
+ * | `eyeHeight` | `number` | Eye height above the floor, `babylon` units |
+ * | `walkSpeed` | {@linkcode PluginCameraWalkSpeed} | Arrow-key walking speed |
+ * | `isCollisionEnabled` | `boolean` | Whether walking stops at walls |
+ */
+export const PluginCameraNavigationSettings = z.object({
+  isKeyboardNavigationEnabled: z.boolean(),
+  eyeHeight: z.number(),
+  walkSpeed: PluginCameraWalkSpeed,
+  isCollisionEnabled: z.boolean(),
+})
+export type PluginCameraNavigationSettings = z.infer<
+  typeof PluginCameraNavigationSettings
+>
+
+/**
+ * The settings to change in {@linkcode PluginCameraApi.updateNavigationSettings};
+ * omitted fields keep their value. `eyeHeight` is in `babylon` units, between
+ * 0.8 m and 2.5 m (3.15 to 9.84 units).
+ */
+export const PluginCameraNavigationSettingsPatch = z
+  .object({
+    isKeyboardNavigationEnabled: z.boolean().optional(),
+    eyeHeight: z.number().finite().min(3.15).max(9.84).optional(),
+    walkSpeed: PluginCameraWalkSpeed.optional(),
+    isCollisionEnabled: z.boolean().optional(),
+  })
+  .strict()
+export type PluginCameraNavigationSettingsPatch = z.infer<
+  typeof PluginCameraNavigationSettingsPatch
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.updateNavigationSettings}.
+ */
+export const PluginCameraUpdateNavigationSettingsArgs = z.object({
+  patch: PluginCameraNavigationSettingsPatch,
+})
+export type PluginCameraUpdateNavigationSettingsArgs = z.infer<
+  typeof PluginCameraUpdateNavigationSettingsArgs
+>