@cynodia/axiom-agent-api 0.4.1-alpha.1 → 0.5.2-alpha.1

package/README.md

@@ -5,8 +5,12 @@ framework.
 
 **Status: experimental / alpha.** The API may change between alpha releases.
 
-The machine-facing interface: semantic queries over the graph, field-level dependency
-and mutation-impact analysis, and transactional graph transformations.
+The machine-facing interface: semantic queries over the graph, field-level dependency and
+mutation-impact analysis, presentation and UX queries, and transactional graph
+transformations.
+
+Main exports: `AgentAPI`, `GraphQueries`, `PresentationQueries`, `Transaction`,
+`ChangeSet`.
 
 ## Installation
 
@@ -20,6 +24,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/api.d.ts

@@ -1,12 +1,12 @@
 import type { ApplicationGraph, ValidationResult } from '@cynodia/axiom-core';
-import { GraphQueries } from './queries.js';
+import { PresentationQueries } from './presentation-queries.js';
 import { Transaction } from './transaction.js';
 import type { ChangeSet } from './changes.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
  */
-export declare class AgentAPI extends GraphQueries {
+export declare class AgentAPI extends PresentationQueries {
     private readonly changeLog;
     constructor(graph: ApplicationGraph);
     validate(): ValidationResult;

package/dist/api.js

@@ -1,11 +1,11 @@
 import { validateGraph } from '@cynodia/axiom-core';
-import { GraphQueries } from './queries.js';
+import { PresentationQueries } from './presentation-queries.js';
 import { Transaction } from './transaction.js';
 /**
  * The machine-facing interface to an application. Agents query semantics and apply
  * structural transformations; they never edit generated code.
  */
-export class AgentAPI extends GraphQueries {
+export class AgentAPI extends PresentationQueries {
     changeLog = [];
     constructor(graph) {
         super(graph);

package/dist/changes.d.ts

@@ -1,5 +1,5 @@
-import type { AnyNode, FieldDef, FieldId, GraphEdge, NodeId } from '@cynodia/axiom-core';
-export type GraphChange = AddNodeChange | RemoveNodeChange | UpdateNodeChange | AddFieldChange | RemoveFieldChange | AddEdgeChange | RemoveEdgeChange;
+import type { AnyNode, FieldDef, FieldId, GraphEdge, NodeId, ThemeInput } from '@cynodia/axiom-core';
+export type GraphChange = AddNodeChange | RemoveNodeChange | UpdateNodeChange | AddFieldChange | RemoveFieldChange | AddEdgeChange | RemoveEdgeChange | SetThemeChange;
 export interface AddNodeChange {
     kind: 'add-node';
     nodeId: NodeId;
@@ -35,6 +35,16 @@ export interface RemoveEdgeChange {
     kind: 'remove-edge';
     edge: GraphEdge;
 }
+/**
+ * A change to the application's visual identity. It is recorded like any other change and
+ * can never alter behaviour, which is why an application-wide restyling is one operation
+ * rather than an edit to every node.
+ */
+export interface SetThemeChange {
+    kind: 'set-theme';
+    before?: ThemeInput;
+    after?: ThemeInput;
+}
 /** A semantic change record: graph operations and intent, never a textual diff. */
 export interface ChangeSet {
     id: string;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './changes.js';
 export * from './queries.js';
+export * from './presentation-queries.js';
 export * from './transaction.js';
 export * from './api.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './changes.js';
 export * from './queries.js';
+export * from './presentation-queries.js';
 export * from './transaction.js';
 export * from './api.js';

package/dist/presentation-queries.d.ts

@@ -0,0 +1,106 @@
+import type { ActionDef, Density, DeviceClass, DiagnosticNode, FormNode, NodeId, Presentation, PresentationRole, ResolvedPresentation, ResolvedResponsive, StateDef, Theme, UINode, UxRole, ValidationIssue, ViewNode } from '@cynodia/axiom-core';
+import { GraphQueries } from './queries.js';
+/** One grouped part of a form, and what it contains. */
+export interface FormSectionSummary {
+    nodeId: NodeId;
+    name?: string;
+    /** Text nodes inside the section that act as headings. */
+    headings: string[];
+    inputIds: NodeId[];
+}
+/**
+ * The shape of a form as UX, rather than as a list of children: which parts are sections,
+ * which controls are required, where the actions are and which one is primary.
+ */
+/**
+ * The **declared** structure of a form: what it contains, not what is on screen right now.
+ *
+ * It is read along the primary render path, so an alternative branch — an empty template,
+ * a conditional's false branch — is not described as part of the form's structure.
+ */
+export interface FormStructure {
+    formId: NodeId;
+    density: Density;
+    submitActionId?: NodeId;
+    /** Set when the form uses a declared `ButtonNode` as its submit control. */
+    submitButtonId?: NodeId;
+    sections: FormSectionSummary[];
+    /** Inputs that belong to no section. */
+    ungroupedInputIds: NodeId[];
+    actionGroupIds: NodeId[];
+    primaryActionIds: NodeId[];
+    destructiveActionIds: NodeId[];
+    requiredInputIds: NodeId[];
+}
+/**
+ * Presentation and UX queries, §46 and §47.
+ *
+ * These are the questions that cannot be answered from a stylesheet: which control is the
+ * primary action, which regions are grouped and why, what happens on a narrow display,
+ * where the presentation contradicts the application's own semantics. They are answerable
+ * here only because UX intent is structured data.
+ *
+ * Resolution is recomputed per call rather than cached: a transaction mutates the graph
+ * underneath these queries, and a stale presentation answer would be worse than a slow one.
+ */
+export declare class PresentationQueries extends GraphQueries {
+    /** The application's visual identity, completed against the default theme. */
+    getTheme(): Theme;
+    /** Exactly what a node declares, before defaults, inheritance or inference. */
+    getPresentation(nodeId: NodeId): Presentation | undefined;
+    /** Presentation with every question answered, as a renderer receives it. */
+    resolvePresentation(nodeId: NodeId): ResolvedPresentation | undefined;
+    /** Resolved presentation for every UI node in the application. */
+    resolveAllPresentation(): Record<NodeId, ResolvedPresentation>;
+    getUxRole(nodeId: NodeId): UxRole | undefined;
+    /** What changes on a compact, regular or wide display. */
+    getResponsiveBehavior(nodeId: NodeId): Partial<Record<DeviceClass, ResolvedResponsive>>;
+    /** Every UI node whose resolved UX role is this one. */
+    findNodesByUxRole(uxRole: UxRole): UINode[];
+    /** Every UI node presented in this role, however the role was decided. */
+    findNodesByRole(role: PresentationRole): UINode[];
+    /** Which nodes end up at a given density, inheritance included. */
+    findNodesByDensity(density: Density): UINode[];
+    /** Views that present anything in this role — "which views use this theme role?". */
+    getViewsUsingRole(role: PresentationRole): ViewNode[];
+    /** Actions a view presents as primary. */
+    getPrimaryActions(viewId: NodeId): ActionDef[];
+    /** Actions a view presents as destructive, whether declared or inferred. */
+    getDestructiveActions(viewId: NodeId): ActionDef[];
+    /** Forms that offer no primary action, which is a hierarchy an agent can repair. */
+    getFormsWithoutPrimaryAction(): FormNode[];
+    /** Nodes carrying renderer-specific presentation that cannot be analyzed. */
+    getOpaquePresentationNodes(): UINode[];
+    /** UI nodes that present failures from this action. */
+    getDiagnosticPresentations(actionId: NodeId): DiagnosticNode[];
+    /**
+     * Actions that can refuse but whose refusal no UI node presents.
+     *
+     * An action counts as able to refuse if it declares a guard, a precondition or a
+     * postcondition. Only actions a control actually invokes are reported, since an action
+     * nothing invokes has no refusal to explain.
+     */
+    getActionsWithoutDiagnosticPresentation(): ActionDef[];
+    /** States marked as ephemeral presentation state rather than domain facts. */
+    getEphemeralStates(): StateDef[];
+    /**
+     * Presentation and UX findings, optionally narrowed to one view. These are the answers
+     * to "which views contain presentation warnings?".
+     */
+    getPresentationWarnings(viewId?: NodeId): ValidationIssue[];
+    /** A form described as UX: sections, controls, action groups and hierarchy. */
+    getFormStructure(formId: NodeId): FormStructure;
+    protected presentationMap(): Record<NodeId, ResolvedPresentation>;
+    protected uiNodes(): UINode[];
+    /**
+     * UI nodes beneath this one. `primaryPathOnly` restricts the walk to the arrangement that
+     * appears when every collection has members and every condition holds, which is what
+     * "structure that is on screen together" means.
+     */
+    protected descendants(id: NodeId, options?: {
+        primaryPathOnly?: boolean;
+    }): UINode[];
+    protected descendantIds(id: NodeId): NodeId[];
+    private actionsWithUxRole;
+}
+//# sourceMappingURL=presentation-queries.d.ts.map

package/dist/presentation-queries.js

@@ -0,0 +1,302 @@
+import { isUINode, primaryChildIds, resolvePresentationMap, uiChildIds, validateGraph, } from '@cynodia/axiom-core';
+import { GraphQueries } from './queries.js';
+/** Diagnostic codes produced by the presentation layer. */
+const PRESENTATION_CODES = [
+    'UNKNOWN_PRESENTATION_TOKEN',
+    'PRESENTATION_SEMANTIC_CONFLICT',
+    'MULTIPLE_PRIMARY_ACTIONS',
+    'FORM_WITHOUT_PRIMARY_ACTION',
+    'DESTRUCTIVE_ACTION_PRESENTED_AS_SUCCESS',
+    'DESTRUCTIVE_ACTION_UNMARKED',
+    'EXCESSIVE_HORIZONTAL_ACTIONS',
+    'EMPTY_STATE_WITHOUT_RECOVERY_ACTION',
+    'RIGID_HORIZONTAL_LAYOUT',
+    'CONFLICTING_SIZING',
+    'INTERACTIVE_ELEMENT_MISSING_LABEL',
+    'FORM_INPUT_MISSING_LABEL',
+    'INVALID_HEADING_STRUCTURE',
+    'OPAQUE_PRESENTATION',
+];
+/**
+ * Presentation and UX queries, §46 and §47.
+ *
+ * These are the questions that cannot be answered from a stylesheet: which control is the
+ * primary action, which regions are grouped and why, what happens on a narrow display,
+ * where the presentation contradicts the application's own semantics. They are answerable
+ * here only because UX intent is structured data.
+ *
+ * Resolution is recomputed per call rather than cached: a transaction mutates the graph
+ * underneath these queries, and a stale presentation answer would be worse than a slow one.
+ */
+export class PresentationQueries extends GraphQueries {
+    /** The application's visual identity, completed against the default theme. */
+    getTheme() {
+        return this.graph.theme;
+    }
+    /** Exactly what a node declares, before defaults, inheritance or inference. */
+    getPresentation(nodeId) {
+        const node = this.graph.getNode(nodeId);
+        return node && isUINode(node) ? node.presentation : undefined;
+    }
+    /** Presentation with every question answered, as a renderer receives it. */
+    resolvePresentation(nodeId) {
+        return this.presentationMap()[nodeId];
+    }
+    /** Resolved presentation for every UI node in the application. */
+    resolveAllPresentation() {
+        return this.presentationMap();
+    }
+    getUxRole(nodeId) {
+        return this.resolvePresentation(nodeId)?.uxRole;
+    }
+    /** What changes on a compact, regular or wide display. */
+    getResponsiveBehavior(nodeId) {
+        return this.resolvePresentation(nodeId)?.responsive ?? {};
+    }
+    /** Every UI node whose resolved UX role is this one. */
+    findNodesByUxRole(uxRole) {
+        const resolved = this.presentationMap();
+        return this.uiNodes().filter((node) => resolved[node.id]?.uxRole === uxRole);
+    }
+    /** Every UI node presented in this role, however the role was decided. */
+    findNodesByRole(role) {
+        const resolved = this.presentationMap();
+        return this.uiNodes().filter((node) => resolved[node.id]?.role === role);
+    }
+    /** Which nodes end up at a given density, inheritance included. */
+    findNodesByDensity(density) {
+        const resolved = this.presentationMap();
+        return this.uiNodes().filter((node) => resolved[node.id]?.density === density);
+    }
+    /** Views that present anything in this role — "which views use this theme role?". */
+    getViewsUsingRole(role) {
+        const views = new Map();
+        for (const node of this.findNodesByRole(role)) {
+            for (const view of this.enclosingViews(node.id)) {
+                views.set(view.id, view);
+            }
+        }
+        return [...views.values()];
+    }
+    /** Actions a view presents as primary. */
+    getPrimaryActions(viewId) {
+        return this.actionsWithUxRole(viewId, 'primary-action');
+    }
+    /** Actions a view presents as destructive, whether declared or inferred. */
+    getDestructiveActions(viewId) {
+        return this.actionsWithUxRole(viewId, 'destructive-action');
+    }
+    /** Forms that offer no primary action, which is a hierarchy an agent can repair. */
+    getFormsWithoutPrimaryAction() {
+        return this.graph
+            .getNodesByKind('form')
+            .filter((form) => this.getFormStructure(form.id).primaryActionIds.length === 0);
+    }
+    /** Nodes carrying renderer-specific presentation that cannot be analyzed. */
+    getOpaquePresentationNodes() {
+        const resolved = this.presentationMap();
+        return this.uiNodes().filter((node) => resolved[node.id]?.opaque === true);
+    }
+    /** UI nodes that present failures from this action. */
+    getDiagnosticPresentations(actionId) {
+        return this.uiNodes().filter((node) => node.kind === 'diagnostic' && node.actionId === actionId);
+    }
+    /**
+     * Actions that can refuse but whose refusal no UI node presents.
+     *
+     * An action counts as able to refuse if it declares a guard, a precondition or a
+     * postcondition. Only actions a control actually invokes are reported, since an action
+     * nothing invokes has no refusal to explain.
+     */
+    getActionsWithoutDiagnosticPresentation() {
+        const invoked = new Set();
+        for (const node of this.uiNodes()) {
+            if (node.kind === 'button') {
+                invoked.add(node.actionId);
+            }
+            if (node.kind === 'form' && node.submitActionId) {
+                invoked.add(node.submitActionId);
+            }
+        }
+        const presented = new Set(this.uiNodes()
+            .filter((node) => node.kind === 'diagnostic')
+            .map((node) => node.actionId));
+        return this.graph.getNodesByKind('action').filter((action) => {
+            if (!invoked.has(action.id) || presented.has(action.id)) {
+                return false;
+            }
+            const canRefuse = (action.guards ?? []).length > 0 ||
+                (action.preconditions ?? []).length > 0 ||
+                (action.postconditions ?? []).length > 0;
+            return canRefuse;
+        });
+    }
+    /** States marked as ephemeral presentation state rather than domain facts. */
+    getEphemeralStates() {
+        return this.graph.getNodesByKind('state').filter((state) => state.ephemeral === true);
+    }
+    /**
+     * Presentation and UX findings, optionally narrowed to one view. These are the answers
+     * to "which views contain presentation warnings?".
+     */
+    getPresentationWarnings(viewId) {
+        const result = validateGraph(this.graph);
+        const findings = [...result.errors, ...result.warnings].filter((finding) => PRESENTATION_CODES.includes(finding.code));
+        if (!viewId) {
+            return findings;
+        }
+        const scope = new Set([viewId, ...this.descendantIds(viewId)]);
+        return findings.filter((finding) => finding.nodeId !== undefined && scope.has(finding.nodeId));
+    }
+    /** A form described as UX: sections, controls, action groups and hierarchy. */
+    getFormStructure(formId) {
+        const form = this.graph.getNode(formId);
+        if (!form || form.kind !== 'form') {
+            throw new Error(`${formId} is not a form`);
+        }
+        const resolved = this.presentationMap();
+        const sections = [];
+        const sectionInputs = new Set();
+        const actionGroupIds = [];
+        const primaryActionIds = new Set();
+        const destructiveActionIds = new Set();
+        const requiredInputIds = [];
+        const allInputIds = [];
+        const submitButton = form.submitButtonId
+            ? this.graph.getNode(form.submitButtonId)
+            : undefined;
+        const submitActionId = form.submitActionId ??
+            (submitButton && isUINode(submitButton) && submitButton.kind === 'button'
+                ? submitButton.actionId
+                : undefined);
+        if (submitActionId) {
+            primaryActionIds.add(submitActionId);
+        }
+        for (const node of this.descendants(formId, { primaryPathOnly: true })) {
+            const view = resolved[node.id];
+            if (view?.uxRole === 'form-section') {
+                const inner = this.descendants(node.id, { primaryPathOnly: true });
+                const inputIds = inner.filter((child) => child.kind === 'input').map((child) => child.id);
+                inputIds.forEach((id) => sectionInputs.add(id));
+                sections.push({
+                    nodeId: node.id,
+                    ...(node.name ? { name: node.name } : {}),
+                    headings: inner
+                        .filter((child) => child.kind === 'text')
+                        .filter((child) => isHeading(resolved[child.id]))
+                        .map((child) => (typeof child.value === 'string' ? child.value : '')),
+                    inputIds,
+                });
+            }
+            if (view?.uxRole === 'action-group' || view?.uxRole === 'toolbar') {
+                actionGroupIds.push(node.id);
+            }
+            if (node.kind === 'input') {
+                allInputIds.push(node.id);
+                // Required is a fact about the model, not a presentation decision.
+                const addressed = requiredFieldOf(this, node);
+                if (addressed) {
+                    requiredInputIds.push(node.id);
+                }
+            }
+            if (node.kind === 'button') {
+                if (view?.uxRole === 'primary-action') {
+                    primaryActionIds.add(node.actionId);
+                }
+                if (view?.uxRole === 'destructive-action') {
+                    destructiveActionIds.add(node.actionId);
+                }
+            }
+        }
+        return {
+            formId,
+            density: resolved[formId]?.density ?? 'comfortable',
+            ...(submitActionId ? { submitActionId } : {}),
+            ...(form.submitButtonId ? { submitButtonId: form.submitButtonId } : {}),
+            sections,
+            ungroupedInputIds: allInputIds.filter((id) => !sectionInputs.has(id)),
+            actionGroupIds,
+            primaryActionIds: [...primaryActionIds],
+            destructiveActionIds: [...destructiveActionIds],
+            requiredInputIds,
+        };
+    }
+    // ---------------------------------------------------------------- internals
+    presentationMap() {
+        return resolvePresentationMap(this.graph.listNodes(), this.graph.theme);
+    }
+    uiNodes() {
+        return this.graph.listNodes().filter((node) => isUINode(node));
+    }
+    /**
+     * UI nodes beneath this one. `primaryPathOnly` restricts the walk to the arrangement that
+     * appears when every collection has members and every condition holds, which is what
+     * "structure that is on screen together" means.
+     */
+    descendants(id, options = {}) {
+        const children = options.primaryPathOnly ? primaryChildIds : uiChildIds;
+        const found = [];
+        const seen = new Set([id]);
+        const visit = (current) => {
+            const node = this.graph.getNode(current);
+            if (!node || !isUINode(node)) {
+                return;
+            }
+            for (const childId of children(node)) {
+                if (seen.has(childId)) {
+                    continue;
+                }
+                seen.add(childId);
+                const child = this.graph.getNode(childId);
+                if (child && isUINode(child)) {
+                    found.push(child);
+                    visit(childId);
+                }
+            }
+        };
+        visit(id);
+        return found;
+    }
+    descendantIds(id) {
+        return this.descendants(id).map((node) => node.id);
+    }
+    actionsWithUxRole(viewId, uxRole) {
+        const resolved = this.presentationMap();
+        const found = new Map();
+        const candidates = [this.graph.getNode(viewId), ...this.descendants(viewId)];
+        for (const node of candidates) {
+            if (!node || !isUINode(node) || node.kind !== 'button') {
+                continue;
+            }
+            if (resolved[node.id]?.uxRole !== uxRole) {
+                continue;
+            }
+            const action = this.graph.getNode(node.actionId);
+            if (action?.kind === 'action') {
+                found.set(action.id, action);
+            }
+        }
+        // A form's own submit is a primary action even without a button node of its own.
+        if (uxRole === 'primary-action') {
+            for (const node of candidates) {
+                if (node && isUINode(node) && node.kind === 'form' && node.submitActionId) {
+                    const action = this.graph.getNode(node.submitActionId);
+                    if (action?.kind === 'action') {
+                        found.set(action.id, action);
+                    }
+                }
+            }
+        }
+        return [...found.values()];
+    }
+}
+function isHeading(resolved) {
+    const role = resolved?.textRole;
+    return role === 'heading' || role === 'title' || role === 'display';
+}
+/** Whether the field an input addresses is declared required. */
+function requiredFieldOf(queries, node) {
+    const location = node.binding.location;
+    const fieldId = location.kind === 'field' ? location.fieldId : undefined;
+    return fieldId ? queries.getField(fieldId)?.field.required === true : false;
+}

package/dist/transaction.d.ts

@@ -1,6 +1,6 @@
 import { ApplicationGraph } from '@cynodia/axiom-core';
-import type { ActionDef, AnyNode, ButtonNode, ConditionalNode, ConstraintDef, ContainerNode, EdgeId, EdgeKind, Expression, FieldDef, FieldDisplayNode, FieldId, FormNode, InputNode, Location, NodeId, RepeatNode, RouteDef, StateDef, TextNode, UINode, ValidationResult, ViewNode } from '@cynodia/axiom-core';
-import { GraphQueries } from './queries.js';
+import type { ActionDef, AnyNode, ButtonNode, ConditionalNode, ConstraintDef, ContainerNode, Density, DeviceClass, EdgeId, EdgeKind, Expression, FieldDef, FieldDisplayNode, FieldId, FormNode, InputNode, Location, NodeId, Presentation, RepeatNode, ResponsiveOverride, RouteDef, StateDef, TextNode, ThemeInput, UINode, UxRole, ValidationResult, ValueFormat, ViewNode } from '@cynodia/axiom-core';
+import { PresentationQueries } from './presentation-queries.js';
 import type { ChangeSet, GraphChange } from './changes.js';
 export declare class TransactionError extends Error {
     readonly result?: ValidationResult;
@@ -13,7 +13,7 @@ type UIInput<T extends UINode> = Omit<T, 'id' | 'kind'> & {
  * A staged set of graph transformations. Every change is applied to a private copy, so
  * the graph an agent (or a runtime) can observe is unchanged until `commit()` succeeds.
  */
-export declare class Transaction extends GraphQueries {
+export declare class Transaction extends PresentationQueries {
     private readonly target;
     private readonly onCommit;
     private readonly operations;
@@ -81,6 +81,28 @@ export declare class Transaction extends GraphQueries {
      * field added to the model is also populated by the actions that create records.
      */
     addFieldToConstructors(entityId: NodeId, fieldId: FieldId, value: Expression): NodeId[];
+    /**
+     * Replaces a node's presentation intent outright.
+     *
+     * "Make this form more compact" is one of these calls, not seventeen edited style
+     * declarations — and because the result is still semantic data, the next agent can read
+     * back what was intended rather than infer it from CSS.
+     */
+    setPresentation(nodeId: NodeId, presentation: Presentation | undefined): void;
+    /** Merges presentation intent, leaving whatever the node already said in place. */
+    mergePresentation(nodeId: NodeId, patch: Presentation): void;
+    setUxRole(nodeId: NodeId, uxRole: UxRole | undefined): void;
+    setDensity(nodeId: NodeId, density: Density): void;
+    setValueFormat(nodeId: NodeId, format: ValueFormat | undefined): void;
+    /** States what a node does on one class of display. */
+    setResponsiveBehavior(nodeId: NodeId, device: DeviceClass, override: ResponsiveOverride | undefined): void;
+    /**
+     * Replaces the theme. An application-wide visual change belongs here rather than in the
+     * UI nodes: a theme cannot alter an action, a constraint, a location or a route.
+     */
+    setTheme(theme: ThemeInput | undefined): void;
+    /** Changes part of the theme, keeping the rest of what the application declared. */
+    mergeTheme(patch: ThemeInput): void;
     appendChild(parentId: NodeId, childId: NodeId, position?: number): void;
     addNode<T extends AnyNode>(node: T): NodeId;
     updateNode(node: AnyNode): void;
@@ -97,6 +119,7 @@ export declare class Transaction extends GraphQueries {
     rollback(): void;
     private assertOpen;
     private addUiNode;
+    private requireUiNode;
     private requireNode;
 }
 export {};

package/dist/transaction.js

@@ -1,5 +1,5 @@
-import { ApplicationGraph, createFieldId, createNodeId, randomHex, synchronizeEdges, validateGraph, } from '@cynodia/axiom-core';
-import { GraphQueries } from './queries.js';
+import { ApplicationGraph, createFieldId, createNodeId, isUINode, randomHex, synchronizeEdges, validateGraph, } from '@cynodia/axiom-core';
+import { PresentationQueries } from './presentation-queries.js';
 export class TransactionError extends Error {
     result;
     constructor(message, result) {
@@ -12,7 +12,7 @@ export class TransactionError extends Error {
  * A staged set of graph transformations. Every change is applied to a private copy, so
  * the graph an agent (or a runtime) can observe is unchanged until `commit()` succeeds.
  */
-export class Transaction extends GraphQueries {
+export class Transaction extends PresentationQueries {
     target;
     onCommit;
     operations = [];
@@ -180,6 +180,70 @@ export class Transaction extends GraphQueries {
         }
         return updated;
     }
+    // ------------------------------------------------------- presentation and theme
+    /**
+     * Replaces a node's presentation intent outright.
+     *
+     * "Make this form more compact" is one of these calls, not seventeen edited style
+     * declarations — and because the result is still semantic data, the next agent can read
+     * back what was intended rather than infer it from CSS.
+     */
+    setPresentation(nodeId, presentation) {
+        const node = this.requireUiNode(nodeId);
+        if (presentation === undefined) {
+            delete node.presentation;
+        }
+        else {
+            node.presentation = structuredClone(presentation);
+        }
+        this.updateNode(node);
+    }
+    /** Merges presentation intent, leaving whatever the node already said in place. */
+    mergePresentation(nodeId, patch) {
+        const node = this.requireUiNode(nodeId);
+        node.presentation = { ...(node.presentation ?? {}), ...structuredClone(patch) };
+        this.updateNode(node);
+    }
+    setUxRole(nodeId, uxRole) {
+        this.mergePresentation(nodeId, { uxRole });
+    }
+    setDensity(nodeId, density) {
+        this.mergePresentation(nodeId, { density });
+    }
+    setValueFormat(nodeId, format) {
+        this.mergePresentation(nodeId, { format });
+    }
+    /** States what a node does on one class of display. */
+    setResponsiveBehavior(nodeId, device, override) {
+        const node = this.requireUiNode(nodeId);
+        const responsive = { ...(node.presentation?.responsive ?? {}) };
+        if (override === undefined) {
+            delete responsive[device];
+        }
+        else {
+            responsive[device] = structuredClone(override);
+        }
+        node.presentation = { ...(node.presentation ?? {}), responsive };
+        this.updateNode(node);
+    }
+    /**
+     * Replaces the theme. An application-wide visual change belongs here rather than in the
+     * UI nodes: a theme cannot alter an action, a constraint, a location or a route.
+     */
+    setTheme(theme) {
+        const before = this.graph.declaredTheme;
+        this.graph.setTheme(theme);
+        this.operations.push({
+            kind: 'set-theme',
+            ...(before ? { before } : {}),
+            ...(theme ? { after: structuredClone(theme) } : {}),
+        });
+    }
+    /** Changes part of the theme, keeping the rest of what the application declared. */
+    mergeTheme(patch) {
+        const before = this.graph.declaredTheme ?? {};
+        this.setTheme(mergeThemeInput(before, patch));
+    }
     appendChild(parentId, childId, position) {
         const parent = this.graph.getNode(parentId);
         if (!parent || !('children' in parent) || !Array.isArray(parent.children)) {
@@ -280,6 +344,13 @@ export class Transaction extends GraphQueries {
         const id = node.id ?? createNodeId(node.kind.replace('-', '_'));
         return this.addNode({ ...node, id });
     }
+    requireUiNode(id) {
+        const node = this.graph.getNode(id);
+        if (!node || !isUINode(node)) {
+            throw new TransactionError(`${id} is not a UI node`);
+        }
+        return node;
+    }
     requireNode(id, kind) {
         const node = this.graph.getNode(id);
         if (!node || node.kind !== kind) {
@@ -288,3 +359,20 @@ export class Transaction extends GraphQueries {
         return node;
     }
 }
+/** Deep merge of two partial themes, so a patch never has to restate whole tables. */
+function mergeThemeInput(base, patch) {
+    const isPlain = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+    const merge = (left, right) => {
+        if (!isPlain(right)) {
+            return right === undefined ? left : right;
+        }
+        const result = isPlain(left) ? { ...left } : {};
+        for (const [key, value] of Object.entries(right)) {
+            if (value !== undefined) {
+                result[key] = merge(result[key], value);
+            }
+        }
+        return result;
+    };
+    return merge(structuredClone(base), structuredClone(patch));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-agent-api",
-  "version": "0.4.1-alpha.1",
+  "version": "0.5.2-alpha.1",
   "description": "Semantic queries and transactional graph transformations for AI agents.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -31,7 +31,7 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.4.1-alpha.1"
+    "@cynodia/axiom-core": "0.5.2-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json tsconfig.test.json",