@salsita-ai/sdk 0.49.0-develop.cbee856178 → 0.49.0-develop.d4bea2382c

package/dist/docs/3d-scene/cameras/locks.mdx

@@ -0,0 +1,439 @@
+# Camera - Locks
+
+Keep a user's chosen viewing angle or magnification while the configurator moves between related product views. Camera locks place cameras into named groups: give two cameras the same explicit group and the destination camera retains that part of the live view when it activates.
+
+- [Apply camera locks](#apply-camera-locks)
+- [Choose what to preserve](#choose-what-to-preserve)
+- [Understand transition behavior](#understand-transition-behavior)
+- [Try the example](#try-the-example)
+- [Example](#example)
+- [Complete Implementation](#complete-implementation)
+
+## Apply camera locks
+
+Assign the same literal group name to the outgoing and incoming cameras that should share a live view. For perspective cameras, `distanceLockGroup` preserves dolly distance and `rotationLockGroup` preserves the live azimuth and polar angles:
+
+```yaml
+components:
+  Scene:
+    fitRootPerspectiveCamera:
+      overview:
+        distanceLockGroup: product-view
+        rotationLockGroup: product-view
+  Product:
+    fitEntityPerspectiveCamera:
+      detail:
+        distanceLockGroup: product-view
+        rotationLockGroup: product-view
+```
+
+When the Product camera activates after the Scene camera, it still calculates its normal target from Product, but it uses the user's current distance and rotation. The same applies in the other direction. Group names have no predefined meaning; choose stable names that describe the related camera views in your configurator.
+
+Orthographic cameras use `zoomLockGroup` instead of `distanceLockGroup`:
+
+```yaml
+components:
+  Scene:
+    fitRootOrthographicCamera:
+      overview:
+        zoomLockGroup: product-view
+        rotationLockGroup: product-view
+  Product:
+    fitEntityOrthographicCamera:
+      detail:
+        zoomLockGroup: product-view
+        rotationLockGroup: product-view
+```
+
+Add the group property to every camera that participates. Group names match exactly and case-sensitively, including whitespace. A missing group, `null`, or a different string means that aspect follows the destination camera normally; two missing or `null` groups never create a lock.
+
+## Choose what to preserve
+
+Distance or zoom and rotation are independent. Configure only the behavior the product flow needs:
+
+- Set only `rotationLockGroup` to retain the viewing angle while the destination camera calculates its normal fit distance or zoom.
+- Set only `distanceLockGroup` on perspective cameras to retain dolly distance while applying the destination orientation.
+- Set only `zoomLockGroup` on orthographic cameras to retain zoom while applying the destination orientation.
+- Set both relevant groups to translate the retained view around the destination camera's newly calculated target.
+
+Lock groups are available on fit-root, fit-entity, fit-selection, and static cameras. A camera can belong to different groups for rotation and magnification by using different names for the two aspects.
+
+## Understand transition behavior
+
+The destination camera still owns its target, boundary behavior, and limits. Preserved distance and zoom are clamped to its configured limits. Preserved angles use the same limit resolution as a normally applied camera: finite two-sided ranges clamp during the transition, while a one-sided azimuth limit is placed on its allowed side within one revolution of the preserved angle, so the angle stays where it is and the limit is reached by orbiting toward it. This can intentionally crop a newly fitted target: a lock preserves the user's view rather than guaranteeing that all destination content remains visible.
+
+A matching group also applies when the active camera refits itself after mesh, bounds, or canvas-padding changes. This is useful with `fitMeshChanges`: geometry can change the target or fit while the chosen live aspects remain stable. A refit only preserves an aspect whose live value is a settled or user-chosen view: when it interrupts an unfinished transition that was still animating that aspect toward its destination, such as the first load, a Reset, or a switch from a camera with different groups, the refit completes the destination view instead of freezing the animation midway.
+
+Locks apply only between cameras of the same projection type. Switching between perspective and orthographic cameras uses the destination view normally, even when their group names match. Projection parameters such as perspective `fov` and orthographic `frustumSize` are not preserved; keep them consistent when a visual projection snap would be distracting.
+
+Reset Camera bypasses all locks for that action and restores the active camera's configured view. The next automatic transition uses locks normally again. Export rendering remains independent from the interactive camera's lock history.
+
+## Try the example
+
+The example uses dynamic expressions and sidebar switches only to make each lock easy to turn on and off while experimenting. A normal integration should use stable literal group names as shown above. Object B and the full-scene camera share a group, while Object A uses a different group:
+
+- Object A: a fit-selection camera with the `object-a` group.
+- Object B: a fit-entity camera activated by `$filter.selectedEntityIds`, with the `object-b-and-root` group.
+- Nothing selected: a fit-root camera with the `object-b-and-root` group.
+
+1. Leave both lock switches on, click Object B to select it, then orbit and zoom or dolly to an obvious view.
+2. Click the empty canvas to clear the selection. The target changes to the whole scene, but the live rotation and magnification stay because B and the root share both groups.
+3. Turn off one lock and repeat B → Nothing selected. The enabled aspect stays; the disabled aspect follows the destination camera.
+4. Click Object A to select it. Its groups are different, so the configured A view is applied normally.
+5. While B or Nothing selected is active, toggle **Show B extra part**. `fitMeshChanges` refits the same camera from mesh-derived bounds. An unlocked distance or zoom fits the larger shape while a locked rotation stays unchanged.
+6. With both locks enabled, switch Perspective ↔ Orthographic. Projection changes never preserve the live view.
+7. Change the live view and press the camera button in the toolbar. Reset Camera bypasses the locks once and restores the active camera's configured fit and angles.
+8. In the perspective view with nothing selected, dolly fully out to the root camera's `maxDistance` of 9000, then click Object B. The preserved distance is clamped to B's `maxDistance` of 6500, so the camera moves closer while the rotation stays. In the orthographic view, zoom fully in on Object B and clear the selection: B's `maxZoom` of 3.5 is clamped to the root camera's 3.
+
+For the camera activation rules used here, see [Fit Selection](?path=/docs/3d-scene-cameras-fit-selection--docs), [Fit Entity](?path=/docs/3d-scene-cameras-fit-entity--docs), [Fit Root](?path=/docs/3d-scene-cameras-fit-root--docs), and [Camera Transitions](?path=/docs/3d-scene-cameras-transitions--docs).
+
+## Example
+
+Use the sidebar to toggle each lock independently and change B's fitted mesh, the control over the canvas to switch projection, and the camera toolbar button to reset.
+
+## Complete Implementation
+
+{/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}
+
+<details>
+<summary>Click to view the complete implementation files</summary>
+
+### ./spec/domain.yaml
+
+```yaml
+model:
+  latest:
+    entityTypes:
+      - Scene
+      - ObjectA
+      - ObjectB
+    aliases:
+      RootEntity:
+        - Scene
+    shapes:
+      Scene:
+        lockRotation:
+          type: boolean
+        lockZoomOrDistance:
+          type: boolean
+        showBExtraPart:
+          type: boolean
+
+relations:
+  Scene:
+    $objectA:
+      kind: allOfType
+      target: ObjectA
+      cardinality: 1-1
+      composedOf: true
+    $objectB:
+      kind: allOfType
+      target: ObjectB
+      cardinality: 1-1
+      composedOf: true
+  ObjectA:
+    $scene:
+      kind: allOfType
+      target: Scene
+      cardinality: 1-1
+      composedOf: false
+  ObjectB:
+    $scene:
+      kind: allOfType
+      target: Scene
+      cardinality: 1-1
+      composedOf: false
+
+presets:
+  - name: Camera locks
+    description: Compare independent rotation and zoom or distance locks while changing camera targets.
+    rootEntityType: Scene
+    initialDomainEntities:
+      - id: Scene-1
+        type: Scene
+        lockRotation: true
+        lockZoomOrDistance: true
+        showBExtraPart: false
+      - id: ObjectA-1
+        type: ObjectA
+      - id: ObjectB-1
+        type: ObjectB
+
+viewStates:
+  - perspective
+  - orthographic
+
+# This example resolves lock groups from boolean attributes only so readers can
+# compare locked and unlocked behavior interactively. In an application, assign
+# stable literal lock groups directly to the related camera configurations.
+components:
+  Scene:
+    applicationConfig:
+      main:
+        layout: universal
+        ignoreSelectionInSidebar: true
+        miniSidebar: true
+        splitSidebar: true
+        distanceDataUnit: mm
+    toolbar:
+      main:
+        desktop:
+          - kind: toolbarButtonGroup
+            children:
+              - kind: resetCameraToolbarButton
+                props:
+                  icon: CameraRotate
+        mobile:
+          - kind: toolbarButtonGroup
+            children:
+              - kind: resetCameraToolbarButton
+    viewControls:
+      projection:
+        items:
+          - label: Perspective
+            value: perspective
+            icon: Eye
+          - label: Orthographic
+            value: orthographic
+            icon: Square
+    fitRootPerspectiveCamera:
+      nothingSelected:
+        near: 10
+        far: 20000
+        fov: 42
+        azimuthAngle: 0.55
+        polarAngle: 1.05
+        minDistance: 1200
+        maxDistance: 9000
+        distanceLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        fitMeshChanges: true
+        $filter:
+          viewStates: [perspective]
+    fitRootOrthographicCamera:
+      nothingSelected:
+        near: 10
+        far: 20000
+        frustumSize: 5000
+        distance: 6000
+        azimuthAngle: 0.55
+        polarAngle: 1.05
+        minZoom: 0.4
+        maxZoom: 3
+        zoomLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        fitMeshChanges: true
+        $filter:
+          viewStates: [orthographic]
+    attributeSwitch:
+      lockRotation:
+        value:
+          $bind: lockRotation
+      lockZoomOrDistance:
+        value:
+          $bind: lockZoomOrDistance
+      showBExtraPart:
+        value:
+          $bind: showBExtraPart
+
+  ObjectA:
+    fitSelectionPerspectiveCamera:
+      selected:
+        priority: 10
+        near: 10
+        far: 20000
+        fov: 42
+        azimuthAngle: -0.85
+        polarAngle: 1.25
+        minDistance: 700
+        maxDistance: 5000
+        distanceLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        $filter:
+          viewStates: [perspective]
+    fitSelectionOrthographicCamera:
+      selected:
+        priority: 10
+        near: 10
+        far: 20000
+        frustumSize: 5000
+        distance: 4000
+        azimuthAngle: -0.85
+        polarAngle: 1.25
+        minZoom: 0.5
+        maxZoom: 4
+        zoomLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        $filter:
+          viewStates: [orthographic]
+    sceneEntityBoxObject:
+      body:
+        width: 900
+        height: 1200
+        depth: 700
+        anchor: center
+    sceneEntityProperties:
+      main:
+        offsetX: -1600
+        offsetY: 600
+    sceneEntityLocalMaterialOverride:
+      main:
+        materialsToOverride: [BoxMaterial]
+        color: '#4f7cac'
+        roughness: 0.65
+    selectable:
+      main: {}
+
+  ObjectB:
+    fitEntityPerspectiveCamera:
+      selected:
+        priority: 10
+        near: 10
+        far: 20000
+        # Projection settings are intentionally identical to the root camera.
+        # Distance/zoom locks preserve controls state, not projection parameters;
+        # changing these would cause an immediate visual snap before the pan.
+        fov: 42
+        azimuthAngle: 1.0
+        polarAngle: 0.9
+        minDistance: 900
+        maxDistance: 6500
+        distanceLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        fitMeshChanges: true
+        $filter:
+          viewStates: [perspective]
+          selectedEntityIds:
+            $read: id
+    fitEntityOrthographicCamera:
+      selected:
+        priority: 10
+        near: 10
+        far: 20000
+        frustumSize: 5000
+        distance: 4500
+        azimuthAngle: 1.0
+        polarAngle: 0.9
+        minZoom: 0.4
+        maxZoom: 3.5
+        zoomLockGroup:
+          $read: $distanceLockGroup
+        rotationLockGroup:
+          $read: $rotationLockGroup
+        fitMeshChanges: true
+        $filter:
+          viewStates: [orthographic]
+          selectedEntityIds:
+            $read: id
+    sceneEntityBoxObject:
+      body:
+        width: 1100
+        height: 900
+        depth: 850
+        anchor: center
+      extra:
+        width: 1900
+        height: 350
+        depth: 500
+        anchor: center
+        $filter:
+          active:
+            $read: $showExtraPart
+    sceneEntityObjectProperties:
+      extra:
+        offsetX: 800
+        offsetY: 750
+        offsetZ: -250
+        $filter:
+          active:
+            $read: $showExtraPart
+    sceneEntityProperties:
+      main:
+        offsetX: 1600
+        offsetY: 450
+    sceneEntityLocalMaterialOverride:
+      main:
+        materialsToOverride: [BoxMaterial]
+        color: '#d9822b'
+        roughness: 0.65
+    selectable:
+      main: {}
+```
+
+### ./src/components/CameraLockControls.tsx
+
+```tsx
+import { propertyPageComponent } from '@salsita-ai/sdk/domain'
+import { AttributeSwitchSelector } from '@salsita-ai/sdk/react'
+import { PropertyContainer } from '@salsita-ai/sdk/ui'
+
+import { phx } from '../../.phoenix/phx.js'
+
+export default [
+  phx.domain.attachComponent
+    .withComponent(propertyPageComponent, 'main')
+    .withEntity('Scene')
+    .attach(s => ({
+      page: (
+        <PropertyContainer.Group spacing="large">
+          <PropertyContainer.Item
+            title="Try the camera locks"
+            description="Object B and the full-scene camera share lock groups, while Object A uses different groups. Orbit and zoom or dolly on Object B, then switch between camera targets to compare what is preserved. Disable either lock to make that part of the view follow the destination camera instead."
+          />
+          <AttributeSwitchSelector
+            entityId={s.id}
+            instanceName="lockRotation"
+            title="Lock rotation"
+            description="Preserve live azimuth and polar angles."
+          />
+          <AttributeSwitchSelector
+            entityId={s.id}
+            instanceName="lockZoomOrDistance"
+            title="Lock zoom / distance"
+            description="Preserve perspective distance or orthographic zoom."
+          />
+          <AttributeSwitchSelector
+            entityId={s.id}
+            instanceName="showBExtraPart"
+            title="Show B extra part"
+            description="Change B's mesh bounds to trigger a same-camera refit."
+          />
+        </PropertyContainer.Group>
+      ),
+    })),
+]
+```
+
+### ./src/expressions/camera-locks.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomExpressions({
+  Scene: {
+    $distanceLockGroup: s => (s.lockZoomOrDistance ? 'object-b-and-root' : null),
+    $rotationLockGroup: s => (s.lockRotation ? 'object-b-and-root' : null),
+  },
+  ObjectA: {
+    $distanceLockGroup: s => (s.$scene.lockZoomOrDistance ? 'object-a' : null),
+    $rotationLockGroup: s => (s.$scene.lockRotation ? 'object-a' : null),
+  },
+  ObjectB: {
+    $distanceLockGroup: s => (s.$scene.lockZoomOrDistance ? 'object-b-and-root' : null),
+    $rotationLockGroup: s => (s.$scene.lockRotation ? 'object-b-and-root' : null),
+    $showExtraPart: s => s.$scene.showBExtraPart,
+  },
+})
+```
+
+</details>

package/dist/docs/3d-scene/cameras/static.mdx

@@ -541,6 +541,8 @@ Choose perspective cameras for natural, immersive viewing experiences. Choose or
 
 ## Example
 
+To retain the user's live rotation, distance, or zoom when switching between static camera views that share a lock group, see the [Camera Locks example](?path=/docs/3d-scene-cameras-locks--docs).
+
 This example shows multiple static cameras combining both perspective and orthographic projections positioned to showcase the model from different specific angles. Each camera maintains its configured position while still allowing user interaction within defined limits.
 
 Try using the view controls at the top of the interface to switch between different camera perspectives. Notice how the 3D and Front views provide natural perspective viewing with depth, while the Top and Left views use true orthographic projection with `frustumSize` for technical accuracy. The orthographic views use `animateTransition: false` to provide instant, precise positioning ideal for technical examination.

package/dist/docs/3d-scene/cameras/transitions.mdx

@@ -117,6 +117,8 @@ The camera system uses memoization to maintain the same component instance when
 
 This example combines all three transition scenarios. Use the step navigation to see component instance changes, adjust the radius slider in "Bounding Box" view to see geometry-based transitions, and toggle the box visibility in "Fit Mesh" view to see mesh-change transitions.
 
+To preserve a user's live rotation, distance, or zoom across selected camera transitions, see the [Camera Locks example](?path=/docs/3d-scene-cameras-locks--docs).
+
 ## Complete Implementation
 
 {/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}

package/dist/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-07T10:56:14.429Z",
+  "generatedAt": "2026-10-07T13:21:27.057Z",
   "categories": [
     {
       "name": "Phoenix",
@@ -1381,6 +1381,17 @@
               ],
               "source": "storybook-example"
             },
+            {
+              "title": "Locks",
+              "description": "Keep a user's chosen viewing angle or magnification while the configurator moves between related product views. Camera locks place cameras into named groups: give two cameras the same explicit group...",
+              "path": "docs/3d-scene/cameras/locks.mdx",
+              "category": [
+                "3d scene",
+                "Cameras",
+                "Locks"
+              ],
+              "source": "storybook-example"
+            },
             {
               "title": "Simple",
               "description": "This example demonstrates the default camera behavior in Phoenix configurators. When no camera components are configured, the system provides built-in camera controls with sensible defaults, giving...",

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -17,7 +17,7 @@ The Phoenix CLI (`phoenix` command) is the unified tool for all configurator dev
 `phoenix init [folder]` starts a configurator project in `[folder]` (default: the working directory):
 
 ```bash
-npx -p @salsita-ai/sdk phoenix init my-configurator
+npx -p @salsita-ai/sdk@canary phoenix init my-configurator
 cd my-configurator
 pnpm install
 pnpm phoenix sync

package/dist/docs/phoenix/project-structure.mdx

@@ -197,7 +197,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. Other skill folders are never touched.
+Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
 
 Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; use the `phoenix-review` skill instead of `/review`.
 

package/dist/docs/phoenix/sdk-builder-workflow.mdx

@@ -4,18 +4,19 @@ An SDK-builder workspace lets you build one configurator from the application sp
 
 Your workspace comes with one project and one `production` environment. Its first deployment is a hello-world configurator, so you have a live link before you change anything.
 
-Your workspace's Studio shows the setup, the link to your configurator and the setup steps with your workspace filled in. Studio already names the CLI `salsita`, the name it is being renamed to; until that rename ships, use the `phoenix` commands on this page. If the first deployment fails, Studio shows why and lets you retry it.
+Your workspace's Studio shows the setup, the link to your configurator and the setup steps with your workspace filled in. If the first deployment fails, Studio shows why and lets you retry it.
 
 ## Before you start
 
 - **Package access:** `@salsita-ai/sdk` is public on npm; `npx` and `pnpm install` download it without a registry token.
 - **Workspace details:** you need your workspace slug and its Phoenix region (`eu` or `us`), which you also received with your workspace.
 - **Tools:** Node.js and pnpm.
+- **SDK build:** during the internal beta, use the `canary` build of the SDK, as the commands below do. It is published from every change to the platform, so it is newer than the last release.
 
 ## 1. Create a project
 
 ```bash
-npx -p @salsita-ai/sdk phoenix init my-configurator
+npx -p @salsita-ai/sdk@canary phoenix init my-configurator
 cd my-configurator
 pnpm install
 pnpm phoenix sync
@@ -90,7 +91,7 @@ Tell us what is broken, confusing or missing, from wherever you are:
 - In Studio, **Send beta feedback** in the sidebar opens a short form.
 - In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
 
-Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. They are told never to include secrets, customer data or your project's source.
+Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. They are told never to include secrets, customer data or your project's source. After a deploy goes live, the agent also asks you, once per conversation, to rate building with Phoenix from 0 to 10; it tells you the answer goes to the Phoenix team, shows the message and sends it only after you approve it.
 
 ## Known limits
 

package/dist/domain/projections/common/camera-orbit.d.ts

@@ -1,5 +1,24 @@
 import { type Matrix4, Vector3 } from 'three';
 import type { DimensionUnit } from '../../dimensions/index.js';
+/** Camera angle and an equivalent pair of bounds that contains or clamps that angle. */
+export interface ResolvedCameraAngleBounds {
+    readonly angle: number;
+    readonly min: number;
+    readonly max: number;
+}
+/**
+ * Resolves periodic camera bounds around the supplied world-space angle.
+ *
+ * Equivalent angles separated by a full revolution remain the same view, so finite bounds are shifted to the
+ * revolution nearest the supplied angle before it is clamped. This prevents a preserved live angle near the 0/2π
+ * seam from introducing a full turn when the destination uses an equivalent range on another revolution.
+ *
+ * A one-sided range contains every angle on some revolution, so its finite bound is placed on the allowed side
+ * within one revolution of the angle: the angle is always inside the range and the limit is reached by orbiting
+ * toward it. Comparing a normalized angle against the raw bound instead let camera-controls snap the camera by up
+ * to a full turn on the next orbit input whenever the two happened to sit on different revolutions.
+ */
+export declare const resolveCameraAngleBounds: (angle: number, lowerBoundary: number, upperBoundary: number) => ResolvedCameraAngleBounds;
 /** Camera component state that determines its orbit around a target. */
 export interface CameraOrbitState {
     /** Camera azimuth angle in radians. */
@@ -32,20 +51,23 @@ export interface ResolveCameraOrbitProps {
     /** World transform used when the state's angles are relative. */
     readonly worldMatrix: Matrix4;
 }
-/** Camera orbit shared by interactive and exported rendering, expressed in world angles and default distance units. */
-export interface ResolvedCameraOrbit {
-    /** Resolved world azimuth angle in radians. */
+/** Camera rotation prepared in world angles, before applying angle bounds. */
+export interface PreparedCameraRotation {
+    /** World azimuth angle in radians. */
     readonly azimuthAngle: number;
-    /** Resolved minimum world azimuth angle in radians. */
+    /** Minimum world azimuth angle in radians. */
     readonly minAzimuthAngle: number;
-    /** Resolved maximum world azimuth angle in radians. */
+    /** Maximum world azimuth angle in radians. */
     readonly maxAzimuthAngle: number;
-    /** Resolved polar angle in radians. */
+    /** Polar angle in radians. */
     readonly polarAngle: number;
-    /** Resolved minimum polar angle in radians. */
+    /** Minimum polar angle in radians. */
     readonly minPolarAngle: number;
-    /** Resolved maximum polar angle in radians. */
+    /** Maximum polar angle in radians. */
     readonly maxPolarAngle: number;
+}
+/** Camera orbit prepared in world angles and default distance units, before applying angle bounds. */
+export interface PreparedCameraOrbit extends PreparedCameraRotation {
     /** Camera distance in domain default distance units, if configured. */
     readonly distance: number | undefined;
     /** Minimum camera distance in domain default distance units. */
@@ -53,8 +75,14 @@ export interface ResolvedCameraOrbit {
     /** Maximum camera distance in domain default distance units. */
     readonly maxDistance: number;
 }
+/** Camera orbit shared by interactive and exported rendering after applying angle bounds. */
+export type ResolvedCameraOrbit = PreparedCameraOrbit;
+/** Applies camera defaults, relative rotation, and distance units without clamping angles. */
+export declare const prepareCameraOrbit: ({ state, dimensionUnit, worldMatrix, }: ResolveCameraOrbitProps) => PreparedCameraOrbit;
+/** Applies the configured angle bounds to a prepared camera rotation. */
+export declare const resolvePreparedCameraRotation: (cameraRotation: PreparedCameraRotation) => PreparedCameraRotation;
 /** Resolves camera angle defaults, bounds, relative rotation, and distance units. */
-export declare const resolveCameraOrbit: ({ state, dimensionUnit, worldMatrix, }: ResolveCameraOrbitProps) => ResolvedCameraOrbit;
+export declare const resolveCameraOrbit: (props: ResolveCameraOrbitProps) => ResolvedCameraOrbit;
 /** Applies camera distance bounds after the caller supplies a fallback in default distance units. */
 export declare const resolveCameraDistance: (distance: number | undefined, bounds: Pick<ResolvedCameraOrbit, 'minDistance' | 'maxDistance'>, fallbackDistance: number) => number;
 /** Converts a camera orbit to its Cartesian offset from the look-at target. */

package/dist/domain/projections/common/camera-orbit.js

@@ -1 +1 @@
-import{Vector3 as a}from"three";import{distanceUnitToDefault as e}from"../../dimensions/index.js";import{getWorldAzimuthAngle as n}from"./world-transform.js";let t=Math.PI/2-.3,i=(a,e,n)=>{if(!Number.isFinite(e)||!Number.isFinite(n))return{angle:a,min:Math.min(e,n),max:Math.max(e,n)};let t=2*Math.PI,i=n-e,m=a-((a-e)%t+t)%t,r=m+i;if(a<=r)return{angle:a,min:m,max:r};if(a-r<=m+t-a)return{angle:r,min:m,max:r};let l=m+t;return{angle:l,min:l,max:l+i}};export const resolveCameraOrbit=({state:a,dimensionUnit:m,worldMatrix:r})=>{var l;let s=!0===a.relative?n(r):0,o=i(a.polarAngle??t,a.minPolarAngle??0,a.maxPolarAngle??Math.PI),h=i(Number.isFinite(l=(a.azimuthAngle??-.3)+s)?(l%(2*Math.PI)+2*Math.PI)%(2*Math.PI):l,(a.minAzimuthAngle??-1/0)+s,(a.maxAzimuthAngle??1/0)+s);return{azimuthAngle:h.angle,minAzimuthAngle:h.min,maxAzimuthAngle:h.max,polarAngle:o.angle,minPolarAngle:o.min,maxPolarAngle:o.max,distance:e(a.distance,m),minDistance:e(a.minDistance,m)??Number.EPSILON,maxDistance:e(a.maxDistance,m)??1/0}};export const resolveCameraDistance=(a,e,n)=>Math.max(e.minDistance,Math.min(a??n,e.maxDistance));export const cameraOrbitToCartesian=(e,n,t)=>new a(t*Math.sin(n)*Math.sin(e),t*Math.cos(n),t*Math.sin(n)*Math.cos(e));
+import{Vector3 as e}from"three";import{distanceUnitToDefault as a}from"../../dimensions/index.js";import{getWorldAzimuthAngle as n}from"./world-transform.js";let t=Math.PI/2-.3,r=2*Math.PI;export const resolveCameraAngleBounds=(e,a,n)=>{let t=Number.isFinite(a),i=Number.isFinite(n);if(!Number.isFinite(e)||!t&&!i)return{angle:e,min:Math.min(a,n),max:Math.max(a,n)};if(!t)return{angle:e,min:a,max:n+r*Math.ceil((e-n)/r)};if(!i)return{angle:e,min:a+r*Math.floor((e-a)/r),max:n};let m=n-a,l=e-((e-a)%r+r)%r,o=l+m;if(e<=o)return{angle:e,min:l,max:o};if(e-o<=l+r-e)return{angle:o,min:l,max:o};let s=l+r;return{angle:s,min:s,max:s+m}};export const prepareCameraOrbit=({state:e,dimensionUnit:r,worldMatrix:i})=>{let m=!0===e.relative?n(i):0;return{azimuthAngle:(e.azimuthAngle??-.3)+m,minAzimuthAngle:(e.minAzimuthAngle??-1/0)+m,maxAzimuthAngle:(e.maxAzimuthAngle??1/0)+m,polarAngle:e.polarAngle??t,minPolarAngle:e.minPolarAngle??0,maxPolarAngle:e.maxPolarAngle??Math.PI,distance:a(e.distance,r),minDistance:a(e.minDistance,r)??Number.EPSILON,maxDistance:a(e.maxDistance,r)??1/0}};export const resolvePreparedCameraRotation=e=>{var a;let n=resolveCameraAngleBounds(e.polarAngle,e.minPolarAngle,e.maxPolarAngle),t=resolveCameraAngleBounds(Number.isFinite(a=e.azimuthAngle)?(a%(2*Math.PI)+2*Math.PI)%(2*Math.PI):a,e.minAzimuthAngle,e.maxAzimuthAngle);return{azimuthAngle:t.angle,minAzimuthAngle:t.min,maxAzimuthAngle:t.max,polarAngle:n.angle,minPolarAngle:n.min,maxPolarAngle:n.max}};export const resolveCameraOrbit=e=>{let a=prepareCameraOrbit(e);return{...a,...resolvePreparedCameraRotation(a)}};export const resolveCameraDistance=(e,a,n)=>Math.max(a.minDistance,Math.min(e??n,a.maxDistance));export const cameraOrbitToCartesian=(a,n,t)=>new e(t*Math.sin(n)*Math.sin(a),t*Math.cos(n),t*Math.sin(n)*Math.cos(a));

package/dist/domain/projections/common/index.d.ts

@@ -1,5 +1,5 @@
 export { resolveBoundingBox, resolveBoundingSphere } from './bounding-shape.js';
-export { cameraOrbitToCartesian, resolveCameraDistance, resolveCameraOrbit, type CameraOrbitState, type ResolveCameraOrbitProps, type ResolvedCameraOrbit, } from './camera-orbit.js';
+export { cameraOrbitToCartesian, prepareCameraOrbit, resolveCameraDistance, resolveCameraOrbit, resolvePreparedCameraRotation, type CameraOrbitState, type PreparedCameraOrbit, type PreparedCameraRotation, type ResolveCameraOrbitProps, type ResolvedCameraOrbit, } from './camera-orbit.js';
 export { toMmVec3 } from './distance-vectors.js';
 export { createSceneObjectTransformMatrix, type SceneObjectTransformState } from './scene-object-transform.js';
 export { getPerspectiveBoxFitDistance, getPerspectiveSphereFitDistance, getWorldToViewSpaceQuaternion, type PerspectiveBoxFitDistanceProps, type PerspectiveCameraFitFrustum, type PerspectiveCameraFitViewingAngles, type PerspectiveSphereFitDistanceProps, } from './perspective-camera-fit.js';

package/dist/domain/projections/common/index.js

@@ -1 +1 @@
-export{resolveBoundingBox,resolveBoundingSphere}from"./bounding-shape.js";export{cameraOrbitToCartesian,resolveCameraDistance,resolveCameraOrbit}from"./camera-orbit.js";export{toMmVec3}from"./distance-vectors.js";export{createSceneObjectTransformMatrix}from"./scene-object-transform.js";export{getPerspectiveBoxFitDistance,getPerspectiveSphereFitDistance,getWorldToViewSpaceQuaternion}from"./perspective-camera-fit.js";export{getWorldAzimuthAngle}from"./world-transform.js";
+export{resolveBoundingBox,resolveBoundingSphere}from"./bounding-shape.js";export{cameraOrbitToCartesian,prepareCameraOrbit,resolveCameraDistance,resolveCameraOrbit,resolvePreparedCameraRotation}from"./camera-orbit.js";export{toMmVec3}from"./distance-vectors.js";export{createSceneObjectTransformMatrix}from"./scene-object-transform.js";export{getPerspectiveBoxFitDistance,getPerspectiveSphereFitDistance,getWorldToViewSpaceQuaternion}from"./perspective-camera-fit.js";export{getWorldAzimuthAngle}from"./world-transform.js";

package/dist/domain/system-components/fit-entity-orthographic-camera-component.d.ts

@@ -20,6 +20,14 @@ export type FitEntityOrthographicCameraComponentState = {
      * @default true
      */
     readonly animateTransition?: boolean | undefined;
+    /**
+     * Preserves the live camera zoom when switching between orthographic cameras with the same group.
+     */
+    readonly zoomLockGroup?: string | null | undefined;
+    /**
+     * Preserves the live camera rotation when switching between cameras with the same group.
+     */
+    readonly rotationLockGroup?: string | null | undefined;
     /**
      * Uses fitToBox strategy to fit the entity. By default, fitToSphere strategy is used.
      */