@cynodia/axiom-runtime 0.4.1-alpha.1 → 0.5.0-alpha.1

package/README.md

@@ -9,6 +9,10 @@ The domain-independent runtime: the state store, expression evaluation, the muta
 engine, constraint checking, the semantic UI renderer and routing. It takes its whole
 environment through a `HostEnvironment`, so it runs in a browser or headlessly.
 
+The renderer reads presentation that the compiler has already resolved and turns it into
+semantic class names, landmark and heading elements, and formatted values. It writes no
+styles and computes no lengths — what those classes mean is the theme's business.
+
 ## Installation
 
 ```bash

package/dist/dom.d.ts

@@ -27,6 +27,21 @@ export interface StorageAdapter {
     read(key: string): string | null;
     write(key: string, value: string): void;
 }
+/**
+ * A confirmation, described rather than drawn. A host may present it however its platform
+ * presents such things; nothing here is browser-specific, and the graph never constructs
+ * dialog markup.
+ */
+export interface ConfirmationRequest {
+    actionId: string;
+    title: string;
+    description?: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    severity: 'informational' | 'warning' | 'destructive';
+    /** A single line for hosts that can only ask a plain question. */
+    message: string;
+}
 /** Everything the runtime needs from its environment, so nothing is read from globals. */
 export interface HostEnvironment {
     document: DomDocument;
@@ -34,6 +49,8 @@ export interface HostEnvironment {
     pushPath(path: string): void;
     onPathChange(listener: () => void): void;
     confirm(message: string): boolean;
+    /** Preferred over `confirm` when the host can present a structured confirmation. */
+    confirmRequest?(request: ConfirmationRequest): boolean;
     now(): string;
     uuid(): string;
     storage?: StorageAdapter;

package/dist/format.d.ts

@@ -0,0 +1,8 @@
+import type { ValueFormat } from '@cynodia/axiom-core';
+/**
+ * Renders a value for display. A value the format cannot describe — a date field holding
+ * something that is not a date — falls back to its plain text rather than inventing a
+ * plausible-looking result.
+ */
+export declare function formatValue(value: unknown, format: ValueFormat | undefined, locale?: string): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -0,0 +1,122 @@
+import { isPresent, toText } from './mutation/values.js';
+/**
+ * Semantic value formatting. Formatting is presentation: the stored value never changes,
+ * and the graph describes what it wants with a structured `ValueFormat` rather than a
+ * function, so the description survives serialization and can be reasoned about.
+ */
+const DATE_STYLES = {
+    short: 'short',
+    medium: 'medium',
+    long: 'long',
+};
+function numberFormat(locale, options) {
+    const intl = globalThis.Intl;
+    if (!intl?.NumberFormat) {
+        return (value) => String(value);
+    }
+    const formatter = new intl.NumberFormat(locale, options);
+    return (value) => formatter.format(value);
+}
+function asNumber(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function asDate(value) {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value;
+    }
+    if (typeof value === 'string' || typeof value === 'number') {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? null : parsed;
+    }
+    return null;
+}
+function formatDate(value, locale, style, withTime) {
+    const date = asDate(value);
+    if (!date) {
+        return null;
+    }
+    const intl = globalThis.Intl;
+    if (!intl?.DateTimeFormat) {
+        return date.toISOString();
+    }
+    const dateStyle = DATE_STYLES[style ?? 'medium'] ?? 'medium';
+    const options = withTime
+        ? { dateStyle, timeStyle: dateStyle === 'long' ? 'medium' : 'short' }
+        : { dateStyle };
+    return new intl.DateTimeFormat(locale, options).format(date);
+}
+/**
+ * Renders a value for display. A value the format cannot describe — a date field holding
+ * something that is not a date — falls back to its plain text rather than inventing a
+ * plausible-looking result.
+ */
+export function formatValue(value, format, locale = 'en-US') {
+    if (!format) {
+        return toText(value);
+    }
+    if (format.kind !== 'boolean' && !isPresent(value)) {
+        return '';
+    }
+    switch (format.kind) {
+        case 'text':
+            return toText(value);
+        case 'number': {
+            const numeric = asNumber(value);
+            if (numeric === null) {
+                return toText(value);
+            }
+            return numberFormat(locale, {
+                useGrouping: format.grouping !== false,
+                ...(format.decimals === undefined
+                    ? {}
+                    : { minimumFractionDigits: format.decimals, maximumFractionDigits: format.decimals }),
+            })(numeric);
+        }
+        case 'currency': {
+            const numeric = asNumber(value);
+            if (numeric === null) {
+                return toText(value);
+            }
+            return numberFormat(locale, {
+                style: 'currency',
+                currency: format.currency,
+                ...(format.decimals === undefined
+                    ? {}
+                    : { minimumFractionDigits: format.decimals, maximumFractionDigits: format.decimals }),
+            })(numeric);
+        }
+        case 'percentage': {
+            const numeric = asNumber(value);
+            if (numeric === null) {
+                return toText(value);
+            }
+            // A percentage may be stored as a fraction or as a whole number of percent.
+            const fraction = format.scale === 'percent' ? numeric / 100 : numeric;
+            return numberFormat(locale, {
+                style: 'percent',
+                ...(format.decimals === undefined
+                    ? {}
+                    : { minimumFractionDigits: format.decimals, maximumFractionDigits: format.decimals }),
+            })(fraction);
+        }
+        case 'boolean': {
+            if (!isPresent(value)) {
+                return '';
+            }
+            return value ? format.trueLabel ?? 'Yes' : format.falseLabel ?? 'No';
+        }
+        case 'date':
+            return formatDate(value, locale, format.style, false) ?? toText(value);
+        case 'datetime':
+            return formatDate(value, locale, format.style, true) ?? toText(value);
+        default:
+            return toText(value);
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/memory-host.d.ts

@@ -1,4 +1,4 @@
-import type { DomDocument, DomElement, DomEvent, DomListener, HostEnvironment, StorageAdapter } from './dom.js';
+import type { ConfirmationRequest, DomDocument, DomElement, DomEvent, DomListener, HostEnvironment, StorageAdapter } from './dom.js';
 /**
  * An in-memory DOM and host. The runtime never touches browser globals directly, so the
  * same renderer that drives a real page can be driven headlessly in tests.
@@ -36,6 +36,8 @@ export interface MemoryHost extends HostEnvironment {
     path: string;
     reports: string[];
     confirmations: string[];
+    /** The structured confirmations asked for, so a test can assert what was presented. */
+    confirmationRequests: ConfirmationRequest[];
     storage?: StorageAdapter;
 }
 export declare function createMemoryHost(options?: MemoryHostOptions): MemoryHost;

package/dist/memory-host.js

@@ -61,6 +61,7 @@ export function createMemoryHost(options = {}) {
         path: options.path ?? '/',
         reports: [],
         confirmations: [],
+        confirmationRequests: [],
         document: new MemoryDocument(),
         getPath: () => host.path,
         pushPath: (next) => {
@@ -73,6 +74,10 @@ export function createMemoryHost(options = {}) {
             host.confirmations.push(message);
             return typeof confirmResult === 'function' ? confirmResult() : confirmResult;
         },
+        confirmRequest: (request) => {
+            host.confirmationRequests.push(request);
+            return host.confirm(request.message);
+        },
         now: () => {
             counter += 1;
             return `2026-01-01T00:00:${String(counter).padStart(2, '0')}.000Z`;

package/dist/presentation-classes.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedPresentation, TextRole, UxRole } from '@cynodia/axiom-core';
+/** Every class a node's resolved presentation implies, in a stable order. */
+export declare function presentationClassList(resolved: ResolvedPresentation | undefined): string[];
+export declare function presentationClasses(resolved: ResolvedPresentation | undefined, ...extra: string[]): string;
+/**
+ * Landmarks. A UX role that names a region of the page becomes the element that means
+ * that region, so assistive technology gets the structure the graph declared.
+ */
+export declare function landmarkTag(uxRole: UxRole | undefined): string | undefined;
+/**
+ * Headings are real headings, so the document has an outline rather than a set of large
+ * words. The three heading text roles are three levels: an application title, a title
+ * within it, and a section heading under that.
+ */
+export declare function headingTag(textRole: TextRole | undefined): string | undefined;
+/** The ARIA role a UX role implies, where one is warranted. */
+export declare function ariaRoleFor(uxRole: UxRole | undefined): string | undefined;
+//# sourceMappingURL=presentation-classes.d.ts.map

package/dist/presentation-classes.js

@@ -0,0 +1,147 @@
+/**
+ * The web renderer's translation of resolved presentation into class names.
+ *
+ * The renderer emits semantic classes and nothing else — no inline styles, no computed
+ * lengths, no colours. What those classes mean is decided by the generated stylesheet, so
+ * the same resolved presentation can drive an entirely different renderer.
+ */
+function layoutClasses(prefix, layout) {
+    const classes = [`axiom-${prefix}layout-${layout.kind}`, `axiom-${prefix}gap-${layout.gap}`];
+    if (!prefix) {
+        classes.push(`axiom-align-${layout.align}`, `axiom-justify-${layout.justify}`);
+        classes.push(layout.wrap ? 'axiom-wrap' : 'axiom-nowrap');
+        if (layout.columns !== undefined) {
+            classes.push(typeof layout.columns === 'number'
+                ? `axiom-columns-${layout.columns}`
+                : `axiom-columns-adaptive-${layout.columns.minimum}`);
+        }
+    }
+    return classes;
+}
+function sizingClasses(prefix, sizing) {
+    const classes = [`axiom-${prefix}width-${sizing.width}`];
+    if (!prefix) {
+        classes.push(`axiom-height-${sizing.height}`);
+        if (sizing.minWidth) {
+            classes.push(`axiom-minwidth-${sizing.minWidth}`);
+        }
+        if (sizing.maxWidth) {
+            classes.push(`axiom-maxwidth-${sizing.maxWidth}`);
+        }
+    }
+    return classes;
+}
+function paddingClasses(prefix, padding) {
+    return [`axiom-${prefix}pad-x-${padding.horizontal}`, `axiom-${prefix}pad-y-${padding.vertical}`];
+}
+function responsiveClasses(device, override) {
+    const prefix = `${device}-`;
+    const classes = [];
+    if (override.hidden) {
+        classes.push(`axiom-${prefix}hidden`);
+    }
+    if (override.layout) {
+        classes.push(...layoutClasses(prefix, override.layout));
+    }
+    if (override.sizing) {
+        classes.push(...sizingClasses(prefix, override.sizing));
+    }
+    if (override.padding) {
+        classes.push(...paddingClasses(prefix, override.padding));
+    }
+    if (override.density) {
+        classes.push(`axiom-${prefix}density-${override.density}`);
+    }
+    return classes;
+}
+/** Every class a node's resolved presentation implies, in a stable order. */
+export function presentationClassList(resolved) {
+    if (!resolved) {
+        return [];
+    }
+    const classes = [
+        `axiom-density-${resolved.density}`,
+        `axiom-emphasis-${resolved.emphasis}`,
+        `axiom-surface-${resolved.surface}`,
+        `axiom-text-${resolved.textRole}`,
+        `axiom-treatment-${resolved.treatment}`,
+    ];
+    if (resolved.role) {
+        classes.push(`axiom-role-${resolved.role}`);
+    }
+    if (resolved.uxRole) {
+        classes.push(`axiom-ux-${resolved.uxRole}`);
+    }
+    classes.push(...layoutClasses('', resolved.layout));
+    classes.push(...sizingClasses('', resolved.sizing));
+    classes.push(...paddingClasses('', resolved.padding));
+    for (const device of ['compact', 'regular', 'wide']) {
+        const override = resolved.responsive[device];
+        if (override) {
+            classes.push(...responsiveClasses(device, override));
+        }
+    }
+    // The escape hatch: a renderer-specific class, attached and otherwise not understood.
+    const override = resolved.rendererOverrides?.web;
+    if (override && typeof override.className === 'string' && override.className.trim()) {
+        classes.push('axiom-opaque', ...override.className.trim().split(/\s+/));
+    }
+    return classes;
+}
+export function presentationClasses(resolved, ...extra) {
+    return [...extra, ...presentationClassList(resolved)].filter(Boolean).join(' ');
+}
+/**
+ * Landmarks. A UX role that names a region of the page becomes the element that means
+ * that region, so assistive technology gets the structure the graph declared.
+ */
+export function landmarkTag(uxRole) {
+    switch (uxRole) {
+        case 'header-region':
+            return 'header';
+        case 'footer-region':
+            return 'footer';
+        case 'navigation-group':
+            return 'nav';
+        case 'content-region':
+            return 'main';
+        case 'sidebar':
+            return 'aside';
+        case 'form-section':
+            return 'section';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Headings are real headings, so the document has an outline rather than a set of large
+ * words. The three heading text roles are three levels: an application title, a title
+ * within it, and a section heading under that.
+ */
+export function headingTag(textRole) {
+    switch (textRole) {
+        case 'display':
+            return 'h1';
+        case 'title':
+            return 'h2';
+        case 'heading':
+            return 'h3';
+        default:
+            return undefined;
+    }
+}
+/** The ARIA role a UX role implies, where one is warranted. */
+export function ariaRoleFor(uxRole) {
+    switch (uxRole) {
+        case 'toolbar':
+            return 'toolbar';
+        case 'error-state':
+            return 'alert';
+        case 'warning-state':
+        case 'success-state':
+        case 'informational-state':
+            return 'status';
+        default:
+            return undefined;
+    }
+}

package/dist/runtime.js

@@ -1,3 +1,5 @@
+import { formatValue } from './format.js';
+import { ariaRoleFor, headingTag, landmarkTag, presentationClasses, } from './presentation-classes.js';
 import { createMutationEngine } from './mutation/mutation-engine.js';
 import { LocationResolutionError, resolveLocation } from './mutation/resolve-location.js';
 import { createStateStore } from './mutation/store.js';
@@ -96,6 +98,14 @@ export function createAxiomRuntime(options) {
     let transactionCounter = 0;
     const mutationLog = [];
     const inputValidation = options.inputValidation ?? 'immediate';
+    const theme = ir.theme;
+    const locale = theme?.locale ?? 'en-US';
+    /** Messages for inputs whose last write was refused, so a control can say so. */
+    const inputErrors = new Map();
+    /** Presentation, already resolved by the compiler. The renderer decides nothing. */
+    function presentationOf(id) {
+        return ir.presentation?.[id];
+    }
     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();
@@ -529,9 +539,9 @@ export function createAxiomRuntime(options) {
             }
         };
         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) {
+            // Drafts are incomplete by definition, ephemeral state is not a domain fact at all,
+            // and derived states are views of data already validated where it is stored.
+            if (state.draft || state.ephemeral || state.derivation) {
                 continue;
             }
             visit(read(state.id), state.valueType);
@@ -897,8 +907,7 @@ export function createAxiomRuntime(options) {
             return { ok: false, diagnostics: [...collected] };
         }
         if (action.requiresConfirmation) {
-            const message = action.confirmationMessage ?? `Confirm ${action.name ?? action.id}. This cannot be undone.`;
-            if (!host.confirm(message)) {
+            if (!askForConfirmation(action)) {
                 return { ok: false, diagnostics: [...collected] };
             }
         }
@@ -1007,18 +1016,49 @@ export function createAxiomRuntime(options) {
         }
         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(' ');
+    /** The semantic classes a node's resolved presentation implies. No styles, no colours. */
+    function nodeClasses(node, ...base) {
+        return presentationClasses(presentationOf(node.id), ...base);
+    }
+    /** A semantic icon, drawn with the glyph the theme supplies for it. */
+    function appendIcon(parent, resolved) {
+        const name = resolved?.icon;
+        if (!name) {
+            return false;
+        }
+        const icon = element('span', 'axiom-icon');
+        icon.setAttribute('aria-hidden', 'true');
+        icon.setAttribute('data-icon', name);
+        icon.textContent = theme?.icons?.[name] ?? '';
+        parent.appendChild(icon);
+        return true;
+    }
+    /**
+     * Asks for confirmation. The graph describes what is asked; the host decides how to ask.
+     * A host that can only manage a plain question still gets a sentence to show.
+     */
+    function askForConfirmation(action) {
+        const declared = action.confirmation;
+        const fallback = `Confirm ${action.name ?? action.id}. This cannot be undone.`;
+        const composed = declared
+            ? [declared.title, declared.description].filter(Boolean).join(' — ')
+            : '';
+        const message = action.confirmationMessage ?? (composed || fallback);
+        if (!host.confirmRequest) {
+            return host.confirm(message);
+        }
+        const request = {
+            actionId: action.id,
+            title: declared?.title ?? action.name ?? action.id,
+            confirmLabel: declared?.confirmLabel ?? 'Confirm',
+            cancelLabel: declared?.cancelLabel ?? 'Cancel',
+            severity: declared?.severity ?? (action.destructive ? 'destructive' : 'informational'),
+            message,
+            ...(declared?.description ?? action.confirmationMessage
+                ? { description: declared?.description ?? action.confirmationMessage }
+                : {}),
+        };
+        return host.confirmRequest(request);
     }
     function renderChildren(ids, scope, parent) {
         for (const id of ids) {
@@ -1044,10 +1084,31 @@ export function createAxiomRuntime(options) {
             return null;
         }
     }
+    /**
+     * Which control edits this value. Semantic intent wins, then the older HTML-shaped
+     * hint, then the type of the location the input is bound to.
+     */
     function resolveInputTag(node) {
         const located = ir.locationTypes[node.id];
         const resolved = located ? unwrapType(located) : null;
+        const enumValues = resolved?.kind === 'enum' ? resolved.values : [];
         const hint = node.inputHint;
+        switch (presentationOf(node.id)?.control) {
+            case 'multiline':
+                return { tag: 'textarea', variant: 'multiline' };
+            case 'select':
+                return { tag: 'select', options: enumValues, variant: 'select' };
+            case 'radio-group':
+                return { tag: 'radio-group', options: enumValues, variant: 'radio-group' };
+            case 'switch':
+                return { tag: 'input', type: 'checkbox', variant: 'switch' };
+            case 'checkbox':
+                return { tag: 'input', type: 'checkbox', variant: 'checkbox' };
+            case 'stepper':
+                return { tag: 'input', type: 'number', variant: 'stepper' };
+            default:
+                break;
+        }
         if (hint === 'multiline') {
             return { tag: 'textarea' };
         }
@@ -1055,7 +1116,7 @@ export function createAxiomRuntime(options) {
             return { tag: 'select' };
         }
         if (hint === 'select' || (!hint && resolved?.kind === 'enum')) {
-            return { tag: 'select', options: resolved?.kind === 'enum' ? resolved.values : [] };
+            return { tag: 'select', options: enumValues };
         }
         if (hint === 'checkbox' || (!hint && resolved?.kind === 'primitive' && resolved.primitive === 'boolean')) {
             return { tag: 'input', type: 'checkbox' };
@@ -1131,28 +1192,55 @@ export function createAxiomRuntime(options) {
         if (node.visibleWhen && !toBoolean(evaluate(node.visibleWhen, scope))) {
             return null;
         }
+        const presentation = presentationOf(node.id);
         switch (node.kind) {
             case 'view': {
-                const container = element('div', `axiom-view ${presentationClasses(node)}`.trim());
+                const container = element('div', nodeClasses(node, 'axiom-view'));
                 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());
+                // A UX role that names a region of the page becomes the element that means it, so
+                // the landmark structure an author declared is the one assistive technology sees.
+                const container = element(landmarkTag(presentation?.uxRole) ?? 'div', nodeClasses(node, 'axiom-container'));
                 container.setAttribute('data-node', node.id);
+                const ariaRole = ariaRoleFor(presentation?.uxRole);
+                if (ariaRole) {
+                    container.setAttribute('role', ariaRole);
+                }
+                if (presentation?.accessibleLabel) {
+                    container.setAttribute('aria-label', presentation.accessibleLabel);
+                }
+                appendIcon(container, presentation);
                 renderChildren(node.children, scope, container);
                 return container;
             }
             case 'text': {
-                const text = element('span', `axiom-text ${presentationClasses(node)}`.trim());
+                const text = element(headingTag(presentation?.textRole) ?? 'span', nodeClasses(node, 'axiom-text'));
                 text.setAttribute('data-node', node.id);
-                text.textContent =
-                    typeof node.value === 'string' ? node.value : toText(evaluate(node.value, scope));
+                // A status role announces itself whatever kind of node carries it.
+                const textRole = ariaRoleFor(presentation?.uxRole);
+                if (textRole) {
+                    text.setAttribute('role', textRole);
+                }
+                if (presentation?.accessibleLabel) {
+                    text.setAttribute('aria-label', presentation.accessibleLabel);
+                }
+                const raw = typeof node.value === 'string' ? node.value : evaluate(node.value, scope);
+                const rendered = presentation?.format ? formatValue(raw, presentation.format, locale) : toText(raw);
+                if (appendIcon(text, presentation)) {
+                    const value = element('span', 'axiom-text-value');
+                    value.textContent = rendered;
+                    text.appendChild(value);
+                }
+                else {
+                    text.textContent = rendered;
+                }
                 return text;
             }
             case 'repeat': {
-                const container = element('div', 'axiom-repeat');
+                const container = element('div', nodeClasses(node, 'axiom-repeat'));
                 container.setAttribute('data-node', node.id);
                 const source = evaluate(node.source, scope);
                 const items = Array.isArray(source) ? source : [];
@@ -1169,7 +1257,7 @@ export function createAxiomRuntime(options) {
                 return container;
             }
             case 'field-display': {
-                const container = element('div', 'axiom-field');
+                const container = element('div', nodeClasses(node, 'axiom-field'));
                 container.setAttribute('data-node', node.id);
                 const field = fieldOf(node.fieldId);
                 if (node.label ?? field?.name) {
@@ -1177,21 +1265,27 @@ export function createAxiomRuntime(options) {
                     label.textContent = node.label ?? field?.name ?? '';
                     container.appendChild(label);
                 }
+                appendIcon(container, presentation);
                 const value = element('span', 'axiom-field-value');
                 const source = evaluate(node.source, scope);
-                value.textContent = isRecord(source) ? toText(source[node.fieldId]) : '';
+                // The stored value is untouched; only what is shown is formatted.
+                value.textContent = isRecord(source)
+                    ? formatValue(source[node.fieldId], presentation?.format, locale)
+                    : '';
                 container.appendChild(value);
                 return container;
             }
             case 'form': {
-                const form = element('form', 'axiom-form');
+                const form = element('form', nodeClasses(node, 'axiom-form'));
                 form.setAttribute('data-node', node.id);
                 renderChildren(node.children, scope, form);
                 if (node.submitActionId) {
-                    const submit = element('button', 'axiom-submit');
+                    const actions = element('div', 'axiom-container axiom-ux-action-group axiom-layout-horizontal axiom-gap-small axiom-align-center axiom-justify-end axiom-wrap axiom-width-fill');
+                    const submit = element('button', 'axiom-submit axiom-button axiom-role-primary axiom-emphasis-strong axiom-ux-primary-action');
                     submit.setAttribute('type', 'submit');
                     submit.textContent = node.submitLabel ?? 'Submit';
-                    form.appendChild(submit);
+                    actions.appendChild(submit);
+                    form.appendChild(actions);
                     const actionId = node.submitActionId;
                     form.addEventListener('submit', (event) => {
                         event.preventDefault?.();
@@ -1201,25 +1295,86 @@ export function createAxiomRuntime(options) {
                 return form;
             }
             case 'input': {
-                const wrapper = element('label', 'axiom-input');
+                const descriptor = resolveInputTag(node);
+                const grouped = descriptor.tag === 'radio-group';
+                const controlId = `axiom-control-${node.id}`;
+                const required = ir.locationRequired?.[node.id] === true;
+                const wrapper = element(grouped ? 'div' : 'label', nodeClasses(node, 'axiom-input'));
                 wrapper.setAttribute('data-node', node.id);
-                if (node.label) {
-                    const label = element('span', 'axiom-input-label');
-                    label.textContent = node.label;
+                if (grouped) {
+                    wrapper.setAttribute('role', 'group');
+                }
+                else {
+                    // The label is the element, and it names the control by id as well, so the
+                    // association survives however the two are laid out.
+                    wrapper.setAttribute('for', controlId);
+                }
+                const labelText = node.label ?? presentation?.accessibleLabel;
+                if (labelText) {
+                    const label = element('span', 'axiom-input-label axiom-text-label');
+                    label.textContent = labelText;
+                    if (required) {
+                        const marker = element('span', 'axiom-required-marker');
+                        marker.setAttribute('aria-hidden', 'true');
+                        marker.textContent = '*';
+                        label.appendChild(marker);
+                    }
                     wrapper.appendChild(label);
                 }
-                const descriptor = resolveInputTag(node);
-                const control = element(descriptor.tag, 'axiom-control');
+                const current = readLocation(node.binding.location, scope);
+                const describedBy = [];
+                const control = element(grouped ? 'div' : descriptor.tag, grouped ? 'axiom-radio-group' : 'axiom-control');
                 control.setAttribute('data-node', node.id);
-                if (descriptor.type) {
-                    control.setAttribute('type', descriptor.type);
+                if (descriptor.variant) {
+                    control.setAttribute('data-control', descriptor.variant);
                 }
-                if (node.placeholder) {
-                    control.setAttribute('placeholder', node.placeholder);
+                if (!grouped) {
+                    control.setAttribute('id', controlId);
+                    if (descriptor.type) {
+                        control.setAttribute('type', descriptor.type);
+                    }
+                    if (node.placeholder) {
+                        control.setAttribute('placeholder', node.placeholder);
+                    }
+                    if (required) {
+                        control.setAttribute('aria-required', 'true');
+                    }
+                    if (!labelText && presentation?.accessibleLabel) {
+                        control.setAttribute('aria-label', presentation.accessibleLabel);
+                    }
                 }
-                const current = readLocation(node.binding.location, scope);
-                if (descriptor.type === 'checkbox') {
+                if (grouped) {
+                    wrapper.setAttribute('data-control', descriptor.variant ?? 'radio-group');
+                }
+                if (descriptor.variant === 'switch') {
+                    control.setAttribute('role', 'switch');
+                }
+                const radios = [];
+                if (grouped) {
+                    for (const choice of optionChoices(node, scope, descriptor.options ?? [])) {
+                        const option = element('label', 'axiom-radio-option');
+                        const radio = element('input', 'axiom-radio');
+                        radios.push(radio);
+                        radio.setAttribute('type', 'radio');
+                        radio.setAttribute('name', controlId);
+                        radio.setAttribute('value', choice.value);
+                        radio.value = choice.value;
+                        if (toText(current) === choice.value) {
+                            radio.checked = true;
+                            radio.setAttribute('checked', 'checked');
+                        }
+                        const caption = element('span');
+                        caption.textContent = choice.label;
+                        option.appendChild(radio);
+                        option.appendChild(caption);
+                        control.appendChild(option);
+                    }
+                }
+                else if (descriptor.type === 'checkbox') {
                     control.checked = Boolean(current);
+                    if (Boolean(current)) {
+                        control.setAttribute('checked', 'checked');
+                    }
                 }
                 else if (descriptor.tag === 'select') {
                     for (const choice of optionChoices(node, scope, descriptor.options ?? [])) {
@@ -1248,7 +1403,12 @@ export function createAxiomRuntime(options) {
                     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;
+                    // A draft is incomplete while it is filled in, and ephemeral presentation state
+                    // is not a domain fact at all; neither is guarded per keystroke.
+                    const guarded = inputValidation === 'immediate' &&
+                        rootState !== undefined &&
+                        rootState.draft !== true &&
+                        rootState.ephemeral !== true;
                     const before = guarded ? countViolations(hardViolations()) : null;
                     const transaction = transactions.begin();
                     const context = {
@@ -1260,6 +1420,7 @@ export function createAxiomRuntime(options) {
                     mutate(() => mutations.set(node.binding.location, next, scope, context), context, failures);
                     if (failures.length > 0) {
                         settle(transaction, 'rolled-back');
+                        inputErrors.set(node.id, failures[0].message);
                         failures.forEach(report);
                     }
                     else {
@@ -1271,6 +1432,7 @@ export function createAxiomRuntime(options) {
                         ];
                         if (rejected.length > 0) {
                             settle(transaction, 'rolled-back');
+                            inputErrors.set(node.id, rejected[0].message);
                             rejected.forEach((diagnostic) => report({ ...diagnostic, details: { ...diagnostic.details, source: 'input', nodeId: node.id } }));
                             report({
                                 code: RUNTIME_DIAGNOSTIC_CODES.INPUT_REJECTED,
@@ -1282,27 +1444,64 @@ export function createAxiomRuntime(options) {
                         }
                         else {
                             settle(transaction, 'committed');
+                            inputErrors.delete(node.id);
                         }
                     }
                     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;
-                });
+                // A radio group's listeners live on its radios; everything else is one control.
+                for (const target of grouped ? radios : [control]) {
+                    target.addEventListener('input', apply);
+                    target.addEventListener('change', apply);
+                    target.addEventListener('focus', () => {
+                        focusedNodeId = node.id;
+                    });
+                }
                 inputElements.set(node.id, control);
                 wrapper.appendChild(control);
+                if (presentation?.description) {
+                    const help = element('span', 'axiom-input-description axiom-text-caption');
+                    help.setAttribute('id', `${controlId}-description`);
+                    help.textContent = presentation.description;
+                    describedBy.push(`${controlId}-description`);
+                    wrapper.appendChild(help);
+                }
+                const rejection = inputErrors.get(node.id);
+                if (rejection) {
+                    // The refusal is related to the control it refused, not left floating.
+                    const error = element('span', 'axiom-input-description axiom-role-destructive axiom-text-caption');
+                    error.setAttribute('id', `${controlId}-error`);
+                    error.setAttribute('role', 'alert');
+                    error.textContent = rejection;
+                    describedBy.push(`${controlId}-error`);
+                    wrapper.appendChild(error);
+                    if (!grouped) {
+                        control.setAttribute('aria-invalid', 'true');
+                    }
+                }
+                if (describedBy.length > 0 && !grouped) {
+                    control.setAttribute('aria-describedby', describedBy.join(' '));
+                }
                 return wrapper;
             }
             case 'button': {
-                const button = element('button', `axiom-button ${node.destructive ? 'axiom-destructive' : ''} ${presentationClasses(node)}`.trim());
+                const button = element('button', nodeClasses(node, 'axiom-button'));
                 button.setAttribute('data-node', node.id);
                 button.setAttribute('type', 'button');
-                button.textContent =
-                    typeof node.label === 'string' ? node.label : toText(evaluate(node.label, scope));
+                const label = typeof node.label === 'string' ? node.label : toText(evaluate(node.label, scope));
+                if (appendIcon(button, presentation)) {
+                    const caption = element('span', 'axiom-button-label');
+                    caption.textContent = label;
+                    button.appendChild(caption);
+                }
+                else {
+                    button.textContent = label;
+                }
+                if (presentation?.accessibleLabel) {
+                    button.setAttribute('aria-label', presentation.accessibleLabel);
+                }
                 button.addEventListener('click', (event) => {
                     event.preventDefault?.();
                     const args = {};
@@ -1314,7 +1513,7 @@ export function createAxiomRuntime(options) {
                 return button;
             }
             case 'conditional': {
-                const container = element('div', 'axiom-conditional');
+                const container = element('div', nodeClasses(node, 'axiom-conditional'));
                 container.setAttribute('data-node', node.id);
                 const branch = toBoolean(evaluate(node.condition, scope)) ? node.whenTrue : node.whenFalse ?? [];
                 renderChildren(branch, scope, container);

package/dist/source.js

@@ -11,6 +11,8 @@ const RUNTIME_MODULES = [
     './mutation/transaction.js',
     './mutation/resolve-location.js',
     './mutation/mutation-engine.js',
+    './format.js',
+    './presentation-classes.js',
     './runtime.js',
 ];
 const BUNDLED_BASENAMES = RUNTIME_MODULES.map((module) => module.slice(module.lastIndexOf('/') + 1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-runtime",
-  "version": "0.4.1-alpha.1",
+  "version": "0.5.0-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.4.1-alpha.1"
+    "@cynodia/axiom-core": "0.5.0-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",