kaloko 0.4.10 → 0.4.11

package/README.md

@@ -113,6 +113,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 +211,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.4.11",
   "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

@@ -81,6 +81,15 @@
         "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." }
       }
     },
+    "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": {
       "type": "object",
       "additionalProperties": false,
@@ -92,6 +101,25 @@
     }
   },
   "$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" }
+          }
+        }
+      ]
+    },
     "environment": {
       "type": "object",
       "additionalProperties": false,

package/schemas/scenario.v1.json

@@ -163,6 +163,25 @@
     }
   },
   "$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" }
+          }
+        }
+      ]
+    },
     "slug": {
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
@@ -269,6 +288,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.",
@@ -710,7 +730,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

@@ -13,7 +13,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 +51,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 +65,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
@@ -93,6 +97,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)

package/skills/kaloko/reference/mcp.md

@@ -28,6 +28,7 @@ file.
 | `list_notifications` | the token owner's inbox (`unread_only`, `limit`) |
 | `list_projects` | projects of the organization with counts; the slug is the `project` filter of `list_runs` and the value for `project:` in a scenario |
 | `get_criteria_verdicts` | reviewer verdicts on manual or overridden criteria of a run |
+| `get_step_recording` | a step's recording and trace (`run_id`, `step`, `locale`, `viewport`, `trace: true` for the full trace): video URLs, duration, its chapter of a flow recording, failed attempts, the trace summary (failed requests, console errors, slowest request); see [recording.md](recording.md). `get_run_summary` lists trace summaries per step too |
 | `get_review_queue` | what a person still has to decide in a run (`run_id`, or `scenario` / nothing for the newest run): steps in review order with reasons, decisions, approvals carried over unchanged steps with their origin, counts and `review_url` to give the person |
 | `decide_step` | records your (the agent's) decision on a step: `approve`, or `return` with a `note`; marked as an agent's and not counted as a person's. Never use it to approve for a person |
 | `revoke_carried_approval` | revokes an approval carried over to a step that looks unchanged but should be looked at again (`run_id`, `step`) |

package/skills/kaloko/reference/recording.md

@@ -0,0 +1,95 @@
+# Recordings, traces and the walkthrough video
+
+A screenshot shows where a step ended. A recording shows how it got there:
+the clicks, the spinner that never stopped, the menu that opened twice. A trace
+lists what happened meanwhile: actions, network requests with status, size and
+timing, and console messages.
+
+## When to record
+
+Record when a screenshot cannot show the problem or the behaviour a reviewer
+has to judge:
+
+- a flaky step (passes, then fails on the same commit): `--record failed` keeps
+  only the attempts that fail;
+- animations, transitions, loading states, drag and drop, menus and dialogs
+  that open and close;
+- a bug report or a PR where the person needs to see the interaction once;
+- a demo for a client or a release note (`kaloko video export`).
+
+Do not record every walk by default. Recordings are much larger than
+screenshots, count in the organization's storage and expire after 30 days on
+Business. Traces are small and are kept for every walked web step anyway.
+
+## Commands
+
+```bash
+kaloko walk --record                     # each step: from the previous screen to its capture
+kaloko walk --record flow                # the whole walk per locale, a chapter per step
+kaloko walk --record failed              # only steps whose script fails or whose checks fail
+kaloko walk --record --record-quality low --steps checkout
+kaloko walk --no-trace                   # no trace either
+kaloko video list                        # what was recorded and traced, with sizes
+kaloko video trace --step checkout       # the step's trace as a timeline in the terminal
+kaloko video export --format mp4         # the run's recordings with a title card per step
+kaloko video tools                       # ffmpeg, adb, simctl on this machine
+```
+
+In a scenario, or in `kaloko.config.yml` for the whole project:
+
+```yaml
+capture:
+  record: { mode: failed, quality: low, max_seconds: 45 }   # or true, step, flow, failed, false
+  trace: true
+nodes:
+  - id: checkout
+    record: true          # this step always; record: false never
+```
+
+Quality presets: `low` 8 fps up to 960 px, `medium` (default) 12 fps up to
+1280 px, `high` 24 fps up to 1920 px. A step keeps its last 60 seconds and a
+flow its last 15 minutes unless `max_seconds` says otherwise.
+
+## What you get
+
+Per recorded step under `steps/<step>/<locale>/<viewport>.`: `rec.webm` (VP9
+from Chrome, no extra tools), `rec.mp4` (H.264, when ffmpeg is installed; Safari
+before iOS 17.4 needs it), `rec.poster.webp`, `rec.webp` (a few-second animated
+preview; `rec.gif` where the browser cannot encode WebP) and `trace.json`. The
+pointer and clicks are drawn into web recordings. A flow recording is
+`attachments/flow/<locale>.rec.*`; the walkthrough is
+`attachments/walkthrough.rec.<format>`.
+
+Web and Electron record through Chrome's screencast; walks in Firefox or WebKit
+are neither recorded nor traced. Apps: Android with `adb shell screenrecord`
+(segments, touches shown), the iOS Simulator with `simctl io recordVideo`,
+macOS desktop apps with `screencapture` (Screen Recording permission). App
+recordings need ffmpeg for the poster and preview; `kaloko doctor` lists what is
+missing with the install command for the OS.
+
+## On the canvas
+
+The step detail gets Video next to Screenshot: the poster first, nothing loads
+until played, markers for the start, the capture, actions and failed requests.
+Technical shows the trace; a click on a row moves the video there. Cards play
+the preview on hover. Replay plays the flow recording with its chapters. The
+walkthrough video is in the top bar.
+
+## Plans and sharing
+
+Recording is local and works on every plan. `kaloko share` uploads recordings
+on Business and Enterprise; on Free and Team it says they stay in the local
+preview and shares screenshots and traces. A recording over the service's file
+limit (25 MB) stays local too: lower the quality or `max_seconds`. Recordings
+expire 30 days after the run is shared (Enterprise chooses in Settings →
+Storage); the screenshots stay as long as the run. Uploading is still "ask
+first", and so is turning recordings on for a whole project.
+
+## Reading them as an agent
+
+`kaloko video trace --step <id>` locally, or MCP `get_step_recording`
+(`run_id`, `step`; `trace: true` adds the full trace) on a shared run. It
+answers the video URLs, duration, the step's chapter of a flow recording,
+failed attempts and the trace summary: failed requests with status, console
+errors, the slowest request. Fetch the URLs with the same token. Start there
+when a step failed and the evidence in the criteria is not enough.

package/src/cli.mjs

@@ -51,6 +51,9 @@ import { exportDesign } from './lib/design-export.mjs'
 import { driverFor, isApp, pngSize, ocr as ocrImage } from './lib/apps/drivers.mjs'
 import { captureApp } from './lib/apps/capture.mjs'
 import { readTree, flatten } from './lib/apps/tree.mjs'
+import { recordSettings, recordingSession, recordingFiles, traceFiles, stripRecordings, withoutRecordings } from './lib/recording.mjs'
+import { nativeSession } from './lib/apps/recording-native.mjs'
+import { videoCmd } from './lib/video-cli.mjs'
 
 
 const HELP = `kaloko — walk, assess and approve what your agents built, on one flow canvas
@@ -130,6 +133,11 @@ Run
                                     steps' captures from the previous local run
        [--heal | --no-heal]         A selector the page lost gets a proposal from the page (test id, role and name,
                                     text) with a patch; --heal applies it to the step script once the step passes
+       [--record [step|flow|failed]] [--record-quality low|medium|high] [--no-trace]
+                                    Record each step from the previous screen to its capture (step), the whole walk
+                                    per locale with a chapter per step (flow), or only steps that fail (failed);
+                                    also capture.record in the config or scenario, record: true on a step.
+                                    A trace (actions, requests, console) is kept per step unless --no-trace
   affected [--scenario file | --all] [--base ref] [--files a,b] [--json] [--check] [--offline]
                                     Which steps changed files reach, and why: framework route files against step paths
                                     and URLs captured earlier, imports, global files, i18n messages, step scripts and
@@ -147,6 +155,11 @@ Results
                                     the semantic questions again on the stored captures (no walk);
                                     console, overflow and performance keep their live result
   build                             Write run.json and the local preview (index.html)
+  video export [--format mp4|webm|gif] [--locale l] [--steps a,b] [--lang en|cs] [--out file]
+                                    The run's recordings in flow order with a title card per step (title, verdict);
+                                    shared with the run on Business and up
+  video list | trace --step <id> | tools
+                                    Recordings and traces of the run; a step's trace as a timeline; ffmpeg, adb, simctl
   preview                           Build and print the preview path
   share [--expires 30] [--pr]       Upload the run to kaloko.app (KALOKO_TOKEN, tester role); files travel by content
                                     hash, so unchanged captures are not sent again and a broken-off share resumes;
@@ -505,6 +518,14 @@ function linkFor (env, node, locale) {
   if (/^[a-z][a-z0-9+.-]*:/i.test(p)) return p
   return env.base_url ? urlFor(env, { path: p }, locale) : null
 }
+/** A headless Chrome of its own for encoding recordings, started on first use (one per walk). */
+function lazyEncoder (config) {
+  let started = null
+  return {
+    page: () => (started ||= launchEphemeral(config).then(async (b) => ({ b, p: await b.newPage() })).catch(() => ({ b: null, p: null }))).then((x) => x.p),
+    close: async () => { if (started) await (await started).b?.close().catch(() => {}) }
+  }
+}
 const appViewport = (run) => Object.keys(run.meta.scope.viewports || {})[0] || null
 
 /**
@@ -522,6 +543,8 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
   const encoder = enc ? await enc.newPage().catch(() => null) : null
   const streak = failureStreak(args['keep-going'] ? 0 : 3)
   const maxChars = config.evaluators?.jev?.max_state_chars
+  // recordings and traces (batch D): Electron windows use the screencast recorder, devices record themselves
+  const recSettings = recordSettings({ args, config, scenario })
   try {
     for (const locale of locales) {
       const driver = driverFor(platform, env, { root, scenarioDir, locale })
@@ -530,6 +553,9 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
         if (driver.web) observeConsole(driver.page)
         say(`${platform} ${locale}: ${driver.web ? 'Electron window' : 'app'} ready`)
       } catch (error) { failed.push(`${platform} (${locale}): ${error.message.split('\n')[0]}`); say(`✗ ${platform} ${locale}: ${error.message.split('\n')[0]}`); await driver.close().catch(() => {}); if (error instanceof UserError) break; continue }
+      const rec = driver.web
+        ? await recordingSession({ page: driver.page, run, scenario, locale, settings: recSettings, viewports: run.meta.scope.viewports, encoder: async () => encoder, say, label: `${platform} ${locale}` }).catch(() => null)
+        : await nativeSession({ platform, env, run, scenario, locale, settings: recSettings, driver, encoder: async () => encoder, say }).catch(() => null)
       try {
         for (const node of scenario.nodes) {
           if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
@@ -542,30 +568,42 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
           const link = linkFor(env, node, locale)
           if (!scripted && !(link && ['playwright', 'script'].includes(node.execution?.strategy))) { pending.push(`${node.id} (${locale}): ${node.execution?.strategy || 'agent'} — ${(node.execution?.instructions || '').split('\n')[0]}`); continue }
           if (streak.stopped(locale)) { skipped.push(`${node.id} (${locale})`); continue }
+          const records = []
           try {
             let captured = false
+            await rec?.beforeStep(node)
             const capture = async (o = {}) => {
               captured = true
+              await rec?.beforeCapture(node)
               if (driver.web) {
                 const [w, h] = await driver.page.evaluate(() => [innerWidth, innerHeight])
-                return captureStep({ page: driver.page, node, locale, options: captureOptions(scenario, node), viewports: { [o.viewport || appViewport(run) || 'window']: [w, h] }, run, consoleFile: null, maxChars, extra: { platform, device: 'Electron' } })
+                const r = await captureStep({ page: driver.page, node, locale, options: captureOptions(scenario, node), viewports: { [o.viewport || appViewport(run) || 'window']: [w, h] }, run, consoleFile: null, maxChars, extra: { platform, device: 'Electron' } })
+                records.push(...r)
+                return r
               }
-              return captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: o.viewport || appViewport(run), run, platform, encoder, maxChars, extra: { url: link } })
+              const r = await captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: o.viewport || appViewport(run), run, platform, encoder, maxChars, extra: { url: link } })
+              records.push(r)
+              return r
             }
             if (scripted) {
               const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
               await mod.default({ app: driver, page: driver.page || null, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
             } else await driver.link(link)
             if (!captured) await capture()
+            await rec?.afterStep(node, driver.web ? { records } : { record: records[0] })
             say(`✓ ${node.id} ${locale}`)
             streak.ok(locale)
           } catch (error) {
+            await rec?.afterStep(node, driver.web ? { error, records } : { error, record: records[0] }).catch(() => {})
             failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
             say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
             if (streak.record(locale, error.message)) say(`  stopping ${locale}: the last 3 steps failed with the same error`)
           }
         }
-      } finally { await driver.close().catch(() => {}) }
+      } finally {
+        for (const n of (await rec?.finish().catch((e) => [`recording: ${e.message}`])) || []) say(`  ${n}`)
+        await driver.close().catch(() => {})
+      }
     }
   } finally { await enc?.close().catch(() => {}) }
   if (pending.length) say(`\nSteps for an agent or a person (drive the app, then kaloko capture --step <id> --image shot.png [--tree dump.xml|json]):\n  - ${[...new Set(pending)].join('\n  - ')}`)
@@ -861,6 +899,11 @@ const commands = {
     say(`✓ ${node.id} ${locale}: "${results.subject}" → ${results.count} viewport(s)`)
   },
 
+  async video (args) {
+    const { config, root } = await context(args)
+    await videoCmd({ config, root, args, say })
+  },
+
   async walk (args) {
     const { config, root, run, scenario, env } = await runContext(args)
     if (args.affected) {
@@ -905,6 +948,9 @@ const commands = {
     // semantic questions of every new capture start right away; the walk ends with the verdicts (--no-evaluate: skip)
     const prefetch = args['no-evaluate'] ? null : semanticPrefetch({ scenario, config, root })
     const walked = await readCaptures(run.dir)
+    // recordings and traces (batch D, #12): opt-in recordings, traces unless turned off; encoded in an own headless Chrome
+    const recSettings = recordSettings({ args, config, scenario })
+    const encoder = lazyEncoder(config)
     const sessions = scenario.sessions || null
     // named sessions: one isolated browser context per person and locale (cookies, storage, sign-in), created lazily
     const sessionContexts = new Map()
@@ -939,6 +985,12 @@ const commands = {
       const page = await lctx.newPage()
       const shared = conn && !parallel // the shared browser's own context logs its console to a file
       if (!shared) observeConsole(page)
+      // one recorder per page (the walk's tab and each named session's), started on its first step
+      const recorders = new Map()
+      const recorderFor = async (p) => {
+        if (!recorders.has(p)) recorders.set(p, recordingSession({ page: p, run, scenario, locale, settings: recSettings, viewports: run.meta.scope.viewports, encoder: encoder.page, say, label: locale }).catch(() => null))
+        return recorders.get(p)
+      }
       try {
         // every locale starts as a new visitor on its first walk in the run (an own context is new already)
         if (shared && !walked.some((c) => c.locale === locale)) { await resetSession(lctx, page, baseUrl(env, locale)); say(`session reset (new visitor, ${locale})`) }
@@ -978,11 +1030,17 @@ const commands = {
           const scriptFile = resolve(scenarioDir, node.execution.script)
           // one invocation of the step script; the automatic capture runs unless the script captured the step itself:
           // a crop is an attachment (#49), and a capture from an earlier walk must not stand in for this one (#50)
+          const rec = await recorderFor(sPage)
           const runStep = async (mod) => {
             let captured = false
-            const capture = (opts = {}) => { captured = true; return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, opts.viewports), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); return r }) }
-            await mod.default({ page: sPage, context: sCtx, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
-            if (!captured) await capture()
+            rec?.beforeStep(node)
+            const records = []
+            const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, opts.viewports), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
+            try {
+              await mod.default({ page: sPage, context: sCtx, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
+              if (!captured) await capture()
+            } catch (error) { await rec?.afterStep(node, { error }); throw error }
+            await rec?.afterStep(node, { records })
           }
           try {
             await runStep(await import(pathToFileURL(scriptFile).href))
@@ -1002,7 +1060,10 @@ const commands = {
             if (streak.record(streakKey, error.message)) say(`  stopping ${node.session ? `session ${node.session}` : 'this walk'} (${locale}): the last 3 steps failed with the same error; fix the shared cause (sign-in, environment) and rerun, or pass --keep-going`)
           }
         }
-      } finally { await page.close().catch(() => {}) }
+      } finally {
+        for (const r of recorders.values()) { const notes = await (await r)?.finish().catch((e) => [`recording: ${e.message}`]); for (const n of notes || []) say(`  ${n}`) }
+        await page.close().catch(() => {})
+      }
       return { pending, failed, skipped }
     }
     let results
@@ -1014,6 +1075,7 @@ const commands = {
       for (const c of ownContexts) await c.close().catch(() => {})
       if (conn) await conn.browser.close() // over CDP this only disconnects; the shared browser keeps running
       if (ephemeral) await ephemeral.close()
+      await encoder.close()
       await releaseLock?.()
     }
     const pending = results.flatMap((r) => r.pending); const failed = results.flatMap((r) => r.failed); const skipped = results.flatMap((r) => r.skipped)
@@ -1107,7 +1169,7 @@ const commands = {
     const kept = await keepVideos(run, source.videos)
     say(`\nImported ${captured} screen(s)${attached ? `, ${attached} more as attachments` : ''} into ${run.meta.id}.${encoder ? '' : ' (No Chrome: images kept as they are, without thumbnails.)'}`)
     if (unmatched.length) say(`Not matched to a step (${unmatched.length}): name the step in steps.json ("step": "<id>"), or pass --map "${unmatched[0]}=<step id>". Steps: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}`)
-    if (kept.length) say(`Recordings kept in the run folder, not uploaded (the canvas does not play them yet): ${kept.join(', ')}`)
+    if (kept.length) say(`Recordings kept in the run folder, not attached to a step and not uploaded: ${kept.join(', ')}. kaloko walk --record records steps for the canvas.`)
     say('Next: kaloko evaluate, then kaloko preview (local canvas) or kaloko share. Imported screens have no page to check: their deterministic criteria wait for a walk, semantic ones for a person.')
   },
 
@@ -1311,9 +1373,16 @@ const commands = {
       await writeFile(join(run.dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n')
       return
     }
-    const manifest = await buildManifest({ run, scenario, config, root, catalog: [] })
+    let manifest = await buildManifest({ run, scenario, config, root, catalog: [] })
     await writePreview({ run, manifest })
-    const files = new Set()
+    // the plan and storage before anything is sent; recordings travel on plans with the recordings feature only
+    const u = await client.request('GET', `/orgs/${config.org}/usage`).catch(() => null)
+    const recs = recordingFiles(manifest)
+    if (recs.length && u?.limits?.features && !u.limits.features.recordings) {
+      manifest = stripRecordings(manifest)
+      say(`Recordings stay in the local preview (${recs.length} file(s)): sharing them is part of the Business plan and up, and this organization is on ${u.limits.plan_name}. Screenshots and traces are shared as usual.`)
+    }
+    const files = new Set([...traceFiles(manifest), ...recordingFiles(manifest)])
     for (const n of manifest.nodes) {
       for (const byVp of Object.values(n.captures || {})) for (const c of Object.values(byVp)) [c.image || c.png, c.thumb, c.html, c.eval, c.tree, c.spec].filter(Boolean).forEach((p) => files.add(p))
       for (const a of n.attachments || []) files.add(a.file)
@@ -1326,16 +1395,25 @@ const commands = {
     }
     const days = Number(args.expires) || config.share?.expires_days || 30
     // by content hash (#28): files the organization already stores (earlier runs, an interrupted share) are not sent
-    const entries = await hashFiles(run.dir, [...files])
+    let entries = await hashFiles(run.dir, [...files])
+    // a recording above the service's file limit stays local (with its poster and preview), the rest is shared
+    const tooBig = new Set(entries.filter((e) => /\.rec\./.test(e.path) && u?.limits?.max_file_bytes && e.bytes > u.limits.max_file_bytes).map((e) => e.path))
+    if (tooBig.size) {
+      manifest = withoutRecordings(manifest, tooBig)
+      const keep = new Set([...traceFiles(manifest), ...recordingFiles(manifest)])
+      entries = entries.filter((e) => !/\.rec\./.test(e.path) || keep.has(e.path))
+      say(`${tooBig.size} recording(s) larger than ${fmtBytes(u.limits.max_file_bytes)} stay in the local preview: ${[...tooBig].slice(0, 3).join(', ')}${tooBig.size > 3 ? ', …' : ''}. Record them with record.quality: low or a lower max_seconds to share them.`)
+    }
     const missing = await missingHashes(client, config.org, entries.map((e) => e.hash))
     const total = entries.reduce((n, e) => n + e.bytes, 0)
     const fresh = missing ? [...new Map(entries.filter((e) => missing.has(e.hash)).map((e) => [e.hash, e.bytes])).values()].reduce((n, b) => n + b, 0) : total
     const resumed = (await readJson(join(run.dir, PROGRESS_FILE), null).catch(() => null))?.run === manifest.id
     try {
-      const u = await client.request('GET', `/orgs/${config.org}/usage`)
+      if (!u) throw new Error('usage unavailable')
       if (total > u.limits.max_run_bytes) throw new UserError(`This run is ${fmtBytes(total)}; the limit per run is ${fmtBytes(u.limits.max_run_bytes)}. Capture fewer viewports or locales, or ask an admin for a higher limit.`)
       if (u.usage.bytes + fresh > u.limits.quota_bytes) throw new UserError(`Storage quota would be exceeded: ${fmtBytes(u.usage.bytes)} used + ${fmtBytes(fresh)} > ${fmtBytes(u.limits.quota_bytes)}. Delete old runs in Settings or ask for a higher quota.`)
-      say(`${resumed ? 'Resuming the interrupted share: ' : ''}${files.size} files, ${fmtBytes(total)}${missing ? `; ${fmtBytes(fresh)} new, the rest already stored` : ''} (organization uses ${fmtBytes(u.usage.bytes)} of ${fmtBytes(u.limits.quota_bytes)})`)
+      const recBytes = entries.filter((e) => /\.rec\./.test(e.path)).reduce((n, e) => n + e.bytes, 0)
+      say(`${resumed ? 'Resuming the interrupted share: ' : ''}${files.size} files, ${fmtBytes(total)}${recBytes ? ` (recordings ${fmtBytes(recBytes)})` : ''}${missing ? `; ${fmtBytes(fresh)} new, the rest already stored` : ''} (organization uses ${fmtBytes(u.usage.bytes)} of ${fmtBytes(u.limits.quota_bytes)})`)
     } catch (e) { if (e instanceof UserError && /limit|quota/.test(e.message)) throw e }
     const created = await client.request('POST', `/orgs/${config.org}/runs?expires_days=${days}`, manifest)
     await writeFile(join(run.dir, PROGRESS_FILE), JSON.stringify({ run: manifest.id, started_at: new Date().toISOString() }) + '\n').catch(() => {})