state-scenarios-cli 0.2.0 → 0.4.0

package/skills/state-scenarios/references/network.md

@@ -0,0 +1,67 @@
+# Network: strict mode, third parties and existing MSW
+
+## Strict mode
+
+`?scenario-strict` (or `startScenarios({ strict: true })`) answers every request the scenario
+doesn't cover with a 501, so nothing reaches a real backend. Page loads and assets (any path with a
+file extension) pass. `shoot`, `openScenario` and the MCP server run strict by default.
+`unhandledRequests(page)`, the panel and `shoot` list what wasn't covered.
+
+## Requests that should pass or be silenced
+
+```ts
+import { type ScenarioInput, startScenarios } from 'state-scenarios';
+
+declare const scenarios: ScenarioInput[];
+
+await startScenarios({
+  scenarios,
+  allow: ['images.example-cdn.com'], // reaches the real network, even in strict mode
+  ignore: [/posthog|segment|sentry|google-analytics|googletagmanager|recaptcha|hcaptcha|intercom/i],
+});
+```
+
+- `allow`: requests the screen needs from the real network, such as CDN images or a maps API.
+- `ignore`: analytics, error reporting, captcha and chat SDKs. Never reported as unhandled; in strict
+  mode they get an empty 204 instead of a 501, so most SDKs stay quiet and don't retry.
+- An SDK that still logs errors (some expect a JSON body): don't start it in scenarios,
+  `if (!currentSession()?.active) analytics.init(...)`.
+
+Patterns are URL substrings or regular expressions. Match the hosts the app actually calls.
+
+## Apps that already use MSW
+
+Start your worker and pass it in. Scenario entries answer first, then your handlers, then the strict
+catch-all; `destroy()` restores your handlers.
+
+```ts
+await worker.start();
+await startScenarios({ scenarios, worker });
+```
+
+## Reusing handlers from tests
+
+Pass handlers by name, then name them in scenarios. They answer after the scenario's `network`.
+
+```ts
+import { type ScenarioInput, startScenarios } from 'state-scenarios';
+import { statementsEmpty } from './test/handlers'; // the handlers your unit tests use
+
+const scenarios: ScenarioInput[] = [
+  { name: 'no-statements', handlers: ['statementsEmpty'], ready: 'text=No statements yet' },
+];
+
+await startScenarios({ scenarios, handlers: { statementsEmpty } });
+```
+
+```json
+{
+  "name": "no-statements",
+  "extends": "signed-in",
+  "handlers": ["statementsEmpty"],
+  "ready": "text=No statements yet"
+}
+```
+
+An unknown name fails when the scenario opens and lists the known ones. `validate` can't see
+handlers, so it only checks the JSON.

package/skills/state-scenarios/references/setup.md

@@ -0,0 +1,94 @@
+# Setup
+
+## Install and init
+
+```bash
+npm i state-scenarios zod msw          # msw only when scenarios mock the network
+npm i -D state-scenarios-cli @playwright/test
+npm i state-scenarios-react            # useScenarioState, for component state (React, Preact)
+
+npx state-scenarios init src/scenarios
+```
+
+`init` writes `src/scenarios/default.json` and `src/scenario.schema.json`, prints a wiring snippet,
+installs these skills into `.agents/skills/` (and `.claude/skills/`), and registers the MCP server
+in `.mcp.json`. It never edits your source files. `--no-skills` skips the skills and the MCP server.
+
+Vite: serve the MSW worker and let the panel save into the project.
+
+```ts
+// vite.config.ts
+import { msw } from 'msw/vite';
+import { stateScenarios } from 'state-scenarios/vite';
+
+export default { plugins: [msw({ mode: 'worker-only' }), stateScenarios({ dir: 'src/scenarios' })] };
+```
+
+Without the MSW Vite plugin: `npx msw init public`.
+
+## Wire the runtime before render
+
+```ts
+import { type ScenarioInput, startScenarios } from 'state-scenarios';
+import { mountPanel } from 'state-scenarios/panel';
+
+if (import.meta.env.DEV) {
+  const session = await startScenarios({
+    scenarios: Object.values(
+      import.meta.glob<ScenarioInput>('/src/scenarios/*.json', { eager: true, import: 'default' }),
+    ),
+    adapters: [], // see below
+    refresh: () => queryClient.resetQueries(), // when scenarios mock the network
+  });
+  mountPanel(session, { schemaPath: '../scenario.schema.json' });
+}
+// then create the router and render
+```
+
+- `await` it before rendering. The first fetches must already hit the scenario's mocks.
+- Routers read the URL once, when they're created. If a module creates the router as soon as it
+  is imported (`export const router = createBrowserRouter(...)`), a static import runs before the
+  session. Import it after:
+
+  ```ts
+  // main.ts: start the session first, then import the router
+  import type { ScenarioInput } from 'state-scenarios';
+
+  if (import.meta.env.DEV) {
+    const { startScenarios } = await import('state-scenarios');
+    await startScenarios({
+      scenarios: Object.values(
+        import.meta.glob<ScenarioInput>('/src/scenarios/*.json', { eager: true, import: 'default' }),
+      ),
+    });
+  }
+
+  const { router } = await import('./routing/router'); // created now, with the scenario's URL
+  ```
+
+- Next.js (App Router): start it from a `'use client'` wrapper in the root layout and render
+  children once it resolves. The package README has the component and the save route.
+- Apps that already run MSW: start your worker and pass it as `worker`. See topic `network`.
+
+## Connect app state
+
+Mock the network first. Add adapters for state no response can produce, such as a panel left open
+or cached data during a refetch.
+
+| State lives in | Connect with                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------ |
+| TanStack Query | `tanstackQuery(queryClient)` from `state-scenarios/tanstack-query`                                           |
+| Zustand        | `zustandAdapter(store, { schema: StoreSchema.partial() })` from `state-scenarios/zustand`                    |
+| Redux          | `withScenarioState(rootReducer, StateSchema)`, then `reduxAdapter(store)`                                    |
+| XState         | `xstateAdapter(machine, { context: ContextSchema })`, then `createActor(machine, { snapshot: xs.snapshot })` |
+| Cookies        | `cookiesAdapter()` from `state-scenarios/cookies`                                                            |
+| A component    | `useScenarioState('page', state, (s) => dispatch({ type: 'set', state: s }), Schema)`                        |
+
+Pass a Zod schema wherever an adapter accepts one: invalid scenario state is then rejected before
+anything changes. `scenarioJsonSchema({ state: { key: Schema } })` regenerates the editor schema
+with typed `state`.
+
+## Check
+
+`npx state-scenarios doctor src/scenarios --base-url http://localhost:5173` passes. Opening
+`/?scenario=default` sets `<html data-scenario="default">`.

package/skills/state-scenarios/references/verify.md

@@ -0,0 +1,47 @@
+# Verify a UI change across every state
+
+Start the dev server, then:
+
+```bash
+npx state-scenarios shoot src/scenarios --base-url http://localhost:5173 --out .scenario-shots
+```
+
+For each scenario `shoot` opens the link in strict mode, waits for `ready`, saves `<name>.png`, and
+checks for unmocked requests, uncaught exceptions and `console.error` calls. `--only a,b` limits
+the run; `--json` prints the report for scripts.
+
+## When a scenario fails
+
+The terminal names a page for it: `❯ details .scenario-shots/<name>.md`. Read that page. It has:
+
+- the codes (`READY_TIMEOUT`, `UNMOCKED_REQUEST`, `SESSION_NOT_STARTED`, `SCENARIO_NOT_IN_APP`, `PAGE_ERROR`,
+  `CONSOLE_ERROR`, `ELEMENT_NOT_FOUND`) and the link that reopens the state;
+- for a ready timeout, whether the selector matched anything, plus distinctive selectors on the
+  page now;
+- for unmocked requests, `network` entries ready to paste (fill in real bodies, or record them);
+- uncaught exceptions and console errors.
+
+Look at the screenshot before changing the scenario: a ready timeout can mean the selector is
+wrong, or that the UI change broke the state. Fix the app when the screenshot shows a bug.
+
+## Evidence
+
+Look at the PNGs for the states the change touches, plus loading, empty and error. Attach the
+relevant ones to the PR. Pages for passing scenarios are deleted on each run, so the `.md` files
+in the output folder are always the current failures.
+
+## In Playwright tests
+
+```ts
+import { openScenario, unhandledRequests } from 'state-scenarios/playwright';
+
+await openScenario(page, 'orders-empty');
+expect(await unhandledRequests(page)).toEqual([]);
+```
+
+## Missing states
+
+Ask which states lack scenarios: loading, empty, error, partial data, long content, permissions,
+signed out. Capture them (topic `capture`). `npx state-scenarios suggest` asks a model to list
+candidate states from the source and drafts them into `proposed/`; treat drafts as ideas, then
+`promote` the reviewed ones.

package/skills/state-scenarios/references/writing-scenarios.md

@@ -0,0 +1,55 @@
+# Writing scenarios
+
+| Field                 | Meaning                                                                                                                                   | Through `extends`                                                        |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `name`                | kebab-case, unique                                                                                                                        | –                                                                        |
+| `extends`             | Scenario name(s) to build on; later parents win                                                                                           | –                                                                        |
+| `path`                | Route it opens at, e.g. `/orders/42`                                                                                                      | inherited                                                                |
+| `url`                 | Query params the app starts with                                                                                                          | merged; `null` removes                                                   |
+| `network[]`           | `method`, `path` (MSW syntax: `/api/users/:id`, absolute URLs, `*`), optional `query`, then one of `response`, `sequence`, `remove: true` | a child entry replaces the parent's with the same method, path and query |
+| `handlers`            | Names of MSW handlers passed to `startScenarios({ handlers })`                                                                            | combined                                                                 |
+| `state`               | Per-adapter state, keyed by adapter key                                                                                                   | deep-merged; `null` removes                                              |
+| `ready`               | Playwright selector visible once this state shows                                                                                         | not inherited                                                            |
+| `viewport`            | `{ "width": 390, "height": 844 }` for `shoot` and `record`                                                                                | inherited                                                                |
+| `description`, `tags` | For people and the panel                                                                                                                  | not inherited                                                            |
+
+Responses: `body` is sent as JSON, `text` as text (an HTML error page). `status` defaults to 200.
+`headers` sets headers. `delay` is milliseconds, or `"infinite"` to hold the request open for a
+loading state. `sequence` answers successive calls in order and repeats the last one, e.g. fail
+then succeed on retry:
+
+```json
+{
+  "name": "flaky-then-recovers",
+  "extends": "default",
+  "network": [{
+    "path": "/api/orders",
+    "sequence": [{ "status": 503, "body": { "error": "busy" } }, { "body": [{ "id": 1 }] }]
+  }],
+  "ready": "text=Order #1"
+}
+```
+
+Loading state: `"response": { "delay": "infinite" }` and `"ready": "text=Loading orders…"`.
+
+## Ready selectors
+
+`text=No orders yet`, `role=heading[name="Orders"]`, `[data-testid=empty-orders]`, or CSS. Pick
+something that is visible only in this state: a count like "0" or a heading every state shares is
+too generic. Check it against the running app (panel, or MCP `check_ready`) before saving.
+
+## Combining
+
+`?scenario=signed-in,server-error` combines scenarios like `extends`, later names winning.
+
+## Rules and validation
+
+`defineScenarioRules` checks business rules on every resolved scenario. Export `rules` from a module
+and pass it to `startScenarios({ rules })` and `--rules` on the CLI.
+
+```bash
+npx state-scenarios validate src/scenarios --rules src/scenario-rules.ts
+```
+
+Schema shape, `extends` lookups and rules are checked. Whether production can actually reach a
+state is your call: a valid scenario can describe a response the backend never sends.