@wix/agent-skills 1.16.1 → 1.16.3

package/skills/wix-app/references/editor-react-component/FUNCTION-HANDLERS.md

@@ -0,0 +1,167 @@
+# Function Event Handlers
+
+Rules and patterns for adding function event handler props to an Editor React component's TypeScript interface, wiring them to DOM events, and declaring custom callbacks.
+
+---
+
+## Rules
+
+### Standard SDK Event Handlers
+
+These are the standard event handler props the editor SDK exposes to site owners. Use the exact prop names — ZeroConfig and the manifest system recognize them.
+
+| Prop name    | React DOM event | Type                                             |
+| ------------ | --------------- | ------------------------------------------------ |
+| `onClick`    | `onClick`       | `(event: React.MouseEvent) => void`              |
+| `onDblClick` | `onDoubleClick` | `(event: React.MouseEvent) => void`              |
+| `onChange`   | `onChange`      | `(event: React.ChangeEvent<HTMLElement>) => void` |
+| `onFocus`    | `onFocus`       | `(event: React.FocusEvent) => void`              |
+| `onBlur`     | `onBlur`        | `(event: React.FocusEvent) => void`              |
+| `onMouseIn`  | `onMouseEnter`  | `(event: React.MouseEvent) => void`              |
+| `onMouseOut` | `onMouseLeave`  | `(event: React.MouseEvent) => void`              |
+
+Three props have a **name mismatch** between the SDK prop and the DOM event: `onDblClick` → `onDoubleClick`, `onMouseIn` → `onMouseEnter`, `onMouseOut` → `onMouseLeave`.
+
+### Declaring Standard Handler Props
+
+Declare standard handlers inline with the exact SDK prop names and React event types:
+
+```typescript
+interface MyComponentProps {
+  label?: string;
+  onClick?: (event: React.MouseEvent) => void;
+  onDblClick?: (event: React.MouseEvent) => void;
+  onChange?: (event: React.ChangeEvent<HTMLElement>) => void;
+  onFocus?: (event: React.FocusEvent) => void;
+  onBlur?: (event: React.FocusEvent) => void;
+  onMouseIn?: (event: React.MouseEvent) => void;
+  onMouseOut?: (event: React.MouseEvent) => void;
+}
+```
+
+Only declare handlers the component actually exposes. Do not add all seven if the component only handles two.
+
+### Wiring Standard Handlers to DOM Events
+
+Destructure the props and pass them to the correct DOM event — applying the name mappings:
+
+```typescript
+export const MyComponent = (props: MyComponentProps) => {
+  const { onClick, onDblClick, onFocus, onBlur, onMouseIn, onMouseOut } = props;
+  return (
+    <div
+      onClick={onClick}
+      onDoubleClick={onDblClick}
+      onFocus={onFocus}
+      onBlur={onBlur}
+      onMouseEnter={onMouseIn}
+      onMouseLeave={onMouseOut}
+    >
+      {/* ... */}
+    </div>
+  );
+};
+```
+
+### Custom Callbacks
+
+Component-specific callbacks that do not correspond to a DOM event (e.g., `onPlay`, `onPause`, `onEnded`, `onTimeupdate`) are **not** standard SDK event handlers. Type them as `() => void` — no React event parameter:
+
+```typescript
+interface VideoPlayerProps {
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+}
+```
+
+Pass them directly to the underlying element — no name remapping needed:
+
+```typescript
+export const VideoPlayer = (props: VideoPlayerProps) => {
+  const { onPlay, onPause, onEnded } = props;
+  return <video onPlay={onPlay} onPause={onPause} onEnded={onEnded} />;
+};
+```
+
+---
+
+## Common Mistakes
+
+### Passing SDK prop name directly to DOM instead of remapping
+
+**❌ Wrong:**
+
+```typescript
+export const MyComponent = (props: MyComponentProps) => {
+  const { onMouseIn, onMouseOut, onDblClick } = props;
+  return (
+    <div
+      onMouseIn={onMouseIn} // ❌ not a valid React DOM prop
+      onMouseOut={onMouseOut} // ❌ not a valid React DOM prop
+      onDblClick={onDblClick} // ❌ not a valid React DOM prop
+    />
+  );
+};
+```
+
+**✅ Correct:**
+
+```typescript
+export const MyComponent = (props: MyComponentProps) => {
+  const { onMouseIn, onMouseOut, onDblClick } = props;
+  return (
+    <div
+      onMouseEnter={onMouseIn} // ✅ onMouseIn → onMouseEnter
+      onMouseLeave={onMouseOut} // ✅ onMouseOut → onMouseLeave
+      onDoubleClick={onDblClick} // ✅ onDblClick → onDoubleClick
+    />
+  );
+};
+```
+
+### Adding a React event parameter to custom callbacks
+
+**❌ Wrong:**
+
+```typescript
+interface VideoPlayerProps {
+  onPlay?: (event: React.SyntheticEvent) => void; // ❌ event param on custom callback
+  onEnded?: (event: React.SyntheticEvent) => void; // ❌ event param on custom callback
+}
+```
+
+**✅ Correct:**
+
+```typescript
+interface VideoPlayerProps {
+  onPlay?: () => void; // ✅ no event param
+  onEnded?: () => void; // ✅ no event param
+}
+```
+
+**Why:** Custom callbacks are component-level notifications to the site owner, not DOM event forwarders. They carry no event object — the SDK passes no event to them.
+
+### Using the DOM event name as the SDK prop name
+
+**❌ Wrong:**
+
+```typescript
+interface MyComponentProps {
+  onDoubleClick?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
+  onMouseEnter?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
+  onMouseLeave?: (event: React.MouseEvent) => void; // ❌ DOM name, not SDK name
+}
+```
+
+**✅ Correct:**
+
+```typescript
+interface MyComponentProps {
+  onDblClick?: (event: React.MouseEvent) => void; // ✅ SDK prop name
+  onMouseIn?: (event: React.MouseEvent) => void; // ✅ SDK prop name
+  onMouseOut?: (event: React.MouseEvent) => void; // ✅ SDK prop name
+}
+```
+
+**Why:** The SDK prop names (`onDblClick`, `onMouseIn`, `onMouseOut`) are what ZeroConfig and the manifest system register. Using DOM names breaks the editor's event wiring.

package/skills/wix-app/references/editor-react-component/MANIFEST-ERRORS.md

@@ -0,0 +1,19 @@
+# Manifest Build Errors
+
+The error name is always the first token before the colon (`IoError:`, `ParseError:`, `NotFoundError:`). Find the matching row, apply the fix, then re-run both commands.
+
+| Error | Fix |
+|---|---|
+| `IoError: Failed to load compiled bundle` | Re-run `npx wix build`; fix any TypeScript/build errors it reports first |
+| `IoError: Failed to access component "X" from compiled bundle` | Corrupted artifact — delete `dist/`, re-run `npx wix build` from scratch |
+| `IoError: CSS selector matching failed for "X"` | Fix invalid selector syntax in `<componentName>.module.css` |
+| `IoError: Component "X" render produced no root element` | Component returns null or bare text — ensure it always renders a root JSX element |
+| `IoError` (render phase, no other pattern) | SSR crash — remove browser-only APIs (`window`, `document`, `localStorage`) used at render time; ensure props have defaults |
+| `NotFoundError: File not found` | Source `.tsx` missing — restore it or re-scaffold with `npx wix generate` |
+| `NotFoundError: Component "X" was not found as a named export` | Confirm `component.tsx` has a default export and re-run `npx wix build` |
+| `ParseError: Failed to parse TypeScript config` | Fix `tsconfig.json`; run `npx tsc --noEmit` to surface the error |
+| `ParseError: Failed to extract component types from "X"` | TypeScript error in the component — run `npx tsc --noEmit` and fix |
+| `ParseError: Failed to compile "<file.scss>"` | SCSS syntax error — line/column is in the error message |
+| `ParseError: Failed to parse CSS file for component "X"` | CSS syntax error in `.module.css` — line/column is in the error message |
+
+After each fix, re-run `npx wix build && npx wix generate manifest` to confirm.

package/skills/wix-app/references/editor-react-component/PARTS.md

@@ -23,7 +23,7 @@ An element deserves its own named part if a site owner would plausibly need to i
 - ❌ **State or variant** (`active`, `selected`, `current`, `disabled`, `open`, `checked`) — not a part, it's a **design state** of a part. Implement it per [`DESIGN-STATES.md`](DESIGN-STATES.md): native states from interactive markup; custom states as a flat global modifier on the element's own (component-name-prefixed) class (e.g. `carousel-slide--active`, toggled in JSX) plus a `:global(.carousel-slide--active)` CSS rule. The modifier is a state, not a named part.
 - ❌ **Hidden/shown state of an existing part** — the hidden and shown states of a part are not separate parts. The element itself should be a named part (so the editor can control its visibility per breakpoint); creating an additional part to represent its hidden or shown variant is wrong.
 - ❌ **Pure grouping wrapper** — not a part. A `<div>` whose only role is to hold already-named siblings has no independent editor surface; let layout live in the parent's CSS.
-- ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs. **Exception — interactive HTML elements (`<button>`, `<a>`, `<input>`) are never excluded by this criterion.** They always carry an independent styling surface: background, border, border-radius, hover/focus states, color, and typography are all meaningfully tunable per element in the editor. Apply this exclusion only to purely static structural elements (layout wrappers, grouping containers, decorative dividers). This makes an interactive element a named part **when it is an inner element** — if it is the elected root (Step 0), it is already named by `'<component-name>'` and must not be given a prefixed inner-part class as well.
+- ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs. **Exception — interactive HTML elements (`<button>`, `<a>`, `<input>`) are never excluded by this criterion.** They always carry an independent styling surface: background, border, border-radius, interaction states, color, and typography are all meaningfully tunable per element in the editor. Apply this exclusion only to purely static structural elements (layout wrappers, grouping containers, decorative dividers). This makes an interactive element a named part **when it is an inner element** — if it is the elected root (Step 0), it is already named by `'<component-name>'` and must not be given a prefixed inner-part class as well.
 - ❌ **Positional duplicate** — not separate parts. Elements that are semantically identical and differ only in position (e.g. prev/next buttons) are one part; differentiate position with CSS (`:first-of-type` / `:last-of-type`, `data-` attribute, or `:nth-child`).
 - ✅ **Passes all checks** — a named part. Classify as **Semantic** (needs `elementProps`: data, behavior, direction, event handlers) or **Styling-only** (CSS class is sufficient).
 
@@ -36,4 +36,3 @@ Before finalising, verify each proposed part against its parent:
 If yes — the part adds no independent editor surface and should be removed. This catches rationalisation after-the-fact ("the parent *could* expose this CSS property too, but so could the child separately"). When in doubt, fewer parts is usually better.
 
 Then run the same question in reverse, on the root: if the root has exactly one child part and no editor surface of its own, it is a plumbing wrapper — delete it and promote the child per Step 0.
-

package/skills/wix-app/references/editor-react-component/REACT-GUIDELINES.md

@@ -9,6 +9,7 @@ This guide defines rules and guidance on **how to implement** production-quality
 - [`DIRECTIONALITY.md`](DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`COMPONENT-API.md`](COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
+- [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md) — Standard SDK event handler props, DOM wiring, custom callbacks
 - [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
 - [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
 
@@ -110,7 +111,7 @@ Unless explicitly specified as a component capability/API in the specification,
 **External handlers (only when specified):**
 
 - Only expose handlers that are explicitly listed as component capabilities
-- Example: If specification says "onClick callback for external control", then add `onClick?: () => void` to props
+- Use the standard SDK prop names and DOM wiring rules from [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md)
 
 **Child component handlers:**
 
@@ -170,4 +171,3 @@ See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`COMPONENT-API.md`](COMPONENT-API.
 **Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards; toggle custom-state classes from data ([`DESIGN-STATES.md`](DESIGN-STATES.md))
 
 **Phase 3: Styles** — Apply Part 2 SCSS rules, including state styles ([`DESIGN-STATES.md`](DESIGN-STATES.md)). If the request uses the words **branded**, **themed**, or **brand-aware**, also apply [`BRANDED-COMPONENTS.md`](BRANDED-COMPONENTS.md) before writing CSS.
-

package/skills/wix-base44-connector/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: wix-base44-connector
+description: "Build on Wix from the Base44 builder sandbox — this file is the complete guide (site context, doc discovery, API contracts, who calls Wix from where), and scripts/utils.js is its helper module, loaded from disk per exec. Triggers: build a Base44 app on a connected Wix site, look up a Wix API from the sandbox, decide frontend vs backend for a Wix call."
+---
+
+# Building on Wix from Base44
+
+The Wix connector is connected; this is how the app gets built on it — gather the site's context,
+find the APIs and learn their contracts from the docs, write the code. **Discover everything**: endpoints, paths, doc URLs,
+request and response fields all come from the calls below, never from memory or pattern. 404 or
+empty ⇒ discover, not permute. Examples teach mechanics and go stale — verify before relying.
+
+## What are you building?
+
+The app's audience picks the token, and the token picks the architecture: the **visitor token is
+public** — anyone can mint it from the site's `clientId` — and the **admin token is a secret**,
+the connector's, server-side only.
+
+```
+browser            ──(visitor token)─► wixapis.com   the visitor's own reads & actions
+base44/functions/* ──(admin token)───► wixapis.com   work that needs the owner's identity
+exec_tool          ──(admin token)───► wixapis.com   you: ad hoc probing/managing while building
+```
+
+**A site for visitors** — storefront, blog, booking. Headless means the Wix site has no pages of
+its own: your app IS its frontend. **The complete visitor experience —
+every page, every read, every action a visitor takes — is browser calls on the visitor token;
+none of it needs a backend function.** Public reads
+included (the visitor token queries the catalog directly), and `carts/current/*` + checkout act
+on the CALLER's cart, so only the visitor token reaches the visitor's cart. One file carries it
+all: `src/lib/wixClient.js` (Write the code, below). `base44/functions/*` appear only where work
+needs the owner's identity — elevated-permission ops a visitor triggers, webhooks, scheduled
+jobs — and for the app's non-Wix backend.
+
+**An admin tool for the owner** — dashboard, back office. The pages act as the owner, whose token
+is a secret: `pages → base44/functions/* ──(admin token)──► wixapis.com`.
+
+## The helpers
+
+Research and probing run in exec_tool, and one loader opens every exec (execs share no state —
+reload each round; the module lives on disk next to this file, network only as first-touch
+fallback):
+
+```js
+const fs = require("fs"), P = ".agents/skills/wix-base44-connector/utils.js";
+if (!fs.existsSync(P)) { fs.mkdirSync(".agents/skills/wix-base44-connector", { recursive: true });
+  fs.writeFileSync(P, await (await fetch("https://www.wix.com/skills/wix-base44-connector/scripts/utils.js")).text()); }
+const wx = (() => { const m = { exports: {} };
+  new Function("module", "exports", "require", fs.readFileSync(P, "utf8"))(m, m.exports, require); return m.exports; })();
+```
+
+Results ≤ 4,000 chars come back inline (exec results clip at ~5,000); anything bigger is saved
+under `.agents/skills/wix-base44-connector/scratch/` and returns `{ path, bytes, lines, outline }` —
+the outline is the map. Read a saved file the way you already know how:
+`wx.bash("grep -n 'term' <path> | head -40")` to find (GNU grep/sed, awk is mawk, no rg;
+across everything saved: `grep -rn 'term' .agents/skills/wix-base44-connector/scratch/`), and
+`read_file` to quote — a window via `offset`/`limit` at the lines grep named, or the whole
+file when it fits read_file's 45K cap. **API responses are site data and never land in
+scratch** — project them to facts. Fetch every URL inside exec with `fetch()` — website/browser
+tools clip at 10,000 chars silently. One exec per round; timeout 10s, up to 120 via `{timeout}`.
+
+## Gather context — the dynamic context report
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+return await wx.context(accessToken, "Apps");   // no section arg → the report's outline
+```
+
+One report: installed apps **with ids** (incl. Stores' catalog version — V1 vs V3 decides its
+endpoints), the OAuth app id (**also the visitor `clientId`**), locale, currency, CMS collections.
+An empty report = bad token, never an empty site.
+
+## Learn Wix — find the APIs, learn their contracts
+
+```js
+// know the product? browse is deterministic — menuUrl alone orients (children + counts);
+// filter before listing methods, unfiltered listings clip
+await wx.browse("https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings",
+                { include: ["METHOD"], filter: "resched", depth: 4 });
+
+// don't know where it lives? search ranks, never says "no match" — drop wrong-product hits
+await wx.search("pause a pricing plan subscription and resume it");
+// → { hits: [{ method, endpoint /* callable */, docsUrl, gist }] } — hits often ARE the answer
+```
+
+Go deeper for fields, enums, or absence — only the spec index proves absence.
+
+### Read a doc page
+
+Method pages are 100 KB+, twin REST and SDK halves repeating field names at different types —
+map and window in the SAME exec; coordinates are for your code, not for a second round:
+
+```js
+const pg = await wx.page(docsUrl);   // whole text when small; else { path, bytes, lines, outline }
+// your half, windowed to your term and its Examples (a complete working request — URL, headers,
+// body — usually all you need), one round:
+return wx.bash(`sed -n '/^## REST API/,/^## JavaScript SDK/p' ${pg.path} | grep -B5 -A40 -i 'examples\\|<term>' | head -c 3800`);
+// a giant fenced example → its field vocabulary instead of paging it:
+// wx.bash(`sed -n '<a>,<b>p' ${pg.path} | grep -oE '"[a-zA-Z]+":' | sort -u | head -60`)
+```
+
+`search` also saves its raw content beside the inline hits — grep its `path` when a hit's six
+lines weren't enough.
+
+### The spec index
+
+Answers questions about pages you already found — arrive with a `docsUrl`, match by it. Also the
+only proof an API does NOT exist:
+
+```js
+await wx.spec(`
+  const r = lightIndex.find(x => x.docsUrl === "<docsUrl from browse/search>");
+  return r.methods.map(m => ({ op: m.operationId.split(".").pop(), verb: m.httpMethod,
+                               call: m.publicUrl }));   // publicUrl is callable — path is PARTIAL
+`);
+// request fields next round: getResourceSchemaByUrl(docsUrl) →
+//   m.requestBody.content["application/json"].schema.properties — names and types, drill deeper
+//   per round; $circular stubs resolve via s.components.schemas["<name>"]
+```
+
+### Management recipes — check before composing admin flows
+
+~100 curated multi-step recipes (install apps, seed catalogs, set up whole verticals):
+
+```js
+await wx.recipes();           // categories with counts
+await wx.recipes("stores");   // a category's list — or any task word: wx.recipes("coupon")
+await wx.page(url);           // read the chosen recipe — whole when small, saved + outline when
+                              // big; then grep / read_file windows by the outline's line numbers
+```
+
+A matching recipe beats composing the flow from single endpoints: it carries ordering and
+cross-step gotchas no method page mentions.
+
+## Write the code
+
+**Response shapes obey the discover rule in every lane**: code against fields you saw in a live
+response or the schema — remembered names are often from older versions. Probe one real row first.
+
+### Admin calls — exec ad hoc, backend functions deployed
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+const data = await wx.post("https://www.wixapis.com/contacts/v5/contacts/query",   // spec-index publicUrl
+  { query: { cursorPaging: { limit: 10 } } }, accessToken);
+// let it throw — the thrown message is your result; .catch hides the answer
+return wx.clip({ error: null, count: data.contacts?.length, first: data.contacts?.[0] });
+//  ↑ one real row, whole — the shapes you code against live here, not in key names
+```
+
+The same call deploys as `base44/functions/*` (work the app does as the owner) — shipped code
+carries its own four-line fetch; the helpers are a build tool, not a runtime dependency.
+
+### A visitor client — src/lib/wixClient.js
+
+The "site for visitors" shape (What are you building?), in code — one file pages import. Neither
+`clientId` (from the context report) nor the minted token is a secret; together they are "an
+anonymous visitor", safe in shipped code:
+
+```js
+// src/lib/wixClient.js
+let token;
+const mint = async (body) => {
+  const r = await (await fetch("https://www.wixapis.com/oauth2/token", { method: "POST",
+    headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) })).json();
+  token = r.access_token; sessionStorage.setItem("wixRefresh", r.refresh_token);   // expires_in: 14400s = 4h
+};
+// first visit:  mint({ clientId: WIX_CLIENT_ID, grantType: "anonymous" });
+// on expiry:    mint({ refreshToken: sessionStorage.getItem("wixRefresh"), grantType: "refresh_token" });
+//               a fresh anonymous mint is a NEW visitor — the old one's cart goes with it
+export const wix = (path, opts = {}) => fetch("https://www.wixapis.com" + path, { ...opts,
+  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
+```
+
+Token contract: `…/headless/authentication/retrieve-tokens`. Prove the lane in one exec before
+writing pages — mint a visitor, make one public read with it:
+
+```js
+const { access_token } = await wx.post("https://www.wixapis.com/oauth2/token",
+  { clientId: WIX_CLIENT_ID, grantType: "anonymous" });   // clientId: from the context report
+return await wx.post("<a public read from Learn Wix>", { query: {} }, access_token);
+// 200 ⇒ every visitor-facing page in the app is this same call, no server between
+// a lean default response isn't the whole shape — contracts often define a fields param
+// that opts INTO heavier parts (formatted prices, media); read the contract for it
+```

package/skills/wix-base44-connector/scripts/utils.js

@@ -0,0 +1,212 @@
+// Wix docs helpers for the Base44 sandbox — the scratch-lane set. Small results return
+// inline; anything over ~4,000 chars (exec results clip at ~5,000) is saved under the
+// scratch dir and comes back as { path, bytes, lines, outline } with the read tools
+// pre-pointed at it.
+//
+// Load per exec (execs share no state) — from disk, network only as first-touch fallback:
+//   const fs = require("fs"), P = ".agents/skills/wix-base44-connector/utils.js";
+//   if (!fs.existsSync(P)) { fs.mkdirSync(".agents/skills/wix-base44-connector", { recursive: true });
+//     fs.writeFileSync(P, await (await fetch("https://www.wix.com/skills/wix-base44-connector/scripts/utils.js")).text()); }
+//   const wx = (() => { const m = { exports: {} };
+//     new Function("module", "exports", "require", fs.readFileSync(P, "utf8"))(m, m.exports, require); return m.exports; })();
+//
+// Read a saved file the way you already know how: wx.bash("grep -n 'term' <path> | head -40")
+// to find, read_file(<path>) with offset/limit to window (numbered lines, 45K cap — no exec
+// round needed), pipelines for the rest (GNU grep/sed; awk is mawk; no rg).
+//
+// API responses are site data and stay OUT of scratch (scratch ships with the app):
+// post() never saves — project responses to facts.
+
+const fs = require("fs");
+const path = require("path");
+
+const BUDGET = 4000;
+const SCRATCH = ".agents/skills/wix-base44-connector/scratch";
+
+const clip = (out) => {
+  if (typeof out === "string")
+    return out.length <= BUDGET ? out : { truncated: true, total: out.length, head: out.slice(0, BUDGET) };
+  // absence must be visible: JSON.stringify silently ERASES undefined keys, so a probe like
+  // { lineItems: resp.cart?.lineItems } loses the very field that proves the call failed —
+  // render undefined as null instead
+  const s = JSON.stringify(out, (k, v) => v === undefined ? null : v);
+  return s.length <= BUDGET ? JSON.parse(s) : { truncated: true, total: s.length, head: s.slice(0, BUDGET) };
+};
+
+// One transport for every JSON call — Content-Type, optional Bearer, ok-guard.
+// Admin calls are this with the connector token: post(publicUrl, body, accessToken).
+async function post(url, body, token) {
+  const r = await fetch(url, { method: "POST", body: JSON.stringify(body),
+    headers: { "Content-Type": "application/json", ...(token && { Authorization: `Bearer ${token}` }) } });
+  if (!r.ok) {
+    const head = (await r.text()).slice(0, 300);
+    throw new Error(r.status + " " + head + (r.status < 500
+      ? " — a 4xx means wrong body or reference: read this endpoint's contract before changing the call"
+      : ""));
+  }
+  return r.json();
+}
+
+function save(name, text) {
+  const dir = path.join(process.cwd(), SCRATCH);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, name), text);
+  return { path: SCRATCH + "/" + name, bytes: Buffer.byteLength(text), lines: text.split("\n").length };
+}
+
+const outlineOf = (lines, cap = 30) => {
+  const heads = [];
+  lines.forEach((t, i) => { if (/^#{1,3} /.test(t)) heads.push({ line: i + 1, text: t.trim().slice(0, 80) }); });
+  return { outline: heads.slice(0, cap), outlineOmitted: Math.max(0, heads.length - cap) };
+};
+
+// A ref is a scratch path or the URL it came from — resolve to lines, fetching+saving
+// URLs on first touch (the .md suffix is appended for extensionless docs URLs).
+const slugOf = (url) => url.replace(/\?.*$/, "").split("/").pop().replace(/\.md$/, "") + ".md";
+async function resolveRef(ref) {
+  const isUrl = /^https?:/.test(ref);
+  const name = isUrl ? slugOf(ref) : ref.split("/").pop();
+  const file = path.join(process.cwd(), SCRATCH, name);
+  if (fs.existsSync(file)) return { path: SCRATCH + "/" + name, lines: fs.readFileSync(file, "utf8").split("\n") };
+  if (!isUrl) throw new Error("no such scratch file: " + ref + " — pass a returned path or the source URL");
+  const mdUrl = /\.[a-z]{2,5}$/.test(ref.replace(/\?.*$/, "")) ? ref : ref.replace(/\?.*$/, "") + ".md";
+  const res = await fetch(mdUrl);
+  if (!res.ok) throw new Error(res.status + " on " + mdUrl + " — not a docs page; take URLs from output, don't compose");
+  const text = await res.text();
+  const saved = save(name, text);
+  return { path: saved.path, lines: text.split("\n") };
+}
+
+// ── gather context ────────────────────────────────────────────────────────────
+
+// The dynamic context report — site data, never saved. No section → the whole report
+// when it fits, else its header outline; with one → that section's text. Empty
+// report = bad token, never an empty site.
+async function context(token, section) {
+  const { markdown } = await post(
+    "https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown", {}, token);
+  if (!section) {
+    if (markdown.length <= BUDGET) return markdown;   // most sites: the whole report, one round
+    return { truncated: true, total: markdown.length, head: markdown.slice(0, BUDGET),
+             note: "site data — never saved (no path); narrow: wx.context(token, '<section name>')" };
+  }
+  const m = markdown.match(new RegExp("^#{1,3} .*" + section + "[\\s\\S]*?(?=\\n#{1,3} |$)", "im"));
+  return clip({ total: markdown.length, section: m ? m[0] : "not found — call context(token) for the outline" });
+}
+
+// ── find what to read ─────────────────────────────────────────────────────────
+
+// Browse the docs tree — deterministic. menuUrl alone orients (children + counts);
+// filter before listing methods. An oversized listing is saved with its outline.
+async function browse(menuUrl, { include, filter, depth } = {}) {
+  const { content } = await post("https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse", {
+    menu_url: menuUrl, ...(include && { include }),
+    ...(filter && { name_filter: filter }), ...(depth && { depth }),
+  });   // 404 "No menu node found" ⇒ re-orient a level up
+  if (content.length <= BUDGET) return content;
+  const s = save("browse-" + (menuUrl.replace(/\/+$/, "").split("/").pop() || "root") + ".md", content);
+  return { ...s, next: `wx.bash("grep -in 'term' ${s.path} | head -40")   // one line per node — or re-browse with a filter` };
+}
+
+// Semantic search — ranks, never says "no match". The reduced hits come back inline
+// AND the full raw content is saved for grep/window follow-ups.
+async function search(term, { type = "REST", max = 5, lines = 6 } = {}) {
+  const { content } = await post("https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown",
+    { search_term: term, document_type: type, maximum_results: max, lines_in_each_result: lines });
+  const hits = content.split(/\n---\n+(?=#### )/).map(b => ({
+    method:   (b.match(/^# Method: (.+)$/m) || [])[1],
+    endpoint: (b.match(/^# Method API Endpoint: (.+)$/m) || [])[1],   // callable
+    docsUrl:  (b.match(/#### \[[^\]]+\]\((https:[^)]+)\)/) || [])[1],
+    gist: ((b.match(/## Method Description:\s*\n([\s\S]{0,400})/) || [])[1] || "")
+      .trim().replace(/\s+/g, " ").slice(0, 220),
+  })).filter(h => h.docsUrl);
+  const saved = save("search-" + term.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40) + ".md", content);
+  if (!hits.length) return clip({ ...saved, head: content.slice(0, 1200),
+    note: `no method blocks parsed — raw head above; wx.bash("grep -in 'term' ${saved.path}") for the rest` });
+  return clip({ ...saved, hits });
+}
+
+// ── read a page (docs pages and recipes alike) ────────────────────────────────
+
+// Fetch + save + map in one round: whole text inline when small, else
+// { path, bytes, lines, outline } — the outline's line numbers feed grep and read_file windows.
+async function page(url) {
+  const { path: p, lines } = await resolveRef(url);
+  const text = lines.join("\n");
+  if (text.length <= BUDGET) return text;
+  const o = outlineOf(lines);
+  const bytes = Buffer.byteLength(text);
+  return { path: p, bytes, lines: lines.length, ...o,
+           next: [
+             `wx.bash("grep -in 'term' ${p} | head -40")`,
+             bytes <= 45000 ? `read_file ${p}   // whole (fits the 45K cap), or a window via offset/limit`
+                            : `read_file ${p} with offset/limit   // window a section by the outline's lines`,
+           ] };
+}
+
+// ── shell ─────────────────────────────────────────────────────────────────────
+
+// Compose native pipelines over scratch — grep -n, sed -n, mawk, sort, uniq, wc
+// (GNU grep/sed; awk is mawk; no rg). Cap your own output (| head -40); the return
+// clips regardless. grep's exit 1 means no match, not failure — the return says so.
+function bash(cmd) {
+  const { execSync } = require("child_process");
+  try {
+    const out = execSync(cmd, { timeout: 15000, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+    return out.trim() ? clip(out)
+      : "(no output — a filter may have swallowed the signal; rerun without the reducer)";
+  } catch (e) {
+    const exit = e.status ?? null, err = (e.stderr || "").toString().trim();
+    return { exit, ...(err && { err: err.slice(0, 300) }),
+             out: clip((e.stdout || "").toString()),
+             ...(exit === 1 && !err && { note: "exit 1 with no stderr — a no-match, not a failure" }) };
+  }
+}
+
+// ── the spec index ────────────────────────────────────────────────────────────
+
+// Run a query over the API spec index. In scope: lightIndex (RESOURCES with
+// .methods — operationId, summary, httpMethod, path [PARTIAL — never call it],
+// publicUrl [callable], docsUrl) and getResourceSchemaByUrl(docsUrl). Arrive with
+// a docsUrl and match by it — also the only proof an API does NOT exist.
+// A big result is saved as JSON; grep it for the keys you saw in its head.
+async function spec(code) {
+  if (!/^\s*async function/.test(code)) code = `async function(){ ${code} }`;
+  const { result } = await post("https://mcp.wix.com/api/code-mode/search", { code });
+  if (result == null || (Array.isArray(result) && !result.length))
+    return { result, note: "empty — the query missed the shape, not proof of absence; find the resource by docsUrl on lightIndex" };
+  const text = JSON.stringify(result, null, 1);
+  if (text.length <= BUDGET) return result;
+  return { ...save("spec.json", text),
+           shape: Array.isArray(result) ? `Array(${result.length})` : Object.keys(result || {}).slice(0, 15),
+           head: text.slice(0, 600) };
+}
+
+// ── management recipes ────────────────────────────────────────────────────────
+
+// ~100 curated multi-step admin flows. No arg → categories with counts; a category
+// name → its recipes; any other term → search every recipe's name + gist for it.
+// Read the chosen url with page(url), then grep/window/fields.
+async function recipes(q) {
+  const { base, files } = await (await fetch("https://dev.wix.com/docs/skills/manage.manifest.json")).json();
+  const cat = f => (f.path.match(/^references\/([^/]+)\//) || [])[1];
+  const row = f => ({ name: f.name, cat: cat(f), gist: (f.description || "").slice(0, 120),
+                      url: base + f.path, kb: Math.round(f.size / 1024) });
+  if (!q) {
+    const cats = {};
+    for (const f of files) { const c = cat(f); if (c) cats[c] = (cats[c] || 0) + 1; }
+    return cats;
+  }
+  const inCat = files.filter(f => cat(f) === q);
+  if (inCat.length) return clip(inCat.map(row));
+  const re = new RegExp(q, "i");
+  const m = files.filter(f => re.test(f.name + " " + (f.description || "")));
+  if (!m.length) {
+    const cats = {};
+    for (const f of files) { const c = cat(f); if (c) cats[c] = (cats[c] || 0) + 1; }
+    return { note: `nothing matches "${q}" — the categories:`, categories: cats };
+  }
+  return clip(m.map(row));
+}
+
+module.exports = { post, clip, context, browse, search, page, bash, spec, recipes };