@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-harmony-editor/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: wix-harmony-editor
+description: Edit Wix Harmony sites through an authenticated Harmony editor using Playwright over a local Chrome CDP session. Use for inspecting, changing, saving, and verifying Harmony editor components and layouts, and for copying an existing website's pages into Harmony exactly (see COPY-SITE.md); do not use for Wix Studio, the classic Editor, Dashboard data, or publishing without explicit approval.
+---
+
+# Wix Harmony editor
+
+Work through the Wix Harmony editor, not the published site. Use the local Chrome launcher and Playwright; the standard in-app browser may not expose the isolated Chrome CDP session.
+
+This file is how to connect to the editor and work in it. **Copying an existing site's page
+into Harmony has its own rules: read [COPY-SITE.md](COPY-SITE.md) before starting a copy.**
+
+**Order for a migration: create the site, then bring the data (store, bookings, blog and other
+app data, public and/or private), then build the front end here.** Do not start the editor for a
+store or other app-backed site before its data is in, unless the user asks and approves
+(COPY-SITE.md, "Order").
+
+## Safety and scope
+
+- Treat the editor as a persistent external system. Inspect before writing.
+- Obtain clear user authorization immediately before a persistent change unless the request already explicitly authorizes that exact change. State the component and intended effect.
+- Never publish unless the user explicitly asks. Saving a draft is not publishing.
+- Work only on visible front-end editor content. Dashboard data (Stores, Bookings, contacts, orders, coupons, members, blog posts, or settings) is out of scope. Site media and fonts that the page displays are front-end content and in scope.
+- The launcher uses a separate Chrome profile. Never use, copy, or inspect the user's normal Chrome profile.
+- Do not expose cookies, local storage, headers, session data, or CDP WebSocket URLs. Use only the local `http://127.0.0.1:9333` endpoint launched for this task.
+- If the sandbox blocks `connectOverCDP` with `EPERM`, request elevation specifically for the local loopback connection. Do not use a remote host, a different port, or a workaround that exposes the debugger.
+
+## Launch and authenticate
+
+Run the bundled launcher with the Wix editor URL:
+
+```bash
+skills/wix-harmony-editor/scripts/launch.sh 'https://example.editor.wix.com/edit/...'
+```
+
+It starts a headed Chrome instance with an isolated, private profile and a loopback-only CDP port. If Wix shows a sign-in page, let the user authenticate in that browser. Never ask for or enter credentials yourself.
+
+The launcher is intentionally quiet about CDP internals. It reports only whether local Chrome is reachable.
+
+The first launch usually lands on `users.wix.com/signin`. Tell the user to sign in in that
+window (the account that owns the site), then poll until the editor tab exists and
+`window.repluggableAppDebug` is defined. Do not treat the sign-in page as an error.
+
+## Attach with Playwright
+
+Confirm the expected editor is open before doing anything else:
+
+```bash
+node --input-type=module -e "
+import { chromium } from 'playwright';
+const browser = await chromium.connectOverCDP('http://127.0.0.1:9333');
+const pages = browser.contexts().flatMap(context => context.pages());
+console.log(await Promise.all(pages.map(async page => ({ url: page.url(), title: await page.title() }))));
+await browser.close();
+"
+```
+
+In a Playwright script, resolve the editor page mechanically:
+
+```js
+const page = browser.contexts()
+  .flatMap(context => context.pages())
+  .find(page => page.url().includes('editor.wix.com/edit/'));
+
+if (!page) throw new Error('No authenticated Wix Harmony editor page is open.');
+```
+
+`browser.close()` detaches Playwright; it does not close the launched Chrome instance.
+
+## Initialize and use the Harmony API
+
+All API code runs in `page.evaluate`:
+
+```js
+const api = await repluggableAppDebug.host.getAPI({
+  name: 'RunEditorLLMCodeToolAPI',
+  public: true,
+  layer: 'DATA_SERVICE',
+});
+```
+
+Execute editor code with the required editor context:
+
+```js
+await api.execute(
+  { code: 'return await editorLLMApis.catalog.list();' },
+  { biParams: {} },
+);
+```
+
+The `{ biParams: {} }` second argument is required in this workflow. Omitting it produces `Cannot read properties of undefined (reading 'biParams')`; that error changed nothing in the observed case, but do not use failed calls to discover write signatures.
+
+### Discover before acting
+
+1. Start with `editorLLMApis.catalog.list()` for namespace orientation.
+2. Read documentation only for namespaces needed by the task, in one documentation-only call:
+
+   ```js
+   return await editorLLMApis.catalog.describe({
+     namespaces: ['pages', 'components', 'layout', 'breakpoints', 'appearance', 'site'],
+   });
+   ```
+
+   `describe` has a response budget. A namespace that does not fit comes back as
+   `[NOT RETURNED …]` or `[Truncated …]`; fetch that one alone with
+   `catalog.describe({ namespaces: ['<name>'] })`. `components`, `richText`, `media`,
+   `layout` and `appearance` each need their own call. Save the docs to files and read
+   them from there instead of re-fetching.
+3. Never introspect undocumented API objects or guess a write method's arguments.
+4. Open/focus the correct page before reads, because component reads resolve against the focused page.
+5. Use IDs, element paths, units, tokens, and schemas returned by live reads—never assumed values.
+6. After every write, do a fresh read of the normalized, user-visible result. A write echo alone is not verification.
+
+Common namespaces: `pages` (focus the page), `components` (find and inspect), `layout` (measure and resize), `breakpoints` (desktop/mobile view), `appearance` (borders/backgrounds), and `site` (save/publish status).
+
+## Execution pattern
+
+```js
+const result = await page.evaluate(async () => {
+  const api = await repluggableAppDebug.host.getAPI({
+    name: 'RunEditorLLMCodeToolAPI',
+    public: true,
+    layer: 'DATA_SERVICE',
+  });
+
+  return api.execute({
+    code: `
+      const focused = await editorLLMApis.pages.getFocused();
+      return { focused };
+    `,
+  }, { biParams: {} });
+});
+```
+
+Check the returned action result for errors before taking the next step.
+
+A failed snippet reports `completedCalls` with the ids it created. Those writes persist:
+continue from the failed call reusing those ids, never re-run the whole snippet.
+
+### Bundled scripts
+
+Run from this skill's directory. They import `playwright`, resolved from the working tree.
+
+| Script | Use |
+|---|---|
+| `scripts/launch.sh <editorUrl>` | Start the isolated, headed Chrome on loopback CDP `9333`. |
+| `node scripts/copy/lint-api.mjs --capabilities caps.json [--snippet] <file…>` | Check every `A.<ns>.<method>(` call against the editor's real method list (recorded by `snapshot-capabilities.mjs`) before it is sent. |
+| `node scripts/copy/editor-run.mjs <snippet.js> [--site <metaSiteId>] [--capabilities caps.json]` | Run one editor-API snippet kept in a file; prints `result` or the failure summary. Lints the snippet when `--capabilities` / `HARMONY_CAPABILITIES` is set. Prefer this over inline `-e` code (no quoting bugs, replayable record). |
+| `node scripts/copy/upload-media-manager.mjs <sectionId> <file…>` | Upload local files to the site's Media Manager through the editor's own dialog. |
+| `node scripts/copy/compare-preview.mjs <sourceUrl> <outDir>` | Editor Preview at true canvas width vs the source, plus stacked zoom crops. |
+| `node scripts/copy/preview-widths.mjs <sourceUrl> <outDir> --widths … [--scale-check <sectionId>]` | Preview at exact widths (slider) vs the source, plus a check that every element scales with the width. |
+| `node scripts/copy/build-description.mjs`, `check-description.mjs`, `deploy-description.mjs` | Page description → local compliance/overlap/render check → one-pass deploy with read-back; see [COPY-SITE.md](COPY-SITE.md). |
+| `node scripts/copy/export-page.mjs`, `snapshot-capabilities.mjs`, `import-media.mjs` | Recipes from a copied page, the editor's accepted schemas, public images imported by URL. |
+| `node scripts/copy/mobile-stage.mjs hide\|bg-opacity …` | The two mobile-only changes with no API: Hide, and the background image opacity. |
+| `node scripts/copy/mirror-site.mjs`, `serve-mirror.mjs`, `check-mirror.mjs` | Offline copy of the source site, served locally and pixel-checked against live; see [COPY-SITE.md](COPY-SITE.md) step 0. |
+| `node scripts/copy/measure-source.mjs`, `node scripts/copy/render-plate.mjs` | Site copying; see [COPY-SITE.md](COPY-SITE.md). |
+
+### Editor behaviors learned live
+
+These hold for the Harmony editor API as observed; check the live read when one disagrees.
+
+- **Global header and footer.** `sections.list` returns the page's header/footer as a
+  `RefComponent` (`role: header|footer`); background and layout writes on that id are
+  refused. Target its `masterId` (on `masterPage`) for `setContainerBackground`,
+  `components.add` and `layout.*`.
+- **Text inside the global header/footer** refuses the text-panel actions
+  (`richText.setColor`, `setLink`, `setAlign`, `setFontFamily`: "cannot be selected").
+  Style it with `appearance.setStyles` on the text component (`color`, `textAlign`,
+  `fontFamily`, `fontSize`, `lineHeight`, …). For a link, put an inline
+  `<a href>` in `richText.setText` HTML (it survives), or use a Button with `links.set`.
+- **Header/footer height has two parts.** Each has an internal container
+  (`wixSystemElements.InternalContainer`, child of the master; find it in the stage DOM
+  as `[class*="internalContainerRoot"]` under `#<pageHeaderOrFooterId>`). The background
+  layer and the visible height follow the internal container, not the header/footer box.
+  `layout.setSize` both to the same height; the background may update only after the next
+  `setContainerBackground`. The internal container's grid rows are
+  `[minContent, 1fr]`: a second text block that stacks under the first can be clipped.
+  Merge lines into one rich text with `<br>` instead.
+- **Freeform layout is a grid of rows.** A section places each child in a grid row with
+  margins. `layout.setComposition` resolves all of a container's children as one set and
+  **rejects the whole arrangement if any two boxes overlap or leave the container**,
+  sometimes silently, leaving the auto-placed positions. Even sub-pixel overlaps of
+  touching text boxes count. Send one complete, overlap-free arrangement per container,
+  read `getComposition` back, and fix the inputs. Do **not** correct drift with
+  `layout.move` after a composition: it re-flows the rows and makes it worse.
+- **Content-sized boxes.** Rich text height is `lines × line-height`. A single-line text whose
+  box is exactly as wide as its words can wrap on a sub-pixel font difference and push
+  everything below it down. Give single-line boxes ≥10 px of slack (left-aligned, so the
+  text start does not move). Buttons grow to fit a wrapped label; `setSize` height on a
+  content-sized axis is only a minimum.
+- **Sizes scale with the viewport (spx).** Font sizes, margins and box sizes written in
+  px are stored as `spx` (scaled to the 1280 reference width), so a desktop layout grows
+  and shrinks proportionally between the desktop breakpoints. Anything that stays a real
+  `px` breaks that proportion: a `lineHeight: '42px'` on text, a px line-height inside a
+  button label, a px section height. Write line heights as `em` ratios
+  (`'1.4em'`), write `fontSize` and `lineHeight` in the same `setStyles` call (writing
+  only `lineHeight` can rescale the stored font size), and read both back. Prove it with
+  `preview-widths.mjs --scale-check`: every child must scale by `w2/w1`.
+- **Auto-height sections.** A section added with `sections.add` has `height: auto`, set by its
+  content rows, so it scales with the page. A section that came with the template, or
+  one whose height was set with `layout.setSize`, has a fixed `px` height that does not
+  scale. For a copied page, use a new auto-height section and move the content into it
+  with `components.canReparent` + `components.reparent` (ids and styles are kept).
+- **Desktop vs mobile views.** The mobile view (below 1024 px) shows the same components.
+  Per view through the API, in the mobile view: `layout.setComposition` positions, widths
+  and the section `box.height`. Shared (a write in mobile view changes desktop too):
+  image heights (send none on mobile, the ratio derives them), `layout.setSize`,
+  `appearance.setStyles`, `appearance.setContainerBackground`. Stage-only, per view: Hide
+  and the background image opacity (`scripts/copy/mobile-stage.mjs`).
+- **Classic scrollbars shrink the canvas.** With an always-visible OS scrollbar the stage loses
+  15 px: a desktop section reads 1265 instead of 1280, a mobile one 375 instead of 390, and every
+  composition then lands off (a deploy reports dozens of differences; switching the OS setting
+  between a trackpad and a mouse does this). The copy scripts call `hide-scrollbars.mjs`
+  (`Emulation.setScrollbarsHidden`, which lasts only while their CDP session is attached). If you
+  drive the editor another way, check `layout.getComposition` on a section: width must be 1280/390.
+- **Compositions are anchored, not absolute.** Each child is kept relative to the one above
+  it. When a child ends up shorter or taller than the box sent (a new text that reflows, an
+  image height off its ratio, a Button below its label height), everything after it
+  moves. Send the heights the engine will compute and re-send the set until
+  `getComposition` matches (`deploy-description.mjs` does both).
+- **Rich text.** `setText` keeps inline `<span style="color|font-weight|font-family|font-size">`
+  and `<a href>` as sent (a `px` font size in a span does not scale: use `em`). `links.set`
+  on a rich text rewrites it: the root becomes `<h1>` with an underline span. Keep text
+  links inline. A plain single line goes through `injectText`.
+- **Buttons size to their label.** A set height is a minimum; a tall transparent click area
+  gets its height from the label `lineHeight` in `em`.
+- **Results over ~50 KB are truncated** (`"[Truncated: … chars]"` in place of the value).
+  Read in batches, or compare inside the snippet and return only the differences.
+- **`pages.add` creates an empty placeholder section** (`shouldReuse: true`); a deploy that
+  adds its own section removes it.
+- **Hide is per view, and only from mobile.** Right-click a component or section on the
+  mobile stage → **Hide** hides it on mobile only. Desktop has no Hide (it is the base
+  view), so content can be hidden from mobile but never from desktop. Un-hide in the
+  Layers panel → **Hidden on mobile** → the eye button on the row
+  (`[data-hook="layers-item@DESKTOP--<id>"] button`).
+- **Global header/footer are hard to make responsive.** They are a single row
+  (`[minContent, 1fr]` grid) and their background does not follow the page content.
+  For an exact copy, collapse them (header, footer *and* their internal containers set to
+  1 px, background transparent) and build the nav and footer inside the page's own
+  section, where they scale with everything else.
+- **Media.** `media.uploadFiles` accepts only temporary wixmp chat URLs. Import public web
+  images from a copied page with `scripts/copy/import-media.mjs`, which downloads each one
+  itself (public destinations only) and uploads the bytes through `POST
+  https://www.wixapis.com/site-media/v1/files/generate-upload-url` (site token, header
+  `wix-site-id`); never pass an untrusted page's URL to `files/import`, which makes Wix fetch it.
+  Then read the `uri` with `media.searchSiteFiles`. Upload local files with
+  `scripts/copy/upload-media-manager.mjs`. Image values for `content.set` are
+  `{ uri, name, alt, width, height }`; add `displayMode: 'fit'` to show the whole image.
+- **Fonts.** Only the editor's catalog and the site's *uploaded* fonts render. Importing a
+  `.ttf` through the media API creates a FONT file that is **not** registered. Register
+  fonts through the editor: select any text, open the font dropdown in the text toolbar,
+  click **Upload fonts**, then feed `input[type=file][accept*=".ttf"]` with
+  `setInputFiles`. Afterwards `fonts.resolve('<Name>')` refuses but suggests the uploaded
+  family (`wfont_<x>_<id>,wf_<id25>,orig_<name>`): use that full string as `fontFamily`.
+- **Buttons as text links.** A Button with transparent background, zero borders/padding and
+  a styled `label` element is the reliable linked text in global header/footer. Theme
+  button looks are saved styles: restyle one button locally, then
+  `themeComponents.updateFromComponent({ kind: 'button', styleId: 'button-primary', … })`.
+- **Pinned elements.** `layout.pinToScreen({ position: 'center-bottom', offsetPx })` pins a
+  floating button and moves it to the page (out of the section). A pinned component cannot
+  be resized: set its size first, or unpin, resize and pin again.
+- **Tokens expire.** A CLI site token (`npx @wix/cli@latest token --site <id>`) stops working during
+  a long session (REST calls start returning 403). Re-mint and retry once before
+  diagnosing anything else.
+- **True-width Preview.** The Preview frame defaults to 1280 px whatever the window size.
+  Its width slider (`[data-hook="slider-handle"]`, `aria-valuenow`, range 390 to the
+  window width minus 84) is only rendered while the window is at least ~1300 px wide.
+  Click the slider track near the target, then use the arrow keys for the exact width
+  (`preview-widths.mjs` does this). A free site adds a 44 px "Upgrade" banner above
+  the page. The editor stage is zoomed (`Fit (60–110%)`), so stage screenshots are not a
+  pixel reference.
+- **Watch the published state.** `site.getStatus().isPublished` became `true` during
+  scripted UI work on this site, cause unknown. Read it before and after UI automation,
+  never click by raw coordinates in the top bar (Publish is there), and report a change
+  to the user instead of quietly reverting it.
+
+## Example: make a hero frame responsive
+
+When a hero frame scales in width but its text overflows at wide desktop sizes, find visible title text, inspect its ancestors, and identify the bordered frame container:
+
+```js
+const title = await editorLLMApis.components.find({
+  textContains: 'Hero title',
+  limit: 20,
+});
+
+const inspection = await editorLLMApis.components.inspect({
+  componentId: title.components[0].id,
+  aspects: ['layout', 'styles'],
+  neighbourhood: true,
+});
+```
+
+Read the frame's declared layout and composition. A typical problem is a percentage width paired with fixed pixel height while the text uses `spx` sizing:
+
+```js
+const frameId = 'REPLACE_WITH_FRAME_COMPONENT_ID';
+const layout = await editorLLMApis.layout.get({ componentId: frameId });
+const composition = await editorLLMApis.layout.getComposition({ componentId: frameId });
+const measured = await editorLLMApis.layout.measure({ componentId: frameId });
+return { layout, composition, measured };
+```
+
+For a frame declared as `height: { value: 536, unit: 'px' }`, the responsive repair is normally to preserve the value and use Wix scaled pixels. After authorization:
+
+```js
+const updated = await editorLLMApis.layout.setSize({
+  componentId: frameId,
+  height: 536, // plain pixels: the component keeps its own unit (spx stays spx) and the value is recomputed
+});
+
+const verifiedLayout = await editorLLMApis.layout.get({ componentId: frameId });
+const status = await editorLLMApis.site.getStatus();
+return { updated, verifiedLayout, status };
+```
+
+Verify that the stored height is `{ type: 'spx', value: 536 }`, that the editor reports a successful save state, and that the site remains unpublished unless publication was explicitly requested.

package/skills/wix-harmony-editor/scripts/copy/build-description.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// Turn a source measurement (measure-source.mjs) into a PAGE DESCRIPTION: one JSON file that
+// lists every Harmony component the copied page needs — type, content, styles, link, desktop
+// box and mobile placement — so the page can be checked locally and deployed in one pass.
+//
+//   node scripts/copy/build-description.mjs <source.json> <out.desc.json>
+//        --fonts font-ledger.json            source family -> Harmony family (wfont_… or catalog)
+//        [--recipes export.json ...]         exported Harmony components (export-page.js) whose
+//                                            styles/links are reused for the same text or image
+//        [--source-origin https://site] [--local-origin http://127.0.0.1:8732]
+//        [--pages '{"https://site/":"<homePageId>"}'] source URL -> Harmony pageId (PageLink); "self" = this page (needs --page-id <id>)
+//        [--layout '{"navMaxY":60,…}']        thresholds for the mobile grouping (defaults below)
+//        [--name "<Page name>"] [--decorative <img-src-substring>,…]  (kept in the plate, no component)
+//
+// Deterministic: the same inputs give the same file. Anything it cannot decide is listed in
+// `review` for the agent (or a person) instead of guessed.
+import fs from 'fs';
+import { openItems, pendingItems } from './desc-hash.mjs';
+import { normU, stripTracking } from './link-url.mjs';
+
+const args = process.argv.slice(2);
+const opt = (n, d) => { const i = args.indexOf(`--${n}`); return i >= 0 ? args[i + 1] : d; };
+const optAll = (n) => args.flatMap((a, i) => (a === `--${n}` ? [args[i + 1]] : []));
+const [srcFile, outFile] = args.filter((a, i) => !a.startsWith('--') && !(i > 0 && args[i - 1].startsWith('--')));
+if (!srcFile || !outFile || !opt('fonts')) { console.error('usage: build-description.mjs <source.json> <out.desc.json> --fonts font-ledger.json [--recipes export.json ...]'); process.exit(2); }
+const src = JSON.parse(fs.readFileSync(srcFile, 'utf8'));
+const fontLedger = JSON.parse(fs.readFileSync(opt('fonts'), 'utf8')).families || {};
+const recipes = optAll('recipes').flatMap((f) => { const d = JSON.parse(fs.readFileSync(f, 'utf8')); return d.components || [d]; });
+const sourceOrigin = opt('source-origin', null), localOrigin = opt('local-origin', null);
+const pageMap = JSON.parse(opt('pages', '{}'));
+// --linkmap links.json: { "<source URL>": { link: <Harmony link>, inline?: "<absolute URL for links inside text>" } }.
+// Every link the source has is looked up here first. Rich text cannot hold a PageLink, so a link inside text uses
+// `inline` (an absolute URL on the new site). `unbuilt: "<why>"` marks a page the new site does not have yet: its link points at an
+// existing page for now, and the page stays in desc.pendingItems (the cutover hand-off) until the entry drops `unbuilt`.
+// Lookup keys are normalised by link-url.mjs (case of the path and query values is kept, tracking parameters are removed).
+// Build it from the migrated data: a store category or product link
+// MUST land on the new store's category / product page, never on the source site (see COPY-SITE.md "Links").
+const rawLinkmap = opt('linkmap') ? JSON.parse(fs.readFileSync(opt('linkmap'), 'utf8')) : {};
+const linkmap = Object.fromEntries(Object.entries(rawLinkmap).map(([u, v]) => [normU(u), v]));
+const mapped = (u) => linkmap[normU(u)] || null;
+
+// "self" in --pages means this very page: it needs --page-id, never becomes the literal id "self"
+for (const [u, v] of Object.entries(pageMap)) if (v === 'self') {
+  if (!opt('page-id')) { console.error(`--pages maps ${u} to "self": pass --page-id <this page's Harmony pageId>`); process.exit(2); }
+  pageMap[u] = opt('page-id');
+}
+const decorative = (opt('decorative', '') || '').split(',').filter(Boolean);
+const review = [];
+// Mobile grouping thresholds (desktop px at the measured width). The defaults come from a fixed-width,
+// centred 1280 layout with a top nav, a header band, a main column and a right-hand sidebar; another
+// theme needs its own numbers: pass --layout and read the `review` item that says defaults were used.
+const L = { navMaxY: 60, mainLeftMin: 200, mainLeftMax: 400, mainTopMin: 300, sideMinX: 860, footHeight: 160, ...JSON.parse(opt('layout', '{}')) };
+
+// ---- helpers ------------------------------------------------------------------------------
+const toSource = (u) => (u && localOrigin && sourceOrigin ? u.split(localOrigin).join(sourceOrigin) : u);
+const plain = (h) => (h || '').replace(/<br\s*\/?>/g, ' ').replace(/<[^>]+>/g, '').replace(/&nbsp;|&#160;/g, ' ').replace(/&amp;/g, '&').replace(/&#8217;|’/g, "'").replace(/\s+/g, ' ').trim().toLowerCase();
+const hex = (c) => { if (/^#[0-9a-f]{6}$/i.test(String(c).trim())) return String(c).trim().toUpperCase(); const m = String(c).match(/\d+(\.\d+)?/g); if (!m) return c; const [r, g, b, a] = m.map(Number); const h = '#' + [r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('').toUpperCase(); return a !== undefined && a < 1 ? `rgba(${r},${g},${b},${a})` : h; };
+const px = (v) => parseFloat(v);
+const fontFor = (family) => {
+  const first = String(family).split(',')[0].replace(/["']/g, '').trim();
+  const hit = Object.entries(fontLedger).find(([k]) => k.toLowerCase() === first.toLowerCase());
+  if (hit) return hit[1];
+  const generic = { courier: 'courier new', 'courier new': 'courier new', arial: 'arial', helvetica: 'helvetica-w01-roman', georgia: 'georgia', 'times new roman': 'times new roman' };
+  if (generic[first.toLowerCase()]) return generic[first.toLowerCase()];
+  review.push({ font: first, why: 'no Harmony family for this source font: upload it (Upload fonts dialog) and add it to the font ledger' });
+  return first.toLowerCase();
+};
+const linkFor = (href) => {
+  if (!href) return null;
+  let u = toSource(href);
+  const lm = mapped(u); if (lm?.link) return { ...lm.link, ...(lm.unbuilt ? { unbuilt: { url: stripTracking(u), reason: lm.unbuilt } } : {}) };
+  u = stripTracking(u); // tracking parameters change per visit
+  const pid = pageMap[u] ?? pageMap[u.replace(/\/$/, '')] ?? pageMap[u + '/'];
+  if (pid) return { type: 'PageLink', pageId: pid, target: '_self' };
+  if (u.startsWith('mailto:')) return { type: 'EmailLink', recipient: u.slice(7).split('?')[0] };
+  if (u.startsWith('tel:')) return { type: 'PhoneLink', phoneNumber: u.slice(4) };
+  const sameSite = sourceOrigin && u.startsWith(sourceOrigin);
+  return { type: 'ExternalLink', url: u, target: sameSite ? '_self' : '_blank', ...(sameSite ? { sourcePage: true } : {}) };
+};
+const align = (a) => ({ left: 'start', start: 'start', right: 'end', end: 'end', center: 'center', justify: 'justify' }[a] || 'start');
+// a recipe is reused when the same words (text) or the same file (image) exist on an exported page
+const recipeText = (txt, size, color) => {
+  // same words AND the same look: the recipe's font size within 1px and the same colour
+  const look = (r) => { const st = Object.assign({}, ...(r.styles || []).map((e) => e.props)); return { size: px(st.fontSize), color: hex(st.color) }; };
+  const cands = recipes.filter((r) => (r.html ? plain(r.html) : r.content?.label ? plain(r.content.label) : null) === txt)
+    .filter((r) => { const l = look(r); return Math.abs(l.size - size) <= 1 && l.color === hex(color); });
+  return cands[0] || null;
+};
+const recipeImage = (srcUrl) => { const f = srcUrl.split('/').pop().split('?')[0]; return recipes.find((r) => r.type === 'wixEditorElements.Image' && (r.content?.image?.name || '').endsWith(f)) || null; };
+const KEEP = { // the style keys a copy writes; everything else stays the component's default
+  'wixEditorElements.WRichText': { root: ['color', 'textAlign', 'fontFamily', 'fontSize', 'fontStyle', 'fontWeight', 'lineHeight', 'letterSpacing'] },
+  'wixEditorElements.Button': { root: ['background', 'backgroundColor', 'backgroundImage', 'boxShadow', 'paddingTop', 'paddingBottom', 'paddingInlineStart', 'paddingInlineEnd', 'borderTopWidth', 'borderBottomWidth', 'borderInlineStartWidth', 'borderInlineEndWidth', 'borderStartStartRadius', 'borderStartEndRadius', 'borderEndStartRadius', 'borderEndEndRadius'], label: ['color', 'textAlign', 'fontFamily', 'fontSize', 'fontWeight', 'fontStyle', 'lineHeight', 'letterSpacing', 'textDecorationLine'] },
+  'wixEditorElements.Image': { root: ['opacity'] },
+};
+const recipeStyles = (r) => {
+  const keep = KEEP[r.type] || {}; const out = {};
+  for (const e of r.styles || []) { const k = e.path.join('/') || 'root'; if (!keep[k]) continue; const props = Object.fromEntries(Object.entries(e.props).filter(([p, v]) => keep[k].includes(p) && !String(v).startsWith('var('))); if (Object.keys(props).length) out[k] = props; }
+  return out;
+};
+const textStyles = (t) => {
+  const size = px(t.size); const pitch = t.linePitch || px(t.lineHeight) || size * 1.2;
+  const ls = t.letterSpacing === 'normal' ? 'normal' : `${Math.round((px(t.letterSpacing) / size) * 1000) / 1000}em`;
+  return { root: { fontFamily: fontFor(t.font), fontSize: `${size}px`, lineHeight: `${Math.round((pitch / size) * 10000) / 10000}em`, fontWeight: String(t.weight), fontStyle: t.style, color: hex(t.color), textAlign: align(t.align), letterSpacing: ls } };
+};
+// single-line left-aligned text gets its painted width plus slack, so it never wraps early;
+// multi-line text keeps the source block (or float run) width so it wraps where the source wraps
+const textBox = (t, seg) => {
+  const pitch = t.linePitch || px(t.lineHeight) || px(t.size) * 1.2;
+  const b = seg ? seg.box : t.block; const lines = seg ? seg.lines : t.lines || 1;
+  const y = Math.round(seg ? seg.lineTop : t.lineTop);
+  if (lines <= 1 && !seg) { // one line: its painted width plus slack, anchored the way it is aligned
+    const g = t.glyphBox || t.textBox; // the words, not an inline icon beside them
+    const w = Math.min(b.w, g.w + 12), a = align(t.align);
+    const x = a === 'center' ? Math.round(g.x + g.w / 2 - w / 2) : a === 'end' ? g.x + g.w + 6 - w : g.x;
+    return { x: Math.max(b.x, Math.min(x, b.x + b.w - w)), y, width: w, height: Math.round(pitch) };
+  }
+  return { x: b.x, y, width: b.w, height: Math.round(lines * pitch) };
+};
+
+// a click area that paints nothing
+const TRANSPARENT = { root: { backgroundColor: 'rgba(0,0,0,0)', background: 'rgba(0,0,0,0)', boxShadow: 'none', borderTopWidth: '0px', borderBottomWidth: '0px', borderInlineStartWidth: '0px', borderInlineEndWidth: '0px', paddingTop: '0px', paddingBottom: '0px', paddingInlineStart: '0px', paddingInlineEnd: '0px' }, label: { color: 'rgba(0,0,0,0)' } };
+
+// ---- components ---------------------------------------------------------------------------
+const comps = []; let n = 0;
+const key = (kind, label) => `${kind}-${String(++n).padStart(2, '0')}-${plain(label).replace(/[^a-z0-9]+/g, '-').slice(0, 24).replace(/-$/, '')}`;
+
+for (const f of src.fixed) {
+  const r = recipes.find((x) => x.pin && plain(x.content?.label) === plain(f.text));
+  if (!r) { review.push({ fixed: f.text, why: 'floating element without a recipe: build a pinned Button from fixed[] by hand once, export it, and pass it as --recipes' }); continue; }
+  comps.push({ key: key('pinned', f.text), kind: 'pinned', type: r.type, label: r.content.label, link: linkFor(f.href), styles: recipeStyles(r), pin: { position: r.pin.position, offsetPx: { horizontal: r.pin.offsetPx.horizontal, vertical: f.bottomOffset } }, desktop: { x: f.box.x, y: f.box.y, width: f.box.w, height: f.box.h }, from: `recipe:${r.label}`, recipeId: r.id });
+}
+
+for (const t of src.texts) {
+  if (src.fixed.some((f) => plain(f.text) === plain(t.text))) continue; // the floating element's own words
+  if (t.hiddenText) {
+    if (!t.links.length) continue;
+    const r = recipes.find((x) => x.type === 'wixEditorElements.Button' && /hotspot/.test(x.label));
+    comps.push({ key: key('hotspot', t.text), kind: 'hotspot', type: 'wixEditorElements.Button', label: t.text.trim(), link: linkFor(t.links[0]), styles: r ? recipeStyles(r) : TRANSPARENT, desktop: { x: t.block.x, y: t.block.y, width: t.block.w, height: t.block.h }, from: r ? `recipe:${r.label}` : 'measured', recipeId: r ? r.id : null, note: 'click area over artwork in the plate (image-replacement link on the source)' });
+    continue;
+  }
+  if (t.occluded) { review.push({ text: t.text.slice(0, 40), why: 'covered by another element on the source: not copied' }); continue; }
+  const parts = t.segments || [null];
+  for (const seg of parts) {
+    let rich = toSource(seg ? seg.rich : t.rich);
+    if (!plain(rich)) continue;
+    const r = !seg && recipeText(plain(rich), px(t.size), t.color);
+    if (r && r.type === 'wixEditorElements.Button') { // the exported page used a Button for this text (nav links)
+      comps.push({ key: key('button', t.text), kind: 'button', type: r.type, label: r.content.label, link: linkFor((t.links[0] || null)), styles: recipeStyles(r), desktop: { x: t.block.x, y: t.block.y, width: t.block.w, height: t.block.h }, from: `recipe:${r.label}`, recipeId: r.id });
+      continue;
+    }
+    // links in text stay INLINE <a href>: links.set on a rich text rewrites it (root becomes <h1>,
+    // an underline span is added). A text that must reach a Harmony page is listed for review.
+    const link = null;
+    // a text that is itself inside a link (nav item, "show all") has no <a> in its own markup: wrap it, or the link is lost
+    if (t.links?.length && !/<a href=/.test(rich) && !seg) rich = `<a href="${toSource(t.links[0])}">${rich}</a>`;
+    const unbuiltInline = [];
+    rich = rich.replace(/<a href="([^"]+)"/g, (all, h) => { const lm = mapped(h); const to = lm?.inline || (lm?.link?.type === 'ExternalLink' ? lm.link.url : null); if (lm?.unbuilt) unbuiltInline.push({ url: stripTracking(toSource(h)), reason: lm.unbuilt, standIn: to || 'unchanged (still the source URL)' }); return to ? `<a href="${to.replace(/&/g, '&amp;')}"` : all; });
+    for (const m of rich.matchAll(/<a href="([^"]+)"/g)) { const l = linkFor(m[1]); if (l?.type === 'PageLink') review.push({ text: plain(rich).slice(0, 40), why: `inline link to a Harmony page (${l.pageId}): rich text keeps the source URL; use a Button if it must be a page link` }); }
+    const tag = /^h[1-6]$/i.test(t.tag || '') ? t.tag.toLowerCase() : 'p';
+    const tk = key('text', seg ? seg.rich : t.text);
+    comps.push({ key: tk, kind: 'text', type: 'wixEditorElements.WRichText', html: `<${tag}>${rich}</${tag}>`, link, ...(unbuiltInline.length ? { unbuiltInline } : {}), styles: r ? recipeStyles(r) : textStyles(t), desktop: textBox(t, seg), lines: seg ? seg.lines : t.lines, from: r ? `recipe:${r.label}` : 'measured', recipeId: r ? r.id : null, ...(seg ? { note: `run ${parts.indexOf(seg) + 1}/${parts.length} of a paragraph that wraps around a float`, ...(parts.indexOf(seg) > 0 ? { continues: true } : {}) } : {}) });
+  }
+}
+
+for (const im of src.images) {
+  if (decorative.some((d) => im.src.includes(d))) continue;
+  const r = recipeImage(im.src);
+  comps.push({ key: key('image', im.src.split('/').pop()), kind: 'image', type: 'wixEditorElements.Image', image: r ? { uri: r.content.image.uri, name: r.content.image.name, width: r.content.image.width, height: r.content.image.height, alt: im.alt || r.content.image.alt || '' } : { source: toSource(im.src).replace(/-\d+x\d+(\.\w+)$/, '$1'), sourceRendered: toSource(im.src), name: im.src.split('/').pop(), alt: im.alt || '', width: im.box.w, height: im.box.h }, displayMode: 'fitWidth', link: linkFor(im.href), desktop: { x: im.box.x, y: im.box.y, width: im.box.w, height: im.box.h }, from: r ? `recipe:${r.label}` : 'measured', recipeId: r ? r.id : null });
+}
+
+// ---- elements Harmony supplies itself (--native native.json) -------------------------------------
+// [{ "key": "cart", "type": "checkout_Orders.CartIcon_legacy", "desktop": { x, y, width, height }, "styles": {...} }]
+// A cart icon or login a store needs: added with the page in the same deploy, never by hand afterwards (every
+// add or remove after the deploy lets the editor squeeze the page's blank bands and shifts the whole layout).
+for (const nv of opt('native') ? JSON.parse(fs.readFileSync(opt('native'), 'utf8')) : []) comps.push({ key: `native-${nv.key}`, kind: 'native', type: nv.type, label: nv.key, link: null, styles: nv.styles || {}, desktop: nv.desktop, from: 'native', recipeId: null });
+
+// ---- every source link is a link in the copy ------------------------------------------------
+// Text and image links are set above. Any other visible link (icons painted in the plate, the logo, a tile, a
+// social icon) becomes a transparent click area over its box, so no link is dropped.
+const overlap = (a, b) => { const w = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x), h = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y); return w > 0 && h > 0 ? (w * h) / (b.width * b.height) : 0; }; // share of b (the source link's box) that a covers
+const sameLink = (a, b) => a && b && a.type === b.type && (a.url || a.pageId || a.phoneNumber || a.recipient) === (b.url || b.pageId || b.phoneNumber || b.recipient) && (a.innerRoute || '') === (b.innerRoute || '');
+const seen = new Set();
+for (const a of src.anchors || []) {
+  const href = toSource(a.href); const bx = { x: a.box.x, y: a.box.y, width: a.box.w, height: a.box.h };
+  if (bx.x < 0 || bx.x + bx.width > src.width + 1 || /^javascript:/i.test(href) || /demandware\.store|\/on\/demandware/.test(href)) continue; // off the page (carousel clones) or an app action, not a page link
+  if ((src.fixed || []).some((f) => overlap({ x: f.box.x, y: f.box.y, width: f.box.w, height: f.box.h }, bx) >= 0.5)) continue; // a floating element (chat pill...): pinned by hand/recipe, listed in review, never a click area over the page
+  const dupe = `${normU(href)}@${bx.x},${bx.y}`; if (seen.has(dupe)) continue; seen.add(dupe);
+  const want = linkFor(href); if (!want) continue;
+  const inl = mapped(href); const inlineUrl = inl?.inline || inl?.link?.url || href;
+  const covered = comps.some((c) => overlap(c.desktop, bx) >= 0.5 && (c.kind === 'native' || sameLink(c.link, want) || (c.kind === 'text' && (c.html.includes(`href="${inlineUrl.replace(/&/g, '&amp;')}"`) || c.html.includes(`href="${href}"`)))));
+  if (covered) continue;
+  comps.push({ key: key('hotspot', a.text || href), kind: 'hotspot', type: 'wixEditorElements.Button', label: (a.text || 'link').slice(0, 40), link: want, styles: TRANSPARENT, desktop: bx, from: 'measured', recipeId: null, note: 'click area over a source link that is not text or an image' });
+}
+
+for (const u of src.unsupported || []) review.push({ unsupported: `${u.tag}${u.src ? ' ' + u.src : ''} at x${u.box.x} y${u.box.y} ${u.box.w}x${u.box.h}`, why: 'not rebuilt by this method (only text, images, buttons and the plate): decide by hand, e.g. a Harmony app/element, a link, or leave it out and tell the customer' });
+if (!opt('layout')) review.push({ layout: 'default mobile grouping thresholds', why: 'tuned for a fixed-width 1280 layout with nav, header band, main column and right sidebar: check the mobile render, or pass --layout' });
+// ---- mobile: one readable column in reading order, reusing an exported page's mobile boxes --
+const W = 390, M = 24, CW = W - 2 * M;
+const recipeOf = (c) => (c.recipeId ? recipes.find((r) => r.id === c.recipeId) : null);
+const top = Math.min(...src.texts.filter((t) => /^(start|left)$/.test(t.align) && t.block.x > L.mainLeftMin && t.block.x < L.mainLeftMax && t.block.y > L.mainTopMin).map((t) => t.block.y), 1e9); // first main-column line
+const group = (c) => {
+  const d = c.desktop;
+  if (c.kind === 'pinned') return 'pinned';
+  if (d.y < L.navMaxY) return 'nav';
+  if (d.y + d.height <= top) return 'head';
+  if (d.x >= L.sideMinX) return 'side';
+  if (d.y > src.page.height - L.footHeight) return 'foot';
+  return 'main';
+};
+for (const c of comps) {
+  c.mobile = { group: group(c) };
+  const r = recipeOf(c);
+  if (c.mobile.group === 'pinned') continue;
+  if (c.kind === 'hotspot') { c.mobile.hidden = true; continue; }
+  if (c.kind === 'native') { c.mobile.width = c.desktop.width; c.mobile.x = W - M - c.desktop.width; continue; } // keeps its own size: it is not a full-width block
+  if (r && r.mobile && ['nav', 'head'].includes(c.mobile.group)) { c.mobile.box = r.mobile; continue; } // the same chrome as the exported page
+  if (r?.mobile && c.mobile.group === 'side') { c.mobile.x = r.mobile.x; c.mobile.width = r.mobile.width; continue; } // same arrangement as the exported page
+  const w = c.kind === 'image' ? Math.min(c.desktop.width, CW) : CW;
+  c.mobile.width = w;
+  c.mobile.x = c.kind === 'image' ? Math.round((W - w) / 2) : M;
+}
+const ordered = ['nav', 'head', 'main', 'side', 'foot'];
+comps.forEach((c) => { c.mobile.order = ordered.indexOf(c.mobile.group) * 100000 + Math.round(c.desktop.y / 10) * 10 + c.desktop.x / 10000; }); // rows within 10 px read left to right
+// icons that sit side by side on desktop stay in one row on mobile
+for (const c of comps) { const row = comps.filter((o) => o !== c && o.mobile.group === c.mobile.group && o.kind === 'image' && c.kind === 'image' && Math.abs(o.desktop.y - c.desktop.y) < 8); if (row.length && [c, ...row].reduce((n, o) => n + o.mobile.width, 0) + 12 * row.length <= CW) c.mobile.row = Math.min(...[c, ...row].map((o) => Math.round(o.desktop.y))); } // only when the row really fits the mobile width: large cards stack
+
+// a row that stays a row on mobile: spread its images evenly across the content width, in desktop order
+const rows = new Map(); for (const c of comps) if (c.mobile.row != null) rows.set(`${c.mobile.group}:${c.mobile.row}`, [...(rows.get(`${c.mobile.group}:${c.mobile.row}`) || []), c]);
+for (const items of rows.values()) { items.sort((a, b) => a.desktop.x - b.desktop.x); const sum = items.reduce((n, o) => n + o.mobile.width, 0); const gap = items.length > 1 ? (CW - sum) / (items.length - 1) : 0; let x = M; for (const o of items) { o.mobile.x = Math.round(x); x += o.mobile.width + gap; } }
+
+// the page colour: an exported page's section colour when given, else the body's
+const exportedSection = optAll('recipes').map((f) => JSON.parse(fs.readFileSync(f, 'utf8')).section).find(Boolean);
+const sectionColor = exportedSection?.background?.find((f) => f.key === 'backgroundColor')?.value?.raw || hex((src.backgrounds.find((b) => b.tag === 'BODY') || {}).color || '#FFFFFF');
+// mobile band colours are sampled from the plate by check-description
+const out = {
+  schema: 'harmony-page-description/1',
+  generatedAt: new Date().toISOString(),
+  source: { url: toSource(src.url), measured: src.url, width: src.width, height: src.page.height, centered: src.page.centered },
+  page: { name: opt('name', null) },
+  layout: L,
+  section: { desktop: { width: src.width, height: src.page.height }, background: { plate: null, fittingType: 'fill', backgroundColor: sectionColor }, mobile: { width: W, margin: M, gap: 12, groupGap: 28, bands: {} } },
+  components: comps,
+  openItems: openItems({ components: comps, source: { url: toSource(src.url) } }), // links still pointing at the source site: the cutover hand-off
+  pendingItems: pendingItems({ components: comps }), // pages the copy still lacks (their links point at a stand-in page): the cutover hand-off
+  review,
+};
+fs.writeFileSync(outFile, JSON.stringify(out, null, 1));
+const count = (k) => comps.filter((c) => c.kind === k).length;
+console.log(JSON.stringify({ out: outFile, components: comps.length, text: count('text'), image: count('image'), button: count('button'), hotspot: count('hotspot'), pinned: count('pinned'), fromRecipes: comps.filter((c) => c.from.startsWith('recipe')).length, newMedia: comps.filter((c) => c.image && !c.image.uri).map((c) => c.image.name), review }));