@octanejs/three 0.1.0

package/LICENSE

@@ -0,0 +1,49 @@
+Octane Three binding
+====================
+
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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.
+
+React Three Fiber-derived algorithms and types
+===============================================
+
+MIT License
+
+Copyright (c) 2019-2025 Poimandres
+
+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,215 @@
+# `@octanejs/three`
+
+An experimental React Three Fiber 9-compatible web renderer for Octane. Octane
+keeps ownership of component execution, hooks, context, Suspense, refs, and
+effects; this package supplies the Three-specific host layer.
+
+Milestones 0, 2, 3, 4, 5, and 6 are implemented on top of Octane's renderer SDK
+foundation. The current technical preview includes:
+
+- the serializable compiler preset, renderer entry point, renderer-local Three
+  intrinsic types, and pinned upstream export/test crosswalk;
+- the Three constructor catalogue, object and constructor-component `extend`
+  forms, `primitive`, and constructor `args`;
+- real Three host objects with prop diff/application, automatic, string, and
+  function attachments, ordered placement and moves, reconstruction, retained
+  visibility, lifecycle/ref delivery, and ownership-aware disposal; and
+- the DOM `Canvas` boundary, programmatic roots, promise-returning renderer
+  configuration, the callable root store, camera/scene/raycaster setup,
+  resize/DPR/viewport state, shadows and color configuration;
+- one shared `always`/`demand`/`never` frame loop, global frame effects,
+  `useStore`, `useThree`, `useFrame`, `useGraph`, managed-instance helpers, and
+  the deterministic `@octanejs/three/testing` harness;
+- R3F-compatible ray and pointer events, including 3D bubbling, hit ordering,
+  propagation, hover transitions, missed clicks, pointer capture, custom event
+  managers, external DOM sources, and coordinate prefixes;
+- a Suspense-aware `useLoader` cache with constructor and instance loaders,
+  scalar and array inputs, extensions, progress, GLTF graph augmentation,
+  `preload`, `clear`, and cached error routing;
+- retained Three Suspense and Activity visibility, ownership-safe teardown, and
+  client-side Three-to-DOM pending/error projection;
+- same-renderer `createPortal` placement into borrowed `Object3D` targets,
+  R3F-shaped state/event enclaves, nested context retention, one shared frame
+  loop, physical Three event bubbling, and root-scoped target teardown; and
+- public behavior, prepared-driver, and same-source compiled scene evidence
+  against R3F 9.6.1 with the exact Three r172 oracle.
+
+Full Canvas SSR/hydration adoption, XR, OffscreenCanvas lifecycle, and live HMR
+behavior follow in later milestones.
+
+Three deliberate correctness fixes differ from R3F 9.6.1:
+
+- removing a pierced prop such as `material-color` resets the nested material
+  property, instead of writing the default to a same-named leaf on the root
+  object; and
+- reconstructing a captured or hovered object rewrites every stored
+  intersection to the replacement, so subsequent captured events reach the
+  live handler instead of retaining the retired object; and
+- retained Activity subtrees are excluded from recursive raycasts while
+  hidden, rather than allowing an interactive visible ancestor to pierce an
+  invisible descendant.
+
+## Compiler configuration
+
+DOM remains the application renderer. Scene modules opt into Three through the
+shared renderer preset and the `*.three.tsrx` convention:
+
+```ts
+import { defineConfig } from '@octanejs/vite-plugin';
+import { threeRenderers } from '@octanejs/three/config';
+
+export default defineConfig({
+	compiler: {
+		renderers: threeRenderers,
+	},
+});
+```
+
+The same serializable `threeRenderers` value can be supplied to the Rsbuild and
+low-level Rspack integrations. Vite and Rsbuild additionally own application
+SSR and hydration; the Rspack plugin owns compilation and HMR only.
+
+The preset selects `@octanejs/three/renderer`, keeps Three scene modules
+client-only on the server, ignores authored text inside scenes, exposes a
+renderer-local intrinsic catalogue without merging Three tags into DOM JSX,
+and declares `Canvas.children` as the DOM-to-Three renderer boundary.
+
+## Canvas and scene modules
+
+The application remains a normal DOM Octane app. Only scene modules use the
+`.three.tsrx` convention:
+
+```tsx
+// App.tsrx
+import { Canvas } from '@octanejs/three';
+import { Scene } from './Scene.three.tsrx';
+
+export function App() @{
+	<Canvas frameloop="demand">
+		<Scene />
+	</Canvas>
+}
+```
+
+```tsx
+// Scene.three.tsrx
+import { useFrame } from '@octanejs/three';
+import { useRef } from '@octanejs/three/renderer';
+
+export function Scene() @{
+	const mesh = useRef(null);
+	useFrame((_state, delta) => (mesh.current.rotation.x += delta));
+	<mesh ref={mesh}>
+		<boxGeometry args={[1, 1, 1]} />
+		<meshBasicMaterial color="hotpink" />
+	</mesh>
+}
+```
+
+The low-level API follows Octane's component-plus-props root convention. Both
+synchronous and asynchronous renderer factories settle before the component
+can execute:
+
+```ts
+import { createRoot } from '@octanejs/three';
+
+const root = createRoot(canvas);
+await root.configure({ frameloop: 'never', dpr: 1 });
+root.render(Scene, { color: 'hotpink' });
+root.store.getState().advance(1 / 60);
+```
+
+Tests can inject the WebGL-free deterministic harness from
+`@octanejs/three/testing`; it drives the same root, host commits, hooks, and
+public `advance()` loop as an application. Its awaitable `fireEvent()` helper
+directly invokes the latest committed handler and settles scheduled work when
+raycasting itself is not under test.
+
+`Canvas` installs the default web event manager. Use `eventSource` to subscribe
+through another element and `eventPrefix` (`offset`, `client`, `page`, `layer`,
+or `screen`) to choose the coordinate pair. Programmatic roots can supply a
+custom `events(store)` manager factory and update it through `state.setEvents()`.
+
+`useStore()` returns the upstream-compatible callable store. Because a later
+`store(selector)` call is a dynamic function call, the compiler cannot assign
+that call its own lexical hook slot; keep that compatibility form unconditional
+and in stable order. Prefer `useStore(selector, equality?)` or
+`useThree(selector, equality?)` when using Octane's conditional-hook semantics.
+
+## Portals
+
+`createPortal` keeps its children in the authored Octane owner/context tree but
+places their Three hosts below a borrowed `Object3D`. The optional state layer
+matches R3F's portal model: it has its own scene, raycaster, pointer, and event
+priority while sharing the outer root's interaction registry and frame loop.
+
+```tsx
+import { createPortal, useThree } from '@octanejs/three';
+
+function Overlay() @{
+	const scene = useThree((state) => state.scene);
+	<group name={scene.name + '-overlay'} />
+}
+
+export function Scene(props) @{
+	<>
+		{createPortal(<Overlay />, props.overlayTarget, {
+			events: { priority: 2 },
+		})}
+	</>
+}
+```
+
+Portal targets are borrowed and never disposed by Octane. A managed target must
+belong to the same root; a local `Object3D` target also cannot cross a commit
+transport. Pointer hits use the portal layer's camera/raycaster, then bubble
+through physical `Object3D.parent` ancestry as they do in R3F. Component errors,
+effects, context, and scheduling continue to follow logical Octane ownership.
+
+## Assets, Suspense, and errors
+
+`useLoader` follows the R3F v9 cache contract. A loader constructor is
+instantiated once, while an existing loader instance is used directly. The
+loader identity and normalized input form the cache key; extensions and
+progress callbacks configure the first request for that key.
+
+```tsx
+import { useLoader } from '@octanejs/three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+
+function Model() @{
+	const gltf = useLoader(GLTFLoader, '/model.glb');
+	<primitive object={gltf.scene} />
+}
+
+export function Scene() @{
+	@try {
+		<Model />
+	} @pending {
+		<group name="loading-model" />
+	} @catch (error) {
+		<group name={'model-error:' + error.message} />
+	}
+}
+
+useLoader.preload(GLTFLoader, '/model.glb');
+// Later, when the next read must issue a fresh request:
+useLoader.clear(GLTFLoader, '/model.glb');
+```
+
+`clear` evicts the exact cache entry; it does not abort a request or dispose
+the resolved asset. Declarative Three resources remain owned by their mounted
+host tree, while objects passed through `primitive` remain caller-owned. A
+root-level Three suspension or render error is projected through `Canvas` to
+the nearest client DOM `@pending` or `@catch` arm. Streaming server fallback
+and Canvas hydration remain Milestone 7 work.
+
+## Compatibility target
+
+The compatibility baseline is `@react-three/fiber@9.6.1` at commit
+`2a528745e9aa7c9e6cca41e404b59d45cf0d0cc7`, with `three@0.172.0` as the exact
+behavioral oracle. React Native/Expo, R3F 10's WebGPU/TSL APIs, and Drei are
+separate follow-on efforts.
+
+See [`docs/three-port-plan.md`](../../docs/three-port-plan.md) for the delivery
+phases and [`UPSTREAM.md`](./UPSTREAM.md) for source and license provenance.

package/UPSTREAM.md

@@ -0,0 +1,58 @@
+# Upstream React Three Fiber audit
+
+This port targets the immutable React Three Fiber release `v9.6.1`:
+
+- repository: `https://github.com/pmndrs/react-three-fiber`;
+- tag commit: `2a528745e9aa7c9e6cca41e404b59d45cf0d0cc7`;
+- package: `@react-three/fiber@9.6.1`;
+- exact Three behavior and type oracle: `three@0.172.0` and
+  `@types/three@0.172.0`.
+
+The upstream package accepts `three >=0.156`, but this port initially supports
+only the pinned r172 lane. The broader peer range is gated on a real
+minimum-version validation lane.
+
+## Source boundary
+
+The package adapts the R3F web/core behavior rather than its React renderer
+shell:
+
+- `packages/fiber/src/three-types.ts` informs renderer-local intrinsic and math
+  shorthand types;
+- `packages/fiber/src/core/reconciler.tsx` informs catalogue, reconstruction,
+  ordering, attachment, disposal, and interaction-transfer behavior;
+- `packages/fiber/src/core/utils.tsx` informs Three prop resolution and
+  application;
+- `packages/fiber/src/core/store.ts`, `renderer.tsx`, `loop.ts`, `events.ts`, and
+  `hooks.tsx` inform their corresponding package-owned subsystems;
+- `packages/fiber/src/web/Canvas.tsx` informs the DOM shell while Octane's
+  declared renderer boundary replaces R3F's second React root and context
+  bridge.
+
+React Reconciler, ReactDOM, `scheduler`, `its-fine`, `react-use-measure`,
+`use-sync-external-store`, and `suspend-react` are not runtime dependencies of
+the port. React and R3F are development-only differential oracles.
+
+The case-level export/test crosswalk must classify upstream behavior as
+behavioral, differential, browser-only, type/package evidence, or not
+applicable. It is release evidence, not permission to copy Fiber ownership
+internals into Octane.
+
+Milestone 5 follows the pinned `useLoader` observable contract: constructor
+loaders are singleton instances, cache identity combines the loader and
+normalized input, GLTF-shaped results receive the public graph map, and
+`preload`/`clear` share that same key. Cache eviction does not imply asset
+disposal; disposal follows Octane's declarative host ownership instead.
+
+Milestone 6 follows the pinned `createPortal` contract: the supplied
+`Object3D` is a borrowed physical target, the portal store has an immediate
+`previousRoot` plus local scene/raycaster/pointer/event state, and pointer
+events bubble through physical Three ancestry. Octane's universal portal range
+retains logical context, error, effect, and scheduling ownership without
+embedding React Reconciler or representing the target as a fake host child.
+
+## License provenance
+
+React Three Fiber is MIT-licensed, Copyright 2019–2025 Poimandres. Adapted
+algorithms and types retain that notice in [`LICENSE`](./LICENSE). Three is a
+peer dependency under its own MIT license; no Three source is vendored here.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@octanejs/three",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "React Three Fiber-compatible web bindings for Octane's universal renderer.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/three"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "UPSTREAM.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core/index.ts",
+    "./renderer": "./src/renderer.ts",
+    "./config": "./src/config.ts",
+    "./testing": "./src/testing.ts",
+    "./intrinsics": "./src/intrinsics.ts",
+    "./intrinsics/jsx-runtime": "./src/intrinsics.ts"
+  },
+  "dependencies": {
+    "@types/three": "0.172.0",
+    "zustand": "^5.0.0"
+  },
+  "peerDependencies": {
+    "three": ">=0.172.0 <0.173.0",
+    "octane": "0.1.7"
+  },
+  "devDependencies": {
+    "@react-three/fiber": "9.6.1",
+    "@rsbuild/core": "^2.1.5",
+    "@rspack/core": "^2.1.3",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "playwright": "^1.61.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "three": "0.172.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9",
+    "@octanejs/rsbuild-plugin": "0.1.2",
+    "@octanejs/rspack-plugin": "0.1.2",
+    "octane": "0.1.7",
+    "@octanejs/vite-plugin": "0.1.7"
+  },
+  "scripts": {
+    "test": "pnpm upstream:check && vitest run --root ../.. --project three",
+    "upstream:check": "node scripts/check-upstream-crosswalk.mjs"
+  }
+}

package/src/config.ts

@@ -0,0 +1,50 @@
+/**
+ * Serializable compiler metadata for Three-rendered TSRX modules.
+ *
+ * This module intentionally imports neither Three nor an Octane runtime. Vite,
+ * Rspack, Rsbuild, and language tooling can load the same data without creating
+ * renderer state or evaluating browser-only code.
+ */
+export const THREE_RENDERER_ID = 'three';
+
+export const threeRenderer = {
+	module: '@octanejs/three/renderer',
+	target: 'universal',
+	server: 'client-only',
+	intrinsics: '@octanejs/three/intrinsics',
+	text: 'ignore',
+	capabilities: ['local-host-callback', 'visibility', 'portal'],
+} as const;
+
+export const threeRendererRegistry = {
+	[THREE_RENDERER_ID]: threeRenderer,
+} as const;
+
+export const threeRendererRules = [
+	{
+		include: '**/*.three.tsrx',
+		renderer: THREE_RENDERER_ID,
+	},
+] as const;
+
+export const threeRendererBoundaries = {
+	'@octanejs/three': {
+		Canvas: {
+			ownerRenderer: 'dom',
+			childRenderer: THREE_RENDERER_ID,
+			prop: 'children',
+			server: 'omit-child',
+		},
+	},
+} as const;
+
+export const threeRenderers = {
+	registry: threeRendererRegistry,
+	rules: threeRendererRules,
+	boundaries: threeRendererBoundaries,
+} as const;
+
+/** Short compatibility name for app config files. */
+export const renderers = threeRenderers;
+
+export default threeRenderers;

package/src/core/attach.ts

@@ -0,0 +1,117 @@
+/**
+ * Three attachment path handling.
+ *
+ * Adapted from React Three Fiber v9.6.1's string attachment and automatic
+ * geometry/material behavior:
+ * https://github.com/pmndrs/react-three-fiber/blob/2a528745e9aa7c9e6cca41e404b59d45cf0d0cc7/packages/fiber/src/core/utils.tsx#L286-L319
+ * https://github.com/pmndrs/react-three-fiber/blob/2a528745e9aa7c9e6cca41e404b59d45cf0d0cc7/packages/fiber/src/core/utils.tsx#L525-L529
+ *
+ * Function attachments use Octane's post-accept local-callback channel, so
+ * this module intentionally owns string and automatic attachments only.
+ */
+import { inspectAppliedThreePropsPath, resolveProperty } from './props.js';
+
+const ARRAY_INDEX = /-\d+$/;
+
+export type EffectiveAttachment = string | null | undefined;
+
+export interface AttachmentState<Parent extends object = object, Child = unknown> {
+	readonly kind: 'string';
+	readonly parent: Parent;
+	readonly child: Child;
+	readonly path: string;
+	readonly root: any;
+	readonly key: string;
+	readonly previous: unknown;
+	active: boolean;
+}
+
+function isPropertyRoot(value: unknown): value is Record<string, any> {
+	return value !== null && (typeof value === 'object' || typeof value === 'function');
+}
+
+function requirePropertyRoot(value: unknown, path: string): asserts value is Record<string, any> {
+	if (!isPropertyRoot(value)) {
+		throw new Error(
+			`@octanejs/three: Cannot attach to ${JSON.stringify(path)} because its parent is not an object.`,
+		);
+	}
+}
+
+/**
+ * Return the authored attachment, or R3F's automatic geometry/material target.
+ * An explicit null suppresses automatic attachment.
+ */
+export function getEffectiveAttachment(
+	object: unknown,
+	authored: EffectiveAttachment = undefined,
+): EffectiveAttachment {
+	if (authored !== undefined) return authored;
+	if ((object as { isBufferGeometry?: boolean } | null)?.isBufferGeometry === true) {
+		return 'geometry';
+	}
+	if ((object as { isMaterial?: boolean } | null)?.isMaterial === true) return 'material';
+	return undefined;
+}
+
+/** Validate a final string attachment target without mutating its parent. */
+export function validateStringAttachment(
+	parent: object,
+	path: string,
+	overrides: Readonly<Record<string, unknown>> = {},
+): void {
+	if (path.length === 0) throw new TypeError('@octanejs/three: attach must not be empty.');
+
+	// Indexed attachments first replace the target property with an array when
+	// necessary, so only the array property's parent must already be object-like.
+	const targetPath = ARRAY_INDEX.test(path) ? path.replace(ARRAY_INDEX, '') : path;
+	const status = inspectAppliedThreePropsPath(parent, targetPath, overrides);
+	if (status === 'valid') return;
+	const reason =
+		status === 'uncertain'
+			? 'a custom setter makes its final parent shape uncertain'
+			: 'its parent is not an object';
+	throw new Error(`@octanejs/three: Cannot attach to ${JSON.stringify(path)} because ${reason}.`);
+}
+
+/** Attach a child at a direct or dash-pierced Three property path. */
+export function attachString<Parent extends object, Child>(
+	parent: Parent,
+	child: Child,
+	path: string,
+): AttachmentState<Parent, Child> {
+	if (path.length === 0) throw new TypeError('@octanejs/three: attach must not be empty.');
+
+	// R3F's `material-0` convention creates the target array when necessary.
+	if (ARRAY_INDEX.test(path)) {
+		const arrayPath = path.replace(ARRAY_INDEX, '');
+		const arrayTarget = resolveProperty(parent, arrayPath);
+		requirePropertyRoot(arrayTarget.root, arrayPath);
+		if (!Array.isArray(arrayTarget.root[arrayTarget.key])) {
+			arrayTarget.root[arrayTarget.key] = [];
+		}
+	}
+
+	const target = resolveProperty(parent, path);
+	requirePropertyRoot(target.root, path);
+	const previous = target.root[target.key];
+	target.root[target.key] = child;
+	return {
+		kind: 'string',
+		parent,
+		child,
+		path,
+		root: target.root,
+		key: target.key,
+		previous,
+		active: true,
+	};
+}
+
+/** Restore the property value captured by `attachString`, exactly once. */
+export function detachAttachment(state: AttachmentState): void {
+	if (!state.active) return;
+	state.active = false;
+	if (state.previous === undefined) delete state.root[state.key];
+	else state.root[state.key] = state.previous;
+}