@wootsup/yt-builder-mcp 1.7.2 → 1.9.0

package/dist/tools/library.js

@@ -0,0 +1,1060 @@
+/**
+ * Layout Library tools — browse + fetch + insert + save the YOOtheme Pro
+ * Library catalog (layouts / element presets), PLUS the Image Sourcing pair
+ * (Task D1) that fills layout image slots with real photography. Task 2
+ * (Layout Library, Spec #2) + Task 3 (Spec #3) + Task 6 (Spec #6) + Task 7
+ * (Spec #7) + Task D1 (Image Sourcing).
+ *
+ *   yootheme_builder_library_browse
+ *      → paginated, taxonomy-filtered catalog rows (tableResult — Wave G.2).
+ *   yootheme_builder_library_get
+ *      → a SINGLE item's full tree + derived section list (the natural next
+ *        call after library_browse — id comes straight off a browse row).
+ *   yootheme_builder_library_insert
+ *      → compose + persist a browsed/fetched item onto a page/template
+ *        through the REAL hardened write chain.
+ *   yootheme_builder_library_save_as
+ *      → the REVERSE direction: save a page/subtree INTO "My Layouts".
+ *   yootheme_builder_image_search
+ *      → search Unsplash / Pexels (real photography) or YOOtheme Pro Images
+ *        (curated decorative/background assets) — forwards to the SAME
+ *        `?key=<theme apikey>` proxy auth `library_browse` uses (Task A0-C1,
+ *        PHP `ImageSearchService`). Returns candidate rows; `total:0` means
+ *        no Library API key configured, mirroring browse's empty-catalog hint.
+ *   yootheme_builder_image_import
+ *      → sideload ONE chosen photo (typically a `full_url` from
+ *        image_search) into the site's own Media Library. Returns
+ *        `{imported:true, local_url}` to bind via element_update_settings,
+ *        or `{imported:false, reason}` on a caught failure (never a 500).
+ *
+ * browse/get/image_search are read-only forwards, exactly like the sibling
+ * L1 read tools (sources_list / template_summary / pages_list): resolve the
+ * site via the pool, GET the plugin REST endpoint, project into a table +
+ * strict structuredContent, stamp the result-level `_meta` (site_id/
+ * site_url/platform/resolved_via) via withSiteMeta. insert/save_as/
+ * image_import are WRITE forwards (withWriteSiteRetry — pre-flights a KNOWN
+ * read-only token before any body build, mirroring every other write tool's
+ * U2 pattern).
+ *
+ * ── Tiering (Task 7, deliberate) ─────────────────────────────────────────
+ * `library_save_as` is registered as an ADVANCED tool — it is NOT added to
+ * `ESSENTIAL_TOOLS` (essentials.ts) and does NOT appear as a first-class
+ * `tools/list` entry. `tools/list` sits close to the 28000B token-baseline
+ * ceiling (see `tests/perf/token-baseline.test.ts`); a 4th Layout-Library L1
+ * tool would risk busting it. `CapturingServer` (gateway/capturing-server.ts)
+ * automatically captures ANY registered tool whose name is absent from both
+ * `ESSENTIAL_TOOLS` and `DIRECT_TOP_LEVEL_TOOLS` into the L2 advanced
+ * registry — reachable via `yootheme_builder_advanced({tool, arguments})` —
+ * so simply NOT listing this name in essentials.ts is the entire tiering
+ * decision (mirrors how `yootheme_builder_clean_implode_directives` /
+ * `yootheme_builder_element_unbind_source` are advanced-only today). The
+ * name falls through the gateway's domain taxonomy (domains.ts) to "misc"
+ * (no `library` domain exists there) — intentional, NOT a bug (see
+ * `domain-order.test.ts`'s own pinned "misc" fallthrough cases): it keeps the
+ * gateway's own tools/list-visible description text from growing at all,
+ * while `{tool: "yootheme_builder_library_save_as"}` discovery and
+ * `{tool, arguments}` execution both remain fully reachable (the gateway
+ * dispatches by an exact Map lookup, independent of the domain-grouped
+ * DESCRIPTION text — see `gateway/advanced-tool/execute.ts`).
+ *
+ * @license MIT
+ */
+import { tableResult } from '@getimo/mcp-toolkit';
+import { z } from 'zod';
+import { withSiteRetry, withWriteSiteRetry } from './pool-resolve-helper.js';
+import { SITE_ID_SCHEMA } from './shared-schemas.js';
+import { creating, defineTool, errorResult, jsonResult, mutating, readOnly, structuredResult, withSiteMeta, } from './tool-builder.js';
+// ─── outputSchema (Wave G.2 §4) ────────────────────────────────────
+/**
+ * Fixed section-purpose enum (Task 8, Section Corpus Phase 1) — mirrors the
+ * PHP-side `SectionPurposeClassifier` / `SectionIndexEntry` purpose values
+ * byte-for-byte (design spec §A, Global Constraints). Only applies when
+ * `kind="section"`. Declared here (ahead of `LIBRARY_ITEM_SCHEMA`, which
+ * consumes it for the browse row's `purpose` field) rather than further
+ * down where the original Task 8 pass left it, since Task 8b (this file)
+ * now needs it at both the item-schema AND the browse-filter-schema sites.
+ */
+export const SECTION_PURPOSE_VALUES = [
+    'hero',
+    'features',
+    'stats',
+    'team',
+    'testimonial',
+    'cta',
+    'gallery',
+    'pricing',
+    'faq',
+    'contact',
+    'logos',
+    'content',
+];
+/**
+ * Track 1 Task 7 (WootsUp AI Layouts) — the `source` axis for
+ * browse/get/insert: `"catalog"` (the remote YOOtheme Pro Library, the
+ * DEFAULT) or `"ai"` (the plugin's OWN isolated "WootsUp AI Layouts" store,
+ * saved via library_save_as, no apikey). Mirrors the PHP-side
+ * `LibrarySourceRegistry` keys byte-for-byte.
+ */
+const LIBRARY_SOURCE_VALUES = ['catalog', 'ai'];
+/**
+ * The wire default for the `source` axis. It is NEVER forwarded (a catalog
+ * browse/get/insert is byte-identical to the pre-Task-7 request — the PHP
+ * controller reads the SAME absent-param default), so only `"ai"` ever
+ * appears on the wire. Mirrors `LibrarySourceRegistry::DEFAULT_SOURCE`.
+ */
+const DEFAULT_LIBRARY_SOURCE = 'catalog';
+/**
+ * Track 1 Task 7 (WootsUp AI Layouts) — the `destination` axis for
+ * library_save_as: `"ai"` (save INTO the isolated AI store, the DEFAULT) or
+ * `"native"` (the escape hatch — save into YOOtheme's native "My Layouts").
+ */
+const SAVE_DESTINATION_VALUES = ['ai', 'native'];
+/**
+ * The wire default for the `destination` axis — the AI store. NEVER forwarded
+ * (an ai-default save is byte-identical to the pre-Task-7 body; the PHP
+ * `MyLayoutsStore` reads the SAME absent-param `ai` default), so only
+ * `"native"` ever appears on the wire.
+ */
+const DEFAULT_SAVE_DESTINATION = 'ai';
+/**
+ * Mirrors `CatalogService::mapItem()` (PHP): every key is always PRESENT
+ * (never omitted) but each value may be `null` when the raw catalog item
+ * did not carry that taxonomy field — hence `.nullable()`, not `.optional()`.
+ */
+const LIBRARY_ITEM_META_SCHEMA = z.object({
+    topic: z.string().nullable(),
+    type: z.string().nullable(),
+    role: z.string().nullable(),
+    website: z.string().nullable(),
+    image: z.string().nullable(),
+});
+/**
+ * Task 8b (Section Corpus Phase 1, PLAN-GAP fix) — a `kind="section"` browse
+ * row (`SectionCatalog::mapEntry()`, PHP) carries a DIFFERENT shape than a
+ * layout/element row: no `meta` wrapper, TOP-LEVEL `topic`/`type`/`website`,
+ * plus `layout_id`/`section_index`/`purpose`/`element_signature`/
+ * `visual_effects`/`has_images`/`image_count`/`element_count`. All of these
+ * are `.optional()` — additive, never present on a layout/element row — so a
+ * strict-outputSchema host still accepts the pre-existing byte-unchanged
+ * layout/element shape.
+ */
+const LIBRARY_ITEM_SCHEMA = z.object({
+    id: z.string(),
+    name: z.string(),
+    kind: z.enum(['layout', 'element', 'section']),
+    meta: LIBRARY_ITEM_META_SCHEMA,
+    thumbnail_url: z.string().nullable(),
+    layout_id: z.string().optional(),
+    section_index: z.number().optional(),
+    purpose: z.enum(SECTION_PURPOSE_VALUES).optional(),
+    element_signature: z.string().optional(),
+    visual_effects: z.array(z.string()).optional(),
+    topic: z.string().nullable().optional(),
+    type: z.string().nullable().optional(),
+    website: z.string().nullable().optional(),
+    has_images: z.boolean().optional(),
+    image_count: z.number().optional(),
+    // Close-out finding (f): CONTENT elements only — excludes structural
+    // section/row/column wrappers. Distinct from library_get's
+    // `sections[].element_count` (LIBRARY_SECTION_SCHEMA below), which
+    // counts ALL descendants including structural nodes — the same
+    // section reports a different count from each; do not assume parity.
+    element_count: z
+        .number()
+        .optional()
+        .describe('CONTENT elements only (excludes structural section/row/column wrappers). ' +
+        'Distinct from library_get\'s sections[].element_count, which counts ALL descendants.'),
+});
+export const LIBRARY_BROWSE_OUTPUT_SCHEMA = z.object({
+    items: z.array(LIBRARY_ITEM_SCHEMA),
+    total: z.number(),
+    // `CatalogService::browse()` always emits the key; `null` means "last page".
+    next_cursor: z.string().nullable(),
+});
+// ─── library_get (Task 3) ───────────────────────────────────────────
+const LIBRARY_SECTION_SCHEMA = z.object({
+    index: z.number(),
+    name: z.string(),
+    path: z.string(),
+    element_count: z.number(),
+});
+export const LIBRARY_GET_OUTPUT_SCHEMA = z.object({
+    id: z.string(),
+    // Task 8b (Section Corpus Phase 1, PLAN-GAP fix): "section" is a valid
+    // resolved kind — `LibraryController::getSection()` (PHP) always
+    // returns a literal `kind: "section"` for a composite-id fetch.
+    kind: z.enum(['layout', 'element', 'section']),
+    name: z.string(),
+    version: z.string(),
+    // The raw fetched tree (`{type, children, version, images, ...}` for a
+    // layout; a single element node for a preset) — an arbitrary JSON
+    // object, not a fixed shape.
+    tree: z.record(z.string(), z.unknown()),
+    // Top-level `tree.children` (layouts only — always `[]` for a preset,
+    // even when its own tree happens to carry `children`).
+    sections: z.array(LIBRARY_SECTION_SCHEMA),
+    images_manifest_count: z.number(),
+});
+// ─── library_insert (Task 6) ─────────────────────────────────────────
+/**
+ * Mirrors `LibraryInsertService::insert()`'s `$target` union (PHP) exactly:
+ * a fresh page, a splice into an EXISTING template/page (layout/section on
+ * the layout root, or a preset on a Column), or a splice into a
+ * sublayout/fragment element.
+ */
+const LIBRARY_INSERT_TARGET_SCHEMA = z.union([
+    z.object({
+        new_page: z.object({
+            title: z.string().min(1).describe('The new page\'s title (e.g. "Landing Page").'),
+            status: z
+                .enum(['publish', 'draft', 'pending', 'private', 'future'])
+                .optional()
+                .describe('Post status. Omit for the platform default (draft).'),
+        }),
+    }),
+    z.object({
+        sublayout: z.object({
+            template_id: z
+                .string()
+                .min(1)
+                .describe('The `page:<id>` template holding the sublayout/fragment element (from pages_list).'),
+            element_path: z
+                .string()
+                .min(1)
+                .describe('JSON-Pointer rel-path to the sublayout/fragment element (e.g. "/children/0/children/0").'),
+        }),
+    }),
+    z.object({
+        template_id: z
+            .string()
+            .min(1)
+            .describe('The `page:<id>` template to splice into (from pages_list).'),
+        element_path: z
+            .string()
+            .optional()
+            .describe('JSON-Pointer rel-path: the layout ROOT ("" or omitted) for a layout/section item, ' +
+            'or a Column for an element preset (kind:"element").'),
+    }),
+]);
+/**
+ * A DOWNGRADED UI-invariant violation (2026-07-12 fix, "trusted
+ * library-insert downgrades enum/type violations to warnings"): a pure
+ * value-shape mismatch (`invalid_enum_value` / `type_mismatch`) that
+ * YOOtheme's OWN factory content carried but the site's installed YOOtheme
+ * schema doesn't declare — a version-skew artifact, allowed through rather
+ * than hard-rejecting the whole insert. Every OTHER violation class still
+ * 422s (`library.ui_invariant_violation`) exactly as before.
+ */
+const LIBRARY_INSERT_WARNING_SCHEMA = z.object({
+    field: z.string(),
+    code: z.string(),
+    message: z.string(),
+});
+export const LIBRARY_INSERT_OUTPUT_SCHEMA = z.object({
+    template_id: z.string(),
+    inserted_path: z.string(),
+    element_count: z.number(),
+    images_mode: z.enum(['placeholder', 'curated']),
+    images_resolved: z.object({
+        downloaded: z.number(),
+        placeholders: z.number(),
+    }),
+    new_etag: z.string(),
+    frontend_url: z.string().nullable(),
+    warnings: z.array(LIBRARY_INSERT_WARNING_SCHEMA).optional(),
+});
+const LIBRARY_TABLE_COLUMNS = [
+    { key: 'id', label: 'ID', width: 10, llmOnly: true },
+    { key: 'name', label: 'NAME', width: 26 },
+    { key: 'kind', label: 'KIND', width: 8 },
+    { key: 'meta.topic', label: 'TOPIC', width: 20 },
+    { key: 'meta.role', label: 'ROLE', width: 14 },
+    { key: 'meta.website', label: 'WEBSITE', width: 18 },
+];
+function asNullableString(v) {
+    return typeof v === 'string' ? v : null;
+}
+function isSectionPurpose(v) {
+    return typeof v === 'string' && SECTION_PURPOSE_VALUES.includes(v);
+}
+/**
+ * Task 8b (Section Corpus Phase 1, PLAN-GAP fix) — `requestedKind` is the
+ * caller's own `library_browse({kind})` argument. It is needed because a
+ * `kind="section"` row from `SectionCatalog::mapEntry()` (PHP) carries NO
+ * per-row `kind` field at all (unlike layout/element rows, which always do)
+ * — the whole response is homogeneous per browse call, since `kind` is a
+ * REST-level filter. So: `r.kind` wins when the row DOES carry one
+ * (layout/element, and defensively "section" too, should REST ever add it);
+ * otherwise fall back to what the caller asked for; otherwise "layout"
+ * (today's pre-Task-8b default, byte-unchanged).
+ */
+function mapLibraryItem(raw, requestedKind) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const metaRaw = r.meta !== null && typeof r.meta === 'object' ? r.meta : {};
+    const kind = r.kind === 'element' ? 'element' : r.kind === 'section' || requestedKind === 'section' ? 'section' : 'layout';
+    const base = {
+        id: typeof r.id === 'string' ? r.id : '',
+        name: typeof r.name === 'string' ? r.name : '',
+        kind,
+        meta: {
+            topic: asNullableString(metaRaw.topic),
+            type: asNullableString(metaRaw.type),
+            role: asNullableString(metaRaw.role),
+            website: asNullableString(metaRaw.website),
+            image: asNullableString(metaRaw.image),
+        },
+        thumbnail_url: asNullableString(r.thumbnail_url),
+    };
+    // ADDITIVE ONLY: a layout/element row returns exactly `base` — no
+    // section keys are ever added, not even as `undefined` — so the
+    // pre-Task-8b shape stays byte-unchanged (regression-tested via
+    // toStrictEqual in library.test.ts).
+    if (kind !== 'section')
+        return base;
+    return {
+        ...base,
+        layout_id: typeof r.layout_id === 'string' ? r.layout_id : undefined,
+        section_index: typeof r.section_index === 'number' ? r.section_index : undefined,
+        purpose: isSectionPurpose(r.purpose) ? r.purpose : undefined,
+        element_signature: typeof r.element_signature === 'string' ? r.element_signature : undefined,
+        visual_effects: Array.isArray(r.visual_effects)
+            ? r.visual_effects.filter((v) => typeof v === 'string')
+            : undefined,
+        topic: asNullableString(r.topic),
+        type: asNullableString(r.type),
+        website: asNullableString(r.website),
+        has_images: typeof r.has_images === 'boolean' ? r.has_images : undefined,
+        image_count: typeof r.image_count === 'number' ? r.image_count : undefined,
+        element_count: typeof r.element_count === 'number' ? r.element_count : undefined,
+    };
+}
+export async function handleLibraryBrowse({ client }, { kind, source, topic, type, role, website, element_type, purpose, has_effects, query, limit, cursor }) {
+    try {
+        const qs = new URLSearchParams();
+        if (kind !== undefined)
+            qs.set('kind', kind);
+        // Only forward a NON-default source (the PHP controller reads the same
+        // absent-param `catalog` default) so a catalog browse is byte-identical
+        // to the pre-Task-7 request.
+        if (source !== undefined && source !== DEFAULT_LIBRARY_SOURCE)
+            qs.set('source', source);
+        if (typeof topic === 'string' && topic !== '')
+            qs.set('topic', topic);
+        if (typeof type === 'string' && type !== '')
+            qs.set('type', type);
+        if (typeof role === 'string' && role !== '')
+            qs.set('role', role);
+        if (typeof website === 'string' && website !== '')
+            qs.set('website', website);
+        if (typeof element_type === 'string' && element_type !== '')
+            qs.set('element_type', element_type);
+        if (purpose !== undefined)
+            qs.set('purpose', purpose);
+        if (has_effects !== undefined)
+            qs.set('has_effects', String(has_effects));
+        if (typeof query === 'string' && query !== '')
+            qs.set('query', query);
+        if (limit !== undefined)
+            qs.set('limit', String(limit));
+        if (typeof cursor === 'string' && cursor !== '')
+            qs.set('cursor', cursor);
+        const qstr = qs.toString();
+        const data = await client.get(`/library/browse${qstr !== '' ? `?${qstr}` : ''}`);
+        const rawItems = Array.isArray(data.items) ? data.items : [];
+        const items = rawItems
+            .map((item) => mapLibraryItem(item, kind))
+            .filter((i) => i !== undefined);
+        const total = typeof data.total === 'number' ? data.total : items.length;
+        const nextCursor = typeof data.next_cursor === 'string' ? data.next_cursor : null;
+        const rows = items;
+        const toolkitResult = tableResult(rows, {
+            columns: [...LIBRARY_TABLE_COLUMNS],
+            header: (count) => `${String(count)} of ${String(total)} library items`,
+            footer: 'Activate one on a page with yootheme_builder_element_add / page_dynamize, ' +
+                'or pass `cursor` (next_cursor) for the next page.',
+        });
+        // HARD CONSTRAINT (Task 8): browse NEVER returns an image content
+        // block, even for kind="section" rows that carry a thumbnail_url —
+        // tableResult() only ever emits text rows. Use
+        // yootheme_builder_library_get's include_thumbnail on a shortlisted
+        // id for an actual image.
+        return structuredResult(toolkitResult, {
+            items,
+            total,
+            next_cursor: nextCursor,
+        });
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { kind: kind ?? 'layout', source: source ?? DEFAULT_LIBRARY_SOURCE, topic, type, role, website, element_type, purpose, has_effects, query },
+            hint: 'Run yootheme_builder_diagnose to verify auth. Omit filters to browse the full catalog.',
+        });
+    }
+}
+function mapLibrarySection(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r.index !== 'number'
+        || typeof r.name !== 'string'
+        || typeof r.path !== 'string'
+        || typeof r.element_count !== 'number') {
+        return undefined;
+    }
+    return { index: r.index, name: r.name, path: r.path, element_count: r.element_count };
+}
+/**
+ * Task 8 (Section Corpus Phase 1) — the REST `/library/get` response's
+ * `thumbnail` field (present ONLY when `include_thumbnail=true` was passed
+ * AND the server-side fetch succeeded — see `LibraryController::attachThumbnail()`).
+ * A missing/malformed field (either key absent, or either value not a
+ * non-empty string) is treated as "no thumbnail" — the caller never emits a
+ * broken image block.
+ */
+function mapThumbnail(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r.mime_type !== 'string' || r.mime_type === '')
+        return undefined;
+    if (typeof r.data_base64 !== 'string' || r.data_base64 === '')
+        return undefined;
+    return { mime_type: r.mime_type, data_base64: r.data_base64 };
+}
+export async function handleLibraryGet({ client }, { id, kind, source, include_thumbnail }) {
+    try {
+        const qs = new URLSearchParams({ id });
+        if (kind !== undefined)
+            qs.set('kind', kind);
+        // Only forward a NON-default source (see handleLibraryBrowse).
+        if (source !== undefined && source !== DEFAULT_LIBRARY_SOURCE)
+            qs.set('source', source);
+        if (include_thumbnail === true)
+            qs.set('include_thumbnail', 'true');
+        const data = await client.get(`/library/get?${qs.toString()}`);
+        const resolvedKind = data.kind === 'element' ? 'element' : data.kind === 'section' ? 'section' : 'layout';
+        const tree = data.tree !== null && typeof data.tree === 'object' && !Array.isArray(data.tree)
+            ? data.tree
+            : {};
+        const rawSections = Array.isArray(data.sections) ? data.sections : [];
+        const sections = rawSections
+            .map(mapLibrarySection)
+            .filter((s) => s !== undefined);
+        const payload = {
+            id: typeof data.id === 'string' ? data.id : id,
+            kind: resolvedKind,
+            name: typeof data.name === 'string' ? data.name : '',
+            version: typeof data.version === 'string' ? data.version : '',
+            tree,
+            sections,
+            images_manifest_count: typeof data.images_manifest_count === 'number' ? data.images_manifest_count : 0,
+        };
+        // Task 8: an image content block is ADDITIONAL to the JSON text
+        // block, never a replacement — `structuredContent` (below) stays
+        // exactly the pre-Task-8 shape so a strict-outputSchema host never
+        // sees an undeclared key, and a large base64 blob is never
+        // duplicated into structuredContent alongside the image block.
+        // Gated on the CALLER's own `include_thumbnail === true` (not just
+        // "the REST body happened to carry a thumbnail field") — a defensive
+        // belt-and-braces on top of the server-side opt-in gate, so a future
+        // REST regression can never surprise-inject an unrequested,
+        // token-costly image block.
+        const thumbnail = include_thumbnail === true ? mapThumbnail(data.thumbnail) : undefined;
+        const jsonEnvelope = jsonResult(payload);
+        const content = thumbnail !== undefined
+            ? [...jsonEnvelope.content, { type: 'image', data: thumbnail.data_base64, mimeType: thumbnail.mime_type }]
+            : jsonEnvelope.content;
+        return structuredResult({ content }, payload);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { id, kind: kind ?? 'layout', source: source ?? DEFAULT_LIBRARY_SOURCE },
+            hint: 'Verify the id via yootheme_builder_library_browse first (its items[].id ' +
+                'feeds this tool directly) — ids are catalog- and kind-specific.',
+        });
+    }
+}
+/**
+ * 2026-07-12 fix ("trusted library-insert downgrades enum/type violations to
+ * warnings") — maps the REST `warnings[]` array (each `{field, code,
+ * message}`) if present. Mirrors the OTHER `map*` helpers in this file:
+ * malformed entries are dropped rather than propagated, and an absent/empty
+ * source array maps to `undefined` (the key is OMITTED from the result, not
+ * emitted as `[]`) — this is the "if present" contract: pre-fix inserts
+ * (a REST body carrying no `warnings` key at all) round-trip byte-unchanged.
+ */
+function mapLibraryInsertWarnings(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const warnings = [];
+    for (const entry of raw) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const w = entry;
+        if (typeof w.field !== 'string' || typeof w.code !== 'string' || typeof w.message !== 'string')
+            continue;
+        warnings.push({ field: w.field, code: w.code, message: w.message });
+    }
+    return warnings.length > 0 ? warnings : undefined;
+}
+function mapLibraryInsertResult(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r.template_id !== 'string' || typeof r.inserted_path !== 'string')
+        return undefined;
+    const resolvedRaw = r.images_resolved !== null && typeof r.images_resolved === 'object'
+        ? r.images_resolved
+        : {};
+    const warnings = mapLibraryInsertWarnings(r.warnings);
+    return {
+        template_id: r.template_id,
+        inserted_path: r.inserted_path,
+        element_count: typeof r.element_count === 'number' ? r.element_count : 0,
+        images_mode: r.images_mode === 'curated' ? 'curated' : 'placeholder',
+        images_resolved: {
+            downloaded: typeof resolvedRaw.downloaded === 'number' ? resolvedRaw.downloaded : 0,
+            placeholders: typeof resolvedRaw.placeholders === 'number' ? resolvedRaw.placeholders : 0,
+        },
+        new_etag: typeof r.new_etag === 'string' ? r.new_etag : '',
+        frontend_url: typeof r.frontend_url === 'string' ? r.frontend_url : null,
+        ...(warnings !== undefined ? { warnings } : {}),
+    };
+}
+export async function handleLibraryInsert({ client }, { id, kind, source, target, section_index, images, etag }) {
+    const resolvedImages = images ?? 'placeholder';
+    try {
+        const body = { id, target, images: resolvedImages };
+        if (kind !== undefined)
+            body.kind = kind;
+        // Only forward a NON-default source (see handleLibraryBrowse); the PHP
+        // LibraryInsertService reads the same absent-param `catalog` default.
+        if (source !== undefined && source !== DEFAULT_LIBRARY_SOURCE)
+            body.source = source;
+        if (section_index !== undefined)
+            body.section_index = section_index;
+        if (typeof etag === 'string' && etag !== '')
+            body.etag = etag;
+        const data = await client.post('/library/insert', { body });
+        const mapped = mapLibraryInsertResult(data);
+        if (mapped === undefined) {
+            throw new Error('Malformed /library/insert response — missing template_id/inserted_path.');
+        }
+        return structuredResult(jsonResult(mapped), mapped);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { id, kind: kind ?? 'layout', source: source ?? DEFAULT_LIBRARY_SOURCE, images: resolvedImages },
+            hint: 'Verify the id via yootheme_builder_library_get first. A 422 target_not_a_column means ' +
+                'a preset (kind:"element") was pointed at a non-Column — scaffold a section→row→column ' +
+                'hull first with yootheme_builder_scaffold_section, then point element_path at the new ' +
+                'Column. A 412 means the etag is stale — re-read (get_etag/pages_list) and retry.',
+        });
+    }
+}
+// ─── library_save_as (Task 7) ────────────────────────────────────────────
+const LIBRARY_SAVE_SOURCE_SCHEMA = z.object({
+    template_id: z
+        .string()
+        .min(1)
+        .describe('The `page:<id>` template holding the subtree to save (from pages_list).'),
+    element_path: z
+        .string()
+        .optional()
+        .describe('JSON-Pointer rel-path to the subtree to save (e.g. "/children/0"). Omit to save the ENTIRE page layout.'),
+});
+export const LIBRARY_SAVE_AS_OUTPUT_SCHEMA = z.object({
+    library_id: z.string(),
+    name: z.string(),
+    storage: z.string(),
+    invalid_source_possible: z.boolean(),
+});
+function mapLibrarySaveAsResult(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r.library_id !== 'string' || typeof r.name !== 'string' || typeof r.storage !== 'string') {
+        return undefined;
+    }
+    return {
+        library_id: r.library_id,
+        name: r.name,
+        storage: r.storage,
+        invalid_source_possible: r.invalid_source_possible === true,
+    };
+}
+export async function handleLibrarySaveAs({ client }, { source, name, destination }) {
+    try {
+        const body = { source, name };
+        // Only forward a NON-default destination (the PHP MyLayoutsStore reads
+        // the same absent-param `ai` default), so an ai-default save is
+        // byte-identical to the pre-Task-7 body — only the `native` escape
+        // hatch ever appears on the wire.
+        if (destination !== undefined && destination !== DEFAULT_SAVE_DESTINATION)
+            body.destination = destination;
+        const data = await client.post('/library/save', { body });
+        const mapped = mapLibrarySaveAsResult(data);
+        if (mapped === undefined) {
+            throw new Error('Malformed /library/save response — missing library_id/name/storage.');
+        }
+        return structuredResult(jsonResult(mapped), mapped);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { template_id: source.template_id, element_path: source.element_path, name, destination: destination ?? DEFAULT_SAVE_DESTINATION },
+            hint: 'Verify template_id via yootheme_builder_pages_list and element_path via ' +
+                'yootheme_builder_page_get_layout (its rel_path column). A 404 ' +
+                'element_path_not_found means the pointer does not resolve inside that template.',
+        });
+    }
+}
+// ─── image_search / image_import (Task D1, Image Sourcing) ────────────────
+//
+// Thin GET/POST forwards to `/library/image-search` (Task C1) mirroring
+// library_browse's read-projection pattern, and `/library/image-import`
+// mirroring library_insert's write-forward pattern. Response shapes are
+// pinned by the PHP controller tests
+// (tests/php/unit/Library/LibraryControllerImageSearchTest.php +
+// LibraryControllerImageImportTest.php):
+//   GET  /library/image-search  → {items, total, source, query, hint?}
+//   POST /library/image-import  → {imported:true, local_url} |
+//                                  {imported:false, reason}
+const IMAGE_SOURCE_VALUES = ['unsplash', 'pexels', 'proimages'];
+/**
+ * Cross-source orientation dialect (D1 concern, see the plan doc): the
+ * Unsplash proxy accepts "squarish", the Pexels proxy accepts "square" for
+ * the SAME concept. `ImageSearchService::buildQueryString()` (PHP) forwards
+ * whatever string is supplied verbatim, per-source, with NO translation — so
+ * this schema accepts BOTH spellings instead of forcing one source's
+ * vocabulary onto the other (which would either reject a legitimate Pexels
+ * "square" request or silently mis-filter it).
+ */
+const IMAGE_ORIENTATION_VALUES = ['landscape', 'portrait', 'squarish', 'square'];
+const IMAGE_RESULT_SCHEMA = z.object({
+    id: z.string(),
+    source: z.string(),
+    thumb_url: z.string(),
+    full_url: z.string(),
+    width: z.number(),
+    height: z.number(),
+    alt: z.string(),
+    author: z.string(),
+    author_url: z.string(),
+    orientation: z.string(),
+});
+export const IMAGE_SEARCH_OUTPUT_SCHEMA = z.object({
+    items: z.array(IMAGE_RESULT_SCHEMA),
+    total: z.number(),
+    source: z.string(),
+    query: z.string(),
+    // Present ONLY on the empty-result path (no Library API key configured,
+    // or genuinely zero matches — the REST layer cannot and must not
+    // distinguish the two; see LibraryControllerImageSearchTest).
+    hint: z.string().optional(),
+});
+export const IMAGE_IMPORT_OUTPUT_SCHEMA = z.object({
+    imported: z.boolean(),
+    // Present only when imported:true.
+    local_url: z.string().optional(),
+    // Present only when imported:false (a caught importer failure — never a 500).
+    reason: z.string().optional(),
+});
+function mapImageResult(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r.id !== 'string' || r.id === '')
+        return undefined;
+    return {
+        id: r.id,
+        source: typeof r.source === 'string' ? r.source : '',
+        thumb_url: typeof r.thumb_url === 'string' ? r.thumb_url : '',
+        full_url: typeof r.full_url === 'string' ? r.full_url : '',
+        width: typeof r.width === 'number' ? r.width : 0,
+        height: typeof r.height === 'number' ? r.height : 0,
+        alt: typeof r.alt === 'string' ? r.alt : '',
+        author: typeof r.author === 'string' ? r.author : '',
+        author_url: typeof r.author_url === 'string' ? r.author_url : '',
+        orientation: typeof r.orientation === 'string' ? r.orientation : '',
+    };
+}
+const IMAGE_TABLE_COLUMNS = [
+    { key: 'source', label: 'SOURCE', width: 9 },
+    { key: 'dimensions', label: 'SIZE', width: 10 },
+    { key: 'author', label: 'AUTHOR', width: 18 },
+    { key: 'orientation', label: 'ORIENT', width: 10 },
+    // llmOnly: the copyable next-call value (yootheme_builder_image_import's
+    // `url` arg) — excluded from the Rich Card UI (too long for a table
+    // cell) but present in the ASCII text the LLM reads. Always present in
+    // structuredContent.items[].full_url regardless of table membership.
+    { key: 'full_url', label: 'FULL_URL', width: 50, llmOnly: true },
+];
+export async function handleImageSearch({ client }, { source, query, per_page, orientation, color }) {
+    const resolvedSource = source ?? 'unsplash';
+    try {
+        const qs = new URLSearchParams();
+        qs.set('source', resolvedSource);
+        qs.set('query', query);
+        if (per_page !== undefined)
+            qs.set('per_page', String(per_page));
+        if (typeof orientation === 'string' && orientation !== '')
+            qs.set('orientation', orientation);
+        if (typeof color === 'string' && color !== '')
+            qs.set('color', color);
+        const data = await client.get(`/library/image-search?${qs.toString()}`);
+        const rawItems = Array.isArray(data.items) ? data.items : [];
+        const items = rawItems.map(mapImageResult).filter((i) => i !== undefined);
+        const total = typeof data.total === 'number' ? data.total : items.length;
+        const resolvedResponseSource = typeof data.source === 'string' ? data.source : resolvedSource;
+        const resolvedQuery = typeof data.query === 'string' ? data.query : query;
+        const hint = typeof data.hint === 'string' ? data.hint : undefined;
+        const rows = items.map((i) => ({
+            ...i,
+            dimensions: `${String(i.width)}x${String(i.height)}`,
+        }));
+        const toolkitResult = tableResult(rows, {
+            columns: [...IMAGE_TABLE_COLUMNS],
+            header: (count) => `${String(count)} of ${String(total)} ${resolvedResponseSource} image${total === 1 ? '' : 's'} for "${resolvedQuery}"`,
+            footer: hint
+                ?? 'Import a chosen row\'s full_url with yootheme_builder_image_import, then bind '
+                    + 'the returned local_url via element_update_settings.',
+        });
+        return structuredResult(toolkitResult, {
+            items,
+            total,
+            source: resolvedResponseSource,
+            query: resolvedQuery,
+            ...(hint !== undefined ? { hint } : {}),
+        });
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { source: resolvedSource, query, per_page, orientation, color },
+            hint: 'total:0 usually means no YOOtheme Pro Library API key is configured (the same '
+                + 'theme apikey library_browse/insert use). Run yootheme_builder_diagnose to verify auth.',
+        });
+    }
+}
+function mapImageImportResult(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r.imported !== 'boolean')
+        return undefined;
+    if (r.imported) {
+        if (typeof r.local_url !== 'string' || r.local_url === '')
+            return undefined;
+        return { imported: true, local_url: r.local_url };
+    }
+    return {
+        imported: false,
+        reason: typeof r.reason === 'string' && r.reason !== '' ? r.reason : 'Import failed for an unknown reason.',
+    };
+}
+export async function handleImageImport({ client }, { url }) {
+    try {
+        const data = await client.post('/library/image-import', { body: { url } });
+        const mapped = mapImageImportResult(data);
+        if (mapped === undefined) {
+            throw new Error('Malformed /library/image-import response — missing imported/local_url.');
+        }
+        return structuredResult(jsonResult(mapped), mapped);
+    }
+    catch (e) {
+        return errorResult({
+            error: e,
+            context: { url },
+            hint: 'Verify the url is a reachable http(s) image URL (typically a full_url from '
+                + 'yootheme_builder_image_search). A read_only_token error means this bearer key '
+                + 'needs the write scope — regenerate it in YT Builder MCP → Keys.',
+        });
+    }
+}
+export function buildLibraryTools(pool) {
+    return [
+        defineTool({
+            name: 'yootheme_builder_library_browse',
+            description: 'Browse the YOOtheme Pro Library catalog: pre-designed page LAYOUTS, element ' +
+                'PRESETS, or purpose-classified SECTIONS (hero/features/cta/...). Filter with ' +
+                '`kind` ("layout" default | "element" | "section"), `topic`, `type`/`role`, ' +
+                '`element_type`, `purpose`/`has_effects` (sections only), `website`, `query`. ' +
+                'Returns `{items, total, next_cursor}`; a "section" id is the composite ' +
+                '"<layoutId>#<sectionIndex>" — feeds straight into library_get/library_insert. ' +
+                '`total:0` usually means no Library API key configured. Operates on the default ' +
+                'site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                kind: z
+                    .enum(['layout', 'element', 'section'])
+                    .optional()
+                    .describe('Catalog to browse: "layout" (full pre-designed pages, default), "element" ' +
+                    '(single-element presets), or "section" (individual page sections classified ' +
+                    'by purpose). A "section" row\'s `id` is the COMPOSITE ' +
+                    '"<layoutId>#<sectionIndex>" (e.g. "8563daec#0") — pass it straight to ' +
+                    'yootheme_builder_library_get / yootheme_builder_library_insert with kind:"section".'),
+                source: z
+                    .enum(LIBRARY_SOURCE_VALUES)
+                    .default('catalog')
+                    .describe('Which library to browse: "catalog" (the remote YOOtheme Pro Library, default) ' +
+                    'or "ai" (your OWN "WootsUp AI Layouts" saved via library_save_as — no API ' +
+                    'key needed). The "ai" source honours only `query` + `kind` (layout|element); ' +
+                    'catalog layout/element taxonomy filters (topic/type/role/website) and ' +
+                    'kind:"section" are rejected with a 400. (purpose/has_effects are section-only ' +
+                    'and never apply to a layout/element browse, so — like on the catalog path — ' +
+                    'they are silently ignored on source:"ai", not rejected.)'),
+                topic: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Site industry/topic filter (e.g. "Health & Fitness", "Beauty & Fashion"). Exact match.'),
+                type: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Layout site-purpose filter (e.g. "Company", "E-commerce"). Only applies when kind="layout". Exact match.'),
+                role: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Page-role filter (e.g. "Home", "Contact", "Services"). Only applies when kind="layout". Exact match.'),
+                website: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Source demo-website name filter (e.g. "FC Greenfield", "Makai"). Exact match.'),
+                element_type: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Preset element-type filter (e.g. "accordion", "alert"). Only applies when kind="element". Exact match.'),
+                purpose: z
+                    .enum(SECTION_PURPOSE_VALUES)
+                    .optional()
+                    .describe('Section-purpose filter (e.g. "hero", "features", "cta"). Only applies when kind="section". Exact match.'),
+                has_effects: z
+                    .boolean()
+                    .optional()
+                    .describe('Filter sections by whether they carry a scroll/visual effect (parallax, ' +
+                    'floating decoration, sticky, viewport-height). Only applies when kind="section".'),
+                query: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Case-insensitive substring match on the item name (e.g. "hero").'),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(100)
+                    .optional()
+                    .describe('Max rows to return (1-100, default 25). The response carries next_cursor when more remain.'),
+                cursor: z
+                    .string()
+                    .optional()
+                    .describe('Opaque cursor from a previous response\'s next_cursor — fetches the next page.'),
+            },
+            outputSchema: LIBRARY_BROWSE_OUTPUT_SCHEMA,
+            annotations: readOnly('Browse Layout Library'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleLibraryBrowse({ client }, rest), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_library_get',
+            description: 'Fetch a SINGLE YOOtheme Pro Library layout or element preset by `id` — call ' +
+                'after yootheme_builder_library_browse (items[].id feeds this). Returns ' +
+                '`{id, kind, name, version, tree, sections, images_manifest_count}`: `tree` is ' +
+                'the raw JSON; `sections` lists `tree.children` (layouts only, presets return ' +
+                '`[]`), each `{index, name, path, element_count}`. `include_thumbnail:true` ' +
+                'also returns an image block (costs tokens — see its own description). ' +
+                'Read-only; does not insert/bind. Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                id: z
+                    .string()
+                    .min(1)
+                    .describe('The Library item id (e.g. "955bd3dc") — copy from a yootheme_builder_library_browse row\'s `items[].id`.'),
+                kind: z
+                    .enum(['layout', 'element', 'section'])
+                    .optional()
+                    .describe('The item\'s catalog: "layout" (default), "element" (preset), or "section" ' +
+                    '(id is the COMPOSITE "<layoutId>#<sectionIndex>", e.g. "8563daec#2"). ' +
+                    'Must match the id\'s own kind.'),
+                source: z
+                    .enum(LIBRARY_SOURCE_VALUES)
+                    .default('catalog')
+                    .describe('Which library the `id` belongs to: "catalog" (remote YOOtheme Pro Library, ' +
+                    'default) or "ai" (your OWN "WootsUp AI Layouts"). Must match the source the ' +
+                    'id came from in yootheme_builder_library_browse.'),
+                include_thumbnail: z
+                    .boolean()
+                    .default(false)
+                    .describe('Fetch the item\'s thumbnail and return it as an ADDITIONAL image content block ' +
+                    '(alongside the JSON). Costs real tokens — measured ~952 tokens for a layout ' +
+                    'thumbnail (2026-07-12) — so use it ONLY to visually confirm 2-3 shortlisted ' +
+                    'finalists right before inserting, never for bulk browsing (yootheme_builder_library_browse\'s ' +
+                    'items[].thumbnail_url is a plain URL and costs nothing). Default false.'),
+            },
+            outputSchema: LIBRARY_GET_OUTPUT_SCHEMA,
+            annotations: readOnly('Get Layout Library Item'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleLibraryGet({ client }, rest), site)),
+        }),
+        defineTool({
+            name: 'yootheme_builder_library_insert',
+            description: 'Insert a YOOtheme Pro Library item (layout, section, or preset) onto a page — ' +
+                'call after yootheme_builder_library_get/browse. `target`: new_page (creates a ' +
+                'page), {template_id,element_path?} (splices onto the layout root, or a preset ' +
+                'onto a Column), or sublayout (splices rows into a fragment). A preset ' +
+                '(kind:"element") MUST target a Column — 422 otherwise; scaffold one first with ' +
+                'yootheme_builder_scaffold_section. `images`: "placeholder" (default) or ' +
+                '"curated" (downloads to Media Library). Optional `etag` locks (412 if stale). ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                id: z
+                    .string()
+                    .min(1)
+                    .describe('The Library item id (e.g. "955bd3dc") — copy from a yootheme_builder_library_browse/library_get result.'),
+                kind: z
+                    .enum(['layout', 'element', 'section'])
+                    .optional()
+                    .describe('The item\'s catalog: "layout" (default), "element" (preset, MUST target a ' +
+                    'Column), or "section" (id is the COMPOSITE "<layoutId>#<sectionIndex>", ' +
+                    'e.g. "8563daec#2"). Must match the id\'s own kind.'),
+                source: z
+                    .enum(LIBRARY_SOURCE_VALUES)
+                    .default('catalog')
+                    .describe('Which library the `id` belongs to: "catalog" (remote YOOtheme Pro Library, ' +
+                    'default) or "ai" (your OWN "WootsUp AI Layouts", composed AS-SAVED — its ' +
+                    'images are never re-resolved). Must match the source the id came from.'),
+                target: LIBRARY_INSERT_TARGET_SCHEMA.describe('EXACTLY ONE of new_page / {template_id,element_path} / sublayout — see the tool description for the target-rule matrix.'),
+                section_index: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe('Reduce a multi-section layout to ONE section before inserting (its index in library_get\'s `sections[]`). Layouts only, ignored for kind:"element".'),
+                images: z
+                    .enum(['placeholder', 'curated'])
+                    .default('placeholder')
+                    .describe('"placeholder" (default, safe, no network I/O) or "curated" (downloads + sideloads every unique image into the Media Library).'),
+                etag: z
+                    .string()
+                    .optional()
+                    .describe('Optional optimistic-lock ETag (from get_etag/pages_list). Mismatched → 412; caller must re-read and retry.'),
+            },
+            outputSchema: LIBRARY_INSERT_OUTPUT_SCHEMA,
+            annotations: creating('Insert Layout Library Item'),
+            handler: async ({ site_id, ...rest }) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_library_insert', async (client, site) => withSiteMeta(await handleLibraryInsert({ client }, rest), site)),
+        }),
+        // Task 7 (Layout Library, Spec #7) — ADVANCED tool (deliberately NOT
+        // added to essentials.ts/ESSENTIAL_TOOLS): reachable ONLY via
+        // yootheme_builder_advanced({tool, arguments}), never a first-class
+        // tools/list entry. See the module docblock's "Tiering" note.
+        defineTool({
+            name: 'yootheme_builder_library_save_as',
+            description: 'Save a page or subtree into a reusable library — the REVERSE of ' +
+                'yootheme_builder_library_insert. `source`: {template_id, ' +
+                'element_path?} (omit element_path to save the WHOLE page). ' +
+                '`destination`: "ai" (default — your isolated "WootsUp AI Layouts", ' +
+                'reusable via library_browse/insert source:"ai") or "native" ' +
+                '(YOOtheme\'s built-in My Layouts). Returns `{library_id, name, ' +
+                'storage, invalid_source_possible}` (the last flags bound sources ' +
+                'that may need re-binding after reload). Advanced/gateway-only. ' +
+                'Operates on the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                source: LIBRARY_SAVE_SOURCE_SCHEMA.describe('The page/subtree to save.'),
+                name: z
+                    .string()
+                    .min(1)
+                    .describe('Display name for the new library entry (e.g. "Hero Section").'),
+                destination: z
+                    .enum(SAVE_DESTINATION_VALUES)
+                    .default('ai')
+                    .describe('Where to save: "ai" (default — the isolated "WootsUp AI Layouts" store, ' +
+                    'reusable by the agent via library_browse/insert with source:"ai", never ' +
+                    'pollutes YOOtheme\'s native My Layouts) or "native" (the escape hatch: save ' +
+                    'into YOOtheme\'s built-in "My Layouts").'),
+            },
+            outputSchema: LIBRARY_SAVE_AS_OUTPUT_SCHEMA,
+            annotations: creating('Save to My Layouts'),
+            handler: async ({ site_id, ...rest }) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_library_save_as', async (client, site) => withSiteMeta(await handleLibrarySaveAs({ client }, rest), site)),
+        }),
+        // Task D1 (Image Sourcing) — read-only forward, mirrors library_browse.
+        defineTool({
+            name: 'yootheme_builder_image_search',
+            description: 'Search real on-topic photos (Unsplash/Pexels) or YOOtheme Pro Images to fill '
+                + 'layout image slots with REAL, on-brand photography instead of bare '
+                + 'placeholders. Returns candidate rows with `full_url` (pass straight to '
+                + 'yootheme_builder_image_import) plus dimensions/author/orientation. '
+                + '`total:0` usually means no Library API key is configured (the same theme '
+                + 'apikey library_browse/insert use). Operates on the default site unless '
+                + 'site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                source: z
+                    .enum(IMAGE_SOURCE_VALUES)
+                    .default('unsplash')
+                    .describe('Image source. unsplash/pexels = real photography; proimages = YOOtheme '
+                    + 'Pro curated decorative/background assets, not topical photography.'),
+                query: z
+                    .string()
+                    .min(1)
+                    .describe('Search terms, e.g. "coffee roasting", "modern architecture interior". '
+                    + 'Search deliberately by industry + tone, not a generic term like "business".'),
+                per_page: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(30)
+                    .default(12)
+                    .describe('How many candidates to return (1-30, default 12).'),
+                orientation: z
+                    .enum(IMAGE_ORIENTATION_VALUES)
+                    .optional()
+                    .describe('landscape for heroes/banners, portrait for cards. "squarish" is the '
+                    + 'Unsplash spelling, "square" is the Pexels spelling for the same shape. '
+                    + 'Both are accepted; ignored for proimages.'),
+                color: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Optional upstream color filter (e.g. "black_and_white"). Passed through as-is.'),
+            },
+            outputSchema: IMAGE_SEARCH_OUTPUT_SCHEMA,
+            annotations: readOnly('Search Images'),
+            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleImageSearch({ client }, rest), site)),
+        }),
+        // Task D1 (Image Sourcing) — write forward, mirrors library_insert.
+        // mutating() (writes to the Media Library) but NOT destructive() — it
+        // only creates, never deletes (Global Constraints, plan doc).
+        defineTool({
+            name: 'yootheme_builder_image_import',
+            description: 'Sideload a chosen photo (typically a `full_url` from '
+                + 'yootheme_builder_image_search) into the site\'s own Media Library. Returns '
+                + '`{imported:true, local_url}`. Bind local_url into an element via '
+                + 'element_update_settings({props:{image: local_url}, merge:true}). A caught '
+                + 'import failure returns `{imported:false, reason}`, never a 500. Operates on '
+                + 'the default site unless site_id is provided.',
+            inputSchema: {
+                site_id: SITE_ID_SCHEMA,
+                url: z
+                    .string()
+                    .url()
+                    .describe('The image URL to sideload (typically a full_url from '
+                    + 'yootheme_builder_image_search). Downloads it into the site Media '
+                    + 'Library and returns a local URL to bind via element_update_settings.'),
+            },
+            outputSchema: IMAGE_IMPORT_OUTPUT_SCHEMA,
+            annotations: mutating('Import Image'),
+            handler: async ({ site_id, ...rest }) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_image_import', async (client, site) => withSiteMeta(await handleImageImport({ client }, rest), site)),
+        }),
+    ];
+}
+//# sourceMappingURL=library.js.map