aem-eds-kit 0.4.25 → 0.4.30

package/CHANGELOG.md

@@ -7,17 +7,56 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ### Changed
+- **`block from-design` now fetches the design once into a cached snapshot,
+  then generates from it** (fetch → cache → generate). The CLI resolves the
+  design via the cheapest adapter - local SVG/PNG export, a cached snapshot
+  (`tmp/eds-cli/design-cache/`), the **Figma REST** API (with a token), or a
+  **single** Figma MCP call the agent caches - so retries and refine passes
+  never re-fetch. Replaces the old flow where the agent made several MCP calls
+  mid-generation. New `src/lib/figma/rest.ts` and `design-source.ts`.
+- **MCP usage cut to one call per block.** The prompt now uses only
+  `get_design_context` (dropped `get_variable_defs`; `get_screenshot` is opt-in
+  via `--screenshot`) - the Figma Dev Mode MCP server meters tool calls per plan
+  (Starter/View/Collab: ~6-20/month). Set a Figma token to skip MCP via REST.
+- **Block generation defaults to the fastest model (Haiku)**, overridable with
+  `model` in config - block codegen is structured, bounded work.
+- **`eds block preview` no longer auto-launches.** After `from-design` you get a
+  menu to refine the block or open the preview on demand; `--no-serve` became
+  `--serve` (opt-in, non-interactive runs only).
+- **Shorter interactive-menu labels** (details moved to each choice's
+  description).
 - **Smaller published package (~206 kB → ~73 kB packed; 808 kB → ~220 kB
   unpacked).** The build no longer ships a source map (it was ~60% of the
   package; re-enable ad hoc with `tsup --sourcemap`) and now minifies the single
   bundled binary (`dist/bin/eds.js` 265 kB → ~170 kB).
 
 ### Fixed
+- **Block preview blank-screen cases.** The harness now (a) reduces a full-HTML
+  `_<name>.preview.html` mock to its `<body>` contents, (b) reveals the body past
+  the EDS `body.appear` visibility gate (which `scripts.js` would normally flip),
+  and (c) loads the block script via a defensive dynamic `import()` so a bad
+  import (e.g. a missing `scripts/*.js`) shows the authored markup instead of a
+  blank frame. The prompt now requires a bare preview fragment and self-contained
+  block JS.
+- **`eds block preview header|footer`** now warns that these are page chrome and
+  can't render standalone (they fetch the nav/footer fragment and need the full
+  page runtime).
 - Removed the dangling `main`/`types` fields that pointed at a never-built
   `dist/index.js` (a bare `import "aem-eds-kit"` would have failed) - the package
   is a CLI, exposed via its `bin`.
 
 ### Added
+- **`eds block preview` with no name → a live gallery of every content block**,
+  each in its own width-honest iframe. Routes are computed per request, so a
+  block generated while the gallery is open appears on the next reload
+  (header/footer are skipped - page chrome can't render standalone). New
+  `buildGallery` + a dynamic request handler on the preview server.
+- **`block from-design` accepts a local SVG/PNG export** (`eds block from-design
+  ./hero.svg`) - reads the design straight from disk, no network and no MCP.
+- **Figma REST path** via a Personal Access Token (`FIGMA_TOKEN` env or
+  `figma.token` config, scope `file_content:read`) - a quota separate from the
+  MCP tool-call limit. New flags `--mcp` (force MCP) and `--refresh` (ignore the
+  cache).
 - **`block from-design` records the design's frame widths** in the block's
   `.eds-meta.json` (`breakpoints`), so `eds block preview` is width-honest at the
   **real design widths**, not a fixed device set. The agent writes the widths it

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,28 +290,49 @@ 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 adapter automatically:
 
-The agent reads the design through its MCP connection (for Figma: `get_design_context`, `get_variable_defs`, `get_screenshot`), generates pixel-perfect code (JS + CSS) **and its Universal Editor model** by default, uses lightweight **placeholders** for not-yet-authored content (so the block is visible before Universal Editor takes over), then self-verifies. You see a **live, colour-coded log** with per-phase timings, and on success the **live preview starts 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 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).
+
+> **Figma MCP limits:** the Dev Mode MCP server is metered per plan (Starter / View / Collab seats: ~6–20 **tool calls a month**). `eds` uses **one** MCP call per block and caches it; set a Figma token to skip MCP entirely via REST. See [How Figma integration works](#how-figma-integration-works).
 
 ```bash
 eds block from-design                               # interactive wizard
-eds block from-design "<figma-url>" --name hero     # non-interactive
+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 ./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` |
 | `--dry-run` | Build the prompt only |
 | `--no-ue-model` | Skip the Universal Editor model |
-| `--no-screenshot` | Skip the screenshot (fewer tokens; structural verification) |
-| `--no-serve` | Don't auto-start the live preview |
+| `--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 |
+| `--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 |
 
+Set a **Figma Personal Access Token** (scope `file_content:read`) to use the REST path — via `FIGMA_TOKEN` env or `figma.token` in config. The block generation model defaults to the fastest (Haiku); override with `model` in config.
+
 The generated block records the **design's frame widths** in its `.eds-meta.json` (`breakpoints`), so `eds block preview` shows it at the real design widths rather than a fixed device set. The agent writes the widths it reads from the design; `--widths` overrides them, and 375/768/1280 is only the fallback.
 
 **Supported Figma URL formats:**
@@ -313,16 +358,55 @@ eds block list
 eds block list --json          # machine-readable output
 ```
 
-### `eds block preview <name>`
+### `eds block preview [name]`
+
+Serves a **live, breakpoint-switchable preview** in your browser - no build, no files written to your project (the harness is served from memory). A dropdown switches widths inside a width-honest iframe, and **edits live-reload** the browser (the server watches the block folder).
 
-Serves a **live, breakpoint-switchable preview** of a block in your browser - no build, no files written to your project (the harness is served from memory). A dropdown switches widths inside an iframe, and **edits live-reload** the browser (the server watches the block folder).
+Run it **with no name** for a **gallery** of every content block, each in its own iframe. Routes are computed per request, so a block generated while the gallery is open **appears on the next reload** (header/footer are skipped — they're page chrome and can't render standalone).
 
 ```bash
-eds block preview hero
+eds block preview                              # gallery of all blocks
+eds block preview hero                         # a single block
 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.
@@ -449,23 +533,26 @@ The vendored framework (`scripts/aem.js` / `lib-franklin.js`) is never flagged.
 
 ## How Figma integration works
 
-You don't need a Figma API token. `aem-eds-kit` never talks to Figma directly - it writes a focused prompt and hands it to the AI agent you already use, which has its own Figma MCP connection. The agent reads the design and writes the files; `eds` orchestrates the handoff and checks the result.
+The design is fetched **once** into a cached snapshot, then the agent generates from it. Separating the fetch from the generation means retries and refine passes never re-fetch, and the snapshot is inspectable (`tmp/eds-cli/design-cache/`). `eds` picks the cheapest adapter available:
 
 ```
-┌──────────┐     prompt      ┌─────────────┐    MCP calls    ┌───────────┐
-│  eds-cli │ ──────────────→ │ Claude Code │ ──────────────→ │ Figma MCP │
-│          │                 │ / Cursor    │ ←────────────── │  Server   │
-│          │ ←────────────── │ / Codex     │   design data   └───────────┘
-│          │   block files   └─────────────┘
-└──────────┘
+                    ┌─ local SVG/PNG ─┐
+                    ├─ cache hit ──────┤      design.json      ┌─────────────┐   block files
+ design reference ──┼─ Figma REST ─────┼───→  (cached) ───────→│ Claude Code │ ───────────────→ repo
+   (url / file)     └─ Figma MCP ──────┘      snapshot          │ /Cursor/Codex│
+                        (1 call, agent dumps to cache)          └─────────────┘
 ```
 
+- **No token needed** for the MCP path — the agent uses its own Figma MCP connection and makes **one** `get_design_context` call per block (then caches it).
+- **Set a Figma token** (`FIGMA_TOKEN` or `figma.token`) to use the **REST** path instead: `eds` fetches the node over HTTPS and embeds a compact spec — a **separate, far larger quota** than the MCP limit, so it works comfortably on Starter / Collab seats.
+- **Local export** (`./file.svg|png`) reads straight from disk — zero network, best for vector/text-heavy frames.
+
 The prompt includes:
-- Figma file key and node ID to fetch
-- EDS block conventions (`decorate(block)`, vanilla JS, semantic HTML, full-width/mobile-first)
+- The design data (embedded spec, local file, or a single-call MCP fetch) for the target node
+- EDS block conventions (`decorate(block)`, vanilla JS, semantic HTML, full-width/mobile-first, self-contained JS)
 - CSS custom properties from your `styles/styles.css`
-- Universal Editor model generation (fields mapped from Figma layers/variants) - on by default
-- Lighthouse performance requirements + pixel-perfect self-verification
+- Universal Editor model generation (fields mapped from design layers/variants) - on by default
+- Lighthouse performance requirements + a single structural self-verification pass
 - Output file structure
 
 ## Configuration
@@ -475,9 +562,12 @@ Priority: CLI flags → env vars → `.edsrc.json` (project) → `~/.eds/config.
 **`~/.eds/config.json`** (created by `eds figma setup`):
 ```json
 {
-  "agent": "claude"
+  "agent": "claude",
+  "model": "haiku",
+  "figma": { "token": "figd_…" }
 }
 ```
+`model` sets the block-generation model (default: fastest / Haiku). `figma.token` (or the `FIGMA_TOKEN` env var) enables the REST fetch path — a Personal Access Token with scope `file_content:read`. Tokens are secrets; keep them out of the repo.
 
 **`.edsrc.json`** (project root, optional):
 ```json
@@ -574,7 +664,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`.