@effect-motion/renderer 0.5.0

package/dist/Text.js

@@ -0,0 +1,318 @@
+import { ThreeRaw as THREE, Tsl } from "@effect-motion/three";
+import { Effect } from "effect";
+import { EffectMotionError } from "effect-motion";
+import { typesetterWorkerModule } from "troika-three-text";
+import createSdfGenerator from "webgl-sdf-generator";
+/**
+ * Text rendering: fonts, glyph atlas, and layout.
+ *
+ * @remarks
+ * Text is drawn from a signed-distance-field atlas rather than as geometry,
+ * which is what lets a string stay crisp at any scale without re-tessellating
+ * as it grows.
+ *
+ * Each glyph is rasterized into a shared atlas texture the first time it is
+ * seen, then reused. A scene that animates one word costs one atlas build,
+ * not one per frame.
+ *
+ * The pipeline deliberately uses only troika's typesetting layer — font
+ * parsing, shaping, and glyph outlines — and none of its rendering, which
+ * assumes WebGL and a canvas. The SDF generation and the atlas material
+ * belong to this package, so the same code path serves browser and headless
+ * Node.
+ *
+ * ponytail: the atlas is fixed-capacity (256 glyphs) with one glyph per
+ * cell, and SDF generation is pure JS with no GPU acceleration. Both trade
+ * speed and memory for a uniform, canvas-free pipeline; overflow is a typed
+ * error naming the remedy.
+ */
+const SDF_GLYPH_SIZE = 64;
+const SDF_EXPONENT = 9;
+const SDF_MARGIN = 1 / 16;
+const ATLAS_WIDTH = 1024;
+const ATLAS_HEIGHT = 1024;
+const GLYPHS_PER_ROW = ATLAS_WIDTH / SDF_GLYPH_SIZE;
+/** ponytail: fixed-capacity atlas (256 glyphs); grow-and-reallocate when a
+ * scene ever exceeds it. Overflow is a typed error naming the remedy. */
+const ATLAS_CAPACITY = GLYPHS_PER_ROW * (ATLAS_HEIGHT / SDF_GLYPH_SIZE);
+const toBase64 = (bytes) => {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("base64");
+    }
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+};
+export const make = () => {
+    const atlasData = new Uint8Array(ATLAS_WIDTH * ATLAS_HEIGHT);
+    const atlas = new THREE.DataTexture(atlasData, ATLAS_WIDTH, ATLAS_HEIGHT, THREE.RedFormat, THREE.UnsignedByteType);
+    atlas.minFilter = THREE.LinearFilter;
+    atlas.magFilter = THREE.LinearFilter;
+    atlas.generateMipmaps = false;
+    return {
+        atlas,
+        atlasData,
+        fonts: new Map(),
+        glyphs: new Map(),
+        glyphCount: 0,
+        sdf: createSdfGenerator(),
+        typesetter: undefined,
+    };
+};
+/**
+ * Register a font's bytes under its id.
+ *
+ * @remarks
+ * Idempotent per id — registering the same font twice does nothing the
+ * second time. A font must be registered before any string using it can be
+ * laid out; `Sync.resolveResources` handles that for frames.
+ */
+export const registerFont = (text, id, bytes) => {
+    if (!text.fonts.has(id)) {
+        text.fonts.set(id, `data:font/ttf;base64,${toBase64(bytes)}`);
+    }
+};
+export const hasFont = (text, id) => text.fonts.has(id);
+export const dispose = (text) => {
+    text.atlas.dispose();
+};
+/** the atlas slot for a glyph, generating its SDF on first sight —
+ * sync inner kernel; failures surface through `layout`'s error channel */
+const glyphSlot = (text, fontSrc, glyphId, result) => {
+    const key = `${fontSrc}#${glyphId}`;
+    const cached = text.glyphs.get(key);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const glyph = result.glyphData[fontSrc]?.[glyphId];
+    if (glyph === undefined) {
+        throw new Error(`no glyph data for glyph ${glyphId}`);
+    }
+    if (text.glyphCount >= ATLAS_CAPACITY) {
+        throw new Error(`glyph atlas is full (${ATLAS_CAPACITY} glyphs) — raise the atlas size in @effect-motion/renderer's Text module`);
+    }
+    const [minX, minY, maxX, maxY] = glyph.pathBounds;
+    // margin around path edges, mirroring troika's atlas math
+    const fontUnitsMargin = (Math.max(maxX - minX, maxY - minY) / SDF_GLYPH_SIZE) *
+        (SDF_MARGIN * SDF_GLYPH_SIZE + 0.5);
+    const viewBox = [
+        minX - fontUnitsMargin,
+        minY - fontUnitsMargin,
+        maxX + fontUnitsMargin,
+        maxY + fontUnitsMargin,
+    ];
+    const maxDist = Math.max(viewBox[2] - viewBox[0], viewBox[3] - viewBox[1]);
+    const sdfData = text.sdf.javascript.generate(SDF_GLYPH_SIZE, SDF_GLYPH_SIZE, glyph.path, viewBox, maxDist, SDF_EXPONENT);
+    const index = text.glyphCount++;
+    const col = index % GLYPHS_PER_ROW;
+    const row = Math.floor(index / GLYPHS_PER_ROW);
+    const x0 = col * SDF_GLYPH_SIZE;
+    const y0 = row * SDF_GLYPH_SIZE;
+    for (let y = 0; y < SDF_GLYPH_SIZE; y++) {
+        text.atlasData.set(sdfData.subarray(y * SDF_GLYPH_SIZE, (y + 1) * SDF_GLYPH_SIZE), (y0 + y) * ATLAS_WIDTH + x0);
+    }
+    text.atlas.needsUpdate = true;
+    const slot = {
+        uv: [
+            x0 / ATLAS_WIDTH,
+            y0 / ATLAS_HEIGHT,
+            (x0 + SDF_GLYPH_SIZE) / ATLAS_WIDTH,
+            (y0 + SDF_GLYPH_SIZE) / ATLAS_HEIGHT,
+        ],
+        viewBox,
+    };
+    text.glyphs.set(key, slot);
+    return slot;
+};
+/**
+ * Lay out a string into positioned glyph quads.
+ *
+ * @remarks
+ * Typesets the text, rasterizes any glyph not already in the atlas, and
+ * returns per-glyph quad bounds and atlas UV rects with the anchor and
+ * baseline offsets applied. By default the text's baseline-left sits at
+ * local (0, 0).
+ *
+ * Asynchronous because typesetting and SDF generation are; the renderer
+ * registers the work so a frame is never drawn with half its glyphs.
+ * Typesetting and SDF failures arrive as typed errors naming the font.
+ *
+ * The font must be registered first — an unregistered font is a defect.
+ */
+export const layout = Effect.fnUntraced(function* (text, request) {
+    const src = text.fonts.get(request.fontId);
+    if (src === undefined) {
+        return yield* Effect.die(new Error(`Text: font "${request.fontId}" was not registered before layout`));
+    }
+    const result = yield* Effect.tryPromise({
+        try: async () => {
+            text.typesetter ??= typesetterWorkerModule.onMainThread._getInitResult();
+            const typesetter = await text.typesetter;
+            return new Promise((resolve) => {
+                typesetter.typeset({
+                    text: request.text,
+                    font: [{ label: "user", src }],
+                    fontSize: request.fontSize,
+                    sdfGlyphSize: SDF_GLYPH_SIZE,
+                }, resolve);
+            });
+        },
+        catch: (cause) => EffectMotionError.of(`Text: typesetting failed for font "${request.fontId}"`, cause),
+    });
+    return yield* Effect.try({
+        try: () => {
+            const count = result.glyphIds.length;
+            const bounds = new Float32Array(count * 4);
+            const uvRects = new Float32Array(count * 4);
+            const { blockBounds, topBaseline } = result;
+            // anchor offsets: baseline-left at (0,0) by default (scene semantics)
+            const width = blockBounds[2] - blockBounds[0];
+            const anchor = request.textAnchor;
+            const dx = (anchor === "middle" ? -width / 2 : anchor === "end" ? -width : 0) -
+                blockBounds[0];
+            const dy = request.baseline === "middle"
+                ? -(blockBounds[1] + blockBounds[3]) / 2
+                : request.baseline === "hanging"
+                    ? -blockBounds[3]
+                    : -topBaseline;
+            for (let i = 0; i < count; i++) {
+                const glyphId = result.glyphIds[i] ?? 0;
+                const fontIndex = result.glyphFontIndices[i] ?? 0;
+                const font = result.fontData[fontIndex];
+                if (font === undefined) {
+                    continue;
+                }
+                const slot = glyphSlot(text, font.src, glyphId, result);
+                const posX = result.glyphPositions[i * 2] ?? 0;
+                const posY = result.glyphPositions[i * 2 + 1] ?? 0;
+                const fontSizeMult = result.fontSize / font.unitsPerEm;
+                bounds[i * 4] = dx + posX + slot.viewBox[0] * fontSizeMult;
+                bounds[i * 4 + 1] = dy + posY + slot.viewBox[1] * fontSizeMult;
+                bounds[i * 4 + 2] = dx + posX + slot.viewBox[2] * fontSizeMult;
+                bounds[i * 4 + 3] = dy + posY + slot.viewBox[3] * fontSizeMult;
+                uvRects[i * 4] = slot.uv[0];
+                uvRects[i * 4 + 1] = slot.uv[1];
+                uvRects[i * 4 + 2] = slot.uv[2];
+                uvRects[i * 4 + 3] = slot.uv[3];
+            }
+            return { bounds, uvRects, count, blockBounds };
+        },
+        catch: (cause) => EffectMotionError.of(`Text: glyph SDF generation failed for font "${request.fontId}"`, cause),
+    });
+});
+// ── glyph mesh: instanced quads + TSL SDF material ───────────────────────
+/** unit quad (0..1)², two triangles — instanced per glyph */
+const makeQuadGeometry = () => {
+    const geometry = new THREE.InstancedBufferGeometry();
+    geometry.setAttribute("position", new THREE.Float32BufferAttribute([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0], 3));
+    geometry.setIndex([0, 1, 2, 2, 1, 3]);
+    geometry.instanceCount = 0;
+    return geometry;
+};
+/**
+ * Build a mesh that draws glyphs from the shared atlas.
+ *
+ * @remarks
+ * Rendered in two passes so overlapping glyph ink — connected scripts, tight
+ * kerning — blends exactly ONCE per pixel at any opacity. A single-pass
+ * approach would double-blend the joins and show them as darker seams on
+ * semi-transparent text.
+ *
+ * - core pass: fragments with SDF coverage ≥ 0.5 draw flat at the string
+ *   opacity, write depth with `LessDepth` — a second glyph's core at the
+ *   same depth fails the test, deduplicating the join.
+ * - edge pass: the antialiasing ring (coverage < 0.5) blends without depth
+ *   writes; core-covered pixels reject it via the depth buffer.
+ *
+ * The mesh carries a tiny z-lift so text sits above coplanar backdrops
+ * (invisible at ordinary scales, deterministic).
+ */
+export const makeMesh = (text) => {
+    const geometry = makeQuadGeometry();
+    const t = Tsl;
+    const buildNodes = () => {
+        const glyphBounds = t.attribute("glyphBounds", "vec4");
+        const glyphUvRect = t.attribute("glyphUvRect", "vec4");
+        const corner = t.vec2(t.positionGeometry.x, t.positionGeometry.y);
+        const position = t.vec3(t.mix(glyphBounds.xy, glyphBounds.zw, corner), 0);
+        const uv = t.mix(glyphUvRect.xy, glyphUvRect.zw, corner);
+        const distance = t.texture(text.atlas, uv).r;
+        const halfWidth = t.fwidth(distance).mul(0.5);
+        const coverage = t.smoothstep(t.float(0.5).sub(halfWidth), t.float(0.5).add(halfWidth), distance);
+        return { position, coverage };
+    };
+    const uOpacity = Tsl.uniform(1);
+    const coreMaterial = new THREE.MeshBasicNodeMaterial();
+    coreMaterial.transparent = true;
+    coreMaterial.side = THREE.DoubleSide;
+    coreMaterial.depthWrite = true;
+    coreMaterial.depthFunc = THREE.LessDepth;
+    {
+        const { position, coverage } = buildNodes();
+        coreMaterial.positionNode = position;
+        // margins/edges get alpha 0 and are DISCARDED by the alpha test, so
+        // they never write depth — only actual ink deduplicates
+        coreMaterial.opacityNode = coverage
+            .greaterThanEqual(0.5)
+            .select(uOpacity, t.float(0));
+        coreMaterial.alphaTestNode = t.float(1 / 255);
+    }
+    const edgeMaterial = new THREE.MeshBasicNodeMaterial();
+    edgeMaterial.transparent = true;
+    edgeMaterial.side = THREE.DoubleSide;
+    edgeMaterial.depthWrite = false;
+    {
+        const { position, coverage } = buildNodes();
+        edgeMaterial.positionNode = position;
+        edgeMaterial.opacityNode = coverage
+            .lessThan(0.5)
+            .select(coverage.mul(uOpacity), t.float(0));
+    }
+    const coreMesh = new THREE.Mesh(geometry, coreMaterial);
+    const edgeMesh = new THREE.Mesh(geometry, edgeMaterial);
+    coreMesh.frustumCulled = false;
+    edgeMesh.frustumCulled = false;
+    // hidden until setQuads installs glyphBounds/glyphUvRect — otherwise the
+    // material renders referencing attributes the geometry doesn't have yet,
+    // spamming "attribute not found" warnings every frame before layout lands
+    let hasQuads = false;
+    let wantVisible = true;
+    coreMesh.visible = false;
+    edgeMesh.visible = false;
+    const group = new THREE.Group();
+    // z-lift: keep text above coplanar backdrops so the core depth test
+    // never loses to a shape at the same depth
+    coreMesh.position.z = 0.05;
+    edgeMesh.position.z = 0.05;
+    group.add(coreMesh);
+    group.add(edgeMesh);
+    const setVisible = (visible) => {
+        wantVisible = visible;
+        coreMesh.visible = visible && hasQuads;
+        edgeMesh.visible = visible && hasQuads;
+    };
+    return {
+        mesh: group,
+        setQuads: (quads) => {
+            geometry.setAttribute("glyphBounds", new THREE.InstancedBufferAttribute(quads.bounds, 4));
+            geometry.setAttribute("glyphUvRect", new THREE.InstancedBufferAttribute(quads.uvRects, 4));
+            geometry.instanceCount = quads.count;
+            hasQuads = true;
+            setVisible(wantVisible);
+        },
+        setColor: (r, g, b, a) => {
+            for (const material of [coreMaterial, edgeMaterial]) {
+                material.color.setRGB(r / 255, g / 255, b / 255, THREE.SRGBColorSpace);
+            }
+            uOpacity.value = a;
+            setVisible(a > 0);
+        },
+        dispose: () => {
+            geometry.dispose();
+            coreMaterial.dispose();
+            edgeMaterial.dispose();
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `@effect-motion/renderer` — draws effect-motion frames with three.js and
+ * WebGPU.
+ *
+ * @remarks
+ * The core library produces frames: plain data describing where everything
+ * is at one instant. This package turns those frames into pixels, and is the
+ * only place the two worlds meet.
+ *
+ * Rendering is RETAINED, not immediate. A long-lived three scene is kept in
+ * step with the frame stream: each frame is diffed against the last, so
+ * objects are built once, mutated when their data changes, and disposed when
+ * they leave. Playing a scene therefore does not rebuild the scene graph
+ * every frame.
+ *
+ * Two entry points, by environment:
+ *
+ * - **Browser** — {@link Renderer}, which draws to a canvas. Import from the
+ *   package root.
+ * - **Node** — `@effect-motion/renderer/node`, which renders headlessly on a
+ *   real GPU (Dawn) and reads frames back as PNGs. This is the export path.
+ *   It lives behind its own subpath so Node-only code never reaches a
+ *   browser bundle.
+ *
+ * Both are scoped: acquire one in a `Scope` and every GPU resource is
+ * released when it closes.
+ *
+ * Determinism note: the FRAME stream is deterministic, but pixels are not
+ * promised to be bit-identical across GPUs and drivers. Two runs of the same
+ * scene look the same; they are not guaranteed to hash the same.
+ *
+ * @example
+ * Render one frame to a PNG, headlessly.
+ * ```typescript
+ * import * as NodeRenderer from "@effect-motion/renderer/node";
+ * import { Effect } from "effect";
+ *
+ * const png = yield* Effect.scoped(
+ * 	NodeRenderer.make({ width: 500, height: 300 }).pipe(
+ * 		Effect.flatMap((renderer) => NodeRenderer.renderToPng(renderer, frame)),
+ * 	),
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * as Builtins from "./Builtins.js";
+export { builtinRegistry, builtinRenderers } from "./Builtins.js";
+export * as EntityRenderer from "./EntityRenderer.js";
+export * as Images from "./Images.js";
+export * as Renderer from "./Renderer.js";
+export * as Sync from "./Sync.js";
+export * as Text from "./Text.js";

package/dist/index.js

@@ -0,0 +1,58 @@
+/**
+ * `@effect-motion/renderer` — draws effect-motion frames with three.js and
+ * WebGPU.
+ *
+ * @remarks
+ * The core library produces frames: plain data describing where everything
+ * is at one instant. This package turns those frames into pixels, and is the
+ * only place the two worlds meet.
+ *
+ * Rendering is RETAINED, not immediate. A long-lived three scene is kept in
+ * step with the frame stream: each frame is diffed against the last, so
+ * objects are built once, mutated when their data changes, and disposed when
+ * they leave. Playing a scene therefore does not rebuild the scene graph
+ * every frame.
+ *
+ * Two entry points, by environment:
+ *
+ * - **Browser** — {@link Renderer}, which draws to a canvas. Import from the
+ *   package root.
+ * - **Node** — `@effect-motion/renderer/node`, which renders headlessly on a
+ *   real GPU (Dawn) and reads frames back as PNGs. This is the export path.
+ *   It lives behind its own subpath so Node-only code never reaches a
+ *   browser bundle.
+ *
+ * Both are scoped: acquire one in a `Scope` and every GPU resource is
+ * released when it closes.
+ *
+ * Determinism note: the FRAME stream is deterministic, but pixels are not
+ * promised to be bit-identical across GPUs and drivers. Two runs of the same
+ * scene look the same; they are not guaranteed to hash the same.
+ *
+ * @example
+ * Render one frame to a PNG, headlessly.
+ * ```typescript
+ * import * as NodeRenderer from "@effect-motion/renderer/node";
+ * import { Effect } from "effect";
+ *
+ * const png = yield* Effect.scoped(
+ * 	NodeRenderer.make({ width: 500, height: 300 }).pipe(
+ * 		Effect.flatMap((renderer) => NodeRenderer.renderToPng(renderer, frame)),
+ * 	),
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ */
+// The only place frames meet three: the retained frame renderer consuming
+// effect-motion's frame stream through the bindings-only @effect-motion/three
+// wrapper. Browser-safe surface; the Node adapter (Dawn + readback) arrives
+// via a dedicated subpath so node-only code never reaches a browser bundle.
+// One module per actor, re-exported as namespaces.
+export * as Builtins from "./Builtins.js";
+export { builtinRegistry, builtinRenderers } from "./Builtins.js";
+export * as EntityRenderer from "./EntityRenderer.js";
+export * as Images from "./Images.js";
+export * as Renderer from "./Renderer.js";
+export * as Sync from "./Sync.js";
+export * as Text from "./Text.js";

package/dist/node.d.ts

@@ -0,0 +1,158 @@
+import { Renderer as Gpu, PostProcessing, RenderTarget, type ThreeException } 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";
+/**
+ * Headless rendering for Node — the export path.
+ *
+ * @remarks
+ * Renders frames on a real GPU without a browser (through Dawn, Chrome's
+ * WebGPU implementation) and reads them back as PNG buffers. This is how a
+ * scene becomes files on disk, or gets piped into a video encoder.
+ *
+ * Importing this module installs the WebGPU globals and browser shims three
+ * expects, as a side effect, before any renderer exists. That is why it is a
+ * separate subpath: none of it should reach a browser bundle.
+ *
+ * A renderer is fixed to one size for its lifetime, and rendering a
+ * differently-sized frame is a defect rather than a silent rescale. Acquire
+ * one per export, not one per frame — setup cost is paid once, and every
+ * frame after reuses the same device, retained scene, and font atlas.
+ *
+ * @example
+ * Export every frame of a scene to PNG files.
+ * ```typescript
+ * import * as NodeRenderer from "@effect-motion/renderer/node";
+ * import * as Scene from "effect-motion/Scene";
+ * import { Effect } from "effect";
+ * import * as Stream from "effect/Stream";
+ * import { writeFile } from "node:fs/promises";
+ *
+ * yield* Effect.scoped(
+ * 	Effect.gen(function* () {
+ * 		const renderer = yield* NodeRenderer.make({ width: 500, height: 300 });
+ * 		let index = 0;
+ * 		yield* Scene.stream(scene, { frameRate: 30 }).pipe(
+ * 			Stream.runForEach((frame) =>
+ * 				Effect.gen(function* () {
+ * 					const png = yield* NodeRenderer.renderToPng(renderer, frame);
+ * 					yield* Effect.promise(() =>
+ * 						writeFile(`out/${String(index++).padStart(5, "0")}.png`, png),
+ * 					);
+ * 				}),
+ * 			),
+ * 		);
+ * 	}),
+ * );
+ * ```
+ */
+type AnyFrame = Frame<unknown>;
+type AnyEntityRenderer = EntityRenderer<never>;
+/**
+ * Encode a raw RGBA buffer as a PNG.
+ *
+ * @remarks
+ * {@link renderToPng} already does this, so reach for it directly only when
+ * you have pixels from somewhere else. The encoder is deliberately minimal —
+ * no filtering, just zlib — which keeps it fast at the cost of somewhat
+ * larger files than an optimizing encoder would produce.
+ *
+ * @param rgba - Exactly `width * height * 4` bytes, 8 bits per channel.
+ * @param width - Image width in pixels.
+ * @param height - Image height in pixels.
+ * @returns The PNG file bytes.
+ * @throws If `rgba` is not exactly `width * height * 4` bytes.
+ */
+export declare const encodePng: (rgba: Uint8Array, width: number, height: number) => Uint8Array;
+export interface NodeRendererOptions {
+    /** Logical width; frames rendered must match it. */
+    readonly width: number;
+    /** Logical height; frames rendered must match it. */
+    readonly height: number;
+    /**
+     * Supersampling factor — output is `width × height` scaled by this, so 2
+     * renders four times the pixels for cleaner edges.
+     *
+     * @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 headless renderer.
+ *
+ * @remarks
+ * Mostly data — the API is {@link renderToPng}. `pixelWidth` and
+ * `pixelHeight` are the actual output dimensions, which differ from `width`
+ * and `height` when supersampling.
+ */
+export interface NodeRenderer {
+    readonly sync: Sync.Sync;
+    readonly gpu: Gpu.Renderer;
+    /** the acquisition scope — image decodes fork into it (see Renderer.ts) */
+    readonly scope: Scope.Scope;
+    /** internal: the plain render pipeline (world content only) */
+    readonly post: PostProcessing.RenderPipeline;
+    /** internal: pipeline with the HUD pass composited over the world */
+    readonly postWithHud: PostProcessing.RenderPipeline;
+    /** internal: the readback render target */
+    readonly target: RenderTarget.RenderTarget;
+    readonly width: number;
+    readonly height: number;
+    readonly pixelWidth: number;
+    readonly pixelHeight: number;
+    readonly pixelRatio: number;
+}
+/**
+ * Render one frame and return it as PNG bytes.
+ *
+ * @remarks
+ * The whole export path in one call: resolve the frame's fonts and images,
+ * sync the retained scene, wait for glyph layouts and decodes, render, read
+ * the pixels back off the GPU, and encode.
+ *
+ * Call it once per frame on the SAME renderer; state is retained between
+ * calls, so consecutive frames only pay for what changed.
+ *
+ * The frame's dimensions must match the renderer's. A mismatch is a defect
+ * naming both sizes, not a silent rescale.
+ *
+ * Output is `pixelWidth × pixelHeight` — larger than the logical size when
+ * a `pixelRatio` was given.
+ *
+ * @param renderer - A renderer from {@link make}.
+ * @param frame - The frame to draw.
+ * @returns PNG file bytes.
+ */
+export declare const renderToPng: (renderer: NodeRenderer, frame: AnyFrame) => Effect.Effect<Uint8Array<ArrayBufferLike>, EffectMotionError | RenderException | ThreeException, never>;
+/**
+ * Acquire a headless renderer.
+ *
+ * @remarks
+ * Scoped: the GPU device, render targets, and every retained object are
+ * released when the scope closes. Acquire one per export and reuse it for
+ * every frame — startup involves creating a GPU device, so per-frame
+ * acquisition is dramatically slower.
+ *
+ * `width` and `height` fix the renderer's size for its lifetime and must
+ * match the frames you render.
+ *
+ * Use `pixelRatio` to supersample: a ratio of 2 renders at twice the linear
+ * resolution (four times the pixels), which is the usual way to get cleaner
+ * edges in an export.
+ *
+ * Depth of field is not applied — every frame renders sharp.
+ *
+ * @param options - Dimensions, supersampling, and any custom entity
+ *   renderers.
+ * @returns A renderer, valid for the current scope.
+ */
+export declare const make: (options: NodeRendererOptions) => Effect.Effect<NodeRenderer, ThreeException, Scope.Scope>;
+export {};