@effect-motion/three 0.5.0

package/dist/Renderer.d.ts

@@ -0,0 +1,204 @@
+import type { Scope } from "effect";
+import { Effect } from "effect";
+import * as Pipeable from "effect/Pipeable";
+import * as THREE from "three/webgpu";
+import type * as RenderTarget from "./RenderTarget.js";
+import type * as Scene from "./Scene.js";
+import type { ThreeException } from "./ThreeException.js";
+/**
+ * The GPU renderer — a scoped handle over three's `WebGPURenderer`.
+ *
+ * @remarks
+ * {@link make} hands back a renderer whose async initialization has already
+ * completed, so nothing downstream has to await a device that might not be
+ * ready. On scope close it drains the GPU queue before disposing, which is
+ * what prevents the "destroyed texture used in a submit" errors that
+ * disposing mid-flight would otherwise produce.
+ *
+ * Work that touches the GPU — {@link render}, {@link readRenderTarget},
+ * {@link compile} — is an Effect, typed as `ThreeException`. Sizing and
+ * output-target bookkeeping cannot fail, so those stay synchronous and
+ * chain through `.pipe`.
+ */
+export declare const TypeId: "~three/Renderer";
+/**
+ * A handle to an initialized GPU renderer.
+ *
+ * @remarks
+ * The three renderer stays reachable through `~three.renderer` for anything
+ * this wrapper does not cover — a deliberate escape hatch, not the front
+ * door.
+ */
+export interface Renderer extends Pipeable.Pipeable {
+    readonly [TypeId]: typeof TypeId;
+    readonly "~three.renderer": THREE.WebGPURenderer;
+}
+/** Whether `u` is a {@link Renderer} handle. */
+export declare const isRenderer: (u: unknown) => u is Renderer;
+type WebGPURendererParameters = NonNullable<ConstructorParameters<typeof THREE.WebGPURenderer>[0]>;
+/**
+ * Everything three's `WebGPURenderer` accepts, plus initial sizing applied
+ * before initialization.
+ *
+ * @remarks
+ * Sizing here rather than after `make` avoids an initial render at the
+ * wrong size. Canvas CSS is never touched — callers own the element's
+ * styling.
+ */
+export interface MakeOptions extends WebGPURendererParameters {
+    readonly width?: number;
+    readonly height?: number;
+    readonly pixelRatio?: number;
+}
+/**
+ * Acquire a renderer, initialization already awaited.
+ *
+ * @remarks
+ * Scoped: on close the renderer waits for in-flight GPU work to land,
+ * drains the queue, and disposes. A failure during that teardown is logged
+ * rather than raised, so it never masks the scope's real outcome.
+ *
+ * Without a `canvas`, three creates one. For headless use, pass the canvas
+ * and device from `@effect-motion/three/node`.
+ *
+ * @param options - Renderer parameters plus optional initial sizing.
+ * @returns A renderer, valid for the current scope.
+ *
+ * @example
+ * ```typescript
+ * const renderer = yield* Renderer.make({ width: 640, height: 360 });
+ * ```
+ */
+export declare const make: (options?: MakeOptions) => Effect.Effect<Renderer, ThreeException, Scope.Scope>;
+/**
+ * Draw a scene through a camera.
+ *
+ * @remarks
+ * Output goes wherever {@link setRenderTarget} last pointed — the canvas by
+ * default, or an offscreen target. Safe to call immediately after
+ * {@link make}, since initialization is already complete by then.
+ */
+export declare const render: (self: Renderer, scene: Scene.Scene, camera: THREE.Camera) => Effect.Effect<void, ThreeException>;
+/**
+ * Read rendered pixels back off the GPU as RGBA bytes.
+ *
+ * @remarks
+ * The result is exactly `width * height * 4` bytes, top-down and tightly
+ * packed — ready to hand to an image encoder. WebGPU itself pads each row
+ * to a 256-byte boundary; that padding is stripped here so callers never
+ * deal with stride.
+ *
+ * Colors come back LINEAR. Render through a
+ * {@link PostProcessing.RenderPipeline} first if you want the sRGB output
+ * transform applied — reading a raw render target and encoding it directly
+ * produces a visibly dark image.
+ *
+ * @param target - The target to read.
+ * @param width - Region width in device pixels.
+ * @param height - Region height in device pixels.
+ * @returns `width * height * 4` bytes of RGBA.
+ */
+export declare const readRenderTarget: (self: Renderer, target: RenderTarget.RenderTarget, width: number, height: number) => Effect.Effect<Uint8Array, ThreeException>;
+/**
+ * Compile the shader pipelines a scene needs, ahead of drawing it.
+ *
+ * @remarks
+ * WebGPU compiles a pipeline the first time it is used, which lands as a
+ * visible hitch (roughly 40–80ms) on the first frame. Calling this after
+ * the scene is populated but before anything is shown moves that cost into
+ * startup.
+ */
+export declare const compile: (self: Renderer, scene: Scene.Scene, camera: THREE.Camera) => Effect.Effect<void, ThreeException>;
+/**
+ * Point the renderer's output at an offscreen target, or `null` to draw to
+ * the canvas.
+ *
+ * @remarks
+ * Rendering to a target is how a result becomes something to sample —
+ * reading pixels back, or feeding a texture into another pass. Save and
+ * restore the previous target around nested renders; {@link getRenderTarget}
+ * is there for exactly that.
+ */
+export declare const setRenderTarget: {
+    (target: RenderTarget.RenderTarget | null): (self: Renderer) => Renderer;
+    (self: Renderer, target: RenderTarget.RenderTarget | null): Renderer;
+};
+/**
+ * The current output target, or `null` when drawing to the canvas.
+ *
+ * @remarks
+ * Read it before redirecting output so you can restore it afterwards.
+ */
+export declare const getRenderTarget: (self: Renderer) => RenderTarget.RenderTarget | null;
+/**
+ * Whether the renderer clears the canvas before each render.
+ *
+ * @remarks
+ * Turning it off is how a second pass draws ON TOP of what is already
+ * there — an overlay or HUD tier. Turn it back on afterwards, or the next
+ * frame will accumulate over this one.
+ */
+export declare const setAutoClear: {
+    (autoClear: boolean): (self: Renderer) => Renderer;
+    (self: Renderer, autoClear: boolean): Renderer;
+};
+/**
+ * Clear the depth buffer.
+ *
+ * @remarks
+ * Paired with `setAutoClear(false)` for an overlay pass: without it, the
+ * overlay's geometry would be depth-tested against the world it is meant to
+ * sit above and could be hidden by it.
+ */
+export declare const clearDepth: (self: Renderer) => Renderer;
+/**
+ * Advance three's internal frame counter by one.
+ *
+ * @remarks
+ * Only needed when driving renders yourself rather than through three's
+ * animation loop — a headless export, above all.
+ *
+ * Nodes that dedupe their work per frame (the scene pass especially) decide
+ * whether to recompute by comparing against this counter. three only ticks
+ * it inside its own rAF loop, which an export outruns, so consecutive
+ * exported frames would sample a stale texture and come out
+ * pairwise-duplicated. Calling this once per exported frame makes one
+ * exported frame mean one three frame.
+ */
+export declare const advanceFrame: (self: Renderer) => Renderer;
+/**
+ * Set the renderer's logical size in CSS pixels.
+ *
+ * @remarks
+ * The actual drawing buffer is this multiplied by the pixel ratio. Canvas
+ * CSS is left alone unless `updateStyle` is true, since callers usually own
+ * the element's layout.
+ *
+ * @defaultValue `updateStyle` — `false`
+ */
+export declare const setSize: {
+    (width: number, height: number, updateStyle?: boolean): (self: Renderer) => Renderer;
+    (self: Renderer, width: number, height: number, updateStyle?: boolean): Renderer;
+};
+/**
+ * Set device pixels per logical pixel.
+ *
+ * @remarks
+ * Pass `window.devicePixelRatio` for a sharp result on a high-DPI display,
+ * or a fixed value above 1 to supersample an export for cleaner edges.
+ */
+export declare const setPixelRatio: {
+    (pixelRatio: number): (self: Renderer) => Renderer;
+    (self: Renderer, pixelRatio: number): Renderer;
+};
+/** The current device-pixels-per-logical-pixel ratio. */
+export declare const getPixelRatio: (self: Renderer) => number;
+/**
+ * The drawing buffer's size in device pixels — the logical size multiplied
+ * by the pixel ratio, and therefore the dimensions to read pixels back at.
+ */
+export declare const getDrawingBufferSize: (self: Renderer) => {
+    readonly width: number;
+    readonly height: number;
+};
+export {};

package/dist/Renderer.js

@@ -0,0 +1,241 @@
+import { Effect, Predicate } from "effect";
+import { dual } from "effect/Function";
+import * as Pipeable from "effect/Pipeable";
+import * as THREE from "three/webgpu";
+import { wrap, wrapPromise } from "./Interop.js";
+import * as RenderTargetModule from "./RenderTarget.js";
+/**
+ * The GPU renderer — a scoped handle over three's `WebGPURenderer`.
+ *
+ * @remarks
+ * {@link make} hands back a renderer whose async initialization has already
+ * completed, so nothing downstream has to await a device that might not be
+ * ready. On scope close it drains the GPU queue before disposing, which is
+ * what prevents the "destroyed texture used in a submit" errors that
+ * disposing mid-flight would otherwise produce.
+ *
+ * Work that touches the GPU — {@link render}, {@link readRenderTarget},
+ * {@link compile} — is an Effect, typed as `ThreeException`. Sizing and
+ * output-target bookkeeping cannot fail, so those stay synchronous and
+ * chain through `.pipe`.
+ */
+export const TypeId = "~three/Renderer";
+/** Whether `u` is a {@link Renderer} handle. */
+export const isRenderer = (u) => Predicate.hasProperty(u, TypeId);
+/**
+ * `dual`'s predicate receives the whole `arguments` object, not the first
+ * argument — dispatch on `args[0]`. Guard-based, never arity (AGENTS.md).
+ */
+const firstArgIsRenderer = (args) => isRenderer(args[0]);
+const brand = (renderer) => {
+    const self = {
+        [TypeId]: TypeId,
+        "~three.renderer": renderer,
+        // see Scene.ts on the array-like cast
+        pipe(...fns) {
+            return Pipeable.pipeArguments(self, fns);
+        },
+    };
+    return self;
+};
+const acquire = Effect.fnUntraced(function* (options) {
+    const { width, height, pixelRatio, ...parameters } = options;
+    const renderer = yield* wrap("WebGPURenderer", () => new THREE.WebGPURenderer(parameters));
+    if (pixelRatio !== undefined) {
+        renderer.setPixelRatio(pixelRatio);
+    }
+    if (width !== undefined && height !== undefined) {
+        renderer.setSize(width, height, false);
+    }
+    yield* wrapPromise("WebGPURenderer.init", () => renderer.init());
+    return brand(renderer);
+});
+// disposing destroys GPU textures immediately, but the backend's in-flight
+// async chains (deferred submits, per-render resolves) can still submit
+// afterwards — "Destroyed texture used in a submit" validation spam. Let
+// pending work land while resources are alive, drain the queue, then
+// dispose. A release failure is logged, never thrown — teardown must not
+// mask the scope's real outcome.
+const release = (self) => {
+    const renderer = self["~three.renderer"];
+    return Effect.sleep("50 millis").pipe(Effect.andThen(wrapPromise("WebGPURenderer queue drain", async () => {
+        const device = renderer.backend.device;
+        if (device !== undefined) {
+            await device.queue.onSubmittedWorkDone();
+        }
+    })), Effect.andThen(wrap("WebGPURenderer.dispose", () => renderer.dispose())), Effect.catchCause((cause) => Effect.logWarning("WebGPURenderer dispose failed", cause)));
+};
+/**
+ * Acquire a renderer, initialization already awaited.
+ *
+ * @remarks
+ * Scoped: on close the renderer waits for in-flight GPU work to land,
+ * drains the queue, and disposes. A failure during that teardown is logged
+ * rather than raised, so it never masks the scope's real outcome.
+ *
+ * Without a `canvas`, three creates one. For headless use, pass the canvas
+ * and device from `@effect-motion/three/node`.
+ *
+ * @param options - Renderer parameters plus optional initial sizing.
+ * @returns A renderer, valid for the current scope.
+ *
+ * @example
+ * ```typescript
+ * const renderer = yield* Renderer.make({ width: 640, height: 360 });
+ * ```
+ */
+export const make = (options = {}) => Effect.acquireRelease(acquire(options), release);
+/**
+ * Draw a scene through a camera.
+ *
+ * @remarks
+ * Output goes wherever {@link setRenderTarget} last pointed — the canvas by
+ * default, or an offscreen target. Safe to call immediately after
+ * {@link make}, since initialization is already complete by then.
+ */
+export const render = (self, scene, camera) => wrap("WebGPURenderer.render", () => self["~three.renderer"].render(scene["~three.scene"], camera));
+/**
+ * Read rendered pixels back off the GPU as RGBA bytes.
+ *
+ * @remarks
+ * The result is exactly `width * height * 4` bytes, top-down and tightly
+ * packed — ready to hand to an image encoder. WebGPU itself pads each row
+ * to a 256-byte boundary; that padding is stripped here so callers never
+ * deal with stride.
+ *
+ * Colors come back LINEAR. Render through a
+ * {@link PostProcessing.RenderPipeline} first if you want the sRGB output
+ * transform applied — reading a raw render target and encoding it directly
+ * produces a visibly dark image.
+ *
+ * @param target - The target to read.
+ * @param width - Region width in device pixels.
+ * @param height - Region height in device pixels.
+ * @returns `width * height * 4` bytes of RGBA.
+ */
+export const readRenderTarget = (self, target, width, height) => wrapPromise("readRenderTargetPixelsAsync", () => self["~three.renderer"].readRenderTargetPixelsAsync(target["~three.renderTarget"], 0, 0, width, height)).pipe(Effect.map((pixels) => {
+    const padded = new Uint8Array(pixels.buffer, pixels.byteOffset, pixels.byteLength);
+    const tightRow = width * 4;
+    const paddedRow = Math.ceil(tightRow / 256) * 256;
+    if (padded.length === tightRow * height) {
+        return padded;
+    }
+    const rgba = new Uint8Array(tightRow * height);
+    for (let y = 0; y < height; y++) {
+        rgba.set(padded.subarray(y * paddedRow, y * paddedRow + tightRow), y * tightRow);
+    }
+    return rgba;
+}));
+/**
+ * Compile the shader pipelines a scene needs, ahead of drawing it.
+ *
+ * @remarks
+ * WebGPU compiles a pipeline the first time it is used, which lands as a
+ * visible hitch (roughly 40–80ms) on the first frame. Calling this after
+ * the scene is populated but before anything is shown moves that cost into
+ * startup.
+ */
+export const compile = (self, scene, camera) => wrapPromise("WebGPURenderer.compileAsync", () => self["~three.renderer"]
+    .compileAsync(scene["~three.scene"], camera)
+    .then(() => undefined));
+/**
+ * Point the renderer's output at an offscreen target, or `null` to draw to
+ * the canvas.
+ *
+ * @remarks
+ * Rendering to a target is how a result becomes something to sample —
+ * reading pixels back, or feeding a texture into another pass. Save and
+ * restore the previous target around nested renders; {@link getRenderTarget}
+ * is there for exactly that.
+ */
+export const setRenderTarget = dual(firstArgIsRenderer, (self, target) => {
+    self["~three.renderer"].setRenderTarget(target === null ? null : target["~three.renderTarget"]);
+    return self;
+});
+/**
+ * The current output target, or `null` when drawing to the canvas.
+ *
+ * @remarks
+ * Read it before redirecting output so you can restore it afterwards.
+ */
+export const getRenderTarget = (self) => {
+    const target = self["~three.renderer"].getRenderTarget();
+    return target === null ? null : RenderTargetModule.fromRaw(target);
+};
+/**
+ * Whether the renderer clears the canvas before each render.
+ *
+ * @remarks
+ * Turning it off is how a second pass draws ON TOP of what is already
+ * there — an overlay or HUD tier. Turn it back on afterwards, or the next
+ * frame will accumulate over this one.
+ */
+export const setAutoClear = dual(firstArgIsRenderer, (self, autoClear) => {
+    self["~three.renderer"].autoClear = autoClear;
+    return self;
+});
+/**
+ * Clear the depth buffer.
+ *
+ * @remarks
+ * Paired with `setAutoClear(false)` for an overlay pass: without it, the
+ * overlay's geometry would be depth-tested against the world it is meant to
+ * sit above and could be hidden by it.
+ */
+export const clearDepth = (self) => {
+    self["~three.renderer"].clearDepth();
+    return self;
+};
+/**
+ * Advance three's internal frame counter by one.
+ *
+ * @remarks
+ * Only needed when driving renders yourself rather than through three's
+ * animation loop — a headless export, above all.
+ *
+ * Nodes that dedupe their work per frame (the scene pass especially) decide
+ * whether to recompute by comparing against this counter. three only ticks
+ * it inside its own rAF loop, which an export outruns, so consecutive
+ * exported frames would sample a stale texture and come out
+ * pairwise-duplicated. Calling this once per exported frame makes one
+ * exported frame mean one three frame.
+ */
+export const advanceFrame = (self) => {
+    self["~three.renderer"]._nodes.nodeFrame.update();
+    return self;
+};
+/**
+ * Set the renderer's logical size in CSS pixels.
+ *
+ * @remarks
+ * The actual drawing buffer is this multiplied by the pixel ratio. Canvas
+ * CSS is left alone unless `updateStyle` is true, since callers usually own
+ * the element's layout.
+ *
+ * @defaultValue `updateStyle` — `false`
+ */
+export const setSize = dual(firstArgIsRenderer, (self, width, height, updateStyle = false) => {
+    self["~three.renderer"].setSize(width, height, updateStyle);
+    return self;
+});
+/**
+ * Set device pixels per logical pixel.
+ *
+ * @remarks
+ * Pass `window.devicePixelRatio` for a sharp result on a high-DPI display,
+ * or a fixed value above 1 to supersample an export for cleaner edges.
+ */
+export const setPixelRatio = dual(firstArgIsRenderer, (self, pixelRatio) => {
+    self["~three.renderer"].setPixelRatio(pixelRatio);
+    return self;
+});
+/** The current device-pixels-per-logical-pixel ratio. */
+export const getPixelRatio = (self) => self["~three.renderer"].getPixelRatio();
+/**
+ * The drawing buffer's size in device pixels — the logical size multiplied
+ * by the pixel ratio, and therefore the dimensions to read pixels back at.
+ */
+export const getDrawingBufferSize = (self) => {
+    const size = self["~three.renderer"].getDrawingBufferSize(new THREE.Vector2());
+    return { width: size.x, height: size.y };
+};

package/dist/Scene.d.ts

@@ -0,0 +1,105 @@
+import type { Scope } from "effect";
+import { Effect } from "effect";
+import * as Pipeable from "effect/Pipeable";
+import * as THREE from "three/webgpu";
+import type * as Object3D from "./Object3D.js";
+/**
+ * The scene graph root — a scoped handle over three's `Scene`.
+ *
+ * @remarks
+ * three is already shaped the way this wrapper wants, so this is a
+ * branding-and-lifecycle layer rather than a redesign. Everything here —
+ * {@link add}, {@link remove}, {@link clear}, {@link setBackground} — is
+ * infallible bookkeeping on an object already in hand, so it stays
+ * synchronous and chains through `.pipe`. Effect enters only at
+ * {@link make}, which registers teardown.
+ *
+ * @example
+ * ```typescript
+ * const scene = yield* Scene.make();
+ * scene.pipe(Scene.add([mesh]), Scene.setBackground(new Color(0x16161d)));
+ * ```
+ */
+export declare const TypeId: "~three/Scene";
+/**
+ * A handle to a three scene.
+ *
+ * @remarks
+ * The underlying scene stays reachable through `~three.scene` for anything
+ * this wrapper does not cover.
+ */
+export interface Scene extends Pipeable.Pipeable {
+    readonly [TypeId]: typeof TypeId;
+    readonly "~three.scene": THREE.Scene;
+}
+/** Whether `u` is a {@link Scene} handle. */
+export declare const isScene: (u: unknown) => u is Scene;
+/**
+ * Wrap an existing three scene WITHOUT registering teardown.
+ *
+ * @remarks
+ * For a scene whose lifetime something else already owns and will clean up.
+ * Prefer {@link make}, which ties teardown to a scope; reach for this only
+ * when a longer-lived owner is genuinely in charge.
+ */
+export declare const makeUnsafe: (scene: THREE.Scene) => Scene;
+/**
+ * A scoped scene that detaches its children when the scope closes.
+ *
+ * @remarks
+ * Detaching is NOT disposal. A scene does not own the geometries,
+ * materials, and textures hanging off its objects — those are routinely
+ * shared between objects and outlive any one graph — so whoever created
+ * them is responsible for freeing them.
+ */
+export declare const make: () => Effect.Effect<Scene, never, Scope.Scope>;
+/**
+ * Detach every child from the scene root.
+ *
+ * @remarks
+ * Unparents only — see {@link make} on why this does not dispose anything.
+ */
+export declare const clear: (self: Scene) => Scene;
+/** The scene root's direct children (not a deep traversal). */
+export declare const children: (self: Scene) => ReadonlyArray<Object3D.Object3D>;
+/**
+ * Whether the scene root has no children.
+ *
+ * @remarks
+ * The "is there anything to draw" check — worth making before an optional
+ * pass, so an empty overlay tier costs nothing.
+ */
+export declare const isEmpty: (self: Scene) => boolean;
+/**
+ * Attach objects to the scene root.
+ *
+ * @remarks
+ * Re-adding an object that is already parented moves it, as in three
+ * itself — an object has exactly one parent.
+ */
+export declare const add: {
+    (objects: ReadonlyArray<Object3D.Object3D>): (self: Scene) => Scene;
+    (self: Scene, objects: ReadonlyArray<Object3D.Object3D>): Scene;
+};
+/**
+ * Detach objects from the scene root.
+ *
+ * @remarks
+ * A no-op for objects that are not attached, and it does not dispose them —
+ * a removed object can be added back.
+ */
+export declare const remove: {
+    (objects: ReadonlyArray<Object3D.Object3D>): (self: Scene) => Scene;
+    (self: Scene, objects: ReadonlyArray<Object3D.Object3D>): Scene;
+};
+/**
+ * Set the background color or texture, or `null` for transparency.
+ *
+ * @remarks
+ * `null` is what an overlay tier wants: with nothing painted behind it,
+ * whatever was rendered first shows through.
+ */
+export declare const setBackground: {
+    (background: THREE.Color | THREE.Texture | null): (self: Scene) => Scene;
+    (self: Scene, background: THREE.Color | THREE.Texture | null): Scene;
+};

package/dist/Scene.js

@@ -0,0 +1,118 @@
+import { Effect, Predicate } from "effect";
+import { dual } from "effect/Function";
+import * as Pipeable from "effect/Pipeable";
+import * as THREE from "three/webgpu";
+/**
+ * The scene graph root — a scoped handle over three's `Scene`.
+ *
+ * @remarks
+ * three is already shaped the way this wrapper wants, so this is a
+ * branding-and-lifecycle layer rather than a redesign. Everything here —
+ * {@link add}, {@link remove}, {@link clear}, {@link setBackground} — is
+ * infallible bookkeeping on an object already in hand, so it stays
+ * synchronous and chains through `.pipe`. Effect enters only at
+ * {@link make}, which registers teardown.
+ *
+ * @example
+ * ```typescript
+ * const scene = yield* Scene.make();
+ * scene.pipe(Scene.add([mesh]), Scene.setBackground(new Color(0x16161d)));
+ * ```
+ */
+export const TypeId = "~three/Scene";
+/** Whether `u` is a {@link Scene} handle. */
+export const isScene = (u) => Predicate.hasProperty(u, TypeId);
+/**
+ * `dual`'s predicate receives the whole `arguments` object, not the first
+ * argument — dispatch on `args[0]`, as the motion package's animators do.
+ * Guard-based, never arity (AGENTS.md).
+ */
+const firstArgIsScene = (args) => isScene(args[0]);
+/**
+ * Wrap an existing three scene WITHOUT registering teardown.
+ *
+ * @remarks
+ * For a scene whose lifetime something else already owns and will clean up.
+ * Prefer {@link make}, which ties teardown to a scope; reach for this only
+ * when a longer-lived owner is genuinely in charge.
+ */
+export const makeUnsafe = (scene) => {
+    const self = {
+        [TypeId]: TypeId,
+        "~three.scene": scene,
+        // pipeArguments reads its second parameter as an array-like; a rest
+        // array satisfies that at runtime, and the cast avoids both the
+        // `arguments` object and a lint suppression
+        pipe(...fns) {
+            return Pipeable.pipeArguments(self, fns);
+        },
+    };
+    return self;
+};
+/**
+ * A scoped scene that detaches its children when the scope closes.
+ *
+ * @remarks
+ * Detaching is NOT disposal. A scene does not own the geometries,
+ * materials, and textures hanging off its objects — those are routinely
+ * shared between objects and outlive any one graph — so whoever created
+ * them is responsible for freeing them.
+ */
+export const make = Effect.fnUntraced(function* () {
+    const scene = new THREE.Scene();
+    yield* Effect.addFinalizer(() => Effect.sync(() => scene.clear()));
+    return makeUnsafe(scene);
+});
+/**
+ * Detach every child from the scene root.
+ *
+ * @remarks
+ * Unparents only — see {@link make} on why this does not dispose anything.
+ */
+export const clear = (self) => {
+    self["~three.scene"].clear();
+    return self;
+};
+/** The scene root's direct children (not a deep traversal). */
+export const children = (self) => self["~three.scene"].children;
+/**
+ * Whether the scene root has no children.
+ *
+ * @remarks
+ * The "is there anything to draw" check — worth making before an optional
+ * pass, so an empty overlay tier costs nothing.
+ */
+export const isEmpty = (self) => self["~three.scene"].children.length === 0;
+/**
+ * Attach objects to the scene root.
+ *
+ * @remarks
+ * Re-adding an object that is already parented moves it, as in three
+ * itself — an object has exactly one parent.
+ */
+export const add = dual(firstArgIsScene, (self, objects) => {
+    self["~three.scene"].add(...objects);
+    return self;
+});
+/**
+ * Detach objects from the scene root.
+ *
+ * @remarks
+ * A no-op for objects that are not attached, and it does not dispose them —
+ * a removed object can be added back.
+ */
+export const remove = dual(firstArgIsScene, (self, objects) => {
+    self["~three.scene"].remove(...objects);
+    return self;
+});
+/**
+ * Set the background color or texture, or `null` for transparency.
+ *
+ * @remarks
+ * `null` is what an overlay tier wants: with nothing painted behind it,
+ * whatever was rendered first shows through.
+ */
+export const setBackground = dual(firstArgIsScene, (self, background) => {
+    self["~three.scene"].background = background;
+    return self;
+});

package/dist/ThreeException.d.ts

@@ -0,0 +1,24 @@
+declare const ThreeException_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ThreeException";
+} & Readonly<A>;
+/**
+ * A three.js operation failed.
+ *
+ * @remarks
+ * Every fallible call in this package reports through this one error type,
+ * so a caller catches by tag rather than guarding each three API
+ * separately. `operation` names which call failed — `"WebGPURenderer.init"`,
+ * `"readRenderTargetPixelsAsync"` — and `cause` carries whatever three
+ * threw or rejected with.
+ *
+ * Typical causes are environmental rather than logical: no WebGPU adapter,
+ * a lost device, a shader that failed to compile.
+ */
+export declare class ThreeException extends ThreeException_base<{
+    /** The underlying error three threw or rejected with. */
+    cause?: unknown;
+    /** Name of the three.js operation that failed. */
+    operation?: string;
+}> {
+}
+export {};