@cynodia/axiom-runtime 0.4.0-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/mutation/transaction.d.ts

@@ -16,6 +16,12 @@ export interface RuntimeTransaction {
 export interface TransactionManager {
     begin(): RuntimeTransaction;
     currentId(): string | undefined;
+    /**
+     * Committed state as it was immediately before the outermost open transaction began —
+     * what a transition rule means by "previous". Not the previous operation, not the
+     * previous iteration.
+     */
+    entrySnapshot(): unknown;
 }
 export declare function createTransactionManager(store: StoreSnapshot, nextId: () => string): TransactionManager;
 //# sourceMappingURL=transaction.d.ts.map

package/dist/mutation/transaction.js

@@ -2,6 +2,7 @@ export function createTransactionManager(store, nextId) {
     const open = [];
     return {
         currentId: () => open[0]?.id,
+        entrySnapshot: () => open[0]?.snapshot,
         begin() {
             const isRoot = open.length === 0;
             const id = isRoot ? nextId() : open[0].id;

package/dist/mutation/values.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Raised when an expression cannot be evaluated — a collection operator applied to
+ * something that is not a collection, an aggregation over non-numeric data, a reference
+ * that does not resolve. Failing loudly is deliberate: an expression must never return a
+ * plausible-looking value and report a failure at the same time.
+ */
+export declare class ExpressionEvaluationError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message: string, details?: Record<string, unknown>);
+}
 /**
  * Value helpers shared by the runtime and the mutation subsystem.
  *
@@ -12,8 +22,13 @@
 export declare function cloneValue<T>(value: T): T;
 export declare function deepFreeze<T>(value: T): T;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
-/** Presence semantics used by `required` — distinct from boolean coercion. */
+/**
+ * Presence answers one question: does a value exist? It says nothing about whether the
+ * value is empty. An empty collection, an empty string, zero and false are all present.
+ */
 export declare function isPresent(value: unknown): boolean;
+/** Emptiness of a collection or a string. Anything else is never empty. */
+export declare function isEmptyValue(value: unknown): boolean;
 export declare function toBoolean(value: unknown): boolean;
 export declare function toText(value: unknown): string;
 export declare function compareValues(left: unknown, right: unknown): number;

package/dist/mutation/values.js

@@ -1,3 +1,17 @@
+/**
+ * Raised when an expression cannot be evaluated — a collection operator applied to
+ * something that is not a collection, an aggregation over non-numeric data, a reference
+ * that does not resolve. Failing loudly is deliberate: an expression must never return a
+ * plausible-looking value and report a failure at the same time.
+ */
+export class ExpressionEvaluationError extends Error {
+    details;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = 'ExpressionEvaluationError';
+        this.details = details;
+    }
+}
 /**
  * Value helpers shared by the runtime and the mutation subsystem.
  *
@@ -24,18 +38,25 @@ export function deepFreeze(value) {
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** Presence semantics used by `required` — distinct from boolean coercion. */
+/**
+ * Presence answers one question: does a value exist? It says nothing about whether the
+ * value is empty. An empty collection, an empty string, zero and false are all present.
+ */
 export function isPresent(value) {
+    return value !== null && value !== undefined;
+}
+/** Emptiness of a collection or a string. Anything else is never empty. */
+export function isEmptyValue(value) {
     if (value === null || value === undefined) {
-        return false;
+        return true;
     }
     if (typeof value === 'string') {
-        return value.trim().length > 0;
+        return value.trim().length === 0;
     }
     if (Array.isArray(value)) {
-        return value.length > 0;
+        return value.length === 0;
     }
-    return true;
+    return false;
 }
 export function toBoolean(value) {
     if (Array.isArray(value)) {
@@ -63,6 +84,19 @@ export function compareValues(left, right) {
     const rightText = toText(right);
     return leftText === rightText ? 0 : leftText < rightText ? -1 : 1;
 }
+/** A stable serialization, so record comparison does not depend on key order. */
+function canonical(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonical).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`).join(',')}}`;
+}
 export function valuesEqual(left, right) {
     if (left === right) {
         return true;
@@ -71,7 +105,7 @@ export function valuesEqual(left, right) {
         return (left ?? null) === (right ?? null);
     }
     if (typeof left === 'object' || typeof right === 'object') {
-        return JSON.stringify(left) === JSON.stringify(right);
+        return canonical(left) === canonical(right);
     }
     return false;
 }

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.d.ts

@@ -20,6 +20,7 @@ export declare const RUNTIME_DIAGNOSTIC_CODES: {
     readonly MUTATION_FAILED: "MUTATION_FAILED";
     readonly DERIVED_STATE_WRITE: "DERIVED_STATE_WRITE";
     readonly UNKNOWN_STATE: "UNKNOWN_STATE";
+    readonly TRANSITION_CONSTRAINT_VIOLATION: "TRANSITION_CONSTRAINT_VIOLATION";
     readonly UNSUPPORTED_EXPRESSION: "UNSUPPORTED_EXPRESSION";
     readonly UNSUPPORTED_OPERATION: "UNSUPPORTED_OPERATION";
     readonly ROUTE_NOT_FOUND: "ROUTE_NOT_FOUND";
@@ -69,7 +70,14 @@ export interface AxiomRuntime {
     start(): void;
     render(): void;
     getState(id: NodeId): unknown;
-    setState(id: NodeId, value: unknown): void;
+    /**
+     * Replaces a state value outright, for hosts, tests and seeding.
+     *
+     * This is an administrative facility, not a semantic write: it does not evaluate
+     * preconditions, entity constraints or transition constraints. Application behaviour
+     * belongs in actions and input bindings, which are governed.
+     */
+    hydrateState(id: NodeId, value: unknown): void;
     invokeAction(id: NodeId, args?: Record<string, unknown>): ActionResult;
     navigate(path: string): void;
     currentRoute(): RouteMatch | null;