@effect-motion/renderer 0.5.0 → 0.6.0

package/dist/Builtins.js

@@ -343,10 +343,10 @@ const disposePathChild = (child) => {
     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.
+// Layout and glyph commits are async (shaping + 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);
@@ -369,7 +369,8 @@ const text = {
             data.textAnchor,
             data.baseline,
         ].join("|");
-        if (retained.object.userData.textKey !== key) {
+        const keyChanged = retained.object.userData.textKey !== key;
+        if (keyChanged) {
             retained.object.userData.textKey = key;
             ctx.waitFor(Text.layout(ctx.text, {
                 text: data.text,
@@ -377,10 +378,23 @@ const text = {
                 fontSize: data.fontSize,
                 textAnchor: data.textAnchor,
                 baseline: data.baseline,
-            }).pipe(Effect.map((quads) => textMesh.setQuads(quads))));
+            }).pipe(Effect.flatMap((result) => {
+                textMesh.setLayout(result);
+                return textMesh.commit();
+            })));
         }
         const { r, g, b, a } = Color.bytes(data.fillColor);
-        textMesh.setColor(r, g, b, (a / 255) * data.opacity);
+        const alpha = (a / 255) * data.opacity;
+        const colorKey = `${r}|${g}|${b}|${alpha}`;
+        if (retained.object.userData.textColorKey !== colorKey) {
+            retained.object.userData.textColorKey = colorKey;
+            textMesh.setColor(r, g, b, alpha);
+            // a layout commit is already queued on key change; only a pure
+            // color/opacity change needs its own
+            if (!keyChanged) {
+                ctx.waitFor(textMesh.commit());
+            }
+        }
         retained.object.position.copy(ctx.toThree(leaf.world.x, leaf.world.y, leaf.world.z));
     },
 };

package/dist/Renderer.d.ts

@@ -1,5 +1,5 @@
 import type { ThreeException } from "@effect-motion/three";
-import { Renderer as Gpu } from "@effect-motion/three";
+import { Renderer as Gpu, PostProcessing } from "@effect-motion/three";
 import { Effect, Scope } from "effect";
 import type { EffectMotionError } from "effect-motion";
 import type { Frame } from "effect-motion/Scene";
@@ -40,6 +40,36 @@ type AnyEntityRenderer = EntityRenderer<never>;
  * fails.
  */
 export declare const renderCompTargets: (renderer: Gpu.Renderer, sync: Sync.Sync, pixelRatio: number) => Effect.Effect<void, ThreeException, never>;
+/**
+ * Depth-of-field sample quality: `"full"` is the node's default tap count
+ * (export quality); `"realtime"` halves it — about half the GPU cost, a
+ * little more sample noise, same blur shape and edges.
+ */
+export type DofQuality = "realtime" | "full";
+/**
+ * The depth-aware DoF node over a sync's world scene.
+ *
+ * @remarks
+ * Internal, shared by both render paths. Built once per renderer, the first
+ * time a frame asks for DoF; {@link setDofUniforms} feeds it each frame.
+ *
+ * `maxBlurPx` is the node default (30 render px) here; the browser path
+ * rescales it per frame with the pixel ratio (see {@link renderWorldWithDof}).
+ * Node export keeps 30 render px.
+ */
+export declare const makeDofNode: (sync: Sync.Sync, quality?: DofQuality) => PostProcessing.DepthAwareDofNode;
+/** Copy this frame's focus and lens radius into the DoF node's uniforms. */
+export declare const setDofUniforms: (node: PostProcessing.DepthAwareDofNode, dof: Sync.DofState) => void;
+/**
+ * A compositor that blends a sync's HUD pass over a world color node.
+ *
+ * @remarks
+ * Internal, shared by both render paths. The HUD pass (identity camera,
+ * transparent background) is blended INSIDE the pipeline, so the sRGB output
+ * transform applies exactly once. ponytail: TSL typing quarantined as in
+ * Text.ts.
+ */
+export declare const makeHudOver: (sync: Sync.Sync) => ((world: unknown) => unknown);
 export interface MakeOptions {
     /** Canvas to draw into; one is created if omitted. */
     readonly canvas?: HTMLCanvasElement;
@@ -59,6 +89,15 @@ export interface MakeOptions {
      * Merged over the built-in manifest by entity tag.
      */
     readonly renderers?: Record<string, AnyEntityRenderer>;
+    /**
+     * Depth-of-field sample quality. `"realtime"` halves the blur's gather
+     * taps, about half the blur's GPU time, for a little more sample noise;
+     * pass `"full"` for export-quality blur (what the Node renderer always
+     * uses) when frame rate does not matter, e.g. recording the canvas.
+     *
+     * @defaultValue `"realtime"`
+     */
+    readonly dofQuality?: DofQuality;
 }
 /**
  * A live browser renderer.
@@ -79,6 +118,15 @@ export interface Renderer {
      * their own.
      */
     readonly scope: Scope.Scope;
+    /** Depth-of-field sample quality, from {@link MakeOptions.dofQuality}. */
+    readonly dofQuality: DofQuality;
+    /** internal: the DoF pipeline, built the first time a frame asks for it */
+    dofChain: {
+        readonly node: PostProcessing.DepthAwareDofNode;
+        readonly pipeline: PostProcessing.RenderPipeline;
+        /** the same chain with the HUD composited over the DoF output */
+        readonly pipelineWithHud: PostProcessing.RenderPipeline;
+    } | null;
 }
 /**
  * Resize the drawing buffer.
@@ -133,8 +181,9 @@ export declare const resolveResources: (renderer: Renderer, frame: AnyFrame) =>
  * 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`.
+ * With a camera `aperture > 0` the world draws through the depth-aware
+ * depth-of-field chain (built on first use); at aperture 0 it is never
+ * touched. HUD content is drawn after it and stays sharp.
  */
 export declare const render: (renderer: Renderer) => Effect.Effect<void, ThreeException | EffectMotionError>;
 /**

package/dist/Renderer.js

@@ -1,4 +1,4 @@
-import { Renderer as Gpu, RenderTarget, Scene as ThreeScene, } from "@effect-motion/three";
+import { Renderer as Gpu, PostProcessing, RenderTarget, Scene as ThreeScene, } from "@effect-motion/three";
 import { Effect, Scope } from "effect";
 import { dual } from "effect/Function";
 import { builtinRegistry } from "./Builtins.js";
@@ -36,6 +36,71 @@ export const renderCompTargets = Effect.fnUntraced(function* (renderer, sync, pi
         yield* Gpu.render(renderer, comp.sync.scene, comp.sync.camera).pipe(Effect.ensuring(Effect.sync(() => Gpu.setRenderTarget(renderer, previous))));
     }
 });
+/**
+ * The depth-aware DoF node over a sync's world scene.
+ *
+ * @remarks
+ * Internal, shared by both render paths. Built once per renderer, the first
+ * time a frame asks for DoF; {@link setDofUniforms} feeds it each frame.
+ *
+ * `maxBlurPx` is the node default (30 render px) here; the browser path
+ * rescales it per frame with the pixel ratio (see {@link renderWorldWithDof}).
+ * Node export keeps 30 render px.
+ */
+export const makeDofNode = (sync, quality = "full") => PostProcessing.depthAwareDof(PostProcessing.pass(sync.scene, sync.camera), {
+    focusDistance: sync.dof.focusDistance,
+    aperture: sync.dof.aperture,
+    // ponytail: a fixed half tap count, about half the blur's GPU time.
+    // Scale taps by pixel count or measured frame time if a bigger canvas
+    // or slower GPU still drops frames.
+    ...(quality === "realtime" ? { taps: { near: 32, far: 24 } } : {}),
+});
+/** Copy this frame's focus and lens radius into the DoF node's uniforms. */
+export const setDofUniforms = (node, dof) => {
+    node.focusDistance.value = dof.focusDistance;
+    node.aperture.value = dof.aperture;
+};
+/**
+ * A compositor that blends a sync's HUD pass over a world color node.
+ *
+ * @remarks
+ * Internal, shared by both render paths. The HUD pass (identity camera,
+ * transparent background) is blended INSIDE the pipeline, so the sRGB output
+ * transform applies exactly once. ponytail: TSL typing quarantined as in
+ * Text.ts.
+ */
+export const makeHudOver = (sync) => {
+    const hudTex = PostProcessing.pass(sync.hudScene, sync.hudCamera).getTextureNode();
+    return (world) => world.mul(hudTex.a.oneMinus()).add(hudTex.rgb.mul(hudTex.a));
+};
+/**
+ * Draw the world through the DoF pipeline, building it on first use.
+ *
+ * @remarks
+ * The chain's render targets dedupe per three frame, so the frame counter is
+ * advanced here — a player can render several frames within one rAF tick.
+ *
+ * HUD content is composited inside the pipeline: the pipeline writes the
+ * canvas directly, so a second plain canvas render would present three's
+ * internal framebuffer — which never saw the DoF output — over it.
+ */
+const renderWorldWithDof = (renderer, hud) => {
+    if (renderer.dofChain === null) {
+        const node = makeDofNode(renderer.sync, renderer.dofQuality);
+        renderer.dofChain = {
+            node,
+            pipeline: PostProcessing.makePipeline(renderer.gpu, node),
+            pipelineWithHud: PostProcessing.makePipeline(renderer.gpu, makeHudOver(renderer.sync)(node)),
+        };
+    }
+    setDofUniforms(renderer.dofChain.node, renderer.sync.dof);
+    // the blur cap is in render px; the Player's pixel ratio follows the
+    // displayed size, so scale the cap with it (30 logical px) to keep the
+    // look stable, clamped to the node's 48 px dilation reach
+    renderer.dofChain.node.maxBlurPx.value = Math.min(48, 30 * Gpu.getPixelRatio(renderer.gpu));
+    Gpu.advanceFrame(renderer.gpu);
+    return PostProcessing.render(hud ? renderer.dofChain.pipelineWithHud : renderer.dofChain.pipeline);
+};
 /**
  * `dual`'s predicate gets the whole `arguments` object — dispatch on
  * args[0]. Renderer is a plain interface (not branded), so this is a
@@ -102,26 +167,33 @@ export const resolveResources = (renderer, frame) => Sync.resolveResources(rende
  * 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`.
+ * With a camera `aperture > 0` the world draws through the depth-aware
+ * depth-of-field chain (built on first use); at aperture 0 it is never
+ * touched. HUD content is drawn after it and stays sharp.
  */
-export const render = (renderer) => Sync.whenReady(renderer.sync).pipe(Effect.flatMap(() => renderCompTargets(renderer.gpu, renderer.sync, Gpu.getPixelRatio(renderer.gpu))), Effect.flatMap(() => 
-// ponytail: no depth of field — every frame renders sharp, and
-// Sync still derives the camera's DoF state for a future rebuild.
-Gpu.render(renderer.gpu, renderer.sync.scene, renderer.sync.camera)), Effect.flatMap(() => {
-    // HUD overlay: identity camera, above everything, DoF-exempt
-    if (ThreeScene.isEmpty(renderer.sync.hudScene)) {
-        return Effect.void;
+export const render = (renderer) => Sync.whenReady(renderer.sync).pipe(Effect.flatMap(() => renderCompTargets(renderer.gpu, renderer.sync, Gpu.getPixelRatio(renderer.gpu))), Effect.flatMap(() => {
+    const hud = !ThreeScene.isEmpty(renderer.sync.hudScene);
+    if (renderer.sync.dof.on) {
+        // HUD composited inside the DoF pipeline — see renderWorldWithDof
+        return renderWorldWithDof(renderer, hud);
     }
-    return Effect.sync(() => {
-        Gpu.setAutoClear(renderer.gpu, false);
-        Gpu.clearDepth(renderer.gpu);
-    }).pipe(Effect.flatMap(() => Gpu.render(renderer.gpu, renderer.sync.hudScene, renderer.sync.hudCamera)), 
-    // autoClear must come back on even when the hud render fails
-    Effect.ensuring(Effect.sync(() => {
-        Gpu.setAutoClear(renderer.gpu, true);
-    })));
+    const world = Gpu.render(renderer.gpu, renderer.sync.scene, renderer.sync.camera);
+    if (!hud) {
+        return world;
+    }
+    // HUD overlay: identity camera, above everything. Both passes go
+    // through three's internal framebuffer, so the overlay loads the
+    // world it sits on.
+    return world.pipe(Effect.andThen(renderHudOverlay(renderer)));
 }));
+const renderHudOverlay = (renderer) => Effect.sync(() => {
+    Gpu.setAutoClear(renderer.gpu, false);
+    Gpu.clearDepth(renderer.gpu);
+}).pipe(Effect.flatMap(() => Gpu.render(renderer.gpu, renderer.sync.hudScene, renderer.sync.hudCamera)), 
+// autoClear must come back on even when the hud render fails
+Effect.ensuring(Effect.sync(() => {
+    Gpu.setAutoClear(renderer.gpu, true);
+})));
 /**
  * Compile shader pipelines ahead of showing anything.
  *
@@ -172,5 +244,11 @@ export const make = Effect.fn("Renderer.make")(function* (options) {
     });
     yield* Effect.addFinalizer(() => Sync.dispose(sync));
     const scope = yield* Effect.scope;
-    return { sync, gpu, scope };
+    return {
+        sync,
+        gpu,
+        scope,
+        dofQuality: options.dofQuality ?? "realtime",
+        dofChain: null,
+    };
 });

package/dist/Sync.d.ts

@@ -35,18 +35,17 @@ export interface SyncStats {
  * The depth-of-field request derived from a frame's camera.
  *
  * @remarks
- * Currently computed but NOT consumed: depth-of-field rendering is not
- * implemented, and both render paths draw every frame sharp. The values are
- * kept in step with the camera so the feature can be rebuilt without
- * re-deriving them.
+ * Both render paths read it per frame: when `on`, the world draws through the
+ * depth-aware DoF post chain with these values as its uniforms; otherwise the
+ * plain path runs and the chain is never touched.
  */
 export interface DofState {
     /** Whether the camera asked for DoF (`aperture` and `focusDistance` both > 0). */
     on: boolean;
-    /** View-space distance to the intended sharp plane. */
+    /** View-space distance to the sharp plane, world units. */
     focusDistance: number;
-    /** Blur radius in uv units, derived from the aperture; 0 is off. */
-    strengthUv: number;
+    /** Lens radius, world units; 0 is a pinhole (off). */
+    aperture: number;
 }
 /**
  * A nested scene (from `Scene.play`) as the renderer holds it.
@@ -102,10 +101,7 @@ export interface Sync {
     readonly hudScene: ThreeScene.Scene;
     readonly hudCamera: THREE.PerspectiveCamera;
     readonly stats: SyncStats;
-    /**
-     * Depth-of-field request derived from the frame's camera — currently
-     * derived but not drawn. See {@link DofState}.
-     */
+    /** Depth-of-field request derived from the frame's camera. See {@link DofState}. */
     readonly dof: DofState;
     /** the renderer's SDF text actor (fonts, atlas, layout) */
     readonly text: Text.Text;

package/dist/Sync.js

@@ -66,7 +66,7 @@ export const make = (registry) => {
         hudScene: ThreeScene.makeUnsafe(new THREE.Scene()),
         hudCamera: new THREE.PerspectiveCamera(50, 1, NEAR, FAR),
         stats: { objects: 0, lastSyncMs: 0 },
-        dof: { on: false, focusDistance: 0, strengthUv: 0 },
+        dof: { on: false, focusDistance: 0, aperture: 0 },
         text: Text.make(),
         images: Images.make(),
         comps: new Map(),
@@ -146,10 +146,7 @@ const syncCameras = (sync, frame) => {
     ThreeScene.setBackground(sync.scene, sync.background);
     sync.dof.on = camera.aperture > 0 && camera.focusDistance > 0;
     sync.dof.focusDistance = camera.focusDistance;
-    // aperture → uv-space CoC scale, matched against the ThorVG sigma
-    // curve (sigma = aperture·f·|d−F|/(d·F) ≈ aperture·|d−F|/F at rest):
-    // blur radius ≈ 2σ → strength = 2·aperture / viewport height.
-    sync.dof.strengthUv = (camera.aperture * 2) / frame.height;
+    sync.dof.aperture = camera.aperture;
 };
 /**
  * Phase 2 — walk the instance tree, collecting leaves and syncing comps.
@@ -461,10 +458,12 @@ export const resolveResources = Effect.fnUntraced(function* (sync, frame) {
     for (const family of fonts) {
         const provided = Context.getOption(context, Font.Loader(family));
         if (provided._tag === "Some") {
-            Text.registerFont(sync.text, family, provided.value.bytes);
+            // a provided font whose bytes fail to parse is a broken asset — a
+            // loud defect naming the font, like the missing-loader path below
+            yield* Effect.orDie(Text.registerFont(sync.text, family, provided.value.bytes));
         }
         else if (family === Font.defaultFont.id) {
-            Text.registerFont(sync.text, family, yield* Font.loadDefaultBytes);
+            yield* Effect.orDie(Text.registerFont(sync.text, family, yield* Font.loadDefaultBytes));
         }
         else {
             return yield* Effect.die(new Error(`Renderer: no font loader provided for "${family}" — provide it via Font.layer(${JSON.stringify(family)}, ...)`));

package/dist/Text.d.ts

@@ -1,34 +1,56 @@
 import { ThreeRaw as THREE } from "@effect-motion/three";
+import { type FontHandle } from "@text-rendering-toolkit/font";
+import { type LayoutResult } from "@text-rendering-toolkit/layout";
+import { TextResources } from "@text-rendering-toolkit/three-webgpu";
 import { Effect } from "effect";
 import { EffectMotionError } from "effect-motion";
-import createSdfGenerator from "webgl-sdf-generator";
-interface GlyphSlot {
-    /** atlas UV rect [u0, v0, u1, v1] */
-    readonly uv: [number, number, number, number];
-    /** SDF viewbox in font units [minX, minY, maxX, maxY] */
-    readonly viewBox: [number, number, number, number];
-}
 /**
- * A laid-out string: where each glyph goes and which part of the atlas it
- * samples.
+ * Text rendering: fonts, glyph atlas, and layout.
  *
  * @remarks
- * Coordinates are mesh-local and y-UP (three's convention), not scene
- * coordinates.
+ * 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.
+ *
+ * The pipeline is `@text-rendering-toolkit`: HarfBuzz shaping and glyph
+ * outlines (`/font`), anchoring and line layout (`/layout`), and the
+ * `WebGPURenderer` glyph mesh (`/three-webgpu`) in its `depthInk` mode —
+ * fully-covered ink blends exactly once per pixel at any opacity and writes
+ * the depth buffer, so text participates in the renderer's z-buffer
+ * occlusion. The same code path serves browser and headless Node; the glyph
+ * atlas is shared per renderer and grows on demand.
+ *
+ * This module is the adapter: it owns the per-renderer font handles and
+ * atlas resources, maps entity anchor semantics onto layout anchors, and
+ * wraps every toolkit boundary in typed effects.
  */
-export interface GlyphQuads {
-    /** Per-glyph quad bounds, four numbers each: minX, minY, maxX, maxY. */
-    readonly bounds: Float32Array;
-    /** Per-glyph atlas UV rects, four numbers each: u0, v0, u1, v1. */
-    readonly uvRects: Float32Array;
-    /** How many glyphs — `bounds` and `uvRects` hold four numbers per glyph. */
-    readonly count: number;
-    /**
-     * The whole text block's bounds before the anchor offset — the measured
-     * size of the string.
-     */
-    readonly blockBounds: [number, number, number, number];
+/**
+ * The per-renderer text state: loaded fonts and the shared glyph resources.
+ *
+ * @remarks
+ * Owned by a `Sync` and disposed with it, after every mesh borrowing the
+ * resources (borrowers before owner). Mostly data — the API is the sibling
+ * functions ({@link registerFont}, {@link layout}, {@link makeMesh}).
+ */
+export interface Text {
+    /** internal: shared glyph SDF cache + atlas for every mesh of this renderer */
+    readonly resources: TextResources;
+    /** internal: font id → loaded caller-owned handle */
+    readonly fonts: Map<string, FontHandle>;
 }
+export declare const make: () => Text;
+/**
+ * Load 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. Effectful
+ * because font parsing initializes WASM shaping state.
+ */
+export declare const registerFont: (text: Text, id: string, bytes: Uint8Array) => Effect.Effect<void, EffectMotionError>;
+export declare const hasFont: (text: Text, id: string) => boolean;
+export declare const dispose: (text: Text) => void;
 /** What to lay out: the string, the font, its size, and its alignment. */
 export interface LayoutRequest {
     readonly text: string;
@@ -49,84 +71,40 @@ export interface LayoutRequest {
     readonly baseline?: "auto" | "middle" | "hanging" | undefined;
 }
 /**
- * The per-renderer text state: registered fonts, the shared SDF atlas, and
- * the glyph cache.
- *
- * @remarks
- * Owned by a `Sync` and disposed with it. Mostly data — the API is the
- * sibling functions ({@link registerFont}, {@link layout},
- * {@link makeMesh}).
- */
-export interface Text {
-    readonly atlas: THREE.DataTexture;
-    /** internal: raw atlas bytes the texture samples */
-    readonly atlasData: Uint8Array;
-    /** internal: font id → data URI */
-    readonly fonts: Map<string, string>;
-    /** internal: `${fontSrc}#${glyphId}` → atlas slot */
-    readonly glyphs: Map<string, GlyphSlot>;
-    /** internal: next free atlas cell */
-    glyphCount: number;
-    /** internal: the pure-JS SDF generator instance */
-    readonly sdf: ReturnType<typeof createSdfGenerator>;
-    /** internal: memoized typesetter init */
-    typesetter: Promise<import("troika-three-text").Typesetter> | undefined;
-}
-export declare const make: () => Text;
-/**
- * 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 declare const registerFont: (text: Text, id: string, bytes: Uint8Array) => void;
-export declare const hasFont: (text: Text, id: string) => boolean;
-export declare const dispose: (text: Text) => void;
-/**
- * Lay out a string into positioned glyph quads.
+ * Lay out a string into a renderer-neutral {@link LayoutResult}.
  *
  * @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).
+ * Shapes and positions the glyphs with the anchor and baseline offsets
+ * applied. By default the text's baseline-left sits at local (0, 0).
+ * Coordinates are y-up layout units, axis-identical to scene space.
  *
- * 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.
+ * Layout failures arrive as typed errors naming the font. The font must be
+ * registered first — an unregistered font is a defect.
  */
-export declare const layout: (text: Text, request: LayoutRequest) => Effect.Effect<GlyphQuads, EffectMotionError, never>;
-/** A glyph mesh over the shared atlas, with its update and release hooks. */
+export declare const layout: (text: Text, request: LayoutRequest) => Effect.Effect<LayoutResult, EffectMotionError, never>;
+/** A glyph mesh over the shared resources, with its update and release hooks. */
 export interface TextMesh {
     readonly mesh: THREE.Object3D;
-    /** Point the mesh at a new layout — call after {@link layout} resolves. */
-    readonly setQuads: (quads: GlyphQuads) => void;
-    /** Set the fill color; `r`, `g`, `b` are 0–1, `a` is opacity. */
+    /** Point the mesh at a new layout — pair with {@link TextMesh.commit}. */
+    readonly setLayout: (layout: LayoutResult) => void;
+    /** Set the fill color; `r`, `g`, `b` are 0–255, `a` is 0–1 opacity. */
     readonly setColor: (r: number, g: number, b: number, a: number) => void;
-    /** Release the mesh's geometry and materials. */
+    /** Flush pending layout/appearance changes into the GPU state. */
+    readonly commit: () => Effect.Effect<void, EffectMotionError>;
+    /** Release the mesh's geometry and materials (shared resources stay). */
     readonly dispose: () => void;
 }
 /**
- * Build a mesh that draws glyphs from the shared atlas.
+ * Build a mesh that draws glyphs from the shared resources.
  *
  * @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 toolkit mesh is created lazily on the first {@link TextMesh.setLayout}
+ * — its constructor requires a layout, and a text entity has none until its
+ * first layout resolves. Appearance setters are inert until
+ * {@link TextMesh.commit} runs; the entity renderer registers commits with
+ * `ctx.waitFor`, so a frame is never drawn with half-built text.
  *
  * The mesh carries a tiny z-lift so text sits above coplanar backdrops
  * (invisible at ordinary scales, deterministic).
  */
 export declare const makeMesh: (text: Text) => TextMesh;
-export {};

package/dist/Text.js

@@ -1,318 +1,140 @@
-import { ThreeRaw as THREE, Tsl } from "@effect-motion/three";
+import { ThreeRaw as THREE } from "@effect-motion/three";
+import { loadFont } from "@text-rendering-toolkit/font";
+import { layoutText, } from "@text-rendering-toolkit/layout";
+import { Text as GlyphText, TextResources, } from "@text-rendering-toolkit/three-webgpu";
 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,
-    };
-};
+export const make = () => ({
+    resources: new TextResources(),
+    fonts: new Map(),
+});
 /**
- * Register a font's bytes under its id.
+ * Load 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.
+ * laid out; `Sync.resolveResources` handles that for frames. Effectful
+ * because font parsing initializes WASM shaping state.
  */
-export const registerFont = (text, id, bytes) => {
-    if (!text.fonts.has(id)) {
-        text.fonts.set(id, `data:font/ttf;base64,${toBase64(bytes)}`);
-    }
-};
+export const registerFont = (text, id, bytes) => text.fonts.has(id)
+    ? Effect.void
+    : Effect.tryPromise({
+        try: async () => {
+            const handle = await loadFont(bytes);
+            text.fonts.set(id, handle);
+        },
+        catch: (cause) => EffectMotionError.of(`Text: font "${id}" could not be loaded`, cause),
+    });
 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`);
+    for (const handle of text.fonts.values()) {
+        handle.dispose();
     }
-    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;
+    text.fonts.clear();
+    text.resources.dispose();
 };
+// entity anchor semantics → layout anchors; the defaults preserve
+// baseline-left at local (0, 0)
+const anchorXOf = (anchor) => anchor === "middle" ? "center" : anchor === "end" ? "right" : "left";
+const anchorYOf = (baseline) => baseline === "middle"
+    ? "middle"
+    : baseline === "hanging"
+        ? "top"
+        : "top-baseline";
 /**
- * Lay out a string into positioned glyph quads.
+ * Lay out a string into a renderer-neutral {@link LayoutResult}.
  *
  * @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).
+ * Shapes and positions the glyphs with the anchor and baseline offsets
+ * applied. By default the text's baseline-left sits at local (0, 0).
+ * Coordinates are y-up layout units, axis-identical to scene space.
  *
- * 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.
+ * Layout 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) {
+    if (!text.fonts.has(request.fontId)) {
         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),
+        try: () => layoutText({
+            text: request.text,
+            style: {
+                key: "fill",
+                fontKeys: [request.fontId],
+                fontSize: request.fontSize,
+                language: "und",
+            },
+            layout: {
+                anchorX: anchorXOf(request.textAnchor),
+                anchorY: anchorYOf(request.baseline),
+            },
+        }, text.fonts),
+        catch: (cause) => EffectMotionError.of(`Text: layout 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.
+ * Build a mesh that draws glyphs from the shared resources.
  *
  * @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 toolkit mesh is created lazily on the first {@link TextMesh.setLayout}
+ * — its constructor requires a layout, and a text entity has none until its
+ * first layout resolves. Appearance setters are inert until
+ * {@link TextMesh.commit} runs; the entity renderer registers commits with
+ * `ctx.waitFor`, so a frame is never drawn with half-built text.
  *
  * 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;
+    const color = new THREE.Color(1, 1, 1);
+    let opacity = 1;
+    let glyphs = null;
+    const applyAppearance = (mesh) => {
+        mesh.color = color;
+        mesh.opacity = opacity;
     };
     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);
+        setLayout: (layoutResult) => {
+            if (glyphs === null) {
+                glyphs = new GlyphText({
+                    layout: layoutResult,
+                    fonts: text.fonts,
+                    resources: text.resources,
+                    depthInk: true,
+                });
+                // z-lift: keep text above coplanar backdrops so the depth-ink
+                // core never loses to a shape at the same depth
+                glyphs.position.z = 0.05;
+                group.add(glyphs);
+            }
+            else {
+                glyphs.layout = layoutResult;
+            }
+            applyAppearance(glyphs);
         },
         setColor: (r, g, b, a) => {
-            for (const material of [coreMaterial, edgeMaterial]) {
-                material.color.setRGB(r / 255, g / 255, b / 255, THREE.SRGBColorSpace);
+            color.setRGB(r / 255, g / 255, b / 255, THREE.SRGBColorSpace);
+            opacity = a;
+            group.visible = a > 0;
+            if (glyphs !== null) {
+                applyAppearance(glyphs);
             }
-            uOpacity.value = a;
-            setVisible(a > 0);
         },
+        commit: () => Effect.suspend(() => {
+            const target = glyphs;
+            return target === null
+                ? Effect.void
+                : Effect.tryPromise({
+                    try: () => target.sync(),
+                    catch: (cause) => EffectMotionError.of("Text: glyph commit failed", cause),
+                });
+        }),
         dispose: () => {
-            geometry.dispose();
-            coreMaterial.dispose();
-            edgeMaterial.dispose();
+            glyphs?.dispose();
         },
     };
 };

package/dist/node.d.ts

@@ -102,6 +102,17 @@ export interface NodeRenderer {
     readonly post: PostProcessing.RenderPipeline;
     /** internal: pipeline with the HUD pass composited over the world */
     readonly postWithHud: PostProcessing.RenderPipeline;
+    /**
+     * internal: DoF variants of `post` / `postWithHud` (HUD composited over
+     * the DoF output, so it stays sharp), built the first time a frame asks
+     */
+    dofChain: {
+        readonly node: PostProcessing.DepthAwareDofNode;
+        readonly post: PostProcessing.RenderPipeline;
+        readonly postWithHud: PostProcessing.RenderPipeline;
+    } | null;
+    /** internal: blends the HUD pass over a world color node */
+    readonly overHud: (world: unknown) => unknown;
     /** internal: the readback render target */
     readonly target: RenderTarget.RenderTarget;
     readonly width: number;
@@ -148,7 +159,9 @@ export declare const renderToPng: (renderer: NodeRenderer, frame: AnyFrame) => E
  * 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.
+ * A camera with `aperture > 0` renders through the depth-aware
+ * depth-of-field chain, built on the first frame that asks for it; HUD
+ * content is composited over the result and stays sharp.
  *
  * @param options - Dimensions, supersampling, and any custom entity
  *   renderers.

package/dist/node.js

@@ -5,7 +5,7 @@ import { Renderer as Gpu, PostProcessing, RenderTarget, Scene as ThreeScene, } f
 import * as NodeGpu from "@effect-motion/three/node";
 import { Effect, Scope } from "effect";
 import { builtinRegistry } from "./Builtins.js";
-import { renderCompTargets } from "./Renderer.js";
+import { makeDofNode, makeHudOver, renderCompTargets, setDofUniforms, } from "./Renderer.js";
 import * as Sync from "./Sync.js";
 // ── minimal RGBA → PNG encoder (filter 0 + zlib), lifted from the ThorVG
 // package's node PNG path; node:zlib does the compression ────────────────
@@ -129,9 +129,20 @@ export const renderToPng = Effect.fnUntraced(function* (renderer, frame) {
     // ensuring, addFinalizer.
     Gpu.advanceFrame(renderer.gpu);
     yield* renderCompTargets(renderer.gpu, renderer.sync, renderer.pixelRatio);
-    const pipeline = ThreeScene.isEmpty(renderer.sync.hudScene)
-        ? renderer.post
-        : renderer.postWithHud;
+    const hud = !ThreeScene.isEmpty(renderer.sync.hudScene);
+    let pipeline = hud ? renderer.postWithHud : renderer.post;
+    if (renderer.sync.dof.on) {
+        if (renderer.dofChain === null) {
+            const node = makeDofNode(renderer.sync);
+            renderer.dofChain = {
+                node,
+                post: PostProcessing.makePipeline(renderer.gpu, node),
+                postWithHud: PostProcessing.makePipeline(renderer.gpu, renderer.overHud(node)),
+            };
+        }
+        setDofUniforms(renderer.dofChain.node, renderer.sync.dof);
+        pipeline = hud ? renderer.dofChain.postWithHud : renderer.dofChain.post;
+    }
     yield* PostProcessing.render(pipeline);
     const rgba = yield* Gpu.readRenderTarget(renderer.gpu, renderer.target, renderer.pixelWidth, renderer.pixelHeight);
     return encodePng(rgba, renderer.pixelWidth, renderer.pixelHeight);
@@ -152,7 +163,9 @@ export const renderToPng = Effect.fnUntraced(function* (renderer, frame) {
  * 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.
+ * A camera with `aperture > 0` renders through the depth-aware
+ * depth-of-field chain, built on the first frame that asks for it; HUD
+ * content is composited over the result and stays sharp.
  *
  * @param options - Dimensions, supersampling, and any custom entity
  *   renderers.
@@ -180,13 +193,12 @@ export const make = Effect.fn("NodeRenderer.make")(function* (options) {
     });
     yield* Effect.addFinalizer(() => Sync.dispose(sync));
     const scenePass = PostProcessing.pass(sync.scene, sync.camera);
-    // ponytail: no depth of field — the pipeline draws the scene pass
-    // straight through.
     const sceneColor = scenePass.getTextureNode();
     const post = PostProcessing.makePipeline(gpu, sceneColor);
-    const hudScenePass = PostProcessing.pass(sync.hudScene, sync.hudCamera);
-    const hudTex = hudScenePass.getTextureNode();
-    const postWithHud = PostProcessing.makePipeline(gpu, sceneColor.mul(hudTex.a.oneMinus()).add(hudTex.rgb.mul(hudTex.a)));
+    // HUD composite variant, chosen per frame only when HUD content exists —
+    // the plain pipeline never pays for the pass
+    const overHud = makeHudOver(sync);
+    const postWithHud = PostProcessing.makePipeline(gpu, overHud(sceneColor));
     const target = yield* RenderTarget.make(pixelWidth, pixelHeight);
     Gpu.setRenderTarget(gpu, target);
     const scope = yield* Effect.scope;
@@ -196,6 +208,8 @@ export const make = Effect.fn("NodeRenderer.make")(function* (options) {
         scope,
         post,
         postWithHud,
+        dofChain: null,
+        overHud,
         target,
         width: options.width,
         height: options.height,

package/package.json

@@ -1,65 +1,66 @@
 {
-  "name": "@effect-motion/renderer",
-  "version": "0.5.0",
-  "description": "Retained three.js frame renderer for effect-motion",
-  "type": "module",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/julia-script/effect-motion.git",
-    "directory": "packages/renderer"
-  },
-  "homepage": "https://github.com/julia-script/effect-motion#readme",
-  "bugs": "https://github.com/julia-script/effect-motion/issues",
-  "keywords": [
-    "effect",
-    "motion",
-    "renderer",
-    "three",
-    "webgpu",
-    "motion-graphics"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./*": {
-      "types": "./dist/*.d.ts",
-      "default": "./dist/*.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@effect/platform-node": "4.0.0-beta.98",
-    "@types/three": "^0.185.1",
-    "jpeg-js": "^0.4.4",
-    "pngjs": "^7.0.0",
-    "three": "^0.185.1",
-    "troika-three-text": "^0.52.4",
-    "webgl-sdf-generator": "^1.1.1",
-    "@effect-motion/three": "^0.5.0",
-    "effect-motion": "^0.5.0"
-  },
-  "peerDependencies": {
-    "effect": ">=4.0.0-beta.98"
-  },
-  "devDependencies": {
-    "@types/node": "^26.1.1",
-    "@types/pngjs": "^6.0.5",
-    "effect": "4.0.0-beta.98",
-    "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
-    "test": "vitest run --passWithNoTests",
-    "check": "tsc --noEmit"
-  }
-}
+	"name": "@effect-motion/renderer",
+	"version": "0.6.0",
+	"description": "Retained three.js frame renderer for effect-motion",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/julia-script/effect-motion.git",
+		"directory": "packages/renderer"
+	},
+	"homepage": "https://github.com/julia-script/effect-motion#readme",
+	"bugs": "https://github.com/julia-script/effect-motion/issues",
+	"keywords": [
+		"effect",
+		"motion",
+		"renderer",
+		"three",
+		"webgpu",
+		"motion-graphics"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./*": {
+			"types": "./dist/*.d.ts",
+			"default": "./dist/*.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+		"test": "vitest run --passWithNoTests",
+		"check": "tsc --noEmit"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@effect-motion/three": "workspace:^",
+		"@effect/platform-node": "4.0.0-rc.115",
+		"@text-rendering-toolkit/font": "^0.3.0",
+		"@text-rendering-toolkit/layout": "^0.3.0",
+		"@text-rendering-toolkit/three-webgpu": "^0.3.0",
+		"@types/three": "^0.185.1",
+		"effect-motion": "workspace:^",
+		"jpeg-js": "^0.4.4",
+		"pngjs": "^7.0.0",
+		"three": "^0.185.1"
+	},
+	"peerDependencies": {
+		"effect": ">=4.0.0-rc.115"
+	},
+	"devDependencies": {
+		"@types/node": "^26.1.1",
+		"@types/pngjs": "^6.0.5",
+		"effect": "4.0.0-rc.115",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.10"
+	}
+}