effect-motion 0.4.0 → 0.5.0

package/dist/Physics.js

@@ -4,12 +4,36 @@ import * as Entity from "./Entity.js";
 import * as Instance from "./Instance.js";
 import * as Runner from "./Runner.js";
 import * as Scene from "./Scene.js";
-/** fast, gently damped general-purpose spring */
+/**
+ * The spring used when a call names none: quick and only lightly damped, so
+ * it overshoots a little before settling.
+ */
 export const defaultSpring = {
     mass: 0.05,
     stiffness: 10,
     damping: 0.5,
 };
+/**
+ * The named spring presets, each a calibrated point in `{ mass, stiffness,
+ * damping }` space. Pass the NAME to any spring animator — it autocompletes.
+ *
+ * @remarks
+ * Durations below are measured for a 100px move at 60fps and scale with
+ * distance; a spring's length is emergent, so treat them as character, not
+ * contract:
+ *
+ * - `strike` — hardest and fastest, launched with initial velocity (~0.7s).
+ * - `jump` — a quick launched hop (~1.4s).
+ * - `smooth` — mild overshoot, unobtrusive (~2s).
+ * - `beat` — a small, tight pulse; the least overshoot of the set (~2.6s).
+ * - `swing` — a relaxed, pendulum-like arc (~3.5s).
+ * - `plop` — lands heavy and wobbles noticeably (~7s).
+ * - `bounce` — barely damped, so it rings for a LONG time: about 37 seconds
+ *   and 90 direction changes for a 100px move. Striking as a one-off accent,
+ *   but check the frame count before putting it in a timed sequence.
+ *
+ * @see {@link Spring} to define your own.
+ */
 export const springs = {
     beat: { mass: 0.13, stiffness: 5.7, damping: 1.2, initialVelocity: 10 },
     plop: { mass: 0.2, stiffness: 20, damping: 0.68 },
@@ -95,23 +119,80 @@ const simulate = Effect.fnUntraced(function* (from, to, springInput, fn, settleT
     yield* Scene.tick;
 });
 const springPosition = Effect.fnUntraced(function* (instanceOrEffect, from, to, springInput, settleTolerance) {
-    const instance = yield* Instance.flatten(instanceOrEffect);
-    const lens = Entity.traitOrDie(instance.entity, "~position");
-    const current = lens.get(yield* Scene.data(instance));
+    const instance = yield* Instance.flattenInstance(instanceOrEffect);
+    // flatten the Vec3 for the simulator: it works on flat numeric records
+    // (design D2), so the tagged struct is unwrapped here and rebuilt below
+    const position = (yield* Scene.data(instance)).position;
+    const current = { x: position.x, y: position.y, z: position.z };
     // partial targets/origins hold the missing axis at its current value
     const target = { ...current, ...to };
     const start = { ...current, ...(from ?? {}) };
-    yield* simulate(start, target, springInput ?? defaultSpring, (value) => Scene.update(instance, (data) => lens.set(data, value)), settleTolerance);
+    yield* simulate(start, target, springInput ?? defaultSpring, (value) => Scene.update(instance, (data) => ({
+        ...data,
+        position: Entity.vec3(value),
+    })), settleTolerance);
     return instance;
 });
 const firstArgIsInstance = (args) => Instance.isInstance(args[0]);
 /**
- * Spring an instance to a position via its `~position` trait — the
- * durationless counterpart of `Motion.moveTo` (settles exactly, length
- * emerges from the physics). Dual:
- * `springTo(instance, to, springInput?, settleTolerance?)` or
- * `instance.pipe(springTo(to, springInput?, settleTolerance?))`.
+ * Spring an instance to a position — `Motion.moveTo` with momentum instead
+ * of a duration.
+ *
+ * @remarks
+ * The animation runs until the simulation settles, then lands exactly on
+ * `to`, so chaining springs is safe: each starts precisely where the last
+ * finished, with no accumulated drift. How long that takes depends on the
+ * spring AND the distance — a longer move rings longer.
+ *
+ * Because the length is emergent, a spring is awkward to synchronize
+ * against a fixed beat. When several things must finish together, either
+ * spring them inside a `Scene.all` and let the slowest govern, or use a
+ * duration-based tween with an elastic easing.
+ *
+ * Targets are partial, like `moveTo` — naming only `x` holds the other axes.
+ * Every axis is simulated by the same spring, so a diagonal move settles as
+ * one motion.
+ *
+ * @param to - Target position; omitted axes hold their current value.
+ * @param springInput - A preset name from {@link springs}, or a custom
+ *   {@link Spring}.
+ * @param settleTolerance - How close to the target (in both displacement
+ *   and velocity) counts as settled. Larger ends sooner and cuts the tail.
+ * @defaultValue `springInput` — {@link defaultSpring}; `settleTolerance` — `0.001`
+ * @returns The instance, so animators chain.
+ * @see {@link spring} to start from an explicit position.
+ *
+ * @example
+ * A struck-then-settling entrance, using two different presets.
+ * ```typescript
+ * yield* badge.pipe(
+ * 	Physics.springTo({ y: 120 }, "strike"),
+ * 	Physics.springTo({ x: 300 }, "smooth"),
+ * );
+ * ```
  */
 export const springTo = dual(firstArgIsInstance, (instance, to, springInput, settleTolerance) => springPosition(instance, undefined, to, springInput, settleTolerance));
-/** Like `springTo`, but from an explicit position (partials filled from current). */
+/**
+ * Like {@link springTo}, but starting from an explicit position.
+ *
+ * @remarks
+ * The springy entrance: an instance declared at its resting place can still
+ * fly in from off-screen and settle, because the origin is stated rather
+ * than read from the entity. Both `from` and `to` are partial and fill
+ * missing axes from the current position.
+ *
+ * @param from - Starting position; omitted axes start at the current value.
+ * @param to - Target position; omitted axes hold their current value.
+ * @param springInput - A preset name from {@link springs}, or a custom
+ *   {@link Spring}.
+ * @param settleTolerance - How close counts as settled.
+ * @defaultValue `springInput` — {@link defaultSpring}; `settleTolerance` — `0.001`
+ * @returns The instance, so animators chain.
+ *
+ * @example
+ * Drop a card in from above and let it settle where it was declared.
+ * ```typescript
+ * yield* card.pipe(Physics.spring({ y: -200 }, { y: 150 }, "plop"));
+ * ```
+ */
 export const spring = dual(firstArgIsInstance, (instance, from, to, springInput, settleTolerance) => springPosition(instance, from, to, springInput, settleTolerance));

package/dist/Projection.d.ts

@@ -4,11 +4,13 @@
  * point twice is bit-for-bit identical, which is what keeps 2.5D scenes
  * deterministic.
  *
- * The model is the After Effects one: a camera with a world position, Euler
- * orientation, and a focal length, looking down world -z at rest. World
- * points are transformed into the camera's frame (the view transform, which
- * is the inverse of the camera's own world transform), then divided by their
- * depth in front of the camera to land on screen.
+ * The model: a camera with a world position, Euler orientation, and a focal
+ * length, looking down world -z at rest. World points are transformed into
+ * the camera's frame (the view transform, which is the inverse of the
+ * camera's own world transform), then divided by their depth in front of the
+ * camera to land on screen. Scene space is right-handed — x right, y up,
+ * origin at the viewport center, +z toward the viewer — so the camera's
+ * optical axis passes through world (0, 0) at rest.
  *
  * Identity invariant: the default camera (see `defaultFocalLength` and
  * `defaultCameraZ`) projects a world point at `z = 0` to screen `(x, y)` at
@@ -23,10 +25,6 @@ export interface Vec3 {
     readonly y: number;
     readonly z: number;
 }
-export interface Vec2 {
-    readonly x: number;
-    readonly y: number;
-}
 /** The camera view, as it arrives on the frame from the runner. */
 export interface CameraView {
     readonly x: number;
@@ -37,11 +35,20 @@ export interface CameraView {
     readonly rotZ: number;
     readonly focalLength: number;
     /**
-     * view-space distance to the sharp plane (depth of field). Runner-filled
-     * to the resting camera distance, so the z=0 plane is in focus untouched.
+     * View-space distance to the intended sharp plane. Runner-filled to the
+     * resting camera distance.
+     *
+     * @remarks
+     * Currently inert: depth-of-field rendering is not implemented, so every
+     * frame renders sharp regardless of this value.
      */
     readonly focusDistance: number;
-    /** depth-of-field blur strength; 0 (the default) = pinhole, DoF off */
+    /**
+     * Intended depth-of-field blur strength; 0 is a pinhole.
+     *
+     * @remarks
+     * Currently inert — see {@link CameraView.focusDistance}.
+     */
     readonly aperture: number;
 }
 /**
@@ -76,8 +83,7 @@ export interface PointOfInterest {
 }
 /**
  * The auto-orient Euler angles (yaw + pitch, no roll) aiming a camera at
- * `poi` from its WORLD position (viewport-center pan already composed in —
- * see `resolveCamera`). The view transform flips z before rotating
+ * `poi` from its WORLD position. The view transform flips z before rotating
  * (in-front is +z), which inverts rotation handedness vs. world space;
  * that subtlety is handled here, exactly once, pinned by tests that
  * project the POI and assert it lands on the viewport center.
@@ -93,133 +99,32 @@ export declare const lookAtOrientation: (position: Vec3, poi: Vec3) => {
  * camera's own frame (so a lone `rotZ` rolls about the view axis and the
  * POI stays centered); the exact composed rotation is extracted back to
  * the fixed Rz·Ry·Rx Euler convention the view transform consumes.
- * Camera `x`/`y` are pan-from-viewport-center, so the world position
- * composes `origin` in before aiming. Absent POI is a pass-through
- * (one-node camera, unchanged); a partial POI is a loud defect. The
- * user's rotation fields are never written back — derivation happens
- * here, at view-assembly time.
- */
-export declare const resolveCamera: (camera: CameraView & PointOfInterest, origin: Vec2) => CameraView;
-/**
- * The four world-space corners of a flat rectangular plane. The rect spans
- * local `[x, x+width] × [y, y+height]` on the z=0 plane; each corner is
- * rotated about the rect's local origin `(x, y)` by the Euler orientation,
- * then translated to `world` (the plane's composed world anchor minus its own
- * local x/y, so rotation pivots on the anchor). Winding: TL, TR, BR, BL.
+ * Camera `x`/`y` are world coordinates (the center-origin frame makes a
+ * resting camera sit on the optical axis through world (0, 0)). Absent POI
+ * is a pass-through (one-node camera, unchanged); a partial POI is a loud
+ * defect. The user's rotation fields are never written back — derivation
+ * happens here, at view-assembly time.
  */
-export declare const planeCorners: (rect: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}, orientation: {
-    rotX: number;
-    rotY: number;
-    rotZ: number;
-}, world: Vec3) => [Vec3, Vec3, Vec3, Vec3];
+export declare const resolveCamera: (camera: CameraView & PointOfInterest) => CameraView;
 /**
- * A world point in the camera's frame, measured relative to `origin` (the
- * viewport center). The camera's `x`/`y` are a pan *from* the origin, so a
- * resting camera (pan 0) keeps world-x/y = screen-x/y at unit scale. `+z` in
- * the result is in front of the camera: the camera looks down world -z, so a
- * resting camera at z=focalLength sees the z=0 plane at view-z = focalLength.
+ * A world point in the camera's frame. The camera's `x`/`y` are its world
+ * position (origin at the viewport center), so a resting camera keeps
+ * world-x/y = screen-x/y at unit scale. `+z` in the result is in front of
+ * the camera: the camera looks down world -z, so a resting camera at
+ * z=focalLength sees the z=0 plane at view-z = focalLength.
  */
-export declare const toView: (camera: CameraView, p: Vec3, origin: Vec2) => Vec3;
+export declare const toView: (camera: CameraView, p: Vec3) => Vec3;
 /**
- * Project a world point to screen. `origin` is the screen point the camera's
- * optical axis passes through — the viewport center — so pan/zoom read as
- * "into the middle of the shot", while a resting camera reproduces plain-2D
+ * Project a world point to screen. The camera's optical axis passes through
+ * screen (0, 0) — the viewport center — so pan/zoom read as "into the
+ * middle of the shot", while a resting camera reproduces plain-2D
  * placement. A point at or behind the camera (view-z <= 0) has no valid
  * projection; `depth` is still returned for sorting, `scale` clamps to 0.
  */
-export declare const project: (camera: CameraView, p: Vec3, origin: Vec2) => Projected;
-/**
- * The affine placement for a camera-facing billboard whose local origin is
- * `anchor`: translate the anchor's projected screen point and uniformly
- * scale by its perspective scale. Returned as SVG matrix components
- * `(a b c d e f)` — a and d carry the scale, e/f the translation — so a shape
- * authored in local space lands correctly without knowing about the camera.
- */
-export interface Affine {
-    readonly a: number;
-    readonly b: number;
-    readonly c: number;
-    readonly d: number;
-    readonly e: number;
-    readonly f: number;
-}
-export declare const billboardAffine: (proj: Projected, anchor: Vec2) => Affine;
-/**
- * Project the world-space corners of a tilted plane to a screen polygon.
- * The polygon is clipped against the near plane in view space
- * (Sutherland–Hodgman, winding preserved) before the per-vertex perspective
- * divide, so a plane crossing the camera renders its visible part instead
- * of folding — a quad straddling the plane yields up to 5 vertices; a plane
- * fully behind yields none (cull). Fully in front, this is plain per-corner
- * projection: a receding plane is a true perspective trapezoid.
- */
-export declare const projectPlane: (camera: CameraView, corners: ReadonlyArray<Vec3>, origin: Vec2) => Array<Vec2>;
-/** A projected segment: exact screen endpoints plus its single sort key. */
-export interface ProjectedSegment {
-    readonly a: Vec2;
-    readonly b: Vec2;
-    /** midpoint view-space depth of the visible (clipped) segment */
-    readonly depth: number;
-    /** perspective scale at that midpoint (focalLength / depth) */
-    readonly scale: number;
-}
-/**
- * Project a world-space segment (a skeletal shape's two endpoints) to
- * screen. Both endpoints go to view space, are clipped against the near
- * plane (lerp to z = NEAR — the 1D case of projectPlane's polygon clip),
- * and are projected individually, so a line spanning depth foreshortens
- * per endpoint. Returns `undefined` when the segment lies entirely behind
- * the near plane (cull). `depth`/`scale` come from the visible midpoint.
- */
-export declare const projectSegment: (camera: CameraView, a: Vec3, b: Vec3, origin: Vec2) => ProjectedSegment | undefined;
-/** A subpath of a skeletal path: world-space points, closed or open. */
-export interface Subpath3 {
-    readonly points: ReadonlyArray<Vec3>;
-    readonly closed: boolean;
-}
-/** A projected path: screen subpaths plus the path's single sort key. */
-export interface ProjectedPath {
-    readonly subpaths: ReadonlyArray<{
-        readonly points: ReadonlyArray<Vec2>;
-        readonly closed: boolean;
-    }>;
-    /** mean view-space depth of the near-visible points */
-    readonly depth: number;
-    /** perspective scale at that depth (focalLength / depth) */
-    readonly scale: number;
-}
-/**
- * Project a skeletal path's world-space subpaths to screen — the N-point
- * generalization of `projectSegment`. Every point goes to view space and is
- * projected individually, so a path spanning depth foreshortens per point.
- * Near-plane clipping is per subpath: a closed subpath clips as a polygon
- * (Sutherland–Hodgman, winding preserved — the tilted-plane treatment); an
- * open subpath clips per span (lerp to z = NEAR) and SPLITS into separate
- * visible pieces when interior points fall behind the plane. Returns
- * `undefined` when nothing survives (cull). `depth`/`scale` come from the
- * mean view depth of all emitted points — one key per path, the same
- * ceiling as a segment's midpoint.
- */
-export declare const projectPath: (camera: CameraView, subpaths: ReadonlyArray<Subpath3>, origin: Vec2) => ProjectedPath | undefined;
-/**
- * Clip a screen-space segment to a rectangle (Liang–Barsky). Returns the
- * clipped pair, or `undefined` when the segment lies entirely outside.
- * ThorVG's software rasterizer pays stroke cost proportional to a path's
- * full extent — offscreen included — so segments are clipped to the
- * viewport (plus a stroke margin) before painting; a near-camera line can
- * project tens of thousands of px wide otherwise (measured ~7× the cost
- * of its visible part).
- */
-export declare const clipSegmentToRect: (a: Vec2, b: Vec2, min: Vec2, max: Vec2) => readonly [Vec2, Vec2] | undefined;
+export declare const project: (camera: CameraView, p: Vec3) => Projected;
 /**
  * The view-space depth of a world point — the painter's-sort key alone.
  * With no camera rotation this is `camera.z - p.z`; rotation tilts the
- * depth axis, so the full view transform is used. Origin only shifts x/y,
- * never depth, so a zero origin suffices.
+ * depth axis, so the full view transform is used.
  */
 export declare const depthOf: (camera: CameraView, p: Vec3) => number;