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

package/README.md

@@ -9,6 +9,13 @@ 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 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.
+
+Main exports: `createAxiomRuntime`, `createBrowserHost`, `createMemoryHost`,
+`RUNTIME_DIAGNOSTIC_CODES`, `formatValue`, `presentationClassList`.
+
 ## Installation
 
 ```bash
@@ -21,6 +28,13 @@ Most applications should install the facade package instead, which re-exports th
 npm install @cynodia/axiom@alpha
 ```
 
+
+## Documentation
+
+The canonical operational contract lives in the `docs/` directory of the
+[`@cynodia/axiom`](https://www.npmjs.com/package/@cynodia/axiom) package, and in
+[the repository](https://github.com/cynodia/axiom). Start with `docs/AGENT_REFERENCE.md`.
+
 ## License
 
 MIT

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,21 @@
+import type { ResolvedPresentation, 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 element follows the resolved **`headingLevel`**, never the type scale: a value drawn
+ * at `display` size with `headingLevel: 'none'` is a `<span>`, which is what a monetary
+ * total or a dashboard statistic should be.
+ */
+export declare function headingTag(resolved: ResolvedPresentation | 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,154 @@
+/**
+ * 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) {
+    // A `none` token is the absence of the property, not a value to assert. Emitting it
+    // would override the component rules that give a control its own metrics.
+    const classes = [`axiom-${prefix}layout-${layout.kind}`];
+    if (layout.gap !== 'none') {
+        classes.push(`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) {
+    const classes = [];
+    if (padding.horizontal !== 'none') {
+        classes.push(`axiom-${prefix}pad-x-${padding.horizontal}`);
+    }
+    if (padding.vertical !== 'none') {
+        classes.push(`axiom-${prefix}pad-y-${padding.vertical}`);
+    }
+    return classes;
+}
+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 element follows the resolved **`headingLevel`**, never the type scale: a value drawn
+ * at `display` size with `headingLevel: 'none'` is a `<span>`, which is what a monetary
+ * total or a dashboard statistic should be.
+ */
+export function headingTag(resolved) {
+    const level = resolved?.headingLevel;
+    return typeof level === 'number' ? `h${level}` : 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

@@ -31,6 +31,10 @@ export declare const RUNTIME_DIAGNOSTIC_CODES: {
     readonly PERSISTED_STATE_UNREADABLE: "PERSISTED_STATE_UNREADABLE";
 };
 export type RuntimeDiagnosticCode = (typeof RUNTIME_DIAGNOSTIC_CODES)[keyof typeof RUNTIME_DIAGNOSTIC_CODES];
+/**
+ * A structured runtime failure. Match on `code` and read `details`; the `message` is for
+ * people and is not a stable contract.
+ */
 export interface RuntimeDiagnostic {
     code: RuntimeDiagnosticCode;
     message: string;
@@ -49,13 +53,30 @@ export interface ActionResult {
     ok: boolean;
     diagnostics: RuntimeDiagnostic[];
 }
+/**
+ * The outcome of an action's most recent invocation.
+ *
+ * `ok` and `cancelled` both carry no diagnostics, so a `diagnostic` UI node presenting
+ * this action shows nothing after either. They are distinguished here because the
+ * difference matters to an agent: `cancelled` means a person declined the confirmation,
+ * not that the action was refused.
+ */
+export interface ActionOutcome {
+    actionId: NodeId;
+    outcome: 'ok' | 'failed' | 'cancelled';
+    diagnostics: RuntimeDiagnostic[];
+}
 export interface RouteMatch {
     route: CompiledRoute;
     /** Parameter values keyed by route parameter id. */
     parameters: Record<string, string>;
 }
 export type NativeImplementation = (inputs: Record<string, unknown>) => unknown;
-/** When constraints are evaluated after an input writes to its location. */
+/**
+ * When entity constraints are evaluated after an input writes to its location.
+ * `'deferred'` turns the per-keystroke check off entirely, leaving validity to the next
+ * action. Transition constraints are unaffected by this setting and always apply.
+ */
 export type InputValidationMode = 'immediate' | 'deferred';
 export interface AxiomRuntimeOptions {
     ir: ApplicationIR;
@@ -69,6 +90,7 @@ export interface AxiomRuntimeOptions {
 export interface AxiomRuntime {
     start(): void;
     render(): void;
+    /** A deep clone of the value. Derived state is recomputed. */
     getState(id: NodeId): unknown;
     /**
      * Replaces a state value outright, for hosts, tests and seeding.
@@ -78,12 +100,24 @@ export interface AxiomRuntime {
      * belongs in actions and input bindings, which are governed.
      */
     hydrateState(id: NodeId, value: unknown): void;
+    /**
+     * Runs an action as a transaction and returns the diagnostics **of that invocation**,
+     * so nothing has to diff global history. Either every mutation commits or every one is
+     * rolled back.
+     */
     invokeAction(id: NodeId, args?: Record<string, unknown>): ActionResult;
     navigate(path: string): void;
     currentRoute(): RouteMatch | null;
     /** Every diagnostic reported so far. Per-invocation results carry their own. */
     diagnostics(): RuntimeDiagnostic[];
+    /** Clears the running log **and** every recorded action outcome. */
     clearDiagnostics(): void;
+    /**
+     * The outcome of this action's most recent invocation, or `undefined` if it has not been
+     * invoked since the last clear or route change. This is what a `diagnostic` UI node
+     * presents.
+     */
+    getActionOutcome(id: NodeId): ActionOutcome | undefined;
     /** Every mutation this runtime has applied, in order, with its semantic location. */
     getMutationLog(): MutationLogEntry[];
     registerNativeOperation(implementationId: string, implementation: NativeImplementation): void;