permdock 0.1.0 → 0.3.0

package/dist/react-native/index.js

@@ -1,14 +1,251 @@
 "use client";
 import { t as compact } from "../compact-y6vfu2_f.js";
-import { n as requiredPlans, t as describe } from "../describe-Bt1YD5uS.js";
-import { n as parseSnapshot } from "../snapshot-DE8dE_hz.js";
-import { t as emptySnapshot } from "../from-snapshot-BMGnhmgv.js";
-import { t as approvalHeaders } from "../headers-B5RRv3Xm.js";
-import { n as PermDockStoreContext } from "../context-gtAwAILx.js";
-import { a as useFilter, c as usePermission, d as useSubject, f as useTenant, i as useAssignableRoles, l as usePermissions, n as useApproval, o as useMemberships, r as useAssignablePermissions, s as usePermDock, t as Protected, u as useRoles } from "../protected-B4K3BKoX.js";
-import { t as createClientStore } from "../store-C6hFW6ta.js";
-import { useEffect, useMemo } from "react";
+import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+import { r as requiredPlans } from "../problem-details-_AMOYz-w.js";
+import { t as describe } from "../describe-B_gVZEVi.js";
+import { a as normalizeMemberships, d as scopeList, m as tenantOf$1, o as resolveScope } from "../scopes-CVdPrWN-.js";
+import { n as parseSnapshot, o as bindConditionRefs } from "../snapshot-Enxd0n-s.js";
+import { s as flattenGrantee } from "../grantee-Cv5Sogfv.js";
+import { p as resolveActiveTenant, u as nowSeconds } from "../validity-uOp8UpYn.js";
+import { n as isThenable } from "../thenable-okc2xDsj.js";
+import { r as heldRoleNames, t as emptySnapshot } from "../from-snapshot-CTLijvdm.js";
+import { t as parseLocalSnapshotManifest } from "../parse-local-manifest-BrMozJCo.js";
+import { t as approvalHeaders } from "../headers-BZSDieNT.js";
+import { n as storeOf, r as isJws, t as adapterStore } from "../store-options-ByhZq1jV.js";
+import { i as PermDockStoreContext, n as useKeyed, t as useLiveOptions } from "../live-options-H2eG8dfJ.js";
+import { a as useFilter, c as usePermission, d as useSubject, f as useTenant, i as useAssignableRoles, l as usePermissions, n as useApproval, o as useMemberships, r as useAssignablePermissions, s as usePermDock, t as Protected, u as useRoles } from "../protected-utU-SLuy.js";
+import { useEffect, useMemo, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
+//#region src/react-native/guards.ts
+/** `true` once the provider has a snapshot to answer from: storage was read or a seed was given. Hide the splash screen on it. */
+function useSnapshotReady() {
+	return usePermDock().status() !== "pending";
+}
+/**
+* A boolean for `Stack.Protected` and `Tabs.Protected`: `false` while the
+* snapshot is pending, `true` only when every permission is allowed for
+* `data`.
+*/
+function usePermissionGuard(permission, data) {
+	const permdock = usePermDock();
+	return useMemo(() => {
+		if (permdock.status() === "pending") return false;
+		const store = storeOf(permdock);
+		const list = Array.isArray(permission) ? permission : [permission];
+		return list.length > 0 && list.every((item) => store.permissionState(item, data).allowed);
+	}, [
+		permdock,
+		permission,
+		data
+	]);
+}
+//#endregion
+//#region src/react-native/local.ts
+const CARRIED = /* @__PURE__ */ new Set([
+	"id",
+	"roles",
+	"plans",
+	"tenant",
+	"memberships"
+]);
+function isClaimRef(ref) {
+	const [root, head] = ref.split(".", 2);
+	return root === "principal" && !CARRIED.has(String(head));
+}
+function bindGrant(grant, subject) {
+	const bind = (condition) => condition === void 0 ? void 0 : bindConditionRefs(condition, subject, isClaimRef);
+	return grant.where === void 0 && grant.check === void 0 ? grant : compact({
+		...grant,
+		where: bind(grant.where),
+		check: bind(grant.check)
+	});
+}
+function renamed(grant, name) {
+	const to = [];
+	for (const item of flattenGrantee(grant.to)) to.push(item.kind === "role" && item.role === "\0custom" ? {
+		kind: "role",
+		role: name,
+		scope: item.scope
+	} : item);
+	return {
+		...grant,
+		role: name,
+		to
+	};
+}
+/**
+* The grants a custom role holds, from the entries the server resolved one
+* by one: an entry the table does not know grants nothing.
+*/
+function customGrants(table, role) {
+	const entries = Array.isArray(role.grants) ? role.grants : [];
+	const removed = /* @__PURE__ */ new Set();
+	const allows = [];
+	for (const item of entries) {
+		if (item === null || typeof item !== "object") continue;
+		const entry = new Map(Object.entries(item));
+		const key = entry.get("permission");
+		if (typeof key !== "string") continue;
+		const effect = entry.get("effect") ?? "allow";
+		const level = entry.get("level");
+		const known = [...entry.keys()].every((name) => name === "permission" || name === "effect" || name === "level");
+		const row = Object.hasOwn(table.permissions, key) ? table.permissions[key] : void 0;
+		const unknownLevel = level !== void 0 && (typeof level !== "string" || row?.levels === void 0 || !Object.hasOwn(row.levels, level));
+		if (!known || effect !== "allow" || unknownLevel && row !== void 0) {
+			removed.add(key);
+			continue;
+		}
+		allows.push({
+			key,
+			level
+		});
+	}
+	const out = [];
+	const included = /* @__PURE__ */ new Set();
+	const names = Array.isArray(role.includes) ? role.includes : [];
+	for (const name of names) {
+		const list = typeof name === "string" && Object.hasOwn(table.includes, name) ? table.includes[name] : void 0;
+		for (const grant of list ?? []) {
+			if (grant.effect === "deny" || !removed.has(grant.permission)) out.push(grant);
+			if (grant.effect === "allow") included.add(grant.permission);
+		}
+	}
+	for (const { key, level } of allows) {
+		if (removed.has(key) || included.has(key)) continue;
+		const row = Object.hasOwn(table.permissions, key) ? table.permissions[key] : void 0;
+		const grants = typeof level === "string" ? row?.levels?.[level] : row?.all;
+		out.push(...grants ?? []);
+	}
+	return out.map((grant) => renamed(grant, role.name));
+}
+function isList(value) {
+	return Array.isArray(value);
+}
+function customScope(role, scopes) {
+	if (role.scope === "global") return "global";
+	if (role.scope !== void 0) return resolveScope(scopes, role.scope);
+	return role.team === void 0 ? scopes[0]?.name : scopes[1]?.name;
+}
+/**
+* The snapshot a server would send for `data`, built from the manifest. It
+* drives UI guards only: the server still decides every request.
+*/
+function buildLocalSnapshot(manifest, data, now = Math.floor(nowSeconds())) {
+	if (manifest === null || typeof manifest !== "object" || manifest.v !== 1 || !isList(manifest.grants)) throw new Error("PermDock: unsupported local snapshot manifest");
+	const scopes = scopeList(manifest.scopes);
+	const input = data.principal;
+	const memberships = input === null ? [] : normalizeMemberships(input.memberships, scopes);
+	const tenant = input === null ? void 0 : resolveActiveTenant({
+		id: input.id,
+		memberships
+	}, input.tenant, scopes, now);
+	const principal = input === null ? null : compact({
+		id: input.id,
+		roles: input.roles ?? [],
+		plans: input.plans,
+		tenant,
+		memberships
+	});
+	const subject = {
+		principal: principal === null ? null : {
+			...input?.attributes,
+			...principal
+		},
+		context: {}
+	};
+	const declared = new Set(manifest.roles);
+	const globalRoles = new Set(input?.roles ?? []);
+	const grants = [];
+	const attach = (grant, membership) => {
+		grants.push(bindGrant(membership === void 0 ? grant : {
+			...grant,
+			membership
+		}, subject));
+	};
+	for (const grant of manifest.grants) {
+		const roleItems = flattenGrantee(grant.to).filter((item) => item.kind === "role");
+		if (roleItems.length > 0 && principal === null) continue;
+		if (!roleItems.every((item) => item.scope !== "global" || declared.has(item.role) && globalRoles.has(item.role))) continue;
+		const scoped = roleItems.filter((item) => item.scope !== "global");
+		if (scoped.length === 0) {
+			attach(grant);
+			continue;
+		}
+		for (const membership of memberships) if (scoped.every((item) => declared.has(item.role) && membership.roles.includes(item.role) && (typeof item.scope === "string" ? membership.scope === item.scope : membership.on !== void 0))) attach(grant, membership);
+	}
+	const custom = (data.customRoles ?? []).filter((role) => role !== null && typeof role === "object" && typeof role.name === "string" && !declared.has(role.name));
+	for (const role of custom) {
+		const scope = customScope(role, scopes);
+		const table = scope !== void 0 && Object.hasOwn(manifest.custom, scope) ? manifest.custom[scope] : void 0;
+		if (scope === void 0 || table === void 0) continue;
+		const resolved = customGrants(table, role);
+		if (scope === "global") {
+			if (role.tenant === void 0 && globalRoles.has(role.name)) for (const grant of resolved) attach(grant);
+			continue;
+		}
+		const id = role.team ?? role.id;
+		for (const membership of memberships) if (membership.scope === scope && typeof role.tenant === "string" && tenantOf$1(membership, scopes) === role.tenant && (id === void 0 || membership.id === id) && membership.roles.includes(role.name)) for (const grant of resolved) attach(grant, membership);
+	}
+	const roles = subject.principal === null ? [] : heldRoleNames(subject, tenant, scopes, { rank: manifest.rank ?? [] }, now);
+	return freezeDeep(compact({
+		v: 1,
+		issuedAt: now,
+		subject: {
+			principal,
+			context: {}
+		},
+		roles,
+		grants,
+		tenants: tenant === void 0 ? [] : [tenant],
+		scopes: manifest.scopes,
+		vocabulary: manifest.vocabulary
+	}));
+}
+/**
+* A snapshot source over the device's own membership rows (SQLite, a
+* PowerSync or Electric replica): offline, the UI guards answer from them.
+*/
+function localSnapshot(options) {
+	return compact({
+		get: async () => buildLocalSnapshot(options.manifest, await options.read()),
+		subscribe: options.subscribe
+	});
+}
+//#endregion
+//#region src/react-native/powersync.ts
+/**
+* A `localSnapshot` source over a PowerSync database: `get` runs every query
+* with `db.getAll`, and a `db.watch` per query reports changes. A watch
+* result with unchanged content re-renders nothing (`connectSource`). The source
+* takes the database as an argument; `permdock/react-native` never imports
+* `@powersync/*`.
+*/
+function powersyncSource(db, options) {
+	const names = Object.keys(options.queries);
+	return localSnapshot({
+		manifest: options.manifest,
+		read: async () => {
+			const results = await Promise.all(names.map(async (name) => {
+				const query = options.queries[name];
+				return [name, await db.getAll(query.sql, [...query.parameters ?? []])];
+			}));
+			const rows = {};
+			for (const [name, list] of results) rows[name] = list;
+			return options.read(rows);
+		},
+		subscribe: (listener) => {
+			const controller = new AbortController();
+			for (const name of names) {
+				const query = options.queries[name];
+				db.watch(query.sql, [...query.parameters ?? []], { onResult: listener }, { signal: controller.signal });
+			}
+			return () => {
+				controller.abort();
+			};
+		}
+	});
+}
+//#endregion
 //#region src/react-native/storage.ts
 const SNAPSHOT_KEY = "permdock.snapshot";
 const TENANT_KEY = "permdock.tenant";
@@ -26,67 +263,181 @@ function memoryStorage(initial = {}) {
 		}
 	};
 }
-function isThenable(value) {
-	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
-}
-function acceptSnapshot(raw, subjectId) {
-	if (raw === null || raw.length === 0) return;
+const NOTHING = {
+	stored: void 0,
+	tenant: void 0
+};
+/**
+* A persisted snapshot the device may use: `subjectId`'s own, and signed
+* whenever a verifier is configured, so a copy edited on the device never
+* stands in for a signed one. `null` reads nothing.
+*/
+function acceptStored(raw, subjectId, signed) {
+	if (raw === null || raw.length === 0 || subjectId === null) return;
+	if (isJws(raw)) return signed ? {
+		kind: "signed",
+		jws: raw
+	} : void 0;
+	if (signed) return;
 	try {
-		const parsed = JSON.parse(raw);
-		const snapshot = parseSnapshot(parsed);
-		const id = snapshot.subject.principal?.id;
-		if (subjectId !== void 0 && id !== subjectId) return;
-		return snapshot;
+		const snapshot = parseSnapshot(JSON.parse(raw));
+		return snapshot.subject.principal?.id === subjectId ? {
+			kind: "snapshot",
+			snapshot
+		} : void 0;
 	} catch {
 		return;
 	}
 }
-async function readStored(storage, subjectId) {
-	const raw = await Promise.resolve(storage.getItem(SNAPSHOT_KEY));
-	const tenantRaw = await Promise.resolve(storage.getItem(TENANT_KEY));
+function tenantOf(raw) {
+	return raw === null || raw.length === 0 ? void 0 : raw;
+}
+/** The tenant is read only alongside an accepted snapshot. */
+function storedRead(raw, tenantRaw, subjectId, signed) {
+	const stored = acceptStored(raw, subjectId, signed);
 	return {
-		snapshot: acceptSnapshot(raw, subjectId),
-		tenant: tenantRaw === null || tenantRaw.length === 0 ? void 0 : tenantRaw
+		stored,
+		tenant: stored === void 0 ? void 0 : tenantOf(tenantRaw)
 	};
 }
-function readStoredSync(storage, subjectId) {
-	const raw = storage.getItem(SNAPSHOT_KEY);
-	const tenantRaw = storage.getItem(TENANT_KEY);
-	if (isThenable(raw) || isThenable(tenantRaw)) return;
+function guardStorage(storage) {
+	let warned = false;
+	const fail = (error) => {
+		if (!(Reflect.get(globalThis, "__DEV__") === true) || warned) return;
+		warned = true;
+		console.warn("PermDock: the snapshot storage failed; guards answer from memory until it works again.", error);
+	};
+	const settle = (run) => {
+		try {
+			const result = run();
+			if (isThenable(result)) Promise.resolve(result).catch(fail);
+		} catch (error) {
+			fail(error);
+		}
+	};
 	return {
-		snapshot: acceptSnapshot(raw, subjectId),
-		tenant: tenantRaw === null || tenantRaw.length === 0 ? void 0 : tenantRaw
+		read(key) {
+			try {
+				return storage.getItem(key);
+			} catch (error) {
+				fail(error);
+				return null;
+			}
+		},
+		write(key, value) {
+			settle(() => storage.setItem(key, value));
+		},
+		remove(key) {
+			settle(() => storage.removeItem(key));
+		},
+		fail
 	};
 }
-function persistSnapshot(storage, snapshot, tenant) {
-	const write = storage.setItem(SNAPSHOT_KEY, JSON.stringify(snapshot));
-	if (isThenable(write)) write.catch(() => void 0);
-	if (tenant === void 0) return;
-	const next = storage.setItem(TENANT_KEY, tenant);
-	if (isThenable(next)) next.catch(() => void 0);
+/** `undefined` when the storage answers asynchronously; any failure reads as empty. */
+function readStoredSync(storage, subjectId, signed) {
+	if (subjectId === null) return NOTHING;
+	const raw = storage.read(SNAPSHOT_KEY);
+	const tenantRaw = storage.read(TENANT_KEY);
+	if (isThenable(raw) || isThenable(tenantRaw)) return;
+	return storedRead(raw, tenantRaw, subjectId, signed);
+}
+async function readStored(storage, subjectId, signed) {
+	if (subjectId === null) return NOTHING;
+	try {
+		const [raw, tenantRaw] = await Promise.all([Promise.resolve(storage.read(SNAPSHOT_KEY)), Promise.resolve(storage.read(TENANT_KEY))]);
+		return storedRead(raw, tenantRaw, subjectId, signed);
+	} catch (error) {
+		storage.fail(error);
+		return NOTHING;
+	}
+}
+/** Writes `raw` (the snapshot JSON or its JWS) and the tenant. */
+function persistSnapshot(storage, raw, tenant) {
+	storage.write(SNAPSHOT_KEY, raw);
+	if (tenant !== void 0) storage.write(TENANT_KEY, tenant);
 }
 function clearStorage(storage) {
-	const snap = storage.removeItem(SNAPSHOT_KEY);
-	if (isThenable(snap)) snap.catch(() => void 0);
-	const tenant = storage.removeItem(TENANT_KEY);
-	if (isThenable(tenant)) tenant.catch(() => void 0);
+	storage.remove(SNAPSHOT_KEY);
+	storage.remove(TENANT_KEY);
 }
 //#endregion
 //#region src/react-native/store.ts
-function isJws(value) {
-	const parts = value.split(".");
-	return parts.length === 3 && parts.every((part) => part.length > 0);
+/** The snapshot's content without `issuedAt`, which every local rebuild changes. */
+function contentKey(snapshot) {
+	return JSON.stringify({
+		...snapshot,
+		issuedAt: 0
+	});
+}
+/**
+* Whether a source read changes nothing: same content as the snapshot the
+* store holds, and the store already settled on it.
+*/
+function unchanged(store, next) {
+	if (typeof next === "string" || store.get().status() === "stale") return false;
+	try {
+		return contentKey(parseSnapshot(next)) === contentKey(store.snapshot());
+	} catch {
+		return false;
+	}
+}
+/**
+* Hydrates `store` from `source` now, on every change it reports and on each
+* return to the foreground. Only the latest read applies; a read with
+* unchanged content re-renders nothing, and a failed read keeps the current
+* snapshot. Returns the unsubscribe.
+*/
+function connectSource(store, source, subscribeForeground) {
+	let active = true;
+	let seq = 0;
+	const pull = () => {
+		seq += 1;
+		const mine = seq;
+		Promise.resolve().then(() => source.get()).then((next) => {
+			if (active && mine === seq && !unchanged(store, next)) store.replace(next);
+		}, () => void 0);
+	};
+	pull();
+	const unsubscribe = source.subscribe?.(pull);
+	const offForeground = subscribeForeground?.((next) => {
+		if (next !== false) pull();
+	});
+	return () => {
+		active = false;
+		unsubscribe?.();
+		offForeground?.();
+	};
+}
+function seedOf(stored) {
+	if (stored === void 0) return;
+	return stored.kind === "signed" ? stored.jws : stored.snapshot;
+}
+function belongsTo(snapshot, subjectId) {
+	return subjectId !== null && snapshot.subject.principal?.id === subjectId;
+}
+/** A JWS stays a string for the verifier; anything else parses or is dropped. */
+function parseSeed(given) {
+	if (given === void 0) return;
+	if (typeof given === "string" && isJws(given)) return given;
+	try {
+		return parseSnapshot(typeof given === "string" ? JSON.parse(given) : given);
+	} catch {
+		return;
+	}
 }
 function createNativeStore(options) {
-	const signed = typeof options.snapshot === "string" && isJws(options.snapshot) ? options.snapshot : void 0;
-	const seeded = options.snapshot === void 0 || signed !== void 0 ? void 0 : typeof options.snapshot === "string" ? acceptSnapshot(options.snapshot, options.subjectId) : acceptSnapshot(JSON.stringify(options.snapshot), options.subjectId);
-	const sync = signed === void 0 ? readStoredSync(options.storage, options.subjectId) : void 0;
-	const snapshot = signed ?? seeded ?? sync?.snapshot ?? emptySnapshot();
-	const tenant = options.tenant ?? sync?.tenant;
+	const storage = guardStorage(options.storage);
+	const signed = options.verifier !== void 0;
+	const revalidates = options.snapshotUrl !== void 0 || options.source !== void 0;
+	const seeded = parseSeed(options.snapshot);
+	const carried = options.previous !== void 0 && belongsTo(options.previous.snapshot(), options.subjectId) ? options.previous : void 0;
+	const sync = seeded === void 0 && carried === void 0 ? readStoredSync(storage, options.subjectId, signed) : void 0;
+	const waiting = seeded === void 0 && carried === void 0 && sync === void 0;
+	const fromStorage = seedOf(sync?.stored);
+	const snapshot = seeded ?? carried?.snapshot() ?? fromStorage ?? emptySnapshot();
+	const tenant = options.tenant ?? carried?.tenant() ?? sync?.tenant ?? void 0;
 	let booted = false;
-	let touched = false;
-	const store = createClientStore(compact({
-		snapshot,
+	const store = adapterStore(compact({
 		endpoint: options.endpoint,
 		snapshotUrl: options.snapshotUrl,
 		approvals: options.approvals,
@@ -95,75 +446,137 @@ function createNativeStore(options) {
 		headers: options.headers,
 		maxAge: options.maxAge,
 		verifier: options.verifier,
+		awaiting: waiting,
+		passCache: true
+	}), snapshot, {
 		server: false,
-		onSnapshot: (next, nextTenant) => {
-			if (!booted) return;
-			touched = true;
-			persistSnapshot(options.storage, next, nextTenant);
+		stale: revalidates && (fromStorage !== void 0 || waiting),
+		onSnapshot: (next, nextTenant, raw) => {
+			if (!booted || !belongsTo(next, options.subjectId)) return;
+			if (signed && raw === void 0) return;
+			persistSnapshot(storage, raw ?? JSON.stringify(next), nextTenant);
 		},
 		onClear: () => {
-			touched = true;
-			clearStorage(options.storage);
+			clearStorage(storage);
 		}
-	}));
-	booted = true;
-	if (seeded !== void 0) persistSnapshot(options.storage, seeded, tenant);
-	if (sync === void 0 && seeded === void 0 && signed === void 0) readStored(options.storage, options.subjectId).then((stored) => {
-		if (!touched && stored.snapshot !== void 0) store.replace(stored.snapshot);
 	});
+	booted = true;
+	if (seeded !== void 0 && typeof seeded !== "string") {
+		if (belongsTo(seeded, options.subjectId)) persistSnapshot(storage, JSON.stringify(seeded), tenant);
+	} else if (seeded !== void 0 && signed) persistSnapshot(storage, seeded, tenant);
+	if (options.subjectId === null) clearStorage(storage);
+	if (waiting) {
+		let storedTenant;
+		const read = readStored(storage, options.subjectId, signed).then(({ stored, tenant: persisted }) => {
+			const value = seedOf(stored);
+			if (value === void 0) throw new Error("nothing stored");
+			storedTenant = persisted;
+			return value;
+		});
+		store.track(read);
+		read.then(() => {
+			if (options.tenant === void 0 && storedTenant !== void 0 && store.tenant() !== storedTenant && store.snapshot().tenants.includes(storedTenant)) store.get().refresh({ tenant: storedTenant });
+		}, () => void 0);
+	}
 	return store;
 }
 //#endregion
 //#region src/react-native/provider.tsx
 function PermDockProvider(props) {
-	const store = useMemo(() => createNativeStore(compact({
+	const live = useLiveOptions(props, false);
+	const shown = useRef(null);
+	const store = useKeyed(() => createNativeStore(compact({
 		storage: props.storage,
+		subjectId: props.subjectId,
 		snapshot: props.snapshot,
 		snapshotUrl: props.snapshotUrl,
+		source: props.source,
 		endpoint: props.endpoint,
 		approvals: props.approvals,
 		tenant: props.tenant,
-		subjectId: props.subjectId,
-		revalidate: props.revalidate,
-		subscribeForeground: props.subscribeForeground,
-		fetch: props.fetch,
-		headers: props.headers,
+		fetch: live.fetch,
+		headers: live.readHeaders,
 		maxAge: props.maxAge,
-		verifier: props.verifier
+		verifier: live.verifier,
+		previous: shown.current ?? void 0
 	})), [
 		props.storage,
+		props.subjectId,
 		props.snapshot,
 		props.snapshotUrl,
+		props.source,
 		props.endpoint,
 		props.approvals,
 		props.tenant,
-		props.subjectId,
-		props.revalidate,
-		props.subscribeForeground,
-		props.fetch,
-		props.headers,
+		live.fetch,
 		props.maxAge,
-		props.verifier
+		live.verifier
 	]);
 	useEffect(() => {
+		const previous = shown.current;
+		shown.current = store;
+		if (previous !== null && previous !== store) previous.dispose();
+	}, [store]);
+	useEffect(() => props.source === void 0 ? void 0 : connectSource(store, props.source, props.subscribeForeground), [
+		store,
+		props.source,
+		props.subscribeForeground
+	]);
+	useEffect(() => {
+		if (props.snapshotUrl === void 0) return;
 		const mode = props.revalidate ?? "launch";
+		let inFlight = false;
+		let online = true;
+		let active = true;
+		let timer;
 		const refresh = () => {
-			if (props.snapshotUrl === void 0) return;
-			store.get().refresh().catch(() => void 0);
+			if (inFlight || !online) return;
+			inFlight = true;
+			store.get().refresh().catch(() => void 0).finally(() => {
+				inFlight = false;
+			});
 		};
-		if (mode === "launch" || mode === "focus" || typeof mode === "number") refresh();
-		if (typeof mode === "number") {
-			const timer = setInterval(refresh, mode * 1e3);
-			return () => {
+		const startTimer = () => {
+			if (typeof mode === "number" && timer === void 0) timer = setInterval(refresh, mode * 1e3);
+		};
+		const stopTimer = () => {
+			if (timer !== void 0) {
 				clearInterval(timer);
-			};
-		}
-		if (mode === "focus" && props.subscribeForeground !== void 0) return props.subscribeForeground(refresh);
+				timer = void 0;
+			}
+		};
+		refresh();
+		startTimer();
+		const offForeground = props.subscribeForeground?.((next) => {
+			const now = next !== false;
+			if (now === active) {
+				if (now && mode === "focus") refresh();
+				return;
+			}
+			active = now;
+			if (!active) {
+				stopTimer();
+				return;
+			}
+			startTimer();
+			if (mode === "focus" || typeof mode === "number") refresh();
+		});
+		const offOnline = props.subscribeOnline?.((next) => {
+			const back = next && !online;
+			online = next;
+			if (back && active) refresh();
+		});
+		return () => {
+			stopTimer();
+			offForeground?.();
+			offOnline?.();
+		};
 	}, [
 		store,
 		props.revalidate,
 		props.snapshotUrl,
-		props.subscribeForeground
+		props.subscribeForeground,
+		props.subscribeOnline
 	]);
 	return /* @__PURE__ */ jsx(PermDockStoreContext, {
 		value: store,
@@ -171,4 +584,113 @@ function PermDockProvider(props) {
 	});
 }
 //#endregion
-export { PermDockProvider, Protected, approvalHeaders, createNativeStore, describe, memoryStorage, requiredPlans, useApproval, useAssignablePermissions, useAssignableRoles, useFilter, useMemberships, usePermDock, usePermission, usePermissions, useRoles, useSubject, useTenant };
+//#region src/react-native/storage-adapters.ts
+/** SecureStore warns above 2048 bytes and may refuse larger values on some devices. */
+const SECURE_STORE_CHUNK_BYTES = 2048;
+const INDEX_PREFIX = "permdock-chunks:";
+function utf8Length(char) {
+	const point = char.codePointAt(0) ?? 0;
+	if (point < 128) return 1;
+	if (point < 2048) return 2;
+	return point < 65536 ? 3 : 4;
+}
+function split(value, max) {
+	const out = [];
+	let current = "";
+	let bytes = 0;
+	for (const char of value) {
+		const size = utf8Length(char);
+		if (bytes + size > max) {
+			out.push(current);
+			current = "";
+			bytes = 0;
+		}
+		current += char;
+		bytes += size;
+	}
+	out.push(current);
+	return out;
+}
+function chunkCount(index) {
+	if (index?.startsWith(INDEX_PREFIX) !== true) return;
+	const count = Number(index.slice(16));
+	return Number.isSafeInteger(count) && count > 0 ? count : void 0;
+}
+function chunkKey(key, index) {
+	return `${key}.${index}`;
+}
+/**
+* A `PermDockStorage` over `expo-secure-store`. Values are split into chunks
+* of at most 2048 bytes under `<key>.<n>`; `<key>` holds the chunk count and
+* is written last, so an interrupted write reads as absent.
+*/
+function secureStoreStorage(store, options) {
+	const removeChunks = async (key, from, to) => {
+		for (let index = from; index < to; index += 1) await store.deleteItemAsync(chunkKey(key, index), options);
+	};
+	return {
+		getItem: (key) => {
+			const count = chunkCount(store.getItem(key, options));
+			if (count === void 0) return null;
+			let value = "";
+			for (let index = 0; index < count; index += 1) {
+				const part = store.getItem(chunkKey(key, index), options);
+				if (part === null) return null;
+				value += part;
+			}
+			return value;
+		},
+		setItem: async (key, value) => {
+			const before = chunkCount(store.getItem(key, options)) ?? 0;
+			await store.deleteItemAsync(key, options);
+			const parts = split(value, SECURE_STORE_CHUNK_BYTES);
+			for (const [index, part] of parts.entries()) store.setItem(chunkKey(key, index), part, options);
+			store.setItem(key, `${INDEX_PREFIX}${parts.length}`, options);
+			await removeChunks(key, parts.length, before);
+		},
+		removeItem: async (key) => {
+			const before = chunkCount(store.getItem(key, options)) ?? 0;
+			await store.deleteItemAsync(key, options);
+			await removeChunks(key, 0, before);
+		}
+	};
+}
+/** A synchronous `PermDockStorage` over a `react-native-mmkv` instance: the first frame already has the snapshot. */
+function mmkvStorage(mmkv) {
+	return {
+		getItem: (key) => mmkv.getString(key) ?? null,
+		setItem: (key, value) => {
+			mmkv.set(key, value);
+		},
+		removeItem: (key) => {
+			if ("remove" in mmkv) mmkv.remove(key);
+			else mmkv.delete(key);
+		}
+	};
+}
+//#endregion
+//#region src/react-native/subscriptions.ts
+/**
+* `subscribeForeground` over `AppState`: `active` returns to the foreground
+* and `background` leaves it. iOS `inactive` (a system sheet over the app) is
+* neither.
+*/
+function appStateForeground(appState) {
+	return (listener) => {
+		const subscription = appState.addEventListener("change", (state) => {
+			if (state === "active") listener(true);
+			else if (state === "background") listener(false);
+		});
+		return () => {
+			subscription.remove();
+		};
+	};
+}
+/** `subscribeOnline` over NetInfo. An unknown (`null`) connection counts as online. */
+function netInfoOnline(netInfo) {
+	return (listener) => netInfo.addEventListener((state) => {
+		listener(state.isConnected !== false && state.isInternetReachable !== false);
+	});
+}
+//#endregion
+export { PermDockProvider, Protected, appStateForeground, approvalHeaders, buildLocalSnapshot, connectSource, createNativeStore, describe, localSnapshot, memoryStorage, mmkvStorage, netInfoOnline, parseLocalSnapshotManifest, powersyncSource, requiredPlans, secureStoreStorage, useApproval, useAssignablePermissions, useAssignableRoles, useFilter, useMemberships, usePermDock, usePermission, usePermissionGuard, usePermissions, useRoles, useSnapshotReady, useSubject, useTenant };