@effect-motion/renderer 0.5.0

package/dist/EntityRenderer.d.ts

@@ -0,0 +1,188 @@
+import type { ThreeRaw as THREE } from "@effect-motion/three";
+import type { Effect } from "effect";
+import type { EffectMotionError, Entity } from "effect-motion";
+import type * as Images from "./Images.js";
+import type * as Text from "./Text.js";
+/**
+ * The contract for drawing one kind of entity — how you teach the renderer
+ * to draw something it does not already know.
+ *
+ * @remarks
+ * Renderers are RETAINED rather than immediate: instead of one paint
+ * function called every frame, each provides three moments in an object's
+ * life.
+ *
+ * - `build` — create the three object, once, when the instance first appears.
+ * - `update` — mutate that object when its data or world position changed.
+ *   Skipped entirely on frames where nothing changed.
+ * - `dispose` (on the returned {@link Retained}) — release GPU resources
+ *   when the instance leaves the frame.
+ *
+ * The split is what keeps a still scene cheap and, more importantly, what
+ * makes GPU resources land in a `dispose` you control: geometries,
+ * materials, and textures created in `build` are yours to free.
+ *
+ * Register renderers through the `renderers` option on either
+ * `Renderer.make` or the Node adapter's `make`; the map is merged over the
+ * built-ins by entity tag, so the same mechanism adds a new kind or
+ * overrides an existing one.
+ */
+/**
+ * A leaf's final position in scene space, with every ancestor group's
+ * translation already folded in.
+ *
+ * @remarks
+ * Absolute, not relative: a renderer never has to walk parents itself. In
+ * SCENE coordinates (x right, y up, origin at the viewport center) — pass
+ * through {@link RenderContext.toThree} to keep the boundary explicit.
+ */
+export interface World {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/**
+ * The services a renderer implementation gets from the engine: coordinate
+ * conversion, viewport size, async registration, and the shared text and
+ * image actors.
+ */
+export interface RenderContext {
+    /**
+     * Convert scene coordinates to three coordinates.
+     *
+     * @remarks
+     * The two spaces are axis-identical (x right, y up, origin at the
+     * viewport center), so this is the identity — kept as the one named
+     * boundary seam. Always position objects through this rather than
+     * assuming the equivalence at call sites.
+     */
+    readonly toThree: (x: number, y: number, z: number) => THREE.Vector3;
+    /** Current viewport width in scene units. */
+    readonly width: number;
+    /** Current viewport height in scene units. */
+    readonly height: number;
+    /**
+     * Register async work the frame must not be drawn without.
+     *
+     * @remarks
+     * `build` and `update` are synchronous, but some content is not ready
+     * immediately — a glyph layout, a texture decode. Hand that work here and
+     * the render path waits for it before presenting, so a frame never ships
+     * half-built. Failures surface in the render call's error channel.
+     */
+    readonly waitFor: (work: Effect.Effect<unknown, EffectMotionError>) => void;
+    /** The shared SDF text actor: registered fonts, the glyph atlas, layout. */
+    readonly text: Text.Text;
+    /** Decoded image textures, cached for the renderer's scope. */
+    readonly images: Images.Images;
+}
+/**
+ * One instance as it is handed to a renderer: its id, its entity data for
+ * this frame, and its composed world position.
+ *
+ * @typeParam Ent - The entity data type this renderer draws.
+ */
+export interface Leaf<Ent = Entity.Entity> {
+    readonly id: string;
+    readonly data: Ent;
+    readonly world: World;
+}
+/**
+ * What a renderer hands back from `build` and keeps for the life of an
+ * instance: the three object, its billboard behavior, and how to free it.
+ */
+export interface Retained {
+    readonly object: THREE.Object3D;
+    /**
+     * Whether the object turns to face the camera each frame.
+     *
+     * @remarks
+     * `true` keeps an authored silhouette intact under any camera orbit — a
+     * circle stays circular rather than foreshortening into an ellipse.
+     * `false` lets the object sit in the world as a real oriented plane.
+     *
+     * Mutable, because a shape can change its mind: a Rect billboards while
+     * its rotation is zero and stops the moment it tilts.
+     */
+    billboard: boolean;
+    /**
+     * Release GPU resources — geometries, materials, textures.
+     *
+     * @remarks
+     * Called when the instance leaves the frame or the renderer's scope
+     * closes. Anything allocated in `build` that holds GPU memory is freed
+     * here; three does not do it for you.
+     */
+    readonly dispose: () => void;
+}
+/**
+ * How to draw one kind of entity.
+ *
+ * @remarks
+ * See the module overview for the retained `build` / `update` / `dispose`
+ * lifecycle. Pass an implementation via the `renderers` option on
+ * `Renderer.make` or the Node adapter's `make`, keyed by entity tag.
+ *
+ * @typeParam Ent - The entity data type this renderer draws.
+ *
+ * @example
+ * Override how Circles are drawn — a flat wireframe instead of the built-in.
+ * ```typescript
+ * const wireCircle: EntityRenderer.EntityRenderer<Entity.EntityByTag<"Circle">> = {
+ * 	build: (leaf, ctx) => {
+ * 		const geometry = new THREE.CircleGeometry(leaf.data.radius, 32);
+ * 		const material = new THREE.MeshBasicMaterial({ wireframe: true });
+ * 		const object = new THREE.Mesh(geometry, material);
+ * 		object.position.copy(ctx.toThree(leaf.world.x, leaf.world.y, leaf.world.z));
+ * 		return {
+ * 			object,
+ * 			billboard: true,
+ * 			dispose: () => {
+ * 				geometry.dispose();
+ * 				material.dispose();
+ * 			},
+ * 		};
+ * 	},
+ * 	update: (retained, leaf, ctx) => {
+ * 		retained.object.position.copy(
+ * 			ctx.toThree(leaf.world.x, leaf.world.y, leaf.world.z),
+ * 		);
+ * 	},
+ * };
+ *
+ * const renderer = yield* NodeRenderer.make({
+ * 	width: 500,
+ * 	height: 300,
+ * 	renderers: { Circle: wireCircle },
+ * });
+ * ```
+ */
+export interface EntityRenderer<Ent> {
+    /**
+     * Create the three object for a newly appeared instance.
+     *
+     * @remarks
+     * Called once per instance. Anything allocated here that holds GPU memory
+     * must be released by the returned {@link Retained}'s `dispose`.
+     */
+    readonly build: (leaf: Leaf<Ent>, ctx: RenderContext) => Retained;
+    /**
+     * Mutate an existing object because its data or world position changed.
+     *
+     * @remarks
+     * Called only when something actually changed, so this is where per-frame
+     * work belongs. Mutate the retained object in place rather than replacing
+     * it — the engine holds the reference already in the scene.
+     */
+    readonly update: (retained: Retained, leaf: Leaf<Ent>, ctx: RenderContext) => void;
+}
+/**
+ * An exhaustive map from every built-in entity tag to its renderer.
+ *
+ * @remarks
+ * Exhaustive on purpose: adding an entity to the core library without a
+ * renderer here is a compile error rather than a blank space at runtime.
+ */
+export type EntityRenderers = {
+    readonly [Tag in Entity.EntityTag]: EntityRenderer<Entity.EntityByTag<Tag>>;
+};

package/dist/EntityRenderer.js

@@ -0,0 +1 @@
+export {};

package/dist/Images.d.ts

@@ -0,0 +1,68 @@
+import { ThreeRaw as THREE } from "@effect-motion/three";
+import { Deferred, Effect } from "effect";
+import { EffectMotionError } from "effect-motion";
+/**
+ * Decoded image textures, cached per renderer.
+ *
+ * @remarks
+ * Encoded bytes arrive from loader services and are decoded once per
+ * renderer scope into three textures, released when that scope closes. An
+ * image used on a thousand frames is decoded once.
+ *
+ * This module is the decode boundary. In a browser, decoding goes through
+ * the platform's own `createImageBitmap`; in Node it sniffs magic bytes and
+ * decodes PNG or JPEG with pure-JS decoders — no canvas and no native
+ * dependencies, which is what keeps headless export portable. On the Node
+ * path, PNG and JPEG are the supported formats.
+ *
+ * Decodes are forked so they overlap the rest of the frame's sync rather
+ * than blocking it, and `whenReady` on the sync actor is what waits for
+ * them before a frame is drawn.
+ */
+/** A decoded image: its GPU texture and natural pixel dimensions. */
+export interface DecodedImage {
+    readonly texture: THREE.Texture;
+    /** Natural width in pixels, before any scaling. */
+    readonly width: number;
+    /** Natural height in pixels, before any scaling. */
+    readonly height: number;
+}
+/**
+ * The per-renderer image cache. Mostly data — the API is the sibling
+ * functions ({@link register}, {@link ready}, {@link has},
+ * {@link dispose}).
+ */
+export interface Images {
+    /** internal: image id → its in-flight or completed decode */
+    readonly entries: Map<string, Deferred.Deferred<DecodedImage, EffectMotionError>>;
+}
+export declare const make: () => Images;
+export declare const has: (images: Images, id: string) => boolean;
+/**
+ * Begin decoding an image's bytes under an id.
+ *
+ * @remarks
+ * Idempotent per id: registering the same image twice does nothing the
+ * second time, and a racing decode cannot clobber the first result. The
+ * decode is forked so it overlaps the rest of the frame's sync; use
+ * {@link ready} to await the texture.
+ */
+export declare const register: (images: Images, id: string, bytes: Uint8Array<ArrayBufferLike>) => Effect.Effect<void, never, import("effect/Scope").Scope>;
+/**
+ * Await the decoded texture for an id.
+ *
+ * @remarks
+ * {@link register} must have run first — asking for an unregistered image is
+ * a defect, though in practice `Sync.resolveResources` guarantees
+ * registration for anything a frame references. A failed decode arrives as a
+ * typed error naming the image.
+ */
+export declare const ready: (images: Images, id: string) => Effect.Effect<DecodedImage, EffectMotionError>;
+/**
+ * Release every decoded texture.
+ *
+ * @remarks
+ * Called when the renderer's scope closes. Only completed decodes hold a
+ * texture — an in-flight or failed one has nothing to free.
+ */
+export declare const dispose: (images: Images) => Effect.Effect<void, never, never>;

package/dist/Images.js

@@ -0,0 +1,116 @@
+import { ThreeRaw as THREE } from "@effect-motion/three";
+import { Deferred, Effect } from "effect";
+import { EffectMotionError } from "effect-motion";
+const decodeNode = async (bytes) => {
+    const isPng = bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e;
+    const isJpeg = bytes[0] === 0xff && bytes[1] === 0xd8;
+    let rgba;
+    let width;
+    let height;
+    if (isPng) {
+        const { PNG } = await import("pngjs");
+        const png = PNG.sync.read(Buffer.from(bytes));
+        rgba = new Uint8Array(png.data);
+        width = png.width;
+        height = png.height;
+    }
+    else if (isJpeg) {
+        const jpeg = await import("jpeg-js");
+        const decoded = jpeg.decode(bytes, { useTArray: true });
+        rgba = decoded.data;
+        width = decoded.width;
+        height = decoded.height;
+    }
+    else {
+        throw new Error("unsupported image format on the Node path — PNG and JPEG are supported (headless decode is pure JS)");
+    }
+    // decoded rows are top-down; DataTexture samples v=0 at data row 0
+    // (bottom in three's UV convention) — flip rows so the image is upright
+    const flipped = new Uint8Array(rgba.length);
+    const stride = width * 4;
+    for (let y = 0; y < height; y++) {
+        flipped.set(rgba.subarray(y * stride, (y + 1) * stride), (height - 1 - y) * stride);
+    }
+    const texture = new THREE.DataTexture(flipped, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+    texture.colorSpace = THREE.SRGBColorSpace;
+    texture.minFilter = THREE.LinearFilter;
+    texture.magFilter = THREE.LinearFilter;
+    texture.needsUpdate = true;
+    return { texture, width, height };
+};
+const decodeBrowser = async (bytes) => {
+    const bitmap = await createImageBitmap(new Blob([bytes]));
+    const texture = new THREE.Texture(bitmap);
+    texture.colorSpace = THREE.SRGBColorSpace;
+    texture.needsUpdate = true;
+    return { texture, width: bitmap.width, height: bitmap.height };
+};
+/**
+ * Decode bytes to a texture, picking the platform's decoder. Internal —
+ * failures are typed and name the image.
+ */
+const decode = (id, bytes) => Effect.tryPromise({
+    try: () => typeof createImageBitmap === "undefined"
+        ? decodeNode(bytes)
+        : decodeBrowser(bytes),
+    catch: (cause) => EffectMotionError.of(`Images: decoding image "${id}" failed`, cause),
+});
+export const make = () => ({ entries: new Map() });
+export const has = (images, id) => images.entries.has(id);
+/**
+ * Begin decoding an image's bytes under an id.
+ *
+ * @remarks
+ * Idempotent per id: registering the same image twice does nothing the
+ * second time, and a racing decode cannot clobber the first result. The
+ * decode is forked so it overlaps the rest of the frame's sync; use
+ * {@link ready} to await the texture.
+ */
+export const register = Effect.fnUntraced(function* (images, id, bytes) {
+    if (images.entries.has(id)) {
+        return;
+    }
+    const deferred = yield* Deferred.make();
+    images.entries.set(id, deferred);
+    // fork: the decode overlaps sync work rather than blocking it. Its
+    // result lands in the Deferred either way, so a failure surfaces
+    // through `ready` instead of dying on an unobserved fiber.
+    yield* Effect.forkScoped(Effect.matchEffect(decode(id, bytes), {
+        onFailure: (error) => Deferred.fail(deferred, error),
+        onSuccess: (image) => Deferred.succeed(deferred, image),
+    }));
+});
+/**
+ * Await the decoded texture for an id.
+ *
+ * @remarks
+ * {@link register} must have run first — asking for an unregistered image is
+ * a defect, though in practice `Sync.resolveResources` guarantees
+ * registration for anything a frame references. A failed decode arrives as a
+ * typed error naming the image.
+ */
+export const ready = (images, id) => {
+    const entry = images.entries.get(id);
+    return entry === undefined
+        ? Effect.die(new Error(`Images: image "${id}" was not registered before use`))
+        : Deferred.await(entry);
+};
+/**
+ * Release every decoded texture.
+ *
+ * @remarks
+ * Called when the renderer's scope closes. Only completed decodes hold a
+ * texture — an in-flight or failed one has nothing to free.
+ */
+export const dispose = Effect.fnUntraced(function* (images) {
+    for (const entry of images.entries.values()) {
+        const done = yield* Deferred.isDone(entry);
+        if (!done) {
+            continue;
+        }
+        yield* Deferred.await(entry).pipe(Effect.map((image) => image.texture.dispose()), 
+        // a failed decode has no texture — nothing to release
+        Effect.ignore);
+    }
+    images.entries.clear();
+});

package/dist/RenderException.d.ts

@@ -0,0 +1,29 @@
+declare const RenderException_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RenderException";
+} & Readonly<A>;
+/**
+ * A malformed scene graph, found while walking a frame.
+ *
+ * @remarks
+ * Raised for four situations, each an authoring bug rather than a
+ * recoverable condition:
+ *
+ * - an instance referenced more than once (a duplicate parent, or a cycle);
+ * - a reference to an instance id that is not in the frame;
+ * - a `Hud` nested inside world content, when it must be a top-level child
+ *   of the root or of another Hud;
+ * - an entity whose kind has no registered renderer.
+ *
+ * The message names the offending instance. It arrives as a typed error
+ * rather than a thrown exception: the walk itself throws to escape a deep
+ * recursion, but that is caught once at the sync seam so callers never see
+ * an exception cross an unrelated Effect boundary.
+ */
+export declare class RenderException extends RenderException_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+    /** Build the error with a message and an optional underlying cause. */
+    static of(message: string, cause?: unknown): RenderException;
+}
+export {};

package/dist/RenderException.js

@@ -0,0 +1,25 @@
+import { Data } from "effect";
+/**
+ * A malformed scene graph, found while walking a frame.
+ *
+ * @remarks
+ * Raised for four situations, each an authoring bug rather than a
+ * recoverable condition:
+ *
+ * - an instance referenced more than once (a duplicate parent, or a cycle);
+ * - a reference to an instance id that is not in the frame;
+ * - a `Hud` nested inside world content, when it must be a top-level child
+ *   of the root or of another Hud;
+ * - an entity whose kind has no registered renderer.
+ *
+ * The message names the offending instance. It arrives as a typed error
+ * rather than a thrown exception: the walk itself throws to escape a deep
+ * recursion, but that is caught once at the sync seam so callers never see
+ * an exception cross an unrelated Effect boundary.
+ */
+export class RenderException extends Data.TaggedError("RenderException") {
+    /** Build the error with a message and an optional underlying cause. */
+    static of(message, cause) {
+        return new RenderException({ message, cause });
+    }
+}

package/dist/Renderer.d.ts

@@ -0,0 +1,174 @@
+import type { ThreeException } from "@effect-motion/three";
+import { Renderer as Gpu } from "@effect-motion/three";
+import { Effect, Scope } from "effect";
+import type { EffectMotionError } from "effect-motion";
+import type { Frame } from "effect-motion/Scene";
+import type { EntityRenderer } from "./EntityRenderer.js";
+import type { RenderException } from "./RenderException.js";
+import * as Sync from "./Sync.js";
+/**
+ * The browser renderer: draws frames to a canvas with WebGPU.
+ *
+ * @remarks
+ * Acquire one with {@link make} inside a `Scope`, then drive it once per
+ * frame in three steps:
+ *
+ * 1. {@link resolveResources} — make sure fonts and images the frame needs
+ *    are loaded.
+ * 2. {@link syncFrame} — bring the retained three scene in step with the
+ *    frame.
+ * 3. {@link render} — draw it.
+ *
+ * The split exists so resource loading and scene-graph work can be paid for
+ * separately from drawing; a player can sync ahead of presenting.
+ *
+ * Everything is scoped: the GPU renderer and every retained object are
+ * released when the scope closes.
+ *
+ * For headless rendering and PNG export, use
+ * `@effect-motion/renderer/node` instead.
+ */
+type AnyFrame = Frame<unknown>;
+type AnyEntityRenderer = EntityRenderer<never>;
+/**
+ * Draw every nested sub-composition into its own render target.
+ *
+ * @remarks
+ * Internal, called by both render paths before their main pass. Depth-first,
+ * so a comp nested inside another is drawn before its parent samples it, and
+ * the previously bound target is always restored — including when a render
+ * fails.
+ */
+export declare const renderCompTargets: (renderer: Gpu.Renderer, sync: Sync.Sync, pixelRatio: number) => Effect.Effect<void, ThreeException, never>;
+export interface MakeOptions {
+    /** Canvas to draw into; one is created if omitted. */
+    readonly canvas?: HTMLCanvasElement;
+    /** Logical width in CSS pixels. */
+    readonly width: number;
+    /** Logical height in CSS pixels. */
+    readonly height: number;
+    /**
+     * Device pixels per logical pixel — pass `window.devicePixelRatio` for a
+     * sharp result on a high-DPI display.
+     *
+     * @defaultValue `1`
+     */
+    readonly pixelRatio?: number;
+    /**
+     * Renderers for custom entity kinds, or overrides for built-in ones.
+     * Merged over the built-in manifest by entity tag.
+     */
+    readonly renderers?: Record<string, AnyEntityRenderer>;
+}
+/**
+ * A live browser renderer.
+ *
+ * @remarks
+ * Mostly data — the API is the sibling functions ({@link syncFrame},
+ * {@link resolveResources}, {@link render}, {@link prewarm}). `sync.stats`
+ * is useful for diagnostics: it reports how many objects are retained and
+ * how long the last sync took.
+ */
+export interface Renderer {
+    readonly sync: Sync.Sync;
+    readonly gpu: Gpu.Renderer;
+    /**
+     * The scope this renderer was acquired in. Image decodes fork into it,
+     * so they are interrupted with the renderer rather than outliving it —
+     * and callers of `resolveResources` do not have to carry a Scope of
+     * their own.
+     */
+    readonly scope: Scope.Scope;
+}
+/**
+ * Resize the drawing buffer.
+ *
+ * @remarks
+ * `width` and `height` are logical (CSS) pixels; `pixelRatio` scales to
+ * device pixels, so pass `window.devicePixelRatio` for a sharp result on a
+ * high-DPI display. Call on canvas resize.
+ */
+export declare const setViewport: {
+    (width: number, height: number, pixelRatio: number): (renderer: Renderer) => Renderer;
+    (renderer: Renderer, width: number, height: number, pixelRatio: number): Renderer;
+};
+/**
+ * Bring the retained three scene in step with a frame.
+ *
+ * @remarks
+ * This is the diff: objects new to this frame are built, ones whose data or
+ * world position changed are updated, and ones that left are disposed.
+ * Unchanged objects are skipped entirely, which is what makes a mostly-still
+ * scene cheap to hold on screen.
+ *
+ * Scene-graph problems — an instance referenced twice, an unknown id, a Hud
+ * nested inside world content, an entity with no registered renderer —
+ * arrive as a typed {@link RenderException} naming the offender rather than
+ * as a thrown exception.
+ */
+export declare const syncFrame: (renderer: Renderer, frame: AnyFrame) => Effect.Effect<void, RenderException>;
+/**
+ * Load the fonts and images a frame needs, before syncing it.
+ *
+ * @remarks
+ * Resources are resolved from the CALLER's context, so the loaders a scene
+ * declared must be provided around this call. Work is done once per resource
+ * per renderer: already-loaded fonts and images are skipped.
+ *
+ * The built-in default font is auto-provided, so plain text needs no setup.
+ * A font or image the frame references with no loader in context is a defect
+ * naming the id and the `Font.layer` / `Image.layer` call that would fix it.
+ */
+export declare const resolveResources: (renderer: Renderer, frame: AnyFrame) => Effect.Effect<void>;
+/**
+ * Draw the current retained scene to the canvas.
+ *
+ * @remarks
+ * Call after {@link syncFrame}. Before drawing, this waits for the async
+ * work that sync registered — glyph layouts and image decodes — so a frame
+ * never presents half-built text or a missing texture. A failed layout or
+ * decode surfaces as a typed error naming the resource.
+ *
+ * Nested sub-compositions are drawn to their own render targets first, then
+ * the world, then any HUD content composited on top through an identity
+ * camera so it ignores camera movement.
+ *
+ * Depth of field is not applied: every frame renders sharp, regardless of a
+ * camera's `aperture`.
+ */
+export declare const render: (renderer: Renderer) => Effect.Effect<void, ThreeException | EffectMotionError>;
+/**
+ * Compile shader pipelines ahead of showing anything.
+ *
+ * @remarks
+ * Call once after the first {@link syncFrame} and before revealing the
+ * canvas. WebGPU compiles a pipeline the first time it is used, which would
+ * otherwise land as a visible hitch on frame one; doing it here moves that
+ * cost into startup.
+ */
+export declare const prewarm: (renderer: Renderer) => Effect.Effect<void, ThreeException>;
+/**
+ * Acquire a renderer for a canvas.
+ *
+ * @remarks
+ * Scoped: the GPU device and every retained object are disposed when the
+ * scope closes, so a player that mounts and unmounts leaks nothing.
+ *
+ * Pass `renderers` to draw entity kinds the built-ins do not cover, or to
+ * override how a built-in kind is drawn — the map is merged over the
+ * built-in manifest by entity tag.
+ *
+ * @param options - Canvas, dimensions, pixel ratio, and any custom entity
+ *   renderers.
+ * @returns A renderer, valid for the current scope.
+ *
+ * @example
+ * ```typescript
+ * const renderer = yield* Renderer.make({ canvas, width: 500, height: 300 });
+ * yield* Renderer.resolveResources(renderer, frame);
+ * yield* Renderer.syncFrame(renderer, frame);
+ * yield* Renderer.render(renderer);
+ * ```
+ */
+export declare const make: (options: MakeOptions) => Effect.Effect<Renderer, ThreeException, Scope.Scope>;
+export {};