@aryacode/dsh-engineering 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [0.8.0] - 2026-10-27
+
+### Added
+
+- **FactoryTalk View ME authoring.** The surface no longer only edits an export someone handed over:
+  - `ftview_apps` lists the ME applications installed on the host through the vendor export server
+    (74 applications were listed on the commissioning host).
+  - `ftview_export` exports one application to a NEW folder through `MEExportSvr` — no Studio window,
+    no project change. Proven end to end: 19 files and 13 displays for `Carpenter_EPS_Laminator001`.
+  - `ftview_draft_display_create`, `ftview_draft_object_add`, `ftview_draft_object_set`,
+    `ftview_draft_object_delete` and `ftview_draft_object_order` author displays and objects against a
+    source-positioned tree that keeps nesting (groups), connections and states.
+  - **Vendor-schema validation.** Every changed display is validated against the installed
+    `Gfx-ME*.xsd` through .NET before it can be applied; `ftview_apply` refuses a document the schema
+    rejects (`SCHEMA_INVALID`). All 13 real displays in the Laminator export validate with zero errors.
+  - `ftview_apply` now writes `Displays/BatchImport_<app>.xml` and `IMPORT.md`, the vendor's own
+    one-step import list for Studio's Batch Import.
+  - `ftview_verify_import` re-exports the application through the vendor engine and compares it object
+    by object with the draft, listing differing attributes and missing/extra objects.
+
+### Documentation
+
+- `packages/ftview/SKILL.md`: an Authoring section (apps → export → author → validate) and an Import
+  and verify section that states plainly which steps remain Studio and ME Transfer Utility.
+- README: 97 tools, FactoryTalk View ME 22, and the 0.8.0 milestone.
+## [0.7.0] - 2026-10-27
+
+### Added
+
+- **Ladder generation that cannot emit invalid NeutralText.** Three pieces:
+  - `list_instructions` — the instruction catalog the composer validates: mnemonic, category, summary
+    and operand slots with their kinds (BOOL, NUMBER, TIMER, …), filterable. 41 instructions, covering
+    every mnemonic the Laminator project uses (45 distinct across 860 rungs).
+  - `compose_rung` — builds one rung from a structure tree (`spec_json`) or a named pattern
+    (`start_stop_latch`, `fault_latch`, `ton_delay`, `interlock`), resolves every operand against the
+    export (including unqualified program tags and aliases), type-checks each slot, emits the export's
+    own bracket style, and re-parses its output with the same parser `draft_rung` uses. Unknown
+    instructions name the nearest catalog entries; a wrong operand count, a non-BOOL contact, a
+    non-numeric value slot, an undeclared tag or an undeclared AOI is refused before anything is staged.
+    Passing `program`, `routine`, `mode` and `rung` stages the rung in the draft; `fault_latch` stages
+    its two rungs consecutively.
+- **Rung comments are read and written.** The model read the `Comment` **attribute** only, so a real
+  Studio export's 572 child `<Comment>` elements were invisible. `decodeRung` now supports both shapes,
+  `draft_rung` accepts a `comment`, and `draft_rung_comment` sets or clears one on an existing rung.
+  CDATA terminators in a comment round-trip through the existing escaping.
+- **Documentation dimension.** `document_project` writes a handover bundle into a NEW folder and never
+  touches the export: `PROJECT.md` (controller, revision, tasks, programs, counts), `io.md`/`io.csv`,
+  `tags.csv` and `tags-studio.csv` (the `Tag Name,Description` shape Studio's Tags and Comments import
+  expects), and `rungs/<program>.md` with each rung's number, comment, NeutralText, instructions and
+  resolved tags. Filters: `include`, `programs`, `routines`, `rungs_per_file`.
+
+### Documentation
+
+- `packages/l5x/SKILL.md`: a Generate section (catalog → compose → validate → apply) and a
+  Documentation section (bundle contents, the comment round trip, what the bundle cannot prove).
+- README: 89 tools, L5X 44, and the 0.7.0 milestone.
+
 ## [0.6.0] - 2026-10-27
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 MotionWorks IEC and FactoryTalk Optix sit behind a single install, one row per surface. A row is the
 switch: disable it and that plugin unloads, so its tool schemas leave the request.
 
-`@aryacode/dsh-engineering` · 85 tools · 5 rows · 4 products · MIT
+`@aryacode/dsh-engineering` · 97 tools · 5 rows · 4 products · MIT
 
 ---
 
@@ -36,14 +36,14 @@ bundle.
 
 | Product | Tools | Default | Needs |
 |---|---|---|---|
-| **Studio 5000 L5X** | 40 | all on | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
-| **FactoryTalk View ME** | 14 | all on | Node for an export folder; FactoryTalk View Studio ME for discovery and the handoff |
+| **Studio 5000 L5X** | 44 | all on | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
+| **FactoryTalk View ME** | 22 | all on | Node for an export folder; FactoryTalk View Studio ME for discovery and the handoff |
 | **MotionWorks IEC** | 24 | all on | MotionWorks IEC 3 Pro installed; verified against 1.19 |
 | **FactoryTalk Optix** | 10 (3 need preview) | all on | Optix Studio installed; Tesseract for OCR |
 
 Tool groups, by product:
 
-- **L5X** — 11 read (`open_project` … `compare_projects`), 9 staged drafts (`draft_*`), 6 Logix
+- **L5X** — 13 read (`open_project` … `document_project`), 11 staged drafts (`draft_*`, `compose_rung`), 6 Logix
   Designer SDK, 7 supervised controller, 7 live EtherNet/IP (2 reads, 2 identity/discovery, 1 batch read, 2 approval-gated writes)
 - **FactoryTalk View** — 6 read, 5 staged edits, 3 Studio handoff
 - **MotionWorks IEC** — 7 session, 7 saved-project reads, 3 verify, 7 direct edits
@@ -120,6 +120,8 @@ the lean profile is the one that turns them off.
 
 | Version | What landed |
 |---|---|
+| **0.8.0** | FactoryTalk View authoring: export through the vendor engine, author displays and objects in a schema-validated tree, stage a `BatchImport` handoff, and verify the import object by object |
+| **0.7.0** | Ladder generation that cannot emit invalid NeutralText: an instruction catalog, a pattern/tree composer that resolves and type-checks every operand, rung comments read and written, and a documentation bundle (`document_project`) with the Studio tags-and-comments CSV |
 | **0.5.0** | Commissioned on real files: FactoryTalk View reads genuine Studio exports (`<gfx>` displays, comma CSVs, UTF-16) instead of reporting zero; L5X alias resolution cuts 315 false "unresolved reference" findings to 16 on a 1279-tag project; `add_tag` no longer demands a value; a locked ACD exports from a copy |
 | **0.4.17** | MotionWorks edits the real project again: the pre-edit backup is written where the bridge and engine verify it, an already-open project is attached instead of reloaded, and `mw_get` returns the body hash the edit takes |
 | **0.4.15** | Every tool surface ships on by default; the row Configure pages switch them off |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "AryaCode engineering bundle: one install surface for the Studio 5000 L5X, FactoryTalk View ME, MotionWorks IEC and FactoryTalk Optix surfaces, one row per product, with the ladder and display previews.",
   "keywords": [
     "dsh",
@@ -55,15 +55,6 @@
       ]
     }
   },
-  "scripts": {
-    "test": "node --import tsx --test test/patch.spec.mjs test/docs.spec.mjs test/tool-reference.spec.mjs test/manifests.spec.mjs test/client-face.spec.mjs test/config.spec.mjs test/netlogic.spec.mjs",
-    "docs:tools": "tsx scripts/gen-tool-reference.ts",
-    "docs:check": "tsx scripts/gen-tool-reference.ts --check",
-    "netlogic:sync": "node scripts/sync-netlogic.mjs",
-    "build:client": "node scripts/build-client.mjs",
-    "assemble": "node scripts/assemble.mjs",
-    "prepack": "node scripts/build-client.mjs && node scripts/assemble.mjs"
-  },
   "dependencies": {
     "fast-xml-parser": "5.11.1",
     "fast-xml-validator": "1.4.2",
@@ -103,5 +94,13 @@
     "./mwi/skill": "./vendor/mwi/lib/skill.js",
     "./mwi/verify": "./vendor/mwi/lib/verify.js",
     "./mwi/edit": "./vendor/mwi/lib/edit.js"
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/patch.spec.mjs test/docs.spec.mjs test/tool-reference.spec.mjs test/manifests.spec.mjs test/client-face.spec.mjs test/config.spec.mjs test/netlogic.spec.mjs",
+    "docs:tools": "tsx scripts/gen-tool-reference.ts",
+    "docs:check": "tsx scripts/gen-tool-reference.ts --check",
+    "netlogic:sync": "node scripts/sync-netlogic.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "assemble": "node scripts/assemble.mjs"
   }
-}
+}

package/vendor/ftview/SKILL.md

@@ -65,11 +65,40 @@ unavailable, say editing is not enabled here rather than trying another tool.
 - `ftview_draft_display_add` stages a new display by copying an existing display file.
 - `ftview_draft_tag_upsert` stages one HMI tag description/type change or a new tag row.
 - One operation per call. Each returns the draft id and the operation count; nothing is written yet.
-- `ftview_validate` applies the staged edits to a re-parsed copy and reports the changed files.
-- `ftview_apply` writes a NEW export folder. It never modifies the source.
-
-After applying, reopen the written folder with `ftview_open` and compare it with the source using
-`ftview_compare`.
+- `ftview_validate` applies the staged edits to a re-parsed copy, checks the changed displays against
+  the installed `Gfx-ME*.xsd` and reports the changed files. `ftview_apply` refuses to write when the
+  vendor schema rejects a document.
+- `ftview_apply` writes a NEW export folder, plus `Displays/BatchImport_<app>.xml` and `IMPORT.md` so
+  Studio's Batch Import has the exact list of changed displays. It never modifies the source.
+
+## Authoring
+
+Start from the application, not from a folder someone emailed:
+
+1. `ftview_apps` lists the ME applications installed on this host.
+2. `ftview_export` writes one to a NEW folder through the vendor export server. No Studio window is
+   needed and the application is not modified.
+3. `ftview_open` that folder, then author against it:
+   - `ftview_draft_display_create` for a new display;
+   - `ftview_draft_object_add` for one object (`text`, `panel`, `momentaryButton`, `numericDisplay`,
+     `gotoButton`, …) with geometry, caption and tag connections;
+   - `ftview_draft_object_set`, `ftview_draft_object_delete`, `ftview_draft_object_order` for existing
+     objects.
+4. `ftview_validate` must show `schema.ran: true` with no schema errors before you apply. `schema.ran:
+   false` means the host has no Studio schema and validation did not run; say so instead of claiming
+   validity.
+
+## Import and verify
+
+`ftview_apply` writes the folder, the manifest and `IMPORT.md`. Then:
+
+1. A human opens the application in FactoryTalk View Studio and imports the displays listed in the
+   manifest.
+2. `ftview_verify_import` exports the application again and compares it object by object with the
+   draft. `matched: true` for every display is the only proof the import landed; anything else lists
+   the differing attributes and objects.
+3. Creating the runtime application (`.mer`) and downloading it to the terminal remain Studio and
+   ME Transfer Utility steps. No tool here creates a `.mer` or contacts a PanelView.
 
 ## Studio
 

package/vendor/ftview/lib/display-tree.d.ts

@@ -0,0 +1,99 @@
+/**
+ * A source-positioned tree of one ME display.
+ *
+ * The flat object list was enough to report names, but authoring needs nesting
+ * (groups), connection elements and state blocks, and every edit needs to
+ * change only the bytes it owns. This scanner keeps element offsets in the
+ * original text, so an untouched object is never re-serialized.
+ *
+ * @module dsh-engineering-ftview/display-tree
+ */
+/** One element of a display document. */
+export interface DisplayNode {
+    /** Element name as written, e.g. `momentaryButton`. */
+    readonly type: string;
+    /** Attributes in document order, values still entity-encoded. */
+    readonly attributes: Readonly<Record<string, string>>;
+    /** Children in document order. */
+    readonly children: readonly DisplayNode[];
+    /** Offset of the opening `<`. */
+    readonly start: number;
+    /** Offset just after the opening tag. */
+    readonly tagEnd: number;
+    /** Offset just after the final child, or `tagEnd` for an empty element. */
+    readonly contentEnd: number;
+    /** Offset just after the closing tag (or after `/>`). */
+    readonly end: number;
+    /** True when the element was written as `<x ... />`. */
+    readonly selfClosing: boolean;
+}
+/** One parsed display document. */
+export interface DisplayTree {
+    /** The root element, `<gfx>` or `<display>`. */
+    readonly root: DisplayNode;
+    /** The original text. */
+    readonly xml: string;
+    /** Structural problems found while scanning. */
+    readonly issues: readonly string[];
+}
+/** Decode the five XML entities that can appear in an attribute value. */
+export declare function decodeEntities(value: string): string;
+/** Encode one attribute value for XML. */
+export declare function encodeEntities(value: string): string;
+/**
+ * Scan one display document into a tree.
+ *
+ * @param xml - Whole display file.
+ * @returns Root element, the source text and any structural issues.
+ */
+export declare function parseDisplayTree(xml: string): DisplayTree;
+/** The raw text of one node. */
+export declare function nodeText(tree: DisplayTree, node: DisplayNode): string;
+/** Children of one type, in document order. */
+export declare function childrenOfType(node: DisplayNode, type: string): readonly DisplayNode[];
+/** The first child of one type. */
+export declare function firstChildOfType(node: DisplayNode, type: string): DisplayNode | undefined;
+/** Decoded attribute value, or undefined when absent. */
+export declare function attributeOf(node: DisplayNode, name: string): string | undefined;
+/** Depth-first walk. */
+export declare function walk(node: DisplayNode, visit: (node: DisplayNode, depth: number) => void, depth?: number): void;
+/** Every named object in the display, nested, in document order. */
+export declare function namedObjects(root: DisplayNode): readonly DisplayNode[];
+/**
+ * Set one attribute on a node, changing only its opening tag.
+ *
+ * @param tree - Parsed display.
+ * @param node - Target element.
+ * @param name - Attribute name.
+ * @param value - Plain value; entities are encoded here.
+ * @returns New document text.
+ */
+export declare function setAttribute(tree: DisplayTree, node: DisplayNode, name: string, value: string): string;
+/** Remove one element from a document. */
+export declare function removeNode(tree: DisplayTree, node: DisplayNode): string;
+/**
+ * Insert an element inside a parent, at one child index.
+ *
+ * @param tree - Parsed display.
+ * @param parent - Parent element.
+ * @param childXml - Element text, already indented for its depth.
+ * @param index - Insert before this child; defaults to the end.
+ * @returns New document text.
+ */
+export declare function insertChild(tree: DisplayTree, parent: DisplayNode, childXml: string, index?: number): string;
+/** Indentation prefix for one depth. */
+export declare function indent(depth: number): string;
+/**
+ * Render a new element.
+ *
+ * @param type - Element name.
+ * @param attributes - Attribute values, already encoded where needed.
+ * @param inner - Child markup, or undefined for an empty element.
+ * @param depth - Indentation depth.
+ * @returns Element text.
+ */
+export declare function renderElement(type: string, attributes: Readonly<Record<string, string>>, inner: string | undefined, depth: number): string;
+/** Locate one named object anywhere in the tree. */
+export declare function findNamed(root: DisplayNode, name: string): DisplayNode | undefined;
+/** Path of one node, e.g. `gfx > group[Group1] > momentaryButton`. */
+export declare function nodePath(node: DisplayNode): string;

package/vendor/ftview/lib/display-tree.js

@@ -0,0 +1,306 @@
+/**
+ * A source-positioned tree of one ME display.
+ *
+ * The flat object list was enough to report names, but authoring needs nesting
+ * (groups), connection elements and state blocks, and every edit needs to
+ * change only the bytes it owns. This scanner keeps element offsets in the
+ * original text, so an untouched object is never re-serialized.
+ *
+ * @module dsh-engineering-ftview/display-tree
+ */
+import { EngineeringError } from "./core.js";
+/** Decode the five XML entities that can appear in an attribute value. */
+export function decodeEntities(value) {
+    return value
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&quot;', '"')
+        .replaceAll('&apos;', "'")
+        .replaceAll('&#10;', '\n')
+        .replaceAll('&#xA;', '\n')
+        .replaceAll('&amp;', '&');
+}
+/** Encode one attribute value for XML. */
+export function encodeEntities(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll('\n', '&#10;');
+}
+/** Scan one opening tag starting at `start`. */
+function scanTag(xml, start) {
+    let cursor = start + 1;
+    const nameMatch = /^[A-Za-z_][\w.:-]*/u.exec(xml.slice(cursor));
+    if (nameMatch === null)
+        throw new EngineeringError('INVALID_DISPLAY', `Malformed element at offset ${start}.`, 'Open the file with ftview_get and fix the markup, or restore it from a backup.');
+    const name = nameMatch[0];
+    cursor += name.length;
+    const attributes = [];
+    while (cursor < xml.length) {
+        const character = xml[cursor];
+        if (character === '>') {
+            const before = xml.slice(start, cursor);
+            return { name, attributes, tagEnd: cursor + 1, selfClosing: /\/\s*$/u.test(before) };
+        }
+        if (/\s/u.test(character)) {
+            cursor += 1;
+            continue;
+        }
+        if (character === '/') {
+            cursor += 1;
+            continue;
+        }
+        const attributeStart = cursor;
+        const attributeName = /^[A-Za-z_][\w.:-]*/u.exec(xml.slice(cursor));
+        if (attributeName === null)
+            throw new EngineeringError('INVALID_DISPLAY', `Malformed attribute in <${name}> at offset ${cursor}.`, 'Fix the attribute name, then reopen the display.');
+        cursor += attributeName[0].length;
+        while (xml[cursor] === ' ' || xml[cursor] === '\t')
+            cursor += 1;
+        if (xml[cursor] !== '=') {
+            attributes.push({ name: attributeName[0], value: '', start: attributeStart, end: cursor });
+            continue;
+        }
+        cursor += 1;
+        while (xml[cursor] === ' ' || xml[cursor] === '\t')
+            cursor += 1;
+        const quote = xml[cursor];
+        if (quote !== '"' && quote !== "'")
+            throw new EngineeringError('INVALID_DISPLAY', `Unquoted value for ${attributeName[0]} in <${name}>.`, 'Quote every attribute value, then reopen the display.');
+        const valueStart = cursor + 1;
+        cursor = xml.indexOf(quote, valueStart);
+        if (cursor < 0)
+            throw new EngineeringError('INVALID_DISPLAY', `Unterminated value for ${attributeName[0]} in <${name}>.`, 'Close the quote, then reopen the display.');
+        attributes.push({ name: attributeName[0], value: xml.slice(valueStart, cursor), start: attributeStart, end: cursor + 1 });
+        cursor += 1;
+    }
+    throw new EngineeringError('INVALID_DISPLAY', `Unterminated <${name}> element.`, 'Fix the element, then reopen the display.');
+}
+/**
+ * Scan one display document into a tree.
+ *
+ * @param xml - Whole display file.
+ * @returns Root element, the source text and any structural issues.
+ */
+export function parseDisplayTree(xml) {
+    const issues = [];
+    let root;
+    const stack = [];
+    let cursor = 0;
+    while (cursor < xml.length) {
+        const open = xml.indexOf('<', cursor);
+        if (open < 0)
+            break;
+        if (xml.startsWith('<!--', open)) {
+            const end = xml.indexOf('-->', open + 4);
+            if (end < 0) {
+                issues.push(`Unterminated comment at offset ${open}.`);
+                break;
+            }
+            cursor = end + 3;
+            continue;
+        }
+        if (xml.startsWith('<![CDATA[', open)) {
+            const end = xml.indexOf(']]>', open + 9);
+            if (end < 0) {
+                issues.push(`Unterminated CDATA at offset ${open}.`);
+                break;
+            }
+            cursor = end + 3;
+            continue;
+        }
+        if (xml.startsWith('<?', open)) {
+            const end = xml.indexOf('?>', open + 2);
+            if (end < 0) {
+                issues.push(`Unterminated processing instruction at offset ${open}.`);
+                break;
+            }
+            cursor = end + 2;
+            continue;
+        }
+        if (xml.startsWith('<!', open)) {
+            const end = xml.indexOf('>', open + 2);
+            if (end < 0) {
+                issues.push(`Unterminated declaration at offset ${open}.`);
+                break;
+            }
+            cursor = end + 1;
+            continue;
+        }
+        if (xml.startsWith('</', open)) {
+            const end = xml.indexOf('>', open + 2);
+            if (end < 0) {
+                issues.push(`Unterminated closing tag at offset ${open}.`);
+                break;
+            }
+            const name = xml.slice(open + 2, end).trim();
+            const current = stack.pop();
+            if (current === undefined || current.type !== name) {
+                issues.push(`Unexpected </${name}> at offset ${open}.`);
+                cursor = end + 1;
+                continue;
+            }
+            const node = {
+                type: current.type,
+                attributes: current.attributes,
+                children: current.children,
+                start: current.start,
+                tagEnd: current.tagEnd,
+                contentEnd: current.children.length === 0 ? current.tagEnd : current.children[current.children.length - 1].end,
+                end: end + 1,
+                selfClosing: false,
+            };
+            const parent = stack[stack.length - 1];
+            if (parent === undefined)
+                root = node;
+            else
+                parent.children.push(node);
+            cursor = end + 1;
+            continue;
+        }
+        const tag = scanTag(xml, open);
+        const attributes = {};
+        for (const attribute of tag.attributes)
+            attributes[attribute.name] = attribute.value;
+        if (tag.selfClosing) {
+            const node = { type: tag.name, attributes, children: [], start: open, tagEnd: tag.tagEnd, contentEnd: tag.tagEnd, end: tag.tagEnd, selfClosing: true };
+            const parent = stack[stack.length - 1];
+            if (parent === undefined)
+                root = node;
+            else
+                parent.children.push(node);
+            cursor = tag.tagEnd;
+            continue;
+        }
+        stack.push({ type: tag.name, attributes, children: [], start: open, tagEnd: tag.tagEnd, selfClosing: false });
+        cursor = tag.tagEnd;
+    }
+    if (stack.length > 0)
+        issues.push(`Unclosed element <${stack[stack.length - 1]?.type}>.`);
+    if (root === undefined)
+        throw new EngineeringError('INVALID_DISPLAY', 'The file has no root element.', 'Pass a FactoryTalk View display XML file.');
+    return { root, xml, issues };
+}
+/** The raw text of one node. */
+export function nodeText(tree, node) {
+    return tree.xml.slice(node.start, node.end);
+}
+/** Children of one type, in document order. */
+export function childrenOfType(node, type) {
+    return node.children.filter(child => child.type === type);
+}
+/** The first child of one type. */
+export function firstChildOfType(node, type) {
+    return node.children.find(child => child.type === type);
+}
+/** Decoded attribute value, or undefined when absent. */
+export function attributeOf(node, name) {
+    const raw = node.attributes[name];
+    return raw === undefined ? undefined : decodeEntities(raw);
+}
+/** Depth-first walk. */
+export function walk(node, visit, depth = 0) {
+    visit(node, depth);
+    for (const child of node.children)
+        walk(child, visit, depth + 1);
+}
+/** Every named object in the display, nested, in document order. */
+export function namedObjects(root) {
+    const found = [];
+    for (const child of root.children)
+        walk(child, node => { if (node.attributes.name !== undefined)
+            found.push(node); });
+    return found;
+}
+/** Serialize attributes with their original quoting. */
+function renderAttributes(attributes) {
+    return Object.entries(attributes).map(([name, value]) => ` ${name}="${value}"`).join('');
+}
+/**
+ * Set one attribute on a node, changing only its opening tag.
+ *
+ * @param tree - Parsed display.
+ * @param node - Target element.
+ * @param name - Attribute name.
+ * @param value - Plain value; entities are encoded here.
+ * @returns New document text.
+ */
+export function setAttribute(tree, node, name, value) {
+    const tag = tree.xml.slice(node.start, node.tagEnd);
+    const encoded = encodeEntities(value);
+    const pattern = new RegExp(`(\\s${name.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')}\\s*=\\s*)("[^"]*"|'[^']*')`, 'u');
+    if (pattern.test(tag)) {
+        const replaced = tag.replace(pattern, `$1"${encoded}"`);
+        return tree.xml.slice(0, node.start) + replaced + tree.xml.slice(node.tagEnd);
+    }
+    // Insert before the tag's closing '>' or '/>'.
+    const insertion = /(\/?)\s*>$/u.exec(tag);
+    if (insertion === null)
+        throw new EngineeringError('INVALID_DISPLAY', `Cannot extend <${node.type}>.`, 'Fix the opening tag, then retry.');
+    const at = tag.length - insertion[0].length;
+    const closing = insertion[1] === '/' ? '/>' : '>';
+    const rebuilt = `${tag.slice(0, at)} ${name}="${encoded}"${closing}`;
+    return tree.xml.slice(0, node.start) + rebuilt + tree.xml.slice(node.tagEnd);
+}
+/** Remove one element from a document. */
+export function removeNode(tree, node) {
+    return tree.xml.slice(0, node.start) + tree.xml.slice(node.end);
+}
+/**
+ * Insert an element inside a parent, at one child index.
+ *
+ * @param tree - Parsed display.
+ * @param parent - Parent element.
+ * @param childXml - Element text, already indented for its depth.
+ * @param index - Insert before this child; defaults to the end.
+ * @returns New document text.
+ */
+export function insertChild(tree, parent, childXml, index) {
+    if (parent.selfClosing) {
+        const tag = tree.xml.slice(parent.start, parent.tagEnd);
+        const opened = tag.replace(/\/\s*>$/u, '>');
+        const rebuilt = `${opened}${childXml}</${parent.type}>`;
+        return tree.xml.slice(0, parent.start) + rebuilt + tree.xml.slice(parent.tagEnd);
+    }
+    const children = parent.children;
+    if (index === undefined || index >= children.length) {
+        // Append on a new line after the last child, not inside its own line.
+        const newline = tree.xml.indexOf('\n', parent.contentEnd);
+        const at = newline < 0 ? tree.xml.length : newline + 1;
+        return tree.xml.slice(0, at) + childXml + tree.xml.slice(at);
+    }
+    const at = children[Math.max(0, index)].start;
+    return tree.xml.slice(0, at) + childXml + tree.xml.slice(at);
+}
+/** Indentation prefix for one depth. */
+export function indent(depth) {
+    return '    '.repeat(Math.max(0, depth));
+}
+/**
+ * Render a new element.
+ *
+ * @param type - Element name.
+ * @param attributes - Attribute values, already encoded where needed.
+ * @param inner - Child markup, or undefined for an empty element.
+ * @param depth - Indentation depth.
+ * @returns Element text.
+ */
+export function renderElement(type, attributes, inner, depth) {
+    const open = `${indent(depth)}<${type}${renderAttributes(attributes)}`;
+    return inner === undefined ? `${open}/>\n` : `${open}>\n${inner}${indent(depth)}</${type}>\n`;
+}
+/** Locate one named object anywhere in the tree. */
+export function findNamed(root, name) {
+    let found;
+    walk(root, node => {
+        if (found === undefined && attributeOf(node, 'name') === name)
+            found = node;
+    });
+    return found;
+}
+/** Path of one node, e.g. `gfx > group[Group1] > momentaryButton`. */
+export function nodePath(node) {
+    return node.type;
+}