@rindle/react 0.1.0-rc.5

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 [yyyy] [name of copyright owner]
+
+   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,43 @@
+# @rindle/react
+
+React bindings for Rindle stores.
+
+```tsx
+import { Rindle, useQuery } from "@rindle/react";
+
+createRoot(root).render(
+  <Rindle store={app.store}>
+    <Issues />
+  </Rindle>,
+);
+
+function Issues() {
+  const issues = useQuery(queries.issuesPage(null));
+  return issues.map((issue) => <div key={issue.id}>{issue.title}</div>);
+}
+```
+
+`useQuery(query)` returns live `data`, subscribes on mount, and releases on unmount.
+
+For local-first backends, the React-facing data view is shared by compiled local AST. Each
+mounted hook still retains its own `name`/`args` lease through the Store, so backend-level
+subscription refcounting remains responsible for server dedupe and teardown. Backends that
+cannot split local views from remote subscriptions keep the older materialized-view fallback.
+
+## Other exports
+
+- `Rindle` / `RindleProvider` — the context provider (`RindleProvider` is an alias of `Rindle`).
+- `useQuery(query)` — live query data; subscribes on mount, releases on unmount.
+- `useQueryStatus(query)` — the query's `ResultType`, which tracks the **server channel only**:
+  `unknown` while it loads (not yet server-authoritative), `complete` once the server has
+  answered. A pending optimistic mutation no longer moves it — "is a write pending here?" is a
+  separate axis on the backend (`backend.pending(qid)` / `onPending`), and `error` is reserved
+  and currently unproduced. Shares `useQuery`'s leased view, so reading both is one subscription.
+- `useFragment(fragment, ref)` — a pure read of an already-projected fragment slice off the root
+  query's view (FRAGMENT-COMPOSITION-DESIGN.md §7). Adds no lease and never re-renders on its own;
+  it keeps a component tree waterfall-free by letting descendants read the one query the root opened.
+- `useRindleStore()` — the `Store` from context, for imperative writes/reads inside components.
+- `QueryCache` — the per-provider cache that dedupes a query's materialized view across hooks.
+- `queryCacheKey(query)` — the stable string key (`@rindle/client`'s `stableKey(ast)`) under which
+  the cache stores that view. Same AST → same key → one shared entry, and it matches the SSR seed
+  key so hydration finds the dehydrated view. Keys the view (bare AST), not the lease.

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import type { ReactNode } from "react";
+import type { ColsMap, Fragment, FragmentRef, Query, ResultType, Store } from "@rindle/client";
+type AnyQuery = Query<any, any, any>;
+export type QueryData<Q extends AnyQuery> = ReturnType<Q["materialize"]>["data"];
+export type { ResultType } from "@rindle/client";
+export type { Fragment, FragmentRef } from "@rindle/client";
+export interface RindleProps<S extends ColsMap = ColsMap> {
+    store: Store<S>;
+    children?: ReactNode;
+}
+interface QueryLease {
+    id: number;
+    viewKey: string;
+}
+declare class RindleContextValue {
+    readonly store: Store<ColsMap>;
+    readonly cache: QueryCache;
+    constructor(store: Store<ColsMap>);
+}
+export declare function Rindle<S extends ColsMap>({ store, children }: RindleProps<S>): import("react").FunctionComponentElement<import("react").ProviderProps<RindleContextValue | null>>;
+export declare const RindleProvider: typeof Rindle;
+export declare function useRindleStore<S extends ColsMap = ColsMap>(): Store<S>;
+export declare function useQuery<Q extends AnyQuery>(query: Q): QueryData<Q>;
+/** The SERVER-CHANNEL state of a query's view (`@rindle/client` {@link ResultType}): `unknown` while
+ *  it loads (not yet server-authoritative), `complete` once the server has answered. A pending
+ *  optimistic mutation no longer moves this — that is a separate axis now (FOLDED-MUTATIONS-DESIGN
+ *  §7); the `error` variant is reserved and currently unproduced. Shares the same cached/leased view
+ *  as {@link useQuery} (so reading both for one query is one subscription), and re-renders only when
+ *  the status changes. */
+export declare function useQueryStatus(query: AnyQuery): ResultType;
+/**
+ * Read a {@link Fragment}'s slice off the shared root view (FRAGMENT-COMPOSITION-DESIGN.md §7).
+ *
+ * The waterfall-free contract: the ROOT component `useQuery`s the composed query (every child
+ * fragment spread into it), and every descendant calls `useFragment` — a PURE READ of the
+ * already-projected node at this fragment's alias — instead of opening its own `useQuery`. So a
+ * whole component tree resolves through the ONE query the root opened, with no request waterfall;
+ * a descendant that opens its own `useQuery` reintroduces the waterfall at that boundary.
+ *
+ * Phase 0 is a typed pass-through: `ref` already IS the projected node (the parent got it from
+ * `useQuery` and handed the slice down), so this returns it typed as the fragment's
+ * {@link FragmentRef}. `fragment` declares *which* selection this component reads (co-location +
+ * the seam masking plugs into); masking (Phase 2) narrows the returned shape with no call-site
+ * change. Not a subscription — it adds no lease and never re-renders on its own.
+ */
+export declare function useFragment<F extends Fragment<any, any, any>>(fragment: F, ref: FragmentRef<F>): FragmentRef<F>;
+export declare class QueryCache {
+    private readonly entries;
+    private nextLeaseId;
+    private readonly store;
+    constructor(store: Store<ColsMap>);
+    retain<Q extends AnyQuery>(viewKey: string, query: Q): QueryLease;
+    release(lease: QueryLease): void;
+    subscribe(viewKey: string, listener: () => void): () => void;
+    snapshot(viewKey: string, one: boolean): unknown;
+    /** A query's current {@link ResultType} (from its view), or `unknown` before it is retained. */
+    resultType(viewKey: string): ResultType;
+    /** The SSR/hydration snapshot for `viewKey` — the store's preloaded/dehydrated seed, read
+     *  WITHOUT retaining (the server never opens a subscription). Falls back to empty so a
+     *  non-preloaded query renders like an unhydrated one. */
+    serverSnapshot(viewKey: string, one: boolean): unknown;
+    /** The SSR {@link ResultType}: `complete` when a seed exists (server-authoritative first paint),
+     *  else `unknown`. */
+    serverResultType(viewKey: string): ResultType;
+    size(): number;
+    private createSplitEntry;
+    private createSplitLease;
+    private createMaterializedEntry;
+    private createMaterializedLease;
+    private chooseCanonical;
+    private setCanonical;
+}
+export declare function queryCacheKey(query: AnyQuery): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,252 @@
+import { createContext, createElement, useCallback, useContext, useMemo, useRef, useSyncExternalStore, } from "react";
+import { stableKey } from "@rindle/client";
+const EMPTY_ARRAY = Object.freeze([]);
+class RindleContextValue {
+    store;
+    cache;
+    constructor(store) {
+        this.store = store;
+        this.cache = new QueryCache(store);
+    }
+}
+const RindleContext = createContext(null);
+export function Rindle({ store, children }) {
+    const value = useMemo(() => new RindleContextValue(store), [store]);
+    return createElement(RindleContext.Provider, { value }, children);
+}
+export const RindleProvider = Rindle;
+export function useRindleStore() {
+    return useRindleContext().store;
+}
+export function useQuery(query) {
+    const ctx = useRindleContext();
+    const descriptor = useMemo(() => describeQuery(query), [query]);
+    const queryRef = useRef(query);
+    queryRef.current = query;
+    const subscribe = useCallback((onStoreChange) => {
+        const lease = ctx.cache.retain(descriptor.viewKey, queryRef.current);
+        const unsubscribe = ctx.cache.subscribe(descriptor.viewKey, onStoreChange);
+        return () => {
+            unsubscribe();
+            ctx.cache.release(lease);
+        };
+    }, [ctx.cache, descriptor.leaseKey, descriptor.viewKey]);
+    const getSnapshot = useCallback(() => ctx.cache.snapshot(descriptor.viewKey, descriptor.one), [ctx.cache, descriptor.viewKey, descriptor.one]);
+    // SSR (SSR-DESIGN.md §6): the server calls `getServerSnapshot` (never `subscribe`), so it must
+    // surface the dehydrated/preloaded seed directly — not the live cache, which is never retained
+    // on the server. The client's hydration pass reads the same seed, matching the SSR markup.
+    const getServerSnapshot = useCallback(() => ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one), [ctx.cache, descriptor.viewKey, descriptor.one]);
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+/** The SERVER-CHANNEL state of a query's view (`@rindle/client` {@link ResultType}): `unknown` while
+ *  it loads (not yet server-authoritative), `complete` once the server has answered. A pending
+ *  optimistic mutation no longer moves this — that is a separate axis now (FOLDED-MUTATIONS-DESIGN
+ *  §7); the `error` variant is reserved and currently unproduced. Shares the same cached/leased view
+ *  as {@link useQuery} (so reading both for one query is one subscription), and re-renders only when
+ *  the status changes. */
+export function useQueryStatus(query) {
+    const ctx = useRindleContext();
+    const descriptor = useMemo(() => describeQuery(query), [query]);
+    const queryRef = useRef(query);
+    queryRef.current = query;
+    const subscribe = useCallback((onStoreChange) => {
+        const lease = ctx.cache.retain(descriptor.viewKey, queryRef.current);
+        const unsubscribe = ctx.cache.subscribe(descriptor.viewKey, onStoreChange);
+        return () => {
+            unsubscribe();
+            ctx.cache.release(lease);
+        };
+    }, [ctx.cache, descriptor.leaseKey, descriptor.viewKey]);
+    const getSnapshot = useCallback(() => ctx.cache.resultType(descriptor.viewKey), [ctx.cache, descriptor.viewKey]);
+    // SSR: a seeded query is server-authoritative for first paint (`complete`); otherwise `unknown`.
+    const getServerSnapshot = useCallback(() => ctx.cache.serverResultType(descriptor.viewKey), [ctx.cache, descriptor.viewKey]);
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+/**
+ * Read a {@link Fragment}'s slice off the shared root view (FRAGMENT-COMPOSITION-DESIGN.md §7).
+ *
+ * The waterfall-free contract: the ROOT component `useQuery`s the composed query (every child
+ * fragment spread into it), and every descendant calls `useFragment` — a PURE READ of the
+ * already-projected node at this fragment's alias — instead of opening its own `useQuery`. So a
+ * whole component tree resolves through the ONE query the root opened, with no request waterfall;
+ * a descendant that opens its own `useQuery` reintroduces the waterfall at that boundary.
+ *
+ * Phase 0 is a typed pass-through: `ref` already IS the projected node (the parent got it from
+ * `useQuery` and handed the slice down), so this returns it typed as the fragment's
+ * {@link FragmentRef}. `fragment` declares *which* selection this component reads (co-location +
+ * the seam masking plugs into); masking (Phase 2) narrows the returned shape with no call-site
+ * change. Not a subscription — it adds no lease and never re-renders on its own.
+ */
+export function useFragment(fragment, ref) {
+    void fragment;
+    return ref;
+}
+export class QueryCache {
+    entries = new Map();
+    nextLeaseId = 1;
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    retain(viewKey, query) {
+        let entry = this.entries.get(viewKey);
+        if (!entry) {
+            entry = this.store.canRetainRemoteQueries()
+                ? this.createSplitEntry(viewKey, query)
+                : this.createMaterializedEntry(viewKey, query);
+            this.entries.set(viewKey, entry);
+            const lease = entry.leases[0];
+            return { id: lease.id, viewKey };
+        }
+        if (entry.mode === "split") {
+            const lease = this.createSplitLease(viewKey, entry.handle, query);
+            entry.leases.push(lease);
+            return { id: lease.id, viewKey };
+        }
+        const lease = this.createMaterializedLease(viewKey, query);
+        entry.leases.push(lease);
+        if (!entry.canonical.remote && lease.remote)
+            this.setCanonical(entry, lease);
+        return { id: lease.id, viewKey };
+    }
+    release(lease) {
+        const entry = this.entries.get(lease.viewKey);
+        if (!entry)
+            return;
+        const index = entry.leases.findIndex((l) => l.id === lease.id);
+        if (index < 0)
+            return;
+        if (entry.mode === "split") {
+            const [released] = entry.leases.splice(index, 1);
+            released.releaseRemote();
+            if (entry.leases.length > 0)
+                return;
+            entry.canonicalUnsubscribe();
+            entry.handle.destroy();
+            this.entries.delete(lease.viewKey);
+            return;
+        }
+        const [released] = entry.leases.splice(index, 1);
+        if (entry.canonical.id === released.id) {
+            entry.canonicalUnsubscribe();
+            entry.canonicalUnsubscribe = () => { };
+        }
+        released.view.destroy();
+        if (entry.leases.length === 0) {
+            this.entries.delete(lease.viewKey);
+            return;
+        }
+        if (entry.canonical.id === released.id)
+            this.setCanonical(entry, this.chooseCanonical(entry.leases));
+    }
+    subscribe(viewKey, listener) {
+        const entry = this.entries.get(viewKey);
+        if (!entry)
+            return () => { };
+        entry.listeners.add(listener);
+        return () => {
+            entry.listeners.delete(listener);
+        };
+    }
+    snapshot(viewKey, one) {
+        const entry = this.entries.get(viewKey);
+        if (entry)
+            return entry.mode === "split" ? entry.handle.view.data : entry.canonical.view.data;
+        return one ? null : EMPTY_ARRAY;
+    }
+    /** A query's current {@link ResultType} (from its view), or `unknown` before it is retained. */
+    resultType(viewKey) {
+        const entry = this.entries.get(viewKey);
+        if (!entry)
+            return "unknown";
+        return entry.mode === "split" ? entry.handle.view.resultType : entry.canonical.view.resultType;
+    }
+    /** The SSR/hydration snapshot for `viewKey` — the store's preloaded/dehydrated seed, read
+     *  WITHOUT retaining (the server never opens a subscription). Falls back to empty so a
+     *  non-preloaded query renders like an unhydrated one. */
+    serverSnapshot(viewKey, one) {
+        const seed = this.store.seedSnapshot(viewKey);
+        if (!seed)
+            return one ? null : EMPTY_ARRAY;
+        return one ? (seed.rows[0] ?? null) : seed.rows;
+    }
+    /** The SSR {@link ResultType}: `complete` when a seed exists (server-authoritative first paint),
+     *  else `unknown`. */
+    serverResultType(viewKey) {
+        return this.store.seedSnapshot(viewKey) ? "complete" : "unknown";
+    }
+    size() {
+        return this.entries.size;
+    }
+    createSplitEntry(viewKey, query) {
+        const handle = this.store.createCachedQueryView(query);
+        const entry = {
+            mode: "split",
+            handle,
+            leases: [],
+            canonicalUnsubscribe: () => { },
+            listeners: new Set(),
+        };
+        entry.leases.push(this.createSplitLease(viewKey, handle, query));
+        entry.canonicalUnsubscribe = handle.view.subscribe(() => {
+            for (const listener of entry.listeners)
+                listener();
+        });
+        return entry;
+    }
+    createSplitLease(viewKey, handle, query) {
+        return { id: this.nextLeaseId++, viewKey, releaseRemote: handle.retain(query) };
+    }
+    createMaterializedEntry(viewKey, query) {
+        const lease = this.createMaterializedLease(viewKey, query);
+        const entry = {
+            mode: "materialized",
+            leases: [lease],
+            canonical: lease,
+            canonicalUnsubscribe: () => { },
+            listeners: new Set(),
+        };
+        this.setCanonical(entry, lease);
+        return entry;
+    }
+    createMaterializedLease(viewKey, query) {
+        return {
+            id: this.nextLeaseId++,
+            viewKey,
+            view: this.store.materialize(query),
+            remote: typeof query.name === "string",
+        };
+    }
+    chooseCanonical(leases) {
+        return leases.find((lease) => lease.remote) ?? leases[0];
+    }
+    setCanonical(entry, lease) {
+        entry.canonicalUnsubscribe();
+        entry.canonical = lease;
+        entry.canonicalUnsubscribe = lease.view.subscribe(() => {
+            for (const listener of entry.listeners)
+                listener();
+        });
+    }
+}
+export function queryCacheKey(query) {
+    return describeQuery(query).viewKey;
+}
+function useRindleContext() {
+    const ctx = useContext(RindleContext);
+    if (!ctx)
+        throw new Error("Rindle context is missing. Wrap this tree in <Rindle store={store}>.");
+    return ctx;
+}
+function describeQuery(query) {
+    const ast = query.ast();
+    const remote = typeof query.name === "string" ? { name: query.name, args: query.args } : null;
+    return {
+        // `viewKey` MUST match the SSR seed key (`@rindle/client`'s `stableKey(ast)`) so
+        // `getServerSnapshot` finds the dehydrated entry — one canonical serializer, shared.
+        viewKey: stableKey(ast),
+        leaseKey: stableKey({ ast, remote }),
+        one: ast.one === true,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rindle/react",
+  "version": "0.1.0-rc.5",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rindle-sh/rindle.git",
+    "directory": "packages/react"
+  },
+  "type": "module",
+  "description": "React bindings for Rindle: context provider plus useQuery with shared AST-keyed view retain/release.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@rindle/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@rindle/client": "0.1.0-rc.5"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/jsdom": "^21.1.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^25.0.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc --noEmit && node --conditions=@rindle/source --test test/*.test.ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,360 @@
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from "react";
+import type { ReactNode } from "react";
+import { stableKey } from "@rindle/client";
+import type { CachedQueryView, ColsMap, Fragment, FragmentRef, Query, ResultType, Store } from "@rindle/client";
+
+type AnyQuery = Query<any, any, any>;
+type AnyView = ReturnType<AnyQuery["materialize"]>;
+
+export type QueryData<Q extends AnyQuery> = ReturnType<Q["materialize"]>["data"];
+
+export type { ResultType } from "@rindle/client";
+export type { Fragment, FragmentRef } from "@rindle/client";
+
+export interface RindleProps<S extends ColsMap = ColsMap> {
+  store: Store<S>;
+  children?: ReactNode;
+}
+
+interface QueryDescriptor {
+  viewKey: string;
+  leaseKey: string;
+  one: boolean;
+}
+
+interface QueryLease {
+  id: number;
+  viewKey: string;
+}
+
+interface MaterializedLease extends QueryLease {
+  view: AnyView;
+  remote: boolean;
+}
+
+interface SplitLease extends QueryLease {
+  releaseRemote: () => void;
+}
+
+type CacheLease = MaterializedLease | SplitLease;
+
+interface BaseCacheEntry {
+  leases: CacheLease[];
+  canonicalUnsubscribe: () => void;
+  listeners: Set<() => void>;
+}
+
+interface SplitCacheEntry extends BaseCacheEntry {
+  mode: "split";
+  handle: CachedQueryView<AnyQuery>;
+  leases: SplitLease[];
+}
+
+interface MaterializedCacheEntry extends BaseCacheEntry {
+  mode: "materialized";
+  leases: MaterializedLease[];
+  canonical: MaterializedLease;
+}
+
+type CacheEntry = SplitCacheEntry | MaterializedCacheEntry;
+
+const EMPTY_ARRAY: readonly never[] = Object.freeze([]);
+
+class RindleContextValue {
+  readonly store: Store<ColsMap>;
+  readonly cache: QueryCache;
+
+  constructor(store: Store<ColsMap>) {
+    this.store = store;
+    this.cache = new QueryCache(store);
+  }
+}
+
+const RindleContext = createContext<RindleContextValue | null>(null);
+
+export function Rindle<S extends ColsMap>({ store, children }: RindleProps<S>) {
+  const value = useMemo(() => new RindleContextValue(store as unknown as Store<ColsMap>), [store]);
+  return createElement(RindleContext.Provider, { value }, children);
+}
+
+export const RindleProvider = Rindle;
+
+export function useRindleStore<S extends ColsMap = ColsMap>(): Store<S> {
+  return useRindleContext().store as unknown as Store<S>;
+}
+
+export function useQuery<Q extends AnyQuery>(query: Q): QueryData<Q> {
+  const ctx = useRindleContext();
+  const descriptor = useMemo(() => describeQuery(query), [query]);
+  const queryRef = useRef(query);
+  queryRef.current = query;
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const lease = ctx.cache.retain(descriptor.viewKey, queryRef.current);
+      const unsubscribe = ctx.cache.subscribe(descriptor.viewKey, onStoreChange);
+      return () => {
+        unsubscribe();
+        ctx.cache.release(lease);
+      };
+    },
+    [ctx.cache, descriptor.leaseKey, descriptor.viewKey],
+  );
+
+  const getSnapshot = useCallback(
+    () => ctx.cache.snapshot(descriptor.viewKey, descriptor.one) as QueryData<Q>,
+    [ctx.cache, descriptor.viewKey, descriptor.one],
+  );
+
+  // SSR (SSR-DESIGN.md §6): the server calls `getServerSnapshot` (never `subscribe`), so it must
+  // surface the dehydrated/preloaded seed directly — not the live cache, which is never retained
+  // on the server. The client's hydration pass reads the same seed, matching the SSR markup.
+  const getServerSnapshot = useCallback(
+    () => ctx.cache.serverSnapshot(descriptor.viewKey, descriptor.one) as QueryData<Q>,
+    [ctx.cache, descriptor.viewKey, descriptor.one],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+/** The SERVER-CHANNEL state of a query's view (`@rindle/client` {@link ResultType}): `unknown` while
+ *  it loads (not yet server-authoritative), `complete` once the server has answered. A pending
+ *  optimistic mutation no longer moves this — that is a separate axis now (FOLDED-MUTATIONS-DESIGN
+ *  §7); the `error` variant is reserved and currently unproduced. Shares the same cached/leased view
+ *  as {@link useQuery} (so reading both for one query is one subscription), and re-renders only when
+ *  the status changes. */
+export function useQueryStatus(query: AnyQuery): ResultType {
+  const ctx = useRindleContext();
+  const descriptor = useMemo(() => describeQuery(query), [query]);
+  const queryRef = useRef(query);
+  queryRef.current = query;
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const lease = ctx.cache.retain(descriptor.viewKey, queryRef.current);
+      const unsubscribe = ctx.cache.subscribe(descriptor.viewKey, onStoreChange);
+      return () => {
+        unsubscribe();
+        ctx.cache.release(lease);
+      };
+    },
+    [ctx.cache, descriptor.leaseKey, descriptor.viewKey],
+  );
+
+  const getSnapshot = useCallback(() => ctx.cache.resultType(descriptor.viewKey), [ctx.cache, descriptor.viewKey]);
+
+  // SSR: a seeded query is server-authoritative for first paint (`complete`); otherwise `unknown`.
+  const getServerSnapshot = useCallback(
+    () => ctx.cache.serverResultType(descriptor.viewKey),
+    [ctx.cache, descriptor.viewKey],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+/**
+ * Read a {@link Fragment}'s slice off the shared root view (FRAGMENT-COMPOSITION-DESIGN.md §7).
+ *
+ * The waterfall-free contract: the ROOT component `useQuery`s the composed query (every child
+ * fragment spread into it), and every descendant calls `useFragment` — a PURE READ of the
+ * already-projected node at this fragment's alias — instead of opening its own `useQuery`. So a
+ * whole component tree resolves through the ONE query the root opened, with no request waterfall;
+ * a descendant that opens its own `useQuery` reintroduces the waterfall at that boundary.
+ *
+ * Phase 0 is a typed pass-through: `ref` already IS the projected node (the parent got it from
+ * `useQuery` and handed the slice down), so this returns it typed as the fragment's
+ * {@link FragmentRef}. `fragment` declares *which* selection this component reads (co-location +
+ * the seam masking plugs into); masking (Phase 2) narrows the returned shape with no call-site
+ * change. Not a subscription — it adds no lease and never re-renders on its own.
+ */
+export function useFragment<F extends Fragment<any, any, any>>(fragment: F, ref: FragmentRef<F>): FragmentRef<F> {
+  void fragment;
+  return ref;
+}
+
+export class QueryCache {
+  private readonly entries = new Map<string, CacheEntry>();
+  private nextLeaseId = 1;
+  private readonly store: Store<ColsMap>;
+
+  constructor(store: Store<ColsMap>) {
+    this.store = store;
+  }
+
+  retain<Q extends AnyQuery>(viewKey: string, query: Q): QueryLease {
+    let entry = this.entries.get(viewKey);
+    if (!entry) {
+      entry = this.store.canRetainRemoteQueries()
+        ? this.createSplitEntry(viewKey, query)
+        : this.createMaterializedEntry(viewKey, query);
+      this.entries.set(viewKey, entry);
+      const lease = entry.leases[0];
+      return { id: lease.id, viewKey };
+    }
+    if (entry.mode === "split") {
+      const lease = this.createSplitLease(viewKey, entry.handle, query);
+      entry.leases.push(lease);
+      return { id: lease.id, viewKey };
+    }
+    const lease = this.createMaterializedLease(viewKey, query);
+    entry.leases.push(lease);
+    if (!entry.canonical.remote && lease.remote) this.setCanonical(entry, lease);
+    return { id: lease.id, viewKey };
+  }
+
+  release(lease: QueryLease): void {
+    const entry = this.entries.get(lease.viewKey);
+    if (!entry) return;
+    const index = entry.leases.findIndex((l) => l.id === lease.id);
+    if (index < 0) return;
+    if (entry.mode === "split") {
+      const [released] = entry.leases.splice(index, 1);
+      released.releaseRemote();
+      if (entry.leases.length > 0) return;
+      entry.canonicalUnsubscribe();
+      entry.handle.destroy();
+      this.entries.delete(lease.viewKey);
+      return;
+    }
+    const [released] = entry.leases.splice(index, 1);
+    if (entry.canonical.id === released.id) {
+      entry.canonicalUnsubscribe();
+      entry.canonicalUnsubscribe = () => {};
+    }
+    released.view.destroy();
+    if (entry.leases.length === 0) {
+      this.entries.delete(lease.viewKey);
+      return;
+    }
+    if (entry.canonical.id === released.id) this.setCanonical(entry, this.chooseCanonical(entry.leases));
+  }
+
+  subscribe(viewKey: string, listener: () => void): () => void {
+    const entry = this.entries.get(viewKey);
+    if (!entry) return () => {};
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+    };
+  }
+
+  snapshot(viewKey: string, one: boolean): unknown {
+    const entry = this.entries.get(viewKey);
+    if (entry) return entry.mode === "split" ? entry.handle.view.data : entry.canonical.view.data;
+    return one ? null : EMPTY_ARRAY;
+  }
+
+  /** A query's current {@link ResultType} (from its view), or `unknown` before it is retained. */
+  resultType(viewKey: string): ResultType {
+    const entry = this.entries.get(viewKey);
+    if (!entry) return "unknown";
+    return entry.mode === "split" ? entry.handle.view.resultType : entry.canonical.view.resultType;
+  }
+
+  /** The SSR/hydration snapshot for `viewKey` — the store's preloaded/dehydrated seed, read
+   *  WITHOUT retaining (the server never opens a subscription). Falls back to empty so a
+   *  non-preloaded query renders like an unhydrated one. */
+  serverSnapshot(viewKey: string, one: boolean): unknown {
+    const seed = this.store.seedSnapshot(viewKey);
+    if (!seed) return one ? null : EMPTY_ARRAY;
+    return one ? (seed.rows[0] ?? null) : seed.rows;
+  }
+
+  /** The SSR {@link ResultType}: `complete` when a seed exists (server-authoritative first paint),
+   *  else `unknown`. */
+  serverResultType(viewKey: string): ResultType {
+    return this.store.seedSnapshot(viewKey) ? "complete" : "unknown";
+  }
+
+  size(): number {
+    return this.entries.size;
+  }
+
+  private createSplitEntry<Q extends AnyQuery>(viewKey: string, query: Q): SplitCacheEntry {
+    const handle = this.store.createCachedQueryView(query) as unknown as CachedQueryView<AnyQuery>;
+    const entry: SplitCacheEntry = {
+      mode: "split",
+      handle,
+      leases: [],
+      canonicalUnsubscribe: () => {},
+      listeners: new Set(),
+    };
+    entry.leases.push(this.createSplitLease(viewKey, handle, query));
+    entry.canonicalUnsubscribe = handle.view.subscribe(() => {
+      for (const listener of entry.listeners) listener();
+    });
+    return entry;
+  }
+
+  private createSplitLease<Q extends AnyQuery>(
+    viewKey: string,
+    handle: CachedQueryView<AnyQuery>,
+    query: Q,
+  ): SplitLease {
+    return { id: this.nextLeaseId++, viewKey, releaseRemote: handle.retain(query) };
+  }
+
+  private createMaterializedEntry<Q extends AnyQuery>(viewKey: string, query: Q): MaterializedCacheEntry {
+    const lease = this.createMaterializedLease(viewKey, query);
+    const entry: MaterializedCacheEntry = {
+      mode: "materialized",
+      leases: [lease],
+      canonical: lease,
+      canonicalUnsubscribe: () => {},
+      listeners: new Set(),
+    };
+    this.setCanonical(entry, lease);
+    return entry;
+  }
+
+  private createMaterializedLease<Q extends AnyQuery>(viewKey: string, query: Q): MaterializedLease {
+    return {
+      id: this.nextLeaseId++,
+      viewKey,
+      view: this.store.materialize(query) as AnyView,
+      remote: typeof query.name === "string",
+    };
+  }
+
+  private chooseCanonical(leases: MaterializedLease[]): MaterializedLease {
+    return leases.find((lease) => lease.remote) ?? leases[0];
+  }
+
+  private setCanonical(entry: MaterializedCacheEntry, lease: MaterializedLease): void {
+    entry.canonicalUnsubscribe();
+    entry.canonical = lease;
+    entry.canonicalUnsubscribe = lease.view.subscribe(() => {
+      for (const listener of entry.listeners) listener();
+    });
+  }
+}
+
+export function queryCacheKey(query: AnyQuery): string {
+  return describeQuery(query).viewKey;
+}
+
+function useRindleContext(): RindleContextValue {
+  const ctx = useContext(RindleContext);
+  if (!ctx) throw new Error("Rindle context is missing. Wrap this tree in <Rindle store={store}>.");
+  return ctx;
+}
+
+function describeQuery(query: AnyQuery): QueryDescriptor {
+  const ast = query.ast();
+  const remote = typeof query.name === "string" ? { name: query.name, args: query.args } : null;
+  return {
+    // `viewKey` MUST match the SSR seed key (`@rindle/client`'s `stableKey(ast)`) so
+    // `getServerSnapshot` finds the dehydrated entry — one canonical serializer, shared.
+    viewKey: stableKey(ast),
+    leaseKey: stableKey({ ast, remote }),
+    one: ast.one === true,
+  };
+}