@trueclone/cli 0.1.0 → 0.3.0

package/scripts/next.mjs

@@ -15,7 +15,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import net from 'node:net';
-import { parse } from 'parse5';
+import { parse, serialize } from 'parse5';
 import { fileURLToPath as toPath } from 'node:url';
 import { parseArgs } from './lib.mjs';
 
@@ -30,13 +30,17 @@ const cloneDir = path.join(root, 'clone');
 const out = path.join(root, 'next');
 const port = Number(flags.port || 3100);
 
-// Versions: motion libraries pinned to what the verified HTML clone loads, so behaviour is identical.
+// Two kinds of clone. A hand-built one (styles.css + one script.js using GSAP/Lenis/Swiper/three from npm) is
+// converted section by section; a seeded one (trueclone seed: the original's own stylesheets, trueclone's players, a
+// script.js and the libraries it vendored) goes through seededApp() and needs no motion library from npm.
+const seeded = await fs.stat(path.join(cloneDir, 'css')).then(() => true, () => false);
+// Versions: motion libraries pinned to what the verified hand-built HTML clone loads, so behaviour is identical.
 const PKG = {
   name: `${name}-next`, private: true, version: '0.1.0',
   scripts: { dev: 'next dev', build: 'next build', start: `next start -p ${port}` },
   dependencies: {
     next: '16.4.0', react: '19.3.0', 'react-dom': '19.3.0',
-    gsap: '3.13.0', lenis: '1.1.18', swiper: '11.2.6', three: '0.128.0',
+    ...(seeded ? {} : { gsap: '3.13.0', lenis: '1.1.18', swiper: '11.2.6', three: '0.128.0' }),
     clsx: '2.1.1', 'tailwind-merge': '3.7.0',
   },
   devDependencies: {
@@ -48,12 +52,19 @@ const PKG = {
 // ---------------- HTML -> JSX ----------------
 const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
 const RENAME = {
-  class: 'className', for: 'htmlFor', tabindex: 'tabIndex', readonly: 'readOnly', maxlength: 'maxLength', minlength: 'minLength',
+  class: 'className', for: 'htmlFor', tabindex: 'tabIndex', readonly: 'readOnly', nomodule: 'noModule', formnovalidate: 'formNoValidate', itemscope: 'itemScope', maxlength: 'maxLength', minlength: 'minLength',
   crossorigin: 'crossOrigin', autoplay: 'autoPlay', playsinline: 'playsInline', srcset: 'srcSet', autocomplete: 'autoComplete',
   enctype: 'encType', colspan: 'colSpan', rowspan: 'rowSpan', contenteditable: 'contentEditable', spellcheck: 'spellCheck',
   novalidate: 'noValidate', allowfullscreen: 'allowFullScreen', frameborder: 'frameBorder', inputmode: 'inputMode', datetime: 'dateTime',
+  cellpadding: 'cellPadding', cellspacing: 'cellSpacing', charset: 'charSet', accesskey: 'accessKey', usemap: 'useMap',
+  formaction: 'formAction', marginwidth: 'marginWidth', marginheight: 'marginHeight', hreflang: 'hrefLang', srclang: 'srcLang',
+  srcdoc: 'srcDoc', referrerpolicy: 'referrerPolicy', fetchpriority: 'fetchPriority', enterkeyhint: 'enterKeyHint',
+  itemprop: 'itemProp', itemscope: 'itemScope', itemtype: 'itemType', 'accept-charset': 'acceptCharset', 'http-equiv': 'httpEquiv',
 };
-const BOOL = new Set(['muted', 'loop', 'playsinline', 'autoplay', 'controls', 'disabled', 'checked', 'required', 'hidden', 'novalidate', 'readonly', 'multiple', 'selected', 'allowfullscreen']);
+// Legacy presentational attributes (email-style tables) that React has no typed prop for: passed through a spread,
+// which React renders as-is and TypeScript doesn't reject.
+const LEGACY = new Set(['valign', 'bgcolor', 'background', 'nowrap', 'hspace', 'vspace', 'clear', 'char', 'charoff', 'compact', 'frame', 'rules', 'axis']);
+const BOOL = new Set(['muted', 'loop', 'playsinline', 'autoplay', 'controls', 'disabled', 'checked', 'required', 'hidden', 'novalidate', 'readonly', 'multiple', 'selected', 'allowfullscreen', 'open', 'default', 'reversed', 'async', 'defer', 'nomodule', 'formnovalidate', 'inert', 'itemscope']);
 const camel = (s) => s.replace(/[-:]([a-z])/g, (m, c) => c.toUpperCase());
 const styleObject = (css) => {
   const o = {};
@@ -73,30 +84,64 @@ function jsxAttrs(node, inSvg) {
   const parts = [];
   for (const a of node.attrs || []) {
     if (/^on[a-z]+$/.test(a.name)) continue; // inline handlers are strings; the motion script owns behaviour
-    if (a.name === 'style') { usesStyle = true; parts.push(`style={${JSON.stringify(styleObject(a.value))} as CSSProperties}`); continue; }
-    if (BOOL.has(a.name) && (a.value === '' || a.value === a.name)) { parts.push(RENAME[a.name] || a.name); continue; }
+    // an input's value/checked are its starting state here; as plain props React would make the field read-only
+    if (node.tagName === 'input' && a.name === 'value') { parts.push(attrString('defaultValue', a.value)); continue; }
+    if (node.tagName === 'input' && a.name === 'checked') { parts.push('defaultChecked'); continue; }
+    if (LEGACY.has(a.name) && !inSvg) { parts.push(`{...{ ${JSON.stringify(a.name)}: ${JSON.stringify(a.value)} }}`); continue; }
+    // url(assets/…) in an inline style resolves against the page in the clone; the app serves assets at /assets
+    if (a.name === 'style') { usesStyle = true; parts.push(`style={${JSON.stringify(styleObject(a.value.replace(/url\((['"]?)(?:\.\.\/)?assets\//g, (m, q) => `url(${q}/assets/`)))} as CSSProperties}`); continue; }
+    // SVG elements have no typed boolean props (hidden), so they go through the spread too
+    if (BOOL.has(a.name) && (a.value === '' || a.value === a.name)) { parts.push(inSvg ? `{...{ ${JSON.stringify(a.name)}: true }}` : RENAME[a.name] || a.name); continue; }
     let n = RENAME[a.name] || a.name;
     if (!RENAME[a.name] && inSvg && !n.startsWith('data-') && !n.startsWith('aria-')) n = camel(n);
     if (n === 'xmlns:xlink') continue;
+    // an empty src/srcset/poster makes the browser request the page itself (React logs an error for each); an
+    // empty href means "this page", which # also does without the request
+    if (['src', 'srcSet', 'poster'].includes(n) && a.value === '') continue;
+    if (n === 'href' && a.value === '') { parts.push('href="#"'); continue; }
     const v = ['src', 'href', 'poster', 'srcSet'].includes(n) ? fixUrl(a.value) : a.value;
+    // React types these as numbers: tabIndex="0" fails type-checking, tabIndex={0} is the same attribute
+    if (['tabIndex', 'colSpan', 'rowSpan', 'maxLength', 'minLength', 'span', 'size', 'cols', 'rows'].includes(n) && /^-?\d+$/.test(v)) { parts.push(`${n}={${v}}`); continue; }
     parts.push(attrString(n, v));
   }
   return parts.length ? ' ' + parts.join(' ') : '';
 }
 
-function toJsx(node, depth, inSvg = false) {
+// JSX trims and collapses whitespace that HTML renders, so text is written to keep exactly what the browser showed:
+// verbatim where white-space is preserved (code samples), elsewhere with its edge spaces as {" "}
+const BLOCK = new Set(['address', 'article', 'aside', 'blockquote', 'body', 'dd', 'details', 'dialog', 'div', 'dl', 'dt', 'fieldset', 'figcaption', 'figure', 'footer', 'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'head', 'header', 'hr', 'html', 'li', 'main', 'nav', 'ol', 'p', 'pre', 'section', 'summary', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'tr', 'ul']);
+const SPACE = '{" "}';
+const keepsWhitespace = (node) => ['pre', 'textarea', 'listing', 'xmp'].includes(node.tagName)
+  || (node.attrs || []).some((a) => (a.name === 'class' && /(^|\s)whitespace-(pre|break-spaces)/.test(a.value)) || (a.name === 'style' && /white-space:\s*(pre|break-spaces)/.test(a.value)));
+const textJsx = (s) => (/[{}<>&"']/.test(s) ? `{${JSON.stringify(s)}}` : s);
+
+function toJsx(node, depth, inSvg = false, inPre = false) {
   const pad = '  '.repeat(depth);
   if (node.nodeName === '#comment') return '';
   if (node.nodeName === '#text') {
-    if (!node.value.trim()) return node.value.includes('\n') ? '' : ' ';
+    if (inPre) return `{${JSON.stringify(node.value)}}`;
+    if (!node.value.trim()) {
+      // whitespace between two inline things renders as one space; next to a block, or at an edge, it renders nothing
+      const sibs = node.parentNode?.childNodes || [];
+      const i = sibs.indexOf(node);
+      const prev = sibs[i - 1], next = sibs[i + 1];
+      return prev && next && !BLOCK.has(prev.tagName) && !BLOCK.has(next.tagName) ? SPACE : '';
+    }
     const text = node.value.replace(/\s+/g, ' ');
-    return /[{}<>&"']/.test(text) ? `{${JSON.stringify(text)}}` : text;
+    return `${/^\s/.test(text) ? SPACE : ''}${textJsx(text.trim())}${/\s$/.test(text) ? SPACE : ''}`;
   }
   if (['script', 'noscript', 'style'].includes(node.nodeName)) return '';
   const tag = node.tagName;
   const svg = inSvg || tag === 'svg';
+  const pre = inPre || keepsWhitespace(node);
   const attrs = jsxAttrs(node, svg);
-  const kids = (node.childNodes || []).map((c) => toJsx(c, depth + 1, svg)).filter((s) => s !== '');
+  // a host with a declarative shadow root (<template shadowrootmode>): the browser's HTML parser builds the shadow
+  // root from the streamed markup, React must not touch the inside, so the host's content is emitted as raw HTML
+  if ((node.childNodes || []).some((c) => c.tagName === 'template' && (c.attrs || []).some((a) => a.name === 'shadowrootmode'))) {
+    const inner = serialize(node).replace(/url\((['"]?)(?:\.\.\/)?assets\//g, (m, q) => `url(${q}/assets/`).replace(/(src|href|poster)="assets\//g, '$1="/assets/');
+    return `${pad}<${tag}${attrs} suppressHydrationWarning dangerouslySetInnerHTML={{ __html: ${JSON.stringify(inner)} }} />`;
+  }
+  const kids = (node.childNodes || []).map((c) => toJsx(c, depth + 1, svg, pre)).filter((s) => s !== '');
   if (VOID.has(tag) || !kids.length) return `${pad}<${tag}${attrs} />`;
   const inline = kids.every((k) => !k.startsWith('  ')) && kids.join('').length < 120;
   if (inline) return `${pad}<${tag}${attrs}>${kids.map((k) => k.trim() || ' ').join('')}</${tag}>`;
@@ -121,12 +166,14 @@ await fs.rm(path.join(out, 'app'), { recursive: true, force: true });
 await fs.rm(path.join(out, 'components', 'site'), { recursive: true, force: true });
 for (const d of ['app', 'components/site', 'lib', 'styles', 'public']) await fs.mkdir(path.join(out, d), { recursive: true });
 
+let components = [];
+if (seeded) components = await seededApp();
+else {
 // Sections: everything before <main> is "chrome" (nav, menu, intro, cursor); each child of <main> is a section.
 const mainEl = find(body, 'main');
 const chrome = els(body).filter((e) => e !== mainEl && e.tagName !== 'script');
 const sections = mainEl ? els(mainEl) : [];
 const used = new Set();
-const components = [];
 const writeComponent = async (compName, nodes, depth = 2) => {
   usesStyle = false;
   const jsx = nodes.map((n) => toJsx(n, depth)).filter(Boolean).join('\n');
@@ -249,12 +296,29 @@ ${components.map((c) => `        <${c} />`).join('\n')}
   );
 }
 `);
+}
 
 // Assets, design system docs, config
 await fs.rm(path.join(out, 'public', 'assets'), { recursive: true, force: true });
 await fs.cp(path.join(cloneDir, 'assets'), path.join(out, 'public', 'assets'), { recursive: true });
 for (const f of ['DESIGN.md', 'design-tokens.json']) await fs.copyFile(path.join(root, f), path.join(out, f)).catch(() => {});
 await fs.writeFile(path.join(out, 'package.json'), JSON.stringify(PKG, null, 2) + '\n');
+// custom elements (<code-island>, <swiper-container>) have no JSX type: declared here, or `next build` fails
+const custom = new Set();
+(function walk(n) { if (n.tagName && n.tagName.includes('-')) custom.add(n.tagName); for (const c of n.childNodes || []) walk(c); })(body);
+if (custom.size) {
+  await fs.writeFile(path.join(out, 'custom-elements.d.ts'), `// Generated by scripts/next.mjs: the page's custom elements, typed for JSX.
+import type { DetailedHTMLProps, HTMLAttributes } from 'react';
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+${[...custom].map((t) => `      ${JSON.stringify(t)}: DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & Record<string, unknown>;`).join('\n')}
+    }
+  }
+}
+`);
+} else await fs.rm(path.join(out, 'custom-elements.d.ts'), { force: true });
 await fs.writeFile(path.join(out, 'postcss.config.mjs'), "export default { plugins: { '@tailwindcss/postcss': {} } };\n");
 await fs.writeFile(path.join(out, 'next.config.mjs'), `import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -280,11 +344,228 @@ await fs.writeFile(path.join(out, 'components.json'), JSON.stringify({
 }, null, 2) + '\n');
 await fs.writeFile(path.join(out, 'lib', 'utils.ts'), "import { clsx, type ClassValue } from 'clsx';\nimport { twMerge } from 'tailwind-merge';\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n");
 await fs.writeFile(path.join(out, '.gitignore'), 'node_modules/\n.next/\nnext-env.d.ts\n*.tsbuildinfo\n');
-console.log(`generated ${path.relative(process.cwd(), out)}: ${components.length} section components + SiteChrome + SiteMotion`);
+console.log(`generated ${path.relative(process.cwd(), out)} (${seeded ? 'seeded clone' : 'hand-built clone'}): ${components.length} components + ${seeded ? 'SiteScripts' : 'SiteChrome + SiteMotion'}`);
+
+// ---------------- Seeded clones ----------------
+// The page is the original's markup and stylesheets (trueclone seed), so the app keeps them as they are:
+// - the stylesheets and inline <style> blocks of <head>, in their order, after the shadcn theme; Tailwind's own class
+//   scanning is limited to components/ui, because the original's compiled CSS already defines every class in the
+//   markup and a second build from a different theme would compete with it;
+// - <html> and <body> attributes (font-variable classes, dark mode, color-scheme);
+// - the largest body child is split at its first element with 3+ children: each of those becomes a component, the
+//   wrappers around them stay in the page with their classes; other body children are components of their own;
+// - trueclone's players and script.js are served from public/ and run in order after hydration, with the data
+//   blocks they read (script type="application/json") rendered in the page.
+async function seededApp() {
+  const attrsOf = (n) => Object.fromEntries((n.attrs || []).map((a) => [a.name, a.value]));
+  // styles
+  await fs.mkdir(path.join(out, 'styles', 'site'), { recursive: true });
+  const imports = [];
+  let inline = 0, usesTailwind = false;
+  // <style> blocks (and stylesheet links) can sit inside <body> too, anywhere in the tree: same cascade, so they
+  // follow the head's in document order
+  const bodyStyles = [];
+  (function walk(n) { for (const c of n.childNodes || []) { if (c.tagName === 'style' || c.tagName === 'link') bodyStyles.push(c); else walk(c); } })(body);
+  for (const e of [...els(head), ...bodyStyles]) {
+    const a = attrsOf(e);
+    let css = null, file = null;
+    if (e.tagName === 'link' && a.rel === 'stylesheet' && a.href && !/^(https?:)?\/\//.test(a.href)) {
+      css = await fs.readFile(path.join(cloneDir, a.href), 'utf8').catch(() => null);
+      file = path.basename(a.href);
+    } else if (e.tagName === 'style') {
+      css = (e.childNodes || []).map((c) => c.value || '').join('');
+      file = `inline-${++inline}.css`;
+    }
+    if (css === null) continue;
+    // stylesheets lived in clone/css/ (assets at ../assets/), inline blocks in the page (assets at assets/)
+    css = css.replace(/url\((['"]?)(?:\.\.\/)?assets\//g, (m, q) => `url(${q}/assets/`);
+    usesTailwind ||= /--tw-|tailwindcss v\d/.test(css);
+    await fs.writeFile(path.join(out, 'styles', 'site', file), css);
+    imports.push(`import '../styles/site/${file}';`);
+  }
+  // globals.css = the shadcn theme only; the original's stylesheets are imported by layout.tsx AFTER it, so they come
+  // later in the cascade and win every tie (same layer names, same variable names: the original is often Tailwind too)
+  const theme = await fs.readFile(path.join(root, 'globals.css'), 'utf8').catch(() => '@import "tailwindcss";\n');
+  // Tailwind's preflight resets what the browser draws by default (form controls, headings, lists); an original built
+  // without Tailwind relies on those defaults, so its clone gets Tailwind's theme and utilities but not the reset
+  const tailwind = usesTailwind ? '@import "tailwindcss" source(none);'
+    : '/* no preflight: the original was not built with Tailwind and relies on browser defaults */\n@layer theme, base, components, utilities;\n@import "tailwindcss/theme.css" layer(theme);\n@import "tailwindcss/utilities.css" layer(utilities) source(none);';
+  const scoped = theme.replace('@import "tailwindcss";', `${tailwind}\n@source "../components/ui";`);
+  await fs.writeFile(path.join(out, 'app', 'globals.css'), scoped);
+  const siteCssImports = imports;
+
+  // markup
+  const SKIP_BODY = new Set(['script', 'noscript', 'next-route-announcer', 'template']);
+  const kids = els(body).filter((e) => !SKIP_BODY.has(e.tagName));
+  const size = (n) => (n.childNodes || []).reduce((s, c) => s + 1 + size(c), 0);
+  const content = kids.reduce((x, y) => (size(y) > size(x) ? y : x), kids[0]);
+  let container = content;
+  while (els(container).length < 3) {
+    const inner = els(container);
+    if (!inner.length) break;
+    container = inner.reduce((x, y) => (size(y) > size(x) ? y : x));
+  }
+  const used = new Set();
+  const names = [];
+  // names: the element's id when it has one, otherwise its tag and position (utility classes such as "mx-auto" and
+  // placeholder headings say nothing about what a section is)
+  let counter = 0;
+  const nameFor = (node, fallback) => {
+    counter++;
+    const id = attrsOf(node).id;
+    let n = id ? pascal(id) : `${pascal(node.tagName) || fallback}${String(counter).padStart(2, '0')}`;
+    if (/^\d/.test(n)) n = 'S' + n;
+    n = n.slice(0, 40) || fallback;
+    let k = n, i = 2;
+    while (used.has(k)) k = `${n}${i++}`;
+    used.add(k);
+    return k;
+  };
+  const writeComp = async (compName, node) => {
+    usesStyle = false;
+    const jsx = toJsx(node, 3);
+    const typeImport = usesStyle ? "import type { CSSProperties } from 'react';\n\n" : '';
+    await fs.writeFile(path.join(out, 'components', 'site', `${compName}.tsx`), `// Generated from clone/index.html by scripts/next.mjs. Edit the HTML clone and regenerate.\n${typeImport}export default function ${compName}() {\n  return (\n    <>\n${jsx}\n    </>\n  );\n}\n`);
+    names.push(compName);
+  };
+  // the page: wrappers kept inline down to the container, the container's children as components
+  let pageUsesStyle = false;
+  const wrap = async (node, depth) => {
+    const pad = '  '.repeat(depth);
+    if (node.nodeName === '#text' || node.nodeName === '#comment') return toJsx(node, depth);
+    usesStyle = false;
+    const attrs = jsxAttrs(node, false);
+    pageUsesStyle ||= usesStyle;
+    const children = [];
+    for (const c of node.childNodes || []) {
+      if (node === container && c.tagName) { const n = nameFor(c, 'Section'); await writeComp(n, c); children.push(`${pad}  <${n} />`); }
+      else if (c.tagName && c !== container && !c.childNodes?.some(() => false) && !(contains(c, container))) { usesStyle = false; children.push(toJsx(c, depth + 1)); pageUsesStyle ||= usesStyle; }
+      else if (c.tagName) children.push(await wrap(c, depth + 1));
+    }
+    const body = children.filter((s) => s && s.trim()).join('\n');
+    return body ? `${pad}<${node.tagName}${attrs}>\n${body}\n${pad}</${node.tagName}>` : `${pad}<${node.tagName}${attrs} />`;
+  };
+  const contains = (a, b) => { for (let n = b; n; n = n.parentNode) if (n === a) return true; return false; };
+  const pageParts = [];
+  for (const k of kids) {
+    if (k === content) pageParts.push(await wrap(k, 3));
+    else { const n = nameFor(k, 'Part'); await writeComp(n, k); pageParts.push(`      <${n} />`); }
+  }
+  // data blocks the players read, and the scripts themselves (copied to public/, run in order after hydration)
+  const scripts = els(body).filter((e) => e.tagName === 'script');
+  const dataBlocks = scripts.filter((s) => /json/.test(attrsOf(s).type || '') && attrsOf(s).id)
+    .map((s) => `      <script type="${attrsOf(s).type}" id="${attrsOf(s).id}" dangerouslySetInnerHTML={{ __html: ${JSON.stringify((s.childNodes || []).map((c) => c.value || '').join(''))} }} />`);
+  // the scripts, copied to public/ at their own relative paths (a script that loads a sibling file keeps working),
+  // with the files their import statements and import() calls name; a module script stays a module
+  // in document order: files (copied) and inline scripts (run as written); data blocks are rendered in the page
+  const scriptTags = scripts.map((s) => ({ ...attrsOf(s), code: (s.childNodes || []).map((c) => c.value || '').join('') }))
+    .filter((a) => !/json/.test(a.type || '') && (a.src ? !/^(https?:)?\/\//.test(a.src) : a.code.trim()));
+  const copied = new Set();
+  const copyScript = async (rel, depth = 0) => {
+    const clean = rel.split(/[?#]/)[0].replace(/^\.\//, '');
+    if (copied.has(clean) || depth > 4) return;
+    copied.add(clean);
+    const from = path.join(cloneDir, clean);
+    const text = await fs.readFile(from, 'utf8').catch(() => null);
+    if (text === null) { console.warn(`WARNING script referenced but not in clone/: ${clean}`); return; }
+    await fs.mkdir(path.dirname(path.join(out, 'public', clean)), { recursive: true });
+    await fs.copyFile(from, path.join(out, 'public', clean));
+    for (const m of text.matchAll(/(?:^|[^\w$.])import\s*(?:[\w$*{},\s]+from\s*)?['"]([^'"]+)['"]|import\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+      const spec = m[1] || m[2];
+      if (!spec || /^(https?:)?\/\//.test(spec) || !/^[./]/.test(spec)) continue;
+      await copyScript(path.posix.join(path.posix.dirname(clean), spec), depth + 1);
+    }
+    // a script file named in a string (new URL('vendor/three.module.min.js', here), a worker, a lazy loader)
+    for (const m of text.matchAll(/['"]([\w./-]+\.m?js)['"]/g)) {
+      const rel = path.posix.join(path.posix.dirname(clean), m[1].replace(/^\//, ''));
+      if (!copied.has(rel) && await fs.stat(path.join(cloneDir, rel)).then(() => true, () => false)) await copyScript(rel, depth + 1);
+    }
+  };
+  for (const a of scriptTags) if (a.src) await copyScript(a.src);
+  const scriptList = scriptTags.map((a) => ({ ...(a.src ? { src: '/' + a.src.split(/[?#]/)[0].replace(/^\.\//, '') } : { code: a.code }), ...(a.type === 'module' ? { type: 'module' } : {}) }));
+  await fs.writeFile(path.join(out, 'components', 'site', 'SiteScripts.tsx'), `'use client';
+// Generated by scripts/next.mjs: runs the clone's scripts (trueclone's players, inline scripts, script.js) in order,
+// once, the moment hydration is done. The HTML clone runs them as deferred scripts right after parsing; a component
+// app cannot (hydration would re-render what they change), so the files are preloaded from the first byte (see
+// layout.tsx), inserted together with async=false (ordered execution, parallel fetch), and the boot contract
+// (<html class="tc-boot">, seed) keeps script-built regions hidden until the last one has run.
+import { useLayoutEffect } from 'react';
+
+const SCRIPTS: { src?: string; code?: string; type?: string }[] = ${JSON.stringify(scriptList)};
+
+export default function SiteScripts() {
+  useLayoutEffect(() => {
+    const w = window as unknown as Record<string, unknown>;
+    if (w.__siteScripts) return; // React strict mode runs effects twice in dev
+    w.__siteScripts = true;
+    w.__tcInjected = true;
+    let last: HTMLScriptElement | null = null;
+    for (const { src, code, type } of SCRIPTS) {
+      const s = document.createElement('script');
+      if (type) s.type = type;
+      if (src) { s.src = src; s.async = false; } else { s.textContent = code || ''; }
+      document.body.appendChild(s);
+      if (src) last = s;
+    }
+    const boot = () => { const b = (w as { tcBoot?: { release: () => void } }).tcBoot; if (b) b.release(); else requestAnimationFrame(() => document.documentElement.classList.remove('tc-boot')); };
+    if (last) last.addEventListener('load', boot), last.addEventListener('error', boot); else boot();
+  }, []);
+  return null;
+}
+`);
+  // layout: the original's <html> and <body> attributes
+  usesStyle = false;
+  const htmlAttrs = jsxAttrs(htmlEl, false);
+  const bodyAttrs = jsxAttrs(body, false);
+  const layoutStyle = usesStyle;
+  await fs.writeFile(path.join(out, 'app', 'layout.tsx'), `// Generated by scripts/next.mjs
+import type { Metadata } from 'next';
+${layoutStyle ? "import type { CSSProperties } from 'react';\n" : ''}import './globals.css';
+// the original's stylesheets, in its <head> order, after the theme
+${siteCssImports.join('\n')}
+
+export const metadata: Metadata = {
+  title: ${JSON.stringify(title)},
+  robots: { index: false, follow: false },
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html${htmlAttrs} suppressHydrationWarning>
+      <head>
+        {/* the clone's scripts start downloading with the page; SiteScripts runs them the moment hydration is done */}
+${scriptList.filter((s) => s.src).map((s) => `        <link rel="${s.type === 'module' ? 'modulepreload' : 'preload'}" href=${JSON.stringify(s.src)}${s.type === 'module' ? '' : ' as="script"'} />`).join('\n')}
+      </head>
+      <body${bodyAttrs} suppressHydrationWarning>{children}</body>
+    </html>
+  );
+}
+`);
+  await fs.writeFile(path.join(out, 'app', 'page.tsx'), `// Generated by scripts/next.mjs from a seeded clone: the original's structure, one component per section.
+${pageUsesStyle ? "import type { CSSProperties } from 'react';\n" : ''}${names.map((c) => `import ${c} from '@/components/site/${c}';`).join('\n')}
+import SiteScripts from '@/components/site/SiteScripts';
+
+export default function Page() {
+  return (
+    <>
+${pageParts.join('\n')}
+${dataBlocks.join('\n')}
+      <SiteScripts />
+    </>
+  );
+}
+`);
+  return names;
+}
 
 // ---------------- Install / build / verify ----------------
+// npm/npx are .cmd files on Windows and need a shell; Node warns (DEP0190) when a shell gets separate arguments, so
+// build one quoted command line there instead
+const spawnCmd = (cmd, args, opts = {}) => (process.platform === 'win32'
+  ? spawn([cmd, ...args].map((a) => (/[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(' '), { ...opts, shell: true })
+  : spawn(cmd, args, opts));
 const run = (cmd, args, opts = {}) => new Promise((resolve, reject) => {
-  const p = spawn(cmd, args, { cwd: out, stdio: 'inherit', shell: process.platform === 'win32', ...opts });
+  const p = spawnCmd(cmd, args, { cwd: out, stdio: 'inherit', ...opts });
   p.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} ${args.join(' ')} exited ${code}`))));
 });
 if (flags.install || flags.build || flags.verify) await run('npm', ['install', '--no-audit', '--no-fund']);
@@ -301,7 +582,7 @@ const freePort = async (start) => {
 if (flags.verify) {
   const verifyPort = await freePort(port);
   if (verifyPort !== port) console.warn(`port ${port} is busy (another server?) - verifying on ${verifyPort}`);
-  const server = spawn('npx', ['next', 'start', '-p', String(verifyPort)], { cwd: out, shell: process.platform === 'win32', stdio: 'ignore' });
+  const server = spawnCmd('npx', ['next', 'start', '-p', String(verifyPort)], { cwd: out, stdio: 'ignore' });
   const url = `http://127.0.0.1:${verifyPort}/`;
   for (let i = 0; i < 60; i++) { try { if ((await fetch(url)).ok) break; } catch { /* starting */ } await new Promise((r) => setTimeout(r, 1000)); }
   const lab = path.resolve('.');

package/scripts/owned.mjs

@@ -0,0 +1,66 @@
+// Which regions of the clone does script.js own? The seed carries the original's markup in its post-script state; a
+// script that rebuilds a region at boot (a hero grid, a card layout it places, a slider it wraps) replaces that
+// markup. This loads the clone twice, with its scripts blocked and with them running, and lists the top-level sections
+// whose structure the scripts changed: those are the agent's, and the seed's recorded players must not run there
+// (hand them over, see SKILL.md). Runs again after each build round.
+// usage: node scripts/owned.mjs <name> [--viewport desktop]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, serve, settle, sectionsOf } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: trueclone owned <name> [--viewport desktop]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const vp = VIEWPORTS.find((v) => v.name === (flags.viewport || 'desktop'));
+const server = await serve(path.join(root, 'clone'));
+const browser = await openBrowser(flags.cdp);
+
+// a structural signature per top-level section: element count, tag sequence hash, inline-style count
+const signatures = () => {
+  const hash = (s) => { let h = 2166136261; for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619); } return (h >>> 0).toString(16); };
+  const unwrap = (el) => { let n = el; while (n.children.length === 1 && !n.matches('header,footer,main,section,nav,article,aside')) n = n.children[0]; return n; };
+  const tops = [...unwrap(document.body).children].filter((el) => !['SCRIPT', 'STYLE', 'TEMPLATE', 'LINK', 'NOSCRIPT'].includes(el.tagName));
+  return tops.map((el) => {
+    const r = el.getBoundingClientRect();
+    const all = el.getElementsByTagName('*');
+    return { label: `${el.tagName.toLowerCase()}${el.id ? `#${el.id}` : ''}${el.classList.length ? `.${[...el.classList].slice(0, 2).join('.')}` : ''}`, y: Math.round(r.top + scrollY), elements: all.length, tags: hash([...all].map((e) => e.tagName).join(',')), styled: [...all].filter((e) => e.hasAttribute('style')).length, shadow: [...all].some((e) => e.shadowRoot) };
+  });
+};
+let before, after;
+try {
+  const url = `${server.url}index.html`;
+  const a = await newPage(browser, vp);
+  await a.page.route(/\.m?js(\?|$)/, (r) => r.abort());
+  await a.page.goto(url, { waitUntil: 'load', timeout: 60000 });
+  await a.page.waitForTimeout(500);
+  before = await a.page.evaluate(signatures);
+  await a.context.close();
+  const b = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+  await b.page.goto(url, { waitUntil: 'load', timeout: 60000 });
+  await settle(b.page);
+  after = await b.page.evaluate(signatures);
+  await b.context.close();
+} finally {
+  if (!flags.cdp) await browser.close();
+  server.close();
+}
+const rows = before.map((s, i) => {
+  const t = after[i] || {};
+  const changed = !t.label ? 'removed' : t.elements !== s.elements || t.tags !== s.tags ? `rebuilt (${s.elements} → ${t.elements} elements)` : t.styled !== s.styled ? `restyled (${s.styled} → ${t.styled} inline styles)` : null;
+  return { section: s.label, y: s.y, before: s.elements, after: t.elements ?? null, changed };
+});
+for (const t of after.slice(before.length)) rows.push({ section: t.label, y: t.y, before: 0, after: t.elements, changed: 'added by a script' });
+await fs.mkdir(path.join(root, 'compare'), { recursive: true });
+await fs.writeFile(path.join(root, 'compare', 'owned.json'), JSON.stringify({ at: new Date().toISOString(), viewport: vp.name, rows }, null, 2));
+// structure changed: the script owns the section; only inline styles changed: it animates inside the seed's markup
+const owned = rows.filter((r) => r.changed && !r.changed.startsWith('restyled'));
+const animated = rows.filter((r) => r.changed?.startsWith('restyled'));
+console.log(owned.length ? `script.js rebuilds ${owned.length} section(s) at ${vp.name}:` : `script.js rebuilds no section at ${vp.name}: the seed's markup and players stand as they are`);
+for (const r of owned) console.log(`  ${r.section} (y ${r.y}): ${r.changed}`);
+if (owned.length) console.log('hand these over to script.js (remove the data-tc-* marks there) and hide them until boot if the original hides them too (seed --hide-until-boot).');
+if (animated.length) console.log(`animated inside the seed's markup (inline styles only): ${animated.map((r) => r.section).join(', ')}`);
+console.log(`-> ${path.relative(process.cwd(), path.join(root, 'compare', 'owned.json'))}`);

package/scripts/report.mjs

@@ -22,8 +22,8 @@ if (!meta) {
 }
 
 // Targets a clone has to meet (the same ones the skill gives the agent).
-const T = { layout: 98, statesGap: 5, motion: 95, detail: 95, hovers: 90 };
-const mark = (ok) => (ok === null ? '–' : ok ? 'pass' : '**below target**');
+const T = { layout: 98, statesGap: 5, motion: 95, detail: 95, hovers: 90, load: 95 };
+const mark = (ok, acceptedNote) => (ok === null ? '–' : ok ? 'pass' : acceptedNote ? `accepted (${acceptedNote})` : '**below target**');
 const pct = (v) => (v === undefined || v === null ? '–' : `${v}%`);
 const VPS = ['desktop', 'tablet', 'mobile'];
 
@@ -34,35 +34,65 @@ const curves = Object.fromEntries(await Promise.all(VPS.map(async (v) => [v, awa
 const interact = await read('compare/interact/report.json');
 const hovers = await read('compare/hovers.desktop.json');
 const detail = await read('compare/detail.json');
+const load = await read('compare/load.json');
+const times = await read('compare/score-times.json');
+const drift = await read('compare/drift.json');
 const motionInv = await read('reference/motion.desktop.json');
+// notes.md: the agent's "Accepted differences" and "Findings" come into the report; an accepted entry that names a
+// check (and optionally a width) turns that check's "below target" into "accepted"
+const notes = await fs.readFile(path.join(root, 'notes.md'), 'utf8').catch(() => '');
+const notesSection = (title) => {
+  const m = new RegExp(`^## ${title}[^\\n]*\\n([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(notes);
+  return m ? m[1].replace(/<!--[\s\S]*?-->/g, '').split('\n').map((l) => l.trim()).filter((l) => /^[-*]\s+\S/.test(l)).map((l) => l.replace(/^[-*]\s+/, '')) : [];
+};
+const accepted = notesSection('Accepted differences');
+const findings = notesSection('Findings');
+const acceptedFor = (check, vp) => accepted.filter((a) => new RegExp(`\\b${check}\\b`, 'i').test(a) && (!vp || new RegExp(`\\b${vp}\\b`, 'i').test(a) || !/\b(desktop|tablet|mobile)\b/i.test(a)));
 
 const byVp = (rep, key = 'match') => Object.fromEntries((rep?.viewports || []).map((v) => [v.viewport, v[key] ?? v.score]));
 const L = byVp(layout), V = byVp(visual), S = byVp(states), D = byVp(detail, 'score');
 const C = Object.fromEntries(VPS.map((v) => [v, curves[v]?.score]));
 
 const rows = [];
-const row = (check, values, ok, note = '') => rows.push(`| ${check} | ${VPS.map((v) => pct(values[v])).join(' | ')} | ${mark(ok)} | ${note} |`);
+// `test` is a per-width predicate (value, width) => boolean, or a ready boolean/null for single-value checks
+const row = (check, values, test, note = '') => {
+  const ok = typeof test === 'function' ? all(values, test) : test;
+  // below target, but every failing width has an accepted entry in notes.md: the decision is recorded, not hidden
+  const key = check.split(' ')[0].toLowerCase();
+  const failing = typeof test === 'function' ? present(values).filter((v) => !test(values[v], v)) : ok === false ? present(values) : [];
+  const covered = failing.length && failing.every((v) => acceptedFor(key, v).length);
+  const stale = drift?.stale && ['detail', 'hovers', 'motion', 'load', 'interactions'].includes(key) ? ' **stale capture**' : '';
+  rows.push(`| ${check} | ${VPS.map((v) => pct(values[v])).join(' | ')} | ${mark(ok, covered ? acceptedFor(key)[0].slice(0, 60) : null)}${stale} | ${note} |`);
+};
 const present = (vals) => VPS.filter((v) => vals[v] !== undefined && vals[v] !== null);
 const all = (vals, test) => (present(vals).length ? present(vals).every((v) => test(vals[v], v)) : null);
-row(`Layout (structure)`, L, all(L, (x) => x >= T.layout), `target ≥ ${T.layout}%; text and media masked`);
-if (meta.mode === 'exact') row('Layout (real pixels)', V, all(V, (x) => x >= T.layout), 'exact mode: same text and media');
-row('Scroll states', S, all(S, (x, v) => L[v] === undefined || x >= L[v] - T.statesGap), `within ${T.statesGap} points of layout`);
-row('Motion curves', C, all(C, (x) => x >= T.motion), present(C).length ? `target ≥ ${T.motion}%` : 'no motion map (no scroll or time animation to score)');
-row('Detail (styles)', D, all(D, (x) => x >= T.detail), `target ≥ ${T.detail}%; font, size, weight, line height, colour, boxes`);
+row(`Layout (structure)`, L, (x) => x >= T.layout, `target ≥ ${T.layout}%; text and media masked`);
+if (meta.mode === 'exact') row('Layout (real pixels)', V, (x) => x >= T.layout, 'exact mode: same text and media');
+row('Scroll states', S, (x, v) => L[v] === undefined || x >= L[v] - T.statesGap, `within ${T.statesGap} points of layout`);
+row('Motion curves', C, (x) => x >= T.motion, present(C).length ? `target ≥ ${T.motion}%` : 'no motion map (no scroll or time animation to score)');
+row('Detail (styles)', D, (x) => x >= T.detail, `target ≥ ${T.detail}%; font, size, weight, line height, colour, boxes`);
 row('Hovers', { desktop: hovers?.score }, hovers ? hovers.score >= T.hovers : null, `target ≥ ${T.hovers}% of the reference hover effects`);
+const LD = byVp(load, 'score');
+const tts = (side) => VPS.map((v) => load?.viewports.find((x) => x.viewport === v)).filter(Boolean).map((x) => (x[side]?.settledAt === null ? '>4000' : x[side]?.settledAt)).filter((x) => x !== undefined);
+row('Load sequence', LD, (x) => x >= T.load, present(LD).length ? `target ≥ ${T.load}%; how settled each side is at 0.25 to 4 s, cold cache, same network (settled at: reference ${tts('ref').map((x) => `${x}ms`).join(' / ') || '–'}, clone ${tts('clone').map((x) => `${x}ms`).join(' / ') || '–'})` : 'not measured (trueclone load <name>)');
 const scenarios = interact?.scenarios || [];
 const failed = scenarios.filter((s) => s.expect && !s.expect.pass);
 row('Interactions', { desktop: scenarios.length ? +(scenarios.reduce((n, s) => n + (s.score || 0), 0) / scenarios.length).toFixed(2) : undefined }, scenarios.length ? failed.length === 0 : null,
   scenarios.length ? `${scenarios.length - failed.length}/${scenarios.length} scenarios change something on both sides` : 'no interactions.json');
 
 const failing = rows.filter((r) => r.includes('below target')).length;
-const verdict = failing ? `${failing} check(s) below target` : 'every scored check meets its target';
+const acceptedCount = rows.filter((r) => r.includes('| accepted (')).length;
+const verdict = (failing ? `${failing} check(s) below target` : 'every scored check meets its target') + (acceptedCount ? ` (${acceptedCount} accepted with a reason in notes.md)` : '') + (drift?.stale ? '; the live site has changed since the capture: re-capture before trusting the live-measured checks' : '');
 
 // Weakest spots, to fix first.
 const weak = [];
 for (const v of VPS) for (const s of (layout?.viewports.find((x) => x.viewport === v)?.worstSections || []).slice(0, 2)) if (s.match < 99) weak.push(`- Layout ${v}: section "${String(s.label).slice(0, 50)}" at y ${s.y} is ${s.match}%`);
 for (const v of VPS) for (const e of (curves[v]?.entries || []).filter((x) => x.score < 90).slice(0, 3)) weak.push(`- Motion ${v}: "${e.name}" ${e.score}%${e.note ? ` (${e.note})` : ''}`);
 for (const s of failed) weak.push(`- Interaction "${s.name}": the expected change happened on ${s.expect.ref ? 'the reference' : 'neither side'}${s.expect.clone ? '' : ', not on the clone'}`);
+for (const v of (load?.viewports || []).filter((x) => x.score < T.load)) {
+  const worst = Object.entries(v.gap || {}).sort((a, b) => b[1] - a[1])[0];
+  if (worst) weak.push(`- Load ${v.viewport}: at ${worst[0]}ms the clone is ${v.clone.curve[worst[0]]}% settled, the reference ${v.ref.curve[worst[0]]}% (settled at ${v.clone.settledAt ?? '>4000'}ms vs ${v.ref.settledAt ?? '>4000'}ms)`);
+}
 for (const v of detail?.viewports || []) {
   const groups = new Map();
   for (const it of v.issues || []) { const k = it.props[0].split(' ').slice(0, 1)[0]; groups.set(k, (groups.get(k) || 0) + 1); }
@@ -92,6 +122,8 @@ const md = `# trueclone report: ${name}
 | Captured | ${meta.capturedAt} |
 | Scored | ${layout?.at || '–'}${layout?.clone && !/127\.0\.0\.1:\d+\/$/.test(layout.clone) ? ` against ${layout.clone}` : ''} |
 | Verdict | **${verdict}** |
+${times ? `| Scoring time | ${times.totalMin} min (${times.kind}${times.only ? `, only ${times.only.join(',')}` : ''}): ${Object.entries(times.steps).filter(([, s]) => s.seconds).map(([k, s]) => `${k} ${s.seconds}s`).join(', ')}${Object.values(times.steps).some((s) => /kept/.test(s.status)) ? '; unchanged checks kept from their last run' : ''} |` : ''}
+${(detail?.viewports || []).some((v) => v.unstable) || hovers?.unstable || (load?.viewports || []).some((v) => v.unstable) ? `| Not scored | ${(detail?.viewports || []).filter((v) => v.unstable).map((v) => `${v.unstable} detail probe${v.unstable > 1 ? 's' : ''} (${v.viewport})`).concat(hovers?.unstable ? [`${hovers.unstable} hover${hovers.unstable > 1 ? 's' : ''}`] : [], (load?.viewports || []).filter((v) => v.unstable).map((v) => `load ${v.viewport} (±${v.noise} between two runs)`)).join(', ')}: unstable on the reference or the clone itself (random motion, timing), excluded from the scores above |` : ''}
 
 ## Scores
 
@@ -99,8 +131,8 @@ const md = `# trueclone report: ${name}
 |---|---|---|---|---|---|
 ${rows.join('\n')}
 
-${weak.length ? `## Fix first\n\n${weak.join('\n')}\n` : '## Fix first\n\nNothing below 99% on layout, 90% on motion or failing.\n'}
-## Motion found on the reference
+${drift?.stale ? `## Stale capture\n\nThe live page differs from the capture of ${meta.capturedAt}: ${drift.viewports.filter((v) => v.stale).map((v) => `${v.viewport} ${v.livePageHeight}px tall vs ${v.capturedPageHeight}px captured, ${v.liveSections} vs ${v.capturedSections} sections`).join('; ')}. Layout and states score against the captured screenshots; detail, hovers, motion, interactions and load measure the live page and are marked stale above. Re-capture (\`trueclone capture\`, then \`states\`, \`reveals\`, \`seed --force\`) before reading them.\n\n` : ''}${accepted.length ? `## Accepted differences\n\nRecorded in notes.md with a reason; a check below target that is covered here is marked "accepted" in the table.\n\n${accepted.map((a) => `- ${a}`).join('\n')}\n\n` : ''}${weak.length ? `## Fix first\n\n${weak.join('\n')}\n` : '## Fix first\n\nNothing below 99% on layout, 90% on motion or failing.\n'}
+${findings.length ? `## Findings (tool defects met on this site)\n\n${findings.map((f) => `- ${f}`).join('\n')}\n\n` : ''}## Motion found on the reference
 
 ${motionInv ? `Libraries: ${libs.length ? libs.join(', ') : 'none (no GSAP, Lenis, Swiper or similar)'}. ScrollTriggers: ${motionInv.triggers?.length ?? 0}. Tweens created while scrolling: ${motionInv.onScroll?.length ?? 0}. CSS animations: ${(motionInv.css || []).length}.` : 'Not inventoried yet (trueclone motion <name>).'}