@wootsup/yt-builder-mcp 1.1.6 → 1.1.7

package/dist/tools/multi-items/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Multi-Items tool barrel — public entry-point for the YT-Pro
+ * Multi-Items binding pattern tools.
+ *
+ *   yootheme_builder_inspect_multi_items_binding
+ *     → Report the Multi-Items binding state for an element.
+ *
+ *   yootheme_builder_clean_implode_directives
+ *     → Remove legacy implode directives from an element binding.
+ *
+ * The canonical container ↔ item map lives in `./item-container-map.ts`
+ * (mirror of `WootsUp\BuilderMcp\Elements\ItemContainerMap`).
+ *
+ * @license MIT
+ */
+export { buildMultiItemsTools } from './builders.js';
+export { ITEM_CHILDREN_OF_CONTAINER, containerOf, isContainer, isItem, itemOf, } from './item-container-map.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/multi-items/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACH,0BAA0B,EAC1B,WAAW,EACX,WAAW,EACX,MAAM,EACN,MAAM,GACT,MAAM,yBAAyB,CAAC"}

package/dist/tools/multi-items/index.js

@@ -0,0 +1,18 @@
+/**
+ * Multi-Items tool barrel — public entry-point for the YT-Pro
+ * Multi-Items binding pattern tools.
+ *
+ *   yootheme_builder_inspect_multi_items_binding
+ *     → Report the Multi-Items binding state for an element.
+ *
+ *   yootheme_builder_clean_implode_directives
+ *     → Remove legacy implode directives from an element binding.
+ *
+ * The canonical container ↔ item map lives in `./item-container-map.ts`
+ * (mirror of `WootsUp\BuilderMcp\Elements\ItemContainerMap`).
+ *
+ * @license MIT
+ */
+export { buildMultiItemsTools } from './builders.js';
+export { ITEM_CHILDREN_OF_CONTAINER, containerOf, isContainer, isItem, itemOf, } from './item-container-map.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/multi-items/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/multi-items/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACH,0BAA0B,EAC1B,WAAW,EACX,WAAW,EACX,MAAM,EACN,MAAM,GACT,MAAM,yBAAyB,CAAC"}

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

@@ -0,0 +1,41 @@
+/**
+ * `inspect_multi_items_binding` handler — surfaces Multi-Items binding
+ * state on an element via REST round-trip.
+ *
+ * Companion of the PHP `MultiItemsInspector` — see
+ * src/modules/builder-source-binding/src/MultiItemsInspector.php
+ * for the report shape.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { type RestClient } from '../../client.js';
+import { type ToolResult } from '../tool-builder.js';
+export declare const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA: z.ZodObject<{
+    template_id: z.ZodString;
+    report: z.ZodObject<{
+        element_path: z.ZodString;
+        element_type: z.ZodString;
+        is_container: z.ZodBoolean;
+        is_item: z.ZodBoolean;
+        container_type: z.ZodNullable<z.ZodString>;
+        item_type: z.ZodNullable<z.ZodString>;
+        current_binding_level: z.ZodEnum<{
+            none: "none";
+            container: "container";
+            item: "item";
+        }>;
+        has_implode_directives: z.ZodBoolean;
+        warning: z.ZodOptional<z.ZodString>;
+        recommended_fix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    etag: z.ZodString;
+}, z.core.$strip>;
+export interface MultiItemsHandlerDeps {
+    readonly client: RestClient;
+}
+export declare function handleInspectMultiItemsBinding({ client }: MultiItemsHandlerDeps, { template_id, element_path }: {
+    template_id: string;
+    element_path: string;
+}): Promise<ToolResult>;
+//# sourceMappingURL=inspect-handler.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,50 @@
+/**
+ * `inspect_multi_items_binding` handler — surfaces Multi-Items binding
+ * state on an element via REST round-trip.
+ *
+ * Companion of the PHP `MultiItemsInspector` — see
+ * src/modules/builder-source-binding/src/MultiItemsInspector.php
+ * for the report shape.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { encodeElementPath } from '../../client.js';
+import { errorResult, jsonResult, structuredResult } from '../tool-builder.js';
+export const INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA = z.object({
+    template_id: z.string(),
+    report: z.object({
+        element_path: z.string(),
+        element_type: z.string(),
+        is_container: z.boolean(),
+        is_item: z.boolean(),
+        container_type: z.string().nullable(),
+        item_type: z.string().nullable(),
+        current_binding_level: z.enum(['none', 'container', 'item']),
+        has_implode_directives: z.boolean(),
+        warning: z.string().optional(),
+        recommended_fix: z.string().optional(),
+    }),
+    etag: z.string(),
+});
+export async function handleInspectMultiItemsBinding({ client }, { 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);
+    }
+    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").',
+        });
+    }
+}
+//# sourceMappingURL=inspect-handler.js.map

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

@@ -0,0 +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"}

package/dist/tools/multi-items/item-container-map.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Multi-Items pattern — TypeScript mirror of the PHP
+ * `WootsUp\BuilderMcp\Elements\ItemContainerMap` constant.
+ *
+ * YT-Pro 4.5.33+ implements `SourceTransform::repeatSource` which
+ * clones the *source-bearing element* N-times as siblings inside its
+ * parent. For "1 container with N children" the binding MUST live on
+ * the `*_item` child element, NEVER on the container.
+ *
+ * The PHP and TS maps MUST stay in lock-step — both files carry a
+ * pin-test that fails if the canonical pairings drift.
+ *
+ * @license MIT
+ */
+/**
+ * Live-verified against `themes/yootheme/packages/builder/elements/
+ * *_item/` on YT-Pro 4.5.33 (dev server, 2026-05-22). 16 pairs total.
+ *
+ * NB: There is NO `slider` / `slider_item` pair on YT-Pro 4.5.33 — the
+ * YT slider/carousel widgets render via `slideshow`, `overlay-slider`,
+ * and `panel-slider`.
+ */
+export declare const ITEM_CHILDREN_OF_CONTAINER: Readonly<Record<string, string>>;
+/**
+ * Surface the `*_item` child type for a known container, or null when
+ * the input is not a known multi-item container.
+ */
+export declare function itemOf(containerType: string): string | null;
+/**
+ * Surface the container type for a known `*_item`, or null otherwise.
+ */
+export declare function containerOf(itemType: string): string | null;
+/**
+ * `true` when $type is one of the multi-item-capable containers.
+ */
+export declare function isContainer(type: string): boolean;
+/**
+ * `true` when $type is a `*_item` child of a multi-item container.
+ */
+export declare function isItem(type: string): boolean;
+//# sourceMappingURL=item-container-map.d.ts.map

package/dist/tools/multi-items/item-container-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-container-map.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/item-container-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiBtE,CAAC;AAEH;;;GAGG;AACH,wBAAgB,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5C"}

package/dist/tools/multi-items/item-container-map.js

@@ -0,0 +1,73 @@
+/**
+ * Multi-Items pattern — TypeScript mirror of the PHP
+ * `WootsUp\BuilderMcp\Elements\ItemContainerMap` constant.
+ *
+ * YT-Pro 4.5.33+ implements `SourceTransform::repeatSource` which
+ * clones the *source-bearing element* N-times as siblings inside its
+ * parent. For "1 container with N children" the binding MUST live on
+ * the `*_item` child element, NEVER on the container.
+ *
+ * The PHP and TS maps MUST stay in lock-step — both files carry a
+ * pin-test that fails if the canonical pairings drift.
+ *
+ * @license MIT
+ */
+/**
+ * Live-verified against `themes/yootheme/packages/builder/elements/
+ * *_item/` on YT-Pro 4.5.33 (dev server, 2026-05-22). 16 pairs total.
+ *
+ * NB: There is NO `slider` / `slider_item` pair on YT-Pro 4.5.33 — the
+ * YT slider/carousel widgets render via `slideshow`, `overlay-slider`,
+ * and `panel-slider`.
+ */
+export const ITEM_CHILDREN_OF_CONTAINER = Object.freeze({
+    accordion: 'accordion_item',
+    button: 'button_item',
+    description_list: 'description_list_item',
+    gallery: 'gallery_item',
+    grid: 'grid_item',
+    list: 'list_item',
+    map: 'map_item',
+    nav: 'nav_item',
+    'overlay-slider': 'overlay-slider_item',
+    'panel-slider': 'panel-slider_item',
+    popover: 'popover_item',
+    slideshow: 'slideshow_item',
+    social: 'social_item',
+    subnav: 'subnav_item',
+    switcher: 'switcher_item',
+    table: 'table_item',
+});
+/**
+ * Surface the `*_item` child type for a known container, or null when
+ * the input is not a known multi-item container.
+ */
+export function itemOf(containerType) {
+    return Object.prototype.hasOwnProperty.call(ITEM_CHILDREN_OF_CONTAINER, containerType)
+        ? ITEM_CHILDREN_OF_CONTAINER[containerType]
+        : null;
+}
+/**
+ * Surface the container type for a known `*_item`, or null otherwise.
+ */
+export function containerOf(itemType) {
+    for (const [container, item] of Object.entries(ITEM_CHILDREN_OF_CONTAINER)) {
+        if (item === itemType) {
+            return container;
+        }
+    }
+    return null;
+}
+/**
+ * `true` when $type is one of the multi-item-capable containers.
+ */
+export function isContainer(type) {
+    return Object.prototype.hasOwnProperty.call(ITEM_CHILDREN_OF_CONTAINER, type);
+}
+/**
+ * `true` when $type is a `*_item` child of a multi-item container.
+ */
+export function isItem(type) {
+    return Object.values(ITEM_CHILDREN_OF_CONTAINER).includes(type);
+}
+//# sourceMappingURL=item-container-map.js.map

package/dist/tools/multi-items/item-container-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-container-map.js","sourceRoot":"","sources":["../../../src/tools/multi-items/item-container-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAqC,MAAM,CAAC,MAAM,CAAC;IACtF,SAAS,EAAE,gBAAgB;IAC3B,MAAM,EAAE,aAAa;IACrB,gBAAgB,EAAE,uBAAuB;IACzC,OAAO,EAAE,cAAc;IACvB,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,WAAW;IACjB,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,UAAU;IACf,gBAAgB,EAAE,qBAAqB;IACvC,cAAc,EAAE,mBAAmB;IACnC,OAAO,EAAE,cAAc;IACvB,SAAS,EAAE,gBAAgB;IAC3B,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,QAAQ,EAAE,eAAe;IACzB,KAAK,EAAE,YAAY;CACtB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,aAAqB;IACxC,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,0BAA0B,EAAE,aAAa,CAAC;QAClF,CAAC,CAAE,0BAA0B,CAAC,aAAa,CAAY;QACvD,CAAC,CAAC,IAAI,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IACxC,KAAK,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,0BAA0B,CAAC,EAAE,CAAC;QACzE,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpB,OAAO,SAAS,CAAC;QACrB,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,0BAA0B,EAAE,IAAI,CAAC,CAAC;AAClF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY;IAC/B,OAAO,MAAM,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC"}

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

@@ -0,0 +1,14 @@
+/**
+ * Page-tool builders — pure `defineTool` factory list.
+ *
+ * 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).
+ *
+ * @license MIT
+ */
+import type { ClientPool } from '../../sites/client-pool.js';
+import { type AnyToolDefinition } from '../tool-builder.js';
+export declare function buildPagesTools(pool: ClientPool): readonly AnyToolDefinition[];
+//# sourceMappingURL=builders.d.ts.map

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

@@ -0,0 +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"}

package/dist/tools/pages/builders.js

@@ -0,0 +1,136 @@
+/**
+ * Page-tool builders — pure `defineTool` factory list.
+ *
+ * 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).
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { withSiteRetry } from '../pool-resolve-helper.js';
+import { SITE_ID_SCHEMA, TEMPLATE_ID } from '../shared-schemas.js';
+import { FIELDS, FLAT } from '../sparse-fields.js';
+import { defineTool, mutating, readOnly, withSiteMeta, } from '../tool-builder.js';
+import { handleGetEtag, handlePageGetLayout, handlePageGetSchema, handlePagesList, handleTemplateSummary, } from './handlers-read.js';
+import { handlePagePublish, handlePageSave } from './handlers-write.js';
+import { ETAG_OUTPUT_SCHEMA, PAGES_LIST_OUTPUT_SCHEMA, SCHEMA_OUTPUT_SCHEMA, TEMPLATE_SUMMARY_OUTPUT_SCHEMA, } from './schemas.js';
+// F-14: page-level save/publish accept OPTIONAL ETag (no precondition lock
+// at template level — element/binding mutations REQUIRE one via the strict
+// ETAG in shared-schemas.ts). Schema and description now agree: optional
+// here, recommended for safety. When provided, 412 Precondition Failed is
+// raised on stale snapshots; when omitted, the save proceeds unconditionally.
+const ETAG = z
+    .string()
+    .optional()
+    .describe('Optimistic-lock ETag (from yootheme_builder_get_etag). ' +
+    'Optional; when provided, optimistic-lock is enforced (412 on conflict). ' +
+    'When omitted, last-write-wins applies. Recommended for collaborative edits.');
+export function buildPagesTools(pool) {
+    return [
+        defineTool({
+            name: 'yootheme_builder_pages_list',
+            description: 'List all pages, templates, and layouts in the YOOtheme Pro builder. ' +
+                'Returns template_id, label, type, element count, and frontend_url per row. ' +
+                'CALL THIS FIRST to discover available template IDs before any tool that needs ' +
+                'a template_id (page_get_layout, element_list, page_get_schema, etc.). ' +
+                'Keywords: list pages, list templates, list layouts, discover template_id, ' +
+                'index, available templates, what pages exist. ' +
+                'Pass `fields:["id","label"]` to slim. ' +
+                'Returns ALL pages in one call (no pagination, typically <50 templates per site). ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: { site_id: SITE_ID_SCHEMA, fields: FIELDS },
+            outputSchema: PAGES_LIST_OUTPUT_SCHEMA,
+            annotations: readOnly('List Pages'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePagesList(client, rest), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_page_get_layout',
+            description: 'Get full layout tree for one template. Default nested `{layout, ' +
+                'etag}`. Set `flat:true` for depth-first array `{elements:[...], ' +
+                'etag}`; combine with `fields[]` to project per-element. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                template_id: TEMPLATE_ID,
+                flat: FLAT,
+                fields: FIELDS,
+            },
+            // No outputSchema: the response shape is a union (nested OR flat with
+            // optional projection) and the JSON-Pointer-keyed nested shape is
+            // structurally open-ended — modelling it precisely buys nothing here.
+            annotations: readOnly('Get Page Layout'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePageGetLayout(client, rest), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_page_get_schema',
+            description: 'Get the flat schema for a template — a list of nodes with their JSON-Pointer ' +
+                'paths and element types. Best entry-point for navigation: lighter than ' +
+                'page_get_layout, sufficient to locate elements before editing. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: { site_id: SITE_ID_SCHEMA, template_id: TEMPLATE_ID },
+            outputSchema: SCHEMA_OUTPUT_SCHEMA,
+            annotations: readOnly('Get Page Schema'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePageGetSchema(client, rest), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_get_etag',
+            description: 'Get the current ETag (state revision) for the YOOtheme builder. ' +
+                'Returns sha256+revision string used for optimistic locking on writes. ' +
+                'Pass the returned value back as `etag` on any write tool (page_save, page_publish, ' +
+                'element_add, element_update_settings, element_clone, element_move, element_delete). ' +
+                'The server returns HTTP 412 if the ETag has changed since you read it. ' +
+                'Keywords: get etag, current etag, state revision, optimistic lock, version stamp. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: { site_id: SITE_ID_SCHEMA },
+            outputSchema: ETAG_OUTPUT_SCHEMA,
+            annotations: readOnly('Get ETag'),
+            handler: async ({ site_id }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleGetEtag(client), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_template_summary',
+            description: 'Token-efficient template overview: element counts by type, binding ' +
+                'count, max nesting depth, and named landmark sections — computed ' +
+                'server-side in one call. Use this to grasp a large template before ' +
+                'pulling element_list or page_get_layout. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: { site_id: SITE_ID_SCHEMA, template_id: TEMPLATE_ID },
+            outputSchema: TEMPLATE_SUMMARY_OUTPUT_SCHEMA,
+            annotations: readOnly('Template Summary'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleTemplateSummary(client, rest), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_page_save',
+            description: 'Re-run save-transforms and persist. ETag optional — when provided, 412 on ' +
+                'conflict; when omitted, last-write-wins. Recommended for collaborative edits. ' +
+                'No-op when state is byte-identical (returns `no_changes:true`, ETag unchanged). ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                template_id: TEMPLATE_ID,
+                etag: ETAG,
+            },
+            annotations: mutating('Save Page'),
+            handler: async ({ site_id, ...rest }, extra) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePageSave(client, rest, extra), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_page_publish',
+            description: 'Publish a template — persist state, flush YT + WP caches, snapshot the ' +
+                'published-state ETag. ETag optional — when provided, 412 on conflict; when ' +
+                'omitted, last-write-wins. Recommended for collaborative edits. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                template_id: TEMPLATE_ID,
+                etag: ETAG,
+            },
+            // Stream D3 T3: publish is idempotent — re-running on an
+            // unchanged template snapshots the same ETag and flushes
+            // the same caches. Matrix marks `idempotentHint:true`.
+            annotations: mutating('Publish Page'),
+            handler: async ({ site_id, ...rest }, extra) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handlePagePublish(client, rest, extra), site)),
+        }),
+    ];
+}
+//# sourceMappingURL=builders.js.map

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

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

package/dist/tools/pages/handlers-read.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Page-tool READ handlers + shared output-schemas.
+ *
+ * Split out of `src/tools/pages.ts` (Round-2 R2-A2-CRIT1) to keep
+ * each file ≤ 200 LoC per Architecture §11. Write handlers (page_save,
+ * page_publish — 3-phase progress contract) live in `./handlers-write.ts`.
+ *
+ * @license MIT
+ */
+import type { RestClient } from '../../client.js';
+import { type ToolResult } from '../tool-builder.js';
+export declare function handlePagesList(client: RestClient, { fields }: {
+    fields?: readonly string[];
+}): Promise<ToolResult>;
+export declare function handlePageGetLayout(client: RestClient, { template_id, flat, fields }: {
+    template_id: string;
+    flat?: boolean;
+    fields?: readonly string[];
+}): Promise<ToolResult>;
+export declare function handlePageGetSchema(client: RestClient, { template_id }: {
+    template_id: string;
+}): Promise<ToolResult>;
+export declare function handleGetEtag(client: RestClient): Promise<ToolResult>;
+/**
+ * T9: a one-call structured overview of a template — element counts by
+ * type, binding count, max nesting depth, and named landmarks. Lets the
+ * agent grasp a 96-node template for ~1 kB instead of pulling the full
+ * element_list dump (20 kB+).
+ */
+export declare function handleTemplateSummary(client: RestClient, { template_id }: {
+    template_id: string;
+}): Promise<ToolResult>;
+//# sourceMappingURL=handlers-read.d.ts.map

package/dist/tools/pages/handlers-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers-read.d.ts","sourceRoot":"","sources":["../../../src/tools/pages/handlers-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAiBlD,OAAO,EAIH,KAAK,UAAU,EAClB,MAAM,oBAAoB,CAAC;AAI5B,wBAAsB,eAAe,CACjC,MAAM,EAAE,UAAU,EAClB,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3C,OAAO,CAAC,UAAU,CAAC,CAyCrB;AAID,wBAAsB,mBAAmB,CACrC,MAAM,EAAE,UAAU,EAClB,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,GACF,OAAO,CAAC,UAAU,CAAC,CA+DrB;AAID,wBAAsB,mBAAmB,CACrC,MAAM,EAAE,UAAU,EAClB,EAAE,WAAW,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,UAAU,CAAC,CA4CrB;AAID,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAoB3E;AAID;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACvC,MAAM,EAAE,UAAU,EAClB,EAAE,WAAW,EAAE,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,UAAU,CAAC,CA6BrB"}