aem-eds-kit 0.4.26 → 0.4.33

package/README.md

@@ -10,7 +10,7 @@
 
 **Turn a design into an EDS block** - JS, CSS and a Universal Editor model - without leaving your terminal.
 
-`aem-eds-kit` gives you the `eds` command. Paste a design link - Figma, Google Stitch, Canva, Sketch or Framer - and it hands the design to the AI agent you already use (Claude Code, Cursor or Codex); the agent reads it through MCP and writes production-ready code straight into your repo. It also scaffolds blocks, previews them in your browser, and keeps your project healthy with a few quick audits.
+`aem-eds-kit` gives you the `eds` command. Paste a design link - a Figma URL, or a Framer / Google Stitch page - and it hands the design to the AI agent you already use (Claude Code, Cursor or Codex), which writes production-ready code straight into your repo. Figma is read through MCP or the REST API; Framer and Stitch render real HTML, so they're **scraped with headless Chromium** (no token needed). It also scaffolds blocks, previews them in your browser, and keeps your project healthy with a few quick audits.
 
 It lives next to `@adobe/aem-cli` (your local dev server) and handles everything around it.
 
@@ -56,6 +56,26 @@ eds block from-design "<figma-url>" --name hero
 
 `eds` runs on your machine, not on your site - it never adds a single byte to what your visitors download.
 
+## Try it in 30 seconds (no Figma account, no token)
+
+From inside an EDS project (or spin a throwaway one up with `eds sandbox new demo`):
+
+```bash
+eds block from-design --sample --name hero --dry-run   # see the prompt - zero setup
+eds block from-design --sample --name hero             # generate it with your AI agent
+eds block preview hero                                  # see it live in the browser
+```
+
+`--sample` uses a **bundled "Kiri Bloom" hero design**, read straight from disk - **no Figma token, no MCP call, no network**. (`--dry-run` needs no AI agent either - it just prints the prompt.)
+
+Ready for the real thing? Point it at the official **Kiri Bloom AEM EDS Kit** training file in Figma:
+
+```bash
+eds block from-design \
+  "https://www.figma.com/design/vwlEKTFhcrlwuA8dRgN5SD/Kiri-Bloom-AEM-EDS-Kit-Example?node-id=0-1" \
+  --name hero
+```
+
 ## Interactive mode
 
 Run `eds` with no command and it opens an **interactive menu** that walks you through every feature (set up the project, generate a block from a design, migrate a classic AEM component, scaffold, create a block, add an integration, preview, Admin API, audits, Figma setup). Most commands are also interactive on their own when you omit arguments - e.g. `eds init`, `eds block from-design` (wizard), `eds migrate component`, `eds scaffold`, `eds integrate`, `eds preview`. Flags and subcommands still work for CI / power users.
@@ -83,6 +103,10 @@ eds scaffold blocks
 # Add a third-party service (GTM, GA4, chat…)
 eds integrate
 
+# QA a block before you ship it (visual regression + content/a11y)
+eds block test hero
+eds block check hero
+
 # Audit your project
 eds doctor
 ```
@@ -103,7 +127,7 @@ eds scaffold ue
 eds scaffold helpers
 
 # 4. Build blocks - from a design, from scratch, or migrated from classic AEM
-eds block from-design            # paste a Figma/Stitch/Canva/Sketch/Framer link
+eds block from-design            # paste a Figma URL, a Framer/Stitch page, or a local SVG
 # eds block create hero
 # eds migrate component ./components/hero
 
@@ -266,14 +290,19 @@ The generated `_<name>.json` uses the EDS block-plugin (xwalk) format (`definiti
 
 ### `eds block from-design [design-url]`
 
-Translates a design - **Figma, Google Stitch, Canva, Sketch or Framer** - into an EDS block. Run with **no URL** for a step-by-step wizard (design source, name, link, content source, UE model, screenshot, run mode). It builds a prompt with EDS conventions + your project's design tokens and hands it to your AI agent (Claude Code, Cursor, or Codex). *(This was `from-figma` before it went design-agnostic; Figma is the most battle-tested source and stays pixel-perfect.)*
+Translates a design - **a Figma URL, a Framer / Google Stitch page, or a local SVG/PNG export** - into an EDS block. Run with **no URL** for a step-by-step wizard (design source, name, link, content source, UE model, screenshot, run mode). It builds a prompt with EDS conventions + your project's design tokens and hands it to your AI agent (Claude Code, Cursor, or Codex). *(This was `from-figma` before it went design-agnostic; Figma is the most battle-tested source and stays pixel-perfect.)*
+
+**Figma vs. web sources.** Figma paints to a WebGL canvas, so it's read through the **REST API** (with a token) or **MCP**. Framer and Google Stitch render **real HTML**, so `eds` **scrapes** them with headless Chromium — reading computed layout, typography, colours and geometry straight off the page (no token, no MCP). Canva and Sketch are canvas/image-based and aren't scrapeable — export a frame and pass it as a local SVG/PNG. The provider is detected from the URL host, or set with `--provider`.
 
-**Fetch → cache → generate.** `eds` resolves the design **once** into a snapshot, then the agent generates from it — so retries and refine passes never re-fetch. It picks the cheapest source automatically:
+**Gated sources (`--auth`).** A Google Stitch project (and a private Framer page) sits behind a login, so an anonymous scrape only sees the sign-in shell. Pass `--auth` and `eds` opens a **headed** browser once — you log in by hand, it saves the session, and every later scrape reuses it. The session (cookies/localStorage) is stored owner-only under `~/.eds/auth/<provider>.json`; re-login with `--auth-refresh`. (The saved session is a secret — it's never written to the repo.)
+
+**Fetch → cache → generate.** `eds` resolves the design **once** into a snapshot, then the agent generates from it — so retries and refine passes never re-fetch. It picks the cheapest adapter automatically:
 
 1. **Local file** — pass a path to an SVG/PNG export (`eds block from-design ./hero.svg`) → read from disk, no network.
-2. **Cache** — a snapshot already fetched for this file/node (`tmp/eds-cli/design-cache/`) is reused.
-3. **Figma REST** — if a Figma token is set, `eds` fetches the node itself and embeds a compact design spec. Separate, generous quota; **does not touch the MCP limit**.
-4. **Figma MCP** — fallback: the agent makes **one** `get_design_context` call and caches it.
+2. **Cache** — a snapshot already fetched for this design (`tmp/eds-cli/design-cache/`) is reused.
+3. **Web scrape (Framer / Stitch)** — the live page is rendered in headless Chromium and its computed layout/styles are extracted. Needs Playwright + a browser: `npx playwright install chromium`.
+4. **Figma REST** — if a Figma token is set, `eds` fetches the node itself and embeds a compact design spec. Separate, generous quota; **does not touch the MCP limit**.
+5. **Figma MCP** — fallback: the agent makes **one** `get_design_context` call and caches it.
 
 The agent then generates pixel-perfect code (JS + CSS) **and its Universal Editor model** by default, with lightweight **placeholders** for not-yet-authored content. You see a **live, colour-coded log** with per-phase timings. On success you get a **menu** — refine the block with another pass, open the live preview, or finish (preview is **opt-in**, never auto-launched).
 
@@ -282,13 +311,17 @@ The agent then generates pixel-perfect code (JS + CSS) **and its Universal Edito
 ```bash
 eds block from-design                               # interactive wizard
 eds block from-design "<figma-url>" --name hero     # non-interactive (REST if a token is set, else MCP)
+eds block from-design "<framer-url>" --name hero    # Framer/Stitch → scraped with headless Chromium
+eds block from-design "<stitch-url>" --name hero --auth   # gated source → log in once, reuse the session
 eds block from-design ./hero.svg --name hero        # from a local export (no network)
+eds block from-design --sample --name hero          # bundled Kiri Bloom sample (no token, no MCP)
 eds block from-design "<figma-url>" --dry-run       # just build the prompt
 ```
 
 | Flag | Description |
 |---|---|
 | `--name <name>` | Override the inferred block name |
+| `--provider <type>` | Design source: `figma` \| `framer` \| `stitch` (else detected from the URL) |
 | `--source <type>` | Content source: `document` \| `ue` \| `cf` \| `mixed` |
 | `--widths <list>` | Design frame widths for preview breakpoints (e.g. `390,768,1440`) |
 | `--agent <type>` | Force `claude` \| `cursor` \| `codex` \| `none` |
@@ -296,7 +329,10 @@ eds block from-design "<figma-url>" --dry-run       # just build the prompt
 | `--no-ue-model` | Skip the Universal Editor model |
 | `--screenshot` | Add a screenshot MCP call for a pixel check (opt-in — costs a call) |
 | `--mcp` | Force the Figma MCP adapter even when a REST token is set |
+| `--auth` | Scrape with a logged-in session (Framer/Stitch): log in once, reuse it |
+| `--auth-refresh` | Force a fresh scrape login even if a session is saved |
 | `--refresh` | Ignore the cached snapshot and re-fetch |
+| `--sample` | Use the bundled Kiri Bloom sample design (no URL, token or MCP) |
 | `--serve` | Auto-start the live preview (non-interactive runs only) |
 | `--yes` | Skip confirmation prompts |
 
@@ -340,6 +376,42 @@ eds block preview hero --widths 375,768,1280   # custom breakpoints
 eds block preview hero --port 9000 --no-open
 ```
 
+### `eds block test [name]` · `eds block check [name]`
+
+Two deterministic QA passes over a block's **rendered** DOM (no agent) - one block, or **all** of them when you omit the name. Both render the block in headless Chromium (Playwright), so install the browser once: `npx playwright install chromium`. Wire them into CI next to the audits - both exit non-zero on failure.
+
+**`eds block test`** - **visual regression.** Screenshots each block at every breakpoint and diffs it (pixelmatch) against a committed baseline in `blocks/<name>/__snapshots__/`; it fails when the changed-pixel ratio crosses the threshold (default 1%) and writes the diff image to `tmp/eds-cli/visual-diff/`. `--update` (re)writes the baselines after an intended change. `--design` does a **design↔render** diff instead - the rendered block against its Figma design image (needs a Figma token and a Figma source in the block's `.eds-meta.json`).
+
+```bash
+eds block test                         # all blocks vs committed baselines
+eds block test hero                    # one block
+eds block test hero --update           # (re)write baselines after an intended change
+eds block test hero --design           # rendered block vs its Figma design image
+eds block test --threshold 0.02        # allow 2% changed pixels
+```
+
+| Flag | Description |
+|---|---|
+| `--update` | (Re)write baseline screenshots instead of comparing |
+| `--threshold <ratio>` | Max changed-pixel ratio before failing (default `0.01` = 1%) |
+| `--design` | Compare the rendered block against its Figma design image (needs a token) |
+| `--widths <list>` | Breakpoint widths (e.g. `375,768,1280`) |
+| `--port <port>` | Port for the internal preview server (default `8788`) |
+
+**`eds block check`** - **content, link & a11y.** Renders each block (after `decorate()`) and flags missing image `alt`, missing image dimensions (CLS risk), links/buttons with no accessible name, empty `href`s and inline event handlers. Checks run at the widest breakpoint; it exits non-zero on any error, or on any warning with `--strict`.
+
+```bash
+eds block check                        # all blocks
+eds block check hero                   # one block
+eds block check --strict               # fail on warnings too
+```
+
+| Flag | Description |
+|---|---|
+| `--strict` | Fail on warnings too, not just errors |
+| `--widths <list>` | Breakpoint widths (the widest is used) |
+| `--port <port>` | Port for the internal preview server (default `8789`) |
+
 ### `eds scaffold ue` · `eds scaffold blocks`
 
 Scaffold Universal Editor components deterministically (no agent). `eds scaffold ue` writes/merges the three UE config files with the default-content components and a **`field-reference` block showing all 17 field types** + a multifield. `eds scaffold blocks` scaffolds standard Block Collection blocks (hero, cards, columns, accordion, embed) with UE models. Run `eds scaffold` for an interactive picker.
@@ -597,7 +669,7 @@ Tests use fixtures in `tests/fixtures/` - a sample EDS project and recorded Figm
 
 ## Roadmap
 
-- **Design sources** - deepen Google Stitch, Canva and Sketch support alongside Figma (the wizard's first step already picks the source), and a generic `eds setup` in place of `eds figma setup`.
+- **Design sources** - Figma (REST/MCP), Framer and Google Stitch (headless-Chromium scrape) are wired; next is deepening the scrape extractor (multi-breakpoint capture, component/variant detection) and a generic `eds setup` in place of `eds figma setup`. Canva/Sketch stay on the local-export path (canvas/image — not scrapeable).
 - **Screenshot-to-block** - build a block from a plain image (harder: no structured layout/measurements, so pixel-perfect is tougher).
 - **Tokens & sync** - design variables → CSS custom properties, and incremental re-sync of an existing block (`--update`).
 - **Headless & CI** - a direct MCP client (no agent needed) for CI/CD, plus `eds lighthouse`, `eds rum` and `eds migrate page`.