@wootsup/yt-builder-mcp 1.1.7 → 1.3.0

package/dist/tools/sources/handlers-bind.js

@@ -9,10 +9,175 @@
  * @license MIT
  */
 import { elicitChoice, elicitConfirmation } from '@getimo/mcp-toolkit';
-import { encodeElementPath } from '../../client.js';
+import { encodeElementPath, encodeTemplateId } from '../../client.js';
+import { RestError } from '../../errors.js';
 import { flattenSourcesPayload, mapSourceRow, } from '../format/sources-format.js';
 import { ambiguityFallbackError, } from '../elicitation.js';
 import { confirmGuard, errorResult, jsonResult, } from '../tool-builder.js';
+import { GRID_ITEM_ITERATOR_REJECT, SLOT_COLLISION_STEERING, } from '../bind-guidance.js';
+/**
+ * Wave-12 F9 — extract validation-hint fields surfaced by the WP REST
+ * plugin when `source_name` is rejected (`unknown_source` code). The PHP
+ * controller writes `given`, `did_you_mean`, and `all_published_sources`
+ * into the WP_Error data; WordPress serialises that under the response
+ * body's `data` key. Surface those hints into the tool-result `context`
+ * so the agent can correct + retry in one step.
+ */
+function extractUnknownSourceHints(body) {
+    if (body === null || typeof body !== 'object')
+        return null;
+    const root = body;
+    if (root.code !== 'yootheme_builder_mcp.source_binding.unknown_source')
+        return null;
+    const data = root.data;
+    if (data === null || typeof data !== 'object')
+        return null;
+    const d = data;
+    return {
+        given: typeof d.given === 'string' ? d.given : undefined,
+        did_you_mean: d.did_you_mean,
+        all_published_sources: d.all_published_sources,
+    };
+}
+/**
+ * F189 — true iff the REST error body is the slot-collision reject (409). The
+ * WP plugin writes `code` = `…source_binding.slot_collision`; both platforms
+ * also carry `data.error_code === 'slot_collision'` (WordPress nests hint data
+ * under `data`; the Joomla envelope surfaces the same `error_code`).
+ */
+function isSlotCollision(body) {
+    if (body === null || typeof body !== 'object')
+        return false;
+    const root = body;
+    if (typeof root.code === 'string' &&
+        root.code.endsWith('source_binding.slot_collision')) {
+        return true;
+    }
+    if (root.error_code === 'slot_collision')
+        return true;
+    const data = root.data;
+    if (data !== null && typeof data === 'object') {
+        return data.error_code === 'slot_collision';
+    }
+    return false;
+}
+/** Pull a `list<string>` from a passthrough body field, or `[]`. */
+function stringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((k) => typeof k === 'string');
+}
+/**
+ * F174 — the bind succeeded but with ZERO field mappings: each of the N
+ * cloned items will render only the template's static placeholder text
+ * ("Title" / "Lorem ipsum"), not real data. This is a silent footgun: a
+ * caged agent bound source_name + bindingLevel only, the call returned 200
+ * + binding_level:"item", and element_get_binding reported a healthy-looking
+ * binding — but the frontend showed N identical placeholder cards. The
+ * warning is NOT a hard reject (a first bind of just the source can be a
+ * legitimate intermediate step), but it must be unmissable.
+ *
+ * `hadMappings` is true when the bind REQUEST carried a non-empty
+ * field_mappings object. We fire only when the request had no mappings AND
+ * the response did not report any dropped mappings (a re-bind that shrinks an
+ * existing map keeps real data on the kept props — that is the F147 warning's
+ * territory, not this one).
+ */
+function zeroFieldMappingsWarning() {
+    return ('0 field mappings bound — the cloned items will render the template\'s ' +
+        'static placeholder texts (Title / Lorem ipsum), not real data. ' +
+        'Re-bind with field_mappings AT THIS ITEM (call element_bind_source ' +
+        'again on THIS same element_path with a non-empty ' +
+        'field_mappings:{<element_prop>:<source_field>}). Do NOT bind the ' +
+        'individual child leaves instead: on YT5 a "#parent" leaf bind written ' +
+        'directly under an iterating item renders placeholder text — the ' +
+        'field_mappings-at-the-item form is the shape that resolves. Discover ' +
+        'props via yootheme_builder_element_type_get_schema, source fields via ' +
+        'apimapper_yootheme_binding_for_flow.');
+}
+/**
+ * F129 + F147 + F174 — when the REST plugin's bind response carries
+ * `unknown_prop_keys` (field_mappings keys the target element-type does
+ * not render) and/or `dropped_field_mappings` (leaves the new, smaller
+ * field_mappings dropped from the prior binding — full replace, not
+ * merge), promote them to a TOP-LEVEL `warning` string so both silent-
+ * footgun signals are the first thing the agent sees. F174: when the bind
+ * persisted a source binding with ZERO field mappings (request had none and
+ * none were dropped), promote the placeholder-render footgun warning too.
+ * Returns the body unchanged when no signal is present (no warning on the
+ * happy path).
+ */
+function withBindWarnings(body, hadMappings) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return body;
+    const root = body;
+    const unknownKeys = stringList(root.unknown_prop_keys);
+    const droppedKeys = stringList(root.dropped_field_mappings);
+    const parts = [];
+    if (unknownKeys.length > 0) {
+        parts.push(`These field_mappings keys are not props the target element renders, ` +
+            `so their values will be silently dropped: ${unknownKeys.join(', ')}. ` +
+            `Run yootheme_builder_element_type_get_schema for valid prop names ` +
+            `(see unknown_prop_keys_did_you_mean for suggestions), or re-bind onto ` +
+            `an element that exposes these props.`);
+    }
+    // G2 (WF1 Phase-2) — the VALUE-side mirror of unknown_prop_keys. A
+    // field_mappings VALUE that names a source-field the bound flow does NOT
+    // emit binds to nothing → the bind returns 200 but the element renders
+    // blank. The PHP chokepoint is the only place that resolves BOTH the
+    // source's field set AND the target element, so it flags these as
+    // `unknown_source_field_values` (with the available set in
+    // `unknown_source_field_values_available`). Promote both into the
+    // top-level warning so the agent sees which field is wrong AND the
+    // valid choices, in one step.
+    const unknownFieldValues = stringList(root.unknown_source_field_values);
+    if (unknownFieldValues.length > 0) {
+        const available = stringList(root.unknown_source_field_values_available);
+        const availableHint = available.length > 0
+            ? ` Available source fields: ${available.join(', ')}.`
+            : '';
+        parts.push(`These field_mappings values name source fields the bound source does ` +
+            `not emit, so they bind to nothing (the element renders blank): ` +
+            `${unknownFieldValues.join(', ')}.${availableHint} Re-bind with a ` +
+            `source-field name the flow actually emits — list them via ` +
+            `apimapper_yootheme_binding_for_flow.`);
+    }
+    if (droppedKeys.length > 0) {
+        parts.push(`field_mappings is a full REPLACE, not a merge — this re-bind dropped ` +
+            `the previously-bound prop(s): ${droppedKeys.join(', ')}. If that was ` +
+            `unintended, re-bind with the full set (include the dropped keys).`);
+    }
+    // F174 — only when the request bound a source with no mappings AND no
+    // prior mappings were dropped. A bind that dropped keys still kept real
+    // data on the survivors → not a zero-mappings placeholder situation.
+    if (!hadMappings && droppedKeys.length === 0 && bindPersistedSource(root)) {
+        parts.push(zeroFieldMappingsWarning());
+    }
+    // F189 — the bind landed a `…List` source on a LEAF renderer (grid_item /
+    // any non-container) that ALSO carries nested children. The item's own slot
+    // bind resolved, but its nested children are render-dead (the template never
+    // renders them). Promote the reject-recipe text so the agent fixes the shape
+    // instead of shipping a placeholder grid.
+    if (root.iterator_is_leaf_renderer === true) {
+        parts.push(GRID_ITEM_ITERATOR_REJECT);
+    }
+    if (parts.length === 0)
+        return body;
+    return { ...root, warning: parts.join(' ') };
+}
+/**
+ * F174 — did the bind response persist an actual source binding (vs an
+ * unbind / no-op)? True when the response `binding.source_name` (or the
+ * top-level `source_name`) is a non-empty string. Guards the zero-mappings
+ * warning so it never fires on an unbind echo.
+ */
+function bindPersistedSource(root) {
+    const fromBinding = root.binding !== null && typeof root.binding === 'object' && !Array.isArray(root.binding)
+        ? root.binding.source_name
+        : undefined;
+    const name = typeof fromBinding === 'string' ? fromBinding : root.source_name;
+    return typeof name === 'string' && name.length > 0;
+}
 // ─── element_bind_source (G.4.3 — ambiguity resolution) ─────────────
 /**
  * Look up sources matching `source_name`. Returns at most one row per
@@ -82,13 +247,62 @@ export async function handleElementBindSource({ client, elicitation }, input) {
         resolvedBody = { ...resolvedBody, source_id };
     }
     try {
-        const data = await client.put(`/pages/${encodeURIComponent(template_id)}/elements/${encoded}/binding`, { body: resolvedBody, etag });
-        return jsonResult(data);
+        const data = await client.put(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/binding`, { body: resolvedBody, etag });
+        // F129 + F147 + F174 — the bind persisted (200), but the REST plugin
+        // may have flagged field_mappings keys the target element-type does
+        // not render (`unknown_prop_keys`) and/or leaves the new, smaller
+        // map dropped from the prior binding (`dropped_field_mappings` —
+        // full replace, not merge); and the bind may have persisted a source
+        // with ZERO field mappings (renders only template placeholders).
+        // All are silent footguns at render time. Lift them into a TOP-LEVEL
+        // warning so the agent notices and corrects, rather than leaving the
+        // signal buried in the passthrough body.
+        const hadMappings = field_mappings !== undefined && Object.keys(field_mappings).length > 0;
+        return jsonResult(withBindWarnings(data, hadMappings));
     }
     catch (e) {
+        // Wave-12 F9 — surface unknown-source hints directly into the
+        // result context so the agent can correct the source_name and
+        // retry in one step instead of guessing.
+        const baseContext = {
+            template_id,
+            element_path,
+            source_name,
+            ...(source_id ? { source_id } : {}),
+        };
+        if (e instanceof RestError) {
+            // F189 — slot collision (409): two fields would land on the same
+            // parent prop slot during F188 consolidation, OR the lifted key is
+            // not a slot of the parent type. The server's message already names
+            // the slot + recipe; surface the canonical steering as the hint so
+            // the agent gives each field its own leaf / a distinct slot.
+            if (isSlotCollision(e.body)) {
+                return errorResult({
+                    error: e,
+                    context: baseContext,
+                    hint: SLOT_COLLISION_STEERING,
+                });
+            }
+            const hints = extractUnknownSourceHints(e.body);
+            if (hints !== null) {
+                if (hints.did_you_mean !== undefined) {
+                    baseContext.did_you_mean = hints.did_you_mean;
+                }
+                if (hints.all_published_sources !== undefined) {
+                    baseContext.all_published_sources = hints.all_published_sources;
+                }
+                return errorResult({
+                    error: e,
+                    context: baseContext,
+                    hint: 'source_name does not match any published source. Pick from ' +
+                        '`all_published_sources` (full list) or `did_you_mean` (closest matches) ' +
+                        'in the context, or run yootheme_builder_sources_list to refresh.',
+                });
+            }
+        }
         return errorResult({
             error: e,
-            context: { template_id, element_path, source_name, ...(source_id ? { source_id } : {}) },
+            context: baseContext,
             hint: 'Verify source_name via yootheme_builder_sources_list. On 412 ' +
                 'refresh ETag and retry.',
         });
@@ -115,7 +329,7 @@ export async function handleElementUnbindSource({ client, elicitation }, input)
     }
     const encoded = encodeElementPath(element_path);
     try {
-        const data = await client.delete(`/pages/${encodeURIComponent(template_id)}/elements/${encoded}/binding`, { etag });
+        const data = await client.delete(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/binding`, { etag });
         return jsonResult(data);
     }
     catch (e) {

package/dist/tools/sources/handlers-bind.js.map

@@ -1 +1 @@
-{"version":3,"file":"handlers-bind.js","sourceRoot":"","sources":["../../../src/tools/sources/handlers-bind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAE,iBAAiB,EAAmB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EACH,qBAAqB,EACrB,YAAY,GAEf,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACH,sBAAsB,GAEzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,GAEb,MAAM,oBAAoB,CAAC;AAG5B,uEAAuE;AAEvE;;;;;;;;;GASG;AACH,KAAK,UAAU,qBAAqB,CAChC,MAAkB,EAClB,WAAmB;IAEnB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAwB,UAAU,CAAC,CAAC;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;IACrC,MAAM,IAAI,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CACzC,EAAE,MAAM,EAAE,WAAW,EAAsB,EAC3C,KAQC;IAED,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,GAC3F,KAAK,CAAC;IACV,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAEhD,qCAAqC;IACrC,EAAE;IACF,oEAAoE;IACpE,qCAAqC;IACrC,EAAE;IACF,iDAAiD;IACjD,gEAAgE;IAChE,kEAAkE;IAClE,qDAAqD;IACrD,uCAAuC;IACvC,iEAAiE;IACjE,kEAAkE;IAClE,0DAA0D;IAC1D,kEAAkE;IAClE,+CAA+C;IAC/C,IAAI,YAAY,GAKZ,EAAE,WAAW,EAAE,CAAC;IACpB,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC7B,YAAY,CAAC,YAAY,GAAG,YAAY,CAAC;IAC7C,CAAC;IACD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QAC/B,YAAY,CAAC,cAAc,GAAG,cAAc,CAAC;IACjD,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,UAAU,GAAG,MAAM,qBAAqB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACpE,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,gBAAgB,GAA2B,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACpE,EAAE,EAAE,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,EAAE;gBAC3B,KAAK,EAAE,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG;aAC3E,CAAC,CAAC,CAAC;YACJ,MAAM,MAAM,GAAG,WAAW;gBACtB,CAAC,CAAC,MAAM,YAAY,CACd,WAAW,EACX,2BAA2B,WAAW,sBAAsB;oBACxD,mBAAmB,YAAY,IAAI,EACvC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACpC;gBACH,CAAC,CAAC,IAAI,CAAC;YACX,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBAClB,OAAO,sBAAsB,CAAC;oBAC1B,IAAI,EAAE,kBAAkB;oBACxB,SAAS,EAAE,WAAW;oBACtB,IAAI,EAAE,SAAS;oBACf,UAAU,EAAE,gBAAgB;oBAC5B,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE;iBACtD,CAAC,CAAC;YACP,CAAC;YACD,YAAY,GAAG,EAAE,GAAG,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAC1D,CAAC;IACL,CAAC;SAAM,CAAC;QACJ,YAAY,GAAG,EAAE,GAAG,YAAY,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;IAED,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CACzB,UAAU,kBAAkB,CAAC,WAAW,CAAC,aAAa,OAAO,UAAU,EACvE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAC/B,CAAC;QACF,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;YACxF,IAAI,EACA,+DAA+D;gBAC/D,yBAAyB;SAChC,CAAC,CAAC;IACP,CAAC;AACL,CAAC;AAED,uEAAuE;AAEvE,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC3C,EAAE,MAAM,EAAE,WAAW,EAAsB,EAC3C,KAAqF;IAErF,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC3D,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,IAAI,OAAO,KAAK,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;YACpC,OAAO,YAAY,CAAC;gBAChB,SAAS,EAAE,eAAe;gBAC1B,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;aACzC,CAAC,CAAC;QACP,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CACrC,WAAW,EACX,2CAA2C,YAAY,gBAAgB;YACnE,IAAI,WAAW,8CAA8C,CACpE,CAAC;QACF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,OAAO,YAAY,CAAC;gBAChB,SAAS,EAAE,eAAe;gBAC1B,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;aACzC,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAC5B,UAAU,kBAAkB,CAAC,WAAW,CAAC,aAAa,OAAO,UAAU,EACvE,EAAE,IAAI,EAAE,CACX,CAAC;QACF,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;YACtC,IAAI,EAAE,yDAAyD;SAClE,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}
+{"version":3,"file":"handlers-bind.js","sourceRoot":"","sources":["../../../src/tools/sources/handlers-bind.ts"],"names":[],"mappings":"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"}

package/dist/tools/sources/handlers.d.ts

@@ -18,12 +18,15 @@ export declare const SOURCES_LIST_OUTPUT_SCHEMA: z.ZodObject<{
     projected_fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
     available_fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
     unknown_fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    projection_warning: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const BINDING_OUTPUT_SCHEMA: z.ZodObject<{
     template_id: z.ZodString;
     element_path: z.ZodString;
     binding: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     has_binding: z.ZodBoolean;
+    field_mapping_count: z.ZodNumber;
+    warning: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export interface SourcesHandlerDeps {
     readonly client: RestClient;

package/dist/tools/sources/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/tools/sources/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQrE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAOlE,OAAO,EAGH,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAI5B,eAAO,MAAM,0BAA0B;;;;;;iBAOrC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;iBAKhC,CAAC;AAEH,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACnD;AAID,wBAAsB,iBAAiB,CACnC,EAAE,MAAM,EAAE,EAAE,kBAAkB,EAC9B,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3C,OAAO,CAAC,UAAU,CAAC,CAyCrB;AAID,wBAAsB,uBAAuB,CACzC,EAAE,MAAM,EAAE,EAAE,kBAAkB,EAC9B,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,UAAU,CAAC,CAgCrB;AAID,OAAO,EACH,uBAAuB,EACvB,yBAAyB,GAC5B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/tools/sources/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AASvF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAQlE,OAAO,EAGH,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAI5B,eAAO,MAAM,0BAA0B;;;;;;;iBAWrC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;iBAahC,CAAC;AAEH,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACnD;AAID,wBAAsB,iBAAiB,CACnC,EAAE,MAAM,EAAE,EAAE,kBAAkB,EAC9B,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3C,OAAO,CAAC,UAAU,CAAC,CA2CrB;AAID,wBAAsB,uBAAuB,CACzC,EAAE,MAAM,EAAE,EAAE,kBAAkB,EAC9B,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,UAAU,CAAC,CAwDrB;AAID,OAAO,EACH,uBAAuB,EACvB,yBAAyB,GAC5B,MAAM,oBAAoB,CAAC"}

package/dist/tools/sources/handlers.js

@@ -10,9 +10,9 @@
  */
 import { detailResult, tableResult } from '@getimo/mcp-toolkit';
 import { z } from 'zod';
-import { encodeElementPath } from '../../client.js';
-import { SOURCES_TABLE_COLUMNS, buildBindingDetail, flattenSourcesPayload, mapSourceRow, remapOriginForPlatform, } from '../format/sources-format.js';
-import { DEFAULT_FIELDS_SOURCES_LIST, projectFields, projectedFieldsEcho, projectionFeedback, } from '../sparse-fields.js';
+import { encodeElementPath, encodeTemplateId } from '../../client.js';
+import { SOURCES_TABLE_COLUMNS, bindingFieldMappingCount, buildBindingDetail, flattenSourcesPayload, mapSourceRow, remapOriginForPlatform, } from '../format/sources-format.js';
+import { DEFAULT_FIELDS_SOURCES_LIST, projectFields, projectedFieldsEcho, projectionFeedback, projectionWarning, } from '../sparse-fields.js';
 import { errorResult, structuredResult, } from '../tool-builder.js';
 // ─── outputSchemas (Wave G.2 §4) ─────────────────────────────────────
 export const SOURCES_LIST_OUTPUT_SCHEMA = z.object({
@@ -22,12 +22,24 @@ export const SOURCES_LIST_OUTPUT_SCHEMA = z.object({
     // F-004 fix (2026-05-25 exhaustive audit): see sparse-fields::projectionFeedback.
     available_fields: z.array(z.string()).optional(),
     unknown_fields: z.array(z.string()).optional(),
+    // F23 (2026-06-10): the LOUD unknown-projection warning also rides in
+    // structuredContent — hosts that surface structuredContent (not the
+    // text leg) to the model would otherwise never see it.
+    projection_warning: z.string().optional(),
 });
 export const BINDING_OUTPUT_SCHEMA = z.object({
     template_id: z.string(),
     element_path: z.string(),
     binding: z.record(z.string(), z.unknown()),
     has_binding: z.boolean(),
+    // F174 — number of field mappings on the binding. Always present (0 when
+    // unbound or mapping-less) so a "verification" read of a bound-but-
+    // mapping-less element no longer looks healthy.
+    field_mapping_count: z.number().int().nonnegative(),
+    // F174 — top-level warning when the element IS bound but has 0 field
+    // mappings (the N clones render only the template's static placeholder
+    // text). Absent on the happy path.
+    warning: z.string().optional(),
 });
 // ─── sources_list ────────────────────────────────────────────────────
 export async function handleSourcesList({ client }, { fields }) {
@@ -46,13 +58,14 @@ export async function handleSourcesList({ client }, { fields }) {
         const items = projectFields(mappedRecords, fields, DEFAULT_FIELDS_SOURCES_LIST);
         const echo = projectedFieldsEcho(fields, DEFAULT_FIELDS_SOURCES_LIST);
         const feedback = projectionFeedback(mappedRecords, fields);
-        const unknownNote = feedback !== undefined && feedback.unknown_fields.length > 0
-            ? ` (unknown fields ignored: ${feedback.unknown_fields.join(', ')}; available: ${feedback.available_fields.join(', ')})`
-            : '';
+        // F23 (2026-06-09): shared loud-warning helper.
+        const unknownNote = projectionWarning(feedback);
         const toolkitResult = tableResult(mappedRecords, {
             columns: [...SOURCES_TABLE_COLUMNS],
             header: (count) => `${String(count)} sources${unknownNote}`,
-            footer: 'Use yootheme_builder_element_bind_source to bind one.',
+            footer: 'Bind one directly: yootheme_builder_element_bind_source({ template_id, ' +
+                'element_path, source_name, field_mappings }) ' +
+                '(a first-class tool in tools/list since F116).',
         });
         return structuredResult(toolkitResult, {
             items,
@@ -61,6 +74,7 @@ export async function handleSourcesList({ client }, { fields }) {
             ...(feedback !== undefined ? {
                 available_fields: [...feedback.available_fields],
                 unknown_fields: [...feedback.unknown_fields],
+                ...(unknownNote.trim() !== '' ? { projection_warning: unknownNote.trim() } : {}),
             } : {}),
         });
     }
@@ -76,7 +90,7 @@ export async function handleSourcesList({ client }, { fields }) {
 export async function handleElementGetBinding({ client }, { template_id, element_path }) {
     const encoded = encodeElementPath(element_path);
     try {
-        const data = await client.get(`/pages/${encodeURIComponent(template_id)}/elements/${encoded}/binding`);
+        const data = await client.get(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/binding`);
         const binding = data !== null && typeof data === 'object' ? data : {};
         // F-01-Mapping (Audit v4): trust the BE-computed `has_binding`
         // flag (BindingSerializer SSoT) — it also flips true for an
@@ -86,12 +100,35 @@ export async function handleElementGetBinding({ client }, { template_id, element
             ? binding.has_binding
             : typeof binding.source_name === 'string' &&
                 binding.source_name.length > 0;
+        // F174 — count the field mappings (same extraction the detail builder
+        // uses) so a "verification" read surfaces the zero-mappings footgun
+        // instead of silently looking healthy. The warning fires ONLY when the
+        // element is actually bound but carries no mappings — the N clones then
+        // render the template's static placeholder text, not real data.
+        const fieldMappingCount = bindingFieldMappingCount(binding);
+        const zeroFieldMappings = hasBinding && fieldMappingCount === 0;
         const toolkitResult = detailResult(buildBindingDetail({ template_id, element_path, binding }));
         return structuredResult(toolkitResult, {
             template_id,
             element_path,
             binding,
             has_binding: hasBinding,
+            field_mapping_count: fieldMappingCount,
+            ...(zeroFieldMappings
+                ? {
+                    warning: 'This element is bound to a source but has 0 field mappings, ' +
+                        'so its cloned items render the template\'s static placeholder ' +
+                        'text (Title / Lorem ipsum), not real data. Re-bind with ' +
+                        'field_mappings AT THIS ITEM via ' +
+                        'yootheme_builder_element_bind_source on THIS element_path ' +
+                        'with field_mappings:{<element_prop>:<source_field>}. Do NOT ' +
+                        'bind the individual child leaves instead: on YT5 a "#parent" ' +
+                        'leaf bind written directly under an iterating item renders ' +
+                        'placeholder text. Discover props with ' +
+                        'yootheme_builder_element_type_get_schema, source fields ' +
+                        'with apimapper_yootheme_binding_for_flow.',
+                }
+                : {}),
         });
     }
     catch (e) {

package/dist/tools/sources/handlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../src/tools/sources/handlers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../src/tools/sources/handlers.ts"],"names":[],"mappings":"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"}

package/dist/tools/sparse-fields.d.ts

@@ -103,4 +103,27 @@ export interface ProjectionFeedback {
     readonly unknown_fields: readonly string[];
 }
 export declare function projectionFeedback(items: readonly Record<string, unknown>[], requested: readonly string[] | undefined): ProjectionFeedback | undefined;
+/**
+ * F23 (2026-06-09): single source of truth for the LOUD text-leg warning
+ * a tool appends to its table header when a `fields[]` projection
+ * contained keys that did not exist on any row.
+ *
+ * Before this helper every read tool assembled the note inline (subtly
+ * different wording per tool, and a new tool wiring `projectionFeedback`
+ * could silently forget the text-leg note entirely — only the
+ * structuredContent `unknown_fields` array surfaced it, which cold
+ * agents never read). Centralising the string here means ALL tools
+ * surface the identical, self-correcting signal:
+ *
+ *   " (unknown projection fields ignored: type — available: rel_path, …)"
+ *
+ * Returns the EMPTY string when there is nothing to warn about (feedback
+ * undefined, or `unknown_fields` empty) so call-sites can unconditionally
+ * append the result to their header.
+ *
+ * The leading space lets a call-site write `header${warning}` without an
+ * extra separator; the parentheses keep it visually scoped inside the
+ * header line.
+ */
+export declare function projectionWarning(feedback: ProjectionFeedback | undefined): string;
 //# sourceMappingURL=sparse-fields.d.ts.map

package/dist/tools/sparse-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sparse-fields.d.ts","sourceRoot":"","sources":["../../src/tools/sparse-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;GAIG;AACH,eAAO,MAAM,MAAM,wCASd,CAAC;AAEN;;;;GAIG;AACH,eAAO,MAAM,IAAI,4BAMZ,CAAC;AAIN;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAMtD,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAIxD,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAIlD,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAKxD,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAKtD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAE,GAAG,SAAqB,CAAC;AAInF;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC7B,CAAC,EAAE,CAWL;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,GAAG,EAAE,CAAC,EACN,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACzC,CAAC,CAQH;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAC/B,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACxC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACxC,SAAS,MAAM,EAAE,GAAG,SAAS,CAI/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,kBAAkB;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACzC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACzC,kBAAkB,GAAG,SAAS,CAkBhC"}
+{"version":3,"file":"sparse-fields.d.ts","sourceRoot":"","sources":["../../src/tools/sparse-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;GAIG;AACH,eAAO,MAAM,MAAM,wCASd,CAAC;AAEN;;;;GAIG;AACH,eAAO,MAAM,IAAI,4BAMZ,CAAC;AAIN;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAMtD,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAIxD,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAIlD,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAKxD,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAKtD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAE,GAAG,SAAqB,CAAC;AAInF;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC7B,CAAC,EAAE,CAWL;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,GAAG,EAAE,CAAC,EACN,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACzC,CAAC,CAQH;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAC/B,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACxC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACxC,SAAS,MAAM,EAAE,GAAG,SAAS,CAI/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,kBAAkB;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACzC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACzC,kBAAkB,GAAG,SAAS,CAkBhC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GACzC,MAAM,CAQR"}

package/dist/tools/sparse-fields.js

@@ -162,4 +162,33 @@ export function projectionFeedback(items, requested) {
     });
     return { available_fields: available, unknown_fields: unknown };
 }
+/**
+ * F23 (2026-06-09): single source of truth for the LOUD text-leg warning
+ * a tool appends to its table header when a `fields[]` projection
+ * contained keys that did not exist on any row.
+ *
+ * Before this helper every read tool assembled the note inline (subtly
+ * different wording per tool, and a new tool wiring `projectionFeedback`
+ * could silently forget the text-leg note entirely — only the
+ * structuredContent `unknown_fields` array surfaced it, which cold
+ * agents never read). Centralising the string here means ALL tools
+ * surface the identical, self-correcting signal:
+ *
+ *   " (unknown projection fields ignored: type — available: rel_path, …)"
+ *
+ * Returns the EMPTY string when there is nothing to warn about (feedback
+ * undefined, or `unknown_fields` empty) so call-sites can unconditionally
+ * append the result to their header.
+ *
+ * The leading space lets a call-site write `header${warning}` without an
+ * extra separator; the parentheses keep it visually scoped inside the
+ * header line.
+ */
+export function projectionWarning(feedback) {
+    if (feedback === undefined || feedback.unknown_fields.length === 0) {
+        return '';
+    }
+    return (` (unknown projection fields ignored: ${feedback.unknown_fields.join(', ')}` +
+        ` — available: ${feedback.available_fields.join(', ')})`);
+}
 //# sourceMappingURL=sparse-fields.js.map

package/dist/tools/sparse-fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"sparse-fields.js","sourceRoot":"","sources":["../../src/tools/sparse-fields.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sparse-fields.js","sourceRoot":"","sources":["../../src/tools/sparse-fields.ts"],"names":[],"mappings":"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"}

package/dist/tools/sublayout/builders.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Sublayout tool builder.
+ *
+ * Surfaces one tool that operates on the YT5 `< SUBLAYOUT` mechanism
+ * (F154 / F93):
+ *
+ *   yootheme_builder_inspect_sublayout
+ *     → Reports the fragment subtree (bindable leaves with full JSON-Pointer
+ *       paths) AND the render-time inner grid (gated title/image props), so an
+ *       agent enriching a panel/grid_item binds the right node and avoids the
+ *       silent-no-op trap (grid props set but the gate unsatisfied).
+ *
+ * L2 (advanced lane) — routed via `yootheme_builder_advanced`. It is a
+ * specialized layout diagnostic for one element family (panel/grid_item
+ * enrichment), not a hot-path every workflow needs (unlike
+ * inspect_multi_items_binding, which earns its L1 slot).
+ *
+ * @license MIT
+ */
+import type { ClientPool } from '../../sites/client-pool.js';
+import { type AnyToolDefinition } from '../tool-builder.js';
+export declare function buildSublayoutTools(pool: ClientPool): readonly AnyToolDefinition[];
+//# sourceMappingURL=builders.d.ts.map

package/dist/tools/sublayout/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/sublayout/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAIH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AAQ5B,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CA+BlF"}

package/dist/tools/sublayout/builders.js

@@ -0,0 +1,54 @@
+/**
+ * Sublayout tool builder.
+ *
+ * Surfaces one tool that operates on the YT5 `< SUBLAYOUT` mechanism
+ * (F154 / F93):
+ *
+ *   yootheme_builder_inspect_sublayout
+ *     → Reports the fragment subtree (bindable leaves with full JSON-Pointer
+ *       paths) AND the render-time inner grid (gated title/image props), so an
+ *       agent enriching a panel/grid_item binds the right node and avoids the
+ *       silent-no-op trap (grid props set but the gate unsatisfied).
+ *
+ * L2 (advanced lane) — routed via `yootheme_builder_advanced`. It is a
+ * specialized layout diagnostic for one element family (panel/grid_item
+ * enrichment), not a hot-path every workflow needs (unlike
+ * inspect_multi_items_binding, which earns its L1 slot).
+ *
+ * @license MIT
+ */
+import { withSiteRetry } from '../pool-resolve-helper.js';
+import { ELEMENT_PATH, SITE_ID_SCHEMA, TEMPLATE_ID } from '../shared-schemas.js';
+import { defineTool, readOnly, withSiteMeta, } from '../tool-builder.js';
+import { InspectionCache } from '../multi-items/inspection-cache.js';
+import { INSPECT_SUBLAYOUT_OUTPUT_SCHEMA, handleInspectSublayout, } from './inspect-sublayout-handler.js';
+export function buildSublayoutTools(pool) {
+    // One shared inspection cache per tool-build, keyed on (template_id,
+    // element_path, global-etag) with a 60s TTL. A write bumps the global
+    // etag and naturally invalidates the entry (mirrors multi-items).
+    const inspectionCache = new InspectionCache();
+    return [
+        defineTool({
+            name: 'yootheme_builder_inspect_sublayout',
+            description: 'Inspects a panel/grid_item `< SUBLAYOUT`: lists the `fragment` subtree ' +
+                'bindable leaves (with JSON-Pointer paths to bind on — NOT the container) ' +
+                'and the render-time inner grid. Flags `ungated_grid_prop` (blocking): grid ' +
+                'props set but the gate (title_align=left / image_align=left|right) ' +
+                'unsatisfied → silent no-op. For container↔item binding see ' +
+                'inspect_multi_items_binding. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                template_id: TEMPLATE_ID,
+                element_path: ELEMENT_PATH,
+            },
+            outputSchema: INSPECT_SUBLAYOUT_OUTPUT_SCHEMA,
+            annotations: readOnly('Inspect Sublayout'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => {
+                const deps = { client, cache: inspectionCache };
+                return withSiteMeta(await handleInspectSublayout(deps, rest), site);
+            }),
+        }),
+    ];
+}
+//# sourceMappingURL=builders.js.map

package/dist/tools/sublayout/builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../../src/tools/sublayout/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACH,UAAU,EACV,QAAQ,EACR,YAAY,GAEf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,EACH,+BAA+B,EAC/B,sBAAsB,GAEzB,MAAM,gCAAgC,CAAC;AAExC,MAAM,UAAU,mBAAmB,CAAC,IAAgB;IAChD,qEAAqE;IACrE,sEAAsE;IACtE,kEAAkE;IAClE,MAAM,eAAe,GAAG,IAAI,eAAe,EAA2B,CAAC;IAEvE,OAAO;QACH,UAAU,CAAC;YACP,IAAI,EAAE,oCAAoC;YAC1C,WAAW,EACP,yEAAyE;gBACzE,2EAA2E;gBAC3E,6EAA6E;gBAC7E,qEAAqE;gBACrE,6DAA6D;gBAC7D,+BAA+B;gBAC/B,0DAA0D;YAC9D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,WAAW,EAAE,WAAW;gBACxB,YAAY,EAAE,YAAY;aAC7B;YACD,YAAY,EAAE,+BAA+B;YAC7C,WAAW,EAAE,QAAQ,CAAC,mBAAmB,CAAC;YAC1C,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CACpC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChD,MAAM,IAAI,GAAyB,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;gBACtE,OAAO,YAAY,CAAC,MAAM,sBAAsB,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YACxE,CAAC,CAAC;SACT,CAAC;KACL,CAAC;AACN,CAAC"}

package/dist/tools/sublayout/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sublayout tool barrel — public entry-point for the YT5 `< SUBLAYOUT`
+ * inspection tool (F154 / F93).
+ *
+ *   yootheme_builder_inspect_sublayout
+ *     → Report the fragment subtree (bindable leaves) + the render-time inner
+ *       grid (gated props) for a panel/grid_item.
+ *
+ * @license MIT
+ */
+export { buildSublayoutTools } from './builders.js';
+export { INSPECT_SUBLAYOUT_OUTPUT_SCHEMA, handleInspectSublayout, type SublayoutHandlerDeps, } from './inspect-sublayout-handler.js';
+//# sourceMappingURL=index.d.ts.map