@askrjs/askr 0.2.4 → 0.3.1

package/dist/{data-ghKopAbp.js → data-2edW0jhF.js}

@@ -1,10 +1,11 @@
-import { n as enqueueRuntimeTask, y as logger } from "./access-BucjYZcX.js";
-import { d as getCurrentAppRenderRuntime, f as getCurrentComponentInstance, i as claimHookIndex } from "./component-scope-4I3yEMkb.js";
-import { u as recordReadableRead } from "./readable-Di1fzSwm.js";
+import { b as ScheduledWork, f as requestRuntimeWork, v as logger } from "./access-CEA2pOry.js";
+import { d as getCurrentAppRenderRuntime, f as getCurrentComponentInstance, i as claimHookIndex } from "./scope-Cq_iYbTR.js";
+import { a as ownComponentCleanup, r as getComponentLifetimeIdentity } from "./capabilities-Bbf0mlp9.js";
+import { v as recordReadableRead } from "./notify-DxxuDPeY.js";
 import { n as getActiveRenderContext } from "./render-context-B7ohlh6t.js";
-import { c as windowFocused, i as routeActive, n as documentVisible, o as timer } from "./lifecycle-operations-Q0k3EFnG.js";
-import { a as getMutationSlotStore, c as resolveDataRuntimeState, i as getDefaultDataRuntime, n as ensureMutationCleanup, o as getQuerySlotStore, r as ensureQueryCleanup, s as invalidateQueriesForRuntime } from "./data-runtime-7t_Y0iv3.js";
-import { a as normalizeAsyncDataError, i as isCurrentAsyncOperation, n as isAbortError, o as notifySource, t as createReadableSource } from "./shared-CYBH3F8I.js";
+import { a as routeActive, i as windowFocused, n as documentVisible, t as timer } from "./timer-C7uqnJVt.js";
+import { a as getMutationSlotStore, c as resolveDataRuntimeState, i as getDefaultDataRuntime, n as ensureMutationCleanup, o as getQuerySlotStore, r as ensureQueryCleanup, s as invalidateQueriesForRuntime } from "./data-runtime-CxoY98lX.js";
+import { a as normalizeAsyncDataError, i as isCurrentAsyncOperation, n as isAbortError, o as notifySource, t as createReadableSource } from "./shared-kU8yvryp.js";
 //#region src/data/query-key.ts
 function serializeQueryKeyNumber(part) {
 	if (Number.isNaN(part)) return "NaN";
@@ -219,15 +220,82 @@ function createMutation(options) {
 	return created;
 }
 //#endregion
+//#region src/data/query-state.ts
+/** Complete query states; transitions never inherit unrelated status flags. */
+function loadingQueryState() {
+	return {
+		data: null,
+		error: null,
+		loading: true,
+		refreshing: false,
+		stale: false,
+		consistency: "fresh",
+		staleReason: null
+	};
+}
+function freshQueryState(data) {
+	return {
+		data,
+		error: null,
+		loading: false,
+		refreshing: false,
+		stale: false,
+		consistency: "fresh",
+		staleReason: null
+	};
+}
+function refreshingQueryState(data, consistency = "refreshing") {
+	return {
+		data,
+		error: null,
+		loading: false,
+		refreshing: true,
+		stale: true,
+		consistency,
+		staleReason: null
+	};
+}
+function staleQueryState(data, reason) {
+	return {
+		data,
+		error: null,
+		loading: false,
+		refreshing: false,
+		stale: true,
+		consistency: "stale",
+		staleReason: reason
+	};
+}
+function errorQueryState(data, error) {
+	return {
+		data,
+		error,
+		loading: false,
+		refreshing: false,
+		stale: true,
+		consistency: "stale",
+		staleReason: "error"
+	};
+}
+//#endregion
 //#region src/data/query-cell.ts
 const RECONCILE_MAX_ATTEMPTS = 3;
 const RECONCILE_RETRY_DELAY_MS = 25;
+var QueryStartWork = class extends ScheduledWork {
+	constructor(run, settle) {
+		super(run);
+		this.settle = settle;
+	}
+	cancel() {
+		super.cancel();
+		this.settle();
+	}
+};
 var QueryCell = class {
 	constructor(options, key, cache) {
 		this.source = createReadableSource();
 		this.controller = null;
 		this.generation = 0;
-		this.startQueued = false;
 		this.pendingRefresh = null;
 		this.pendingRefreshKind = null;
 		this.pendingRefreshResolve = null;
@@ -238,27 +306,11 @@ var QueryCell = class {
 		this.ownerCount = 0;
 		this.owners = /* @__PURE__ */ new Map();
 		this.warnedDefinitionConflictKeys = /* @__PURE__ */ new Set();
-		this.state = {
-			data: null,
-			error: null,
-			loading: true,
-			refreshing: false,
-			stale: false,
-			consistency: "fresh",
-			staleReason: null
-		};
+		this.state = loadingQueryState();
 		this.options = options;
 		this.key = key;
 		this.cache = cache;
-		if (options.initialData !== void 0) this.state = {
-			data: options.initialData,
-			error: null,
-			loading: false,
-			refreshing: false,
-			stale: false,
-			consistency: "fresh",
-			staleReason: null
-		};
+		if (options.initialData !== void 0) this.state = freshQueryState(options.initialData);
 	}
 	attach(generation, hookIndex) {
 		let hooks = this.owners.get(generation);
@@ -291,7 +343,6 @@ var QueryCell = class {
 		this.destroyed = true;
 		this.controller?.abort();
 		this.controller = null;
-		this.startQueued = false;
 		this.reconcileAttemptCount = 0;
 		this.ownerCount = 0;
 		this.owners.clear();
@@ -335,10 +386,10 @@ var QueryCell = class {
 	}
 	/** @internal Whether a collection should schedule this cell's first load. */
 	needsInitialStart() {
-		return !this.destroyed && this.state.data === null && this.state.error === null && !this.pendingRefresh && !this.startQueued;
+		return !this.destroyed && this.state.data === null && this.state.error === null && !this.pendingRefresh;
 	}
 	ensureStarted() {
-		if (this.destroyed || this.state.data !== null || this.pendingRefresh || this.startQueued || this.options.skipInitialFetch) return;
+		if (this.destroyed || this.state.data !== null || this.pendingRefresh || this.options.skipInitialFetch) return;
 		this.queueStart(void 0, "initial");
 	}
 	refresh() {
@@ -347,7 +398,7 @@ var QueryCell = class {
 			if (this.pendingRefreshKind === "invalidation") {
 				this.controller?.abort();
 				this.queueStart(void 0, "manual", true);
-				return this.pendingRefresh;
+				return this.pendingRefresh ?? Promise.resolve();
 			} else return this.pendingRefresh;
 		}
 		this.queueStart(void 0, "manual");
@@ -365,14 +416,7 @@ var QueryCell = class {
 	markPendingWrite() {
 		if (this.destroyed) return;
 		if (this.state.data === null) return;
-		this.setState({
-			loading: false,
-			error: null,
-			refreshing: true,
-			stale: true,
-			consistency: "pending-write",
-			staleReason: null
-		});
+		this.setState(refreshingQueryState(this.state.data, "pending-write"));
 	}
 	queueStart(reconcileSequence, kind = "manual", continuePending = false) {
 		if (this.destroyed) return;
@@ -380,15 +424,13 @@ var QueryCell = class {
 			this.reconcileAttemptCount = 0;
 			return ++this.reconcileSequence;
 		})();
-		this.startQueued = true;
 		this.pendingRefreshKind = kind;
 		const token = ++this.pendingRefreshToken;
 		if (!continuePending || !this.pendingRefresh) this.pendingRefresh = new Promise((resolve) => {
 			this.pendingRefreshResolve = resolve;
 		});
-		enqueueRuntimeTask(() => {
+		requestRuntimeWork("component", new QueryStartWork(() => {
 			if (token !== this.pendingRefreshToken) return;
-			this.startQueued = false;
 			if (this.destroyed) {
 				this.finishPendingRefresh(token);
 				return;
@@ -396,7 +438,11 @@ var QueryCell = class {
 			this.start(sequence).finally(() => {
 				this.finishPendingRefresh(token);
 			});
-		});
+		}, () => {
+			if (token !== this.pendingRefreshToken) return;
+			this.generation += 1;
+			this.finishPendingRefresh(token);
+		}));
 	}
 	finishPendingRefresh(token = this.pendingRefreshToken) {
 		if (token !== this.pendingRefreshToken) return;
@@ -408,10 +454,7 @@ var QueryCell = class {
 	}
 	setState(next) {
 		if (this.destroyed) return;
-		this.state = {
-			...this.state,
-			...next
-		};
+		this.state = next;
 		notifySource(this.source);
 	}
 	async start(reconcileSequence) {
@@ -422,45 +465,17 @@ var QueryCell = class {
 		const controller = new AbortController();
 		this.controller = controller;
 		const hasData = this.state.data !== null;
-		this.setState({
-			loading: !hasData,
-			refreshing: hasData,
-			stale: hasData,
-			consistency: hasData ? "refreshing" : "fresh",
-			error: null,
-			staleReason: null
-		});
+		this.setState(hasData ? refreshingQueryState(this.state.data) : loadingQueryState());
 		let nextData;
 		try {
 			nextData = await this.options.fetch({ signal: controller.signal });
 		} catch (error) {
 			if (this.destroyed || !isCurrentAsyncOperation(this.generation, generation, this.controller, controller)) return;
 			if (isAbortError(error, controller.signal)) {
-				this.setState(hasData ? {
-					loading: false,
-					refreshing: false,
-					stale: true,
-					consistency: "stale",
-					error: null,
-					staleReason: "aborted"
-				} : {
-					loading: true,
-					refreshing: false,
-					stale: false,
-					consistency: "fresh",
-					error: null,
-					staleReason: null
-				});
+				this.setState(hasData ? staleQueryState(this.state.data, "aborted") : loadingQueryState());
 				return;
 			}
-			this.setState({
-				loading: false,
-				refreshing: false,
-				stale: true,
-				consistency: "stale",
-				error: normalizeAsyncDataError(error, "Unknown query error"),
-				staleReason: "error"
-			});
+			this.setState(errorQueryState(this.state.data, normalizeAsyncDataError(error, "Unknown query error")));
 			return;
 		}
 		if (this.destroyed || !isCurrentAsyncOperation(this.generation, generation, this.controller, controller)) return;
@@ -468,59 +483,26 @@ var QueryCell = class {
 		try {
 			isConsistent = this.options.isConsistent?.(nextData) ?? true;
 		} catch (error) {
-			this.setState({
-				loading: false,
-				refreshing: false,
-				stale: true,
-				consistency: "stale",
-				error: normalizeAsyncDataError(error, "Query consistency check failed"),
-				staleReason: "error"
-			});
+			this.setState(errorQueryState(this.state.data, normalizeAsyncDataError(error, "Query consistency check failed")));
 			return;
 		}
 		if (!isConsistent) {
-			this.setState({
-				data: nextData,
-				loading: false,
-				refreshing: false,
-				stale: true,
-				consistency: "stale",
-				staleReason: "inconsistent"
-			});
+			this.setState(staleQueryState(nextData, "inconsistent"));
 			try {
 				await this.reconcile(nextData, generation, controller, reconcileSequence);
 			} catch (error) {
-				if (isCurrentAsyncOperation(this.generation, generation, this.controller, controller)) this.setState({
-					loading: false,
-					refreshing: false,
-					stale: true,
-					consistency: "stale",
-					error: normalizeAsyncDataError(error, "Query reconciliation failed"),
-					staleReason: "error"
-				});
+				if (isCurrentAsyncOperation(this.generation, generation, this.controller, controller)) this.setState(errorQueryState(this.state.data, normalizeAsyncDataError(error, "Query reconciliation failed")));
 			}
 			return;
 		}
 		this.reconcileAttemptCount = 0;
-		this.setState({
-			data: nextData,
-			loading: false,
-			refreshing: false,
-			stale: false,
-			consistency: "fresh",
-			error: null,
-			staleReason: null
-		});
+		this.setState(freshQueryState(nextData));
 	}
 	async reconcile(data, generation, controller, reconcileSequence) {
 		if (!await (this.options.reconcile?.(data, { key: this.options.key }) ?? false) || this.destroyed || reconcileSequence !== this.reconcileSequence || !isCurrentAsyncOperation(this.generation, generation, this.controller, controller)) return;
 		this.reconcileAttemptCount += 1;
 		if (this.reconcileAttemptCount > RECONCILE_MAX_ATTEMPTS) {
-			this.setState({
-				consistency: "stale",
-				refreshing: false,
-				staleReason: "inconsistent"
-			});
+			this.setState(staleQueryState(this.state.data, "inconsistent"));
 			return;
 		}
 		await new Promise((resolve) => setTimeout(resolve, RECONCILE_RETRY_DELAY_MS));
@@ -552,7 +534,7 @@ function createLegacyQuery(options) {
 		existingSlot.cell.warnOnConflictingDefinition(options);
 		return existingSlot.cell;
 	}
-	if (existingSlot) existingSlot.cell.detach(instance._ownershipGeneration, hookIndex);
+	if (existingSlot) existingSlot.cell.detach(getComponentLifetimeIdentity(instance), hookIndex);
 	if (override) return override;
 	let cell = cache.get(options.key);
 	if (!cell) {
@@ -564,7 +546,7 @@ function createLegacyQuery(options) {
 		key: options.key,
 		cell
 	});
-	cell.attach(instance._ownershipGeneration, hookIndex);
+	cell.attach(getComponentLifetimeIdentity(instance), hookIndex);
 	return cell;
 }
 function createDefinedQuery(definition, input, options = {}) {
@@ -803,7 +785,7 @@ function createQueryCollection(options) {
 	const concurrency = normalizeQueryCollectionConcurrency(options.concurrency);
 	const inputs = options.inputs();
 	if (!Array.isArray(inputs)) throw new Error("[Askr] createQueryCollection() inputs must return a readonly array.");
-	const generation = instance._ownershipGeneration;
+	const generation = getComponentLifetimeIdentity(instance);
 	const runtimeState = resolveDataRuntimeState(options.runtime);
 	const store = getCollectionStore(generation);
 	let slot = store.get(hookIndex);
@@ -818,10 +800,14 @@ function createQueryCollection(options) {
 			collection: new QueryCollectionCell(runtimeState)
 		};
 		store.set(hookIndex, slot);
-		(instance.cleanupFns ??= []).push(() => {
-			store.get(hookIndex)?.collection.dispose();
-			store.delete(hookIndex);
-			if (store.size === 0 && collectionSlotsByGeneration.get(generation) === store) collectionSlotsByGeneration.delete(generation);
+		ownComponentCleanup(instance, () => {
+			const current = store.get(hookIndex);
+			try {
+				current?.collection.dispose();
+			} finally {
+				store.delete(hookIndex);
+				if (store.size === 0 && collectionSlotsByGeneration.get(generation) === store) collectionSlotsByGeneration.delete(generation);
+			}
 		});
 	}
 	const context = getActiveRenderContext();
@@ -831,4 +817,4 @@ function createQueryCollection(options) {
 	return collection;
 }
 //#endregion
-export { invalidateOnInterval as a, invalidate as i, createQuery as n, queryScope as o, createMutation as r, createQueryCollection as t };
+export { loadingQueryState as a, createMutation as c, queryScope as d, freshQueryState as i, invalidate as l, createQuery as n, refreshingQueryState as o, errorQueryState as r, staleQueryState as s, createQueryCollection as t, invalidateOnInterval as u };

package/dist/{data-runtime-7t_Y0iv3.js → data-runtime-CxoY98lX.js}

@@ -1,4 +1,5 @@
-import { d as getCurrentAppRenderRuntime } from "./component-scope-4I3yEMkb.js";
+import { d as getCurrentAppRenderRuntime, w as drainOwnedCleanup } from "./scope-Cq_iYbTR.js";
+import { a as ownComponentCleanup, r as getComponentLifetimeIdentity } from "./capabilities-Bbf0mlp9.js";
 import { n as getActiveRenderContext } from "./render-context-B7ohlh6t.js";
 //#region src/data/invalidation-listeners.ts
 const invalidationListeners = /* @__PURE__ */ new Set();
@@ -84,7 +85,7 @@ function resolveDataRuntimeState(runtime) {
 	return runtime ? getDataRuntimeState(runtime) : getActiveDataRuntimeState();
 }
 function getQuerySlotStore(runtimeState, instance) {
-	const generation = instance._ownershipGeneration;
+	const generation = getComponentLifetimeIdentity(instance);
 	let store = runtimeState.querySlotsByGeneration.get(generation);
 	if (!store) {
 		store = /* @__PURE__ */ new Map();
@@ -93,7 +94,7 @@ function getQuerySlotStore(runtimeState, instance) {
 	return store;
 }
 function getMutationSlotStore(runtimeState, instance) {
-	const generation = instance._ownershipGeneration;
+	const generation = getComponentLifetimeIdentity(instance);
 	let store = runtimeState.mutationSlotsByGeneration.get(generation);
 	if (!store) {
 		store = /* @__PURE__ */ new Map();
@@ -102,27 +103,33 @@ function getMutationSlotStore(runtimeState, instance) {
 	return store;
 }
 function ensureQueryCleanup(runtimeState, instance) {
-	const generation = instance._ownershipGeneration;
+	const generation = getComponentLifetimeIdentity(instance);
 	if (runtimeState.queryCleanupRegistered.has(generation)) return;
 	runtimeState.queryCleanupRegistered.add(generation);
 	const slots = getQuerySlotStore(runtimeState, instance);
-	(instance.cleanupFns ??= []).push(() => {
-		for (const [hookIndex, slot] of slots) slot.cell.detach(generation, hookIndex);
-		slots.clear();
-		runtimeState.querySlotsByGeneration.delete(generation);
-		runtimeState.queryCleanupRegistered.delete(generation);
+	ownComponentCleanup(instance, () => {
+		try {
+			drainOwnedCleanup(slots, ([hookIndex, slot]) => slot.cell.detach(generation, hookIndex));
+		} finally {
+			slots.clear();
+			runtimeState.querySlotsByGeneration.delete(generation);
+			runtimeState.queryCleanupRegistered.delete(generation);
+		}
 	});
 }
 function ensureMutationCleanup(runtimeState, instance) {
-	const generation = instance._ownershipGeneration;
+	const generation = getComponentLifetimeIdentity(instance);
 	if (runtimeState.mutationCleanupRegistered.has(generation)) return;
 	runtimeState.mutationCleanupRegistered.add(generation);
 	const slots = getMutationSlotStore(runtimeState, instance);
-	(instance.cleanupFns ??= []).push(() => {
-		for (const slot of slots.values()) slot.cell.abort();
-		slots.clear();
-		runtimeState.mutationSlotsByGeneration.delete(generation);
-		runtimeState.mutationCleanupRegistered.delete(generation);
+	ownComponentCleanup(instance, () => {
+		try {
+			drainOwnedCleanup(slots.values(), (slot) => slot.cell.abort());
+		} finally {
+			slots.clear();
+			runtimeState.mutationSlotsByGeneration.delete(generation);
+			runtimeState.mutationCleanupRegistered.delete(generation);
+		}
 	});
 }
 function invalidateQueriesForRuntime(runtimeState, prefix, markPendingWrite) {

package/dist/{deferred-CxjWCkIn.js → deferred-CbgNhf67.js}

@@ -1,9 +1,9 @@
-import { d as getCurrentAppRenderRuntime, f as getCurrentComponentInstance } from "./component-scope-4I3yEMkb.js";
-import { i as getExecutionModel } from "./manifest-D6rfj_jC.js";
+import { d as getCurrentAppRenderRuntime, f as getCurrentComponentInstance } from "./scope-Cq_iYbTR.js";
+import { i as getExecutionModel } from "./manifest-D1P3UNWV.js";
 import { n as getActiveRenderContext, r as getCurrentRenderData } from "./render-context-B7ohlh6t.js";
-import { t as resource } from "./resource-operation-Vz1S5h2k.js";
-import { A as getDefaultRouteBasePath, C as getCurrentInheritedPolicies, D as getCurrentPathPrefix, E as getCurrentPageScope, F as insertRecordSorted, H as computeRank, L as pushRegistrationScope, N as hasActivePageScope, O as getCurrentScopeKind, S as getCurrentInheritedMeta, T as getCurrentPageChain, U as normalizeRouteSegmentName, W as parseSegments, g as assertRouteRegistrationUnlocked, h as addRouteToStores, w as getCurrentLayoutChain, x as getCurrentInheritedAuthRequirements } from "./route-matching-Bo6UqG-5.js";
-import { _ as createRouteHandler, d as DEFERRED_BOUNDARY, p as isDeferred, s as guardHydratedRouteData } from "./resolution-ClD-K7Lz.js";
+import { t as resource } from "./resource-18-sFRl9.js";
+import { S as isDeferred, b as DEFERRED_BOUNDARY, g as guardHydratedRouteData, l as createRouteHandler } from "./resolution-3DskUkjG.js";
+import { C as getCurrentInheritedMeta, D as getCurrentPageScope, E as getCurrentPageChain, H as computeRank, I as insertRecordSorted, O as getCurrentPathPrefix, P as hasActivePageScope, R as pushRegistrationScope, S as getCurrentInheritedAuthRequirements, T as getCurrentLayoutChain, U as normalizeRouteSegmentName, W as parseSegments, g as assertRouteRegistrationUnlocked, h as addRouteToStores, j as getDefaultRouteBasePath, k as getCurrentScopeKind, w as getCurrentInheritedPolicies } from "./route-matching-CUzZ31gT.js";
 import { allOf } from "@askrjs/auth";
 //#region src/router/access.ts
 function compileNodePolicies(node) {

package/dist/dom-renderer.d.ts

@@ -0,0 +1,77 @@
+import type {
+  RuntimeRendererHost,
+  RuntimeKeyedReorderDecision,
+} from './core.js';
+
+declare const ownerBrand: unique symbol;
+declare const scopeBrand: unique symbol;
+declare const sourceBrand: unique symbol;
+/** Opaque component identity scoped to one DOM renderer factory. */
+export interface DOMComponentOwner {
+  readonly [ownerBrand]: never;
+}
+/** Opaque child scope identity scoped to one DOM renderer factory. */
+export interface DOMChildScope {
+  readonly [scopeBrand]: never;
+}
+/** Opaque reactive source identity scoped to one DOM renderer factory. */
+export interface DOMReactiveSource {
+  readonly [sourceBrand]: never;
+}
+/** Read-only boundary of rendered DOM output. */
+export interface DOMRendererRange {
+  readonly start: Node;
+  readonly end: Node;
+  readonly single: boolean;
+}
+/** DOM evaluation and replacement operations. */
+export interface DOMRendererEvaluation {
+  evaluate(
+    node: unknown,
+    target: Element | null,
+    context?: object,
+    retainedOwner?: DOMComponentOwner
+  ): void;
+  replaceComponentRange(
+    owner: DOMComponentOwner,
+    result: unknown,
+    host: Element | Comment
+  ): Node | null;
+}
+/** DOM lifetime cleanup operations. */
+export interface DOMRendererCleanup {
+  cleanupInstancesUnder(node: Node): void;
+  teardownNodeSubtree(root: Node): void;
+}
+/** Child scope boundary inspection. */
+export interface DOMRendererScopes {
+  resolveChildScopeRange(scope: DOMChildScope): DOMRendererRange | null;
+}
+/** Keyed DOM reconciliation operations. */
+export interface DOMRendererKeys {
+  populateKeyMapForElement(parent: Element): void;
+  getKeyMapForElement(
+    parent: Element
+  ): Map<string | number, Element> | undefined;
+  isKeyedReorderFastPathEligible(
+    parent: Element,
+    children: unknown[],
+    oldKeyMap: Map<string | number, Element> | undefined
+  ): RuntimeKeyedReorderDecision;
+}
+/** Reactive DOM invalidation operations. */
+export interface DOMRendererReactivity {
+  markReactivePropsDirtySource(source: DOMReactiveSource): void;
+}
+/** Complete DOM extension roles. Delegate explicitly to the supplied native host. */
+export interface DOMRendererHost {
+  evaluation: DOMRendererEvaluation;
+  cleanup: DOMRendererCleanup;
+  scopes: DOMRendererScopes;
+  keys: DOMRendererKeys;
+  reactivity: DOMRendererReactivity;
+}
+/** Construct a validated DOM adapter without installing it in a runtime. */
+export declare function createDOMRendererHost(
+  configure: (native: DOMRendererHost) => DOMRendererHost
+): RuntimeRendererHost;

package/dist/domains/actions.d.ts

@@ -0,0 +1,70 @@
+import { JSXElementType, JSXElement, Props } from '../elements.js';
+import '../jsx-globals.js';
+import { AuthContext, AuthRequirement } from '@askrjs/auth';
+import { InferSchema, ObjectSchema } from '@askrjs/schema';
+import { StateTuple, state } from './state.js';
+import { RenderableChild } from './context.js';
+import { on } from './lifecycle.js';
+import { invalidate } from './data.js';
+
+/** A declared server action, built by {@link defineAction}, bound to a form via {@link ActionForm}. */
+interface ActionDescriptor<
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+> {
+  readonly id: string;
+  readonly input: ObjectSchema<TInput>;
+  readonly invalidates: readonly string[];
+}
+
+/** Declare a server action with a stable id, input schema, and query prefixes to invalidate on success. */
+declare function defineAction<TInput extends Record<string, unknown>>(options: {
+  readonly id: string;
+  readonly input: ObjectSchema<TInput>;
+  readonly invalidates?: readonly string[];
+}): ActionDescriptor<TInput>;
+
+/** A native form bound to a declared action; it is not a synthetic event API. */
+declare function ActionForm<TInput extends Record<string, unknown>>({
+  action,
+  children,
+  ...props
+}: {
+  readonly action: ActionDescriptor<TInput>;
+  readonly children?: RenderableChild;
+  readonly [key: string]: unknown;
+}): JSXElement;
+
+/** Server-replayed validation failure for an {@link ActionForm} submission. */
+interface ActionValidationError {
+  readonly kind: 'invalid';
+  readonly action: string;
+  readonly values: Readonly<Record<string, unknown>>;
+  readonly issues: readonly unknown[];
+  readonly fieldErrors: Readonly<Record<string, readonly string[]>>;
+}
+
+/** Pending/result/error status for an action, as reported by the `action()` hook. */
+interface ActionStatus<TResult = unknown> {
+  readonly pending: boolean;
+  readonly result?: TResult;
+  readonly error?: unknown;
+}
+
+/** Returns a command handle, rather than a hook. */
+declare function action<
+  TInput extends Record<string, unknown>,
+  TResult = unknown,
+>(
+  descriptor: ActionDescriptor<TInput>
+): {
+  state: StateTuple<ActionStatus<TResult>>;
+  submit(input: TInput): Promise<TResult>;
+};
+export {
+  ActionDescriptor,
+  defineAction,
+  ActionForm,
+  ActionValidationError,
+  ActionStatus,
+  action,
+};