effect-motion 0.2.0 → 0.3.0

package/dist/Images.js

@@ -0,0 +1,24 @@
+import * as Context from "effect/Context";
+/**
+ * Scene annotation key declaring the images a scene's Image entities depend
+ * on: `scene.annotate(Images.Images, [...])`. The runtime never reads it —
+ * decoded pixels cannot affect frame data. Consumers (the player, export
+ * tools) read it to load assets into their render session before playback.
+ */
+export const Images = Context.Reference("motion/Images", { defaultValue: () => [] });
+/** A scene's declared images — empty for scenes never annotated. */
+export const get = (scene) => Context.get(scene.annotations, Images);
+/**
+ * A scene's declared images as a `name -> url` map for the render session's
+ * `images` option. Only entries with a `src.url` are included — loading is
+ * fetch-by-URL (no filesystem), so `path`-only entries are skipped.
+ */
+export const urlMap = (scene) => {
+    const out = {};
+    for (const image of get(scene)) {
+        if (image.src.url !== undefined) {
+            out[image.name] = image.src.url;
+        }
+    }
+    return out;
+};

package/dist/Instance.d.ts

@@ -1,16 +1,16 @@
 import * as Effect from "effect/Effect";
 import * as Pipeable from "effect/Pipeable";
 import type * as Schema from "effect/Schema";
-import type * as Entity from "./Entity";
+import type * as Entity from "./Entity.js";
 export declare const TypeId: "~motion/Instance";
 export interface Instance<Name extends string = string, Data extends Schema.Top = Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> = {}> extends Pipeable.Pipeable {
     readonly [TypeId]: typeof TypeId;
     readonly id: string;
-    readonly entity: Entity.Entity<Name, Data, Traits, any>;
+    readonly entity: Entity.Entity<Name, Data, Traits>;
 }
 /** the Instance type of a given entity, traits included */
-export type Of<E extends Entity.AnyEntity> = E extends Entity.Entity<infer Name, infer Data, infer Traits, any> ? Instance<Name, Data, Traits> : never;
+export type Of<E extends Entity.AnyEntity> = E extends Entity.Entity<infer Name, infer Data, infer Traits> ? Instance<Name, Data, Traits> : never;
 export declare const isInstance: (u: unknown) => u is Instance;
-export declare const make: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>, MakeInput>(entity: Entity.Entity<Name, Data, Traits, MakeInput>, id: string) => Instance<Name, Data, Traits>;
+export declare const make: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>>(entity: Entity.Entity<Name, Data, Traits>, id: string) => Instance<Name, Data, Traits>;
 export type InstanceOrEffect<Name extends string = string, Data extends Schema.Top = Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> = {}, E = never, R = never> = Instance<Name, Data, Traits> | Effect.Effect<Instance<Name, Data, Traits>, E, R>;
 export declare const flatten: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>, E = never, R = never>(instance: InstanceOrEffect<Name, Data, Traits, E, R>) => Effect.Effect<Instance<Name, Data, Traits>, E, R>;

package/dist/Motion.d.ts

@@ -1,17 +1,23 @@
 import type * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import type * as Schema from "effect/Schema";
-import * as Entity from "./Entity";
-import * as Instance from "./Instance";
-import * as Runner from "./Runner";
-import * as Timing from "./Timing";
-export type InterpolableValue = number;
+import * as Color from "./Color.js";
+import * as Entity from "./Entity.js";
+import * as Instance from "./Instance.js";
+import * as Runner from "./Runner.js";
+import * as Timing from "./Timing.js";
+export declare const color: (to: Color.Color, mode: Color.InterpolationMode) => (from: Color.Color, t: number) => Color.Color;
+type ColorInterpolator = (from: Color.Color, t: number) => Color.Color;
+export type InterpolableValue = number | Color.Color;
 type InterpolableKeys<T> = {
-    [K in keyof T]: T[K] extends InterpolableValue ? K : never;
+    [K in keyof T]-?: NonNullable<T[K]> extends InterpolableValue ? K : never;
 }[keyof T];
 export type InterpolableOnly<T> = Pick<T, InterpolableKeys<T>>;
+type InterpolableOrInterpolator<T> = {
+    [K in keyof T]-?: NonNullable<T[K]> extends number ? number : NonNullable<T[K]> extends Color.Color ? Color.Color | ColorInterpolator : never;
+};
 /** target props, or an updater computing them from the current data */
-export type Target<Data extends Schema.Top> = Partial<InterpolableOnly<Data["Type"]>> | ((data: Data["Type"]) => Partial<InterpolableOnly<Data["Type"]>>);
+export type Target<Data extends Schema.Top> = Partial<InterpolableOrInterpolator<Data["Type"]>> | ((data: Data["Type"]) => Partial<InterpolableOrInterpolator<Data["Type"]>>);
 export declare const resolveTarget: <Data extends Schema.Top>(target: Target<Data>, current: Data["Type"]) => Record<string, number>;
 export declare const startValues: (current: unknown, target: Record<string, number>, explicitFrom: Record<string, number>) => Record<string, number>;
 /**
@@ -23,6 +29,17 @@ export declare const startValues: (current: unknown, target: Record<string, numb
  * instance, so animations chain.
  */
 export declare const tweenTo: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>>(to: Target<Data>, duration: Duration.Input, timing?: Timing.TimingInput) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>) & (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, to: Target<Data>, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
+/**
+ * Parametric animator: each frame applies `fn` with the eased parameter
+ * and the current data, then ticks. The final frame receives exactly
+ * `t = 1` for any timing with f(1) = 1; a zero-length duration still
+ * takes one frame. This is the primitive under coordinated multi-field
+ * motion — arcs, orbits, counters — where independent per-field tweens
+ * cannot express the coupling. Determinism: `fn` sees only `(t, data)`.
+ * Dual: `drive(instance, duration, timing, fn)` or
+ * `instance.pipe(drive(duration, timing, fn))`.
+ */
+export declare const drive: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>>(duration: Duration.Input, timing: Timing.TimingInput, fn: (t: number, data: Data["Type"]) => Data["Type"]) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>) & (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, duration: Duration.Input, timing: Timing.TimingInput, fn: (t: number, data: Data["Type"]) => Data["Type"]) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
 /**
  * Like `tweenTo`, but with an explicit start: interpolates the keys of
  * `to` from `from` (keys missing in `from` start at the current data).

package/dist/Motion.js

@@ -1,14 +1,21 @@
 import * as Effect from "effect/Effect";
 import * as Effectable from "effect/Effectable";
 import { dual } from "effect/Function";
-import * as Entity from "./Entity";
-import * as Instance from "./Instance";
-import * as Runner from "./Runner";
-import * as Scene from "./Scene";
-import * as Time from "./Time";
-import * as Timing from "./Timing";
+import * as Color from "./Color.js";
+import * as Entity from "./Entity.js";
+import * as Instance from "./Instance.js";
+import * as Runner from "./Runner.js";
+import * as Scene from "./Scene.js";
+import * as Time from "./Time.js";
+import * as Timing from "./Timing.js";
+export const color = (to, mode) => {
+    return (from, t) => Color.mix(from, to, t, mode);
+};
 // extrapolating on purpose: eased t goes outside [0, 1] for back/elastic
 const lerpNumber = (from, to, t) => from + (to - from) * t;
+const lerpColor = (from, to, t, mode) => {
+    return Color.mix(from, to, t, mode);
+};
 /**
  * The interpolation engine: from `from` to `to` over `duration`, calling
  * `fn` with the eased value once per frame (each step ends in a
@@ -25,7 +32,18 @@ const interpolate = Effect.fnUntraced(function* (from, to, duration, fn, timing
         const t = timingFn(i / frames);
         const value = {};
         for (const key of keys) {
-            value[key] = lerpNumber(from[key], to[key], t);
+            const fromValue = from[key];
+            const toValue = to[key];
+            if (typeof toValue === "number") {
+                value[key] = lerpNumber(from[key], to[key], t);
+            }
+            else if (typeof toValue === "function") {
+                const interpolator = toValue;
+                value[key] = interpolator(fromValue, t);
+            }
+            else {
+                value[key] = lerpColor(fromValue, toValue, t, "lab");
+            }
         }
         yield* fn(value);
         yield* Scene.tick;
@@ -42,8 +60,13 @@ export const resolveTarget = (target, current) => (typeof target === "function"
 export const startValues = (current, target, explicitFrom) => {
     const start = {};
     for (const key of Object.keys(target)) {
-        start[key] =
-            explicitFrom[key] ?? current[key];
+        const from = explicitFrom[key] ?? current[key];
+        // an optional field that was never set has no start value — lerping
+        // from undefined would silently produce NaN frames; die loudly instead
+        if (from === undefined) {
+            throw new Error(`tween: "${key}" has no current value to start from — pass an explicit from`);
+        }
+        start[key] = from;
     }
     return start;
 };
@@ -69,6 +92,28 @@ const firstArgIsInstance = (args) => Instance.isInstance(args[0]);
  * instance, so animations chain.
  */
 export const tweenTo = dual(firstArgIsInstance, (instance, to, duration, timing) => animate(instance, undefined, to, duration, timing));
+/**
+ * Parametric animator: each frame applies `fn` with the eased parameter
+ * and the current data, then ticks. The final frame receives exactly
+ * `t = 1` for any timing with f(1) = 1; a zero-length duration still
+ * takes one frame. This is the primitive under coordinated multi-field
+ * motion — arcs, orbits, counters — where independent per-field tweens
+ * cannot express the coupling. Determinism: `fn` sees only `(t, data)`.
+ * Dual: `drive(instance, duration, timing, fn)` or
+ * `instance.pipe(drive(duration, timing, fn))`.
+ */
+export const drive = dual(firstArgIsInstance, Effect.fnUntraced(function* (instanceOrEffect, duration, timing, fn) {
+    const instance = yield* Instance.flatten(instanceOrEffect);
+    const runner = yield* Runner.Runner;
+    const timingFn = Timing.resolve(timing);
+    const frames = Math.max(1, Time.toFrames(duration, runner.settings.frameRate));
+    for (let i = 1; i <= frames; i++) {
+        const t = timingFn(i / frames);
+        yield* Scene.update(instance, (data) => fn(t, data));
+        yield* Scene.tick;
+    }
+    return instance;
+}));
 /**
  * Like `tweenTo`, but with an explicit start: interpolates the keys of
  * `to` from `from` (keys missing in `from` start at the current data).

package/dist/Phaser.d.ts

@@ -44,7 +44,7 @@ export declare class Phaser extends Phaser_base {
  * during a sequential handoff or before the scene starts. The slot is
  * released by a finalizer on success, failure, and interrupt alike.
  */
-export declare const run: <A, E, R>(phaser: Phaser["Service"], scene: Effect.Effect<A, E, R>) => Effect.Effect<import("effect/Fiber").Fiber<A, E>, never, Exclude<R, Phaser>>;
+export declare const run: <A, E = never, R = never>(phaser: Phaser["Service"], scene: Effect.Effect<A, E, R>) => Effect.Effect<import("effect/Fiber").Fiber<A, E>, never, Exclude<R, Phaser>>;
 /**
  * Run `effect`, then arrive at the phase boundary.
  *

package/dist/Phaser.js

@@ -14,7 +14,7 @@ export class Phaser extends Context.Service()("motion/Phaser", {
         let arrived = 0;
         let phaseLatch = Latch.makeUnsafe();
         let state = "idle";
-        let waiter = null;
+        const waiters = new Set();
         // The single invariant. Every event that touches `arrived` or
         // `parties` re-runs this.
         const checkQuiescence = () => {
@@ -40,10 +40,12 @@ export class Phaser extends Context.Service()("motion/Phaser", {
                     return;
                 }
                 case "running": {
-                    const resume = waiter;
-                    waiter = null;
                     state = "idle";
-                    resume?.();
+                    const copy = new Set(waiters);
+                    waiters.clear();
+                    for (const waiter of copy) {
+                        waiter();
+                    }
                     return;
                 }
             }
@@ -69,11 +71,13 @@ export class Phaser extends Context.Service()("motion/Phaser", {
             })));
         }));
         const awaitAdvance = Effect.callback((resume) => {
-            if (waiter !== null) {
-                resume(Effect.die(new Error("Phaser: concurrent awaitAdvance — single controller only")));
-                return;
+            const waiter = () => resume(Effect.succeed(phase));
+            waiters.add(waiter);
+            if (waiters.size > 1) {
+                return Effect.sync(() => {
+                    waiters.delete(waiter);
+                });
             }
-            waiter = () => resume(Effect.succeed(phase));
             if (arrived === parties) {
                 // quiescent: arm an advance so parties run the next phase
                 state = "pending";
@@ -87,7 +91,7 @@ export class Phaser extends Context.Service()("motion/Phaser", {
             }
             return Effect.sync(() => {
                 // interrupted while suspended
-                waiter = null;
+                waiters.delete(waiter);
                 state = "idle";
             });
         });

package/dist/Physics.d.ts

@@ -1,8 +1,8 @@
 import * as Effect from "effect/Effect";
 import type * as Schema from "effect/Schema";
-import * as Entity from "./Entity";
-import * as Instance from "./Instance";
-import * as Runner from "./Runner";
+import * as Entity from "./Entity.js";
+import * as Instance from "./Instance.js";
+import * as Runner from "./Runner.js";
 /**
  * Physics-based motion: durationless animations that carry momentum and
  * end on their own. A spring is a damped harmonic oscillator simulated

package/dist/Physics.js

@@ -1,9 +1,9 @@
 import * as Effect from "effect/Effect";
 import { dual } from "effect/Function";
-import * as Entity from "./Entity";
-import * as Instance from "./Instance";
-import * as Runner from "./Runner";
-import * as Scene from "./Scene";
+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 */
 export const defaultSpring = {
     mass: 0.05,

package/dist/PngExporter.d.ts

@@ -0,0 +1,6 @@
+import * as Effect from "effect/Effect";
+import { FileSystem } from "effect/FileSystem";
+import { EffectMotionError } from "./EffectMotionError.js";
+import type * as Renderer from "./Renderer.js";
+export declare const toBuffer: (fb: Renderer.Framebuffer) => Effect.Effect<Uint8Array<ArrayBuffer>, EffectMotionError, never>;
+export declare const toFile: (fb: Renderer.Framebuffer, outPath: string) => Effect.Effect<void, EffectMotionError | import("effect/PlatformError").PlatformError, FileSystem>;

package/dist/PngExporter.js

@@ -0,0 +1,85 @@
+import { deflateSync } from "node:zlib";
+import * as Effect from "effect/Effect";
+import { FileSystem } from "effect/FileSystem";
+import { EffectMotionError } from "./EffectMotionError.js";
+const SIGNATURE = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
+const crcTable = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) {
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+const crc32 = (bytes) => {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) {
+        c = crcTable[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    }
+    return (c ^ 0xffffffff) >>> 0;
+};
+const chunk = (type, data) => {
+    const typeBytes = new Uint8Array([
+        type.charCodeAt(0),
+        type.charCodeAt(1),
+        type.charCodeAt(2),
+        type.charCodeAt(3),
+    ]);
+    const body = new Uint8Array(typeBytes.length + data.length);
+    body.set(typeBytes, 0);
+    body.set(data, typeBytes.length);
+    const out = new Uint8Array(4 + body.length + 4);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, data.length, false);
+    out.set(body, 4);
+    view.setUint32(4 + body.length, crc32(body), false);
+    return out;
+};
+/** Encode a raw RGBA8888 buffer (`width * height * 4` bytes) as a PNG. */
+const encodePng = Effect.fnUntraced(function* (rgba, width, height) {
+    if (rgba.length !== width * height * 4) {
+        return yield* Effect.fail(EffectMotionError.of(`Could not encode PNG: buffer is ${rgba.length} bytes, expected ${width * height * 4} (${width}x${height} RGBA)`));
+    }
+    // prepend a filter byte (0 = none) to each scanline
+    const stride = width * 4;
+    const raw = new Uint8Array((stride + 1) * height);
+    for (let y = 0; y < height; y++) {
+        raw[y * (stride + 1)] = 0;
+        raw.set(rgba.subarray(y * stride, y * stride + stride), y * (stride + 1) + 1);
+    }
+    const ihdr = new Uint8Array(13);
+    const ihdrView = new DataView(ihdr.buffer);
+    ihdrView.setUint32(0, width, false);
+    ihdrView.setUint32(4, height, false);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 6; // color type: RGBA
+    // [10] compression, [11] filter, [12] interlace all 0
+    const idat = new Uint8Array(deflateSync(raw));
+    const chunks = [
+        SIGNATURE,
+        chunk("IHDR", ihdr),
+        chunk("IDAT", idat),
+        chunk("IEND", new Uint8Array(0)),
+    ];
+    const total = chunks.reduce((n, c) => n + c.length, 0);
+    const png = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        png.set(c, offset);
+        offset += c.length;
+    }
+    return png;
+});
+export const toBuffer = (fb) => {
+    return encodePng(fb.rgba, fb.width, fb.height);
+};
+export const toFile = (fb, outPath) => {
+    return Effect.gen(function* () {
+        const fs = yield* FileSystem;
+        const png = yield* toBuffer(fb);
+        yield* fs.writeFile(outPath, png);
+    });
+};

package/dist/Projection.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Perspective projection — pure math shared by every sink, usable without
+ * the Effect runtime. No wall-clock, no RNG: projecting the same camera and
+ * 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.
+ *
+ * Identity invariant: the default camera (see `defaultFocalLength` and
+ * `defaultCameraZ`) projects a world point at `z = 0` to screen `(x, y)` at
+ * scale 1 — so a scene that never touches depth renders exactly as the old
+ * plain-2D pipeline did. That falls out of placing the resting camera a
+ * focal-length back on +z and dividing by focal length at the z=0 plane —
+ * and holds for ANY focal length, which is why the default can be
+ * width-relative without breaking plain-2D scenes.
+ */
+export interface Vec3 {
+    readonly x: number;
+    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;
+    readonly y: number;
+    readonly z: number;
+    readonly rotX: number;
+    readonly rotY: number;
+    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.
+     */
+    readonly focusDistance: number;
+    /** depth-of-field blur strength; 0 (the default) = pinhole, DoF off */
+    readonly aperture: number;
+}
+/**
+ * A projected point: screen position, the view-space depth used as the
+ * painter's-sort key (larger = farther from the camera), and the uniform
+ * `scale` a billboard at this point receives (focalLength / depth).
+ */
+export interface Projected {
+    readonly x: number;
+    readonly y: number;
+    readonly depth: number;
+    readonly scale: number;
+}
+/**
+ * Default focal length (px) for a comp of the given width — After Effects'
+ * default lens: 50mm on 36mm-wide film, so `zoom = width × 50/36`. Width-
+ * relative so perspective strength (how much a given z moves/scales a shape)
+ * reads the same at every output resolution.
+ */
+export declare const defaultFocalLength: (width: number) => number;
+/**
+ * The resting camera sits this far back on +z, looking toward -z, so that
+ * the `z = 0` plane is exactly `focalLength` in front of it — the identity
+ * invariant. A camera authored without a `z` uses this.
+ */
+export declare const defaultCameraZ: (focalLength: number) => number;
+/** Optional point of interest carried beside a camera view (world coords). */
+export interface PointOfInterest {
+    readonly poiX?: number;
+    readonly poiY?: number;
+    readonly poiZ?: number;
+}
+/**
+ * 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
+ * (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.
+ */
+export declare const lookAtOrientation: (position: Vec3, poi: Vec3) => {
+    rotX: number;
+    rotY: number;
+};
+/**
+ * The effective camera view: when a point of interest is set, auto-orient
+ * toward it with the explicit Euler composing AFTER the aim — the After
+ * Effects two-node rule. "After" means the user's rotation applies in the
+ * 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.
+ */
+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];
+/**
+ * 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 declare const toView: (camera: CameraView, p: Vec3, origin: Vec2) => 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
+ * 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;
+/**
+ * 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.
+ */
+export declare const depthOf: (camera: CameraView, p: Vec3) => number;