kwikqa 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,122 @@
+KwikQA End User License Agreement
+
+Effective 23 October 2026
+Copyright (c) 2026 KwikQA. All rights reserved.
+
+KwikQA is proprietary software. It is not open source, and this agreement does not grant any
+open-source license to it.
+
+This agreement is between you and KwikQA ("we"). It governs the KwikQA command-line software,
+including the reporter and failure-capture files it installs into your test projects (together,
+the "Software"), and your use of the KwikQA hosted service the Software connects to (the
+"Service"). The Terms of Service at https://kwikqa.com/terms/ also apply to the Service, and the
+Privacy Policy at https://kwikqa.com/privacy/ explains how personal data is handled. If this
+agreement and the Terms of Service conflict about the Software, this agreement governs.
+
+By installing, copying, or using the Software you accept this agreement. If you use it for an
+organization, you confirm that you may accept it for that organization, and "you" includes it. If
+you do not accept, do not install or use the Software.
+
+1. License. Subject to this agreement and to the plan you hold, we grant you a limited,
+   non-exclusive, non-transferable, non-sublicensable, revocable license to install and run the
+   Software, on machines and in continuous-integration environments you control, to analyze and
+   repair the test suites of software that you or your organization develop. The reporter and
+   capture files may be kept in your test projects and run as part of your own test runs, only for
+   that purpose.
+
+2. Restrictions. You may not, and may not allow anyone else to:
+   (a) copy, modify, merge, or distribute the Software, except to install and run it under this
+       license and to keep the files described in section 1 in your projects;
+   (b) decompile, disassemble, or reverse engineer the Software, except to the extent applicable
+       law permits this despite this restriction;
+   (c) sell, rent, lease, lend, sublicense, or provide the Software or the Service to third parties
+       as a hosted or managed service;
+   (d) use the Software or the Service to build or offer a competing product or service;
+   (e) circumvent plan limits, usage metering, authentication, request approval, or any other
+       technical control, including by changing the Software so that it does not report usage;
+   (f) remove or alter any proprietary, copyright, or license notice; or
+   (g) use the Software or the Service in violation of applicable law, including export control
+       and sanctions laws.
+
+3. Third-party components. The Software includes open-source components, each licensed under its
+   own license. They are listed, with their license texts, in THIRD_PARTY_NOTICES.md, which is
+   distributed with the Software. Those licenses govern those components, and nothing in this
+   agreement limits your rights under them.
+
+4. Plans, fees, and refunds. Plans, prices, and monthly limits are described at
+   https://kwikqa.com/pricing/. Usage is counted per AI request as described there. Paid plans are
+   sold by Paddle.com, our merchant of record, renew monthly or yearly until cancelled, and are
+   refunded as described at https://kwikqa.com/refunds/, including a full refund of your first
+   payment if you cancel within 14 days of it, once in any 12 months. We may change plans or
+   prices with at least 30 days' notice; a change applies from your next billing period after the
+   notice ends.
+
+5. Your data. You keep all rights in your code, test reports, evidence, and the changes the
+   Software makes to your code. The Software builds a redacted, size-limited evidence packet on
+   your machine and shows you a preview of each AI request before anything is sent.
+   (a) On hosted plans, an approved packet goes to the Service, which checks it, counts it toward
+       your plan, and forwards it unchanged to OpenRouter, which sends it to the model endpoint
+       named in the preview. The Service requires that every such request is routed only to an
+       endpoint with a zero-data-retention policy. The Service stores account, plan, usage, and
+       request metadata and a hash of each request; it does not store the evidence, your source
+       code, or the model's answer, which it holds only in memory until your Software collects it
+       (at most 15 minutes).
+   (b) On bring-your-own-key plans, requests go from your machine directly to OpenRouter under your
+       own OpenRouter account and its terms, and you are responsible for those charges. The
+       Software reports each request's kind, model, provider, and test framework to the Service so
+       it counts toward your plan.
+   (c) If your team's owner turns on team insights, the Software also shares the names, files, and
+       projects of failing and flaky tests and the outcome of each fix with your team.
+   (d) Run records, patches, transaction journals, captures, and validation output stay on your
+       machine.
+   You are responsible for making sure that what you approve sending does not include data you
+   are not permitted to share. https://kwikqa.com/security/ describes this in detail.
+
+6. AI output. Diagnoses and proposed repairs are generated with AI models and may be incomplete or
+   wrong. The Software checks proposals against its repair rules, applies a change only after you
+   approve it, and validates applied changes by running your tests, but none of this guarantees
+   that a diagnosis is correct or that a change is suitable for your code. You are responsible for
+   reviewing and accepting changes to your code and for how you use the output.
+
+7. Ownership and feedback. The Software and the Service, and all intellectual property in them,
+   belong to KwikQA and its licensors. This agreement grants no rights except those stated in it.
+   If you send us suggestions or feedback, we may use them without obligation to you.
+
+8. Updates. We may update the Software and the Service, and may stop supporting older versions of
+   the Software when the Service changes. This agreement applies to every update unless an update
+   comes with a different agreement.
+
+9. Term and termination. This agreement lasts until it is terminated. It ends automatically if you
+   breach it, and you may end it at any time by deleting the Software. When it ends you must stop
+   using the Software and delete it. Sections 2, 3, 5, 6, 7, 9, 10, 11, 12, and 13 survive
+   termination.
+
+10. No warranty. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE AND THE SERVICE ARE PROVIDED
+    "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED, OR STATUTORY,
+    INCLUDING ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, OR
+    NON-INFRINGEMENT, AND ANY WARRANTY THAT THE SOFTWARE OR THE SERVICE WILL BE UNINTERRUPTED OR
+    ERROR-FREE, OR THAT ANY DIAGNOSIS OR REPAIR WILL BE CORRECT OR WILL MAKE A TEST PASS.
+
+11. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW: (a) KWIKQA IS NOT LIABLE FOR
+    ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR ANY
+    LOSS OF DATA, PROFITS, REVENUE, OR GOODWILL, HOWEVER CAUSED, EVEN IF ADVISED OF THEIR
+    POSSIBILITY; AND (b) KWIKQA'S TOTAL LIABILITY FOR ALL CLAIMS ARISING OUT OF OR RELATING TO THIS
+    AGREEMENT, THE SOFTWARE, OR THE SERVICE IS LIMITED TO THE GREATER OF THE AMOUNT YOU PAID FOR THE
+    SERVICE IN THE TWELVE MONTHS BEFORE THE EVENT GIVING RISE TO THE CLAIM AND ONE HUNDRED US
+    DOLLARS (USD 100). NOTHING IN THIS AGREEMENT LIMITS LIABILITY THAT CANNOT BE LIMITED UNDER
+    APPLICABLE LAW, OR ANY RIGHTS YOU HAVE AS A CONSUMER THAT CANNOT BE WAIVED.
+
+12. Governing law. This agreement is governed by the laws of India, without regard to its
+    conflict-of-laws rules. The courts of India have jurisdiction over disputes arising from it,
+    except that we may seek urgent relief to protect our intellectual property in any competent
+    court. If you are a consumer, this does not take away the protection of the mandatory laws of
+    the country where you live.
+
+13. General. This agreement, together with the Terms of Service, is the entire agreement about the
+    Software and supersedes any prior agreement about it. You may not assign it without our
+    consent; we may assign it to a successor of our business. If a provision is unenforceable, the
+    rest remains in effect. Not enforcing a provision is not a waiver of it. We may update this
+    agreement; the version in effect when you install or update the Software applies to that
+    version, and material changes are announced on https://kwikqa.com.
+
+Contact: support@kwikqa.com (help), security@kwikqa.com (security), privacy@kwikqa.com (privacy).

package/README.md

@@ -1,3 +1,241 @@
-# Temporary Holding Version
+# KwikQA
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+KwikQA reads a failed **Playwright**, **Cypress**, or **WebdriverIO** run and tells you why it
+failed, using the evidence in your report, the page at the moment of failure, and your test source.
+When the test itself is at fault, it proposes a small repair to your test code, shows you the exact
+diff, applies it only after you approve, and keeps it only if your tests then pass.
+
+```sh
+npm i -D kwikqa
+npx playwright test        # or: npx cypress run, npx wdio run wdio.conf.ts
+npx kwikqa analyze
+npx kwikqa fix
+npx kwikqa validate
+```
+
+Using pnpm, Yarn, or Bun? See [Package managers and monorepos](#package-managers-and-monorepos).
+
+## What it will and won't do
+
+- **Diagnoses with evidence.** Every cause it reports cites the report fields, trace events, or source
+  lines that support it, and it says so when the evidence isn't enough.
+- **Repairs only test code.** It edits specs, page objects, fixtures, and helpers that your
+  `kwikqa.config.json` allows. It never edits application code, dependencies, or lockfiles.
+- **Never weakens a test.** It refuses edits that skip or focus tests, add fixed waits
+  (`waitForTimeout`, `cy.wait(1000)`, `browser.pause`) or retries, force actions past Cypress's
+  checks, remove or swap assertions and `should` chainers, or swallow errors.
+- **Nothing happens without you.** You see each AI request and each patch before it happens. Applying a
+  patch always asks, even in CI mode.
+- **Keeps a repair only if it validates.** `validate` reruns the failing test in a fresh process with
+  your project's own Playwright, Cypress, or WebdriverIO. Cypress runs the test's spec with every
+  other test skipped except the ones that passed before, which must still pass. If anything required
+  fails, the patch is rolled back. One retry is allowed, then it stops.
+- **Leaves your other work alone.** It won't touch files you have already modified, and rollback
+  restores only the bytes it changed.
+
+## Requirements
+
+- Node.js 20.11 or later
+- Playwright Test, Cypress, or WebdriverIO (Mocha or Jasmine) installed in your project with npm,
+  pnpm, Yarn, or Bun. KwikQA runs your project's own copy and never installs packages or browsers.
+- A git repository
+
+## Setup
+
+```sh
+npm i -D kwikqa
+npx kwikqa init
+npx kwikqa login
+```
+
+`init` proposes a `kwikqa.config.json` that lists which files KwikQA may edit, and offers to add
+`.kwikqa/` (local run records) to `.gitignore`. Review and commit the config like any other code.
+
+Then point KwikQA at your runs:
+
+**Playwright.** Add a JSON reporter to `playwright.config.ts`, and keep traces for failures:
+
+```ts
+export default defineConfig({
+  reporter: [["list"], ["json", { outputFile: "test-results/kwikqa-report.json" }]],
+  use: { trace: "retain-on-failure" },
+});
+```
+
+**Cypress.** Add KwikQA's reporter to `cypress.config.ts`. It keeps every retry attempt, where each
+test is declared, and each error's code frame:
+
+```ts
+export default defineConfig({
+  reporter: "node_modules/kwikqa/dist/cypress-reporter.cjs",
+  // ...
+});
+```
+
+Already writing mochawesome or JUnit reports? KwikQA reads those too:
+`npx kwikqa analyze --report mochawesome-report`.
+
+**WebdriverIO.** Add KwikQA's reporter to `wdio.conf.ts`, next to your own:
+
+```ts
+import KwikqaReporter from "kwikqa/wdio-reporter";
+
+export const config = {
+  reporters: ["spec", [KwikqaReporter, {}]],
+  // ...
+};
+```
+
+`@wdio/json-reporter` and JUnit reports work too: `npx kwikqa analyze --report <directory>`.
+
+KwikQA's reporters write to `test-results/kwikqa/`, which `analyze` finds on its own. Cypress and
+WebdriverIO keep no trace of a failure; run `npx kwikqa analyze --capture` and KwikQA re-runs the
+failing specs and records each failure's page (see below).
+
+`login` signs you in with GitHub; the free plan needs no payment details.
+
+### Package managers and monorepos
+
+This page uses npm's commands. With another package manager, install and run KwikQA the same way:
+
+| | Install | Run |
+| --- | --- | --- |
+| npm | `npm i -D kwikqa` | `npx kwikqa analyze` |
+| pnpm | `pnpm add -D kwikqa` | `pnpm exec kwikqa analyze` |
+| Yarn | `yarn add -D kwikqa` | `yarn kwikqa analyze` |
+| Bun | `bun add -d kwikqa` | `bunx kwikqa analyze` |
+
+The commands KwikQA suggests use the same form as the one you ran.
+
+In a monorepo, install KwikQA in the package that holds your tests, and run it from that package's
+folder, where its `kwikqa.config.json` goes. KwikQA finds that package's Playwright, Cypress, or
+WebdriverIO wherever your package manager installed it inside the repository, including the root's
+`node_modules`. It never runs one from outside the repository, so pnpm's global virtual store
+(`enableGlobalVirtualStore`) isn't supported.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `npx kwikqa analyze` | Diagnose the failures in the latest report. `--report <path>` picks a report file or a directory of one run's reports; `--framework` names the framework of a JUnit report; `--local` builds the evidence summary without sending anything; `--no-changes` leaves out recent code changes (see below). |
+| `npx kwikqa analyze --capture` | First re-run the failing tests so every failure has full evidence. Playwright runs with full tracing; with Playwright 1.59+ and [Playwright CLI](https://www.npmjs.com/package/@playwright/cli) installed, it also pauses locator failures at the failing line and asks Playwright for locators of the closest elements (`--no-probe` skips this). Cypress and WebdriverIO re-run the failing specs with your own config plus KwikQA's reporter and failure capture, which records each failed attempt's DOM, command log, console, and network. Asks before running anything; `--yes` approves in CI. |
+| `npx kwikqa fix` | Propose a repair for a test-side cause, show the diff and validation commands, and apply it if you approve. First it offers to re-run the failing tests once: a test that passes now is flaky, so KwikQA reports it and requests no repair. It starts with the failure group whose test-side diagnosis is strongest; if the model declines, or its proposal fails KwikQA's checks, it asks about the next such group, at most three, each with its own preview. One `fix` counts as one fix however many groups it tries. `--group <n>` repairs only group n, as `analyze` numbered it. `--propose-only` stops after the proposal. |
+| `npx kwikqa validate` | Run the approved validation. The repaired test must pass three times in a row, with retries off. Passing keeps the patch; failing rolls it back. When other tests failed with the same cause, it then offers to re-run them once and names any that still fail, so you can run `fix` again for them; the patch stays either way. |
+| `npx kwikqa fix --retry` | After a failed validation, re-diagnose from the new evidence and propose one revised patch. |
+| `npx kwikqa status` | Show your plan, team, and this month's usage. |
+| `npx kwikqa upgrade [plan]` | Show plans, or get a checkout link for one. `--annual` bills yearly; `--seats <n>` sets seats on team plans. On a paid plan it points you to Billing in the dashboard. While the paid plans are coming soon, it lists them without a link. |
+| `npx kwikqa billing` | Open Paddle's customer portal to update your payment method or download invoices. |
+| `npx kwikqa init` / `login` / `logout` | Set up the project, sign in, sign out (`logout` also revokes the token). |
+
+Exit codes: `0` success or an informative result, `1` the repair or validation did not succeed, `2`
+usage error, `3` sign-in, plan, or usage-limit problem.
+
+## Plans
+
+| Plan | Monthly | Annual | Analyses / month | Fixes / month |
+| --- | --- | --- | --- | --- |
+| Free | $0 | – | 10 | 3 |
+| Pro | $20 | $200 | 90 | 20 |
+| Team (3+ seats) | $25 / seat | $250 / seat | 100 / seat, shared | 25 / seat, shared |
+| BYOK | $10 | $100 | 500 | 150 |
+| BYOK Team (3+ seats) | $15 / seat | $150 / seat | Unlimited | Unlimited |
+
+One analysis is one diagnosis sent to the AI. One fix is one repair attempt, validated by
+`npx kwikqa validate`, and its one retry is included. Local-only analysis is free, and so is any
+request you decline or that stops before sending. `fix` reuses the diagnosis `analyze` already
+produced for the same run, so it doesn't use another analysis.
+
+The paid plans are coming soon: until they open, every account uses Free.
+
+Annual billing gives two months free. Cancel within 14 days of your first payment, monthly or
+annual, and it is refunded in full, once in any 12 months. After that, cancelling an annual plan from the dashboard refunds
+its unused months; monthly plans stay active until the end of the paid month. Payments go through
+Paddle, the merchant of record.
+
+### Teams
+
+On Team and BYOK Team, the owner invites people by GitHub username at
+https://kwikqa.com/dashboard/team/. Everyone, including CI tokens they create, draws from one
+monthly pool.
+
+The owner can also turn on **team insights**: the flakiest tests, fix history, acceptance rate,
+and repair success at https://kwikqa.com/dashboard/insights/. While insights are on, the CLI shares
+the names, files, and projects of failing and flaky tests and each fix's outcome with the team, and
+says so after each command. It never shares evidence, source, diffs, or error messages, and
+`analyze --local` shares nothing. `npx kwikqa status` shows whether insights are on.
+
+### Bring your own key
+
+On the BYOK plans, KwikQA sends requests straight to OpenRouter with your key, and your evidence
+never passes through KwikQA's servers. The CLI reports each request's kind, model, and provider to
+KwikQA so it counts toward your plan:
+
+```sh
+export OPENROUTER_API_KEY=sk-or-...
+# Optional: choose your own models as author/model@provider
+export KWIKQA_DIAGNOSIS_MODEL=anthropic/claude-haiku-5.5@anthropic
+export KWIKQA_REPAIR_MODEL=openai/gpt-6.1-sol@openai
+```
+
+## What is sent, and where
+
+Before any request, KwikQA builds a bounded evidence packet on your machine from your failing tests
+only. It contains selected report fields, trace events or the Cypress and WebdriverIO command log,
+the elements around each failed locator, the accessibility snapshot of the page at the failure,
+short source excerpts, and recent code changes that mention the failure. Secrets,
+credentials, password fields, and sensitive fields are removed from that packet before you see the
+preview. Redaction recognizes credentials, not every kind of personal data: names or email
+addresses in your test data can still appear in page text, so test with data you may share.
+Screenshots and videos are described by size and dimensions only; their pixels are never sent. Full
+files, full diffs, and your whole repository are never sent.
+
+Recent code changes tell a deliberately changed app from a broken one. KwikQA searches your
+uncommitted changes and your branch's commits since it left the default branch (on the default
+branch, the last 20 commits from the past 30 days). It looks for changed lines that contain what
+the failure names: locator text and test ids, expected and received values, and failed request
+paths. Only matching hunks of source files are kept, at most 12, each with its commit's subject
+line. The subjects of the commits searched (at most 20) and the names of source files with
+uncommitted changes are listed too. Author names, emails, commit bodies, and documentation are
+never read. The preview says how
+many changed hunks a request carries. `--no-changes` on `analyze` and `fix` leaves them out.
+
+- **Free, Pro, Team:** the redacted packet goes to the KwikQA service, which forwards it unchanged to
+  OpenRouter and the model endpoint shown in the preview. Requests go only to endpoints with a
+  zero-data-retention policy (Claude on Google Cloud Vertex AI, GPT on Microsoft Azure): the
+  service refuses a request that doesn't ask for that, and OpenRouter refuses rather than route it
+  to an endpoint that would keep it. The service keeps only account, usage, token, and cost
+  metadata and a hash of the request. It never stores your evidence, your source, or the model's
+  answer, which it holds in memory until your CLI collects it, for at most 15 minutes.
+- **BYOK, BYOK Team:** the packet goes from your machine directly to OpenRouter, under your
+  OpenRouter account and its settings. KwikQA's default routes ask for zero data retention there
+  too; a route you set with `KWIKQA_DIAGNOSIS_MODEL` or `KWIKQA_REPAIR_MODEL` does not. The CLI
+  reports only the request's kind, model, provider, and test framework to KwikQA, to count it.
+
+Run records, transaction journals, captures, and validation output stay on your machine in
+`.kwikqa/`. [Security and data handling](https://kwikqa.com/security/) and the
+[privacy policy](https://kwikqa.com/privacy/) have the details.
+
+## CI
+
+`analyze` can run unattended; `fix` cannot, because applying a patch always needs a person.
+
+```sh
+export KWIKQA_TOKEN=...   # create a CI token at https://kwikqa.com/dashboard/account/
+npx playwright test || npx kwikqa analyze --yes
+npx cypress run || npx kwikqa analyze --yes
+```
+
+## Account and billing
+
+The dashboard at https://kwikqa.com/dashboard/ shows your plan, usage, and recent requests. There
+you can change your plan, seats, or billing period, cancel, manage your team, create and revoke
+CLI and CI tokens, download your data, or delete your account.
+
+## Support and license
+
+KwikQA is proprietary software licensed under the end user license agreement in the package's
+`LICENSE` file; it is not open source. The open-source components bundled with it, and their
+licenses, are listed in `dist/THIRD_PARTY_NOTICES.md` in the package. The hosted service is also
+covered by the [terms of service](https://kwikqa.com/terms/), the
+[privacy policy](https://kwikqa.com/privacy/), and the [refund policy](https://kwikqa.com/refunds/).
+Questions and support: https://kwikqa.com/support

package/dist/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,54 @@
+# Third-party notices
+
+KwikQA is proprietary software (see LICENSE). It includes the following open-source
+components, each licensed under its own license, reproduced here.
+
+## @babel/parser 7.29.9 (MIT)
+
+```text
+Copyright (C) 2012-2014 by various contributors (see AUTHORS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+## fflate 0.8.3 (MIT)
+
+```text
+MIT License
+
+Copyright (c) 2026 Arjun Barrett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/cypress-capture.js

@@ -0,0 +1,190 @@
+// KwikQA's Cypress failure capture (KQA-081). `npx kwikqa analyze --capture` loads it through a
+// generated support file that imports the project's own support file first, so custom commands
+// and settings are unchanged. It never runs in a normal `cypress run`.
+//
+// When a test attempt fails it records, from the page under test: the DOM (as KwikQA's snapshot
+// tree), the Cypress command log with each command's state and error, console errors and
+// warnings, uncaught page errors, the network requests Cypress logged, and the paths of the
+// failure screenshots. Each attempt is written with cy.writeFile under the capture directory set
+// by the generated support file, named so KwikQA's reporter can attach it to the attempt.
+/* global Cypress, cy, afterEach, beforeEach */
+
+const settings = globalThis.__kwikqaCapture || {};
+const OUT = settings.directory || ".kwikqa/capture/cypress";
+// Validation runs only the tests a repair is accountable for: Cypress cannot select tests by name,
+// so every other test is skipped before its own hooks run, and the run's exit code covers just these.
+const ONLY = Array.isArray(settings.only) ? new Set(settings.only) : undefined;
+
+if (ONLY) {
+  beforeEach(function kwikqaOnly() {
+    const test = this.currentTest;
+    if (test && !ONLY.has(test.titlePath().join(" "))) this.skip();
+  });
+}
+const MAX_NODES = 20000;
+const MAX_TEXT = 2000;
+const MAX_LOG = 300;
+const SKIPPED_TAGS = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "LINK", "META"]);
+const FORM_FIELDS = new Set(["INPUT", "TEXTAREA", "SELECT"]);
+
+function fnv1a(text) {
+  let hash = 0x811c9dc5;
+  for (const byte of new TextEncoder().encode(text)) {
+    hash ^= byte;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+/** Must match captureKey in cypress-reporter.cjs. */
+function captureKey(spec, titlePath, retry) {
+  const slug = String(spec)
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .slice(-60);
+  return `${slug}--${fnv1a(`${spec}\u0000${titlePath.join("\u0000")}`)}--${retry}`;
+}
+
+/** The page as `[TAG, {attributes}, ...children]`, text as strings: KwikQA's snapshot tree. */
+function serialize(root) {
+  let budget = MAX_NODES;
+  const visit = (node) => {
+    if (budget <= 0) return undefined;
+    if (node.nodeType === 3) {
+      const value = node.textContent || "";
+      return value.trim() === "" ? undefined : value.slice(0, MAX_TEXT);
+    }
+    if (node.nodeType !== 1) return undefined;
+    if (SKIPPED_TAGS.has(node.tagName)) return undefined;
+    budget -= 1;
+    const attributes = {};
+    for (const attribute of Array.from(node.attributes)) {
+      attributes[attribute.name] = String(attribute.value).slice(0, MAX_TEXT);
+    }
+    // Form state is a property, not an attribute; the snapshot records what the user saw, under
+    // the names KwikQA's DOM renderer already reads from Playwright snapshots.
+    if (FORM_FIELDS.has(node.tagName) && typeof node.value === "string") {
+      attributes.__playwright_value_ = node.value.slice(0, MAX_TEXT);
+    }
+    if (node.checked === true) attributes.__playwright_checked_ = "true";
+    const children = [];
+    const childNodes = node.shadowRoot
+      ? [...Array.from(node.shadowRoot.childNodes), ...Array.from(node.childNodes)]
+      : Array.from(node.childNodes);
+    for (const child of childNodes) {
+      const value = visit(child);
+      if (value !== undefined) children.push(value);
+    }
+    return [node.tagName, attributes, ...children];
+  };
+  return { tree: visit(root), truncated: budget <= 0 };
+}
+
+let commands = [];
+let consoleEntries = [];
+let screenshots = [];
+
+function brief(attributes) {
+  const props = attributes.renderProps || {};
+  const message = props.message !== undefined ? props.message : attributes.message;
+  return {
+    id: attributes.id,
+    name: String(attributes.name || ""),
+    ...(attributes.displayName ? { displayName: String(attributes.displayName) } : {}),
+    message: String(message === undefined ? "" : message).slice(0, MAX_TEXT),
+    state: String(attributes.state || ""),
+    ...(attributes.err
+      ? { error: String(attributes.err.message || attributes.err).slice(0, MAX_TEXT) }
+      : {}),
+    ...(attributes.url ? { url: String(attributes.url) } : {}),
+  };
+}
+
+Cypress.on("test:before:run", () => {
+  commands = [];
+  consoleEntries = [];
+  screenshots = [];
+});
+Cypress.on("log:added", (attributes) => {
+  if (commands.length < MAX_LOG) commands.push(brief(attributes));
+});
+Cypress.on("log:changed", (attributes) => {
+  const index = commands.findIndex((entry) => entry.id === attributes.id);
+  if (index >= 0) commands[index] = brief(attributes);
+});
+Cypress.on("window:before:load", (win) => {
+  for (const level of ["error", "warn"]) {
+    const original = win.console[level];
+    win.console[level] = (...args) => {
+      if (consoleEntries.length < MAX_LOG) {
+        consoleEntries.push({
+          level,
+          text: args
+            .map((arg) => String(arg))
+            .join(" ")
+            .slice(0, MAX_TEXT),
+        });
+      }
+      return original.apply(win.console, args);
+    };
+  }
+  win.addEventListener("error", (event) => {
+    consoleEntries.push({ level: "pageerror", text: String(event.message).slice(0, MAX_TEXT) });
+  });
+  win.addEventListener("unhandledrejection", (event) => {
+    consoleEntries.push({
+      level: "pageerror",
+      text: `Unhandled rejection: ${String(event.reason).slice(0, MAX_TEXT)}`,
+    });
+  });
+});
+Cypress.Screenshot.defaults({
+  onAfterScreenshot(_element, props) {
+    screenshots.push({ path: props.path, testFailure: props.testFailure === true });
+  },
+});
+
+afterEach(function kwikqaCapture() {
+  const test = this.currentTest;
+  if (test?.state !== "failed") return;
+  const titlePath = test.titlePath();
+  const retry =
+    typeof test.currentRetry === "function" ? test.currentRetry() : test._currentRetry || 0;
+  const spec = Cypress.spec.relative;
+  cy.document({ log: false }).then((doc) => {
+    const snapshot = serialize(doc.documentElement);
+    const network = commands
+      .filter(
+        (entry) =>
+          entry.name === "request" ||
+          entry.name === "xhr" ||
+          entry.displayName === "fetch" ||
+          entry.displayName === "xhr",
+      )
+      .map((entry) => ({
+        message: entry.message,
+        state: entry.state,
+        ...(entry.url ? { url: entry.url } : {}),
+      }));
+    const capture = {
+      schema: "kwikqa-capture",
+      schemaVersion: "1.0",
+      framework: "cypress",
+      spec,
+      titlePath,
+      retry,
+      url: doc.location ? doc.location.href : "",
+      title: doc.title,
+      viewport: {
+        width: Cypress.config("viewportWidth"),
+        height: Cypress.config("viewportHeight"),
+      },
+      dom: snapshot.tree,
+      domTruncated: snapshot.truncated,
+      commands: commands.map(({ id, ...rest }) => rest),
+      console: consoleEntries,
+      network,
+      screenshots,
+    };
+    cy.writeFile(`${OUT}/${captureKey(spec, titlePath, retry)}.json`, capture, { log: false });
+  });
+});