@octanejs/livestore 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Overengineering Studio
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,45 @@
+# @octanejs/livestore
+
+Octane bindings for [LiveStore](https://livestore.dev/), ported from
+`@livestore/react@0.4.0` at commit
+`c80acb39066b9472da426a35c81969df4919ae2d`.
+
+The package reuses LiveStore's published framework-neutral store, schema,
+query, registry, and framework-toolkit packages. It replaces only the React
+context, Suspense, hook, and component layer with Octane equivalents.
+The exact upstream source, tests, snapshots, package metadata, and license are
+vendored byte-for-byte under `upstream/`; [UPSTREAM.md](./UPSTREAM.md) records
+the export and test crosswalk.
+
+```sh
+pnpm add @octanejs/livestore @livestore/adapter-web
+```
+
+```ts
+import { StoreRegistry, storeOptions, useStore } from '@octanejs/livestore';
+```
+
+The stable root surface includes `StoreRegistryProvider`, `useStoreRegistry`,
+`useStore`, `useQuery`, `useQueryRef`, `useClientDocument`, and
+`useSyncStatus`. `LiveList` is available from both the root and
+`@octanejs/livestore/experimental`, matching the pinned upstream release.
+
+`ReactApi` and `withReactApi` retain their upstream names for source
+compatibility, but attach Octane hooks and do not depend on React.
+
+## Compatibility
+
+- LiveStore dependencies are pinned to the coherent 0.4.0 release closure,
+  which uses Effect 3.
+- Query errors are labeled `@livestore/octane:useQuery`. The pinned
+  framework-toolkit still uses an internal refresh-reason tag named `react`;
+  this diagnostic-only upstream detail is intentionally not forked.
+- React Strict Mode double invocation is not emulated.
+- The upstream short-`unusedCacheTime` retain timing limitation remains:
+  `useStore` retains in a passive effect after a successful render.
+
+LiveStore is Apache-2.0 licensed. This adaptation preserves that license and
+documents Octane-specific changes in this repository.
+
+Maintainers can verify the pinned evidence with
+`pnpm --dir packages/livestore upstream:verify`.

package/UPSTREAM.md

@@ -0,0 +1,81 @@
+# LiveStore React upstream contract
+
+## Pin and source boundary
+
+| Field | Value |
+|---|---|
+| Package | `@livestore/react` |
+| Version | `0.4.0` |
+| Canonical tag commit | `c80acb39066b9472da426a35c81969df4919ae2d` |
+| Supported upstream range | exactly `0.4.0` |
+| React oracle | `19.2.3` with `@types/react@19.2.7` |
+| License | Apache-2.0 |
+
+The npm package publishes `src/` and built `dist/`, but its repository contains
+the authoritative React source, tests, snapshots, configuration, package
+metadata, and license. The byte-exact `packages/@livestore/react` directory from
+the canonical tag commit is vendored under `upstream/` and locked file-by-file
+by `upstream/SHA256SUMS`. It is excluded from the published package by the
+explicit `files` allowlist.
+
+The port reuses LiveStore's released framework-neutral packages unchanged. Only
+the React-facing binding under the pinned directory is adapted. `src/` mirrors
+the upstream module layout; `.tsx` components become `.tsrx`, while hook modules
+retain their upstream paths.
+
+Run `pnpm --dir packages/livestore upstream:verify` to verify every vendored
+byte and the recorded source/test inventory. The pristine React-parity lane
+runs that same verifier before copying or executing the upstream suite.
+
+## Runtime export crosswalk
+
+| Upstream export | Octane disposition | Evidence |
+|---|---|---|
+| `Dispatch`, `SetStateAction`, `SetStateActionPartial`, `StateSetters` | Re-exported from the unchanged framework toolkit | `typetests/public-api.test-d.ts` |
+| `captureStackInfo` | Re-exported from the unchanged framework toolkit | `tests/package-contract.test.ts` |
+| `StoreRegistry`, `storeOptions` | Re-exported from the unchanged LiveStore core | `tests/package-contract.test.ts` |
+| `StoreRegistryContext` | Ported to Octane context at `src/StoreRegistryContext.tsrx` | `tests/conformance/registry-context.test.ts` |
+| `StoreRegistryProvider`, `StoreRegistryProviderProps` | Ported to Octane TSRX at the mirrored module path | `tests/lifecycle.test.ts`, `typetests/public-api.test-d.ts` |
+| `useStoreRegistry` | Ported to Octane context with the upstream override behavior | `tests/conformance/registry-context.test.ts` |
+| `useStore` | Ported to Octane Suspense, retention, and slot ownership | `tests/lifecycle.test.ts` |
+| `ReactApi` | Historical upstream public name retained; members use Octane hooks | `typetests/public-api.test-d.ts` |
+| `withReactApi` | Historical upstream public name retained and augments the same Store object | `tests/lifecycle.test.ts` |
+| `useQuery`, `useQueryRef` | Ported over LiveStore's unchanged reactive-query core | `tests/query.test.ts` |
+| `UseClientDocumentResult`, `useClientDocument` | Ported over the unchanged client-document core | `tests/document-sync.test.ts` |
+| `useSyncStatus` | Ported to Octane's external-store subscription boundary | `tests/conformance/sync-status.test.ts`, `tests/ssr/server.test.ts` |
+| `LiveList`, `LiveListProps` | Ported to keyed Octane `@for`; exported from root and `./experimental` | `tests/conformance/live-list.test.ts`, `typetests/public-api.test-d.ts` |
+
+`useRcResource`, `useStateRefWithReactiveInput`, and
+`__resetUseRcResourceCache` are upstream-private modules. They remain internal
+implementation/test support and are not added to the public namespace.
+
+## Test-suite disposition
+
+The pinned React binding contains four runtime test files, one shared fixture,
+and two snapshots. The source artifacts are all present under `upstream/`.
+
+Parity-owned adapted cases live only in `tests/document-sync.test.ts`,
+`tests/lifecycle.test.ts`, and `tests/query.test.ts`. Octane-only unpaired
+cases live under `tests/conformance/` and are classified outside React-parity
+ownership in `audit/test-classifications.json`.
+
+| Upstream artifact | Disposition |
+|---|---|
+| `src/useRcResource.test.tsx` | Adapted by `tests/lifecycle.test.ts`; stable reuse, last-consumer cleanup, key replacement, scope replacement, and rapid replacement are covered. React StrictMode double-invoke is not applicable because Octane has no StrictMode double-invoke. |
+| `src/useStore.test.tsx` | Adapted by `tests/lifecycle.test.ts`; shared registry promise identity belongs to unchanged `StoreRegistry`, while Suspense, stable re-render, error propagation, store switching, retention, and `useActionState` transition commit (`does not block useActionState transitions from committing`, upstream L176) are binding contracts. The upstream skipped `unusedCacheTime=0` case remains an upstream core issue, not a parity claim. Registry context override/missing-provider coverage is Octane-only in `tests/conformance/registry-context.test.ts`. |
+| `src/useQuery.test.tsx` | Adapted by `tests/query.test.ts`; synchronous reads, commits, query identity changes, signals/query builders, and per-store query derivation are the observable contracts. React-window-specific lifecycle stress is React-only; keyed `LiveList` supplies Octane's equivalent list integration evidence in `tests/conformance/live-list.test.ts` (outside parity ownership). Query-resource last-consumer cleanup is Octane-only in `tests/conformance/query-resource.test.ts`. Internal reactivity-graph snapshots are deliberately not copied because repository testing guidance forbids pinning private graph shape. |
+| `src/useClientDocument.test.tsx` | Adapted by `tests/document-sync.test.ts`; ID changes, value/functional/external updates, query chaining (`should work for a useClientDocument query chained with a useTemporary query`, upstream L195), and KV overwrite semantics (`kv client document overwrites value (Schema.Any, no partial merge)`, upstream L238) are binding contracts. Sync-status subscription/hydration is Octane-only in `tests/conformance/sync-status.test.ts`. OpenTelemetry span snapshots exercise unchanged LiveStore instrumentation internals and are not re-snapshotted by the Octane binding. |
+| `src/__tests__/fixture.tsx` | Adapted through the released `@livestore/framework-toolkit/testing` TodoMVC fixture used by the Octane tests. |
+| `src/__snapshots__/useQuery.test.tsx.snap` | Not ported: it pins framework-neutral private reactivity-graph representation, outside the binding observation boundary. |
+| `src/__snapshots__/useClientDocument.test.tsx.snap` | Not ported: it pins framework-neutral OpenTelemetry and stack-frame serialization internals, outside the binding observation boundary. |
+
+## Intentional divergences
+
+- Octane has no StrictMode double-invocation, so the React suite's strict/non-strict
+  matrix collapses to one lifecycle lane.
+- Upstream's framework toolkit still names the augmentation `ReactApi` and
+  `withReactApi`. Those names are preserved for source compatibility even though
+  their implementation is Octane-native.
+- Public query instrumentation uses the label `octane`. The framework-neutral
+  toolkit's internal refresh tag remains `react` because that released core API
+  is reused unchanged.

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@octanejs/livestore",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "LiveStore bindings for Octane, ported from @livestore/react over LiveStore's framework-neutral core.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/livestore"
+  },
+  "main": "src/mod.ts",
+  "module": "src/mod.ts",
+  "types": "src/mod.ts",
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/mod.ts",
+    "./experimental": "./src/experimental/mod.ts"
+  },
+  "dependencies": {
+    "@livestore/common": "0.4.0",
+    "@livestore/framework-toolkit": "0.4.0",
+    "@livestore/livestore": "0.4.0",
+    "@livestore/utils": "0.4.0",
+    "@opentelemetry/api": "1.9.0"
+  },
+  "peerDependencies": {
+    "octane": "0.1.31"
+  },
+  "devDependencies": {
+    "@livestore/adapter-web": "0.4.0",
+    "@livestore/utils-dev": "0.4.0",
+    "@opentelemetry/sdk-trace-base": "2.2.0",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/react": "16.3.1",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "@types/react-window": "1.8.8",
+    "@tsrx/react": "^0.2.56",
+    "esbuild": "^0.28.1",
+    "jsdom": "26.1.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-window": "1.8.11",
+    "vite": "7.3.1",
+    "vitest": "^4.1.10",
+    "octane": "0.1.31"
+  },
+  "scripts": {
+    "test": "vitest run --config vitest.config.ts && vitest run --config vitest.ssr.config.ts",
+    "test:upstream": "node scripts/run-pristine-upstream.mjs",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsrx-tsc --noEmit -p typetests/tsconfig.json",
+    "upstream:verify": "node scripts/verify-upstream.mjs"
+  }
+}

package/src/StoreRegistryContext.tsrx

@@ -0,0 +1,26 @@
+import { createContext, useContext } from 'octane';
+import type { ComponentBody, OctaneNode } from 'octane';
+import type { StoreRegistry } from '@livestore/livestore';
+
+export const StoreRegistryContext = createContext<StoreRegistry | undefined>(undefined);
+
+export type StoreRegistryProviderProps = {
+	storeRegistry: StoreRegistry;
+	children?: OctaneNode;
+};
+
+export const StoreRegistryProvider: ComponentBody<StoreRegistryProviderProps> = ({
+	storeRegistry,
+	children,
+}) =>
+	<StoreRegistryContext.Provider value={storeRegistry}>{children}</StoreRegistryContext.Provider>;
+
+export const useStoreRegistry = (override?: StoreRegistry): StoreRegistry => {
+	if (override !== undefined && typeof override !== 'symbol') return override;
+
+	const storeRegistry = useContext(StoreRegistryContext);
+	if (storeRegistry == null) {
+		throw new Error('useStoreRegistry() must be used within <StoreRegistryProvider>');
+	}
+	return storeRegistry;
+};

package/src/experimental/components/LiveList.tsrx

@@ -0,0 +1,75 @@
+import type { LiveQueryDef, Store } from '@livestore/livestore';
+import { computed } from '@livestore/livestore';
+import { memo, useEffect, useMemo, useState } from 'octane';
+import type { OctaneNode } from 'octane';
+import { useQuery } from '../../useQuery';
+
+export type LiveListProps<TItem> = {
+	items$: LiveQueryDef<ReadonlyArray<TItem>>;
+	renderItem: (item: TItem, options: { index: number; isInitialListRender: boolean }) => OctaneNode;
+	getKey: (item: TItem, index: number) => string | number;
+	store: Store<any, any>;
+};
+
+type ItemWrapperProps<TItem> = {
+	itemKey: string | number;
+	item$: LiveQueryDef<TItem>;
+	index: number;
+	isInitialListRender: boolean;
+	renderItem: LiveListProps<TItem>['renderItem'];
+	store: Store<any, any>;
+};
+
+export function LiveList<TItem>({ items$, renderItem, getKey, store }: LiveListProps<TItem>) @{
+	const [hasMounted, setHasMounted] = useState(false);
+	useEffect(() => setHasMounted(true), []);
+	const keys = useQuery(computed((get) => get(items$).map(getKey)), { store });
+	const entries = useMemo(
+		() => keys.map(
+			(key, index) => ({
+				key,
+				index,
+				item$: computed((get) => get(items$).find((item) => getKey(item, 0) === key)!, {
+					deps: [key],
+				}) as LiveQueryDef<TItem>,
+			}),
+		),
+		[getKey, items$, keys],
+	);
+
+	<>
+		@for (const entry of entries; key entry.key) {
+			<ItemWrapperMemo
+				itemKey={entry.key}
+				item$={entry.item$}
+				store={store}
+				index={entry.index}
+				isInitialListRender={!hasMounted}
+				renderItem={renderItem}
+			/>
+		}
+	</>
+}
+
+function ItemWrapper<TItem>({
+	item$,
+	index,
+	isInitialListRender,
+	renderItem,
+	store,
+}: ItemWrapperProps<TItem>) @{
+	const item = useQuery(item$, { store });
+	const options = useMemo(() => ({ index, isInitialListRender }), [index, isInitialListRender]);
+	<>
+		{renderItem(item, options)}
+	</>
+}
+
+const ItemWrapperMemo = memo(
+	ItemWrapper,
+	(previous, next) =>
+		previous.itemKey === next.itemKey && previous.renderItem === next.renderItem &&
+			previous.store === next.store &&
+			previous.index === next.index &&
+			previous.isInitialListRender === next.isInitialListRender,
+) as typeof ItemWrapper;

package/src/experimental/mod.ts

@@ -0,0 +1 @@
+export { LiveList, type LiveListProps } from './components/LiveList.tsrx';

package/src/internal.ts

@@ -0,0 +1,38 @@
+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/livestore:${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;
+}
+
+export function splitSlot(
+	args: unknown[],
+	preserveSingleSymbol?: (value: symbol) => boolean,
+): [unknown[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot =
+		typeof tail === 'symbol' && !(args.length === 1 && preserveSingleSymbol?.(tail))
+			? tail
+			: undefined;
+	return [slot === undefined ? args : args.slice(0, -1), slot];
+}

package/src/mod.ts

@@ -0,0 +1,14 @@
+export type {
+	Dispatch,
+	SetStateAction,
+	SetStateActionPartial,
+	StateSetters,
+} from '@livestore/framework-toolkit';
+export { captureStackInfo } from '@livestore/framework-toolkit';
+export { StoreRegistry, storeOptions } from '@livestore/livestore';
+export { LiveList, type LiveListProps } from './experimental/components/LiveList.tsrx';
+export * from './StoreRegistryContext.tsrx';
+export { type UseClientDocumentResult, useClientDocument } from './useClientDocument';
+export { useQuery, useQueryRef } from './useQuery';
+export { type ReactApi, useStore, withReactApi } from './useStore';
+export { useSyncStatus } from './useSyncStatus';

package/src/useClientDocument.ts

@@ -0,0 +1,113 @@
+import type { RowQuery } from '@livestore/common';
+import { SessionIdSymbol } from '@livestore/common';
+import { State } from '@livestore/common/schema';
+import {
+	removeUndefinedValues,
+	type StateSetters,
+	validateTableOptions,
+} from '@livestore/framework-toolkit';
+import type { LiveQuery, LiveQueryDef, Store } from '@livestore/livestore';
+import { queryDb } from '@livestore/livestore';
+import { omitUndefineds, shouldNeverHappen } from '@livestore/utils';
+import { useMemo } from 'octane';
+import { splitSlot, subSlot } from './internal';
+import { useQueryRef } from './useQuery';
+
+export type UseClientDocumentResult<
+	TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny,
+> = [
+	row: TTableDef['Value'],
+	setRow: StateSetters<TTableDef>,
+	id: string,
+	query$: LiveQuery<TTableDef['Value']>,
+];
+
+export function useClientDocument<
+	TTableDef extends State.SQLite.ClientDocumentTableDef.Trait<
+		any,
+		any,
+		any,
+		{ partialSet: boolean; default: any }
+	>,
+>(
+	table: TTableDef,
+	id?: State.SQLite.ClientDocumentTableDef.DefaultIdType<TTableDef> | SessionIdSymbol,
+	options?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+): UseClientDocumentResult<TTableDef>;
+export function useClientDocument<
+	TTableDef extends State.SQLite.ClientDocumentTableDef.Trait<
+		any,
+		any,
+		any,
+		{ partialSet: boolean; default: any }
+	>,
+>(
+	table: TTableDef,
+	id: State.SQLite.ClientDocumentTableDef.DefaultIdType<TTableDef> | string | SessionIdSymbol,
+	options?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+): UseClientDocumentResult<TTableDef>;
+export function useClientDocument<TTableDef extends State.SQLite.ClientDocumentTableDef.Any>(
+	table: TTableDef,
+	idOrOptions:
+		string | SessionIdSymbol | Partial<RowQuery.GetOrCreateOptions<TTableDef>> | undefined,
+	options: Partial<RowQuery.GetOrCreateOptions<TTableDef>> | undefined,
+	storeArg: { store?: Store } | undefined,
+	slot: symbol,
+): UseClientDocumentResult<TTableDef>;
+export function useClientDocument<TTableDef extends State.SQLite.ClientDocumentTableDef.Any>(
+	table: TTableDef,
+	...rest: [
+		idOrOptions?: string | SessionIdSymbol | Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+		options?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+		storeArg?: { store?: Store },
+		slot?: symbol,
+	]
+): UseClientDocumentResult<TTableDef> {
+	const [args, slot] = splitSlot(rest, (value) => value === SessionIdSymbol);
+	const idOrOptions = args[0] as
+		string | SessionIdSymbol | Partial<RowQuery.GetOrCreateOptions<TTableDef>> | undefined;
+	const optionsArgument = args[1] as Partial<RowQuery.GetOrCreateOptions<TTableDef>> | undefined;
+	const storeArg = args[2] as { store?: Store } | undefined;
+	const id =
+		typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol
+			? idOrOptions
+			: table[State.SQLite.ClientDocumentTableDefSymbol].options.default.id;
+	const options =
+		typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol
+			? optionsArgument
+			: idOrOptions;
+	const { default: defaultValues } = options ?? {};
+
+	useMemo(() => validateTableOptions(table), [table], subSlot(slot, 'document:validate'));
+	const tableName = table.sqliteDef.name;
+	const store = storeArg?.store ?? shouldNeverHappen('No store provided to useClientDocument');
+	const idStr: string = id === SessionIdSymbol ? store.sessionId : id;
+	type QueryDef = LiveQueryDef<TTableDef['Value']>;
+	const queryDef: QueryDef = useMemo(
+		() =>
+			queryDb(table.get(id, { default: defaultValues! }), {
+				deps: [idStr, tableName, JSON.stringify(defaultValues)],
+			}),
+		[table, id, defaultValues, idStr],
+		subSlot(slot, 'document:query'),
+	);
+	const queryRef = useQueryRef(
+		queryDef,
+		{
+			otelSpanName: `LiveStore:useClientDocument:${tableName}:${idStr}`,
+			...omitUndefineds({ store: storeArg?.store }),
+		},
+		subSlot(slot, 'document:query-ref'),
+	);
+	const setState = useMemo<StateSetters<TTableDef>>(
+		() => (newValueOrFn: TTableDef['Value']) => {
+			const newValue =
+				typeof newValueOrFn === 'function' ? newValueOrFn(queryRef.valueRef.current) : newValueOrFn;
+			if (queryRef.valueRef.current === newValue) return;
+			store.commit(table.set(removeUndefinedValues(newValue), id));
+		},
+		[id, queryRef.valueRef, store, table],
+		subSlot(slot, 'document:set'),
+	);
+	return [queryRef.valueRef.current, setState, idStr, queryRef.queryRcRef.value];
+}

package/src/useQuery.ts

@@ -0,0 +1,139 @@
+import type * as otel from '@opentelemetry/api';
+import {
+	captureStackInfo,
+	computeRcRefKey,
+	createQueryResource,
+	type NormalizedQueryable,
+	normalizeQueryable,
+	runInitialQuery,
+} from '@livestore/framework-toolkit';
+import type { LiveQuery, Queryable, Store } from '@livestore/livestore';
+import type { LiveQueries } from '@livestore/livestore/internal';
+import { deepEqual, shouldNeverHappen } from '@livestore/utils';
+import { useDebugValue, useEffect, useMemo } from 'octane';
+import { splitSlot, subSlot } from './internal';
+import { useRcResource } from './useRcResource';
+import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput';
+
+type ValueRef<T> = { current: T };
+type QueryOptions = {
+	store?: Store;
+	otelContext?: otel.Context;
+	otelSpanName?: string;
+};
+
+export function useQuery<TQueryable extends Queryable<any>>(
+	queryable: TQueryable,
+	options?: { store?: Store },
+): Queryable.Result<TQueryable>;
+export function useQuery<TQueryable extends Queryable<any>>(
+	queryable: TQueryable,
+	...rest: [options?: { store?: Store }, slot?: symbol]
+): Queryable.Result<TQueryable> {
+	const [args, slot] = splitSlot(rest);
+	return useQueryRef(queryable, args[0] as QueryOptions | undefined, subSlot(slot, 'query:ref'))
+		.valueRef.current;
+}
+
+export function useQueryRef<TQueryable extends Queryable<any>>(
+	queryable: TQueryable,
+	options?: QueryOptions,
+): {
+	valueRef: ValueRef<Queryable.Result<TQueryable>>;
+	queryRcRef: LiveQueries.RcRef<LiveQuery<Queryable.Result<TQueryable>>>;
+};
+export function useQueryRef<TQueryable extends Queryable<any>>(
+	queryable: TQueryable,
+	options: QueryOptions | undefined,
+	slot: symbol,
+): {
+	valueRef: ValueRef<Queryable.Result<TQueryable>>;
+	queryRcRef: LiveQueries.RcRef<LiveQuery<Queryable.Result<TQueryable>>>;
+};
+export function useQueryRef<TQueryable extends Queryable<any>>(
+	queryable: TQueryable,
+	...rest: [options?: QueryOptions, slot?: symbol]
+): {
+	valueRef: ValueRef<Queryable.Result<TQueryable>>;
+	queryRcRef: LiveQueries.RcRef<LiveQuery<Queryable.Result<TQueryable>>>;
+} {
+	const [args, slot] = splitSlot(rest);
+	const options = args[0] as QueryOptions | undefined;
+	const store = options?.store ?? shouldNeverHappen('No store provided to useQuery');
+	type TResult = Queryable.Result<TQueryable>;
+
+	const normalized = useMemo<NormalizedQueryable<TResult>>(
+		() => normalizeQueryable(queryable as Queryable<TResult>),
+		[queryable],
+		subSlot(slot, 'query:normalized'),
+	);
+	const rcRefKey = useMemo(
+		() => computeRcRefKey(store, normalized),
+		[normalized, store],
+		subSlot(slot, 'query:key'),
+	);
+	const stackInfo = useMemo(() => captureStackInfo(), [], subSlot(slot, 'query:stack'));
+
+	const { queryRcRef, span, otelContext } = useRcResource(
+		store,
+		rcRefKey,
+		() =>
+			createQueryResource(store, normalized, stackInfo, {
+				otelSpanName: options?.otelSpanName,
+				otelContext: options?.otelContext,
+			}),
+		() => {},
+		undefined,
+		subSlot(slot, 'query:resource'),
+	);
+	const query$ = queryRcRef.value;
+	useDebugValue(
+		`LiveStore:useQuery:${query$.id}:${query$.label}`,
+		undefined,
+		subSlot(slot, 'query:debug'),
+	);
+
+	const initialResult = useMemo(
+		() => runInitialQuery(query$, otelContext, stackInfo, 'octane'),
+		[otelContext, query$, stackInfo],
+		subSlot(slot, 'query:initial'),
+	);
+	const [valueRef, setValue] = useStateRefWithReactiveInput(
+		initialResult,
+		subSlot(slot, 'query:state'),
+	);
+
+	useEffect(
+		() => {
+			query$.activeSubscriptions.add(stackInfo);
+			span.updateName(options?.otelSpanName ?? `LiveStore:useQuery:${query$.label}`);
+			return store.subscribe(
+				query$,
+				(newValue) => {
+					if (deepEqual(newValue, valueRef.current) === false) setValue(newValue);
+				},
+				{
+					onUnsubsubscribe: () => query$.activeSubscriptions.delete(stackInfo),
+					label: query$.label,
+					otelContext,
+				},
+			);
+		},
+		[stackInfo, query$, setValue, store, valueRef, otelContext, span, options?.otelSpanName],
+		subSlot(slot, 'query:subscribe'),
+	);
+
+	useRcResource(
+		store,
+		rcRefKey,
+		() => ({ queryRcRef, span }),
+		(resource) => {
+			resource.queryRcRef.deref();
+			resource.span.end();
+		},
+		undefined,
+		subSlot(slot, 'query:lifetime'),
+	);
+
+	return { valueRef, queryRcRef };
+}

package/src/useRcResource.ts

@@ -0,0 +1,109 @@
+import { useEffect, useMemo, useRef } from 'octane';
+import { splitSlot, subSlot } from './internal';
+
+type Entry = { _tag: 'active'; rc: number; resource: unknown } | { _tag: 'destroyed' };
+type Bucket = Map<string, Entry>;
+
+let scopedBuckets = new WeakMap<object, Bucket>();
+
+const getBucket = (scope: object): Bucket => {
+	let bucket = scopedBuckets.get(scope);
+	if (bucket === undefined) {
+		bucket = new Map();
+		scopedBuckets.set(scope, bucket);
+	}
+	return bucket;
+};
+
+export function useRcResource<T>(
+	scope: object,
+	key: string,
+	create: () => T,
+	dispose: (resource: NoInfer<T>) => void,
+	options?: { debugPrint?: (resource: NoInfer<T>) => ReadonlyArray<unknown> },
+): T;
+export function useRcResource<T>(
+	scope: object,
+	key: string,
+	create: () => T,
+	dispose: (resource: NoInfer<T>) => void,
+	options: { debugPrint?: (resource: NoInfer<T>) => ReadonlyArray<unknown> } | undefined,
+	slot: symbol,
+): T;
+export function useRcResource<T>(
+	scope: object,
+	key: string,
+	create: () => T,
+	dispose: (resource: NoInfer<T>) => void,
+	...rest: [
+		options?: { debugPrint?: (resource: NoInfer<T>) => ReadonlyArray<unknown> },
+		slot?: symbol,
+	]
+): T {
+	const [args, slot] = splitSlot(rest);
+	void args[0];
+
+	const heldRef = useRef<{ scope: object; key: string; resource: T } | undefined>(
+		undefined,
+		subSlot(slot, 'rc:held'),
+	);
+	const createRef = useRef(create, subSlot(slot, 'rc:create'));
+	const disposeRef = useRef(dispose, subSlot(slot, 'rc:dispose'));
+
+	createRef.current = create;
+	disposeRef.current = dispose;
+
+	const release = (held: { scope: object; key: string; resource: T }) => {
+		const bucket = getBucket(held.scope);
+		const cachedItem = bucket.get(held.key);
+		if (cachedItem?._tag !== 'active') return;
+		cachedItem.rc--;
+		if (cachedItem.rc === 0) {
+			disposeRef.current(cachedItem.resource as T);
+			bucket.delete(held.key);
+		}
+	};
+
+	const resource = useMemo(
+		() => {
+			const previous = heldRef.current;
+			if (previous !== undefined) release(previous);
+
+			const bucket = getBucket(scope);
+			const cachedItem = bucket.get(key);
+			let next: T;
+			if (cachedItem?._tag === 'active') {
+				cachedItem.rc++;
+				next = cachedItem.resource as T;
+			} else {
+				next = createRef.current();
+				bucket.set(key, { _tag: 'active', rc: 1, resource: next });
+			}
+
+			heldRef.current = { scope, key, resource: next };
+			return next;
+		},
+		[scope, key],
+		subSlot(slot, 'rc:memo'),
+	);
+
+	useEffect(
+		() => {
+			const held = heldRef.current;
+			return () => {
+				if (held !== undefined && heldRef.current === held) {
+					release(held);
+					heldRef.current = undefined;
+				}
+			};
+		},
+		[scope, key],
+		subSlot(slot, 'rc:effect'),
+	);
+
+	return resource;
+}
+
+export const __resetUseRcResourceCache = (): void => {
+	scopedBuckets = new WeakMap();
+};

package/src/useStore.ts

@@ -0,0 +1,64 @@
+import type { LiveStoreSchema } from '@livestore/common/schema';
+import { SessionIdSymbol } from '@livestore/common';
+import type { RegistryStoreOptions, Store, SyncStatus } from '@livestore/livestore';
+import type { Schema } from '@livestore/utils/effect';
+import { use, useEffect } from 'octane';
+import { useStoreRegistry } from './StoreRegistryContext.tsrx';
+import { splitSlot, subSlot } from './internal';
+import { useClientDocument } from './useClientDocument';
+import { useQuery } from './useQuery';
+import { useSyncStatus } from './useSyncStatus';
+
+export type ReactApi = {
+	useQuery: typeof useQuery;
+	useClientDocument: typeof useClientDocument;
+	useSyncStatus: () => SyncStatus;
+};
+
+export function useStore<
+	TSchema extends LiveStoreSchema,
+	TContext = {},
+	TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+>(
+	options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>,
+): Store<TSchema, TContext> & ReactApi;
+export function useStore<
+	TSchema extends LiveStoreSchema,
+	TContext = {},
+	TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+>(
+	options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>,
+	...rest: [slot?: symbol]
+): Store<TSchema, TContext> & ReactApi {
+	const [, slot] = splitSlot(rest);
+	const storeRegistry = useStoreRegistry();
+	const storeOrPromise = storeRegistry.getOrLoadPromise(options);
+	const store = storeOrPromise instanceof Promise ? use(storeOrPromise) : storeOrPromise;
+	useEffect(
+		() => storeRegistry.retain(options),
+		[storeRegistry, options],
+		subSlot(slot, 'store:retain'),
+	);
+	return withReactApi(store);
+}
+
+export const withReactApi = <TSchema extends LiveStoreSchema, TContext = {}>(
+	store: Store<TSchema, TContext>,
+): Store<TSchema, TContext> & ReactApi => {
+	const augmented = store as any;
+	augmented.useQuery = (queryable: unknown, ...rest: unknown[]) =>
+		(useQuery as (...args: unknown[]) => unknown)(queryable, { store }, ...rest);
+	augmented.useClientDocument = (table: unknown, ...rest: unknown[]) => {
+		const [args, slot] = splitSlot(rest, (value) => value === SessionIdSymbol);
+		return (useClientDocument as (...args: unknown[]) => unknown)(
+			table,
+			args[0],
+			args[1],
+			{ store },
+			slot,
+		);
+	};
+	augmented.useSyncStatus = (...rest: unknown[]) =>
+		(useSyncStatus as (...args: unknown[]) => SyncStatus)({ store }, ...rest);
+	return augmented;
+};

package/src/useSyncStatus.ts

@@ -0,0 +1,41 @@
+import type { Store, SyncStatus } from '@livestore/livestore';
+import { useDebugValue, useEffect, useRef, useState } from 'octane';
+import { splitSlot, subSlot } from './internal';
+
+export function useSyncStatus(options: { store: Store<any> }): SyncStatus;
+export function useSyncStatus(
+	options: { store: Store<any> },
+	...rest: [slot?: symbol]
+): SyncStatus {
+	const [, slot] = splitSlot(rest);
+	const { store } = options;
+	const [, rerender] = useState(0, subSlot(slot, 'sync:status'));
+	const current = useRef({ store, status: store.syncStatus() }, subSlot(slot, 'sync:current'));
+	if (current.current.store !== store) {
+		current.current = { store, status: store.syncStatus() };
+	}
+	useEffect(
+		function subscribeSyncStatusEffect() {
+			const subscribedStore = store;
+			return subscribedStore.subscribeSyncStatus(function onSyncStatus(status) {
+				// Ignore emissions from a previous store while effect cleanup is pending.
+				if (current.current.store !== subscribedStore) {
+					return;
+				}
+				current.current.status = status;
+				rerender(function increment(value) {
+					return value + 1;
+				});
+			});
+		},
+		[store],
+		subSlot(slot, 'sync:effect'),
+	);
+	const { status } = current.current;
+	useDebugValue(
+		`LiveStore:useSyncStatus:${status.isSynced === true ? 'synced' : 'pending'}`,
+		undefined,
+		subSlot(slot, 'sync:debug'),
+	);
+	return status;
+}

package/src/utils/useStateRefWithReactiveInput.ts

@@ -0,0 +1,41 @@
+import { useCallback, useRef, useState } from 'octane';
+import { subSlot } from '../internal';
+
+type StateRef<T> = { current: T };
+type StateUpdate<T> = T | ((previous: T) => T);
+
+export function useStateRefWithReactiveInput<T>(
+	inputState: T,
+): [StateRef<T>, (newState: StateUpdate<T>) => void];
+export function useStateRefWithReactiveInput<T>(
+	inputState: T,
+	slot: symbol,
+): [StateRef<T>, (newState: StateUpdate<T>) => void];
+export function useStateRefWithReactiveInput<T>(
+	inputState: T,
+	slot?: symbol,
+): [StateRef<T>, (newState: StateUpdate<T>) => void] {
+	const [, rerender] = useState(0, subSlot(slot, 'state-ref:render'));
+	const lastKnownInputStateRef = useRef(inputState, subSlot(slot, 'state-ref:input'));
+	const stateRef = useRef(inputState, subSlot(slot, 'state-ref:value')) as StateRef<T>;
+
+	if (lastKnownInputStateRef.current !== inputState) {
+		lastKnownInputStateRef.current = inputState;
+		stateRef.current = inputState;
+	}
+
+	const setStateAndRerender = useCallback(
+		(newState: StateUpdate<T>) => {
+			const value =
+				typeof newState === 'function'
+					? (newState as (previous: T) => T)(stateRef.current)
+					: newState;
+			stateRef.current = value;
+			rerender((count) => count + 1);
+		},
+		[],
+		subSlot(slot, 'state-ref:set'),
+	);
+
+	return [stateRef, setStateAndRerender];
+}