similarbuild 0.1.0

package/templates/skills/sb-inspect-live/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: sb-inspect-live
+description: Inspects a live URL at a given mobile viewport and returns DOM, computed tokens, screenshot, pseudo-elements, and image URLs for visual cloning. Use when the SimilarBuild orchestrator (`/build-page`, `/build-site`, `/clip-section`) requests live inspection, or when the user asks to 'inspect a live page'.
+---
+
+# sb-inspect-live
+
+## Overview
+
+Captures everything `sb-build-output` needs to reconstruct a live page faithfully: DOM tree, computed CSS tokens, full-page screenshot, pseudo-elements (`::before`/`::after`), and a normalized list of image URLs. Mobile-first by default (viewport 390×844) — desktop-only inspection masks structural differences that bite during the build (Anti-pattern #4).
+
+All deterministic work — Playwright launch, lazy-load triggering, getComputedStyle walk, pseudo-element capture, asset URL collection — happens in `scripts/inspect-live.mjs`. This SKILL.md only describes inputs, outputs, and failure handling so the orchestrator can integrate the result.
+
+Act as a visual-fidelity sentinel: if the script returns suspicious output (empty DOM, bot-challenge text, widget blocked), surface that flag rather than passing garbage downstream.
+
+## Inputs
+
+| Argument          | Required | Default       | Notes                                                                                |
+| ----------------- | -------- | ------------- | ------------------------------------------------------------------------------------ |
+| `url`             | yes      | —             | Absolute URL to inspect.                                                             |
+| `viewport-width`  | no       | `390`         | Mobile-first. Override only if the orchestrator explicitly needs desktop.            |
+| `viewport-height` | no       | `844`         | iPhone 14-class default.                                                             |
+| `selector`        | no       | (full page)   | CSS selector to scope inspection to one element + descendants.                       |
+| `wait-strategy`   | no       | `lazy-load`   | `lazy-load` (step-scroll baseline), `auto` (also wait for known widgets), or a specific widget name (`kaching-bundles`, `judge-me`). |
+| `output-dir`      | yes      | —             | Directory where `screenshot.png` and `inspection.json` are written.                  |
+
+If `viewport-width` is unspecified and the project has `.claude/sb-config.yaml` with `default_viewport`, use that. Otherwise 390.
+
+## Output
+
+A single JSON object printed to stdout AND saved to `{output-dir}/inspection.json`:
+
+```json
+{
+  "url": "https://example.com/page",
+  "viewport": { "width": 390, "height": 844 },
+  "sectionType": "hero",
+  "sectionBoundingBox": { "x": 0, "y": 0, "w": 390, "h": 844 },
+  "tokens": {
+    "typography": { "h1": {...}, "h2": {...}, "body": {...}, "button": {...} },
+    "colors": { "background": "...", "text": "...", "primary": "...", "accent": "..." },
+    "layout": { "container": {...}, "section": {...} }
+  },
+  "dom": [ { "tag": "...", "classes": [...], "id": "...", "text": "...", "bbox": {...}, "computed": {...}, "children": [...] } ],
+  "pseudoElements": [ { "selector": "...", "pseudo": "::before", "content": "...", "computed": {...} } ],
+  "imgUrls": [ { "url": "...", "type": "img|background|source-srcset", "context": "...", "alt": "...", "bbox": {...} } ],
+  "screenshot": "{output-dir}/screenshot.png",
+  "widgetBlocked": false
+}
+```
+
+`sectionBoundingBox` is the document-relative bbox (CSS pixels, includes scroll) of the actual section element matched by `sectionType`, when one was found by class/tag signature search. The orchestrator forwards it to `sb-compare-visual --crop-live-bbox` so a section build is diffed against a section slice of the full-page live (resolves anti-pattern #10). It's `null` in three cases: (a) `--selector` was passed (live screenshot is already element-only — no crop needed), (b) only the `h1` heuristic fallback fired (sectionType ended up `hero` but no specific section element was identifiable), or (c) `sectionType` is the generic `section`/`unknown`. Treat `null` as "do not crop".
+
+Pseudo-elements are non-negotiable — without them, overlap/accent reconstruction silently drifts (Anti-pattern #6).
+
+## Dependencies
+
+The host project must have these npm packages installed (the SimilarBuild installer handles this; for ad-hoc test runs, install at the project root):
+
+- `playwright` (with chromium browser — `npx playwright install chromium`)
+- `playwright-extra`
+- `puppeteer-extra-plugin-stealth` (used through `playwright-extra` to bypass bot detection)
+
+Node ≥ 20.
+
+## On Activation
+
+1. **Resolve inputs.** Collect `url`, `viewport-width`, `viewport-height`, `selector`, `wait-strategy`, `output-dir` from the caller. Apply defaults above. Read `default_viewport` from `{project-root}/.claude/sb-config.yaml` if it exists and viewport wasn't passed.
+
+2. **Ensure output-dir exists.** `mkdir -p` it.
+
+3. **Run the script.** From the project root:
+
+   ```bash
+   node {skill-root}/scripts/inspect-live.mjs \
+     --url "{url}" \
+     --viewport-width {viewport-width} \
+     --viewport-height {viewport-height} \
+     --output-dir "{output-dir}" \
+     --wait-strategy "{wait-strategy}" \
+     [--selector "{selector}"]
+   ```
+
+   The script handles: stealth chromium launch, iPhone user-agent, `domcontentloaded` + 3.5s settle, step-scroll (0→12000 step 400, 150ms each) to trigger lazy-load, force-eager rewrite of `<img loading="lazy">`, additional waits for known widget selectors, section-type detection, computed-token capture on key elements, depth-bounded DOM walk, pseudo-element walk, image URL collection, and screenshot capture. See `scripts/inspect-live.mjs --help` for the full flag list.
+
+4. **Validate the result.** Parse stdout as JSON. If the script exits non-zero, surface the stderr to the orchestrator and stop — don't fabricate output.
+
+5. **Forward `widgetBlocked`.** If the JSON has `widgetBlocked: true`, do NOT discard the result — pass it through. The orchestrator decides whether to invoke Plan B (ask the user for an alternative URL or scoping). Common triggers: Cloudflare challenge page, < 1KB body, or known bot-challenge text patterns.
+
+6. **Return the JSON unchanged** to the caller. Do not summarize, mutate, or strip fields — `sb-extract-assets` consumes `imgUrls` and `sb-build-output` consumes everything.
+
+## Failure modes
+
+| Symptom                                           | Likely cause                            | What to surface                                                       |
+| ------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------- |
+| Script exits non-zero                             | Network failure, invalid URL, missing browser | Pass stderr verbatim. Suggest `npx playwright install chromium` if the message mentions a missing browser binary. |
+| `widgetBlocked: true` in JSON                    | Bot detection / Cloudflare / paywall    | Forward unchanged — orchestrator handles escalation.                  |
+| `dom` is empty but `widgetBlocked: false`        | Selector matched no elements            | Re-run without `--selector` or refine. The orchestrator may retry.   |
+| Screenshot file present but byte-size very small | Page failed to render but didn't crash  | Treat as `widgetBlocked` even if not flagged; surface the byte-size.  |
+
+## Conventions
+
+- Bare paths (e.g. `scripts/inspect-live.mjs`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}` resolves to the project working directory.