@wootsup/yt-builder-mcp 1.2.0 → 1.4.0

package/dist/tools/sparse-fields.js

@@ -46,6 +46,84 @@ export const FLAT = z
     .default(false)
     .describe('When true, response is a flat [{path, element_type, ...}] array. Enables ' +
     'fields[] projection. Default: false (nested layout, no projection).');
+/**
+ * G-B (Glöckle 2026-06-26): an OPTIONAL caller-supplied cap on the size of
+ * the LLM-visible text leg of a high-volume read tool, so an agent on a
+ * tight context budget can bound a single read instead of relying solely on
+ * the toolkit's count-driven default cap (2000 / 4000 / 8000 chars). Cuts
+ * the TEXT leg only — structuredContent (the UI / typed payload) is never
+ * truncated, so a host that surfaces structuredContent still sees the full
+ * result. Floor of 200 stops a pathological `max_chars: 1` from yielding an
+ * all-marker, no-content body.
+ */
+export const MAX_CHARS = z
+    .number()
+    .int()
+    .min(200)
+    .max(100_000)
+    .optional()
+    .describe('Optional cap (chars) on the text output, overriding the default detail ' +
+    'cap. Truncates the LLM-visible text leg only (structuredContent stays ' +
+    'complete). Use to bound a single read on a tight context budget — e.g. ' +
+    'max_chars:2000.');
+/**
+ * G-B: shared opaque offset-cursor codec for client-side pagination.
+ *
+ * `pages_list` (B2) shipped a private copy of this; `sources_list` (G-B) needs
+ * the identical contract (a `base64url("o:<n>")` token, also tolerant of the
+ * raw `o:<n>` form for hand-crafted iteration). Extracted here so both list
+ * tools encode/decode byte-identically — a cursor handed back to either tool
+ * means the same offset.
+ */
+export function decodeOffsetCursor(cursor) {
+    if (cursor === undefined || cursor === '')
+        return 0;
+    let raw = cursor;
+    if (!/^o:\d+$/.test(cursor)) {
+        try {
+            raw = Buffer.from(cursor.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
+        }
+        catch {
+            return 0;
+        }
+    }
+    const m = /^o:(\d+)$/.exec(raw);
+    return m ? Number(m[1]) : 0;
+}
+export function encodeOffsetCursor(offset) {
+    return Buffer.from(`o:${offset}`, 'utf8').toString('base64url');
+}
+/** Marker appended when {@link applyMaxChars} truncates a text leg. */
+const TRUNCATION_MARKER = '\n--- TRUNCATED by max_chars ---';
+/**
+ * G-B: cap the text leg of an already-built tool result at `maxChars`.
+ *
+ * Pure: returns a NEW result, never mutates. Truncates ONLY the first text
+ * content block (the LLM-visible leg) when it exceeds `maxChars`; every other
+ * block — and `structuredContent` / `_meta` — passes through untouched so the
+ * UI / typed payload remains complete. A no-op when `maxChars` is undefined,
+ * when the first block is not text, or when the text is already within budget.
+ *
+ * The slice reserves room for the truncation marker so the returned text never
+ * exceeds `maxChars`.
+ */
+export function applyMaxChars(result, maxChars) {
+    if (maxChars === undefined)
+        return result;
+    const first = result.content[0];
+    if (first === undefined || first.type !== 'text' || typeof first.text !== 'string') {
+        return result;
+    }
+    if (first.text.length <= maxChars)
+        return result;
+    const room = Math.max(0, maxChars - TRUNCATION_MARKER.length);
+    const truncated = first.text.slice(0, room) + TRUNCATION_MARKER;
+    const rest = result.content.slice(1);
+    return {
+        ...result,
+        content: [{ ...first, text: truncated }, ...rest],
+    };
+}
 // ─── Default field-sets per tool ─────────────────────────────────────
 /**
  * Default fields echoed when the caller omits `fields`. Following the
@@ -162,4 +240,62 @@ 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(', ')})`);
+}
+// ─── Text-table column projection ────────────────────────────────────
+/** Field keys that get a wide text-table column (paths, URLs, hash ids). */
+const WIDE_FIELD_KEYS = new Set([
+    'path',
+    'rel_path',
+    'parent_path',
+    'url',
+    'home_url',
+    'site_url',
+    'template_id',
+    'permalink',
+]);
+/**
+ * Build slim text-table columns from a caller-supplied `fields[]` projection,
+ * so a list tool's TEXT leg (what the LLM reads) honors `fields` instead of
+ * always rendering the full row set. Without this the projection only narrows
+ * the structuredContent leg while the text table still emits — and gets
+ * truncated at — every column (the Glöckle "fields[] ignored" finding).
+ *
+ * Width heuristic: path / URL / id-like keys get a wide column, everything
+ * else a modest one; labels are uppercased to match the toolkit style.
+ */
+export function columnsFromFields(fields) {
+    return fields.map((key) => ({
+        key,
+        label: key.replace(/_/g, ' ').toUpperCase(),
+        width: WIDE_FIELD_KEYS.has(key) ? 48 : 16,
+    }));
+}
 //# 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/sublayout/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACH,+BAA+B,EAC/B,sBAAsB,EACtB,KAAK,oBAAoB,GAC5B,MAAM,gCAAgC,CAAC"}

package/dist/tools/sublayout/index.js

@@ -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, } from './inspect-sublayout-handler.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/sublayout/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACH,+BAA+B,EAC/B,sBAAsB,GAEzB,MAAM,gCAAgC,CAAC"}

package/dist/tools/sublayout/inspect-sublayout-handler.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `inspect_sublayout` handler — surfaces the YT5 `< SUBLAYOUT` mechanism
+ * (F154 / F93) via REST round-trip.
+ *
+ * YT5's `< SUBLAYOUT` breadcrumb conflates TWO structurally different things:
+ *
+ *  1. The `fragment` element — a real container node whose bind-able leaves
+ *     (title, meta, crest image) live in `fragment.children[...]`, NOT on the
+ *     `panel`/`grid_item` the Customizer first selected.
+ *  2. The render-time inner grid — `panel`/`grid_item` build a `uk-grid` from
+ *     PROPS injected by the container at render. There is NO JSON node for it,
+ *     and it is GATED: the inner wrapper is only emitted when
+ *     `title_align === 'left'` / `image_align ∈ {left,right}`. Patching
+ *     `title_grid_width` without first satisfying the gate is a SILENT no-op.
+ *
+ * Companion of the PHP `SublayoutInspector` — see
+ * src/modules/builder-source-binding/src/SublayoutInspector.php for the
+ * report shape. Mirrors the `inspect_multi_items_binding` handler:
+ * optional InspectionCache keyed on (template_id, element_path, global-etag).
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { type RestClient } from '../../client.js';
+import { type ToolResult } from '../tool-builder.js';
+import { InspectionCache } from '../multi-items/inspection-cache.js';
+export declare const INSPECT_SUBLAYOUT_OUTPUT_SCHEMA: z.ZodObject<{
+    template_id: z.ZodString;
+    report: z.ZodObject<{
+        element_path: z.ZodString;
+        element_type: z.ZodString;
+        is_sublayout_capable: z.ZodBoolean;
+        fragments: z.ZodArray<z.ZodObject<{
+            fragment_path: z.ZodString;
+            child_count: z.ZodNumber;
+            bindable_leaves: z.ZodArray<z.ZodObject<{
+                leaf_path: z.ZodString;
+                element_type: z.ZodString;
+                bindable_props: z.ZodArray<z.ZodString>;
+                is_bound: z.ZodBoolean;
+                bound_source_name: z.ZodNullable<z.ZodString>;
+                bound_source_exists: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        grid: z.ZodObject<{
+            title: z.ZodObject<{
+                gate_prop: z.ZodString;
+                gate_value: z.ZodNullable<z.ZodString>;
+                gate_satisfied: z.ZodBoolean;
+                active_props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, z.core.$strip>;
+            image: z.ZodObject<{
+                gate_prop: z.ZodString;
+                gate_value: z.ZodNullable<z.ZodString>;
+                gate_satisfied: z.ZodBoolean;
+                active_props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+        warnings: z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            props: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            gate_prop: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        no_sublayout: z.ZodBoolean;
+    }, z.core.$strip>;
+    etag: z.ZodString;
+    hint: z.ZodOptional<z.ZodObject<{
+        severity: z.ZodEnum<{
+            advisory: "advisory";
+            blocking: "blocking";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Severity of the advisory hint attached to every report. */
+export type HintSeverity = 'advisory' | 'blocking';
+/** The structured inspect payload the handler caches + emits. */
+type InspectStructured = Record<string, unknown>;
+export interface SublayoutHandlerDeps {
+    readonly client: RestClient;
+    /**
+     * Optional inspection cache. When provided, results are keyed on
+     * (template_id, element_path, global-etag) with a 60s TTL. A write bumps
+     * the global etag and naturally invalidates the entry. Omit to disable
+     * caching (e.g. shape-pin tests that assert the raw round-trip).
+     */
+    readonly cache?: InspectionCache<InspectStructured>;
+}
+export declare function handleInspectSublayout({ client, cache }: SublayoutHandlerDeps, { template_id, element_path }: {
+    template_id: string;
+    element_path: string;
+}): Promise<ToolResult>;
+export {};
+//# sourceMappingURL=inspect-sublayout-handler.d.ts.map

package/dist/tools/sublayout/inspect-sublayout-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-sublayout-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/sublayout/inspect-sublayout-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAoCrE,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuB1C,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,CAAC;AAEnD,iEAAiE;AACjE,KAAK,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;CACvD;AAyED,wBAAsB,sBAAsB,CACxC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,oBAAoB,EACvC,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,UAAU,CAAC,CAuCrB"}

package/dist/tools/sublayout/inspect-sublayout-handler.js

@@ -0,0 +1,181 @@
+/**
+ * `inspect_sublayout` handler — surfaces the YT5 `< SUBLAYOUT` mechanism
+ * (F154 / F93) via REST round-trip.
+ *
+ * YT5's `< SUBLAYOUT` breadcrumb conflates TWO structurally different things:
+ *
+ *  1. The `fragment` element — a real container node whose bind-able leaves
+ *     (title, meta, crest image) live in `fragment.children[...]`, NOT on the
+ *     `panel`/`grid_item` the Customizer first selected.
+ *  2. The render-time inner grid — `panel`/`grid_item` build a `uk-grid` from
+ *     PROPS injected by the container at render. There is NO JSON node for it,
+ *     and it is GATED: the inner wrapper is only emitted when
+ *     `title_align === 'left'` / `image_align ∈ {left,right}`. Patching
+ *     `title_grid_width` without first satisfying the gate is a SILENT no-op.
+ *
+ * Companion of the PHP `SublayoutInspector` — see
+ * src/modules/builder-source-binding/src/SublayoutInspector.php for the
+ * report shape. Mirrors the `inspect_multi_items_binding` handler:
+ * optional InspectionCache keyed on (template_id, element_path, global-etag).
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { encodeElementPath, encodeTemplateId } from '../../client.js';
+import { errorResult, jsonResult, structuredResult } from '../tool-builder.js';
+import { capInspectionDepth } from '../multi-items/format/inspection-format.js';
+/** A single render-time inner-grid axis (title | image). */
+const GRID_AXIS_SCHEMA = z.object({
+    gate_prop: z.string(),
+    gate_value: z.string().nullable(),
+    gate_satisfied: z.boolean(),
+    active_props: z.record(z.string(), z.unknown()),
+});
+/** A bindable leaf inside a fragment subtree. */
+const BINDABLE_LEAF_SCHEMA = z.object({
+    leaf_path: z.string(),
+    element_type: z.string(),
+    bindable_props: z.array(z.string()),
+    is_bound: z.boolean(),
+    bound_source_name: z.string().nullable(),
+    // null when the registry is not wired (UNKNOWN, never a false miss).
+    bound_source_exists: z.boolean().nullable().optional(),
+});
+/** A direct fragment child of the addressed container. */
+const FRAGMENT_SCHEMA = z.object({
+    fragment_path: z.string(),
+    child_count: z.number().int().nonnegative(),
+    bindable_leaves: z.array(BINDABLE_LEAF_SCHEMA),
+});
+/** A single enrichment-hazard warning. */
+const SUBLAYOUT_WARNING_SCHEMA = z.object({
+    code: z.string(),
+    message: z.string(),
+    props: z.array(z.string()).optional(),
+    gate_prop: z.string().optional(),
+});
+export const INSPECT_SUBLAYOUT_OUTPUT_SCHEMA = z.object({
+    template_id: z.string(),
+    report: z.object({
+        element_path: z.string(),
+        element_type: z.string(),
+        is_sublayout_capable: z.boolean(),
+        fragments: z.array(FRAGMENT_SCHEMA),
+        grid: z.object({
+            title: GRID_AXIS_SCHEMA,
+            image: GRID_AXIS_SCHEMA,
+        }),
+        warnings: z.array(SUBLAYOUT_WARNING_SCHEMA),
+        no_sublayout: z.boolean(),
+    }),
+    etag: z.string(),
+    // Typed advisory/blocking marker. `blocking` when an ungated grid prop is
+    // a silent no-op (the trap this tool exists for); `advisory` otherwise.
+    hint: z
+        .object({
+        severity: z.enum(['advisory', 'blocking']),
+        message: z.string(),
+    })
+        .optional(),
+});
+/**
+ * Classify the report into an advisory/blocking hint.
+ *
+ * Precedence: an `ungated_grid_prop` warning (a silent no-op — the trap this
+ * tool exists for) is `blocking`; everything else is `advisory`. A
+ * sublayout-less element gets a short "nothing to enrich" advisory so the
+ * agent does not keep probing.
+ */
+function buildHint(report) {
+    const r = (report ?? {});
+    const warnings = Array.isArray(r.warnings)
+        ? r.warnings
+        : [];
+    const ungated = warnings.find((w) => w.code === 'ungated_grid_prop');
+    if (ungated !== undefined && typeof ungated.message === 'string' && ungated.message !== '') {
+        return { severity: 'blocking', message: ungated.message };
+    }
+    if (r.no_sublayout === true) {
+        return {
+            severity: 'advisory',
+            message: 'This element has no `fragment` sublayout child and no inner-grid ' +
+                'props — there is nothing to enrich here. Bind a source directly on a ' +
+                'leaf via yootheme_builder_element_bind_source, or add a fragment first.',
+        };
+    }
+    if (r.is_sublayout_capable === false) {
+        return {
+            severity: 'advisory',
+            message: 'This element type is not sublayout-capable (panel / grid_item). The ' +
+                'fragment subtree + inner-grid gate apply only to those containers.',
+        };
+    }
+    return {
+        severity: 'advisory',
+        message: 'Sublayout looks consistent. Bind the source on a `fragment.children` leaf ' +
+            '(use a leaf_path from the report), NOT on this container. Inner-grid props ' +
+            'only take effect when their gate (title_align=left / image_align=left|right) ' +
+            'is satisfied.',
+    };
+}
+/**
+ * Render a structured inspect payload into the ToolResult envelope. The text
+ * leg is depth-capped so a deeply-nested report cannot balloon the LLM
+ * context; structuredContent stays verbatim so it keeps validating against
+ * INSPECT_SUBLAYOUT_OUTPUT_SCHEMA (additionalProperties:false).
+ */
+function renderInspectResult(structured) {
+    const text = jsonResult(capInspectionDepth(structured));
+    return structuredResult(text, structured);
+}
+export async function handleInspectSublayout({ client, cache }, { template_id, element_path }) {
+    const encoded = encodeElementPath(element_path);
+    try {
+        // When a cache is wired, key on the GLOBAL state etag. Every write
+        // bumps it, so a mutated template surfaces a fresh etag → a new key →
+        // a guaranteed miss. Read-only repeats within the TTL skip the inspect
+        // round-trip below.
+        let cacheEtag;
+        if (cache !== undefined) {
+            cacheEtag = await fetchStateEtag(client);
+            if (cacheEtag !== undefined) {
+                const cached = cache.get(template_id, element_path, cacheEtag);
+                if (cached !== undefined) {
+                    return renderInspectResult(cached);
+                }
+            }
+        }
+        const data = await client.get(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/sublayout/inspect`);
+        const hint = buildHint(data.report);
+        const structured = { ...data, hint };
+        if (cache !== undefined && cacheEtag !== undefined) {
+            cache.set(template_id, element_path, cacheEtag, structured);
+        }
+        return renderInspectResult(structured);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { template_id, element_path },
+            hint: 'Pass the CONTAINER element_path (a `panel` or `grid_item`) — the tool ' +
+                'descends into its fragment child itself. Verify the path via ' +
+                'yootheme_builder_element_list (JSON-Pointer, RFC-6901: /0/children/1).',
+        });
+    }
+}
+/**
+ * Read the global state ETag used as the cache-invalidation token. Returns
+ * `undefined` (cache disabled for this call) if the etag probe fails or
+ * returns a non-string — a missing etag must never poison the cache key, and
+ * a probe failure should fall through to a live inspect rather than abort.
+ */
+async function fetchStateEtag(client) {
+    try {
+        const res = await client.get('/etag');
+        return typeof res.etag === 'string' && res.etag !== '' ? res.etag : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=inspect-sublayout-handler.js.map

package/dist/tools/sublayout/inspect-sublayout-handler.js.map

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

package/dist/tools/tool-builder/results.d.ts

@@ -12,6 +12,25 @@
  */
 import type { ResolvedSite } from '../../sites/registry.js';
 import type { ToolContent, ToolResult } from './types.js';
+/**
+ * F80 (2026-06-10): the size at/above which a JSON-document text body is
+ * split off into its own content block instead of carrying the in-band
+ * `[label @ host] ` site-prefix.
+ *
+ * Why a threshold rather than "all JSON": a tool host (Claude Code, …)
+ * spills only OVERSIZED tool results to a temp file. That file is read
+ * back with `jq`, so the bytes must be pure JSON — an in-band prefix
+ * corrupts the first line and breaks the parse (the observed F80
+ * friction on `page_get_layout`, a multi-kB layout dump). Small JSON
+ * envelopes (error results, single-element confirms, short lists) are
+ * NEVER dumped, so they keep the in-band prefix — which preserves the
+ * long-standing contract that `content[0].text` is the directly-parseable
+ * JSON for those results (141 error-matrix / handler tests depend on it).
+ *
+ * 8 kB is comfortably below any host's spill threshold yet above every
+ * small structured envelope this surface emits.
+ */
+export declare const SITE_PREFIX_JSON_SPLIT_THRESHOLD: number;
 /**
  * Convert any JSON-serializable value into the MCP content envelope
  * (2-space JSON). Wave G.6.4b: every payload is deep-walked through
@@ -37,6 +56,18 @@ export declare function errorResult(opts: {
  * Confirm-guard preview helper for destructive tools. Returns the
  * preview `ToolResult` when `confirm` is false; callers `return` it
  * before executing the destructive REST call.
+ *
+ * F131 (Wave 4a): the blocked-state result is now STRUCTURALLY distinct
+ * from a successful mutation. Previously the preview was a plain
+ * `jsonResult` with no `isError` — envelope-identical to a success — so a
+ * model that did not parse `preview:true` read "delete succeeded" and
+ * silently left the element in place (the dry-run / silent-no-op footgun
+ * class). Three redundant signals now make the block unmistakable:
+ *   1. result-level `isError: true` (hosts that only read the error flag),
+ *   2. body `applied: false` + `requires_confirmation: true` (structured
+ *      consumers),
+ *   3. a leading "NOT EXECUTED" line in the human-readable warning text
+ *      (models that skim prose).
  */
 export declare function confirmGuard(opts: {
     operation: string;

package/dist/tools/tool-builder/results.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/results.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAU1D;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CAM5F;AAaD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CAYb;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,UAAU,CAQb;AAuBD;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAC7C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,YAAY,GACnB,CAAC,CA2DH;AAED,wBAAgB,gBAAgB,CAC5B,aAAa,EAAE;IACX,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,EACD,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C,UAAU,CAgBZ"}
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/results.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAU1D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gCAAgC,QAAW,CAAC;AA2BzD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CAM5F;AAaD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CAYb;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,UAAU,CAab;AAuBD;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAC7C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,YAAY,GACnB,CAAC,CA6FH;AAED,wBAAgB,gBAAgB,CAC5B,aAAa,EAAE;IACX,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,EACD,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C,UAAU,CAgBZ"}