@wootsup/yt-builder-mcp 1.12.0 → 2.0.0

package/dist/tools/modules/modules-update.js

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import { RestError } from '../../errors.js';
+import { PHASE_CONFIRM, PHASE_SEND, PHASE_SERVER } from '../progress-phases.js';
+import { SITE_ID_SCHEMA } from '../shared-schemas.js';
+import { asModuleId, MODULE_ID_SCHEMA } from './module-id-schema.js';
+import { FIELD_HINTS, hintFor, UPDATE_PLACEMENT_HINTS } from './placement-hints.js';
+import { createProgressReporter, errorResult, jsonResult, } from '../tool-builder.js';
+export const MODULES_UPDATE_INPUT = {
+    site_id: SITE_ID_SCHEMA,
+    id: MODULE_ID_SCHEMA.describe('The widget id (WordPress, e.g. "custom_html-2") or module id (Joomla, numeric, e.g. ' +
+        '"42"). A bare number is accepted for the Joomla form. Letters, digits, "_" and "-" ' +
+        'only (the addressable set the plugin REST route captures). Copy from ' +
+        'yootheme_builder_local_content_read(kind:"modules") or a page\'s modules_by_page ' +
+        '(page_get_layout / pages_audit with include_modules:true).'),
+    title: z
+        .string()
+        .optional()
+        .describe('The widget/module title. Stored byte-identical to what you send — never sanitized. A ' +
+        '"dangerous"-looking value is never rewritten; it is either stored verbatim or the ' +
+        'call is rejected. REJECTED with a 400 on a WordPress `block` widget: that type has ' +
+        'NO title at all (its instance is `{content}` only) and WordPress never renders one, ' +
+        'so a stored title would be invisible on the site while the read surface reported it ' +
+        'as real. Put the heading in the block markup instead.'),
+    content: z
+        .string()
+        .optional()
+        .describe('The widget/module BODY — the markup a visitor sees. Stored byte-identical: no ' +
+        'wp_kses, no strip_tags, no entity encoding. Widget content IS markup, so a value is ' +
+        'either stored verbatim or the call is rejected, never rewritten. WordPress: written ' +
+        'to the instance key this widget TYPE uses (custom_html/block → content, text → ' +
+        'text). Joomla: the #__modules.content column. REJECTED with a 400 for a type that ' +
+        'has no body (WordPress: an id_base outside the catalogue; Joomla: mod_menu, which ' +
+        'renders from its params) — the message names the types that do. To change wording ' +
+        'without touching placement, send content alone: every field you omit stays ' +
+        'byte-identical.'),
+    position: z
+        .string()
+        .optional()
+        .describe('WordPress: the sidebar/widget-area id to move the widget into (implies active:true — ' +
+        'combining with active:false is refused, not guessed). Joomla: the module POSITION ' +
+        'string (e.g. "sidebar-a"), moved via a plain column update (no active coupling). ' +
+        'Sending "" CLEARS the position on Joomla: a module with no position is a native ' +
+        'state there, the one placement:"module_element" already produces. WordPress refuses ' +
+        '"" instead, because a widget exists only while it sits in a registered area, so ' +
+        'there is nothing to move it to; send active:false to park it in wp_inactive_widgets, ' +
+        'and name a position again to bring it back. A position of nothing but blank space is ' +
+        'refused on both: that is a value, not an intent. ' +
+        'When the server cannot vouch for the value — the site list was not readable from ' +
+        'here AND the name is not one of builder-1..builder-6 — it is written anyway and the ' +
+        'answer carries position_verified:false. That field is ABSENT both when the value was ' +
+        'vouched for and when this call wrote no position at all, so read after.position to ' +
+        'tell those two apart. A dry_run never carries it, and neither does an update that ' +
+        'names no position: the flag reports on a position THIS call wrote, never on the one ' +
+        'the module already had. ' +
+        'One consequence this call CAN have is reported in notes rather than refused: if a ' +
+        'Module/Widget element already embeds this module and you move it to a position that ' +
+        'renders it on its own (a real theme position or widget area, not builder-1..builder-6), ' +
+        'it will render TWICE from then on — once through each element and once through the ' +
+        'position. The note names the elements and how to get back to one appearance. ' +
+        'modules_create refuses that same combination up front; this verb has no placement ' +
+        'argument to refuse it with, and both platforms allow the move in their own UI.'),
+    active: z
+        .boolean()
+        .optional()
+        .describe('WordPress: true/false toggles between a real widget area and the "inactive widgets" ' +
+        'bucket. active:true ALONE is only valid when the widget is already placed in a real ' +
+        'area — WordPress keeps no "restore to X" memory for an inactive widget, so reactivating ' +
+        'one that is currently inactive/unplaced REQUIRES position too (never guessed). Joomla: ' +
+        'the `published` column AND the publish_up/publish_down window — the SAME derivation ' +
+        'local_content_read uses, so a module scheduled for the future already reads ' +
+        'active:false. active:true is REJECTED with a 409 (blocked_by_cms_state) while that ' +
+        'window would still leave it "scheduled"/"expired": your request is fine and the CMS ' +
+        'is not, which is what separates that code from a 400. This tool never writes the ' +
+        'scheduling columns and will not promise an activation it cannot deliver. Independent ' +
+        'of position.'),
+    showtitle: z
+        .boolean()
+        .optional()
+        .describe('Joomla ONLY — whether the module title renders (its own DB column). WordPress REJECTS ' +
+        'this key with a 400: on WordPress showtitle instead lives INSIDE theme_overlay. ' +
+        'Read it back as the `showtitle` field of the local_content_read modules row ' +
+        '(both platforms).'),
+    ordering: z
+        .number()
+        .int()
+        .optional()
+        .describe('Joomla ONLY — the module\'s position-relative ordering. WordPress rejects this key.'),
+    access: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Joomla ONLY — the module\'s VIEW LEVEL (a row id in #__viewlevels; 1 = Public on a stock ' +
+        'install). Not a flag: Joomla filters modules with ' +
+        '`access IN (authorised view levels)`, and 0 is in NOBODY\'s set — not even a Super ' +
+        'User\'s — so a module at access:0 renders for no one while looking published. Send ' +
+        'access:1 to repair such a module (this is what local_content_read reports as ' +
+        'builder_visible:false). Must be a POSITIVE integer: 0 is refused, because 0 is the ' +
+        'very state being repaired. WordPress rejects this key.'),
+    assignment: z
+        .object({
+        mode: z
+            .enum(['all', 'none', 'selected', 'except'])
+            .describe('all: every page. none: nowhere. selected: only menu_ids. except: every page but menu_ids.'),
+        menu_ids: z
+            .array(z.number().int().positive())
+            .optional()
+            .describe('Required (non-empty) for mode "selected"/"except"; must be OMITTED for "all"/"none". ' +
+            'Always POSITIVE integers — the mode already encodes include vs. exclude, so a ' +
+            'negative id here would double-encode the direction.'),
+    })
+        .optional()
+        .describe('Joomla ONLY — page assignment, rewritten TRANSACTIONALLY in `#__modules_menu`. WordPress ' +
+        'rejects this key: WordPress has no per-page module-assignment concept.'),
+    theme_overlay: z
+        .record(z.string(), z.union([z.string(), z.boolean(), z.number()]))
+        .optional()
+        .describe('The theme display-overlay — WordPress `_theme` (17 keys, incl. showtitle) vs. Joomla ' +
+        '`params.yoo_config` (18 keys, incl. language_parent_icon/language_icon INSTEAD of ' +
+        'showtitle). The two key lists DIFFER; an unknown key for the target platform (or a ' +
+        'wrong value type) is REJECTED with a 400 naming every allowed key — never dropped, ' +
+        'never coerced. MERGES onto the stored overlay: a key you OMIT keeps its CURRENT stored ' +
+        'value; only the keys you explicitly include are written. To learn the exact keys, first ' +
+        'call with an empty theme_overlay:{} and read the 400\'s allowed-keys list, or dry_run ' +
+        'and inspect `before.theme_overlay`.'),
+    dry_run: z
+        .boolean()
+        .optional()
+        .describe('DEFAULT true — a call without it inspects and writes NOTHING, returning the ' +
+        '{before, after, changed, notes, after_read_back} diff of what a real write WOULD do. ' +
+        'Pass false to persist. ' +
+        'The two answers can differ in ONE way, deliberately, and only on JOOMLA: a real ' +
+        'write there RE-READS the stored module after committing and reports `after` (and ' +
+        '`changed`) as what it read back, so a field that did not land is reported at its ' +
+        'STORED value plus a note naming the divergence — and if that verification read ' +
+        'itself fails, the REQUESTED value is kept and a note says it is unverified. On ' +
+        'WORDPRESS there is no read-back: `after` is what you requested, and a write that ' +
+        'does not persist is raised as an ERROR rather than shown as a diverging `after`. ' +
+        'A dry run cannot know any of that in advance. ' +
+        '`after_read_back` lists exactly the keys whose `after` was READ OUT OF STORAGE, so ' +
+        'a key named in `changed` but ABSENT from `after_read_back` is a transition that was ' +
+        'requested and never measured — check it before treating it as landed. It is `[]` ' +
+        'for every dry run (nothing was written) and on WordPress (no read-back at all); ' +
+        'that is a plain statement, not a failure. Read `notes` whenever it is NON-EMPTY: ' +
+        'notes accompany a non-empty `changed` too, not only an empty one.'),
+};
+export async function handleModulesUpdate(client, input, extra) {
+    const { id, dry_run, ...rest } = input;
+    const progress = extra ? createProgressReporter(extra) : null;
+    await progress?.report(0, 3, PHASE_SEND);
+    await progress?.report(1, 3, PHASE_SERVER);
+    const body = { dry_run: dry_run ?? true };
+    for (const [key, value] of Object.entries(rest)) {
+        if (value !== undefined) {
+            body[key] = value;
+        }
+    }
+    try {
+        const data = await client.post(`/modules/${encodeURIComponent(asModuleId(id))}`, { body });
+        await progress?.report(3, 3, PHASE_CONFIRM);
+        return jsonResult(data);
+    }
+    catch (e) {
+        const code = e instanceof RestError ? (e.code ?? '') : '';
+        return errorResult({
+            error: e,
+            context: { id },
+            hint: hintFor(UPDATE_PLACEMENT_HINTS, code) ??
+                hintFor(FIELD_HINTS, code) ??
+                'On 400 invalid_field: the key is unknown OR wrong for this platform (e.g. showtitle on ' +
+                    'WordPress, or settings/params/content on either) — the error names every allowed key. ' +
+                    'On 404: the id does not exist — re-check via yootheme_builder_local_content_read(kind:' +
+                    '"modules"). A dry_run:true call never writes and is always safe to retry.',
+        });
+    }
+}
+//# sourceMappingURL=modules-update.js.map

package/dist/tools/modules/modules-update.js.map

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

package/dist/tools/modules/placement-hints.d.ts

@@ -0,0 +1,5 @@
+export declare const PLACEMENT_HINTS: Readonly<Record<string, string>>;
+export declare const UPDATE_PLACEMENT_HINTS: Readonly<Record<string, string>>;
+export declare function hintFor(table: Readonly<Record<string, string>>, code: string): string | undefined;
+export declare const FIELD_HINTS: Readonly<Record<string, string>>;
+//# sourceMappingURL=placement-hints.d.ts.map

package/dist/tools/modules/placement-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement-hints.d.ts","sourceRoot":"","sources":["../../../src/tools/modules/placement-hints.ts"],"names":[],"mappings":"AA2HA,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyC5D,CAAC;AA8EF,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAenE,CAAC;AAwBF,wBAAgB,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjG;AAwDD,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqCxD,CAAC"}

package/dist/tools/modules/placement-hints.js

@@ -0,0 +1,90 @@
+export const PLACEMENT_HINTS = {
+    'yootheme_builder_mcp.modules.placement_not_chosen': '`placement` was missing or not one of position, module_element, or ' +
+        'position_element. The error carries BOTH halves of the answer: `ways`, every way this ' +
+        'platform can reach a page with its reach and a summary, and `notes`, what modules_create ' +
+        'can build and when no module is needed at all. Read the notes, pick a way, and resend the ' +
+        'call with its `placement` value set. A dry_run:true call never creates anything and is ' +
+        'always safe to retry.',
+    'yootheme_builder_mcp.modules.placement_needs_a_position': 'The placement you chose NEEDS a `position` and the call carried none. The ways that do ' +
+        'take different values: placement:"position" takes a real template position or widget ' +
+        'area, and the error names the ones this site declares; placement:"position_element" ' +
+        'takes one of builder-1 to builder-6. (On WORDPRESS placement:"module_element" needs one ' +
+        'too, and takes builder-1 to builder-6: a widget exists only inside a registered area, so ' +
+        'there is no positionless widget for this tool to create. On JOOMLA that placement needs ' +
+        'none, because a module with no position is a native state there.) Resend the SAME ' +
+        'placement with `position` set; switching placement to get past this builds something ' +
+        'other than what you asked for. A dry_run:true call never creates anything and is always ' +
+        'safe to retry.',
+    'yootheme_builder_mcp.modules.placement_position_unknown': 'The `position` you named is not one this site can use, so the server refused instead of ' +
+        'parking the module where nothing renders it. Neither CMS refuses this on its own, which ' +
+        'is why the check is here. Take the next value from the MESSAGE: it is already narrowed ' +
+        'to the placement you chose. If it offers none, the message says which of two things ' +
+        'that means: either this site declares no template position this placement could use, ' +
+        'or its list could not be read from here, which is not the same thing. ' +
+        '`placement:"position"` takes a template position or widget ' +
+        'area this site declares; `placement:"position_element"` takes `builder-1` to ' +
+        '`builder-6` and nothing else; `placement:"module_element"` takes `builder-1` to ' +
+        '`builder-6` and no template position at all (those six are REQUIRED on WordPress ' +
+        'since 2026-08-08 and optional on Joomla, where a module with no position is a ' +
+        'native state). `declared_positions` rides ' +
+        'alongside as the raw fact of what the site declares, so it can hold values no call ' +
+        'accepts. Where that list could not be read, the value has to ' +
+        'come from the template itself. A dry_run:true call never creates anything and is always ' +
+        'safe to retry.',
+    'yootheme_builder_mcp.modules.placement_position_conflict': '`position` and `placement` describe different outcomes here, so the server refused ' +
+        'instead of guessing which one you meant. The error names the combination and the call ' +
+        'that does what you asked for. Change one of the two and resend. A dry_run:true call ' +
+        'never creates anything and is always safe to retry.',
+};
+export const UPDATE_PLACEMENT_HINTS = {
+    'yootheme_builder_mcp.modules.placement_position_unknown': 'The `position` you named is not one this site can use, so the server refused instead of ' +
+        'moving the module somewhere nothing renders it. Neither CMS refuses this on its own, ' +
+        'which is why the check is here. Nothing was written: the module still sits where it did. ' +
+        'Take the next value from the MESSAGE, which names the positions this site declares and ' +
+        'then adds `builder-1` to `builder-6`, which are taken by name whether or not the site ' +
+        'lists them; a module in one of those renders only where a Position element in a page ' +
+        'layout calls it. When the message names none of the site\'s OWN positions it says which ' +
+        'of two things that means: either this site declares none a module could be moved to, or ' +
+        'its list could not be read from here, and those are not the same thing. The builder ' +
+        'names are offered either way. `declared_positions` rides alongside as the raw fact of ' +
+        'what the site declares, so it can hold values no call accepts. Leave `position` out ' +
+        'entirely to keep the one this module already has. A dry_run:true call never writes and ' +
+        'is always safe to retry.',
+};
+export function hintFor(table, code) {
+    return Object.hasOwn(table, code) ? table[code] : undefined;
+}
+export const FIELD_HINTS = {
+    'yootheme_builder_mcp.modules.field_not_on_this_type': 'The field name is fine and this tool can write it — but not on THIS widget/module type, ' +
+        'which has no such field at all. There is nothing to rename, so re-sending the same call ' +
+        'with a corrected key cannot work. The message names the types that DO carry it, and where ' +
+        'this type keeps the equivalent instead (block markup, `theme_overlay`, or the ' +
+        'type-specific params). Pick one of those two answers. A dry_run:true call never writes ' +
+        'and is always safe to retry.',
+    'yootheme_builder_mcp.modules.field_combination_invalid': 'Every field you sent is valid on its own; TOGETHER they do not describe one outcome — ' +
+        'either they contradict each other, or one of them needs a partner the call did not carry. ' +
+        'The message names which of the two it is and in which direction. Change the COMBINATION: ' +
+        'add the missing field, or drop one of the pair. Correcting a value will not help, because ' +
+        'no single value is wrong. A dry_run:true call never writes and is always safe to retry.',
+    'yootheme_builder_mcp.modules.field_value_invalid': 'The KEY you sent is right; the VALUE is not. A wrong JSON type (the string "false" is not ' +
+        'the boolean false, and a `position` must be a string), a value outside a closed set (an ' +
+        'unknown widget/module type, an unrecognised `assignment.mode` on Joomla), or outside a ' +
+        'permitted range (Joomla `menu_ids` must be positive). The message names the expected type or the allowed values, so correct the ' +
+        'value of the named key and resend — renaming the key will not help, because the key is ' +
+        'already correct. Nothing was written. A dry_run:true call never writes and is always ' +
+        'safe to retry.',
+    'yootheme_builder_mcp.modules.position_not_clearable': 'You asked to take this widget out of every area by sending `position: ""`, and on ' +
+        'WordPress a widget exists only while it sits in one — there is no area named "". Nothing ' +
+        'was written. Send `active:false` instead: that parks the widget in wp_inactive_widgets, ' +
+        'and naming a position again brings it back. The same value is accepted on JOOMLA, where a ' +
+        'module with no position is a native state, so this refusal is about the platform rather ' +
+        'than about the value being malformed. A dry_run:true call never writes and is always safe ' +
+        'to retry.',
+    'yootheme_builder_mcp.modules.blocked_by_cms_state': 'Name, value and combination are all correct. The CMS is in a state that would make the ' +
+        'outcome you asked for untrue — the module would still not be visible — and this tool ' +
+        'deliberately does not write the columns that would change that state. So there is nothing ' +
+        'to fix in the call: the message names the exact field and value standing in the way, and ' +
+        'the change belongs in the CMS module manager. Repeat the call afterwards. A dry_run:true ' +
+        'call never writes and is always safe to retry.',
+};
+//# sourceMappingURL=placement-hints.js.map

package/dist/tools/modules/placement-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement-hints.js","sourceRoot":"","sources":["../../../src/tools/modules/placement-hints.ts"],"names":[],"mappings":"AA2HA,MAAM,CAAC,MAAM,eAAe,GAAqC;IAC7D,mDAAmD,EAC/C,qEAAqE;QACrE,wFAAwF;QACxF,2FAA2F;QAC3F,4FAA4F;QAC5F,yFAAyF;QACzF,uBAAuB;IAC3B,yDAAyD,EACrD,yFAAyF;QACzF,uFAAuF;QACvF,sFAAsF;QACtF,0FAA0F;QAC1F,2FAA2F;QAC3F,0FAA0F;QAC1F,oFAAoF;QACpF,uFAAuF;QACvF,0FAA0F;QAC1F,gBAAgB;IACpB,yDAAyD,EACrD,0FAA0F;QAC1F,0FAA0F;QAC1F,yFAAyF;QACzF,sFAAsF;QACtF,uFAAuF;QACvF,wEAAwE;QACxE,6DAA6D;QAC7D,+EAA+E;QAC/E,kFAAkF;QAClF,mFAAmF;QACnF,gFAAgF;QAChF,4CAA4C;QAC5C,qFAAqF;QACrF,+DAA+D;QAC/D,0FAA0F;QAC1F,gBAAgB;IACpB,0DAA0D,EACtD,qFAAqF;QACrF,wFAAwF;QACxF,sFAAsF;QACtF,qDAAqD;CAC5D,CAAC;AA8EF,MAAM,CAAC,MAAM,sBAAsB,GAAqC;IACpE,yDAAyD,EACrD,0FAA0F;QAC1F,uFAAuF;QACvF,2FAA2F;QAC3F,yFAAyF;QACzF,wFAAwF;QACxF,uFAAuF;QACvF,0FAA0F;QAC1F,0FAA0F;QAC1F,sFAAsF;QACtF,wFAAwF;QACxF,sFAAsF;QACtF,yFAAyF;QACzF,0BAA0B;CACjC,CAAC;AAwBF,MAAM,UAAU,OAAO,CAAC,KAAuC,EAAE,IAAY;IACzE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChE,CAAC;AAwDD,MAAM,CAAC,MAAM,WAAW,GAAqC;IACzD,qDAAqD,EACjD,0FAA0F;QAC1F,0FAA0F;QAC1F,4FAA4F;QAC5F,gFAAgF;QAChF,yFAAyF;QACzF,8BAA8B;IAClC,wDAAwD,EACpD,wFAAwF;QACxF,4FAA4F;QAC5F,2FAA2F;QAC3F,4FAA4F;QAC5F,yFAAyF;IAC7F,kDAAkD,EAC9C,4FAA4F;QAC5F,0FAA0F;QAC1F,yFAAyF;QACzF,kIAAkI;QAClI,yFAAyF;QACzF,uFAAuF;QACvF,gBAAgB;IACpB,qDAAqD,EACjD,oFAAoF;QACpF,2FAA2F;QAC3F,0FAA0F;QAC1F,4FAA4F;QAC5F,0FAA0F;QAC1F,4FAA4F;QAC5F,WAAW;IACf,mDAAmD,EAC/C,yFAAyF;QACzF,uFAAuF;QACvF,4FAA4F;QAC5F,2FAA2F;QAC3F,2FAA2F;QAC3F,gDAAgD;CACvD,CAAC"}

package/dist/tools/modules/placement-ways.d.ts

@@ -0,0 +1,13 @@
+export type Platform = 'wordpress' | 'joomla';
+export type PlacementWay = {
+    readonly platform: Platform;
+    readonly placement: 'position' | 'module_element' | 'position_element';
+    readonly reach: 'site_wide' | 'single_page';
+    readonly canLimitToPages?: boolean;
+    readonly summary: string;
+};
+export declare const PLACEMENT_WAYS: readonly PlacementWay[];
+export declare const PLACEMENT_NOTES: Readonly<Record<Platform, readonly string[]>>;
+export declare function waysFor(platform: Platform): readonly PlacementWay[];
+export declare function notesFor(platform: Platform): readonly string[];
+//# sourceMappingURL=placement-ways.d.ts.map

package/dist/tools/modules/placement-ways.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement-ways.d.ts","sourceRoot":"","sources":["../../../src/tools/modules/placement-ways.ts"],"names":[],"mappings":"AA+DA,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE9C,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;IAEvE,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAAC;IAM5C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAsCjD,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC,CAezE,CAAC;AAEF,wBAAgB,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,YAAY,EAAE,CAEnE;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,MAAM,EAAE,CAE9D"}

package/dist/tools/modules/placement-ways.js

@@ -0,0 +1,61 @@
+export const PLACEMENT_WAYS = [
+    {
+        platform: 'joomla', placement: 'position', reach: 'site_wide', canLimitToPages: true,
+        summary: 'The module sits in a template position such as top and appears on EVERY page. '
+            + 'Pass the position with this call. No layout edit, and one module serves the whole '
+            + 'site. To narrow it to chosen pages, set the menu assignment with modules_update.',
+    },
+    {
+        platform: 'joomla', placement: 'module_element', reach: 'single_page',
+        summary: 'A Module element inside a column of ONE page layout embeds this module, and it '
+            + 'appears on that page only. Call scaffold_section first for a valid column path.',
+    },
+    {
+        platform: 'joomla', placement: 'position_element', reach: 'single_page',
+        summary: 'The module goes into one of the positions builder-1 to builder-6. On its own it '
+            + 'appears NOWHERE. A Position element placed in a page layout is what renders it, and '
+            + 'it then appears on that page only.',
+    },
+    {
+        platform: 'wordpress', placement: 'position', reach: 'site_wide', canLimitToPages: false,
+        summary: 'The widget sits in a widget area and appears on EVERY page. Pass the area with '
+            + 'this call. No layout edit, and one widget serves the whole site. WordPress has no '
+            + 'built-in per-page control, so narrowing it to chosen pages needs a plugin.',
+    },
+    {
+        platform: 'wordpress', placement: 'module_element', reach: 'single_page',
+        summary: 'A Widget element inside a column of ONE page layout embeds this widget, and it '
+            + 'appears on that page only. Needs a position: builder-1 to builder-6, the areas '
+            + 'that render nothing on their own. Call scaffold_section first for a valid '
+            + 'column path.',
+    },
+    {
+        platform: 'wordpress', placement: 'position_element', reach: 'single_page',
+        summary: 'The widget goes into one of the areas builder-1 to builder-6. On its own it '
+            + 'appears NOWHERE. An Area element placed in a page layout is what renders it, and it '
+            + 'then appears on that page only.',
+    },
+];
+export const PLACEMENT_NOTES = {
+    joomla: [
+        'modules_create builds two native module types (mod_custom, mod_menu). '
+            + 'A builder module (mod_yootheme_builder) must already exist. Once it does, all three '
+            + 'placements work for it exactly as they do for a native module.',
+        'You may not need a module at all: a YOOtheme element such as alert placed straight into a '
+            + 'page layout does the same job, at the cost of a separate copy per page.',
+    ],
+    wordpress: [
+        'modules_create builds three native widget types (custom_html, text, block). '
+            + 'A builder widget must already exist. Once it does, all three placements work for it '
+            + 'exactly as they do for a native widget.',
+        'You may not need a widget at all: a YOOtheme element such as alert placed straight into a '
+            + 'page layout does the same job, at the cost of a separate copy per page.',
+    ],
+};
+export function waysFor(platform) {
+    return PLACEMENT_WAYS.filter((w) => w.platform === platform);
+}
+export function notesFor(platform) {
+    return PLACEMENT_NOTES[platform];
+}
+//# sourceMappingURL=placement-ways.js.map

package/dist/tools/modules/placement-ways.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement-ways.js","sourceRoot":"","sources":["../../../src/tools/modules/placement-ways.ts"],"names":[],"mappings":"AA+EA,MAAM,CAAC,MAAM,cAAc,GAA4B;IACnD;QACI,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI;QACpF,OAAO,EAAE,gFAAgF;cACnF,oFAAoF;cACpF,kFAAkF;KAC3F;IACD;QACI,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,aAAa;QACrE,OAAO,EAAE,iFAAiF;cACpF,iFAAiF;KAC1F;IACD;QACI,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,kBAAkB,EAAE,KAAK,EAAE,aAAa;QACvE,OAAO,EAAE,kFAAkF;cACrF,sFAAsF;cACtF,oCAAoC;KAC7C;IAED;QACI,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK;QACxF,OAAO,EAAE,iFAAiF;cACpF,oFAAoF;cACpF,4EAA4E;KACrF;IACD;QACI,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,aAAa;QACxE,OAAO,EAAE,iFAAiF;cACpF,iFAAiF;cACjF,4EAA4E;cAC5E,cAAc;KACvB;IACD;QACI,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,KAAK,EAAE,aAAa;QAC1E,OAAO,EAAE,8EAA8E;cACjF,sFAAsF;cACtF,iCAAiC;KAC1C;CACJ,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAkD;IAC1E,MAAM,EAAE;QACJ,wEAAwE;cAClE,sFAAsF;cACtF,gEAAgE;QACtE,4FAA4F;cACtF,yEAAyE;KAClF;IACD,SAAS,EAAE;QACP,8EAA8E;cACxE,sFAAsF;cACtF,yCAAyC;QAC/C,4FAA4F;cACtF,yEAAyE;KAClF;CACJ,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,QAAkB;IACtC,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,QAAkB;IACvC,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACrC,CAAC"}

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

@@ -1,23 +1,3 @@
-/**
- * Multi-Items tool builders.
- *
- * Surfaces two tools that operate on the YT-Pro Multi-Items binding
- * pattern (container ↔ `*_item` pairings — see
- * `./item-container-map.ts`):
- *
- *   yootheme_builder_inspect_multi_items_binding
- *     → Reports the binding level (none/container/item), the matching
- *       container/item pair, and whether legacy implode directives are
- *       attached. Surfaces a `recommended_fix` when the binding sits on
- *       the container level.
- *
- *   yootheme_builder_clean_implode_directives
- *     → Removes every `props.source.props.*.implode` directive from
- *       the addressed element. Returns the audit log + new etag.
- *
- * @license MIT
- */
-import type { ClientPool } from '../../sites/client-pool.js';
 import { type AnyToolDefinition } from '../tool-builder.js';
-export declare function buildMultiItemsTools(pool: ClientPool): readonly AnyToolDefinition[];
+export declare function buildMultiItemsTools(): readonly AnyToolDefinition[];
 //# sourceMappingURL=builders.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAKH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AAY5B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CA0EnF"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAwBA,OAAO,EAIH,KAAK,iBAAiB,EACzB,MAAM,oBAAoB,CAAC;AAM5B,wBAAgB,oBAAoB,IAAI,SAAS,iBAAiB,EAAE,CAsDnE"}

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

@@ -1,93 +1,50 @@
-/**
- * Multi-Items tool builders.
- *
- * Surfaces two tools that operate on the YT-Pro Multi-Items binding
- * pattern (container ↔ `*_item` pairings — see
- * `./item-container-map.ts`):
- *
- *   yootheme_builder_inspect_multi_items_binding
- *     → Reports the binding level (none/container/item), the matching
- *       container/item pair, and whether legacy implode directives are
- *       attached. Surfaces a `recommended_fix` when the binding sits on
- *       the container level.
- *
- *   yootheme_builder_clean_implode_directives
- *     → Removes every `props.source.props.*.implode` directive from
- *       the addressed element. Returns the audit log + new etag.
- *
- * @license MIT
- */
 import { z } from 'zod';
-import { withSiteRetry, withWriteSiteRetry } from '../pool-resolve-helper.js';
-import { ELEMENT_PATH, ETAG, SITE_ID_SCHEMA, TEMPLATE_ID } from '../shared-schemas.js';
-import { defineTool, destructive, readOnly, withSiteMeta, } from '../tool-builder.js';
-import { CLEAN_IMPLODE_OUTPUT_SCHEMA, handleCleanImplodeDirectives, } from './clean-implode-handler.js';
-import { INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA, handleInspectMultiItemsBinding, } from './inspect-handler.js';
-import { InspectionCache } from './inspection-cache.js';
-export function buildMultiItemsTools(pool) {
-    // 6.2 — one shared inspection cache per tool-build, keyed on
-    // (template_id, element_path, global-etag) with a 60s TTL. Survives
-    // across calls within a server lifetime; a write bumps the global
-    // etag and naturally invalidates the entry.
-    const inspectionCache = new InspectionCache();
-    // W6.3 — per-handler resolveSiteOrError. The handlers consume a
-    // single-field `MultiItemsHandlerDeps`, so we synthesise it inline
-    // with the resolved client.
+import { ELEMENT_PATH, ETAG_PREVIEW_OPTIONAL, SITE_ID_SCHEMA, LAYOUT_ID } from '../shared-schemas.js';
+import { HOST_PROMPT_PROMISE } from '../tool-builder/confirm-preview.js';
+import { defineTool, destructiveIdempotent, readOnly, } from '../tool-builder.js';
+import { CLEAN_IMPLODE_OUTPUT_SCHEMA, INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA, } from './output-schemas.js';
+export function buildMultiItemsTools() {
     return [
         defineTool({
             name: 'yootheme_builder_inspect_multi_items_binding',
             description: 'Reports Multi-Items binding state: container/item pair (grid↔grid_item, ' +
-                'slideshow↔slideshow_item, map↔map_item, …), the binding level ' +
-                '(none|container|item), and a recommended_fix when it sits on the container. ' +
-                // F39 (2026-06-10): a bound map_item with NO `location` field
-                // renders 0 markers → blocking map_location_warning.
-                'For map/map_item, a bound item without a `location` ("lat,lng") field is ' +
-                'flagged as a blocking map_location_warning (renders 0 markers). ' +
-                // F189 (2026-06-12): a `…List` on a grid_item with nested children
-                // is render-dead (leaf renderer) → blocking iterator_is_leaf_renderer.
-                'A List on a grid_item with nested children → blocking ' +
-                'iterator_is_leaf_renderer (children never render). ' +
-                // SOURCES_BINDING-13: reciprocal pointer to the implode-cleanup tool.
-                'If rows render as ONE comma-joined string, see clean_implode_directives.',
+                'map↔map_item, …), binding level (none|container|item), recommended_fix. ' +
+                'For map/map_item, a bound item without a `location` field is flagged as a ' +
+                'blocking map_location_warning (0 markers). ' +
+                'If rows render as ONE comma-joined string, see clean_implode_directives ' +
+                '(gateway-only).',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
-                template_id: TEMPLATE_ID,
+                layout_id: LAYOUT_ID,
                 element_path: ELEMENT_PATH,
             },
             outputSchema: INSPECT_MULTI_ITEMS_OUTPUT_SCHEMA,
             annotations: readOnly('Inspect Multi-Items Binding'),
-            handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => {
-                const deps = { client, cache: inspectionCache };
-                return withSiteMeta(await handleInspectMultiItemsBinding(deps, rest), site);
-            }),
         }),
         defineTool({
             name: 'yootheme_builder_clean_implode_directives',
             description: 'Use when a Multi-Items element renders rows as ONE comma-joined string instead of ' +
-                'N repeated items — typically stale `implode` directives left by a plugin upgrade ' +
-                '(detect via yootheme_builder_inspect_multi_items_binding). Strips ' +
-                '`props.source.props.*.implode` directives from an element binding. Returns audit ' +
-                'log + new ETag. Idempotent (cleaned_count: 0 when nothing to remove) but ' +
-                'destructive: the binding can\'t be restored without re-mapping. Ask the user to ' +
-                'confirm, then call with `confirm: true`. Requires ETag.',
+                'N repeated items — stale `implode` directives left by a plugin upgrade (detect via ' +
+                'inspect_multi_items_binding). Destructive: the binding can\'t be restored without ' +
+                're-mapping. The clean requires confirm:true + ETag; the dry run neither. ' +
+                'Without `confirm` the call runs a ' +
+                'server-side DRY RUN and reports `would_clean_count` while writing nothing. Live ' +
+                'at once.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
-                template_id: TEMPLATE_ID,
+                layout_id: LAYOUT_ID,
                 element_path: ELEMENT_PATH,
-                etag: ETAG,
+                etag: ETAG_PREVIEW_OPTIONAL.optional(),
                 confirm: z
                     .boolean()
                     .optional()
                     .describe('Must be true to execute. Without it the call returns a preview ' +
                     'and makes NO server-side change; the agent must ask the user ' +
-                    'to confirm and retry with `confirm: true`.'),
+                    'to confirm and retry with `confirm: true`. ' +
+                    HOST_PROMPT_PROMISE),
             },
             outputSchema: CLEAN_IMPLODE_OUTPUT_SCHEMA,
-            annotations: destructive('Clean Implode Directives'),
-            handler: async ({ site_id, ...rest }) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_clean_implode_directives', async (client, site) => {
-                const deps = { client };
-                return withSiteMeta(await handleCleanImplodeDirectives(deps, rest), site);
-            }),
+            annotations: destructiveIdempotent('Clean Implode Directives'),
         }),
     ];
 }

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

@@ -1 +1 @@
-{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EACH,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,GAEf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,2BAA2B,EAC3B,4BAA4B,GAC/B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACH,iCAAiC,EACjC,8BAA8B,GAEjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACjD,6DAA6D;IAC7D,oEAAoE;IACpE,kEAAkE;IAClE,4CAA4C;IAC5C,MAAM,eAAe,GAAG,IAAI,eAAe,EAA2B,CAAC;IAEvE,gEAAgE;IAChE,mEAAmE;IACnE,4BAA4B;IAC5B,OAAO;QACH,UAAU,CAAC;YACP,IAAI,EAAE,8CAA8C;YACpD,WAAW,EACP,0EAA0E;gBAC1E,gEAAgE;gBAChE,8EAA8E;gBAC9E,8DAA8D;gBAC9D,qDAAqD;gBACrD,2EAA2E;gBAC3E,kEAAkE;gBAClE,mEAAmE;gBACnE,uEAAuE;gBACvE,wDAAwD;gBACxD,qDAAqD;gBACrD,sEAAsE;gBACtE,0EAA0E;YAC9E,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,WAAW,EAAE,WAAW;gBACxB,YAAY,EAAE,YAAY;aAC7B;YACD,YAAY,EAAE,iCAAiC;YAC/C,WAAW,EAAE,QAAQ,CAAC,6BAA6B,CAAC;YACpD,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CACpC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChD,MAAM,IAAI,GAA0B,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;gBACvE,OAAO,YAAY,CAAC,MAAM,8BAA8B,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAChF,CAAC,CAAC;SACT,CAAC;QAEF,UAAU,CAAC;YACP,IAAI,EAAE,2CAA2C;YACjD,WAAW,EACP,oFAAoF;gBACpF,mFAAmF;gBACnF,oEAAoE;gBACpE,mFAAmF;gBACnF,2EAA2E;gBAC3E,kFAAkF;gBAClF,yDAAyD;YAC7D,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,WAAW,EAAE,WAAW;gBACxB,YAAY,EAAE,YAAY;gBAC1B,IAAI,EAAE,IAAI;gBACV,OAAO,EAAE,CAAC;qBACL,OAAO,EAAE;qBACT,QAAQ,EAAE;qBACV,QAAQ,CACL,iEAAiE;oBAC7D,+DAA+D;oBAC/D,4CAA4C,CACnD;aACR;YACD,YAAY,EAAE,2BAA2B;YACzC,WAAW,EAAE,WAAW,CAAC,0BAA0B,CAAC;YACpD,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CACpC,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,2CAA2C,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAClG,MAAM,IAAI,GAA0B,EAAE,MAAM,EAAE,CAAC;gBAC/C,OAAO,YAAY,CAAC,MAAM,4BAA4B,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAC9E,CAAC,CAAC;SACT,CAAC;KACL,CAAC;AACN,CAAC"}
+{"version":3,"file":"builders.js","sourceRoot":"","sources":["../../../src/tools/multi-items/builders.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtG,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EACH,UAAU,EACV,qBAAqB,EACrB,QAAQ,GAEX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,2BAA2B,EAC3B,iCAAiC,GACpC,MAAM,qBAAqB,CAAC;AAE7B,MAAM,UAAU,oBAAoB;IAChC,OAAO;QACH,UAAU,CAAC;YACP,IAAI,EAAE,8CAA8C;YACpD,WAAW,EACP,0EAA0E;gBAC1E,0EAA0E;gBAG1E,4EAA4E;gBAC5E,6CAA6C;gBAE7C,0EAA0E;gBAC1E,iBAAiB;YACrB,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,SAAS,EAAE,SAAS;gBACpB,YAAY,EAAE,YAAY;aAC7B;YACD,YAAY,EAAE,iCAAiC;YAC/C,WAAW,EAAE,QAAQ,CAAC,6BAA6B,CAAC;SACvD,CAAC;QAEF,UAAU,CAAC;YACP,IAAI,EAAE,2CAA2C;YACjD,WAAW,EACP,oFAAoF;gBACpF,qFAAqF;gBACrF,oFAAoF;gBACpF,2EAA2E;gBAC3E,oCAAoC;gBACpC,kFAAkF;gBAClF,UAAU;YACd,WAAW,EAAE;gBACT,OAAO,EAAE,cAAc;gBACvB,SAAS,EAAE,SAAS;gBACpB,YAAY,EAAE,YAAY;gBAC1B,IAAI,EAAE,qBAAqB,CAAC,QAAQ,EAAE;gBACtC,OAAO,EAAE,CAAC;qBACL,OAAO,EAAE;qBACT,QAAQ,EAAE;qBACV,QAAQ,CACL,iEAAiE;oBAC7D,+DAA+D;oBAC/D,6CAA6C;oBAC7C,mBAAmB,CAC1B;aACR;YACD,YAAY,EAAE,2BAA2B;YAGzC,WAAW,EAAE,qBAAqB,CAAC,0BAA0B,CAAC;SACjE,CAAC;KACL,CAAC;AACN,CAAC"}

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

@@ -1,18 +1,3 @@
-/**
- * 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

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

@@ -1,18 +1,3 @@
-/**
- * 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

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