@wootsup/yt-builder-mcp 1.12.0 → 2.0.0

package/dist/tools/elements/handlers-write.js

@@ -1,797 +0,0 @@
-/**
- * Element-tool write handlers (add/update/move/clone/delete).
- *
- * Wave G.4.0 split: read handlers + shared types in `./handlers.ts`.
- * Wave G.4.1: `handleElementDelete` consults `deps.elicitation` when
- * `confirm` is undefined — falls back to the explicit preview when
- * elicitation is unavailable.
- * Wave G.5: every handler emits 2-phase client-side progress
- * (`PHASE_SEND` → `PHASE_CONFIRM`) when the caller supplied a
- * `progressToken` — see `../progress-phases.ts` for the contract.
- *
- * @license MIT
- */
-import { elicitConfirmation } from '@getimo/mcp-toolkit';
-import { encodeElementPath, encodeTemplateId } from '../../client.js';
-import { RestError } from '../../errors.js';
-import { BIND_VIA_GATEWAY_EXAMPLE, BIND_VIA_GATEWAY_HINT } from '../bind-guidance.js';
-import { PHASE_CONFIRM, PHASE_SEND } from '../progress-phases.js';
-import { confirmGuard, createProgressReporter, errorResult, jsonResult, } from '../tool-builder.js';
-import { fetchSchemaFields, guardHeaderTransparencyWrite, seedRequiredEnumDefaults, validateEnumPropValues, validatePropsAgainstLiveSchema, withHeaderTransparencyWarnings, } from './schema-validation.js';
-// ─── Wave-7 (2026-05-29): props validation ──────────────────────────
-//
-// Cold-AI #5 hand-authored `props.source` / `props.source_extended` via
-// element_update_settings({props:{source}}). YT-Pro's render-side then
-// silently ignored the binding because `source` is not a leaf prop — it
-// lives as a SIBLING of `props` on the element node. The agent had no
-// signal that the call was a no-op until visual verification failed.
-//
-// These keys MUST go through yootheme_builder_element_bind_source (which
-// writes them at the correct nesting level). Reject hand-authored attempts
-// up-front so the agent gets a structured error instead of a silent broken
-// render.
-const RESERVED_BINDING_KEYS = new Set([
-    'source',
-    'source_extended',
-    // YT-Pro UI-only placeholders that customers paste from
-    // Inspect/Copy in the visual builder. They never resolve outside the
-    // builder runtime so they're useless inside a stored layout.
-    'source_node',
-]);
-// Wave-7 (2026-05-29): common cold-AI prop-key typos. The PHP backend
-// silently drops unknown props, so a typo like `title` on a headline (real
-// key is `content`) renders an empty headline. We surface a fix suggestion
-// up-front for the small fixed set of high-frequency mistakes.
-//
-// Format: typo → { element_type → canonical_key }
-// element_type === '*' applies to any element where the typo is known to be
-// a typo on every type that has it.
-const COMMON_PROP_TYPOS = {
-    title: {
-        headline: 'content',
-        subtitle: 'content',
-        text: 'content',
-        quote: 'content',
-        button_item: 'content',
-        // Wave-9 F9 (cold-AI #8): `button` accepts `content` at runtime
-        // even though the UI-tab fieldset omits it (see
-        // Inspector::knownAcceptedButHiddenFields). `title` is the most
-        // common cold-AI typo for the button label.
-        button: 'content',
-    },
-    text: {
-        headline: 'content',
-        text: 'content',
-        quote: 'content',
-        // Wave-9 F9: same rationale as `title` above — agents reading
-        // documentation often type `text` for the button label.
-        button: 'content',
-    },
-    label: {
-        button_item: 'content',
-        // Wave-9 F9: `label` is a common cold-AI alias for button text.
-        button: 'content',
-    },
-    url: {
-        button_item: 'link',
-        // Wave-9 F9 (cold-AI #8): `button` accepts `link` at runtime.
-        button: 'link',
-    },
-    href: {
-        // Wave-9 F9: HTML-native authors reach for `href` first.
-        button_item: 'link',
-        button: 'link',
-    },
-    button_text: {
-        button_item: 'content',
-        button: 'content',
-    },
-    button_link: {
-        button_item: 'link',
-        button: 'link',
-    },
-    style: {
-        button_item: 'button_style',
-    },
-    size: {
-        button_item: 'button_size',
-    },
-};
-function detectPropTypos(props, elementType) {
-    if (props === undefined || props === null)
-        return [];
-    const findings = [];
-    for (const key of Object.keys(props)) {
-        const map = COMMON_PROP_TYPOS[key];
-        if (map === undefined)
-            continue;
-        const suggested = map[elementType];
-        if (suggested !== undefined) {
-            findings.push({ typo: key, suggested });
-        }
-    }
-    return findings;
-}
-function rejectOnPropTypos(props, elementType) {
-    const findings = detectPropTypos(props, elementType);
-    if (findings.length === 0)
-        return null;
-    // F14 (2026-06-09): name the CANONICAL prop explicitly + imperatively
-    // (`use \`content\` instead of \`title\``) rather than only posing it
-    // as a question. A cold agent that hit `element_add headline {title}`
-    // got the element rendered empty because YT-Pro silently drops the
-    // unknown alias; the error must state the right key so the agent can
-    // self-correct in one step without a schema round-trip.
-    const summary = findings
-        .map((f) => `use \`${f.suggested}\` instead of \`${f.typo}\``)
-        .join('; ');
-    // Lead with the single most-likely fix so the canonical key is the
-    // first concrete token the agent reads.
-    const primary = findings[0];
-    const rename = primary !== undefined
-        ? `Rename \`${primary.typo}\` → \`${primary.suggested}\`. `
-        : '';
-    return errorResult({
-        error: new Error(`Unknown prop(s) for element type \`${elementType}\`: ${summary}. ` +
-            rename +
-            'YT-Pro silently drops unknown props server-side, so the element would render empty. ' +
-            'Call yootheme_builder_element_type_get_schema to see the canonical prop keys.'),
-        context: {
-            element_type: elementType,
-            findings,
-        },
-        hint: `Re-try with the canonical key (e.g. \`${primary?.suggested ?? 'content'}\`), ` +
-            'or fetch the schema first: ' +
-            `yootheme_builder_element_type_get_schema({ element_type: "${elementType}" }).`,
-    });
-}
-function validatePropsForReservedKeys(props, elementType) {
-    if (props === undefined || props === null)
-        return null;
-    const offending = [];
-    for (const key of Object.keys(props)) {
-        if (RESERVED_BINDING_KEYS.has(key)) {
-            offending.push(key);
-        }
-    }
-    if (offending.length === 0)
-        return null;
-    return errorResult({
-        error: new Error(`Reserved binding key(s) ${offending
-            .map((k) => `\`${k}\``)
-            .join(', ')} are NOT valid props for element type \`${elementType}\`. ` +
-            `Source binding lives as a SIBLING of \`props\` on the element node, ` +
-            `NOT nested inside props. Set the source via the gateway: ` +
-            `${BIND_VIA_GATEWAY_EXAMPLE} — it writes the binding at the correct ` +
-            `nesting level (the bind tool is advanced, not in tools/list). ` +
-            `For per-prop leaf bindings (headline.content, etc.) pass the prop name ` +
-            `inside the \`field_mappings\` argument of that same call. ` +
-            // F97 (2026-06-10): a FILTERED prop (e.g. a `_condition` that
-            // renders a row only when a field is non-empty) is the most
-            // common reason an agent reaches for a raw `source` here. The
-            // theme-canonical, validated path is the field_mappings OBJECT
-            // form on element_bind_source — name it so the agent never has
-            // to hand-author a dead `source` blob nor build pre-filtered
-            // flows as a workaround.
-            `For a FILTERED prop (e.g. a \`_condition\` that shows a row only when a ` +
-            `field is set) use the field_mappings OBJECT form: ` +
-            `field_mappings: { _condition: { name: "<field>", filters: { condition: "!!" } } } ` +
-            `(\`"!!"\` = render only when non-empty, \`"!"\` = only when empty; a bare ` +
-            `_condition with no filters operator renders ALWAYS). Date-format leaves use ` +
-            `{ name: "<field>", filters: { date: "D, d.m.y" } }.`),
-        context: { element_type: elementType, offending_keys: offending },
-        hint: 'Run yootheme_builder_element_type_get_schema to see the binding contract ' +
-            `(do_not section lists this anti-pattern). Then ${BIND_VIA_GATEWAY_HINT} ` +
-            'For filtered props pass the field_mappings object form ' +
-            '({ <prop>: { name, filters } }) on element_bind_source.',
-    });
-}
-// ─── children-tree guard (F132, Wave 4a) ─────────────────────────────
-//
-// `element_add` accepts a `children` array of arbitrary element objects.
-// Before Wave 4a only the top-level `props` were validated, so a cold agent
-// building a grid+grid_item tree in ONE element_add could smuggle the exact
-// forbidden shapes through the children:
-//
-//   children: [{ type:'grid_item', source:{query:…}, props:{title:…} }]
-//
-// `source` is a SIBLING of `props` on YT-Pro element nodes; hand-authoring it
-// (or `source_extended` / `source_node`) never resolves in a stored layout —
-// the render silently produces 0 rows while element_add returns success. The
-// same applies to per-prop typos (`title` on a headline → empty headline).
-//
-// This walks the whole children subtree and applies the SAME two guards that
-// protect top-level props, plus a sibling-`source` rejection per node.
-function elementTypeOfChild(node) {
-    const t = node.type;
-    if (typeof t === 'string' && t !== '')
-        return t;
-    const et = node.element_type;
-    if (typeof et === 'string' && et !== '')
-        return et;
-    return '<child>';
-}
-function rejectSourceSiblingOnChild(node, elementType) {
-    const offending = [...RESERVED_BINDING_KEYS].filter((k) => k in node);
-    if (offending.length === 0)
-        return null;
-    return errorResult({
-        error: new Error(`Hand-authored binding key(s) ${offending
-            .map((k) => `\`${k}\``)
-            .join(', ')} found on a \`children\` node (element type \`${elementType}\`). ` +
-            `A source binding must NOT be hand-authored inside an element_add tree — ` +
-            `the stored layout silently renders 0 rows. Add the bare container/child ` +
-            `structure first, then bind with \`yootheme_builder_element_bind_source\`, ` +
-            `which writes the binding at the correct nesting level.`),
-        context: { element_type: elementType, offending_keys: offending },
-        hint: 'Remove `source` / `source_extended` / `source_node` from the children tree. ' +
-            'Build the structure, then call yootheme_builder_element_bind_source. See ' +
-            'yootheme_builder_element_type_get_schema (do_not section).',
-    });
-}
-/**
- * Recursively validate a `children` array: each node's own `props` is run
- * through the reserved-key + prop-typo guards, the node itself is checked
- * for a hand-authored `source` sibling, and nested `children` recurse.
- * Returns the FIRST rejection found, or null when the whole tree is clean.
- */
-function validateChildrenTree(children) {
-    if (!Array.isArray(children))
-        return null;
-    for (const raw of children) {
-        if (raw === null || typeof raw !== 'object')
-            continue;
-        const node = raw;
-        const elementType = elementTypeOfChild(node);
-        const sourceRejection = rejectSourceSiblingOnChild(node, elementType);
-        if (sourceRejection !== null)
-            return sourceRejection;
-        const props = node.props !== null && typeof node.props === 'object'
-            ? node.props
-            : undefined;
-        const propsRejection = validatePropsForReservedKeys(props, elementType);
-        if (propsRejection !== null)
-            return propsRejection;
-        const typoRejection = rejectOnPropTypos(props, elementType);
-        if (typoRejection !== null)
-            return typoRejection;
-        const nested = validateChildrenTree(node.children);
-        if (nested !== null)
-            return nested;
-    }
-    return null;
-}
-/**
- * ELEMENT_WRITE-12 — status/code-aware catch hint for `element_add`.
- *
- * The former hint was a single static string mentioning 412 + 400 for EVERY
- * failure. The actual high-frequency failure is a 422
- * `…elements.invalid_hierarchy` (e.g. adding a `row` at the layout root) — which
- * is neither 412 nor 400, and whose real fix (scaffold_section) went unnamed.
- * Inspect the RestError and emit the fix that matches the failure.
- */
-function elementAddHint(e) {
-    if (e instanceof RestError) {
-        const code = e.code ?? '';
-        if (e.status === 422 && code.includes('invalid_hierarchy')) {
-            return ('invalid_hierarchy: this element type cannot be added at that parent ' +
-                '(e.g. a row/column at the layout root). Call ' +
-                'yootheme_builder_scaffold_section({ template_id, columns }) to create a ' +
-                'valid section→row→column hull, then pass a returned column path as ' +
-                'parent_path.');
-        }
-        if (e.status === 412) {
-            return 'On 412 refresh via yootheme_builder_get_etag and retry.';
-        }
-        if (e.status === 400) {
-            return 'On 400 check `element_type` is valid via yootheme_builder_element_types_list.';
-        }
-    }
-    return ('On 412 refresh via yootheme_builder_get_etag and retry. On 400 check ' +
-        '`element_type` is valid via yootheme_builder_element_types_list. On 422 ' +
-        'invalid_hierarchy scaffold a section→row→column hull first with ' +
-        'yootheme_builder_scaffold_section and add into a returned column path.');
-}
-/**
- * ELEMENT_WRITE-12 — status/code-aware catch hint for `element_update_settings`.
- * A 422 invalid-value (a prop value the element rejects) is NOT fixed by
- * `merge:true`, so the merge advice only rides on the non-422 path.
- */
-function elementUpdateHint(e) {
-    if (e instanceof RestError && e.status === 422) {
-        return ('On 422 a prop VALUE was rejected by the element (invalid enum / type). ' +
-            'Fetch the accepted values with yootheme_builder_element_type_get_schema ' +
-            '(read each field\'s value_hint/enum) and resend a valid value — ' +
-            '`merge:true` does NOT fix an invalid value.');
-    }
-    return ('On 412 refresh via yootheme_builder_get_etag and retry. To merge ' +
-        'props instead of replacing, pass `merge:true` (server deep-merges ' +
-        'the request into current props).');
-}
-// ─── element_add ─────────────────────────────────────────────────────
-export async function handleElementAdd({ client }, input, extra) {
-    // Union of F165 (type_name → element_type alias) and F70 (position →
-    // index alias). Both aliases are folded onto their canonical keys and
-    // stripped so they never leak into the REST body. The canonical key
-    // wins when both are supplied.
-    const { template_id, etag, type_name, index, position, ...rest } = input;
-    const elementType = typeof rest.element_type === 'string' && rest.element_type !== ''
-        ? rest.element_type
-        : typeof type_name === 'string'
-            ? type_name
-            : '';
-    if (elementType === '') {
-        return errorResult({
-            error: new Error('element_type is required.'),
-            context: { template_id },
-            hint: 'Provide `element_type` (e.g. "grid"; `type_name` is accepted as an ' +
-                'alias). Use yootheme_builder_element_types_list for the catalogue.',
-        });
-    }
-    // F70: index wins over the position alias; absent → body carries no
-    // index (server appends), preserving the historical append request.
-    const resolvedIndex = index ?? position;
-    const body = {
-        parent_path: typeof rest.parent_path === 'string' ? rest.parent_path : '',
-        element_type: elementType,
-        // ELEMENT_WRITE-4 (part 2): the first-class builder name → node-level
-        // `name`. Only forwarded when a non-empty string so an omitted/blank
-        // value leaves the server default (an unnamed node) untouched.
-        ...(typeof rest.name === 'string' && rest.name !== '' ? { name: rest.name } : {}),
-        ...(rest.props !== undefined ? { props: rest.props } : {}),
-        ...(rest.children !== undefined ? { children: rest.children } : {}),
-        ...(resolvedIndex !== undefined ? { index: resolvedIndex } : {}),
-    };
-    // Wave-7: guard against hand-authored source/source_extended in props.
-    const propsRejection = validatePropsForReservedKeys(input.props, elementType);
-    if (propsRejection !== null)
-        return propsRejection;
-    // Wave-7: guard against common prop-key typos (title→content etc.).
-    const typoRejection = rejectOnPropTypos(input.props, elementType);
-    if (typoRejection !== null)
-        return typoRejection;
-    // F132 (Wave 4a): the same guards must reach the `children` subtree —
-    // otherwise a single element_add can smuggle a forbidden source/typo
-    // through a nested child and silently render 0 rows.
-    const childrenRejection = validateChildrenTree(input.children);
-    if (childrenRejection !== null)
-        return childrenRejection;
-    // Ordering-red-border fix (2026-07-25): fetch the live element-type
-    // schema ONCE here — reused below for the unknown-KEY check (B3), the
-    // explicit-invalid-enum-VALUE hard-reject, and the required-enum
-    // default-seeding, so one element_add call never triggers more than one
-    // schema round-trip. Best-effort: ANY failure (network, non-2xx, unknown
-    // shape) resolves to `null` and every dependent check below falls
-    // through to its pre-fix behaviour (additive-before-breaking).
-    const schemaFields = await fetchSchemaFields(client, elementType);
-    // B3 (2026-06-29): live-schema cross-check. The static guards above catch a
-    // fixed set of known mistakes; this rejects ANY top-level prop key absent
-    // from the element-type's real schema (fields[].name) — the silent-drop
-    // class the static map cannot enumerate. Best-effort: a schema fetch
-    // failure / unknown shape / empty field list never breaks the write
-    // (additive-before-breaking; the plugin is live 1.6.x).
-    const liveSchemaRejection = await validatePropsAgainstLiveSchema({
-        client,
-        elementType,
-        props: input.props,
-        reservedKeys: RESERVED_BINDING_KEYS,
-        fields: schemaFields,
-    });
-    if (liveSchemaRejection !== null)
-        return liveSchemaRejection;
-    // Ordering-red-border fix (2026-07-25): a caller-supplied value for a
-    // KNOWN enum-constrained field that is not one of its accepted members is
-    // hard-rejected up-front with an actionable message — the same mistake
-    // the PHP write guard would 422 on, caught earlier. Never touches a key
-    // the caller did NOT supply (that's the seeding step below).
-    const enumValueRejection = validateEnumPropValues({
-        elementType,
-        fields: schemaFields ?? [],
-        props: input.props,
-        reservedKeys: RESERVED_BINDING_KEYS,
-    });
-    if (enumValueRejection !== null)
-        return enumValueRejection;
-    // Ordering-red-border fix (2026-07-25): seed every REQUIRED enum field
-    // (schema `enum` without a `''` member) that declares a non-empty schema
-    // `default` and that the caller did NOT supply — mirrors what YOOtheme's
-    // own native element-creation initialises. Without this, an element
-    // created via element_add carries NO value for a required dropdown (e.g.
-    // "Ordering"), and the Vue Builder flags it red. A caller-supplied value
-    // (already validated above) is NEVER overwritten.
-    if (schemaFields !== null) {
-        body.props = seedRequiredEnumDefaults(schemaFields, body.props);
-    }
-    const progress = extra ? createProgressReporter(extra) : null;
-    await progress?.report(0, 2, PHASE_SEND);
-    try {
-        const data = await client.post(`/pages/${encodeTemplateId(template_id)}/elements`, { body, etag });
-        await progress?.report(2, 2, PHASE_CONFIRM);
-        return jsonResult(data);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: input,
-            hint: elementAddHint(e),
-        });
-    }
-}
-// ─── scaffold_section (WF2 Option C) ─────────────────────────────────
-/**
- * `scaffold_section` — POST /pages/{template_id}/elements/scaffold-section.
- *
- * Create a VALID `section → row → column` hull (optionally N columns) in ONE
- * atomic call and return the column pointer(s) to drop content into. This is
- * the positive-steering counterpart to the server-side hierarchy guard: it
- * makes the correct structure the cheapest path, so the guard rarely fires.
- * The whole hull lands in a single server-side transaction (one ETag bump).
- */
-export async function handleScaffoldSection({ client }, input, extra) {
-    const { template_id, columns, column_widths, etag } = input;
-    const progress = extra ? createProgressReporter(extra) : null;
-    await progress?.report(0, 2, PHASE_SEND);
-    try {
-        const body = {};
-        if (columns !== undefined) {
-            body.columns = columns;
-        }
-        if (column_widths !== undefined) {
-            body.column_widths = column_widths;
-        }
-        const data = await client.post(`/pages/${encodeTemplateId(template_id)}/elements/scaffold-section`, { body, etag });
-        await progress?.report(2, 2, PHASE_CONFIRM);
-        return jsonResult(data);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id, columns, column_widths },
-            hint: 'On 412 refresh via yootheme_builder_get_etag and retry. The response ' +
-                '`column_paths` are valid parents for yootheme_builder_element_add — ' +
-                'drop your content elements into those columns.',
-        });
-    }
-}
-// ─── element_update_settings ─────────────────────────────────────────
-/**
- * B3 — best-effort element-type discovery for `element_update_settings`, which
- * carries no `element_type` input. Reads the element and returns its type, or
- * `null` on ANY failure (so the live-schema check simply does not run). Mirrors
- * the type extraction in `handleElementGet` (`element_type`, then `type`).
- */
-async function discoverElementType(client, template_id, element_path) {
-    try {
-        const data = await client.get(`/pages/${encodeTemplateId(template_id)}/elements/${encodeElementPath(element_path)}`);
-        if (typeof data.element_type === 'string' && data.element_type !== '') {
-            return data.element_type;
-        }
-        if (typeof data.type === 'string' && data.type !== '') {
-            return data.type;
-        }
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
-export async function handleElementUpdateSettings({ client }, input, extra) {
-    const { template_id, element_path, props, name, merge, unset, etag } = input;
-    // Wave-7: guard against hand-authored source/source_extended in props.
-    // element_path is the only identity we have at this layer; the agent gets
-    // a clear message anyway because the offending key is named explicitly.
-    const propsRejection = validatePropsForReservedKeys(props, `<at ${element_path}>`);
-    if (propsRejection !== null)
-        return propsRejection;
-    // Task 6 (transparent-header plan, 2026-07-27): the ONE client-side
-    // chokepoint for YOOtheme's three `header_transparent*` section props.
-    // Runs BEFORE the live-schema probe because it is decided from the payload
-    // alone — a dead prop needs no network round-trip and no theme knowledge.
-    // Rejects class A (props YOOtheme never reads), defaults a switched-on
-    // transparent header's colour to `''` (never `'light'`), and passes class C
-    // (a hero medium) through with a warning. Class B needs the compiled
-    // `theme.css`, which this process cannot read — it stays server-side and is
-    // deliberately NOT approximated here.
-    const headerGuard = guardHeaderTransparencyWrite({
-        props,
-        merge,
-        unset,
-        elementPath: element_path,
-    });
-    if (headerGuard.rejection !== null)
-        return headerGuard.rejection;
-    const effectiveProps = headerGuard.props ?? props;
-    // B3 (2026-06-29): live-schema cross-check. This handler has no
-    // `element_type` input, so discover it best-effort via the element read,
-    // then validate props against the real schema. ANY failure (type
-    // undiscoverable, schema fetch error, empty field list) falls through to
-    // the prior behaviour — the write is never broken by the probe. Skipped
-    // when there are no props to validate so a no-op update stays a single call.
-    //
-    // Deliberately validates the CALLER's props, not `effectiveProps`: the
-    // header guard above may have seeded `header_transparent_text_color: ''`,
-    // and an older plugin whose schema predates that field would then have this
-    // check hard-reject OUR OWN seed. A seeded key is a no-op server-side
-    // anyway (an absent colour and `''` render identically).
-    if (props !== null && typeof props === 'object' && Object.keys(props).length > 0) {
-        const discoveredType = await discoverElementType(client, template_id, element_path);
-        if (discoveredType !== null) {
-            const liveSchemaRejection = await validatePropsAgainstLiveSchema({
-                client,
-                elementType: discoveredType,
-                props,
-                reservedKeys: RESERVED_BINDING_KEYS,
-            });
-            if (liveSchemaRejection !== null)
-                return liveSchemaRejection;
-        }
-    }
-    const encoded = encodeElementPath(element_path);
-    const progress = extra ? createProgressReporter(extra) : null;
-    await progress?.report(0, 2, PHASE_SEND);
-    try {
-        // T5 / F-12: forward `merge` only when explicitly true so older PHP
-        // builds (which ignore unknown keys anyway) get the same byte-for-
-        // byte body they did before.
-        // Task 6: `effectiveProps` is the SAME reference as `props` unless the
-        // header guard seeded the theme-default colour, so every other write
-        // keeps its byte-identical body.
-        const body = {
-            props: effectiveProps,
-        };
-        if (merge === true) {
-            body.merge = true;
-        }
-        // ELEMENT_WRITE-4 (part 2): forward the first-class builder name → the
-        // node-level `name`. Only when a non-empty string so an omitted value
-        // leaves the current name unchanged.
-        if (typeof name === 'string' && name !== '') {
-            body.name = name;
-        }
-        // Task 10b: forward `unset` only when non-empty (same back-compat
-        // pattern as `merge`) — removal is never schema-validated, it
-        // mirrors the PHP side which honours an `unset` key in the PUT body.
-        if (unset !== undefined && unset.length > 0) {
-            body.unset = unset;
-        }
-        const data = await client.put(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/settings`, { body, etag });
-        await progress?.report(2, 2, PHASE_CONFIRM);
-        // Task 6: a class-C write (transparent header over a hero medium) and
-        // a defaulted colour are ALLOWED — they ride back as non-blocking
-        // `warnings[]` so the agent learns what it must go and LOOK at.
-        // A write with no header props gets the untouched REST body back.
-        return jsonResult(withHeaderTransparencyWarnings(data, headerGuard.warnings));
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id, element_path },
-            hint: elementUpdateHint(e),
-        });
-    }
-}
-// ─── element_set_status ───────────────────────────────────────────────
-/**
- * T-D1 — enable/disable an element via its `props.status` field, the SAME
- * field YOOtheme's own native "Disable element" checkbox writes
- * (`packages/builder/config/builder.php`: `true-value: 'disabled'`,
- * `false-value: ''`) and the ONLY field its render pipeline's
- * `DisabledTransform` checks (`props['status'] !== 'disabled'`). This
- * handler is a thin REST proxy: it forwards `status` verbatim (as a
- * boolean) in the PUT body — the enable-removes-the-key vs
- * disable-writes-'disabled' semantics live server-side in
- * `ElementOps::setStatus()`, which is the exact contract
- * `LayoutAuditExtractor` / `pages_audit` / `template_summary` already read
- * (`content_nodes.status`).
- */
-export async function handleElementSetStatus({ client }, input, extra) {
-    const { template_id, element_path, status, etag } = input;
-    const encoded = encodeElementPath(element_path);
-    const progress = extra ? createProgressReporter(extra) : null;
-    await progress?.report(0, 2, PHASE_SEND);
-    try {
-        const data = await client.put(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/status`, { body: { status }, etag });
-        await progress?.report(2, 2, PHASE_CONFIRM);
-        return jsonResult(data);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id, element_path },
-            hint: 'On 412 refresh via yootheme_builder_get_etag and retry.',
-        });
-    }
-}
-// ─── element_move ────────────────────────────────────────────────────
-export async function handleElementMove({ client }, input, extra) {
-    const { template_id, element_path, to_parent_path, to_index, etag } = input;
-    const encoded = encodeElementPath(element_path);
-    const progress = extra ? createProgressReporter(extra) : null;
-    await progress?.report(0, 2, PHASE_SEND);
-    try {
-        const data = await client.post(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/move`, { body: { to_parent_path, to_index }, etag });
-        await progress?.report(2, 2, PHASE_CONFIRM);
-        return jsonResult(data);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id, element_path, to_parent_path, to_index },
-            hint: 'Verify destination parent accepts the element type. On 412 refresh ' +
-                'ETag and retry.',
-        });
-    }
-}
-// ─── element_clone ───────────────────────────────────────────────────
-export async function handleElementClone({ client }, input, extra) {
-    const { template_id, element_path, etag } = input;
-    const encoded = encodeElementPath(element_path);
-    const progress = extra ? createProgressReporter(extra) : null;
-    await progress?.report(0, 2, PHASE_SEND);
-    try {
-        const data = await client.post(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/clone`, { etag });
-        await progress?.report(2, 2, PHASE_CONFIRM);
-        return jsonResult(data);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id, element_path },
-            hint: 'On 412 refresh via yootheme_builder_get_etag and retry.',
-        });
-    }
-}
-// ─── element_delete (destructive — elicitation + confirm-guard) ─────
-//
-// Wave G.4.1 — destructive confirm via MCP elicitation. Progress
-// reports (Wave G.5) only start AFTER the confirm gate clears.
-// Wave-6 R4 (2026-05-29): Defensive truthiness for the confirm gate.
-// Cold-AI #4 reported the gate kept firing despite `confirm:true`. The Zod
-// schema already coerces only strict booleans (anything non-boolean is
-// rejected upstream as invalid_arguments), but we widen the in-handler
-// check to accept the literal string `"true"` / numeric `1` as a safety net
-// in case a future wrapper round-trips the arg through JSON re-encoding.
-function isConfirmedTrue(v) {
-    if (v === true)
-        return true;
-    if (typeof v === 'string' && v.toLowerCase() === 'true')
-        return true;
-    if (typeof v === 'number' && v === 1)
-        return true;
-    return false;
-}
-function isConfirmedFalse(v) {
-    if (v === false)
-        return true;
-    if (typeof v === 'string' && v.toLowerCase() === 'false')
-        return true;
-    if (typeof v === 'number' && v === 0)
-        return true;
-    return false;
-}
-/**
- * ELEMENT_WRITE-10 — best-effort enrichment of a delete PREVIEW so the human
- * sees WHAT would be deleted, not just a path. Reads the element (try/catch,
- * never blocks the preview on failure) and derives `{element_type, label,
- * descendant_count, text_excerpt}`. Deleting a section can remove 10 descendant
- * nodes; naming them turns "delete element at /children/3" into an informed
- * decision. Returns `{}` on ANY failure so the preview always renders.
- */
-async function bestEffortDeletePreviewDetails(client, template_id, element_path) {
-    try {
-        const data = await client.get(`/pages/${encodeTemplateId(template_id)}/elements/${encodeElementPath(element_path)}`);
-        const elementType = typeof data.element_type === 'string' && data.element_type !== ''
-            ? data.element_type
-            : typeof data.type === 'string'
-                ? data.type
-                : undefined;
-        const label = typeof data.label === 'string' && data.label !== ''
-            ? data.label
-            : typeof data.path_label === 'string' && data.path_label !== ''
-                ? data.path_label
-                : undefined;
-        const descendantCount = countDescendants(data.children);
-        const excerpt = firstTextExcerpt(data.props);
-        const out = {};
-        if (elementType !== undefined)
-            out.element_type = elementType;
-        if (label !== undefined)
-            out.label = label;
-        out.descendant_count = descendantCount;
-        if (excerpt !== undefined)
-            out.text_excerpt = excerpt;
-        return out;
-    }
-    catch {
-        return {};
-    }
-}
-/** Deep-count every descendant node under a `children` array (0 when absent). */
-function countDescendants(children) {
-    if (!Array.isArray(children))
-        return 0;
-    let total = 0;
-    for (const child of children) {
-        if (child !== null && typeof child === 'object' && !Array.isArray(child)) {
-            total += 1;
-            total += countDescendants(child.children);
-        }
-    }
-    return total;
-}
-/** First-line text excerpt from a props map's canonical text carriers, capped. */
-function firstTextExcerpt(props) {
-    if (props === null || typeof props !== 'object' || Array.isArray(props))
-        return undefined;
-    const p = props;
-    for (const key of ['content', 'title', 'text']) {
-        const v = p[key];
-        if (typeof v === 'string' && v.trim() !== '') {
-            const firstLine = v.trim().split('\n')[0] ?? '';
-            return firstLine.length > 80 ? `${firstLine.slice(0, 80)}…` : firstLine;
-        }
-    }
-    return undefined;
-}
-async function resolveDeleteConfirm(client, elicitation, template_id, element_path, confirm) {
-    // Wave-6 R4: explicit truthy check — confirm:true (any form) bypasses
-    // the elicitation/preview path immediately.
-    if (isConfirmedTrue(confirm))
-        return null;
-    // ELEMENT_WRITE-10: only on the PREVIEW path (not a confirmed delete) enrich
-    // the details with WHAT is about to be deleted. Best-effort — never blocks.
-    const enriched = await bestEffortDeletePreviewDetails(client, template_id, element_path);
-    if (isConfirmedFalse(confirm) || !elicitation) {
-        return confirmGuard({
-            operation: 'delete element',
-            details: {
-                template_id,
-                element_path,
-                ...enriched,
-                // R4: echo back what was received so the agent can compare.
-                // Wave-7 (2026-05-29): force-encode undefined to null so the
-                // key survives JSON.stringify in the agent-facing payload.
-                // Without this the agent saw NO received_confirm field at all
-                // (key dropped by serializer) and could not diff sent vs
-                // received — looked like the value was accepted.
-                received_confirm: confirm === undefined ? null : confirm,
-                expected: 'confirm: true (boolean)',
-            },
-        });
-    }
-    const accepted = await elicitConfirmation(elicitation, `Permanently delete element at "${element_path}" in template ` +
-        `"${template_id}"? This cannot be undone.`);
-    return accepted
-        ? null
-        : confirmGuard({
-            operation: 'delete element',
-            details: { template_id, element_path, ...enriched },
-        });
-}
-export async function handleElementDelete({ client, elicitation }, input, extra) {
-    const { template_id, element_path, etag, confirm } = input;
-    const blocked = await resolveDeleteConfirm(client, elicitation, template_id, element_path, confirm);
-    if (blocked)
-        return blocked;
-    const encoded = encodeElementPath(element_path);
-    const progress = extra ? createProgressReporter(extra) : null;
-    await progress?.report(0, 2, PHASE_SEND);
-    try {
-        // Wave-12 / Cold-AI #5 F13 (restored Wave-13 post-merge): forward
-        // `{confirm:true}` as JSON body so the PHP confirm-guard accepts the
-        // delete. Without it the guard returns `requires_confirm:true` and
-        // the caller loops forever.
-        const data = await client.delete(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}`, { etag, body: { confirm: true } });
-        await progress?.report(2, 2, PHASE_CONFIRM);
-        return jsonResult(data);
-    }
-    catch (e) {
-        return errorResult({
-            error: e,
-            context: { template_id, element_path },
-            hint: 'On 412 refresh via yootheme_builder_get_etag and retry. On 404 the ' +
-                'element may already be gone — verify with yootheme_builder_element_list.',
-        });
-    }
-}
-//# sourceMappingURL=handlers-write.js.map