kaloko 0.4.10 → 0.5.0

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
@@ -113,6 +154,24 @@ jobs:
 Uploads go by content hash: captures that did not change since an earlier run
 are not sent again, and an interrupted `share` picks up where it stopped.
 
+## When a screenshot is not enough
+
+```bash
+npx kaloko walk --record                # each step on video, from the previous screen to its capture
+npx kaloko walk --record failed         # only the steps that fail (flaky ones, mostly)
+npx kaloko walk --record flow           # the whole walk per language, a chapter per step
+npx kaloko video export --format mp4    # the run as one video, a title card and verdict before each step
+```
+
+The canvas plays a step's video next to its screenshot, and the Technical tab
+shows its trace: clicks, typing, requests with status and timing, console
+messages. Click a row and the video jumps there. Web recordings need nothing
+but Chrome (WebM with VP9); with ffmpeg installed you also get MP4 for Safari,
+app recordings (Android `screenrecord`, iOS Simulator, macOS) and the
+walkthrough export. `npx kaloko video tools` says what this machine has.
+Recordings stay in the local preview on Free and Team; Business and Enterprise
+share them with the run.
+
 ## Screenshots you already have
 
 ```bash
@@ -193,6 +252,7 @@ Nothing in Kaloko is stored in a format only Kaloko can read. Every export opens
 | Live files (handoff) | `npx kaloko export --live [--version n] --out design/` | the design folder as written |
 | Shared run | `npx kaloko export --run <id>` | zip with `run.json` (`qawalk.run.v1`), screenshots and HTML snapshots, live HTML of design steps, comments and verdicts, and `index.html`: the canvas, offline |
 | Documentation captures | `npx kaloko export --scenario <id>` | newest image and HTML of every step, `index.json` |
+| Walkthrough video | `npx kaloko video export [--format mp4\|webm\|gif]` | one video of the run's recordings with title cards; step recordings are WebM (VP9) and MP4 (H.264), traces JSON (`qawalk.trace.v1`) |
 
 The schemas of these formats ship with the package (`schemas/`).
 

package/package.json

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

@@ -78,7 +78,21 @@
       "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": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Defaults for every scenario of the project; a scenario's capture block wins.",
+      "properties": {
+        "record": { "$ref": "#/$defs/record" },
+        "trace": { "type": "boolean", "default": true, "description": "Keep a trace per walked step (actions, network requests, console) shown under Technical; false or walk --no-trace turns it off." }
       }
     },
     "share": {
@@ -92,6 +106,37 @@
     }
   },
   "$defs": {
+    "record": {
+      "description": "Recordings of walked steps (opt-in): true or step records each step from the previous screen to its capture; flow records the whole walk per locale with a chapter per step; failed keeps only steps that fail; false or off turns it off. Uploaded on Business and Enterprise.",
+      "oneOf": [
+        { "type": "boolean" },
+        { "enum": ["step", "flow", "failed", "off"] },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "enum": ["step", "flow", "failed", "off"], "default": "step" },
+            "quality": { "enum": ["low", "medium", "high"], "default": "medium", "description": "low 8 fps up to 960 px, medium 12 fps up to 1280 px, high 24 fps up to 1920 px" },
+            "max_seconds": { "type": "integer", "minimum": 1, "maximum": 3600, "description": "Longest kept recording; a longer one keeps its end (default 60 for a step, 900 for a flow)" },
+            "codec": { "enum": ["auto", "vp9", "av1", "h264"], "default": "auto", "description": "auto: WebM VP9 (VP8 fallback) from the browser, plus MP4 H.264 when ffmpeg is installed; av1 needs ffmpeg" },
+            "mp4": { "oneOf": [{ "type": "boolean" }, { "const": "auto" }], "default": "auto", "description": "MP4 H.264 next to the WebM (Safari before iOS 17.4); needs ffmpeg" },
+            "cursor": { "type": "boolean", "default": true, "description": "Draw the pointer and clicks into web recordings" }
+          }
+        }
+      ]
+    },
+    "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,
@@ -115,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,
@@ -127,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" }
               }
             },
@@ -142,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" }
               }
             },
@@ -164,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",
@@ -163,6 +171,42 @@
     }
   },
   "$defs": {
+    "record": {
+      "description": "Recordings of walked steps (opt-in): true or step records each step from the previous screen to its capture; flow records the whole walk per locale with a chapter per step; failed keeps only steps that fail; false or off turns it off. Uploaded on Business and Enterprise.",
+      "oneOf": [
+        { "type": "boolean" },
+        { "enum": ["step", "flow", "failed", "off"] },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "enum": ["step", "flow", "failed", "off"], "default": "step" },
+            "quality": { "enum": ["low", "medium", "high"], "default": "medium", "description": "low 8 fps up to 960 px, medium 12 fps up to 1280 px, high 24 fps up to 1920 px" },
+            "max_seconds": { "type": "integer", "minimum": 1, "maximum": 3600, "description": "Longest kept recording; a longer one keeps its end (default 60 for a step, 900 for a flow)" },
+            "codec": { "enum": ["auto", "vp9", "av1", "h264"], "default": "auto", "description": "auto: WebM VP9 (VP8 fallback) from the browser, plus MP4 H.264 when ffmpeg is installed; av1 needs ffmpeg" },
+            "mp4": { "oneOf": [{ "type": "boolean" }, { "const": "auto" }], "default": "auto", "description": "MP4 H.264 next to the WebM (Safari before iOS 17.4); needs ffmpeg" },
+            "cursor": { "type": "boolean", "default": true, "description": "Draw the pointer and clicks into web recordings" }
+          }
+        }
+      ]
+    },
+    "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._-]*$"
@@ -269,6 +313,7 @@
         "capture": {
           "$ref": "#/$defs/capture"
         },
+        "record": { "$ref": "#/$defs/record", "description": "Record this step even when the walk does not (true), or never (false)." },
         "ignore": {
           "type": "array",
           "description": "Regions left out of pixel comparisons (clocks, ads, carousels): a selector, or a rectangle in page pixels of one viewport. kaloko stability suggests them.",
@@ -491,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",
@@ -530,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",
@@ -571,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",
@@ -710,7 +821,9 @@
         "full_page": {
           "type": "boolean",
           "description": "Screenshot of the whole page (default true; false for stack pages: the first screen only)"
-        }
+        },
+        "record": { "$ref": "#/$defs/record" },
+        "trace": { "type": "boolean", "default": true, "description": "Keep a trace per walked step (actions, network requests, console) shown under Technical; false or walk --no-trace turns it off." }
       }
     }
   }

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
@@ -13,7 +15,8 @@ description: >
   design environment (live HTML steps, drafts, versions, the design
   reference, checking implementation against it), and when implementing a
   screen that has an approved design (read the step spec, build with its
-  tokens, check drift).
+  tokens, check drift), and when a step should be recorded on video or its
+  trace read (actions, requests, console).
 ---
 
 # Kaloko
@@ -50,7 +53,9 @@ 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
-the steps a change reaches (`--affected`) and import screenshots into a run. On a design environment: change
+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
 the design folder, walk, and sync the draft (including taking others' steps
 with `--theirs`). Move to the trash runs you uploaded in this session that
 were superseded before anyone looked at them (debug rounds: no comments, no
@@ -62,7 +67,8 @@ Changing acceptance criteria or scope, any production run, writing or
 replacing a CI workflow (`kaloko ci github|gitlab`), uploading with
 `kaloko share` (on a design environment: publishing a version), setting a
 design reference or baseline, merging a design branch, keeping your version of
-a step in a sync conflict (`--mine`), turning on `html_view`, a real clean-up
+a step in a sync conflict (`--mine`), turning on `html_view`, turning on recordings for
+a whole project (`capture.record` in the config: storage), a real clean-up
 (`kaloko prune --yes`), trashing someone else's run, archiving a scenario, and
 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
@@ -78,9 +84,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)
@@ -93,6 +103,9 @@ they can do; never write secrets into the config, a scenario or a script.
   (`--heal`): [reference/execution.md](reference/execution.md)
 - Screenshots, walkthroughs, Playwright reports and traces that an agent or a
   tool already produced, laid out as a run: [reference/import.md](reference/import.md)
+- Video of a step or a whole flow, traces (actions, requests, console) and the
+  walkthrough video; when recording is worth its storage:
+  [reference/recording.md](reference/recording.md)
 - CI: a workflow that walks each pull request's preview deployment and
   comments on it (`kaloko ci github|gitlab`): [reference/ci.md](reference/ci.md)
 - Evaluation, JEV thresholds and reading results: [reference/evaluation.md](reference/evaluation.md)