@wootsup/yt-builder-mcp 1.1.7 → 1.2.0

package/dist/tools/multi-items/clean-implode-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clean-implode-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAKH,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,2BAA2B;;;;;;;;;iBAWtC,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC/B;AAED,wBAAsB,4BAA4B,CAC9C,EAAE,MAAM,EAAE,EAAE,uBAAuB,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GACV,EAAE;IACC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,GACF,OAAO,CAAC,UAAU,CAAC,CAgCrB"}
+{"version":3,"file":"clean-implode-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAKH,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,2BAA2B;;;;;;;;;iBAWtC,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC/B;AAED,wBAAsB,4BAA4B,CAC9C,EAAE,MAAM,EAAE,EAAE,uBAAuB,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GACV,EAAE;IACC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,GACF,OAAO,CAAC,UAAU,CAAC,CAgCrB"}

package/dist/tools/multi-items/clean-implode-handler.js

@@ -12,7 +12,7 @@
  * @license MIT
  */
 import { z } from 'zod';
-import { encodeElementPath } from '../../client.js';
+import { encodeElementPath, encodeTemplateId } from '../../client.js';
 import { confirmGuard, errorResult, jsonResult, structuredResult, } from '../tool-builder.js';
 export const CLEAN_IMPLODE_OUTPUT_SCHEMA = z.object({
     template_id: z.string(),
@@ -37,7 +37,7 @@ export async function handleCleanImplodeDirectives({ client }, { template_id, el
     }
     const encoded = encodeElementPath(element_path);
     try {
-        const data = await client.post(`/pages/${encodeURIComponent(template_id)}/elements/${encoded}/multi-items/clean-implode`, { body: {}, etag });
+        const data = await client.post(`/pages/${encodeTemplateId(template_id)}/elements/${encoded}/multi-items/clean-implode`, { body: {}, etag });
         // The REST endpoint returns the canonical CLEAN_IMPLODE_OUTPUT_SCHEMA
         // shape ({template_id, element_path, cleaned_count, removed_directives,
         // new_etag}) — pass it through as structuredContent so the declared

package/dist/tools/multi-items/clean-implode-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"clean-implode-handler.js","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAmB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,kBAAkB,EAAE,CAAC,CAAC,KAAK,CACvB,CAAC,CAAC,MAAM,CAAC;QACL,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;KAC/C,CAAC,CACL;IACD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAMH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAC9C,EAAE,MAAM,EAA2B,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GAMV;IAED,qEAAqE;IACrE,qEAAqE;IACrE,sEAAsE;IACtE,8EAA8E;IAC9E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,YAAY,CAAC;YAChB,SAAS,EAAE,+CAA+C;YAC1D,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;SACzC,CAAC,CAAC;IACP,CAAC;IACD,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAC1B,UAAU,kBAAkB,CAAC,WAAW,CAAC,aAAa,OAAO,4BAA4B,EACzF,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CACrB,CAAC;QACF,sEAAsE;QACtE,wEAAwE;QACxE,oEAAoE;QACpE,mEAAmE;QACnE,4DAA4D;QAC5D,OAAO,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;YACtC,IAAI,EACA,4EAA4E;gBAC5E,iDAAiD;SACxD,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}
+{"version":3,"file":"clean-implode-handler.js","sourceRoot":"","sources":["../../../src/tools/multi-items/clean-implode-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAmB,MAAM,iBAAiB,CAAC;AACvF,OAAO,EACH,YAAY,EACZ,WAAW,EACX,UAAU,EACV,gBAAgB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,kBAAkB,EAAE,CAAC,CAAC,KAAK,CACvB,CAAC,CAAC,MAAM,CAAC;QACL,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;KAC/C,CAAC,CACL;IACD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAMH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAC9C,EAAE,MAAM,EAA2B,EACnC,EACI,WAAW,EACX,YAAY,EACZ,IAAI,EACJ,OAAO,GAMV;IAED,qEAAqE;IACrE,qEAAqE;IACrE,sEAAsE;IACtE,8EAA8E;IAC9E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,YAAY,CAAC;YAChB,SAAS,EAAE,+CAA+C;YAC1D,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;SACzC,CAAC,CAAC;IACP,CAAC;IACD,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAC1B,UAAU,gBAAgB,CAAC,WAAW,CAAC,aAAa,OAAO,4BAA4B,EACvF,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CACrB,CAAC;QACF,sEAAsE;QACtE,wEAAwE;QACxE,oEAAoE;QACpE,mEAAmE;QACnE,4DAA4D;QAC5D,OAAO,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;YACtC,IAAI,EACA,4EAA4E;gBAC5E,iDAAiD;SACxD,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}

package/dist/tools/multi-items/format/inspection-format.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Multi-Items inspection format-sidecar.
+ *
+ * Wave-16 #34 (6.1): the `inspect_multi_items_binding` report is passed
+ * through verbatim to `structuredContent` (which must stay schema-pure),
+ * but the human-readable text leg is serialized from the same payload.
+ * A deeply-nested report (e.g. a fully-qualified element subtree under
+ * `props` / `minimal_layout`, or a future `children` array) would balloon
+ * that text leg without bound. `capInspectionDepth` walks the value and
+ * truncates any object/array whose depth exceeds the cap, replacing it
+ * with an `…and N more` marker so the agent still sees that the subtree
+ * was elided rather than silently dropped.
+ *
+ * Pure / stateless. `structuredContent` is never passed through this —
+ * only the text-render copy — so output-schema validation is unaffected.
+ *
+ * @license MIT
+ */
+/**
+ * Default recursion cap for the inspect text render. Objects/arrays at a
+ * depth strictly greater than this are collapsed to the `…and N more`
+ * marker. The root value sits at depth 0.
+ */
+export declare const MAX_INSPECTION_DEPTH = 3;
+/**
+ * Recursively cap the depth of a JSON-serializable value.
+ *
+ * - Primitives (string / number / boolean / null / undefined) pass
+ *   through untouched at any depth.
+ * - An object or array sitting AT `maxDepth` is replaced by the
+ *   `…and N more` marker (N = its immediate child count) instead of
+ *   recursing further.
+ * - Otherwise the container is rebuilt with each child capped at
+ *   `depth + 1`.
+ *
+ * @param value    the value to cap.
+ * @param maxDepth recursion cap (defaults to {@link MAX_INSPECTION_DEPTH}).
+ * @param depth    current depth (internal; callers omit it).
+ */
+export declare function capInspectionDepth(value: unknown, maxDepth?: number, depth?: number): unknown;
+//# sourceMappingURL=inspection-format.d.ts.map

package/dist/tools/multi-items/format/inspection-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-format.d.ts","sourceRoot":"","sources":["../../../../src/tools/multi-items/format/inspection-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAYtC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAA6B,EACvC,KAAK,SAAI,GACV,OAAO,CAeT"}

package/dist/tools/multi-items/format/inspection-format.js

@@ -0,0 +1,64 @@
+/**
+ * Multi-Items inspection format-sidecar.
+ *
+ * Wave-16 #34 (6.1): the `inspect_multi_items_binding` report is passed
+ * through verbatim to `structuredContent` (which must stay schema-pure),
+ * but the human-readable text leg is serialized from the same payload.
+ * A deeply-nested report (e.g. a fully-qualified element subtree under
+ * `props` / `minimal_layout`, or a future `children` array) would balloon
+ * that text leg without bound. `capInspectionDepth` walks the value and
+ * truncates any object/array whose depth exceeds the cap, replacing it
+ * with an `…and N more` marker so the agent still sees that the subtree
+ * was elided rather than silently dropped.
+ *
+ * Pure / stateless. `structuredContent` is never passed through this —
+ * only the text-render copy — so output-schema validation is unaffected.
+ *
+ * @license MIT
+ */
+/**
+ * Default recursion cap for the inspect text render. Objects/arrays at a
+ * depth strictly greater than this are collapsed to the `…and N more`
+ * marker. The root value sits at depth 0.
+ */
+export const MAX_INSPECTION_DEPTH = 3;
+/** Render the marker that replaces a truncated subtree. */
+function truncationMarker(childCount, maxDepth) {
+    return `…and ${String(childCount)} more (truncated at depth ${String(maxDepth)})`;
+}
+/** Number of immediate children an object/array exposes. */
+function childCountOf(value) {
+    return Array.isArray(value) ? value.length : Object.keys(value).length;
+}
+/**
+ * Recursively cap the depth of a JSON-serializable value.
+ *
+ * - Primitives (string / number / boolean / null / undefined) pass
+ *   through untouched at any depth.
+ * - An object or array sitting AT `maxDepth` is replaced by the
+ *   `…and N more` marker (N = its immediate child count) instead of
+ *   recursing further.
+ * - Otherwise the container is rebuilt with each child capped at
+ *   `depth + 1`.
+ *
+ * @param value    the value to cap.
+ * @param maxDepth recursion cap (defaults to {@link MAX_INSPECTION_DEPTH}).
+ * @param depth    current depth (internal; callers omit it).
+ */
+export function capInspectionDepth(value, maxDepth = MAX_INSPECTION_DEPTH, depth = 0) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (depth >= maxDepth) {
+        return truncationMarker(childCountOf(value), maxDepth);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => capInspectionDepth(item, maxDepth, depth + 1));
+    }
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        out[key] = capInspectionDepth(child, maxDepth, depth + 1);
+    }
+    return out;
+}
+//# sourceMappingURL=inspection-format.js.map

package/dist/tools/multi-items/format/inspection-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-format.js","sourceRoot":"","sources":["../../../../src/tools/multi-items/format/inspection-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,2DAA2D;AAC3D,SAAS,gBAAgB,CAAC,UAAkB,EAAE,QAAgB;IAC1D,OAAO,QAAQ,MAAM,CAAC,UAAU,CAAC,6BAA6B,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;AACtF,CAAC;AAED,4DAA4D;AAC5D,SAAS,YAAY,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAC9B,KAAc,EACd,WAAmB,oBAAoB,EACvC,KAAK,GAAG,CAAC;IAET,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACpB,OAAO,gBAAgB,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC1E,GAAG,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/tools/multi-items/inspect-handler.d.ts

@@ -6,11 +6,27 @@
  * src/modules/builder-source-binding/src/MultiItemsInspector.php
  * for the report shape.
  *
+ * Wave-16 #34:
+ *   - 6.1 depth-cap: the human-readable text leg is capped at
+ *     {@link MAX_INSPECTION_DEPTH}; structuredContent stays verbatim so
+ *     it keeps validating against the output schema.
+ *   - 6.4 severity marker: the response carries a typed `hint.severity`
+ *     ("advisory" | "blocking") so the agent can tell a structural
+ *     container-level binding bug apart from informational guidance.
+ *
  * @license MIT
  */
 import { z } from 'zod';
 import { type RestClient } from '../../client.js';
 import { type ToolResult } from '../tool-builder.js';
+import { InspectionCache } from './inspection-cache.js';
+/**
+ * Severity of the advisory hint the inspector attaches to every report.
+ * `blocking` means the binding is structurally wrong (sits on the
+ * container instead of the `*_item` child) and the rendered output will
+ * be broken until fixed; `advisory` is informational guidance.
+ */
+export type HintSeverity = 'advisory' | 'blocking';
 export declare const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA: z.ZodObject<{
     template_id: z.ZodString;
     report: z.ZodObject<{
@@ -21,21 +37,40 @@ export declare const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA: z.ZodObject<{
         container_type: z.ZodNullable<z.ZodString>;
         item_type: z.ZodNullable<z.ZodString>;
         current_binding_level: z.ZodEnum<{
-            none: "none";
             container: "container";
             item: "item";
+            none: "none";
         }>;
         has_implode_directives: z.ZodBoolean;
         warning: z.ZodOptional<z.ZodString>;
         recommended_fix: z.ZodOptional<z.ZodString>;
     }, 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>;
+/** The structured inspect payload the handler caches + emits. */
+type InspectStructured = Record<string, unknown>;
 export interface MultiItemsHandlerDeps {
     readonly client: RestClient;
+    /**
+     * 6.2 — optional inspection cache. When provided, the handler keys
+     * results on (template_id, element_path, global-etag) with a 60s TTL.
+     * The builder injects one shared instance so repeat inspects within
+     * the TTL skip the REST round-trip; a write bumps the global etag and
+     * naturally invalidates the entry. Omit it to disable caching (e.g.
+     * the cold-AI shape-pin tests that assert the raw round-trip).
+     */
+    readonly cache?: InspectionCache<InspectStructured>;
 }
-export declare function handleInspectMultiItemsBinding({ client }: MultiItemsHandlerDeps, { template_id, element_path }: {
+export declare function handleInspectMultiItemsBinding({ client, cache }: MultiItemsHandlerDeps, { template_id, element_path }: {
     template_id: string;
     element_path: string;
 }): Promise<ToolResult>;
+export {};
 //# sourceMappingURL=inspect-handler.d.ts.map

package/dist/tools/multi-items/inspect-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/inspect-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhG,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;iBAe5C,CAAC;AAEH,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC/B;AAED,wBAAsB,8BAA8B,CAChD,EAAE,MAAM,EAAE,EAAE,qBAAqB,EACjC,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,UAAU,CAAC,CAqBrB"}
+{"version":3,"file":"inspect-handler.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/inspect-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;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,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,CAAC;AAEnD,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwB5C,CAAC;AAEH,iEAAiE;AACjE,KAAK,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;CACvD;AAoDD,wBAAsB,8BAA8B,CAChD,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,qBAAqB,EACxC,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,UAAU,CAAC,CAwCrB"}

package/dist/tools/multi-items/inspect-handler.js

@@ -6,11 +6,20 @@
  * src/modules/builder-source-binding/src/MultiItemsInspector.php
  * for the report shape.
  *
+ * Wave-16 #34:
+ *   - 6.1 depth-cap: the human-readable text leg is capped at
+ *     {@link MAX_INSPECTION_DEPTH}; structuredContent stays verbatim so
+ *     it keeps validating against the output schema.
+ *   - 6.4 severity marker: the response carries a typed `hint.severity`
+ *     ("advisory" | "blocking") so the agent can tell a structural
+ *     container-level binding bug apart from informational guidance.
+ *
  * @license MIT
  */
 import { z } from 'zod';
-import { encodeElementPath } from '../../client.js';
+import { encodeElementPath, encodeTemplateId } from '../../client.js';
 import { errorResult, jsonResult, structuredResult } from '../tool-builder.js';
+import { capInspectionDepth } from './format/inspection-format.js';
 export const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA = z.object({
     template_id: z.string(),
     report: z.object({
@@ -26,25 +35,99 @@ export const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA = z.object({
         recommended_fix: z.string().optional(),
     }),
     etag: z.string(),
+    // 6.4 — typed advisory/blocking marker. Optional so a verbatim REST
+    // passthrough that predates this field still validates, but the
+    // handler always populates it.
+    hint: z
+        .object({
+        severity: z.enum(['advisory', 'blocking']),
+        message: z.string(),
+    })
+        .optional(),
 });
-export async function handleInspectMultiItemsBinding({ client }, { template_id, element_path }) {
+/**
+ * Classify the report into an advisory/blocking hint. A binding that
+ * sits on the container level is the structural bug Multi-Items aims to
+ * surface — that is `blocking`. Everything else is `advisory`.
+ */
+function buildHint(report) {
+    const r = (report ?? {});
+    if (r.current_binding_level === 'container') {
+        const fix = typeof r.recommended_fix === 'string' && r.recommended_fix !== ''
+            ? r.recommended_fix
+            : 'Move the binding to the first `*_item` child element.';
+        return { severity: 'blocking', message: fix };
+    }
+    return {
+        severity: 'advisory',
+        message: 'Binding looks structurally correct. Verify element_path via ' +
+            'yootheme_builder_element_list if the source still renders empty.',
+    };
+}
+/**
+ * Render a structured inspect payload into the ToolResult envelope.
+ * Shared by the cache-hit and cache-miss paths so both legs (text +
+ * structuredContent) are built identically.
+ *
+ * 6.1 — 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_MULTI_ITEMS_OUTPUT_SCHEMA
+ * (additionalProperties:false).
+ */
+function renderInspectResult(structured) {
+    const text = jsonResult(capInspectionDepth(structured));
+    return structuredResult(text, structured);
+}
+export async function handleInspectMultiItemsBinding({ client, cache }, { template_id, element_path }) {
     const encoded = encodeElementPath(element_path);
     try {
-        const data = await client.get(`/pages/${encodeURIComponent(template_id)}/elements/${encoded}/multi-items/inspect`);
-        // The REST endpoint already returns the canonical
-        // {template_id, report, etag} shape — pass it through as
-        // structuredContent so the declared outputSchema is satisfied
-        // (a tool with an outputSchema MUST emit structuredContent, else
-        // the MCP SDK rejects the call with -32602).
-        return structuredResult(jsonResult(data), data);
+        // 6.2 — when a cache is wired, key on the GLOBAL state etag. Every
+        // write tool 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}/multi-items/inspect`);
+        // 6.4 — attach the typed severity marker to the structured payload.
+        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: 'Verify element_path via yootheme_builder_element_list. Paths are JSON-Pointer ' +
-                'style ("/templates/<id>/layout/children/0").',
+                '(RFC-6901) style: /0/children/1. Use yootheme_builder_element_list to enumerate ' +
+                'valid paths.',
         });
     }
 }
+/**
+ * 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 the whole call.
+ */
+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-handler.js.map

package/dist/tools/multi-items/inspect-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"inspect-handler.js","sourceRoot":"","sources":["../../../src/tools/multi-items/inspect-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAmB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAmB,MAAM,oBAAoB,CAAC;AAEhG,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;QACxB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;QACxB,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE;QACzB,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;QACpB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACrC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAChC,qBAAqB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;QAC5D,sBAAsB,EAAE,CAAC,CAAC,OAAO,EAAE;QACnC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC9B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACzC,CAAC;IACF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AAMH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAChD,EAAE,MAAM,EAAyB,EACjC,EAAE,WAAW,EAAE,YAAY,EAAiD;IAE5E,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CACzB,UAAU,kBAAkB,CAAC,WAAW,CAAC,aAAa,OAAO,sBAAsB,CACtF,CAAC;QACF,kDAAkD;QAClD,yDAAyD;QACzD,8DAA8D;QAC9D,iEAAiE;QACjE,6CAA6C;QAC7C,OAAO,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,OAAO,WAAW,CAAC;YACf,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;YACtC,IAAI,EACA,gFAAgF;gBAChF,8CAA8C;SACrD,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}
+{"version":3,"file":"inspect-handler.js","sourceRoot":"","sources":["../../../src/tools/multi-items/inspect-handler.ts"],"names":[],"mappings":"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"}

package/dist/tools/multi-items/inspection-cache.d.ts

@@ -0,0 +1,85 @@
+/**
+ * InspectionCache — Wave-16 #34 (6.2).
+ *
+ * A tiny in-process TTL cache for `inspect_multi_items_binding` results.
+ * Keyed by `(template_id, element_path, etag)`:
+ *
+ *   - `template_id` + `element_path` identify the element;
+ *   - `etag` is the GLOBAL state ETag (from `GET /etag`). Every write
+ *     tool bumps it (see ETAG schema note: "every successful write
+ *     returns a NEW ETag"). So a write to ANY template surfaces a fresh
+ *     etag → a NEW cache key → a guaranteed miss. The stale entry for a
+ *     mutated template can never be served. This reuses the existing
+ *     etag-bump mechanism rather than inventing a parallel invalidation
+ *     channel.
+ *
+ * TTL is a hard 60s upper bound so an entry cannot live indefinitely
+ * even if the etag never changes (read-only sessions). The clock is
+ * injectable so the TTL behaviour is testable without sleeping.
+ *
+ * Bounded growth — Wave-16 Phase-6 nit. The key embeds the GLOBAL etag,
+ * and every write bumps it, so each `set()` lands under a NEW key while
+ * the old-etag entries are never re-queried (the handler always reads the
+ * current etag). Without a bound they would accumulate in the Map forever
+ * in a long-lived high-write session. Two cheap defenses keep it bounded:
+ *
+ *   1. Opportunistic sweep on every `set()`: drop entries already past
+ *      the TTL. The TTL is a hard upper bound, so a past-TTL entry is dead
+ *      and can never be served — sweeping it changes no observable
+ *      behaviour, it only reclaims the slot.
+ *   2. Hard max-size cap with oldest-first eviction (belt-and-suspenders)
+ *      for the pathological case where many DISTINCT keys all stay fresh
+ *      (a read-only burst the sweep cannot reclaim). `Map` preserves
+ *      insertion order, so the oldest entry is the first key.
+ *
+ * Concrete generic type `T` — no `any`. The cache stores whatever the
+ * handler computed (the structured inspect payload).
+ *
+ * @license MIT
+ */
+/** Hard TTL upper bound for a cached inspection entry (60 seconds). */
+export declare const INSPECTION_CACHE_TTL_MS = 60000;
+/**
+ * Hard ceiling on live entries. Reached only when many DISTINCT keys stay
+ * fresh inside the TTL (a read-only burst the TTL-sweep cannot reclaim);
+ * the normal write-driven etag churn is reclaimed by the sweep long before
+ * this. 256 covers a generous working set while keeping the Map tiny.
+ */
+export declare const INSPECTION_CACHE_MAX_ENTRIES = 256;
+/** Monotonic-ish millisecond clock; defaults to `Date.now`. */
+export type Clock = () => number;
+export declare class InspectionCache<T> {
+    private readonly store;
+    private readonly now;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    constructor(now?: Clock, ttlMs?: number, maxEntries?: number);
+    /** Build the composite cache key. Pipe-joined; the parts are
+     * server-controlled identifiers (template id, JSON-Pointer, quoted
+     * etag) so collision via a literal `|` in a value is not a concern. */
+    private key;
+    /** Read a fresh entry, or `undefined` on miss / expiry. Expired
+     * entries are evicted on access. */
+    get(templateId: string, elementPath: string, etag: string): T | undefined;
+    /**
+     * Store a value under the composite key, stamped with the clock.
+     *
+     * Bounds the Map first (sweep past-TTL entries, then enforce the
+     * max-size cap with oldest-first eviction) so a long-lived high-write
+     * session cannot leak old-etag keys. See class doc for the why.
+     */
+    set(templateId: string, elementPath: string, etag: string, value: T): void;
+    /**
+     * Number of LIVE (non-expired) entries currently held. Counts rather
+     * than returns `store.size` so a caller (and the tests) sees the true
+     * working-set size even if a not-yet-swept dead entry lingers.
+     */
+    size(): number;
+    /** Drop every entry whose TTL has elapsed. Cheap, and dead entries
+     * can never be served, so this changes no observable behaviour. */
+    private sweepExpired;
+    /** Evict oldest-first until the Map is within the max-size cap. `Map`
+     * iterates in insertion order, so the first key is the oldest. */
+    private enforceMaxEntries;
+}
+//# sourceMappingURL=inspection-cache.d.ts.map

package/dist/tools/multi-items/inspection-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-cache.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/inspection-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,+DAA+D;AAC/D,MAAM,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC;AAOjC,qBAAa,eAAe,CAAC,CAAC;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGhC,GAAG,GAAE,KAAgB,EACrB,KAAK,GAAE,MAAgC,EACvC,UAAU,GAAE,MAAqC;IAOrD;;2EAEuE;IACvE,OAAO,CAAC,GAAG;IAIX;wCACoC;IACpC,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAWzE;;;;;;OAMG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAO1E;;;;OAIG;IACH,IAAI,IAAI,MAAM;IASd;uEACmE;IACnE,OAAO,CAAC,YAAY;IASpB;sEACkE;IAClE,OAAO,CAAC,iBAAiB;CAO5B"}

package/dist/tools/multi-items/inspection-cache.js

@@ -0,0 +1,126 @@
+/**
+ * InspectionCache — Wave-16 #34 (6.2).
+ *
+ * A tiny in-process TTL cache for `inspect_multi_items_binding` results.
+ * Keyed by `(template_id, element_path, etag)`:
+ *
+ *   - `template_id` + `element_path` identify the element;
+ *   - `etag` is the GLOBAL state ETag (from `GET /etag`). Every write
+ *     tool bumps it (see ETAG schema note: "every successful write
+ *     returns a NEW ETag"). So a write to ANY template surfaces a fresh
+ *     etag → a NEW cache key → a guaranteed miss. The stale entry for a
+ *     mutated template can never be served. This reuses the existing
+ *     etag-bump mechanism rather than inventing a parallel invalidation
+ *     channel.
+ *
+ * TTL is a hard 60s upper bound so an entry cannot live indefinitely
+ * even if the etag never changes (read-only sessions). The clock is
+ * injectable so the TTL behaviour is testable without sleeping.
+ *
+ * Bounded growth — Wave-16 Phase-6 nit. The key embeds the GLOBAL etag,
+ * and every write bumps it, so each `set()` lands under a NEW key while
+ * the old-etag entries are never re-queried (the handler always reads the
+ * current etag). Without a bound they would accumulate in the Map forever
+ * in a long-lived high-write session. Two cheap defenses keep it bounded:
+ *
+ *   1. Opportunistic sweep on every `set()`: drop entries already past
+ *      the TTL. The TTL is a hard upper bound, so a past-TTL entry is dead
+ *      and can never be served — sweeping it changes no observable
+ *      behaviour, it only reclaims the slot.
+ *   2. Hard max-size cap with oldest-first eviction (belt-and-suspenders)
+ *      for the pathological case where many DISTINCT keys all stay fresh
+ *      (a read-only burst the sweep cannot reclaim). `Map` preserves
+ *      insertion order, so the oldest entry is the first key.
+ *
+ * Concrete generic type `T` — no `any`. The cache stores whatever the
+ * handler computed (the structured inspect payload).
+ *
+ * @license MIT
+ */
+/** Hard TTL upper bound for a cached inspection entry (60 seconds). */
+export const INSPECTION_CACHE_TTL_MS = 60_000;
+/**
+ * Hard ceiling on live entries. Reached only when many DISTINCT keys stay
+ * fresh inside the TTL (a read-only burst the TTL-sweep cannot reclaim);
+ * the normal write-driven etag churn is reclaimed by the sweep long before
+ * this. 256 covers a generous working set while keeping the Map tiny.
+ */
+export const INSPECTION_CACHE_MAX_ENTRIES = 256;
+export class InspectionCache {
+    store = new Map();
+    now;
+    ttlMs;
+    maxEntries;
+    constructor(now = Date.now, ttlMs = INSPECTION_CACHE_TTL_MS, maxEntries = INSPECTION_CACHE_MAX_ENTRIES) {
+        this.now = now;
+        this.ttlMs = ttlMs;
+        this.maxEntries = maxEntries;
+    }
+    /** Build the composite cache key. Pipe-joined; the parts are
+     * server-controlled identifiers (template id, JSON-Pointer, quoted
+     * etag) so collision via a literal `|` in a value is not a concern. */
+    key(templateId, elementPath, etag) {
+        return `${templateId}|${elementPath}|${etag}`;
+    }
+    /** Read a fresh entry, or `undefined` on miss / expiry. Expired
+     * entries are evicted on access. */
+    get(templateId, elementPath, etag) {
+        const k = this.key(templateId, elementPath, etag);
+        const entry = this.store.get(k);
+        if (entry === undefined)
+            return undefined;
+        if (this.now() - entry.storedAt >= this.ttlMs) {
+            this.store.delete(k);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /**
+     * Store a value under the composite key, stamped with the clock.
+     *
+     * Bounds the Map first (sweep past-TTL entries, then enforce the
+     * max-size cap with oldest-first eviction) so a long-lived high-write
+     * session cannot leak old-etag keys. See class doc for the why.
+     */
+    set(templateId, elementPath, etag, value) {
+        const k = this.key(templateId, elementPath, etag);
+        this.sweepExpired();
+        this.store.set(k, { value, storedAt: this.now() });
+        this.enforceMaxEntries();
+    }
+    /**
+     * Number of LIVE (non-expired) entries currently held. Counts rather
+     * than returns `store.size` so a caller (and the tests) sees the true
+     * working-set size even if a not-yet-swept dead entry lingers.
+     */
+    size() {
+        let live = 0;
+        const cutoff = this.now();
+        for (const entry of this.store.values()) {
+            if (cutoff - entry.storedAt < this.ttlMs)
+                live++;
+        }
+        return live;
+    }
+    /** Drop every entry whose TTL has elapsed. Cheap, and dead entries
+     * can never be served, so this changes no observable behaviour. */
+    sweepExpired() {
+        const cutoff = this.now();
+        for (const [k, entry] of this.store) {
+            if (cutoff - entry.storedAt >= this.ttlMs) {
+                this.store.delete(k);
+            }
+        }
+    }
+    /** Evict oldest-first until the Map is within the max-size cap. `Map`
+     * iterates in insertion order, so the first key is the oldest. */
+    enforceMaxEntries() {
+        while (this.store.size > this.maxEntries) {
+            const oldest = this.store.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.store.delete(oldest);
+        }
+    }
+}
+//# sourceMappingURL=inspection-cache.js.map

package/dist/tools/multi-items/inspection-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-cache.js","sourceRoot":"","sources":["../../../src/tools/multi-items/inspection-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAUhD,MAAM,OAAO,eAAe;IACP,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IACzC,GAAG,CAAQ;IACX,KAAK,CAAS;IACd,UAAU,CAAS;IAEpC,YACI,MAAa,IAAI,CAAC,GAAG,EACrB,QAAgB,uBAAuB,EACvC,aAAqB,4BAA4B;QAEjD,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACjC,CAAC;IAED;;2EAEuE;IAC/D,GAAG,CAAC,UAAkB,EAAE,WAAmB,EAAE,IAAY;QAC7D,OAAO,GAAG,UAAU,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;IAClD,CAAC;IAED;wCACoC;IACpC,GAAG,CAAC,UAAkB,EAAE,WAAmB,EAAE,IAAY;QACrD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACrB,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACvB,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,UAAkB,EAAE,WAAmB,EAAE,IAAY,EAAE,KAAQ;QAC/D,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,IAAI;QACA,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACtC,IAAI,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,KAAK;gBAAE,IAAI,EAAE,CAAC;QACrD,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;uEACmE;IAC3D,YAAY;QAChB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,MAAM,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACxC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACzB,CAAC;QACL,CAAC;IACL,CAAC;IAED;sEACkE;IAC1D,iBAAiB;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC9C,IAAI,MAAM,KAAK,SAAS;gBAAE,MAAM;YAChC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;IACL,CAAC;CACJ"}

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

@@ -3,12 +3,41 @@
  *
  * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1). Handler
  * bodies live in `./handlers-read.ts` (pages_list, page_get_layout,
- * page_get_schema, get_etag) and `./handlers-write.ts` (page_save,
- * page_publish — 3-phase progress contract).
+ * page_get_schema, get_etag, template_summary) and `./handlers-write.ts`
+ * (page_save, page_publish, pages_create, pages_delete — 3-phase
+ * progress contract).
+ *
+ * Surface: 9 page-level tools (pre-C4: 7; v1.2 C4 added pages_create +
+ * pages_delete wrapping POST /pages and DELETE /pages/{id}).
  *
  * @license MIT
  */
 import type { ClientPool } from '../../sites/client-pool.js';
 import { type AnyToolDefinition } from '../tool-builder.js';
+/**
+ * Render-context descriptor emitted by the page builders (Wave-16 #33-C).
+ *
+ * Gives the calling agent the page's template lineage, locale, and origin
+ * site in one place so it does not need a second round-trip to reason
+ * about where/how a page renders. `site_url` is always populated from the
+ * resolved site; `parent_template_id` and `locale` are `null` when the
+ * builder cannot reach them (rather than absent) so the shape is stable
+ * for consumers.
+ */
+export interface RenderContext {
+    readonly parent_template_id: string | null;
+    readonly locale: string | null;
+    readonly site_url: string;
+}
+/**
+ * Build the {@link RenderContext} from the data reachable in a page
+ * builder. Pure: no I/O, no `any`. Missing `parentTemplateId` / `locale`
+ * collapse to `null`.
+ */
+export declare function buildRenderContext(input: {
+    siteUrl: string;
+    parentTemplateId?: string | null;
+    locale?: string | null;
+}): RenderContext;
 export declare function buildPagesTools(pool: ClientPool): readonly AnyToolDefinition[];
 //# sourceMappingURL=builders.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAI7D,OAAO,EAKH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AA8B5B,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CAoI9E"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAK7D,OAAO,EAKH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AAsC5B;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GAAG,aAAa,CAMhB;AAyCD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CAqM9E"}