effect-motion 0.4.0 → 0.5.0

package/dist/Projection.js

@@ -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
@@ -102,8 +104,7 @@ const rotate = (v, rx, ry, rz) => {
 };
 /**
  * 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.
@@ -125,13 +126,13 @@ export const lookAtOrientation = (position, poi) => {
  * 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.
+ * 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 const resolveCamera = (camera, origin) => {
+export const resolveCamera = (camera) => {
     const { poiX, poiY, poiZ } = camera;
     const present = [poiX, poiY, poiZ].filter((v) => v !== undefined).length;
     if (present === 0) {
@@ -141,8 +142,8 @@ export const resolveCamera = (camera, origin) => {
         throw new Error("Camera: a point of interest requires all of poiX, poiY, poiZ — got a partial POI");
     }
     const world = {
-        x: origin.x + camera.x,
-        y: origin.y + camera.y,
+        x: camera.x,
+        y: camera.y,
         z: camera.z,
     };
     const aim = lookAtOrientation(world, {
@@ -173,301 +174,41 @@ export const resolveCamera = (camera, origin) => {
     return { ...camera, rotX, rotY, rotZ };
 };
 /**
- * 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.
+ * 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 const planeCorners = (rect, orientation, world) => {
-    const { rotX, rotY, rotZ } = orientation;
-    // local corners relative to the rect's own origin (the rotation pivot)
-    const local = [
-        { x: 0, y: 0 },
-        { x: rect.width, y: 0 },
-        { x: rect.width, y: rect.height },
-        { x: 0, y: rect.height },
-    ];
-    const place = (c) => {
-        const r = rotate({ x: c.x, y: c.y, z: 0 }, rotX, rotY, rotZ);
-        return { x: world.x + r.x, y: world.y + r.y, z: world.z + r.z };
-    };
-    return [place(local[0]), place(local[1]), place(local[2]), place(local[3])];
-};
-/**
- * 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.
- */
-export const toView = (camera, p, origin) => {
+export const toView = (camera, p) => {
     const translated = {
-        x: p.x - origin.x - camera.x,
-        y: p.y - origin.y - camera.y,
+        x: p.x - camera.x,
+        y: p.y - camera.y,
         z: camera.z - p.z, // flip so in-front is +z (camera looks toward -world-z)
     };
     return rotateInverse(translated, camera.rotX, camera.rotY, camera.rotZ);
 };
 /**
- * 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 const project = (camera, p, origin) => {
-    const v = toView(camera, p, origin);
+export const project = (camera, p) => {
+    const v = toView(camera, p);
     const depth = v.z;
     const scale = depth > 0 ? camera.focalLength / depth : 0;
     return {
-        x: origin.x + v.x * scale,
-        y: origin.y + v.y * scale,
+        x: v.x * scale,
+        y: v.y * scale,
         depth,
         scale,
     };
 };
-export const billboardAffine = (proj, anchor) => ({
-    a: proj.scale,
-    b: 0,
-    c: 0,
-    d: proj.scale,
-    // place the anchor's local coords at the projected screen point
-    e: proj.x - anchor.x * proj.scale,
-    f: proj.y - anchor.y * proj.scale,
-});
-/**
- * View-space depth (px) of the near clip plane. A tilted plane can be
- * PARTIALLY behind the camera — projecting a corner at depth <= 0 is
- * meaningless (the old code pinned it to the viewport center, folding the
- * polygon), so the polygon is clipped against this plane first. 1px keeps
- * the worst-case projected scale bounded at `focalLength` per unit.
- */
-const NEAR = 1;
-/**
- * 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 const projectPlane = (camera, corners, origin) => {
-    const view = corners.map((c) => toView(camera, c, origin));
-    return clipPolygonNear(view).map((v) => {
-        const scale = camera.focalLength / v.z;
-        return { x: origin.x + v.x * scale, y: origin.y + v.y * scale };
-    });
-};
-/**
- * Sutherland–Hodgman clip of a view-space polygon against the near plane,
- * winding preserved. Shared by tilted planes and closed path subpaths.
- */
-const clipPolygonNear = (view) => {
-    const clipped = [];
-    for (let i = 0; i < view.length; i++) {
-        // biome-ignore lint/style/noNonNullAssertion: i and (i+1)%length are in bounds
-        const a = view[i];
-        // biome-ignore lint/style/noNonNullAssertion: see above
-        const b = view[(i + 1) % view.length];
-        const aIn = a.z >= NEAR;
-        if (aIn) {
-            clipped.push(a);
-        }
-        if (aIn !== b.z >= NEAR) {
-            const t = (NEAR - a.z) / (b.z - a.z);
-            clipped.push({
-                x: a.x + (b.x - a.x) * t,
-                y: a.y + (b.y - a.y) * t,
-                z: NEAR,
-            });
-        }
-    }
-    return clipped;
-};
-/**
- * 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 const projectSegment = (camera, a, b, origin) => {
-    let va = toView(camera, a, origin);
-    let vb = toView(camera, b, origin);
-    if (va.z < NEAR && vb.z < NEAR) {
-        return undefined;
-    }
-    const clip = (inside, outside) => {
-        const t = (NEAR - inside.z) / (outside.z - inside.z);
-        return {
-            x: inside.x + (outside.x - inside.x) * t,
-            y: inside.y + (outside.y - inside.y) * t,
-            z: NEAR,
-        };
-    };
-    if (va.z < NEAR) {
-        va = clip(vb, va);
-    }
-    else if (vb.z < NEAR) {
-        vb = clip(va, vb);
-    }
-    const toScreen = (v) => {
-        const s = camera.focalLength / v.z;
-        return { x: origin.x + v.x * s, y: origin.y + v.y * s };
-    };
-    const depth = (va.z + vb.z) / 2;
-    return {
-        a: toScreen(va),
-        b: toScreen(vb),
-        depth,
-        scale: camera.focalLength / depth,
-    };
-};
-/**
- * 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 const projectPath = (camera, subpaths, origin) => {
-    const pieces = [];
-    for (const subpath of subpaths) {
-        const view = subpath.points.map((p) => toView(camera, p, origin));
-        if (subpath.closed) {
-            const clipped = clipPolygonNear(view);
-            if (clipped.length >= 2) {
-                pieces.push({ points: clipped, closed: true });
-            }
-            continue;
-        }
-        // open: walk the spans, clipping and splitting at the near plane
-        let current = [];
-        const clip = (a, b) => {
-            const t = (NEAR - a.z) / (b.z - a.z);
-            return {
-                x: a.x + (b.x - a.x) * t,
-                y: a.y + (b.y - a.y) * t,
-                z: NEAR,
-            };
-        };
-        const flush = () => {
-            if (current.length >= 2) {
-                pieces.push({ points: current, closed: false });
-            }
-            current = [];
-        };
-        for (let i = 0; i + 1 < view.length; i++) {
-            // biome-ignore lint/style/noNonNullAssertion: i and i+1 are in bounds
-            const a = view[i];
-            // biome-ignore lint/style/noNonNullAssertion: see above
-            const b = view[i + 1];
-            const aIn = a.z >= NEAR;
-            const bIn = b.z >= NEAR;
-            if (aIn) {
-                if (current.length === 0) {
-                    current.push(a);
-                }
-                if (bIn) {
-                    current.push(b);
-                }
-                else {
-                    current.push(clip(a, b));
-                    flush();
-                }
-            }
-            else if (bIn) {
-                current = [clip(b, a), b];
-            }
-        }
-        flush();
-    }
-    if (pieces.length === 0) {
-        return undefined;
-    }
-    let depthSum = 0;
-    let depthCount = 0;
-    for (const piece of pieces) {
-        for (const v of piece.points) {
-            depthSum += v.z;
-            depthCount++;
-        }
-    }
-    const depth = depthSum / depthCount;
-    const toScreen = (v) => {
-        const s = camera.focalLength / v.z;
-        return { x: origin.x + v.x * s, y: origin.y + v.y * s };
-    };
-    return {
-        subpaths: pieces.map((piece) => ({
-            points: piece.points.map(toScreen),
-            closed: piece.closed,
-        })),
-        depth,
-        scale: camera.focalLength / depth,
-    };
-};
-/**
- * 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 const clipSegmentToRect = (a, b, min, max) => {
-    const dx = b.x - a.x;
-    const dy = b.y - a.y;
-    let t0 = 0;
-    let t1 = 1;
-    const edges = [
-        [-dx, a.x - min.x],
-        [dx, max.x - a.x],
-        [-dy, a.y - min.y],
-        [dy, max.y - a.y],
-    ];
-    for (const [p, q] of edges) {
-        if (p === 0) {
-            // parallel to this edge: outside it means fully outside
-            if (q < 0) {
-                return undefined;
-            }
-            continue;
-        }
-        const r = q / p;
-        if (p < 0) {
-            if (r > t1) {
-                return undefined;
-            }
-            if (r > t0) {
-                t0 = r;
-            }
-        }
-        else {
-            if (r < t0) {
-                return undefined;
-            }
-            if (r < t1) {
-                t1 = r;
-            }
-        }
-    }
-    const at = (t) => ({ x: a.x + dx * t, y: a.y + dy * t });
-    return [t0 === 0 ? a : at(t0), t1 === 1 ? b : at(t1)];
-};
 /**
  * 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 const depthOf = (camera, p) => toView(camera, p, { x: 0, y: 0 }).z;
+export const depthOf = (camera, p) => toView(camera, p).z;

package/dist/Resource.d.ts

@@ -0,0 +1,26 @@
+import * as Effect from "effect/Effect";
+import { EffectMotionError } from "./EffectMotionError.js";
+/**
+ * The shared loader brand. Every loader service (FontLoader, ImageLoader,
+ * future kinds) carries it, and it is the ONLY thing they share: loader
+ * shapes stay separate per kind (fonts grow font metadata, images image
+ * metadata) so nothing over-abstracts, while the type utilities below are
+ * written once against the brand.
+ */
+export declare const LoaderTypeId: "~effect-motion/Resources/Loader";
+export interface LoaderBrand {
+    readonly [LoaderTypeId]: typeof LoaderTypeId;
+}
+/**
+ * The loader members of a requirements union — what a scene's frames carry
+ * as `Frame<Resources>` and what the renderer requires. Distributes:
+ * `FontLoader<"a"> | Runner` → `FontLoader<"a">`.
+ */
+export type ExtractLoaders<R> = R extends LoaderBrand ? R : never;
+/**
+ * A requirements union with the loader members removed — what running a
+ * scene actually needs. Frames are pure of resource bytes (the engine
+ * cannot measure text), so `Scene.run`/`stream` require only this.
+ */
+export type ExcludeLoaders<R> = R extends LoaderBrand ? never : R;
+export declare const fetchBytes: (url: string) => Effect.Effect<Uint8Array, EffectMotionError>;

package/dist/Resource.js

@@ -0,0 +1,41 @@
+import * as Effect from "effect/Effect";
+import { EffectMotionError } from "./EffectMotionError.js";
+/**
+ * The shared loader brand. Every loader service (FontLoader, ImageLoader,
+ * future kinds) carries it, and it is the ONLY thing they share: loader
+ * shapes stay separate per kind (fonts grow font metadata, images image
+ * metadata) so nothing over-abstracts, while the type utilities below are
+ * written once against the brand.
+ */
+export const LoaderTypeId = "~effect-motion/Resources/Loader";
+/**
+ * Fetch a resource's bytes by URL — the common browser-side load effect for
+ * `Font.layer`/`Image.layer`. Fails with a typed error naming the URL, so a
+ * bad source surfaces at layer construction (e.g. the player's error
+ * state), never at frame time. Compose retries on top as needed.
+ *
+ * Memoized per URL at module level: asset bytes are immutable, and layers
+ * rebuild per Player mount (studio scene switches), so each URL is fetched
+ * at most once per process. A FAILED fetch is not cached — the next
+ * construction retries. Custom load effects cache themselves (this pattern)
+ * when they should.
+ */
+const fetchCache = new Map();
+export const fetchBytes = (url) => Effect.tryPromise({
+    try: () => {
+        let pending = fetchCache.get(url);
+        if (pending === undefined) {
+            pending = fetch(url).then(async (response) => {
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                return new Uint8Array(await response.arrayBuffer());
+            });
+            // evict on failure so a transient error can retry
+            pending.catch(() => fetchCache.delete(url));
+            fetchCache.set(url, pending);
+        }
+        return pending;
+    },
+    catch: (cause) => EffectMotionError.of(`Resource fetch failed: ${url}`, cause),
+});