aem-eds-kit 0.4.22 → 0.4.26

package/CHANGELOG.md

@@ -6,7 +6,63 @@ 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
+  reads from the design (prompt instruction), `--widths 390,768,1440` overrides,
+  and 375/768/1280 remains the fallback. New `src/lib/figma/breakpoints.ts`
+  (`parseWidths` / `normalizeBreakpoints`), extended `edsMetaSchema`.
 - **`eds init` writes a local-dev `.env` + `xwalk.json` by default.** `.env`
   carries the `aem up` config (`AEM_OPEN=/`, `AEM_PORT=3007`, `AEM_PAGES_URL`
   prefilled from the git remote); it's never overwritten and always gitignored.

package/README.md

@@ -268,11 +268,21 @@ The generated `_<name>.json` uses the EDS block-plugin (xwalk) format (`definiti
 
 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.)*
 
-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**.
+**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:
+
+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.
+
+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 ./hero.svg --name hero        # from a local export (no network)
 eds block from-design "<figma-url>" --dry-run       # just build the prompt
 ```
 
@@ -280,13 +290,20 @@ eds block from-design "<figma-url>" --dry-run       # just build the prompt
 |---|---|
 | `--name <name>` | Override the inferred block name |
 | `--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 |
+| `--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:**
 - `figma.com/design/:fileKey/:name?node-id=...`
 - `figma.com/file/:fileKey/:name?node-id=...` (legacy)
@@ -310,12 +327,15 @@ 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
 ```
@@ -446,23 +466,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
@@ -472,9 +495,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