kaloko 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "See what your AI agents built: every screen, language and device walked, assessed and approved on one canvas.",
   "keywords": [
     "qa",

package/schemas/config.v1.json

@@ -193,7 +193,9 @@
         "kind": { "enum": ["app", "design"], "default": "app", "description": "app: the application under test (a web app at base_url, or a native app in the app block). design: a folder of live HTML steps served locally by the CLI (serve); its runs are published as design versions (#42)." },
         "serve": { "type": "string", "description": "kind: design. Folder with one sub-folder per step (<step>/index.html, optional <step>/<locale>/index.html) and shared files in _shared/; relative to the config." },
         "fixtures": { "type": "string", "description": "kind: design. Folder of JSON fixtures live steps may fetch instead of real APIs; relative to the config." },
+        "origins": { "type": "array", "maxItems": 20, "items": { "type": "string", "pattern": "^https://(\\*\\.)?[A-Za-z0-9.-]+(:[0-9]{1,5})?/?$" }, "description": "kind: design. Origins the design loads fonts, stylesheets and images from (https://fonts.googleapis.com, https://*.cdn.example.com). The organization allows them in Settings → Security; kaloko design lint warns about one it does not allow. Scripts never load from them." },
         "tokens_mode": { "type": "string", "description": "kind: design. Token mode (e.g. light, dark) steps are rendered in; default: the token set's first mode." },
+        "token_modes": { "oneOf": [{ "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$" } }, { "const": false }], "description": "kind: design. Token modes of the token set to render every step in, one capture per mode (keys <viewport>.mode-<name>); tokens_mode is the default and has the plain key. Not set: every mode of the set when it has two or more, except a set of only light and dark (left to color_schemes). false: only tokens_mode." },
         "html_view": { "type": "boolean", "default": false, "description": "Experimental (#42): keep a static HTML view of every capture (assets rehosted, scripts removed, secrets scrubbed). Refused on production unless the environment is readonly." },
         "base_url": {
           "oneOf": [

package/schemas/revision.v1.json

@@ -12,6 +12,12 @@
     "state": { "type": "string", "default": "default", "description": "default, a design state (empty, error, …) or view:<viewport> for an HTML view." },
     "kind": { "enum": ["design", "html_view"], "default": "design" },
     "entry": { "type": "string" },
+    "items": {
+      "type": ["array", "null"],
+      "description": "Stack steps (#61): the variants of the step, each a folder of the step with its own page (<step>/<id>/index.html). The revision covers the whole step folder; its entry is the overview page or the first variant's.",
+      "maxItems": 200,
+      "items": { "type": "object", "required": ["id", "entry"], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" }, "entry": { "type": "string" } } }
+    },
     "files": { "$ref": "bundle.v1.json#/properties/files" },
     "tokens": { "type": ["object", "null"], "properties": { "project": { "type": ["string", "null"] }, "version": { "type": ["integer", "null"] }, "hash": { "type": ["string", "null"] } } },
     "based_on": { "type": ["string", "null"], "description": "The revision this one changed (a canvas edit, a sync on top of the draft)." },
@@ -31,6 +37,11 @@
           "mode": { "type": "string" }
         }
       }
+    },
+    "item_captures": {
+      "type": "object",
+      "description": "Stack steps (#61): item id → viewport → rendered capture of that variant, shaped like captures.",
+      "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/properties/captures/additionalProperties" } }
     }
   }
 }

package/schemas/run.v1.json

@@ -156,11 +156,11 @@
         },
         "viewports": {
           "type": "object",
-          "description": "Capture key -> [width, height]. A key is the viewport name plus the dimension values that differ from the default, joined by dots (mobile, mobile.webkit, iphone-15.webkit.dark.reduce)."
+          "description": "Capture key -> [width, height]. A key is the viewport name plus the dimension values that differ from the default, joined by dots (mobile, mobile.webkit, iphone-15.webkit.dark.reduce). Token modes of a design add mode-<name>, step states state-<name> as the last part (mobile.mode-brand-b, mobile.dark.state-empty)."
         },
         "variants": {
           "type": "object",
-          "description": "Capture key -> { viewport, browser, color_scheme?, reduced_motion?, forced_colors?, display_mode?, device? }. Absent in runs without dimensions: every key is then a plain viewport in Chromium.",
+          "description": "Capture key -> { viewport, browser, color_scheme?, reduced_motion?, forced_colors?, display_mode?, token_mode?, step_state?, device? }. Absent in runs without dimensions: every key is then a plain viewport in Chromium.",
           "additionalProperties": {
             "type": "object",
             "properties": {
@@ -170,13 +170,15 @@
               "reduced_motion": { "enum": ["no-preference", "reduce"] },
               "forced_colors": { "enum": ["none", "active"] },
               "display_mode": { "enum": ["browser", "standalone"] },
+              "token_mode": { "type": "string", "description": "Token mode of the design's token set the key was rendered in." },
+              "step_state": { "type": "string", "description": "Step state (default, empty, error, loading…) of the key." },
               "device": { "type": "string" }
             }
           }
         },
         "dimensions": {
           "type": "object",
-          "description": "Values of each dimension the run walked (browsers, color_schemes, reduced_motion, forced_colors, display_modes) for the canvas switchers."
+          "description": "Values of each dimension the run walked (browsers, color_schemes, reduced_motion, forced_colors, display_modes, token_modes with the default mode first, states with default first) for the canvas switchers. A step that has no such state has no captures under its keys."
         },
         "devices": {
           "type": "object",
@@ -463,6 +465,8 @@
                 "reduced_motion": { "type": "string" },
                 "forced_colors": { "type": "string" },
                 "display_mode": { "type": "string" },
+                "token_mode": { "type": "string", "description": "Token mode a design capture was rendered in." },
+                "step_state": { "type": "string", "description": "Step state of the capture (default, empty, error…)." },
                 "device_preset": { "type": "string", "description": "Viewport name of the device preset the capture emulated." },
                 "device": { "type": ["string", "null"] },
                 "tree": { "type": ["string", "null"], "description": "UI tree of an app capture (qawalk.tree.v1)." },
@@ -562,6 +566,11 @@
           "type": "object",
           "description": "Page metadata per locale (meta, links, JSON-LD, microdata, headings)."
         },
+        "states": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Step states the step is captured in (default first), when its scenario step lists states."
+        },
         "session": {
           "type": [
             "string",

package/schemas/scenario.v1.json

@@ -68,6 +68,7 @@
     "reduced_motion": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["no-preference", "reduce"] }, "description": "prefers-reduced-motion values (keys <viewport>.reduce)." },
     "forced_colors": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["none", "active"] }, "description": "forced-colors (Windows high contrast) values (keys <viewport>.forced)." },
     "display_modes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["browser", "standalone"] }, "description": "PWA display modes: standalone captures the page as an installed app (display-mode media rules and matchMedia; the whole screen of a device preset)." },
+    "token_modes": { "oneOf": [{ "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$" } }, { "const": false }], "description": "Design environments: token modes of the token set to render every step in (keys <viewport>.mode-<name>). Not set: every mode of the set (see the environment's token_modes). false: only the environment's tokens_mode." },
     "devices": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "description": "App scenarios: devices to walk on, e.g. pixel-8-api-34, iphone-15-ios-18 (emulators, simulators or real devices named in the environment's app.<platform>.devices). One capture key per device." },
     "environments": {
       "type": "array",
@@ -311,6 +312,13 @@
           ],
           "description": "For `kaloko walk --affected`: globs of repository files (relative to the config) that shape this step, next to the routes and imports Kaloko finds itself; `always` walks the step on every affected walk (sign-in, consent)."
         },
+        "states": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$", "not": { "enum": ["index"] } },
+          "description": "States this step is captured in besides the default one, e.g. [empty, error, loading]; any name works. Each state is one more capture per viewport (keys <viewport>.state-<name>) and a value of the State switcher on the canvas. Design steps render <step>/<state>.html (or <step>/<locale>/<state>.html), else <step>/index.html?state=<name>; walks of web and app steps run the step script once more per state with the argument state. `default` may be listed; it is always captured."
+        },
         "page": {
           "enum": ["landing", "work", "list", "settings", "form", "doc"],
           "description": "What kind of page this step is (see the scenario's page); the usability pack asks per type, e.g. one primary call to action only on landing pages."
@@ -542,6 +550,12 @@
           "minItems": 1,
           "items": { "type": "string" },
           "description": "Environments where this criterion applies, e.g. [production] for hreflang to the live domain, the live demo or the sitemap. On any other environment the walk reports it as not applicable (not_evaluated with na: environment) and it does not make the step partial."
+        },
+        "states": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$" },
+          "description": "Step states this criterion applies to, e.g. [empty] for \"says the cart is empty\". Captures of other states report it as not applicable (na: state). Not set: every state of the step."
         }
       }
     },

package/skills/kaloko/reference/design.md

@@ -37,6 +37,11 @@ design/
   images, fonts, module imports, `fetch('./fixtures/x.json')`). Links to other steps are not files it needs.
 - Live steps run sandboxed on their own origin with `connect-src 'self'`: no real APIs. Use JSON fixtures in
   the bundle.
+- Web fonts and images from a service (Google Fonts, Adobe Fonts, the company CDN) load only from origins an
+  organization admin allows in Settings → Security. List the ones the design uses on the environment
+  (`design: { kind: design, serve: design, origins: [https://fonts.googleapis.com, https://fonts.gstatic.com] }`);
+  `kaloko design lint` warns about each the organization does not allow yet, so tell the person to ask an admin.
+  Scripts never load from those origins.
 - Links between steps are plain relative links to the page: `<a href="../payment/index.html">`. The canvas
   follows them; `data-kaloko-go="payment"` (or `data-qawalk-go`) moves to that step whatever the `href` says.
 - Reference token values as CSS custom properties named after the token path (`color.accent` →
@@ -48,6 +53,40 @@ design/
   `kaloko design lint` checks the folder; `kaloko sync` runs it first and stops on errors (things that break on
   the live step), warnings are printed.
 
+## Variants of one template (stack steps)
+
+A step that comes in variants of one template (an e-mail per reason support can pick, a landing per city, a card per
+plan) is one stack step ([stacks.md](stacks.md)), not one step per variant in a lane of its own:
+
+```yaml
+- id: credit
+  kind: stack
+  title: Credit from support
+  items: { urls: [refund, late, damaged] }   # folders of the step; without folder names: every subfolder with a page
+  fields: [{ id: reason, label: Reason, from: .reason }]
+  criteria: [...]                            # every variant meets them
+```
+
+```
+design/credit/index.html                  optional overview (the step's entry; links into the variants)
+design/credit/refund/index.html           one folder per variant: its page and the files next to it
+design/credit/refund/cs/index.html        a locale override of one variant
+design/credit/late/index.html
+```
+
+- `items.urls` that name folders (`refund`, `./refund/`, `refund/index.html`) list the variants in that order. App
+  paths (`/credit?reason=refund`), other sources or no list: every subfolder with an `index.html` is a variant,
+  sorted by name. Locale folders, `dark/` and folders starting with `_` are never variants.
+- One revision covers the whole step folder; changing a variant is a new revision of the step. The walk captures
+  every variant in every viewport (`items.viewports` narrows it) with the index fields and criteria, and reuses
+  captures per revision and variant.
+- `kaloko sync` sends the variants' captures with the step; the published version shows the stack index with every
+  variant and its verdict, and each variant opens live in the lightbox.
+- `kaloko design lint` reports a variant folder without its `index.html` as an error.
+- `kaloko export --live` and `export --design` write the variant folders; the design export adds
+  `screenshots/<step>/<variant>/<locale>/<viewport>.webp`.
+- Not for steps whose variants are different screens of a flow: those stay separate steps.
+
 ## Devices, dark mode and app screens
 
 Design steps can target device presets and colour schemes like any run ([devices.md](devices.md)):
@@ -68,6 +107,30 @@ color_schemes: [light, dark]
   step spec and the token check of a dark capture name the dark tokens, and drift compares dark with dark.
 - Browsers: design steps render in Chromium. Check the implementation in WebKit and Firefox instead.
 
+## Step states and token modes
+
+A step lists its other states in the scenario (`states: [empty, error, loading]`; any name of letters, digits, `-`
+and `_` works). Draw each one so it can be reviewed and built:
+
+- A state is a page next to the step's page: `<step>/<state>.html`, per locale `<step>/<locale>/<state>.html`. It
+  travels with the step's revision like the dark page; give it its own fixtures (`<step>/empty.json`, or a literal
+  `fetch('./fixtures/cart-empty.json')`) so the closure finds them.
+- Without that page the walk opens `<step>/index.html?state=<name>` and says so. Use it when one page switches its
+  states in JS (`new URLSearchParams(location.search).get('state')`); the fixture must still be next to the page or
+  fetched by a literal path.
+- Captures of a state are keyed `<viewport>.state-<name>` (`mobile.dark.state-empty`). Criteria with
+  `states: [empty]` are judged on that state only; other criteria on every state.
+- The canvas shows a State switcher next to the language; review mode and the grid follow it. A step without the
+  state shows its default capture with a note.
+
+Token modes: when the token set has two or more modes (resolver contexts or mode groups), every step renders in each
+mode. The walk sets the mode's tokens as custom properties on `:root` after the page's own styles and
+`data-kaloko-mode="<mode>"` on `<html>`; a page that switches themes by class can read the attribute. Captures are
+keyed `<viewport>.mode-<name>`; the environment's `tokens_mode` (else the first mode) is the default with the plain
+key, and the canvas switches modes like colour schemes. A set with only `light`/`dark` modes follows the colour
+scheme instead (`color_schemes: [light, dark]`), unless `token_modes` names them. `token_modes: [brand-a, brand-b]` (environment, scenario or `kaloko start
+--token-modes`) picks modes; `false` turns it off. Live view shows the default mode; other modes are screenshots.
+
 **Native app screens as portable HTML.** A mockup of an iOS or Android screen is a full-screen page:
 
 - Size it to the screen, not to a document: `html, body { height: 100% }` and the main area `min-height: 100dvh`.
@@ -121,7 +184,36 @@ opens straight into the presentation of that step: share it with the person who
   without it, a step never rendered live) the presentation shows the screenshots.
 - From the local preview and an offline export, the steps open from the run's merged folder (`live/site/`), so plain
   relative links click through there too.
-- A link's query and hash travel to the next step (`../payment/index.html?plan=pro#card`): keep prototype state there.
+- A link's query and hash travel to the next step (`../payment/index.html?plan=pro#card`): enough for one value.
+  For more, use the prototype state below.
+
+### Prototype state
+
+Steps of a prototype share a small store, so a cart filled on one step shows on the next. The frame helper of the
+live step provides `window.kaloko.state`; the canvas keeps it for the viewer in their browser tab, per draft or
+version, and never sends it to the service. *Start over* in the presentation clears it.
+
+```html
+<!-- payment/index.html: the seeds are what the step shows when nothing set it yet -->
+<script type="application/json" id="seed" data-kaloko-state>{ "cart": [{ "name": "Tea", "price": 120 }] }</script>
+<script>
+  const render = (s) => { /* draw s.cart */ }
+  // first the step's own seeds, so it looks right alone (from disk, in a capture, in an export)
+  render(JSON.parse(document.getElementById('seed').textContent))
+  // then what the prototype remembers: the helper loads after the page's scripts and the state comes a moment later
+  addEventListener('kaloko:state', (e) => render(e.detail.state))
+</script>
+```
+
+- `kaloko.state.get(key)`, `set(key, value)` (JSON, up to 64 kB; `null` removes the key), `update(key, fn)`,
+  `subscribe(fn)` (called with the whole state now and on every change; returns an unsubscribe function), `reset()`,
+  `ready` (a promise of the first state). The `kaloko:state` event on `window` carries the same state; scripts that
+  run before the helper use it.
+- The seeds in `<script type="application/json" data-kaloko-state>` fill keys that nothing has set yet. Give every
+  step that reads state seeds that make it look right on its own: reviewers open steps directly, captures render
+  each step alone, and the local preview and exports have no helper, so `window.kaloko` is missing there.
+- Write with `set` or `update` on the step where the person acts (`update('cart', (c) => [...(c || []), item])`),
+  read on the next. Keep it small: ids, counts and form values, not page markup.
 
 ## What changed in a version
 

package/skills/kaloko/reference/execution.md

@@ -34,6 +34,12 @@ call `kaloko session reset` themselves when the plan starts as a new visitor.
   to the node's person (`session.key`, `title`, `mailbox`, `account`, and
   `credentials` for that account in the run's environment; see
   [environments.md](environments.md#accounts-and-sign-in)).
+- Step states: a step with `states: [empty, error]` runs its script once
+  more per state with `state` (`'default'` first, then `'empty'`, …); bring
+  the page into that state (route a mocked API response with `page.route`,
+  empty the cart) before the capture. Each run captures that state's keys
+  (`mobile.state-empty`). For a step an agent walks:
+  `kaloko capture --step <id> --state empty`. App scripts get `state` too.
 - `agent` — steps that need judgement or change often. Follow
   `execution.instructions`, then `kaloko capture --step <id>`.
 - `manual` — a person does it; you capture afterwards.

package/skills/kaloko/reference/portable-html.md

@@ -19,7 +19,14 @@ warnings, `--json` gives every finding with file, line, rule and fix.
   `https://`, no protocol-relative `//cdn…`, no paths starting with `/` (on the live origin `/` is the origin root, from
   disk it is the disk root). Errors: `external-url`, `root-relative`, `outside-folder`, `missing-file`.
 - **No CDNs.** Download libraries into `_shared/` and link them relatively. Fonts are bundled as **woff2**, subset to
-  the characters used, with `@font-face` in the shared CSS; Google Fonts links do not load.
+  the characters used, with `@font-face` in the shared CSS.
+- **Font and asset origins** are the one exception, for stylesheets, fonts and images only: an organization admin
+  allows origins such as `https://fonts.googleapis.com`, `https://fonts.gstatic.com`, `https://use.typekit.net` or
+  the company CDN in Settings → Security, and live steps load them. Declare the ones the design uses on the design
+  environment (`origins: [https://fonts.googleapis.com, https://fonts.gstatic.com]`); `kaloko design lint` then
+  takes them instead of an `external-url` error and warns (`origin-not-allowed`) about each the organization does
+  not allow yet. Scripts, module imports, `fetch` and video never load from them. A bundled font still works from
+  disk and from an export; prefer it when you can.
 - Only bundle file types (html, css, js, mjs, json, svg, woff2, woff, png, jpg, webp, avif, gif, mp4, webm, txt).
   Convert TTF/OTF fonts and other formats (`file-type`).
 - **Size budget:** a file over 1 MB or a step over 5 MB (with the shared files) warns (`large-file`); 10 MB per file
@@ -40,8 +47,10 @@ warnings, `--json` gives every finding with file, line, rule and fix.
 
 ## State and data
 
-- **State lives in the URL**, not in storage: `localStorage`, `sessionStorage`, IndexedDB and cookies throw in the
-  sandboxed frame and are empty for every other viewer (`storage`). Use `location.hash` or the query
+- **State between steps lives in `window.kaloko.state` or the URL**, not in storage: `localStorage`,
+  `sessionStorage`, IndexedDB and cookies throw in the sandboxed frame and are empty for every other viewer
+  (`storage`). For a cart, a chosen plan or details filled in on an earlier step use the prototype state
+  ([design.md → Prototype state](design.md#prototype-state)); for a single value the query and hash do
   (`?plan=pro#card`): a link's query and hash travel to the next step in the presentation, and work from disk.
   Wrap any storage access you keep in `try/catch` with a fallback.
 - **No network:** real APIs, `XMLHttpRequest`, `WebSocket`, `EventSource` do not connect (`websocket`). Put data in

package/skills/kaloko/reference/stacks.md

@@ -126,5 +126,11 @@ two or three example paths), whether the limit cut the list, and that
 semantic criteria covered only the sample. Put the full list in the CSV or
 the MCP result rather than in the issue.
 
+## Design environments
+
+On a design environment a stack step is a template with its variants: each variant is a folder of the step,
+`design/<step>/<variant>/index.html`, listed by `items.urls` or discovered from subfolders, and every variant is
+captured in every viewport. See [design.md](design.md#variants-of-one-template-stack-steps).
+
 Not yet supported for stacks: comparison with a baseline run per page and
 the documentation layer (latest captures per step).

package/src/cli.mjs

@@ -50,6 +50,7 @@ import { walkDesign, syncDesign, publishVersion, previewNotes, historyCmd, refer
 import { screensCmd } from './lib/screens-cli.mjs'
 import { designDir, readBase, headKey } from './lib/design.mjs'
 import { lintDesign, formatLint } from './lib/design-lint.mjs'
+import { cleanAssetOrigins } from './lib/design-origins.mjs'
 import { exportDesign } from './lib/design-export.mjs'
 import { driverFor, isApp, pngSize, ocr as ocrImage } from './lib/apps/drivers.mjs'
 import { captureApp } from './lib/apps/capture.mjs'
@@ -57,7 +58,7 @@ import { readTree, flatten } from './lib/apps/tree.mjs'
 import { recordSettings, recordingSession, parseRecord, recordingFiles, traceFiles, stripRecordings, withoutRecordings } from './lib/recording.mjs'
 import { nativeSession } from './lib/apps/recording-native.mjs'
 import { videoCmd } from './lib/video-cli.mjs'
-import { passesOf, enginesOf, contextOptionsOf, launchEngine, pickKeys, variantFields, variantOf, dimensionValues, BROWSERS } from './lib/dimensions.mjs'
+import { passesOf, enginesOf, contextOptionsOf, launchEngine, pickKeys, variantFields, variantOf, dimensionValues, stateKeys, nodeStates, BROWSERS } from './lib/dimensions.mjs'
 import { startScope, scopeKeys, dimensionLine, baseViewports, engineKeys, appDeviceGroups } from './lib/walk-dimensions.mjs'
 import { deviceConfig, prepareAndroid, readyAndroid, finishAndroid, prepareSimulator, applyAppAppearance } from './lib/apps/devices.mjs'
 import { attachAndroidWebView } from './lib/apps/webview.mjs'
@@ -113,6 +114,9 @@ Run
                                     More dimensions: every step is captured in each combination (keys like
                                     mobile.webkit.dark); default from the scenario, then walk: in the config
        [--devices pixel-8-api-34,iphone-15-ios-18]   App scenarios: the emulators, simulators or devices to walk on
+       [--states empty,error]       Only these step states (states: on a step; keys like mobile.state-empty)
+       [--token-modes brand-a,brand-b | --token-modes none]
+                                    Design environments: the token modes to render (default every mode of the set)
   browser start|stop|status [--env e] [--headed]   One shared browser per environment (port = browser.port + index)
                                     Shared Chromium with CDP (agents, scripts and people drive it)
   browser install [--with-deps] [--browsers chromium,webkit,firefox]
@@ -121,8 +125,8 @@ Run
   devices [--json]                  Device presets for viewports: (phones, foldables, tablets, laptop, desktop, TV)
   open --step <id> [--locale l]     Navigate the current page to the step URL
   session reset                     New visitor: clear cookies and storage in the shared browser
-  capture --step <id> [--locale l] [--url <url>] [--page <substring>] [--viewports a,b]
-                                    Capture the current page for a step in all viewports
+  capture --step <id> [--locale l] [--url <url>] [--page <substring>] [--viewports a,b] [--state <name>]
+                                    Capture the current page for a step in all viewports (--state: as that step state)
   capture --step <id> --crop <css> [--title <text>]
                                     Attach an element screenshot to a step
   capture --step <id> --image <shot.png> [--tree <dump.xml|json> | --ocr] [--platform android|ios|desktop]
@@ -307,9 +311,11 @@ Design (environments with kind: design; live HTML steps in a folder)
   sync [--pull|--push] [--branch b] [--mine a,b|--theirs a,b] [--no-lint]
                                     Exchange revisions with the shared draft; only changed steps and missing files travel
                                     Lints the folder first: errors (things that break on the live step) stop the push
-  design lint [--env e | --dir design/] [--scenario file] [--all] [--strict] [--json]
+  design lint [--env e | --dir design/] [--scenario file] [--all] [--strict] [--offline] [--json]
                                     Check the folder against the portable HTML rules (relative URLs, no CDNs, no storage,
-                                    deterministic content, viewport, lang, links that also work from disk); --strict fails on warnings
+                                    deterministic content, viewport, lang, links that also work from disk); --strict fails on warnings.
+                                    Fonts, styles and images from origins of the environment are compared with the
+                                    organization's allowed origins (--offline skips that)
   share [--name <text>] [--branch b] [--notes file|-] [--notes-preview]
                                     Publish the draft as a version of the flow (a run): "v4 · 3 changed, 17 unchanged",
                                     with "what changed" notes per step (screens per viewport, text, tokens); --notes-preview
@@ -321,7 +327,7 @@ Design (environments with kind: design; live HTML steps in a folder)
                                     a folder exported from Figma works without a token. One way: no prototype links
   history [--scenario id] [--step id] [--locale l] [--json]
                                     Versions of the flow; revisions of a step with who (person or agent) and when
-  spec [step] [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--local] [--json]
+  spec [step] [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--state s] [--local] [--json]
                                     What to build for a step as approved: elements with role, name and selector, styles
                                     mapped to DTCG tokens (or the nearest one), :hover/:focus/:active/:disabled, contrast
   drift [step] [--ref design|vN] [--remote <run id|latest>] [--json]
@@ -457,6 +463,21 @@ function stepOf (scenario, id) {
   return node
 }
 
+/**
+ * Font and asset origins for `kaloko design lint` (#46): `wanted` from `origins` of the design environment, and with
+ * `online` the organization's list from the service (GET /me design_origins; null when not signed in or unreachable).
+ */
+async function lintOrigins (config, env, { online = false } = {}) {
+  let wanted = []
+  try { wanted = cleanAssetOrigins(env?.origins || []) } catch (e) { throw new UserError(`Environment ${env.name}, origins: ${e.message}`) }
+  if (!online || !wanted.length) return { wanted, allowed: null }
+  let timer
+  try {
+    const me = await Promise.race([service(config).request('GET', '/me'), new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error('timeout')), 8000) })])
+    return Array.isArray(me?.design_origins) ? { wanted, allowed: me.design_origins } : { wanted, allowed: null, unchecked: true }
+  } catch { return { wanted, allowed: null, unchecked: true } } finally { clearTimeout(timer) }
+}
+
 /** Scenario of --scenario (id or file) or of the current run. */
 /**
  * kaloko design import figma <file-url|key|folder>: Figma frames (or a folder exported from Figma) become the steps of
@@ -488,7 +509,7 @@ async function designImport (args) {
   if (args.json) say(JSON.stringify(r, null, 2))
   else say(formatImport(r, { dir: relative(process.cwd(), dir) || '.' }))
   if (args['dry-run']) return r
-  const lint = await lintDesign({ dir, scenario })
+  const lint = await lintDesign({ dir, scenario, origins: await lintOrigins(config, env) })
   if (lint.errors) say(`\n${formatLint(lint, { max: 10 })}`)
   if (!args.publish) {
     say(`\nNext: kaloko start --scenario ${relative(process.cwd(), scenarioFile)} --env ${env.name} && kaloko walk && kaloko share (or rerun with --publish).\nAccept the version on the canvas and set it as the design reference (kaloko reference --design --version <n>): implementation runs with packs: [design] are then checked against these frames.`)
@@ -521,6 +542,24 @@ function manualKeys (run, pick) {
   return scopeKeys(scope, keys.length ? keys : engineKeys(scope, 'chromium'), null)
 }
 
+/** Modes of a design environment's token set (tokens.resolver.json or tokens.json); [] without one. */
+async function designTokenModesOf (config, root, env) {
+  try {
+    const { loadTokens } = await import('./lib/drift.mjs')
+    const { modesOf } = await import('./lib/tokens.mjs')
+    const set = await loadTokens({ client: null, config, root, designDir: designDir(env, root) })
+    return set ? modesOf(set) : []
+  } catch { return [] }
+}
+
+/** --state <name> (#46): the keys of that state of the step instead of the default ones. */
+function inState (run, node, keys, state) {
+  if (!state || state === true || state === 'default') return keys
+  const have = nodeStates(run.meta.scope, node)
+  if (!have.includes(state)) throw new UserError(`Step ${node.id} has no state "${state}" in this run (${have.length > 1 ? `its states: ${have.join(', ')}` : 'add states: to the step and start a new run'}).`)
+  return Object.fromEntries(stateKeys(run.meta.scope, Object.keys(keys), state).map((k) => [k, run.meta.scope.viewports[k]]))
+}
+
 /** { key: [w, h] } a capture on a Chromium page takes: every Chromium key of the run, or those of `pick`. */
 function scopeViewports (run, pick) {
   return scopeKeys(run.meta.scope, engineKeys(run.meta.scope, 'chromium'), pick)
@@ -772,15 +811,17 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
             if (!scripted && !(link && ['playwright', 'script'].includes(node.execution?.strategy))) { pending.push(`${node.id} (${locale}): ${node.execution?.strategy || 'agent'} — ${(node.execution?.instructions || '').split('\n')[0]}`); continue }
             const streakKey = `${group.device || ''}|${locale}`
             if (streak.stopped(streakKey)) { skipped.push(`${node.id} (${locale}${tag})`); continue }
-            const records = []
+            let records = []
+            // step states (#46): the script (or the deep link) runs once per state; `state` tells the script which
+            let state = 'default'
             try {
               let captured = false
               await rec?.beforeStep(node)
               const capture = async (o = {}) => {
                 captured = true
-                await rec?.beforeCapture(node)
+                if (state === 'default') await rec?.beforeCapture(node)
                 // a named viewport: within this device, or any of the run when it has no devices (as before)
-                const keys = o.viewport ? pickKeys(scope, group.device ? group.keys : Object.keys(scope.viewports), [o.viewport]) : group.keys
+                const keys = stateKeys(scope, o.viewport ? pickKeys(scope, group.device ? group.keys : Object.keys(scope.viewports), [o.viewport]) : group.keys, state)
                 if (!keys.length) throw new UserError(`Unknown viewport "${o.viewport}" for ${group.device || platform}.`)
                 const out = []
                 for (const key of keys) {
@@ -803,14 +844,25 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
                 records.push(...out)
                 return out.length === 1 ? out[0] : out
               }
-              if (scripted) {
-                const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
-                await mod.default({ app: driver, page: driver.page || null, webview: driver.webview || null, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, device: group.device, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
-              } else await driver.link(link)
-              if (!captured) await capture()
+              const mod = scripted ? await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href) : null
+              const once = async () => {
+                captured = false
+                if (mod) await mod.default({ app: driver, page: driver.page || null, webview: driver.webview || null, locale, state, node: { id: node.id, title: localized(node.title, locale), kind: node.kind, ...(node.states ? { states: nodeStates(scope, node) } : {}) }, device: group.device, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
+                else await driver.link(link)
+                if (!captured) await capture()
+              }
+              await once()
               await rec?.afterStep(node, driver.web ? { records } : { record: records[0] })
               say(`✓ ${node.id} ${locale}${tag}`)
               streak.ok(streakKey)
+              for (const s of nodeStates(scope, node).slice(1)) {
+                state = s; records = []
+                try { await once(); say(`✓ ${node.id} ${locale}${tag} · ${s}`) } catch (error) {
+                  failed.push(`${node.id} (${locale}${tag} · ${s}): ${error.message.split('\n')[0]}`)
+                  say(`✗ ${node.id} ${locale}${tag} · ${s}: ${error.message.split('\n')[0]}`)
+                }
+              }
+              state = 'default'
             } catch (error) {
               await rec?.afterStep(node, driver.web ? { error, records } : { error, record: records[0] }).catch(() => {})
               failed.push(`${node.id} (${locale}${tag}): ${error.message.split('\n')[0]}`)
@@ -1026,7 +1078,9 @@ const commands = {
     if (scenario.environments && !scenario.environments.includes(env.name)) throw new UserError(`Scenario ${scenario.id} is not allowed on ${env.name} (allowed: ${scenario.environments.join(', ')}).`)
     if (env.readonly && !scenario.readonly) throw new UserError(`Environment ${env.name} is readonly; the scenario must declare readonly: true.`)
     const locales = list(args.locales) || scenario.locales || ['default']
-    const scope = { ...startScope({ args, scenario, config, env }), ...(args.note ? { note: args.note } : {}) }
+    // design environments render every mode of their token set (#46): the modes come from the folder's set
+    const tokenModes = env.kind === 'design' ? await designTokenModesOf(config, root, env) : []
+    const scope = { ...startScope({ args, scenario, config, env, tokenModes }), ...(args.note ? { note: args.note } : {}) }
     scope.locales = locales
     const vpNames = baseViewports(scope)
     const git = await gitMeta(root)
@@ -1105,7 +1159,8 @@ const commands = {
     }
     if (isApp(scenario.platform)) {
       // the app's current screen, through the environment's driver (no navigation); --viewport may name a device key
-      const key = typeof args.viewport === 'string' ? args.viewport : Object.keys(run.meta.scope.viewports || {})[0]
+      const key0 = typeof args.viewport === 'string' ? args.viewport : Object.keys(run.meta.scope.viewports || {})[0]
+      const key = Object.keys(inState(run, node, { [key0]: run.meta.scope.viewports[key0] }, args.state))[0] || key0
       const device = run.meta.scope.devices?.[variantOf(run.meta.scope, key).viewport]?.app ? variantOf(run.meta.scope, key).viewport : null
       const cfg = deviceConfig(scenario.platform, env.app?.[scenario.platform] || {}, device)
       const driver = driverFor(scenario.platform, { ...env, app: { ...(env.app || {}), [scenario.platform]: cfg } }, { root, scenarioDir: resolve(root, run.meta.scenario_file, '..'), locale })
@@ -1139,7 +1194,7 @@ const commands = {
         return
       }
       const since = (await readCaptures(run.dir)).filter((c) => c.node === node.id).map((c) => c.at).pop()
-      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: manualKeys(run, list(args.viewports)), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
+      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: inState(run, node, manualKeys(run, list(args.viewports)), args.state), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
       for (const r of results) {
         const failed = Object.entries(r.checks).filter(([, v]) => v.ok === false).map(([k]) => k)
         say(`✓ ${node.id} ${locale} ${r.viewport}  ${r.size.width}×${r.size.height}px  ${failed.length ? `failing checks: ${failed.join(', ')}` : 'checks ok'}${r.blocked_requests.length ? `  blocked: ${r.blocked_requests.length}` : ''}`)
@@ -1197,8 +1252,8 @@ const commands = {
       }
     }
     if (env.kind === 'design') {
-      await walkDesign({ config, root, run, scenario, env, pick: list(args.steps), locales: list(args.locales) || run.meta.scope.locales, viewports: scopeViewports(run, list(args.viewports)), say, noCache: !!args['no-cache'] })
-      const lint = await lintDesign({ dir: designDir(env, root), scenario })
+      await walkDesign({ config, root, run, scenario, env, pick: list(args.steps), locales: list(args.locales) || run.meta.scope.locales, viewports: scopeKeys(run.meta.scope, engineKeys(run.meta.scope, 'chromium', '*'), list(args.viewports)), say, noCache: !!args['no-cache'] })
+      const lint = await lintDesign({ dir: designDir(env, root), scenario, origins: await lintOrigins(config, env) })
       if (lint.errors || lint.warnings) say(`\nPortable HTML: ${lint.errors} error(s), ${lint.warnings} warning(s); kaloko design lint lists them${lint.errors ? ' (errors stop kaloko sync: they break on the live step)' : ''}.`)
       return
     }
@@ -1341,22 +1396,32 @@ const commands = {
               const scriptFile = resolve(scenarioDir, node.execution.script)
               // one invocation of the step script; the automatic capture runs unless the script captured the step itself:
               // a crop is an attachment (#49), and a capture from an earlier walk must not stand in for this one (#50)
-              const rec = await recorderFor(sPage)
-              const runStep = async (mod) => {
+              const rec0 = await recorderFor(sPage)
+              // step states (#46): the script runs once per state with `state`; each run captures that state's keys
+              // (the recording follows the default state)
+              const runStep = async (mod, state = 'default') => {
                 let captured = false
+                const rec = state === 'default' ? rec0 : null
                 rec?.beforeStep(node)
                 const records = []
-                const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeKeys(run.meta.scope, pass.keys, opts.viewports || null), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
+                const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeKeys(run.meta.scope, stateKeys(run.meta.scope, Object.keys(scopeKeys(run.meta.scope, pass.keys, opts.viewports || null)), state)), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
                 try {
-                  await mod.default({ page: sPage, context: sCtx, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
+                  await mod.default({ page: sPage, context: sCtx, locale, state, node: { id: node.id, title: localized(node.title, locale), kind: node.kind, ...(node.states ? { states: nodeStates(run.meta.scope, node) } : {}) }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
                   if (!captured) await capture()
                 } catch (error) { await rec?.afterStep(node, { error }); throw error }
                 await rec?.afterStep(node, { records })
               }
               try {
-                await runStep(await import(pathToFileURL(scriptFile).href))
+                const mod = await import(pathToFileURL(scriptFile).href)
+                await runStep(mod)
                 say(`✓ ${node.id} ${locale}${tag}`)
                 streak.ok(streakKey)
+                for (const state of nodeStates(run.meta.scope, node).slice(1)) {
+                  try { await runStep(mod, state); say(`✓ ${node.id} ${locale}${tag} · ${state}`) } catch (error) {
+                    failed.push(`${node.id} (${locale}${tag} · ${state}): ${error.message.split('\n')[0]}`)
+                    say(`✗ ${node.id} ${locale}${tag} · ${state}: ${error.message.split('\n')[0]}`)
+                  }
+                }
               } catch (error) {
                 // a selector the page no longer has: propose one from the page (#13); --heal applies it once the step passes
                 const healed = args['no-heal'] ? null : await healStep({ error, page: sPage, scriptFile, root, output: config.output, run, node, locale, apply: !!args.heal, rerun: runStep }).catch(() => null)
@@ -1796,7 +1861,7 @@ const commands = {
     const client = service(config)
     if (env.kind === 'design' && !args.pull && !args['no-lint']) {
       // what renders locally may still break on the live step (CSP, sandbox): say so before anything is pushed
-      const lint = await lintDesign({ dir: designDir(env, root), scenario })
+      const lint = await lintDesign({ dir: designDir(env, root), scenario, origins: await lintOrigins(config, env, { online: true }) })
       if (lint.errors || lint.warnings) say(formatLint(lint, { max: 15 }) + '\n')
       if (lint.errors) throw new UserError(`${lint.errors} error(s) above break the design on the live step; fix them, or sync with --no-lint to push anyway.`)
     }
@@ -1805,19 +1870,19 @@ const commands = {
 
   async design (args) {
     if (args._[0] === 'import') return designImport(args)
-    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--json]\n       kaloko design import figma <file-url|key|export folder> [--frames a,b] [--map frames.json] [--token-env FIGMA_TOKEN] [--publish]')
+    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--offline] [--json]\n       kaloko design import figma <file-url|key|export folder> [--frames a,b] [--map frames.json] [--token-env FIGMA_TOKEN] [--publish]')
     const { config, root } = await context(args)
     let run = null
     try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
     let dir = typeof args.dir === 'string' ? resolve(args.dir) : null
+    const runEnv = run ? environment(config, run.meta.environment.name) : null
+    const env = typeof args.env === 'string' ? environment(config, args.env) : runEnv?.kind === 'design' ? runEnv : Object.keys(config.environments || {}).map((n) => environment(config, n)).find((e) => e.kind === 'design')
     if (!dir) {
-      const runEnv = run ? environment(config, run.meta.environment.name) : null
-      const env = typeof args.env === 'string' ? environment(config, args.env) : runEnv?.kind === 'design' ? runEnv : Object.keys(config.environments).map((n) => environment(config, n)).find((e) => e.kind === 'design')
       if (!env) throw new UserError('No design environment: pass --dir <folder> or --env <design env>.')
       dir = designDir(env, root)
     }
     const scenario = typeof args.scenario === 'string' && /\.ya?ml$/.test(args.scenario) ? await loadScenario(resolve(args.scenario)) : run ? await loadScenario(resolve(root, run.meta.scenario_file)).catch(() => null) : null
-    const report = await lintDesign({ dir, scenario })
+    const report = await lintDesign({ dir, scenario, origins: env?.kind === 'design' ? await lintOrigins(config, env, { online: !args.offline }) : null })
     say(args.json ? JSON.stringify(report, null, 2) : formatLint(report, { all: !!args.all, max: args.all ? 500 : 60 }))
     if (report.errors || (args.strict && report.warnings)) process.exitCode = 1
   },