fiber-tunnel 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astralarium
+
+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

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# FiberTunnel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React tunnel that renders content in fiber-tree order.
+
+[Docs](https://astralarium.github.io/fiber-tunnel/)
+| [Github](https://github.com/astralarium/fiber-tunnel)
+| [NPM](https://www.npmjs.com/package/@astralarium/fiber-tunnel)
+
+## Installation
+
+```bash
+npm i @astralarium/fiber-tunnel
+```
+
+Requires React 19.2 or later.
+
+## Usage
+
+```tsx
+import { fiberTunnel } from "@astralarium/fiber-tunnel";
+import { Canvas } from "@react-three/fiber";
+
+const overlay = fiberTunnel();
+
+function Card({ name }: { name: string }) {
+  return (
+    <mesh>
+      <overlay.In>
+        <li>{name}</li>
+      </overlay.In>
+    </mesh>
+  );
+}
+
+function App() {
+  return (
+    <>
+      <ul>
+        <overlay.Out />
+      </ul>
+      <Canvas>
+        <Card name="Ace" />
+        <Card name="King" />
+      </Canvas>
+    </>
+  );
+}
+```
+
+`fiberTunnel()` returns `{ In, Out, refresh }`.
+Create tunnels at module scope or in a component with `useState`.
+
+## Behavior
+
+- `Out` renders content in React tree order.
+- Wrap each nested React root's host in `<FiberAnchor>`,
+  e.g. `<FiberAnchor><Canvas>…</Canvas></FiberAnchor>`.
+  Unanchored roots have no defined order.
+- Updating an `In` updates content in place, preserving state and DOM.
+- Mount only one `Out` per tunnel.
+- Call `refresh()` after reordering `In`s or anchors.
+- Content appears one commit after `In` mounts.
+  `Out` mounted together with `In`s paints empty once.
+  SSR renders empty `Out`s until hydration.
+
+Inspired by [tunnel-rat](https://github.com/pmndrs/tunnel-rat).

package/dist/fiber-tunnel.js

@@ -0,0 +1,179 @@
+"use client";
+import { c as e } from "react/compiler-runtime";
+import t, { Component as n, Fragment as r, createContext as i, useLayoutEffect as a, useRef as o, useSyncExternalStore as s } from "react";
+import { Fragment as c, jsx as l } from "react/jsx-runtime";
+//#region src/fiber-anchor-context.ts
+var u = i(null);
+//#endregion
+//#region src/util.ts
+function d(e) {
+	return e._reactInternals;
+}
+function f(e) {
+	let t = e;
+	for (; t.return;) t = t.return;
+	let n = t.stateNode;
+	return n?.current ? n : null;
+}
+function p(e, t, n) {
+	let r = e.current;
+	if (!r) return;
+	let i = 0, a = 0, o = [r];
+	for (; o.length > 0;) {
+		let e = o.pop();
+		if ((t.has(e) || e.alternate != null && t.has(e.alternate)) && (n.set(e, a), e.alternate && n.set(e.alternate, a), ++i >= t.size)) return;
+		a++, e.sibling && o.push(e.sibling), e.child && o.push(e.child);
+	}
+}
+function m(e, t) {
+	return e === t || e.alternate === t;
+}
+function h(e) {
+	let t = 0;
+	for (;;) {
+		let n = e[0]?.[t];
+		if (!n || e.some((e) => !e[t] || !m(e[t].fiber, n.fiber))) return t;
+		t++;
+	}
+}
+function g(e, t) {
+	for (let n = 0; n < e.length && n < t.length; n++) if (e[n] !== t[n]) return e[n] - t[n];
+	return 0;
+}
+function _(e) {
+	if (e.length <= 1) return e.map((e) => e.item);
+	let t = h(e.map((e) => e.path)), n = e.map((e) => e.path.slice(t)), r = /* @__PURE__ */ new Map();
+	for (let e of n) for (let { root: t, fiber: n } of e) {
+		let e = r.get(t);
+		e || r.set(t, e = /* @__PURE__ */ new Set()), e.add(n);
+	}
+	let i = /* @__PURE__ */ new Map();
+	for (let [e, t] of r) p(e, t, i);
+	return e.map((e, t) => ({
+		...e,
+		key: n[t].length ? n[t].map((e) => i.get(e.fiber) ?? Infinity) : [Infinity]
+	})).sort((e, t) => g(e.key, t.key) || e.order - t.order).map((e) => e.item);
+}
+function v(e) {
+	return _(e.map((e, t) => {
+		let n = e.fiber, r = n && f(n);
+		return {
+			item: e,
+			path: n && r ? [{
+				fiber: n,
+				root: r
+			}] : [],
+			order: t
+		};
+	}));
+}
+//#endregion
+//#region src/fiber-anchor.tsx
+var y = class extends n {
+	static contextType = u;
+	value = null;
+	render() {
+		return (!this.value || this.value.parent !== this.context) && (this.value = {
+			fiber: d(this),
+			parent: this.context
+		}), /* @__PURE__ */ l(u, {
+			value: this.value,
+			children: this.props.children
+		});
+	}
+};
+function b(t) {
+	let n = e(2), r;
+	return n[0] === t ? r = n[1] : (r = /* @__PURE__ */ l(y, { ...t }), n[0] = t, n[1] = r), r;
+}
+//#endregion
+//#region src/env.ts
+var x = process.env.NODE_ENV !== "production", S = [], C = () => S, w = "Multiple tunnel Outs mounted; each renders a copy.", T = "Tunnel Ins span React roots in undefined order. Wrap nested React roots in FiberAnchor; nested roots must bridge context.";
+function E() {
+	let e = /* @__PURE__ */ new Map(), i = null, p = /* @__PURE__ */ new Set(), h = 0, g = 0, v = !1;
+	function y(e) {
+		return p.add(e), () => void p.delete(e);
+	}
+	function b() {
+		return i ??= [...e.values()];
+	}
+	function S(e, t) {
+		let n = [], r = f(e);
+		r && n.push({
+			fiber: e,
+			root: r
+		});
+		for (let e = t; e; e = e.parent) {
+			let t = f(e.fiber);
+			t && t !== r && (n.unshift({
+				fiber: e.fiber,
+				root: t
+			}), r = t);
+		}
+		return n;
+	}
+	function E() {
+		i = null;
+		for (let e of p) e();
+	}
+	function D(t, n, r, i) {
+		let a = S(r, i);
+		x && !v && !e.has(t) && O(a), e.set(t, {
+			id: t,
+			path: a,
+			children: n
+		}), E();
+	}
+	function O(n) {
+		for (let r of e.values()) for (let e = 0; e < n.length && e < r.path.length; e++) if (!m(n[e].fiber, r.path[e].fiber)) {
+			if (n[e].root === r.path[e].root) break;
+			v = !0, console.warn(T + (t.captureOwnerStack?.() ?? ""));
+			return;
+		}
+	}
+	function k(t) {
+		e.delete(t), E();
+	}
+	function A() {
+		E();
+	}
+	class j extends n {
+		static contextType = u;
+		id = h++;
+		anchor = null;
+		register() {
+			this.anchor = this.context, D(this.id, this.props.children, d(this), this.anchor);
+		}
+		componentDidMount() {
+			this.register();
+		}
+		componentDidUpdate(e) {
+			(e.children !== this.props.children || this.anchor !== this.context) && this.register();
+		}
+		componentWillUnmount() {
+			k(this.id);
+		}
+		render() {
+			return null;
+		}
+	}
+	function M() {
+		let e = s(y, b, C), n = o(!1);
+		a(() => {
+			if (x) return g++, g > 1 && !n.current && (n.current = !0, console.error(w + (t.captureOwnerStack?.() ?? ""))), () => void g--;
+		}, []);
+		let i = _(e.map((e) => ({
+			item: e,
+			path: e.path,
+			order: e.id
+		})));
+		return /* @__PURE__ */ l(c, { children: i.map((e) => /* @__PURE__ */ l(r, { children: e.children }, e.id)) });
+	}
+	return {
+		In: j,
+		Out: M,
+		refresh: A
+	};
+}
+//#endregion
+export { b as FiberAnchor, E as fiberTunnel, v as sortByFiberOrder };

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import { ComponentType } from 'react';
+import { JSX } from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Places a nested React root's tunnel content at this point in tree order.
+ * One nested root per anchor; it must bridge context (r3f's `<Canvas>`
+ * does; otherwise use its-fine's `useContextBridge`).
+ *
+ * Moving the anchor needs the tunnel's `refresh()`. Hiding it (Suspense,
+ * Activity) keeps the root's content in the Out.
+ */
+export declare function FiberAnchor(props: FiberAnchorProps): JSX.Element;
+
+/** Props of {@link FiberAnchor}. */
+export declare interface FiberAnchorProps {
+    /** Host of a nested React root, e.g. an r3f `<Canvas>`. */
+    children: ReactNode;
+}
+
+/** A tunnel created by {@link fiberTunnel}. */
+export declare interface FiberTunnel {
+    /** Sends its children to the Out, one commit after mounting. */
+    In: ComponentType<FiberTunnelInProps>;
+    /** Renders the content. Mount one per tunnel: each Out renders a copy. */
+    Out: () => ReactNode;
+    /** Re-reads order from the fiber tree. Call after reordering Ins or
+     * FiberAnchors. */
+    refresh: () => void;
+}
+
+/** Creates a tunnel: content from many Ins renders at one Out, in tree order. */
+export declare function fiberTunnel(): FiberTunnel;
+
+/** Props of {@link FiberTunnel.In}. */
+export declare interface FiberTunnelInProps {
+    /** Rendered at the Out. */
+    children: ReactNode;
+}
+
+/**
+ * Sorts items by React tree position. Items must share a React root.
+ * Unresolvable items keep input order, after the sorted ones.
+ */
+export declare function sortByFiberOrder<T extends {
+    /** The item's React fiber, e.g. from its-fine's `useFiber`. */
+    fiber?: object | null;
+}>(items: readonly T[]): T[];
+
+export { }

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "fiber-tunnel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "description": "React tunnel that renders content in fiber-tree order",
+  "license": "MIT",
+  "author": "Mara Kim <mara@astralarium.net>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astralarium/fiber-tunnel.git"
+  },
+  "keywords": [
+    "react",
+    "tunnel",
+    "portal",
+    "fiber",
+    "react-three-fiber",
+    "pixi",
+    "tunnel-rat"
+  ],
+  "bugs": {
+    "url": "https://github.com/astralarium/fiber-tunnel/issues"
+  },
+  "homepage": "https://astralarium.github.io/fiber-tunnel",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "main": "./dist/fiber-tunnel.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/fiber-tunnel.js",
+      "default": "./dist/fiber-tunnel.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "@eslint/js": "^9.39.2",
+    "@microsoft/api-extractor": "^7.59.4",
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^25.0.9",
+    "@types/react": "^19.2.9",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.26",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "globals": "^17.0.0",
+    "its-fine": "^2.0.0",
+    "jsdom": "^29.0.0",
+    "prettier": "^3.8.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typedoc": "^0.28.16",
+    "typedoc-rhineai-theme": "^1.2.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.53.1",
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b && eslint . && vite build && pnpm pack --out pack/%s-%v.tgz",
+    "build:docs": "typedoc",
+    "lint": "eslint .",
+    "check-types": "tsc -b",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }