similarbuild 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "similarbuild",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Visual migration framework for Claude Code — clone a live page, get a paste-ready WordPress/Elementor or Shopify section file, validated and auto-corrected.",
   "type": "module",
   "bin": {

package/templates/skills/sb-inspect-live/scripts/inspect-live.mjs

@@ -29,7 +29,7 @@ Optional:
   --wait-strategy <name>  lazy-load (default) | auto | kaching-bundles | judge-me
   --max-depth <n>         DOM walk max depth (default 8).
   --max-children <n>      Max children kept per node (default 60).
-  --max-text <n>          Max chars of direct text per node (default 240).
+  --max-text <n>          Max chars of direct text per node (default 0 = no truncation; pass a positive integer to cap).
   --timeout <ms>          Per-step timeout (default 30000).
   --help                  Show this message.
 
@@ -55,7 +55,7 @@ const { values } = parseArgs({
     'output-dir': { type: 'string' },
     'max-depth': { type: 'string', default: '8' },
     'max-children': { type: 'string', default: '60' },
-    'max-text': { type: 'string', default: '240' },
+    'max-text': { type: 'string', default: '0' },
     timeout: { type: 'string', default: '30000' },
     help: { type: 'boolean', default: false },
   },
@@ -960,6 +960,12 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
   // iframes (Klaviyo embeds, recaptcha) are recorded as opaque rectangles.
   let shadowDOMTraversed = false
   let shadowRootCount = 0
+  // §V03-C — counts hosts whose shadow tree was successfully re-serialized
+  // via getHTML+parseHTMLUnsafe and re-walked into a flattened light-DOM
+  // representation. 0 means the post-render shadow-flatten phase was either
+  // unavailable, skipped, or hit zero open roots.
+  let shadowSerializedHostCount = 0
+  const warnings = []
   const externalIframes = []
   function classifyIframePurpose(src) {
     if (!src) return null
@@ -978,7 +984,7 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
   function classifySection(el) {
     const cls = (typeof el.className === 'string' ? el.className : '').toLowerCase()
     const tag = el.tagName.toLowerCase()
-    const id = (el.id || '').toLowerCase()
+    const id = (typeof el.id === 'string' ? el.id : '').toLowerCase()
     const blob = `${tag} ${cls} ${id}`
     if (/\bhero\b/.test(blob)) return 'hero'
     if (/\bbanner\b/.test(blob)) return 'banner'
@@ -1091,7 +1097,10 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
       if (n.nodeType === 3) t += n.nodeValue
     }
     t = t.replace(/\s+/g, ' ').trim()
-    if (t.length > maxText) t = `${t.slice(0, maxText)}…`
+    // §V03-B — maxText === 0 means "no truncation" (default since v0.3.0).
+    // Pre-v0.3.0 default was 240, which silently clipped policy paragraphs
+    // (privacy/terms) at ~25-36% coverage. The cap is now opt-in via flag.
+    if (maxText > 0 && t.length > maxText) t = `${t.slice(0, maxText)}…`
     return t
   }
 
@@ -1107,7 +1116,7 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
     const node = {
       tag: el.tagName.toLowerCase(),
       classes: typeof el.className === 'string' ? el.className.split(/\s+/).filter(Boolean) : [],
-      id: el.id || null,
+      id: typeof el.id === 'string' && el.id ? el.id : null,
       attrs: {},
       text: directText(el),
       bbox: bbox(el),
@@ -1239,7 +1248,7 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
   // pseudo-elements, so this filters automatically.
   const pseudoElements = []
   function pseudoSelectorFor(el) {
-    if (el.id) return `#${el.id}`
+    if (typeof el.id === 'string' && el.id) return `#${el.id}`
     const cls = typeof el.className === 'string' ? el.className.trim().split(/\s+/).filter(Boolean) : []
     if (cls.length) return `${el.tagName.toLowerCase()}.${cls.slice(0, 3).join('.')}`
     return el.tagName.toLowerCase()
@@ -1406,15 +1415,138 @@ function extractInPage({ selector, maxDepth, maxChildren, maxText }) {
   const dom = [walk(root, 0)].filter(Boolean)
   const { sectionType, sectionBoundingBox } = findSectionAndBox(root, !!selector)
 
+  // §V03-C — Shadow DOM serialization via getHTML + parseHTMLUnsafe.
+  // walk() above only sees light DOM and `.shadowRoot.children` direct.
+  // Custom elements whose shadow tree is populated by JS (Shopify
+  // <x-product-form>, <price-list>, <variant-radios>, <store-footer-menu>)
+  // expose content that the children-only walker can technically read,
+  // but `<slot>`-projected content and content composed from declarative
+  // shadow DOM gets fragmented. getHTML({ serializableShadowRoots: true })
+  // emits a single HTML string with `<template shadowrootmode="open">`
+  // declarations inline; parseHTMLUnsafe re-attaches those as live shadow
+  // roots in a parsed document, which the same walk() can then flatten
+  // uniformly. Layout (bbox/computedStyle) on the parsed doc is detached
+  // and returns UA defaults — that's an acknowledged trade-off; the
+  // structural content (tags, classes, attrs, text, src) is what makes
+  // PDP gallery/price/variants visible to the composer downstream.
+  const originalShadowRootCount = shadowRootCount
+  const originalShadowDOMTraversed = shadowDOMTraversed
+  // §V03-C — preserve a snapshot of the live-walker dom[] before any
+  // potential substitution. If the re-walk replaces dom[] with the
+  // shadow-flattened tree (which carries detached parsedDoc bboxes
+  // === {0,0,0,0}), downstream consumers that need real layout (e.g.
+  // /build-site Step 3.5e --crop-live-bbox for header/footer compare)
+  // can fall back to domLive. When substitution doesn't fire, domLive
+  // is left null and consumers use dom[] as-is.
+  let domLive = null
+  try {
+    if (typeof document.documentElement.getHTML === 'function' &&
+        typeof Document.parseHTMLUnsafe === 'function') {
+      const hostsSeen = new Set()
+      const hostsCollected = []
+      function collectHostsFrom(el) {
+        if (!el) return
+        if (el.shadowRoot && !hostsSeen.has(el)) {
+          hostsSeen.add(el)
+          hostsCollected.push(el)
+          for (const child of el.shadowRoot.children) collectHostsFrom(child)
+        }
+        for (const child of el.children) collectHostsFrom(child)
+      }
+      collectHostsFrom(document.documentElement)
+
+      if (hostsCollected.length > 0) {
+        const html = document.documentElement.getHTML({
+          serializableShadowRoots: true,
+          shadowRoots: hostsCollected.map((h) => h.shadowRoot),
+        })
+        const parsedDoc = Document.parseHTMLUnsafe(html)
+        const parsedRoot = selector
+          ? parsedDoc.querySelector(selector)
+          : parsedDoc.body
+        if (parsedRoot) {
+          const flattened = walk(parsedRoot, 0)
+          // §V03-C safety guard: only substitute the live dom[] if the
+          // re-walk did not lose value on EITHER axis (nodes or aggregate
+          // text chars). parseHTMLUnsafe returns a detached doc;
+          // getComputedStyle/getBoundingClientRect degrade to UA defaults
+          // (zero bbox, empty computed). On pages where shadow flattening
+          // adds value (PDPs Shopify with populated custom elements) the
+          // gain is large; on pages without that workload (policies,
+          // plain HTML), the re-walk can lose content because hydrated
+          // shadow content visible to the live walker doesn't reproduce
+          // on the detached tree. When that happens, keep the live
+          // walker result and surface a warning.
+          function measureTree(arr) {
+            let nodes = 0
+            let textChars = 0
+            const stack = Array.isArray(arr) ? [...arr] : [arr]
+            while (stack.length) {
+              const node = stack.pop()
+              if (!node || typeof node !== 'object') continue
+              nodes++
+              if (typeof node.text === 'string') textChars += node.text.length
+              if (Array.isArray(node.children)) {
+                for (const c of node.children) stack.push(c)
+              }
+            }
+            return { nodes, textChars }
+          }
+          if (flattened) {
+            const orig = measureTree(dom)
+            const flat = measureTree([flattened])
+            if (flat.nodes >= orig.nodes && flat.textChars >= orig.textChars) {
+              // Snapshot the live walker result BEFORE substitution so
+              // downstream consumers that depend on real layout (bbox
+              // values are zero on the parsed detached doc) can fall
+              // back when needed — see §V03-C domLive comment above.
+              domLive = dom.length === 1 ? dom[0] : [...dom]
+              dom.length = 0
+              dom.push(flattened)
+              shadowSerializedHostCount = hostsCollected.length
+            } else {
+              warnings.push({
+                code: 'shadow-flatten-skipped-lossy',
+                message: `re-walk lossy: nodes ${flat.nodes} vs ${orig.nodes}, textChars ${flat.textChars} vs ${orig.textChars}; keeping live walker result`,
+              })
+            }
+          }
+          // The re-walk of the parsed (detached) doc re-discovers shadow
+          // roots that parseHTMLUnsafe re-attached, so it would
+          // double-count if we let those increments leak. Restore the
+          // canonical live counts here.
+          shadowRootCount = originalShadowRootCount
+          shadowDOMTraversed = originalShadowDOMTraversed
+        }
+      }
+    } else {
+      warnings.push({
+        code: 'shadow-serialize-unavailable',
+        message:
+          'getHTML or Document.parseHTMLUnsafe not available; shadow DOM falls back to .shadowRoot.children walk (v0.2.x behavior)',
+      })
+    }
+  } catch (err) {
+    shadowRootCount = originalShadowRootCount
+    shadowDOMTraversed = originalShadowDOMTraversed
+    warnings.push({
+      code: 'shadow-serialize-failed',
+      message: String(err && err.message ? err.message : err),
+    })
+  }
+
   return {
     sectionType,
     sectionBoundingBox,
     tokens,
     dom,
+    domLive,
     pseudoElements,
     imgUrls,
     shadowDOMTraversed,
     shadowRootCount,
+    shadowSerializedHostCount,
+    warnings,
     externalIframes,
   }
 }

package/templates/skills/sb-inspect-live/scripts/tests/test-inspect-live.mjs

@@ -37,6 +37,24 @@ test('--help exits 0 and prints usage', () => {
   assert.match(r.stdout, /--wait-strategy/)
 })
 
+// §V03-B — V0.3.0 changed --max-text default from 240 to 0 (no truncation).
+// This regression-protects the policy-page coverage fix.
+test('--help documents --max-text default 0 (no truncation)', () => {
+  const r = spawnSync('node', [SCRIPT, '--help'], { encoding: 'utf8' })
+  assert.equal(r.status, 0, `exit code was ${r.status}`)
+  assert.match(r.stdout, /--max-text/, '--max-text flag must appear in help')
+  // Scope the "default 0" assertion to the --max-text line specifically.
+  // The previous /default\s+0/ would match against any other flag whose
+  // description happens to contain "default 0" (e.g. a future flag whose
+  // default is "0ms" or similar).
+  assert.match(
+    r.stdout,
+    /--max-text[^\n]*default\s+0/,
+    '--max-text line must document default 0',
+  )
+  assert.match(r.stdout, /no truncation/i, 'help must explain semantics')
+})
+
 test('missing --url exits 2', () => {
   const r = spawnSync('node', [SCRIPT, '--output-dir', '/tmp/sb-test'], { encoding: 'utf8' })
   assert.equal(r.status, 2, `exit code was ${r.status}`)