@effect-motion/renderer 0.5.0

package/dist/Builtins.d.ts

@@ -0,0 +1,34 @@
+import type { EntityRenderer, EntityRenderers } from "./EntityRenderer.js";
+/**
+ * The renderer for every built-in entity kind.
+ *
+ * @remarks
+ * Typed as an exhaustive map, so adding an entity to the core library
+ * without a renderer here fails the build rather than silently drawing
+ * nothing.
+ *
+ * To change how a kind is drawn, pass a replacement in the `renderers`
+ * option of `Renderer.make` or the Node adapter's `make` — it is merged over
+ * this map by tag — rather than editing this manifest.
+ */
+export declare const builtinRenderers: EntityRenderers;
+/**
+ * The manifest widened for registry use. The single variance cast lives
+ * here: `EntityRenderers` keys each renderer by its exact entity data (so
+ * coverage over the tag union stays a compile-time guarantee above), while
+ * a registry is keyed by string — contravariant `build`/`update` parameters
+ * make that narrowing inexpressible without the cast.
+ *
+ * ponytail: the ParticleField entry is the D10 escape hatch. It is the ONE
+ * key here that is not a member of the entity union, added explicitly rather
+ * than by leaving the registry open. Delete it with the particles rewrite.
+ */
+/**
+ * {@link builtinRenderers} as the loosely-typed map the renderer's registry
+ * actually holds, keyed by entity tag.
+ *
+ * @remarks
+ * Same contents, widened: a heterogeneous registry cannot be read at any one
+ * entity type. Custom renderers are merged over this.
+ */
+export declare const builtinRegistry: Record<string, EntityRenderer<never>>;

package/dist/Builtins.js

@@ -0,0 +1,584 @@
+import { Line2 as FatLine, ThreeRaw as THREE, Tsl } from "@effect-motion/three";
+import { Effect } from "effect";
+import { Color, Runner } from "effect-motion";
+import { renderOpacity, renderSize } from "effect-motion/particles/overLife";
+import * as Images from "./Images.js";
+import * as Text from "./Text.js";
+/**
+ * Built-in entity renderers: the retained (`build`/`update`/`dispose`) port
+ * of the ThorVG paint manifest. Flat unlit look — MeshBasicNodeMaterial for
+ * fills, Line2NodeMaterial with world-unit widths for strokes (stroke width
+ * is a world-space dimension foreshortened per-pixel by perspective; this
+ * intentionally replaces ThorVG's one-scale-per-segment approximation).
+ */
+const CIRCLE_SEGMENTS = 64;
+// shared unit geometries — shapes scale them, so there are no per-frame
+// geometry rebuilds for circles/ellipses/rects at all. Both are CENTERED on
+// their anchor: `position` is the shape's center, like Manim/Motion Canvas.
+const unitCircle = new THREE.CircleGeometry(1, CIRCLE_SEGMENTS);
+const unitPlane = new THREE.PlaneGeometry(1, 1);
+const setColor = (material, color, shapeOpacity) => {
+    const { r, g, b, a } = Color.bytes(color);
+    material.color.setRGB(r / 255, g / 255, b / 255, THREE.SRGBColorSpace);
+    material.opacity = (a / 255) * shapeOpacity;
+    material.transparent = true;
+};
+const buildFillGroup = () => {
+    const material = new THREE.MeshBasicNodeMaterial();
+    material.side = THREE.DoubleSide;
+    const mesh = new THREE.Mesh(unitPlane, material);
+    const group = new THREE.Group();
+    group.add(mesh);
+    const parts = { group, mesh, outline: null };
+    const retained = {
+        object: group,
+        billboard: true,
+        dispose: () => {
+            material.dispose();
+            if (mesh.geometry !== unitPlane && mesh.geometry !== unitCircle) {
+                mesh.geometry.dispose();
+            }
+            if (parts.outline !== null) {
+                disposeFatLine(parts.outline);
+            }
+        },
+    };
+    group.userData.parts = parts;
+    return { retained, parts };
+};
+const partsOf = (retained) => retained.object.userData.parts;
+/** swap the fill mesh geometry, disposing a previous per-instance one */
+const setFillGeometry = (parts, geometry) => {
+    const previous = parts.mesh.geometry;
+    if (previous !== geometry) {
+        if (previous !== unitPlane && previous !== unitCircle) {
+            previous.dispose();
+        }
+        parts.mesh.geometry = geometry;
+    }
+};
+/** stroke outline from a closed local-space polyline, or none */
+const setOutline = (parts, data, points) => {
+    if (data.strokeColor === undefined || points === null) {
+        if (parts.outline !== null) {
+            parts.group.remove(parts.outline);
+            disposeFatLine(parts.outline);
+            parts.outline = null;
+        }
+        return;
+    }
+    if (parts.outline === null) {
+        parts.outline = makeFatLine();
+        parts.group.add(parts.outline);
+    }
+    const material = parts.outline.material;
+    setColor(material, data.strokeColor, data.opacity);
+    material.linewidth = data.strokeWidth ?? 1;
+    const positions = [];
+    for (const [x, y] of points) {
+        positions.push(x, y, 0);
+    }
+    const first = points[0];
+    if (first !== undefined) {
+        positions.push(first[0], first[1], 0);
+    }
+    parts.outline.geometry.dispose();
+    parts.outline.geometry = new FatLine.LineGeometry();
+    parts.outline.geometry.setPositions(positions);
+    parts.outline.computeLineDistances();
+    parts.outline.visible = material.opacity > 0;
+};
+const ellipsePoints = (rx, ry) => {
+    const points = [];
+    for (let i = 0; i < CIRCLE_SEGMENTS; i++) {
+        const a = (i / CIRCLE_SEGMENTS) * Math.PI * 2;
+        points.push([Math.cos(a) * rx, Math.sin(a) * ry]);
+    }
+    return points;
+};
+// rect outline points, center-anchored local frame (±w/2, ±h/2). Sharp
+// corners only — rounded rects were removed with the entity-model rewrite.
+const rectPoints = (width, height) => [
+    [-width / 2, height / 2],
+    [width / 2, height / 2],
+    [width / 2, -height / 2],
+    [-width / 2, -height / 2],
+];
+const placeFillGroup = (retained, leaf, ctx, fill, opacity) => {
+    const parts = partsOf(retained);
+    const material = parts.mesh.material;
+    setColor(material, fill, opacity);
+    parts.mesh.visible = material.opacity > 0;
+    parts.group.position.copy(ctx.toThree(leaf.world.x, leaf.world.y, leaf.world.z));
+    return parts;
+};
+const circle = {
+    build: (leaf, ctx) => {
+        const { retained, parts } = buildFillGroup();
+        parts.mesh.geometry = unitCircle;
+        circle.update(retained, leaf, ctx);
+        return retained;
+    },
+    update: (retained, leaf, ctx) => {
+        const parts = placeFillGroup(retained, leaf, ctx, leaf.data.fillColor, leaf.data.opacity);
+        parts.mesh.scale.set(leaf.data.radius, leaf.data.radius, 1);
+        setOutline(parts, leaf.data, leaf.data.strokeColor !== undefined
+            ? ellipsePoints(leaf.data.radius, leaf.data.radius)
+            : null);
+    },
+};
+const ellipse = {
+    build: (leaf, ctx) => {
+        const { retained, parts } = buildFillGroup();
+        parts.mesh.geometry = unitCircle;
+        ellipse.update(retained, leaf, ctx);
+        return retained;
+    },
+    update: (retained, leaf, ctx) => {
+        const parts = placeFillGroup(retained, leaf, ctx, leaf.data.fillColor, leaf.data.opacity);
+        parts.mesh.scale.set(leaf.data.radiusX, leaf.data.radiusY, 1);
+        setOutline(parts, leaf.data, leaf.data.strokeColor !== undefined
+            ? ellipsePoints(leaf.data.radiusX, leaf.data.radiusY)
+            : null);
+    },
+};
+const rect = {
+    build: (leaf, ctx) => {
+        const { retained } = buildFillGroup();
+        rect.update(retained, leaf, ctx);
+        return retained;
+    },
+    update: (retained, leaf, ctx) => {
+        const parts = placeFillGroup(retained, leaf, ctx, leaf.data.fillColor, leaf.data.opacity);
+        const data = leaf.data;
+        // corner radii are gone with the entity-model rewrite (design D13):
+        // rects render sharp
+        setFillGeometry(parts, unitPlane);
+        parts.mesh.scale.set(data.width, data.height, 1);
+        setOutline(parts, data, data.strokeColor !== undefined
+            ? rectPoints(data.width, data.height)
+            : null);
+        const { x: rotX, y: rotY, z: rotZ } = data.rotation;
+        const tilted = rotX !== 0 || rotY !== 0 || rotZ !== 0;
+        retained.billboard = !tilted;
+        if (tilted) {
+            // scene Eulers apply X→Y→Z extrinsically (matrix Rz·Ry·Rx), which
+            // is three's Euler order "ZYX" verbatim — no conjugation; rotation
+            // is about the shape's center (the centered unitPlane's origin)
+            parts.group.rotation.order = "ZYX";
+            parts.group.rotation.set(rotX, rotY, rotZ);
+        }
+        else {
+            parts.group.rotation.set(0, 0, 0);
+        }
+    },
+};
+// ── strokes (line / path) ────────────────────────────────────────────────
+const makeFatLine = () => {
+    const line = new FatLine.Line2(new FatLine.LineGeometry());
+    // swap in the wrapper's alpha-blending material (upstream's transparent
+    // path is a broken shared framebuffer copy — see BlendedLine2NodeMaterial)
+    line.material.dispose();
+    const material = new FatLine.BlendedLine2NodeMaterial();
+    material.worldUnits = true;
+    line.material = material;
+    return line;
+};
+const disposeFatLine = (line) => {
+    line.geometry.dispose();
+    line.material.dispose();
+};
+const line = {
+    build: (leaf, ctx) => {
+        const fatLine = makeFatLine();
+        const retained = {
+            object: fatLine,
+            billboard: false,
+            dispose: () => disposeFatLine(fatLine),
+        };
+        line.update(retained, leaf, ctx);
+        return retained;
+    },
+    update: (retained, leaf, ctx) => {
+        const fatLine = retained.object;
+        const material = fatLine.material;
+        setColor(material, leaf.data.strokeColor, leaf.data.opacity);
+        material.linewidth = leaf.data.strokeWidth;
+        fatLine.visible = material.opacity > 0;
+        // `world` is the line's position (ancestor offset composed in). Both
+        // `start` and `end` are offsets FROM position, so each endpoint is
+        // world + its own offset — a zero/zero line is a point at position.
+        const a = ctx.toThree(leaf.world.x + leaf.data.start.x, leaf.world.y + leaf.data.start.y, leaf.world.z + leaf.data.start.z);
+        const b = ctx.toThree(leaf.world.x + leaf.data.end.x, leaf.world.y + leaf.data.end.y, leaf.world.z + leaf.data.end.z);
+        fatLine.geometry.setPositions([a.x, a.y, a.z, b.x, b.y, b.z]);
+        fatLine.computeLineDistances();
+    },
+};
+const pathSubpaths = (commands, anchor) => {
+    const subpaths = [];
+    let current = [];
+    let lastMove = { ...anchor };
+    const world = (p) => ({
+        x: anchor.x + p.x,
+        y: anchor.y + p.y,
+        z: anchor.z + (p.z ?? 0),
+    });
+    const flush = (closed) => {
+        if (current.length >= 2) {
+            subpaths.push({ points: current, closed });
+        }
+        current = [];
+    };
+    for (const command of commands) {
+        switch (command._tag) {
+            case "M": {
+                flush(false);
+                lastMove = world(command);
+                current = [lastMove];
+                break;
+            }
+            case "L": {
+                if (current.length === 0) {
+                    current.push(lastMove);
+                }
+                current.push(world(command));
+                break;
+            }
+            case "Z": {
+                flush(true);
+                break;
+            }
+        }
+    }
+    flush(false);
+    return subpaths;
+};
+// ponytail: rebuilt wholesale whenever the path changes (geometry churn
+// accepted — acceptance paths are static). Closed subpaths fill with the
+// path's fill color, triangulated in x/y with per-vertex z applied after
+// (earcut only uses the input vertices, so mildly non-planar subpaths keep
+// their depths). Holes are not supported — each closed subpath fills
+// independently (winding analysis is a later concern).
+const path = {
+    build: (leaf, ctx) => {
+        const group = new THREE.Group();
+        const retained = {
+            object: group,
+            billboard: false,
+            dispose: () => {
+                for (const child of [...group.children]) {
+                    disposePathChild(child);
+                }
+            },
+        };
+        path.update(retained, leaf, ctx);
+        return retained;
+    },
+    update: (retained, leaf, ctx) => {
+        const group = retained.object;
+        for (const child of [...group.children]) {
+            group.remove(child);
+            disposePathChild(child);
+        }
+        const { strokeColor: stroke, fillColor: fill, opacity } = leaf.data;
+        const strokeWidth = leaf.data.strokeWidth ?? 1;
+        const subpaths = pathSubpaths(leaf.data.commands, leaf.world);
+        for (const subpath of subpaths) {
+            // fill: closed subpaths only, triangulated in x/y
+            if (subpath.closed && subpath.points.length >= 3) {
+                const contour = subpath.points.map((p) => new THREE.Vector2(p.x, p.y));
+                const triangles = THREE.ShapeUtils.triangulateShape(contour, []);
+                const positions = new Float32Array(subpath.points.length * 3);
+                for (const [i, p] of subpath.points.entries()) {
+                    const v = ctx.toThree(p.x, p.y, p.z);
+                    positions[i * 3] = v.x;
+                    positions[i * 3 + 1] = v.y;
+                    positions[i * 3 + 2] = v.z;
+                }
+                const geometry = new THREE.BufferGeometry();
+                geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
+                geometry.setIndex(triangles.flat());
+                const material = new THREE.MeshBasicNodeMaterial();
+                material.side = THREE.DoubleSide;
+                setColor(material, fill, opacity);
+                const mesh = new THREE.Mesh(geometry, material);
+                mesh.visible = material.opacity > 0;
+                group.add(mesh);
+            }
+            // stroke: world-unit fat polyline
+            if (stroke !== undefined) {
+                const fatLine = makeFatLine();
+                const material = fatLine.material;
+                setColor(material, stroke, opacity);
+                material.linewidth = strokeWidth;
+                fatLine.visible = material.opacity > 0;
+                const positions = [];
+                const push = (p) => {
+                    const v = ctx.toThree(p.x, p.y, p.z);
+                    positions.push(v.x, v.y, v.z);
+                };
+                for (const p of subpath.points) {
+                    push(p);
+                }
+                const first = subpath.points[0];
+                if (subpath.closed &&
+                    subpath.points.length > 1 &&
+                    first !== undefined) {
+                    push(first);
+                }
+                fatLine.geometry.setPositions(positions);
+                fatLine.computeLineDistances();
+                group.add(fatLine);
+            }
+        }
+    },
+};
+const disposePathChild = (child) => {
+    if (child instanceof FatLine.Line2) {
+        disposeFatLine(child);
+        return;
+    }
+    const mesh = child;
+    mesh.geometry.dispose();
+    mesh.material.dispose();
+};
+// ── text: SDF glyphs (see Text.ts) ───────────────────────────────────────
+// Layout is async (typesetting + first-sight glyph SDF generation) and
+// registered with ctx.waitFor, so the render path never presents a
+// half-built string. The mesh billboards and scales with perspective like
+// the other billboard shapes.
+const text = {
+    build: (leaf, ctx) => {
+        const textMesh = Text.makeMesh(ctx.text);
+        const retained = {
+            object: textMesh.mesh,
+            billboard: true,
+            dispose: () => textMesh.dispose(),
+        };
+        retained.object.userData.textMesh = textMesh;
+        text.update(retained, leaf, ctx);
+        return retained;
+    },
+    update: (retained, leaf, ctx) => {
+        const textMesh = retained.object.userData.textMesh;
+        const data = leaf.data;
+        const key = [
+            data.text,
+            data.fontSize,
+            data.fontFamily.id,
+            data.textAnchor,
+            data.baseline,
+        ].join("|");
+        if (retained.object.userData.textKey !== key) {
+            retained.object.userData.textKey = key;
+            ctx.waitFor(Text.layout(ctx.text, {
+                text: data.text,
+                fontId: data.fontFamily.id,
+                fontSize: data.fontSize,
+                textAnchor: data.textAnchor,
+                baseline: data.baseline,
+            }).pipe(Effect.map((quads) => textMesh.setQuads(quads))));
+        }
+        const { r, g, b, a } = Color.bytes(data.fillColor);
+        textMesh.setColor(r, g, b, (a / 255) * data.opacity);
+        retained.object.position.copy(ctx.toThree(leaf.world.x, leaf.world.y, leaf.world.z));
+    },
+};
+// ── images: decoded once per renderer scope, billboard planes ────────────
+// (data.position.x, data.position.y) is the picture's CENTER like Rect; both
+// dimensions set draw at that size, else the natural decoded size; a lone
+// dimension is ignored.
+const image = {
+    build: (leaf, ctx) => {
+        const material = new THREE.MeshBasicNodeMaterial();
+        material.transparent = true;
+        material.side = THREE.DoubleSide;
+        const mesh = new THREE.Mesh(unitPlane, material);
+        const retained = {
+            object: mesh,
+            billboard: true,
+            // textures are store-owned (disposed with the renderer scope)
+            dispose: () => material.dispose(),
+        };
+        image.update(retained, leaf, ctx);
+        return retained;
+    },
+    update: (retained, leaf, ctx) => {
+        const mesh = retained.object;
+        const material = mesh.material;
+        const data = leaf.data;
+        const applySize = (natural) => {
+            const both = data.width !== undefined && data.height !== undefined;
+            mesh.scale.set(both ? data.width : natural.width, both ? data.height : natural.height, 1);
+        };
+        if (mesh.userData.imageId !== data.image.id) {
+            mesh.userData.imageId = data.image.id;
+            mesh.visible = false;
+            ctx.waitFor(Images.ready(ctx.images, data.image.id).pipe(Effect.flatMap((decoded) => Effect.sync(() => {
+                material.map = decoded.texture;
+                material.needsUpdate = true;
+                mesh.userData.natural = {
+                    width: decoded.width,
+                    height: decoded.height,
+                };
+                applySize(mesh.userData.natural);
+                mesh.visible = material.opacity > 0;
+            }))));
+        }
+        else if (mesh.userData.natural !== undefined) {
+            applySize(mesh.userData.natural);
+        }
+        material.opacity = data.opacity;
+        if (mesh.userData.natural !== undefined) {
+            mesh.visible = data.opacity > 0;
+        }
+        mesh.position.copy(ctx.toThree(leaf.world.x, leaf.world.y, leaf.world.z));
+    },
+};
+const particleField = {
+    build: (leaf, ctx) => {
+        const capacity = Math.max(1, leaf.data.buffer.length);
+        const geometry = new THREE.InstancedBufferGeometry();
+        geometry.setAttribute("position", unitCircle.getAttribute("position"));
+        const circleIndex = unitCircle.getIndex();
+        if (circleIndex !== null) {
+            geometry.setIndex(circleIndex);
+        }
+        geometry.setAttribute("particleOffset", new THREE.InstancedBufferAttribute(new Float32Array(capacity * 3), 3));
+        geometry.setAttribute("particleColor", new THREE.InstancedBufferAttribute(new Float32Array(capacity * 4), 4));
+        geometry.instanceCount = 0;
+        const material = new THREE.MeshBasicNodeMaterial();
+        material.transparent = true;
+        material.side = THREE.DoubleSide;
+        const t = Tsl;
+        const offset = t.attribute("particleOffset", "vec3");
+        const color = t.attribute("particleColor", "vec4");
+        material.positionNode = t.vec3(t.positionGeometry.x.mul(offset.z).add(offset.x), t.positionGeometry.y.mul(offset.z).add(offset.y), 0);
+        material.colorNode = t.vec4(color.rgb, color.a);
+        const mesh = new THREE.Mesh(geometry, material);
+        mesh.frustumCulled = false;
+        const retained = {
+            object: mesh,
+            billboard: true,
+            dispose: () => {
+                geometry.dispose();
+                material.dispose();
+            },
+        };
+        particleField.update(retained, leaf, ctx);
+        return retained;
+    },
+    update: (retained, leaf, ctx) => {
+        const mesh = retained.object;
+        const geometry = mesh.geometry;
+        const data = leaf.data;
+        const offsets = geometry.getAttribute("particleOffset");
+        const colors = geometry.getAttribute("particleColor");
+        let count = 0;
+        for (const p of data.buffer) {
+            if (!p.alive) {
+                continue;
+            }
+            const radius = renderSize(p, data.sizeOverLife);
+            if (radius <= 0) {
+                continue;
+            }
+            const alpha = renderOpacity(p, data.opacityOverLife) *
+                data.opacity;
+            if (alpha <= 0) {
+                continue;
+            }
+            if (count >= offsets.count) {
+                break;
+            }
+            // local offsets pass through (scene space = three local space);
+            // the mesh itself sits at the field's anchor
+            offsets.setXYZ(count, p.x, p.y, radius);
+            const { r, g, b } = Color.bytes(p.color);
+            colors.setXYZW(count, r / 255, g / 255, b / 255, alpha);
+            count++;
+        }
+        offsets.needsUpdate = true;
+        colors.needsUpdate = true;
+        geometry.instanceCount = count;
+        mesh.visible = count > 0;
+        mesh.position.copy(ctx.toThree(leaf.world.x, leaf.world.y, leaf.world.z));
+    },
+};
+// ── staged gaps: loud, never silent ──────────────────────────────────────
+// containers never reach leaf rendering — the frame walk composes them
+const container = (name) => ({
+    build: (leaf) => {
+        throw new Error(`${name} is a container and must be composed by the frame walk, not rendered as a leaf — instance "${leaf.id}" (renderer walk bug)`);
+    },
+    update: () => { },
+});
+/**
+ * The exhaustive renderer map for every built-in entity. Typed
+ * `EntityRenderers<...>` so a missing built-in fails to type-check — the
+ * same coverage-manifest guarantee `builtinPaints` gives the ThorVG path.
+ */
+/**
+ * A renderer slot for an entity that never reaches the walk. Dying loudly
+ * beats a silent no-op: if one of these is ever invoked, the frame contract
+ * changed and we want to hear about it.
+ */
+const neverRendered = (tag) => ({
+    build: () => {
+        throw new Error(`Renderer: ${tag} is not renderable`);
+    },
+    update: () => {
+        throw new Error(`Renderer: ${tag} is not renderable`);
+    },
+    dispose: () => { },
+});
+/**
+ * The renderer for every built-in entity kind.
+ *
+ * @remarks
+ * Typed as an exhaustive map, so adding an entity to the core library
+ * without a renderer here fails the build rather than silently drawing
+ * nothing.
+ *
+ * To change how a kind is drawn, pass a replacement in the `renderers`
+ * option of `Renderer.make` or the Node adapter's `make` — it is merged over
+ * this map by tag — rather than editing this manifest.
+ */
+export const builtinRenderers = {
+    Circle: circle,
+    Ellipse: ellipse,
+    Rect: rect,
+    Line: line,
+    Path: path,
+    Text: text,
+    Group: container("Group"),
+    Hud: container("Hud"),
+    Image: image,
+    // the camera is view state and never painted; it is omitted from the
+    // frame's instance map, so this entry is unreachable by construction —
+    // it exists only to satisfy exhaustiveness over the tag union
+    Camera: neverRendered("Camera"),
+};
+/**
+ * The manifest widened for registry use. The single variance cast lives
+ * here: `EntityRenderers` keys each renderer by its exact entity data (so
+ * coverage over the tag union stays a compile-time guarantee above), while
+ * a registry is keyed by string — contravariant `build`/`update` parameters
+ * make that narrowing inexpressible without the cast.
+ *
+ * ponytail: the ParticleField entry is the D10 escape hatch. It is the ONE
+ * key here that is not a member of the entity union, added explicitly rather
+ * than by leaving the registry open. Delete it with the particles rewrite.
+ */
+/**
+ * {@link builtinRenderers} as the loosely-typed map the renderer's registry
+ * actually holds, keyed by entity tag.
+ *
+ * @remarks
+ * Same contents, widened: a heterogeneous registry cannot be read at any one
+ * entity type. Custom renderers are merged over this.
+ */
+export const builtinRegistry = {
+    ...builtinRenderers,
+    [Runner.PARTICLE_FIELD_TAG]: particleField,
+};