permdock 0.3.1 → 0.5.0

package/dist/principal-source-pHneukrx.js

@@ -0,0 +1,103 @@
+import { t as freezeCopy } from "./freeze-CrU8nQeX.js";
+import { a as ownRecord } from "./paths-DXSHAMIa.js";
+//#region src/core/principal-source.ts
+function nonEmpty(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+/**
+* A `PrincipalIdentity` in the form sources compare: an email trimmed and
+* lower-cased with no provider or workspace, a chat identity with a
+* provider. Anything else, inherited fields included, is `undefined`.
+*/
+function normalizeIdentity(value) {
+	const record = ownRecord(value);
+	const kind = record?.["kind"];
+	const raw = record?.["value"];
+	if (record === void 0 || !nonEmpty(raw)) return;
+	if (kind === "email") return Object.freeze({
+		kind,
+		value: raw.trim().toLowerCase()
+	});
+	if (kind !== "chat") return;
+	const provider = record["provider"];
+	const workspace = record["workspace"];
+	if (!nonEmpty(provider) || workspace !== void 0 && !nonEmpty(workspace)) return;
+	return Object.freeze({
+		kind,
+		provider,
+		value: raw,
+		...workspace === void 0 ? {} : { workspace }
+	});
+}
+function identityKey(identity) {
+	return JSON.stringify([
+		identity.kind,
+		identity.provider ?? null,
+		identity.workspace ?? null,
+		identity.value
+	]);
+}
+function principalWithId(found, id) {
+	const foundId = ownRecord(found)?.["id"];
+	if (!nonEmpty(foundId) || id !== void 0 && foundId !== id) return null;
+	return found;
+}
+/**
+* `source.principal(id, { tenant })`, failing closed: no source, `null`, a
+* throw, a rejection or a principal with another id is `null`.
+*/
+async function loadPrincipal(source, id, tenant) {
+	if (source === void 0 || !nonEmpty(id)) return null;
+	try {
+		return principalWithId(await source.principal(id, tenant === void 0 ? {} : { tenant }), id);
+	} catch {
+		return null;
+	}
+}
+/**
+* `source.principalByIdentity(identity)` over the normalised identity,
+* failing closed: no source or method, an invalid identity, `null`, a throw
+* or a rejection is `null`.
+*/
+async function loadPrincipalByIdentity(source, identity) {
+	const normalized = normalizeIdentity(identity);
+	if (source?.principalByIdentity === void 0 || normalized === void 0) return null;
+	try {
+		return principalWithId(await source.principalByIdentity(normalized));
+	} catch {
+		return null;
+	}
+}
+/**
+* In-process principals for tests and single-replica apps. `identities`
+* links an email or chat identity to a principal id; each answer is a fresh
+* frozen copy. `tenant` is not a filter, as for a database source.
+*/
+function memoryPrincipalSource(input) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const principal of input.principals) {
+		if (!nonEmpty(principal.id) || byId.has(principal.id)) throw new TypeError("PermDock: memoryPrincipalSource needs a unique, non-empty id per principal");
+		byId.set(principal.id, principal);
+	}
+	const links = /* @__PURE__ */ new Map();
+	for (const link of input.identities ?? []) {
+		const identity = normalizeIdentity(link.identity);
+		if (identity === void 0 || !nonEmpty(link.principal)) throw new TypeError("PermDock: memoryPrincipalSource identities link an email or chat identity to a principal id");
+		links.set(identityKey(identity), link.principal);
+	}
+	const copyOf = (id) => {
+		const found = id === void 0 ? void 0 : byId.get(id);
+		return found === void 0 ? null : freezeCopy(structuredClone(found));
+	};
+	return Object.freeze({
+		principal(id) {
+			return copyOf(id);
+		},
+		principalByIdentity(identity) {
+			const normalized = normalizeIdentity(identity);
+			return normalized === void 0 ? null : copyOf(links.get(identityKey(normalized)));
+		}
+	});
+}
+//#endregion
+export { loadPrincipalByIdentity as n, memoryPrincipalSource as r, loadPrincipal as t };

package/dist/prisma/index.d.ts

@@ -1,4 +1,5 @@
-import { Ir as Condition, Pr as Subject, mn as WhereResult } from "../policy-IB6yxpC3.js";
+import { Rt as Instant, ir as Subject, lr as Condition } from "../policy-types-DzwivBgR.js";
+import { c as WhereResult } from "../permdock-D7eeLJER.js";
 import { r as RelationsMapping } from "../graph-sql-B-dsAT6j.js";
 import { n as WithSubjectOptions, t as RowCheck } from "../row-check-Dt35czLy.js";
 //#region src/prisma/model-fields.d.ts
@@ -29,7 +30,8 @@ export declare function prismaModelFields(datamodel: string | PrismaDatamodel, m
 type PrismaWhereOptions = {
   readonly fields?: Readonly<Record<string, string>>;
   readonly subject?: Subject;
-  readonly now?: number;
+  /** The clock membership expiry is read at; a `Temporal.Instant` fits. Defaults to the current time. */
+  readonly now?: Instant;
   readonly listFields?: readonly string[];
   readonly requiredFields?: readonly string[];
   /** Required and list fields read from the schema by `prismaModelFields`; adds to `requiredFields` and `listFields`. */
@@ -93,7 +95,8 @@ type PrismaCombinators = {
 type PrismaPredicateOptions = {
   readonly fields?: Readonly<Record<string, string>>;
   readonly subject?: Subject;
-  readonly now?: number;
+  /** The clock membership expiry is read at; a `Temporal.Instant` fits. Defaults to the current time. */
+  readonly now?: Instant;
   /** Required and list fields from `prismaModelFields`; `contains` on a list field is refused. */
   readonly model?: PrismaModelFields;
   readonly listFields?: readonly string[];

package/dist/prisma/index.js

@@ -1,9 +1,9 @@
-import { t as compact } from "../compact-y6vfu2_f.js";
+import { t as compact } from "../compact-CAf557ZB.js";
 import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
-import { w as assertSafeKey } from "../permissions-DVoF6dMt.js";
-import { n as PermDockValidationError } from "../validation-error-CnjZ4t92.js";
-import { a as relatedRowGuard, l as renderGraphSql, n as escapeLike, s as relatedTargetsSql, t as compileWhere, u as restrictedRowsSql } from "../compile-Ba4blROR.js";
-import { a as rowCheckOf, n as statementText, r as subjectStatements } from "../subject-settings-BwBmCdTR.js";
+import { t as assertSafeKey } from "../paths-DXSHAMIa.js";
+import { n as PermDockValidationError } from "../validation-error-ZfUHbKvf.js";
+import { a as relatedRowGuard, l as renderGraphSql, n as escapeLike, s as relatedTargetsSql, t as compileWhere, u as restrictedRowsSql } from "../compile-CMqMx_IN.js";
+import { n as statementText, o as rowCheckOf, r as subjectStatements, s as loadPeer } from "../subject-settings-CkEwrw3W.js";
 //#region src/prisma/to-where.ts
 function fieldTests(options) {
 	const mapped = (field) => fieldName(field, options.fields);
@@ -165,13 +165,7 @@ async function checkRow(delegate, input, unique, options = {}) {
 //#region src/prisma/predicate.ts
 function loadCombinators(injected) {
 	if (injected !== void 0) return injected;
-	const loader = globalThis.process?.getBuiltinModule?.("node:module");
-	try {
-		if (loader === void 0) throw new Error("no module loader");
-		return loader.createRequire(import.meta.url)("@prisma/orm-postgres/orm-client");
-	} catch {
-		throw new Error("PermDock: toPredicate needs @prisma/orm-postgres; pass `combinators` on runtimes without require");
-	}
+	return loadPeer("@prisma/orm-postgres/orm-client", "PermDock: toPredicate needs @prisma/orm-postgres; pass `combinators` on runtimes without require");
 }
 function refused$1(detail) {
 	return new PermDockValidationError({

package/dist/{problem-B43ztKIm.js → problem-CTviyH5L.js}

@@ -1,7 +1,9 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
-import { n as PermDockValidationError, t as PROBLEM_BASE } from "./validation-error-CnjZ4t92.js";
-import { i as stepUpOf, n as problemDetails, t as notFoundDetails } from "./problem-details-_AMOYz-w.js";
-import { a as deniedMessage, i as approvalMessage } from "./errors-Cz5zn0mW.js";
+import { t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { n as PermDockValidationError } from "./validation-error-ZfUHbKvf.js";
+import { a as problemType, i as stepUpOf, n as problemDetails, o as statusProblem, t as notFoundDetails } from "./problem-details-cn5X30gZ.js";
+import { a as deniedMessage, i as approvalMessage } from "./errors-BKy0EfhN.js";
+import { a as durationOf, g as secondsOf, p as nowSeconds } from "./time-DkWjdL98.js";
 //#region src/server/problem.ts
 function quoted(value) {
 	return `"${value.replaceAll(/["\\]/gu, "")}"`;
@@ -66,16 +68,11 @@ function problemResponse(details, permission, decision, extra, credentials) {
 }
 /** RFC 9457 413 for a batch over `max` evaluations. */
 function batchTooLarge(max) {
-	return problemResponse({
-		type: `${PROBLEM_BASE}/payload-too-large`,
-		title: "Payload too large",
-		status: 413,
-		detail: `evaluations batch exceeds ${String(max)}`
-	});
+	return problemResponse(statusProblem(413, `evaluations batch exceeds ${String(max)}`));
 }
 function validationProblem(detail) {
 	return problemResponse(compact({
-		type: `${PROBLEM_BASE}/validation`,
+		type: problemType("validation"),
 		title: "Invalid request",
 		status: 400,
 		detail
@@ -86,14 +83,14 @@ function resourceRef(permission) {
 }
 function isLimitDetail(value) {
 	if (value === null || typeof value !== "object") return false;
-	const { count, window, resetsAt } = value;
-	return Number.isFinite(count) && Number.isFinite(window) && Number.isFinite(resetsAt);
+	const { count, per, resetsAt } = value;
+	return Number.isFinite(count) && durationOf(per) !== void 0 && secondsOf(resetsAt) !== void 0;
 }
 /**
 * `Retry-After` plus the `RateLimit` / `RateLimit-Policy` fields of
 * draft-ietf-httpapi-ratelimit-headers-11, one policy per exhausted grant.
 */
-function rateLimitHeaders(decision, now = Date.now() / 1e3) {
+function rateLimitHeaders(decision, now) {
 	if (decision.outcome !== "denied") return {};
 	const policies = /* @__PURE__ */ new Map();
 	for (const denial of decision.denials) {
@@ -105,12 +102,12 @@ function rateLimitHeaders(decision, now = Date.now() / 1e3) {
 	const entries = [...policies].map(([name, detail]) => ({
 		name: sfString(name),
 		detail,
-		wait: Math.max(1, Math.ceil(detail.resetsAt - now))
+		wait: Math.max(1, (secondsOf(detail.resetsAt) ?? 0) - nowSeconds(now))
 	}));
 	return {
 		"Retry-After": String(Math.min(...entries.map((entry) => entry.wait))),
 		RateLimit: entries.map((entry) => `${entry.name};r=0;t=${entry.wait}`).join(", "),
-		"RateLimit-Policy": entries.map((entry) => `${entry.name};q=${entry.detail.count};w=${entry.detail.window}`).join(", ")
+		"RateLimit-Policy": entries.map((entry) => `${entry.name};q=${entry.detail.count};w=${entry.detail.per}`).join(", ")
 	};
 }
 /**
@@ -162,14 +159,14 @@ function problemFromDecision(decision, permission, subject, options = {}) {
 function notFoundProblem(instance) {
 	return problemResponse(notFoundDetails(instance));
 }
-const ANONYMOUS = {
+const ANONYMOUS = freezeDeep({
 	outcome: "denied",
 	denials: [{
 		role: null,
 		reason: "anonymous"
 	}],
 	alternatives: []
-};
+});
 /** The `401` for a request with no subject, with the RFC 6750 challenge its credentials call for. */
 function unauthenticatedProblem(credentials) {
 	return decisionResponse(problemDetails({
@@ -177,15 +174,9 @@ function unauthenticatedProblem(credentials) {
 		detail: "anonymous"
 	}), ANONYMOUS, { credentials });
 }
+/** RFC 9110 section 15.5.6: a `405` lists the methods the resource supports in `Allow`. */
 function methodNotAllowed(allow) {
-	const response = problemResponse({
-		type: `${PROBLEM_BASE}/method-not-allowed`,
-		title: "Method not allowed",
-		status: 405,
-		detail: `use ${allow}`
-	});
-	response.headers.set("Allow", allow);
-	return response;
+	return problemResponse(statusProblem(405, `use ${allow}`), void 0, void 0, { Allow: allow });
 }
 //#endregion
-export { notFoundProblem as a, protectedResourceMetadataUrl as c, wwwAuthenticate as d, methodNotAllowed as i, unauthenticatedProblem as l, bearerChallenge as n, problemFromDecision as o, decisionResponse as r, problemResponse as s, batchTooLarge as t, validationProblem as u };
+export { methodNotAllowed as a, problemResponse as c, validationProblem as d, wwwAuthenticate as f, decisionResponse as i, protectedResourceMetadataUrl as l, batchTooLarge as n, notFoundProblem as o, bearerChallenge as r, problemFromDecision as s, ANONYMOUS as t, unauthenticatedProblem as u };

package/dist/{problem-details-DX075l9V.d.ts → problem-details-DXlt-vks.d.ts}

@@ -1,4 +1,4 @@
-import { Yn as Decision } from "./policy-IB6yxpC3.js";
+import { Nn as Decision } from "./policy-types-DzwivBgR.js";
 //#region src/core/problem-details.d.ts
 type Disclosure = "hide" | "reveal";
 /** The plans a `not-entitled` denial asks for; empty unless every denial is `not-entitled`. */

package/dist/{problem-details-_AMOYz-w.js → problem-details-cn5X30gZ.js}

@@ -1,29 +1,41 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
-import { t as PROBLEM_BASE } from "./validation-error-CnjZ4t92.js";
-//#region src/core/wire-denial.ts
-const IN_PROCESS = /* @__PURE__ */ new Set(["closure-error", "validation"]);
-function jsonDetail(value) {
-	if (value === void 0 || value === null || value instanceof Error) return;
-	if (typeof value === "string" || typeof value === "boolean") return value;
-	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
-	if (typeof value !== "object") return;
-	try {
-		return JSON.parse(JSON.stringify(value));
-	} catch {
-		return;
-	}
+import { t as compact } from "./compact-CAf557ZB.js";
+import { t as PROBLEM_BASE } from "./validation-error-ZfUHbKvf.js";
+import { t as wireDenials } from "./wire-denial-C7PaVYEM.js";
+//#region src/core/problem-types.ts
+/** The `type` URI of a PermDock problem type. */
+function problemType(type) {
+	return `${PROBLEM_BASE}/${type}`;
 }
-function wireDenial(denial) {
+/** RFC 9110 section 15 reason phrases for the statuses PermDock answers with. */
+const REASON_PHRASES = {
+	400: "Bad Request",
+	401: "Unauthorized",
+	403: "Forbidden",
+	404: "Not Found",
+	405: "Method Not Allowed",
+	406: "Not Acceptable",
+	409: "Conflict",
+	412: "Precondition Failed",
+	413: "Content Too Large",
+	415: "Unsupported Media Type",
+	422: "Unprocessable Content",
+	428: "Precondition Required",
+	429: "Too Many Requests",
+	500: "Internal Server Error",
+	501: "Not Implemented",
+	502: "Bad Gateway",
+	503: "Service Unavailable"
+};
+/** An `about:blank` problem: the `title` is the status's reason phrase. */
+function statusProblem(status, detail, extra = {}) {
 	return compact({
-		role: denial.role,
-		reason: denial.reason,
-		to: denial.to,
-		detail: IN_PROCESS.has(denial.reason) ? void 0 : jsonDetail(denial.detail)
+		type: "about:blank",
+		title: REASON_PHRASES[status] ?? "Error",
+		status,
+		detail,
+		...extra
 	});
 }
-function wireDenials(denials) {
-	return denials.map(wireDenial);
-}
 //#endregion
 //#region src/core/problem-details.ts
 /** Reasons that only arise once a matching grant was found, so they reveal nothing hidden. */
@@ -63,13 +75,7 @@ function stepUpOf(decision) {
 }
 /** The `404` a missing row and a hidden one share, so the two read the same. */
 function notFoundDetails(instance) {
-	return compact({
-		type: `${PROBLEM_BASE}/not-found`,
-		title: "Not found",
-		status: 404,
-		detail: "No such resource",
-		instance
-	});
+	return statusProblem(404, "No such resource", compact({ instance }));
 }
 /**
 * The RFC 9457 body for a decision that is not `granted`. One status matrix
@@ -86,7 +92,7 @@ function problemDetails(input) {
 		resource: input.resource
 	});
 	if (decision.outcome === "approval-required") return compact({
-		type: `${PROBLEM_BASE}/approval-required`,
+		type: problemType("approval-required"),
 		title: "Approval required",
 		status: 403,
 		detail: input.detail,
@@ -96,16 +102,12 @@ function problemDetails(input) {
 	});
 	const reasons = new Set(decision.denials.map((denial) => denial.reason));
 	if (input.disclosure === "hide" && ![...reasons].every((reason) => HOLDS_GRANT.has(reason))) return notFoundDetails(input.instance);
-	if (reasons.has("anonymous")) return compact({
-		type: `${PROBLEM_BASE}/unauthenticated`,
-		title: "Authentication required",
-		status: 401,
-		detail: "Authenticate and repeat the request",
+	if (reasons.has("anonymous")) return statusProblem(401, "Authenticate and repeat the request", compact({
 		instance: input.instance,
 		permission: input.permission
-	});
+	}));
 	const denied = compact({
-		type: `${PROBLEM_BASE}/denied`,
+		type: problemType("denied"),
 		title: "Permission denied",
 		status: 403,
 		detail: input.detail,
@@ -116,29 +118,30 @@ function problemDetails(input) {
 	if (reasons.has("insufficient-user-authentication")) return {
 		...denied,
 		status: 401,
-		type: `${PROBLEM_BASE}/step-up-required`,
+		type: problemType("step-up-required"),
+		title: "Step-up required",
 		...stepUpOf(decision)
 	};
 	const plans = requiredPlans(decision);
 	if (plans.length > 0) return {
 		...denied,
-		type: `${PROBLEM_BASE}/not-entitled`,
+		type: problemType("not-entitled"),
 		title: "Plan upgrade required",
 		plans
 	};
 	if (reasons.size > 0 && [...reasons].every((reason) => reason === "limit")) return {
 		...denied,
 		status: 429,
-		type: `${PROBLEM_BASE}/rate-limited`,
+		type: problemType("rate-limited"),
 		title: "Rate limit exceeded"
 	};
 	if (reasons.has("limit-unavailable") && [...reasons].every((reason) => reason === "limit" || reason === "limit-unavailable")) return {
 		...denied,
 		status: 503,
-		type: `${PROBLEM_BASE}/limit-unavailable`,
+		type: problemType("limit-unavailable"),
 		title: "Rate limit unavailable"
 	};
 	return denied;
 }
 //#endregion
-export { wireDenials as a, stepUpOf as i, problemDetails as n, requiredPlans as r, notFoundDetails as t };
+export { problemType as a, stepUpOf as i, problemDetails as n, statusProblem as o, requiredPlans as r, notFoundDetails as t };

package/dist/problem-types-CJ2325SZ.js

@@ -0,0 +1,5 @@
+//#region src/cli/cloud/problem-types.ts
+/** The Problem `type` of `GET /v1/projects/{id}/policy` before the first `cloud push`. */
+const POLICY_NOT_PUBLISHED = "https://permdock.com/problems/policy-not-published";
+//#endregion
+export { POLICY_NOT_PUBLISHED as t };

package/dist/{prompt-CXYhLfsS.js → prompt-DfZLJLIn.js}

@@ -1,8 +1,8 @@
 import { cancel, confirm, isCancel, multiselect } from "@clack/prompts";
-//#region src/cli/commands/prompt.ts
+//#region src/cli/core/prompt.ts
 /** What a command reports when the person at the terminal cancels a prompt. */
 const CANCELLED = {
-	code: 2,
+	code: 130,
 	output: "Cancelled."
 };
 /** A yes or no question; `undefined` when cancelled. */

package/dist/protected-DEPHc2xV.d.ts

@@ -0,0 +1,38 @@
+import { Nn as Decision, j as PolicyVocabulary, nr as Membership } from "./policy-types-DzwivBgR.js";
+import { r as Role, w as Permission } from "./vocabulary-D6lPdb4Z.js";
+import { r as DescribeOptions, t as DecisionDescription } from "./describe-BZUsixiL.js";
+import { a as FilterResult, c as PermissionSet, d as RolesOptions, f as SubjectView, l as PermissionState, o as GateMode, p as TenantView, r as ClientPermDock, s as GateView, t as ApprovalHandle } from "./types-BNORmDM8.js";
+import { r as ProtectedProps } from "./types-tIgIeIKJ.js";
+import { ReactNode } from "react";
+//#region src/react/hooks.d.ts
+declare function usePermDock<V extends PolicyVocabulary = PolicyVocabulary>(): ClientPermDock<V>;
+declare function usePermission(permission: Permission, data?: unknown): PermissionState;
+declare function usePermissions(permissions: readonly Permission[], data?: unknown): PermissionSet;
+declare function useFilter<T>(permission: Permission<string, T, "instance">, rows: readonly T[]): FilterResult<T>;
+declare function useTenant(): TenantView;
+declare function useMemberships(): readonly Membership[];
+declare function useRoles(options?: RolesOptions): {
+  readonly roles: readonly Role[];
+};
+declare function useAssignableRoles(): readonly Role[];
+declare function useAssignablePermissions(options?: {
+  readonly tenant?: string;
+}): readonly Permission[];
+declare function useSubject(): SubjectView;
+/** `describe` with the provider's `messages`; a call's own `messages` win. */
+declare function useDescribe(): (decision: Decision, options?: DescribeOptions) => DecisionDescription;
+declare function useApproval(decision: Decision): ApprovalHandle;
+/**
+ * What a permission-gated control renders: `hidden`, `disabled`,
+ * `needsApproval`, `upgrade` and a localised `reason`, from the same
+ * snapshot as `usePermission`. React and React Native share it; a recipe
+ * renders the fields and decides nothing.
+ */
+declare function useGate(permission: Permission, data?: unknown, options?: {
+  readonly mode?: GateMode;
+}): GateView;
+//#endregion
+//#region src/react/protected.d.ts
+declare function Protected(props: ProtectedProps): ReactNode;
+//#endregion
+export { useDescribe as a, useMemberships as c, usePermissions as d, useRoles as f, useAssignableRoles as i, usePermDock as l, useTenant as m, useApproval as n, useFilter as o, useSubject as p, useAssignablePermissions as r, useGate as s, Protected as t, usePermission as u };

package/dist/{protected-utU-SLuy.js → protected-DfjY5mLA.js}

@@ -1,6 +1,6 @@
-import { n as storeOf } from "./store-options-ByhZq1jV.js";
-import { a as protectedView, c as subjectView, i as permissionSet, l as tenantView, n as filterResult, o as rolesView, s as scopedTenant, t as approvalHandle } from "./views-Soe7bGSC.js";
-import { i as PermDockStoreContext, r as PermDockSnapshotPromiseContext } from "./live-options-H2eG8dfJ.js";
+import { n as storeOf } from "./store-options-BqEakYRa.js";
+import { c as rolesView, d as subjectView, f as tenantView, i as gateView, l as scopedTenant, n as describeWith, o as permissionSet, r as filterResult, s as protectedView, t as approvalHandle, u as slotContent } from "./views-DTIIO-oQ.js";
+import { a as PermDockUiContext, i as PermDockStoreContext, r as PermDockSnapshotPromiseContext } from "./live-options-BaAFCIiu.js";
 import { Suspense, use, useMemo, useSyncExternalStore } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/react/hooks.ts
@@ -72,29 +72,58 @@ function useSubject() {
 	const permdock = usePermDock();
 	return useMemo(() => subjectView(permdock), [permdock]);
 }
+/** `describe` with the provider's `messages`; a call's own `messages` win. */
+function useDescribe() {
+	const { messages } = use(PermDockUiContext);
+	return useMemo(() => describeWith(messages), [messages]);
+}
 function useApproval(decision) {
 	return approvalHandle(storeOf(usePermDock()), decision);
 }
+/**
+* What a permission-gated control renders: `hidden`, `disabled`,
+* `needsApproval`, `upgrade` and a localised `reason`, from the same
+* snapshot as `usePermission`. React and React Native share it; a recipe
+* renders the fields and decides nothing.
+*/
+function useGate(permission, data, options = {}) {
+	const state = usePermission(permission, data);
+	const describeDecision = useDescribe();
+	const mode = options.mode ?? "disable";
+	return useMemo(() => gateView(state, (decision) => describeDecision(decision, { permission }), mode), [
+		state,
+		describeDecision,
+		permission,
+		mode
+	]);
+}
 //#endregion
 //#region src/react/protected.tsx
 function Protected(props) {
-	if (props.pending === void 0) return /* @__PURE__ */ jsx(Guard, { ...props });
+	const { defaults } = use(PermDockUiContext);
+	const pending = slotContent("pending", props, defaults);
+	if (pending === void 0) return /* @__PURE__ */ jsx(Guard, { ...props });
 	return /* @__PURE__ */ jsx(Suspense, {
-		fallback: props.pending,
+		fallback: pending,
 		children: /* @__PURE__ */ jsx(Guard, { ...props })
 	});
 }
 function Guard(props) {
+	const { defaults } = use(PermDockUiContext);
 	const root = usePermDock();
 	const local = usePermission(props.permission, props.data);
 	const scoped = useMemo(() => scopedTenant(root, props.tenant), [root, props.tenant]);
 	const view = protectedView(local, root, props.permission, props.data, scoped);
 	switch (view.slot) {
-		case "pending": return props.pending ?? null;
-		case "fallback": return typeof props.fallback === "function" ? props.fallback(view.decision) : props.fallback ?? null;
+		case "pending": return slotContent("pending", props, defaults) ?? null;
+		case "denied": return render(slotContent("denied", props, defaults), view.decision);
+		case "approval": return render(slotContent("approval", props, defaults), view.decision);
 		case "default": return typeof props.children === "function" ? props.children(view.decision) : props.children;
 		default: return view;
 	}
 }
+function render(content, decision) {
+	return typeof content === "function" ? content(decision) : content ?? null;
+}
 //#endregion
-export { useFilter as a, usePermission as c, useSubject as d, useTenant as f, useAssignableRoles as i, usePermissions as l, useApproval as n, useMemberships as o, useAssignablePermissions as r, usePermDock as s, Protected as t, useRoles as u };
+export { useDescribe as a, useMemberships as c, usePermissions as d, useRoles as f, useAssignableRoles as i, usePermDock as l, useTenant as m, useApproval as n, useFilter as o, useSubject as p, useAssignablePermissions as r, useGate as s, Protected as t, usePermission as u };

package/dist/{provider-CSQd7m92.js → provider-CC-u3bYP.js}

@@ -1,8 +1,8 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
-import { t as emptySnapshot } from "./from-snapshot-CTLijvdm.js";
-import { t as adapterStore } from "./store-options-ByhZq1jV.js";
-import { i as PermDockStoreContext, n as useKeyed, r as PermDockSnapshotPromiseContext, t as useLiveOptions } from "./live-options-H2eG8dfJ.js";
-import { useLayoutEffect } from "react";
+import { t as compact } from "./compact-CAf557ZB.js";
+import { t as emptySnapshot } from "./from-snapshot-D2lZt4Dd.js";
+import { t as adapterStore } from "./store-options-BqEakYRa.js";
+import { a as PermDockUiContext, i as PermDockStoreContext, n as useKeyed, r as PermDockSnapshotPromiseContext, t as useLiveOptions } from "./live-options-BaAFCIiu.js";
+import { useLayoutEffect, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/react/provider.tsx
 function PermDockProvider(props) {
@@ -20,7 +20,10 @@ function PermDockProvider(props) {
 		maxAge: props.maxAge,
 		verifier: live.verifier,
 		awaiting,
-		passCache: true
+		passCache: true,
+		onSnapshot: live.onSnapshot,
+		onClear: live.onClear,
+		approvalInterval: props.approvalInterval
 	}), props.snapshot ?? emptySnapshot()), [
 		props.snapshot,
 		props.endpoint,
@@ -31,8 +34,15 @@ function PermDockProvider(props) {
 		live.headers,
 		props.maxAge,
 		live.verifier,
-		awaiting
+		awaiting,
+		live.onSnapshot,
+		live.onClear,
+		props.approvalInterval
 	]);
+	const ui = useMemo(() => ({
+		defaults: props.defaults,
+		messages: props.messages
+	}), [props.defaults, props.messages]);
 	useLayoutEffect(() => {
 		if (promise !== null && !suspend) store.track(promise);
 	}, [
@@ -42,9 +52,12 @@ function PermDockProvider(props) {
 	]);
 	return /* @__PURE__ */ jsx(PermDockStoreContext, {
 		value: store,
-		children: /* @__PURE__ */ jsx(PermDockSnapshotPromiseContext, {
-			value: suspend ? promise : null,
-			children: props.children
+		children: /* @__PURE__ */ jsx(PermDockUiContext, {
+			value: ui,
+			children: /* @__PURE__ */ jsx(PermDockSnapshotPromiseContext, {
+				value: suspend ? promise : null,
+				children: props.children
+			})
 		})
 	});
 }

package/dist/{provider-DZY281jO.d.ts → provider-DMVt6yYn.d.ts}

@@ -1,4 +1,4 @@
-import { t as PermDockProviderProps } from "./types-BnIEz1sU.js";
+import { n as PermDockProviderProps } from "./types-tIgIeIKJ.js";
 import { ReactElement } from "react";
 //#region src/react/provider.d.ts
 declare function PermDockProvider(props: PermDockProviderProps): ReactElement;

package/dist/{provider-store-Cfbvo4DE.js → provider-store-B5Yrkhzr.js}

@@ -1,6 +1,6 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
-import { t as emptySnapshot } from "./from-snapshot-CTLijvdm.js";
-import { i as isPromiseLike, t as adapterStore } from "./store-options-ByhZq1jV.js";
+import { t as compact } from "./compact-CAf557ZB.js";
+import { t as emptySnapshot } from "./from-snapshot-D2lZt4Dd.js";
+import { i as isPromiseLike, t as adapterStore } from "./store-options-BqEakYRa.js";
 //#region src/client/provider-store.ts
 /**
 * Store options that read `read()` on every request, so a rotated token, a
@@ -30,6 +30,9 @@ function providerStore(options, read, snapshot) {
 		approvals: options.approvals,
 		tenant: options.tenant,
 		maxAge: options.maxAge,
+		onSnapshot: options.onSnapshot,
+		onClear: options.onClear,
+		approvalInterval: options.approvalInterval,
 		...liveOptions(read)
 	}), promised || snapshot === void 0 ? emptySnapshot() : snapshot);
 	if (promised) store.follow(snapshot);