testaro 78.0.6 → 78.4.0

package/.gitattributes

@@ -0,0 +1,94 @@
+# Generated by tsc from the sibling .ts sources (npm run build:ts); do not edit.
+types.js linguist-generated=true
+types.d.ts linguist-generated=true
+procs/xPath.js linguist-generated=true
+procs/xPath.d.ts linguist-generated=true
+procs/catalog.js linguist-generated=true
+procs/catalog.d.ts linguist-generated=true
+procs/testaro.js linguist-generated=true
+procs/testaro.d.ts linguist-generated=true
+testaro/altScheme.js linguist-generated=true
+testaro/altScheme.d.ts linguist-generated=true
+testaro/autocomplete.js linguist-generated=true
+testaro/autocomplete.d.ts linguist-generated=true
+testaro/datalistRef.js linguist-generated=true
+testaro/datalistRef.d.ts linguist-generated=true
+testaro/hr.js linguist-generated=true
+testaro/hr.d.ts linguist-generated=true
+testaro/lineHeight.js linguist-generated=true
+testaro/lineHeight.d.ts linguist-generated=true
+testaro/radioSet.js linguist-generated=true
+testaro/radioSet.d.ts linguist-generated=true
+testaro/allSlanted.js linguist-generated=true
+testaro/allSlanted.d.ts linguist-generated=true
+testaro/distortion.js linguist-generated=true
+testaro/distortion.d.ts linguist-generated=true
+testaro/miniText.js linguist-generated=true
+testaro/miniText.d.ts linguist-generated=true
+testaro/phOnly.js linguist-generated=true
+testaro/phOnly.d.ts linguist-generated=true
+testaro/legendLoc.js linguist-generated=true
+testaro/legendLoc.d.ts linguist-generated=true
+testaro/linkExt.js linguist-generated=true
+testaro/linkExt.d.ts linguist-generated=true
+testaro/linkOldAtt.js linguist-generated=true
+testaro/linkOldAtt.d.ts linguist-generated=true
+testaro/linkTo.js linguist-generated=true
+testaro/linkTo.d.ts linguist-generated=true
+testaro/linkUl.js linguist-generated=true
+testaro/linkUl.d.ts linguist-generated=true
+testaro/nonTable.js linguist-generated=true
+testaro/nonTable.d.ts linguist-generated=true
+testaro/optRoleSel.js linguist-generated=true
+testaro/optRoleSel.d.ts linguist-generated=true
+testaro/pseudoP.js linguist-generated=true
+testaro/pseudoP.d.ts linguist-generated=true
+testaro/secHeading.js linguist-generated=true
+testaro/secHeading.d.ts linguist-generated=true
+testaro/textSem.js linguist-generated=true
+testaro/textSem.d.ts linguist-generated=true
+testaro/titledEl.js linguist-generated=true
+testaro/titledEl.d.ts linguist-generated=true
+testaro/zIndex.js linguist-generated=true
+testaro/zIndex.d.ts linguist-generated=true
+testaro/title.js linguist-generated=true
+testaro/title.d.ts linguist-generated=true
+testaro/docType.js linguist-generated=true
+testaro/docType.d.ts linguist-generated=true
+testaro/allHidden.js linguist-generated=true
+testaro/allHidden.d.ts linguist-generated=true
+testaro/role.js linguist-generated=true
+testaro/role.d.ts linguist-generated=true
+testaro/bulk.js linguist-generated=true
+testaro/bulk.d.ts linguist-generated=true
+testaro/headEl.js linguist-generated=true
+testaro/headEl.d.ts linguist-generated=true
+testaro/linkAmb.js linguist-generated=true
+testaro/linkAmb.d.ts linguist-generated=true
+testaro/dupAtt.js linguist-generated=true
+testaro/dupAtt.d.ts linguist-generated=true
+testaro/hover.js linguist-generated=true
+testaro/hover.d.ts linguist-generated=true
+testaro/motion.js linguist-generated=true
+testaro/motion.d.ts linguist-generated=true
+testaro/targetsNear.js linguist-generated=true
+testaro/targetsNear.d.ts linguist-generated=true
+testaro/textNodes.js linguist-generated=true
+testaro/textNodes.d.ts linguist-generated=true
+testaro/elements.js linguist-generated=true
+testaro/elements.d.ts linguist-generated=true
+testaro/allCaps.js linguist-generated=true
+testaro/allCaps.d.ts linguist-generated=true
+testaro/focAll.js linguist-generated=true
+testaro/focAll.d.ts linguist-generated=true
+testaro/styleDiff.js linguist-generated=true
+testaro/styleDiff.d.ts linguist-generated=true
+testaro/buttonMenu.js linguist-generated=true
+testaro/buttonMenu.d.ts linguist-generated=true
+testaro/tabNav.js linguist-generated=true
+testaro/tabNav.d.ts linguist-generated=true
+testaro/registry.js linguist-generated=true
+testaro/registry.d.ts linguist-generated=true
+testaro/registry.ts linguist-generated=true
+tests/testaro.js linguist-generated=true
+tests/testaro.d.ts linguist-generated=true

package/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+# © 2026 Jeff Witt.
+#
+# Licensed under the MIT License. See LICENSE file at the project root or
+# https://opensource.org/license/mit/ for details.
+#
+# SPDX-License-Identifier: MIT
+
+# CI: lints the code and validates the Testaro rules on every push and pull request.
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          cache: npm
+      # Postinstall scripts only download browsers and a JRE, which linting does not need.
+      - run: npm ci --ignore-scripts
+      - run: npm run lint
+
+  validate:
+    name: Validate Testaro rules
+    runs-on: ubuntu-latest
+    # The image tag must match the playwright version in package-lock.json (see CONTAINERS.md).
+    # The next step enforces that; when Playwright is updated, update the tag here, too.
+    container:
+      image: mcr.microsoft.com/playwright:v1.62.1-noble
+    timeout-minutes: 45
+    env:
+      # The default Docker seccomp profile blocks the namespace cloning of the Chromium sandbox.
+      TESTARO_CHROMIUM_NO_SANDBOX: 'true'
+    steps:
+      - uses: actions/checkout@v5
+      - name: Require the container image to match the pinned Playwright version
+        run: |
+          lockVersion=$(node -p "require('./package-lock.json').packages['node_modules/playwright'].version")
+          imageVersion='1.62.1'
+          if [ "$lockVersion" != "$imageVersion" ]; then
+            echo "package-lock.json pins playwright $lockVersion, but this workflow uses the v$imageVersion image."
+            echo "Update the container image tag and imageVersion in .github/workflows/ci.yml (see CONTAINERS.md)."
+            exit 1
+          fi
+      - run: npm ci
+      - run: npm run tests

package/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+# © 2026 Jeff Witt.
+#
+# Licensed under the MIT License. See LICENSE file at the project root or
+# https://opensource.org/license/mit/ for details.
+#
+# SPDX-License-Identifier: MIT
+
+# Publishes the package to npm when a GitHub release is published (the release tag must equal
+# v<package.json version>), or on manual dispatch. Authenticates with the NPM_TOKEN repository
+# secret, a granular access token with publish permission for the testaro package.
+# prepublishOnly regenerates the rule registry and the emitted TypeScript, and the version
+# check refuses a release tag that does not match.
+
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          cache: npm
+          registry-url: https://registry.npmjs.org
+      - name: Check that the release tag matches the package version
+        if: github.event_name == 'release'
+        run: |
+          version=$(node -p "require('./package.json').version")
+          if [ "${{ github.event.release.tag_name }}" != "v$version" ]; then
+            echo "Release tag ${{ github.event.release.tag_name }} does not match package version v$version" >&2
+            exit 1
+          fi
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/typescript.yml

@@ -0,0 +1,35 @@
+name: TypeScript
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  typecheck:
+    name: Type check and syntax check
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Generate rule registry
+        run: npm run build:registry
+      - name: Compile TypeScript
+        run: npm run build:ts
+      - name: Committed emit matches sources
+        run: git diff --exit-code
+      - name: Syntax-check all JavaScript
+        run: |
+          set -e
+          find . -name '*.js' \
+            -not -path './node_modules/*' \
+            -not -path './.git/*' \
+            -not -path './dist/*' \
+            -not -path './ed11y/*' \
+            -print0 | xargs -0 -n1 node --check

package/AGENTS.md

@@ -7,7 +7,7 @@
 - **Run job**: `npm run run [jobID]`
 - **Directory watch**: `npm run dirWatch`
 - **Network watch**: `npm run netWatch`
-- **Lint**: `npx eslint <file>` (follows `.eslintrc.json`)
+- **Lint**: `npm run lint` (follows `eslint.config.mjs`)
 
 ## Architecture
 
@@ -15,7 +15,7 @@
 - **Key files**: `run.js` (main executor), `actSpecs.js` (act specifications), `call.js` (CLI entry), `tests/testaro.js` (Testaro tool rules)
 - **Tools**: Integrates these accessibility tools: Axe, Alfa, IBM Checker, QualWeb, ASLint, WAVE, Ed11y, HTML CodeSniffer, Nu Html Checker API, Nu Html Checker, Testaro
 - **Data flow**: Jobs (JSON) → run.js → tool tests → reports (with standardized results)
-- **Env vars**: Required for WAVE (`WAVE_KEY`); optional `DEBUG`, `WAITS`, `JOBDIR`, `REPORTDIR`, `AGENT`
+- **Env vars**: Required for WAVE (`WAVE_KEY`); optional `DEBUG`, `WAITS`, `JOBDIR`, `REPORTDIR`; for server polling `NETWATCH_URL_JOB`, `NETWATCH_URL_REPORT`, `NETWATCH_AUTH_TYPE`, `NETWATCH_WORKER_ID`, `NETWATCH_WORKER_SECRET`
 
 ## Code Style
 

package/CLAUDE.md

@@ -12,7 +12,7 @@ npm run deps
 npm run build
 
 # Lint (ESLint)
-npx eslint .
+npm run lint
 
 # Validate a single Testaro rule (replace <ruleID> with the rule name, e.g. allSlanted)
 npm test <ruleID>
@@ -32,25 +32,25 @@ node call netWatch <true|false> <intervalSeconds> [<true|false>]
 
 ## Architecture
 
-Testaro is an ensemble accessibility test runner. It integrates 10 external tools plus ~50 of its own rules (the "testaro" tool) and produces standardized reports from a job document.
+Testaro is an ensemble accessibility test runner. It integrates 12 external tools plus ~50 of its own rules (the "testaro" tool) and produces standardized reports from a job document.
 
 ### Job → Report lifecycle
 
 1. A caller provides a **job** — a plain JS/JSON object with a `target` URL, `browserID`, optional `device`, and an `acts` array.
-2. `run.js` exports `doJob(job)`, which validates the job (`procs/job.js`), builds a DOM **catalog** (`procs/catalog.js`), then delegates to `procs/doActs.js`.
-3. `doActs.js` iterates the acts array. For `test` acts it forks a child process running `procs/doTestAct.js` (one per tool invocation) and enforces per-tool time limits. Non-test acts (browser interactions) execute in the parent.
-4. Each tool's test module lives in `tests/<toolID>.js`. It calls the tool's library and converts the native result to the **standard result** shape (`prevented`, `totals[4]`, `instances[]`).
+2. `run.js` exports `doJob(job)`, which validates the job (`procs/job.js`), builds a DOM **catalog** (`procs/catalog.ts`) as checkpoint 0, then delegates to `procs/doActs.js`.
+3. `doActs.js` iterates the acts array. For `test` acts it forks a child process running `procs/doTestAct.js` (one per tool invocation) and enforces per-tool time limits. Non-test acts (browser interactions) execute in the parent through `procs/actDo.js`. A `checkpoint` act snapshots the live page (`procs/checkpoint.js`) as a page state that later test acts observe: the child's launcher replays the recorded interaction acts before the tool runs (`docs/checkpoint-scanning.md`).
+4. Each tool's test module lives in `tests/<toolID>.ts` (compiled to a committed `tests/<toolID>.js`). It calls the tool's library and converts the native result to the **standard result** shape (`prevented`, `totals[4]`, `outcomeTotals`, `instances[]`) using the helpers in `procs/standard.ts`. Every instance carries an `outcome` (`failed` or `cantTell`) that is the authoritative certainty signal; `ordinalSeverity` still encodes certainty per tool until it is redefined as impact only (see `docs/standard-result-outcome.md`).
 5. `doJob` returns the job object with `jobData` and `catalog` added at the top level and `result` added inside each `test` act. The job's `standard` property controls what `result` contains: `'no'` → `nativeResult` only; `'only'` → `standardResult` only; `'also'` → both.
 
-The 18 act types are defined and documented in `actSpecs.js` (`etc` property). The main interactive types are `button`, `checkbox`, `focus`, `link`, `press`, `presses`, `radio`, `reveal`, `search`, `select`, `text`, `url`, `wait`. The `test` type runs a tool. `launch`, `next`, `page`, `state` control flow.
+The 19 act types are defined and documented in `actSpecs.js` (`etc` property). The main interactive types are `button`, `checkbox`, `focus`, `link`, `press`, `presses`, `radio`, `reveal`, `search`, `select`, `text`, `url`, `wait`. The `test` type runs a tool. `launch`, `next`, `page`, `state` control flow. `checkpoint` snapshots a page state. A `test` act's optional `scope` (`page` or `changed`) restricts element-local rules to the subtrees changed since the previous checkpoint (`procs/scope.js`); reports with two or more checkpoints gain `flow`, the issue deltas between checkpoints (`procs/flow.js`). Move acts accept a Playwright `selector`; `procs/userPath.js` converts a recorded user path (yra-monitor's action shape) into acts. See `docs/checkpoint-scanning.md`.
 
 ### Testaro rules (`testaro/` directory)
 
-Each file exports a `reporter(page, catalog, withItems)` async function. Rules are registered in `tests/testaro.js` in the `allRules` array, which controls default execution order, contamination flags, time limits, and `defaultOn`.
+Each file exports a `reporter(page, catalog, withItems)` async function. Rules are registered in `tests/testaro.ts` in the `allRules` array, which controls default execution order, contamination flags, time limits, `defaultOn`, and an optional default `outcome`. The generated `testaro/registry.ts` maps rule IDs to modules.
 
 The default order in `allRules` reflects a two-phase execution strategy: non-contaminating rules (`contaminates: false`) come first and all share a single page load; contaminating rules (`contaminates: true`) follow, each tested on a freshly loaded copy of the page.
 
-Two rules, `shoot0` and `shoot1`, are atypical: they report no violations. Instead they take screenshots at different points during a job so that the `motion` rule can compare them to detect and measure visible page change, avoiding the latency that would be required if `motion` took its own screenshots and waited between them.
+The `motion` rule is atypical: it takes its own screenshot and compares it with the page image of the checkpoint being tested (`report.images`, made when the catalog was built), so that visible page change is detected without waiting between two screenshots of its own.
 
 Two implementation patterns exist:
 
@@ -59,9 +59,9 @@ Two implementation patterns exist:
 
 ### Validation
 
-Validation is currently broken. A reconsideration of its architecture is anticipated, but in the meantime the next paragraph describes its current inoperative design.
+A revision of the validation architecture is currently being planned. In the meantime the next paragraph describes its current design, not guaranteed to work without error.
 
-Validation tests live in `validation/tests/jobs/` (jobs with `expect` arrays) and `validation/tests/targets/` (static HTML pages served locally as test targets). Running `npm test <ruleID>` executes `validation/executors/test.js` → `validation/validateTest.js`, which runs the job and compares `result` fields against `expect` clauses.
+Validation tests live in `validation/tests/jobProperties/` (jobs with `expect` arrays) and `validation/tests/targets/` (static HTML pages served locally as test targets). Running `npm test <ruleID>` executes `validation/executors/test.js` → `validation/validateTest.js`, which runs the job and compares `result` fields against `expect` clauses.
 
 ### Tool XPath strategy
 
@@ -81,21 +81,23 @@ Key variables:
 - `WAITS` — ms delay inserted between Playwright operations (useful for debugging)
 - `WAVE_KEY` — API key for the WAVE subscription API
 - `JOBDIR` / `REPORTDIR` — root directories for job files and report output
-- `AGENT` — instance name used in network-watch mode
-- `NETWATCH_URL_<N>_JOB/REPORT/AUTH`, `NETWATCH_URLS` — server polling configuration
+- `NETWATCH_URL_JOB`/`NETWATCH_URL_REPORT`/`NETWATCH_AUTH_TYPE`/`NETWATCH_WORKER_ID`/`NETWATCH_WORKER_SECRET` — server polling configuration
 - `TIMEOUT_MULTIPLIER` — scales all per-tool time limits (default 1)
+- `NAV_WAIT_UNTIL`/`NAV_TIMEOUT`/`NAV_FAIL_FAST_4XX`, `SCANNER_ID`, `PRESCAN_SCROLL`, `TESTARO_RULE_RETRIES`, `QUALWEB_STEALTH`/`QUALWEB_ADBLOCK` — deployment defaults that job properties (`navigation`, `scannerId`, `scroll`, `browserChannel`; `retries`, `stealth`, `adBlock` on test acts) override (`procs/config.js`)
 
 ## Code style
 
-ESLint (`eslintrc.json`): 2-space indent, single quotes, semicolons, Stroustrup brace style (`else`/`catch` on a new line after `}`), `no-use-before-define`. The `htmlcs/HTMLCS.js` file uses a separate, looser ESLint config and must not be reformatted.
+The rule modules, the tool adapters, `procs/testaro.ts`, `procs/catalog.ts`, `procs/xPath.ts`, `procs/standard.ts`, and `types.ts` are TypeScript sources; their `.js` and `.d.ts` outputs are committed. Edit the `.ts` file, then run `npm run build:ts` (and `npm run build:registry` after adding or removing a rule module) and commit the regenerated outputs; CI fails if they drift. Files without a `.ts` counterpart are still plain JavaScript. See `CONTRIBUTING.md`.
+
+ESLint (`eslint.config.mjs`): 2-space indent, single quotes, semicolons, Stroustrup brace style (`else`/`catch` on a new line after `}`), `no-use-before-define`. Emitted `.js` files are excluded from linting. The vendored `htmlcs/HTMLCS.js`, `ed11y`, `surea11y`, and `pour` bundles are excluded from linting; `htmlcs/HTMLCS.js` must not be reformatted.
 
 Long comments are not broken into multiple lines per paragraph.
 
 ## Adding a new Testaro rule
 
-1. Add an entry to `allRules` in `tests/testaro.js`.
-2. Create `testaro/<ruleID>.js` exporting a `reporter` function using `doTest` (preferred) or `getBasicResult`.
-3. Write a validation job in `validation/tests/jobs/<ruleID>.json` with an `expect` array and corresponding HTML target(s) in `validation/tests/targets/<ruleID>/`.
+1. Add an entry to `allRules` in `tests/testaro.ts`.
+2. Create `testaro/<ruleID>.ts` exporting a `reporter` function using `doTest` (preferred) or `getBasicResult`, then run `npm run build:registry && npm run build:ts` and commit the regenerated registry and emitted files.
+3. Write a validation job in `validation/tests/jobProperties/<ruleID>.json` with an `expect` array and corresponding HTML target(s) in `validation/tests/targets/<ruleID>/`.
 4. Run `npm test <ruleID>` until validation passes.
 
 ## Key files
@@ -104,14 +106,18 @@ Long comments are not broken into multiple lines per paragraph.
 | ---- | ------- |
 | `run.js` | `doJob()` — the main entry point |
 | `call.js` | CLI wrapper for `run`, `dirWatch`, `netWatch` |
-| `procs/doActs.js` | Iterates acts; forks child for each tool |
+| `procs/doActs.js` | Iterates acts; forks child for each tool; assigns test acts to checkpoints |
+| `procs/actDo.js` | Performs the acts that operate on a live page; replays a checkpoint's acts |
+| `procs/checkpoint.js` | Snapshots a live page as a checkpoint |
 | `procs/doTestAct.js` | Child-process entry point for tool invocations |
 | `procs/testaro.js` | `doTest` / `getBasicResult` helpers for Testaro rules |
 | `procs/launch.js` | Browser lifecycle (launch, goTo, nonce, wait) |
-| `procs/catalog.js` | Builds the element catalog from the DOM |
+| `procs/catalog.ts` | Builds the element catalog from the DOM (checkpoint 0, and any live page for later checkpoints) |
 | `procs/job.js` | Job validation; `tools` constant |
 | `actSpecs.js` | Canonical specs for all 18 act types |
-| `tests/testaro.js` | `allRules` registry for the testaro tool |
+| `tests/testaro.ts` | `allRules` registry for the testaro tool |
+| `procs/standard.ts` | Builders for the standard result and its instances (`outcome`, `uncertainty`, `needed`) |
+| `testaro/registry.ts` | Generated map of rule IDs to rule modules (`npm run build:registry`) |
 | `testaro/<ruleID>.js` | One file per Testaro rule |
 | `validation/validateTest.js` | Core validation harness |
 

package/CONTAINERS.md

@@ -63,17 +63,20 @@ docker run --rm --init \
 
 ## Server polling
 
-To poll a server for jobs instead of watching a directory, override the command and provide the `netWatch` variables:
+To poll a server for jobs instead of watching a directory, override the command and provide the `netWatch` variables, such as:
 
 ```bash
 docker run --rm --init \
-  -e AGENT=agent1 \
-  -e NETWATCH_URL_JOB=https://example.com/api/testaro-agent/job \
-  -e NETWATCH_URL_REPORT=https://example.com/api/testaro-agent/report \
-  -e NETWATCH_URL_AUTH=password \
-  testaro node call netWatch true 300 true
+  -e NETWATCH_URL_JOB=https://myserver.com/worker/job \
+  -e NETWATCH_URL_REPORT=https://myserver.com/worker/report \
+  -e NETWATCH_AUTH_TYPE=header \
+  -e NETWATCH_WORKER_ID=worker1 \
+  -e NETWATCH_WORKER_SECRET=seekRut \
+  testaro node call netWatch true 300
 ```
 
+The same variables can be supplied through the Compose stack instead: define them in `.env` and run `docker compose run testaro node call netWatch true 300`. A third `netWatch` argument of `true` would disable certificate verification; leave it off except against servers you control.
+
 ## Operational notes
 
 - **Init process**: Testaro forks a child process per test act, and some tools relaunch browsers repeatedly, so zombie reaping matters more than for typical browser-automation applications. Always run with an init process (`docker run --init`; in Compose, `init: true`).
@@ -84,6 +87,7 @@ docker run --rm --init \
 ## License
 
 © 2026 Jeff Witt.
+© 2026 Jonathan Robert Pool.
 
 Licensed under the [MIT License](https://opensource.org/license/mit/). See [LICENSE](LICENSE) file at the project root for details.
 

package/CONTRIBUTING.md

@@ -41,18 +41,18 @@ The second step is to write a validator for the new rule. A validator is softwar
 
 Every Testaro rule (which means each of the approximately 50 rules of the Testaro tool) has a correspoding validator. A validator has two parts:
 
-- A job file, in the `validation/tests/jobs` directory. It tells Testaro what tests to perform and what the results should be.
+- A job-properties file, in the `validation/tests/jobProperties` directory. It tells Testaro what tests to perform and what the results should be.
 - A target directory, within the `validation/tests/targets` directory. The target directory contains one or more HTML files that will be tested by the job.
 
 Inspecting some of the jobs and targets in the `validation/tests` directory can help you understand how validators work.
 
 ### Step 3
 
-The third step is to add an entry to the `allRules` object in the `tests/testaro.js` file.
+The third step is to add an entry to the `allRules` array in the `tests/testaro.ts` file, and then to run `npm run build:ts` so that the emitted `tests/testaro.js` matches. See [Editing TypeScript files](#editing-typescript-files) below.
 
 ### Step 4
 
-The fourth step is to implement the new rule by creating a JavaScript file and saving it in the `testaro` directory.
+The fourth step is to implement the new rule by creating a TypeScript file and saving it in the `testaro` directory. Then run `npm run build:registry && npm run build:ts`, which adds the rule to the generated registry and compiles both files. See [Editing TypeScript files](#editing-typescript-files) below.
 
 To optimize quality, it may be wise for one person to perform steps 1, 2, and 3, and then for a second person independently to perform step 4 (“clean-room” development).
 
@@ -62,6 +62,32 @@ Whether a new rule should be implemented with support from the `doTest` function
 
 The existing `testaro` tests can serve as templates for new ones. At present, only the `hover` and `role` tests make use of the `getBasicResult` function.
 
+## Editing TypeScript files
+
+Testaro is migrating from JavaScript to TypeScript, one file at a time ([issue #73](https://github.com/YRA-Tech/testaro/issues/73)). Files that have been converted exist in three forms in the same directory:
+
+- `x.ts` — the source, the only one you edit.
+- `x.js` — compiled from `x.ts` by the TypeScript compiler, and **committed**.
+- `x.d.ts` — the type declarations, also compiled and committed.
+
+The emitted files are committed rather than built at install time so that the package layout is identical to what it was before the migration: consumers that deep-import a module path, and the `patch-package` patches that some deployments apply, keep working unchanged. Every converted `.ts` file says so near the top:
+
+```text
+Compiled to x.js by tsc (issue #73); edit this file, not the emitted one.
+```
+
+**If a file has a `.ts` version, edit that one and never the emitted `.js`.** After editing, run:
+
+```bash
+npm run build:ts
+```
+
+and commit the regenerated `.js` and `.d.ts` alongside your `.ts` change. If you added or removed a rule module in the `testaro` directory, run `npm run build:registry` first, which regenerates `testaro/registry.ts` from the modules on disk.
+
+Continuous integration enforces this: it regenerates the registry, compiles, and fails the pull request if any emitted file differs from what was committed. A hand-edited `.js` will therefore fail the check, and the edit would be overwritten by the next compile in any case.
+
+Files that have not been converted yet are still plain JavaScript with no `.ts` counterpart; edit those directly, as before. Some of them have a hand-written `x.d.ts` neighbor that describes the module to converted TypeScript files. If you change such a module's exported interface, update its `.d.ts` to match.
+
 ## License agreement
 
 From 12 February 2024 through 30 September 2025, contributors of code to Testaro executed the [CVS Health OSS Project Contributor License Agreement](https://forms.office.com/pages/responsepage.aspx?id=uGG7-v46dU65NKR_eCuM1xbiih2MIwxBuRvO0D_wqVFUQ1k0OE5SVVJWWkY4MTVJMkY3Sk9GM1FHRC4u) for Testaro before any pull request was approved and merged.

package/Dockerfile

@@ -10,7 +10,7 @@
 # The base-image tag must match the version of the playwright package in
 # package-lock.json, so that the browsers baked into the image are the ones
 # the installed Playwright expects.
-FROM mcr.microsoft.com/playwright:v1.62.0-noble
+FROM mcr.microsoft.com/playwright:v1.62.1-noble
 
 # Install a headless Java runtime for the nuVnu test (vnu-jar); baking it in
 # prevents vnu-jar from downloading a Temurin runtime over the network on