@effect-motion/renderer 0.5.0

package/dist/Sync.js

@@ -0,0 +1,480 @@
+import { RenderTarget, ThreeRaw as THREE, Scene as ThreeScene, } from "@effect-motion/three";
+import { Context, Effect } from "effect";
+import { Color, Runner, } from "effect-motion";
+import * as Font from "effect-motion/Font";
+import * as ImageResource from "effect-motion/Image";
+import * as Projection from "effect-motion/Projection";
+import * as Images from "./Images.js";
+import { RenderException } from "./RenderException.js";
+import * as Text from "./Text.js";
+/**
+ * The GPU-free half of rendering: turning frames into a retained three
+ * scene.
+ *
+ * @remarks
+ * Everything here is plain three objects and no GPU, which is what makes
+ * the whole frame-to-scene-graph path testable without a device.
+ * `Renderer.make` and the Node adapter each wire a `Sync` to a real WebGPU
+ * renderer; this module never draws anything itself.
+ *
+ * Each frame runs four phases:
+ *
+ * 1. **Cameras** — resolve the world camera (including its point-of-interest
+ *    aim) into three's coordinate conventions, and set the background.
+ * 2. **Walk** — descend the instance tree, folding ancestor translations
+ *    into each leaf's world position and routing HUD subtrees to their own
+ *    tier.
+ * 3. **Diff** — build objects that are new, update ones that changed,
+ *    dispose ones that left.
+ * 4. **Billboards** — turn billboarded objects to face their tier's camera.
+ *
+ * This is the hot path — it runs per frame over every instance — so the
+ * inner loops are deliberately raw synchronous mutation rather than Effect
+ * combinators.
+ *
+ * Scene-graph violations throw from inside the recursive walk and are caught
+ * once at {@link syncFrame}'s seam, where they become a typed
+ * `RenderException`. Threading a result type through every level of a
+ * descent would cost checking and re-propagation at each step for a case
+ * that always aborts.
+ */
+const NEAR = 1;
+const FAR = 1_000_000;
+/** the renderer for a leaf, with the tag↔renderer pairing asserted once */
+const dispatch = (renderer) => renderer;
+// ── coordinate mapping ────────────────────────────────────────────────────
+// Scene space: x right, y up, origin at the viewport center, +z toward the
+// viewer, camera at rest on +z looking down -z — axis-identical to three.
+// Positions map by the IDENTITY, kept as the named `ctx.toThree` seam so
+// the boundary stays explicit. OBJECT rotations pass through unnegated:
+// scene Eulers apply X→Y→Z extrinsically (matrix Rz·Ry·Rx — see
+// Projection.ts's rotate), which is three's Euler order "ZYX" verbatim.
+// The CAMERA still conjugates: the scene view transform flips z before
+// rotating (in-front is +z view depth — see Projection.toView), so with
+// F = diag(1,1,-1) the three camera matrix is F-conjugated per axis:
+//   R_three = Rz(rz)·Ry(-ry)·Rx(-rx)  →  order "ZYX", set(-rx, -ry, rz)
+// unit plane centered on its anchor (matches the Builtins module's anchor)
+const unitPlaneShared = new THREE.PlaneGeometry(1, 1);
+export const make = (registry) => {
+    const camera = new THREE.PerspectiveCamera(50, 1, NEAR, FAR);
+    camera.rotation.order = "ZYX";
+    const base = {
+        // makeUnsafe: this Sync owns the scenes' lifetime through its own
+        // dispose, so they are not separately scope-registered
+        scene: ThreeScene.makeUnsafe(new THREE.Scene()),
+        camera,
+        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 },
+        text: Text.make(),
+        images: Images.make(),
+        comps: new Map(),
+        registry,
+        retained: new Map(),
+        background: new THREE.Color(),
+        width: 0,
+        height: 0,
+        pending: [],
+    };
+    const ctx = {
+        // scene space is axis-identical to three space — identity, kept as
+        // the named boundary seam
+        toThree: (x, y, z) => new THREE.Vector3(x, y, z),
+        get width() {
+            return base.width;
+        },
+        get height() {
+            return base.height;
+        },
+        waitFor: (work) => {
+            base.pending.push(work);
+        },
+        text: base.text,
+        images: base.images,
+    };
+    return Object.assign(base, { ctx });
+};
+/**
+ * Wait for the async work a sync registered — glyph layouts and image
+ * decodes — including inside nested sub-compositions.
+ *
+ * @remarks
+ * Both render paths call this before drawing, which is what guarantees a
+ * frame never presents half-built text or a missing texture. A failed layout
+ * or decode surfaces as a typed error naming the resource, rather than
+ * silently rendering nothing.
+ */
+export const whenReady = (sync) => Effect.suspend(() => {
+    const pending = sync.pending.splice(0, sync.pending.length);
+    const nested = [...sync.comps.values()].map((comp) => whenReady(comp.sync));
+    return pending.length === 0 && nested.length === 0
+        ? Effect.void
+        : Effect.all([...pending, ...nested], {
+            concurrency: "unbounded",
+            discard: true,
+        });
+});
+/**
+ * Phase 1 — cameras, background, and the DoF request.
+ *
+ * The world camera resolves its point-of-interest aim and conjugates into
+ * three's view convention (the scene view flips z — see the module's
+ * coordinate-mapping note); the HUD camera is the identity view, so z=0
+ * HUD content lands exactly where authored regardless of where the world
+ * camera went.
+ */
+const syncCameras = (sync, frame) => {
+    const camera = Projection.resolveCamera(frame.camera);
+    sync.camera.position.set(camera.x, camera.y, camera.z);
+    // camera conjugation (view z-flip) — see the coordinate-mapping note
+    sync.camera.rotation.set(-camera.rotX, -camera.rotY, camera.rotZ);
+    sync.camera.aspect = frame.width / frame.height;
+    sync.camera.fov =
+        (2 * Math.atan(frame.height / (2 * camera.focalLength)) * 180) / Math.PI;
+    sync.camera.updateProjectionMatrix();
+    const hudFocal = Projection.defaultFocalLength(frame.width);
+    sync.hudCamera.position.set(0, 0, Projection.defaultCameraZ(hudFocal));
+    sync.hudCamera.rotation.set(0, 0, 0);
+    sync.hudCamera.aspect = frame.width / frame.height;
+    sync.hudCamera.fov =
+        (2 * Math.atan(frame.height / (2 * hudFocal)) * 180) / Math.PI;
+    sync.hudCamera.updateProjectionMatrix();
+    ThreeScene.setBackground(sync.hudScene, null);
+    const bg = Color.bytes(frame.backgroundColor);
+    sync.background.setRGB(bg.r / 255, bg.g / 255, bg.b / 255, THREE.SRGBColorSpace);
+    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;
+};
+/**
+ * Phase 2 — walk the instance tree, collecting leaves and syncing comps.
+ *
+ * Containers contribute translation and recurse; sized groups become
+ * comps; everything else is a leaf. HUD subtrees route to the screen-space
+ * tier. THROWS on scene-graph violations — see the module doc.
+ */
+const walkTree = (sync, frame) => {
+    const leaves = [];
+    const visited = new Set();
+    const seenComps = new Set();
+    const walk = (id, offset, hud, inWorldContainer) => {
+        if (visited.has(id)) {
+            throw new Error(`Renderer: instance "${id}" is referenced more than once (duplicate parent or cycle)`);
+        }
+        visited.add(id);
+        const entry = frame.instances[id];
+        if (entry === undefined) {
+            throw new Error(`Renderer: unknown instance id "${id}"`);
+        }
+        // `visible` is an ordinary field on every paintable entity now; the
+        // camera is the one member without it, and never reaches the walk
+        if ("visible" in entry.data && !entry.data.visible) {
+            return;
+        }
+        const isHud = entry.data._tag === "Hud";
+        if (isHud && inWorldContainer) {
+            throw new Error(`Renderer: Hud "${id}" is nested inside world content — a Hud must be a top-level child of the root (or of another Hud)`);
+        }
+        const subtreeHud = hud || isHud;
+        // ponytail: ParticleField (the D10 escape hatch) carries flat x/y/z
+        // instead of a nested position; delete the fallback with the rewrite
+        const local = entry.data.position ??
+            entry.data;
+        const world = {
+            x: offset.x + local.x,
+            y: offset.y + local.y,
+            // a Hud's z is depth WITHIN the screen-space tier (design D12); it
+            // composes exactly like world depth, just in the HUD scene
+            z: offset.z + local.z,
+        };
+        const childIds = childIdsOf(entry.data);
+        // container-ness comes from the entity CARRYING children, not from
+        // having any: an empty Group (children appended later) renders
+        // nothing rather than dispatching to the throwing leaf slot
+        if ("children" in entry.data || isHud) {
+            // a comp is DECLARED by Scene.play, not inferred from a group
+            // carrying a size (design D13)
+            const size = frame.comps[id] ?? null;
+            if (size !== null) {
+                syncComp(sync, id, entry.data, size, world, subtreeHud, frame);
+                seenComps.add(id);
+                return;
+            }
+            // a pure container: contribute position, recurse, render
+            // nothing itself. ponytail: translation-only, matching the
+            // ThorVG walk — a Group's 2D affine transform is not yet
+            // threaded into child world coords.
+            for (const childId of childIds) {
+                walk(childId, world, subtreeHud, inWorldContainer || !subtreeHud);
+            }
+            return;
+        }
+        leaves.push({
+            leaf: { id, data: entry.data, world },
+            hud: subtreeHud,
+        });
+    };
+    const rootEntry = frame.instances[frame.root];
+    if (rootEntry !== undefined) {
+        visited.add(frame.root);
+        for (const childId of childIdsOf(rootEntry.data)) {
+            walk(childId, { x: 0, y: 0, z: 0 }, false, false);
+        }
+    }
+    return { leaves, seenComps };
+};
+/**
+ * Phase 3 — diff the walked leaves against the retained map: build what
+ * is new, update what changed (by reference equality on data and world
+ * position), dispose what left the frame. THROWS on an unregistered
+ * entity — see the module doc.
+ */
+const diffRetained = (sync, walked) => {
+    const seen = new Set();
+    for (const { leaf, hud } of walked.leaves) {
+        seen.add(leaf.id);
+        const existing = sync.retained.get(leaf.id);
+        if (existing === undefined) {
+            const renderer = sync.registry[leaf.data._tag];
+            if (renderer === undefined) {
+                throw new Error(`no entity renderer registered for "${leaf.data._tag}" — instance "${leaf.id}"`);
+            }
+            const retained = dispatch(renderer).build(leaf, sync.ctx);
+            sync.retained.set(leaf.id, {
+                renderer,
+                retained,
+                hud,
+                lastData: leaf.data,
+                lastWorld: leaf.world,
+            });
+            ThreeScene.add(hud ? sync.hudScene : sync.scene, [retained.object]);
+            continue;
+        }
+        const sameData = existing.lastData === leaf.data;
+        const sameWorld = existing.lastWorld.x === leaf.world.x &&
+            existing.lastWorld.y === leaf.world.y &&
+            existing.lastWorld.z === leaf.world.z;
+        if (!sameData || !sameWorld) {
+            dispatch(existing.renderer).update(existing.retained, leaf, sync.ctx);
+            existing.lastData = leaf.data;
+            existing.lastWorld = leaf.world;
+        }
+    }
+    for (const [id, entry] of sync.retained) {
+        if (!seen.has(id)) {
+            ThreeScene.remove(entry.hud ? sync.hudScene : sync.scene, [
+                entry.retained.object,
+            ]);
+            entry.retained.dispose();
+            sync.retained.delete(id);
+        }
+    }
+    for (const [id, comp] of sync.comps) {
+        if (!walked.seenComps.has(id)) {
+            ThreeScene.remove(comp.hud ? sync.hudScene : sync.scene, [comp.holder]);
+            disposeComp(comp);
+            sync.comps.delete(id);
+        }
+    }
+};
+/**
+ * Phase 4 — billboards face their tier's view plane: copy the camera
+ * quaternion so a circle stays circular under any camera orbit.
+ *
+ * ponytail: transparent depth ties break by three's stable sort over
+ * deterministic creation order (identical across runs and platforms given
+ * the deterministic frame stream); switch to a custom transparent sort
+ * keyed by instance id if cross-version stability ever matters.
+ */
+const syncBillboards = (sync) => {
+    for (const entry of sync.retained.values()) {
+        if (entry.retained.billboard) {
+            entry.retained.object.quaternion.copy(entry.hud ? sync.hudCamera.quaternion : sync.camera.quaternion);
+        }
+    }
+    for (const comp of sync.comps.values()) {
+        comp.holder.quaternion.copy(comp.hud ? sync.hudCamera.quaternion : sync.camera.quaternion);
+    }
+};
+/**
+ * The raw per-frame kernel: the four phases, unguarded. Internal — comps
+ * recurse through this, and their violations propagate to the outermost
+ * `syncFrame`'s single catch.
+ */
+const syncFrameUnsafe = (sync, frame) => {
+    const t0 = performance.now();
+    sync.width = frame.width;
+    sync.height = frame.height;
+    syncCameras(sync, frame);
+    diffRetained(sync, walkTree(sync, frame));
+    syncBillboards(sync);
+    sync.stats.objects = sync.retained.size;
+    sync.stats.lastSyncMs = performance.now() - t0;
+};
+/**
+ * Bring the retained scenes in step with a frame.
+ *
+ * @remarks
+ * Runs the four phases described in the module overview. Objects are built,
+ * updated, or disposed as the frame demands; unchanged ones are skipped by
+ * reference equality on their data and world position, so a still scene
+ * costs almost nothing to hold.
+ *
+ * Scene-graph violations arrive as a typed `RenderException` naming the
+ * offending instance — never as a thrown exception escaping into the
+ * caller's Effect.
+ */
+export const syncFrame = (sync, frame) => Effect.try({
+    try: () => syncFrameUnsafe(sync, frame),
+    catch: (cause) => RenderException.of(cause instanceof Error ? cause.message : "frame sync failed", cause),
+});
+/** child ids, or none — containers are the only entities with children */
+const childIdsOf = (data) => "children" in data ? data.children : [];
+const syncComp = (sync, id, groupData, compConfig, world, hud, frame) => {
+    let comp = sync.comps.get(id);
+    if (comp === undefined) {
+        const material = new THREE.MeshBasicNodeMaterial();
+        material.transparent = true;
+        material.side = THREE.DoubleSide;
+        const plane = new THREE.Mesh(unitPlaneShared, material);
+        const transformHolder = new THREE.Group();
+        transformHolder.add(plane);
+        const holder = new THREE.Group();
+        holder.add(transformHolder);
+        comp = {
+            sync: make(sync.registry),
+            holder,
+            transformHolder,
+            plane,
+            material,
+            rt: null,
+            width: compConfig.width,
+            height: compConfig.height,
+            hud,
+        };
+        sync.comps.set(id, comp);
+        ThreeScene.add(hud ? sync.hudScene : sync.scene, [holder]);
+    }
+    comp.width = compConfig.width;
+    comp.height = compConfig.height;
+    // inner sync: the comp's subtree in comp-local space under the
+    // identity camera, with the comp's own background (or transparent).
+    // Unsafe: violations inside a comp propagate to the outermost
+    // syncFrame's catch, which is the whole point of one seam per frame.
+    const background = compConfig.backgroundColor ?? null;
+    syncFrameUnsafe(comp.sync, {
+        ...frame,
+        root: id,
+        width: compConfig.width,
+        height: compConfig.height,
+        backgroundColor: background ?? Color.transparent,
+        camera: Runner.identityCameraView(compConfig.width),
+    });
+    if (background === null || Color.bytes(background).a === 0) {
+        ThreeScene.setBackground(comp.sync.scene, null);
+    }
+    // outer placement: center-anchored plane (a comp places like an Image of
+    // its own size), group opacity on the composite
+    comp.holder.position.copy(sync.ctx.toThree(world.x, world.y, world.z));
+    comp.plane.scale.set(compConfig.width, compConfig.height, 1);
+    comp.material.opacity = Math.max(0, Math.min(1, "opacity" in groupData ? groupData.opacity : 1));
+    comp.holder.visible = comp.material.opacity > 0;
+    // Group's 2D affine is gone (task 1.3 found the ops→affine DSL was never
+    // wired up). A comp's own transform composes like any entity's.
+    comp.transformHolder.matrixAutoUpdate = true;
+    comp.transformHolder.position.set(0, 0, 0);
+    comp.transformHolder.rotation.set(0, 0, 0);
+    comp.transformHolder.scale.set(1, 1, 1);
+};
+const disposeComp = Effect.fnUntraced(function* (comp) {
+    yield* dispose(comp.sync);
+    comp.material.dispose();
+    if (comp.rt !== null) {
+        RenderTarget.dispose(comp.rt);
+    }
+});
+/**
+ * Release every retained object, texture, and sub-composition.
+ *
+ * @remarks
+ * Called automatically when a renderer's scope closes; you rarely call it
+ * directly. Effectful because decoded image textures live behind Deferreds
+ * that may still be in flight.
+ */
+export const dispose = Effect.fnUntraced(function* (sync) {
+    for (const entry of sync.retained.values()) {
+        ThreeScene.remove(entry.hud ? sync.hudScene : sync.scene, [
+            entry.retained.object,
+        ]);
+        entry.retained.dispose();
+    }
+    sync.retained.clear();
+    for (const comp of sync.comps.values()) {
+        ThreeScene.remove(comp.hud ? sync.hudScene : sync.scene, [comp.holder]);
+        disposeComp(comp);
+    }
+    sync.comps.clear();
+    Text.dispose(sync.text);
+    yield* Images.dispose(sync.images);
+});
+/**
+ * Load the fonts and images a frame references into the sync actor.
+ *
+ * @remarks
+ * Frames carry resource REFERENCES, never bytes, so the bytes are resolved
+ * here from the caller's context. Only resources not already loaded are
+ * fetched, so this is cheap to call every frame.
+ *
+ * The built-in default font is auto-provided beneath caller context, so
+ * plain text works with no setup — and providing your own loader under the
+ * same `"sans-serif"` id overrides it. Any other font or image with no
+ * loader in context is a defect naming the id and the `Font.layer` /
+ * `Image.layer` call that would fix it.
+ */
+export const resolveResources = Effect.fnUntraced(function* (sync, frame) {
+    const fonts = new Set();
+    const images = new Set();
+    for (const entry of Object.values(frame.instances)) {
+        if (entry.data._tag === "Text") {
+            const family = entry.data._tag === "Text" ? entry.data.fontFamily.id : null;
+            if (family !== null && !Text.hasFont(sync.text, family)) {
+                fonts.add(family);
+            }
+        }
+        if (entry.data._tag === "Image") {
+            const id = entry.data._tag === "Image" ? entry.data.image.id : null;
+            if (id !== null && !Images.has(sync.images, id)) {
+                images.add(id);
+            }
+        }
+    }
+    if (fonts.size === 0 && images.size === 0) {
+        return;
+    }
+    // the caller's live context — loaders resolve from it by rebuilt tag
+    const context = (yield* Effect.context());
+    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);
+        }
+        else if (family === Font.defaultFont.id) {
+            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)}, ...)`));
+        }
+    }
+    for (const id of images) {
+        const provided = Context.getOption(context, ImageResource.Loader(id));
+        if (provided._tag === "None") {
+            return yield* Effect.die(new Error(`Renderer: no image loader provided for "${id}" — provide it via Image.layer(${JSON.stringify(id)}, ...)`));
+        }
+        yield* Images.register(sync.images, id, provided.value.bytes);
+    }
+});

package/dist/Text.d.ts

@@ -0,0 +1,132 @@
+import { ThreeRaw as THREE } from "@effect-motion/three";
+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.
+ *
+ * @remarks
+ * Coordinates are mesh-local and y-UP (three's convention), not scene
+ * coordinates.
+ */
+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];
+}
+/** What to lay out: the string, the font, its size, and its alignment. */
+export interface LayoutRequest {
+    readonly text: string;
+    /** Id of a font registered with {@link registerFont}. */
+    readonly fontId: string;
+    readonly fontSize: number;
+    /**
+     * Horizontal alignment relative to the entity's position.
+     *
+     * @defaultValue `"start"`
+     */
+    readonly textAnchor?: "start" | "middle" | "end" | undefined;
+    /**
+     * Vertical alignment relative to the entity's position.
+     *
+     * @defaultValue `"auto"` — the text's own baseline
+     */
+    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.
+ *
+ * @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 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 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. */
+    readonly setColor: (r: number, g: number, b: number, a: number) => void;
+    /** Release the mesh's geometry and materials. */
+    readonly dispose: () => void;
+}
+/**
+ * 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 declare const makeMesh: (text: Text) => TextMesh;
+export {};