@effect-motion/three 0.5.0

package/dist/Interop.d.ts

@@ -0,0 +1,28 @@
+import { Effect } from "effect";
+import { ThreeException } from "./ThreeException.js";
+/**
+ * The seam between three.js and Effect: turning thrown exceptions and
+ * rejected promises into typed failures.
+ *
+ * @remarks
+ * Used to wrap the calls that can actually fail — construction, GPU work,
+ * async initialization. Per-frame object mutation deliberately does NOT go
+ * through here: it cannot fail, and wrapping it would allocate an Effect per
+ * property write in a hot loop.
+ */
+/**
+ * Run a synchronous three call, converting a throw into a
+ * {@link ThreeException}.
+ *
+ * @param operation - Name of the three operation, used in the error.
+ * @param fn - The call to make.
+ */
+export declare const wrap: <A>(operation: string, fn: () => A) => Effect.Effect<A, ThreeException, never>;
+/**
+ * Run an async three call, converting a rejection into a
+ * {@link ThreeException}.
+ *
+ * @param operation - Name of the three operation, used in the error.
+ * @param fn - The call to make.
+ */
+export declare const wrapPromise: <A>(operation: string, fn: () => Promise<A>) => Effect.Effect<A, ThreeException, never>;

package/dist/Interop.js

@@ -0,0 +1,34 @@
+import { Effect } from "effect";
+import { ThreeException } from "./ThreeException.js";
+/**
+ * The seam between three.js and Effect: turning thrown exceptions and
+ * rejected promises into typed failures.
+ *
+ * @remarks
+ * Used to wrap the calls that can actually fail — construction, GPU work,
+ * async initialization. Per-frame object mutation deliberately does NOT go
+ * through here: it cannot fail, and wrapping it would allocate an Effect per
+ * property write in a hot loop.
+ */
+/**
+ * Run a synchronous three call, converting a throw into a
+ * {@link ThreeException}.
+ *
+ * @param operation - Name of the three operation, used in the error.
+ * @param fn - The call to make.
+ */
+export const wrap = (operation, fn) => Effect.try({
+    try: fn,
+    catch: (cause) => new ThreeException({ operation, cause }),
+});
+/**
+ * Run an async three call, converting a rejection into a
+ * {@link ThreeException}.
+ *
+ * @param operation - Name of the three operation, used in the error.
+ * @param fn - The call to make.
+ */
+export const wrapPromise = (operation, fn) => Effect.tryPromise({
+    try: fn,
+    catch: (cause) => new ThreeException({ operation, cause }),
+});

package/dist/Line2.d.ts

@@ -0,0 +1,42 @@
+import { Line2NodeMaterial } from "three/webgpu";
+/**
+ * Thick lines — strokes with a real pixel width.
+ *
+ * @remarks
+ * A plain three `Line` is always one pixel wide regardless of its material,
+ * because that is all the GPU's line primitive offers. `Line2` draws
+ * strokes as geometry instead, so a width in pixels means something.
+ *
+ * This module is a stable import point over three's addon subpaths, which
+ * move between versions, plus one behavioral fix — see
+ * {@link BlendedLine2NodeMaterial}. Construction and mutation are ordinary
+ * synchronous three.
+ */
+type SetupDiffuseColorArgs = Parameters<Line2NodeMaterial["setupDiffuseColor"]>;
+/**
+ * A `Line2NodeMaterial` whose transparency actually blends.
+ *
+ * @remarks
+ * Use this instead of three's `Line2NodeMaterial` for any stroke that is
+ * not fully opaque.
+ *
+ * Upstream, a transparent fat line does not truly blend. It fakes
+ * transparency by sampling a copy of the framebuffer's opaque content —
+ * three's own comment says "transparency is not supported, yet". That copy
+ * is a module-level singleton, recreated per render and shared by every
+ * renderer on the page, which produces two problems: validation errors
+ * about destroyed textures whenever more than one renderer is alive, and
+ * wrong results against other translucent content, which the copy does not
+ * contain.
+ *
+ * This subclass skips that branch during shader setup and uses ordinary
+ * alpha blending, so a translucent stroke composites like every other
+ * material. Drop it if upstream ever supports real fat-line transparency.
+ */
+export declare class BlendedLine2NodeMaterial extends Line2NodeMaterial {
+    constructor(...parameters: ConstructorParameters<typeof Line2NodeMaterial>);
+    setupDiffuseColor(...args: SetupDiffuseColorArgs): void;
+}
+export { LineGeometry } from "three/addons/lines/LineGeometry.js";
+export { Line2 } from "three/addons/lines/webgpu/Line2.js";
+export { Line2NodeMaterial } from "three/webgpu";

package/dist/Line2.js

@@ -0,0 +1,39 @@
+import { Line2NodeMaterial, NormalBlending } from "three/webgpu";
+/**
+ * A `Line2NodeMaterial` whose transparency actually blends.
+ *
+ * @remarks
+ * Use this instead of three's `Line2NodeMaterial` for any stroke that is
+ * not fully opaque.
+ *
+ * Upstream, a transparent fat line does not truly blend. It fakes
+ * transparency by sampling a copy of the framebuffer's opaque content —
+ * three's own comment says "transparency is not supported, yet". That copy
+ * is a module-level singleton, recreated per render and shared by every
+ * renderer on the page, which produces two problems: validation errors
+ * about destroyed textures whenever more than one renderer is alive, and
+ * wrong results against other translucent content, which the copy does not
+ * contain.
+ *
+ * This subclass skips that branch during shader setup and uses ordinary
+ * alpha blending, so a translucent stroke composites like every other
+ * material. Drop it if upstream ever supports real fat-line transparency.
+ */
+export class BlendedLine2NodeMaterial extends Line2NodeMaterial {
+    constructor(...parameters) {
+        super(...parameters);
+        this.blending = NormalBlending;
+    }
+    setupDiffuseColor(...args) {
+        // momentarily report opaque so the base setup skips its
+        // viewportOpaqueMipTexture fake-transparency branch; the flag is
+        // restored so the render pipeline still alpha-blends
+        const transparent = this.transparent;
+        this.transparent = false;
+        super.setupDiffuseColor(...args);
+        this.transparent = transparent;
+    }
+}
+export { LineGeometry } from "three/addons/lines/LineGeometry.js";
+export { Line2 } from "three/addons/lines/webgpu/Line2.js";
+export { Line2NodeMaterial } from "three/webgpu";

package/dist/Object3D.d.ts

@@ -0,0 +1,13 @@
+import type * as THREE from "three/webgpu";
+/**
+ * Leaf value type: an `Object3D` carries no lifecycle of its own — the
+ * disposables hang off it (geometries, materials), and those get their
+ * own modules — so it stays a plain alias to three's type rather than a
+ * branded handle. See "Wrapping a library that is already actor-shaped"
+ * in AGENTS.md.
+ *
+ * Imported from `three/webgpu` (not `three`) so it is the same nominal
+ * type the rest of the package uses; the two entries declare separate
+ * class identities to TypeScript.
+ */
+export type Object3D = THREE.Object3D;

package/dist/Object3D.js

@@ -0,0 +1 @@
+export {};

package/dist/PostProcessing.d.ts

@@ -0,0 +1,112 @@
+import { type Effect } from "effect";
+import * as Pipeable from "effect/Pipeable";
+import { pass as threePass, uniform } from "three/tsl";
+import * as THREE from "three/webgpu";
+import type * as Renderer from "./Renderer.js";
+import type * as Scene from "./Scene.js";
+import type { ThreeException } from "./ThreeException.js";
+/**
+ * Post-processing: rendering a scene through a shader graph rather than
+ * straight to the output.
+ *
+ * @remarks
+ * Two pieces. A {@link pass} renders a scene and exposes its result as
+ * something a shader can sample; a {@link RenderPipeline} draws a node
+ * graph built from those samples. Together they cover compositing two
+ * scenes, applying a full-screen effect, or — the plainest use, and the
+ * reason the export path has one at all — getting the sRGB output
+ * transform applied, which a direct render-target readback does not do.
+ *
+ * Construction and graph assembly are synchronous and infallible;
+ * {@link render} drives the GPU, so it is the one Effect here.
+ *
+ * TSL node types are deliberately `unknown` throughout this module. three's
+ * published node types expand into unions large enough to send `tsc` into a
+ * multi-minute type check, so they are quarantined and consumers re-declare
+ * the minimal shape they actually use.
+ */
+export declare const TypeId: "~three/RenderPipeline";
+/** A handle to a post-processing pipeline. */
+export interface RenderPipeline extends Pipeable.Pipeable {
+    readonly [TypeId]: typeof TypeId;
+    readonly "~three.renderPipeline": THREE.RenderPipeline;
+}
+/** Whether `u` is a {@link RenderPipeline} handle. */
+export declare const isRenderPipeline: (u: unknown) => u is RenderPipeline;
+/**
+ * A rendered scene, exposed as nodes a shader graph can sample.
+ *
+ * @remarks
+ * Accessors return TSL nodes typed as `unknown` — see the module overview
+ * on why. Consumers re-declare the minimal node shape they use.
+ */
+export interface Pass {
+    readonly "~three.pass": ReturnType<typeof threePass>;
+    /** The pass's rendered color, as a node to sample. */
+    readonly getTextureNode: (name?: string) => unknown;
+    /**
+     * Per-pixel view-space depth, for effects that need to know how far away
+     * something is — fog, or a depth-driven blur.
+     */
+    readonly getViewZNode: (name?: string) => unknown;
+    /**
+     * The camera's near and far planes as auto-updating uniforms.
+     *
+     * @remarks
+     * Needed to linearize depth at an arbitrary sample point.
+     * {@link Pass.getViewZNode} only reports depth at the current pixel, so
+     * any effect gathering depth from NEIGHBOURING taps has to do the
+     * conversion itself. Reaches past three's public surface to get them.
+     */
+    readonly cameraNear: unknown;
+    readonly cameraFar: unknown;
+}
+/**
+ * Render a scene through a camera into something a shader graph can sample.
+ *
+ * @remarks
+ * The pass is the input end of a post chain: build one, take
+ * {@link Pass.getTextureNode} as a node, combine it however you like, and
+ * hand the result to {@link makePipeline}.
+ */
+export declare const pass: (scene: Scene.Scene, camera: THREE.Camera) => Pass;
+/**
+ * Release a pass's GPU resources.
+ *
+ * @remarks
+ * Passes are not scoped, so dispose one explicitly when its owner goes
+ * away.
+ */
+export declare const disposePass: (self: Pass) => void;
+/**
+ * Build a pipeline that draws a shader graph to the renderer's output.
+ *
+ * @remarks
+ * `outputNode` is the assembled TSL graph — a pass's texture straight
+ * through for a plain sRGB transform, or something composited from several
+ * sources. Its type is `unknown` on purpose; see the module overview.
+ *
+ * @param renderer - The renderer to draw with.
+ * @param outputNode - The TSL node graph producing the final color.
+ *
+ * @example
+ * A scene drawn through a pipeline, so the sRGB output transform applies.
+ * ```typescript
+ * const scenePass = PostProcessing.pass(scene, camera);
+ * const pipeline = PostProcessing.makePipeline(
+ * 	renderer,
+ * 	scenePass.getTextureNode(),
+ * );
+ * yield* PostProcessing.render(pipeline);
+ * ```
+ */
+export declare const makePipeline: (renderer: Renderer.Renderer, outputNode: unknown) => RenderPipeline;
+/**
+ * Draw the pipeline to the renderer's current output.
+ *
+ * @remarks
+ * Use this INSTEAD of `Renderer.render` when a pipeline is involved — it
+ * renders the passes the graph depends on and applies the output transform.
+ */
+export declare const render: (self: RenderPipeline) => Effect.Effect<void, ThreeException>;
+export { uniform };

package/dist/PostProcessing.js

@@ -0,0 +1,102 @@
+import { Predicate } from "effect";
+import * as Pipeable from "effect/Pipeable";
+import { pass as threePass, uniform } from "three/tsl";
+import * as THREE from "three/webgpu";
+import { wrap } from "./Interop.js";
+/**
+ * Post-processing: rendering a scene through a shader graph rather than
+ * straight to the output.
+ *
+ * @remarks
+ * Two pieces. A {@link pass} renders a scene and exposes its result as
+ * something a shader can sample; a {@link RenderPipeline} draws a node
+ * graph built from those samples. Together they cover compositing two
+ * scenes, applying a full-screen effect, or — the plainest use, and the
+ * reason the export path has one at all — getting the sRGB output
+ * transform applied, which a direct render-target readback does not do.
+ *
+ * Construction and graph assembly are synchronous and infallible;
+ * {@link render} drives the GPU, so it is the one Effect here.
+ *
+ * TSL node types are deliberately `unknown` throughout this module. three's
+ * published node types expand into unions large enough to send `tsc` into a
+ * multi-minute type check, so they are quarantined and consumers re-declare
+ * the minimal shape they actually use.
+ */
+export const TypeId = "~three/RenderPipeline";
+/** Whether `u` is a {@link RenderPipeline} handle. */
+export const isRenderPipeline = (u) => Predicate.hasProperty(u, TypeId);
+/**
+ * Render a scene through a camera into something a shader graph can sample.
+ *
+ * @remarks
+ * The pass is the input end of a post chain: build one, take
+ * {@link Pass.getTextureNode} as a node, combine it however you like, and
+ * hand the result to {@link makePipeline}.
+ */
+export const pass = (scene, camera) => {
+    const raw = threePass(scene["~three.scene"], camera);
+    const internals = raw;
+    return {
+        "~three.pass": raw,
+        cameraNear: internals._cameraNear,
+        cameraFar: internals._cameraFar,
+        getTextureNode: (name) => name === undefined ? raw.getTextureNode() : raw.getTextureNode(name),
+        getViewZNode: (name) => name === undefined ? raw.getViewZNode() : raw.getViewZNode(name),
+    };
+};
+/**
+ * Release a pass's GPU resources.
+ *
+ * @remarks
+ * Passes are not scoped, so dispose one explicitly when its owner goes
+ * away.
+ */
+export const disposePass = (self) => {
+    self["~three.pass"].dispose?.();
+};
+/**
+ * Build a pipeline that draws a shader graph to the renderer's output.
+ *
+ * @remarks
+ * `outputNode` is the assembled TSL graph — a pass's texture straight
+ * through for a plain sRGB transform, or something composited from several
+ * sources. Its type is `unknown` on purpose; see the module overview.
+ *
+ * @param renderer - The renderer to draw with.
+ * @param outputNode - The TSL node graph producing the final color.
+ *
+ * @example
+ * A scene drawn through a pipeline, so the sRGB output transform applies.
+ * ```typescript
+ * const scenePass = PostProcessing.pass(scene, camera);
+ * const pipeline = PostProcessing.makePipeline(
+ * 	renderer,
+ * 	scenePass.getTextureNode(),
+ * );
+ * yield* PostProcessing.render(pipeline);
+ * ```
+ */
+export const makePipeline = (renderer, outputNode) => {
+    const pipeline = new THREE.RenderPipeline(renderer["~three.renderer"]);
+    // the node graph's type is quarantined; the pipeline accepts it
+    pipeline.outputNode = outputNode;
+    const self = {
+        [TypeId]: TypeId,
+        "~three.renderPipeline": pipeline,
+        // see Scene.ts on the array-like cast
+        pipe(...fns) {
+            return Pipeable.pipeArguments(self, fns);
+        },
+    };
+    return self;
+};
+/**
+ * Draw the pipeline to the renderer's current output.
+ *
+ * @remarks
+ * Use this INSTEAD of `Renderer.render` when a pipeline is involved — it
+ * renders the passes the graph depends on and applies the output transform.
+ */
+export const render = (self) => wrap("RenderPipeline.render", () => self["~three.renderPipeline"].render());
+export { uniform };

package/dist/RenderTarget.d.ts

@@ -0,0 +1,86 @@
+import type { Scope } from "effect";
+import { Effect } from "effect";
+import * as Pipeable from "effect/Pipeable";
+import * as THREE from "three/webgpu";
+/**
+ * An offscreen render destination — draw into it instead of the canvas.
+ *
+ * @remarks
+ * Rendering to a target is how a rendered result becomes something you can
+ * use: read its pixels back for export, or sample its texture in another
+ * pass.
+ *
+ * Construction cannot fail — the GPU allocation is deferred until first
+ * use — so {@link make} is an Effect purely to register teardown. That is
+ * also the only reason this is a branded handle rather than a plain alias:
+ * a render target owns GPU memory that has to be released.
+ */
+export declare const TypeId: "~three/RenderTarget";
+/**
+ * A handle to an offscreen render destination.
+ *
+ * @remarks
+ * The underlying target stays reachable through `~three.renderTarget` for
+ * anything this wrapper does not cover.
+ */
+export interface RenderTarget extends Pipeable.Pipeable {
+    readonly [TypeId]: typeof TypeId;
+    readonly "~three.renderTarget": THREE.RenderTarget;
+}
+/** Whether `u` is a {@link RenderTarget} handle. */
+export declare const isRenderTarget: (u: unknown) => u is RenderTarget;
+/**
+ * A render target of `width × height` device pixels, freed when the scope
+ * closes.
+ *
+ * @remarks
+ * Dimensions are DEVICE pixels, so multiply by the pixel ratio yourself
+ * when supersampling.
+ */
+export declare const make: (width: number, height: number) => Effect.Effect<RenderTarget, never, Scope.Scope>;
+/**
+ * A render target WITHOUT scope-registered teardown.
+ *
+ * @remarks
+ * For targets whose lifetime does not match a scope — one recreated on
+ * every resize, for instance, where a longer-lived owner tracks it and
+ * calls {@link dispose}. Prefer {@link make} whenever a scope will do.
+ */
+export declare const makeUnsafe: (width: number, height: number) => RenderTarget;
+/**
+ * Wrap an existing three render target, without registering teardown.
+ *
+ * @remarks
+ * Same caveat as {@link makeUnsafe}: whoever owns it must dispose it.
+ */
+export declare const fromRaw: (target: THREE.RenderTarget) => RenderTarget;
+/**
+ * Release the target's GPU memory.
+ *
+ * @remarks
+ * Only for targets from {@link makeUnsafe} or {@link fromRaw} — one from
+ * {@link make} disposes itself with its scope, and disposing it here would
+ * be a double free.
+ */
+export declare const dispose: (self: RenderTarget) => void;
+/**
+ * The target's color texture — what you sample to use the rendered result
+ * in another pass.
+ */
+export declare const texture: (self: RenderTarget) => THREE.Texture;
+/** The target's width in device pixels. */
+export declare const width: (self: RenderTarget) => number;
+/** The target's height in device pixels. */
+export declare const height: (self: RenderTarget) => number;
+/**
+ * Resize the target in place.
+ *
+ * @remarks
+ * three reallocates the underlying GPU textures, so the handle stays valid
+ * and nothing needs re-registering with the scope. Contents are not
+ * preserved — redraw after resizing.
+ */
+export declare const setSize: {
+    (nextWidth: number, nextHeight: number): (self: RenderTarget) => RenderTarget;
+    (self: RenderTarget, nextWidth: number, nextHeight: number): RenderTarget;
+};

package/dist/RenderTarget.js

@@ -0,0 +1,97 @@
+import { Effect, Predicate } from "effect";
+import { dual } from "effect/Function";
+import * as Pipeable from "effect/Pipeable";
+import * as THREE from "three/webgpu";
+/**
+ * An offscreen render destination — draw into it instead of the canvas.
+ *
+ * @remarks
+ * Rendering to a target is how a rendered result becomes something you can
+ * use: read its pixels back for export, or sample its texture in another
+ * pass.
+ *
+ * Construction cannot fail — the GPU allocation is deferred until first
+ * use — so {@link make} is an Effect purely to register teardown. That is
+ * also the only reason this is a branded handle rather than a plain alias:
+ * a render target owns GPU memory that has to be released.
+ */
+export const TypeId = "~three/RenderTarget";
+/** Whether `u` is a {@link RenderTarget} handle. */
+export const isRenderTarget = (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 firstArgIsRenderTarget = (args) => isRenderTarget(args[0]);
+const brand = (target) => {
+    const self = {
+        [TypeId]: TypeId,
+        "~three.renderTarget": target,
+        // see Scene.ts on the array-like cast
+        pipe(...fns) {
+            return Pipeable.pipeArguments(self, fns);
+        },
+    };
+    return self;
+};
+/**
+ * A render target of `width × height` device pixels, freed when the scope
+ * closes.
+ *
+ * @remarks
+ * Dimensions are DEVICE pixels, so multiply by the pixel ratio yourself
+ * when supersampling.
+ */
+export const make = Effect.fnUntraced(function* (width, height) {
+    const target = new THREE.RenderTarget(width, height);
+    yield* Effect.addFinalizer(() => Effect.sync(() => target.dispose()));
+    return brand(target);
+});
+/**
+ * A render target WITHOUT scope-registered teardown.
+ *
+ * @remarks
+ * For targets whose lifetime does not match a scope — one recreated on
+ * every resize, for instance, where a longer-lived owner tracks it and
+ * calls {@link dispose}. Prefer {@link make} whenever a scope will do.
+ */
+export const makeUnsafe = (width, height) => brand(new THREE.RenderTarget(width, height));
+/**
+ * Wrap an existing three render target, without registering teardown.
+ *
+ * @remarks
+ * Same caveat as {@link makeUnsafe}: whoever owns it must dispose it.
+ */
+export const fromRaw = (target) => brand(target);
+/**
+ * Release the target's GPU memory.
+ *
+ * @remarks
+ * Only for targets from {@link makeUnsafe} or {@link fromRaw} — one from
+ * {@link make} disposes itself with its scope, and disposing it here would
+ * be a double free.
+ */
+export const dispose = (self) => {
+    self["~three.renderTarget"].dispose();
+};
+/**
+ * The target's color texture — what you sample to use the rendered result
+ * in another pass.
+ */
+export const texture = (self) => self["~three.renderTarget"].texture;
+/** The target's width in device pixels. */
+export const width = (self) => self["~three.renderTarget"].width;
+/** The target's height in device pixels. */
+export const height = (self) => self["~three.renderTarget"].height;
+/**
+ * Resize the target in place.
+ *
+ * @remarks
+ * three reallocates the underlying GPU textures, so the handle stays valid
+ * and nothing needs re-registering with the scope. Contents are not
+ * preserved — redraw after resizing.
+ */
+export const setSize = dual(firstArgIsRenderTarget, (self, nextWidth, nextHeight) => {
+    self["~three.renderTarget"].setSize(nextWidth, nextHeight);
+    return self;
+});