@wirebench/engine 2.1.1

package/dist/xsd/builtins.d.ts

@@ -0,0 +1,36 @@
+import type { QName } from '../wsdl/qname.js';
+/** A built-in XSD (or SOAP-encoding) type known to the engine without a schema declaration. */
+export interface BuiltinType {
+    readonly name: QName;
+    /** The type this one derives from, for the derived built-ins. */
+    readonly base?: QName;
+    /** True for the 19 XSD primitive datatypes (plus the two ur-types, which have no base). */
+    readonly primitive: boolean;
+    /** True for `soapenc:Array`, the only complex built-in. */
+    readonly complex?: boolean;
+    /** Set on `soapenc:Array` so encoded-array handling can special-case it. */
+    readonly soapEncArray?: boolean;
+    /** For a `soapenc:*` alias: the XSD type it aliases. */
+    readonly aliasOf?: QName;
+    /**
+     * A type-appropriate example value, used only when a caller explicitly asks
+     * for realistic sample data. The default everywhere is {@link BuiltinType.placeholder}.
+     */
+    readonly sampleValue: string;
+    /** The placeholder emitted by default for every built-in. */
+    readonly placeholder: '?';
+}
+/** Every built-in type, keyed by Clark notation (`{ns}local`). */
+export declare const BUILTIN_TYPES: ReadonlyMap<string, BuiltinType>;
+/** The local names of every XSD 1.0 built-in type. */
+export declare const XSD_BUILTIN_NAMES: readonly string[];
+/**
+ * Attributes the SOAP 1.1 encoding namespace defines (`soapenc:arrayType` and
+ * friends). References to these never resolve against a user schema, so the
+ * schema set treats them as known rather than reporting `unresolved-ref`.
+ */
+export declare const SOAP_ENC_ATTRIBUTES: readonly string[];
+/** Looks up a built-in type by expanded name, or `undefined` when it is not one. */
+export declare function lookupBuiltin(name: QName): BuiltinType | undefined;
+/** True when `name` denotes a built-in XSD (or SOAP-encoding) type. */
+export declare function isBuiltinType(name: QName): boolean;

package/dist/xsd/builtins.js

@@ -0,0 +1,108 @@
+import { NS } from '../xml/namespaces.js';
+import { qnameToString } from '../wsdl/qname.js';
+/** `[localName, baseLocalName | undefined, sampleValue]` for each XSD 1.0 built-in. */
+const XSD_TABLE = [
+    // ur-types
+    ['anyType', undefined, 'string'],
+    ['anySimpleType', undefined, 'string'],
+    // primitives
+    ['string', undefined, 'string'],
+    ['boolean', undefined, 'true'],
+    ['decimal', undefined, '1.0'],
+    ['float', undefined, '1.0'],
+    ['double', undefined, '1.0'],
+    ['duration', undefined, 'P1D'],
+    ['dateTime', undefined, '2000-01-01T00:00:00'],
+    ['time', undefined, '00:00:00'],
+    ['date', undefined, '2000-01-01'],
+    ['gYearMonth', undefined, '2000-01'],
+    ['gYear', undefined, '2000'],
+    ['gMonthDay', undefined, '--01-01'],
+    ['gDay', undefined, '---01'],
+    ['gMonth', undefined, '--01'],
+    ['hexBinary', undefined, '61'],
+    ['base64Binary', undefined, 'YQ=='],
+    ['anyURI', undefined, 'http://example.com'],
+    ['QName', undefined, 'QName'],
+    ['NOTATION', undefined, 'NOTATION'],
+    // derived from string
+    ['normalizedString', 'string', 'string'],
+    ['token', 'normalizedString', 'string'],
+    ['language', 'token', 'en'],
+    ['NMTOKEN', 'token', 'token'],
+    ['NMTOKENS', 'NMTOKEN', 'token'],
+    ['Name', 'token', 'name'],
+    ['NCName', 'Name', 'name'],
+    ['ID', 'NCName', 'id'],
+    ['IDREF', 'NCName', 'id'],
+    ['IDREFS', 'IDREF', 'id'],
+    ['ENTITY', 'NCName', 'entity'],
+    ['ENTITIES', 'ENTITY', 'entity'],
+    // derived from decimal
+    ['integer', 'decimal', '1'],
+    ['nonPositiveInteger', 'integer', '-1'],
+    ['negativeInteger', 'nonPositiveInteger', '-1'],
+    ['long', 'integer', '1'],
+    ['int', 'long', '1'],
+    ['short', 'int', '1'],
+    ['byte', 'short', '1'],
+    ['nonNegativeInteger', 'integer', '1'],
+    ['unsignedLong', 'nonNegativeInteger', '1'],
+    ['unsignedInt', 'unsignedLong', '1'],
+    ['unsignedShort', 'unsignedInt', '1'],
+    ['unsignedByte', 'unsignedShort', '1'],
+    ['positiveInteger', 'nonNegativeInteger', '1'],
+];
+function buildTable() {
+    const map = new Map();
+    for (const [localName, base, sampleValue] of XSD_TABLE) {
+        const name = { namespaceUri: NS.XSD, localName };
+        map.set(qnameToString(name), {
+            name,
+            ...(base !== undefined ? { base: { namespaceUri: NS.XSD, localName: base } } : {}),
+            primitive: base === undefined,
+            sampleValue,
+            placeholder: '?',
+        });
+    }
+    // SOAP 1.1 encoding mirrors the XSD simple types one-for-one; treat each as an
+    // alias so `soapenc:int` behaves exactly like `xs:int` for generation purposes.
+    for (const [localName, , sampleValue] of XSD_TABLE) {
+        const name = { namespaceUri: NS.SOAP11_ENC, localName };
+        map.set(qnameToString(name), {
+            name,
+            aliasOf: { namespaceUri: NS.XSD, localName },
+            primitive: false,
+            sampleValue,
+            placeholder: '?',
+        });
+    }
+    const arrayName = { namespaceUri: NS.SOAP11_ENC, localName: 'Array' };
+    map.set(qnameToString(arrayName), {
+        name: arrayName,
+        primitive: false,
+        complex: true,
+        soapEncArray: true,
+        sampleValue: '',
+        placeholder: '?',
+    });
+    return map;
+}
+/** Every built-in type, keyed by Clark notation (`{ns}local`). */
+export const BUILTIN_TYPES = buildTable();
+/** The local names of every XSD 1.0 built-in type. */
+export const XSD_BUILTIN_NAMES = XSD_TABLE.map(([localName]) => localName);
+/**
+ * Attributes the SOAP 1.1 encoding namespace defines (`soapenc:arrayType` and
+ * friends). References to these never resolve against a user schema, so the
+ * schema set treats them as known rather than reporting `unresolved-ref`.
+ */
+export const SOAP_ENC_ATTRIBUTES = ['arrayType', 'offset', 'position', 'id', 'href', 'root'];
+/** Looks up a built-in type by expanded name, or `undefined` when it is not one. */
+export function lookupBuiltin(name) {
+    return BUILTIN_TYPES.get(qnameToString(name));
+}
+/** True when `name` denotes a built-in XSD (or SOAP-encoding) type. */
+export function isBuiltinType(name) {
+    return BUILTIN_TYPES.has(qnameToString(name));
+}

package/dist/xsd/check-references.d.ts

@@ -0,0 +1,25 @@
+import type { QName } from '../wsdl/qname.js';
+import type { AttributeDecl, AttributeGroup, ElementDecl, Group, SchemaProblem, TypeDefinition } from './model.js';
+/** The parts of a built `SchemaSet` the reference check reads. */
+export interface ReferenceCheckTarget {
+    readonly elements: ReadonlyMap<string, ElementDecl>;
+    readonly types: ReadonlyMap<string, TypeDefinition>;
+    readonly groups: ReadonlyMap<string, Group>;
+    readonly attributeGroups: ReadonlyMap<string, AttributeGroup>;
+    readonly attributes: ReadonlyMap<string, AttributeDecl>;
+    lookupElement(name: QName): ElementDecl | undefined;
+    lookupType(name: QName): TypeDefinition | undefined;
+    lookupGroup(name: QName): Group | undefined;
+    lookupAttributeGroup(name: QName): AttributeGroup | undefined;
+    lookupAttribute(name: QName): AttributeDecl | undefined;
+}
+/**
+ * Records an `unresolved-ref` problem for every dangling reference in `set`:
+ * type, element, group, attribute, attribute-group and substitution-group
+ * heads. References into the XSD and SOAP-encoding namespaces are satisfied by
+ * the built-in table, so they are never reported.
+ *
+ * Unresolved references are never fatal: the corresponding lookup simply
+ * returns `undefined`, and consumers decide how to degrade.
+ */
+export declare function checkReferences(set: ReferenceCheckTarget, problems: SchemaProblem[]): void;

package/dist/xsd/check-references.js

@@ -0,0 +1,145 @@
+import { NS } from '../xml/namespaces.js';
+import { qnameToString } from '../wsdl/qname.js';
+/** Namespaces whose references are satisfied by the built-in table rather than a schema. */
+function isExternallyKnown(name) {
+    return name.namespaceUri === NS.XSD || name.namespaceUri === NS.SOAP11_ENC;
+}
+/**
+ * Records an `unresolved-ref` problem for every dangling reference in `set`:
+ * type, element, group, attribute, attribute-group and substitution-group
+ * heads. References into the XSD and SOAP-encoding namespaces are satisfied by
+ * the built-in table, so they are never reported.
+ *
+ * Unresolved references are never fatal: the corresponding lookup simply
+ * returns `undefined`, and consumers decide how to degrade.
+ */
+export function checkReferences(set, problems) {
+    const report = (what, name, source) => {
+        problems.push({
+            code: 'unresolved-ref',
+            message: `Unresolved ${what} reference ${qnameToString(name)}`,
+            location: source.location,
+            ...(source.line !== undefined ? { line: source.line, column: source.column ?? 1 } : {}),
+        });
+    };
+    const checkType = (name, source) => {
+        if (name !== undefined && !isExternallyKnown(name) && set.lookupType(name) === undefined) {
+            report('type', name, source);
+        }
+    };
+    const checkSimple = (type, source) => {
+        checkType(type.base, source);
+        if (type.baseType !== undefined) {
+            checkSimple(type.baseType, source);
+        }
+        if (type.itemType !== undefined) {
+            if ('kind' in type.itemType) {
+                checkSimple(type.itemType, source);
+            }
+            else {
+                checkType(type.itemType, source);
+            }
+        }
+        for (const member of type.memberTypes ?? []) {
+            if ('kind' in member) {
+                checkSimple(member, source);
+            }
+            else {
+                checkType(member, source);
+            }
+        }
+    };
+    const checkAttributes = (uses, source) => {
+        for (const use of uses) {
+            if (use.kind === 'attribute') {
+                checkType(use.type, source);
+                if (use.anonymousType !== undefined) {
+                    checkSimple(use.anonymousType, source);
+                }
+            }
+            else if (use.kind === 'attributeRef') {
+                if (!isExternallyKnown(use.ref) && set.lookupAttribute(use.ref) === undefined) {
+                    report('attribute', use.ref, source);
+                }
+            }
+            else if (use.kind === 'attributeGroupRef') {
+                if (!isExternallyKnown(use.ref) && set.lookupAttributeGroup(use.ref) === undefined) {
+                    report('attribute group', use.ref, source);
+                }
+            }
+        }
+    };
+    const checkParticle = (particle, source) => {
+        switch (particle.kind) {
+            case 'localElement':
+                checkElement(particle.decl);
+                break;
+            case 'elementRef':
+                if (!isExternallyKnown(particle.ref) && set.lookupElement(particle.ref) === undefined) {
+                    report('element', particle.ref, source);
+                }
+                break;
+            case 'groupRef':
+                if (!isExternallyKnown(particle.ref) && set.lookupGroup(particle.ref) === undefined) {
+                    report('group', particle.ref, source);
+                }
+                break;
+            case 'sequence':
+            case 'choice':
+            case 'all':
+                for (const child of particle.particles) {
+                    checkParticle(child, source);
+                }
+                break;
+            default:
+                break;
+        }
+    };
+    const checkComplex = (type) => {
+        const content = type.content;
+        if (content.kind === 'complexContent' || content.kind === 'simpleContent') {
+            checkType(content.base, type.source);
+        }
+        if (content.kind === 'particle') {
+            checkParticle(content.particle, type.source);
+        }
+        else if (content.kind === 'complexContent' && content.particle !== undefined) {
+            checkParticle(content.particle, type.source);
+        }
+        checkAttributes(content.attributes, type.source);
+    };
+    const checkElement = (decl) => {
+        checkType(decl.type, decl.source);
+        if (decl.substitutionGroup !== undefined && set.lookupElement(decl.substitutionGroup) === undefined) {
+            report('substitution group head', decl.substitutionGroup, decl.source);
+        }
+        if (decl.anonymousType !== undefined) {
+            if (decl.anonymousType.kind === 'complexType') {
+                checkComplex(decl.anonymousType);
+            }
+            else {
+                checkSimple(decl.anonymousType, decl.source);
+            }
+        }
+    };
+    for (const decl of set.elements.values()) {
+        checkElement(decl);
+    }
+    for (const type of set.types.values()) {
+        if (type.kind === 'complexType') {
+            checkComplex(type);
+        }
+        else {
+            checkSimple(type, type.source);
+        }
+    }
+    for (const group of set.groups.values()) {
+        checkParticle(group.particle, group.source);
+    }
+    for (const group of set.attributeGroups.values()) {
+        checkAttributes(group.attributes, group.source);
+    }
+    for (const attribute of set.attributes.values()) {
+        checkAttributes([attribute], attribute.source);
+    }
+}

package/dist/xsd/form-edits.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Structural edits on a {@link FormNode} tree — everything the Form view cannot
+ * express as a plain text splice into an existing value.
+ *
+ * Each edit returns a *new* tree (nothing is mutated), which the caller then
+ * serialises with `applyForm` and splices back over the body element's range.
+ * Because the tree is rebuilt from the document before every edit, an edit can
+ * never operate on a stale shape.
+ */
+import type { FormNode } from './form-model.js';
+/** One structural change the Form view can ask for, addressed by node id. */
+export type FormEdit = 
+/** Make an omitted optional element (or attribute) exist, filled with placeholders. */
+{
+    readonly kind: 'insert-optional';
+    readonly nodeId: string;
+}
+/** Remove a present optional element (or attribute) again. */
+ | {
+    readonly kind: 'remove-optional';
+    readonly nodeId: string;
+}
+/** Append one occurrence to a `repeat` node. */
+ | {
+    readonly kind: 'add-repeat';
+    readonly nodeId: string;
+}
+/** Drop occurrence `index` of a `repeat` node. */
+ | {
+    readonly kind: 'remove-repeat';
+    readonly nodeId: string;
+    readonly index: number;
+}
+/** Switch a `choice` node to alternative `index`, replacing whatever stood there. */
+ | {
+    readonly kind: 'select-choice';
+    readonly nodeId: string;
+    readonly index: number;
+}
+/** Set a field/attribute value structurally (used when it is not present in the text yet). */
+ | {
+    readonly kind: 'set-value';
+    readonly nodeId: string;
+    readonly value: string;
+};
+/**
+ * Applies one structural {@link FormEdit} to `form`, returning a new tree.
+ *
+ * Unknown node ids and impossible edits (adding past `maxOccurs`, removing
+ * below `minOccurs`) are no-ops rather than errors: the renderer only ever
+ * offers the affordances the tree says are available, and a stale click must
+ * not fail a request.
+ *
+ * @param form the tree to change
+ * @param edit what to change
+ */
+export declare function applyFormEdit(form: FormNode, edit: FormEdit): FormNode;

package/dist/xsd/form-edits.js

@@ -0,0 +1,153 @@
+/**
+ * Structural edits on a {@link FormNode} tree — everything the Form view cannot
+ * express as a plain text splice into an existing value.
+ *
+ * Each edit returns a *new* tree (nothing is mutated), which the caller then
+ * serialises with `applyForm` and splices back over the body element's range.
+ * Because the tree is rebuilt from the document before every edit, an edit can
+ * never operate on a stale shape.
+ */
+/** Applies `change` to the node with `id`, rebuilding only the spine above it. */
+function mapNode(node, id, change) {
+    if (node.id === id) {
+        return change(node);
+    }
+    const children = node.children.map((child) => mapNode(child, id, change));
+    const instances = node.repeat?.instances.map((instance) => mapNode(instance, id, change));
+    const childrenChanged = children.some((child, i) => child !== node.children[i]);
+    const instancesChanged = instances?.some((instance, i) => instance !== node.repeat?.instances[i]) === true;
+    if (!childrenChanged && !instancesChanged) {
+        return node;
+    }
+    return {
+        ...node,
+        children,
+        ...(node.repeat !== undefined && instances !== undefined ? { repeat: { ...node.repeat, instances } } : {}),
+    };
+}
+/**
+ * Marks a not-present subtree as present, so it serialises: the node itself,
+ * every required descendant, and every attribute that must be written. Optional
+ * descendants stay absent — the user adds them one at a time.
+ */
+function materialise(node) {
+    if (node.kind === 'repeat') {
+        const repeat = node.repeat;
+        if (repeat === undefined) {
+            return node;
+        }
+        const instances = repeat.instances.length > 0 ? repeat.instances : [materialise(repeat.template)];
+        return { ...node, present: true, repeat: { ...repeat, instances, canRemove: instances.length > node.occurs.min } };
+    }
+    if (node.kind === 'choice') {
+        const selected = node.choice?.selected ?? 0;
+        return {
+            ...node,
+            present: true,
+            choice: { selected },
+            children: node.children.map((child, i) => (i === selected ? materialise(child) : child)),
+        };
+    }
+    return {
+        ...node,
+        present: true,
+        children: node.children.map((child) => (child.required || child.kind === 'attribute' ? materialise(child) : child)),
+    };
+}
+/** Clears a subtree's presence, so it disappears from the serialised fragment. */
+function dematerialise(node) {
+    return { ...node, present: false };
+}
+/** Re-ids a template subtree so a newly added occurrence gets stable, unique ids. */
+function reid(node, id) {
+    return {
+        ...node,
+        id,
+        children: node.children.map((child, i) => reid(child, `${id}/${i}`)),
+        ...(node.repeat !== undefined
+            ? {
+                repeat: {
+                    ...node.repeat,
+                    instances: node.repeat.instances.map((instance, i) => reid(instance, `${id}#${i}`)),
+                    template: reid(node.repeat.template, `${id}#t`),
+                },
+            }
+            : {}),
+    };
+}
+function addRepeat(node) {
+    const repeat = node.repeat;
+    if (repeat === undefined || !repeat.canAdd) {
+        return node;
+    }
+    const instances = [...repeat.instances, reid(materialise(repeat.template), `${node.id}#${repeat.instances.length}`)];
+    const limit = node.occurs.max === 'unbounded' ? Number.POSITIVE_INFINITY : node.occurs.max;
+    return {
+        ...node,
+        present: true,
+        repeat: {
+            ...repeat,
+            instances,
+            canAdd: instances.length < limit,
+            canRemove: instances.length > node.occurs.min,
+        },
+    };
+}
+function removeRepeat(node, index) {
+    const repeat = node.repeat;
+    if (repeat === undefined || index < 0 || index >= repeat.instances.length) {
+        return node;
+    }
+    const instances = repeat.instances
+        .filter((_, i) => i !== index)
+        .map((instance, i) => reid(instance, `${node.id}#${i}`));
+    const limit = node.occurs.max === 'unbounded' ? Number.POSITIVE_INFINITY : node.occurs.max;
+    return {
+        ...node,
+        present: instances.length > 0,
+        repeat: {
+            ...repeat,
+            instances,
+            canAdd: instances.length < limit,
+            canRemove: instances.length > node.occurs.min,
+        },
+    };
+}
+function selectChoice(node, index) {
+    if (index < 0 || index >= node.children.length) {
+        return node;
+    }
+    return {
+        ...node,
+        present: true,
+        choice: { selected: index },
+        children: node.children.map((child, i) => (i === index ? materialise(child) : dematerialise(child))),
+    };
+}
+/**
+ * Applies one structural {@link FormEdit} to `form`, returning a new tree.
+ *
+ * Unknown node ids and impossible edits (adding past `maxOccurs`, removing
+ * below `minOccurs`) are no-ops rather than errors: the renderer only ever
+ * offers the affordances the tree says are available, and a stale click must
+ * not fail a request.
+ *
+ * @param form the tree to change
+ * @param edit what to change
+ */
+export function applyFormEdit(form, edit) {
+    switch (edit.kind) {
+        case 'insert-optional':
+            return mapNode(form, edit.nodeId, materialise);
+        case 'remove-optional':
+            return mapNode(form, edit.nodeId, dematerialise);
+        case 'add-repeat':
+            return mapNode(form, edit.nodeId, addRepeat);
+        case 'remove-repeat':
+            return mapNode(form, edit.nodeId, (node) => removeRepeat(node, edit.index));
+        case 'select-choice':
+            return mapNode(form, edit.nodeId, (node) => selectChoice(node, edit.index));
+        case 'set-value':
+            return mapNode(form, edit.nodeId, (node) => ({ ...node, present: true, value: edit.value }));
+    }
+}

package/dist/xsd/form-model.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The schema-driven form model behind the request editor's Form view.
+ *
+ * {@link buildForm} projects one element declaration — optionally overlaid with
+ * the XML that currently stands for it — onto a tree of {@link FormNode}s the
+ * renderer can lay out as labelled fields, repeat groups and choice branches.
+ * {@link applyForm} serialises such a tree back to an XML fragment, so a
+ * structural change (add a repetition, select a choice branch, materialise an
+ * omitted optional element) is "rebuild the tree, mutate it, re-render it".
+ *
+ * Two invariants make that safe to run against a user's hand-edited envelope:
+ *
+ * 1. **Nothing in the source is dropped.** Source children a particle never
+ *    claims become `any` nodes carrying the verbatim text; source attributes
+ *    with no schema counterpart (including `xmlns:*` and `xsi:type`) are kept
+ *    as `extraAttributes` and re-emitted first.
+ * 2. **Recursion is only cut where the source is silent.** A recursive type is
+ *    expanded past `maxDepth` whenever the XML actually goes that deep.
+ *
+ * Everything here is pure, synchronous and JSON-serialisable: the tree crosses
+ * the IPC boundary to the renderer as-is.
+ */
+import type { QName } from '../wsdl/qname.js';
+import type { Occurs } from './model.js';
+import type { SchemaSet } from './schema-set.js';
+import type { TextRange } from './xml-scan.js';
+export type { TextRange } from './xml-scan.js';
+/** How a leaf's value should be edited. `other` means "no useful editor; plain text". */
+export type FormValueBase = 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'time' | 'dateTime' | 'binary' | 'other';
+/** What the renderer needs to choose an editor and show validation hints for a leaf. */
+export interface FormType {
+    /** Clark notation for a named type, `xs:int` for a built-in, `''` for an anonymous one. */
+    readonly name: string;
+    readonly base: FormValueBase;
+    readonly enum?: readonly string[];
+    readonly pattern?: string;
+    /** Lexical bound from the type's facets, shown as a hint — never enforced here (Task 42 validates). */
+    readonly min?: string;
+    readonly max?: string;
+}
+/** A literal attribute kept verbatim from the source because no schema attribute claims it. */
+export interface FormExtraAttribute {
+    readonly name: string;
+    readonly value: string;
+}
+/** The repeat bookkeeping on a `repeat` node. */
+export interface FormRepeat {
+    /** One node per occurrence present in (or generated for) the document, in order. */
+    readonly instances: readonly FormNode[];
+    /** A not-present node used as the shape of the next occurrence "+ Add" creates. */
+    readonly template: FormNode;
+    readonly canAdd: boolean;
+    readonly canRemove: boolean;
+}
+/**
+ * One node of the form tree.
+ *
+ * `kind` decides which fields matter:
+ * - `field` — an editable leaf (`type`, `value`, `valueRange`); its `children` are its attributes.
+ * - `group` — a complex element; `children` are attributes then child particles.
+ * - `choice` — `children` are the alternatives; `choice.selected` names the live one.
+ * - `repeat` — occurrences live in `repeat.instances`, **not** in `children` (always empty).
+ * - `attribute` — an attribute of the enclosing element.
+ * - `any` — a wildcard, or source content the schema does not describe; `raw` holds it verbatim.
+ */
+export interface FormNode {
+    /** Stable path id, e.g. `r/2#1/0`. Survives a rebuild of the same document. */
+    readonly id: string;
+    readonly kind: 'field' | 'group' | 'choice' | 'repeat' | 'attribute' | 'any';
+    readonly name: QName;
+    /** The lexical name to write: taken from the source when it exists, else prefixed from scope. */
+    readonly label: string;
+    readonly required: boolean;
+    readonly occurs: Occurs;
+    readonly type?: FormType;
+    /** Current text for a `field`/`attribute`. The `?` placeholder counts as empty to the UI. */
+    readonly value?: string;
+    /** Range of `value` in the source document; absent when the node is not present as editable text. */
+    readonly valueRange?: TextRange;
+    /** Whether this node exists in the document right now. */
+    readonly present: boolean;
+    readonly nillable?: boolean;
+    readonly documentation?: string;
+    /** A schema-fixed value: the field is not editable. */
+    readonly fixed?: string;
+    /** The `xsi:type` standing on this element, shown as a read-only badge. */
+    readonly xsiType?: string;
+    /** Prefix → URI to declare on this element. Set on the root, and on nodes that need a new prefix. */
+    readonly namespaces?: Readonly<Record<string, string>>;
+    /** Source attributes no schema attribute claimed (`xmlns:*`, `xsi:type`, wildcards). */
+    readonly extraAttributes?: readonly FormExtraAttribute[];
+    /** Comments standing immediately before this node in the source. */
+    readonly comments?: readonly string[];
+    /** Comments standing after this node's last child in the source. */
+    readonly trailingComments?: readonly string[];
+    /** Set when the schema recursed past `maxDepth` and expansion stopped; edit such content in XML. */
+    readonly truncated?: boolean;
+    /** Verbatim source text for an `any` node, re-emitted unchanged. */
+    readonly raw?: string;
+    readonly children: readonly FormNode[];
+    readonly choice?: {
+        readonly selected?: number;
+    };
+    readonly repeat?: FormRepeat;
+}
+/** Knobs {@link buildForm} accepts. */
+export interface BuildFormOptions {
+    /** Nesting depth after which a *not-present* complex element stops expanding. Default 5. */
+    readonly maxDepth?: number;
+    /** Fill new leaves with type-appropriate examples instead of `?`. Default false. */
+    readonly sampleValues?: boolean;
+    /** Prefix already in scope per namespace URI, e.g. from the enclosing envelope. */
+    readonly prefixes?: Readonly<Record<string, string>>;
+    /**
+     * Added to every reported `valueRange`, so a fragment sliced out of a larger
+     * document still reports ranges in that document's coordinates.
+     */
+    readonly offset?: number;
+    /**
+     * Namespace URI per prefix inherited from an enclosing document. A body
+     * fragment sliced out of an envelope declares none of its own, so without
+     * this its elements would all resolve into the empty namespace.
+     */
+    readonly inScope?: Readonly<Record<string, string>>;
+}
+/**
+ * Builds the form tree for one global element declaration.
+ *
+ * @param schemaSet the compiled schemas the element is declared in
+ * @param element the global element to model
+ * @param xml the fragment that currently stands for it, or `undefined` for a fresh form
+ * @param options depth cut-off, sample values, and prefixes already in scope
+ * @returns the root node; never throws — an unknown element yields an `any` node instead
+ */
+export declare function buildForm(schemaSet: SchemaSet, element: QName, xml?: string, options?: BuildFormOptions): FormNode;
+/**
+ * Builds the form tree for an element whose content is described by a *type*
+ * rather than a global element declaration — the shape an rpc-style message
+ * part takes.
+ */
+export declare function buildFormForType(schemaSet: SchemaSet, elementName: QName, type: QName, xml?: string, options?: BuildFormOptions): FormNode;
+/** Knobs {@link applyForm} accepts. */
+export interface ApplyFormOptions {
+    /** Indent per level; three spaces by default, matching the sample generator. */
+    readonly indent?: string;
+}
+/**
+ * Serialises a form tree back to an XML fragment: the exact text that should
+ * replace the element the tree was built from. Comments captured from the
+ * source are re-emitted in place, and `any` nodes pass their source text
+ * through verbatim, so nothing the user wrote is lost.
+ */
+export declare function applyForm(form: FormNode, options?: ApplyFormOptions): string;