kaloko 0.4.11 → 0.5.1

package/README.md

@@ -11,10 +11,11 @@ there, and the newest captures double as documentation.
 - Product and guides: <https://kaloko.app>
 - Service (organizations, shared canvases, reviews): <https://kaloko.app>
 
-Kaloko also walks **native apps**: Android over adb, the iOS Simulator,
-Electron and macOS apps. Screens taken by any other tool (Maestro, Appium,
-XCUITest) are imported with their UI tree. See the `apps` reference of the
-skill.
+Pages are walked in Chromium, WebKit and Firefox, on phone, tablet and
+desktop presets, in light and dark mode. Native apps too: Android, iOS,
+Electron, macOS and Windows. Screens taken by any other tool (Maestro, Appium,
+XCUITest) are imported with their UI tree. See
+[What Kaloko can walk and design](#what-kaloko-can-walk-and-design).
 
 ## Install
 
@@ -71,8 +72,48 @@ once with `--concurrency 3`. When a step's selector no longer exists, the walk
 proposes one from the page and prints the patch; `--heal` applies it once the
 step passes.
 
+Automatic criteria read the page itself: text, counts and attributes, the URL
+after a step (`url_matches`), computed styles, also against a design token
+(`style_equals` with `token: color.brand.primary`), and read-only values such
+as `localStorage` or `dataLayer` (`js_equals`). A step script never has to
+compute a result and leave a marker for a criterion to find. The acceptance
+reference of the `kaloko` skill lists every check.
+
 `npx kaloko help` lists every command.
 
+## What Kaloko can walk and design
+
+*Full*: Kaloko drives it, captures it and runs the checks. *Capture only*: Kaloko
+takes the screens, your tool or a person moves between them. *Via import*: another
+tool takes the screens and `kaloko capture --image` or `kaloko import` lays them out.
+
+| Target | How | Checks | Design | Support |
+|---|---|---|---|---|
+| Web in Chromium | Playwright, the shared browser or an own one | all | live HTML steps | full |
+| Web in WebKit (Safari's engine) and Firefox | Playwright, one pass per engine | all except the accessibility tree, focus rings and layout shifts (and the Tab walk on WebKit) | rendered in Chromium | full |
+| Phones, foldables, tablets, laptop to 2560 px, TV | device presets: size, pixel ratio, touch, user agent | all | whole screen, device frame, safe areas | full |
+| Light and dark, reduced motion, high contrast | emulated per capture | all; contrast per scheme | dark pages, token modes per scheme | full |
+| Installed web app (PWA) | `display-mode: standalone` rules and `matchMedia` | all | yes | full for CSS; scripts that read the mode at load need a real install |
+| Android: emulator, USB or Wi-Fi phone | adb: deep links, taps, typing, dark mode | UI tree, app pack | HTML mockups | full |
+| Android WebView | DevTools over adb (debuggable builds) | web checks on the page | | full |
+| iOS Simulator | simctl: deep links, dark mode; taps with idb | UI tree with idb, text by OCR without | HTML mockups | full with idb, capture only without |
+| iPhone and iPad | devicectl, idevicescreenshot or pymobiledevice3 | text by OCR | HTML mockups | capture only |
+| Electron | Playwright | all web checks | | full |
+| macOS apps | window screenshot, accessibility tree | UI tree | | capture only |
+| Windows apps | PowerShell and UI Automation: taps, typing | UI tree | | full on Windows, via import elsewhere |
+| React Native, Flutter, iOS WKWebView, Maestro, Appium, XCUITest | their own runner | UI tree from a dump, or text | | via import |
+
+```bash
+npx kaloko devices                                         # the presets
+npx kaloko browser install --browsers webkit,firefox
+npx kaloko start --scenario qa/flows/checkout.yml --env staging \
+  --browsers chromium,webkit --color-schemes light,dark --viewports iphone-se,pixel-8,desktop-hd
+```
+
+The canvas switches between browsers and schemes next to the locale, draws the device frame and shows the same
+step in another browser beside it. `npx kaloko doctor` says which engines and app tools are missing on this
+machine and how to install them. Details: `skills/kaloko/reference/devices.md` and `apps.md`.
+
 ## Pull request previews in CI
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.4.11",
+  "version": "0.5.1",
   "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

@@ -78,7 +78,12 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "concurrency": { "type": "integer", "minimum": 1, "maximum": 16, "description": "Locales walked at the same time, each in its own browser context (kaloko walk --concurrency). Default: by CPU in an own browser, one at a time on the shared browser." }
+        "concurrency": { "type": "integer", "minimum": 1, "maximum": 16, "description": "Locales walked at the same time, each in its own browser context (kaloko walk --concurrency). Default: by CPU in an own browser, one at a time on the shared browser." },
+        "browsers": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["chromium", "webkit", "firefox"] }, "description": "Default browser engines for web runs when the scenario and kaloko start --browsers say nothing." },
+        "color_schemes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["light", "dark"] }, "description": "Default colour schemes (prefers-color-scheme) for every run." },
+        "reduced_motion": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["no-preference", "reduce"] } },
+        "forced_colors": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["none", "active"] } },
+        "display_modes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["browser", "standalone"] } }
       }
     },
     "capture": {
@@ -120,6 +125,18 @@
         }
       ]
     },
+    "appDevices": {
+      "type": "object",
+      "description": "Devices a scenario's devices: list names, each an emulator, simulator or real device. Without an entry the name is matched against adb serials and AVDs (pixel-8-api-34 → Pixel_8_API_34) or simulators (iphone-15-ios-18 → iPhone 15 on iOS 18).",
+      "additionalProperties": {
+        "type": "object", "additionalProperties": false,
+        "properties": {
+          "serial": { "type": "string" }, "avd": { "type": "string" }, "connect": { "type": "string" },
+          "udid": { "type": "string" }, "device": { "type": "string", "description": "Simulator name (iOS) or the canvas label (Android)." }, "runtime": { "type": "string" },
+          "real": { "type": "boolean" }, "title": { "type": "string", "description": "Label on the canvas." }
+        }
+      }
+    },
     "environment": {
       "type": "object",
       "additionalProperties": false,
@@ -143,7 +160,7 @@
         "app": {
           "type": "object",
           "additionalProperties": false,
-          "description": "The app under test in this environment, per platform (scenario platform: android, ios, electron, desktop). Paths of app scenarios are deep links.",
+          "description": "The app under test in this environment, per platform (scenario platform: android, ios, electron, desktop, windows). Paths of app scenarios are deep links.",
           "properties": {
             "android": {
               "type": "object", "additionalProperties": false,
@@ -155,6 +172,12 @@
                 "serial": { "type": "string", "description": "adb device serial; default ANDROID_SERIAL or the only device." },
                 "device": { "type": "string", "description": "Label for the canvas; default the device model." },
                 "reset": { "type": "boolean", "description": "Clear app data at the start of every locale (a new user)." },
+                "connect": { "type": "string", "description": "A real device over Wi-Fi: host:port for adb connect before the walk (pair it once with adb pair)." },
+                "avd": { "type": "string", "description": "Emulator (Android Virtual Device) to start when it is not running, e.g. Pixel_8_API_34." },
+                "emulator": { "type": "string", "description": "Path to the emulator binary (default: emulator on PATH or in ANDROID_HOME)." },
+                "wake": { "type": "boolean", "description": "Wake and unlock the screen of a real device before the walk (no PIN; default true)." },
+                "webview": { "type": "boolean", "description": "When the screen is a WebView with debugging on, capture its page (DOM, web checks) too; default false." },
+                "devices": { "$ref": "#/$defs/appDevices" },
                 "adb": { "type": "string" }, "launch_wait": { "type": "integer" }, "settle": { "type": "integer" }
               }
             },
@@ -170,6 +193,9 @@
                 "idb": { "type": "boolean", "description": "Use idb for the UI tree and taps when installed (default true)." },
                 "ocr": { "type": "boolean", "description": "Without idb, read the screen text by OCR (macOS Vision; default true)." },
                 "status_bar": { "type": "boolean", "description": "Clean status bar (9:41, full battery) for captures; default true." },
+                "runtime": { "type": "string", "description": "Simulator runtime, e.g. iOS 18 (the newest matching one)." },
+                "real": { "type": "boolean", "description": "A real iPhone or iPad (udid): installs and launches with xcrun devicectl, screenshots with idevicescreenshot (libimobiledevice); no taps or UI tree, OCR on macOS." },
+                "devices": { "$ref": "#/$defs/appDevices" },
                 "scale": { "type": "integer" }, "launch_wait": { "type": "integer" }, "settle": { "type": "integer" }
               }
             },
@@ -192,6 +218,20 @@
                 "launch": { "type": "boolean", "description": "Open the app at the start (default true)." },
                 "reset": { "type": "boolean" }, "ocr": { "type": "boolean" }, "launch_wait": { "type": "integer" }, "settle": { "type": "integer" }
               }
+            },
+            "windows": {
+              "type": "object", "additionalProperties": false,
+              "description": "A Windows desktop app, driven through UI Automation with Windows PowerShell (no extra install).",
+              "properties": {
+                "name": { "type": "string", "description": "Process name or window title, e.g. notepad or Contoso Shop." },
+                "path": { "type": "string", "description": "Executable to start (relative to the repository or absolute)." },
+                "aumid": { "type": "string", "description": "AppUserModelID of a Store/MSIX app to start instead of path." },
+                "args": { "type": "array", "items": { "type": "string" } },
+                "launch": { "type": "boolean", "description": "Start the app at the start (default true)." },
+                "reset": { "type": "boolean", "description": "Close a running instance first." },
+                "powershell": { "type": "string", "description": "PowerShell binary (default powershell.exe; pwsh works on Windows too)." },
+                "launch_wait": { "type": "integer" }, "settle": { "type": "integer" }
+              }
             }
           }
         },

package/schemas/run.v1.json

@@ -147,7 +147,32 @@
           }
         },
         "viewports": {
-          "type": "object"
+          "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)."
+        },
+        "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.",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "viewport": { "type": "string" },
+              "browser": { "enum": ["chromium", "webkit", "firefox"] },
+              "color_scheme": { "enum": ["light", "dark"] },
+              "reduced_motion": { "enum": ["no-preference", "reduce"] },
+              "forced_colors": { "enum": ["none", "active"] },
+              "display_mode": { "enum": ["browser", "standalone"] },
+              "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."
+        },
+        "devices": {
+          "type": "object",
+          "description": "Viewport name -> device preset (title, kind, screen, size, dpr, safe areas, frame) for device frames on the canvas."
         },
         "note": {
           "type": "string"
@@ -405,7 +430,13 @@
                 "url": {
                   "type": ["string", "null"]
                 },
-                "platform": { "type": "string", "description": "App captures: android, ios, electron or desktop." },
+                "platform": { "type": "string", "description": "App captures: android, ios, electron, desktop or windows." },
+                "browser": { "type": "string", "description": "Engine of a web capture when the run has dimensions; absent = chromium." },
+                "color_scheme": { "type": "string" },
+                "reduced_motion": { "type": "string" },
+                "forced_colors": { "type": "string" },
+                "display_mode": { "type": "string" },
+                "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)." },
                 "http_status": {

package/schemas/scenario.v1.json

@@ -50,17 +50,25 @@
       "minItems": 1
     },
     "viewports": {
-      "type": "object",
-      "additionalProperties": {
-        "type": "array",
-        "items": {
-          "type": "integer",
-          "minimum": 200
+      "description": "Viewports by name: a size [width, height], a device preset (iphone-15, ipad-landscape, fold-open, laptop, tv-1080p, <preset>-landscape …) or { device, width?, height?, full_screen? }. A list of preset names works too: [iphone-se, pixel-8, desktop-hd].",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/viewport" }
         },
-        "minItems": 2,
-        "maxItems": 2
-      }
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": { "oneOf": [{ "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": { "$ref": "#/$defs/viewport" } }] }
+        }
+      ]
     },
+    "browsers": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["chromium", "webkit", "firefox"] }, "description": "Browser engines to walk the web flow in (Playwright). Default: chromium. Captures of other engines are keyed <viewport>.<engine>." },
+    "color_schemes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["light", "dark"] }, "description": "prefers-color-scheme values to capture every step in (keys <viewport>.dark). Not set: the browser default, nothing emulated." },
+    "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)." },
+    "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",
       "items": {
@@ -72,9 +80,9 @@
       "default": false
     },
     "platform": {
-      "enum": ["web", "android", "ios", "electron", "desktop"],
+      "enum": ["web", "android", "ios", "electron", "desktop", "windows"],
       "default": "web",
-      "description": "What the flow runs on. web: pages in Chrome. android/ios/electron/desktop: an app, driven by the environment's app block (adb, iOS Simulator, Playwright Electron, macOS window) or captured with kaloko capture --image. Node paths are deep links for apps."
+      "description": "What the flow runs on. web: pages in a browser (an installed PWA too: display_modes). android/ios/electron/desktop/windows: an app, driven by the environment's app block (adb, iOS Simulator or device, Playwright Electron, macOS window, Windows UI Automation) or captured with kaloko capture --image. Node paths are deep links for apps."
     },
     "tags": {
       "type": "array",
@@ -182,6 +190,23 @@
         }
       ]
     },
+    "viewport": {
+      "oneOf": [
+        { "type": "array", "items": { "type": "integer", "minimum": 200 }, "minItems": 2, "maxItems": 2 },
+        { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "A device preset name." },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["device"],
+          "properties": {
+            "device": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+            "width": { "type": "integer", "minimum": 200 },
+            "height": { "type": "integer", "minimum": 200 },
+            "full_screen": { "type": "boolean", "description": "The whole screen without browser bars (app mockups, kiosk). Design environments use it by default." }
+          }
+        }
+      ]
+    },
     "slug": {
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
@@ -511,12 +536,19 @@
             "count",
             "text_matches",
             "text_absent",
+            "text_equals",
             "attr_equals",
+            "attr_matches",
             "no_overflow",
             "no_console_errors",
             "title_matches",
             "meta_matches",
             "link_matches",
+            "url_matches",
+            "url_equals",
+            "style_equals",
+            "style_matches",
+            "js_equals",
             "http_status",
             "link_home",
             "links_ok",
@@ -550,22 +582,73 @@
         },
         "selector": {
           "type": "string",
-          "description": "CSS selector; links_ok: the links to check (default a[href])."
+          "description": "CSS selector; links_ok: the links to check (default a[href]); style_*: the elements whose computed style is read."
         },
         "pattern": {
           "type": "string",
-          "description": "Regex; links_ok: link paths to skip."
+          "description": "Regex; links_ok: link paths to skip; url_matches: tested on the URL part; style_matches: on the computed value; attr_matches: on the attribute; js_equals: on the result."
         },
         "attr": {
           "type": "string"
         },
+        "property": {
+          "type": "string",
+          "minLength": 1,
+          "description": "style_equals, style_matches: the CSS property read with getComputedStyle (color, background-color, display, font-size, …). Use longhands, not shorthands like background."
+        },
+        "token": {
+          "type": "string",
+          "pattern": "^[^{}]+$",
+          "description": "style_equals: a DTCG token name (color.brand.primary) instead of value; resolved from the project's token set, or from the page's --color-brand-primary custom property."
+        },
+        "tolerance": {
+          "type": "number",
+          "minimum": 0,
+          "description": "style_equals: allowed difference for lengths, in px."
+        },
+        "op": {
+          "enum": [
+            "<",
+            "<=",
+            ">",
+            ">=",
+            "=="
+          ],
+          "description": "style_equals, js_equals: compare numerically with value instead of equality (font-size >= 16px)."
+        },
+        "all": {
+          "type": "boolean",
+          "description": "style_*, text_equals, attr_matches: every match must pass (default: at least one)."
+        },
+        "part": {
+          "enum": [
+            "href",
+            "path",
+            "query",
+            "hash",
+            "host",
+            "origin"
+          ],
+          "description": "url_matches: which part of the URL the pattern tests (default href, the whole URL)."
+        },
+        "ignore_query": {
+          "type": "boolean",
+          "description": "url_equals: compare without the query string and hash."
+        },
+        "expression": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "description": "js_equals: one read-only JavaScript expression evaluated in the page (document.querySelectorAll('.item').length, localStorage.getItem('cart'), window.dataLayer?.length). No assignments, no ++/--, only reading calls; 2 s timeout."
+        },
         "value": {
           "type": [
             "string",
             "number",
-            "boolean"
+            "boolean",
+            "null"
           ],
-          "description": "attr_equals: the attribute value; http_status: the exact status (e.g. 404). Without value, http_status accepts min..max (default 200..299)."
+          "description": "attr_equals: the attribute value; text_equals: the whole text (whitespace collapsed); url_equals: a path (/thanks, query included unless ignore_query) or a whole URL; style_equals: the expected CSS value (colours in any CSS form, lengths in px or rem); js_equals: the expected result, or the number to compare with op; http_status: the exact status (e.g. 404). Without value, http_status accepts min..max (default 200..299)."
         },
         "min": {
           "type": "integer",
@@ -591,7 +674,15 @@
           "pattern": "^[imsu]{0,4}$",
           "description": "Regex flags for pattern: i (ignore case), m, s. Page text is innerText, so CSS text-transform (uppercase buttons) applies."
         }
-      }
+      },
+      "allOf": [
+        {"if": {"properties": {"assert": {"enum": ["style_equals", "style_matches"]}}, "required": ["assert"]}, "then": {"required": ["selector", "property"]}},
+        {"if": {"properties": {"assert": {"const": "style_equals"}}, "required": ["assert"]}, "then": {"anyOf": [{"required": ["value"]}, {"required": ["token"]}]}},
+        {"if": {"properties": {"assert": {"enum": ["style_matches", "url_matches", "attr_matches"]}}, "required": ["assert"]}, "then": {"required": ["pattern"]}},
+        {"if": {"properties": {"assert": {"const": "attr_matches"}}, "required": ["assert"]}, "then": {"required": ["selector", "attr"]}},
+        {"if": {"properties": {"assert": {"enum": ["url_equals", "text_equals"]}}, "required": ["assert"]}, "then": {"required": ["value"]}},
+        {"if": {"properties": {"assert": {"const": "js_equals"}}, "required": ["assert"]}, "then": {"required": ["expression"]}}
+      ]
     },
     "semantic": {
       "type": "object",

package/skills/kaloko/SKILL.md

@@ -5,7 +5,9 @@ description: >
   evidence: writing or updating ACCEPTANCE.md or qa/scenario.yml, running a
   scenario on local, review, staging or production (readonly), capturing
   screens and e-mails, evaluating criteria, or building and sharing the
-  Kaloko canvas, for web pages as well as Android, iOS and desktop apps,
+  Kaloko canvas, for web pages in Chromium, WebKit and Firefox, on phone,
+  tablet and desktop presets, in light and dark mode, as well as Android, iOS,
+  macOS and Windows apps,
   including checking many pages of one template at once (magazine articles,
   product pages, an SEO page catalogue). Also when someone asks what a
   reviewer rejected on a canvas, what is waiting in the Kaloko inbox, or how
@@ -50,7 +52,8 @@ Start the shared browser, walk a scenario on a non-production environment,
 create test data there (users, roles, carts), capture screens and e-mails,
 evaluate, build the preview, and fix scenario mechanics (selectors, scripts)
 that do not change what is being accepted, including applying a selector
-proposal with `kaloko walk --heal` when it names the same element. Walk only
+proposal with `kaloko walk --heal` when it names the same element, and pulling
+the regions people drew to ignore into the scenario (`kaloko stability --pull`). Walk only
 the steps a change reaches (`--affected`) and import screenshots into a run. Record steps locally
 (`walk --record`) when a screenshot cannot show what a person has to judge, read traces, and
 export a walkthrough video into the run folder. On a design environment: change
@@ -71,7 +74,8 @@ a whole project (`capture.record` in the config: storage), a real clean-up
 anything the environment profile blocks. Never trash an accepted run, a
 baseline, a run with review comments, or a run linked from an open PR or issue
 comment. Never approve a
-step or accept a run on a person's behalf; report what waits for them
+step or accept a run on a person's behalf, and never hand out a signed
+acceptance record (`kaloko signoff`) for a run a person has not accepted; report what waits for them
 (`kaloko review`, MCP `get_review_queue`) instead. Ask the person
 for secret values (passwords, tokens, gate credentials) and for sign-ins only
 they can do; never write secrets into the config, a scenario or a script.
@@ -82,9 +86,13 @@ they can do; never write secrets into the config, a scenario or a script.
   the sample run, the first flow from a URL or a task, share, point the person
   to the canvas): [reference/first-run.md](reference/first-run.md)
 - Writing or updating the plan and scenario: [reference/acceptance.md](reference/acceptance.md)
-- Android, iOS (Simulator), Electron and macOS apps, or screens captured by
+- Android, iOS (Simulator or a real iPhone), Electron, macOS and Windows apps,
+  several devices of one app, WebViews inside apps, or screens captured by
   another tool (Maestro, Appium, XCUITest) with their UI tree:
   [reference/apps.md](reference/apps.md)
+- Walking in WebKit and Firefox, on device presets (phones, foldables,
+  tablets, TV), in dark mode, with reduced motion or as an installed PWA:
+  [reference/devices.md](reference/devices.md)
 - Many pages of one template in one step (articles, products, an SEO
   catalogue from a sitemap or a listing), with an index on the canvas:
   [reference/stacks.md](reference/stacks.md)

package/skills/kaloko/reference/acceptance.md

@@ -182,7 +182,8 @@ returning visitor). The plan is the source of truth; this is only the default.
 Each criterion gets exactly one check:
 
 - `deterministic` for anything countable or exact: presence, counts, text,
-  prices, attributes, overflow, console errors, title/meta/canonical.
+  prices, attributes, the URL, computed styles, values in the page,
+  overflow, console errors, title/meta/canonical.
 - `semantic` for judgement: clarity, separation of consents, whether copy
   fits the purpose. Write the question in English, yes = met, one condition
   per question. Add `true`/`false` for edge cases and `scope` (CSS selector)
@@ -216,6 +217,74 @@ button styled uppercase reads `VYTVOŘIT`. Add `flags: i` to ignore case
 white-label check for `vyvolej` also matches the Czech verb "Vyvolej si";
 anchor it (`vyvolej\.to`).
 
+`text_equals` compares the whole text of an element (whitespace collapsed,
+`flags: i` ignores case) with `value`: a total, a status, a label.
+`attr_matches` runs `pattern` on an attribute (`selector`, `attr`). Both pass
+when one match passes; `all: true` asks every match.
+
+### URL, computed styles and values in the page
+
+Never make a step script compute a check and leave a `data-qa-*` marker for
+a criterion to find. The marker proves only that the script ran. Check the
+URL, the style or the value directly:
+
+```yaml
+# the URL after the step (part: href (default), path, query, hash, host, origin)
+- { id: AC1, text: Lands on the thank-you page, check: { type: deterministic, assert: url_matches, part: path, pattern: '^/(cs|en)/thanks$' } }
+# exact path; ignore_query drops ?… and #…; a value with https:// compares the whole URL
+- { id: AC2, text: Stays on the cart, check: { type: deterministic, assert: url_equals, value: /cart, ignore_query: true } }
+# computed CSS (getComputedStyle) of the matched elements
+- { id: AC3, text: Primary button in brand colour, check: { type: deterministic, assert: style_equals, selector: button.primary, property: background-color, token: color.brand.primary, all: true } }
+- { id: AC4, text: Body text at least 16 px, check: { type: deterministic, assert: style_equals, selector: main p, property: font-size, op: '>=', value: 16px, all: true } }
+- { id: AC5, text: Error text red, check: { type: deterministic, assert: style_equals, selector: .field-error, property: color, value: '#d92d20' } }
+- { id: AC6, text: Promo banner hidden, check: { type: deterministic, assert: style_matches, selector: .promo, property: display, pattern: '^none$' } }
+# a read-only expression in the page
+- { id: AC7, text: Three items in the cart, check: { type: deterministic, assert: js_equals, expression: "document.querySelectorAll('.cart-item').length", value: 3 } }
+- { id: AC8, text: Cart kept for the next visit, check: { type: deterministic, assert: js_equals, expression: "JSON.parse(localStorage.getItem('cart') || '[]').length", op: '>=', value: 1 } }
+- { id: AC9, text: Purchase sent to analytics, check: { type: deterministic, assert: js_equals, expression: "window.dataLayer?.some((e) => e.event === 'purchase')", value: true } }
+```
+
+- `url_matches` and `url_equals` read the URL the browser shows after the
+  step, redirects included. The evidence names the URL.
+- `style_equals` compares `property` (a longhand: `background-color`, not
+  `background`) with `value` or `token`. Colours compare in one form, so
+  `red`, `#ff0000` and `rgb(255, 0, 0)` are equal; transparency counts.
+  Lengths compare in px (`rem` uses the page's root size), with
+  `tolerance: 1` for rounding; `op: '<' | '<=' | '>' | '>=' | '=='` compares
+  numbers. Other values (`display`, `font-weight`, `font-family`) compare as
+  text without quotes or case. Visible matches count; when none is visible
+  (a check for `display: none`), every match does. `style_matches` runs
+  `pattern` on the computed value.
+- `token: color.brand.primary` takes the expected value from the project's
+  DTCG token set (`kaloko tokens push`, or `tokens.json` of the design
+  folder) when `kaloko evaluate` runs, or from the page's
+  `--color-brand-primary` custom property during the walk. The evidence
+  reads `color is rgb(46, 107, 255) = color.brand.primary (#2e6bff)`.
+- `:hover` and `:focus` states are not supported: the check reads the page
+  as the step left it. Hover or focus the element in the step script when
+  that state is what you accept, and say so in the criterion text.
+- `js_equals` evaluates one `expression` in the page (2 s limit; promises are
+  awaited) and compares the result with `value` (a number value accepts
+  `"3"`; `null` matches a missing `localStorage` key), with `op` and a
+  number, or with `pattern` (objects as JSON). Without `value` and
+  `pattern` the result must be truthy. Only reading is allowed: no
+  assignment, no `++`/`--`, no `new` except `new URL(…)`, and calls only
+  from a list of reading methods (`querySelector(All)`, `getAttribute`,
+  `getItem`, `getComputedStyle`, `filter`, `some`, `JSON.parse`, …).
+  `kaloko validate` refuses anything else (`setItem`, `click`, `fetch`).
+  The guard is a convention, not a sandbox: a getter in the page can still
+  run code, so read data the page exposes (storage, `dataLayer`, the DOM)
+  and nothing that acts. Prefer `style_*`, `text_*` and `count` when they
+  can say the same.
+
+On `kaloko evaluate --recheck` the URL checks run again from the stored URL.
+The computed styles and expression results are stored with the capture, so a
+recheck decides again from them when the criterion still reads the same
+selector and property (or the same expression), for example after you fix
+the expected value. A new selector, property or expression needs the live
+page: the criterion is "not evaluated" with that reason until the step is
+captured again.
+
 Two checks need the network and run next to the capture, once per page:
 
 - `links_ok`: every same-origin link (`selector`, default `a[href]`) answers
@@ -273,5 +342,7 @@ design pixel check (`AC801`) leave them out:
 
 Do not guess them: `kaloko walk --stability 3` notes what moves while the
 page sits still, and `kaloko stability` compares the step with earlier runs
-and writes suggestions (see [execution.md](execution.md)). Ignore only noise;
-a region that matters to a criterion stays in.
+and writes suggestions (see [execution.md](execution.md)). Reviewers can also
+draw a region on a screenshot on kaloko.app; `kaloko stability --pull` writes
+those into `ignore:`. Ignore only noise; a region that matters to a criterion
+stays in.