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; 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:
- Create the Harmony site (blank template, unpublished). Nothing else is done to it yet.
- 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-replatformflow) then fills that app. A page's product tiles, category links and carousels need real catalog items to point at. - 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.mjsshows 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-checklists 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.
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 forposts). mirror-siterecords 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-mirrorscreenshots 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. Every script here that opens a page (measure-source,mirror-site,find-interactions,render-plate,check-description,compare-preview,preview-widths) accepts only anhttp(s)URL on a public host, or a local mirror on loopback (source-guard.mjs). It refuses a private address, cloud metadata, an internal name andfile:, and while the page loads it also blocks requests and redirects to such addresses. A public page cannot reach loopback.
- Get the URL list from the source's public API (WordPress:
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 1280Besides 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 inem),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,occludedandhiddenText(image-replacement links: a click area over artwork).Fonts first. List every family in
texts[].font. Upload missing ones through the editor's Upload fonts dialog (SKILL.md → Fonts) and record thewfont_…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).Recipes and capabilities (once per site).
node scripts/copy/export-page.mjs <pageId> <sectionId> <work>/recipes.jsonexports 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.jsonrecords what the editor accepts per component type.changedSinceLastSnapshot: truemeans the editor changed: re-check before deploying.
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 itsreviewlist: anything it could not decide is there, never guessed.Prepare media in parallel (nothing here waits on anything else):
node scripts/copy/import-media.mjs <projectDir> <work>/page.desc.jsonimports 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 …thenupload-media-manager.mjs <anySectionId> <plate>; put its uri insection.background.plate.
Check locally until clean:
node scripts/copy/check-description.mjs <work>/page.desc.json <work>/check --capabilities … --fonts … --source <local url> --plate <plate.png> --writeIt 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 atcheck/render-1280.pngandcheck/render-390.png.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 reportproblemCount: 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.Stage steps (no API):
node scripts/copy/mobile-stage.mjs hide <id…>for click areas and anything else that must not show on mobile, andnode scripts/copy/mobile-stage.mjs bg-opacity <sectionId> 0so the desktop plate does not show on a phone (the band gradient shows instead).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>.scaleDeviationsmust be empty. Compareh-1280.pngwith the source at a 46 px offset (the free-site banner), masking the floating button. Look at 768 and 390.Links: every source link is a link in the copy, and none may point back at the source.
measure-sourcerecords every visible link (anchors).build-descriptionsets 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> }.innerRouteis the slug only: the editor prefixes/category/itself (category/<slug>gave/category/category/<slug>). - product: the editor rejects
PageLink+innerRoutefor 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
inlineis 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 todesc.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 withoutunbuilt) does.check-descriptionfails whenpendingItemsis 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/Aand/product/aare different pages) and ignore per-visit tracking parameters (utm_*,fbclid,gclid,_ga,mc_*,visitorId) and the fragment.check-descriptionFAILS 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.
- category:
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.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 theindex.jsonfiles (union ofresources,pages,captured, copy thebodies).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 runnode scripts/copy/split-sections.mjs <spec.json> --page <pageId> --section <oldSectionId>(spec format in the script header: name,y0/y1in 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 2with one cut per section). For a plate section runmobile-stage.mjs bg-opacity <sectionId> 0unless the plate survives a phone width, and check each section's mobile height (the editor may keep an old tall height: sendsetCompositionagain). A grid of tiles uses"cards": trueso 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.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 withoutReferer/Origin: https://play.vidyard.comand 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 awixEditorElements.VideoUploadat 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 } }.adaptiveSourcesmust 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 Playwrightpage.routeonpages.parastorage.com/sites/*.jsonand addadaptiveSources: []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.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_legacyobject ("Slider Product Gallery") in that section; the static images, names and prices are dropped (dropin 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, thenPOST /categories/v1/categoriesandPOST /categories/v1/bulk/categories/<id>/add-itemswithappId 215238eb-22a5-4c36-9e7b-e7c08025e04e). The category cannot be set throughcontent.set; open the gallery's Settings (editActions.run({ action: 'chooseSource' })), "Change Category", search, "Select" (the picker is the iframeecom.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).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 inlistAddable, such as Forms and Popups), andapps.searchfor 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, thenforms.listshows "Newsletter signup", typewixForms.Form_legacy): it is an app install, so say so before doing it. Then:forms.updatefor 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 throughforms.update),appearance.setStyleson the form's elements (form-backgroundtransparent,text,input,submit-button,form-containerpaddings; the consent line takestext.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.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 reportshiddenPanes: 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.Tabs. Add
wixEditorElements.TabsContainerin the section; it comes with 3 tabs. Set the names and count withcontent.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.reparentthe tab's tiles into it (or add them there), give each tile its link, and place them withlayout.setCompositionon 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'ssetComposition, its height follows the content. StyletabContent(background) andmenuItem(background, colour, font size, letter spacing, padding, bottom border) withappearance.setStyles; the active tab's look is theselectedstate:appearance.changeState({ elementPath: ['menuItem'], state: 'selected' }), set the colour and bottom border, thenchangeStateback tonull. The tab bar's own fill (menu-backgroundand the othermenu-*root properties) is rejected bysetStyles("must NOT have unevaluated properties"): set "Tab container color" in the Design panel (editActions.run({ action: 'design' }), Fill colors, the swatch, the hex field).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 withPATCH /stores/v3/products/<id>including"fields": ["MEDIA_ITEMS_INFO"](withoutfieldsthe update fails with a 500). Test every product image with<url>/v1/fill/w_300,h_300/x.jpgafter an import.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/propertieswith{"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.getCompositiongives the first contentyand 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 mobilesetCompositioncan 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).
- 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 (
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 withappearance.setStylesper 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 withcomponents.copy({ componentIds })on the home page, thenpages.navigateto the store page andcomponents.paste(), thensections.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
Measure, never eyeball. Every position, size, colour and font comes from
source.json. If a number is missing, extend the measurement, not your guess.Real fonts or nothing. Wrong fonts are the most visible difference. Upload the source's fonts before placing any text.
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.
Everything scales or nothing does. No
pxthat survives in the stored data:- line heights as
em; - images in
fitWidth; - sections with
height: auto; - no fixed-height header/footer.
One
pxline height in one button makes the page short at 1920. Run--scale-checkafter every batch of style writes.- line heights as
Overlap-free arrangement. Harmony rejects the whole composition if any two boxes overlap, including touching text boxes whose height is
lines × line-heightwith decimals. Resolve source overlaps by baking the decorative party into the plate or by nudging a box 1 px. Never repair drift withlayout.move.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).
- single-line: the painted words (
Width differences in a substitute font are fixed with
letterSpacing(e.g.-0.4px), never by shrinking the box below the text.Mobile: positions, widths and the section height are per view through
setCompositionin the mobile view; image heights, sizes fromsetSize, 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.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.
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
isPublishedbefore and after UI automation.
- Batch 10–15 components per snippet,
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).Links inside text stay inline
<a href>.links.seton a rich text rewrites it (root becomes<h1>, an underline span appears). Strip tracking parameters (utm_*,visitorId, …) from links: they change per visit.Compare against the offline copy. A live source can paint popups over itself (an order widget opened a modal and made a 90% "difference").
Write down what each new site taught you (see "Improve the method" below): site specifics in your migration folder, generic findings as
dev3 notefor the skill maintainer.
Starting a new site (checklist)
- Public data only. Never ask for or use credentials.
- 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).
- Steps 0–10 below, one page at a time; copy the homepage first so later pages can reuse its recipes (nav, footer, fonts).
- Run
snapshot-capabilities.mjsonce per session and pass it as--capabilitiestocheck-description.mjsandeditor-run.mjs(or setHARMONY_CAPABILITIES): every editor call is then linted against the editor's real method list. - Read the
reviewlist of everybuild-descriptionrun. It lists what the method cannot decide: missing fonts, embeds/video/forms (unsupported), floating elements without a recipe, default mobile thresholds (--layout). - 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.addtakes{ containerId, components: [{ componentType, box }] }and returnsadded[].componentId;layout.setSizetakes plain numbers;fonts.resolvetakes{ fontFamily }.snapshot-capabilitiesfails 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) needdisplayMode: filland an explicitsetSize, 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 withlayout.setSize+layout.measure, then record it.check-description --heightstakes 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
setSizestops 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 runsite.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_PORTto a free port andWIX_HARMONY_PROFILE_DIRto a folder for this site beforelaunch.sh, and use the samePW_PORTfor 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):
- source URL, and the list of pages to copy, homepage first;
- the Harmony site (msid) and editor URL;
- the migration folder and the
PW_PORT/ profile folder; - 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
openItemslist 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.mdin the migration folder (what broke, the fix, how you noticed). It is customer data, so it stays out ofskills/. - 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 withdev3 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 (
centeringDxis 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
couriertocourier new), and the floating button takes a catalog font with a small negative letter spacing. - Desktop:
- one auto-height section,
fillbackground 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;
scaleDeviationsempty between 1024, 1280 and 1920.
- one auto-height section,
- 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/setContainerBackgroundchanged desktop; - a
pxline 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;scaleDeviationsempty 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.