@burojs/react 0.4.0 → 0.5.0

package/dist/flows-runtime.js

@@ -0,0 +1,1157 @@
+'use client';
+"use client";
+import { $ as readPermissions, $t as useApp, At as useCurrentUIActivation, B as resourceDescriptorBase, Bn as executeMutation, Cr as executeQuery, E as registerFlowRun, Ft as useOptionalPresentationMount, G as EMPTY_COUNTED, Hn as resolveCountExecution, J as hopId, K as EMPTY_ROWS, L as createRuntimeActionDataAccess, Lt as FLOW_COMPONENT, N as useFrameworkAudit, Q as projectRows, Qn as useLocale, Qt as useUIPresentationRuntime, R as createUnavailableActionDataAccess, Rt as FlowScreenEntry, U as useFlowAttemptsStore, W as useCurrentUserId, X as listValue, Y as isSignedOut, Z as projectRow, at as whereValueUsable, bt as useDispatcherEffects, d as useProjectedTitle, fn as DismissRegistryContext, ft as useFlowRowResolver, hn as useDismissPending, i as conjoinHostPage, k as useOptionalVisibilityCtx, ln as useNavigationHold, lt as disposeWhenIdle, mr as useFlowFormCatalog, n as usePresentFlow, nn as useRouteNavigate, nt as useContextSnapshot, o as hostPageRef, ot as withRowId, pn as DismissScopeContext, pr as useApplicationSnapshot, qn as buildStandardQueryDescriptor, r as usePageFlowGate, rr as useTranslate, s as useHostPage, t as reportMissingFlowHost, v as useFormController, xr as useOptionalDataRuntime, z as customMutationDescriptor } from "./present-flow-pFzbn0cZ.js";
+import { FLOW_SETTLE_MS, LIST_SOURCE_DEFAULT_LIMIT, attemptKey, attemptSlot, compileFlow, createCustomQueryDescriptor, createIdempotencyKey, createMutationDescriptor, createQueryDescriptor, dtoFields, fnv1a, formatEntityRef, hrefFor, humanizeKey, isDataError, isFlowRef, lowerVia, normalizeDataError, normalizeEntityRef, projectSource, relationAmbiguousError, resolveDataCapability, resolveFieldAccess, resolveFlowGate, ruleContextFor, runThenEffects, snapshotResourceFields, trustedFlowAttachments } from "@burojs/core";
+import { useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { fieldEntriesToMap } from "@burojs/core/internal";
+import { createFlowFormPort, createFlowRun, createMemoryAttempts, hashCanonical } from "@burojs/core/flows";
+//#region src/flows/source-reader.ts
+const resource = (target) => ({
+	kind: "resource",
+	ref: target
+});
+function ownData(value, key) {
+	if (value === null || typeof value !== "object") return void 0;
+	const descriptor = Object.getOwnPropertyDescriptor(value, key);
+	return descriptor !== void 0 && "value" in descriptor ? descriptor.value : void 0;
+}
+function operand(value, sources) {
+	if (value.kind !== "ref") return value.value;
+	let current = sources[value.source];
+	for (const segment of value.path) {
+		current = ownData(current, segment);
+		if (current === void 0) return void 0;
+	}
+	return current;
+}
+const isMissing = (error) => error.kind === "not-found" || error.kind === "forbidden";
+function configuration(code, message) {
+	return normalizeDataError(Object.assign(new Error(message), {
+		kind: "configuration",
+		code
+	}));
+}
+function createFlowSourceReader(input) {
+	const { runtime } = input;
+	const app = runtime.app;
+	const registryDef = (target) => app.registry.get(resource(target));
+	const idFieldOf = (target) => {
+		const idField = registryDef(target)?.data?.idField;
+		return typeof idField === "string" && idField !== "" ? idField : void 0;
+	};
+	const recordDto = (target) => {
+		const def = registryDef(target);
+		return def === void 0 ? void 0 : dtoFields(def, "record");
+	};
+	const listDto = (target) => {
+		const def = registryDef(target);
+		return def === void 0 ? void 0 : dtoFields(def, "list");
+	};
+	const context = async () => ({
+		runtime,
+		snapshot: app.runtime.getSnapshot(),
+		session: await runtime.waitUntilReady(),
+		locale: input.inputs().locale
+	});
+	const run = async (descriptor, signal) => {
+		if (isDataError(descriptor)) throw descriptor;
+		return await executeQuery({
+			descriptor,
+			runtime,
+			signal
+		});
+	};
+	const row = async (target, key, by, signal) => {
+		const ctx = await context();
+		const projection = recordDto(target);
+		const idField = idFieldOf(target) ?? "id";
+		const dto = projection === void 0 || projection.includes(idField) ? projection : [...projection, idField];
+		try {
+			if (by === void 0) {
+				const answer = await run(buildStandardQueryDescriptor(ctx, resource(target), {
+					kind: "one",
+					id: key,
+					...projection === void 0 ? {} : { projection }
+				}), signal);
+				return withRowId(projectRow(answer?.data ?? null, dto), idField, key);
+			}
+			const answer = await run(buildStandardQueryDescriptor(ctx, resource(target), {
+				kind: "list",
+				filter: {
+					field: by,
+					op: "eq",
+					value: key
+				},
+				pagination: {
+					kind: "offset",
+					page: 1,
+					pageSize: 2
+				},
+				...projection === void 0 ? {} : { projection }
+			}), signal);
+			const rows = Array.isArray(answer?.data) ? answer.data : [];
+			if (rows.length === 0) return null;
+			if (rows.length === 1) return projectRow(rows[0], dto);
+			throw relationAmbiguousError(formatEntityRef(target), by, String(key));
+		} catch (error) {
+			const failure = normalizeDataError(error);
+			if (isMissing(failure)) return null;
+			throw failure;
+		}
+	};
+	const list = async (entry, sources, signal) => {
+		const fieldKind = (field) => {
+			const found = snapshotResourceFields(app.runtime.getSnapshot())(entry.target)?.find((candidate) => candidate.name === field);
+			return typeof found?.kind === "string" ? found.kind : void 0;
+		};
+		const conditions = [];
+		for (const condition of entry.where) {
+			const value = operand(condition.value, sources);
+			if (!whereValueUsable(value, fieldKind(condition.field))) return entry.count === true ? EMPTY_COUNTED : EMPTY_ROWS;
+			conditions.push({
+				field: condition.field,
+				op: condition.op,
+				value
+			});
+		}
+		const filter = conditions.length === 0 ? void 0 : conditions.length === 1 ? conditions[0] : { and: conditions };
+		const ctx = await context();
+		const projection = listDto(entry.target);
+		const answer = await run(buildStandardQueryDescriptor(ctx, resource(entry.target), {
+			kind: "list",
+			...filter === void 0 ? {} : { filter },
+			...entry.sort === void 0 ? {} : { sort: entry.sort },
+			pagination: {
+				kind: "offset",
+				page: 1,
+				pageSize: entry.limit ?? LIST_SOURCE_DEFAULT_LIMIT
+			},
+			...projection === void 0 ? {} : { projection }
+		}), signal);
+		const rows = projectRows(answer?.data, projection);
+		if (entry.count !== true) return listValue(rows);
+		const inline = typeof answer?.total === "number" ? answer.total : void 0;
+		const execution = resolveCountExecution("auto", inline, {
+			query: true,
+			live: false
+		});
+		if (isDataError(execution)) throw execution;
+		if (execution.kind === "inline") return listValue(rows, execution.total);
+		const counted = await run(buildStandardQueryDescriptor(ctx, resource(entry.target), {
+			kind: "count",
+			...filter === void 0 ? {} : { filter }
+		}), signal);
+		if (typeof counted?.total !== "number") throw configuration("count-missing", "The count read returned no total.");
+		return listValue(rows, counted.total);
+	};
+	const query = async (entry, sources, signal) => {
+		const values = {};
+		for (const [key, value] of Object.entries(entry.input)) {
+			const resolved = operand(value, sources);
+			values[key] = resolved === void 0 ? null : resolved;
+		}
+		const ctx = await context();
+		return run(createCustomQueryDescriptor({
+			snapshot: ctx.snapshot,
+			session: ctx.session,
+			locale: ctx.locale,
+			ref: entry.query,
+			input: values
+		}), signal);
+	};
+	const via = async (entry, sources, signal) => {
+		if (input.owner === null) throw configuration("via-invalid", "An app flow has no record for a 'via' source.");
+		let hops;
+		try {
+			hops = lowerVia(normalizeEntityRef(input.owner), {
+				path: entry.path,
+				...entry.to === void 0 ? {} : { to: entry.to },
+				...entry.by === void 0 ? {} : { by: entry.by }
+			}, snapshotResourceFields(app.runtime.getSnapshot()), idFieldOf);
+		} catch (error) {
+			const code = error.code;
+			throw configuration(typeof code === "string" ? code : "via-invalid", error instanceof Error ? error.message : String(error));
+		}
+		let current = sources.record ?? null;
+		for (const hop of hops) {
+			const key = hopId(ownData(current, hop.field));
+			if (key === null) return null;
+			current = await row(hop.target, key, hop.by, signal);
+			if (current === null) return null;
+		}
+		return current;
+	};
+	return async (source, signal) => {
+		const { record, args, scope } = input.inputs();
+		const sources = {
+			record,
+			args,
+			scope
+		};
+		switch (source.kind) {
+			case "one": {
+				const key = hopId(operand(source.key, sources));
+				if (key === null) return null;
+				return row(source.target, key, source.by, signal);
+			}
+			case "list": return list(source, sources, signal);
+			case "query": return query(source, sources, signal);
+			case "via": return via(source, sources, signal);
+		}
+	};
+}
+//#endregion
+//#region src/flows/ports.ts
+const resourceHandle = (resource) => ({
+	kind: "resource",
+	ref: normalizeEntityRef(resource)
+});
+function validKey(value) {
+	if (typeof value === "string") return value === "" ? void 0 : value;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+}
+function settleQueries(runtime) {
+	const client = runtime.queryClient;
+	return new Promise((resolve) => {
+		let done = false;
+		let unsubscribe;
+		const finish = () => {
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			unsubscribe?.();
+			resolve();
+		};
+		const timer = setTimeout(finish, FLOW_SETTLE_MS);
+		Promise.resolve().then(() => {
+			if (client.isFetching() === 0) {
+				finish();
+				return;
+			}
+			unsubscribe = client.getQueryCache().subscribe(() => {
+				if (client.isFetching() === 0) finish();
+			});
+		});
+	});
+}
+function createRuntimeFlowPorts(input) {
+	const { runtime, app, flow } = input;
+	const projectSourceValue = (name, value) => {
+		if (value === null || typeof value !== "object") return value;
+		const owner = flow.resource === null ? void 0 : normalizeEntityRef(flow.resource);
+		let target;
+		let shape = "row";
+		if (name === "record") target = owner;
+		else {
+			const withs = flow.flow.with ?? {};
+			const entry = Object.hasOwn(withs, name) ? withs[name] : void 0;
+			if (entry?.kind === "one") target = entry.target;
+			else if (entry?.kind === "list") {
+				target = entry.target;
+				shape = "rows";
+			} else if (entry?.kind === "via" && owner !== void 0) try {
+				const fieldsOf = snapshotResourceFields(app.runtime.getSnapshot());
+				target = lowerVia(owner, {
+					path: entry.path,
+					...entry.to === void 0 ? {} : { to: entry.to },
+					...entry.by === void 0 ? {} : { by: entry.by }
+				}, fieldsOf).at(-1)?.target;
+			} catch {
+				return null;
+			}
+		}
+		if (target === void 0) return value;
+		const def = app.registry.get({
+			kind: "resource",
+			ref: target
+		});
+		if (def === void 0) return value;
+		const context = input.context();
+		const resource = formatEntityRef(target);
+		const decisions = resolveFieldAccess({
+			rules: app.ruleSource.rules(resource),
+			fields: dtoFields(def, shape === "row" ? "record" : "list"),
+			context: ruleContextFor({
+				user: context.user,
+				scope: context.scope,
+				...context.permissions === void 0 ? {} : { permissions: context.permissions },
+				...shape === "row" ? { record: value } : {},
+				mode: shape === "row" ? "show" : "list",
+				resource
+			}),
+			permissions: context.permissions,
+			reach: shape === "row" ? "record" : "every"
+		});
+		const closed = Object.fromEntries(Object.entries(decisions).map(([field, decision]) => [field, decision.view === "visible" ? decision : {
+			...decision,
+			view: "hidden"
+		}]));
+		const idField = def.data?.idField;
+		const projected = projectSource({
+			status: "ready",
+			value,
+			refreshing: false
+		}, closed, shape, typeof idField === "string" && idField !== "" ? idField : "id");
+		return projected.status === "ready" ? projected.value : value;
+	};
+	const describe = async (call) => {
+		if (call.op === "custom") return customMutationDescriptor(runtime, normalizeEntityRef(call.target), call.input);
+		const base = await resourceDescriptorBase(runtime, resourceHandle(call.target));
+		const kind = call.op === "create" ? "createOne" : call.op === "update" ? "updateOne" : "deleteOne";
+		return createMutationDescriptor({
+			...base,
+			kind,
+			...call.id === void 0 ? {} : { id: call.id },
+			...call.op === "delete" || call.input === void 0 ? {} : { input: call.input }
+		});
+	};
+	const queryOne = async (resource, id, signal) => {
+		const base = await resourceDescriptorBase(runtime, resourceHandle(resource));
+		return (await executeQuery({
+			descriptor: createQueryDescriptor({
+				...base,
+				kind: "one",
+				id
+			}),
+			runtime,
+			signal
+		})).data;
+	};
+	const hasOne = (resource) => {
+		try {
+			const binding = app.resolveDataBinding(resourceHandle(resource));
+			const service = runtime.providers.resolve(binding.providerId);
+			return typeof resolveDataCapability(service.provider, {
+				lifecycle: "query",
+				kind: "one"
+			}) === "function";
+		} catch {
+			return false;
+		}
+	};
+	const replaySafe = () => {
+		if (flow.op !== "custom") return false;
+		try {
+			const value = app.runtime.getSnapshot().getProjection({
+				kind: "custom-mutation",
+				ref: normalizeEntityRef(flow.target)
+			})?.value;
+			const replay = value?.replay;
+			if ((replay?.capability === "mutation-replay-policy" && typeof replay.id === "string" ? app.getPluginCapability("mutation-replay-policy", replay.id) : void 0) !== "once-after-auth-refresh" || value?.binding?.provider === void 0) return false;
+			const service = runtime.providers.resolve(value.binding.provider);
+			return resolveDataCapability(service.provider, {
+				lifecycle: "mutation",
+				kind: "custom"
+			}).replay?.idempotency === "keyed-replay-once";
+		} catch {
+			return false;
+		}
+	};
+	const readSource = createFlowSourceReader({
+		runtime,
+		owner: flow.resource,
+		inputs: () => {
+			const context = input.context();
+			return {
+				record: input.record,
+				args: input.args ?? {},
+				scope: context.scope,
+				locale: context.locale
+			};
+		}
+	});
+	return {
+		gate() {
+			const context = input.context();
+			return resolveFlowGate({
+				app,
+				resource: flow.resource,
+				flow,
+				ctx: ruleContextFor({
+					...input.record === void 0 ? {} : { record: input.record },
+					...flow.resource === null ? {} : { resource: flow.resource },
+					mode: input.record === void 0 ? "list" : "show",
+					user: context.user,
+					scope: context.scope,
+					...context.permissions === void 0 ? {} : { permissions: context.permissions }
+				}),
+				permissionsStatus: context.permissions?.status
+			});
+		},
+		read(_name, source, signal) {
+			return readSource(source, signal);
+		},
+		async reread(resource, ids, signal) {
+			const clean = ids.filter((id) => validKey(id) !== void 0);
+			if (clean.length === 0) return [];
+			if (clean.length === 1 && hasOne(resource)) {
+				const row = await queryOne(resource, clean[0], signal);
+				return row === null || row === void 0 ? [] : [row];
+			}
+			const base = await resourceDescriptorBase(runtime, resourceHandle(resource));
+			return (await executeQuery({
+				descriptor: createQueryDescriptor({
+					...base,
+					kind: "many",
+					ids: clean
+				}),
+				runtime,
+				signal
+			})).data ?? [];
+		},
+		async mutate(call) {
+			const descriptor = await describe(call);
+			const output = await executeMutation({
+				descriptor,
+				runtime,
+				idempotencyKey: call.key,
+				...call.replay === "never" ? { replay: "never" } : {}
+			});
+			await settleQueries(runtime);
+			return output;
+		},
+		attempts: input.attempts,
+		audit(event) {
+			input.context().audit?.emit(event, { initiates: true });
+		},
+		checks: {
+			source: (resource) => app.checkSource.checks(resource),
+			data: input.data,
+			get ctx() {
+				return input.context().visibility;
+			},
+			t: (key, params, defaultValue) => input.context().t(key, params, defaultValue)
+		},
+		form: input.form,
+		project: projectSourceValue,
+		attachment: trustedFlowAttachments(app.runtime, flow),
+		clock: {
+			now: () => Date.now(),
+			uuid: () => createIdempotencyKey(),
+			wait: (ms, signal) => new Promise((resolve, reject) => {
+				const timer = setTimeout(resolve, ms);
+				signal.addEventListener("abort", () => {
+					clearTimeout(timer);
+					reject(signal.reason);
+				}, { once: true });
+			})
+		},
+		hash: hashCanonical,
+		user: input.user,
+		get replaySafe() {
+			return replaySafe();
+		}
+	};
+}
+//#endregion
+//#region src/flows/use-flow-run.ts
+const IDLE = Object.freeze({
+	step: "gate",
+	history: Object.freeze([]),
+	control: "undecided",
+	values: Object.freeze({}),
+	issues: Object.freeze([]),
+	warnings: Object.freeze([]),
+	key: null,
+	attempt: null,
+	canResend: false,
+	formStep: null
+});
+const ABSENT = Object.freeze({
+	...IDLE,
+	control: "absent"
+});
+const NO_SUBSCRIBE = () => () => {};
+function compileTarget(app, target) {
+	const named = isFlowRef(target) ? target.target : target;
+	try {
+		if ("appAction" in named) {
+			const def = app.registry.appActions.get(named.appAction);
+			return def === void 0 ? null : compileFlow(def, named.appAction);
+		}
+		const def = app.registry.get(named.resource);
+		return def === void 0 ? null : compileFlow(def, named.action);
+	} catch {
+		return null;
+	}
+}
+const keyOfTarget = (target) => {
+	const named = isFlowRef(target) ? target.target : target;
+	return "appAction" in named ? `app:${named.appAction}` : `r:${named.resource}/${named.action}`;
+};
+let warnedNoUser = false;
+const isObject$1 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const idOf = (value) => typeof value === "string" && value !== "" ? value : typeof value === "number" && Number.isFinite(value) ? String(value) : void 0;
+function flowAttemptKey(compiled, user, record, args, selection) {
+	const recordId = idOf(record?.[compiled.idField] ?? record?.id);
+	return attemptKey({
+		user,
+		flow: compiled.flowId,
+		slot: attemptSlot({
+			...recordId === void 0 ? {} : { record: recordId },
+			...args === void 0 || Object.keys(args).length === 0 ? {} : { argsHash: fnv1a(args) },
+			...selection === void 0 || compiled.each ? {} : { selectionHash: fnv1a([...selection].sort()) }
+		})
+	});
+}
+function thenFor(compiled, effects, record) {
+	let open;
+	const target = effects.open;
+	if (isObject$1(target) && !Object.hasOwn(target, "block")) {
+		const resource = typeof target.resource === "string" ? target.resource : compiled.resource ?? void 0;
+		const id = idOf(target.id) ?? idOf(record?.[compiled.idField] ?? record?.id);
+		if (resource !== void 0 && id !== void 0) open = {
+			kind: "record",
+			resource,
+			id,
+			mode: target.mode === "edit" ? "edit" : "show",
+			quick: target.quick === true
+		};
+	}
+	const then = {
+		...effects.notify === void 0 ? {} : { notify: effects.notify },
+		...effects.redirect === void 0 ? {} : { redirect: effects.redirect },
+		...open === void 0 ? {} : { open }
+	};
+	return Object.keys(then).length === 0 ? null : then;
+}
+function useFlowRun(target, opts = {}) {
+	const app = useApp();
+	const runtime = useOptionalDataRuntime();
+	const appSnapshot = useApplicationSnapshot();
+	const targetKey = keyOfTarget(target);
+	const compiled = useMemo(() => compileTarget(app, target), [
+		app,
+		targetKey,
+		appSnapshot
+	]);
+	const userId = useCurrentUserId();
+	const store = useFlowAttemptsStore();
+	const context = useContextSnapshot();
+	const signedOut = isSignedOut(context);
+	const visibility = useOptionalVisibilityCtx();
+	const translate = useTranslate();
+	const locale = useLocale();
+	const audit = useFrameworkAudit();
+	const latest = useRef(null);
+	latest.current = {
+		user: context.user,
+		scope: context.scope,
+		permissions: readPermissions(context),
+		visibility,
+		t: (key, params, defaultValue) => {
+			const text = translate(key, params === void 0 ? void 0 : { params });
+			return text === key ? defaultValue ?? key : text;
+		},
+		audit,
+		locale
+	};
+	const data = useMemo(() => runtime === null ? createUnavailableActionDataAccess("A flow needs a data runtime; none is mounted.") : createRuntimeActionDataAccess(runtime), [runtime]);
+	const liveRecordKey = opts.record === void 0 ? "" : JSON.stringify(opts.record);
+	const heldRecordKey = useRef(liveRecordKey);
+	const writing = useRef(false);
+	if (!writing.current) heldRecordKey.current = liveRecordKey;
+	const recordKey = heldRecordKey.current;
+	const argsKey = opts.args === void 0 ? "" : JSON.stringify(opts.args);
+	const selectionKey = opts.selection === void 0 ? "" : [...opts.selection.ids].sort().join("\0");
+	const latestOpts = useRef(opts);
+	latestOpts.current = opts;
+	const [generation, setGeneration] = useState(0);
+	const carried = useRef(void 0);
+	const restart = useCallback(() => {
+		const lease = latestOpts.current.lease;
+		if (lease?.run != null) {
+			disposeWhenIdle(lease.run);
+			lease.run = null;
+			lease.deps = null;
+		}
+		setGeneration((value) => value + 1);
+	}, []);
+	const attempts = useMemo(() => {
+		if (compiled === null) return null;
+		if (userId === null) return signedOut ? createMemoryAttempts() : null;
+		return store === null || store.user !== userId ? null : store.port;
+	}, [
+		compiled,
+		userId,
+		signedOut,
+		store,
+		generation
+	]);
+	const run = useMemo(() => {
+		if (compiled === null || runtime === null || attempts === null) return null;
+		if (latestOpts.current.linkOnly === true && (compiled.flow.host === "page" || compiled.flow.host !== void 0 && typeof compiled.flow.host === "object")) return null;
+		const { record, args, selection, lease } = latestOpts.current;
+		const leaseDeps = lease === void 0 ? null : [
+			compiled.flowId,
+			userId,
+			lease.record,
+			argsKey
+		].join("\0");
+		if (lease?.run != null && lease.deps === leaseDeps) return lease.run;
+		const ports = createRuntimeFlowPorts({
+			runtime,
+			app,
+			flow: compiled,
+			...record === void 0 ? {} : { record },
+			...args === void 0 ? {} : { args },
+			attempts,
+			form: createFlowFormPort(compiled.flow, app, { i18nPrefix: compiled.formId }),
+			user: userId,
+			data,
+			context: () => latest.current
+		});
+		const created = createFlowRun({
+			flow: compiled,
+			...record === void 0 ? {} : { record },
+			...args === void 0 ? {} : { args },
+			...selection === void 0 ? {} : { selection },
+			ports
+		});
+		registerFlowRun(created, compiled.formId);
+		if (carried.current !== void 0) created.setValues(carried.current);
+		carried.current = void 0;
+		if (lease !== void 0) {
+			lease.run = created;
+			lease.deps = leaseDeps;
+			lease.opened = false;
+		}
+		return created;
+	}, [
+		compiled,
+		runtime,
+		attempts,
+		app,
+		userId,
+		data,
+		recordKey,
+		argsKey,
+		selectionKey,
+		generation
+	]);
+	useEffect(() => {
+		if (!signedOut || compiled === null || warnedNoUser) return;
+		if (process.env.NODE_ENV === "production") return;
+		warnedNoUser = true;
+		console.warn(`[burojs] ${compiled.flowId} runs without a signed-in user: its attempts are kept in memory for this run only, and its form keeps no draft.`);
+	}, [signedOut, compiled]);
+	useEffect(() => {
+		if (run === null) return;
+		const lease = latestOpts.current.lease;
+		if (lease === void 0) {
+			run.open();
+			return () => run.dispose();
+		}
+		if (lease.opened) return;
+		lease.opened = true;
+		run.open();
+	}, [run]);
+	const permissionsStatus = readPermissions(context)?.status;
+	useEffect(() => {
+		if (run === null || permissionsStatus === "loading") return;
+		if (run.getSnapshot().control === "undecided") run.open();
+	}, [run, permissionsStatus]);
+	const snapshot = useSyncExternalStore(run?.subscribe ?? NO_SUBSCRIBE, () => run?.getSnapshot() ?? (compiled === null ? ABSENT : IDLE), () => run?.getSnapshot() ?? (compiled === null ? ABSENT : IDLE));
+	const locked = snapshot.control === "running";
+	writing.current = locked;
+	useDismissPending(locked);
+	useNavigationHold(locked);
+	const scopeEffects = useDispatcherEffects();
+	const effectsOf = opts.thenEffects ?? scopeEffects;
+	const ranThen = useRef(null);
+	const outcome = snapshot.outcome;
+	const thenEffects = snapshot.effects;
+	const thenHeld = useRef(false);
+	const thenOf = useRef({
+		run,
+		compiled
+	});
+	thenOf.current = {
+		run,
+		compiled
+	};
+	const runThen = useCallback(() => {
+		const { run: current, compiled: flow } = thenOf.current;
+		if (current === null || flow === null) return;
+		const now = current.getSnapshot();
+		if (now.outcome?.outcome !== "success" || now.effects === void 0) return;
+		if (ranThen.current === now.outcome) return;
+		ranThen.current = now.outcome;
+		const then = thenFor(flow, now.effects, latestOpts.current.record);
+		if (then === null) return;
+		runThenEffects(effectsOf(), then).catch((error) => {
+			if (process.env.NODE_ENV !== "production") console.error(`[burojs] ${flow.flowId}: a then effect threw.`, error);
+		});
+	}, [effectsOf]);
+	const holdThen = useCallback((hold) => {
+		thenHeld.current = hold;
+	}, []);
+	useEffect(() => {
+		if (thenHeld.current) return;
+		runThen();
+	}, [
+		run,
+		compiled,
+		outcome,
+		thenEffects,
+		runThen
+	]);
+	const lockedRef = useRef(locked);
+	lockedRef.current = locked;
+	useEffect(() => {
+		if (run === null || store === null || compiled === null || compiled.each) return;
+		const { record, args, selection } = latestOpts.current;
+		const key = flowAttemptKey(compiled, userId, record, args, selection?.ids);
+		return store.subscribe(() => {
+			if (lockedRef.current) return;
+			const now = run.getSnapshot();
+			const held = now.outcome?.outcome === "unknown" ? now.key : null;
+			if ((store.port.read(key)?.key ?? null) === held) return;
+			carried.current = now.values;
+			restart();
+		});
+	}, [
+		run,
+		store,
+		compiled,
+		userId,
+		restart
+	]);
+	const reset = useCallback(() => {
+		if (lockedRef.current) return;
+		carried.current = void 0;
+		restart();
+	}, [restart]);
+	return useMemo(() => ({
+		run,
+		snapshot,
+		compiled,
+		reset,
+		holdThen,
+		runThen
+	}), [
+		run,
+		snapshot,
+		compiled,
+		reset,
+		holdThen,
+		runThen
+	]);
+}
+//#endregion
+//#region src/hooks/use-action.ts
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isStandard = (value) => isObject(value) && isObject(value["~standard"]) && typeof value["~standard"].validate === "function";
+function schemaOf(declared, attachment) {
+	if (isStandard(declared)) return declared;
+	if (!isObject(declared)) return void 0;
+	const schema = declared.schema;
+	if (isStandard(schema)) return schema;
+	if (isObject(schema) && typeof schema.capability === "string" && typeof schema.id === "string") {
+		const resolved = attachment(schema.capability, schema.id);
+		if (isStandard(resolved)) return resolved;
+		if (isObject(resolved) && isStandard(resolved.schema)) return resolved.schema;
+	}
+}
+async function invalidArg(compiled, args, attachment) {
+	const declared = compiled.flow.args;
+	for (const [name, entry] of Object.entries(declared ?? {})) {
+		const optional = isObject(entry) && (entry.optional === true || entry.isOptional === true);
+		if (args[name] === void 0 && optional) continue;
+		const schema = schemaOf(entry, attachment);
+		if (schema === void 0) continue;
+		if ((await schema["~standard"].validate(args[name])).issues !== void 0) return name;
+	}
+	return null;
+}
+function useAction(target, opts = {}) {
+	const app = useApp();
+	const navigate = useRouteNavigate();
+	const { run, snapshot, compiled } = useFlowRun(target, {
+		...opts.record === void 0 ? {} : { record: opts.record },
+		...opts.args === void 0 ? {} : { args: opts.args },
+		surface: "code",
+		linkOnly: true
+	});
+	const named = isFlowRef(target) ? target.target : target;
+	const resolveRow = useFlowRowResolver("resource" in named ? named.resource : "");
+	const pageHosted = compiled?.flow.host === "page";
+	const hostPage = useHostPage(compiled?.flow.host);
+	const hosted = hostPageRef(compiled?.flow.host) !== void 0;
+	const hostGate = usePageFlowGate(named);
+	const pageControl = pageHosted ? resolveRow(compiled.name, opts.record) : void 0;
+	const title = useProjectedTitle(compiled?.resource ?? void 0, compiled === null ? void 0 : opts.record?.[compiled.idField] ?? opts.record?.id, opts.record);
+	const present = usePresentFlow();
+	const presentInput = {
+		label: compiled === null ? "" : typeof compiled.flow.label === "string" ? compiled.flow.label : humanizeKey(compiled.name),
+		...opts.record === void 0 || title === "" ? {} : { title },
+		...opts.record === void 0 ? {} : { record: opts.record },
+		...opts.args === void 0 ? {} : { args: opts.args }
+	};
+	const hostRef = useRef({
+		present,
+		presentInput,
+		target
+	});
+	hostRef.current = {
+		present,
+		presentInput,
+		target
+	};
+	const inflight = useRef(null);
+	const hostState = hosted ? conjoinHostPage(hostGate.answer.state === "available" ? "ready" : hostGate.answer.state === "hidden" ? "absent" : hostGate.answer.state, hostPage) : void 0;
+	const hostLink = hostState === void 0 ? void 0 : {
+		state: hostState,
+		href: hostPage?.href ?? ""
+	};
+	const latest = useRef({
+		run,
+		snapshot,
+		compiled,
+		args: opts.args,
+		pageControl,
+		hostLink
+	});
+	latest.current = {
+		run,
+		snapshot,
+		compiled,
+		args: opts.args,
+		pageControl,
+		hostLink
+	};
+	const pageOf = useRef({
+		navigate,
+		app,
+		record: opts.record
+	});
+	pageOf.current = {
+		navigate,
+		app,
+		record: opts.record
+	};
+	const attachments = useMemo(() => compiled === null ? () => void 0 : trustedFlowAttachments(app.runtime, compiled), [app, compiled]);
+	const runNow = useCallback(() => {
+		if (inflight.current !== null) return inflight.current;
+		const { run: current, snapshot: now, compiled: flow, args, pageControl: link, hostLink: pageLink } = latest.current;
+		if (pageLink !== void 0) {
+			if (pageLink.state !== "ready" || pageLink.href === "") return Promise.resolve(Object.freeze({
+				outcome: "unavailable",
+				state: pageLink.state
+			}));
+			pageOf.current.navigate(pageLink.href);
+			return Promise.resolve(Object.freeze({ outcome: "navigated" }));
+		}
+		if (flow !== null && link !== void 0) {
+			if (link.state !== "ready") return Promise.resolve(Object.freeze({
+				outcome: "unavailable",
+				state: link.state
+			}));
+			const { navigate: go, app: owner, record } = pageOf.current;
+			const id = record?.[flow.idField] ?? record?.id;
+			if (typeof id !== "string" && typeof id !== "number" || String(id) === "" || flow.resource === null) {
+				if (process.env.NODE_ENV !== "production") console.error(`[burojs] useAction(${flow.flowId}): a page-hosted flow needs the record it runs on; nothing was opened.`);
+				return Promise.resolve(Object.freeze({ outcome: "failed" }));
+			}
+			go(hrefFor(owner.registry, flow.resource, {
+				action: "flow",
+				id: String(id),
+				flow: flow.name
+			}));
+			return Promise.resolve(Object.freeze({ outcome: "navigated" }));
+		}
+		if (current === null || flow === null || now.control === "undecided" || now.control === "absent") return Promise.resolve(Object.freeze({
+			outcome: "unavailable",
+			state: current === null && flow !== null ? "undecided" : now.control
+		}));
+		const started = (async () => {
+			const invalid = await invalidArg(flow, args ?? {}, attachments);
+			if (invalid !== null) {
+				if (process.env.NODE_ENV !== "production") console.error(`[burojs] useAction(${flow.flowId}): args.${invalid} does not match the flow's declared args; nothing was run.`);
+				return Object.freeze({ outcome: "failed" });
+			}
+			if (flow.hasHost) {
+				const { present: open, presentInput: given, target: what } = hostRef.current;
+				const closed = open({
+					...given,
+					target: what,
+					host: flow.flow.host === "sheet" ? "sheet" : "dialog"
+				});
+				if (closed !== null) return closed;
+			}
+			return current.submit();
+		})();
+		inflight.current = started;
+		started.finally(() => {
+			if (inflight.current === started) inflight.current = null;
+		});
+		return started;
+	}, [attachments]);
+	const state = hostState ?? (pageControl === void 0 ? snapshot.control : pageControl.state);
+	const reason = hosted ? hostGate.answer.state === "disabled" ? hostGate.answer.reason : void 0 : pageControl === void 0 ? snapshot.reason : pageControl.reason;
+	return useMemo(() => Object.freeze({
+		state,
+		...reason === void 0 ? {} : { reason },
+		run: runNow
+	}), [
+		state,
+		reason,
+		runNow
+	]);
+}
+//#endregion
+//#region src/flows/use-flow-form.ts
+const NO_FIELDS = Object.freeze({});
+function useFlowForm(run, compiled, snapshot, opts = {}) {
+	const form = compiled?.flow.form;
+	const userId = useCurrentUserId();
+	const fields = useMemo(() => form === void 0 ? NO_FIELDS : fieldEntriesToMap(form.fields), [compiled]);
+	const tree = form?.body;
+	const body = useMemo(() => tree === void 0 ? void 0 : () => tree, [compiled]);
+	const recordId = opts.record === void 0 || compiled === null ? void 0 : opts.record[compiled.idField] ?? opts.record.id;
+	const flowDraft = useMemo(() => ({
+		...typeof recordId === "string" || typeof recordId === "number" ? { recordId: String(recordId) } : {},
+		...opts.args === void 0 || Object.keys(opts.args).length === 0 ? {} : { argsHash: fnv1a(opts.args) },
+		...opts.selection === void 0 || compiled?.each === true ? {} : { selectionHash: fnv1a([...opts.selection].sort()) },
+		...compiled === null ? {} : { attempt: flowAttemptKey(compiled, userId, opts.record, opts.args, opts.selection) }
+	}), [
+		String(recordId),
+		JSON.stringify(opts.args ?? null),
+		(opts.selection ?? []).join("\0"),
+		compiled,
+		userId
+	]);
+	const onChange = useCallback((values) => run?.setValues(values), [run]);
+	const blocks = useFlowFormCatalog();
+	const metaSources = useMemo(() => Object.freeze({
+		record: Object.freeze({
+			status: "ready",
+			value: opts.record ?? null,
+			refreshing: false
+		}),
+		args: Object.freeze({
+			status: "ready",
+			value: opts.args ?? {},
+			refreshing: false
+		})
+	}), [opts.record, opts.args]);
+	const controller = useFormController({
+		blocks,
+		metaSources,
+		fields,
+		...body === void 0 ? {} : { body },
+		mode: "create",
+		surface: "create",
+		...compiled === null ? {} : {
+			formId: compiled.formId,
+			i18nPrefix: compiled.resource === null ? `appActions.${compiled.name}` : `${compiled.resource}.actions.${compiled.name}`
+		},
+		...form?.draft === void 0 || run === null ? {} : { draft: form.draft },
+		...run === null ? {} : { flowRun: run },
+		flowDraft,
+		flowIssues: snapshot.issues,
+		value: snapshot.values,
+		onChange
+	});
+	const seeded = useRef(null);
+	const opened = snapshot.history.includes("open");
+	useEffect(() => {
+		if (run === null || !opened || seeded.current === run) return;
+		seeded.current = run;
+		controller.reset(run.getSnapshot().values);
+	}, [
+		run,
+		opened,
+		controller
+	]);
+	const succeeded = snapshot.outcome?.outcome === "success";
+	const outcome = snapshot.outcome;
+	const cleared = useRef(null);
+	useEffect(() => {
+		if (!succeeded || cleared.current === outcome) return;
+		cleared.current = outcome;
+		controller.reset(snapshot.values);
+		controller.draft.discard();
+	}, [
+		succeeded,
+		outcome,
+		snapshot.values,
+		controller
+	]);
+	return controller;
+}
+//#endregion
+//#region src/flows/use-flow-host.ts
+function useFlowHost(flow, opts) {
+	const runtime = useUIPresentationRuntime();
+	const mount = useOptionalPresentationMount();
+	const registry = useContext(DismissRegistryContext);
+	const enclosing = useContext(DismissScopeContext);
+	const activation = useCurrentUIActivation();
+	const [openId, setOpenId] = useState(null);
+	const [closed, setClosed] = useState(0);
+	const current = useRef(null);
+	const latest = useRef({
+		flow,
+		opts
+	});
+	latest.current = {
+		flow,
+		opts
+	};
+	const open = useCallback((hostOverride) => {
+		const { flow: now, opts: given } = latest.current;
+		const { run, compiled } = now;
+		if (run === null || compiled === null || mount === null) return null;
+		if (current.current !== null) return null;
+		const host = hostOverride ?? (compiled.flow.host === "sheet" ? "sheet" : "dialog");
+		if (mount.mode === "app" && !mount.registry.isMounted()) {
+			console.error(`[burojs] ${compiled.flowId} opened nothing: BuroProvider is in presentations="app" mode but no <BuroPresentationOutlet/> is mounted.`);
+			return null;
+		}
+		if (mount.hosts[host] === void 0) {
+			reportMissingFlowHost(mount.registry, host);
+			return null;
+		}
+		if (mount.hosts.screens?.flow === void 0) {
+			reportMissingFlowHost(mount.registry, "screens.flow");
+			return null;
+		}
+		const props = {
+			run,
+			host,
+			label: given.label,
+			compiled,
+			...given.title === void 0 ? {} : { title: given.title },
+			...given.record === void 0 ? {} : { record: given.record },
+			...given.args === void 0 ? {} : { args: given.args },
+			...given.selection === void 0 ? {} : { selection: given.selection }
+		};
+		const result = runtime.present({
+			component: FLOW_COMPONENT,
+			host,
+			props: { entry: new FlowScreenEntry(props) },
+			options: {
+				ownTitle: true,
+				wrapper: false
+			},
+			activation
+		});
+		if (!result.ok) return null;
+		if (registry !== null && enclosing !== null) registry.recordParent(result.instance.id, enclosing.id);
+		let settle = () => void 0;
+		const closed = new Promise((resolve) => {
+			settle = resolve;
+		});
+		current.current = {
+			id: result.instance.id,
+			settle,
+			run
+		};
+		now.holdThen(true);
+		setOpenId(result.instance.id);
+		return closed;
+	}, [
+		runtime,
+		mount,
+		registry,
+		enclosing,
+		activation
+	]);
+	useEffect(() => {
+		if (openId === null) return;
+		const check = () => {
+			const open = current.current;
+			if (open === null || open.id !== openId) return;
+			if (runtime.getSnapshot().some((descriptor) => descriptor.id === openId)) return;
+			current.current = null;
+			const snapshot = open.run.getSnapshot();
+			open.settle(snapshot.outcome ?? Object.freeze({
+				outcome: "halted",
+				step: snapshot.step
+			}));
+			setOpenId(null);
+			setClosed((value) => value + 1);
+		};
+		check();
+		return runtime.subscribe(check);
+	}, [runtime, openId]);
+	useEffect(() => {
+		if (closed === 0) return;
+		latest.current.flow.holdThen(false);
+		latest.current.flow.runThen();
+		latest.current.flow.reset();
+	}, [closed]);
+	useEffect(() => () => {
+		const open = current.current;
+		if (open === null) return;
+		current.current = null;
+		runtime.dismiss(open.id);
+		const snapshot = open.run.getSnapshot();
+		open.settle(snapshot.outcome ?? Object.freeze({
+			outcome: "halted",
+			step: snapshot.step
+		}));
+	}, [runtime]);
+	return useMemo(() => ({
+		open,
+		isOpen: openId !== null
+	}), [open, openId]);
+}
+//#endregion
+//#region src/flows/forget-each.ts
+function useForgetEachAttempt(target) {
+	const app = useApp();
+	const userId = useCurrentUserId();
+	const store = useFlowAttemptsStore();
+	const audit = useFrameworkAudit();
+	const latest = useRef({
+		app,
+		userId,
+		store,
+		audit,
+		target
+	});
+	latest.current = {
+		app,
+		userId,
+		store,
+		audit,
+		target
+	};
+	return useCallback(async (id) => {
+		const { app: now, userId: user, store: tab, audit: sink, target: what } = latest.current;
+		if (user === null || tab === null || tab.user !== user || id === "") return false;
+		const named = isFlowRef(what) ? what.target : what;
+		if ("appAction" in named) return false;
+		const def = now.registry.get(named.resource);
+		if (def === void 0) return false;
+		const compiled = compileFlow(def, named.action);
+		const key = attemptKey({
+			user,
+			flow: compiled.flowId,
+			slot: attemptSlot({ record: id })
+		});
+		const stored = tab.port.read(key) ?? await tab.port.ask(key);
+		if (stored === null || stored.flow !== compiled.flowId) return false;
+		tab.port.drop(key);
+		sink?.emit(Object.freeze({
+			type: "flow.submit",
+			flow: compiled.flowId,
+			...compiled.resource === null ? {} : { resource: compiled.resource },
+			recordId: id,
+			mutation: compiled.mutationRef,
+			idempotencyKey: stored.key,
+			attempt: 1,
+			outcome: "unknown",
+			resolvedBy: "user",
+			acceptedWarnings: Object.freeze([]),
+			diff: Object.freeze({})
+		}), { initiates: true });
+		return true;
+	}, []);
+}
+//#endregion
+export { useAction, useFlowForm, useFlowHost, useFlowRun, useForgetEachAttempt };
+
+//# sourceMappingURL=flows-runtime.js.map