@pwa-platform/react 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PWA Platform contributors
+
+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,9 @@
+# @pwa-platform/react
+
+React 19 binding for PWA Platform.
+
+Use `PwaProvider` and `usePwa()` in a React 19 application. Also configure `@pwa-platform/vite` for build artifacts.
+
+This is a `0.1.0` prerelease. It provides online use, installation integration, static precaching, a safe offline fallback, and controlled updates. It does not enable runtime business API caching, private data caching, automatic write replay, or Push for applications. Production deployment requires the application and infrastructure checks described in the PWA Platform release runbook.
+
+License: MIT.

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import type { PwaClient, PwaClientConfig } from "@pwa-platform/client-runtime";
+import { type ReactElement, type ReactNode } from "react";
+import { type PwaMethods, type PwaState } from "./store.js";
+export type { PwaMethods, PwaState } from "./store.js";
+export type PwaBinding = PwaMethods & {
+    readonly state: PwaState;
+};
+export type PwaProviderProps = {
+    readonly config: PwaClientConfig;
+    /**
+     * Defaults to a facade built from `config`; passed explicitly only to inject a fake in tests. Whatever is passed
+     * is disposed when the provider unmounts — the binding takes ownership of it for its lifetime.
+     */
+    readonly client?: PwaClient;
+    /**
+     * Automatic periodic checks, forwarded to `createPwaClient` when the provider builds its own facade. Omitted
+     * means off. Meaningless together with `client` — an injected facade is already built, so `PwaProvider` throws
+     * during render when both are passed (spec: 修订：主动检查更新).
+     */
+    readonly updateCheck?: {
+        readonly intervalMs: number;
+    };
+    readonly children?: ReactNode;
+};
+export declare function PwaProvider(props: PwaProviderProps): ReactElement;
+/** Reads the binding provided by `PwaProvider`. Throws when no provider is above it in the tree. */
+export declare function usePwa(): PwaBinding;
+//# 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":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,EAQL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAOL,KAAK,UAAU,EACf,KAAK,QAAQ,EAEd,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;CAC/B,CAAC;AAMF,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,YAAY,CA2BjE;AAED,oGAAoG;AACpG,wBAAgB,MAAM,IAAI,UAAU,CAwBnC"}

package/dist/index.js

@@ -0,0 +1,58 @@
+import { createContext, createElement, useContext, useEffect, useMemo, useState, useSyncExternalStore, } from "react";
+import { bindFacade, CLIENT_AND_UPDATE_CHECK_ERROR, createStore, INITIAL_STATE, providerEffectDeps, SERVER_METHODS, } from "./store.js";
+const StoreContext = createContext(null);
+// No JSX anywhere in this package: `tsconfig.base.json` sets no `jsx` option, and changing the whole repository's
+// compiler configuration for one provider that renders no elements of its own is not worth it.
+export function PwaProvider(props) {
+    const { config, client, updateCheck, children } = props;
+    // Checked first, before any hook runs: an injected facade is already built, and the provider has no way to
+    // configure its automatic update check after the fact. Because this precedes every hook call, it can also be
+    // exercised directly as a plain function call in a unit test, without a renderer.
+    if (client !== undefined && updateCheck !== undefined) {
+        throw new Error(CLIENT_AND_UPDATE_CHECK_ERROR);
+    }
+    // One store per provider instance, created lazily so it already exists on the first render and children can read
+    // state immediately. The facade is attached by the effect below, not here.
+    const [store] = useState(createStore);
+    useEffect(
+    // The whole body lives in `bindFacade` so it can be tested without a renderer. Creating the facade inside the
+    // effect is also what StrictMode requires: it deliberately mounts, unmounts and mounts again, and a facade
+    // built during render would be disposed by the first cleanup and then reused dead on the second mount.
+    () => bindFacade(store, config, client, updateCheck), 
+    // Depends on the config's *fields*, not on the object, and on `updateCheck`'s `intervalMs` field rather than
+    // the object itself — for the same reason. `<PwaProvider config={{ ... }} updateCheck={{ ... }}>` builds new
+    // objects on every render, and an object dependency would tear the facade down and build a fresh, unregistered
+    // one each time — with the store's flags still describing the old one. React's own docs flag object
+    // dependencies for exactly this reason. See `providerEffectDeps` for the list itself, extracted for a unit
+    // test this component cannot carry (spec: 已知限制).
+    providerEffectDeps(store, client, config, updateCheck));
+    return createElement(StoreContext.Provider, { value: store }, children);
+}
+/** Reads the binding provided by `PwaProvider`. Throws when no provider is above it in the tree. */
+export function usePwa() {
+    const store = useContext(StoreContext);
+    if (store === null) {
+        throw new Error("No PWA binding found: wrap the tree in a PwaProvider first");
+    }
+    // The third argument is what React reads on the server and while hydrating. Without it a server render throws
+    // (ADR-0016, 2026-09-17 amendment). The provider's effect never runs on the server, so no facade exists there and
+    // the initial state is the only true answer.
+    const state = useSyncExternalStore(store.subscribe, store.getSnapshot, getServerSnapshot);
+    // On the server the store's methods would wait for a facade that is never attached; hand out ones that reject.
+    const methods = typeof window === "undefined" ? SERVER_METHODS : store;
+    // Memoised so the binding keeps its identity between renders. Without this, an application that lists the
+    // binding in a dependency array would re-run that effect on every single render.
+    return useMemo(() => ({
+        state,
+        register: methods.register,
+        promptInstall: methods.promptInstall,
+        applyUpdate: methods.applyUpdate,
+        logout: methods.logout,
+        checkForUpdate: methods.checkForUpdate,
+    }), [state, methods]);
+}
+/** Module-level, so React sees the same function on every render. */
+function getServerSnapshot() {
+    return INITIAL_STATE;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,SAAS,EACT,OAAO,EACP,QAAQ,EACR,oBAAoB,GAGrB,MAAM,OAAO,CAAC;AACf,OAAO,EACL,UAAU,EACV,6BAA6B,EAC7B,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,cAAc,GAIf,MAAM,YAAY,CAAC;AAsBpB,MAAM,YAAY,GAAG,aAAa,CAAkB,IAAI,CAAC,CAAC;AAE1D,kHAAkH;AAClH,+FAA+F;AAC/F,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IACxD,2GAA2G;IAC3G,6GAA6G;IAC7G,kFAAkF;IAClF,IAAI,MAAM,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IACD,iHAAiH;IACjH,2EAA2E;IAC3E,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;IAEtC,SAAS;IACP,8GAA8G;IAC9G,2GAA2G;IAC3G,uGAAuG;IACvG,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC;IACpD,6GAA6G;IAC7G,6GAA6G;IAC7G,+GAA+G;IAC/G,oGAAoG;IACpG,2GAA2G;IAC3G,iDAAiD;IACjD,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,CACvD,CAAC;IAEF,OAAO,aAAa,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC1E,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,MAAM;IACpB,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,8GAA8G;IAC9G,kHAAkH;IAClH,6CAA6C;IAC7C,MAAM,KAAK,GAAG,oBAAoB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC;IAC1F,+GAA+G;IAC/G,MAAM,OAAO,GAAe,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC;IACnF,0GAA0G;IAC1G,iFAAiF;IACjF,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,KAAK;QACL,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC,EACF,CAAC,KAAK,EAAE,OAAO,CAAC,CACjB,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,SAAS,iBAAiB;IACxB,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,88 @@
+import { type PwaClient, type PwaClientConfig, type PwaClientEvent } from "@pwa-platform/client-runtime";
+export type PwaState = {
+    /** `registered` was emitted: the worker is registered at the plan's scope. */
+    readonly registered: boolean;
+    /** `install-eligible` was emitted and the app is not installed yet: `promptInstall()` can be called. */
+    readonly installEligible: boolean;
+    readonly installed: boolean;
+    /** `update-waiting` was emitted: a new version is waiting and `applyUpdate()` can be called. */
+    readonly updateWaiting: boolean;
+};
+export declare const INITIAL_STATE: PwaState;
+/**
+ * Applies one lifecycle event and returns the next state — the *same* object when nothing changes. That identity
+ * is load-bearing: `useSyncExternalStore` compares snapshots by reference and would re-render forever if a fresh
+ * object came back every time.
+ *
+ * `installed` and `update-applied` clear the flags for prompts the facade no longer offers: `appinstalled` drops
+ * the saved install prompt, and a controller change completes a previously announced update prompt. The other
+ * events never fall back to false, because the facade emits no cancellation event for them. `logout()` is the visible case: it returns a boolean
+ * without emitting anything, so `registered` stays true (spec: known limitations).
+ */
+export declare function reduce(state: PwaState, event: PwaClientEvent): PwaState;
+/** The five facade methods, taken from `PwaClient` so the signatures cannot drift from it. */
+export type PwaMethods = Pick<PwaClient, "register" | "promptInstall" | "applyUpdate" | "logout" | "checkForUpdate">;
+/**
+ * The message every method rejects with during server-side rendering. The Vue package carries the same text, and
+ * the server-side parity suite in examples-browser-e2e compares the two.
+ */
+export declare const SERVER_RENDERING_ERROR = "PWA methods are unavailable during server-side rendering: call them in the browser after hydration";
+/**
+ * What the binding hands out on the server (ADR-0016, 2026-09-17 amendment). There is no service worker, no install
+ * prompt and no facade there, so every method rejects at once — waiting for a facade that will never be attached
+ * would leave the call pending forever, and touching a browser API would throw something far less clear.
+ */
+export declare const SERVER_METHODS: PwaMethods;
+/**
+ * The message `PwaProvider` throws when both `client` and `updateCheck` are passed. The Vue package carries the
+ * same text (spec: 修订：主动检查更新, 框架绑定增量), and each package's test suite asserts it word for word.
+ */
+export declare const CLIENT_AND_UPDATE_CHECK_ERROR = "Cannot pass both client and updateCheck: an injected client is already built, so the binding has no way to configure its automatic update check";
+export type PwaStore = PwaMethods & {
+    /** `useSyncExternalStore`'s subscribe: the callback runs only when the snapshot actually changed. */
+    subscribe(onChange: () => void): () => void;
+    getSnapshot(): PwaState;
+    /**
+     * Binds a facade and starts tracking its events. Called from the provider's effect rather than during render,
+     * which is what StrictMode's deliberate mount → unmount → mount requires: each mount attaches a fresh facade
+     * and each cleanup detaches it, so a disposed facade is never reused.
+     */
+    attach(client: PwaClient): void;
+    /**
+     * Stops tracking and resets the state. The reset is the point: with no facade attached, the flags describe
+     * nothing. Leaving them set is what let a rebuilt provider show "registered" for a facade that had never
+     * registered. The facade itself is disposed by whoever created it.
+     */
+    detach(): void;
+};
+export declare function createStore(): PwaStore;
+/** The shape of `PwaProviderProps.updateCheck`, repeated here rather than imported to keep this file React-free. */
+type UpdateCheckOption = {
+    readonly intervalMs: number;
+};
+/**
+ * Creates (or takes) a facade, attaches it to the store, and returns the teardown. This is the entire body of the
+ * provider's effect, extracted so it can be unit tested without a renderer: the provider is then a one-liner with
+ * nowhere to hide a defect.
+ *
+ * `client` and `updateCheck` are positional optional parameters rather than fields on an options object on
+ * purpose. The caller holds them as `X | undefined` (they come from props), and under `exactOptionalPropertyTypes`
+ * an optional *property* rejects an explicitly passed `undefined`. Optional parameters carry no such restriction,
+ * so this avoids a `client?: PwaClient | undefined` signature that reads like a mistake.
+ *
+ * The returned teardown disposes the facade even when it was injected — the binding takes ownership for its
+ * lifetime, which keeps the Vue and React sides behaving alike. `PwaProvider` is responsible for rejecting a call
+ * that passes both `client` and `updateCheck` before this function is ever reached.
+ */
+export declare function bindFacade(store: PwaStore, config: PwaClientConfig, client?: PwaClient, updateCheck?: UpdateCheckOption): () => void;
+/**
+ * The provider's `useEffect` dependency list, extracted for the same reason as `bindFacade`: this package ships no
+ * renderer, so nothing inside the component itself has a unit test. What matters here is the *shape* of the list
+ * React compares with `Object.is` — in particular that `updateCheck` contributes its `intervalMs` field and not
+ * the option object itself. An application that passes a fresh `{ intervalMs }` literal on every render must not
+ * tear the facade down and rebuild it just because that object's identity changed, exactly as `config`'s fields
+ * are read individually rather than depending on the `config` object.
+ */
+export declare function providerEffectDeps(store: PwaStore, client: PwaClient | undefined, config: PwaClientConfig, updateCheck: UpdateCheckOption | undefined): readonly unknown[];
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAYA,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE1H,MAAM,MAAM,QAAQ,GAAG;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,wGAAwG;IACxG,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC,CAAC;AAIF,eAAO,MAAM,aAAa,EAAE,QAK1B,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,GAAG,QAAQ,CAqBvE;AAED,8FAA8F;AAC9F,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,eAAe,GAAG,aAAa,GAAG,QAAQ,GAAG,gBAAgB,CAAC,CAAC;AAErH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,uGAAuG,CAAC;AAM3I;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,UAM3B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,6BAA6B,oJACyG,CAAC;AAEpJ,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG;IAClC,qGAAqG;IACrG,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,WAAW,IAAI,QAAQ,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAAC;CAChB,CAAC;AAEF,wBAAgB,WAAW,IAAI,QAAQ,CAiFtC;AAED,oHAAoH;AACpH,KAAK,iBAAiB,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,SAAS,EAClB,WAAW,CAAC,EAAE,iBAAiB,GAC9B,MAAM,IAAI,CAYZ;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,iBAAiB,GAAG,SAAS,GACzC,SAAS,OAAO,EAAE,CAWpB"}

package/dist/store.js

@@ -0,0 +1,203 @@
+// The whole binding, in plain TypeScript with no React in sight: the state machine, the subscription, the five
+// forwarded methods, and the facade's lifetime. React's side is a provider that calls `bindFacade` from an effect
+// and a hook that reads a snapshot.
+//
+// The split is deliberate. `useSyncExternalStore` only runs inside a render, and this package ships no renderer
+// (spec: known limitations), so anything left in the component would have no unit test at all — and a defect did
+// hide there: the provider used to rebuild the facade whenever the `config` prop changed identity while the store
+// kept its old flags, so the UI read "registered" against a facade that had never registered. `bindFacade` exists
+// so that whole create → attach → detach → dispose cycle is testable without mounting anything.
+//
+// This is the React package's own copy of the state machine; the Vue package has its own and neither imports the
+// other. The parity suite compares their state sequences.
+import { createPwaClient } from "@pwa-platform/client-runtime";
+// Frozen, not merely `readonly`: it is a shared module-level object and every store starts from it, so a stray
+// write would change the starting state of every store created afterwards.
+export const INITIAL_STATE = Object.freeze({
+    registered: false,
+    installEligible: false,
+    installed: false,
+    updateWaiting: false,
+});
+/**
+ * Applies one lifecycle event and returns the next state — the *same* object when nothing changes. That identity
+ * is load-bearing: `useSyncExternalStore` compares snapshots by reference and would re-render forever if a fresh
+ * object came back every time.
+ *
+ * `installed` and `update-applied` clear the flags for prompts the facade no longer offers: `appinstalled` drops
+ * the saved install prompt, and a controller change completes a previously announced update prompt. The other
+ * events never fall back to false, because the facade emits no cancellation event for them. `logout()` is the visible case: it returns a boolean
+ * without emitting anything, so `registered` stays true (spec: known limitations).
+ */
+export function reduce(state, event) {
+    switch (event.type) {
+        case "registered":
+            return state.registered ? state : { ...state, registered: true };
+        case "install-eligible":
+            return state.installEligible ? state : { ...state, installEligible: true };
+        case "installed":
+            return state.installed && !state.installEligible
+                ? state
+                : { ...state, installed: true, installEligible: false };
+        case "update-waiting":
+            return state.updateWaiting ? state : { ...state, updateWaiting: true };
+        case "update-applied":
+            return state.updateWaiting ? { ...state, updateWaiting: false } : state;
+        default: {
+            // Every member of PwaClientEventType is handled above. Should client-runtime ever add one, this turns into a
+            // compile error here rather than a silently ignored event at runtime.
+            const unreachable = event.type;
+            return unreachable;
+        }
+    }
+}
+/**
+ * The message every method rejects with during server-side rendering. The Vue package carries the same text, and
+ * the server-side parity suite in examples-browser-e2e compares the two.
+ */
+export const SERVER_RENDERING_ERROR = "PWA methods are unavailable during server-side rendering: call them in the browser after hydration";
+function rejectOnServer() {
+    return Promise.reject(new Error(SERVER_RENDERING_ERROR));
+}
+/**
+ * What the binding hands out on the server (ADR-0016, 2026-09-17 amendment). There is no service worker, no install
+ * prompt and no facade there, so every method rejects at once — waiting for a facade that will never be attached
+ * would leave the call pending forever, and touching a browser API would throw something far less clear.
+ */
+export const SERVER_METHODS = Object.freeze({
+    register: rejectOnServer,
+    promptInstall: rejectOnServer,
+    applyUpdate: rejectOnServer,
+    logout: rejectOnServer,
+    checkForUpdate: rejectOnServer,
+});
+/**
+ * The message `PwaProvider` throws when both `client` and `updateCheck` are passed. The Vue package carries the
+ * same text (spec: 修订：主动检查更新, 框架绑定增量), and each package's test suite asserts it word for word.
+ */
+export const CLIENT_AND_UPDATE_CHECK_ERROR = "Cannot pass both client and updateCheck: an injected client is already built, so the binding has no way to configure its automatic update check";
+export function createStore() {
+    const listeners = new Set();
+    let state = INITIAL_STATE;
+    let client = null;
+    let unsubscribe = null;
+    /** Calls made while no facade is attached, released by the next `attach`. */
+    let waiters = [];
+    /**
+     * The attached facade — or, when none is attached yet, a promise for the next one.
+     *
+     * Waiting rather than throwing is what makes the binding usable from a child's mount effect. React runs effects
+     * child-first, so a component inside `PwaProvider` that registers on mount runs *before* the provider's own effect
+     * attaches the facade. Throwing here made that — the most natural way to write it — fail silently: the rejection
+     * was swallowed and nothing ever registered. The end-to-end suite caught it on its first real render.
+     *
+     * The same gap reopens under StrictMode's deliberate remount (detach, then children's effects, then attach again),
+     * so a call made after a detach waits too. A call made after the provider is gone for good never settles; the
+     * component that made it is gone as well, so no rejection is left unhandled.
+     */
+    function bound() {
+        if (client !== null)
+            return Promise.resolve(client);
+        return new Promise((resolve) => {
+            waiters.push(resolve);
+        });
+    }
+    /** A copy, so a listener that unsubscribes during delivery does not disturb this dispatch. */
+    function emit() {
+        for (const listener of [...listeners])
+            listener();
+    }
+    return {
+        subscribe(onChange) {
+            listeners.add(onChange);
+            return () => {
+                listeners.delete(onChange);
+            };
+        },
+        getSnapshot() {
+            return state;
+        },
+        attach(next) {
+            // A second attach without an intervening detach would otherwise leak the first subscription. The provider
+            // pairs them correctly today, but a store that leaks under misuse is a trap for the next caller.
+            unsubscribe?.();
+            client = next;
+            // Release every call that arrived before this facade did.
+            const released = waiters;
+            waiters = [];
+            for (const release of released)
+                release(next);
+            unsubscribe = next.subscribe((event) => {
+                const previous = state;
+                state = reduce(state, event);
+                // Notify only on a real change. Waking React for an event that changed nothing would re-render the tree
+                // for no reason, and `getSnapshot` would hand back the very same object anyway.
+                if (state !== previous)
+                    emit();
+            });
+        },
+        detach() {
+            unsubscribe?.();
+            unsubscribe = null;
+            client = null;
+            if (state !== INITIAL_STATE) {
+                state = INITIAL_STATE;
+                emit();
+            }
+        },
+        // Each call waits for a facade (see `bound`), then forwards unchanged: return values and rejections are the
+        // facade's own.
+        register: async () => (await bound()).register(),
+        promptInstall: async () => (await bound()).promptInstall(),
+        applyUpdate: async () => (await bound()).applyUpdate(),
+        logout: async () => (await bound()).logout(),
+        checkForUpdate: async () => (await bound()).checkForUpdate(),
+    };
+}
+/**
+ * Creates (or takes) a facade, attaches it to the store, and returns the teardown. This is the entire body of the
+ * provider's effect, extracted so it can be unit tested without a renderer: the provider is then a one-liner with
+ * nowhere to hide a defect.
+ *
+ * `client` and `updateCheck` are positional optional parameters rather than fields on an options object on
+ * purpose. The caller holds them as `X | undefined` (they come from props), and under `exactOptionalPropertyTypes`
+ * an optional *property* rejects an explicitly passed `undefined`. Optional parameters carry no such restriction,
+ * so this avoids a `client?: PwaClient | undefined` signature that reads like a mistake.
+ *
+ * The returned teardown disposes the facade even when it was injected — the binding takes ownership for its
+ * lifetime, which keeps the Vue and React sides behaving alike. `PwaProvider` is responsible for rejecting a call
+ * that passes both `client` and `updateCheck` before this function is ever reached.
+ */
+export function bindFacade(store, config, client, updateCheck) {
+    const facade = client ??
+        // Built conditionally, not `createPwaClient({ config, updateCheck })`: with `updateCheck` typed
+        // `UpdateCheckOption | undefined`, that object literal would write `X | undefined` into a property declared
+        // `updateCheck?: X`, which `exactOptionalPropertyTypes` rejects. The branch narrows it to `X`.
+        createPwaClient(updateCheck !== undefined ? { config, updateCheck } : { config });
+    store.attach(facade);
+    return () => {
+        store.detach();
+        facade.dispose();
+    };
+}
+/**
+ * The provider's `useEffect` dependency list, extracted for the same reason as `bindFacade`: this package ships no
+ * renderer, so nothing inside the component itself has a unit test. What matters here is the *shape* of the list
+ * React compares with `Object.is` — in particular that `updateCheck` contributes its `intervalMs` field and not
+ * the option object itself. An application that passes a fresh `{ intervalMs }` literal on every render must not
+ * tear the facade down and rebuild it just because that object's identity changed, exactly as `config`'s fields
+ * are read individually rather than depending on the `config` object.
+ */
+export function providerEffectDeps(store, client, config, updateCheck) {
+    return [
+        store,
+        client,
+        config.appId,
+        config.scope,
+        config.serviceWorkerUrl,
+        config.updateMode,
+        config.installEnabled,
+        updateCheck?.intervalMs,
+    ];
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pwa-platform/react",
+  "version": "0.1.0-beta.0",
+  "description": "React 19 binding for PWA Platform.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "dependencies": {
+    "@pwa-platform/client-runtime": "0.1.0-beta.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "react": "19.3.0",
+    "@pwa-platform/vue": "0.1.0-beta.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "tag": "next"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  }
+}