partforge 0.44.0 → 0.46.0

package/types/part.d.ts

@@ -297,11 +297,18 @@ export type Easing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
 export type Keyframes = Array<[number, number]>;
 
 /**
- * A camera cue angle: one of the seven canonical angles (`CanonicalView` in the
- * app entry — `"iso" | "front" | "back" | "top" | "bottom" | "left" | "right"`).
- * Cues fire during play only; scrubbing never moves the camera.
+ * The seven angles the viewer can frame a part from. Defined here rather than in
+ * the app entry so `CameraCue` can be the real union without an import cycle —
+ * the app entry re-exports it under its own name.
  */
-export type CameraCue = string;
+export type CanonicalView = "iso" | "front" | "back" | "left" | "right" | "top" | "bottom";
+
+/**
+ * A camera cue angle. `partforge lint` rejects anything outside the canonical
+ * seven (`animation-camera-invalid`), so the type says so too. Cues fire during
+ * play only; scrubbing never moves the camera.
+ */
+export type CameraCue = CanonicalView;
 
 /** One step of a multi-step animation. Steps play in order; prev/next navigate them. */
 export interface AnimationStep {
@@ -310,31 +317,31 @@ export interface AnimationStep {
   /** Seconds. Step durations are relative — they set each step's share of the timeline. */
   duration: number;
   easing?: Easing;
-  /** Param key -> keyframes. A param tracked nowhere keeps its current value. */
-  tracks: Record<string, Keyframes>;
+  /**
+   * Param key -> keyframes. A param tracked nowhere keeps its current value.
+   *
+   * Optional so a step can move only the camera — an establishing shot that
+   * holds the pose while the view swings round. `partforge lint` still requires
+   * that at least one step in the animation carries tracks, which is a
+   * whole-animation rule the type system can't express per step.
+   */
+  tracks?: Record<string, Keyframes>;
   /** Swing the camera to this angle when the step begins. */
   camera?: CameraCue;
 }
 
 /**
- * One named animation: pure keyframe data over EXISTING params. Declare either
- * `tracks` (one anonymous step) or `steps`, never both. See
- * docs/AUTHORING-PARTS.md "Animations".
+ * The fields both animation forms share. Exported so a host can extend it —
+ * `AnimationSpec` itself is a union and cannot be `extends`-ed.
  */
-export interface AnimationSpec {
+export interface AnimationSpecCommon {
   /** Shown in the transport bar's picker. Defaults to the animation's key. */
   label?: string;
   /** CommonMark, shown behind the ⓘ glyph. */
   description?: string;
-  /** Seconds. Required in the single-step (`tracks`) form. */
-  duration?: number;
   easing?: Easing;
   /** Wrap continuously. Single-step animations only. */
   loop?: boolean;
-  /** The single-step form: param key -> keyframes. */
-  tracks?: Record<string, Keyframes>;
-  /** The multi-step form. */
-  steps?: AnimationStep[];
   /**
    * One mechanism per animation: an angle (an intro cue at t=0), a
    * `[[t, angle], …]` cue list, or per-step `camera` names.
@@ -350,6 +357,27 @@ export interface AnimationSpec {
   autoplay?: boolean;
 }
 
+/**
+ * An animation is EITHER single-phase (`tracks` + `duration`) OR stepped
+ * (`steps`) — never both, never neither. `partforge lint` enforces that
+ * (`animation-tracks-or-steps`), and the union says the same thing, so a block
+ * carrying both is rejected before it ever reaches lint.
+ */
+export type AnimationSpec =
+  | (AnimationSpecCommon & {
+      /** Seconds — the whole animation's duration in the single-phase form. */
+      duration: number;
+      /** Param key -> keyframes. */
+      tracks: Record<string, Keyframes>;
+      steps?: never;
+    })
+  | (AnimationSpecCommon & {
+      /** The multi-step form; each step carries its own relative `duration`. */
+      steps: AnimationStep[];
+      tracks?: never;
+      duration?: never;
+    });
+
 // --- the part itself --------------------------------------------------------
 
 /**