@lacneu/wix-openclaw 0.3.1 → 0.4.0

package/dist/tools/seo.js

@@ -64,6 +64,9 @@ const SeoTagSchema = Type.Object({
         description: 'Tag properties, e.g. `{"name": "description", "content": "…"}`.',
     })),
     children: Type.Optional(Type.String({ description: "Inner content, e.g. the text of a <title>." })),
+    meta: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+        description: 'Tag metadata, e.g. `{"height": 300, "width": 240}`.',
+    })),
     custom: Type.Optional(Type.Boolean()),
     disabled: Type.Optional(Type.Boolean()),
 });
@@ -403,6 +406,429 @@ function sanitizeRedirect(one) {
         ...(one.id !== undefined ? { id: one.id } : {}),
     };
 }
+// ---------------------------------------------------------------------------
+// TRANCHE 2 — writing tags. A DIFFERENT DESTRUCTIVENESS FROM THE REDIRECTS.
+//
+// A redirect delete destroys another row: it can be listed, named, hashed. A
+// tag write destroys THE PREVIOUS VALUE OF WHAT IT WRITES — `tags` replaces the
+// item's set in full. So a caller that sets a title wipes the description that
+// was there, gets exactly what it asked for, and loses something it never
+// mentioned. That is this half's "redirects do not chain".
+//
+// The pre-flight therefore reports what DISAPPEARS — the tags the item holds
+// now whose slot the new set does not fill — never an echo of what is being
+// sent. A caller reading back its own input learns nothing.
+// ---------------------------------------------------------------------------
+/** What a tag occupies, as a human-readable slot: two tags with the same label
+ *  are the same fact about the page, so one replaces the other. */
+function tagLabel(tag) {
+    const type = typeof tag.type === "string" ? tag.type : "?";
+    const props = (tag.props ?? {});
+    // EVERY DISCRIMINATOR, not the first one found. Stopping at `rel` collapsed
+    // every `link rel="alternate"` onto one slot, and `script` had no
+    // discriminator at all: a page carrying three JSON-LD blocks or four
+    // hreflang alternates would have read as "all kept" when a single tag was
+    // sent, and the other two or three would have gone unannounced.
+    const parts = ["name", "property", "rel", "httpEquiv", "hreflang", "type", "href"]
+        .map((k) => [k, props[k]])
+        .filter(([, v]) => typeof v === "string" && v.length > 0)
+        .map(([k, v]) => `${k}=${String(v)}`);
+    // A `script` is identified by what it carries: two JSON-LD blocks share every
+    // property. Hashing the body means EDITING one reads as a loss plus an
+    // addition — over-announcing, which is the safe direction here.
+    if (type === "script" && typeof tag.children === "string") {
+        parts.push(`body=${createHmac("sha256", TOKEN_SECRET).update(tag.children).digest("hex").slice(0, 8)}`);
+    }
+    // A DISCRIMINATOR THIS VERSION DOES NOT LIST STILL IDENTIFIES A TAG.
+    // `meta charset=…`, `meta itemprop=…` and whatever Wix adds next matched
+    // none of the keys above, so every one of them collapsed onto the bare
+    // `meta` slot — a SINGULAR slot, which reads as an edit, so proposing one
+    // replaced another without announcing the loss. A digest of the props that
+    // are not the tag's payload keeps them apart. Editing such a tag then reads
+    // as a loss plus an addition: over-announcing, the safe direction here.
+    if (parts.length === 0) {
+        const identity = Object.entries(props)
+            .filter(([k, v]) => k !== "content" && typeof v === "string" && v.length > 0)
+            .map(([k, v]) => `${k}=${String(v)}`)
+            .sort();
+        if (identity.length > 0) {
+            parts.push(`props=${createHmac("sha256", TOKEN_SECRET)
+                .update(identity.join("\u0000"))
+                .digest("hex")
+                .slice(0, 8)}`);
+        }
+    }
+    // A TAG WITH NO DISCRIMINATOR AT ALL is told apart by what it carries, or
+    // not at all. A `meta` holding only `content` matched nothing above and fell
+    // back onto the bare `meta` slot, where one silently replaced another.
+    // `title` is the one type that is singular BY NATURE, so it keeps its bare
+    // slot and an edit of it still reads as an edit.
+    if (parts.length === 0 && type !== "title" && typeof props.content === "string") {
+        parts.push(`content=${createHmac("sha256", TOKEN_SECRET)
+            .update(props.content)
+            .digest("hex")
+            .slice(0, 8)}`);
+    }
+    return parts.length > 0 ? `${type}[${parts.join(",")}]` : type;
+}
+/** A slot plus the value it carries, bounded.
+ *
+ *  A LABEL ALONE CANNOT BE DECIDED ON. Editing a `title` in place keeps its
+ *  slot, so `wouldLose` is empty and the before/after read identically —
+ *  `title` and `title`. On a PATTERN, that is an operator handing over a token
+ *  for a rewrite of every page of a type without ever seeing the old template
+ *  or the new one. The value is what makes the two tell apart. */
+function tagPreview(tag) {
+    const t = (tag ?? {});
+    const props = (t.props ?? {});
+    const raw = typeof t.children === "string"
+        ? t.children
+        : typeof props.content === "string"
+            ? props.content
+            : typeof props.href === "string"
+                ? props.href
+                : undefined;
+    // BOUNDED: a JSON-LD block or a long description would otherwise push the
+    // rest of the refusal — the part that says what disappears — out of view.
+    const value = raw === undefined ? undefined : raw.length > 200 ? `${raw.slice(0, 200)}…` : raw;
+    return {
+        slot: tagLabel(t),
+        ...(value !== undefined ? { value } : {}),
+    };
+}
+/** Rebuild a tag from the fields Wix defines, dropping everything else.
+ *
+ *  TypeBox passes undeclared properties through and `execute` is callable
+ *  directly, so a schema that omits a field does not remove it. `language` in
+ *  particular must be actively dropped: tags can only be written for the item's
+ *  primary language, and sending one fails with `LANGUAGE_NOT_SUPPORTED` even
+ *  when the field mask does not name it. */
+function sanitizeTag(raw, allowedTypes) {
+    const t = (raw ?? {});
+    const type = typeof t.type === "string" ? t.type : "";
+    if (!allowedTypes.includes(type)) {
+        throw new Error(`Refusing to write: tag type ${JSON.stringify(type)} is not accepted here. ` +
+            `This endpoint accepts ${allowedTypes.map((x) => `\`${x}\``).join(", ")}. ` +
+            "Wix reuses one tag shape across APIs but each accepts only some types.");
+    }
+    // `custom: true` routes the write through the site's Advanced/Custom Tags
+    // list, which refuses `title` and `script` with TAG_TYPE_NOT_ALLOWED.
+    if (t.custom === true && (type === "title" || type === "script")) {
+        throw new Error("Refusing to write: a `title` or `script` tag cannot carry `custom: true` " +
+            "— Wix rejects it with TAG_TYPE_NOT_ALLOWED. Omit `custom` for those, " +
+            "including for JSON-LD structured data.");
+    }
+    const out = { type };
+    if (t.props !== undefined && t.props !== null && typeof t.props === "object" && !Array.isArray(t.props)) {
+        out.props = t.props;
+    }
+    // `meta` IS PART OF THE WRITABLE SHAPE (e.g. `{height, width}`). Dropping it
+    // made every read-modify-write quietly degrade a tag that carried it — and
+    // the loss guard could not see it, since a singular slot is matched by slot.
+    if (t.meta !== undefined &&
+        t.meta !== null &&
+        typeof t.meta === "object" &&
+        !Array.isArray(t.meta)) {
+        out.meta = t.meta;
+    }
+    if (typeof t.children === "string")
+        out.children = t.children;
+    if (typeof t.custom === "boolean")
+        out.custom = t.custom;
+    if (typeof t.disabled === "boolean")
+        out.disabled = t.disabled;
+    return out;
+}
+/** The tags an item or the site holds RIGHT NOW, hashed like a redirect token:
+ *  consent is given on a list that was shown, and stops being consent the
+ *  moment that list changes. */
+function tagsToken(site, scope, current, proposed = []) {
+    // THE TOKEN SIGNS THE CHANGE, not just the state. Binding it to the current
+    // tags alone let a caller earn a token by proposing to drop the description,
+    // then reuse that same token with `tags: []` and take the title too — a loss
+    // nobody was ever shown. Proposal included, any edit to what is being written
+    // mints a different token and earns a fresh refusal.
+    const canonical = JSON.stringify([
+        site,
+        scope,
+        current.map((t) => [tagLabel(t), JSON.stringify(t)]).sort(),
+        proposed.map((t) => [tagLabel(t), JSON.stringify(t)]).sort(),
+    ]);
+    return `${scope}:${createHmac("sha256", TOKEN_SECRET)
+        .update(canonical)
+        .digest("hex")
+        .slice(0, 16)}`;
+}
+/** Tags the item holds now that the incoming set does not replace — the loss
+ *  nobody asked for. */
+/** What identifies one tag AMONG OTHERS IN THE SAME SLOT: its content. */
+function tagContent(t) {
+    // THE WHOLE TAG, not just its text. Two tags sharing a slot and a `content`
+    // can still differ by `custom` or `disabled`, and comparing only the text
+    // reported the odd one out as kept.
+    const tag = (t ?? {});
+    const props = (tag.props ?? {});
+    return JSON.stringify([
+        Object.keys(props)
+            .sort()
+            .map((k) => [k, props[k]]),
+        tag.meta ?? null,
+        typeof tag.children === "string" ? tag.children : null,
+        tag.custom === true,
+        tag.disabled === true,
+    ]);
+}
+/** Tags the item holds now that the incoming set does not replace.
+ *
+ *  A slot that appears ONCE is matched by slot alone: replacing a description
+ *  with another description is an edit, not a loss, and demanding an
+ *  acknowledgement for every routine rewrite would be ceremony.
+ *
+ *  A slot that REPEATS — two `og:image`, several `article:tag`, several JSON-LD
+ *  blocks — cannot be matched that way: sending one of them made all of them
+ *  read as kept, and the rest went out silently. There, a tag survives only if
+ *  an identical one is being sent. */
+function tagsLostBy(current, next) {
+    const incomingBySlot = new Map();
+    for (const t of next) {
+        const slot = tagLabel(t);
+        const list = incomingBySlot.get(slot) ?? [];
+        list.push(tagContent(t));
+        incomingBySlot.set(slot, list);
+    }
+    const currentCounts = new Map();
+    for (const t of current) {
+        const slot = tagLabel(t);
+        currentCounts.set(slot, (currentCounts.get(slot) ?? 0) + 1);
+    }
+    // THE VALUE TRAVELS WITH THE LOSS. A slot alone reads the same whether the
+    // description that disappears said one thing or another, and the operator is
+    // deciding on the thing, not on its address.
+    const lost = [];
+    // MATCHES ARE CONSUMED. Two identical tags held today against ONE being sent
+    // is a loss of one of them; a set that only tested membership called both
+    // kept.
+    const unclaimed = new Map([...incomingBySlot].map(([k, v]) => [k, [...v]]));
+    for (const t of current) {
+        const slot = tagLabel(t);
+        const incoming = incomingBySlot.get(slot);
+        if (incoming === undefined || incoming.length === 0) {
+            lost.push({ ...tagPreview(t), tag: t });
+            continue;
+        }
+        const repeated = (currentCounts.get(slot) ?? 0) > 1 || incoming.length > 1;
+        if (!repeated)
+            continue;
+        const pool = unclaimed.get(slot) ?? [];
+        const at = pool.indexOf(tagContent(t));
+        if (at === -1) {
+            lost.push({ ...tagPreview(t), tag: t });
+        }
+        else {
+            pool.splice(at, 1);
+            unclaimed.set(slot, pool);
+        }
+    }
+    return lost;
+}
+/** Read one item's SEO tags, failing closed like `listExisting`. */
+async function readItemOwnTags(client, siteId, itemType, itemId, signal) {
+    const resp = await client.request("GET", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(itemType)}/${encodeURIComponent(itemId)}`, { siteId, signal });
+    // THE ENVELOPE MUST BE THERE. Falling back to the whole response accepted any
+    // 2xx object — `{}` , or a Developer Preview reshuffle — as "this item owns no
+    // tags", and a full replacement then went out with nothing to acknowledge.
+    // An item with no tags of its own still returns `itemSeoTags`; it is `tags`
+    // that is legitimately empty.
+    const holder = resp !== null && typeof resp === "object"
+        ? resp.itemSeoTags
+        : undefined;
+    if (holder === null || typeof holder !== "object" || Array.isArray(holder)) {
+        throw new Error("Refusing to write: the read of this item's SEO tags did not return the " +
+            "`itemSeoTags` object this version understands, so the check for what " +
+            "the write would replace cannot be trusted.");
+    }
+    const tags = holder.tags;
+    if (tags !== undefined && !Array.isArray(tags)) {
+        throw new Error("Refusing to write: this item's SEO tags could not be read as a list, so " +
+            "the check for what the write would replace cannot be trusted.");
+    }
+    return tags ?? [];
+}
+/** The acknowledgement a tag write takes, mirroring the redirects'. */
+const AcknowledgeReplacementParam = Type.Optional(Type.String({
+    description: "The `token` from a previous refusal, once the user has accepted losing " +
+        "the tags it listed. Tied to what the item holds RIGHT NOW: if the tags " +
+        "changed since the refusal, the token no longer matches and the call is " +
+        "refused again with a fresh list.",
+}));
+/** `fieldMask` travels as a COMMA-SEPARATED STRING over REST. The SDK takes an
+ *  array, which is what a model reaches for; sending one here is silently not
+ *  the documented shape. Built, never accepted from the caller. */
+function fieldMaskOf(...fields) {
+    return fields.filter((f) => typeof f === "string").join(",");
+}
+const SEO_PATTERNS = "/promote/seo/v1/seo-patterns";
+/** The current pattern for a page type, plus HOW MANY PAGES it drives.
+ *
+ *  The count is best-effort on purpose: `pageType` and the item-tags
+ *  `itemType` are two vocabularies that overlap but are not documented as the
+ *  same, so a type that lists nothing is reported as `unknown` rather than
+ *  blocking the write. Refusing on a failed COUNT would be refusing on an
+ *  inference. */
+async function readPatternPreflight(client, siteId, pageType, pageId, signal) {
+    // THE COUNT RUNS FIRST, AND THE PATTERN IS READ LAST. Both orders answer
+    // the same, but the pattern read is what the caller's token is computed
+    // over: with up to ten listing requests standing between that read and
+    // the PATCH, a dashboard edit landing in between was overwritten under a
+    // token that had never been shown it. Reading it last leaves no request
+    // of ours inside the window.
+    // THE COUNT IS A CLAIM, so it says what it does not know.
+    //   - it follows the cursor instead of reporting the first page as the total;
+    //   - it excludes items that carry their OWN tags, which a pattern does not
+    //     drive — counting them overstated the blast radius;
+    //   - an EMPTY list reads as `unknown`, not `0`: `pageType` and the item-tags
+    //     `itemType` are two vocabularies that overlap without being documented
+    //     as the same, so "nothing came back" cannot be told apart from "this
+    //     type is not listable here";
+    //   - past the page bound it reports `"100+"` rather than a number it did
+    //     not finish counting.
+    let pageCount = "unknown";
+    // UNKNOWN UNTIL COUNTED. Reporting `0` when the listing failed asserted that
+    // no page carries tags of its own — a fact the pre-flight never established.
+    let partialOverrides = "unknown";
+    try {
+        let cursor = null;
+        let unreadableCursor = false;
+        let driven = 0;
+        let overridden = 0;
+        let seen = 0;
+        let rounds = 0;
+        do {
+            // THE COMPOSITE TYPE for a Wix Data page — `WIX_DATA_PAGE_ITEM-{pageId}`,
+            // as this plugin's own `wix_seo_list_item_tags` description already
+            // states. Listing the bare type returned nothing, so a dynamic page
+            // pattern lost exactly the blast radius the pre-flight exists to show.
+            const listType = pageType === "WIX_DATA_PAGE_ITEM" && pageId !== undefined
+                ? `${pageType}-${pageId}`
+                : pageType;
+            const listed = await client.request("GET", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(listType)}`, {
+                siteId,
+                signal,
+                query: compactQuery({
+                    "paging.limit": 100,
+                    ...(cursor !== null ? { "paging.cursor": cursor } : {}),
+                }),
+            });
+            const body = (listed ?? {});
+            const items = Array.isArray(body.itemsSeoTags) ? body.itemsSeoTags : [];
+            seen += items.length;
+            // EVERY ITEM COUNTS. `hasOverride` says the item sets SOME tag of its
+            // own, not that it escapes the pattern — the tags it does not override
+            // still resolve from it. Excluding those pages understated the blast
+            // radius, down to zero on a type where every item has a title of its own.
+            driven += items.length;
+            overridden += items.filter((i) => i.hasOverride === true).length;
+            const next = body.pagingMetadata?.cursors?.next;
+            // A CURSOR IN A SHAPE THIS VERSION DOES NOT READ IS NOT AN END OF LIST.
+            // Coercing it to `null` stopped the walk early and then reported the
+            // pages counted so far as an EXACT total — understating the blast
+            // radius on the very screen that exists to show it.
+            if (next !== undefined && next !== null && typeof next !== "string") {
+                unreadableCursor = true;
+                break;
+            }
+            cursor = typeof next === "string" && next.length > 0 ? next : null;
+        } while (cursor !== null && ++rounds < 10);
+        if (!unreadableCursor && seen > 0) {
+            // PAST THE BOUND, BOTH NUMBERS ARE LOWER BOUNDS. Only `pageCount` said
+            // so: pages never walked can carry overrides too, so an exact
+            // `partialOverrides` understated how many pages keep tags of their own
+            // — on the screen that exists to size the blast radius.
+            pageCount = cursor !== null ? `${driven}+` : driven;
+            partialOverrides = cursor !== null ? `${overridden}+` : overridden;
+        }
+    }
+    catch (err) {
+        // AN ABORT IS NOT A FAILED COUNT. Swallowing it let a cancelled call carry
+        // on and answer with a refusal, reported as a successful result.
+        throwIfAborted(signal);
+        if (err instanceof Error && err.name === "AbortError")
+            throw err;
+        pageCount = "unknown";
+        partialOverrides = "unknown";
+    }
+    const resp = await client.request("GET", `${SEO_PATTERNS}/${encodeURIComponent(pageType)}`, {
+        siteId,
+        signal,
+        // THE RESOURCE THE WRITE WILL TOUCH. `pageId` narrows the pattern to one
+        // dynamic page; omitting it here read the page TYPE's generic pattern
+        // while the write went to the page's own — so the token, the templates
+        // shown and the page count all described something else.
+        query: compactQuery({ pageId }),
+    });
+    // FAIL CLOSED. Falling back to the whole response turned an unrecognised
+    // body into "this page type has no pattern" — and for the reset that is the
+    // branch that skips the acknowledgement entirely, sending a site-wide reset
+    // with nothing shown.
+    const holder = resp !== null && typeof resp === "object"
+        ? resp.seoPattern
+        : undefined;
+    if (holder === null || typeof holder !== "object" || Array.isArray(holder)) {
+        throw new Error("Refusing to write: the read of this page type's pattern did not return " +
+            "the `seoPattern` object this version understands, so the check for " +
+            "what the write would replace cannot be trusted.");
+    }
+    const pattern = holder.pattern;
+    // A `pattern` THAT IS THERE BUT UNREADABLE IS NOT AN ABSENT ONE. A string or
+    // an array used to fall through to `tags: []`, and the reset — whose whole
+    // acknowledgement hangs on `tags.length > 0` — then fired immediately on
+    // every page of the type.
+    if (pattern !== undefined &&
+        (pattern === null || typeof pattern !== "object" || Array.isArray(pattern))) {
+        throw new Error("Refusing to write: this page type's `pattern` came back in a shape this " +
+            "version does not understand, so it cannot be told apart from a page " +
+            "type that has no pattern at all.");
+    }
+    const rawTags = pattern !== null && pattern !== undefined && typeof pattern === "object"
+        ? pattern.tags
+        : undefined;
+    if (rawTags !== undefined && !Array.isArray(rawTags)) {
+        throw new Error("Refusing to write: this page type's pattern could not be read as a list " +
+            "of tag templates, so the check for what the write would replace " +
+            "cannot be trusted.");
+    }
+    // OWNERSHIP COMES FROM `source`, NOT FROM A COUNT. A site pattern holding
+    // zero templates is still the site's own: inferring absence from
+    // `tags.length` made the create recommend a POST that fails
+    // PATTERN_ALREADY_EXISTS, and let the reset fire with no acknowledgement.
+    const source = holder.source;
+    // NO `source`, NO ANSWER. Deducing ownership from the template count made an
+    // OWNED but empty pattern read as the Wix default — the branch on which the
+    // reset skips its acknowledgement entirely and deletes that pattern.
+    if (typeof source !== "string" || source.length === 0) {
+        throw new Error("Refusing to write: this page type's pattern came back without a " +
+            "`source`, so a pattern the site owns cannot be told apart from the " +
+            "Wix default — and the two lead to opposite writes.");
+    }
+    const hasOwnPattern = source !== "PATTERN_SOURCE_DEFAULT";
+    return {
+        tags: rawTags ?? [],
+        pageCount,
+        partialOverrides,
+        hasOwnPattern,
+    };
+}
+/** The blast radius, as the token sees it.
+ *
+ *  THE RADIUS IS PART OF WHAT WAS ACKNOWLEDGED. Binding only the templates let
+ *  a token minted while the type held 12 pages authorise the same write once it
+ *  held 400: the second pre-flight recomputed the count, printed nothing, and
+ *  wrote. An operator who accepted "this changes 12 pages" never accepted 400.
+ *  A count that becomes `unknown` expires the token too — fail-closed is the
+ *  same direction as everywhere else here. */
+function radiusOf(p) {
+    return `pages=${p.pageCount}:own=${p.partialOverrides}`;
+}
 export function buildSeoTools(client) {
     return [
         // ---------------------------------------------------------------- audit
@@ -828,6 +1254,619 @@ export function buildSeoTools(client) {
                 });
             }),
         }, client),
+        // ---------------------------------------------------- tranche 2: writes
+        defineWixTool({
+            name: "wix_seo_set_item_tags",
+            description: "Set one item's SEO tags. REPLACES the item's own tags IN FULL: send " +
+                "the complete set you want it to have, not just the one you are " +
+                "changing. To give an item back the tags it inherits, call " +
+                "`wix_seo_reset_item_tags` — an empty list is not the way. " +
+                "THE CHECK IS RUN FOR YOU: the tool reads the item first and REFUSES, " +
+                "naming every tag the write would drop, until you call again with " +
+                "`acknowledgeReplacement` set to the `token` from that refusal. " +
+                "PUBLISHED vs SAVED — a static page keeps both. Without `publish` you " +
+                "change the saved revision; with `publish: true` you change ONLY the " +
+                "published one. The read tools always return the SAVED revision, so " +
+                "after a `publish` write they keep showing the old values: that is " +
+                "NOT a failed write and re-sending will not change it. To move both, " +
+                "call twice — once without `publish`, once with. This tool's own " +
+                "response is not a read of the published page either, so never report " +
+                "the live page as changed on the strength of it. " +
+                "Tags are validated before anything is saved: an invalid tag changes " +
+                "nothing. Tags can only be written for the item's primary language.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                itemType: Type.String({
+                    description: "e.g. `STATIC_PAGE`, `BLOG_POST`, `STORES_PRODUCT`.",
+                }),
+                itemId: Type.String({ description: "GUID of the item." }),
+                tags: Type.Array(SeoTagSchema, {
+                    maxItems: 100,
+                    description: "The COMPLETE set of tags this item should own. Accepted types: " +
+                        "`title`, `meta`, `script`, `link`" + ".",
+                }),
+                publish: Type.Optional(Type.Boolean({
+                    description: "Write the PUBLISHED revision instead of the saved one. Read " +
+                        "the tool description before using it.",
+                })),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                // AN EMPTY LIST IS NOT A REPLACEMENT. Upstream is explicit: to give
+                // an item back what it inherits, call Reset — sending no tags
+                // leaves an empty override behind instead. `minItems` in the schema
+                // does not cover it, since `execute` is callable directly.
+                if (params.tags.length === 0) {
+                    return {
+                        refused: "an empty tag list does not restore inherited tags, it leaves an empty override",
+                        howToProceed: "Call `wix_seo_reset_item_tags` to return this item to the " +
+                            "tags it inherits.",
+                    };
+                }
+                const next = params.tags.map((t) => sanitizeTag(t, ["title", "meta", "script", "link"]));
+                const current = await readItemOwnTags(client, params.siteId, params.itemType, params.itemId, signal);
+                // THE PUBLISHED REVISION CANNOT BE PRE-READ. `publish: true` writes
+                // the published revision, while every read returns the SAVED one —
+                // Wix exposes no way to read the published tags. So the list below
+                // describes the draft, and a live-only tag would be dropped without
+                // ever appearing in it. A write nobody could be shown is refused
+                // every time, loss detected or not: the one answer a safety check
+                // must never invent is the reassuring one.
+                const blindToLive = params.publish === true;
+                const scope = `item:${params.itemType}:${params.itemId}:${blindToLive ? "published" : "saved"}`;
+                const token = tagsToken(effectiveSite, scope, current, next);
+                const lost = tagsLostBy(current, next);
+                if ((lost.length > 0 || blindToLive) &&
+                    params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: blindToLive
+                            ? "this writes the PUBLISHED revision, which cannot be read back — what it replaces there is not knowable, and has not been acknowledged"
+                            : "this write would drop tags the item holds today, and they have not been acknowledged for their CURRENT state",
+                        ...(blindToLive
+                            ? {
+                                publishedRevisionUnreadable: "`wouldLose` below is the SAVED revision. If the published page carries tags the draft does not, this write drops them and they are not listed — no API returns them.",
+                            }
+                            : {}),
+                        wouldLose: lost,
+                        keeping: next.map((t) => tagPreview(t)),
+                        token,
+                        howToProceed: "Show what would be lost to the user — these are facts the " +
+                            "page states today. Only if they accept, call again with " +
+                            "`acknowledgeReplacement` set to the token above, adding any " +
+                            "of those tags you meant to keep to `tags`.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("PATCH", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(params.itemType)}/${encodeURIComponent(params.itemId)}`, {
+                    siteId: params.siteId,
+                    signal,
+                    // NOT REPLAYED: the pre-flight ran against the state read once;
+                    // a replay re-applies a write whose basis may have moved.
+                    retry: false,
+                    body: {
+                        itemSeoTags: { tags: next },
+                        // BUILT, NOT ACCEPTED. Over REST the mask is a comma-separated
+                        // STRING; the SDK takes an array, which is what a model
+                        // reaches for.
+                        fieldMask: fieldMaskOf("tags"),
+                        ...(params.publish === true ? { publish: true } : {}),
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_reset_item_tags",
+            description: "Give one item back the tags it INHERITS, discarding every tag of its " +
+                "own. All or nothing: there is no way to reset only some of them. " +
+                "The tool reads the item first and REFUSES, listing everything that " +
+                "would go, until you call again with `acknowledgeReplacement` set to " +
+                "the `token` from that refusal. Permanent — the previous tags are not " +
+                "kept anywhere.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                itemType: Type.String(),
+                itemId: Type.String(),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const current = await readItemOwnTags(client, params.siteId, params.itemType, params.itemId, signal);
+                const scope = `reset:${params.itemType}:${params.itemId}`;
+                const token = tagsToken(effectiveSite, scope, current);
+                // A TOKEN EVEN THOUGH THE OUTCOME IS A NAMED STATE. The outcome
+                // does not depend on what is there now, but the CONSENT does: the
+                // user accepts losing the list they were shown. If the item's tags
+                // changed in between, that list no longer describes the loss.
+                if (current.length > 0 && params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "resetting discards every tag this item owns, and they have not been acknowledged for their CURRENT state",
+                        wouldLose: current.map((t) => ({ ...tagPreview(t), tag: t })),
+                        token,
+                        howToProceed: "Show these to the user. Only if they accept the loss, call " +
+                            "again with `acknowledgeReplacement` set to the token above.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(params.itemType)}/${encodeURIComponent(params.itemId)}/reset-to-default`, { siteId: params.siteId, signal, retry: false });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_set_site_tags",
+            description: "Set the SITE-WIDE SEO tags — they apply to every page. REPLACES the " +
+                "site's tags IN FULL, same rule as the per-item write. The tool REFUSES, " +
+                "naming every site-wide tag the write would drop, until you call " +
+                "again with `acknowledgeReplacement` set to the `token` from that " +
+                "refusal. " +
+                "ONLY `meta` TAGS: Wix rejects `title`, `script` and `link` here even " +
+                "though the shared tag shape lists them. There is currently no way to " +
+                "set site-wide structured data through any Wix API — write a per-page " +
+                "`script` tag with `wix_seo_set_item_tags` instead.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                tags: Type.Array(SeoTagSchema, {
+                    maxItems: 100,
+                    description: "The COMPLETE set of site-wide tags. `meta` only.",
+                }),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const next = params.tags.map((t) => sanitizeTag(t, ["meta"]));
+                const resp = await client.request("GET", "/promote/seo/v1/site-seo-tags", { siteId: params.siteId, signal });
+                // Same fail-closed rule as the per-item read: falling back to the
+                // whole response turned `{}` into "the site has no tags", and the
+                // PATCH then replaced every site-wide tag with nothing to
+                // acknowledge.
+                const holder = resp !== null && typeof resp === "object"
+                    ? resp.siteSeoTags
+                    : undefined;
+                if (holder === null ||
+                    typeof holder !== "object" ||
+                    Array.isArray(holder)) {
+                    throw new Error("Refusing to write: the read of the site's SEO tags did not " +
+                        "return the `siteSeoTags` object this version understands, " +
+                        "so the check for what the write would replace cannot be " +
+                        "trusted.");
+                }
+                const rawTags = holder.tags;
+                if (rawTags !== undefined && !Array.isArray(rawTags)) {
+                    throw new Error("Refusing to write: the site's SEO tags could not be read as a " +
+                        "list, so the check for what the write would replace cannot " +
+                        "be trusted.");
+                }
+                const current = rawTags ?? [];
+                const token = tagsToken(effectiveSite, "site", current, next);
+                const lost = tagsLostBy(current, next);
+                if (lost.length > 0 && params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "this write would drop site-wide tags in force today, and they have not been acknowledged for their CURRENT state",
+                        wouldLose: lost,
+                        keeping: next.map((t) => tagPreview(t)),
+                        token,
+                        howToProceed: "These apply to EVERY page. Show them to the user and only " +
+                            "call again, with `acknowledgeReplacement` set to the token " +
+                            "above, once they accept the loss.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("PATCH", "/promote/seo/v1/site-seo-tags", {
+                    siteId: params.siteId,
+                    signal,
+                    retry: false,
+                    body: {
+                        siteSeoTags: { tags: next },
+                        fieldMask: fieldMaskOf("tags"),
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_bulk_set_item_tags",
+            description: "Set the SEO tags of MANY items of the same type in one call. Each " +
+                "entry behaves like `wix_seo_set_item_tags`: it REPLACES that item's " +
+                "own tags in full. The tool reads every item first and REFUSES, " +
+                "listing per entry what would be dropped, until you call again with " +
+                "`acknowledgeReplacement` set to the `token` from that refusal. " +
+                "SIZE: up to 100 entries, but `BLOG_POST` is capped at 20 by Wix and " +
+                "exceeding an item type's own limit fails the WHOLE call with " +
+                "`BULK_CHUNK_SIZE_EXCEEDED` — split and retry. " +
+                "PARTIAL SUCCESS: read `results[].itemMetadata` and correlate by " +
+                "`originalIndex`; check `bulkActionMetadata.totalFailures`. One bad " +
+                "entry fails alone. But an unsupported item type, or an unauthorized " +
+                "request, rejects the whole call with no per-entry results — handle " +
+                "both. Re-sending an entry that already succeeded is safe: the writes " +
+                "are idempotent. " +
+                "`publish` is REQUEST-level here: it applies to every entry, and like " +
+                "the single write it moves only the published revision while the read " +
+                "tools keep returning the saved one.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                itemType: Type.String(),
+                entries: Type.Array(Type.Object({
+                    itemId: Type.String(),
+                    tags: Type.Array(SeoTagSchema, { maxItems: 100 }),
+                }), { minItems: 1, maxItems: 100 }),
+                publish: Type.Optional(Type.Boolean()),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                // ENFORCED HERE because Wix fails the WHOLE call, not the offending
+                // entries: a 40-post batch would write nothing at all. The cap is
+                // the reference's own (`BLOG_POST` 20), not a guess.
+                const perTypeCap = params.itemType === "BLOG_POST" ? 20 : 100;
+                if (params.entries.length > perTypeCap) {
+                    return {
+                        refused: `Wix caps a ${params.itemType} bulk write at ${perTypeCap} entries and rejects the whole call beyond it`,
+                        entries: params.entries.length,
+                        howToProceed: `Split into batches of at most ${perTypeCap} and call again.`,
+                    };
+                }
+                // DUPLICATES REFUSED BEFORE THE READS. Two entries for one item are
+                // two FULL replacements of the same tags, both pre-flighted against
+                // the same starting state: the second silently undoes whatever the
+                // first introduced, and neither loss appears in `wouldLose`.
+                const ids = params.entries.map((e) => e.itemId);
+                const duplicated = [...new Set(ids.filter((id, i) => ids.indexOf(id) !== i))];
+                if (duplicated.length > 0) {
+                    return {
+                        refused: "the same item appears more than once in this batch, and each entry replaces its tags in full",
+                        duplicated,
+                        howToProceed: "Merge the entries for each item into one complete set of " +
+                            "tags and call again.",
+                    };
+                }
+                const empties = params.entries
+                    .filter((e) => e.tags.length === 0)
+                    .map((e) => e.itemId);
+                if (empties.length > 0) {
+                    return {
+                        refused: "an empty tag list does not restore inherited tags, it leaves an empty override",
+                        entriesWithNoTags: empties,
+                        howToProceed: "Drop those entries and call `wix_seo_reset_item_tags` for " +
+                            "each item that should go back to what it inherits.",
+                    };
+                }
+                const prepared = params.entries.map((e) => ({
+                    itemId: e.itemId,
+                    next: e.tags.map((t) => sanitizeTag(t, ["title", "meta", "script", "link"])),
+                }));
+                // ONE READ PER ENTRY. There is no bulk read of item tags, and the
+                // loss cannot be shown without knowing what each item holds today.
+                const losses = [];
+                const currentOf = new Map();
+                for (const e of prepared) {
+                    throwIfAborted(signal);
+                    const current = await readItemOwnTags(client, params.siteId, params.itemType, e.itemId, signal);
+                    currentOf.set(e.itemId, current);
+                    const lost = tagsLostBy(current, e.next);
+                    if (lost.length > 0)
+                        losses.push({ itemId: e.itemId, wouldLose: lost });
+                }
+                // Same blindness as the single write, request-wide here.
+                const blindToLive = params.publish === true;
+                const scope = `bulk:${params.itemType}:${blindToLive ? "published" : "saved"}`;
+                const token = tagsToken(effectiveSite, scope, 
+                // PAIRED, NOT TWO SORTED LISTS. Signing the proposals apart from
+                // their item ids made A→X/B→Y and A→Y/B→X hash identically, so an
+                // acknowledgement earned for one pairing authorised the other and
+                // replaced tags whose loss was never approved.
+                prepared
+                    .map((e) => [e.itemId, currentOf.get(e.itemId) ?? [], e.next])
+                    .sort((a, b) => String(a[0]).localeCompare(String(b[0]))), []);
+                if ((losses.length > 0 || blindToLive) &&
+                    params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: blindToLive
+                            ? "this batch writes the PUBLISHED revision of every entry, which cannot be read back — what it replaces there is not knowable, and has not been acknowledged"
+                            : "this batch would drop tags these items hold today, and they have not been acknowledged for their CURRENT state",
+                        ...(blindToLive
+                            ? {
+                                publishedRevisionUnreadable: "`wouldLose` below is each item's SAVED revision. Tags that exist only on the published page are dropped without being listed.",
+                            }
+                            : {}),
+                        wouldLose: losses,
+                        itemsAffected: prepared.length,
+                        token,
+                        howToProceed: "Show the losses to the user, grouped by item. Only if they " +
+                            "accept, call again with `acknowledgeReplacement` set to the " +
+                            "token above — the token covers the WHOLE batch and goes " +
+                            "stale if any of these items changes.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", "/promote/seo/v1/bulk/item-seo-tags/set", {
+                    siteId: params.siteId,
+                    signal,
+                    // NOT REPLAYED: bulk is non-atomic, so a replay's own per-entry
+                    // results would hide which of the first attempt's writes landed.
+                    retry: false,
+                    body: {
+                        itemType: params.itemType,
+                        entries: prepared.map((e) => ({
+                            itemId: e.itemId,
+                            itemSeoTags: { tags: e.next },
+                            fieldMask: fieldMaskOf("tags"),
+                        })),
+                        ...(params.publish === true ? { publish: true } : {}),
+                    },
+                });
+            }),
+        }, client),
+        // ------------------------------------------------- tranche 2: patterns
+        //
+        // THE WIDEST BLAST RADIUS IN THIS PLUGIN. A pattern is the tag template for
+        // an ENTIRE page type: writing one changes the title of every blog post, or
+        // every product, at once. It also has NO REVISION, and the site's SEO
+        // settings in the Wix dashboard write to the same pattern — last write
+        // wins. Hence: read immediately before writing, bind the token to what was
+        // read, and say how many pages are downstream.
+        defineWixTool({
+            name: "wix_seo_list_patterns",
+            description: "List the site's SEO patterns — the tag templates applied per page " +
+                "type. A page type absent from the list is on its Wix default. " +
+                "Read-only.",
+            parameters: Type.Object({ siteId: SiteIdParam }),
+            run: (params, _client, signal) => client.request("GET", `${SEO_PATTERNS}`, {
+                siteId: params.siteId,
+                signal,
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_get_pattern",
+            description: "One page type's SEO pattern. Read `source` to know whose it is: " +
+                "`PATTERN_SOURCE_DEFAULT` means the page type renders Wix's default, " +
+                "anything else means the site owns the pattern — an owned pattern " +
+                "may legitimately hold ZERO templates, so an empty `pattern` is not " +
+                "the same as having none. `wix_seo_create_pattern` is for a page type " +
+                "on the Wix default; `wix_seo_set_pattern` for one the site owns. " +
+                "Pass `pageId` to read the pattern of ONE dynamic page rather than " +
+                "the page type's — the writes accept the same targeting, and a write " +
+                "replaces the pattern in full, so this is how you read what to send " +
+                "back. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String({
+                    description: "e.g. `BLOG_POST`, `STORES_PRODUCT`.",
+                }),
+                pageId: Type.Optional(Type.String({
+                    description: "GUID of a single dynamic page. Supported for " +
+                        "`WIX_DATA_PAGE_ITEM` page types.",
+                })),
+            }),
+            run: (params, _client, signal) => client.request("GET", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}`, {
+                siteId: params.siteId,
+                signal,
+                query: compactQuery({ pageId: params.pageId }),
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_list_pattern_variables",
+            description: "The variables a page type's pattern may reference. A pattern tag " +
+                "that names anything else is invalid — call this BEFORE writing a " +
+                "pattern rather than guessing a variable name. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String(),
+            }),
+            run: (params, _client, signal) => client.request("GET", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}/variables`, { siteId: params.siteId, signal }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_set_pattern",
+            description: "Change the pattern of a page type that ALREADY HAS ONE. For a page " +
+                "type still on its Wix default, use `wix_seo_create_pattern` — this " +
+                "one changes, it does not create. " +
+                "REPLACES the page type's tag templates IN FULL: read the pattern " +
+                "first and send back the complete set. Wix documents an empty " +
+                "pattern as CLEARING it, returning the page type to the Wix default " +
+                "— but `wix_seo_reset_pattern` is the method that says so plainly, " +
+                "and it is the one to use when that is the intent. " +
+                "THIS CHANGES EVERY PAGE OF THE TYPE AT ONCE. The tool reads the " +
+                "current pattern, reports how many pages are downstream, and REFUSES " +
+                "until you call again with `acknowledgeReplacement` set to the " +
+                "`token` from that refusal. " +
+                "A pattern has no revision and the Wix dashboard writes to the same " +
+                "one: last write wins, so a token that has gone stale means somebody " +
+                "else changed it — re-read before insisting. " +
+                "A tag may reference only the variables `wix_seo_list_pattern_variables` " +
+                "returns for this page type.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String(),
+                tags: Type.Array(SeoTagSchema, {
+                    maxItems: 100,
+                    description: "The COMPLETE set of tag templates for this page type.",
+                }),
+                pageId: Type.Optional(Type.String({
+                    description: "GUID of a single dynamic page, when the pattern applies to " +
+                        "that page alone rather than to the whole type.",
+                })),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const next = params.tags.map((t) => sanitizeTag(t, ["title", "meta", "script", "link"]));
+                const preflight = await readPatternPreflight(client, params.siteId, params.pageType, params.pageId, signal);
+                const token = tagsToken(effectiveSite, `pattern:${params.pageType}:${params.pageId ?? "-"}:${preflight.hasOwnPattern ? "owned" : "default"}:${radiusOf(preflight)}`, preflight.tags, next);
+                const lost = tagsLostBy(preflight.tags, next);
+                // The mirror of the create's check: PATCH changes a pattern that
+                // exists, so on a page type still rendering the Wix default it
+                // cannot do anything but fail — asking for an acknowledgement
+                // first would only make the failure slower.
+                if (!preflight.hasOwnPattern) {
+                    return {
+                        refused: "this page type is on the Wix default and has no pattern of its own to change",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        howToProceed: "Use `wix_seo_create_pattern` to give it its first pattern.",
+                    };
+                }
+                if (params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "a pattern applies to every page of its type; this write has not been acknowledged for the pattern's CURRENT state",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        pagesWithSomeTagsOfTheirOwn: preflight.partialOverrides,
+                        currentTemplates: preflight.tags.map((t) => tagPreview(t)),
+                        wouldLose: lost,
+                        keeping: next.map((t) => tagPreview(t)),
+                        token,
+                        howToProceed: "Tell the user how many pages this changes and what the " +
+                            "templates become. Only once they accept, call again with " +
+                            "`acknowledgeReplacement` set to the token above.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("PATCH", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}`, {
+                    siteId: params.siteId,
+                    signal,
+                    retry: false,
+                    body: {
+                        seoPattern: {
+                            pattern: { tags: next },
+                            ...(params.pageId !== undefined ? { pageId: params.pageId } : {}),
+                        },
+                        fieldMask: fieldMaskOf("pattern"),
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_create_pattern",
+            description: "Give a page type its FIRST pattern, replacing the Wix default. If " +
+                "the page type already has one, use `wix_seo_set_pattern` instead — " +
+                "these two share a path and differ only by HTTP method, so the wrong " +
+                "one is an easy mistake. " +
+                "Same blast radius as the set: every page of the type renders from " +
+                "this template. The tool REFUSES, reporting how many pages are " +
+                "downstream, until you call again with `acknowledgeReplacement` set " +
+                "to the `token` from that refusal.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String(),
+                tags: Type.Array(SeoTagSchema, { maxItems: 100 }),
+                pageId: Type.Optional(Type.String()),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const next = params.tags.map((t) => sanitizeTag(t, ["title", "meta", "script", "link"]));
+                const preflight = await readPatternPreflight(client, params.siteId, params.pageType, params.pageId, signal);
+                const token = tagsToken(effectiveSite, `pattern-create:${params.pageType}:${params.pageId ?? "-"}:${preflight.hasOwnPattern ? "owned" : "default"}:${radiusOf(preflight)}`, preflight.tags, next);
+                // TERMINAL, NOT A TOKEN. Handing one out for a page type that
+                // already owns a pattern only bought a POST Wix answers with
+                // PATTERN_ALREADY_EXISTS.
+                if (preflight.hasOwnPattern) {
+                    return {
+                        refused: "this page type already has a pattern of its own — create is for a page type still on the Wix default",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        howToProceed: "Use `wix_seo_set_pattern` to change it, or " +
+                            "`wix_seo_reset_pattern` to return the page type to the Wix " +
+                            "default first.",
+                    };
+                }
+                if (params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "this pattern will drive every page of its type, and has not been acknowledged",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        pagesWithSomeTagsOfTheirOwn: preflight.partialOverrides,
+                        // SHOWN, like the set's. Acknowledging a replacement of
+                        // something never displayed is not consent.
+                        currentTemplates: preflight.tags.map((t) => tagPreview(t)),
+                        proposedTemplates: next.map((t) => tagPreview(t)),
+                        token,
+                        howToProceed: preflight.hasOwnPattern
+                            ? "This page type ALREADY has a pattern — `wix_seo_set_pattern` is the method for that. Confirm with the user before proceeding."
+                            : "Tell the user how many pages this changes, then call again with `acknowledgeReplacement` set to the token above.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}`, {
+                    siteId: params.siteId,
+                    signal,
+                    retry: false,
+                    body: {
+                        seoPattern: {
+                            pattern: { tags: next },
+                            ...(params.pageId !== undefined ? { pageId: params.pageId } : {}),
+                        },
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_reset_pattern",
+            description: "Return a page type to its WIX DEFAULT pattern, discarding the site's " +
+                "own. Every page of the type re-renders from the default. The tool " +
+                "reads the current pattern, reports how many pages are downstream and " +
+                "REFUSES until you call again with `acknowledgeReplacement` set to " +
+                "the `token` from that refusal. Permanent. " +
+                "Pass `pageId` to reset the pattern of ONE dynamic page — without it " +
+                "the reset targets the page TYPE's own pattern, which is a different " +
+                "object and leaves a per-page override in place.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String(),
+                pageId: Type.Optional(Type.String({
+                    description: "GUID of a single dynamic page whose pattern to reset. " +
+                        "`wix_seo_set_pattern` and `wix_seo_create_pattern` can create " +
+                        "such an override, so this is how it is undone.",
+                })),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const preflight = await readPatternPreflight(client, params.siteId, params.pageType, params.pageId, signal);
+                const token = tagsToken(effectiveSite, `pattern-reset:${params.pageType}:${params.pageId ?? "-"}:${radiusOf(preflight)}`, preflight.tags);
+                if (preflight.hasOwnPattern && params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "resetting discards the site's own pattern for this page type, and it has not been acknowledged for its CURRENT state",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        // BOUND, THEREFORE SHOWN. The token covers this number, so a
+                        // retry could be refused with a refusal that read identically
+                        // — the caller unable to see which half of the radius moved.
+                        pagesWithSomeTagsOfTheirOwn: preflight.partialOverrides,
+                        wouldLose: preflight.tags.map((t) => ({
+                            ...tagPreview(t),
+                            tag: t,
+                        })),
+                        token,
+                        howToProceed: "Show the templates that would go and the number of pages " +
+                            "affected. Only if the user accepts, call again with " +
+                            "`acknowledgeReplacement` set to the token above.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}/reset-to-default`, {
+                    siteId: params.siteId,
+                    signal,
+                    retry: false,
+                    // PLACEMENT INFERRED, AND SAID SO. The reference lists
+                    // `pageId` as a method parameter of this POST without showing
+                    // it on the wire, so the body is the REST convention rather
+                    // than a documented fact. It matters: if Wix ignored the field
+                    // the reset would hit the page TYPE's pattern instead of the
+                    // one page, which is a far wider loss than the refusal
+                    // described. Confirming it needs a live create-then-reset on a
+                    // throwaway dynamic page, which this plugin will not do to
+                    // answer a question.
+                    ...(params.pageId !== undefined
+                        ? { body: { pageId: params.pageId } }
+                        : {}),
+                });
+            }),
+        }, client),
     ];
 }
 // `SeoTagSchema` is exported for the write tools that land in tranche 2