/**
 * Set a property ON a control the document itself defines.
 *
 * `modify-property` reached three of the four places a form control can live:
 * the form's own Design properties, and — through <ControlModifications>, see
 * formExtensionControlModifications.ts — a BASE-form control from an extension.
 * It could not reach a control of the agent's OWN form, nor a control an
 * extension ADDS: for those it only had the form-level writer, which edits
 * <Design> and nothing below it. So setting MenuItemName / MultiSelect /
 * NeedsRecord on a button meant rewriting the whole form XML by hand.
 *
 * The control is found by its <Name>, wherever it is nested:
 *
 *   <AxForm> … <AxFormControl i:type="AxFormMenuFunctionButtonControl">
 *                <Name>PostButton</Name> …
 *   <AxFormExtension> … <AxFormExtensionControl> <FormControl i:type="…">
 *                <Name>PostButton</Name> …
 *
 * and the property is written as a direct child of that control, in the order
 * shipped metadata uses for its i:type. That order is not decided here: it is
 * the census in formControlElementOrder.generated.ts, mined from 309,668 shipped
 * controls. It matters because the metadata deserializer DROPS an element it
 * meets out of sequence, without a word (#979) — a property appended at the end
 * would be written, reported, and ignored. The same census also refuses a
 * property the type never carries (MenuItemName on a plain AxFormButtonControl):
 * that is a different control type, not a missing property.
 *
 * Pure and side-effect-free: the file I/O stays in the caller. Offsets come from
 * the offset-preserving tree, so every byte outside the touched element is kept.
 */
export type FormControlPropertyOutcome = {
    ok: true;
    xml: string;
    /** False when the file already carried exactly this value — nothing to write. */
    changed: boolean;
    /** Human-readable account of what happened, for the tool reply. */
    detail: string;
} | {
    ok: false;
    reason: string;
};
/**
 * Set `propertyName` = `propertyValue` on the control named `controlName` in an
 * AxForm, or on a control an AxFormExtension adds. An empty value removes the
 * element — absence is the default, and shipped metadata never writes it empty.
 *
 * Returns `null` when the document defines no control of that name, so the
 * caller can fall back (a form extension then means a BASE-form control, which
 * goes to <ControlModifications>). Returns `{ ok: false }` — never a partial
 * write — when the name is ambiguous, the control type or property is not in the
 * census, or the existing element is not a plain value.
 */
export declare function upsertFormControlProperty(xml: string, controlName: string, propertyName: string, propertyValue: string): FormControlPropertyOutcome | null;
//# sourceMappingURL=formControlPropertyXml.d.ts.map