kaloko 0.8.0 → 0.10.0

package/README.md

@@ -182,7 +182,9 @@ npx kaloko import walkthrough/ --adhoc      # a Cursor or Antigravity walkthroug
 lays screenshots, Playwright reports and traces out as a run: matched to the
 scenario's steps (by step id in `steps.json`, URL or title), or as an ad-hoc
 flow when there is no scenario. Build and share it like any run. When something does not work (Chrome,
-token, environment URL, evaluator key), `npx kaloko doctor` says what to fix.
+token, environment URL, evaluator key), `npx kaloko doctor` says what to fix, and
+`npx kaloko doctor --fix` installs a missing browser, creates missing folders and fills in `org:` from your token.
+Every error the CLI prints says what to do next; if you are still stuck, write to support@sinfin.cz.
 
 ## Review only what changed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.8.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).