@cynodia/axiom-runtime 0.6.0-alpha.1 → 0.6.2-alpha.1

package/README.md

@@ -19,13 +19,13 @@ Main exports: `createAxiomRuntime`, `createBrowserHost`, `createMemoryHost`,
 ## Installation
 
 ```bash
-npm install @cynodia/axiom-runtime@alpha
+npm install @cynodia/axiom-runtime
 ```
 
 Most applications should install the facade package instead, which re-exports this one:
 
 ```bash
-npm install @cynodia/axiom@alpha
+npm install @cynodia/axiom
 ```
 
 

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './mutation/store.js';
 export * from './mutation/transaction.js';
 export * from './mutation/resolve-location.js';
 export * from './mutation/mutation-engine.js';
+export * from './remote.js';
 export * from './format.js';
 export * from './presentation-classes.js';
 export * from './runtime.js';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from './mutation/store.js';
 export * from './mutation/transaction.js';
 export * from './mutation/resolve-location.js';
 export * from './mutation/mutation-engine.js';
+export * from './remote.js';
 export * from './format.js';
 export * from './presentation-classes.js';
 export * from './runtime.js';

package/dist/mutation/values.d.ts

@@ -31,6 +31,16 @@ export declare function isPresent(value: unknown): boolean;
 export declare function isEmptyValue(value: unknown): boolean;
 export declare function toBoolean(value: unknown): boolean;
 export declare function toText(value: unknown): string;
+/**
+ * Lexicographic order by Unicode code point.
+ *
+ * Not locale collation, and deliberately not the language's default string comparison:
+ * ordering is part of the semantic contract, so two conforming runtimes must agree on it
+ * character for character. Code points are the one ordering every language can reproduce
+ * exactly — a UTF-16 comparison, which is what `<` does here, disagrees with a UTF-8 one
+ * whenever a string mixes astral characters with U+E000..U+FFFF.
+ */
+export declare function compareText(left: string, right: string): number;
 export declare function compareValues(left: unknown, right: unknown): number;
 export declare function valuesEqual(left: unknown, right: unknown): boolean;
 //# sourceMappingURL=values.d.ts.map

package/dist/mutation/values.js

@@ -76,13 +76,33 @@ export function toText(value) {
     }
     return JSON.stringify(value);
 }
+/**
+ * Lexicographic order by Unicode code point.
+ *
+ * Not locale collation, and deliberately not the language's default string comparison:
+ * ordering is part of the semantic contract, so two conforming runtimes must agree on it
+ * character for character. Code points are the one ordering every language can reproduce
+ * exactly — a UTF-16 comparison, which is what `<` does here, disagrees with a UTF-8 one
+ * whenever a string mixes astral characters with U+E000..U+FFFF.
+ */
+export function compareText(left, right) {
+    const leftPoints = Array.from(left);
+    const rightPoints = Array.from(right);
+    const shared = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < shared; index += 1) {
+        const leftPoint = leftPoints[index].codePointAt(0);
+        const rightPoint = rightPoints[index].codePointAt(0);
+        if (leftPoint !== rightPoint) {
+            return leftPoint < rightPoint ? -1 : 1;
+        }
+    }
+    return leftPoints.length === rightPoints.length ? 0 : leftPoints.length < rightPoints.length ? -1 : 1;
+}
 export function compareValues(left, right) {
     if (typeof left === 'number' && typeof right === 'number') {
         return left === right ? 0 : left < right ? -1 : 1;
     }
-    const leftText = toText(left);
-    const rightText = toText(right);
-    return leftText === rightText ? 0 : leftText < rightText ? -1 : 1;
+    return compareText(toText(left), toText(right));
 }
 /** A stable serialization, so record comparison does not depend on key order. */
 function canonical(value) {

package/dist/remote.d.ts

@@ -0,0 +1,51 @@
+import type { NodeId, RuntimeDiagnostic } from './runtime-types.js';
+/**
+ * A browser-safe gateway to an Axiom authority.
+ *
+ * It lives here, in the runtime, rather than in the server package, because a browser
+ * client needs it and that package imports Node built-ins a browser has no use for.
+ * Everything below uses `fetch` and nothing else, so a generated page can reach an
+ * authority with no application code and no Node dependency at all.
+ *
+ * The protocol is the semantic one: the client asks for actions, never for URLs. The
+ * endpoint is a single path, the same for every application.
+ */
+/** Must match `PROTOCOL_VERSION` in `@cynodia/axiom-server`. */
+export declare const AXIOM_PROTOCOL_VERSION = "axiom.protocol.v1";
+/** The endpoint an Axiom authority answers on, unless a host says otherwise. */
+export declare const AXIOM_DEFAULT_ENDPOINT = "/axiom";
+export interface HttpRemoteGatewayOptions {
+    /** Defaults to `/axiom` on the current origin. */
+    endpoint?: string;
+    /** Read per request, so a host can refresh a credential without rebuilding the client. */
+    credential?: () => string | null;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+/**
+ * Builds the gateway a client runtime is configured with.
+ *
+ * ```ts
+ * createAxiomRuntime({ ir, rootElement, host, remote: createHttpRemoteGateway() });
+ * ```
+ *
+ * A transport failure becomes a structured diagnostic rather than an exception escaping
+ * into application code, so a refused or unreachable authority reaches the interface the
+ * same way a refused local action does.
+ */
+export declare function createHttpRemoteGateway(options?: HttpRemoteGatewayOptions): {
+    invoke(request: {
+        actionId: NodeId;
+        arguments: Record<string, unknown>;
+        requestId: string;
+    }): Promise<{
+        ok: boolean;
+        diagnostics: RuntimeDiagnostic[];
+        changes: Record<NodeId, unknown>;
+    }>;
+    snapshot(): Promise<{
+        states: Record<NodeId, unknown>;
+    }>;
+};
+//# sourceMappingURL=remote.d.ts.map

package/dist/remote.js

@@ -0,0 +1,101 @@
+/**
+ * A browser-safe gateway to an Axiom authority.
+ *
+ * It lives here, in the runtime, rather than in the server package, because a browser
+ * client needs it and that package imports Node built-ins a browser has no use for.
+ * Everything below uses `fetch` and nothing else, so a generated page can reach an
+ * authority with no application code and no Node dependency at all.
+ *
+ * The protocol is the semantic one: the client asks for actions, never for URLs. The
+ * endpoint is a single path, the same for every application.
+ */
+/** Must match `PROTOCOL_VERSION` in `@cynodia/axiom-server`. */
+export const AXIOM_PROTOCOL_VERSION = 'axiom.protocol.v1';
+/** The endpoint an Axiom authority answers on, unless a host says otherwise. */
+export const AXIOM_DEFAULT_ENDPOINT = '/axiom';
+function unreachable(message) {
+    return {
+        code: 'AUTHORITY_UNREACHABLE',
+        message,
+        severity: 'error',
+    };
+}
+/**
+ * Builds the gateway a client runtime is configured with.
+ *
+ * ```ts
+ * createAxiomRuntime({ ir, rootElement, host, remote: createHttpRemoteGateway() });
+ * ```
+ *
+ * A transport failure becomes a structured diagnostic rather than an exception escaping
+ * into application code, so a refused or unreachable authority reaches the interface the
+ * same way a refused local action does.
+ */
+export function createHttpRemoteGateway(options = {}) {
+    const endpoint = options.endpoint ?? AXIOM_DEFAULT_ENDPOINT;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    async function send(body) {
+        if (!fetchImpl) {
+            throw new Error('No fetch implementation is available');
+        }
+        const controller = options.timeoutMs && typeof AbortController === 'function' ? new AbortController() : undefined;
+        const timer = controller ? setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+        try {
+            const response = await fetchImpl(endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    ...body,
+                    protocol: AXIOM_PROTOCOL_VERSION,
+                    credential: options.credential?.() ?? null,
+                }),
+                ...(controller ? { signal: controller.signal } : {}),
+            });
+            if (!response.ok) {
+                throw new Error(`The authority answered ${response.status}`);
+            }
+            return (await response.json());
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    }
+    return {
+        async invoke(request) {
+            try {
+                const answer = await send({
+                    kind: 'invoke',
+                    actionId: request.actionId,
+                    arguments: request.arguments,
+                    requestId: request.requestId,
+                });
+                if (answer.kind === 'result') {
+                    return {
+                        ok: answer.ok === true,
+                        diagnostics: answer.diagnostics ?? [],
+                        changes: answer.changes ?? {},
+                    };
+                }
+                return { ok: false, diagnostics: answer.diagnostics ?? [], changes: {} };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    diagnostics: [unreachable(error instanceof Error ? error.message : String(error))],
+                    changes: {},
+                };
+            }
+        },
+        async snapshot() {
+            // A failed snapshot must reject: `start()` distinguishes "not loaded" from "empty",
+            // and swallowing the failure here would erase that difference.
+            const answer = await send({ kind: 'snapshot' });
+            if (answer.kind !== 'snapshot' || !answer.snapshot) {
+                throw new Error('The authority did not return a snapshot');
+            }
+            return { states: answer.snapshot.states ?? {} };
+        },
+    };
+}

package/dist/runtime-types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The handful of types the browser-safe gateway needs, declared without importing the
+ * runtime module.
+ *
+ * `remote.ts` is inlined into generated pages, and a value import from core would be
+ * stripped from that bundle. Keeping these local also means the gateway pulls in nothing
+ * else at all.
+ */
+/**
+ * Structurally identical to `NodeId` in `@cynodia/axiom-core`, and it must stay that way:
+ * the brand exists only at compile time, so declaring the same shape here makes the two the
+ * same type without an import the browser bundle cannot carry.
+ * `packages/runtime/test/host.test.ts` fails if the two declarations drift apart.
+ */
+export type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
+export interface RuntimeDiagnostic {
+    /**
+     * A code from `RUNTIME_DIAGNOSTIC_CODES` or `SERVER_DIAGNOSTIC_CODES`, but typed as a
+     * string here on purpose: a diagnostic arriving over the wire is untrusted input, and a
+     * gateway cannot promise it is one of ours. Match on it; do not switch exhaustively.
+     */
+    code: string;
+    message: string;
+    severity: 'error' | 'warning';
+    details?: Record<string, unknown>;
+    nodeId?: NodeId;
+    actionId?: NodeId;
+    constraintId?: NodeId;
+    stateId?: NodeId;
+    transactionId?: string;
+}
+/**
+ * How a client runtime reaches an authority.
+ *
+ * It lives here, beside the browser-safe gateway, rather than in `runtime.ts`, so that the
+ * gateway a page is given and the gateway the runtime accepts are the **same type**. When
+ * they were declared separately, `createHttpRemoteGateway()` did not typecheck as one and
+ * every consumer needed a cast — for a value the framework hands them itself.
+ */
+export interface RemoteGateway {
+    invoke(request: {
+        actionId: NodeId;
+        arguments: Record<string, unknown>;
+        requestId: string;
+    }): Promise<{
+        ok: boolean;
+        diagnostics: RuntimeDiagnostic[];
+        changes: Record<NodeId, unknown>;
+    }>;
+    /** The authoritative values of every observable state. */
+    snapshot?(): Promise<{
+        states: Record<NodeId, unknown>;
+    }>;
+}
+//# sourceMappingURL=runtime-types.d.ts.map

package/dist/runtime-types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime.d.ts

@@ -1,3 +1,4 @@
+import type { RemoteGateway } from './runtime-types.js';
 import type { ApplicationIR, CompiledRoute, Expression, FieldId, Location, NodeId } from '@cynodia/axiom-core';
 import type { DomElement, HostEnvironment } from './dom.js';
 import type { MutationLogEntry } from './mutation/mutation-engine.js';
@@ -33,6 +34,8 @@ export declare const RUNTIME_DIAGNOSTIC_CODES: {
     readonly SERVER_STATE_WRITE: "SERVER_STATE_WRITE";
     /** An action belongs to the authority, but no gateway to it was configured. */
     readonly REMOTE_ACTION_UNAVAILABLE: "REMOTE_ACTION_UNAVAILABLE";
+    /** The authority could not be reached. Authoritative state was not loaded. */
+    readonly AUTHORITY_UNREACHABLE: "AUTHORITY_UNREACHABLE";
 };
 export type RuntimeDiagnosticCode = (typeof RUNTIME_DIAGNOSTIC_CODES)[keyof typeof RUNTIME_DIAGNOSTIC_CODES];
 /**
@@ -70,21 +73,7 @@ export interface ActionResult {
  * is dispatched and answered later, so `invokeAction` returns `pending` and the outcome
  * arrives through the same diagnostic lifecycle a local refusal uses.
  */
-export interface RemoteGateway {
-    invoke(request: {
-        actionId: NodeId;
-        arguments: Record<string, unknown>;
-        requestId: string;
-    }): Promise<{
-        ok: boolean;
-        diagnostics: RuntimeDiagnostic[];
-        changes: Record<NodeId, unknown>;
-    }>;
-    /** The authoritative values of every observable state. */
-    snapshot?(): Promise<{
-        states: Record<NodeId, unknown>;
-    }>;
-}
+export type { RemoteGateway } from './runtime-types.js';
 /**
  * The outcome of an action's most recent invocation.
  *
@@ -126,7 +115,35 @@ export interface AxiomRuntimeOptions {
     recordMutationValues?: boolean;
 }
 export interface AxiomRuntime {
-    start(): void;
+    /**
+     * Brings the runtime to its initial usable state.
+     *
+     * The lifecycle is fixed and does not depend on whether a gateway is configured:
+     *
+     * 1. local state is initialized from `initialValue` and persistence, before anything else;
+     * 2. route matching is resolved and the application renders once, so a slow authority
+     *    never leaves a blank page;
+     * 3. if a `remote` gateway with a snapshot is configured, authoritative state is loaded
+     *    and applied, and the application renders again.
+     *
+     * `start()` returns a promise that settles when step 3 has completed. Awaiting it is the
+     * whole startup sequence: **there is no second call to remember.** Ignoring the promise
+     * is safe — steps 1 and 2 have already run synchronously — but authoritative state may
+     * not have arrived yet.
+     *
+     * If synchronization fails, the failure is reported as an `AUTHORITY_UNREACHABLE`
+     * diagnostic and `authoritativeStateLoaded()` stays false, so an empty authoritative
+     * collection is never mistaken for a loaded one.
+     */
+    start(): Promise<void>;
+    /**
+     * Whether authoritative state has been loaded successfully.
+     *
+     * `false` with a configured gateway means the authority has not answered — which is not
+     * the same as an authoritative collection that is genuinely empty. Applications with no
+     * remote gateway are always `true`: all their state is local.
+     */
+    authoritativeStateLoaded(): boolean;
     render(): void;
     /** A deep clone of the value. Derived state is recomputed. */
     getState(id: NodeId): unknown;
@@ -169,6 +186,14 @@ export interface AxiomRuntime {
      * provides one.
      */
     syncAuthoritativeState(): Promise<void>;
+    /**
+     * Resolves when no remote invocation is outstanding.
+     *
+     * An action started from the interface has no promise the caller can hold; this is how a
+     * test, a script or a host waits for the authority to have answered without guessing a
+     * delay. Resolves immediately when nothing is in flight.
+     */
+    settled(): Promise<void>;
     /**
      * Evaluates an expression in the root scope, reporting rather than throwing. It is a
      * pure read: an expression cannot change state.

package/dist/runtime.js

@@ -37,6 +37,8 @@ export const RUNTIME_DIAGNOSTIC_CODES = {
     SERVER_STATE_WRITE: 'SERVER_STATE_WRITE',
     /** An action belongs to the authority, but no gateway to it was configured. */
     REMOTE_ACTION_UNAVAILABLE: 'REMOTE_ACTION_UNAVAILABLE',
+    /** The authority could not be reached. Authoritative state was not loaded. */
+    AUTHORITY_UNREACHABLE: 'AUTHORITY_UNREACHABLE',
 };
 const MISSING = Symbol('missing');
 function unwrapType(type) {
@@ -89,6 +91,17 @@ function describeValue(value) {
     }
     return `${typeof value} ${JSON.stringify(value)}`;
 }
+/**
+ * Distinguishes runtimes that share a process.
+ *
+ * `host.uuid()` is the only entropy a runtime has, and a deterministic host — the memory
+ * host, a conformance host, a test double — hands every runtime it constructs the same
+ * sequence. Two clients would then generate the same request id for their first remote
+ * invocation, and the authority would answer the second from the first one's idempotency
+ * record. A counter that lives above the host closes that: within a process it is what
+ * separates two runtimes, and across processes a real host's uuid is.
+ */
+let runtimeSessions = 0;
 export function createAxiomRuntime(options) {
     const { ir, rootElement, host } = options;
     const store = createStateStore();
@@ -97,6 +110,15 @@ export function createAxiomRuntime(options) {
     const diagnostics = [];
     /** Rendered controls, keyed by render instance — not by node id. */
     const inputElements = new Map();
+    /**
+     * How each rendered form submits, keyed by the form's render instance.
+     *
+     * A form with a declared submit control must invoke the action **exactly** as that button
+     * would on its own — same arguments, evaluated in the button's own scope. Registering the
+     * button's invocation here is what makes the two paths literally the same code, rather
+     * than two that have to be kept in step.
+     */
+    const submitInvokers = new Map();
     let focusedInstance = null;
     let focusedCaret = null;
     let started = false;
@@ -112,6 +134,11 @@ export function createAxiomRuntime(options) {
      */
     let applyingAuthoritative = false;
     let remoteRequests = 0;
+    /** Generated once, and only when this runtime can actually talk to an authority. */
+    const sessionId = remote ? `s${(runtimeSessions += 1)}-${host.uuid()}` : '';
+    /** False until the authority has answered, when one is configured. */
+    let authoritativeLoaded = options.remote?.snapshot === undefined;
+    let startup = Promise.resolve();
     const theme = ir.theme;
     const locale = theme?.locale ?? 'en-US';
     /**
@@ -1009,18 +1036,23 @@ export function createAxiomRuntime(options) {
             return { ok: false, diagnostics: [] };
         }
         remoteRequests += 1;
-        // A stable key, so a retry after a lost answer cannot execute the action twice.
-        const requestId = `${ir.id}:${action.id}:${remoteRequests}:${host.uuid()}`;
+        // A stable key, so a retry after a lost answer cannot execute the action twice — and one
+        // carrying this runtime's own session identity, so two clients never claim the same key.
+        const requestId = `${ir.id}:${sessionId}:${action.id}:${remoteRequests}:${host.uuid()}`;
         recordOutcome(action.id, 'pending', []);
         renderApplication();
         const settle = remote
             .invoke({ actionId: action.id, arguments: args, requestId })
             .then((answer) => {
             applyAuthoritative(answer.changes ?? {});
-            answer.diagnostics.forEach(report);
-            recordOutcome(action.id, answer.ok ? 'ok' : 'failed', answer.ok ? [] : answer.diagnostics);
+            // A diagnostic from an authority is untrusted input: its `code` is a string until it
+            // matches something we know. It is carried through unchanged, because a client that
+            // rewrote a refusal would be inventing one.
+            const reported = answer.diagnostics;
+            reported.forEach(report);
+            recordOutcome(action.id, answer.ok ? 'ok' : 'failed', answer.ok ? [] : reported);
             renderApplication();
-            return { ok: answer.ok, diagnostics: answer.diagnostics };
+            return { ok: answer.ok, diagnostics: reported };
         })
             .catch((error) => {
             // A transport failure becomes a structured diagnostic, not an escaping exception.
@@ -1037,10 +1069,54 @@ export function createAxiomRuntime(options) {
             return { ok: false, diagnostics: [failure] };
         });
         pending.set(action.id, settle);
+        void settle.finally(() => {
+            if (pending.get(action.id) === settle) {
+                pending.delete(action.id);
+            }
+        });
         return { ok: false, pending: true, diagnostics: [] };
     }
     /** In-flight remote invocations, so `invokeActionAsync` can await one. */
     const pending = new Map();
+    /**
+     * Waits until nothing is outstanding with an authority.
+     *
+     * A remote action started from the interface — a click, a form submit — returns to the
+     * event handler immediately, so there is no promise for the caller to hold. Without this,
+     * anything driving the UI has to guess a delay. It loops because settling one invocation
+     * may start another.
+     */
+    async function allSettled() {
+        while (pending.size > 0) {
+            await Promise.allSettled([...pending.values()]);
+        }
+    }
+    /**
+     * Loads authoritative state and applies it.
+     *
+     * A failure is a diagnostic, not an exception, and leaves `authoritativeLoaded` false —
+     * so an application can tell "the authority has not answered" from "the collection is
+     * empty", which are very different things to show a person.
+     */
+    async function syncAuthoritative() {
+        if (!remote?.snapshot) {
+            return;
+        }
+        try {
+            const snapshot = await remote.snapshot();
+            applyAuthoritative(snapshot.states ?? {});
+            authoritativeLoaded = true;
+        }
+        catch (error) {
+            authoritativeLoaded = false;
+            report({
+                code: RUNTIME_DIAGNOSTIC_CODES.AUTHORITY_UNREACHABLE,
+                message: `Authoritative state could not be loaded: ${error instanceof Error ? error.message : String(error)}`,
+                severity: 'error',
+            });
+        }
+        renderApplication();
+    }
     function runAction(actionId, args = {}) {
         const remoteAction = remoteActionIds.has(actionId) ? ir.actions[actionId] : undefined;
         if (remoteAction) {
@@ -1446,6 +1522,18 @@ export function createAxiomRuntime(options) {
             }
             return target;
         };
+        /**
+         * `data-control` names the one element a person actually operates.
+         *
+         * A single semantic node can render as more than one element — an input is a label
+         * wrapping a control, and both carry `data-node`, because both are that node. Anything
+         * that wants to type into it, click it or read its value needs the inner one, and
+         * `data-node` cannot say which that is. This can.
+         */
+        const asControl = (target) => {
+            target.setAttribute('data-control', node.id);
+            return target;
+        };
         switch (node.kind) {
             case 'view': {
                 const container = identify(element('div', nodeClasses(node, 'axiom-view')));
@@ -1544,8 +1632,15 @@ export function createAxiomRuntime(options) {
                         actions.appendChild(submit);
                         form.appendChild(actions);
                     }
+                    const formInstance = instanceKey(node.id, path);
                     form.addEventListener('submit', (event) => {
                         event.preventDefault?.();
+                        // A declared control carries the arguments; a generated one has none to carry.
+                        const declared = submitInvokers.get(formInstance);
+                        if (declared) {
+                            declared();
+                            return;
+                        }
                         runAction(submitActionId);
                     });
                 }
@@ -1581,7 +1676,10 @@ export function createAxiomRuntime(options) {
                 const describedBy = [];
                 const control = identify(element(grouped ? 'div' : descriptor.tag, grouped ? 'axiom-radio-group' : 'axiom-control'));
                 if (descriptor.variant) {
-                    control.setAttribute('data-control', descriptor.variant);
+                    control.setAttribute('data-variant', descriptor.variant);
+                }
+                if (!grouped) {
+                    asControl(control);
                 }
                 if (!grouped) {
                     control.setAttribute('id', controlId);
@@ -1599,7 +1697,9 @@ export function createAxiomRuntime(options) {
                     }
                 }
                 if (grouped) {
-                    wrapper.setAttribute('data-control', descriptor.variant ?? 'radio-group');
+                    // A radio group has no single element to operate, so the group itself is it.
+                    wrapper.setAttribute('data-variant', descriptor.variant ?? 'radio-group');
+                    asControl(wrapper);
                 }
                 if (descriptor.variant === 'switch') {
                     control.setAttribute('role', 'switch');
@@ -1743,7 +1843,7 @@ export function createAxiomRuntime(options) {
             }
             case 'button': {
                 const submits = submitControls.get(node.id);
-                const button = identify(element('button', nodeClasses(node, 'axiom-button', submits ? 'axiom-submit' : '')));
+                const button = asControl(identify(element('button', nodeClasses(node, 'axiom-button', submits ? 'axiom-submit' : ''))));
                 button.setAttribute('type', 'button');
                 const label = typeof node.label === 'string' ? node.label : toText(evaluate(node.label, scope));
                 if (presentation?.icon) {
@@ -1769,18 +1869,40 @@ export function createAxiomRuntime(options) {
                 if (reporting) {
                     button.setAttribute('aria-describedby', reporting);
                 }
+                // A remote action is in flight until the authority answers, and a person watching a
+                // button that does nothing will press it again. `pending` is already a semantic
+                // runtime outcome; this is the whole of its presentation — the control says it is
+                // working, and refuses a second invocation until it is not. No async model, no
+                // spinner vocabulary, nothing an author writes.
+                const pending = actionOutcomes.get(node.actionId)?.outcome === 'pending';
+                if (pending) {
+                    button.setAttribute('data-pending', 'true');
+                    button.setAttribute('aria-busy', 'true');
+                    button.setAttribute('disabled', 'true');
+                }
+                /** What this button does, wherever the interaction came from. */
+                const invoke = () => {
+                    if (pending) {
+                        // The authority has not answered the last one. Pressing again would be a second
+                        // transaction, not a retry of the first.
+                        return;
+                    }
+                    const args = {};
+                    for (const [parameterId, argument] of Object.entries(node.arguments ?? {})) {
+                        args[parameterId] = evaluate(argument, scope);
+                    }
+                    runAction(node.actionId, args);
+                };
                 if (submits) {
                     // Native form submission runs the action; a click handler here would run it twice.
+                    // The form invokes exactly this, so the button's arguments are not lost.
                     button.setAttribute('type', 'submit');
+                    submitInvokers.set(instanceKey(submits.formId, path), invoke);
                     return button;
                 }
                 button.addEventListener('click', (event) => {
                     event.preventDefault?.();
-                    const args = {};
-                    for (const [parameterId, argument] of Object.entries(node.arguments ?? {})) {
-                        args[parameterId] = evaluate(argument, scope);
-                    }
-                    runAction(node.actionId, args);
+                    invoke();
                 });
                 return button;
             }
@@ -1828,6 +1950,7 @@ export function createAxiomRuntime(options) {
     }
     function renderApplication() {
         inputElements.clear();
+        submitInvokers.clear();
         const scope = rootScope();
         if (!activeRoute) {
             const missing = element('div', 'axiom-no-route');
@@ -1862,7 +1985,7 @@ export function createAxiomRuntime(options) {
     return {
         start() {
             if (started) {
-                return;
+                return startup;
             }
             started = true;
             host.onPathChange(() => {
@@ -1873,7 +1996,14 @@ export function createAxiomRuntime(options) {
                 inputErrors.clear();
                 renderApplication();
             });
+            // Local state and a first render happen synchronously, so an application is on screen
+            // before the authority is consulted.
             syncRoute();
+            startup = remote?.snapshot ? syncAuthoritative() : Promise.resolve();
+            return startup;
+        },
+        authoritativeStateLoaded() {
+            return authoritativeLoaded;
         },
         render: renderApplication,
         getState(id) {
@@ -1926,13 +2056,11 @@ export function createAxiomRuntime(options) {
             }
             return (await pending.get(id)) ?? result;
         },
-        async syncAuthoritativeState() {
-            if (!remote?.snapshot) {
-                return;
-            }
-            const snapshot = await remote.snapshot();
-            applyAuthoritative(snapshot.states ?? {});
-            renderApplication();
+        syncAuthoritativeState() {
+            return syncAuthoritative();
+        },
+        settled() {
+            return allSettled();
         },
         evaluate(expression) {
             const outcome = tryEvaluate(expression, rootScope(), {});

package/dist/source.js

@@ -12,6 +12,7 @@ const RUNTIME_MODULES = [
     './mutation/resolve-location.js',
     './mutation/mutation-engine.js',
     './format.js',
+    './remote.js',
     './presentation-classes.js',
     './runtime.js',
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-runtime",
-  "version": "0.6.0-alpha.1",
+  "version": "0.6.2-alpha.1",
   "description": "Domain-independent runtime that executes an Axiom application graph.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.6.0-alpha.1"
+    "@cynodia/axiom-core": "0.6.2-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",