@cynodia/axiom-ui 0.7.0-alpha.1

package/dist/expand.js

@@ -0,0 +1,227 @@
+import { stripAuthoringMetadata, withAuthoringMetadata } from '@cynodia/axiom-core';
+import { PROVENANCE_KEY, TOOLKIT_NAME, TOOLKIT_VERSION, partId, provenanceOf } from './pattern.js';
+export class PatternExpansionError extends Error {
+    findings;
+    constructor(findings) {
+        super(`The pattern declaration was rejected before expansion:\n${findings
+            .map((finding) => `  [${finding.code}] ${finding.path}: ${finding.message}`)
+            .join('\n')}`);
+        this.findings = findings;
+        this.name = 'PatternExpansionError';
+    }
+}
+/** Expansions are recorded per graph, outside it: an expansion record is not application data. */
+const records = new WeakMap();
+export function createToolkit(definitions) {
+    const patterns = new Map(definitions.map((definition) => [definition.name, definition]));
+    function expandInto(graph, declaration, model, ownership, parent, ancestry) {
+        const definition = patterns.get(declaration.pattern);
+        if (!definition) {
+            throw new PatternExpansionError([
+                {
+                    code: 'UNKNOWN_PATTERN',
+                    message: `No pattern named "${declaration.pattern}". Available: ${[...patterns.keys()].join(', ')}.`,
+                    severity: 'error',
+                    path: declaration.instance,
+                },
+            ]);
+        }
+        // Checked against the graph before a single node is created, so a mistake is reported
+        // against the declaration the author wrote rather than against generated output.
+        const findings = definition.check?.(declaration, { graph, instance: declaration.instance }) ?? [];
+        if (findings.some((finding) => finding.severity === 'error')) {
+            throw new PatternExpansionError(findings);
+        }
+        const record = {
+            instance: declaration.instance,
+            pattern: declaration.pattern,
+            declaration,
+            ownership,
+            patternVersion: definition.version ?? TOOLKIT_VERSION,
+            rootId: partId(declaration.instance, 'root'),
+            nodeIds: [],
+            generated: {},
+            explanations: [],
+            findings,
+            ...(parent ? { parent } : {}),
+        };
+        const context = {
+            graph,
+            instance: declaration.instance,
+            id: (part, index) => partId(declaration.instance, part, index),
+            add(node, part) {
+                const provenance = {
+                    toolkit: TOOLKIT_NAME,
+                    pattern: declaration.pattern,
+                    patternVersion: record.patternVersion,
+                    instance: declaration.instance,
+                    part,
+                    ownership,
+                    ...(parent ? { parent } : {}),
+                    ...(ancestry.length > 0 ? { ancestry: [...ancestry] } : {}),
+                };
+                const stamped = model === 'macro' ? node : withAuthoringMetadata(node, { [PROVENANCE_KEY]: provenance });
+                graph.addNode(stamped);
+                record.nodeIds.push(node.id);
+                // The node as generated, without provenance, is the baseline drift compares against.
+                record.generated[String(node.id)] = stripAuthoringMetadata(node);
+                return node.id;
+            },
+            explain: (message) => record.explanations.push(message),
+            child: (nested) => expandInto(graph, nested, model, ownership, declaration.instance, [...ancestry, declaration.instance]),
+            slot(name) {
+                const content = declaration[name];
+                if (content === undefined) {
+                    return [];
+                }
+                const items = Array.isArray(content) ? content : [content];
+                return items.map((item) => typeof item === 'string'
+                    ? item
+                    : expandInto(graph, item, model, ownership, declaration.instance, [...ancestry, declaration.instance]));
+            },
+        };
+        record.rootId = definition.expand(declaration, context);
+        const existing = records.get(graph) ?? [];
+        existing.push(record);
+        records.set(graph, existing);
+        return record.rootId;
+    }
+    return {
+        patterns,
+        expand(graph, declaration, options = {}) {
+            return expandInto(graph, declaration, options.model ?? 'provenance', options.ownership ?? 'declaration', undefined, []);
+        },
+        expansions: (graph) => [...(records.get(graph) ?? [])],
+        inspect: (graph, instance) => (records.get(graph) ?? []).find((record) => record.instance === instance),
+    };
+}
+/**
+ * Which pattern instance owns a node, read from the graph alone.
+ *
+ * This is the Model B claim under test: an agent holding only the expanded graph — no
+ * toolkit, no expansion record, no build step — can still recover the grouping.
+ */
+export function nodesOfInstance(graph, instance) {
+    return graph
+        .listNodes()
+        .filter((node) => provenanceOf(node)?.instance === instance)
+        .map((node) => node.id);
+}
+export function instancesOfPattern(graph, pattern) {
+    const found = new Set();
+    for (const node of graph.listNodes()) {
+        const provenance = provenanceOf(node);
+        if (provenance?.pattern === pattern) {
+            found.add(provenance.instance);
+        }
+    }
+    return [...found];
+}
+/**
+ * Compares the graph against what expansion produced, property by property.
+ *
+ * Under `declaration` ownership this is the safety net: the declaration is the source of
+ * truth, so a hand-edited generated node will be silently overwritten on the next build
+ * unless something says so first. Under `graph` ownership drift is expected and this is
+ * merely a record of how far the graph has moved from its origin.
+ *
+ * It reports what changed rather than only that something did, because "your edit will be
+ * lost" is only actionable if it names the edit.
+ */
+export function detectDrift(graph, expansion) {
+    const drifts = [];
+    const report = (nodeId, property, expected, actual, message) => {
+        drifts.push({
+            code: 'TOOLKIT_EXPANSION_DRIFT',
+            instance: expansion.instance,
+            pattern: expansion.pattern,
+            nodeId,
+            property,
+            expected,
+            actual,
+            message,
+        });
+    };
+    for (const id of expansion.nodeIds) {
+        const current = graph.getNode(id);
+        const generated = expansion.generated[String(id)];
+        if (!current) {
+            report(id, 'removed', generated, undefined, `${String(id)} was generated by ${expansion.instance} and has been removed`);
+            continue;
+        }
+        if (!provenanceOf(current)) {
+            report(id, 'provenance-lost', expansion.instance, undefined, `${String(id)} no longer records which pattern generated it`);
+        }
+        const now = stripAuthoringMetadata(current);
+        const then = generated;
+        for (const key of new Set([...Object.keys(then), ...Object.keys(now)])) {
+            if (JSON.stringify(now[key]) !== JSON.stringify(then[key])) {
+                report(id, key, then[key], now[key], `${String(id)}.${key} differs from what ${expansion.pattern} generated`);
+            }
+        }
+    }
+    return drifts;
+}
+/**
+ * Hands ownership of a pattern's generated nodes to the graph.
+ *
+ * The alternative to accidental drift. After this the declaration is history: the nodes stay
+ * exactly as they are, edits to them are legitimate, and re-expanding the declaration would
+ * be a mistake rather than a refresh. Provenance is kept — it still answers "where did this
+ * come from" — but re-marked so nothing treats the declaration as authoritative again.
+ *
+ * There is no un-detach. Recovering a declaration from an expanded graph is a different
+ * problem and this prototype does not attempt it.
+ */
+export function materializePattern(graph, expansion) {
+    for (const id of expansion.nodeIds) {
+        const node = graph.getNode(id);
+        if (!node) {
+            continue;
+        }
+        const provenance = provenanceOf(node);
+        if (!provenance) {
+            continue;
+        }
+        graph.updateNode(withAuthoringMetadata(node, {
+            [PROVENANCE_KEY]: { ...provenance, ownership: 'graph' },
+        }));
+    }
+    expansion.ownership = 'graph';
+    return expansion;
+}
+export function diffPatternExpansion(expansion, target, graphForTarget) {
+    target.expand(graphForTarget, expansion.declaration, { model: 'provenance', ownership: 'declaration' });
+    const after = target.inspect(graphForTarget, expansion.instance);
+    const before = expansion.generated;
+    const now = after?.generated ?? {};
+    const added = Object.keys(now).filter((id) => !(id in before));
+    const removed = Object.keys(before).filter((id) => !(id in now));
+    const changed = [];
+    for (const id of Object.keys(before).filter((entry) => entry in now)) {
+        const from = before[id];
+        const to = now[id];
+        for (const key of new Set([...Object.keys(from), ...Object.keys(to)])) {
+            if (JSON.stringify(from[key]) !== JSON.stringify(to[key])) {
+                changed.push({ nodeId: id, property: key, from: from[key], to: to[key] });
+            }
+        }
+    }
+    return { added, removed, changed };
+}
+/**
+ * Strips every trace of the toolkit from an expanded graph.
+ *
+ * §37 requires that doing this changes nothing but toolkit-aware introspection, and §66
+ * requires the result still validate, compile, execute and render. A function that performs
+ * the removal is how both are tested rather than asserted.
+ */
+export function stripProvenance(graph) {
+    for (const node of graph.listNodes()) {
+        const stripped = stripAuthoringMetadata(node);
+        if (stripped !== node) {
+            graph.updateNode(stripped);
+        }
+    }
+    return graph;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export * from './pattern.js';
+export * from './inference.js';
+export * from './expand.js';
+export * from './catalog.js';
+export * from './queries.js';
+export { page } from './patterns/page.js';
+export { metricGrid } from './patterns/metric-grid.js';
+export { entityList, rowRef, rowField } from './patterns/entity-list.js';
+export { entityForm } from './patterns/entity-form.js';
+export { actionBar } from './patterns/action-bar.js';
+export { axiomUi } from './toolkit.js';
+export type { PageDeclaration } from './patterns/page.js';
+export type { MetricGridDeclaration, MetricDeclaration } from './patterns/metric-grid.js';
+export type { EntityListDeclaration } from './patterns/entity-list.js';
+export type { EntityFormDeclaration, EntityFormTarget } from './patterns/entity-form.js';
+export type { ActionBarDeclaration } from './patterns/action-bar.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,11 @@
+export * from './pattern.js';
+export * from './inference.js';
+export * from './expand.js';
+export * from './catalog.js';
+export * from './queries.js';
+export { page } from './patterns/page.js';
+export { metricGrid } from './patterns/metric-grid.js';
+export { entityList, rowRef, rowField } from './patterns/entity-list.js';
+export { entityForm } from './patterns/entity-form.js';
+export { actionBar } from './patterns/action-bar.js';
+export { axiomUi } from './toolkit.js';

package/dist/inference.d.ts

@@ -0,0 +1,55 @@
+import type { ActionDef, ApplicationGraph, EntityDef, FieldDef, FieldId, NodeId, StateDef, TypeRef, ValueFormat, ControlVariant } from '@cynodia/axiom-core';
+/**
+ * What the toolkit reads out of the graph instead of asking the author to restate it.
+ *
+ * The rule (§34): **infer what Axiom already knows; require only application-specific UX
+ * choices.** Everything here is a read of an existing declaration — an entity's identity
+ * field, a field's type, an action's `destructive` flag. Nothing here guesses from a *name*,
+ * because a heuristic over names is precisely the kind of hidden rule that makes an agent's
+ * output unpredictable.
+ */
+export declare function stateOf(graph: ApplicationGraph, id: NodeId): StateDef | undefined;
+export declare function entityOf(graph: ApplicationGraph, id: NodeId): EntityDef | undefined;
+export declare function actionOf(graph: ApplicationGraph, id: NodeId): ActionDef | undefined;
+/** The entity a collection state holds, if it holds one. */
+export declare function memberEntityId(valueType: TypeRef): NodeId | undefined;
+export declare function isCollection(valueType: TypeRef): boolean;
+export declare function fieldOf(entity: EntityDef, fieldId: FieldId): FieldDef | undefined;
+/** Unwraps `optional` so a nullable number is still a number for presentation purposes. */
+export declare function baseType(valueType: TypeRef): TypeRef;
+/**
+ * A value format from a declared type.
+ *
+ * Deliberately conservative: it never infers `currency` or `percentage`, because nothing in
+ * a `number` says which — that is an application-specific UX choice and stays explicit.
+ * Guessing from a field named `price` is exactly the hidden heuristic §35 warns about.
+ */
+export declare function formatFor(valueType: TypeRef): ValueFormat | undefined;
+/** A control from a declared type. Absent means "let the runtime decide", which it can. */
+export declare function controlFor(valueType: TypeRef): ControlVariant | undefined;
+/**
+ * A human label for a field.
+ *
+ * `name` is metadata authors already write, so the toolkit uses it and falls back to the id
+ * only when there is nothing else. It does **not** prettify an id into title case: a label
+ * invented from an identifier is a guess presented as a fact.
+ */
+export declare function labelFor(field: FieldDef): string | undefined;
+/** Fields worth showing in a list when the author names none: every field but the identity. */
+export declare function defaultListFields(entity: EntityDef): FieldId[];
+/**
+ * Fields worth editing when the author names none.
+ *
+ * A create form offers **every** field, identity included; an edit form omits the identity,
+ * because an instance's identity is what addresses it and is not a thing to retype.
+ *
+ * Phase 1 had one rule for both and chose "omit the identity", by analogy with the list. That
+ * was wrong for creation, and wrong in the dangerous direction: the form rendered, validated,
+ * and then refused every submission for a value the author could not see was missing. Which
+ * mode a form is in cannot be inferred from a draft state, so it is declared — and the
+ * default is the one whose mistake is visible.
+ */
+export declare function defaultFormFields(entity: EntityDef, mode?: 'create' | 'edit'): FieldId[];
+/** The UX role an action's own semantics imply. */
+export declare function roleForAction(action: ActionDef, isPrimary: boolean): 'primary-action' | 'secondary-action' | 'destructive-action';
+//# sourceMappingURL=inference.d.ts.map

package/dist/inference.js

@@ -0,0 +1,113 @@
+/**
+ * What the toolkit reads out of the graph instead of asking the author to restate it.
+ *
+ * The rule (§34): **infer what Axiom already knows; require only application-specific UX
+ * choices.** Everything here is a read of an existing declaration — an entity's identity
+ * field, a field's type, an action's `destructive` flag. Nothing here guesses from a *name*,
+ * because a heuristic over names is precisely the kind of hidden rule that makes an agent's
+ * output unpredictable.
+ */
+export function stateOf(graph, id) {
+    const node = graph.getNode(id);
+    return node?.kind === 'state' ? node : undefined;
+}
+export function entityOf(graph, id) {
+    const node = graph.getNode(id);
+    return node?.kind === 'entity' ? node : undefined;
+}
+export function actionOf(graph, id) {
+    const node = graph.getNode(id);
+    return node?.kind === 'action' ? node : undefined;
+}
+/** The entity a collection state holds, if it holds one. */
+export function memberEntityId(valueType) {
+    if (valueType.kind === 'collection') {
+        return memberEntityId(valueType.itemType) ?? undefined;
+    }
+    if (valueType.kind === 'optional') {
+        return memberEntityId(valueType.valueType);
+    }
+    return valueType.kind === 'entity' ? valueType.entityId : undefined;
+}
+export function isCollection(valueType) {
+    return valueType.kind === 'collection' || (valueType.kind === 'optional' && isCollection(valueType.valueType));
+}
+export function fieldOf(entity, fieldId) {
+    return entity.fields.find((field) => field.id === fieldId);
+}
+/** Unwraps `optional` so a nullable number is still a number for presentation purposes. */
+export function baseType(valueType) {
+    return valueType.kind === 'optional' ? baseType(valueType.valueType) : valueType;
+}
+/**
+ * A value format from a declared type.
+ *
+ * Deliberately conservative: it never infers `currency` or `percentage`, because nothing in
+ * a `number` says which — that is an application-specific UX choice and stays explicit.
+ * Guessing from a field named `price` is exactly the hidden heuristic §35 warns about.
+ */
+export function formatFor(valueType) {
+    const base = baseType(valueType);
+    if (base.kind !== 'primitive') {
+        return undefined;
+    }
+    switch (base.primitive) {
+        case 'number':
+            return { kind: 'number' };
+        case 'boolean':
+            return { kind: 'boolean' };
+        case 'date':
+            return { kind: 'date' };
+        case 'datetime':
+            return { kind: 'datetime' };
+        default:
+            return undefined;
+    }
+}
+/** A control from a declared type. Absent means "let the runtime decide", which it can. */
+export function controlFor(valueType) {
+    const base = baseType(valueType);
+    if (base.kind === 'enum') {
+        return 'select';
+    }
+    if (base.kind !== 'primitive') {
+        return undefined;
+    }
+    return base.primitive === 'boolean' ? 'checkbox' : base.primitive === 'number' ? 'stepper' : undefined;
+}
+/**
+ * A human label for a field.
+ *
+ * `name` is metadata authors already write, so the toolkit uses it and falls back to the id
+ * only when there is nothing else. It does **not** prettify an id into title case: a label
+ * invented from an identifier is a guess presented as a fact.
+ */
+export function labelFor(field) {
+    return field.name;
+}
+/** Fields worth showing in a list when the author names none: every field but the identity. */
+export function defaultListFields(entity) {
+    return entity.fields.filter((field) => field.id !== entity.identityFieldId).map((field) => field.id);
+}
+/**
+ * Fields worth editing when the author names none.
+ *
+ * A create form offers **every** field, identity included; an edit form omits the identity,
+ * because an instance's identity is what addresses it and is not a thing to retype.
+ *
+ * Phase 1 had one rule for both and chose "omit the identity", by analogy with the list. That
+ * was wrong for creation, and wrong in the dangerous direction: the form rendered, validated,
+ * and then refused every submission for a value the author could not see was missing. Which
+ * mode a form is in cannot be inferred from a draft state, so it is declared — and the
+ * default is the one whose mistake is visible.
+ */
+export function defaultFormFields(entity, mode = 'create') {
+    return mode === 'edit' ? defaultListFields(entity) : entity.fields.map((field) => field.id);
+}
+/** The UX role an action's own semantics imply. */
+export function roleForAction(action, isPrimary) {
+    if (action.destructive) {
+        return 'destructive-action';
+    }
+    return isPrimary ? 'primary-action' : 'secondary-action';
+}

package/dist/pattern.d.ts

@@ -0,0 +1,192 @@
+import type { ApplicationGraph, Expression, NodeId, Presentation, UINode } from '@cynodia/axiom-core';
+/**
+ * The toolkit's contract with a pattern.
+ *
+ * A pattern is **not** a component. It has no runtime existence, renders nothing, and owns
+ * no state. It is a function from a declaration to canonical Axiom UI nodes, plus enough
+ * machine-readable description for an agent to use it without reading its implementation.
+ *
+ * The split matters: `inputs`, `slots` and `purpose` are **data** and are queryable through
+ * the catalog; `expand` is authoring-time TypeScript and never reaches a graph, an IR or a
+ * runtime. That is the hybrid answer to "are pattern definitions data or code" — the part an
+ * agent must discover is data, the part that only runs during authoring is code.
+ */
+/**
+ * User-visible text a pattern places in the graph.
+ *
+ * The rule 0.7 adopts (spec7 §29): **a pattern input carrying user-visible value text takes
+ * `string | Expression`** unless there is a concrete semantic reason it cannot. Phase 2 found
+ * `PageDeclaration.title: string` produced a detail page titled "Edit product" rather than
+ * the product's name — and the restriction was the pattern's, not Axiom's, because
+ * `TextNode.value` accepted an expression all along.
+ */
+export type PatternText = string | Expression;
+/**
+ * A node's `name` is metadata for people and resolves nothing, so it only makes sense when
+ * the text is literal. An expression has no name to give.
+ */
+export declare function nameOf(text: PatternText | undefined): string | undefined;
+/** How a pattern input is described to an agent that has never seen the pattern. */
+export interface PatternInput {
+    /**
+     * `state` — a state id whose value the pattern reads.
+     * `entity` — an entity id.
+     * `field-list` — field ids of the entity in play.
+     * `action` / `action-list` — action ids the pattern binds controls to.
+     * `text` — a literal caption.
+     * `slot` — semantic UI content supplied by the caller (never markup).
+     * `nodes` — existing UI node ids to place.
+     * `flag` / `token` — a boolean or a presentation token.
+     */
+    kind: 'state' | 'entity' | 'field-list' | 'action' | 'action-list' | 'text' | 'slot' | 'nodes' | 'flag' | 'token';
+    required: boolean;
+    /** What the pattern does with it. One sentence, for an agent choosing inputs. */
+    purpose: string;
+    /** What the pattern derives when the input is absent, if anything. */
+    inferredWhenAbsent?: string;
+}
+export interface PatternDefinition<Declaration = Record<string, unknown>> {
+    name: string;
+    /**
+     * The pattern's own version, recorded in provenance.
+     *
+     * It is what makes a stored expansion reproducible and a toolkit upgrade diffable: without
+     * it, "expand this declaration again" means "expand it under whatever semantics are
+     * installed today", and an application changes shape on an unrelated `npm install`.
+     */
+    version?: string;
+    /** What UX concept this compresses. */
+    purpose: string;
+    inputs: Record<string, PatternInput>;
+    /** Slot names, in the order a renderer would encounter them. */
+    slots: readonly string[];
+    /** What the expansion is guaranteed to produce, as canonical node kinds. */
+    produces: readonly UINode['kind'][];
+    /**
+     * The shape of the generated tree, part by part.
+     *
+     * A blind agent using the prototype read the pattern implementations despite the docs
+     * saying it should not need to — because the catalogue said what a pattern *takes* and not
+     * what it *builds*, and composing against a generated tree requires knowing its shape.
+     * Each entry is a `part` name (the same one provenance records), the node kind, and where
+     * it sits. Generated ids are `ui_<instance>_<part>`, so this doubles as the id an author
+     * can address before expansion has happened.
+     */
+    expansion: readonly {
+        part: string;
+        kind: UINode['kind'];
+        role: string;
+    }[];
+    /**
+     * Checked before expansion, against the graph. Returning findings here is what makes a
+     * mistake point at `ProductList.fields[2]` rather than at a generated node id.
+     */
+    check?(declaration: Declaration, context: CheckContext): PatternFinding[];
+    expand(declaration: Declaration, context: ExpansionContext): NodeId;
+}
+export interface PatternFinding {
+    code: string;
+    message: string;
+    severity: 'error' | 'warning';
+    /** Where in the declaration, e.g. `ProductList.fields[2]`. */
+    path: string;
+}
+export interface CheckContext {
+    graph: ApplicationGraph;
+    /** The declaration's own instance id, for building a `path`. */
+    instance: string;
+}
+/**
+ * What a pattern is given while it expands.
+ *
+ * Everything a pattern adds to the graph goes through `add`, which is what makes provenance,
+ * deterministic identity and the expansion explanation possible without each pattern
+ * remembering to cooperate.
+ */
+export interface ExpansionContext extends CheckContext {
+    /** A deterministic id: same declaration and same part always yield the same id. */
+    id(part: string, index?: number): NodeId;
+    /** Adds a canonical UI node and returns its id. */
+    add<T extends UINode>(node: T, part: string): NodeId;
+    /** Records why the expansion chose something, for `inspectPattern`. */
+    explain(message: string): void;
+    /** Expands a nested pattern declaration and returns its root node id. */
+    child(declaration: PatternDeclaration): NodeId;
+    /** Slot content the caller supplied, already expanded to node ids. */
+    slot(name: string): NodeId[];
+}
+/**
+ * A pattern instance as the author writes it: **plain data**, no closures.
+ *
+ * Slots hold node ids or nested declarations — semantic content, never markup — which is
+ * what keeps a declaration serializable and analyzable.
+ */
+export interface PatternDeclaration {
+    pattern: string;
+    /** Stable, author-chosen, and the root of every generated id. */
+    instance: string;
+    [input: string]: unknown;
+}
+export type SlotContent = NodeId | PatternDeclaration;
+/** Which of the three researched architectures an expansion runs under. */
+export type ExpansionModel = 'macro' | 'provenance' | 'pattern-node';
+/**
+ * Provenance: how a node was authored, never how it executes.
+ *
+ * It lives under core's reserved **authoring metadata** key, which means the compiler strips
+ * it from every artifact by default — client IR, server IR, generated page — and a tool that
+ * wants it asks for it. Phase 1 put it in plain `metadata` and it shipped to the browser;
+ * that was the leak, and this is the fix. Nothing about the fix is toolkit-specific.
+ *
+ * Everything in it is a stable, serializable string. Nothing here is a source location, an
+ * AST pointer or anything else that changes when a file is reformatted.
+ */
+export interface ToolkitProvenance {
+    toolkit: string;
+    pattern: string;
+    /** The pattern's own version, so a stored expansion can be reproduced or diffed. */
+    patternVersion: string;
+    instance: string;
+    /** Which part of the pattern this node is — `row`, `field`, `empty-state`. */
+    part: string;
+    index?: number;
+    /** The enclosing pattern instance, for nested patterns. */
+    parent?: string;
+    /** The full chain from outermost to nearest, so an ancestor is reachable in one read. */
+    ancestry?: string[];
+    /** Who owns this node now. See `Ownership`. */
+    ownership: Ownership;
+}
+/**
+ * Who decides what a generated node contains.
+ *
+ * - `declaration` — the pattern declaration is the source of truth. The graph is a build artifact, re-expansion is authoritative, and an edit to a generated node is drift.
+ * - `graph` — the expanded graph is the source of truth. The declaration is history, provenance is informational, and edits are legitimate.
+ *
+ * The choice is explicit at every entry point, because leaving it implicit is what makes
+ * "may I edit this node?" unanswerable.
+ */
+export type Ownership = 'declaration' | 'graph';
+export declare const PROVENANCE_KEY = "toolkit";
+export declare const TOOLKIT_NAME = "@cynodia/axiom-ui";
+/**
+ * The semantics an expansion was produced under.
+ *
+ * Bumped whenever a pattern's expansion changes, which is what makes a stored expansion
+ * reproducible and an upgrade diffable: 0.7 changed three patterns — an edit mode, a label
+ * inferred from a state, a title that may be an expression — so an expansion recorded as
+ * `0.2.0` is not one this toolkit would produce. `diffPatternExpansion` is how an author sees
+ * the difference before adopting it.
+ */
+export declare const TOOLKIT_VERSION = "0.7.0";
+export declare function provenanceOf(node: {
+    metadata?: Record<string, unknown>;
+}): ToolkitProvenance | undefined;
+/** The reserved key provenance is nested under, for tests that assert placement. */
+export declare const AUTHORING_KEY = "axiomAuthoring";
+/** Ids are derived from the instance and the part, never from a counter. */
+export declare function partId(instance: string, part: string, index?: number): NodeId;
+export declare function definePattern<Declaration>(definition: PatternDefinition<Declaration>): PatternDefinition<Declaration>;
+/** Presentation helper: drops absent keys so a node carries no empty declaration. */
+export declare function presentation(value: Presentation): Presentation | undefined;
+//# sourceMappingURL=pattern.d.ts.map

package/dist/pattern.js

@@ -0,0 +1,39 @@
+import { AUTHORING_METADATA_KEY, authoringMetadata, nodeId } from '@cynodia/axiom-core';
+/**
+ * A node's `name` is metadata for people and resolves nothing, so it only makes sense when
+ * the text is literal. An expression has no name to give.
+ */
+export function nameOf(text) {
+    return typeof text === 'string' ? text : undefined;
+}
+export const PROVENANCE_KEY = 'toolkit';
+export const TOOLKIT_NAME = '@cynodia/axiom-ui';
+/**
+ * The semantics an expansion was produced under.
+ *
+ * Bumped whenever a pattern's expansion changes, which is what makes a stored expansion
+ * reproducible and an upgrade diffable: 0.7 changed three patterns — an edit mode, a label
+ * inferred from a state, a title that may be an expression — so an expansion recorded as
+ * `0.2.0` is not one this toolkit would produce. `diffPatternExpansion` is how an author sees
+ * the difference before adopting it.
+ */
+export const TOOLKIT_VERSION = '0.7.0';
+export function provenanceOf(node) {
+    const found = authoringMetadata(node)?.[PROVENANCE_KEY];
+    return found === undefined ? undefined : found;
+}
+/** The reserved key provenance is nested under, for tests that assert placement. */
+export const AUTHORING_KEY = AUTHORING_METADATA_KEY;
+/** Ids are derived from the instance and the part, never from a counter. */
+export function partId(instance, part, index) {
+    const suffix = index === undefined ? '' : `_${index}`;
+    return nodeId(`ui_${instance}_${part}${suffix}`.replace(/[^a-zA-Z0-9_]/g, '_'));
+}
+export function definePattern(definition) {
+    return definition;
+}
+/** Presentation helper: drops absent keys so a node carries no empty declaration. */
+export function presentation(value) {
+    const entries = Object.entries(value).filter(([, entry]) => entry !== undefined);
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}