@cynodia/axiom-runtime 0.3.1-alpha.1

package/dist/runtime.js

@@ -0,0 +1,1149 @@
+import { createMutationEngine } from './mutation/mutation-engine.js';
+import { LocationResolutionError, resolveLocation } from './mutation/resolve-location.js';
+import { createStateStore } from './mutation/store.js';
+import { createTransactionManager } from './mutation/transaction.js';
+import { cloneValue, compareValues, deepFreeze, isPresent, isRecord, toBoolean, toText, valuesEqual, } from './mutation/values.js';
+const MISSING = Symbol('missing');
+function unwrapType(type) {
+    return type.kind === 'optional' ? unwrapType(type.valueType) : type;
+}
+function defaultForType(type) {
+    const resolved = unwrapType(type);
+    if (type.kind === 'optional') {
+        return null;
+    }
+    switch (resolved.kind) {
+        case 'collection':
+            return [];
+        case 'primitive':
+            switch (resolved.primitive) {
+                case 'number':
+                    return 0;
+                case 'boolean':
+                    return false;
+                default:
+                    return '';
+            }
+        case 'enum':
+            return resolved.values[0] ?? '';
+        default:
+            return null;
+    }
+}
+export function createAxiomRuntime(options) {
+    const { ir, rootElement, host } = options;
+    const store = createStateStore();
+    const derivedCache = new Map();
+    const natives = new Map(Object.entries(options.nativeOperations ?? {}));
+    const diagnostics = [];
+    const inputElements = new Map();
+    let focusedNodeId = null;
+    let focusedCaret = null;
+    let started = false;
+    let transactionCounter = 0;
+    const mutationLog = [];
+    const inputValidation = options.inputValidation ?? 'immediate';
+    const statesById = new Map(ir.states.map((state) => [state.id, state]));
+    const entitiesById = new Map(ir.entities.map((entity) => [entity.id, entity]));
+    const parameterTypes = new Map();
+    for (const action of Object.values(ir.actions)) {
+        for (const parameter of action.parameters ?? []) {
+            parameterTypes.set(parameter.id, parameter.valueType);
+        }
+    }
+    for (const route of ir.routes) {
+        for (const parameter of route.parameters) {
+            parameterTypes.set(parameter.id, parameter.valueType);
+        }
+    }
+    function report(diagnostic) {
+        diagnostics.push(diagnostic);
+        if (diagnostic.severity === 'error') {
+            host.report?.(`${diagnostic.code}: ${diagnostic.message}`);
+        }
+    }
+    // ---------------------------------------------------------------- state store
+    function storageKey(state) {
+        if (state.persistence?.kind !== 'local-storage') {
+            return null;
+        }
+        return state.persistence.key ?? `${ir.id}:${state.id}`;
+    }
+    function initializeStore() {
+        for (const state of ir.states) {
+            if (state.derivation) {
+                continue;
+            }
+            const key = storageKey(state);
+            if (key && host.storage) {
+                const persisted = host.storage.read(key);
+                if (persisted !== null) {
+                    try {
+                        store.write(state.id, JSON.parse(persisted));
+                        continue;
+                    }
+                    catch {
+                        report({
+                            code: 'PERSISTED_STATE_UNREADABLE',
+                            message: `Stored value for ${state.id} could not be parsed; falling back to the initial value`,
+                            severity: 'warning',
+                            nodeId: state.id,
+                        });
+                    }
+                }
+            }
+            store.write(state.id, state.initialValue === undefined ? defaultForType(state.valueType) : cloneValue(state.initialValue));
+        }
+    }
+    function persistState(stateId) {
+        const state = statesById.get(stateId);
+        if (!state || !host.storage) {
+            return;
+        }
+        const key = storageKey(state);
+        if (key) {
+            host.storage.write(key, JSON.stringify(store.read(stateId) ?? null));
+        }
+    }
+    /**
+     * Derived values are recomputed from their derivation and handed out as frozen copies,
+     * so nothing can work by sharing an object with the state it was derived from.
+     */
+    function readState(stateId) {
+        const state = statesById.get(stateId);
+        if (state?.derivation) {
+            if (derivedCache.has(stateId)) {
+                return derivedCache.get(stateId);
+            }
+            derivedCache.set(stateId, null);
+            const value = deepFreeze(cloneValue(evaluate(state.derivation, rootScope())));
+            derivedCache.set(stateId, value);
+            return value;
+        }
+        return store.read(stateId);
+    }
+    /** The only place the store is written. Values are frozen on the way in. */
+    function writeState(stateId, value) {
+        if (!statesById.has(stateId)) {
+            report({
+                code: 'UNKNOWN_STATE',
+                message: `Cannot write to unknown state ${stateId}`,
+                severity: 'error',
+                nodeId: stateId,
+            });
+            return;
+        }
+        if (statesById.get(stateId)?.derivation) {
+            report({
+                code: 'DERIVED_STATE_WRITE',
+                message: `${stateId} is derived state and cannot be written to`,
+                severity: 'error',
+                nodeId: stateId,
+            });
+            return;
+        }
+        store.write(stateId, value);
+        derivedCache.clear();
+        persistState(stateId);
+    }
+    function restoreStore(snapshot) {
+        store.restore(snapshot);
+        derivedCache.clear();
+    }
+    // ------------------------------------------------------- mutation subsystem
+    const transactions = createTransactionManager({
+        capture: () => store.capture(),
+        restore: restoreStore,
+    }, () => {
+        transactionCounter += 1;
+        return `tx_${transactionCounter}`;
+    });
+    const mutations = createMutationEngine({
+        runtime: {
+            readState: (stateId) => readState(stateId),
+            writeState: (stateId, value) => writeState(stateId, value),
+            evaluate: (expression, scope) => evaluate(expression, scope),
+        },
+        recordValues: options.recordMutationValues !== false,
+        onLog: (entry) => {
+            mutationLog.push(entry);
+        },
+    });
+    /**
+     * Settles a transaction and records the outcome against everything it logged. Only the
+     * outermost transaction decides: a nested one shares its parent's fate.
+     */
+    function settle(transaction, outcome) {
+        if (outcome === 'committed') {
+            transaction.commit();
+        }
+        else {
+            transaction.rollback();
+        }
+        if (!transaction.isRoot) {
+            return;
+        }
+        for (const entry of mutationLog) {
+            if (entry.transactionId === transaction.id && entry.outcome === undefined) {
+                entry.outcome = outcome;
+            }
+        }
+    }
+    /** Applies a mutation inside the current transaction and reports resolution failures. */
+    function mutate(apply, context, failures) {
+        try {
+            return apply();
+        }
+        catch (error) {
+            const failure = {
+                code: error instanceof LocationResolutionError ? 'LOCATION_UNRESOLVED' : 'MUTATION_FAILED',
+                message: error instanceof Error ? error.message : String(error),
+                severity: 'error',
+                ...(context.sourceNodeId ? { nodeId: context.sourceNodeId } : {}),
+            };
+            failures.push(failure);
+            return null;
+        }
+    }
+    // ------------------------------------------------------------------- scopes
+    let activeRoute = null;
+    function rootScope() {
+        const values = new Map();
+        if (activeRoute) {
+            for (const [parameterId, value] of Object.entries(activeRoute.parameters)) {
+                values.set(parameterId, value);
+            }
+        }
+        return { values };
+    }
+    function childScope(parent, id, value) {
+        return { values: new Map([[id, value]]), parent };
+    }
+    function lookup(scope, id) {
+        let current = scope;
+        while (current) {
+            if (current.values.has(id)) {
+                return current.values.get(id);
+            }
+            current = current.parent;
+        }
+        return MISSING;
+    }
+    // --------------------------------------------------------------- evaluation
+    function evaluate(expression, scope) {
+        switch (expression.kind) {
+            case 'literal':
+                return expression.value;
+            case 'ref': {
+                const scoped = lookup(scope, expression.targetId);
+                if (scoped !== MISSING) {
+                    return scoped;
+                }
+                if (statesById.has(expression.targetId)) {
+                    return readState(expression.targetId);
+                }
+                report({
+                    code: 'UNRESOLVED_REFERENCE',
+                    message: `Reference ${expression.targetId} could not be resolved`,
+                    severity: 'error',
+                    nodeId: expression.targetId,
+                });
+                return null;
+            }
+            case 'field': {
+                const source = evaluate(expression.source, scope);
+                if (!isRecord(source)) {
+                    return null;
+                }
+                const value = source[expression.fieldId];
+                return value === undefined ? null : value;
+            }
+            case 'object': {
+                const result = {};
+                for (const entry of expression.entries) {
+                    result[entry.fieldId] = evaluate(entry.value, scope);
+                }
+                return result;
+            }
+            case 'binary':
+                return evaluateBinary(expression.operator, expression.left, expression.right, scope);
+            case 'unary': {
+                const operand = evaluate(expression.operand, scope);
+                return expression.operator === 'not' ? !toBoolean(operand) : -Number(operand ?? 0);
+            }
+            case 'call':
+                return evaluateCall(expression.function, expression.arguments, scope);
+            case 'filter': {
+                const source = evaluate(expression.source, scope);
+                if (!Array.isArray(source)) {
+                    return [];
+                }
+                return source.filter((item) => toBoolean(evaluate(expression.predicate, childScope(scope, expression.scopeId, item))));
+            }
+            case 'find': {
+                const source = evaluate(expression.source, scope);
+                if (!Array.isArray(source)) {
+                    return null;
+                }
+                const found = source.find((item) => toBoolean(evaluate(expression.predicate, childScope(scope, expression.scopeId, item))));
+                return found === undefined ? null : found;
+            }
+            default:
+                report({
+                    code: 'UNKNOWN_EXPRESSION',
+                    message: `Unknown expression kind "${expression.kind}"`,
+                    severity: 'error',
+                });
+                return null;
+        }
+    }
+    function evaluateBinary(operator, leftExpression, rightExpression, scope) {
+        if (operator === 'and') {
+            return toBoolean(evaluate(leftExpression, scope)) && toBoolean(evaluate(rightExpression, scope));
+        }
+        if (operator === 'or') {
+            return toBoolean(evaluate(leftExpression, scope)) || toBoolean(evaluate(rightExpression, scope));
+        }
+        const left = evaluate(leftExpression, scope);
+        const right = evaluate(rightExpression, scope);
+        switch (operator) {
+            case 'eq':
+                return valuesEqual(left, right);
+            case 'neq':
+                return !valuesEqual(left, right);
+            case 'gt':
+                return compareValues(left, right) > 0;
+            case 'gte':
+                return compareValues(left, right) >= 0;
+            case 'lt':
+                return compareValues(left, right) < 0;
+            case 'lte':
+                return compareValues(left, right) <= 0;
+            case 'add':
+                return Number(left ?? 0) + Number(right ?? 0);
+            case 'subtract':
+                return Number(left ?? 0) - Number(right ?? 0);
+            case 'multiply':
+                return Number(left ?? 0) * Number(right ?? 0);
+            case 'divide': {
+                const divisor = Number(right ?? 0);
+                return divisor === 0 ? null : Number(left ?? 0) / divisor;
+            }
+            default:
+                report({ code: 'UNKNOWN_OPERATOR', message: `Unknown operator "${operator}"`, severity: 'error' });
+                return null;
+        }
+    }
+    function evaluateCall(fn, args, scope) {
+        const values = args.map((argument) => evaluate(argument, scope));
+        switch (fn) {
+            case 'required':
+                return isPresent(values[0]);
+            case 'is-empty':
+                return !isPresent(values[0]);
+            case 'length':
+                return Array.isArray(values[0]) ? values[0].length : toText(values[0]).length;
+            case 'count':
+                return Array.isArray(values[0]) ? values[0].length : 0;
+            case 'contains': {
+                const [haystack, needle] = values;
+                if (Array.isArray(haystack)) {
+                    return haystack.some((item) => valuesEqual(item, needle));
+                }
+                return toText(haystack).toLowerCase().includes(toText(needle).toLowerCase());
+            }
+            case 'concat':
+                return values.map(toText).join('');
+            case 'coalesce':
+                return values.find((value) => isPresent(value)) ?? null;
+            case 'one-of':
+                return values.slice(1).some((option) => valuesEqual(option, values[0]));
+            case 'lowercase':
+                return toText(values[0]).toLowerCase();
+            case 'to-string':
+                return toText(values[0]);
+            case 'now':
+                return host.now();
+            case 'uuid':
+                return host.uuid();
+            default:
+                report({ code: 'UNKNOWN_FUNCTION', message: `Unknown function "${fn}"`, severity: 'error' });
+                return null;
+        }
+    }
+    // -------------------------------------------------------------- validation
+    function collectionEntityId(state) {
+        const resolved = unwrapType(state.valueType);
+        if (resolved.kind === 'collection') {
+            const item = unwrapType(resolved.itemType);
+            return item.kind === 'entity' ? item.entityId : null;
+        }
+        return resolved.kind === 'entity' ? resolved.entityId : null;
+    }
+    function instancesOf(entityId) {
+        const instances = [];
+        for (const state of ir.states) {
+            // Drafts are incomplete by definition, and derived states are views of data that
+            // is already validated where it is stored.
+            if (state.draft || state.derivation) {
+                continue;
+            }
+            if (collectionEntityId(state) !== entityId) {
+                continue;
+            }
+            const value = readState(state.id);
+            if (Array.isArray(value)) {
+                instances.push(...value);
+            }
+            else if (isRecord(value)) {
+                instances.push(value);
+            }
+        }
+        return instances;
+    }
+    function checkFieldValue(field, value, entityId) {
+        if (!isPresent(value)) {
+            if (field.required) {
+                return {
+                    code: 'REQUIRED_FIELD_MISSING',
+                    message: `${field.name ?? field.id} is required`,
+                    severity: 'error',
+                    nodeId: entityId,
+                    fieldId: field.id,
+                };
+            }
+            return null;
+        }
+        const resolved = unwrapType(field.valueType);
+        if (resolved.kind === 'enum' && !resolved.values.includes(toText(value))) {
+            return {
+                code: 'ENUM_VALUE_INVALID',
+                message: `${field.name ?? field.id} must be one of: ${resolved.values.join(', ')}`,
+                severity: 'error',
+                nodeId: entityId,
+                fieldId: field.id,
+            };
+        }
+        if (resolved.kind === 'primitive' && resolved.primitive === 'number' && typeof value !== 'number') {
+            return {
+                code: 'TYPE_MISMATCH',
+                message: `${field.name ?? field.id} must be a number`,
+                severity: 'error',
+                nodeId: entityId,
+                fieldId: field.id,
+            };
+        }
+        if (resolved.kind === 'primitive' && resolved.primitive === 'boolean' && typeof value !== 'boolean') {
+            return {
+                code: 'TYPE_MISMATCH',
+                message: `${field.name ?? field.id} must be a boolean`,
+                severity: 'error',
+                nodeId: entityId,
+                fieldId: field.id,
+            };
+        }
+        return null;
+    }
+    /** Schema conformance plus declared constraints, evaluated over live instances. */
+    function evaluateInvariants() {
+        const failures = [];
+        for (const entity of ir.entities) {
+            for (const instance of instancesOf(entity.id)) {
+                if (!isRecord(instance)) {
+                    continue;
+                }
+                for (const field of entity.fields) {
+                    const failure = checkFieldValue(field, instance[field.id], entity.id);
+                    if (failure) {
+                        failures.push(failure);
+                    }
+                }
+            }
+        }
+        for (const constraint of ir.constraints) {
+            failures.push(...evaluateConstraint(constraint));
+        }
+        return failures;
+    }
+    /** Invariant failures that must never be left standing in canonical state. */
+    function hardViolations() {
+        return evaluateInvariants().filter((diagnostic) => diagnostic.severity === 'error');
+    }
+    function violationKey(diagnostic) {
+        return [
+            diagnostic.code,
+            diagnostic.nodeId ?? '',
+            diagnostic.fieldId ?? '',
+            diagnostic.message,
+        ].join('|');
+    }
+    function countViolations(violations) {
+        const counts = new Map();
+        for (const violation of violations) {
+            const key = violationKey(violation);
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        return counts;
+    }
+    /**
+     * Violations that were not already present. A change is only held responsible for what
+     * it broke, so data that was already invalid does not make the rest of the UI unusable.
+     */
+    function violationsIntroducedSince(before) {
+        const remaining = new Map(before);
+        const introduced = [];
+        for (const violation of hardViolations()) {
+            const key = violationKey(violation);
+            const outstanding = remaining.get(key) ?? 0;
+            if (outstanding > 0) {
+                remaining.set(key, outstanding - 1);
+                continue;
+            }
+            introduced.push(violation);
+        }
+        return introduced;
+    }
+    function evaluateConstraint(constraint) {
+        const severity = constraint.severity ?? 'error';
+        const failures = [];
+        const record = () => {
+            failures.push({
+                code: 'CONSTRAINT_VIOLATION',
+                message: constraint.message ?? `Constraint ${constraint.name ?? constraint.id} failed`,
+                severity,
+                nodeId: constraint.id,
+            });
+        };
+        if (!constraint.entityId) {
+            if (!toBoolean(evaluate(constraint.expression, rootScope()))) {
+                record();
+            }
+            return failures;
+        }
+        for (const instance of instancesOf(constraint.entityId)) {
+            const scope = childScope(rootScope(), constraint.entityId, instance);
+            if (!toBoolean(evaluate(constraint.expression, scope))) {
+                record();
+            }
+        }
+        return failures;
+    }
+    // --------------------------------------------------------------- behaviour
+    function executeOperation(operation, scope, context, result) {
+        switch (operation.kind) {
+            case 'set':
+            case 'insert':
+            case 'remove':
+                mutate(() => mutations.apply(operation, scope, context), context, result);
+                return;
+            case 'invoke': {
+                const args = {};
+                for (const [parameterId, argument] of Object.entries(operation.arguments ?? {})) {
+                    args[parameterId] = evaluate(argument, scope);
+                }
+                const nested = runAction(operation.actionId, args);
+                result.push(...nested.diagnostics);
+                return;
+            }
+            case 'navigate': {
+                if (operation.path) {
+                    navigate(operation.path);
+                    return;
+                }
+                const route = ir.routes.find((candidate) => candidate.id === operation.routeId);
+                if (!route) {
+                    result.push({
+                        code: 'ROUTE_NOT_FOUND',
+                        message: `Navigate operation could not resolve route ${String(operation.routeId)}`,
+                        severity: 'error',
+                    });
+                    return;
+                }
+                const values = {};
+                for (const [parameterId, argument] of Object.entries(operation.parameters ?? {})) {
+                    values[parameterId] = toText(evaluate(argument, scope));
+                }
+                navigate(buildPath(route, values));
+                return;
+            }
+            case 'native': {
+                const implementation = natives.get(operation.implementationId);
+                if (!implementation) {
+                    result.push({
+                        code: 'NATIVE_OPERATION_MISSING',
+                        message: `No implementation registered for "${operation.implementationId}"`,
+                        severity: 'error',
+                    });
+                    return;
+                }
+                const inputs = {};
+                for (const [key, argument] of Object.entries(operation.inputs ?? {})) {
+                    // Native code receives copies: it can never reach into managed state.
+                    inputs[key] = cloneValue(evaluate(argument, scope));
+                }
+                const returned = implementation(inputs);
+                if (operation.resultTarget) {
+                    const target = operation.resultTarget;
+                    mutate(() => mutations.set(target, cloneValue(returned), scope, { ...context, source: 'native' }), context, result);
+                }
+                return;
+            }
+            default:
+                result.push({
+                    code: 'UNKNOWN_OPERATION',
+                    message: `Unknown operation kind "${operation.kind}"`,
+                    severity: 'error',
+                });
+        }
+    }
+    function runAction(actionId, args = {}) {
+        const action = ir.actions[actionId];
+        if (!action) {
+            const failure = {
+                code: 'ACTION_NOT_FOUND',
+                message: `Action ${actionId} is not defined`,
+                severity: 'error',
+            };
+            report(failure);
+            return { ok: false, diagnostics: [failure] };
+        }
+        const scope = rootScope();
+        for (const parameter of action.parameters ?? []) {
+            scope.values.set(parameter.id, args[parameter.id] ?? null);
+        }
+        const failures = [];
+        for (const parameter of action.parameters ?? []) {
+            if (parameter.required && !isPresent(scope.values.get(parameter.id))) {
+                failures.push({
+                    code: 'PARAMETER_MISSING',
+                    message: `Action ${action.name ?? action.id} requires ${parameter.name ?? parameter.id}`,
+                    severity: 'error',
+                    nodeId: action.id,
+                });
+            }
+        }
+        if (failures.length > 0) {
+            failures.forEach(report);
+            return { ok: false, diagnostics: failures };
+        }
+        for (const precondition of action.preconditions ?? []) {
+            if (!toBoolean(evaluate(precondition, scope))) {
+                const failure = {
+                    code: 'PRECONDITION_FAILED',
+                    message: action.failureModes?.[0]?.message ??
+                        `A precondition of ${action.name ?? action.id} was not satisfied`,
+                    severity: 'error',
+                    nodeId: action.id,
+                };
+                report(failure);
+                return { ok: false, diagnostics: [failure] };
+            }
+        }
+        if (action.requiresConfirmation) {
+            const message = action.confirmationMessage ?? `Confirm ${action.name ?? action.id}. This cannot be undone.`;
+            if (!host.confirm(message)) {
+                return { ok: false, diagnostics: [] };
+            }
+        }
+        const transaction = transactions.begin();
+        const context = {
+            source: 'action',
+            sourceNodeId: action.id,
+            transactionId: transaction.id,
+        };
+        const operationDiagnostics = [];
+        for (const operation of action.operations ?? []) {
+            executeOperation(operation, scope, context, operationDiagnostics);
+        }
+        const violations = [
+            ...operationDiagnostics.filter((diagnostic) => diagnostic.severity === 'error'),
+            ...evaluateInvariants().filter((diagnostic) => diagnostic.severity === 'error'),
+        ];
+        for (const postcondition of action.postconditions ?? []) {
+            if (!toBoolean(evaluate(postcondition, scope))) {
+                violations.push({
+                    code: 'POSTCONDITION_FAILED',
+                    message: `A postcondition of ${action.name ?? action.id} was not satisfied`,
+                    severity: 'error',
+                    nodeId: action.id,
+                });
+            }
+        }
+        if (violations.length > 0) {
+            settle(transaction, 'rolled-back');
+            violations.forEach(report);
+            renderApplication();
+            return { ok: false, diagnostics: violations };
+        }
+        settle(transaction, 'committed');
+        renderApplication();
+        return { ok: true, diagnostics: operationDiagnostics };
+    }
+    // ------------------------------------------------------------------ routing
+    function buildPath(route, values) {
+        const segments = route.segments.map((segment) => {
+            if (segment.kind === 'static') {
+                return segment.value;
+            }
+            const parameterId = segment.parameterId ?? '';
+            const value = values[parameterId] ?? '';
+            return encodeURIComponent(value);
+        });
+        return `/${segments.join('/')}`.replace(/\/+/g, '/');
+    }
+    function matchRoute(pathname) {
+        const parts = pathname.split('?')[0].split('/').filter(Boolean);
+        for (const route of ir.routes) {
+            if (route.segments.length !== parts.length) {
+                continue;
+            }
+            const parameters = {};
+            let matched = true;
+            for (let index = 0; index < route.segments.length; index += 1) {
+                const segment = route.segments[index];
+                const part = parts[index];
+                if (segment.kind === 'static') {
+                    if (segment.value !== part) {
+                        matched = false;
+                        break;
+                    }
+                    continue;
+                }
+                if (segment.parameterId) {
+                    parameters[segment.parameterId] = decodeURIComponent(part);
+                }
+            }
+            if (matched) {
+                return { route, parameters };
+            }
+        }
+        return null;
+    }
+    function navigate(path) {
+        host.pushPath(path);
+        syncRoute();
+    }
+    function syncRoute() {
+        activeRoute = matchRoute(host.getPath());
+        derivedCache.clear();
+        renderApplication();
+    }
+    // ----------------------------------------------------------------- renderer
+    function element(tagName, className) {
+        const created = host.document.createElement(tagName);
+        if (className) {
+            created.setAttribute('class', className);
+        }
+        return created;
+    }
+    function presentationClasses(node) {
+        const hints = node.presentation;
+        if (!hints) {
+            return '';
+        }
+        return [
+            hints.role ? `axiom-role-${hints.role}` : '',
+            hints.density ? `axiom-density-${hints.density}` : '',
+            hints.emphasis ? `axiom-emphasis-${hints.emphasis}` : '',
+        ]
+            .filter(Boolean)
+            .join(' ');
+    }
+    function renderChildren(ids, scope, parent) {
+        for (const id of ids) {
+            const child = renderNode(id, scope);
+            if (child) {
+                parent.appendChild(child);
+            }
+        }
+    }
+    function fieldOf(id) {
+        return ir.fields[id]?.field;
+    }
+    /** Reads through a location without giving the renderer a way to write. */
+    function readLocation(location, scope) {
+        try {
+            return resolveLocation(location, scope, {
+                readState,
+                writeState,
+                evaluate: (expression, inner) => evaluate(expression, inner),
+            }).read();
+        }
+        catch {
+            return null;
+        }
+    }
+    function resolveInputTag(node) {
+        const located = ir.locationTypes[node.id];
+        const resolved = located ? unwrapType(located) : null;
+        const hint = node.inputHint;
+        if (hint === 'multiline') {
+            return { tag: 'textarea' };
+        }
+        if (node.options) {
+            return { tag: 'select' };
+        }
+        if (hint === 'select' || (!hint && resolved?.kind === 'enum')) {
+            return { tag: 'select', options: resolved?.kind === 'enum' ? resolved.values : [] };
+        }
+        if (hint === 'checkbox' || (!hint && resolved?.kind === 'primitive' && resolved.primitive === 'boolean')) {
+            return { tag: 'input', type: 'checkbox' };
+        }
+        if (hint) {
+            return { tag: 'input', type: hint };
+        }
+        if (resolved?.kind === 'primitive') {
+            switch (resolved.primitive) {
+                case 'number':
+                    return { tag: 'input', type: 'number' };
+                case 'date':
+                case 'datetime':
+                    return { tag: 'input', type: 'date' };
+                default:
+                    return { tag: 'input', type: 'text' };
+            }
+        }
+        return { tag: 'input', type: 'text' };
+    }
+    /** Choices for a select: either enum values or records drawn from application data. */
+    function optionChoices(node, scope, enumValues) {
+        const source = node.options;
+        if (!source) {
+            return enumValues.map((value) => ({ value, label: value }));
+        }
+        const candidates = evaluate(source.source, scope);
+        if (!Array.isArray(candidates)) {
+            return [];
+        }
+        return candidates.filter(isRecord).map((candidate) => {
+            const value = toText(candidate[source.valueFieldId]);
+            const label = source.labelFieldId ? toText(candidate[source.labelFieldId]) : value;
+            return { value, label: label || value };
+        });
+    }
+    function coerceInputValue(inputId, raw, checked) {
+        const located = ir.locationTypes[inputId];
+        const optional = located?.kind === 'optional';
+        const resolved = located ? unwrapType(located) : null;
+        if (resolved?.kind === 'primitive' && resolved.primitive === 'boolean') {
+            return Boolean(checked);
+        }
+        if (resolved?.kind === 'primitive' && resolved.primitive === 'number') {
+            if (raw.trim() === '') {
+                return optional ? null : 0;
+            }
+            const parsed = Number(raw);
+            return Number.isNaN(parsed) ? raw : parsed;
+        }
+        return raw;
+    }
+    function renderNode(id, scope) {
+        const node = ir.uiNodes[id];
+        if (!node) {
+            report({
+                code: 'UI_NODE_MISSING',
+                message: `UI node ${id} is not defined`,
+                severity: 'error',
+                nodeId: id,
+            });
+            return null;
+        }
+        if (node.visibleWhen && !toBoolean(evaluate(node.visibleWhen, scope))) {
+            return null;
+        }
+        switch (node.kind) {
+            case 'view': {
+                const container = element('div', `axiom-view ${presentationClasses(node)}`.trim());
+                container.setAttribute('data-node', node.id);
+                renderChildren(node.children, scope, container);
+                return container;
+            }
+            case 'container': {
+                const container = element('div', `axiom-container axiom-layout-${node.layout ?? 'vertical'} ${presentationClasses(node)}`.trim());
+                container.setAttribute('data-node', node.id);
+                renderChildren(node.children, scope, container);
+                return container;
+            }
+            case 'text': {
+                const text = element('span', `axiom-text ${presentationClasses(node)}`.trim());
+                text.setAttribute('data-node', node.id);
+                text.textContent =
+                    typeof node.value === 'string' ? node.value : toText(evaluate(node.value, scope));
+                return text;
+            }
+            case 'repeat': {
+                const container = element('div', 'axiom-repeat');
+                container.setAttribute('data-node', node.id);
+                const source = evaluate(node.source, scope);
+                const items = Array.isArray(source) ? source : [];
+                if (items.length === 0 && node.emptyTemplateId) {
+                    renderChildren([node.emptyTemplateId], scope, container);
+                    return container;
+                }
+                for (const item of items) {
+                    const child = renderNode(node.templateId, childScope(scope, node.id, item));
+                    if (child) {
+                        container.appendChild(child);
+                    }
+                }
+                return container;
+            }
+            case 'field-display': {
+                const container = element('div', 'axiom-field');
+                container.setAttribute('data-node', node.id);
+                const field = fieldOf(node.fieldId);
+                if (node.label ?? field?.name) {
+                    const label = element('span', 'axiom-field-label');
+                    label.textContent = node.label ?? field?.name ?? '';
+                    container.appendChild(label);
+                }
+                const value = element('span', 'axiom-field-value');
+                const source = evaluate(node.source, scope);
+                value.textContent = isRecord(source) ? toText(source[node.fieldId]) : '';
+                container.appendChild(value);
+                return container;
+            }
+            case 'form': {
+                const form = element('form', 'axiom-form');
+                form.setAttribute('data-node', node.id);
+                renderChildren(node.children, scope, form);
+                if (node.submitActionId) {
+                    const submit = element('button', 'axiom-submit');
+                    submit.setAttribute('type', 'submit');
+                    submit.textContent = node.submitLabel ?? 'Submit';
+                    form.appendChild(submit);
+                    const actionId = node.submitActionId;
+                    form.addEventListener('submit', (event) => {
+                        event.preventDefault?.();
+                        runAction(actionId);
+                    });
+                }
+                return form;
+            }
+            case 'input': {
+                const wrapper = element('label', 'axiom-input');
+                wrapper.setAttribute('data-node', node.id);
+                if (node.label) {
+                    const label = element('span', 'axiom-input-label');
+                    label.textContent = node.label;
+                    wrapper.appendChild(label);
+                }
+                const descriptor = resolveInputTag(node);
+                const control = element(descriptor.tag, 'axiom-control');
+                control.setAttribute('data-node', node.id);
+                if (descriptor.type) {
+                    control.setAttribute('type', descriptor.type);
+                }
+                if (node.placeholder) {
+                    control.setAttribute('placeholder', node.placeholder);
+                }
+                const current = readLocation(node.binding.location, scope);
+                if (descriptor.type === 'checkbox') {
+                    control.checked = Boolean(current);
+                }
+                else if (descriptor.tag === 'select') {
+                    for (const choice of optionChoices(node, scope, descriptor.options ?? [])) {
+                        const option = element('option');
+                        option.setAttribute('value', choice.value);
+                        option.textContent = choice.label;
+                        if (toText(current) === choice.value) {
+                            option.setAttribute('selected', 'selected');
+                        }
+                        control.appendChild(option);
+                    }
+                    control.value = toText(current);
+                }
+                else {
+                    control.value = toText(current);
+                    control.setAttribute('value', toText(current));
+                }
+                // An input mutates through the same engine and transaction machinery as an
+                // action. There is no separate write path inside the renderer.
+                //
+                // A write to canonical state is transactional with respect to hard invariants:
+                // if the value would break one, the whole mutation is rolled back. A write to a
+                // draft is not, because a draft is incomplete by definition while it is filled in.
+                const apply = (event) => {
+                    const source = (event.target ?? control);
+                    const next = coerceInputValue(node.id, source.value ?? '', source.checked);
+                    const rootStateId = ir.locationRoots[node.id];
+                    const rootState = rootStateId === undefined ? undefined : statesById.get(rootStateId);
+                    const guarded = inputValidation === 'immediate' && rootState !== undefined && rootState.draft !== true;
+                    const before = guarded ? countViolations(hardViolations()) : null;
+                    const transaction = transactions.begin();
+                    const context = {
+                        source: 'ui',
+                        sourceNodeId: node.id,
+                        transactionId: transaction.id,
+                    };
+                    const failures = [];
+                    mutate(() => mutations.set(node.binding.location, next, scope, context), context, failures);
+                    if (failures.length > 0) {
+                        settle(transaction, 'rolled-back');
+                        failures.forEach(report);
+                    }
+                    else {
+                        const introduced = before ? violationsIntroducedSince(before) : [];
+                        if (introduced.length > 0) {
+                            settle(transaction, 'rolled-back');
+                            introduced.forEach(report);
+                            report({
+                                code: 'INPUT_REJECTED',
+                                message: `${node.label ?? node.id} kept its previous value: ${introduced[0].message}`,
+                                severity: 'warning',
+                                nodeId: node.id,
+                            });
+                        }
+                        else {
+                            settle(transaction, 'committed');
+                        }
+                    }
+                    focusedNodeId = node.id;
+                    focusedCaret = typeof source.selectionStart === 'number' ? source.selectionStart : null;
+                    renderApplication();
+                };
+                control.addEventListener('input', apply);
+                control.addEventListener('change', apply);
+                control.addEventListener('focus', () => {
+                    focusedNodeId = node.id;
+                });
+                inputElements.set(node.id, control);
+                wrapper.appendChild(control);
+                return wrapper;
+            }
+            case 'button': {
+                const button = element('button', `axiom-button ${node.destructive ? 'axiom-destructive' : ''} ${presentationClasses(node)}`.trim());
+                button.setAttribute('data-node', node.id);
+                button.setAttribute('type', 'button');
+                button.textContent =
+                    typeof node.label === 'string' ? node.label : toText(evaluate(node.label, scope));
+                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);
+                });
+                return button;
+            }
+            case 'conditional': {
+                const container = element('div', 'axiom-conditional');
+                container.setAttribute('data-node', node.id);
+                const branch = toBoolean(evaluate(node.condition, scope)) ? node.whenTrue : node.whenFalse ?? [];
+                renderChildren(branch, scope, container);
+                return container;
+            }
+            default:
+                report({
+                    code: 'UNKNOWN_UI_NODE',
+                    message: `Unknown UI node kind "${node.kind}"`,
+                    severity: 'error',
+                });
+                return null;
+        }
+    }
+    function renderApplication() {
+        inputElements.clear();
+        const scope = rootScope();
+        if (!activeRoute) {
+            const missing = element('div', 'axiom-no-route');
+            missing.textContent = `No route matches ${host.getPath()}`;
+            rootElement.replaceChildren(missing);
+            return;
+        }
+        const view = renderNode(activeRoute.route.viewId, scope);
+        rootElement.replaceChildren(...(view ? [view] : []));
+        restoreFocus();
+    }
+    function restoreFocus() {
+        if (!focusedNodeId) {
+            return;
+        }
+        const control = inputElements.get(focusedNodeId);
+        if (!control) {
+            return;
+        }
+        try {
+            control.focus?.();
+            if (focusedCaret !== null && typeof control.selectionStart === 'number') {
+                control.selectionStart = focusedCaret;
+            }
+        }
+        catch {
+            // Some controls reject caret manipulation; focus alone is enough.
+        }
+    }
+    // -------------------------------------------------------------- public API
+    initializeStore();
+    return {
+        start() {
+            if (started) {
+                return;
+            }
+            started = true;
+            host.onPathChange(() => {
+                activeRoute = matchRoute(host.getPath());
+                derivedCache.clear();
+                renderApplication();
+            });
+            syncRoute();
+        },
+        render: renderApplication,
+        getState(id) {
+            return cloneValue(readState(id));
+        },
+        setState(id, value) {
+            const transaction = transactions.begin();
+            const failures = [];
+            const context = { source: 'system', transactionId: transaction.id };
+            mutate(() => mutations.set({ kind: 'state', stateId: id }, cloneValue(value), rootScope(), context), context, failures);
+            if (failures.length > 0) {
+                settle(transaction, 'rolled-back');
+                failures.forEach(report);
+            }
+            else {
+                settle(transaction, 'committed');
+            }
+            renderApplication();
+        },
+        invokeAction(id, args = {}) {
+            return runAction(id, args);
+        },
+        navigate,
+        currentRoute() {
+            return activeRoute;
+        },
+        diagnostics() {
+            return diagnostics.map((diagnostic) => ({ ...diagnostic }));
+        },
+        getMutationLog() {
+            return mutationLog.map((entry) => ({ ...entry }));
+        },
+        registerNativeOperation(implementationId, implementation) {
+            natives.set(implementationId, implementation);
+        },
+    };
+}
+/** Builds a host bound to the browser globals. Used by generated pages. */
+export function createBrowserHost() {
+    const globals = globalThis;
+    return {
+        document: globals.document,
+        getPath: () => globals.location.pathname,
+        pushPath: (path) => globals.history.pushState({}, '', path),
+        onPathChange: (listener) => globals.addEventListener?.('popstate', listener),
+        confirm: (message) => Boolean(globals.confirm(message)),
+        now: () => new Date().toISOString(),
+        uuid: () => typeof globals.crypto?.randomUUID === 'function'
+            ? globals.crypto.randomUUID()
+            : `id-${Date.now().toString(16)}-${Math.floor(Math.random() * 1e9).toString(16)}`,
+        storage: globals.localStorage
+            ? {
+                read: (key) => globals.localStorage.getItem(key),
+                write: (key, value) => globals.localStorage.setItem(key, value),
+            }
+            : undefined,
+        report: (message) => globals.console?.warn?.(message),
+    };
+}