effect-motion 0.2.0 → 0.3.0

package/dist/Projection.js

@@ -0,0 +1,473 @@
+/**
+ * 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.
+ */
+/**
+ * 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 const defaultFocalLength = (width) => (width * 50) / 36;
+/**
+ * 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 const defaultCameraZ = (focalLength) => focalLength;
+// ── Euler rotation ──────────────────────────────────────────────────────
+// Rotate a vector by the camera's inverse orientation (world → view). The
+// camera's own rotation is applied X→Y→Z; the view transform is its inverse,
+// so we negate the angles and apply Z→Y→X. Small hand-rolled rotations beat
+// a general matrix lib here (ponytail: only these three axes are ever used).
+const rotateInverse = (v, rx, ry, rz) => {
+    let { x, y, z } = v;
+    // inverse of Rz
+    if (rz !== 0) {
+        const c = Math.cos(-rz);
+        const s = Math.sin(-rz);
+        const nx = x * c - y * s;
+        const ny = x * s + y * c;
+        x = nx;
+        y = ny;
+    }
+    // inverse of Ry
+    if (ry !== 0) {
+        const c = Math.cos(-ry);
+        const s = Math.sin(-ry);
+        const nx = x * c + z * s;
+        const nz = -x * s + z * c;
+        x = nx;
+        z = nz;
+    }
+    // inverse of Rx
+    if (rx !== 0) {
+        const c = Math.cos(-rx);
+        const s = Math.sin(-rx);
+        const ny = y * c - z * s;
+        const nz = y * s + z * c;
+        y = ny;
+        z = nz;
+    }
+    return { x, y, z };
+};
+/**
+ * Rotate a vector by an Euler orientation (X→Y→Z), the forward transform
+ * used to orient a shape's local plane into world space. Mirror of
+ * `rotateInverse`.
+ */
+const rotate = (v, rx, ry, rz) => {
+    let { x, y, z } = v;
+    if (rx !== 0) {
+        const c = Math.cos(rx);
+        const s = Math.sin(rx);
+        const ny = y * c - z * s;
+        const nz = y * s + z * c;
+        y = ny;
+        z = nz;
+    }
+    if (ry !== 0) {
+        const c = Math.cos(ry);
+        const s = Math.sin(ry);
+        const nx = x * c + z * s;
+        const nz = -x * s + z * c;
+        x = nx;
+        z = nz;
+    }
+    if (rz !== 0) {
+        const c = Math.cos(rz);
+        const s = Math.sin(rz);
+        const nx = x * c - y * s;
+        const ny = x * s + y * c;
+        x = nx;
+        y = ny;
+    }
+    return { x, y, z };
+};
+/**
+ * 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 const lookAtOrientation = (position, poi) => {
+    const dx = poi.x - position.x;
+    const dy = poi.y - position.y;
+    const dz = position.z - poi.z; // flipped: in-front is +z
+    const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (len === 0) {
+        return { rotX: 0, rotY: 0 };
+    }
+    return { rotY: Math.atan2(dx, dz), rotX: -Math.asin(dy / len) };
+};
+/**
+ * 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 const resolveCamera = (camera, origin) => {
+    const { poiX, poiY, poiZ } = camera;
+    const present = [poiX, poiY, poiZ].filter((v) => v !== undefined).length;
+    if (present === 0) {
+        return camera;
+    }
+    if (present !== 3) {
+        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,
+        z: camera.z,
+    };
+    const aim = lookAtOrientation(world, {
+        x: poiX,
+        y: poiY,
+        z: poiZ,
+    });
+    // aim only: return the derived angles exactly (no fp noise from the
+    // compose/extract round-trip in the common case)
+    if (camera.rotX === 0 && camera.rotY === 0 && camera.rotZ === 0) {
+        return { ...camera, rotX: aim.rotX, rotY: aim.rotY };
+    }
+    // exact composition M = Aim · UserEuler: the user rotation applied in
+    // camera-local space, then aimed — additive angles would roll about the
+    // WORLD axis and drag the POI off-center. Build M's columns with the
+    // same rotate() the pipeline uses, then extract ZYX Euler angles
+    // (rotate ≡ Rz·Ry·Rx, canonical right-handed forms).
+    const compose = (v) => rotate(rotate(v, camera.rotX, camera.rotY, camera.rotZ), aim.rotX, aim.rotY, 0);
+    const c0 = compose({ x: 1, y: 0, z: 0 });
+    const c1 = compose({ x: 0, y: 1, z: 0 });
+    const c2 = compose({ x: 0, y: 0, z: 1 });
+    const rotY = -Math.asin(Math.max(-1, Math.min(1, c0.z)));
+    // gimbal (camera pitched straight up/down): yaw and roll degenerate —
+    // pick roll = 0 and fold everything into pitch
+    const gimbal = Math.abs(c0.z) > 0.999999;
+    const rotX = gimbal ? Math.atan2(-c1.x, c1.y) : Math.atan2(c1.z, c2.z);
+    const rotZ = gimbal ? 0 : Math.atan2(c0.y, c0.x);
+    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.
+ */
+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) => {
+    const translated = {
+        x: p.x - origin.x - camera.x,
+        y: p.y - origin.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
+ * 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);
+    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,
+        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.
+ */
+export const depthOf = (camera, p) => toView(camera, p, { x: 0, y: 0 }).z;

package/dist/Renderer.d.ts

@@ -1,69 +1,118 @@
-import { Layer } from "effect";
-import * as Context from "effect/Context";
+import type { OwnedPaint, RenderSession, ThorvgException, ThorvgWasm } from "@effect-motion/thorvg";
+import * as Tvg from "@effect-motion/thorvg";
+import type { Canvas } from "@effect-motion/thorvg/Canvas";
 import * as Effect from "effect/Effect";
-import type * as Entity from "./Entity";
-import type { EntriesFromEntities, Frame } from "./Scene";
-/** Renders one entity instance to the renderer's per-entity output. */
-export type RenderFunction<Success, Ent extends Entity.AnyEntity, E = never, R = never> = (payload: {
-    entity: Ent;
-    id: string;
-    data: Ent["data"]["Type"];
-    /**
-     * rendered output of this instance's children, post-order (empty for
-     * leaves). In frame data, a `children: string[]` field means child
-     * instance ids — containers embed these results in their own output.
-     */
-    children: ReadonlyArray<Success>;
-}) => Effect.Effect<Success, E, R>;
-/** the frame's render metadata, handed to sink render functions */
+import type * as Scope from "effect/Scope";
+import * as Color from "./Color.js";
+import type * as Entity from "./Entity.js";
+import * as Projection from "./Projection.js";
+import type { Frame } from "./Scene.js";
+/**
+ * The projection handed to each paint function — how the camera places a
+ * paintable this frame. `screen` is the projected billboard placement (an
+ * affine the paint fn applies via `setTransform`); `depth` is the view-space
+ * sort key; `scale` is the perspective scale (<= 0 means the anchor is behind
+ * the camera — cull, unless a `quad` or `segment` is present). `quad`, when
+ * present, is the projected, near-plane-clipped screen polygon of a tilted
+ * plane (3–5 vertices — see Projection.projectPlane); a shape that can tilt
+ * paints an exact path from these instead of applying the billboard affine.
+ * `segment`, when present, is the exact projected screen endpoints of a
+ * skeletal shape (Line) — each endpoint carries its own world depth, so the
+ * pair is projected per point (see Projection.projectSegment) and the paint
+ * fn draws it directly, skipping the billboard affine. `subpaths`, when
+ * present, is the projected screen geometry of a skeletal path (Path): every
+ * command point projected individually and near-plane-clipped per subpath
+ * (see Projection.projectPath) — the paint fn emits it directly at screen
+ * coordinates.
+ */
+export interface PaintProjection {
+    readonly screen: Projection.Affine;
+    readonly depth: number;
+    readonly scale: number;
+    readonly quad?: ReadonlyArray<Projection.Vec2>;
+    readonly segment?: readonly [Projection.Vec2, Projection.Vec2];
+    readonly subpaths?: Projection.ProjectedPath["subpaths"];
+}
+/** The frame's render metadata, handed to paint functions. */
 export interface FrameMeta {
     readonly frameRate: number;
     readonly width: number;
     readonly height: number;
-    readonly backgroundColor: string;
+    readonly backgroundColor: Color.Color;
     /**
-     * the active camera's view — `{x, y}` pan in world units, `zoom` a
-     * uniform scale (1 = identity). Sinks apply it per top-level layer,
-     * scaled by that layer's `depth`. Absent camera work leaves this at
-     * identity `{0, 0, 1}` and output is unchanged.
+     * the active camera's view — world position `{x, y, z}`, Euler
+     * orientation `{rotX, rotY, rotZ}`, and `focalLength` (FOV). The renderer
+     * projects every instance through it. The resting camera (see
+     * Camera.identity) reproduces plain-2D placement for z=0 content.
      */
     readonly camera: {
         readonly x: number;
         readonly y: number;
-        readonly zoom: number;
+        readonly z: number;
+        readonly rotX: number;
+        readonly rotY: number;
+        readonly rotZ: number;
+        readonly focalLength: number;
     };
 }
-export interface EntityRenderer<Name extends string, Success, Ent extends Entity.AnyEntity, E, R> {
-    readonly name: Name;
-    readonly render: RenderFunction<Success, Ent, E, R>;
+/**
+ * Paints one entity instance onto the shared ThorVG scene. It issues ThorVG
+ * C-API calls (make a shape, append geometry, style it, apply the projection,
+ * add it to `scene`) — there is no intermediate description value. A container
+ * (Group / root) paints nothing itself; its position has already composed into
+ * its children's world coordinates by the time this is called.
+ */
+export type PaintFunction<Ent extends Entity.AnyEntity> = (payload: {
+    readonly entity: Ent;
+    readonly id: string;
+    readonly data: Ent["data"]["Type"];
+    readonly projection: PaintProjection;
+    readonly canvas: Canvas;
+    readonly scene: OwnedPaint;
+    readonly meta: FrameMeta;
+}) => Effect.Effect<void, ThorvgException, ThorvgWasm | RenderSession | Scope.Scope>;
+/**
+ * A registry of paint functions keyed by entity name. `PaintFunctions<E>` is
+ * the exhaustive map over an entity union — a built-in with no paint function
+ * is a type error at the render call, not a runtime surprise (the old
+ * "coverage manifest" guarantee, kept without a Context registry).
+ */
+export type PaintFunctions<Entities extends Entity.AnyEntity> = {
+    readonly [K in Entities as K["name"]]: PaintFunction<K>;
+};
+/** RGBA8888 framebuffer plus its dimensions, straight from the SW canvas. */
+export interface Framebuffer {
+    readonly rgba: Uint8Array;
+    /** physical pixel size of the rgba buffer (logical size × dpr) */
+    readonly width: number;
+    readonly height: number;
+    /**
+     * logical scene size — the resolution the buffer should be displayed at
+     * (CSS pixels). Equals width/height when rendered at dpr 1.
+     */
+    readonly logicalWidth: number;
+    readonly logicalHeight: number;
 }
-type RendererName<Tag extends string, Ent extends Entity.AnyEntity> = `${Tag}/${Ent["name"]}`;
 /**
- * Build a renderer family.
+ * Render one frame to an RGBA framebuffer, shared by both output adapters.
  *
- * `make<EntityOutput>()(tag, { render })` creates a frame renderer that
- * resolves one `EntityRenderer` per entity type from context (keyed
- * `<tag>/<entity name>`) and combines the per-entity outputs with
- * `config.render`. Provide per-entity renderers with
- * `makeEntityRendererLayer` and the frame renderer with `layer`.
+ * Uses the RenderSession's canvas (resized in place to the frame's physical
+ * size, cleared of the previous frame), adds a root scene, folds the frame
+ * onto it via `Renderer.render`, then update/draw/sync and reads the SW
+ * framebuffer. The scene and every painted shape are scoped per frame; the
+ * canvas belongs to the session (a player mount, an export run) and is
+ * deleted when the session closes.
+ *
+ * The background is painted as a filled rect (not a canvas clear color) so it
+ * survives into the buffer the same way the SVG sink emitted a background
+ * rect.
  */
-export declare const make: <RenderEntitySuccess, Config = void>() => <const Tag extends string, RenderSuccess>(tag: Tag, config: {
-    render: <Entities>(entities: Iterable<{
-        id: string;
-        render: Effect.Effect<RenderEntitySuccess>;
-        entry: EntriesFromEntities<Entities>;
-    }>, config: Config, meta: FrameMeta) => Effect.Effect<RenderSuccess>;
-}) => {
-    Context: Context.Service<{
-        render: <const Entities extends Entity.AnyEntity>(frame: Frame<Entities>, config: Config) => Effect.Effect<RenderSuccess, never, Entities extends Entity.AnyEntity ? { [K in Entities as K["name"]]: EntityRenderer<`${Tag}/${K["name"]}`, RenderEntitySuccess, K, never, never>; }[Entities["name"]] : never>;
-    }, {
-        render: <const Entities extends Entity.AnyEntity>(frame: Frame<Entities>, config: Config) => Effect.Effect<RenderSuccess, never, Entities extends Entity.AnyEntity ? { [K in Entities as K["name"]]: EntityRenderer<`${Tag}/${K["name"]}`, RenderEntitySuccess, K, never, never>; }[Entities["name"]] : never>;
-    }>;
-    layer: Layer.Layer<{
-        render: <const Entities extends Entity.AnyEntity>(frame: Frame<Entities>, config: Config) => Effect.Effect<RenderSuccess, never, Entities extends Entity.AnyEntity ? { [K in Entities as K["name"]]: EntityRenderer<`${Tag}/${K["name"]}`, RenderEntitySuccess, K, never, never>; }[Entities["name"]] : never>;
-    }, never, never>;
-    makeEntityRendererContext: <const Ent extends Entity.AnyEntity, E = never, R = never>(entity: Ent) => Context.Service<EntityRenderer<`${Tag}/${Ent["name"]}`, RenderEntitySuccess, Ent, E, R>, EntityRenderer<`${Tag}/${Ent["name"]}`, RenderEntitySuccess, Ent, E, R>>;
-    makeEntityRendererService: <const Ent extends Entity.AnyEntity, E = never, R = never>(entity: Ent, render: RenderFunction<RenderEntitySuccess, Ent, E, R>) => EntityRenderer<`${Tag}/${Ent["name"]}`, RenderEntitySuccess, Ent, E, R>;
-    makeEntityRendererLayer: <const Ent extends Entity.AnyEntity, E = never, R = never>(entity: Ent, render: RenderFunction<RenderEntitySuccess, Ent, E, R>) => Layer.Layer<EntityRenderer<RendererName<Tag, Ent>, RenderEntitySuccess, Ent, E, R>>;
-};
-export {};
+export declare const render: (frame: Frame, options?: {
+    /**
+     * device-pixel-ratio multiplier for high-dpi displays. The buffer is
+     * rasterized at `logical × dpr` while paint functions keep working in
+     * logical scene coordinates (the root scene is scaled). Callers display
+     * the buffer at the logical size. Default 1 (node/export paths).
+     */
+    readonly dpr?: number;
+}) => Effect.Effect<Framebuffer, ThorvgException, Tvg.ThorvgWasm | Tvg.RenderSession | Scope.Scope>;