@wootsup/yt-builder-mcp 1.12.0 → 2.1.0

package/dist/tools/elements/schema-validation.js

@@ -1,685 +0,0 @@
-/**
- * Finding B3 — schema-driven write validation for element props.
- *
- * The static `COMMON_PROP_TYPOS` map + `RESERVED_BINDING_KEYS` set in
- * `./handlers-write.ts` only catch a small fixed set of known mistakes. An
- * unknown prop key that is NOT in those tables slips through, the PHP backend
- * silently drops it, and the element renders empty with no signal to the agent
- * (customer B3).
- *
- * This module adds a LIVE cross-check against the element-type's real schema:
- * the authoritative prop keys are `fields[].name` from
- * `GET /element-types/<type>/schema` — the same source the B1
- * `yootheme_builder_element_type_get_schema` tool surfaces (see
- * `../inspection.ts`). When the schema is KNOWN and a key is SURELY unknown,
- * the write is hard-rejected with a Levenshtein `did_you_mean` suggestion.
- *
- * Additive-before-breaking (the plugin is live 1.6.x): every uncertainty —
- * schema fetch failure, unknown schema shape, empty field list — falls THROUGH
- * to the prior behaviour. A schema fetch must NEVER crash the write.
- *
- * @license MIT
- */
-import { errorResult, jsonResult } from '../tool-builder.js';
-/**
- * MCP-side mirror of `Inspector::knownAcceptedButHiddenFields`
- * (`src/modules/builder-inspection/src/Inspector.php`). YT-Pro accepts these
- * props at runtime even though the UI-tab `fieldset` omits them. The PHP
- * `schema()` endpoint already post-merges them into `fields[]`, so a current
- * (1.6.x) plugin schema covers them. This mirror is DEFENSE-IN-DEPTH: against
- * an older plugin whose schema predates that merge, it keeps a genuinely
- * runtime-accepted prop from being false-positive hard-rejected. Keep in sync
- * with the PHP list (deliberately small + ground-truthed).
- */
-export const RUNTIME_ACCEPTED_HIDDEN_PROPS = {
-    button: ['content', 'link'],
-};
-/**
- * Levenshtein edit distance — small pure function (keys are short). Index
- * access is guarded with `?? 0` to satisfy `noUncheckedIndexedAccess`; the
- * row is fully populated at every access so the fallback never fires.
- */
-export function levenshtein(a, b) {
-    const m = a.length;
-    const n = b.length;
-    if (m === 0)
-        return n;
-    if (n === 0)
-        return m;
-    const row = [];
-    for (let j = 0; j <= n; j++)
-        row.push(j);
-    for (let i = 1; i <= m; i++) {
-        let prevDiag = row[0] ?? 0; // distance at (i-1, 0)
-        row[0] = i;
-        for (let j = 1; j <= n; j++) {
-            const above = row[j] ?? 0; // (i-1, j), before overwrite
-            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
-            const deletion = above + 1;
-            const insertion = (row[j - 1] ?? 0) + 1;
-            const substitution = prevDiag + cost;
-            row[j] = Math.min(deletion, insertion, substitution);
-            prevDiag = above;
-        }
-    }
-    return row[n] ?? 0;
-}
-/**
- * Closest real field name for `key`, or `undefined` when nothing is close
- * enough to suggest. Threshold (pinned in tests): `min(max(2, floor(0.4 ·
- * key.length)), key.length - 1)` — always tolerate 1–2 char typos and
- * proportionally more on longer keys, but a suggestion must be CLOSER than the
- * whole key length (M1 clamp), so a wholly-different word is never "suggested".
- */
-export function nearestFieldName(key, fields) {
-    let best;
-    let bestDist = Infinity;
-    for (const field of fields) {
-        const d = levenshtein(key, field);
-        if (d < bestDist) {
-            bestDist = d;
-            best = field;
-        }
-    }
-    if (best === undefined)
-        return undefined;
-    // M1: additionally clamp to STRICTLY less than the key length. A suggestion
-    // must be CLOSER than the whole key — otherwise any very short key would
-    // "match" any other same-length field (`xy` → `id`, distance 2 == length 2).
-    // For longer keys the `key.length - 1` clamp is a no-op; `max(2, …)` keeps
-    // catching 1–2 char typos.
-    const threshold = Math.min(Math.max(2, Math.floor(key.length * 0.4)), key.length - 1);
-    return bestDist <= threshold ? best : undefined;
-}
-/**
- * PAGES_LIBRARY_MEDIA-27 — suggest real field names for an unknown key,
- * combining TWO signals so an obviously-intended key is never missed:
- *
- *   1. PREFIX / SUBSTRING match — a `title` key on a headline should suggest
- *      `title_element` / `title_style` / `title_color`, but char-Levenshtein to
- *      each of those is 6-8 (well over the typo threshold), so the pure-distance
- *      `nearestFieldName` returns nothing. When the unknown key (≥ 3 chars) is a
- *      prefix of — or a substring of — a real field, surface EVERY such field
- *      regardless of edit distance: these are the concrete keys the caller most
- *      likely meant.
- *   2. Levenshtein nearest — the general single/double-char typo case.
- *
- * Prefix matches lead (they are the strongest signal), then substring matches,
- * then the Levenshtein nearest if not already covered. De-duplicated, order
- * preserved. Returns `[]` when nothing is close.
- */
-export function suggestFieldNames(key, fields) {
-    const out = [];
-    const push = (name) => {
-        if (!out.includes(name))
-            out.push(name);
-    };
-    if (key.length >= 3) {
-        // Prefix matches first (`title` → `title_element`, `title_style`, …).
-        for (const field of fields) {
-            if (field !== key && field.startsWith(key))
-                push(field);
-        }
-        // Then substring matches (`color` → `title_color`, `bg_color`).
-        for (const field of fields) {
-            if (field !== key && field.includes(key))
-                push(field);
-        }
-    }
-    // Then the edit-distance nearest for the general typo case.
-    const near = nearestFieldName(key, fields);
-    if (near !== undefined)
-        push(near);
-    return out;
-}
-/**
- * Pull the full `fields[]` list out of the element-type schema response.
- * Mirrors the envelope handling in `../inspection.ts`: the type schema nests
- * under `schema`, with a top-level fallback for older backends.
- *
- * @returns the field list (possibly empty), or `null` when the response
- *   carries no `fields` array at all (unknown schema shape → treat as unknown).
- */
-export function extractSchemaFields(data) {
-    if (data === null || typeof data !== 'object')
-        return null;
-    const obj = data;
-    const schema = obj.schema !== null && typeof obj.schema === 'object'
-        ? obj.schema
-        : obj;
-    const rawFields = schema.fields;
-    if (!Array.isArray(rawFields))
-        return null;
-    const fields = [];
-    for (const raw of rawFields) {
-        if (raw === null || typeof raw !== 'object')
-            continue;
-        const f = raw;
-        const name = f.name;
-        if (typeof name !== 'string' || name === '')
-            continue;
-        const field = { name };
-        if (typeof f.type === 'string' && f.type !== '')
-            field.type = f.type;
-        if (Array.isArray(f.enum)) {
-            // Mirrors Inspector::extractEnum's PHP-side coercion
-            // (is_string/is_int/is_bool → (string) cast) so a wire response
-            // that carries raw scalars instead of pre-stringified values is
-            // still usable.
-            const enumValues = f.enum
-                .filter((v) => typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
-                .map((v) => String(v));
-            if (enumValues.length > 0)
-                field.enum = enumValues;
-        }
-        if ('default' in f)
-            field.default = f.default;
-        fields.push(field);
-    }
-    return fields;
-}
-/**
- * Pull `fields[].name` out of the element-type schema response. Thin
- * name-only projection of {@link extractSchemaFields} — kept as its own
- * export because every EXISTING caller/test only needs the name list.
- *
- * @returns the field-name list (possibly empty), or `null` when the response
- *   carries no `fields` array at all (unknown schema shape → treat as unknown).
- */
-export function extractSchemaFieldNames(data) {
-    const fields = extractSchemaFields(data);
-    return fields === null ? null : fields.map((f) => f.name);
-}
-/**
- * Best-effort fetch of an element-type's full field schema. ANY failure
- * (network, non-2xx, unknown shape) resolves to `null` so the caller falls
- * through to the prior behaviour — a schema fetch must never break the write.
- */
-export async function fetchSchemaFields(client, elementType) {
-    try {
-        const data = await client.get(`/element-types/${encodeURIComponent(elementType)}/schema`);
-        return extractSchemaFields(data);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Best-effort fetch of an element-type's real prop keys. Name-only
- * projection of {@link fetchSchemaFields} — kept as its own export for
- * existing callers that only need the key list.
- */
-export async function fetchSchemaFieldNames(client, elementType) {
-    const fields = await fetchSchemaFields(client, elementType);
-    return fields === null ? null : fields.map((f) => f.name);
-}
-/**
- * Validate `props` against the element-type's LIVE schema. Returns an
- * `errorResult` ONLY when the schema is surely known (non-empty field list) AND
- * at least one prop key is surely unknown; otherwise `null` (pass / fall
- * through). Reserved binding keys are skipped here — their dedicated guard runs
- * first and keeps priority.
- */
-export async function validatePropsAgainstLiveSchema(opts) {
-    const { client, elementType, props, reservedKeys } = opts;
-    if (props === undefined || props === null)
-        return null;
-    const keys = Object.keys(props);
-    if (keys.length === 0)
-        return null;
-    const fields = opts.fields !== undefined ? opts.fields : await fetchSchemaFields(client, elementType);
-    // null = schema unknown / fetch failed; [] = present-but-empty. Both are
-    // "uncertain" → never hard-reject.
-    if (fields === null || fields.length === 0)
-        return null;
-    const fieldNames = fields.map((f) => f.name);
-    // Accepted set = live schema fields ∪ the runtime-accepted-hidden mirror.
-    const accepted = new Set(fieldNames);
-    for (const extra of RUNTIME_ACCEPTED_HIDDEN_PROPS[elementType] ?? []) {
-        accepted.add(extra);
-    }
-    const unknownKeys = [];
-    for (const key of keys) {
-        if (reservedKeys.has(key))
-            continue; // dedicated guard owns these
-        if (accepted.has(key))
-            continue;
-        unknownKeys.push(key);
-    }
-    if (unknownKeys.length === 0)
-        return null;
-    // did_you_mean only for keys with a genuinely-close real field. Never
-    // fabricate a suggestion (a wholly-different key gets no `did_you_mean`).
-    // PAGES_LIBRARY_MEDIA-27: prefix/substring matches join the Levenshtein
-    // nearest, so `title` on a headline now suggests title_element/title_style/
-    // title_color instead of returning nothing.
-    const didYouMean = {};
-    const suggestionParts = [];
-    let firstNear;
-    for (const key of unknownKeys) {
-        const suggestions = suggestFieldNames(key, fieldNames);
-        if (suggestions.length > 0) {
-            didYouMean[key] = suggestions;
-            suggestionParts.push(`\`${key}\` → ${suggestions.map((s) => `\`${s}\``).join('/')}`);
-            if (firstNear === undefined)
-                firstNear = suggestions[0];
-        }
-    }
-    const hasSuggestions = suggestionParts.length > 0;
-    const unknownList = unknownKeys.map((k) => `\`${k}\``).join(', ');
-    return errorResult({
-        error: new Error(`Unknown prop key(s) for element type \`${elementType}\`: ${unknownList}. ` +
-            (hasSuggestions ? `Did you mean ${suggestionParts.join(', ')}? ` : '') +
-            `These keys are not in the element's live schema (fields[].name), so YT-Pro ` +
-            `silently drops them server-side and the element would render empty. ` +
-            `Call yootheme_builder_element_type_get_schema({ element_type: "${elementType}" }) ` +
-            `for the canonical prop keys.`),
-        context: {
-            element_type: elementType,
-            unknown_prop_keys: unknownKeys,
-            ...(hasSuggestions ? { did_you_mean: didYouMean } : {}),
-            valid_prop_keys: fieldNames,
-        },
-        hint: `Re-try with a canonical prop key` +
-            (firstNear !== undefined ? ` (e.g. \`${firstNear}\`)` : '') +
-            `, or fetch the schema first: ` +
-            `yootheme_builder_element_type_get_schema({ element_type: "${elementType}" }).`,
-    });
-}
-// ─── Ordering-red-border fix (2026-07-25) ─────────────────────────────
-//
-// Root cause: `element_add` forwards ONLY the caller-supplied `props`
-// verbatim. YOOtheme's OWN native element-creation additionally initialises
-// every REQUIRED enum field (a `select`/dropdown whose schema `enum` does
-// NOT list `''` as a member — the same "required" definition the PHP-side
-// UiInvariantValidator uses for its `required_field_empty` check) to its
-// schema `default`. An element created via element_add without e.g. an
-// "Ordering" prop therefore has NO value at all for that required dropdown,
-// and YOOtheme's Vue Builder flags the empty required control red.
-//
-// Two functions close this, both scoped to element_add's CREATE path only
-// (element_update_settings is deliberately untouched — an update may
-// legitimately clear a field, so injecting a default there would silently
-// fight the caller):
-//   - `seedRequiredEnumDefaults` fills in the schema default ONLY for a
-//     required-enum field the caller did not supply at all. A caller-
-//     supplied value (valid or not) is NEVER touched here.
-//   - `validateEnumPropValues` hard-rejects a caller-supplied value for a
-//     KNOWN enum-constrained field that is not one of its accepted members
-//     — closing the create-path KEY-only gap `validatePropsAgainstLiveSchema`
-//     deliberately leaves open (it only checks the KEY is known, never the
-//     VALUE).
-/**
- * A field is "required" in the same sense the PHP-side `UiInvariantValidator`
- * uses for its `required_field_empty` violation: it is enum-constrained (a
- * non-empty `enum` list) and that list does NOT contain `''` — an optional
- * select always lists `''` as its "nothing selected" member.
- */
-export function isRequiredEnumField(field) {
-    return field.enum !== undefined && field.enum.length > 0 && !field.enum.includes('');
-}
-/** A schema `default` that is actually usable as a seeded value — present and non-empty. */
-function hasUsableDefault(field) {
-    return field.default !== undefined && field.default !== null && field.default !== '';
-}
-/**
- * Seed every REQUIRED enum field (see {@link isRequiredEnumField}) that
- * declares a non-empty schema `default` and is ABSENT from `props` with that
- * default — mirroring what YOOtheme's own native element-creation
- * initialises. A field the caller already supplied a key for (any value,
- * including one later hard-rejected by {@link validateEnumPropValues}) is
- * never touched: the caller's own value ALWAYS wins, no coercion, ever. An
- * element type with no schema default for a field gets nothing invented for
- * it — the seed set only ever pulls from real schema data.
- *
- * Returns `props` UNCHANGED (same reference, possibly `undefined`) when
- * there is nothing to seed, so a no-op call never allocates a new object.
- */
-export function seedRequiredEnumDefaults(fields, props) {
-    const seeds = {};
-    for (const field of fields) {
-        if (!isRequiredEnumField(field))
-            continue;
-        if (!hasUsableDefault(field))
-            continue;
-        if (props !== undefined && Object.prototype.hasOwnProperty.call(props, field.name))
-            continue;
-        seeds[field.name] = field.default;
-    }
-    if (Object.keys(seeds).length === 0)
-        return props;
-    return { ...seeds, ...(props ?? {}) };
-}
-/**
- * YOOtheme persists a BOOLEAN shorthand (true/false/"true"/"false"/1/0/'1'/'0')
- * in several fields our schema-derivation would otherwise classify as a plain
- * enum-value mismatch (e.g. a link's `link_target: true`, the "open in a new
- * window" checkbox, on a field whose enum is `_blank`/`_self`/…). Mirrors
- * `UiInvariantValidator::isBooleanish` (PHP) so this pre-flight is never
- * STRICTER than the server-side guard the write would hit anyway.
- */
-function isBooleanishEnumValue(value) {
-    return (typeof value === 'boolean' ||
-        value === 1 ||
-        value === 0 ||
-        value === '1' ||
-        value === '0' ||
-        value === 'true' ||
-        value === 'false');
-}
-/**
- * Hard-reject a prop VALUE the caller explicitly supplied for a KNOWN
- * enum-constrained field when that value is not one of the field's declared
- * `enum` members. `validatePropsAgainstLiveSchema` only ever checks that a
- * prop KEY is known — this is the VALUE half, scoped to element_add's create
- * path only (see the section banner above for why).
- *
- * An empty value (`''` / `null` / `undefined`) is deliberately NOT judged
- * here — persisting an empty value on a required field is a DIFFERENT
- * violation (`required_field_empty`) the PHP write guard already owns; this
- * function only judges a genuinely non-empty value against enum membership.
- * A non-scalar value (a dynamic-binding shape) is skipped — it cannot be
- * safely compared against a string enum and is not this function's concern.
- *
- * Returns `null` (pass) whenever the field is unknown to the given `fields`
- * list or is not enum-constrained — this is a value check layered ON TOP of
- * the key check, never a whitelist on its own.
- */
-export function validateEnumPropValues(opts) {
-    const { elementType, fields, props, reservedKeys } = opts;
-    if (props === undefined || props === null)
-        return null;
-    const byName = new Map(fields.map((f) => [f.name, f]));
-    for (const [key, value] of Object.entries(props)) {
-        if (reservedKeys.has(key))
-            continue; // dedicated guard owns these
-        if (value === '' || value === null || value === undefined)
-            continue; // required_field_empty is the PHP guard's concern
-        if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
-            continue;
-        if (isBooleanishEnumValue(value))
-            continue;
-        const field = byName.get(key);
-        if (field === undefined || field.enum === undefined || field.enum.length === 0)
-            continue;
-        if (field.enum.includes(String(value)))
-            continue;
-        return errorResult({
-            error: new Error(`Invalid value for prop \`${key}\` on element type \`${elementType}\`: ` +
-                `${JSON.stringify(value)} is not one of its accepted values. ` +
-                `Valid values: ${field.enum.map((v) => `\`${v}\``).join(', ')}.`),
-            context: {
-                element_type: elementType,
-                field: key,
-                given_value: value,
-                valid_values: field.enum,
-            },
-            hint: `Use one of the valid values, or fetch the schema: ` +
-                `yootheme_builder_element_type_get_schema({ element_type: "${elementType}" }).`,
-        });
-    }
-    return null;
-}
-// ─── Transparent-header write guard (Task 6, 2026-07-27) ─────────────
-//
-// YOOtheme's transparent header lives in three props on a `section`
-// (`header_transparent`, `_noplaceholder`, `_text_color`). The plan's policy
-// is that a transparent header is a deliberate EXCEPTION, never a default, and
-// that whoever turns it on picks the colour deliberately — with no deliberate
-// choice the colour is `''` (the theme default), NEVER `'light'` (which is
-// white navigation text, and recolours even over a flat theme background).
-//
-// This guard is the CLIENT-SIDE half. What it may decide is bounded by what
-// it can KNOW, which is the whole design:
-//
-//   - **Class A (dead props) is theme-INDEPENDENT.** `_text_color` /
-//     `_noplaceholder` on a section whose master switch is off are never read
-//     by YOOtheme — dead whatever the theme declares. So this surface, which
-//     can never read `theme.css`, still rejects them. (Ratified for this
-//     surface by the plan's Task-6 scope; the evaluator docblock in
-//     `HeaderContrastEvaluator.php` records the open fail-open question.)
-//   - **Class B (the layout contradicts the theme's own `--uk-inverse`) needs
-//     the compiled `theme.css`.** TypeScript cannot read it, so class B is NOT
-//     approximated here — it stays with `pages_audit` /
-//     `header_transparency_set`, where the declaration IS readable. Guessing
-//     it client-side would be exactly the invented judgment the plan forbids.
-//   - **Class C (a hero image/video covers the section background) is allowed
-//     with a warning**, never rejected: over a medium no colour is provable
-//     from props and none is safer than another, so the only valid proof is
-//     looking at the rendered page.
-//
-// The SECOND bound is the write's own merge semantics. `element_update_settings`
-// replaces props by default and deep-merges only on `merge:true`
-// (`ElementsController::updateSettings`). A merge payload that omits the master
-// switch therefore says NOTHING about the resulting state — so nothing is
-// rejected and nothing is seeded there. "Not decidable" is a legitimate answer;
-// a false reject on a partial update would be worse than the hole it closes.
-//
-// ONE chokepoint: `handleElementUpdateSettings` calls this and nothing else
-// re-implements it (mirroring the API Mapper Library-First-Guard, which runs at
-// `createConnection` only). `element_add`'s create path is deliberately NOT a
-// second call site — a section created with dead props is caught by the
-// server-side `pages_audit` check, which can also see whether it is the FIRST
-// section (`a2`, the other half of class A, is undecidable from a single
-// element payload and stays server-side too).
-const HEADER_TRANSPARENT_PROP = 'header_transparent';
-const HEADER_TRANSPARENT_TEXT_COLOR_PROP = 'header_transparent_text_color';
-const HEADER_TRANSPARENT_NOPLACEHOLDER_PROP = 'header_transparent_noplaceholder';
-/** The two props that can put a backdrop in front of the theme's own background. */
-const HEADER_MEDIA_PROPS = ['image', 'video'];
-/**
- * Strict-boolean truthiness set — a byte-for-byte mirror of
- * `HeaderContrastFacts::TRUTHY_STRINGS` (PHP). Only genuine true-ish values
- * engage, so the raw-JSON strings `"false"` / `"0"` can never read as true (a
- * loose `!!value` would, which is the bypass the API Mapper Library-First-Guard's
- * `acknowledge_no_library` closed).
- */
-const HEADER_TRUTHY_STRINGS = ['1', 'true', 'yes', 'on'];
-/** Mirror of `HeaderContrastFacts::isTruthyFlag`. */
-function isHeaderTruthyFlag(value) {
-    if (typeof value === 'boolean')
-        return value;
-    if (typeof value === 'number')
-        return value === 1;
-    if (typeof value === 'string')
-        return HEADER_TRUTHY_STRINGS.includes(value.trim().toLowerCase());
-    return false;
-}
-/**
- * Mirror of `HeaderContrastFacts::readTextColor` — an unrecognised value
- * degrades to `''`. A colour this code does not understand is not a colour it
- * may act on (and rejecting a garbage enum value is
- * {@link validateEnumPropValues}' job, not this guard's).
- */
-function readHeaderTextColor(value) {
-    if (typeof value !== 'string')
-        return '';
-    const normalised = value.trim().toLowerCase();
-    if (normalised === 'light')
-        return 'light';
-    if (normalised === 'dark')
-        return 'dark';
-    return '';
-}
-/** Mirror of `HeaderContrastFacts::isPresent` — does a media prop carry an actual backdrop? */
-function isHeaderMediaPresent(value) {
-    if (value === null || value === undefined || value === false)
-        return false;
-    if (typeof value === 'string')
-        return value.trim() !== '';
-    if (Array.isArray(value))
-        return value.length > 0;
-    if (typeof value === 'object')
-        return Object.keys(value).length > 0;
-    if (typeof value === 'number')
-        return value !== 0;
-    return true;
-}
-/**
- * Resolve one prop's state AFTER the write, honouring merge semantics.
- *
- * @param present a reader for "the payload states this key" → its value
- * @param replaces `true` when the write REPLACES all props (the default), so an
- *        absent key means the prop ends up absent; `false` (merge) means an
- *        absent key leaves the stored value — unknowable from here.
- */
-function resolveAfterWrite(props, key, unset, replaces, read, absent) {
-    if (Object.prototype.hasOwnProperty.call(props, key))
-        return read(props[key]);
-    if (unset.has(key))
-        return absent; // explicitly removed → YOOtheme's default
-    return replaces ? absent : 'unknown';
-}
-/** Media backdrop after the write: `true` if either media prop ends up set. */
-function resolveMediaBackdrop(props, unset, replaces) {
-    let anyUnknown = false;
-    for (const key of HEADER_MEDIA_PROPS) {
-        const resolved = resolveAfterWrite(props, key, unset, replaces, isHeaderMediaPresent, false);
-        if (resolved === true)
-            return true;
-        if (resolved === 'unknown')
-            anyUnknown = true;
-    }
-    return anyUnknown ? 'unknown' : false;
-}
-/**
- * The class-A reject. Error shape mirrors the API Mapper Library-First-Guard:
- * the human-readable instruction rides INSIDE `error` (the only leg some MCP
- * plumbing surfaces), with a machine-readable `error_code` alongside it.
- */
-function deadPropRejection(deadProps, elementPath, masterSwitchStatedOff) {
-    const list = deadProps.map((p) => `\`${p}\``).join(', ');
-    const why = masterSwitchStatedOff
-        ? 'this write leaves `header_transparent` off'
-        : 'this write does not set `header_transparent` (a full-replace update drops every prop it omits, '
-            + 'so the master switch ends up off)';
-    return jsonResult({
-        error: `Dead transparent-header prop(s) ${list} at \`${elementPath}\`: ${why}, and YOOtheme reads `
-            + `${list} ONLY while \`header_transparent\` is true. The write would store configuration `
-            + `that looks applied and never is — no error, no builder warning. Either set `
-            + `\`header_transparent: true\` DELIBERATELY in the same call (a transparent header is the `
-            + `exception, not a default — leave it off when in doubt), or drop ${list} from the props. `
-            + `To inspect or repair the transparent header properly use `
-            + `yootheme_builder_header_transparency_set({ template_id: "<id>" }) — it targets the FIRST `
-            + `section by itself (YOOtheme reads these props there only) and dry-runs by default.`,
-        error_code: 'header_transparent_dead_prop',
-        context: {
-            element_path: elementPath,
-            dead_prop_keys: [...deadProps],
-            master_switch: HEADER_TRANSPARENT_PROP,
-        },
-        hint: 'Re-send without the dead prop(s), or add `header_transparent: true` when the customer '
-            + 'actually asked for a transparent header. Prefer '
-            + 'yootheme_builder_header_transparency_set (advanced gateway) — it also checks the '
-            + 'first-section rule and the theme\'s own --uk-inverse declaration, neither of which is '
-            + 'readable from here.',
-    }, { isError: true });
-}
-/**
- * Guard a props write against the transparent-header failure modes.
- *
- * Pure: takes the write's own payload (plus its merge/unset semantics) and
- * returns a rejection, the props to send, and any warnings. No I/O — it never
- * needs the element type either, because the three props are namespaced and
- * exist on `section` alone.
- */
-export function guardHeaderTransparencyWrite(opts) {
-    const { props, elementPath } = opts;
-    const pass = { rejection: null, props, warnings: [] };
-    if (props === undefined || props === null || typeof props !== 'object')
-        return pass;
-    const touchesHeader = Object.prototype.hasOwnProperty.call(props, HEADER_TRANSPARENT_PROP)
-        || Object.prototype.hasOwnProperty.call(props, HEADER_TRANSPARENT_TEXT_COLOR_PROP)
-        || Object.prototype.hasOwnProperty.call(props, HEADER_TRANSPARENT_NOPLACEHOLDER_PROP);
-    // A write that mentions none of the three props changes nothing about the
-    // transparent header — leave it completely alone (same props reference).
-    if (!touchesHeader)
-        return pass;
-    const replaces = opts.merge !== true;
-    const unset = new Set(opts.unset ?? []);
-    const transparent = resolveAfterWrite(props, HEADER_TRANSPARENT_PROP, unset, replaces, isHeaderTruthyFlag, false);
-    const textColor = resolveAfterWrite(props, HEADER_TRANSPARENT_TEXT_COLOR_PROP, unset, replaces, readHeaderTextColor, '');
-    const noPlaceholder = resolveAfterWrite(props, HEADER_TRANSPARENT_NOPLACEHOLDER_PROP, unset, replaces, isHeaderTruthyFlag, false);
-    // ── Class A (a1): a prop YOOtheme will never read ──────────────────
-    if (transparent === false) {
-        const dead = [];
-        if (textColor !== 'unknown' && textColor !== '')
-            dead.push(HEADER_TRANSPARENT_TEXT_COLOR_PROP);
-        if (noPlaceholder === true)
-            dead.push(HEADER_TRANSPARENT_NOPLACEHOLDER_PROP);
-        if (dead.length > 0) {
-            return {
-                rejection: deadPropRejection(dead, elementPath, Object.prototype.hasOwnProperty.call(props, HEADER_TRANSPARENT_PROP)
-                    || unset.has(HEADER_TRANSPARENT_PROP)),
-                props,
-                warnings: [],
-            };
-        }
-    }
-    // Everything below only applies once the header IS transparent afterwards.
-    if (transparent !== true)
-        return pass;
-    const warnings = [];
-    let outProps = props;
-    // ── The safe default: '' (the theme's own), never 'light' ─────────
-    const statesColour = Object.prototype.hasOwnProperty.call(props, HEADER_TRANSPARENT_TEXT_COLOR_PROP);
-    if (!statesColour) {
-        if (textColor === 'unknown') {
-            // merge:true — the stored colour is unreadable from here. Seeding
-            // '' would CLOBBER a value that was set deliberately (or measured
-            // over a hero medium), so say so instead of acting on a guess.
-            warnings.push({
-                code: 'header_transparent_text_color_unstated',
-                message: 'This merge update turns the transparent header ON without stating '
-                    + '`header_transparent_text_color`, and the stored value cannot be read from here — so '
-                    + 'nothing was seeded. State the colour explicitly (`""` = the theme default; `"light"` '
-                    + 'is WHITE navigation text and is never a safe guess), or use '
-                    + 'yootheme_builder_header_transparency_set, which reads the theme\'s own --uk-inverse '
-                    + 'declaration.',
-            });
-        }
-        else if (!unset.has(HEADER_TRANSPARENT_TEXT_COLOR_PROP)) {
-            // Full replace: the resulting props would carry no colour at all.
-            // Record the theme default EXPLICITLY so the layout states the
-            // deliberate choice — and so nothing downstream fills in 'light'.
-            outProps = { ...props, [HEADER_TRANSPARENT_TEXT_COLOR_PROP]: '' };
-            warnings.push({
-                code: 'header_transparent_text_color_defaulted',
-                message: 'The transparent header was turned on without a colour, so '
-                    + '`header_transparent_text_color` was written as `""` — the theme\'s own default for '
-                    + 'this section style. It is never defaulted to `"light"`, which is WHITE navigation '
-                    + 'text and recolours even over a flat theme background. To choose deliberately, read '
-                    + 'the theme declaration via yootheme_builder_header_transparency_set (dry run).',
-            });
-        }
-    }
-    // ── Class C: a medium hides the background the theme describes ────
-    if (resolveMediaBackdrop(props, unset, replaces) === true) {
-        warnings.push({
-            code: 'header_contrast_unverifiable_over_media',
-            message: 'This section has an image or video behind the transparent header. The medium covers '
-                + 'exactly the background the theme\'s --uk-inverse declaration describes, so NO navigation '
-                + 'colour is verifiable from the props here and none is safer than another (not even `""`). '
-                + 'Nothing was changed or recommended: LOOK at the rendered page at the customer\'s '
-                + 'viewport — unscrolled AND after scrolling, because a sticky header drops its '
-                + 'transparency — and set what you SAW.',
-        });
-    }
-    return { rejection: null, props: outProps, warnings };
-}
-/**
- * Merge client-side warnings into a REST response body so a successful write
- * still carries them. A non-object body (or an empty warning list) is returned
- * untouched, so nothing that has no place to put them is reshaped.
- */
-export function withHeaderTransparencyWarnings(data, warnings) {
-    if (warnings.length === 0)
-        return data;
-    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
-        return { data, warnings: [...warnings] };
-    }
-    const existing = data.warnings;
-    const merged = Array.isArray(existing) ? [...existing, ...warnings] : [...warnings];
-    return { ...data, warnings: merged };
-}
-//# sourceMappingURL=schema-validation.js.map