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

package/README.md

@@ -9,6 +9,11 @@ The Application Graph and its semantic model: nodes, fields, structured types,
 expressions, **locations** (addressable writable positions), edge derivation,
 validation and type inference.
 
+It also owns the presentation and UX layer — semantic roles, layout, spacing and sizing
+tokens, device classes, value formats and the `Theme` — together with presentation
+resolution and validation. Presentation lives here because it is part of the canonical
+graph: it is intent, not styling, and it names no colour, length or CSS property.
+
 ## Installation
 
 ```bash

package/dist/diagnostics.d.ts

@@ -50,5 +50,20 @@ export declare const VALIDATION_CODES: {
     readonly initialValueInvalidEntity: "INITIAL_VALUE_INVALID_ENTITY";
     readonly scopeShadowing: "SCOPE_SHADOWING";
     readonly scopeCollidesWithNode: "SCOPE_COLLIDES_WITH_NODE";
+    readonly ephemeralStatePersisted: "EPHEMERAL_STATE_PERSISTED";
+    readonly unknownPresentationToken: "UNKNOWN_PRESENTATION_TOKEN";
+    readonly presentationSemanticConflict: "PRESENTATION_SEMANTIC_CONFLICT";
+    readonly multiplePrimaryActions: "MULTIPLE_PRIMARY_ACTIONS";
+    readonly formWithoutPrimaryAction: "FORM_WITHOUT_PRIMARY_ACTION";
+    readonly destructiveActionPresentedAsSuccess: "DESTRUCTIVE_ACTION_PRESENTED_AS_SUCCESS";
+    readonly destructiveActionUnmarked: "DESTRUCTIVE_ACTION_UNMARKED";
+    readonly excessiveHorizontalActions: "EXCESSIVE_HORIZONTAL_ACTIONS";
+    readonly emptyStateWithoutRecoveryAction: "EMPTY_STATE_WITHOUT_RECOVERY_ACTION";
+    readonly rigidHorizontalLayout: "RIGID_HORIZONTAL_LAYOUT";
+    readonly conflictingSizing: "CONFLICTING_SIZING";
+    readonly interactiveElementMissingLabel: "INTERACTIVE_ELEMENT_MISSING_LABEL";
+    readonly formInputMissingLabel: "FORM_INPUT_MISSING_LABEL";
+    readonly invalidHeadingStructure: "INVALID_HEADING_STRUCTURE";
+    readonly opaquePresentation: "OPAQUE_PRESENTATION";
 };
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -33,4 +33,21 @@ export const VALIDATION_CODES = {
     initialValueInvalidEntity: 'INITIAL_VALUE_INVALID_ENTITY',
     scopeShadowing: 'SCOPE_SHADOWING',
     scopeCollidesWithNode: 'SCOPE_COLLIDES_WITH_NODE',
+    ephemeralStatePersisted: 'EPHEMERAL_STATE_PERSISTED',
+    // Presentation and UX. Everything here is a warning except an unknown token, which the
+    // renderer genuinely cannot act on.
+    unknownPresentationToken: 'UNKNOWN_PRESENTATION_TOKEN',
+    presentationSemanticConflict: 'PRESENTATION_SEMANTIC_CONFLICT',
+    multiplePrimaryActions: 'MULTIPLE_PRIMARY_ACTIONS',
+    formWithoutPrimaryAction: 'FORM_WITHOUT_PRIMARY_ACTION',
+    destructiveActionPresentedAsSuccess: 'DESTRUCTIVE_ACTION_PRESENTED_AS_SUCCESS',
+    destructiveActionUnmarked: 'DESTRUCTIVE_ACTION_UNMARKED',
+    excessiveHorizontalActions: 'EXCESSIVE_HORIZONTAL_ACTIONS',
+    emptyStateWithoutRecoveryAction: 'EMPTY_STATE_WITHOUT_RECOVERY_ACTION',
+    rigidHorizontalLayout: 'RIGID_HORIZONTAL_LAYOUT',
+    conflictingSizing: 'CONFLICTING_SIZING',
+    interactiveElementMissingLabel: 'INTERACTIVE_ELEMENT_MISSING_LABEL',
+    formInputMissingLabel: 'FORM_INPUT_MISSING_LABEL',
+    invalidHeadingStructure: 'INVALID_HEADING_STRUCTURE',
+    opaquePresentation: 'OPAQUE_PRESENTATION',
 };

package/dist/graph.d.ts

@@ -1,6 +1,7 @@
 import type { EdgeId, FieldId, NodeId } from './ids.js';
 import type { EdgeKind, FieldDef, GraphEdge } from './nodes.js';
 import type { AnyNode, ApplicationGraphData, NodeInput, NodeKind, NodeOfKind } from './types.js';
+import type { Theme, ThemeInput } from './theme.js';
 export interface FieldIndexEntry {
     entityId: NodeId;
     field: FieldDef;
@@ -25,6 +26,14 @@ export declare class ApplicationGraph {
     get id(): string;
     get name(): string;
     get version(): string;
+    /**
+     * The application's visual identity, completed against the default theme. A theme is
+     * presentation only: changing it cannot change an action, a constraint or a route.
+     */
+    get theme(): Theme;
+    /** Exactly what the application declared, before defaults were filled in. */
+    get declaredTheme(): ThemeInput | undefined;
+    setTheme(theme: ThemeInput | undefined): void;
     addNode<T extends AnyNode>(node: NodeInput<T>): NodeId;
     getNode<T extends AnyNode = AnyNode>(id: NodeId): T | undefined;
     hasNode(id: NodeId): boolean;

package/dist/graph.js

@@ -1,5 +1,6 @@
 import { deriveEdges } from './derive-edges.js';
 import { createEdgeId, createNodeId } from './ids.js';
+import { resolveTheme } from './theme.js';
 function clone(value) {
     return structuredClone(value);
 }
@@ -16,7 +17,7 @@ export class ApplicationGraph {
     /** Bumped by every change, so the derived edge index can never serve stale data. */
     revision = 0;
     semanticIndex;
-    constructor(id, name, version = '0.4.1') {
+    constructor(id, name, version = '0.5.0') {
         this.data = { id, name, version, nodes: {}, edges: {} };
     }
     get id() {
@@ -28,6 +29,26 @@ export class ApplicationGraph {
     get version() {
         return this.data.version;
     }
+    /**
+     * The application's visual identity, completed against the default theme. A theme is
+     * presentation only: changing it cannot change an action, a constraint or a route.
+     */
+    get theme() {
+        return resolveTheme(this.data.theme);
+    }
+    /** Exactly what the application declared, before defaults were filled in. */
+    get declaredTheme() {
+        return this.data.theme ? structuredClone(this.data.theme) : undefined;
+    }
+    setTheme(theme) {
+        if (theme === undefined) {
+            delete this.data.theme;
+        }
+        else {
+            this.data.theme = structuredClone(theme);
+        }
+        this.revision += 1;
+    }
     addNode(node) {
         const id = (node.id ?? createNodeId(node.kind));
         if (this.data.nodes[id]) {

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './ids.js';
 export * from './diagnostics.js';
 export * from './location.js';
+export * from './presentation.js';
+export * from './theme.js';
 export * from './type-ref.js';
 export * from './expressions.js';
 export * from './nodes.js';
@@ -10,7 +12,9 @@ export * from './graph.js';
 export * from './infer.js';
 export * from './context.js';
 export * from './validate-location.js';
+export * from './resolve-presentation.js';
 export * from './validate.js';
+export * from './validate-presentation.js';
 export * from './derive-edges.js';
 export * from './ir.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from './ids.js';
 export * from './diagnostics.js';
 export * from './location.js';
+export * from './presentation.js';
+export * from './theme.js';
 export * from './type-ref.js';
 export * from './expressions.js';
 export * from './nodes.js';
@@ -10,6 +12,8 @@ export * from './graph.js';
 export * from './infer.js';
 export * from './context.js';
 export * from './validate-location.js';
+export * from './resolve-presentation.js';
 export * from './validate.js';
+export * from './validate-presentation.js';
 export * from './derive-edges.js';
 export * from './ir.js';

package/dist/ir.d.ts

@@ -4,6 +4,8 @@ import type { FieldIndexEntry } from './graph.js';
 import type { UINode } from './ui.js';
 import type { AnyNode } from './types.js';
 import type { TypeRef } from './type-ref.js';
+import type { ResolvedPresentation } from './presentation.js';
+import type { Theme } from './theme.js';
 export interface RouteSegment {
     kind: 'static' | 'parameter';
     value: string;
@@ -48,5 +50,21 @@ export interface ApplicationIR {
      * to canonical application state from a write to a draft.
      */
     locationRoots: Record<NodeId, NodeId>;
+    /**
+     * Whether the field each input addresses is declared required, resolved here so a
+     * renderer can mark it without re-deriving the model.
+     */
+    locationRequired: Record<NodeId, boolean>;
+    /** The application's visual identity, completed against the default theme. */
+    theme: Theme;
+    /**
+     * Presentation with every question already answered, per UI node: renderer defaults,
+     * theme, inheritance, semantic inference, node declaration and responsive overrides all
+     * resolved. A renderer reads this and needs to know nothing about how it was decided.
+     *
+     * It is deliberately still semantic — roles, tokens and device classes, not CSS — so a
+     * second renderer remains possible.
+     */
+    presentation: Record<NodeId, ResolvedPresentation>;
 }
 //# sourceMappingURL=ir.d.ts.map

package/dist/nodes.d.ts

@@ -2,12 +2,7 @@ import type { Expression } from './expressions.js';
 import type { CollectionItemLocation, Location } from './location.js';
 import type { EdgeId, FieldId, NodeId } from './ids.js';
 import type { TypeRef } from './type-ref.js';
-/** Minimal, optional presentation hints. Styling is not a 0.2 research objective. */
-export interface PresentationHints {
-    role?: 'primary' | 'secondary' | 'danger';
-    density?: 'compact' | 'normal';
-    emphasis?: 'normal' | 'strong';
-}
+import type { ConfirmationPresentation } from './presentation.js';
 export interface NodeBase {
     id: NodeId;
     name?: string;
@@ -50,6 +45,16 @@ export interface StateDef extends NodeBase {
      * definition, so instance validation skips them until an action commits the value.
      */
     draft?: boolean;
+    /**
+     * Marks ephemeral presentation state — which panel is expanded, which tab is selected,
+     * whether a dialog is open. It is not canonical domain state: instance validation skips
+     * it, and it may not be persisted. Marking it says so in the graph instead of leaving an
+     * agent to guess which states are domain facts.
+     *
+     * It changes what a state *is*, never what is permitted: a write reaching domain state
+     * is governed exactly as before.
+     */
+    ephemeral?: boolean;
     persistence?: StatePersistence;
 }
 export interface ActionParameter {
@@ -80,6 +85,8 @@ export interface ActionDef extends NodeBase {
     destructive?: boolean;
     requiresConfirmation?: boolean;
     confirmationMessage?: string;
+    /** What the confirmation says, when a plain message is not enough. */
+    confirmation?: ConfirmationPresentation;
 }
 /**
  * The conditions an action checks, however they were written. `guards` pairs each

package/dist/presentation.d.ts

@@ -0,0 +1,270 @@
+import type { NodeId } from './ids.js';
+/**
+ * The presentation and UX vocabulary of 0.5.
+ *
+ * Everything here describes *intent*, never rendering. `role: 'destructive'` says what a
+ * control means; a theme and a renderer decide what that looks like. No entry in this
+ * module names a colour, a pixel, a font or a CSS property, and nothing in it can hold a
+ * function — presentation stays serializable and analyzable like the rest of the graph.
+ */
+/** What a control or region *means*. A theme decides how each role is rendered. */
+export type PresentationRole = 'primary' | 'secondary' | 'tertiary' | 'destructive' | 'success' | 'warning' | 'informational' | 'muted';
+export declare const PRESENTATION_ROLES: readonly PresentationRole[];
+/** 0.2 called the destructive role "danger". It is accepted and normalized, not an error. */
+export type LegacyPresentationRole = 'danger';
+export type Emphasis = 'subtle' | 'normal' | 'strong';
+export declare const EMPHASIS_LEVELS: readonly Emphasis[];
+export type Density = 'compact' | 'comfortable' | 'spacious';
+export declare const DENSITIES: readonly Density[];
+/** 0.2 called the comfortable density "normal". Accepted and normalized. */
+export type LegacyDensity = 'normal';
+/** Semantic spacing. A theme maps each token to a renderer value. */
+export type SpacingToken = 'none' | 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge';
+export declare const SPACING_TOKENS: readonly SpacingToken[];
+/** How a node relates to the space it is given. */
+export type SizingToken = 'fit' | 'fill' | 'content';
+/** A bounded semantic size, used where a measurement would otherwise be needed. */
+export type BoundedSize = 'narrow' | 'medium' | 'wide';
+export type SizingValue = SizingToken | BoundedSize;
+export declare const SIZING_TOKENS: readonly SizingToken[];
+export declare const BOUNDED_SIZES: readonly BoundedSize[];
+export declare const SIZING_VALUES: readonly SizingValue[];
+export type Alignment = 'start' | 'center' | 'end' | 'stretch';
+export declare const ALIGNMENTS: readonly Alignment[];
+/** Distribution along the layout direction. `between` spreads the free space out. */
+export type Justification = Alignment | 'between';
+export declare const JUSTIFICATIONS: readonly Justification[];
+export type LayoutKind = 'vertical' | 'horizontal' | 'grid' | 'stack';
+export declare const LAYOUT_KINDS: readonly LayoutKind[];
+/**
+ * Columns of a grid, stated semantically. `adaptive` says "as many columns of at least
+ * this width as fit", which is what a responsive card list actually means; a number says
+ * exactly how many. Neither form exposes a track template.
+ */
+export type GridColumns = number | {
+    mode: 'adaptive';
+    minimum: BoundedSize;
+};
+export interface LayoutPresentation {
+    kind: LayoutKind;
+    gap?: SpacingToken;
+    /** Across the layout direction. */
+    align?: Alignment;
+    /** Along the layout direction. */
+    justify?: Justification;
+    wrap?: boolean;
+    columns?: GridColumns;
+}
+/** `layout: 'horizontal'` is shorthand for `layout: { kind: 'horizontal' }`. */
+export type LayoutIntent = LayoutKind | LayoutPresentation;
+export interface SizingPresentation {
+    width?: SizingValue;
+    height?: SizingValue;
+    minWidth?: BoundedSize;
+    maxWidth?: BoundedSize;
+}
+/** `padding: 'medium'` is shorthand for the same amount on every side. */
+export type PaddingIntent = SpacingToken | {
+    horizontal?: SpacingToken;
+    vertical?: SpacingToken;
+};
+export type SurfaceRole = 'transparent' | 'base' | 'subtle' | 'raised' | 'inset';
+export declare const SURFACE_ROLES: readonly SurfaceRole[];
+/** Semantic text roles. A theme maps each to font metrics; the graph names no sizes. */
+export type TextRole = 'body' | 'caption' | 'label' | 'heading' | 'title' | 'display';
+export declare const TEXT_ROLES: readonly TextRole[];
+/**
+ * Why a node exists in the interface. A UX role is high-information: `toolbar` implies a
+ * horizontal, wrapping, centre-aligned group, so an author states the role rather than
+ * six layout properties. It stays inspectable — nothing compiles it into an opaque
+ * component.
+ */
+export type UxRole = 'primary-action' | 'secondary-action' | 'destructive-action' | 'navigation-action' | 'form-section' | 'action-group' | 'navigation-group' | 'empty-state' | 'error-state' | 'warning-state' | 'success-state' | 'informational-state' | 'toolbar' | 'sidebar' | 'content-region' | 'header-region' | 'footer-region';
+export declare const UX_ROLES: readonly UxRole[];
+/** UX roles that name an action's place in the hierarchy rather than a region. */
+export declare const ACTION_UX_ROLES: readonly UxRole[];
+/** UX roles that report a condition, and which a renderer may announce. */
+export declare const STATUS_UX_ROLES: readonly UxRole[];
+/** How a value is presented once it has been formatted. */
+export type Treatment = 'plain' | 'badge' | 'pill';
+export declare const TREATMENTS: readonly Treatment[];
+/**
+ * The kind of control a value should be edited with, stated as intent. The renderer maps
+ * it onto whatever the platform offers; the graph never names an HTML input type.
+ */
+export type ControlVariant = 'default' | 'switch' | 'checkbox' | 'radio-group' | 'select' | 'multiline' | 'stepper';
+export declare const CONTROL_VARIANTS: readonly ControlVariant[];
+/** Semantic icon names. A theme supplies the glyphs; the graph stores no artwork. */
+export type IconName = 'add' | 'delete' | 'edit' | 'save' | 'close' | 'warning' | 'success' | 'error' | 'information' | 'navigation-back' | 'navigation-forward' | 'menu' | 'search' | 'refresh' | 'settings' | 'more';
+export declare const ICON_NAMES: readonly IconName[];
+/**
+ * Viewport classes, not pixels. An author says what should happen on a compact display;
+ * the renderer decides where compact begins.
+ */
+export type DeviceClass = 'compact' | 'regular' | 'wide';
+export declare const DEVICE_CLASSES: readonly DeviceClass[];
+export type DateStyle = 'short' | 'medium' | 'long';
+/**
+ * Structured value formatting. Formatting is presentation: the stored value is unchanged,
+ * and there is deliberately no way to supply a function.
+ */
+export type ValueFormat = {
+    kind: 'text';
+} | {
+    kind: 'number';
+    decimals?: number;
+    grouping?: boolean;
+} | {
+    kind: 'currency';
+    currency: string;
+    decimals?: number;
+} | {
+    kind: 'percentage';
+    decimals?: number;
+    scale?: 'fraction' | 'percent';
+} | {
+    kind: 'boolean';
+    trueLabel?: string;
+    falseLabel?: string;
+} | {
+    kind: 'date';
+    style?: DateStyle;
+} | {
+    kind: 'datetime';
+    style?: DateStyle;
+};
+export type ValueFormatKind = ValueFormat['kind'];
+export declare const VALUE_FORMAT_KINDS: readonly ValueFormatKind[];
+/** What a device class changes. Anything absent keeps its resolved value. */
+export interface ResponsiveOverride {
+    layout?: LayoutIntent;
+    sizing?: SizingPresentation;
+    padding?: PaddingIntent;
+    gap?: SpacingToken;
+    density?: Density | LegacyDensity;
+    hidden?: boolean;
+}
+export type ResponsivePresentation = Partial<Record<DeviceClass, ResponsiveOverride>>;
+/**
+ * The escape hatch of §50. It is explicitly keyed by renderer, it is reported by
+ * `AgentAPI`, and semantic analysis makes no claim to understand it. Ordinary
+ * applications — including every acceptance fixture — use none of it.
+ */
+export interface RendererOverride {
+    /** A renderer-specific class name. The renderer attaches it and nothing else. */
+    className?: string;
+    [key: string]: unknown;
+}
+/**
+ * Presentation and UX intent attached to a UI node. Every field is optional: defaults,
+ * inheritance, semantic inference and the theme are expected to do most of the work, and
+ * a graph with no presentation at all still renders as a usable application.
+ */
+export interface Presentation {
+    role?: PresentationRole | LegacyPresentationRole;
+    emphasis?: Emphasis;
+    density?: Density | LegacyDensity;
+    textRole?: TextRole;
+    uxRole?: UxRole;
+    surface?: SurfaceRole;
+    treatment?: Treatment;
+    icon?: IconName;
+    /** An accessible name, for a control whose visible label is an icon or is empty. */
+    accessibleLabel?: string;
+    /** Help text. UX affordance, not business data. */
+    description?: string;
+    layout?: LayoutIntent;
+    sizing?: SizingPresentation;
+    padding?: PaddingIntent;
+    gap?: SpacingToken;
+    format?: ValueFormat;
+    control?: ControlVariant;
+    responsive?: ResponsivePresentation;
+    rendererOverrides?: Record<string, RendererOverride>;
+}
+/**
+ * The 0.2 name for presentation intent. Kept so 0.4 graphs compile unchanged.
+ *
+ * @deprecated Use `Presentation`.
+ */
+export type PresentationHints = Presentation;
+/**
+ * How a confirmation is presented. `ActionDef.requiresConfirmation` already states that a
+ * confirmation is required; this states what the person is asked. It carries no browser
+ * dialog markup, so a renderer with no dialogs can still present it.
+ */
+export interface ConfirmationPresentation {
+    title?: string;
+    description?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    severity?: 'informational' | 'warning' | 'destructive';
+}
+/**
+ * Which layer of §40 gave a resolved property its value. Recording it is what makes
+ * precedence testable instead of a claim in a document.
+ */
+export type PresentationOrigin = 'renderer-default' | 'theme' | 'inherited' | 'inferred' | 'node' | 'responsive';
+export declare const PRESENTATION_ORIGINS: readonly PresentationOrigin[];
+export interface ResolvedLayout {
+    kind: LayoutKind;
+    gap: SpacingToken;
+    align: Alignment;
+    justify: Justification;
+    wrap: boolean;
+    columns?: GridColumns;
+}
+export interface ResolvedSizing {
+    width: SizingValue;
+    height: SizingValue;
+    minWidth?: BoundedSize;
+    maxWidth?: BoundedSize;
+}
+export interface ResolvedPadding {
+    horizontal: SpacingToken;
+    vertical: SpacingToken;
+}
+export interface ResolvedResponsive {
+    layout?: ResolvedLayout;
+    sizing?: ResolvedSizing;
+    padding?: ResolvedPadding;
+    density?: Density;
+    hidden?: boolean;
+}
+/**
+ * Presentation with every question answered. The renderer reads this and nothing else,
+ * so a renderer needs no knowledge of themes, inheritance or inference.
+ */
+export interface ResolvedPresentation {
+    nodeId: NodeId;
+    role?: PresentationRole;
+    emphasis: Emphasis;
+    density: Density;
+    textRole: TextRole;
+    uxRole?: UxRole;
+    surface: SurfaceRole;
+    treatment: Treatment;
+    icon?: IconName;
+    accessibleLabel?: string;
+    description?: string;
+    layout: ResolvedLayout;
+    sizing: ResolvedSizing;
+    padding: ResolvedPadding;
+    format?: ValueFormat;
+    control: ControlVariant;
+    responsive: Partial<Record<DeviceClass, ResolvedResponsive>>;
+    rendererOverrides?: Record<string, RendererOverride>;
+    /** True when the node carries renderer-specific presentation nothing here understands. */
+    opaque: boolean;
+    /** Property name → the layer that decided it. */
+    origins: Record<string, PresentationOrigin>;
+}
+/** Legacy role names, mapped onto the 0.5 vocabulary. */
+export declare function normalizeRole(role: Presentation['role']): PresentationRole | undefined;
+/** Legacy density names, mapped onto the 0.5 vocabulary. */
+export declare function normalizeDensity(density: Presentation['density']): Density | undefined;
+export declare function normalizeLayout(layout: LayoutIntent | undefined): LayoutPresentation | undefined;
+export declare function normalizePadding(padding: PaddingIntent | undefined): ResolvedPadding | undefined;
+/** True when a node carries renderer-specific presentation that cannot be analyzed. */
+export declare function hasOpaquePresentation(presentation: Presentation | undefined): boolean;
+//# sourceMappingURL=presentation.d.ts.map

package/dist/presentation.js

@@ -0,0 +1,152 @@
+export const PRESENTATION_ROLES = [
+    'primary',
+    'secondary',
+    'tertiary',
+    'destructive',
+    'success',
+    'warning',
+    'informational',
+    'muted',
+];
+export const EMPHASIS_LEVELS = ['subtle', 'normal', 'strong'];
+export const DENSITIES = ['compact', 'comfortable', 'spacious'];
+export const SPACING_TOKENS = [
+    'none',
+    'xsmall',
+    'small',
+    'medium',
+    'large',
+    'xlarge',
+];
+export const SIZING_TOKENS = ['fit', 'fill', 'content'];
+export const BOUNDED_SIZES = ['narrow', 'medium', 'wide'];
+export const SIZING_VALUES = [...SIZING_TOKENS, ...BOUNDED_SIZES];
+export const ALIGNMENTS = ['start', 'center', 'end', 'stretch'];
+export const JUSTIFICATIONS = [...ALIGNMENTS, 'between'];
+export const LAYOUT_KINDS = ['vertical', 'horizontal', 'grid', 'stack'];
+export const SURFACE_ROLES = ['transparent', 'base', 'subtle', 'raised', 'inset'];
+export const TEXT_ROLES = ['body', 'caption', 'label', 'heading', 'title', 'display'];
+export const UX_ROLES = [
+    'primary-action',
+    'secondary-action',
+    'destructive-action',
+    'navigation-action',
+    'form-section',
+    'action-group',
+    'navigation-group',
+    'empty-state',
+    'error-state',
+    'warning-state',
+    'success-state',
+    'informational-state',
+    'toolbar',
+    'sidebar',
+    'content-region',
+    'header-region',
+    'footer-region',
+];
+/** UX roles that name an action's place in the hierarchy rather than a region. */
+export const ACTION_UX_ROLES = [
+    'primary-action',
+    'secondary-action',
+    'destructive-action',
+    'navigation-action',
+];
+/** UX roles that report a condition, and which a renderer may announce. */
+export const STATUS_UX_ROLES = [
+    'empty-state',
+    'error-state',
+    'warning-state',
+    'success-state',
+    'informational-state',
+];
+export const TREATMENTS = ['plain', 'badge', 'pill'];
+export const CONTROL_VARIANTS = [
+    'default',
+    'switch',
+    'checkbox',
+    'radio-group',
+    'select',
+    'multiline',
+    'stepper',
+];
+export const ICON_NAMES = [
+    'add',
+    'delete',
+    'edit',
+    'save',
+    'close',
+    'warning',
+    'success',
+    'error',
+    'information',
+    'navigation-back',
+    'navigation-forward',
+    'menu',
+    'search',
+    'refresh',
+    'settings',
+    'more',
+];
+export const DEVICE_CLASSES = ['compact', 'regular', 'wide'];
+export const VALUE_FORMAT_KINDS = [
+    'text',
+    'number',
+    'currency',
+    'percentage',
+    'boolean',
+    'date',
+    'datetime',
+];
+export const PRESENTATION_ORIGINS = [
+    'renderer-default',
+    'theme',
+    'inherited',
+    'inferred',
+    'node',
+    'responsive',
+];
+// --------------------------------------------------------------- normalization
+/** Legacy role names, mapped onto the 0.5 vocabulary. */
+export function normalizeRole(role) {
+    if (role === undefined) {
+        return undefined;
+    }
+    if (role === 'danger') {
+        return 'destructive';
+    }
+    return PRESENTATION_ROLES.includes(role) ? role : undefined;
+}
+/** Legacy density names, mapped onto the 0.5 vocabulary. */
+export function normalizeDensity(density) {
+    if (density === undefined) {
+        return undefined;
+    }
+    if (density === 'normal') {
+        return 'comfortable';
+    }
+    return DENSITIES.includes(density) ? density : undefined;
+}
+export function normalizeLayout(layout) {
+    if (layout === undefined) {
+        return undefined;
+    }
+    return typeof layout === 'string' ? { kind: layout } : layout;
+}
+export function normalizePadding(padding) {
+    if (padding === undefined) {
+        return undefined;
+    }
+    if (typeof padding === 'string') {
+        return { horizontal: padding, vertical: padding };
+    }
+    if (padding.horizontal === undefined && padding.vertical === undefined) {
+        return undefined;
+    }
+    return { horizontal: padding.horizontal ?? 'none', vertical: padding.vertical ?? 'none' };
+}
+/** True when a node carries renderer-specific presentation that cannot be analyzed. */
+export function hasOpaquePresentation(presentation) {
+    const overrides = presentation?.rendererOverrides;
+    return Boolean(overrides && Object.keys(overrides).length > 0);
+}