@uicopilot/storybook-addon 0.18.2 → 0.19.0

package/README.md

@@ -124,13 +124,13 @@ React is optional as a peer dependency — the addon's own UI is bundled and doe
 
 Both are useful, and they answer different questions.
 
-| | Visual regression (snapshots) | UI Parity |
-| --- | --- | --- |
-| Compares against | **The last approved screenshot** of your own component | **The Figma frame** — the design source of truth |
-| Catches | Any change from the previous build | Divergence from what the design says, even if it's been wrong for months |
-| Output | A pixel diff image to eyeball | Named properties with Expected vs. Actual values |
-| Needs | Baselines to approve and re-approve | A one-time story → frame mapping |
-| Blind spot | A component that never matched the design still passes forever | Anything not expressed as a comparable style property |
+|                  | Visual regression (snapshots)                                  | UI Parity                                                                |
+| ---------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Compares against | **The last approved screenshot** of your own component         | **The Figma frame** — the design source of truth                         |
+| Catches          | Any change from the previous build                             | Divergence from what the design says, even if it's been wrong for months |
+| Output           | A pixel diff image to eyeball                                  | Named properties with Expected vs. Actual values                         |
+| Needs            | Baselines to approve and re-approve                            | A one-time story → frame mapping                                         |
+| Blind spot       | A component that never matched the design still passes forever | Anything not expressed as a comparable style property                    |
 
 Snapshot tools tell you **something changed**. UI Parity tells you **it doesn't match the design** — which is the question that comes up in design review, not code review. Teams run both.
 
@@ -159,11 +159,12 @@ export default {
 };
 ```
 
-| Variable | Purpose |
-| --- | --- |
-| `STORYBOOK_UICOPILOT_URL` | Point the addon at your own dashboard deployment instead of `https://app.uiparity.com`. |
-| `STORYBOOK_UICOPILOT_FIGMA_KIT` | A reference Figma community-file URL to surface in the project setup screen as a copyable starting kit. Set automatically by `npx uiparity demo` templates that ship one. |
-| `STORYBOOK_UICOPILOT_NO_PUPPETEER` | Set to `true` to disable server-side screenshot capture and fall back to in-browser capture. Debug/troubleshooting flag. |
+| Variable                           | Purpose                                                                                                                                                                                          |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `STORYBOOK_UICOPILOT_URL`          | Point the addon at your own dashboard deployment instead of `https://app.uiparity.com`.                                                                                                          |
+| `STORYBOOK_UICOPILOT_FIGMA_KIT`    | A reference Figma community-file URL to surface in the project setup screen as a copyable starting kit. Set automatically by `npx uiparity demo` templates that ship one.                        |
+| `STORYBOOK_UICOPILOT_NO_PUPPETEER` | Set to `true` to disable server-side screenshot capture and fall back to in-browser capture. Debug/troubleshooting flag.                                                                         |
+| `STORYBOOK_UICOPILOT_CHROME_PATH`  | Absolute path to a Chrome/Chromium executable. Only needed when your browser is somewhere the addon does not look — a CI image, or a non-standard install. Takes precedence over auto-discovery. |
 
 ### Self-hosting the dashboard
 
@@ -195,8 +196,19 @@ This is almost always a mapping problem — the story is pointed at the wrong Fi
 **The sidebar markers look like Storybook's own test statuses.**
 They share the same status glyph. UI Parity only recolors markers for stories it actually has a status for, so anything untouched is your test runner's, not ours.
 
-**Screenshots fail or time out.**
-Server-side capture needs `puppeteer` installed in your project (it's an optional peer dependency). Install it, or set `STORYBOOK_UICOPILOT_NO_PUPPETEER=true` to use the in-browser fallback.
+**Screenshots fail or time out, or stories come back with no code DOM.**
+Server-side capture runs a headless browser inside your own Storybook dev server, and it needs one of:
+
+- **`puppeteer`** — bundles its own Chromium (~200MB download), works with no browser installed; or
+- **`puppeteer-core`** — ~1MB, and uses a Chrome/Chromium you already have. The addon looks in the standard locations for macOS, Linux and Windows (including per-user Windows installs); point it elsewhere with `STORYBOOK_UICOPILOT_CHROME_PATH`.
+
+Both are optional peer dependencies, so neither is installed for you. `puppeteer-core` is the lighter choice if you already have Chrome — which you probably do.
+
+If the addon reports **"No Chrome or Chromium found"**, that is the missing-browser case: install Chrome or set `STORYBOOK_UICOPILOT_CHROME_PATH`. If it reports **"found a browser … but could not drive it"**, the browser and `puppeteer-core` versions disagree — update one of them. The two are reported separately on purpose, because the fixes are different.
+
+In CI, use an image that ships Chrome (or install it in a setup step) and set `STORYBOOK_UICOPILOT_CHROME_PATH` if it lands somewhere unusual.
+
+Failing all of that, set `STORYBOOK_UICOPILOT_NO_PUPPETEER=true` to use the in-browser fallback.
 
 ## Links