effect-motion 0.3.2 → 0.5.0

package/dist/Camera.js

@@ -1,85 +1,352 @@
 import { Effect } from "effect";
-import * as Schema from "effect/Schema";
+import * as Duration from "effect/Duration";
+import * as Function from "effect/Function";
 import * as Entity from "./Entity.js";
-import * as Projection from "./Projection.js";
-import * as Shape2D from "./shapes/Shape2D.js";
+import * as Instance from "./Instance.js";
+import * as Motion from "./Motion.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";
+// a target argument (vs a duration/timing in the same slot): instances,
+// effects, or a position-like object — Durations are objects too, so
+// exclude them explicitly
+const isTargetArg = (v) => Instance.isInstance(v) ||
+    Effect.isEffect(v) ||
+    (typeof v === "object" &&
+        v !== null &&
+        !Duration.isDuration(v) &&
+        ("x" in v || "y" in v || "z" in v));
+// data-first iff the first arg is an instance AND the second is a target —
+// plain firstArgIsInstance would misread `cam.pipe`-less pipeable calls
+// whose TARGET is an instance (`lookAt(hero, "1 second")`)
+const dataFirst = (args) => Instance.isInstance(args[0]) && isTargetArg(args[1]);
 /**
- * The camera is view state, not a shape — it is never registered with a sink
- * and never drawn. It exists as an ordinary Instance so the existing
- * animators drive it for free: `camera.pipe(moveTo({ z: -800 }))`,
- * `tween("rotY", ...)`, `spring`, `Scene.fork`, etc.
- *
- * `~position` (now x/y/z) is the camera's world position; `rotX/rotY/rotZ`
- * are its Euler orientation; `focalLength` sets the field of view. At rest
- * the camera sits a focal-length back on +z looking down world -z, so a
- * world point at z=0 projects to plain-2D screen coordinates — see
- * `Projection.ts`. The sink reads these off `FrameMeta.camera` and projects
- * every instance through them; instance data stays in world coordinates, so
- * determinism and `moveTo` semantics are untouched by the camera.
- *
- * `z` and `focalLength` have no static schema default: the right resting
- * values are width-relative (After Effects' 50mm-equivalent — see
- * `Projection.defaultFocalLength`), and only the Runner knows the scene
- * width. The Runner fills both at instantiate time for every Camera
- * instance, so by the time animators or the renderer read the data they are
- * always concrete.
+ * Resolve a target once (Effects yield their Instance), returning a
+ * per-frame position reader with the offset folded in: live for
+ * instances, fixed for plain positions.
  */
-const fields = {
-    x: Shape2D.defaultedNumber(0),
-    y: Shape2D.defaultedNumber(0),
-    z: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
-    rotX: Shape2D.defaultedNumber(0),
-    rotY: Shape2D.defaultedNumber(0),
-    rotZ: Shape2D.defaultedNumber(0),
-    focalLength: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
-    // depth of field: view-space distance to the sharp plane, and blur
-    // strength. Like z/focalLength, focusDistance's right default is
-    // width-relative (the resting distance, so z=0 is in focus) — the Runner
-    // fills it. aperture 0 = pinhole = DoF off (explicit opt-in).
-    focusDistance: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
-    aperture: Shape2D.defaultedNumber(0),
-    // Optional point of interest (world coordinates): when present the camera
-    // auto-orients toward it and explicit Euler composes AFTER the aim (the
-    // AE two-node model — see Projection.resolveCamera). Flat numeric fields
-    // so tween/spring drive the aim like any other field. NOT Runner-filled:
-    // absent = today's one-node camera, byte-identical (explicit opt-in).
-    poiX: Schema.optionalKey(Schema.Number),
-    poiY: Schema.optionalKey(Schema.Number),
-    poiZ: Schema.optionalKey(Schema.Number),
+const targetReader = Effect.fnUntraced(function* (target, offset) {
+    const ox = offset?.x ?? 0;
+    const oy = offset?.y ?? 0;
+    const oz = offset?.z ?? 0;
+    if (Instance.isInstance(target) || Effect.isEffect(target)) {
+        const instance = yield* Instance.flattenInstance(target);
+        return Scene.data(instance).pipe(Effect.map((data) => {
+            const p = data.position;
+            return { x: p.x + ox, y: p.y + oy, z: p.z + oz };
+        }));
+    }
+    // AnyInstance's `any` params defeat narrowing — the guards above
+    // returned for instances/effects, so this is a plain position
+    const point = target;
+    const fixed = {
+        x: (point.x ?? 0) + ox,
+        y: (point.y ?? 0) + oy,
+        z: (point.z ?? 0) + oz,
+    };
+    return Effect.succeed(fixed);
+});
+const setPoi = (data, p) => ({
+    ...data,
+    poi: Entity.vec3(p),
+});
+// the camera's WORLD position (center-origin frame: position IS world)
+const worldPosition = Effect.fnUntraced(function* (cam) {
+    const data = yield* Scene.data(cam);
+    return {
+        x: data.position.x,
+        y: data.position.y,
+        z: data.position.z,
+    };
+});
+const lookAtImpl = Effect.fnUntraced(function* (camOrEffect, target, duration, timing, offset) {
+    const cam = yield* Instance.flattenInstance(camOrEffect);
+    const read = yield* targetReader(target, offset);
+    if (duration === undefined) {
+        const p = yield* read;
+        yield* Scene.update(cam, (d) => setPoi(d, p));
+        return cam;
+    }
+    // eased re-aim: a RETARGETED tween — each frame interpolates from the
+    // start POI toward the target's CURRENT position, converging exactly
+    // onto a moving target at t = 1 (a plain-Position target degenerates to
+    // a fixed tween). Effectful per-frame read, so this runs its own loop
+    // rather than Motion.drive (whose callback is pure).
+    const runner = yield* Runner.Runner;
+    const timingFn = Timing.resolve(timing ?? "linear");
+    const data = yield* Scene.data(cam);
+    let start;
+    if (data.poi !== null) {
+        start = data.poi;
+    }
+    else {
+        // no POI yet: seed on the camera's UNAIMED axis (straight down world
+        // -z) at the target's distance. resolveCamera derives zero aim for
+        // that point, so the explicit Euler alone carries the view — engaging
+        // POI mode is snap-free for ANY current orientation, and the tween
+        // takes over from there.
+        const world = yield* worldPosition(cam);
+        const first = yield* read;
+        const distance = Math.hypot(first.x - world.x, first.y - world.y, first.z - world.z);
+        start = { x: world.x, y: world.y, z: world.z - distance };
+    }
+    const frames = Math.max(1, Time.toFrames(duration, runner.settings.frameRate));
+    for (let i = 1; i <= frames; i++) {
+        const t = timingFn(i / frames);
+        const p = yield* read;
+        yield* Scene.update(cam, (d) => setPoi(d, {
+            x: start.x + (p.x - start.x) * t,
+            y: start.y + (p.y - start.y) * t,
+            z: start.z + (p.z - start.z) * t,
+        }));
+        yield* Scene.tick;
+    }
+    return cam;
+});
+/**
+ * Point the camera at something.
+ *
+ * @remarks
+ * Aiming is expressed as a point of interest rather than as rotation
+ * angles, which is what makes it composable: the target can be a live
+ * instance, and the camera keeps facing it as it moves. There is no
+ * `lookAtTo` — the verb already names its target — so an optional
+ * `duration` selects between the two behaviors:
+ *
+ * - **Omitted** — aim snaps this frame. Use it to establish the shot before
+ *   anything moves.
+ * - **Given** — the aim eases over that time as a RETARGETED tween: each
+ *   frame interpolates toward the target's current position, so it converges
+ *   exactly onto a moving target with no snap at the end.
+ *
+ * Setting a point of interest is also the prerequisite for
+ * {@link orbitTo} and {@link dollyTo}, which are both defined relative to it.
+ *
+ * @param target - An instance to track, or a fixed world position.
+ * @param duration - Omit to snap; give a time to ease the re-aim.
+ * @param timing - An easing name or function.
+ * @param offset - Shifts the aim relative to the target, e.g. slightly above.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The camera, so animators chain.
+ *
+ * @example
+ * Snap to establish, then ease across to a second subject.
+ * ```typescript
+ * const camera = yield* Scene.camera;
+ * yield* camera.pipe(Camera.lookAt(hero));
+ * yield* camera.pipe(Camera.lookAt(villain, "1 second", "easeInOutCubic"));
+ * ```
+ */
+export const lookAt = Function.dual(dataFirst, lookAtImpl);
+/**
+ * Keep the camera locked onto a moving target for `duration`.
+ *
+ * @remarks
+ * Where {@link lookAt} with a duration EASES toward a target and stops,
+ * `follow` holds the aim on it: every frame copies the target's position, so
+ * the subject stays pinned while it moves. Run it concurrently with the
+ * subject's own animation — typically inside `Scene.all` or a `Scene.fork`.
+ *
+ * There is no timing parameter, because tracking is a hard per-frame copy
+ * rather than an interpolation. For a lagging, weighted camera, animate the
+ * point of interest with a spring instead.
+ *
+ * Ordering note: within a frame, branches run in the order they were forked.
+ * A follow forked BEFORE its target's animator reads the previous frame's
+ * position — a deterministic one-frame trail, not a bug.
+ *
+ * @param target - An instance to track, or a fixed world position.
+ * @param duration - How long to keep tracking.
+ * @param offset - Shifts the aim relative to the target.
+ * @returns The camera, so animators chain.
+ *
+ * @example
+ * Track the runner for the two seconds it is crossing frame.
+ * ```typescript
+ * yield* Scene.all([
+ * 	runner.pipe(Motion.moveTo({ x: 900 }, "2 seconds")),
+ * 	camera.pipe(Camera.follow(runner, "2 seconds")),
+ * ]);
+ * ```
+ */
+export const follow = Function.dual(dataFirst, Effect.fnUntraced(function* (camOrEffect, target, duration, offset) {
+    const cam = yield* Instance.flattenInstance(camOrEffect);
+    const read = yield* targetReader(target, offset);
+    const runner = yield* Runner.Runner;
+    const frames = Math.max(1, Time.toFrames(duration, runner.settings.frameRate));
+    for (let i = 1; i <= frames; i++) {
+        const p = yield* read;
+        yield* Scene.update(cam, (d) => setPoi(d, p));
+        yield* Scene.tick;
+    }
+    return cam;
+}));
+// orbit/dolly are defined relative to the POI — die loudly without one
+const poiOrDie = (data) => {
+    if (data.poi === null) {
+        throw new Error("Camera: orbit/dolly need a point of interest — set one first (Camera.lookAt(target))");
+    }
+    return data.poi;
 };
-export const Camera = Entity.make("Camera", fields, {
-    // x/y/z is the camera position; rotation + focalLength are raw numeric
-    // fields animated via tween. Inlined (not positionLens()) so the data
-    // type flows into the lens.
-    "~position": {
-        // z is filled by the Runner at instantiate; the ?? 0 is unreachable,
-        // it only satisfies the optional schema type
-        get: (data) => ({ x: data.x, y: data.y, z: data.z ?? 0 }),
-        set: (data, value) => ({
-            ...data,
-            x: value.x,
-            y: value.y,
-            z: value.z,
-        }),
-    },
+const orbitImpl = Effect.fnUntraced(function* (camOrEffect, from, to, duration, timing) {
+    const cam = yield* Instance.flattenInstance(camOrEffect);
+    const startData = yield* Scene.data(cam);
+    const poi = poiOrDie(startData);
+    const world = {
+        x: startData.position.x,
+        z: startData.position.z,
+    };
+    // azimuth 0 = directly +z of the POI (the resting side); positive sweeps
+    // by the right-hand rule about world +y (+z toward +x). radius = the
+    // current horizontal distance, preserved through the arc; height too
+    const radius = Math.hypot(world.x - poi.x, world.z - poi.z);
+    const startAzimuth = from ?? Math.atan2(world.x - poi.x, world.z - poi.z);
+    return yield* Motion.drive(cam, duration, timing ?? "linear", (t, d) => {
+        const data = d;
+        // POI read from live data: orbiting a moving POI stays centered on it
+        const p = poiOrDie(data);
+        const angle = startAzimuth + (to - startAzimuth) * t;
+        return {
+            ...d,
+            position: Entity.vec3({
+                x: p.x + radius * Math.sin(angle),
+                y: d.position.y,
+                z: p.z + radius * Math.cos(angle),
+            }),
+        };
+    });
 });
 /**
- * The identity view for a comp of the given width: resting camera, no
- * rotation, the width-relative default focal length (AE's 50mm equivalent).
- * Projects z=0 content to its plain-2D screen position at scale 1.
+ * Swing the camera around its point of interest, like a turntable.
+ *
+ * @remarks
+ * The camera travels an arc at a fixed radius and height while continuing to
+ * face the subject — the standard "orbit the product" move. Only the
+ * position is animated; the aim follows from the point of interest, so there
+ * is no orientation math to get wrong.
+ *
+ * `azimuth` is an ABSOLUTE angle in radians about the world-Y axis through
+ * the point of interest, where 0 is directly in front (+z of it). A full
+ * turn is `Math.PI * 2`; the sign chooses direction.
+ *
+ * Requires a point of interest — call {@link lookAt} first, or this fails
+ * loudly telling you so.
+ *
+ * @param azimuth - Target angle in radians; 0 is directly in front.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The camera, so animators chain.
+ * @see {@link orbit} to start from an explicit angle.
+ *
+ * @example
+ * A quarter turn around a subject.
+ * ```typescript
+ * yield* camera.pipe(
+ * 	Camera.lookAt(subject),
+ * 	Camera.orbitTo(Math.PI / 2, "2 seconds", "easeInOutCubic"),
+ * );
+ * ```
+ */
+export const orbitTo = Function.dual((args) => Instance.isInstance(args[0]), ((cam, azimuth, duration, timing) => orbitImpl(cam, undefined, azimuth, duration, timing)));
+/**
+ * Like {@link orbitTo}, but starting from an explicit azimuth.
+ *
+ * @remarks
+ * Stating both ends is what makes a full revolution expressible: `orbit(0,
+ * Math.PI * 2, …)` sweeps all the way around, whereas `orbitTo(Math.PI * 2)`
+ * from a resting camera would already be at its target and not move.
+ *
+ * @param from - Starting angle in radians.
+ * @param to - Target angle in radians.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @returns The camera, so animators chain.
+ *
+ * @example
+ * One full revolution.
+ * ```typescript
+ * yield* camera.pipe(Camera.orbit(0, Math.PI * 2, "4 seconds"));
+ * ```
  */
-export const identity = (width) => {
-    const focalLength = Projection.defaultFocalLength(width);
-    return {
-        x: 0,
-        y: 0,
-        z: Projection.defaultCameraZ(focalLength),
-        rotX: 0,
-        rotY: 0,
-        rotZ: 0,
-        focalLength,
-        // the z=0 plane in focus, no depth of field
-        focusDistance: Projection.defaultCameraZ(focalLength),
-        aperture: 0,
+export const orbit = Function.dual((args) => Instance.isInstance(args[0]), orbitImpl);
+const dollyImpl = Effect.fnUntraced(function* (camOrEffect, from, to, duration, timing) {
+    const cam = yield* Instance.flattenInstance(camOrEffect);
+    const startData = yield* Scene.data(cam);
+    const poi = poiOrDie(startData);
+    const world = {
+        x: startData.position.x,
+        y: startData.position.y,
+        z: startData.position.z,
     };
-};
+    const startDistance = Math.hypot(world.x - poi.x, world.y - poi.y, world.z - poi.z);
+    // the fixed unit direction POI → camera; a zero distance has no
+    // direction to dolly along
+    if (startDistance === 0) {
+        throw new Error("Camera: dolly from distance 0 — the camera sits ON its point of interest, so there is no view axis to move along");
+    }
+    const u = {
+        x: (world.x - poi.x) / startDistance,
+        y: (world.y - poi.y) / startDistance,
+        z: (world.z - poi.z) / startDistance,
+    };
+    const d0 = from ?? startDistance;
+    return yield* Motion.drive(cam, duration, timing ?? "linear", (t, d) => {
+        const data = d;
+        const p = poiOrDie(data);
+        const dist = d0 + (to - d0) * t;
+        return {
+            ...d,
+            position: Entity.vec3({
+                x: p.x + u.x * dist,
+                y: p.y + u.y * dist,
+                z: p.z + u.z * dist,
+            }),
+        };
+    });
+});
+/**
+ * Move the camera toward or away from its point of interest along the view
+ * axis.
+ *
+ * @remarks
+ * A push-in or pull-back that keeps the subject centered and the aim
+ * unchanged — only the distance changes. Distinct from tweening the camera's
+ * `z`, which moves along the WORLD axis and would slide the subject off
+ * center once the camera is aimed obliquely.
+ *
+ * Requires a point of interest — call {@link lookAt} first.
+ *
+ * @param distance - Target distance from the point of interest; smaller is
+ *   closer.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The camera, so animators chain.
+ * @see {@link dolly} to start from an explicit distance.
+ *
+ * @example
+ * Push in on a subject.
+ * ```typescript
+ * yield* camera.pipe(
+ * 	Camera.lookAt(subject),
+ * 	Camera.dollyTo(300, "1500 millis", "easeInOutCubic"),
+ * );
+ * ```
+ */
+export const dollyTo = Function.dual((args) => Instance.isInstance(args[0]), ((cam, distance, duration, timing) => dollyImpl(cam, undefined, distance, duration, timing)));
+/**
+ * Like {@link dollyTo}, but starting from an explicit distance.
+ *
+ * @remarks
+ * For a push-in that begins further out than the camera currently sits —
+ * the move starts at `from` regardless of where the camera was left.
+ *
+ * @param from - Starting distance from the point of interest.
+ * @param to - Target distance.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @returns The camera, so animators chain.
+ */
+export const dolly = Function.dual((args) => Instance.isInstance(args[0]), dollyImpl);

package/dist/Color.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Colors: construction, adjustment, and conversion.
+ *
+ * @remarks
+ * Reach for {@link hex} for CSS strings, {@link rgba} for byte components,
+ * or {@link tw} for the built-in Tailwind palette. Perceptual spaces
+ * ({@link oklch}, {@link lab}) are available when you want even lightness
+ * across hues.
+ *
+ * Values are immutable and every adjustment is a dual, so operations
+ * compose in either call style. Colors interpolate, so any fill or stroke
+ * animates with the ordinary tween animators.
+ *
+ * @example
+ * ```typescript
+ * import * as Color from "effect-motion/Color";
+ *
+ * const brand = Color.hex("#7f5af0");
+ * const dim = brand.pipe(Color.darken(0.6), Color.alpha(0.75));
+ * ```
+ */
 import chroma from "chroma-js";
 import { Schema } from "effect";
 import * as Pipeable from "effect/Pipeable";
@@ -8,6 +29,21 @@ declare const Color_base: Schema.Class<Color, Schema.TaggedStruct<"Color", {
     readonly "~b": Schema.Number;
     readonly "~a": Schema.Number;
 }>, {}>;
+/**
+ * A color with an alpha channel.
+ *
+ * @remarks
+ * Build one with a constructor below — {@link hex} for CSS strings,
+ * {@link rgba} for byte components, {@link tw} for the Tailwind palette —
+ * rather than the class directly.
+ *
+ * RGB channels are 0–255 while alpha is 0–1, matching CSS. Colors are
+ * immutable and pipeable, so adjustments compose:
+ * `Color.hex("#7f5af0").pipe(Color.darken(0.5), Color.alpha(0.8))`.
+ *
+ * Colors are interpolable, so any fill or stroke can be animated with the
+ * ordinary tween animators.
+ */
 export declare class Color extends Color_base implements Pipeable.Pipeable {
     static of(r: number, g: number, b: number, a?: number): Color;
     get r(): number;
@@ -16,9 +52,33 @@ export declare class Color extends Color_base implements Pipeable.Pipeable {
     get a(): number;
     pipe: Pipeable.Pipeable["pipe"];
 }
+/** Whether `value` is a {@link Color}. */
 export declare const is: (value: unknown) => value is Color;
+/**
+ * A color from red, green, blue (each 0–255) and optional alpha (0–1).
+ *
+ * @defaultValue `alpha` — `1`
+ *
+ * @example
+ * ```typescript
+ * Color.rgba(22, 22, 29)
+ * ```
+ */
 export declare const rgba: (r: number, g: number, b: number, alpha?: number) => Color;
-/** Parse a CSS color string (`#rgb`, `#rrggbb`, `#rrggbbaa`, named, `rgb()`, …). */
+/**
+ * Parse a CSS color string — the most convenient constructor.
+ *
+ * @remarks
+ * Accepts everything CSS does: `#rgb`, `#rrggbb`, `#rrggbbaa`, named colors
+ * like `"rebeccapurple"`, and functional forms like `rgb()` / `hsl()`.
+ *
+ * @param value - A CSS color string.
+ *
+ * @example
+ * ```typescript
+ * Color.hex("#7f5af0")
+ * ```
+ */
 export declare const hex: (value: string) => Color;
 export declare const hsl: (h: number, s: number, l: number, alpha?: number) => Color;
 export declare const hsv: (h: number, s: number, v: number, alpha?: number) => Color;
@@ -29,10 +89,15 @@ export declare const oklab: (l: number, a: number, b: number, alpha?: number) =>
 export declare const oklch: (l: number, c: number, h: number, alpha?: number) => Color;
 export declare const cmyk: (c: number, m: number, y: number, k: number) => Color;
 export declare const gl: (g: number, l: number, r: number, alpha?: number) => Color;
+/** Set a color's opacity (0–1), leaving its channels untouched. */
 export declare const alpha: ((amount: number) => (self: Color) => Color) & ((self: Color, amount: number) => Color);
+/** Darken by `amount` steps in Lab space. @defaultValue `amount` — `1` */
 export declare const darken: ((amount?: number) => (self: Color) => Color) & ((self: Color, amount?: number) => Color);
+/** Brighten by `amount` steps in Lab space. @defaultValue `amount` — `1` */
 export declare const brighten: ((amount?: number) => (self: Color) => Color) & ((self: Color, amount?: number) => Color);
+/** Increase saturation by `amount` steps. @defaultValue `amount` — `1` */
 export declare const saturate: ((amount?: number) => (self: Color) => Color) & ((self: Color, amount?: number) => Color);
+/** Reduce saturation by `amount` steps. @defaultValue `amount` — `1` */
 export declare const desaturate: ((amount?: number) => (self: Color) => Color) & ((self: Color, amount?: number) => Color);
 export type ChannelMap = {
     rgb: "r" | "g" | "b";
@@ -48,6 +113,18 @@ export type ChannelMap = {
     oklab: "l" | "a" | "b";
     oklch: "l" | "c" | "h";
 };
+/**
+ * Blend two colors, `amount` of the way from `self` to `color`.
+ *
+ * @remarks
+ * `mode` picks the color space the blend travels through, which changes the
+ * intermediate hues considerably: `"lab"` (the animators' default) keeps
+ * perceptual evenness, while `"rgb"` can pass through muddy midpoints.
+ *
+ * @param color - The color to blend toward.
+ * @param amount - 0 keeps `self`, 1 gives `color`.
+ * @param mode - Interpolation space.
+ */
 export declare const mix: ((color: Color, amount: number, mode?: chroma.InterpolationMode) => (self: Color) => Color) & ((self: Color, color: Color, amount: number, mode?: chroma.InterpolationMode) => Color);
 export declare const shade: ((amount?: number, mode?: chroma.InterpolationMode) => (self: Color) => Color) & ((self: Color, amount?: number, mode?: chroma.InterpolationMode) => Color);
 export declare const tint: ((amount?: number, mode?: chroma.InterpolationMode) => (self: Color) => Color) & ((self: Color, amount?: number, mode?: chroma.InterpolationMode) => Color);
@@ -80,8 +157,14 @@ export declare const bytes: (self: Color) => {
     b: number;
     a: number;
 };
+/** Opaque black. */
 export declare const black: Color;
+/** Opaque white. */
 export declare const white: Color;
+/**
+ * Fully transparent — the default scene background, which leaves whatever
+ * is behind the composition showing through.
+ */
 export declare const transparent: Color;
 export declare const twMap: {
     readonly slate: {
@@ -424,5 +507,22 @@ export declare const twMap: {
     };
 };
 type TwColor = keyof typeof twMap;
+/**
+ * A color from the Tailwind palette.
+ *
+ * @remarks
+ * A ready-made, perceptually even set of hues — handy for getting a scene
+ * looking coherent without hand-picking values.
+ *
+ * @param color - Palette name, e.g. `"violet"`.
+ * @param shade - Lightness step, `"50"` (lightest) to `"950"` (darkest).
+ * @param alpha - Opacity, 0–1.
+ * @defaultValue `shade` — `"400"`; `alpha` — `1`
+ *
+ * @example
+ * ```typescript
+ * Color.tw("violet", "500")
+ * ```
+ */
 export declare const tw: (color: TwColor, shade?: "50" | "100" | "200" | "300" | "400" | "500" | "600" | "700" | "800" | "900" | "950", alpha?: number) => Color;
 export {};