@aryacode/dsh-engineering 0.7.0 → 0.8.1

package/vendor/ftview/lib/edit/operations.js

@@ -9,6 +9,7 @@
  */
 import { EngineeringError } from "../core.js";
 import { splitCsv } from "../model.js";
+import { decodeEntities, findNamed, firstChildOfType, insertChild, parseDisplayTree, removeNode, renderElement, setAttribute as setNodeAttribute } from "../display-tree.js";
 /** Escape one XML attribute value. */
 export function escapeAttribute(value) {
     return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
@@ -124,3 +125,203 @@ export function upsertTag(csv, tag) {
         lines.push(cells.map(encodeCell).join(';'));
     return lines.join(eol);
 }
+/** Elements that are parts of an object, never objects themselves. */
+const RESERVED = new Set(['gfx', 'display', 'displaySettings', 'connections', 'connection', 'states', 'state', 'caption', 'imageSettings', 'animations', 'parameters', 'parameter', 'font', 'color']);
+/** Depth of one node below the root. */
+function depthOf(root, target) {
+    let found = -1;
+    const walkNode = (node, depth) => {
+        if (found >= 0)
+            return;
+        if (node === target) {
+            found = depth;
+            return;
+        }
+        for (const child of node.children)
+            walkNode(child, depth + 1);
+    };
+    walkNode(root, 0);
+    return found;
+}
+/** Parent of one node, or undefined for the root. */
+function parentOf(root, target) {
+    let found;
+    const walkNode = (node) => {
+        if (found !== undefined)
+            return;
+        for (const child of node.children) {
+            if (child === target) {
+                found = node;
+                return;
+            }
+            walkNode(child);
+        }
+    };
+    walkNode(root);
+    return found;
+}
+/** Validate an object name and element type before writing anything. */
+function assertObjectStyle(type, name) {
+    if (!/^[A-Za-z_][\w.:-]*$/u.test(type))
+        throw new EngineeringError('INVALID_OBJECT_TYPE', `${JSON.stringify(type)} is not an XML element name.`, 'Pass the object element name as the export writes it, for example "momentaryButton".');
+    if (RESERVED.has(type))
+        throw new EngineeringError('INVALID_OBJECT_TYPE', `${type} is part of a display, not an object type.`, 'Pass an object element such as "text", "panel", "momentaryButton" or "numericDisplay".');
+    if (!/^[A-Za-z_][\w .-]{0,79}$/u.test(name))
+        throw new EngineeringError('INVALID_OBJECT_NAME', `${JSON.stringify(name)} is not an object name.`, 'Use letters, digits, spaces, dots, underscores or dashes, at most 80 characters.');
+}
+/** A `<connections>` block at one depth. */
+function connectionsXml(connections, depth) {
+    const lines = Object.entries(connections).map(([name, expression]) => {
+        if (!/^[A-Za-z_][\w.:-]*$/u.test(name))
+            throw new EngineeringError('INVALID_CONNECTION', `${JSON.stringify(name)} is not a connection name.`, 'Pass the connection as the export writes it, for example "Value" or "Visibility".');
+        return `${'    '.repeat(depth + 1)}<connection name="${escapeAttribute(name)}" expression="${escapeAttribute(expression)}"/>\n`;
+    });
+    return `${'    '.repeat(depth)}<connections>\n${lines.join('')}${'    '.repeat(depth)}</connections>\n`;
+}
+/**
+ * Build a new display document from a schema-valid skeleton.
+ *
+ * @param op - Display identity and size.
+ * @returns Whole XML text.
+ */
+export function createDisplay(op) {
+    const settings = {};
+    if (op.displayType !== undefined)
+        settings.displayType = op.displayType;
+    settings.width = String(op.width);
+    settings.height = String(op.height);
+    if (op.backColor !== undefined)
+        settings.backColor = op.backColor;
+    if (op.displayNumber !== undefined)
+        settings.displayNumber = String(op.displayNumber);
+    const attributes = Object.entries(settings).map(([name, value]) => ` ${name}="${escapeAttribute(value)}"`).join('');
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<gfx xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Gfx-ME17.xsd">\n    <displaySettings${attributes}/>\n</gfx>\n`;
+}
+/**
+ * Add one object to a display.
+ *
+ * @param xml - Display XML.
+ * @param op - Object type, name, geometry and connections.
+ * @returns The modified XML.
+ */
+export function addObject(xml, op) {
+    assertObjectStyle(op.type, op.name);
+    const tree = parseDisplayTree(xml);
+    if (op.parent !== undefined) {
+        const parent = findNamed(tree.root, op.parent);
+        if (parent === undefined)
+            throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.parent)} in this display.`, 'Call ftview_get to see the object names, then add inside an existing group.');
+        const depth = depthOf(tree.root, parent);
+        const attributes = { name: escapeAttribute(op.name), ...op.attributes };
+        const innerConnections = op.connections === undefined ? '' : connectionsXml(op.connections, depth + 1);
+        const element = renderElement(op.type, attributes, innerConnections === '' ? undefined : innerConnections, depth + 1);
+        return insertChild(tree, parent, element, op.index);
+    }
+    const attributes = { name: escapeAttribute(op.name), ...op.attributes };
+    if (op.caption !== undefined && attributes.caption === undefined)
+        attributes.caption = escapeAttribute(op.caption);
+    const innerConnections = op.connections === undefined ? '' : connectionsXml(op.connections, 1);
+    const element = renderElement(op.type, attributes, innerConnections === '' ? undefined : innerConnections, 1);
+    return insertChild(tree, tree.root, element, op.index);
+}
+/**
+ * Change attributes and connections on an existing object.
+ *
+ * @param xml - Display XML.
+ * @param op - Target object and the changes.
+ * @returns The modified XML.
+ */
+export function setObject(xml, op) {
+    let current = xml;
+    for (const [name, value] of Object.entries(op.attributes)) {
+        if (!/^[A-Za-z_][\w.:-]*$/u.test(name))
+            throw new EngineeringError('INVALID_ATTRIBUTE', `${JSON.stringify(name)} is not an XML attribute name.`, 'Pass a plain attribute name such as "visible" or "left".');
+        const tree = parseDisplayTree(current);
+        const node = findNamed(tree.root, op.object);
+        if (node === undefined)
+            throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+        current = setNodeAttribute(tree, node, name, value);
+    }
+    if (op.caption !== undefined) {
+        if (op.caption.length > 2000)
+            throw new EngineeringError('INVALID_CAPTION', 'A caption is limited to 2000 characters.', 'Shorten the caption.');
+        const tree = parseDisplayTree(current);
+        const node = findNamed(tree.root, op.object);
+        if (node === undefined)
+            throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+        current = setNodeAttribute(tree, node, 'caption', op.caption);
+    }
+    if (op.connections !== undefined) {
+        for (const name of Object.keys(op.connections)) {
+            if (!/^[A-Za-z_][\w.:-]*$/u.test(name))
+                throw new EngineeringError('INVALID_CONNECTION', `${JSON.stringify(name)} is not a connection name.`, 'Pass the connection name as the export writes it.');
+            const tree = parseDisplayTree(current);
+            const node = findNamed(tree.root, op.object);
+            if (node === undefined)
+                throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+            const expression = op.connections[name];
+            let block = firstChildOfType(node, 'connections');
+            if (block === undefined) {
+                const depth = depthOf(tree.root, node);
+                const inserted = insertChild(tree, node, connectionsXml({ [name]: expression }, depth + 1));
+                current = inserted;
+                continue;
+            }
+            const existing = block.children.find(child => child.type === 'connection' && decodeEntities(child.attributes.name ?? '') === name);
+            if (existing !== undefined) {
+                const existingTree = parseDisplayTree(current);
+                const existingBlock = findNamed(existingTree.root, op.object);
+                if (existingBlock === undefined)
+                    throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+                const connection = existingBlock.children.find(child => child.type === 'connections')?.children.find(child => child.type === 'connection' && decodeEntities(child.attributes.name ?? '') === name);
+                if (connection === undefined)
+                    throw new EngineeringError('COMPONENT_NOT_FOUND', `Connection ${JSON.stringify(name)} disappeared while editing.`, 'Reopen the display and retry.');
+                current = setNodeAttribute(existingTree, connection, 'expression', expression);
+            }
+            else {
+                const depth = depthOf(tree.root, block);
+                current = insertChild(tree, block, `${'    '.repeat(depth + 1)}<connection name="${escapeAttribute(name)}" expression="${escapeAttribute(expression)}"/>\n`);
+            }
+        }
+    }
+    return current;
+}
+/**
+ * Remove one object.
+ *
+ * @param xml - Display XML.
+ * @param op - Target object.
+ * @returns The modified XML.
+ */
+export function deleteObject(xml, op) {
+    const tree = parseDisplayTree(xml);
+    const node = findNamed(tree.root, op.object);
+    if (node === undefined)
+        throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+    return removeNode(tree, node);
+}
+/**
+ * Move one object within its siblings.
+ *
+ * @param xml - Display XML.
+ * @param op - Target object and the new index.
+ * @returns The modified XML.
+ */
+export function orderObject(xml, op) {
+    const tree = parseDisplayTree(xml);
+    const node = findNamed(tree.root, op.object);
+    if (node === undefined)
+        throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+    const parent = parentOf(tree.root, node);
+    if (parent === undefined)
+        throw new EngineeringError('UNSUPPORTED_TARGET', 'The display root cannot be reordered.', 'Target an object inside the display.');
+    const element = xml.slice(node.start, node.end);
+    const without = removeNode(tree, node);
+    const next = parseDisplayTree(without);
+    const target = op.object;
+    const parentName = parent.type === tree.root.type ? undefined : decodeEntities(parent.attributes.name ?? '');
+    const container = parentName === undefined ? next.root : findNamed(next.root, parentName);
+    if (container === undefined)
+        throw new EngineeringError('COMPONENT_NOT_FOUND', `The parent of ${JSON.stringify(target)} disappeared while reordering.`, 'Reopen the display and retry.');
+    return insertChild(next, container, element, op.index);
+}

package/vendor/ftview/lib/edit/prepare.d.ts

@@ -11,6 +11,7 @@ import { type Coverage, type FsService } from '../core.ts';
 import { type Finding } from '../checks.ts';
 import { type Application } from '../model.ts';
 import { type EditOperation } from './operations.ts';
+import { type SchemaValidation } from '../schema.ts';
 /** One prepared edit set. */
 export interface PreparedEdit {
     /** Files whose text changed, keyed by export-relative path. */
@@ -23,6 +24,8 @@ export interface PreparedEdit {
     readonly findings: readonly Finding[];
     /** Stable hash over the source hashes and the operations. */
     readonly hash: string;
+    /** Vendor-schema validation of the changed and added displays. */
+    readonly schema: SchemaValidation;
 }
 /** Coverage for anything derived from an export. */
 export declare const EDIT_COVERAGE: Coverage;

package/vendor/ftview/lib/edit/prepare.js

@@ -11,7 +11,8 @@ import { createHash } from 'node:crypto';
 import { EngineeringError } from "../core.js";
 import { findingsOf } from "../checks.js";
 import { parseDisplay, parseTagCsv } from "../model.js";
-import { renameDisplay, setAttribute, upsertTag } from "./operations.js";
+import { addObject, createDisplay, deleteObject, orderObject, renameDisplay, setAttribute, setObject, upsertTag } from "./operations.js";
+import { validateSchema } from "../schema.js";
 /** Coverage for anything derived from an export. */
 export const EDIT_COVERAGE = {
     complete: false,
@@ -63,6 +64,31 @@ export async function prepareEdit(fs, app, operations, signal) {
             texts.set(operation.file, setAttribute(current, operation.object, operation.attribute, operation.value));
             continue;
         }
+        if (operation.kind === 'display_create') {
+            if (displayNames.has(operation.name) || added.includes(operation.file)) {
+                throw new EngineeringError('COMPONENT_EXISTS', `A display named ${JSON.stringify(operation.name)} already exists in this export or draft.`, 'Pass a new display name.');
+            }
+            if (app.files.some(file => file.file.toLowerCase() === operation.file.toLowerCase())) {
+                throw new EngineeringError('COMPONENT_EXISTS', `The export already has a file ${operation.file}.`, 'Pass a different file path.');
+            }
+            texts.set(operation.file, createDisplay(operation));
+            added.push(operation.file);
+            displayNames.add(operation.name);
+            continue;
+        }
+        if (operation.kind === 'object_add' || operation.kind === 'object_set' || operation.kind === 'object_delete' || operation.kind === 'object_order') {
+            const known = displayByFile.has(operation.file) || added.includes(operation.file);
+            if (!known) {
+                throw new EngineeringError('COMPONENT_NOT_FOUND', `The draft targets ${operation.file}, which this export no longer contains.`, 'Reopen the export and stage the edit again.');
+            }
+            const current = texts.get(operation.file) ?? await readText(fs, app.root, operation.file, signal);
+            const next = operation.kind === 'object_add' ? addObject(current, operation)
+                : operation.kind === 'object_set' ? setObject(current, operation)
+                    : operation.kind === 'object_delete' ? deleteObject(current, operation)
+                        : orderObject(current, operation);
+            texts.set(operation.file, next);
+            continue;
+        }
         if (operation.kind === 'display_add') {
             const source = app.displays.find(display => display.name === operation.copyFrom);
             if (source === undefined) {
@@ -122,12 +148,20 @@ export async function prepareEdit(fs, app, operations, signal) {
         return !changedFiles.has(file);
     });
     const findings = findingsOf({ displays, tags, tagErrors, diagnostics });
+    // Validate only the documents this draft writes: the unchanged ones were
+    // already read by the session, and re-validating 18 displays per call would
+    // make every edit pay for the whole export.
+    const changedDisplays = [...texts]
+        .filter(([file]) => /\.xml$/iu.test(file) && !/batchimport/iu.test(file))
+        .map(([file, text]) => ({ file, xml: text }));
+    const schema = await validateSchema(changedDisplays);
     const hashInput = app.files.map(file => `${file.file}:${file.sha256}`).join('\n') + '\n' + JSON.stringify(operations);
     return {
         texts,
         added,
         changed: [...app.files.map(file => file.file), ...added],
         findings,
+        schema,
         hash: createHash('sha256').update(hashInput).digest('hex'),
     };
 }

package/vendor/ftview/lib/edit/tools.js

@@ -7,9 +7,13 @@
  *
  * @module dsh-engineering-ftview/edit/tools
  */
-import { createHash } from 'node:crypto';
-import { EngineeringError, object, optionalString, requiredString, string, success, tool } from "../core.js";
+import { createHash, randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { EngineeringError, integer, object, optionalInteger, optionalString, requiredString, string, success, tool } from "../core.js";
 import { EDIT_COVERAGE, prepareEdit } from "./prepare.js";
+import { exportApplication } from "../vendor.js";
+import { allMatched, verifyDisplays } from "../handoff.js";
 /** The view handle parameter, described once. */
 const VIEW_ID = string('View handle returned by ftview_open. Omit when exactly one export is open in this chat.');
 /** The draft handle parameter, described once. */
@@ -27,6 +31,41 @@ function nextValidate(draftId) {
 function objectCount(display, name) {
     return display.objects.filter(object => object.name === name).length;
 }
+/** One display by name, with a repairable failure. */
+function displayOf(view, name) {
+    const display = view.app.displays.find(candidate => candidate.name === name);
+    if (display === undefined) {
+        throw new EngineeringError('COMPONENT_NOT_FOUND', `No display is named ${JSON.stringify(name)} in this export.`, 'Call ftview_list with kind "display" to see the display names.', view.app.displays.slice(0, 5).map(candidate => candidate.name));
+    }
+    return display;
+}
+/** Parse one JSON object argument into string attributes. */
+function jsonObject(value, name) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== 'string')
+        throw new EngineeringError('INVALID_ARGUMENT', `${name} must be a JSON object string.`, `Pass ${name} as a JSON object, for example {"height":"40"}.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new EngineeringError('INVALID_ARGUMENT', `${name} is not valid JSON.`, `Pass ${name} as a JSON object, for example {"height":"40"}.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new EngineeringError('INVALID_ARGUMENT', `${name} must be a JSON object.`, `Pass ${name} as a JSON object, for example {"height":"40"}.`);
+    }
+    const result = {};
+    for (const [key, entry] of Object.entries(parsed)) {
+        if (typeof entry === 'number' || typeof entry === 'boolean')
+            result[key] = String(entry);
+        else if (typeof entry === 'string')
+            result[key] = entry;
+        else
+            throw new EngineeringError('INVALID_ARGUMENT', `${name}.${key} must be a string, number or boolean.`, 'Pass scalar values only.');
+    }
+    return result;
+}
 /**
  * The editing tools.
  *
@@ -131,9 +170,146 @@ export function editTools(session, drafts, fs, maxOperations) {
                 return staged(draft, draft.operations[draft.operations.length - 1]);
             },
         }),
+        tool({
+            name: 'ftview_draft_display_create',
+            description: 'Stage a brand-new display with a schema-valid skeleton. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                name: string('New display name, unique in the export. Example: "Arya Overview".'),
+                width: integer('Display width in pixels. Example: 800.', { minimum: 1, maximum: 16384 }),
+                height: integer('Display height in pixels. Example: 600.', { minimum: 1, maximum: 16384 }),
+                display_type: string('Optional display type as Studio writes it, for example "replace" or "onTop".'),
+                back_color: string('Optional background colour. Example: "#C6C6C6".'),
+                display_number: integer('Optional display number.', { minimum: 0 }),
+                file: string('Optional export-relative file path. Defaults to "Displays/<name>.xml".'),
+            }, ['name', 'width', 'height']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const name = requiredString(args, 'name');
+                if (view.app.displays.some(display => display.name === name)) {
+                    throw new EngineeringError('COMPONENT_EXISTS', `A display named ${JSON.stringify(name)} already exists in this export.`, 'Pass a new display name.');
+                }
+                const displayType = optionalString(args, 'display_type');
+                const backColor = optionalString(args, 'back_color');
+                const displayNumber = optionalInteger(args, 'display_number');
+                const { draft } = stage(exec, optionalString(args, 'view_id'), {
+                    kind: 'display_create',
+                    file: optionalString(args, 'file') ?? `Displays/${name}.xml`,
+                    name,
+                    width: optionalInteger(args, 'width') ?? 800,
+                    height: optionalInteger(args, 'height') ?? 600,
+                    ...(displayType === undefined ? {} : { displayType }),
+                    ...(backColor === undefined ? {} : { backColor }),
+                    ...(displayNumber === undefined ? {} : { displayNumber }),
+                });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_object_add',
+            description: 'Stage one new object inside a display: geometry, attributes and tag connections. Validated against the vendor schema on ftview_validate. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                display: string('Display name as listed by ftview_list.'),
+                type: string('Object element type as the export writes it, e.g. "momentaryButton", "text", "panel", "numericDisplay", "gotoButton".'),
+                name: string('New object name, unique inside the display.'),
+                attributes_json: string('Object attributes as a JSON object, e.g. {"height":"50","width":"120","left":"20","top":"40"}.'),
+                caption: string('Optional caption text (text objects and buttons).'),
+                connections_json: string('Optional connections as a JSON object, e.g. {"Value":"SystemRunning"}.'),
+                parent: string('Optional group name to add inside. Omit to add at the display root.'),
+                index: integer('Optional position among siblings, for z-order.', { minimum: 0 }),
+            }, ['display', 'type', 'name']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const display = displayOf(view, requiredString(args, 'display'));
+                const attributes = { ...jsonObject(args.attributes_json, 'attributes_json') };
+                const caption = optionalString(args, 'caption');
+                if (caption !== undefined)
+                    attributes.caption = caption;
+                const connections = jsonObject(optionalString(args, 'connections_json'), 'connections_json');
+                const parent = optionalString(args, 'parent');
+                const index = optionalInteger(args, 'index');
+                const { draft } = stage(exec, optionalString(args, 'view_id'), {
+                    kind: 'object_add',
+                    file: display.file,
+                    type: requiredString(args, 'type'),
+                    name: requiredString(args, 'name'),
+                    attributes,
+                    ...(parent === undefined ? {} : { parent }),
+                    ...(index === undefined ? {} : { index }),
+                    ...(Object.keys(connections).length === 0 ? {} : { connections }),
+                });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_object_set',
+            description: 'Stage attribute, caption or connection changes on one existing object. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                display: string('Display name as listed by ftview_list.'),
+                object: string('Object name inside the display.'),
+                attributes_json: string('Attributes to set as a JSON object, e.g. {"visible":"0","left":"30"}.'),
+                caption: string('Optional new caption text.'),
+                connections_json: string('Connections to set as a JSON object, e.g. {"Value":"SystemRunning"}.'),
+            }, ['display', 'object']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const display = displayOf(view, requiredString(args, 'display'));
+                const object = requiredString(args, 'object');
+                const attributes = jsonObject(args.attributes_json, 'attributes_json');
+                const connections = jsonObject(optionalString(args, 'connections_json'), 'connections_json');
+                const caption = optionalString(args, 'caption');
+                if (Object.keys(attributes).length === 0 && Object.keys(connections).length === 0 && caption === undefined) {
+                    throw new EngineeringError('INVALID_ARGUMENT', 'No change was requested.', 'Pass attributes_json, connections_json or caption.');
+                }
+                const { draft } = stage(exec, optionalString(args, 'view_id'), {
+                    kind: 'object_set',
+                    file: display.file,
+                    object,
+                    attributes,
+                    ...(caption === undefined ? {} : { caption }),
+                    ...(Object.keys(connections).length === 0 ? {} : { connections }),
+                });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_object_delete',
+            description: 'Stage the removal of one object from a display. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                display: string('Display name as listed by ftview_list.'),
+                object: string('Object name to remove.'),
+            }, ['display', 'object']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const display = displayOf(view, requiredString(args, 'display'));
+                const object = requiredString(args, 'object');
+                const { draft } = stage(exec, optionalString(args, 'view_id'), { kind: 'object_delete', file: display.file, object });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_object_order',
+            description: 'Stage a z-order move for one object among its siblings. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                display: string('Display name as listed by ftview_list.'),
+                object: string('Object name to move.'),
+                index: integer('New position among the object siblings, 0 = back.', { minimum: 0 }),
+            }, ['display', 'object', 'index']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const display = displayOf(view, requiredString(args, 'display'));
+                const object = requiredString(args, 'object');
+                const { draft } = stage(exec, optionalString(args, 'view_id'), { kind: 'object_order', file: display.file, object, index: optionalInteger(args, 'index') ?? 0 });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
         tool({
             name: 'ftview_validate',
-            description: 'Prepare the staged edits: apply them to a re-parsed copy, report the changed files and the new structural findings. Writes nothing.',
+            description: 'Prepare the staged edits: apply them to a re-parsed copy, validate the changed displays against the installed Gfx-ME schema, and report the changed files and findings. Writes nothing.',
             parameters: object({ draft_id: DRAFT_ID }, []),
             async run(args, exec) {
                 const draft = drafts.get(exec, optionalString(args, 'draft_id'));
@@ -142,16 +318,47 @@ export function editTools(session, drafts, fs, maxOperations) {
                 const byRule = {};
                 for (const finding of prepared.findings)
                     byRule[finding.rule] = (byRule[finding.rule] ?? 0) + 1;
-                return success(`${draft.operations.length} operation(s); ${prepared.texts.size} file(s) change; ${prepared.findings.length} finding(s).`, {
+                const schemaErrors = prepared.schema.findings.filter(finding => finding.error);
+                return success(`${draft.operations.length} operation(s); ${prepared.texts.size} file(s) change; ${prepared.findings.length} finding(s); schema ${prepared.schema.ran ? `ran (${schemaErrors.length} error(s))` : 'unavailable'}.`, {
                     draft_id: draft.id,
                     draft_sha256: prepared.hash,
                     changed_files: [...prepared.texts.keys()],
                     added: prepared.added,
                     findings: prepared.findings,
                     by_rule: byRule,
+                    schema: prepared.schema,
                 }, [{ tool: 'ftview_apply', args: { draft_id: draft.id }, why: 'Write the prepared export to a new folder.' }], EDIT_COVERAGE);
             },
         }),
+        tool({
+            name: 'ftview_verify_import',
+            description: 'Export the application again through the vendor engine and compare it object by object with the staged draft, proving whether the import landed. Writes only a temporary export folder.',
+            parameters: object({
+                view_id: VIEW_ID,
+                draft_id: DRAFT_ID,
+                application: string('Application name as ftview_apps lists it. The same application the package was imported into.'),
+            }, ['application']),
+            async run(args, exec) {
+                const draft = drafts.get(exec, optionalString(args, 'draft_id'));
+                const view = session.require(draft.viewId, exec);
+                const prepared = await prepareEdit(fs, view.app, draft.operations, exec.signal);
+                const expected = new Map([...prepared.texts].filter(([file]) => /\.xml$/iu.test(file) && !/batchimport/iu.test(file)));
+                if (expected.size === 0) {
+                    throw new EngineeringError('NOTHING_TO_VERIFY', 'This draft changes no display, so there is nothing to compare.', 'Stage a display edit first, import it in Studio, then run this again.');
+                }
+                const root = join(tmpdir(), `ftview-verify-${randomUUID()}`);
+                const exported = await exportApplication(requiredString(args, 'application'), root);
+                if (exported.error !== undefined) {
+                    throw new EngineeringError('VENDOR_EXPORT_FAILED', exported.error, 'Close the application in Studio if it is open, then retry.');
+                }
+                const results = await verifyDisplays(fs, root, expected);
+                const matched = results.filter(result => result.matched).length;
+                const differences = results.flatMap(result => result.differences.map(difference => ({ file: result.file, ...difference })));
+                return success(`${matched}/${results.length} display(s) match the draft${allMatched(results) ? '' : `; ${differences.length} difference(s)`}. Export kept at ${root}.`, { application: requiredString(args, 'application'), export_root: root, displays: results, differences, matched: allMatched(results) }, matched === results.length
+                    ? [{ tool: 'ftview_draft_display_create', why: 'Author the next screen against the verified export.' }]
+                    : [{ tool: 'ftview_validate', args: { draft_id: draft.id }, why: 'Re-read the draft findings before correcting the difference.' }], EDIT_COVERAGE);
+            },
+        }),
         tool({
             name: 'ftview_apply',
             description: 'Write the prepared edits to a NEW export folder: changed files get the edits, other text exports are copied verbatim. The source folder is never modified.',
@@ -163,6 +370,10 @@ export function editTools(session, drafts, fs, maxOperations) {
                 const draft = drafts.get(exec, optionalString(args, 'draft_id'));
                 const view = session.require(draft.viewId, exec);
                 const prepared = await prepareEdit(fs, view.app, draft.operations, exec.signal);
+                const schemaErrors = prepared.schema.findings.filter(finding => finding.error);
+                if (schemaErrors.length > 0) {
+                    throw new EngineeringError('SCHEMA_INVALID', `${schemaErrors.length} schema error(s); nothing was written. First: ${schemaErrors[0]?.file}: ${schemaErrors[0]?.message}`, 'Fix the offending attributes or elements and run ftview_validate again; apply refuses a document the vendor schema rejects.', schemaErrors.slice(0, 5).map(finding => `${finding.file}: ${finding.message}`));
+                }
                 const outputRoot = await fs.resolve(requiredString(args, 'output_root'), {
                     ...(exec.cwd === undefined ? {} : { cwd: exec.cwd }),
                     ...(exec.signal === undefined ? {} : { signal: exec.signal }),
@@ -190,8 +401,41 @@ export function editTools(session, drafts, fs, maxOperations) {
                     await fs.writeText(`${outputRoot}/${file}`, text, { kind: 'createIfAbsent' }, exec.signal);
                     written += 1;
                 }
+                // The vendor's own import file: Studio's Batch Import reads this list
+                // from the Displays folder. Writing it here is what turns a folder of
+                // XML into a one-step import.
+                const changedDisplays = [...prepared.texts.keys()]
+                    .filter(file => /^Displays\/.+\.xml$/iu.test(file) && !/batchimport/iu.test(file));
+                let manifest;
+                if (changedDisplays.length > 0) {
+                    const entries = changedDisplays
+                        .map(file => `    <import importFile="${file.replace(/^Displays\//u, '').replaceAll('&', '&amp;').replaceAll('"', '&quot;')}"/>`)
+                        .join('\n');
+                    manifest = `Displays/BatchImport_${view.app.name}.xml`;
+                    await fs.writeText(`${outputRoot}/${manifest}`, `<?xml version="1.0" encoding="UTF-8"?>\n<gfxImport>\n${entries}\n</gfxImport>\n`, { kind: 'createIfAbsent' }, exec.signal);
+                    written += 1;
+                    const steps = [
+                        `# Import ${view.app.name}`,
+                        '',
+                        `Open FactoryTalk View Studio → Application Manager, open **${view.app.name}**, and import the displays listed in \`Displays/BatchImport_${view.app.name}.xml\` (${changedDisplays.length} file(s)).`,
+                        '',
+                        'Then:',
+                        '1. Verify each display opens without warnings.',
+                        '2. Create the runtime application (`.mer`).',
+                        '3. Run `ftview_verify_import` with the draft id to prove the import matches this draft.',
+                        '',
+                        'Changed displays:',
+                        ...changedDisplays.map(file => `- ${file}`),
+                        '',
+                    ].join('\n');
+                    await fs.writeText(`${outputRoot}/IMPORT.md`, steps, { kind: 'createIfAbsent' }, exec.signal);
+                    written += 1;
+                }
                 drafts.remove(exec, draft.id);
-                return success(`Wrote ${written} file(s) to ${outputRoot}.`, { output_root: outputRoot, draft_id: draft.id, files_written: written, changed_files: [...prepared.texts.keys()] }, [{ tool: 'ftview_open', args: { root: outputRoot }, why: 'Reopen the written export and check it.' }], APPLY_COVERAGE);
+                return success(`Wrote ${written} file(s) to ${outputRoot}${manifest === undefined ? '' : `; import manifest ${manifest}`}.`, { output_root: outputRoot, draft_id: draft.id, files_written: written, changed_files: [...prepared.texts.keys()], ...(manifest === undefined ? {} : { manifest }), schema: prepared.schema }, [
+                    { tool: 'ftview_open', args: { root: outputRoot }, why: 'Reopen the written export and check it.' },
+                    { tool: 'ftview_verify_import', args: { application: view.app.name }, why: 'After Studio imports it, prove the import matches this draft.' },
+                ], APPLY_COVERAGE);
             },
         }),
     ];