partforge 0.156.0 → 0.158.0

package/types/oracle.d.ts

@@ -5,6 +5,7 @@
 // report/mask/gap types a caller needs to annotate results. The semantic mesh
 // oracle (`describe`) is its own closed package now — its types ship with it, and
 // the direction of this seam is what lets that package consume these helpers.
+import type { CameraCue, Easing, Keyframes, ParamValue, PartDefinition } from "./part.js";
 export type { GeometryKernel, Mesh, PartDefinition, ResolvedParams, Solid } from "./testing.js";
 export {
   // measurement + verification
@@ -29,3 +30,80 @@ export {
   annotationRay, rayPlane,
   type AnnotationRay, type RayPlaneHit, type PlaneSpec,
 } from "./testing.js";
+
+/** One step of a normalized animation (every optional field filled in). */
+export interface NormalizedAnimationStep {
+  /** `null` for the single anonymous step of a bare-`tracks` animation. */
+  label: string | null;
+  duration: number;
+  easing: Easing;
+  tracks: Record<string, Keyframes>;
+  opacity: Record<string, Keyframes>;
+  camera: CameraCue | null;
+}
+
+/** A camera cue on the normalized timeline: fires at `t`, sweeping for `sweep` seconds. */
+export interface NormalizedAnimationCue {
+  t: number;
+  view: CameraCue;
+  /** Seconds; `null` for a lone intro angle. */
+  sweep: number | null;
+}
+
+/** An animation in the canonical shape every consumer (playback, lint, CLI, preview) works against. */
+export interface NormalizedAnimation {
+  name: string;
+  label: string;
+  description: string | null;
+  loop: boolean;
+  autoplay: boolean;
+  steps: NormalizedAnimationStep[];
+  /** Each step's start as normalized t. */
+  stepStarts: number[];
+  /** Seconds. */
+  totalDuration: number;
+  cues: NormalizedAnimationCue[];
+  /** Params any step tracks. */
+  trackedKeys: string[];
+  /** Sub-parts any step fades. */
+  opacityKeys: string[];
+}
+
+/** One sampled instant of a baked preview animation. */
+export interface PreviewAnimationSample {
+  /** Normalized time in [0, 1]. */
+  t: number;
+  /** Sub-part name → column-major model-frame place matrix (16 numbers). */
+  poses: Record<string, number[]>;
+  /** Sub-part name → opacity 0–1; `{}` when the animation declares no fades. */
+  opacity: Record<string, number>;
+}
+
+/** What `samplePreviewAnimation` returns for a bakeable autoplay animation. */
+export interface PreviewAnimationInput {
+  anim: NormalizedAnimation;
+  /** Sorted by `t`; the first has `t === 0`, the last `t === 1`. */
+  samples: PreviewAnimationSample[];
+  /** Sub-part name → place matrix at the params handed in. */
+  base: Record<string, number[]>;
+}
+
+/** Sampling grid rate over the animation's real duration, in Hz. */
+export const PREVIEW_SAMPLE_HZ: 30;
+/** Most samples one preview animation carries; the grid thins, keyframe times never do. */
+export const PREVIEW_SAMPLE_CAP: 600;
+
+/**
+ * Decide whether the view's autoplay animation can be baked into the preview
+ * GLB — every tracked param place-only (the build reads none, and place() is a
+ * rigid motion at every sample) and the shown sub-parts constant — and if so
+ * sample the place matrices along its timeline. `buildReads(name)` returns the
+ * param keys that sub-part's build read, or `null` when unknown. Returns `null`
+ * when there is no autoplay animation or any check fails; never throws.
+ */
+export function samplePreviewAnimation(
+  part: PartDefinition,
+  view: string,
+  params?: Record<string, ParamValue>,
+  options?: { buildReads: (name: string) => ReadonlySet<string> | null },
+): PreviewAnimationInput | null;

package/types/part.d.ts

@@ -576,6 +576,8 @@ export interface SubPartExpectations {
   routedEmpty?: Expectation;
   /** Routed parts only: separate regions in the cut profile (volunteered check: `1`). */
   routedPieces?: Expectation;
+  /** Routed parts only: overlapping near- and far-face pocket pairs whose depths together exceed the stock (volunteered check: `0`). */
+  routedBreakthrough?: Expectation;
 }
 
 /**

package/types/testing.d.ts

@@ -11,6 +11,12 @@ import type { Derived, FontSource, PartDefinition, ResolvedParams } from "./part
 import type { KitOptions } from "./index.js";
 
 export type { Derived, GeometryKernel, Mesh, PartDefinition, ResolvedParams, Solid };
+// Declared in oracle.d.ts (its own surface); testing.js re-exports all of oracle.js.
+export {
+  samplePreviewAnimation, PREVIEW_SAMPLE_HZ, PREVIEW_SAMPLE_CAP,
+  type PreviewAnimationInput, type PreviewAnimationSample, type NormalizedAnimation,
+  type NormalizedAnimationStep, type NormalizedAnimationCue,
+} from "./oracle.js";
 
 // --- kernels ----------------------------------------------------------------
 
@@ -184,12 +190,17 @@ export function meshGaps(built: BuiltSubPart[], opts?: { bvhCache?: Map<Mesh, BV
 /**
  * Build every sub-part of a view in its display pose. Keeps solids LIVE (does
  * NOT call `kernel.cleanup()`) so callers can read exact solid facts first.
+ *
+ * `readsBySubPart`, when given, is filled with each sub-part's name → the params
+ * its `build()` read (expanded through derived values). `place()` reads are
+ * excluded, so a pose-only param never reads as a rebuild.
  */
 export function buildView(
   kernel: GeometryKernel,
   part: PartDefinition,
   view: string,
   params?: ResolvedParams,
+  opts?: { readsBySubPart?: Map<string, string[]> },
 ): BuiltSubPart[];
 
 // --- mesh math --------------------------------------------------------------