@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-harmony-editor/COPY-SITE.md

@@ -1,494 +0,0 @@
-# Copy an existing site page into Harmony, exactly
-
-Use this when the task is to reproduce a live source page (WordPress, Shopify, anything
-public) in a Harmony site. Connecting to the editor and the general editor behaviors are in
-[SKILL.md](SKILL.md); read that first.
-
-## Order: create the site, then the data, then the front end
-
-A copy is never started from the editor. The order is fixed:
-
-1. **Create the Harmony site** (blank template, unpublished). Nothing else is done to it yet.
-2. **Bring the data first** when the source is a store, bookings, events, blog, or any other
-   business that Wix serves from an app (products, categories, services, posts, members and the
-   like). Collect the public data, and the private data where the run has access, or both.
-   What the data turns out to contain tells you which Wix app to install on the site (for
-   example Stores for products and categories), and the data migration (the `wix-replatform`
-   flow) then fills that app. A page's product tiles, category links and carousels need real
-   catalog items to point at.
-3. **Only then copy the front end** in the editor, linking to the migrated items.
-
-Starting the front end before the data is allowed only when the user asks for it and
-approves it. State the consequence when asking: product and category links, and any
-catalog-driven block (best sellers, category tiles, gift guides), keep pointing at the source
-site until the data exists, and they are `openItems` for cutover.
-
-A source with no app data (a brochure site: text, images, contact details) goes straight from
-step 1 to step 3.
-
-## The goal is a copy, not a redesign
-
-"Copy the site" means a visitor cannot tell the Harmony page from the source: the same
-artwork, fonts, sizes, colours, positions, text and links, **at every screen size the
-source supports**. It does **not** mean "inspired by" or "modernized".
-
-For every area, a Wix component that does the same job (collection, signup form, video, cart, social bar...) is used instead of a static picture of it: see item 16.
-
-A freeform rebuild with Harmony's stock components, theme fonts and eyeballed spacing was
-tried and rejected ("doesn't look the same at all"). A copy that was exact at 1280 px but
-broke at 1836 px and looked bad on mobile was also rejected. Do not stop at one width.
-
-**Done** means all of the following:
-- `preview-widths.mjs` shows the Harmony Preview matching the source at 1920, 1836, 1440,
-  1280 and 1024 (no element off by more than ~2 px at 1280, proportional elsewhere), and
-  its `--scale-check` lists **no** deviations;
-- the mobile view (390 px) and tablet widths (768, 1000) show every source text, image
-  and link in a readable single column with the source's artwork, no overlaps and nothing
-  cut off;
-- every link target matches the source (see "Links");
-- every remaining difference is listed for the user with its reason;
-- the draft is saved. Publishing is the user's decision.
-
-## Method: local copy → description → local check → one deploy → stage steps → verify
-
-The decorative layer is copied as rendered pixels (the plate). Everything a visitor reads or
-clicks is a live Harmony component at the measured coordinates. All of it is first written
-down in ONE local file, the **page description**, and checked locally; the editor is touched
-only by a deterministic deploy. Each problem that used to cost an editor round (overlap
-rejection, px values, early wraps, wrong heights) is caught before deploying.
-
-0. **Make a local copy of the whole source site, and prove it.**
-   ```
-   node scripts/copy/mirror-site.mjs <work>/mirror <url> [<url> ...]   # every page and post URL
-   node scripts/copy/serve-mirror.mjs <work>/mirror --port 8732 &
-   node scripts/copy/check-mirror.mjs <work>/mirror <work>/mirror-check
-   ```
-   - Get the URL list from the source's public API (WordPress:
-     `?rest_route=/wp/v2/pages&per_page=100&_fields=id,link,title`, same for `posts`).
-   - `mirror-site` records every response at 390/1024/1280/1920 (responsive images differ
-     per width). Third-party iframes (Google Maps) cannot replay offline, so each is saved as
-     a snapshot image and served in its place.
-   - `check-mirror` screenshots live and local (local browser cut off from the internet)
-     and diffs the pixels. Done when every page is ≤0.1% different with no local 404s and
-     no blocked request other than analytics. A run of all zeros is normal for a static
-     site; the diff was negative-controlled on two different pages (41%).
-   - From here on, measure, plate and compare against `http://127.0.0.1:8732/…` instead of
-     the live site: faster, repeatable, and unaffected by source changes.
-1. **Find the interactions, then measure the source** (the local copy). First `find-interactions.mjs` (item 17): a hidden tab, accordion or toggle pane is part of the page.
-   `node scripts/copy/measure-source.mjs http://127.0.0.1:8732/<page> <work>/source.json --width 1280`
-   Besides boxes, fonts and colours it records per text block: `rich` (Harmony-ready HTML,
-   inline runs as `<span style>` relative to the block's dominant style, sizes in `em`),
-   `segments` (a paragraph that wraps around a float, split into runs that share a line
-   width; floats only count in the same block formatting context and after their DOM
-   position), `glyphBox` (the words only, without inline icons), `linePitch`, `occluded` and
-   `hiddenText` (image-replacement links: a click area over artwork).
-2. **Fonts first.** List every family in `texts[].font`. Upload missing ones through the
-   editor's **Upload fonts** dialog (SKILL.md → Fonts) and record the `wfont_…` families in a
-   font ledger `{ families: { "<Source name>": "<Harmony family>" } }`. Google Fonts files:
-   `https://raw.githubusercontent.com/google/fonts/main/<ofl|apache>/<name>/…` (check the
-   licence). Generic families map to catalog fonts (`courier` → `courier new`).
-3. **Recipes and capabilities (once per site).**
-   - `node scripts/copy/export-page.mjs <pageId> <sectionId> <work>/recipes.json` exports an
-     already-copied page (styles, content, links, desktop and mobile boxes, pinned items).
-     The next page reuses those looks for the same words and images (nav, tabs, notes,
-     footer), matched by text AND font size AND colour.
-   - `node scripts/copy/snapshot-capabilities.mjs <draftSectionId> <work>/capabilities.json`
-     records what the editor accepts per component type. `changedSinceLastSnapshot: true`
-     means the editor changed: re-check before deploying.
-4. **Build the description:**
-   `node scripts/copy/build-description.mjs <work>/source.json <work>/page.desc.json --fonts <ledger> --recipes <work>/recipes.json --source-origin https://<site> --local-origin http://127.0.0.1:8732 --pages '{"https://<site>/":"<homePageId>","https://<site>/<this page>":"<pageId>"}' --name "<Page>" --decorative <img substrings kept in the plate>`
-   Deterministic. Read its `review` list: anything it could not decide is there, never guessed.
-5. **Prepare media in parallel** (nothing here waits on anything else):
-   - `node scripts/copy/import-media.mjs <projectDir> <work>/page.desc.json` imports the
-     public images by URL (REST, mint the token first) and writes their uris back.
-   - `render-plate.mjs <local url> <work>/plate --cuts full:0:<page.height> --width 1920 --scale 2 --keep …`
-     then `upload-media-manager.mjs <anySectionId> <plate>`; put its uri in
-     `section.background.plate`.
-6. **Check locally until clean:**
-   `node scripts/copy/check-description.mjs <work>/page.desc.json <work>/check --capabilities … --fonts … --source <local url> --plate <plate.png> --write`
-   It validates every type, style key, link type and value against the snapshot; renders the
-   description with the source's own fonts; settles 1–3 px touches and click areas; fails on
-   any remaining desktop overlap; diffs the render against the source (expect ~5%: font
-   anti-aliasing); stacks the mobile column with measured heights and derives the mobile
-   background bands from the plate colour behind each component. Look at
-   `check/render-1280.png` and `check/render-390.png`.
-7. **Deploy:** `node scripts/copy/deploy-description.mjs <work>/page.desc.json --page <pageId> --clean`
-   (`pages.add({ name, addToMenu: false })` creates the page.) About 9 editor calls: setup,
-   create in chunks of 10, desktop composition (re-sent until every box lands), pins, mobile
-   composition re-stacked from the heights Harmony really gave each text, and an in-editor
-   read-back that must report `problemCount: 0`. State is kept in `<desc>.deploy.json`:
-   after a fix, re-run without `--clean` (it re-places), or with `--reapply` (it re-sends
-   content, styles and links too). A full page took ~35–50 s.
-8. **Stage steps (no API):**
-   `node scripts/copy/mobile-stage.mjs hide <id…>` for click areas and anything else that must
-   not show on mobile, and `node scripts/copy/mobile-stage.mjs bg-opacity <sectionId> 0` so the
-   desktop plate does not show on a phone (the band gradient shows instead).
-9. **Verify:** `node scripts/copy/preview-widths.mjs http://127.0.0.1:8732/<page> <work>/w --widths 1280,1920,1836,1440,1024,768,390 --scale-check <sectionId>`.
-   `scaleDeviations` must be empty. Compare `h-1280.png` with the source at a 46 px offset
-   (the free-site banner), masking the floating button. Look at 768 and 390.
-10. **Links: every source link is a link in the copy, and none may point back at the source.**
-    `measure-source` records every visible link (`anchors`). `build-description` sets text and image links,
-    wraps a text that sits inside a link (nav items, "show all") in an inline `<a>`, and turns every other link
-    (icons painted in the plate, the logo, social icons, tiles) into a transparent click area over its box.
-    Floating elements (a chat pill) are pinned by recipe, never click areas.
-    **A link to a store category, a product, or any page the copy replaces MUST go to the new site's own page.**
-    Pass `--linkmap links.json`: `{ "<source URL>": { "link": <Harmony link>, "inline": "<absolute URL for text links>" } }`,
-    built from the migrated data (the data step's crosswalk and the Stores category/product slugs):
-    - category: `{ type: 'PageLink', pageId: <the Stores "Category Page" (pages.list marks it isDynamicPage)>, innerRoute: <category slug> }`.
-      `innerRoute` is the slug only: the editor prefixes `/category/` itself (`category/<slug>` gave `/category/category/<slug>`).
-    - product: the editor rejects `PageLink` + `innerRoute` for the Stores product page ("Router not found for this page"),
-      so use `{ type: 'ExternalLink', url: '<site>/product-page/<product slug>', target: '_self' }`.
-    - a link inside rich text cannot be a PageLink: its `inline` is the absolute URL (`<site>/category/<slug>`).
-    - a page that is not built (about, policies, contact, account): point it at a page that exists (Home, the cart or account page)
-      and mark the entry `"unbuilt": "<why>"`; never leave the source URL. The builder writes every such page to
-      `desc.pendingItems` (source URL, the stand-in it points at, the components, responsible role, next action, what resolves
-      it): the durable cutover hand-off. A redirect to Home never resolves it; only mapping the source URL to a real page (the
-      entry without `unbuilt`) does. `check-description` fails when `pendingItems` is stale and lists each pending page as a
-      warning; the deploy report carries them.
-    - lookup keys keep the case of the path and query values (`/Product/A` and `/product/a` are different pages) and ignore
-      per-visit tracking parameters (`utm_*`, `fbclid`, `gclid`, `_ga`, `mc_*`, `visitorId`) and the fragment.
-    `check-description` FAILS while any link still points at the source (`--allow-old-links "<reason>"` only for pages
-    deliberately not built yet). After publishing, read every `<a href>` back from the live page, request each category and
-    product URL, and confirm status 200, the right title, and products listed. A visitor reaching the old site is a critical bug.
-    Slugs can be non-Latin or emoji: the live URL is percent-encoded, the description keeps them readable.
-11. **Elements Harmony supplies (cart icon, login):** add them in the description (`build-description --native native.json`,
-    `kind: native`) so they land in the same deploy. Never add or remove a component by hand after the deploy: each add or
-    remove lets the editor squeeze the page's blank bands (a cart icon or a helper box shifts the page) and the plate
-    no longer lines up. Undo/redo in the editor is one step per run, not per call: undoing too far also undoes the header collapse.
-    A login bar needs the Members app; it is not an addable component on a blank site.
-12. **Local copies of the linked pages:** capture the category and product pages the homepage links to
-    (`mirror-site.mjs <dir> <urls...> --widths 1280 --resume`; it saves every 10 pages, so a long list can resume). Pages take
-    ~25 s each: split a long list over several output directories and merge the `index.json` files (union of `resources`,
-    `pages`, `captured`, copy the `bodies`).
-
-13. **One Harmony section per source section.** A page copied as one big section cannot be edited like a Harmony page, and every
-    add or remove squeezes the whole grid. After the deploy, split it: measure the source's top-level blocks (for SFCC
-    `.experience-region > .experience-component`, plus header, content asset and footer), list them in a spec and run
-    `node scripts/copy/split-sections.mjs <spec.json> --page <pageId> --section <oldSectionId>`
-    (spec format in the script header: name, `y0`/`y1` in source pixels, `delta` (Harmony y minus source y), background, videos,
-    `place`, `include`, `drop`, `cards`). It keeps every component with its id, style and link, gives each section its own
-    background and its own desktop and mobile layout, then removes the old section. Backgrounds: sample each band of the plate;
-    a band that is one colour is a section background colour with no image, only a decorated band gets its own plate
-    (`render-plate.mjs --width 1280 --scale 2` with one cut per section). For a plate section run
-    `mobile-stage.mjs bg-opacity <sectionId> 0` unless the plate survives a phone width, and check each section's mobile height
-    (the editor may keep an old tall height: send `setComposition` again). A grid of tiles uses `"cards": true` so a phone shows
-    tile by tile instead of all images and then all captions. Set `--redo-mobile "<name>"` to re-send one section. A section whose boxes do not land (desktop or mobile, re-read after every write) is not finished: the run exits 1, keeps the original section and resumes from that section. The final cleanup (drop, remove the original section) runs once all sections are finished, checks what still exists, and is recorded, so a repeat or a mobile redo never touches a deleted section.
-14. **Videos are copied as videos.** A source video (Vidyard background player, `<video>`) needs the real mp4: the player's
-    JSON lists signed URLs that expire in minutes and answer 403 without `Referer`/`Origin: https://play.vidyard.com` and a
-    browser User-Agent, so download them while mapping the page. Upload through Media Manager
-    (`upload-media-manager.mjs`; Playwright cannot transfer more than 50 MB per call, so upload a large file alone).
-    A half-width video next to text is a `wixEditorElements.VideoUpload` at the measured box (autoplay, loop, muted, no controls);
-    a full-width one is the section's background video (`videoMedia`). The video value must be
-    `{ uri: 'video/<fileId>/720p/mp4/file.mp4', name, hasAudio, duration, adaptiveSources: [], sources: [{ quality, width, height, types: [{ format: 'mp4', uri }] }], poster: { uri: '<fileId>f002.jpg', name, width, height } }`.
-    **`adaptiveSources` must be present, even `[]`.** Without it the saved document cannot be loaded again: the editor stays on the
-    loading screen ("Failed to wait for Document Services", `Cannot read properties of undefined (reading 'map')`). Recovery: open the
-    editor with Playwright `page.route` on `pages.parastorage.com/sites/*.json` and add `adaptiveSources: []` to the broken video
-    items in the response, change the video once and save; a plain reload then works. After a long run, Preview needs ~20 s to render:
-    scroll the Preview frame and take viewport shots instead of one full-page screenshot.
-15. **A product collection is the Stores slider gallery, never static tiles.** Wherever the source shows a collection (best sellers,
-    new, gift picks, related) add the `checkout_Orders.SliderGallery_legacy` object ("Slider Product Gallery") in that section; the
-    static images, names and prices are dropped (`drop` in the split spec). It is driven by a Stores category: pick an existing
-    category when the source's list matches one, otherwise create one and assign the products found in the source block
-    (parse the block's tiles from the local mirror, match the migrated products by exact name or SKU, then
-    `POST /categories/v1/categories` and `POST /categories/v1/bulk/categories/<id>/add-items` with
-    `appId 215238eb-22a5-4c36-9e7b-e7c08025e04e`). The category cannot be set through `content.set`; open the gallery's
-    Settings (`editActions.run({ action: 'chooseSource' })`), "Change Category", search, "Select" (the picker is the iframe
-    `ecom.wix.com/storefront/settings-minigallery`). The gallery shows its own title (the category name); set "Gallery title
-    alignment" to the source's side and do not add a second heading. Record the category as a cutover item (the source ranks by
-    sales, the new store has no sales history yet).
-
-16. **For every area, look for a Wix component first, and match it.** Before an area of the source is rebuilt from text, images and
-    a plate, name what it *is* (collection, newsletter signup, contact or booking form, search, login, cart, menu, social icons, map,
-    video, gallery, accordion, tabs, repeater) and look for the Wix object that does that job: the addable list
-    (`components.listAddable`), the Add panel's Elements search (it also lists app widgets that are not in `listAddable`, such as
-    Forms and Popups), and `apps.search` for an app that supplies it. Use the object when one exists and configure it to the
-    source (texts, fields, colours, size); build static pieces only for areas with no Wix equivalent, and list those as differences.
-    Examples: product collections -> Slider Product Gallery (item 15); videos -> Video Player or a section background video
-    (item 14); the cart icon -> Cart Icon (item 11); **a newsletter signup (email, consent checkbox, button) -> the Wix Forms
-    "Subscribe" form**. Search the Elements panel for "subscribe" and click the first "Sign Up for Our Newsletter" card with the target
-    section selected (`components.select`, then Playwright on Add > Elements). The first use installs Wix Forms ("Adding Wix Forms",
-    about 30 s, then `forms.list` shows "Newsletter signup", type `wixForms.Form_legacy`): it is an app install, so say so before
-    doing it. Then: `forms.update` for field labels (the form came out in the site's Hebrew, header, consent and button included; the
-    header, consent text and button label are not editable through `forms.update`), `appearance.setStyles` on the form's elements
-    (`form-background` transparent, `text`, `input`, `submit-button`, `form-container` paddings; the consent line takes
-    `text.paragraphColor`), then remove the live texts and the plate drawing the old form, set the section's colour, and compose
-    the form in the section (desktop and mobile) with the section height from the form's measured height.
-    Record any area you could not match, with the Wix object you looked for and why it was not used.
-
-17. **Find what a visitor can do, not only what the page shows.** A screenshot is one state. Before measuring, run
-    `node scripts/copy/find-interactions.mjs <local url> <work>/interactions.json --shots <work>/ix`: with Playwright it lists the
-    controls (tabs, accordions and "read more" toggles, carousel arrows, in-page anchors, details/summary), clicks each one from inside
-    the page (`el.click()`, so a consent dialog or sticky bar over the control does not block it) and records what each state shows
-    (images, links, text, a screenshot). It reports `hiddenPanes`: content that exists only after a click. Every hidden pane must be
-    copied, its images fetched from the mirror (the mirror already holds them) and its links mapped like any other. Also look for what
-    only appears on hover (mega menus, zoom), scroll (sticky bars, reveal animations), time (rotating banners) or a click on an image
-    (quick view, dialogs); click or hover them with Playwright and screenshot each state. Do not call a page copied while any
-    control has an unexplained state. Match each kind to a Wix component (item 16): tabs -> Tabs (`wixEditorElements.TabsContainer`),
-    accordion -> Accordion, carousel -> Slideshow or the Stores slider gallery, hover or dropdown menu -> Menu, dialog or
-    popup -> Popup.
-18. **Tabs.** Add `wixEditorElements.TabsContainer` in the section; it comes with 3 tabs. Set the names and count with
-    `content.set({ values: { tabs: [{ ...tab, name }, ...] } })` using the tab objects read back (a shorter array removes the
-    extra tab). Each tab is an inner container (`components.getTree`): remove its placeholder children, `components.reparent` the
-    tab's tiles into it (or add them there), give each tile its link, and place them with `layout.setComposition` on that inner
-    container (width = the tabs' width, a tile at the source's column and row; do it for desktop and again in the mobile view). A
-    tabs component has no grid of its own: set its x, y and width with the section's `setComposition`, its height follows the
-    content. Style `tabContent` (background) and `menuItem` (background, colour, font size, letter spacing, padding, bottom border)
-    with `appearance.setStyles`; the active tab's look is the `selected` state: `appearance.changeState({ elementPath: ['menuItem'],
-    state: 'selected' })`, set the colour and bottom border, then `changeState` back to `null`. The tab bar's own fill
-    (`menu-background` and the other `menu-*` root properties) is rejected by `setStyles` ("must NOT have unevaluated properties"):
-    set "Tab container color" in the Design panel (`editActions.run({ action: 'design' })`, Fill colors, the swatch, the hex field).
-19. **Check the copy for what is missing, not only for what differs.** A photo that is an `<img>` is hidden from the plate on purpose
-    and must be an Image component; one without a component simply vanishes (a photo beside a text block
-    was lost until a person saw the empty half). After a deploy, compare each section with the source side by side and list every
-    source image, text and control with no counterpart in the copy; fetch the source image from the mirror and upload it. A video file
-    can carry black bars of its own (a 16:9 file with a wider picture has bars top and bottom): extract a frame
-    (`ffmpeg -ss 3 -i video.mp4 -frames:v 1 frame.png`) and size a cover-fit section to the picture.
-    A product image that shows broken in a Stores gallery while its original URL loads is usually a JPEG the image service cannot
-    resize (an Adobe RGB profile or EXIF dimensions that disagree with the real size): re-encode it
-    (`ffmpeg -i in.jpg -map_metadata -1 -vf scale=W:H -q:v 2 out.jpg`), upload it, and set the product's media with
-    `PATCH /stores/v3/products/<id>` including `"fields": ["MEDIA_ITEMS_INFO"]` (without `fields` the update fails with a 500).
-    Test every product image with `<url>/v1/fill/w_300,h_300/x.jpg` after an import.
-
-20. **Copy the content, then improve the site.** A copy that reproduces every flaw of the source is not the goal; where Wix gives a
-    better result, take it. After the sections are built, review the whole page for what a visitor would notice and fix it:
-    - **Site language and direction.** A Hebrew store on a site whose language is English shows "Add to Cart" and a left-to-right
-      Stores layout. Set the language (`PATCH /site-properties/v4/properties` with `{"properties":{"language":"he"},"fields":{"paths":["language"]}}`,
-      the field mask is an object, a plain array answers "Failed to parse JSON"), reload the editor, publish: the Stores widgets
-      come out in Hebrew and mirrored.
-    - **Gaps.** Compare each section's content with its height: `layout.getComposition` gives the first content `y` and the last
-      bottom. Pull the content to a 48-64 px margin and cut the height to match (the source's dead bands are not worth copying). Do
-      it for desktop and re-send the mobile layout afterwards: a desktop re-send also moves the mobile boxes, and a mobile
-      `setComposition` can move the desktop ones, so read both views back after every layout write.
-    - **Mobile.** Stack a feature as icon, title, text (not all icons, then all titles); a tile with its caption; photo first. Hide
-      the click areas that sit over plate icons (`mobile-stage.mjs hide`) and set the mobile height to the last visible bottom + 24.
-    - **Readability.** Text on a dark band must be readable in every state (a form's checkbox label takes `input.inputValueColor`).
-21. **Store pages are part of the copy.** The Category Page (`checkout_Orders.CategoryPage_legacy`) and Product Page
-    (`checkout_Orders.ProductPage_legacy`) are single app widgets: review the source's category and product pages next to them and
-    set the widget's styles with `appearance.setStyles` per element (category: `general`, `productGallery`, `productInfo`,
-    `headerSection`, `sidePanel`, `pagination`, `loadMorePrevious`; product: `actionButtons`, `productInfo`, `quantity`,
-    `infoSections`, `productImages`, `wishlist`) with the brand colours (price, sale price, selected filter and the add-to-cart
-    button in the brand colour, the strikethrough price grey). `editActions.run({ action: 'elements' })` opens "Display
-    elements": switch the category menu off when it lists every category of a store with many categories. The widgets' header and footer
-    are the global ones, which this API cannot fill: copy the home page's header section and footer sections to each store page with
-    `components.copy({ componentIds })` on the home page, then `pages.navigate` to the store page and `components.paste()`, then
-    `sections.reorder` (a pasted section lands last). Add a collection to the product page with the slider gallery in its own
-    section; "Related products" renders empty outside the product widget's own slot, so pick a category.
-
-## Rules for a good, fast copy
-
-1. **Measure, never eyeball.** Every position, size, colour and font comes from
-   `source.json`. If a number is missing, extend the measurement, not your guess.
-2. **Real fonts or nothing.** Wrong fonts are the most visible difference. Upload the
-   source's fonts before placing any text.
-3. **Plate the decoration, rebuild the content.** Paper textures, torn edges, gradients,
-   photos used as backgrounds and ornaments go in the plate. Text, links and meaningful
-   images stay live.
-4. **Everything scales or nothing does.** No `px` that survives in the stored data:
-   - line heights as `em`;
-   - images in `fitWidth`;
-   - sections with `height: auto`;
-   - no fixed-height header/footer.
-
-   One `px` line height in one button makes the page short at 1920. Run
-   `--scale-check` after every batch of style writes.
-5. **Overlap-free arrangement.** Harmony rejects the **whole** composition if any two boxes
-   overlap, including touching text boxes whose height is `lines × line-height` with
-   decimals. Resolve source overlaps by baking the decorative party into the plate or by
-   nudging a box 1 px. Never repair drift with `layout.move`.
-6. **Text boxes** (build-description does this):
-   - single-line: the painted words (`glyphBox`) + 12 px, anchored as aligned (centred text
-     stays centred on its words, not on an inline icon beside them);
-   - multi-line: the block width, or the run width for a paragraph split around a float;
-   - `<br>` stays `<br>`; box top = the first glyph line's top (`lineTop`).
-7. **Width differences in a substitute font** are fixed with `letterSpacing` (e.g.
-   `-0.4px`), never by shrinking the box below the text.
-8. **Mobile: positions, widths and the section height are per view through
-   `setComposition` in the mobile view; image heights, sizes from `setSize`, styles and
-   backgrounds are shared.** Never send an image height on mobile (the ratio derives it), and
-   never style in mobile view. Hide and background-image opacity are stage steps.
-9. **Verify in Preview at exact widths, never on the zoomed stage.** Compare images side by
-   side and sample pixel colours before calling a colour wrong.
-10. **Batch writes, save often, guard publishing.**
-    - Batch 10–15 components per snippet, `site.save()` at the end, and record the
-      returned ids in a work file.
-    - Never re-run a partly failed batch.
-    - Check `isPublished` before and after UI automation.
-11. **Send the heights Harmony will compute.** Boxes are anchored to the box above them: a
-    text sent taller than it renders, an image whose height breaks its ratio, or a Button
-    whose height is below its label pulls everything after it up. Text heights come from the
-    local render with fonts loaded; image heights from the ratio; a click area's height from
-    its label `lineHeight` (em).
-12. **Links inside text stay inline `<a href>`.** `links.set` on a rich text rewrites it (root
-    becomes `<h1>`, an underline span appears). Strip tracking parameters (`utm_*`,
-    `visitorId`, …) from links: they change per visit.
-13. **Compare against the offline copy.** A live source can paint popups over itself
-    (an order widget opened a modal and made a 90% "difference").
-14. **Write down what each new site taught you** (see "Improve the method" below): site
-    specifics in your migration folder, generic findings as `dev3 note` for the skill maintainer.
-
-## Starting a new site (checklist)
-
-1. Public data only. Never ask for or use credentials.
-2. Create the Harmony site from the blank template. If the source is a store or another app-backed business, stop here and migrate the data first ("Order" above); open the editor for the front end afterwards (SKILL.md).
-3. Steps 0–10 below, one page at a time; copy the homepage first so later pages can reuse its
-   recipes (nav, footer, fonts).
-4. Run `snapshot-capabilities.mjs` once per session and pass it as `--capabilities` to
-   `check-description.mjs` and `editor-run.mjs` (or set `HARMONY_CAPABILITIES`): every editor
-   call is then linted against the editor's real method list.
-5. Read the `review` list of every `build-description` run. It lists what the method cannot
-   decide: missing fonts, embeds/video/forms (`unsupported`), floating elements without a
-   recipe, default mobile thresholds (`--layout`).
-6. Keep customer-specific files (mirror, descriptions, ledgers, screenshots) in the project's
-   migration folder, never in `skills/`.
-
-### Dynamic sources (carts, carousels, recommendations, video)
-
-The offline mirror must be proven before measuring (step 0). Pages that load blocks by script
-(product carousels, recommendation widgets, JSONP) need the mirror server's replay features:
-per-site `--port`, runtime-URL shim, fuzzy lookup that ignores timestamps, visitor ids and
-callback names. `check-mirror` refuses a port that serves another site, and reports
-`diffOutsideMediaPct`: video and player regions cannot be compared (headless Chromium has no
-h264), so the 0.1% gate applies outside them. Run `yarn install` first in a fresh worktree:
-the scripts need `playwright`.
-
-### Learned on a fluid, responsive store homepage (RTL)
-
-Result: live components over a full-page plate; desktop scales; mobile is a readable single column;
-vertical position can drift toward the bottom of a long page. What to know before the next one:
-
-- **A fluid layout is copied as the 1280 px design, scaled.** Harmony scales the section with the
-  viewport; the source re-flows. Match at the design width, say so for 1920 and others.
-- **The editor API moved under the scripts.** `components.add` takes `{ containerId, components:
-  [{ componentType, box }] }` and returns `added[].componentId`; `layout.setSize` takes plain
-  numbers; `fonts.resolve` takes `{ fontFamily }`. `snapshot-capabilities` fails first when it
-  moves: run it before anything else.
-- **Plate:** render with a normal viewport height and a scroll pass (footers and bands paint on
-  scroll), at the design width. Images that overlap text (a photo under a text card) and SVGs
-  that cannot be imported as media go in the plate (`--decorative`, `--keep`).
-- **Cropped images** (a hero drawn with `object-fit: cover`) need `displayMode: fill` and an
-  explicit `setSize`, otherwise composition derives the height from the ratio and the page
-  below creeps up. build/postedit marks them when the box ratio differs from the file's by >1.5%.
-- **Texts that wrap one line earlier in Harmony** (different glyph widths): widen the box
-  (right-aligned text grows to the left; centred symmetrically) or use `letterSpacing`
-  (a small negative value fits a link). Find the width in the editor with `layout.setSize` +
-  `layout.measure`, then record it. `check-description --heights` takes the editor's measured
-  text heights.
-- **The section's grid compacts blank vertical bands and loses a few pixels on every
-  `setComposition`.** Re-sending does not converge ("resolved back onto the boxes it already
-  had" is the fixed point). Transparent spacer images hold the rows (the drift shrinks) but
-  their size is shared with mobile and there is no API to hide a component on mobile (the UI
-  hide step could not find "Hide" on a 4 px component), so spacers were not kept. Open item.
-- **Global header/footer cannot be collapsed through the section API** (they are refs; their
-  cart icon and login bar sit on the master page and `setSize` stops at the content height).
-- **Chrome can exit mid-run.** Use a per-site `--port`; after a relaunch read the site state (component
-  count, plate, `isPublished`) and run `site.save()` before continuing.
-
-### Scope and limits
-
-Proven on a fixed-width, centred 1280 px layout (top nav, header band, main column, right
-sidebar). Components other than text, image and button are not rebuilt; embeds, video, forms
-and inline SVG are listed, not copied. A responsive theme (no fixed width, no centring) has not
-been tried: expect to tune `--layout` and to extend the mobile stacking. Say so in the report
-instead of presenting a partial copy as exact.
-
-## Several sites, several agents: one agent per site
-
-A customer migration may run many sites at once. Each site gets **exactly one agent**.
-Never put two agents on the same Harmony site, and never split one site's pages between
-agents: they would share one editor tab, one set of component ids and one save, and overwrite
-each other.
-
-**Per-site isolation** (an agent uses only its own):
-- its own Harmony site (msid) and editor tab;
-- its own Chrome: set `PW_PORT` to a free port and `WIX_HARMONY_PROFILE_DIR` to a folder
-  for this site before `launch.sh`, and use the same `PW_PORT` for every script;
-- its own migration folder (mirror, descriptions, ledgers, screenshots, `capabilities.json`).
-  Another site's files are never read or edited.
-
-**Brief the agent gets** (the orchestrator fills this in; ask if something is missing):
-1. source URL, and the list of pages to copy, homepage first;
-2. the Harmony site (msid) and editor URL;
-3. the migration folder and the `PW_PORT` / profile folder;
-4. the rules: public data only, never publish, never touch the menu or other pages
-   unless asked, report in the format below.
-
-**Order inside a site:** homepage first (nav, footer and fonts become recipes), then the
-other pages one at a time. Run `snapshot-capabilities.mjs` once per session.
-
-**Stop and ask a human** (`dev3 attention "<question>"`) instead of guessing when: the
-source needs a login, a page is mostly embeds/video/forms, the layout is not a fixed-width
-centred one (see Scope and limits), or a check keeps failing after a fix. Do not present a
-partial copy as exact.
-
-### Hand-off when a site (or page) is done
-
-Write one report in the site's migration folder, and send its path to the orchestrator
-(`dev3 message`) with one line of summary. It contains what "Before reporting to the user"
-below requires, plus:
-- the `openItems` list from `<desc>.deploy-report.json` (links still pointing to the source:
-  the cutover operator needs them);
-- the draft's save state and that nothing is published;
-- what you could not copy (`unsupported`, review items) and any layout assumption you
-  changed with `--layout`.
-
-### Improve the method: learnings flow back to the skill
-
-Each site is a test of the method, so what it teaches must reach the next agent.
-- **Per site:** keep a `LEARNINGS.md` in the migration folder (what broke, the fix, how you
-  noticed). It is customer data, so it stays out of `skills/`.
-- **Generic findings** (an editor behavior, a script bug, a missing check, a layout the
-  method can't do) go to the skill. Do not edit `skills/` from a site agent; the skill maintainer
-  merges them. Record each with `dev3 note add` (one insight per note, no customer names or
-  paths) and send the task id to the orchestrator in the hand-off. The maintainer then adds the
-  behavior to SKILL.md "Editor behaviors learned live", a technique to this file, or a
-  script/lint fix with a test.
-- **Before you start:** read the latest SKILL.md and this file, then
-  `dev3 conversations search "harmony <topic>"` if you hit something unfamiliar.
-- A learning is done when the next agent no longer needs to rediscover it: it is in the
-  skill, or a script/check now prevents it.
-
-## Before reporting to the user
-
-State plainly:
-- the widths you verified and what each looks like;
-- the differences that remain and why (substitute system fonts, hover effects not copied,
-  a mobile layout that is readable but not the source's zoomed-out phone view);
-- links that point to the old site because the page is not built yet;
-- the publication state, and any change to it you did not make on purpose.
-
-## Worked reference: a fixed-width WordPress site
-
-- **Source:** a fixed-width, centred layout (`centeringDx` is half the gap between the
-  1920 canvas and the design width). There is no mobile design; on a phone it renders
-  zoomed out.
-- **Fonts:** display fonts uploaded from Google Fonts; a font already in the catalog is
-  mapped by name (for example `courier` to `courier new`), and the floating button takes
-  a catalog font with a small negative letter spacing.
-- **Desktop:**
-  - one auto-height section, `fill` background with a 2x full-page plate;
-  - header and footer collapsed;
-  - small decorative icons and a promo tag baked into the plate; the tag gets a
-    transparent link button;
-  - components: nav buttons, linked images, text blocks, a footer rich text with an
-    inline link, and the pinned order pill;
-  - `scaleDeviations` empty between 1024, 1280 and 1920.
-- **Mobile:**
-  - same components in a single column, nav in two rows;
-  - background-image opacity 0 on mobile, with a band gradient behind it;
-  - the promo-tag click area hidden on mobile.
-- **Things that went wrong:**
-  - a 3-section header/plate/footer copy broke at 1836 (bands scale differently);
-  - mobile `setSize`/`setContainerBackground` changed desktop;
-  - a `px` line height on a hotspot made the page short at 1920;
-  - Preview at 1024 failed until the window was wide enough (slider not rendered).
-
-### A second page through the description pipeline
-
-- Texts (including float runs), images, nav buttons, a click area over a stamp and a pinned
-  order button; most components reused from the homepage recipes.
-- The local pipeline (measure, build, media, check) takes seconds; a deploy takes a handful of
-  editor calls; re-place or re-apply takes seconds. Building the pipeline once makes each
-  further page far cheaper than hand work.
-- Acceptance: read-back `problemCount: 0`; `scaleDeviations` empty 1024-1920; the pixel
-  difference from the source at 1280 reported; mobile a single column with plate-coloured bands.
-- Known: a paragraph split around a float reads as two paragraphs on mobile.