@octanejs/drei 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Paul Henschel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @octanejs/drei
+
+An Octane port of the complete pinned `@react-three/drei@10.7.7` public web API.
+
+This package is under active parity development. Compatibility claims are tied
+to the executable upstream crosswalk and React/Octane evidence described in
+[UPSTREAM.md](./UPSTREAM.md); no unsupported export is exposed as a stub.
+
+Compiler configuration must use `dreiRenderers` from `@octanejs/drei/config`.
+The preset includes the Three renderer and the Three-to-DOM child boundary used
+by `Html` and PivotControls annotations.

package/UPSTREAM.md

@@ -0,0 +1,92 @@
+# Upstream Drei audit
+
+This port targets the immutable `@react-three/drei@10.7.7` release:
+
+- repository: `https://github.com/pmndrs/drei`;
+- tag: `v10.7.7`;
+- tag commit: `b8b99fd4ca1dfb8d821335671320512daa6efea4`;
+- package: `@react-three/drei@10.7.7`;
+- React oracle: React 19 with `@react-three/fiber@9.6.1`;
+- Three compatibility range: `three >=0.159`.
+
+## Source and evidence boundary
+
+`upstream/` is a byte-exact development-only snapshot of the release's `src/`,
+`test/`, package manifest, TypeScript configuration, and MIT license. It is not
+included in the published package. The registry artifact supplies the executable
+React oracle and declaration surface; the tagged repository supplies authored
+source, stories, test configuration, and the sole upstream end-to-end suite.
+
+Drei has no focused unit-test corpus at this pin. Its observable component
+contracts are primarily expressed through Storybook stories. Those artifacts are
+therefore inventoried as upstream evidence, then exercised through paired React
+and Octane characterization fixtures at the appropriate DOM, Three-scene, or
+real-browser observation boundary.
+
+The complete tagged test tree contains exactly four artifacts, all under
+`test/e2e/`: `App.tsx`, `e2e.sh`, `snapshot.test.ts`, and its Linux PNG snapshot.
+They form one whole-gallery Playwright screenshot case. Their byte hashes and
+dispositions are recorded in `audit/upstream-test-artifacts.json`.
+
+The full tarball/Vite/Next workflow in `e2e.sh` remains out of scope. The
+vendored `snapshot.test.ts` case now runs unchanged in Chromium through the
+`playwright-full` lane, which creates the small Vite React app it expects from
+the byte-exact vendored `App.tsx`. The separate `drei-adapted-browser` Vitest
+project ports that scene to Octane and uses the same screenshot oracle; it is
+adapted evidence, never a claim that the upstream test ran there. The upstream
+runtime suite remains `insufficient`: its one case is genuine pristine evidence,
+but an incomplete suite cannot replace the required upstream-suite lanes and
+repo-authored differential evidence.
+
+The tag contains no upstream type-test suite. The upstream `tsconfig.json`
+compiles package source, while the `@ts-expect-error` comments in that source are
+inventoried separately so removing one makes the audit fail. The port's
+`typetests/` remain repository-authored API checks. Paired pristine/adapted
+public-surface type lanes under `typetests/{pristine,adapted}/` run through
+`react-parity:check`; the broader `typetests/*.test-d.ts` suite continues in
+package typecheck.
+
+## Executable parity evidence
+
+`audit/react-parity.json` registers the pristine upstream Playwright lane, the
+separate adapted upstream browser lane, the `drei-differential` Vitest project
+(all paired React/Octane characterization files, including the View canary), and
+repo-authored pristine/adapted type lanes with the global `react-parity:check`
+harness. The View renderer-boundary divergence cites an ordinary
+`ordinary:view-renderer-boundary` audit identity (not a React-parity lane) so
+authentication stays in the ordinary `drei-guards` project.
+`audit/test-classifications.json` gives every port-authored runtime and type
+test file exactly one disposition. Paired files import the pinned React Drei
+oracle in the test body; `config.test.ts`, `crosswalk-guard.test.ts`,
+`react-parity-guard.test.ts`, and `view-renderer-boundary.test.ts` are
+Octane-only and execute in the ordinary `drei-guards` project outside
+`testExecution`. Ordinary `typetests/*.test-d.ts` files are classified
+Octane-only and stay outside parity evidence; only the public-API pair under
+`typetests/{pristine,adapted}/` is parity type evidence.
+
+`audit/runtime-evidence.json` hashes every test file and every collected assertion
+inventory. `audit/upstream-test-artifacts.json` records the executed screenshot
+case and its supporting artifacts. `typetests/assertions.md` defines the
+permitted import/comment transformations and shared assertion groups. The audit
+guard includes negative controls for a dropped differential inventory file, deleted
+assertion, removed upstream `@ts-expect-error` inventory entry, and fabricated
+upstream type suite.
+
+## Completeness contract
+
+`audit/upstream-crosswalk.json` is generated from the pinned public runtime and
+type surfaces. Every public web export must have an Octane implementation and
+executable evidence before this package claims parity. Missing, placeholder, or
+unclassified entries fail validation; intentional Octane differences require a
+consumer-visible rationale and evidence from both implementations.
+
+## Intentional renderer divergence
+
+`View` supports Drei's inline Canvas form, including tracked rectangles, portal
+scenes, scissor rendering, event computation, and render ordering. React Drei
+also lets the same component render in a DOM root and transports its Three
+children through `View.Port` using `tunnel-rat`. Octane components are
+statically owned by one renderer, so a Three component cannot switch to the DOM
+renderer or move authored children between independent DOM and Three roots.
+Calling `View` from a DOM root therefore raises Octane's renderer-boundary
+diagnostic, and `View.Port` remains a callable, type-compatible no-op.

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@octanejs/drei",
+  "version": "0.0.1",
+  "description": "Octane port of @react-three/drei",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./web": "./src/web/index.ts",
+    "./core": "./src/core/index.ts",
+    "./config": "./src/config.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md",
+    "LICENSE",
+    "status.json"
+  ],
+  "dependencies": {
+    "@mediapipe/tasks-vision": "0.10.17",
+    "@monogrid/gainmap-js": "^3.0.6",
+    "@use-gesture/core": "^10.3.1",
+    "camera-controls": "^3.1.0",
+    "detect-gpu": "^5.0.56",
+    "hls.js": "^1.5.17",
+    "maath": "^0.10.8",
+    "meshline": "^3.3.1",
+    "stats-gl": "^2.2.8",
+    "stats.js": "^0.17.0",
+    "three-mesh-bvh": "^0.8.3",
+    "three-stdlib": "^2.35.6",
+    "troika-three-text": "^0.52.4",
+    "@octanejs/zustand": "0.1.34"
+  },
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "peerDependencies": {
+    "@types/three": ">=0.159",
+    "three": ">=0.159",
+    "@octanejs/three": "0.1.28",
+    "octane": "0.1.35"
+  },
+  "peerDependenciesMeta": {
+    "@types/three": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/drei"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "devDependencies": {
+    "@react-three/drei": "10.7.7",
+    "@react-three/fiber": "9.6.1",
+    "@tsrx/react": "^0.2.56",
+    "@types/react": "^19.2.17",
+    "@types/stats.js": "^0.17.4",
+    "@types/three": "0.172.0",
+    "playwright": "^1.61.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "three": "0.172.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10",
+    "@octanejs/three": "0.1.28",
+    "@octanejs/zustand": "0.1.34",
+    "octane": "0.1.35"
+  },
+  "scripts": {
+    "upstream:generate": "node scripts/generate-upstream-crosswalk.mjs",
+    "upstream:check": "node scripts/check-upstream-crosswalk.mjs",
+    "upstream:ready": "node scripts/check-upstream-crosswalk.mjs --ready",
+    "react-parity:generate": "node scripts/generate-react-parity.mjs",
+    "react-parity:check": "node scripts/check-react-parity.mjs",
+    "test": "node scripts/check-react-parity.mjs && vitest run --root ../.. --project drei-differential --project drei-guards --project drei-adapted-browser",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsrx-tsc --noEmit -p typetests/tsconfig.json"
+  }
+}

package/src/config.ts

@@ -0,0 +1,14 @@
+import { threeRenderers } from '@octanejs/three/config';
+
+export const dreiRenderers = {
+	...threeRenderers,
+	boundaries: {
+		...threeRenderers.boundaries,
+		'@octanejs/drei': {
+			Html: { ownerRenderer: 'three', childRenderer: 'dom', prop: 'children' },
+		},
+	},
+} as const;
+
+export const renderers = dreiRenderers;
+export default dreiRenderers;

package/src/core/AccumulativeShadows.three.tsrx

@@ -0,0 +1,313 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { extend, type ThreeElements, type ThreeRef, useFrame, useThree } from '@octanejs/three';
+import { useCallback, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from '@octanejs/three/renderer';
+import { createContext, type OctaneNode, useContext } from 'octane';
+import * as THREE from 'three';
+import { shaderMaterial } from './shaderMaterial.js';
+
+function isLight(object: any): object is THREE.Light {
+	return Boolean(object.isLight);
+}
+
+function isGeometry(object: any): object is THREE.Mesh {
+	return Boolean(object.geometry);
+}
+
+export type AccumulativeShadowsProps = Omit<ThreeElements['group'], 'ref'> & {
+	frames?: number;
+	blend?: number;
+	limit?: number;
+	scale?: number;
+	temporal?: boolean;
+	opacity?: number;
+	alphaTest?: number;
+	color?: string;
+	colorBlend?: number;
+	resolution?: number;
+	toneMapped?: boolean;
+	children?: OctaneNode;
+};
+
+interface AccumulativeContext {
+	lights: Map<any, AccumulativeLightContext>;
+	temporal: boolean;
+	frames: number;
+	blend: number;
+	count: number;
+	getMesh: () => THREE.Mesh<THREE.PlaneGeometry, SoftShadowMaterial>;
+	reset: () => void;
+	update: (frames?: number) => void;
+}
+
+interface AccumulativeLightContext {
+	update: () => void;
+}
+
+type SoftShadowMaterial = THREE.ShaderMaterial & {
+	map: THREE.Texture;
+	color: THREE.Color;
+	alphaTest: number;
+	blend: number;
+	opacity: number;
+};
+
+export const accumulativeContext = createContext<AccumulativeContext>(null!);
+
+const SoftShadowMaterialImpl = shaderMaterial(
+	{ color: new THREE.Color(), blend: 2, alphaTest: 0.75, opacity: 0, map: null },
+	`varying vec2 vUv;
+   void main() {
+     gl_Position = projectionMatrix * viewMatrix * modelMatrix * vec4(position, 1.);
+     vUv = uv;
+   }`,
+	`varying vec2 vUv;
+   uniform sampler2D map;
+   uniform vec3 color;
+   uniform float opacity;
+   uniform float alphaTest;
+   uniform float blend;
+   void main() {
+     vec4 sampledDiffuseColor = texture2D(map, vUv);
+     gl_FragColor = vec4(color * sampledDiffuseColor.r * blend, max(0.0, (1.0 - (sampledDiffuseColor.r + sampledDiffuseColor.g + sampledDiffuseColor.b) / alphaTest)) * opacity);
+     #include <tonemapping_fragment>
+     #include <colorspace_fragment>
+   }`,
+);
+const SoftShadowMaterialElement = extend(SoftShadowMaterialImpl);
+
+const DiscardMaterial = shaderMaterial(
+	{},
+	'void main() { }',
+	'void main() { gl_FragColor = vec4(0.0, 0.0, 0.0, 0.0); discard; }',
+);
+
+class ProgressiveLightMap {
+	renderer: any;
+	res: number;
+	scene: THREE.Scene;
+	object: THREE.Mesh | null = null;
+	buffer1Active = false;
+	progressiveLightMap1: THREE.WebGLRenderTarget;
+	progressiveLightMap2: THREE.WebGLRenderTarget;
+	discardMat = new DiscardMaterial();
+	targetMat = new THREE.MeshLambertMaterial({ fog: false });
+	previousShadowMap: { value: THREE.Texture };
+	averagingWindow = { value: 100 };
+	clearColor = new THREE.Color();
+	clearAlpha = 0;
+	lights: Array<{ object: THREE.Light; intensity: number }> = [];
+	meshes: Array<{ object: THREE.Mesh; material: THREE.Material | THREE.Material[] }> = [];
+
+	constructor(renderer: any, scene: THREE.Scene, res = 1024) {
+		this.renderer = renderer;
+		this.res = res;
+		this.scene = scene;
+		const textureParams = { type: THREE.HalfFloatType, magFilter: THREE.NearestFilter, minFilter: THREE.NearestFilter };
+		this.progressiveLightMap1 = new THREE.WebGLRenderTarget(res, res, textureParams);
+		this.progressiveLightMap2 = new THREE.WebGLRenderTarget(res, res, textureParams);
+		this.previousShadowMap = { value: this.progressiveLightMap1.texture };
+		this.targetMat.onBeforeCompile = (shader) => {
+			shader.vertexShader = `varying vec2 vUv;\n${shader.vertexShader.slice(0, -1)}vUv = uv; gl_Position = vec4((uv - 0.5) * 2.0, 1.0, 1.0); }`;
+			const bodyStart = shader.fragmentShader.indexOf('void main() {');
+			shader.fragmentShader = `varying vec2 vUv;\n${shader.fragmentShader.slice(0, bodyStart)}uniform sampler2D previousShadowMap;\nuniform float averagingWindow;\n${shader.fragmentShader.slice(bodyStart - 1, -1)}\nvec3 texelOld = texture2D(previousShadowMap, vUv).rgb;\ngl_FragColor.rgb = mix(texelOld, gl_FragColor.rgb, 1.0 / averagingWindow);\n}`;
+			shader.uniforms.previousShadowMap = this.previousShadowMap;
+			shader.uniforms.averagingWindow = this.averagingWindow;
+		};
+	}
+
+	clear() {
+		this.renderer.getClearColor(this.clearColor);
+		this.clearAlpha = this.renderer.getClearAlpha();
+		this.renderer.setClearColor('black', 1);
+		this.renderer.setRenderTarget(this.progressiveLightMap1);
+		this.renderer.clear();
+		this.renderer.setRenderTarget(this.progressiveLightMap2);
+		this.renderer.clear();
+		this.renderer.setRenderTarget(null);
+		this.renderer.setClearColor(this.clearColor, this.clearAlpha);
+		this.lights = [];
+		this.meshes = [];
+		this.scene.traverse((object) => {
+			if (isGeometry(object)) this.meshes.push({ object, material: object.material });
+			else if (isLight(object)) this.lights.push({ object, intensity: object.intensity });
+		});
+	}
+
+	prepare() {
+		this.lights.forEach((light) => (light.object.intensity = 0));
+		this.meshes.forEach((mesh) => (mesh.object.material = this.discardMat));
+	}
+
+	finish() {
+		this.lights.forEach((light) => (light.object.intensity = light.intensity));
+		this.meshes.forEach((mesh) => (mesh.object.material = mesh.material));
+	}
+
+	configure(object: THREE.Mesh) {
+		this.object = object;
+	}
+
+	update(camera: THREE.Camera, blendWindow = 100) {
+		if (!this.object) return;
+		this.averagingWindow.value = blendWindow;
+		this.object.material = this.targetMat;
+		const activeMap = this.buffer1Active ? this.progressiveLightMap1 : this.progressiveLightMap2;
+		const inactiveMap = this.buffer1Active ? this.progressiveLightMap2 : this.progressiveLightMap1;
+		const oldBackground = this.scene.background;
+		this.scene.background = null;
+		this.renderer.setRenderTarget(activeMap);
+		this.previousShadowMap.value = inactiveMap.texture;
+		this.buffer1Active = !this.buffer1Active;
+		this.renderer.render(this.scene, camera);
+		this.renderer.setRenderTarget(null);
+		this.scene.background = oldBackground;
+	}
+}
+
+export function AccumulativeShadows({
+	children,
+	temporal,
+	frames = 40,
+	limit = Infinity,
+	blend = 20,
+	scale = 10,
+	opacity = 1,
+	alphaTest = 0.75,
+	color = 'black',
+	colorBlend = 2,
+	resolution = 1024,
+	toneMapped = true,
+	ref,
+	...props
+}: AccumulativeShadowsProps & { ref?: ThreeRef<AccumulativeContext> }) @{
+	const gl = useThree((state) => state.gl);
+	const scene = useThree((state) => state.scene);
+	const camera = useThree((state) => state.camera);
+	const invalidate = useThree((state) => state.invalidate);
+	const plane = useRef<THREE.Mesh<THREE.PlaneGeometry, SoftShadowMaterial> | null>(null);
+	const lights = useRef<THREE.Group | null>(null);
+	const [lightMap] = useState(() => new ProgressiveLightMap(gl, scene, resolution));
+	useLayoutEffect(() => lightMap.configure(plane.current!), []);
+	const api = useMemo<AccumulativeContext>(() => ({
+		lights: new Map(),
+		temporal: Boolean(temporal),
+		frames: Math.max(2, frames),
+		blend: Math.max(2, frames === Infinity ? blend : frames),
+		count: 0,
+		getMesh: () => plane.current!,
+		reset: () => {
+			lightMap.clear();
+			plane.current!.material.opacity = 0;
+			plane.current!.material.alphaTest = 0;
+			api.count = 0;
+		},
+		update: (count = 1) => {
+			const material = plane.current!.material;
+			if (!api.temporal) {
+				material.opacity = opacity;
+				material.alphaTest = alphaTest;
+			} else {
+				material.opacity = Math.min(opacity, material.opacity + opacity / api.blend);
+				material.alphaTest = Math.min(alphaTest, material.alphaTest + alphaTest / api.blend);
+			}
+			lights.current!.visible = true;
+			lightMap.prepare();
+			for (let index = 0; index < count; index++) {
+				api.lights.forEach((light) => light.update());
+				lightMap.update(camera, api.blend);
+			}
+			lights.current!.visible = false;
+			lightMap.finish();
+		},
+	}), [lightMap, camera, scene, temporal, frames, blend, opacity, alphaTest]);
+	useLayoutEffect(() => {
+		api.reset();
+		if (!api.temporal && api.frames !== Infinity) api.update(api.blend);
+	});
+	useImperativeHandle((ref ?? null) as any, () => api, [api]);
+	useFrame(() => {
+		if ((api.temporal || api.frames === Infinity) && api.count < api.frames && api.count < limit) {
+			invalidate();
+			api.update();
+			api.count++;
+		}
+	});
+	<group {...props}>
+		<group {...({ traverse: () => null } as any)} ref={lights}>
+			<accumulativeContext.Provider value={api}>{children}</accumulativeContext.Provider>
+		</group>
+		<mesh receiveShadow ref={plane as any} scale={scale} rotation={[-Math.PI / 2, 0, 0]}>
+			<planeGeometry />
+			<SoftShadowMaterialElement transparent depthWrite={false} toneMapped={toneMapped} color={color} blend={colorBlend} map={lightMap.progressiveLightMap2.texture as any} />
+		</mesh>
+	</group>
+}
+
+export type RandomizedLightProps = Omit<ThreeElements['group'], 'ref'> & {
+	frames?: number;
+	position?: [x: number, y: number, z: number];
+	radius?: number;
+	amount?: number;
+	intensity?: number;
+	ambient?: number;
+	castShadow?: boolean;
+	bias?: number;
+	mapSize?: number;
+	size?: number;
+	near?: number;
+	far?: number;
+};
+
+export function RandomizedLight({
+	castShadow = true,
+	bias = 0.001,
+	mapSize = 512,
+	size = 5,
+	near = 0.5,
+	far = 500,
+	frames = 1,
+	position = [0, 0, 0],
+	radius = 1,
+	amount = 8,
+	intensity = Math.PI,
+	ambient = 0.5,
+	ref,
+	...props
+}: RandomizedLightProps & { ref?: ThreeRef<AccumulativeLightContext> }) @{
+	const group = useRef<THREE.Group | null>(null);
+	const length = new THREE.Vector3(...position).length();
+	const parent = useContext(accumulativeContext);
+	const update = useCallback(() => {
+		if (!group.current) return;
+		for (const light of group.current.children) {
+			if (Math.random() > ambient) {
+				light.position.set(
+					position[0] + THREE.MathUtils.randFloatSpread(radius),
+					position[1] + THREE.MathUtils.randFloatSpread(radius),
+					position[2] + THREE.MathUtils.randFloatSpread(radius),
+				);
+			} else {
+				const lambda = Math.acos(2 * Math.random() - 1) - Math.PI / 2;
+				const phi = 2 * Math.PI * Math.random();
+				light.position.set(
+					Math.cos(lambda) * Math.cos(phi) * length,
+					Math.abs(Math.cos(lambda) * Math.sin(phi) * length),
+					Math.sin(lambda) * length,
+				);
+			}
+		}
+	}, [radius, ambient, length, ...position]);
+	const api = useMemo<AccumulativeLightContext>(() => ({ update }), [update]);
+	useImperativeHandle((ref ?? null) as any, () => api, [api]);
+	useLayoutEffect(() => {
+		if (parent && group.current) parent.lights.set(group.current.uuid, api);
+		return () => { if (group.current) parent?.lights.delete(group.current.uuid); };
+	}, [parent, api]);
+	<group ref={group} {...props}>
+		@for (const index of Array.from({ length: amount }, (_, value) => value); key index) {
+			<directionalLight castShadow={castShadow} shadow-bias={bias} shadow-mapSize={[mapSize, mapSize]} intensity={intensity / amount}>
+				<orthographicCamera attach="shadow-camera" args={[-size, size, size, -size, near, far]} />
+			</directionalLight>
+		}
+	</group>
+}

package/src/core/AdaptivePerformance.three.tsrx

@@ -0,0 +1,49 @@
+import { useThree } from '@octanejs/three';
+import { useEffect } from '@octanejs/three/renderer';
+
+export function AdaptiveEvents() @{
+	const get = useThree((state) => state.get);
+	const setEvents = useThree((state) => state.setEvents);
+	const current = useThree((state) => state.performance.current);
+	useEffect(() => {
+		const enabled = get().events.enabled;
+		return () => setEvents({ enabled });
+	}, []);
+	useEffect(() => setEvents({ enabled: current === 1 }), [current]);
+	null;
+}
+
+export function BakeShadows() @{
+	const gl = useThree((state) => state.gl);
+	const shadowMap = gl.shadowMap!;
+	useEffect(() => {
+		shadowMap.autoUpdate = false;
+		shadowMap.needsUpdate = true;
+		return () => {
+			shadowMap.autoUpdate = shadowMap.needsUpdate = true;
+		};
+	}, [shadowMap]);
+	null;
+}
+
+export function AdaptiveDpr({ pixelated }: { pixelated?: boolean }) @{
+	const gl = useThree((state) => state.gl);
+	const active = useThree((state) => state.internal.active);
+	const current = useThree((state) => state.performance.current);
+	const initialDpr = useThree((state) => state.viewport.initialDpr);
+	const setDpr = useThree((state) => state.setDpr);
+	useEffect(() => {
+		const domElement = gl.domElement as HTMLElement;
+		return () => {
+			if (active) setDpr(initialDpr);
+			if (pixelated && domElement) domElement.style.imageRendering = 'auto';
+		};
+	}, []);
+	useEffect(() => {
+		setDpr(current * initialDpr);
+		if (pixelated && gl.domElement) {
+			(gl.domElement as HTMLElement).style.imageRendering = current === 1 ? 'auto' : 'pixelated';
+		}
+	}, [current]);
+	null;
+}

package/src/core/AsciiRenderer.three.tsrx

@@ -0,0 +1,61 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { useFrame, useThree } from '@octanejs/three';
+import { useEffect, useLayoutEffect, useMemo } from '@octanejs/three/renderer';
+import { AsciiEffect } from 'three-stdlib';
+
+export type AsciiRendererProps = {
+	renderIndex?: number;
+	bgColor?: string;
+	fgColor?: string;
+	characters?: string;
+	invert?: boolean;
+	color?: boolean;
+	resolution?: number;
+};
+
+export function AsciiRenderer({
+	renderIndex = 1,
+	bgColor = 'black',
+	fgColor = 'white',
+	characters = ' .:-+*=%@#',
+	invert = true,
+	color = false,
+	resolution = 0.15,
+}: AsciiRendererProps) @{
+	const { size, gl, scene, camera } = useThree();
+	const canvas = gl.domElement as HTMLCanvasElement;
+	const effect = useMemo(() => {
+		// three-stdlib follows the workspace's newer Three types while the renderer
+		// intentionally accepts the binding's structural renderer contract.
+		const value = new AsciiEffect(gl as any, characters, { invert, color, resolution });
+		value.domElement.style.position = 'absolute';
+		value.domElement.style.top = '0px';
+		value.domElement.style.left = '0px';
+		value.domElement.style.pointerEvents = 'none';
+		return value;
+	}, [characters, invert, color, resolution]);
+
+	useLayoutEffect(() => {
+		effect.domElement.style.color = fgColor;
+		effect.domElement.style.backgroundColor = bgColor;
+	}, [fgColor, bgColor]);
+
+	useEffect(() => {
+		canvas.style.opacity = '0';
+		canvas.parentNode!.appendChild(effect.domElement);
+		return () => {
+			canvas.style.opacity = '1';
+			canvas.parentNode!.removeChild(effect.domElement);
+		};
+	}, [effect]);
+
+	useEffect(() => {
+		effect.setSize(size.width, size.height);
+	}, [effect, size]);
+
+	useFrame(() => {
+		effect.render(scene as any, camera as any);
+	}, renderIndex);
+
+	null;
+}