@octanejs/valtio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,36 @@
+# @octanejs/valtio
+
+[Valtio](https://github.com/pmndrs/valtio) for the
+[Octane](https://github.com/octanejs/octane) UI framework.
+
+The package reuses Valtio's framework-independent `valtio/vanilla` core and
+reimplements only `useSnapshot` with Octane hooks. Existing Valtio components
+can usually migrate by changing the import:
+
+```tsx
+import { proxy, useSnapshot } from '@octanejs/valtio';
+
+const state = proxy({ count: 0 });
+
+function Counter() @{
+  const snap = useSnapshot(state);
+  <button onClick={() => state.count++}>{snap.count as string}</button>
+}
+```
+
+## Entry points
+
+| import | what you get |
+| --- | --- |
+| `@octanejs/valtio` | Valtio's vanilla API plus the Octane-bound `useSnapshot` |
+| `@octanejs/valtio/react` | the Octane-bound `useSnapshot` |
+| `@octanejs/valtio/react/utils` | `useProxy`, for one proxy reference in renders and callbacks |
+| `@octanejs/valtio/vanilla` | `proxy`, `snapshot`, `subscribe`, `ref`, and vanilla types |
+| `@octanejs/valtio/vanilla/utils` | `subscribeKey`, `watch`, `devtools`, proxy collections, and other vanilla utilities |
+
+`useSnapshot` retains Valtio's property-access tracking through `proxy-compare`.
+Read from the returned snapshot and mutate the source proxy. The optional
+`{ sync: true }` subscription mode is supported.
+
+Current scope and verification status are tracked in
+[`status.json`](./status.json).

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@octanejs/valtio",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "Valtio bindings for the Octane renderer, built on valtio/vanilla with an Octane-native useSnapshot hook.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/valtio"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./react": "./src/react.ts",
+    "./react/utils": "./src/react/utils.ts",
+    "./vanilla": "./src/vanilla.ts",
+    "./vanilla/utils": "./src/vanilla/utils.ts"
+  },
+  "dependencies": {
+    "proxy-compare": "^3.0.1",
+    "valtio": "^2.3.2"
+  },
+  "peerDependencies": {
+    "octane": "0.1.17"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "octane": "0.1.17"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project valtio"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from 'valtio/vanilla';
+export { useSnapshot } from './react';
+export type { UseSnapshotOptions } from './react';

package/src/internal.ts

@@ -0,0 +1,26 @@
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) {
+			bare = Symbol.for(`@octanejs/valtio:${tag}`);
+			bareTagCache.set(tag, bare);
+		}
+		return bare;
+	}
+
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) {
+		byTag = new Map();
+		subSlotCache.set(slot, byTag);
+	}
+
+	let child = byTag.get(tag);
+	if (child === undefined) {
+		child = Symbol.for(`${slot.description ?? ''}:${tag}`);
+		byTag.set(tag, child);
+	}
+	return child;
+}

package/src/react/utils.ts

@@ -0,0 +1,36 @@
+import { useLayoutEffect } from 'octane';
+import { subSlot } from '../internal';
+import { useSnapshot } from '../react';
+import type { UseSnapshotOptions } from '../react';
+
+const DUMMY_SYMBOL = Symbol();
+
+export function useProxy<T extends object>(
+	proxyObject: T,
+	...rest: [options?: UseSnapshotOptions, slot?: symbol]
+): T {
+	const tail = rest[rest.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	const options = (typeof rest[0] === 'object' ? rest[0] : undefined) as
+		UseSnapshotOptions | undefined;
+	const currentSnapshot = useSnapshot(proxyObject, options, subSlot(slot, 'snapshot')) as T;
+
+	// Register an empty access so a component that reads only in callbacks does
+	// not subscribe to every property.
+	currentSnapshot[DUMMY_SYMBOL as keyof T];
+
+	let isRendering = true;
+	useLayoutEffect(
+		() => {
+			isRendering = false;
+		},
+		null,
+		subSlot(slot, 'render-effect'),
+	);
+
+	return new Proxy(proxyObject, {
+		get(target, property) {
+			return isRendering ? currentSnapshot[property as keyof T] : target[property as keyof T];
+		},
+	});
+}

package/src/react.ts

@@ -0,0 +1,75 @@
+import { useCallback, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from 'octane';
+import { createProxy as createProxyToCompare, isChanged } from 'proxy-compare';
+import { snapshot, subscribe } from 'valtio/vanilla';
+import type { Snapshot } from 'valtio/vanilla';
+import { subSlot } from './internal';
+
+export type UseSnapshotOptions = {
+	sync?: boolean;
+};
+
+const targetCache = new WeakMap<object, unknown>();
+
+export function useSnapshot<T extends object>(
+	proxyObject: T,
+	...rest: [options?: UseSnapshotOptions, slot?: symbol]
+): Snapshot<T> {
+	const tail = rest[rest.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	const options = (typeof rest[0] === 'object' ? rest[0] : undefined) as
+		UseSnapshotOptions | undefined;
+	const notifyInSync = options?.sync;
+
+	const affected = useMemo(
+		() => new WeakMap<object, unknown>(),
+		[proxyObject],
+		subSlot(slot, 'affected'),
+	);
+	const lastSnapshot = useRef<Snapshot<T> | undefined>(undefined, subSlot(slot, 'last-snapshot'));
+	let inRender = true;
+
+	const currSnapshot = useSyncExternalStore(
+		useCallback(
+			(callback) => {
+				const unsubscribe = subscribe(proxyObject, callback, notifyInSync);
+				callback();
+				return unsubscribe;
+			},
+			[proxyObject, notifyInSync],
+			subSlot(slot, 'subscribe'),
+		),
+		() => {
+			const nextSnapshot = snapshot(proxyObject);
+			try {
+				if (
+					!inRender &&
+					lastSnapshot.current &&
+					!isChanged(lastSnapshot.current, nextSnapshot, affected, new WeakMap())
+				) {
+					return lastSnapshot.current;
+				}
+			} catch {
+				// Accessed promises and other throwing values must not break snapshots.
+			}
+			return nextSnapshot;
+		},
+		() => snapshot(proxyObject),
+		subSlot(slot, 'external-store'),
+	);
+
+	inRender = false;
+	useLayoutEffect(
+		() => {
+			lastSnapshot.current = currSnapshot;
+		},
+		null,
+		subSlot(slot, 'last-snapshot-effect'),
+	);
+
+	const proxyCache = useMemo(
+		() => new WeakMap<object, unknown>(),
+		[],
+		subSlot(slot, 'proxy-cache'),
+	);
+	return createProxyToCompare(currSnapshot, affected, proxyCache, targetCache) as Snapshot<T>;
+}

package/src/vanilla/utils.ts

@@ -0,0 +1 @@
+export * from 'valtio/vanilla/utils';

package/src/vanilla.ts

@@ -0,0 +1 @@
+export * from 'valtio/vanilla';