@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-harmony-editor/scripts/copy/link-url.mjs

@@ -0,0 +1,27 @@
+// URL helpers shared by build-description and its tests.
+//
+// normU: the key a link is looked up by in a --linkmap. Only parts that are equivalent by the URL
+// rules are normalised: scheme and host are case-insensitive (lowercased), a fragment never reaches
+// the server (dropped), a trailing slash on the path and percent-encoding of the path (decoded, so a
+// Hebrew slug compares equal to its encoded form) are folded, and per-visit tracking parameters are
+// removed. The path and the query VALUES keep their case: /Product/A and /product/a can be two
+// different pages, and the two are different keys.
+export const TRACKING = /^(utm_|visitorid$|fbclid$|gclid$|_ga$|mc_)/i;
+
+export const stripTracking = (u) => {
+  try { const x = new URL(u); let changed = false; for (const k of [...x.searchParams.keys()]) if (TRACKING.test(k)) { x.searchParams.delete(k); changed = true; } return changed ? x.href : u; } catch { return u; }
+};
+
+const dec = (s) => { try { return decodeURIComponent(s); } catch { return s; } };
+
+export const normU = (u) => {
+  const s = String(u);
+  try {
+    const x = new URL(stripTracking(s.replace(/#.*$/, '')));
+    const path = dec(x.pathname).replace(/\/$/, '');
+    const q = [...x.searchParams].map(([k, v]) => `${dec(k)}=${dec(v)}`).join('&');
+    return `${x.protocol}//${x.host.toLowerCase()}${path}${q ? '?' + q : ''}`;
+  } catch {
+    return dec(s.replace(/#.*$/, '')).replace(/\/$/, ''); // not an absolute URL (mailto:, tel:, a relative path): compared as written
+  }
+};

package/skills/wix-harmony-editor/scripts/copy/lint-api.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Static check of editor code before it reaches the editor (compliance guard 1b).
+// Every `A.<namespace>.<method>(` / `editorLLMApis.<namespace>.<method>(` call in the given
+// files must exist in the live editor's API list, as recorded by snapshot-capabilities.mjs
+// (`api`). In a snippet, anything else (fetch, require, import(),
+// eval, window/document access) is an error too. Exit 1 on any unknown call.
+//
+//   node scripts/copy/lint-api.mjs --capabilities capabilities.json [--snippet] <file.js|file.mjs> [...]
+//   --snippet: the file is editor code itself (not a Node script): also reject fetch/require/window/…
+//
+// Also used by editor-run.mjs (every snippet) and check-description.mjs (deploy-description.mjs
+// is linted with its generated snippets, since they are template strings in that file).
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const CALL = /\b(?:A|editorLLMApis)\.([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)\s*\(/g;
+const OUTSIDE = /\b(fetch|require|eval|XMLHttpRequest|importScripts)\s*\(|\bimport\s*\(|\b(window|document|localStorage|process)\./g;
+
+// snippet: true for a file that IS editor code (editor-run input); host scripts only get the API-method check
+export function lintApi(code, caps, file = 'snippet', { snippet = false } = {}) {
+  const api = caps?.api;
+  const problems = [];
+  const lines = code.split('\n');
+  const where = (i) => `${file}:${code.slice(0, i).split('\n').length}`;
+  if (!api) return { problems: [{ at: file, error: 'capabilities file has no `api` list: re-run snapshot-capabilities.mjs' }], calls: 0 };
+  let calls = 0;
+  for (const m of code.matchAll(CALL)) {
+    calls++;
+    const [, ns, method] = m;
+    if (!api[ns]) problems.push({ at: where(m.index), error: `unknown namespace '${ns}' (editor has: ${Object.keys(api).join(', ')})` });
+    else if (!api[ns].includes(method)) problems.push({ at: where(m.index), error: `'${ns}.${method}' does not exist; '${ns}' has: ${api[ns].join(', ')}` });
+  }
+  if (snippet) for (const m of code.matchAll(OUTSIDE)) {
+    const line = lines[code.slice(0, m.index).split('\n').length - 1].trim();
+    if (/^\s*(\/\/|\*)/.test(line) || /^import\b/.test(line)) continue; // comments and the script's own module imports
+    problems.push({ at: where(m.index), error: `'${m[0].trim()}' is not part of the editor API: a snippet may only call editorLLMApis` });
+  }
+  return { problems, calls };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const ci = args.indexOf('--capabilities');
+  const capsFile = ci >= 0 ? args[ci + 1] : null;
+  const snippet = args.includes('--snippet');
+  const files = args.filter((a, i) => !a.startsWith('--') && i !== ci + 1);
+  if (!capsFile || !files.length) { console.error('usage: lint-api.mjs --capabilities capabilities.json <file> [...]'); process.exit(2); }
+  const caps = JSON.parse(fs.readFileSync(capsFile, 'utf8'));
+  let bad = 0;
+  for (const f of files) {
+    const { problems, calls } = lintApi(fs.readFileSync(f, 'utf8'), caps, f, { snippet });
+    for (const p of problems) { console.log(`${p.error ? 'ERROR' : 'warn '} ${p.at}: ${p.error || p.warning}`); if (p.error) bad++; }
+    console.log(`${f}: ${calls} API calls, ${problems.filter((p) => p.error).length} errors`);
+  }
+  process.exit(bad ? 1 : 0);
+}

package/skills/wix-harmony-editor/scripts/copy/measure-source.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// Measure a live source page so it can be copied exactly into Harmony.
+//
+//   node scripts/copy/measure-source.mjs <url> <out.json> [--width 1280] [--height 900]
+//
+// Writes one JSON file with everything the copy needs, in page coordinates at --width:
+//   page        height, and a centering check (the same layout rendered 640px wider:
+//               a constant dx of 320 means a centered fixed-width layout, so a wider
+//               background plate lines up with the narrower canvas)
+//   backgrounds every element with a background image or a non-transparent colour
+//   images      every visible <img>: src, natural size, rendered box, alt, link
+//   texts       one entry per text BLOCK: the block box, the first line's top
+//               (lineTop), font family/size/weight/colour/line-height/letter-spacing,
+//               alignment, inner HTML, explicit <br> breaks and links, plus:
+//                 rich      Harmony-ready rich-text HTML: links kept, <br> kept, images and
+//                           nested blocks dropped, and every run whose colour, weight,
+//                           style, decoration, family or size differs from the text's own
+//                           base style (font/size/color below) as an
+//                           inline <span style> (sizes as em, so they scale)
+//                 segments  only when the text wraps around a float (its lines start at
+//                           different x): one {rich, box, lineTop, lines} per run of lines
+//                           sharing a left edge, box width = the space the lines wrap in
+//                 lines, linePitch  painted line count and the real distance between lines
+//                           (can differ from lineHeight when inline content is bigger)
+//                 occluded  true when something else is painted over all of the first line:
+//                           usually not copied
+//                 hiddenText  the words are not painted (image replacement, text-indent
+//                           -9999px): with a link the box is a click area over artwork
+//                           (copy as a transparent link button), without one skip it
+//   fixed       position:fixed elements (floating buttons, chat widgets) incl. shadow DOM
+//   unsupported iframes, video/audio, canvas, forms and form controls, inline svg: not rebuilt by
+//               this method; build-description turns each into a `review` item
+//
+// Read only. It never logs in and never sends anything to the source.
+import { chromium } from 'playwright';
+import fs from 'fs';
+
+const args = process.argv.slice(2);
+const opt = (name, dflt) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : dflt; };
+const [url, out] = args.filter((a, i) => !a.startsWith('--') && !(i > 0 && args[i - 1].startsWith('--')));
+if (!url || !out) { console.error('usage: measure-source.mjs <url> <out.json> [--width 1280] [--height 900]'); process.exit(2); }
+const width = Number(opt('width', 1280));
+const height = Number(opt('height', 900));
+
+const browser = await chromium.launch();
+
+async function measure(w) {
+  const page = await browser.newPage({ viewport: { width: w, height } });
+  await page.goto(url, { waitUntil: 'networkidle', timeout: 90000 });
+  await page.waitForTimeout(1500);
+  const data = await page.evaluate(() => {
+    const R = (r) => ({ x: Math.round(r.x), y: Math.round(r.y + scrollY), w: Math.round(r.width), h: Math.round(r.height) });
+    const visible = (e) => { const s = getComputedStyle(e); return s.display !== 'none' && s.visibility !== 'hidden' && +s.opacity > 0; };
+    const backgrounds = [], images = [], texts = [], fixed = [], unsupported = [];
+    for (const e of document.querySelectorAll('body *')) {
+      if (!visible(e)) continue;
+      const s = getComputedStyle(e), r = e.getBoundingClientRect();
+      if (r.width < 1 || r.height < 1) continue;
+      const hasImg = s.backgroundImage && s.backgroundImage !== 'none';
+      const hasColor = !/rgba\(0, 0, 0, 0\)|transparent/.test(s.backgroundColor);
+      if (hasImg || hasColor) backgrounds.push({ tag: e.tagName, id: e.id || null, cls: String(e.className || '').slice(0, 80), box: R(r), image: hasImg ? s.backgroundImage : null, repeat: s.backgroundRepeat, position: s.backgroundPosition, size: s.backgroundSize, color: s.backgroundColor, radius: s.borderRadius });
+      // things this copy method does not rebuild (it only knows text, images, buttons and the plate): listed so
+      // nothing is dropped silently. Hidden/aria-hidden tracking pixels are skipped by visible() above.
+      if (/^(IFRAME|VIDEO|AUDIO|CANVAS|OBJECT|EMBED|FORM|INPUT|SELECT|TEXTAREA|SVG)$/i.test(e.tagName) && !(e.tagName.toUpperCase() === 'INPUT' && e.type === 'hidden') && !e.closest('svg:not(:scope)') && !(e.tagName.toUpperCase() === 'SVG' && r.width < 24 && r.height < 24)) unsupported.push({ tag: e.tagName.toLowerCase(), src: e.currentSrc || e.src || e.action || null, box: R(r) });
+      if (e.tagName === 'IMG' && e.dataset.embedSrc) { unsupported.push({ tag: 'iframe', src: e.dataset.embedSrc, box: R(r) }); continue; } // the offline copy swapped an iframe for a snapshot image: still an embed, not a picture
+      if (e.tagName === 'IMG') images.push({ src: e.currentSrc || e.src, natural: [e.naturalWidth, e.naturalHeight], box: R(r), alt: e.alt || '', href: e.closest('a') ? e.closest('a').href : null });
+    }
+    // floats only push lines of text in the same block formatting context (BFC)
+    const makesBfc = (e) => { const s = getComputedStyle(e); return e === document.documentElement || s.float !== 'none' || /absolute|fixed/.test(s.position) || !/visible|clip/.test(s.overflowX + s.overflowY) && s.overflow !== 'visible' || /inline-block|flow-root|table-cell|table-caption|flex|grid/.test(s.display) || (e.parentElement && /flex|grid/.test(getComputedStyle(e.parentElement).display)); };
+    const bfcOf = (e) => { for (let p = e; p; p = p.parentElement) if (makesBfc(p)) return p; return document.documentElement; };
+    const floats = [...document.querySelectorAll('body *')].filter((e) => { const s = getComputedStyle(e); return (s.float === 'left' || s.float === 'right') && visible(e); })
+      .map((e) => ({ el: e, bfc: bfcOf(e.parentElement), side: getComputedStyle(e).float, box: () => { const q = e.getBoundingClientRect(), s = getComputedStyle(e); return { left: q.left - parseFloat(s.marginLeft), right: q.right + parseFloat(s.marginRight), top: q.top - parseFloat(s.marginTop), bottom: q.bottom + parseFloat(s.marginBottom) }; } }));
+    const seen = new Set();
+    const tw = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    while (tw.nextNode()) {
+      const n = tw.currentNode;
+      if (!n.textContent.trim()) continue;
+      const el = n.parentElement;
+      if (!el || ['SCRIPT', 'STYLE', 'NOSCRIPT'].includes(el.tagName) || !visible(el)) continue;
+      let block = el; while (block && getComputedStyle(block).display === 'inline') block = block.parentElement;
+      if (!block || seen.has(block)) continue; seen.add(block);
+      const bs = getComputedStyle(block), br = block.getBoundingClientRect();
+      if (br.width < 1 || br.right < 0 || br.left > innerWidth) continue; // off-screen (e.g. hidden menu items)
+      const rg = document.createRange(); rg.selectNodeContents(block); const tr = rg.getBoundingClientRect();
+      const ts = getComputedStyle(el);
+      const lh = parseFloat(ts.lineHeight) || parseFloat(ts.fontSize) * 1.2;
+      const rects = [...rg.getClientRects()].filter((q) => q.width > 0);
+      const firstLine = rects.length ? rects[0] : tr;
+      // a glyph rect is the font's content area, centred on its line box
+      const lineTop = Math.round((firstLine.top + scrollY + (firstLine.height - lh) / 2) * 10) / 10;
+      // ---- rich HTML, line runs (floats) and occlusion -------------------------------
+      const hex = (c) => { const m = 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 escT = (t) => t.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\u00a0/g, '&nbsp;');
+      const inBlock = (n) => { for (let p = n.parentElement; p && p !== block; p = p.parentElement) if (!/^inline/.test(getComputedStyle(p).display)) return false; return true; };
+      // the BASE style is the one most characters are painted in; every other run becomes a flat
+      // <span style> relative to it (sizes in em), links stay <a>, nested blocks are their own entry
+      const runKey = (c) => [c.color, c.fontWeight, c.fontStyle, c.textDecorationLine, c.fontFamily, c.fontSize].join('|');
+      const counts = new Map(); const twc = document.createTreeWalker(block, NodeFilter.SHOW_TEXT);
+      while (twc.nextNode()) { const tn = twc.currentNode; if (!tn.textContent.trim() || !inBlock(tn)) continue; const c = getComputedStyle(tn.parentElement); const k = runKey(c); const e = counts.get(k) || { n: 0, el: tn.parentElement }; e.n += tn.textContent.trim().length; counts.set(k, e); }
+      const baseEl = counts.size ? [...counts.values()].sort((x, y) => y.n - x.n)[0].el : el;
+      const base = getComputedStyle(baseEl);
+      const diff = (cs) => { const st = [];
+        if (cs.color !== base.color) st.push(`color:${hex(cs.color)}`);
+        if (cs.fontWeight !== base.fontWeight) st.push(`font-weight:${cs.fontWeight}`);
+        if (cs.fontStyle !== base.fontStyle) st.push(`font-style:${cs.fontStyle}`);
+        if (cs.textDecorationLine !== base.textDecorationLine) st.push(`text-decoration:${cs.textDecorationLine}`);
+        if (cs.fontFamily !== base.fontFamily) st.push(`font-family:${cs.fontFamily.replace(/"/g, "'")}`);
+        if (cs.fontSize !== base.fontSize) st.push(`font-size:${(parseFloat(cs.fontSize) / parseFloat(base.fontSize)).toFixed(3)}em`);
+        return st.join(';'); };
+      const rich = (node, R) => {
+        let o = '';
+        for (const n of node.childNodes) {
+          if (R && !R.intersectsNode(n)) continue;
+          if (n.nodeType === 3) { const t = n.textContent; const s0 = R && n === R.startContainer ? R.startOffset : 0; const e0 = R && n === R.endContainer ? R.endOffset : t.length;
+            const w = escT(t.slice(s0, e0).replace(/[\n\t ]+/g, ' ')); const d = w.trim() ? diff(getComputedStyle(n.parentElement)) : ''; o += d ? `<span style="${d}">${w}</span>` : w; continue; }
+          if (n.nodeType !== 1) continue;
+          const tag = n.tagName; if (['IMG', 'SCRIPT', 'STYLE', 'NOSCRIPT', 'SVG', 'IFRAME'].includes(tag)) continue;
+          if (tag === 'BR') { o += '<br>'; continue; }
+          const cs = getComputedStyle(n); if (cs.display === 'none' || !/^inline/.test(cs.display)) continue;
+          const inner = rich(n, R);
+          o += tag === 'A' && n.getAttribute('href') ? `<a href="${n.href}">${inner}</a>` : inner;
+        }
+        return o;
+      };
+      const tidy = (h) => h.replace(/^(\s|&nbsp;|<br>)+|(\s|&nbsp;|<br>)+$/g, '');
+      const bcs = getComputedStyle(block);
+      // one entry per visual line: where it starts (text node + offset), its left and top
+      const lineStarts = []; const tw2 = document.createTreeWalker(block, NodeFilter.SHOW_TEXT);
+      const lhB = parseFloat(bcs.lineHeight) || parseFloat(bcs.fontSize) * 1.2;
+      while (tw2.nextNode()) { const tn = tw2.currentNode; if (!inBlock(tn)) continue; const rr = document.createRange();
+        for (let i = 0; i < tn.textContent.length; i++) { if (/\s/.test(tn.textContent[i])) continue; rr.setStart(tn, i); rr.setEnd(tn, i + 1); const q = rr.getBoundingClientRect(); if (!q.width) continue;
+          const last = lineStarts[lineStarts.length - 1]; if (!last || q.top > last.top + lhB / 2) lineStarts.push({ node: tn, offset: i, left: q.left, top: q.top, h: q.height }); } }
+      let segments = null;
+      // image replacement (text-indent:-9999px etc.): the words are not painted, the box is a click area
+      const hiddenText = lineStarts.length > 0 && (lineStarts[0].left > br.right + 50 || lineStarts[0].left < br.left - 50);
+      const leftAligned = /^(start|left|justify)$/.test(bcs.textAlign) && bcs.direction !== 'rtl';
+      if (!hiddenText && leftAligned && lineStarts.length) {
+        // the space each line wraps in: the block's content box minus every float beside the line
+        const contentLeft = br.left + parseFloat(bcs.paddingLeft) + parseFloat(bcs.borderLeftWidth);
+        const contentRight = br.right - parseFloat(bcs.paddingRight) - parseFloat(bcs.borderRightWidth);
+        for (const l of lineStarts) {
+          l.availL = contentLeft; l.availR = contentRight;
+          const myBfc = makesBfc(block) ? block : bfcOf(block);
+          // a float pushes only the lines that come after it in the document
+          for (const fl of floats) { if (fl.el.contains(block) || fl.bfc !== myBfc || !(fl.el.compareDocumentPosition(l.node) & Node.DOCUMENT_POSITION_FOLLOWING)) continue; const q = fl.box(); if (q.bottom <= l.top + 1 || q.top >= l.top + lhB - 1) continue;
+            if (fl.side === 'left' && q.right > l.availL && q.left < contentRight) l.availL = Math.max(l.availL, q.right);
+            if (fl.side === 'right' && q.left < l.availR && q.right > contentLeft) l.availR = Math.min(l.availR, q.left); }
+        }
+        const groups = []; for (const l of lineStarts) { const g = groups[groups.length - 1]; if (g && Math.abs(g.availL - l.availL) < 4 && Math.abs(g.availR - l.availR) < 4) g.lines.push(l); else groups.push({ availL: l.availL, availR: l.availR, left: l.left, lines: [l] }); }
+        // runs of lines that wrap in different spaces (floats beside some lines), or a single run narrowed by a float
+        if (groups.length > 1 || groups[0].availL > contentLeft + 4 || groups[0].availR < contentRight - 4) {
+          segments = groups.map((g, gi) => { const R = document.createRange(); if (gi === 0) R.setStart(block, 0); else R.setStart(g.lines[0].node, g.lines[0].offset);
+            if (gi < groups.length - 1) R.setEnd(groups[gi + 1].lines[0].node, groups[gi + 1].lines[0].offset); else R.setEnd(block, block.childNodes.length);
+            const f = g.lines[0]; const x = Math.round(g.availL);
+            return { rich: tidy(rich(block, R)), lineTop: Math.round((f.top + scrollY + (f.h - lhB) / 2) * 10) / 10, box: { x, y: Math.round(f.top + scrollY + (f.h - lhB) / 2), w: Math.round(g.availR) - x, h: Math.round(g.lines.length * lhB) }, lines: g.lines.length };
+          });
+        }
+      }
+      let occluded = false;
+      if (lineStarts.length) { // scroll the line into view, ignore floating (fixed) layers, test what is on top
+        const f = lineStarts[0]; const sy = scrollY; const absTop = f.top + sy; scrollTo(0, Math.max(0, absTop - 300));
+        const fixedUp = (e) => { for (let p = e; p; p = p.parentElement) if (getComputedStyle(p).position === 'fixed') return true; return false; };
+        const right = Math.min(br.right, f.left + tr.width) - 4; // sample the first line at three points: hidden only if all are covered
+        occluded = [f.left + 4, (f.left + right) / 2, right].every((x) => { const hit = document.elementsFromPoint(x, absTop - scrollY + f.h / 2).find((e) => !fixedUp(e)); return !!hit && hit !== block && !block.contains(hit); });
+        scrollTo(0, sy); }
+      texts.push({
+        rich: tidy(rich(block, null)), segments, occluded, hiddenText,
+        lines: lineStarts.length, linePitch: lineStarts.length > 1 ? Math.round(((lineStarts[lineStarts.length - 1].top - lineStarts[0].top) / (lineStarts.length - 1)) * 10) / 10 : null,
+        text: block.innerText.replace(/\s+\n/g, '\n').trim().slice(0, 400),
+        html: block.innerHTML.replace(/\s+/g, ' ').trim().slice(0, 600),
+        explicitBreaks: block.querySelectorAll('br').length,
+        // the painted WORDS only (inline images excluded): single-line boxes are sized and centred on it
+        glyphBox: (() => { let l = 1e9, t = 1e9, r = -1e9, b = -1e9; const tw3 = document.createTreeWalker(block, NodeFilter.SHOW_TEXT); while (tw3.nextNode()) { const tn = tw3.currentNode; if (!tn.textContent.trim() || !inBlock(tn)) continue; const rr = document.createRange(); rr.selectNodeContents(tn); for (const q of rr.getClientRects()) { if (!q.width) continue; l = Math.min(l, q.left); t = Math.min(t, q.top); r = Math.max(r, q.right); b = Math.max(b, q.bottom); } } return l < 1e9 ? { x: Math.round(l), y: Math.round(t + scrollY), w: Math.round(r - l), h: Math.round(b - t) } : null; })(),
+        // the first painted glyph line sets lineTop (an inline image on the first line must not)
+        block: R(br), textBox: R(tr), lineTop: lineStarts.length && !hiddenText ? Math.round((lineStarts[0].top + scrollY + (lineStarts[0].h - lhB) / 2) * 10) / 10 : lineTop,
+        padding: [bs.paddingTop, bs.paddingRight, bs.paddingBottom, bs.paddingLeft].join(' '),
+        font: base.fontFamily, size: base.fontSize, weight: base.fontWeight, style: base.fontStyle, color: base.color,
+        lineHeight: base.lineHeight, letterSpacing: base.letterSpacing, transform: base.textTransform, align: bs.textAlign,
+        decoration: base.textDecorationLine, shadow: base.textShadow,
+        links: [...new Set([...block.querySelectorAll('a')].map((a) => a.href).concat(block.closest('a') ? [block.closest('a').href] : []))],
+      });
+    }
+    const walk = (root) => { for (const e of root.querySelectorAll('*')) { const s = getComputedStyle(e); if (s.position === 'fixed' && visible(e)) {
+          // report the clickable child (the visible pill), not a full-width wrapper
+          const t = e.matches('a,button') ? e : (e.querySelector('a,button') || e);
+          const ts = getComputedStyle(t), r = t.getBoundingClientRect();
+          fixed.push({ tag: t.tagName, cls: String(t.className || '').slice(0, 80), box: { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) }, bottomOffset: Math.round(innerHeight - r.bottom), text: (t.innerText || '').trim().slice(0, 120), href: t.href || null, background: ts.backgroundColor, radius: ts.borderRadius, padding: ts.padding, font: ts.fontFamily, size: ts.fontSize, weight: ts.fontWeight, color: ts.color });
+        } if (e.shadowRoot) walk(e.shadowRoot); } };
+    walk(document);
+    // every visible link, with its box: build-description turns each one the text and image links do not
+    // already cover into a transparent click area, so no source link is lost (icons, logo, nav, tiles)
+    const anchors = [];
+    for (const a of document.querySelectorAll('a[href]')) {
+      const h = a.getAttribute('href') || ''; if (!h || h.startsWith('#') || /^javascript:/i.test(h) || !visible(a)) continue;
+      const r = a.getBoundingClientRect(); if (r.width < 4 || r.height < 4) continue;
+      anchors.push({ href: a.href, text: ((a.innerText || '').trim().replace(/\s+/g, ' ') || a.getAttribute('aria-label') || (a.querySelector('img') && a.querySelector('img').alt) || '').slice(0, 60), box: { x: Math.round(r.x + scrollX), y: Math.round(r.y + scrollY), w: Math.round(r.width), h: Math.round(r.height) } });
+    }
+    return { anchors, height: Math.max(document.documentElement.scrollHeight, document.body.scrollHeight, Math.round(document.body.getBoundingClientRect().bottom + scrollY)) /* the full scrollable page, body margins included */, backgrounds, images, texts, fixed, unsupported };
+  });
+  await page.close();
+  return data;
+}
+
+const main = await measure(width);
+const wide = await measure(width + 640);
+const dx = wide.images.map((im, i) => (main.images[i] ? im.box.x - main.images[i].box.x : null)).filter((v) => v != null);
+const centered = dx.length > 0 && dx.every((v) => v === dx[0]);
+const result = { url, width, measuredAt: new Date().toISOString(), page: { height: main.height, centeringDx: [...new Set(dx)], centered, offsetAtPlusWidth: centered ? dx[0] : null }, ...main };
+fs.writeFileSync(out, JSON.stringify(result, null, 1));
+await browser.close();
+console.log(JSON.stringify({ out, height: main.height, centered: result.page.centered, centeringDx: result.page.centeringDx, backgrounds: main.backgrounds.length, images: main.images.length, texts: main.texts.length, fixed: main.fixed.length }));

package/skills/wix-harmony-editor/scripts/copy/merge-mirrors.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Merge mirrors captured in parallel (mirror-site.mjs into separate directories) into one.
+//
+//   node scripts/copy/merge-mirrors.mjs <intoDir> <fromDir> [<fromDir> ...]
+//
+// A capture takes ~25 s per page: split a long URL list over several directories, run them at once, merge.
+// resources / embeds: the first entry for a URL wins; pages and captured are unioned; bodies (named by hash)
+// are copied when missing. <intoDir> may be one of the sources' ancestors' mirror: it is created if absent.
+import fs from 'fs';
+
+const [into, ...from] = process.argv.slice(2);
+if (!into || !from.length) { console.error('usage: merge-mirrors.mjs <intoDir> <fromDir...>'); process.exit(2); }
+fs.mkdirSync(`${into}/bodies`, { recursive: true });
+const file = `${into}/index.json`;
+const out = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : { site: null, pages: [], resources: {}, embeds: {} };
+out.embeds ??= {}; out.captured ??= [];
+let copied = 0, added = 0;
+for (const dir of from) {
+  const idx = JSON.parse(fs.readFileSync(`${dir}/index.json`, 'utf8'));
+  out.site ??= idx.site;
+  if (idx.site !== out.site) { console.error(`${dir} mirrors ${idx.site}, not ${out.site}`); process.exit(1); }
+  for (const [u, r] of Object.entries(idx.resources)) if (!out.resources[u]) { out.resources[u] = r; added++; }
+  for (const [u, e] of Object.entries(idx.embeds || {})) out.embeds[u] ??= e;
+  out.pages = [...new Set([...out.pages, ...idx.pages])];
+  out.captured = [...new Set([...out.captured, ...(idx.captured || [])])];
+  if (fs.existsSync(`${dir}/bodies`)) for (const b of fs.readdirSync(`${dir}/bodies`)) if (!fs.existsSync(`${into}/bodies/${b}`)) { fs.copyFileSync(`${dir}/bodies/${b}`, `${into}/bodies/${b}`); copied++; }
+}
+fs.writeFileSync(file, JSON.stringify(out));
+console.log(JSON.stringify({ into, pages: out.pages.length, captured: out.captured.length, resources: Object.keys(out.resources).length, newResources: added, bodiesCopied: copied }));

package/skills/wix-harmony-editor/scripts/copy/mirror-site.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// Save a public site for offline viewing: every response the browser receives while each page
+// loads (HTML, CSS, JS, fonts, images, JSON), at several widths so responsive images are caught.
+//
+//   node scripts/copy/mirror-site.mjs <outDir> <url> [<url> ...] [--widths 390,1024,1280,1920] [--resume]
+//
+// Writes <outDir>/index.json (original URL -> status, content type, body file) and
+// <outDir>/bodies/<sha1>. Bodies are stored unchanged; serve-mirror.mjs rewrites URLs when
+// serving. Third-party embeds (iframes from another host, e.g. Google Maps) cannot be replayed
+// offline (their auth is bound to the live origin), so each one is saved as a snapshot image
+// at 1280 px (index.embeds[src]) and served in place of the iframe.
+// Read only: plain anonymous page loads, nothing is posted to the source.
+import { chromium } from 'playwright';
+import fs from 'fs';
+import crypto from 'crypto';
+
+const args = process.argv.slice(2);
+const opt = (n, d) => { const i = args.indexOf(`--${n}`); return i >= 0 ? args[i + 1] : d; };
+const pos = args.filter((a, i) => !a.startsWith('--') && !(i > 0 && args[i - 1].startsWith('--')));
+const [outDir, ...urls] = pos;
+if (!outDir || !urls.length) { console.error('usage: mirror-site.mjs <outDir> <url...> [--widths 390,1024,1280,1920] [--resume]'); process.exit(2); }
+const widths = opt('widths', '390,1024,1280,1920').split(',').map(Number);
+fs.mkdirSync(`${outDir}/bodies`, { recursive: true });
+const idxFile = `${outDir}/index.json`;
+const index = fs.existsSync(idxFile) ? JSON.parse(fs.readFileSync(idxFile, 'utf8')) : { site: new URL(urls[0]).host, pages: [], resources: {} };
+index.embeds ??= {};
+const key = (u) => u.split('#')[0];
+const failures = [];
+
+const browser = await chromium.launch();
+async function capture(url, width) {
+  const ctx = await browser.newContext({ viewport: { width, height: 900 } });
+  const page = await ctx.newPage();
+  const pending = [];
+  let ok = true;
+  page.on('response', (res) => pending.push((async () => {
+    const u = key(res.url());
+    if (!/^https?:/.test(u)) return;
+    const status = res.status();
+    const headers = res.headers();
+    if (status >= 300 && status < 400) { index.resources[u] ??= { status, location: headers.location || '' }; return; }
+    let body; try { body = await res.body(); } catch { return; } // e.g. aborted beacons
+    const sha = crypto.createHash('sha1').update(body).digest('hex');
+    if (!fs.existsSync(`${outDir}/bodies/${sha}`)) fs.writeFileSync(`${outDir}/bodies/${sha}`, body);
+    const prev = index.resources[u];
+    if (!prev || prev.status !== 200 || status === 200) index.resources[u] = { status, type: headers['content-type'] || '', body: sha, bytes: body.length };
+  })()));
+  try {
+    await page.goto(url, { waitUntil: 'networkidle', timeout: 90000 });
+    // scroll through the page so lazy-loaded images and scripts load, then back to the top
+    const h = await page.evaluate(() => document.documentElement.scrollHeight);
+    for (let y = 0; y <= h; y += 600) { await page.evaluate((y) => scrollTo(0, y), y); await page.waitForTimeout(120); }
+    await page.evaluate(() => scrollTo(0, 0));
+    await page.waitForLoadState('networkidle').catch(() => {});
+    await page.waitForTimeout(800);
+    if (width === 1280) {
+      for (const el of await page.$$('iframe[src]')) {
+        const src = await el.getAttribute('src');
+        if (!/^https?:/.test(src) || new URL(src).host === index.site) continue;
+        const box = await el.evaluate((e) => { e.scrollIntoView({ block: 'center' }); const r = e.getBoundingClientRect(); return { x: r.x + scrollX + e.clientLeft, y: r.y + scrollY + e.clientTop, width: e.clientWidth, height: e.clientHeight }; }); // content box: the border stays CSS
+        if (box.width < 2 || box.height < 2) continue;
+        await page.waitForTimeout(3000); // map tiles
+        const png = await page.screenshot({ fullPage: true, clip: box });
+        const sha = crypto.createHash('sha1').update(png).digest('hex');
+        fs.writeFileSync(`${outDir}/bodies/${sha}`, png);
+        index.embeds[src] = { page: key(url), body: sha };
+      }
+      await page.evaluate(() => scrollTo(0, 0));
+    }
+  } catch (e) { ok = false; failures.push({ url, width, error: String(e).slice(0, 200) }); }
+  await Promise.all(pending);
+  await ctx.close();
+  return ok;
+}
+// a long list is saved as it goes (every 10 pages) and --resume skips pages already in the index, so a crash or a
+// stopped run costs minutes, not the whole capture
+const resume = args.includes('--resume');
+let done = 0;
+for (const url of urls) {
+  if (resume && index.captured?.includes(key(url))) continue;
+  if (!index.pages.includes(key(url))) index.pages.push(key(url));
+  const results = await Promise.all(widths.map((w) => capture(url, w)));
+  // only a page captured at every width counts as captured, so --resume retries a failed one
+  if (!results.every(Boolean)) continue;
+  (index.captured ??= []).push(key(url));
+  if (++done % 10 === 0) fs.writeFileSync(idxFile, JSON.stringify(index));
+}
+await browser.close();
+fs.writeFileSync(idxFile, JSON.stringify(index, null, 1));
+const res = Object.values(index.resources);
+const hosts = [...new Set(Object.keys(index.resources).map((u) => new URL(u).host))];
+console.log(JSON.stringify({ pages: index.pages.length, embeds: Object.keys(index.embeds).length, resources: res.length, bytes: res.reduce((s, r) => s + (r.bytes || 0), 0), hosts, failures }));

package/skills/wix-harmony-editor/scripts/copy/mobile-stage.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// The two mobile-only changes the editor API cannot make, done on the editor stage.
+//
+//   node scripts/copy/mobile-stage.mjs hide <componentId> [<componentId> ...]
+//   node scripts/copy/mobile-stage.mjs bg-opacity <sectionId> <0-100>
+//
+// hide        mobile view, select, right-click the component on the stage, "Hide". Desktop keeps it.
+// bg-opacity  mobile view, select the section, "Replace Background", set the image opacity field.
+//             (setContainerBackground in mobile view writes the SHARED value and changes desktop.)
+// Both read the result back for BOTH views and print it; nothing else on the page is touched.
+// Widths, heights and positions on mobile need no stage work: layout.setComposition in the
+// mobile view is per view (deploy-description.mjs does it).
+import { chromium } from 'playwright';
+
+const [mode, ...rest] = process.argv.slice(2);
+if (!['hide', 'bg-opacity'].includes(mode)) { console.error('usage: mobile-stage.mjs hide <id...> | bg-opacity <sectionId> <0-100>'); process.exit(2); }
+const b = await chromium.connectOverCDP(`http://127.0.0.1:${process.env.PW_PORT || 9333}`);
+const p = b.contexts().flatMap((c) => c.pages()).find((x) => x.url().includes('editor.wix.com/edit/'));
+if (!p) { console.error('No Harmony editor page is open.'); process.exit(3); }
+const api = async (code) => { const r = await p.evaluate(async (code) => { const a = await repluggableAppDebug.host.getAPI({ name: 'RunEditorLLMCodeToolAPI', public: true, layer: 'DATA_SERVICE' }); return a.execute({ code }, { biParams: {} }); }, code); const c = JSON.parse(r.items[0].content); if (!c.success) throw new Error(c.summary); return c.result; };
+await p.setViewportSize({ width: 1600, height: 1000 });
+await p.keyboard.press('Escape').catch(() => {});
+const iframeEl = async () => p.$('iframe[class^="preview-"]');
+const stageRect = async (id) => { const ie = await iframeEl(); const ib = await ie.boundingBox(); const f = await ie.contentFrame(); const r = await f.evaluate((id) => { const e = document.getElementById(id) || document.querySelector(`[id$="${id}"]`); if (!e) return null; const q = e.getBoundingClientRect(); return { x: q.x, y: q.y, w: q.width, h: q.height, vw: innerWidth }; }, id); if (!r) return null; const k = ib.width / r.vw; return { x: ib.x + r.x * k, y: ib.y + r.y * k, w: r.w * k, h: r.h * k }; };
+const hiddenIn = (id) => api(`const out = {}; for (const dev of ['mobile', 'desktop']) { await editorLLMApis.breakpoints.toggle({ device: dev }); const i = await editorLLMApis.components.inspect({ componentId: '${id}', aspects: ['layout'], neighbourhood: false }); out[dev] = !!(i.members && i.members[0] && i.members[0].layout && i.members[0].layout.componentLayout && i.members[0].layout.componentLayout.hidden); } await editorLLMApis.breakpoints.toggle({ device: 'desktop' }); return out;`);
+const out = [];
+
+if (mode === 'hide') {
+  for (const id of rest) {
+    await api(`await editorLLMApis.breakpoints.toggle({ device: 'mobile' }); await editorLLMApis.components.select({ componentIds: ['${id}'] }); return 1;`);
+    await p.waitForTimeout(800);
+    let r = await stageRect(id);
+    for (let i = 0; i < 12 && r && (r.y < 200 || r.y + r.h > 950); i++) { await p.mouse.move(1500, 600); await p.mouse.wheel(0, Math.max(-900, Math.min(900, r.y - 450))); await p.waitForTimeout(500); r = await stageRect(id); }
+    if (!r) { out.push({ id, error: 'not on the mobile stage' }); continue; }
+    await p.mouse.click(r.x + r.w / 2, r.y + r.h / 2); await p.waitForTimeout(600);
+    await p.mouse.click(r.x + r.w / 2, r.y + r.h / 2, { button: 'right' }); await p.waitForTimeout(1000);
+    const hide = p.locator('text=Hide').first();
+    if (await hide.isVisible().catch(() => false)) { await hide.click(); await p.waitForTimeout(1500); } else { out.push({ id, error: 'no Hide in the context menu' }); await p.keyboard.press('Escape'); continue; }
+    out.push({ id, hidden: await hiddenIn(id) });
+  }
+} else {
+  const [id, value] = rest;
+  const read = () => api(`const out = {}; for (const dev of ['mobile', 'desktop']) { await editorLLMApis.breakpoints.toggle({ device: dev }); const f = (await editorLLMApis.appearance.getContainerBackground({ componentId: '${id}' })).background.fields; const o = f.find((x) => x.key === 'backgroundMediaOpacity'); out[dev] = o && o.value ? o.value.raw : null; } await editorLLMApis.breakpoints.toggle({ device: 'desktop' }); return out;`);
+  const before = await read();
+  await api(`await editorLLMApis.breakpoints.toggle({ device: 'mobile' }); await editorLLMApis.components.select({ componentIds: ['${id}'] }); return 1;`);
+  await p.waitForTimeout(1500);
+  await p.getByText('Replace Background', { exact: true }).first().click(); await p.waitForTimeout(2500);
+  const inp = p.locator('input[value="100"], input[value="' + Math.round(Number(before.mobile ?? 1) * 100) + '"]').first();
+  await inp.click({ clickCount: 3 }); await p.keyboard.type(String(value)); await p.keyboard.press('Enter'); await p.waitForTimeout(2000);
+  await p.keyboard.press('Escape').catch(() => {});
+  out.push({ id, before, after: await read() });
+}
+await api(`await editorLLMApis.breakpoints.toggle({ device: 'desktop' }); await editorLLMApis.site.save(); return 1;`);
+out.push({ isPublished: await api(`return (await editorLLMApis.site.getStatus()).isPublished;`) });
+console.log(JSON.stringify(out));
+await b.close();

package/skills/wix-harmony-editor/scripts/copy/preview-widths.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Screenshot the editor Preview at exact viewport widths (desktop slider), plus the source
+// at the same widths, and optionally check that every element scales with the width.
+//
+//   node scripts/copy/preview-widths.mjs <sourceUrl> <outDir> --widths 1920,1440,1280,1024,768
+//        [--scale-check <sectionId>]
+//
+// Writes <outDir>/h-<w>.png (Harmony, full page) and <outDir>/s-<w>.png (source, full page).
+// The Preview width slider ([data-hook="slider-handle"], aria-valuenow) only renders while
+// the window is >= ~1300px wide; the script widens the window as needed, clicks the track
+// near the target and steps with the arrow keys to the exact width.
+// --scale-check compares every direct child of <sectionId> between the first two widths:
+// in a spx-scaled copy each box must equal box * (w2/w1). Any element listed has a px value
+// (line-height, height, margin) that does not scale and will break other screen sizes.
+import { chromium } from 'playwright';
+import { hideScrollbars } from './hide-scrollbars.mjs';
+import fs from 'fs';
+
+const args = process.argv.slice(2);
+const opt = (n, d) => { const i = args.indexOf(`--${n}`); return i >= 0 ? args[i + 1] : d; };
+const [sourceUrl, out] = args.filter((a, i) => !a.startsWith('--') && !(i > 0 && args[i - 1].startsWith('--')));
+const widths = String(opt('widths', '1920,1440,1280,1024')).split(',').map(Number);
+const checkId = opt('scale-check', null);
+if (!sourceUrl || !out) { console.error('usage: preview-widths.mjs <sourceUrl> <outDir> --widths a,b,c [--scale-check <sectionId>]'); process.exit(2); }
+fs.mkdirSync(out, { recursive: true });
+
+const b = await chromium.connectOverCDP(`http://127.0.0.1:${process.env.PW_PORT || 9333}`);
+const ctx = b.contexts()[0];
+const p = b.contexts().flatMap((c) => c.pages()).find((x) => x.url().includes('editor.wix.com/edit/'));
+if (!p) { console.error('No Harmony editor page is open.'); process.exit(3); }
+await hideScrollbars(p); // the Preview frame must not lose 15 px to a classic scrollbar
+const pubBefore = await p.evaluate(async () => { const a = await repluggableAppDebug.host.getAPI({ name: 'RunEditorLLMCodeToolAPI', public: true, layer: 'DATA_SERVICE' }); const r = await a.execute({ code: 'return (await editorLLMApis.site.getStatus()).isPublished;' }, { biParams: {} }); return JSON.parse(r.items[0].content).result; });
+if (!(await p.getByText('Edit Site', { exact: true }).first().isVisible().catch(() => false))) { await p.getByText('Preview', { exact: true }).first().click(); await p.waitForTimeout(7000); }
+const siteFrame = async () => { for (const f of p.frames()) { const ok = await f.evaluate(() => !!document.getElementById('SITE_CONTAINER')).catch(() => false); if (ok) { const fe = await f.frameElement().catch(() => null); if (fe) return { f, box: await fe.boundingBox() }; } } return null; };
+const res = [], rects = {};
+for (const w of widths) {
+  await p.setViewportSize({ width: Math.max(w + 84, 1300), height: 1100 });
+  await p.waitForTimeout(1500);
+  await p.mouse.move(200, 20); await p.waitForTimeout(800);
+  let tr = null;
+  for (let i = 0; i < 20 && !tr; i++) { tr = await p.evaluate(() => { const h = document.querySelector('[data-hook="slider-handle"]'); if (!h) return null; const r = h.parentElement.getBoundingClientRect(); return r.width ? { x: r.x, w: r.width, y: r.y + r.height / 2 } : null; }); if (!tr) await p.waitForTimeout(500); }
+  if (!tr) throw new Error('Preview width slider not found');
+  const val = () => p.evaluate(() => Number(document.querySelector('[data-hook="slider-handle"]').getAttribute('aria-valuenow')));
+  const max = await p.evaluate(() => Number(document.querySelector('[data-hook="slider-handle"]').getAttribute('aria-valuemax')));
+  await p.mouse.click(tr.x + Math.max(1, Math.min(tr.w - 1, ((w - 390) / (max - 390)) * tr.w)), tr.y);
+  await p.waitForTimeout(800);
+  for (let i = 0; i < 400; i++) { const v = await val(); if (v === w) break; await p.keyboard.press(v < w ? 'ArrowRight' : 'ArrowLeft'); }
+  await p.waitForTimeout(3000);
+  let fr = await siteFrame();
+  const docH = await fr.f.evaluate(() => document.documentElement.scrollHeight);
+  if (checkId) rects[w] = await fr.f.evaluate((id) => { const s = document.getElementById(id); if (!s) return null; const sr = s.getBoundingClientRect(); const o = { _section: [0, 0, sr.width, sr.height] }; for (const e of s.querySelectorAll('[id^="comp-"]')) { const q = e.getBoundingClientRect(); if (q.width && e.parentElement.closest('[id^="comp-"]') === s) o[e.id] = [q.x - sr.x, q.y - sr.y, q.width, q.height]; } return o; }, checkId);
+  await p.setViewportSize({ width: Math.max(w + 84, 1300), height: Math.min(Math.round(fr.box.y + docH + 20), 8000) });
+  await p.waitForTimeout(2500);
+  fr = await siteFrame();
+  await p.screenshot({ path: `${out}/h-${w}.png`, clip: { x: fr.box.x, y: fr.box.y, width: fr.box.width, height: Math.min(docH, 8000 - fr.box.y) } });
+  res.push({ w, slider: await val(), frameW: Math.round(fr.box.width), docH });
+}
+await p.getByText('Edit Site', { exact: true }).first().click().catch(() => {});
+await p.waitForTimeout(2500);
+await p.setViewportSize({ width: 1600, height: 1000 });
+const s = await ctx.newPage();
+// a local copy is compared OFFLINE: live third-party widgets (order popups, chat) would paint over it
+if (/^https?:\/\/(127\.0\.0\.1|localhost)[:/]/.test(sourceUrl)) { const origin = new URL(sourceUrl).origin; await s.route('**/*', (r) => (r.request().url().startsWith(origin) ? r.continue() : r.abort())); }
+for (const w of widths) { await s.setViewportSize({ width: w, height: 1000 }); await s.goto(sourceUrl, { waitUntil: 'networkidle', timeout: 90000 }); await s.waitForTimeout(1200); await s.screenshot({ path: `${out}/s-${w}.png`, fullPage: true }); }
+await s.close();
+let scaleDeviations = null;
+if (checkId && widths.length > 1 && rects[widths[0]] && rects[widths[1]]) {
+  const [a, c] = widths, k = c / a; scaleDeviations = [];
+  for (const id of Object.keys(rects[a])) { const A = rects[a][id], C = rects[c][id]; if (!C) continue; const d = [C[0] - A[0] * k, C[1] - A[1] * k, C[2] - A[2] * k, C[3] - A[3] * k].map(Math.round); if (d.some((v) => Math.abs(v) > 3)) scaleDeviations.push({ id, at: [a, A.map(Math.round)], [c]: C.map(Math.round), delta: d }); }
+}
+const pubAfter = await p.evaluate(async () => { const a = await repluggableAppDebug.host.getAPI({ name: 'RunEditorLLMCodeToolAPI', public: true, layer: 'DATA_SERVICE' }); const r = await a.execute({ code: 'return (await editorLLMApis.site.getStatus()).isPublished;' }, { biParams: {} }); return JSON.parse(r.items[0].content).result; });
+console.log(JSON.stringify({ res, scaleDeviations, published: { before: pubBefore, after: pubAfter } }));
+await b.close();