@effect-motion/three 0.5.0

package/dist/ThreeException.js

@@ -0,0 +1,16 @@
+import { Data } from "effect";
+/**
+ * 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 class ThreeException extends Data.TaggedError("ThreeException") {
+}

package/dist/Tsl.d.ts

@@ -0,0 +1,18 @@
+/**
+ * TSL — three's shading language, for building node materials and shader
+ * graphs.
+ *
+ * @remarks
+ * Re-exported so downstream code has a single import root for the subset
+ * this project uses, rather than reaching into `three/tsl` from a dozen
+ * places.
+ *
+ * These are pure description: building a node graph runs no GPU work and
+ * cannot fail, so nothing here is an Effect. Effect enters when a graph is
+ * eventually rendered.
+ *
+ * Note that node types are deliberately not re-exported — three's published
+ * node types expand into unions large enough to stall a type check, so
+ * consumers declare the minimal shape they use. See `PostProcessing`.
+ */
+export { attribute, float, fwidth, interleavedGradientNoise, mix, perspectiveDepthToViewZ, positionGeometry, screenCoordinate, screenUV, smoothstep, texture, uniform, vec2, vec3, vec4, } from "three/tsl";

package/dist/Tsl.js

@@ -0,0 +1,18 @@
+/**
+ * TSL — three's shading language, for building node materials and shader
+ * graphs.
+ *
+ * @remarks
+ * Re-exported so downstream code has a single import root for the subset
+ * this project uses, rather than reaching into `three/tsl` from a dozen
+ * places.
+ *
+ * These are pure description: building a node graph runs no GPU work and
+ * cannot fail, so nothing here is an Effect. Effect enters when a graph is
+ * eventually rendered.
+ *
+ * Note that node types are deliberately not re-exported — three's published
+ * node types expand into unions large enough to stall a type check, so
+ * consumers declare the minimal shape they use. See `PostProcessing`.
+ */
+export { attribute, float, fwidth, interleavedGradientNoise, mix, perspectiveDepthToViewZ, positionGeometry, screenCoordinate, screenUV, smoothstep, texture, uniform, vec2, vec3, vec4, } from "three/tsl";

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `@effect-motion/three` — an Effect wrapper over three.js.
+ *
+ * @remarks
+ * Bindings only. This package knows nothing about effect-motion — no
+ * frames, no entities, no projection — and exists to give three.js the two
+ * things Effect code needs from it: resources that clean themselves up, and
+ * failures in a typed channel.
+ *
+ * The organizing rule is **Effect at the seams, raw three in between**:
+ *
+ * - **Construction and teardown are Effects.** {@link Renderer.make},
+ *   {@link Scene.make}, and {@link RenderTarget.make} are scoped, so a GPU
+ *   device, a scene's children, and a render target's memory are released
+ *   when the scope closes rather than by hand.
+ * - **Anything that can fail or is async is an Effect** — rendering,
+ *   readback, shader compilation — typed as {@link ThreeException}.
+ * - **Infallible mutation stays synchronous and chains.** Adding objects,
+ *   setting a background, resizing: these cannot fail, so wrapping them in
+ *   Effects would buy ceremony and nothing else. They return their handle
+ *   and compose with `.pipe`.
+ *
+ * Handles are branded wrappers around the three object, which stays
+ * reachable — `ThreeRaw` re-exports three itself for the leaf value types
+ * (geometries, materials, `Vector3`) and the per-frame mutation in a hot
+ * path. That escape hatch is deliberate: reaching past a wrapper should be
+ * a visible, greppable import rather than the path of least resistance.
+ *
+ * For headless rendering on a real GPU, import
+ * `@effect-motion/three/node` — it lives behind its own subpath so
+ * Node-only code never reaches a browser bundle.
+ *
+ * @example
+ * Scoped construction, sync chaining, Effects only where GPU work happens.
+ * ```typescript
+ * import { Renderer, RenderTarget, Scene } from "@effect-motion/three";
+ * import { Mesh, PerspectiveCamera } from "three/webgpu";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const scene = yield* Scene.make();
+ * 	const renderer = yield* Renderer.make({ width: 640, height: 360 });
+ * 	const target = yield* RenderTarget.make(640, 360);
+ *
+ * 	scene.pipe(Scene.add([new Mesh()]), Scene.setBackground(null));
+ *
+ * 	const camera = new PerspectiveCamera(50, 16 / 9, 1, 1000);
+ * 	Renderer.setRenderTarget(renderer, target);
+ * 	yield* Renderer.render(renderer, scene, camera);
+ * 	return yield* Renderer.readRenderTarget(renderer, target, 640, 360);
+ * }).pipe(Effect.scoped);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * as ThreeRaw from "three/webgpu";
+export * as Interop from "./Interop.js";
+export * as Line2 from "./Line2.js";
+export * as Object3D from "./Object3D.js";
+export * as PostProcessing from "./PostProcessing.js";
+export * as Renderer from "./Renderer.js";
+export * as RenderTarget from "./RenderTarget.js";
+export * as Scene from "./Scene.js";
+export { ThreeException } from "./ThreeException.js";
+export * as Tsl from "./Tsl.js";

package/dist/index.js

@@ -0,0 +1,76 @@
+/**
+ * `@effect-motion/three` — an Effect wrapper over three.js.
+ *
+ * @remarks
+ * Bindings only. This package knows nothing about effect-motion — no
+ * frames, no entities, no projection — and exists to give three.js the two
+ * things Effect code needs from it: resources that clean themselves up, and
+ * failures in a typed channel.
+ *
+ * The organizing rule is **Effect at the seams, raw three in between**:
+ *
+ * - **Construction and teardown are Effects.** {@link Renderer.make},
+ *   {@link Scene.make}, and {@link RenderTarget.make} are scoped, so a GPU
+ *   device, a scene's children, and a render target's memory are released
+ *   when the scope closes rather than by hand.
+ * - **Anything that can fail or is async is an Effect** — rendering,
+ *   readback, shader compilation — typed as {@link ThreeException}.
+ * - **Infallible mutation stays synchronous and chains.** Adding objects,
+ *   setting a background, resizing: these cannot fail, so wrapping them in
+ *   Effects would buy ceremony and nothing else. They return their handle
+ *   and compose with `.pipe`.
+ *
+ * Handles are branded wrappers around the three object, which stays
+ * reachable — `ThreeRaw` re-exports three itself for the leaf value types
+ * (geometries, materials, `Vector3`) and the per-frame mutation in a hot
+ * path. That escape hatch is deliberate: reaching past a wrapper should be
+ * a visible, greppable import rather than the path of least resistance.
+ *
+ * For headless rendering on a real GPU, import
+ * `@effect-motion/three/node` — it lives behind its own subpath so
+ * Node-only code never reaches a browser bundle.
+ *
+ * @example
+ * Scoped construction, sync chaining, Effects only where GPU work happens.
+ * ```typescript
+ * import { Renderer, RenderTarget, Scene } from "@effect-motion/three";
+ * import { Mesh, PerspectiveCamera } from "three/webgpu";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const scene = yield* Scene.make();
+ * 	const renderer = yield* Renderer.make({ width: 640, height: 360 });
+ * 	const target = yield* RenderTarget.make(640, 360);
+ *
+ * 	scene.pipe(Scene.add([new Mesh()]), Scene.setBackground(null));
+ *
+ * 	const camera = new PerspectiveCamera(50, 16 / 9, 1, 1000);
+ * 	Renderer.setRenderTarget(renderer, target);
+ * 	yield* Renderer.render(renderer, scene, camera);
+ * 	return yield* Renderer.readRenderTarget(renderer, target, 640, 360);
+ * }).pipe(Effect.scoped);
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Browser-safe, bindings-only surface over three.js: branded handles with
+// Effect at the seams (lifecycle, async boundaries, failures), sync
+// chaining for infallible mutation. Knows nothing about effect-motion —
+// no frames, entities, or projection. The Node entry (Dawn device +
+// environment shims) lives at "@effect-motion/three/node" so node-only
+// code never reaches a browser bundle.
+//
+// `ThreeRaw` is the deliberate escape hatch, not the front door: reaching
+// past a wrapper (three's leaf value types, the per-frame object mutation
+// in the renderer's hot path) is a visible, greppable import rather than
+// the path of least resistance. New code should prefer the actors below.
+export * as ThreeRaw from "three/webgpu";
+export * as Interop from "./Interop.js";
+export * as Line2 from "./Line2.js";
+export * as Object3D from "./Object3D.js";
+export * as PostProcessing from "./PostProcessing.js";
+export * as Renderer from "./Renderer.js";
+export * as RenderTarget from "./RenderTarget.js";
+export * as Scene from "./Scene.js";
+export { ThreeException } from "./ThreeException.js";
+export * as Tsl from "./Tsl.js";

package/dist/node.d.ts

@@ -0,0 +1,47 @@
+import type { Effect } from "effect";
+import type { ThreeException } from "./ThreeException.js";
+/**
+ * Acquire a GPU device from Dawn.
+ *
+ * @remarks
+ * Pass the result to `Renderer.make` rather than letting three request its
+ * own. three asks for a "compatibility" feature level, which Chrome quietly
+ * upgrades but Dawn honors literally — costing MSAA and other core features,
+ * so headless output would be visibly worse than the browser's for the same
+ * scene. This requests a core device with every feature the adapter offers.
+ *
+ * Fails with a `ThreeException` when no adapter is available.
+ */
+export declare const makeDevice: () => Effect.Effect<GPUDevice, ThreeException>;
+/**
+ * A canvas-shaped stand-in for headless rendering.
+ *
+ * @remarks
+ * three's renderer requires a canvas and a context even when nothing is
+ * displayed. These satisfy that without a DOM. The renderer must draw only
+ * into render targets: asking this context for the default framebuffer
+ * throws, deliberately, rather than silently rendering nowhere.
+ *
+ * @param width - Buffer width in device pixels.
+ * @param height - Buffer height in device pixels.
+ */
+export declare const stubCanvas: (width: number, height: number) => {
+    canvas: {
+        width: number;
+        height: number;
+        style: {};
+        addEventListener(): void;
+        removeEventListener(): void;
+        dispatchEvent(): void;
+        getContext: () => {
+            configure(): void;
+            unconfigure(): void;
+            getCurrentTexture(): never;
+        };
+    };
+    context: {
+        configure(): void;
+        unconfigure(): void;
+        getCurrentTexture(): never;
+    };
+};

package/dist/node.js

@@ -0,0 +1,157 @@
+import { create, globals } from "webgpu";
+import { wrapPromise } from "./Interop.js";
+/**
+ * Running three.js on a real GPU in Node, with no browser.
+ *
+ * @remarks
+ * WebGPU comes from Dawn (Chrome's implementation, via the `webgpu` npm
+ * bindings). Importing this module installs the browser environment three
+ * expects as a TOP-LEVEL SIDE EFFECT: `navigator.gpu`, the WebGPU
+ * constants, `self`, a `requestAnimationFrame` shim, and a minimal
+ * `XMLHttpRequest` that font loaders need. Import it before creating a
+ * renderer.
+ *
+ * Node-only. Never import it from the browser-safe root entry.
+ *
+ * Two gotchas worth knowing before your first script:
+ *
+ * - **Your script will hang on exit.** three's animation loop keeps
+ *   rescheduling the rAF shim, so Node's event loop never drains. End a
+ *   standalone script with `process.exit(0)`, or run it under
+ *   `NodeRuntime.runMain`, which exits explicitly. Test runners and the
+ *   export pipeline already handle this.
+ * - **There is no canvas**, so render into a `RenderTarget` and read it
+ *   back. {@link stubCanvas} supplies the canvas-shaped object the renderer
+ *   constructor insists on.
+ *
+ * @example
+ * The headless setup, start to finish.
+ * ```typescript
+ * import * as NodeThree from "@effect-motion/three/node";
+ * import { Renderer, RenderTarget, Scene } from "@effect-motion/three";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const device = yield* NodeThree.makeDevice();
+ * 	const { canvas, context } = NodeThree.stubCanvas(640, 360);
+ * 	const renderer = yield* Renderer.make({
+ * 		canvas: canvas as unknown as HTMLCanvasElement,
+ * 		context: context as never,
+ * 		device,
+ * 		width: 640,
+ * 		height: 360,
+ * 	});
+ * 	const target = yield* RenderTarget.make(640, 360);
+ * 	Renderer.setRenderTarget(renderer, target);
+ * 	yield* Renderer.render(renderer, scene, camera);
+ * 	return yield* Renderer.readRenderTarget(renderer, target, 640, 360);
+ * }).pipe(Effect.scoped);
+ * ```
+ */
+// WebGPU constants (GPUBufferUsage etc.) that browser code assumes global
+Object.assign(globalThis, globals);
+// Node ≥ 24 defines `navigator` as a getter-only global — defineProperty
+// over it. Idempotent: skip when a gpu-bearing navigator already exists.
+if (typeof navigator === "undefined" ||
+    navigator.gpu === undefined) {
+    Object.defineProperty(globalThis, "navigator", {
+        value: { gpu: create([]) },
+        configurable: true,
+    });
+}
+// three's internal Animation loop wants requestAnimationFrame on `self`
+const g = globalThis;
+if (g.self === undefined) {
+    g.self = globalThis;
+}
+if (g.requestAnimationFrame === undefined) {
+    g.requestAnimationFrame = (cb) => setTimeout(() => cb(performance.now()), 16);
+    g.cancelAnimationFrame = (id) => clearTimeout(id);
+}
+// Minimal XMLHttpRequest over fetch: arraybuffer GETs only — what font
+// loaders (troika's Typr path) need. Supports data:/http(s) URIs.
+if (g.XMLHttpRequest === undefined) {
+    class NodeXHR {
+        responseType = "";
+        response = null;
+        status = 0;
+        statusText = "";
+        onload = null;
+        onerror = null;
+        url = "";
+        open(_method, url) {
+            this.url = url;
+        }
+        send() {
+            fetch(this.url)
+                .then(async (res) => {
+                this.status = res.status;
+                this.statusText = res.statusText;
+                this.response =
+                    this.responseType === "arraybuffer"
+                        ? await res.arrayBuffer()
+                        : await res.text();
+                this.onload?.();
+            })
+                .catch((err) => {
+                this.onerror?.(err);
+            });
+        }
+    }
+    g.XMLHttpRequest = NodeXHR;
+}
+/**
+ * Acquire a GPU device from Dawn.
+ *
+ * @remarks
+ * Pass the result to `Renderer.make` rather than letting three request its
+ * own. three asks for a "compatibility" feature level, which Chrome quietly
+ * upgrades but Dawn honors literally — costing MSAA and other core features,
+ * so headless output would be visibly worse than the browser's for the same
+ * scene. This requests a core device with every feature the adapter offers.
+ *
+ * Fails with a `ThreeException` when no adapter is available.
+ */
+export const makeDevice = () => wrapPromise("requestAdapter", async () => {
+    const gpu = navigator.gpu;
+    const adapter = await gpu.requestAdapter({
+        featureLevel: "core",
+    });
+    if (adapter === null) {
+        throw new Error("no WebGPU adapter available (Dawn)");
+    }
+    return adapter.requestDevice({
+        requiredFeatures: [...adapter.features],
+    });
+});
+/**
+ * A canvas-shaped stand-in for headless rendering.
+ *
+ * @remarks
+ * three's renderer requires a canvas and a context even when nothing is
+ * displayed. These satisfy that without a DOM. The renderer must draw only
+ * into render targets: asking this context for the default framebuffer
+ * throws, deliberately, rather than silently rendering nowhere.
+ *
+ * @param width - Buffer width in device pixels.
+ * @param height - Buffer height in device pixels.
+ */
+export const stubCanvas = (width, height) => {
+    const context = {
+        configure() { },
+        unconfigure() { },
+        getCurrentTexture() {
+            throw new Error("default framebuffer used in headless mode");
+        },
+    };
+    const canvas = {
+        width,
+        height,
+        style: {},
+        addEventListener() { },
+        removeEventListener() { },
+        dispatchEvent() { },
+        getContext: () => context,
+    };
+    return { canvas, context };
+};

package/dist/usageDemo.d.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+/**
+ * A worked example of this package's conventions, kept compiling so it
+ * cannot drift.
+ *
+ * @remarks
+ * Demonstrates the three rules the wrapper is built on: scoped
+ * construction that cleans itself up, synchronous chaining for mutation
+ * that cannot fail, and Effects only where a call is fallible or async.
+ *
+ * Internal — a reference to read, not part of the public surface. It is
+ * written for the browser and kept compiling rather than kept running:
+ * executing it in Node fails at renderer init, since it takes no canvas or
+ * device. See `@effect-motion/three/node` for the headless equivalent.
+ */
+export declare const program: Effect.Effect<number, import("./ThreeException.js").ThreeException, never>;

package/dist/usageDemo.js

@@ -0,0 +1,35 @@
+import { Effect } from "effect";
+import { Mesh, PerspectiveCamera } from "three/webgpu";
+import * as Renderer from "./Renderer.js";
+import * as RenderTarget from "./RenderTarget.js";
+import * as Scene from "./Scene.js";
+/**
+ * A worked example of this package's conventions, kept compiling so it
+ * cannot drift.
+ *
+ * @remarks
+ * Demonstrates the three rules the wrapper is built on: scoped
+ * construction that cleans itself up, synchronous chaining for mutation
+ * that cannot fail, and Effects only where a call is fallible or async.
+ *
+ * Internal — a reference to read, not part of the public surface. It is
+ * written for the browser and kept compiling rather than kept running:
+ * executing it in Node fails at renderer init, since it takes no canvas or
+ * device. See `@effect-motion/three/node` for the headless equivalent.
+ */
+export const program = Effect.gen(function* () {
+    // scoped construction: the scene detaches its children on close, the
+    // renderer drains and disposes, the target frees its GPU allocation
+    const scene = yield* Scene.make();
+    const renderer = yield* Renderer.make({ width: 640, height: 360 });
+    const target = yield* RenderTarget.make(640, 360);
+    // infallible mutation: sync, chains through pipe, allocates no Effect
+    scene.pipe(Scene.add([new Mesh()]), Scene.setBackground(null));
+    Renderer.setPixelRatio(renderer, 2);
+    // GPU work can fail: Effects, typed as ThreeException
+    const camera = new PerspectiveCamera(50, 16 / 9, 1, 1000);
+    Renderer.setRenderTarget(renderer, target);
+    yield* Renderer.render(renderer, scene, camera);
+    const pixels = yield* Renderer.readRenderTarget(renderer, target, 640, 360);
+    return pixels.byteLength;
+}).pipe(Effect.scoped);

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@effect-motion/three",
+  "version": "0.5.0",
+  "description": "Bindings-only Effect wrapper over three.js for effect-motion",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julia-script/effect-motion.git",
+    "directory": "packages/three"
+  },
+  "homepage": "https://github.com/julia-script/effect-motion#readme",
+  "bugs": "https://github.com/julia-script/effect-motion/issues",
+  "keywords": [
+    "effect",
+    "motion",
+    "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": {
+    "@types/three": "^0.185.1",
+    "three": "^0.185.1",
+    "webgpu": "^0.4.0"
+  },
+  "peerDependencies": {
+    "effect": ">=4.0.0-beta.98"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "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"
+  }
+}