diff --git a/.eslintignore b/.eslintignore
index a8785a4159..9e18c02c13 100644
--- a/.eslintignore
+++ b/.eslintignore
@@ -15,3 +15,9 @@ node_modules
 
 # ignore mocks
 **/mock.ts
+
+# ignore Playwright's output, for the same reason as dist: the HTML report embeds the minified trace
+# viewer. Both directories are mounted out of the container by tools/e2e/docker-compose.yml and turn
+# up as soon as anyone runs the suite locally — but, like dist, never on the fresh checkout CI lints.
+/playwright-report/
+/test-results/
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000000..b0aa6ad401
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,11 @@
+# Deliberately narrow. `* text=auto` is tempting but would renormalize every tracked file in a
+# single commit, so line endings are left alone except where they are load-bearing.
+
+# The Docker build inputs are consumed by a Linux shell. A contributor with core.autocrlf=true
+# would otherwise commit CRLF into the Dockerfile's `RUN` continuations and the yarn shim it
+# writes.
+tools/e2e/** text eol=lf
+
+# Git already detects these as binary; declaring it means no future filter or `text=auto` change
+# can start mangling the screenshot baselines, which are compared byte-for-byte at threshold: 0.
+*.png binary
diff --git a/.github/workflows/e2e-approve-snapshots.yml b/.github/workflows/e2e-approve-snapshots.yml
index 1921d5e9ac..8bc3ff85ed 100644
--- a/.github/workflows/e2e-approve-snapshots.yml
+++ b/.github/workflows/e2e-approve-snapshots.yml
@@ -17,7 +17,9 @@ jobs:
   approve_snapshots:
     if: ${{ github.event.issue.pull_request && contains(github.event.comment.body, '/approve-snapshots') && contains(fromJSON('["OWNER", "MEMBER"]'), github.event.comment.author_association) }}
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    # Same as e2e.yml: the container is rebuilt from scratch on every run, so the old 30-minute
+    # budget no longer covers a cold start.
+    timeout-minutes: 60
     steps:
       - uses: xt0rted/pull-request-comment-branch@e8b8daa837e8ea7331c0003c9c316a64c6d8b0b1 # v3.0.0
         id: comment-branch
@@ -27,11 +29,21 @@ jobs:
       - uses: thollander/actions-comment-pull-request@24bffb9b452ba05a4f3f77933840a6a841d1b32b # v3.0.1
         with:
           message: 🔄 [Updating](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}) snapshots.
-      - uses: ./.github/workflows/actions/setup-node
-      - run: yarn run e2e:setup
+      # Regenerated in the same container that e2e.yml compares against. Doing it on the bare
+      # runner instead would mean the baselines are written by one renderer and checked by another,
+      # and this workflow would happily commit screenshots that fail the very next run.
+      #
+      # npm rather than yarn: no setup-node here, so the repository's Yarn 4 release is not on
+      # PATH. The container does its own install. e2e:docker:update-snapshots additionally mounts
+      # packages/components, which is how the rewritten PNGs reach the working tree for the commit
+      # step below — and which already exists from the checkout, unlike the report directories that
+      # tools/e2e/run.js creates.
       - id: update-snapshots
-        run: |
-          yarn run e2e:components --update-snapshots
+        run: npm run e2e:docker:update-snapshots
+        env:
+          # As in e2e.yml: the compose default is tuned for developer machines, the runner wants
+          # its own core count.
+          PLAYWRIGHT_WORKERS: 100%
       - uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
         id: commit-and-push
         with:
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
index ebf77a6485..be68156275 100644
--- a/.github/workflows/e2e.yml
+++ b/.github/workflows/e2e.yml
@@ -7,20 +7,51 @@ on:
   pull_request:
 
 permissions:
-  contents: write
+  contents: read
   pull-requests: write
 
 jobs:
+  # Runs in the container built from tools/e2e/, not on the runner directly. The screenshots are
+  # compared with threshold: 0 against baselines that carry no {platform} suffix, so the thing that
+  # produces them has to be pinned; a bare runner is only pinned by whatever `ubuntu-latest` happens
+  # to mean this week. The same image is what `yarn run e2e:docker` gives a developer locally, which
+  # is the point — a failure here is reproducible off CI.
+  #
+  # Regeneration must go through the same image: see .github/workflows/e2e-approve-snapshots.yml.
   tests:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    # 30 minutes was sized for a job that only downloaded browsers. GitHub-hosted runners keep no
+    # Docker layer cache between runs, so every run now also pulls the base image and rebuilds the
+    # Node, font and `yarn install` layers from scratch.
+    timeout-minutes: 60
+    permissions:
+      contents: read # for actions/checkout to read the repository
+      pull-requests: write # for thollander/actions-comment-pull-request to comment on PRs
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: ./.github/workflows/actions/setup-node
-      - run: yarn run e2e:setup
+      # No setup-node and no browser install: node is already on the runner, tools/e2e/run.js only
+      # reads package.json, and the browsers come baked into the image. That removes the ~174 MB
+      # `playwright install` download this job used to nurse through a timeout — but it is not a
+      # net time saving and should not be read as one, since the image build replaces it.
+      #
+      # What is bought with that is reproducibility, not speed. If the wall clock ever does become
+      # the problem, the answer is a prebuilt image pulled from GHCR by tag — not
+      # `cache-to: type=gha`, which would push well over a gigabyte of layers into the same 10 GB
+      # Actions cache that every other job's yarn cache is competing for.
+      #
+      # npm rather than yarn: without setup-node the repository's Yarn 4 release is never put on
+      # PATH, and the runner's own `yarn` is v1, which cannot read this manifest. Nothing is
+      # installed here either — the container does its own yarn install.
+      #
+      # The bind-mount targets are created by tools/e2e/run.js rather than by a step here, so that a
+      # local run gets the same treatment; see the comment there.
       - id: run-e2e-tests
-        run: |
-          yarn run e2e:components
+        run: npm run e2e:docker
+        env:
+          # Back to the runner's own setting. The compose file caps workers for developer machines,
+          # where a container sees far more cores than one dev server can be driven from; a 4-vCPU
+          # runner has the opposite problem and wants all of them.
+          PLAYWRIGHT_WORKERS: 100%
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: ${{ always() }}
         id: upload-report
diff --git a/.prettierignore b/.prettierignore
index 1076d9739e..b0e523adf1 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -25,3 +25,7 @@ apps/docs/src/app/components/design-tokens-viewers/data/*.ts
 
 # ignore mocks
 **/mock.ts
+
+# ignore Playwright's output — see .eslintignore
+/playwright-report/
+/test-results/
diff --git a/AGENTS.md b/AGENTS.md
index 1680bc6953..3a8eb7355b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -82,8 +82,17 @@ npx jest <TEST_PATH_PATTERN>       # Run specific Jest tests (e.g., npx jest pac
 yarn run e2e:setup                      # Install Playwright browsers (run once)
 yarn run e2e:components                 # Run all E2E tests
 npx playwright test <TEST_PATH_PATTERN> # Run specific E2E tests (e.g., npx playwright test packages/components/button/e2e.playwright-spec.ts)
+
+# Screenshots differ across operating systems — always use Docker for anything visual:
+yarn run e2e:docker                     # Run E2E tests in Docker (matches CI)
+yarn run e2e:docker:update-snapshots    # Run E2E tests in Docker and update the baselines
 ```
 
+The committed baselines under `__screenshots__` are compared with `threshold: 0` and have no
+platform suffix, so a native run outside Linux fails on font rasterization alone. `e2e:components`
+is still useful for the assertion-based specs; use `e2e:docker` whenever screenshots are involved,
+and never regenerate a baseline any other way.
+
 ### Linting
 
 ```bash
diff --git a/docs/guides/06-testing.md b/docs/guides/06-testing.md
index aa059a9083..0bda76f8a7 100644
--- a/docs/guides/06-testing.md
+++ b/docs/guides/06-testing.md
@@ -41,3 +41,63 @@ yarn run e2e:setup
 ```bash
 yarn run e2e:components
 ```
+
+### Visual regression tests and Docker
+
+The screenshot baselines committed under `__screenshots__` are compared with `threshold: 0` and carry
+no platform suffix, so they are tied to one operating system and one browser build. Running the suite
+natively on Windows or macOS compares your machine's font rasterization against Linux bytes and fails
+regardless of whether anything actually changed.
+
+Run anything visual in Docker instead. The image is built from the Playwright release matching
+`@playwright/test` in `package.json`, which is what CI runs too:
+
+```bash
+yarn run e2e:docker
+```
+
+To accept intentional visual changes, regenerate the baselines the same way and commit the result:
+
+```bash
+yarn run e2e:docker:update-snapshots
+```
+
+Arguments are passed through, replacing the container's command — for example, to run one component:
+
+```bash
+yarn run e2e:docker yarn playwright test packages/components/button
+```
+
+The container always runs with `CI=true`, so that Playwright behaves the way it does on the runner.
+Two consequences matter when debugging inside it: `test.only` is rejected outright rather than
+honoured (`forbidOnly`), and a failing test is retried twice before being reported. Narrow a run with
+a path and `-g` instead of `test.only`:
+
+```bash
+yarn run e2e:docker yarn playwright test packages/components/select -g "single select"
+```
+
+Requires Docker with Compose v2. On Windows carrying Docker Engine inside WSL rather than Docker
+Desktop, `docker.exe` is often missing from the Windows PATH altogether — the Linux binary cannot be
+projected onto it — but the wrapper also falls back to WSL when a `docker.exe` is present yet broken
+(no Compose v2 plugin, a stale install). Either way it forwards the run through `wsl.exe` and
+translates the paths it passes, so the commands above work unchanged from PowerShell. It looks for
+Docker inside WSL's default distribution; set `WSL_DISTRIBUTION` to a distribution name if Docker
+lives elsewhere. That check only confirms the CLI and Compose v2 plugin are present, not that the
+daemon itself is reachable — a stopped daemon, or a WSL user outside the `docker` group, still
+surfaces later, when the actual `docker compose run` fails.
+
+### Worker count
+
+A container reports every core on the host, and Playwright sizes its worker pool from that. Since all
+workers drive one shared Angular dev server, the useful ceiling comes from that server rather than
+from the core count — on a 32-core machine `workers: '100%'` means 64 browsers, and the suite
+collapses into timeouts that look like failures but are not. The compose file therefore caps workers
+at 8. Override it when a machine wants something different:
+
+```bash
+PLAYWRIGHT_WORKERS=16 yarn run e2e:docker
+```
+
+Baselines can also be regenerated without a local Docker install by commenting `/approve-snapshots`
+on a pull request.
diff --git a/package.json b/package.json
index 580f89dfb2..d8a76351d7 100644
--- a/package.json
+++ b/package.json
@@ -70,7 +70,7 @@
         "@messageformat/core": "^3.4.0",
         "@microsoft/api-extractor": "7.56.0",
         "@octokit/rest": "^18.9.1",
-        "@playwright/test": "^1.55.0",
+        "@playwright/test": "1.55.0",
         "@prettier/plugin-xml": "^3.4.2",
         "@rollup/plugin-commonjs": "^24.0.0",
         "@rollup/plugin-json": "^6.0.0",
@@ -284,6 +284,8 @@
         "dev:e2e": "ng serve dev-e2e",
         "e2e:setup": "playwright install chromium --with-deps && playwright install webkit --with-deps",
         "e2e:components": "playwright test",
+        "e2e:docker": "node tools/e2e/run.js",
+        "e2e:docker:update-snapshots": "node tools/e2e/run.js yarn run e2e:components --update-snapshots",
         "-----API-----": "--------------------------------------------------------------------------------------------",
         "approve-api": "ts-node --project tools/api-extractor/tsconfig.json tools/api-extractor/api-extractor.ts",
         "check-api": "yarn run approve-api onlyCheck",
diff --git a/packages/components/code-block/e2e.playwright-spec.ts b/packages/components/code-block/e2e.playwright-spec.ts
index a9d1875f51..e7432dce69 100644
--- a/packages/components/code-block/e2e.playwright-spec.ts
+++ b/packages/components/code-block/e2e.playwright-spec.ts
@@ -4,9 +4,41 @@ import { e2eEnableDarkTheme } from 'packages/e2e/utils';
 test.describe('KbqCodeBlockModule', () => {
     test.describe('E2eCodeBlockStates', () => {
         const getComponent = (page: Page) => page.getByTestId('e2eCodeBlockStates');
+        const codeBlock = 'code.kbq-code-block__code';
+
+        /**
+         * Highlighting lands after the initial render: KbqCodeBlockHighlight reaches highlight.js through
+         * a dynamic import, then rewrites each block's innerHTML and stamps `data-language` on the element
+         * as it finishes. Nothing the component renders blocks on that, so a screenshot taken straight
+         * after navigation can catch the page part-highlighted — some blocks already carrying their
+         * line-number table, others still plain text.
+         *
+         * Left to toHaveScreenshot's own retries this does not fail informatively. The half-applied state
+         * changes the element's height rather than a few pixels, so it surfaces as `Expected an image
+         * 1556px by 3540px, received 1556px by 3232px` — which reads like a layout regression, not a race.
+         * It also only appears under load: eight workers against one dev server reproduced it here, four
+         * did not.
+         *
+         * The first assertion is the guard. Without it the second passes trivially against a page that has
+         * not rendered any code blocks yet.
+         */
+        const waitForHighlighting = async (page: Page) => {
+            await expect(page.locator(codeBlock).first()).toBeAttached();
+            await expect(page.locator(`${codeBlock}:not([data-language])`)).toHaveCount(0);
+        };
 
         test('states', async ({ page }) => {
+            /**
+             * This is the heaviest page in the suite: fifteen code blocks, each highlighted and rebuilt
+             * into a line-numbered table, then captured twice at roughly 1556x3540. The 15s default in
+             * playwright.config.ts is sized for pages a fraction of that, and once several workers share
+             * one dev server this test lands between 9s and 17s — so it does not fail on a wrong render
+             * but on the budget, with no screenshot taken at all to explain why. Tripling it via slow()
+             * costs nothing when the test passes and leaves the assertions untouched.
+             */
+            test.slow();
             await page.goto('/E2eCodeBlockStates');
+            await waitForHighlighting(page);
             await expect(getComponent(page)).toHaveScreenshot('01-light.png');
             await e2eEnableDarkTheme(page);
             await expect(getComponent(page)).toHaveScreenshot('01-dark.png');
diff --git a/packages/components/icon/__screenshots__/02-light.png b/packages/components/icon/__screenshots__/02-light.png
index d9cb8a353d..7e54ce9588 100644
Binary files a/packages/components/icon/__screenshots__/02-light.png and b/packages/components/icon/__screenshots__/02-light.png differ
diff --git a/packages/components/icon/e2e.playwright-spec.ts b/packages/components/icon/e2e.playwright-spec.ts
index 579873b752..e53ec42e65 100644
--- a/packages/components/icon/e2e.playwright-spec.ts
+++ b/packages/components/icon/e2e.playwright-spec.ts
@@ -20,9 +20,30 @@ test.describe('KbqIconModule', () => {
     test.describe('E2eIconSvg', () => {
         const getComponent = (page: Page) => page.getByTestId('e2eIconSvg');
 
-        test('svg icons - dropdown open', async ({ page }) => {
+        /**
+         * Every icon on this page arrives over HTTP: E2eIconSvg registers a resolver mapping each name
+         * onto /assets/SVGIcons/<name>.svg, and KbqIcon injects the response into its host element once
+         * it lands. Until then the host is empty and occupies no space, so the text around it sits where
+         * it will not stay — a capture taken too early differs as a whole-page horizontal shift rather
+         * than as one wrong-looking icon, which is misleading enough to be worth ruling out here.
+         *
+         * Safe to require of every icon because every icon on this page resolves to inline SVG; none
+         * falls back to the font-class path, so this cannot hang on one that was never going to load.
+         * That is a property of E2eIconSvg's resolver provider, not of KbqIcon — the sibling page above
+         * has no such provider and renders its icons as font classes, so the same wait there would never
+         * be satisfied.
+         *
+         * The first assertion is the guard: without it the second passes trivially against a page that
+         * has not rendered yet.
+         */
+        const waitForIcons = async (page: Page) => {
+            await expect(page.locator('.kbq-icon').first()).toBeAttached();
+            await expect(page.locator('.kbq-icon:not(:has(svg))')).toHaveCount(0);
+        };
+
+        test('svg icons', async ({ page }) => {
             await page.goto('/E2eIconSvg');
-            await page.getByTestId('e2eIconSvgDropdownTrigger').click();
+            await waitForIcons(page);
             await expect(getComponent(page)).toHaveScreenshot('02-light.png');
         });
     });
diff --git a/packages/components/icon/e2e.ts b/packages/components/icon/e2e.ts
index 4d2558ffe8..3945931f88 100644
--- a/packages/components/icon/e2e.ts
+++ b/packages/components/icon/e2e.ts
@@ -2,7 +2,6 @@ import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
 import { FormsModule } from '@angular/forms';
 import { KbqButtonModule } from '@koobiq/components/button';
 import { KbqComponentColors } from '@koobiq/components/core';
-import { KbqDropdownModule } from '@koobiq/components/dropdown';
 import { KbqFileUploadModule } from '@koobiq/components/file-upload';
 import { KbqFormFieldModule, PasswordRules } from '@koobiq/components/form-field';
 import {
@@ -170,7 +169,6 @@ export class E2eIconStateAndStyle {
         KbqTagsModule,
         KbqButtonModule,
         KbqSplitButtonModule,
-        KbqDropdownModule,
         KbqFileUploadModule,
         KbqLinkModule,
         KbqFormFieldModule,
@@ -351,20 +349,6 @@ export class E2eIconStateAndStyle {
                         <kbq-cleaner />
                     </kbq-form-field>
                 </div>
-
-                <div>
-                    <button kbq-button data-testid="e2eIconSvgDropdownTrigger" [kbqDropdownTriggerFor]="dropdown">
-                        Dropdown
-                        <i kbq-icon="kbq-chevron-down-s_16"></i>
-                    </button>
-
-                    <kbq-dropdown #dropdown="kbqDropdown">
-                        <button kbq-dropdown-item>
-                            <i kbq-icon="kbq-circle-check_16"></i>
-                            Item with icon
-                        </button>
-                    </kbq-dropdown>
-                </div>
             </div>
         </div>
     `,
diff --git a/packages/e2e/README.md b/packages/e2e/README.md
index baefd4ef1d..9cd102751c 100644
--- a/packages/e2e/README.md
+++ b/packages/e2e/README.md
@@ -25,3 +25,24 @@ yarn run e2e:components
 # Run a specific E2E test file
 yarn playwright test packages/components/button/e2e.playwright-spec.ts
 ```
+
+## Screenshots
+
+The baselines under each component's `__screenshots__` directory are compared with `threshold: 0` and
+have no platform suffix, so they belong to one operating system and one browser build. The commands
+above only compare them meaningfully on Linux; anywhere else they fail on font rasterization alone.
+
+Run anything visual in Docker, which uses the Playwright image matching `@playwright/test` and is what
+CI runs as well:
+
+```bash
+# Run the suite in Docker
+yarn run e2e:docker
+
+# Accept intentional visual changes and rewrite the baselines
+yarn run e2e:docker:update-snapshots
+```
+
+Requires Docker with Compose v2 — see [Testing → Visual regression tests and Docker](../../docs/guides/06-testing.md#visual-regression-tests-and-docker)
+for what the wrapper does on Windows when Docker only runs inside WSL. Without a local Docker
+install, comment `/approve-snapshots` on a pull request to regenerate the baselines in CI.
diff --git a/playwright.config.ts b/playwright.config.ts
index d49b88feb0..ff74b930be 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -8,6 +8,49 @@ const viewport: ViewportSize = {
 const baseURL = process.env.BASE_URL || 'http://localhost:4200';
 const webServerCommand = process.env.WEB_SERVER_COMMAND || 'yarn run dev:e2e --configuration=production';
 
+/**
+ * Every worker drives its own browser against one shared Angular dev server, so the useful ceiling
+ * comes from that server rather than from the core count. '100%' suits a 4-vCPU CI runner, but not
+ * Docker: a container reports every core on the host (Playwright reads `os.cpus()`, which no cgroup
+ * or cpuset limit affects), so on a 32-core machine it means 64 browsers and the suite collapses
+ * into timeouts. tools/e2e's compose file caps it via PLAYWRIGHT_WORKERS and CI sets it back.
+ *
+ * Playwright only accepts a string when it is a percentage, so anything else has to become a number.
+ * With the variable unset this behaves exactly as it did before.
+ *
+ * The value is validated rather than passed through, because Playwright's own guard only rejects
+ * `workers <= 0` — and `NaN <= 0` is false. A typo like `PLAYWRIGHT_WORKERS=amx` would therefore
+ * reach the dispatcher's `for (i = 0; i < workers; i++)` loop, spawn zero workers, run zero tests,
+ * write no report, and still exit 0: a green suite that tested nothing.
+ */
+const resolveWorkers = () => {
+    const override = process.env.PLAYWRIGHT_WORKERS?.trim();
+
+    if (!override) {
+        return isCI ? '100%' : undefined;
+    }
+
+    if (override.endsWith('%')) {
+        const percentage = Number(override.slice(0, -1));
+
+        if (!Number.isFinite(percentage) || percentage <= 0) {
+            throw new Error(`PLAYWRIGHT_WORKERS must be a positive percentage, got ${JSON.stringify(override)}.`);
+        }
+
+        return override;
+    }
+
+    const workers = Number(override);
+
+    if (!Number.isInteger(workers) || workers <= 0) {
+        throw new Error(
+            `PLAYWRIGHT_WORKERS must be a positive integer or a percentage, got ${JSON.stringify(override)}.`
+        );
+    }
+
+    return workers;
+};
+
 /** @see https://playwright.dev/docs/test-configuration */
 export default defineConfig({
     testDir: __dirname,
@@ -17,7 +60,7 @@ export default defineConfig({
     fullyParallel: true,
     forbidOnly: isCI,
     retries: isCI ? 2 : 0,
-    workers: isCI ? '100%' : undefined,
+    workers: resolveWorkers(),
     reporter: [
         ['list', { printSteps: true }],
         ['html', { open: 'never' }]
@@ -32,6 +75,11 @@ export default defineConfig({
         }
     ],
     expect: {
+        // These baselines are compared with threshold: 0, so they are tied to one exact browser
+        // build. @playwright/test is pinned to an exact version in package.json for that reason:
+        // even a patch release can bump the bundled Chromium — 1.55.0 shipped build 1187 and
+        // 1.55.1 shipped 1193 — and that invalidates every screenshot. Upgrade it on its own
+        // branch and refresh the baselines with /approve-snapshots in the same pull request.
         toHaveScreenshot: {
             pathTemplate: '{testFileDir}/__screenshots__/{arg}{ext}',
             threshold: 0,
diff --git a/tools/e2e/Dockerfile b/tools/e2e/Dockerfile
new file mode 100644
index 0000000000..4de1365cb1
--- /dev/null
+++ b/tools/e2e/Dockerfile
@@ -0,0 +1,134 @@
+# syntax=docker/dockerfile:1.7
+#
+# Runs the Playwright component suite in the same browser, operating system and font stack as CI,
+# so that `expect.toHaveScreenshot` produces identical pixels on any developer machine.
+#
+# Build it through `yarn run e2e:docker` (tools/e2e/run.js), which derives PLAYWRIGHT_VERSION from
+# package.json so the image tag cannot drift from the installed @playwright/test.
+ARG PLAYWRIGHT_VERSION
+
+# Digest-pinned deliberately. The suite compares with `threshold: 0`, which makes the base image
+# part of the compiler: were Microsoft to re-push this tag over a newer apt snapshot, every
+# committed screenshot would change with no commit to blame it on.
+#
+# Once a digest is present Docker resolves it and ignores the tag, so the tag is documentation and
+# the browser-revision assertion below is what actually keeps the two honest. When bumping
+# @playwright/test, bump this digest in the same pull request and regenerate the baselines there:
+#
+#   docker buildx imagetools inspect mcr.microsoft.com/playwright:v<version>-noble --format '{{.Manifest.Digest}}'
+#
+# noble is Ubuntu 24.04, matching the `ubuntu-latest` runner the current baselines came from.
+FROM mcr.microsoft.com/playwright:v${PLAYWRIGHT_VERSION}-noble@sha256:b27e719ecbfef153e13fd24e8341736733bf2658b229677eb21ff57ff5d7fb29
+
+WORKDIR /app
+
+# CI=true selects the same Playwright behavior as the runner: retries: 2, forbidOnly, and
+# reuseExistingServer: false. It would also mean workers: '100%', which is wrong in a container —
+# see the PLAYWRIGHT_WORKERS note in tools/e2e/docker-compose.yml.
+#
+# forbidOnly is the one that surprises people: `test.only` is rejected here rather than honoured, so
+# a run is narrowed with a path and `-g`. Parity is worth more than the convenience — the whole
+# point of this image is that a local run and the runner cannot disagree — but it is documented in
+# docs/guides/06-testing.md rather than left to be discovered.
+#
+# TZ is belt-and-braces rather than a fix: the base image currently resolves to Etc/UTC, matching
+# the runner, even though it is built with `ARG TZ=America/Los_Angeles`. Since it is the build
+# argument and not the image that says otherwise, that agreement is incidental — and
+# playwright.config.ts pins neither `locale` nor `timezoneId`, so the datepicker, timepicker and
+# timezone screenshots would silently follow the base image if it ever changed. Stating it costs
+# nothing. LANG and LC_ALL are already C.UTF-8 in the base image.
+#
+# HUSKY=0 because `prepare: husky` runs during `yarn install` and there is no .git in the context.
+ENV CI=true \
+    TZ=UTC \
+    HUSKY=0 \
+    YARN_ENABLE_TELEMETRY=0
+
+# Body text is bundled woff2 (@fontsource/inter, @fontsource/jetbrains-mono), so system fonts only
+# matter for glyphs Inter lacks. The baselines were rendered on ubuntu-latest, which ships DejaVu;
+# this base image does not, and falls through to IPAGothic instead. Matching the runner's fallback
+# face is the whole premise of this image, so it is installed here rather than left to chance.
+#
+# Unlike on main, no source on this branch currently renders a glyph that exercises it: the macOS
+# modifier symbols ⌘ (U+2318) and ⌥ (U+2325) reach the select and tree-select captions through the
+# "select all" master checkbox (#DS-3969), which 19.x does not have. That makes this layer cheap
+# insurance rather than a fix for a failure you can reproduce today — keep it anyway, because the
+# first backport that does introduce such a glyph would otherwise fail with no visible cause, and
+# because a container whose font set differs from the runner's is not the reproduction it claims
+# to be.
+#
+# The two fc-match calls are the assertion, not a demonstration: they are what stops this layer
+# from being "cleaned up" later on the reasonable-sounding grounds that the fonts are bundled.
+# U+2318 and U+2325 are still the right probes — they are the codepoints known to fall through.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends fonts-dejavu-core \
+    && rm -rf /var/lib/apt/lists/* \
+    && fc-cache -f \
+    && for codepoint in 2318 2325; do \
+        fc-match ":charset=$codepoint" family | grep -q '^DejaVu Sans$' \
+            || { echo "U+$codepoint falls back to '$(fc-match ":charset=$codepoint" family)', expected DejaVu Sans." >&2; exit 1; }; \
+    done
+
+# The base image ships Node 22 from NodeSource. Every other CI job runs the .nvmrc version, so
+# install that rather than accept a second Node major for this one job. Its own layer, ahead of the
+# manifests, so that editing package.json does not reinstall Node.
+# `n` keeps every version it fetches under /usr/local/n, which is 202 MB of no use once the binary
+# is in place. Dropped in the same layer, so the bytes are never committed in the first place.
+#
+# `n` is version-pinned because an unpinned global install is a hole in an otherwise reproducible
+# image: the base image is digest-pinned and Node comes from .nvmrc, but `npm install --global n`
+# would resolve to whatever is latest on the day the layer is built. Nothing here reads it after
+# the Node binary is in place, so bumping it is routine — it does not move the Node version.
+COPY .nvmrc ./
+RUN set -eux; \
+    node_version="$(tr -d '\r\n' < .nvmrc)"; \
+    npm install --global n@10.2.0; \
+    n "$node_version"; \
+    npm remove --global n; \
+    rm -rf /usr/local/n; \
+    npm cache clean --force; \
+    test "v$node_version" = "$(node --version)"; \
+    node --version
+
+COPY .yarnrc.yml package.json yarn.lock ./
+COPY .yarn/releases/ .yarn/releases/
+
+# The base image has Yarn 1 classic on PATH from its own `npm install -g yarn`. It cannot read a
+# Berry lockfile, and playwright.config.ts's webServer command (`yarn run dev:e2e ...`) shells out
+# to whatever `yarn` resolves to at test time — so replacing it is required, not a convenience.
+#
+# A shell script rather than a symlink: the executable bit on the committed .cjs is not guaranteed
+# to survive a COPY from a Windows build context. The path is read out of .yarnrc.yml, so this
+# cannot drift from `yarnPath`.
+RUN set -eux; \
+    yarn_path="$(sed -n 's/^yarnPath: *//p' .yarnrc.yml | tr -d '\r')"; \
+    test -f "/app/$yarn_path"; \
+    printf '#!/bin/sh\nexec node "/app/%s" "$@"\n' "$yarn_path" > /usr/local/bin/yarn; \
+    chmod +x /usr/local/bin/yarn; \
+    test "4" = "$(yarn --version | cut -d . -f 1)"; \
+    yarn --version
+
+# package.json's postinstall compiles these into node_modules/@koobiq/builders.
+COPY tools/builders/ tools/builders/
+COPY tools/e2e/assert-browsers.js tools/e2e/
+
+# The cache is cleaned in the same layer rather than a later one: node_modules is already
+# materialised by then (nodeLinker: node-modules), and Yarn's global cache is another 640 MB that
+# would otherwise be committed and then paid for again on every image export and pull.
+RUN yarn install --immutable && yarn cache clean --all
+
+# Fails the build if the image's browsers are not the ones this @playwright/test expects, which is
+# otherwise silent and surfaces much later as an unexplained diff in every screenshot.
+RUN node tools/e2e/assert-browsers.js
+
+COPY . .
+
+# tools/e2e/Dockerfile.dockerignore is an allowlist, and the failure mode of not reading it at all —
+# a builder that is not BuildKit, a rename that leaves the two names out of step — is that the whole
+# working tree lands in the image and everything still works, only slower and off a context nobody
+# reviewed. CHANGELOG.md is the sentinel because no e2e run will ever have a reason to want it, so
+# unlike a directory that might be allowlisted later this cannot quietly become a no-op.
+RUN test ! -e CHANGELOG.md \
+    || { echo 'tools/e2e/Dockerfile.dockerignore was not applied: the whole working tree is in the image.' >&2; exit 1; }
+
+CMD ["yarn", "run", "e2e:components"]
diff --git a/tools/e2e/Dockerfile.dockerignore b/tools/e2e/Dockerfile.dockerignore
new file mode 100644
index 0000000000..cd82fa6220
--- /dev/null
+++ b/tools/e2e/Dockerfile.dockerignore
@@ -0,0 +1,78 @@
+# Build context for tools/e2e/Dockerfile, whose context is the repository root.
+#
+# Named after the Dockerfile rather than being a plain `.dockerignore` at the context root so that it
+# can live next to the thing it belongs to. BuildKit looks for `<dockerfile>.dockerignore` first and
+# only falls back to `<context>/.dockerignore`; Compose v2 always builds through BuildKit, so this is
+# the file that is read. A plain `.dockerignore` dropped into tools/e2e/ would be read by nothing.
+#
+# An allowlist: everything is excluded, then the paths the image actually needs are added back. That
+# is narrower than a denylist but it fails silently — a missing entry surfaces deep inside
+# `ng serve` or `yarn install`, pointing nowhere near the cause. Two things keep it honest: the
+# assertion in the Dockerfile that fires if this file is not applied at all, and the fact that the
+# list below is short enough to check against the imports it exists for.
+#
+# Verify with:
+#   docker build --progress=plain --no-cache -f tools/e2e/Dockerfile \
+#     --build-arg PLAYWRIGHT_VERSION=<version> . 2>&1 | grep "transferring context"
+# Expect roughly 28 MB. Substantially more means one of the patterns below stopped matching.
+
+**
+
+# Yarn 4 and the manifests. .yarn/releases holds the committed Yarn binary that .yarnrc.yml points
+# at; without it the image has only the base image's Yarn 1, which cannot read a Berry lockfile.
+!.nvmrc
+!.yarnrc.yml
+!package.json
+!yarn.lock
+!.yarn/releases/
+!.yarn/releases/**
+
+# Workspace and TypeScript configuration: the dev server builds `dev-e2e` out of angular.json, and
+# playwright.config.ts compiles the specs against tsconfig.playwright-spec.json.
+!angular.json
+!tsconfig.json
+!tsconfig.playwright-spec.json
+!playwright.config.ts
+
+# The library under test, the harness application that renders it, and the Luxon adapter — the e2e
+# pages of datepicker, timepicker, filter-bar and notification-center import
+# `@koobiq/angular-luxon-adapter/adapter`, so the suite does not start without it.
+#
+# The specs themselves import only `@playwright/test` and `packages/e2e/utils`, and the e2e pages
+# import only `@koobiq/components/*` and that one adapter.
+!packages/components/
+!packages/components/**
+!packages/e2e/
+!packages/e2e/**
+!packages/angular-luxon-adapter/
+!packages/angular-luxon-adapter/**
+
+# Pulled in transitively rather than by the e2e pages: 73 files under packages/components import
+# `@koobiq/cdk/a11y`, `@koobiq/cdk/keycodes` or `@koobiq/cdk/testing`, which tsconfig.json maps to
+# packages/cdk/*/index.ts. Leaving it out does not fail the build — `ng serve dev-e2e` starts, fails
+# to resolve them, and the run dies at the 10-minute webServer timeout with nothing pointing here.
+# It is 62 KB. No equivalent entry exists on main, where the CDK was folded into
+# packages/components/core, so do not drop this line while reconciling the two branches.
+!packages/cdk/
+!packages/cdk/**
+
+# The one file the harness borrows from the dev applications: packages/e2e/module.ts puts
+# DevThemeToggle in the root component's imports. Listed as a single file rather than the directory
+# because the rest of packages/components-dev is ~2 MB of dev apps this image has no use for.
+# Without it `ng serve dev-e2e` fails with NG1010 on packages/e2e/module.ts:9 and the run dies at the
+# 10-minute webServer timeout.
+!packages/components-dev/
+!packages/components-dev/theme-toggle.ts
+
+# package.json's postinstall compiles tools/builders into node_modules/@koobiq/builders, which the
+# `dev-e2e` build then needs; tools/e2e carries assert-browsers.js, which runs during the build.
+!tools/builders/
+!tools/builders/**
+!tools/e2e/
+!tools/e2e/**
+
+# Last match wins, so these come after the rules above and take back anything that slipped through
+# them — a stray package-level node_modules, build output, or a log.
+**/node_modules
+**/dist
+**/*.log
diff --git a/tools/e2e/assert-browsers.js b/tools/e2e/assert-browsers.js
new file mode 100644
index 0000000000..92b8d0dcf9
--- /dev/null
+++ b/tools/e2e/assert-browsers.js
@@ -0,0 +1,73 @@
+/**
+ * Asserts that the browsers baked into the Playwright base image are the ones the installed
+ * playwright-core expects. Run at image build time by tools/e2e/Dockerfile.
+ *
+ * The image ships its browsers under /ms-playwright, so `playwright install` never runs in the
+ * container. That only holds while the image tag matches @playwright/test exactly — which is not
+ * something the Dockerfile can guarantee on its own. `FROM` carries both a tag derived from
+ * package.json and a digest, and a digest wins: bumping @playwright/test without bumping the digest
+ * in the same commit changes the tag, resolves the same old image, and leaves the browsers behind.
+ *
+ * When the two disagree, nothing fails loudly: `playwright`'s postinstall quietly downloads a
+ * second browser set, the tests run against a different build than CI, and the result is an
+ * unexplained diff in every screenshot — the baselines are compared with `threshold: 0`, so a
+ * different browser build invalidates all of them at once.
+ *
+ * This check turns all of that into one build failure with an actionable message.
+ */
+
+const { existsSync, readFileSync } = require('node:fs');
+const { dirname, join } = require('node:path');
+
+// playwright-core does not list browsers.json in its "exports" map, so requiring it by subpath
+// throws ERR_PACKAGE_PATH_NOT_EXPORTED. package.json is exported; resolve that and read the file
+// next to it, which stays correct wherever the package is installed.
+const { browsers } = JSON.parse(
+    readFileSync(join(dirname(require.resolve('playwright-core/package.json')), 'browsers.json'), 'utf8')
+);
+
+// Everything `playwright install` would fetch, rather than a hand-maintained list. Chromium is the
+// obvious one, but it is not the only browser this suite uses: the scrollbar and sidepanel specs
+// select WebKit with `test.use({ browserName: 'webkit' })`, which overrides the project's browser
+// per file and is easy to miss when reading playwright.config.ts alone. Deriving the list means a
+// spec that reaches for Firefox tomorrow is covered without anyone remembering to edit this file.
+//
+// The excluded entries are the ones the image legitimately lacks: tip-of-tree and beta channels,
+// `android`, and `winldd` (Windows-only).
+const required = browsers.filter((browser) => browser.installByDefault);
+const missing = [];
+
+if (required.length === 0) {
+    console.error('No installByDefault browsers in playwright-core/browsers.json — the check cannot be trusted.');
+    process.exit(1);
+}
+
+for (const { name, revision } of required) {
+    // playwright-core stores revisions per browser name; on disk the directories use underscores.
+    const directory = `/ms-playwright/${name.replace(/-/g, '_')}-${revision}`;
+
+    if (existsSync(directory)) {
+        console.log(`ok ${directory}`);
+    } else {
+        missing.push(directory);
+    }
+}
+
+if (missing.length > 0) {
+    console.error(
+        [
+            'The base image does not ship the browsers this @playwright/test expects.',
+            `Missing: ${missing.join(', ')}`,
+            '',
+            'The pinned digest in tools/e2e/Dockerfile is stale relative to the @playwright/test',
+            'version in package.json. Refresh it with:',
+            '',
+            '  docker buildx imagetools inspect mcr.microsoft.com/playwright:v<version>-noble \\',
+            "    --format '{{.Manifest.Digest}}'",
+            '',
+            'and regenerate the screenshot baselines in the same pull request.'
+        ].join('\n')
+    );
+
+    process.exit(1);
+}
diff --git a/tools/e2e/docker-compose.update.yml b/tools/e2e/docker-compose.update.yml
new file mode 100644
index 0000000000..b5c7d52f4e
--- /dev/null
+++ b/tools/e2e/docker-compose.update.yml
@@ -0,0 +1,27 @@
+# Overlay applied only by `yarn run e2e:docker:update-snapshots` — see tools/e2e/run.js, which
+# adds this file when it sees --update-snapshots in the arguments.
+#
+# Every one of the __screenshots__ directories lives under packages/components, so a single mount
+# is enough for Playwright's --update-snapshots to write the new baselines back to the working
+# tree.
+#
+# Kept out of the base file on purpose. Two reasons, in order of weight: a plain test run has no
+# business being able to write into the working tree at all, and the mount puts the component
+# library on the Angular build's hot path, which costs about 5 seconds per run across the host
+# filesystem boundary (measured: 27s against 32s for the same spec). Updating snapshots is rare and
+# can afford both; a plain run should pay for neither.
+#
+# This is an overlay, not a second configuration: `--file base --file this` merges the two, so
+# everything the base file sets and this one does not — `platform` above all, which is what ties the
+# baselines to x86-64 — carries over unchanged. Confirm with
+# `docker compose --file tools/e2e/docker-compose.yml --file tools/e2e/docker-compose.update.yml config`,
+# which prints what the run actually uses.
+services:
+  e2e:
+    # The report mounts are repeated from the base file on purpose. Compose has merged sequences
+    # by mount target in some versions and replaced them wholesale in others; spelling all three
+    # out is correct either way, and a repeated identical target is a no-op when they are merged.
+    volumes:
+      - ../../packages/components:/app/packages/components
+      - ../../playwright-report:/app/playwright-report
+      - ../../test-results:/app/test-results
diff --git a/tools/e2e/docker-compose.yml b/tools/e2e/docker-compose.yml
new file mode 100644
index 0000000000..d5468e6a50
--- /dev/null
+++ b/tools/e2e/docker-compose.yml
@@ -0,0 +1,54 @@
+# Runs the Playwright component suite in the image built from tools/e2e/Dockerfile.
+#
+# Invoke it through `yarn run e2e:docker` (tools/e2e/run.js), which supplies PLAYWRIGHT_VERSION
+# from package.json and checks it is an exact version. Running `docker compose` against this file
+# directly leaves that build argument empty, so the tag half of the image reference becomes
+# `v-noble`; the pinned digest still resolves the correct image, but the tag no longer records
+# which @playwright/test the browsers belong to, and nothing then verifies the two agree.
+
+# Named explicitly because Compose otherwise derives the project name from this file's directory,
+# which is just `e2e` — shared with every other repository that puts its compose file in tools/e2e,
+# and enough for two projects to start reusing each other's containers and networks.
+name: koobiq-e2e
+
+services:
+  e2e:
+    # The committed baselines are x86-64. Pinning the platform stops an arm64 machine from quietly
+    # producing renders that differ from CI in a way no diff explains; on Apple Silicon that means
+    # emulation, which is slow but correct. Override only if you know why.
+    platform: ${E2E_PLATFORM:-linux/amd64}
+    build:
+      context: ../..
+      dockerfile: tools/e2e/Dockerfile
+      args:
+        - PLAYWRIGHT_VERSION
+    # Reaps the Chromium processes that would otherwise pile up under PID 1.
+    init: true
+    # Recommended upstream for Chromium. Note that the usual justification — Docker's 64 MB
+    # /dev/shm — does not apply here: Playwright passes --disable-dev-shm-usage unconditionally, so
+    # Chromium uses /tmp regardless. Kept because upstream still recommends it and it costs nothing.
+    ipc: host
+    environment:
+      # A container resolves `localhost` to both 127.0.0.1 and ::1, and Node >= 17 does not reorder
+      # them. If the Angular dev server binds v4 only and Playwright's readiness probe tries ::1
+      # first, the run dies after the 10-minute webServer timeout with nothing useful in the log.
+      # Both variables are read by playwright.config.ts.
+      BASE_URL: http://127.0.0.1:4200
+      WEB_SERVER_COMMAND: yarn run dev:e2e --configuration=production --host 127.0.0.1
+      # A container reports every core on the host — Playwright reads os.cpus(), which no cgroup or
+      # cpuset limit affects — so playwright.config.ts's '100%' would mean 64 browsers against one
+      # dev server on a 32-core machine, and every test times out. Measured on such a machine: 64
+      # workers gave 255 failures and 802 timeouts, 8 workers gave zero of either. CI overrides this
+      # back to '100%', which on a 4-vCPU runner is 4.
+      #
+      # 8 rather than a higher guess because it is the value that was actually measured clean; the
+      # ceiling is the single dev server, not the core count, so raising it buys little.
+      PLAYWRIGHT_WORKERS: ${PLAYWRIGHT_WORKERS:-8}
+    # Outputs only — the source tree comes from the image, deliberately, so a plain run cannot write
+    # anywhere near the working tree. Mounting the sources as well costs about 5 seconds per run
+    # (measured: 27s against 32s for the same spec), because `ng serve dev-e2e` compiles the whole
+    # component library and those ~3200 files then cross the host filesystem boundary. Writing
+    # updated baselines back is docker-compose.update.yml's job instead.
+    volumes:
+      - ../../playwright-report:/app/playwright-report
+      - ../../test-results:/app/test-results
diff --git a/tools/e2e/run.js b/tools/e2e/run.js
new file mode 100644
index 0000000000..3b37cdfc92
--- /dev/null
+++ b/tools/e2e/run.js
@@ -0,0 +1,227 @@
+/**
+ * Runs the Playwright component suite inside Docker, so that screenshots are produced by the same
+ * browser, operating system and font stack as CI.
+ *
+ * Screenshots are compared with `threshold: 0` and the baselines carry no `{platform}` suffix, so a
+ * native run on Windows or macOS compares its own rasterization against Linux bytes and fails on
+ * font rendering alone. This wrapper is the supported way to run — and the only supported way to
+ * update — the committed baselines.
+ *
+ * The image tag comes from package.json rather than being hardcoded: the browsers baked into the
+ * image have to match the installed @playwright/test exactly, and a tag that has drifted from the
+ * manifest is indistinguishable from a genuine visual regression.
+ *
+ *   node tools/e2e/run.js                  # run the suite (the image's CMD)
+ *   node tools/e2e/run.js <command...>     # replace the image's CMD
+ *
+ * Anything after the script name replaces the container's command rather than being appended to
+ * it — that is how `docker compose run` behaves — which is why the update-snapshots script passes
+ * the whole command and not just the flag.
+ */
+
+const { spawnSync } = require('node:child_process');
+const { existsSync, mkdirSync } = require('node:fs');
+const { basename, join } = require('node:path');
+const { devDependencies } = require('../../package.json');
+
+const TIME_LABEL = 'Runtime';
+const REPOSITORY_ROOT = join(__dirname, '../..');
+const COMPOSE_FILE = join(__dirname, 'docker-compose.yml');
+const COMPOSE_UPDATE_FILE = join(__dirname, 'docker-compose.update.yml');
+
+// The two directories docker-compose.yml bind-mounts out of the container for their reports.
+const OUTPUT_DIRECTORIES = ['playwright-report', 'test-results'];
+
+const fail = (message) => {
+    console.error(message);
+    process.exit(1);
+};
+
+// Read straight from the manifest rather than from node_modules: CI runs this without an install
+// step, so the packages are not on disk.
+const version = devDependencies['@playwright/test'];
+
+// The tag has to be exact. A range would either not resolve to a tag at all or, worse, resolve to
+// an image whose browsers differ from the ones the lockfile installs.
+if (!/^\d+\.\d+\.\d+$/.test(version)) {
+    fail(
+        `Expected devDependencies["@playwright/test"] in package.json to be an exact version, got ${JSON.stringify(version)}.`
+    );
+}
+
+// How `docker` is reached. Normally the CLI is on PATH and this is all there is to it; the win32
+// branch below can replace it with a hop through WSL.
+let docker = { command: 'docker', prefix: [] };
+let isForwardedToWsl = false;
+
+// `wsl.exe -e` alone always targets whichever distribution is current default, and there is no way
+// to detect the right one automatically when Docker lives in a different one.
+const wslDistro = process.env.WSL_DISTRIBUTION;
+const wslArgs = (exe) => [...(wslDistro ? ['-d', wslDistro] : []), '-e', exe];
+
+// encoding rather than stdio: 'ignore' so a failure can be explained with the command's own stderr
+// instead of a guess. Neither probe prints anything unless something goes wrong: spawnSync only
+// pipes, it does not inherit.
+const probeCompose = (runner) =>
+    spawnSync(runner.command, [...runner.prefix, 'compose', 'version'], { encoding: 'utf8' });
+
+const describeFailure = (result) =>
+    result.error ? result.error.message : (result.stderr || '').trim() || `exited with status ${result.status}`;
+
+// Both prerequisites are checked up front, because neither fails in a way that explains itself.
+// A missing `docker` surfaces as a bare ENOENT from spawn; a Docker CLI without the v2 compose
+// plugin — a machine carrying only the legacy `docker-compose` binary — spawns fine and exits
+// non-zero, which is indistinguishable from a genuine test failure further down.
+let compose = probeCompose(docker);
+
+// On Windows, retry through WSL whenever the direct probe did not cleanly succeed — not only on
+// ENOENT. `docker.exe` can also be present but broken (a stale Docker Desktop install, a CLI
+// without the compose v2 plugin), and that deserves the same chance to fall through to a working
+// WSL-hosted Engine as a missing binary does.
+//
+// There is no docker.exe for Win32 to find in the WSL-only case — /usr/bin/docker is a Linux ELF
+// binary, and while WSL projects Windows executables into the distribution, nothing does the
+// reverse — so wsl.exe is the only bridge. A `docker.cmd` shim on PATH would not help either: Node
+// does not resolve .bat/.cmd from a non-shell spawn, so the probe above would still ENOENT. Neither
+// would a native Windows CLI talking to the WSL daemon over TCP — it resolves the compose file's
+// relative volumes into Windows paths and hands them to a Linux daemon, which cannot bind-mount
+// `C:\...`. Translating at the wsl.exe boundary (see toDockerPath below) keeps every path
+// Linux-side, where compose expects them.
+if ((compose.error || compose.status !== 0) && process.platform === 'win32') {
+    const viaWsl = { command: 'wsl.exe', prefix: wslArgs('docker') };
+    const probe = probeCompose(viaWsl);
+
+    if (!probe.error && probe.status === 0) {
+        docker = viaWsl;
+        compose = probe;
+        isForwardedToWsl = true;
+    } else {
+        fail(
+            'Could not run `docker compose version`:\n' +
+                `  docker: ${describeFailure(compose)}\n` +
+                `  wsl.exe ${wslArgs('docker').join(' ')}: ${describeFailure(probe)}` +
+                (wslDistro
+                    ? ''
+                    : '\nIf Docker lives in a non-default WSL distribution, set WSL_DISTRIBUTION to its name.')
+        );
+    }
+}
+
+// Not folded into the block above: on Windows a missing `docker` already got a chance via WSL, so
+// by this point it either forwarded successfully or exited with the combined diagnosis. Off
+// Windows there is nothing to fall back to, so a plain ENOENT is reported directly.
+if (process.platform !== 'win32' && compose.error?.code === 'ENOENT') {
+    fail('Could not find `docker` on PATH.');
+}
+
+if (compose.error || compose.status !== 0) {
+    fail(
+        '`docker compose` is unavailable. These scripts need Compose v2, which ships as a Docker\n' +
+            'CLI plugin; the standalone `docker-compose` v1 binary cannot read this configuration.'
+    );
+}
+
+if (isForwardedToWsl) {
+    console.info(
+        `Forwarding through wsl.exe to a Docker Engine inside WSL${wslDistro ? ` (distribution: ${wslDistro})` : ''}.`
+    );
+}
+
+// In forwarded mode every path on the command line is read by a Linux process, so the Win32 paths
+// join() produced have to be translated. wslpath rather than a string replacement, because the mount
+// root is configurable — automount.root in wsl.conf — and need not be /mnt. COMPOSE_FILE and
+// COMPOSE_UPDATE_FILE are both direct children of __dirname (see above), so translating that
+// directory once and joining the statically-known filename covers both without a second wsl.exe
+// round trip.
+let translatedDir;
+
+const toDockerPath = (path) => {
+    if (!isForwardedToWsl) return path;
+
+    if (translatedDir === undefined) {
+        const translated = spawnSync('wsl.exe', [...wslArgs('wslpath'), '-u', __dirname], { encoding: 'utf8' });
+
+        if (translated.error || translated.status !== 0) {
+            fail(`Could not translate ${__dirname} into a WSL path: ${describeFailure(translated)}`);
+        }
+
+        translatedDir = translated.stdout.trim();
+    }
+
+    return `${translatedDir}/${basename(path)}`;
+};
+
+const args = process.argv.slice(2);
+
+// Writing baselines back to the working tree needs the source mounted; a plain run does not, and
+// the mount is slow enough to matter. See tools/e2e/docker-compose.update.yml.
+const isUpdatingSnapshots = args.some(
+    (arg) => arg === '-u' || arg === '--update-snapshots' || arg.startsWith('--update-snapshots=')
+);
+
+console.info(`Playwright version: ${version}`);
+
+if (isUpdatingSnapshots) {
+    console.info('Mounting packages/components so updated baselines land in the working tree.');
+}
+
+const env = { ...process.env, PLAYWRIGHT_VERSION: version };
+
+// docker-compose.yml reads all three, and in forwarded mode it is parsed by a process on the other
+// side of the WSL boundary, which does not inherit the Win32 environment. WSLENV is what carries a
+// variable across; /u marks it as travelling in that direction only. Names of variables that are
+// not set are ignored, and an entry repeated from an existing WSLENV is harmless.
+if (isForwardedToWsl) {
+    const forwarded = ['PLAYWRIGHT_VERSION', 'E2E_PLATFORM', 'PLAYWRIGHT_WORKERS'];
+
+    env.WSLENV = [env.WSLENV, ...forwarded.map((name) => `${name}/u`)].filter(Boolean).join(':');
+}
+
+// Compose creates a missing bind-mount source itself, but the daemon does it — so against a rootful
+// daemon these land in the working tree owned by root, and the developer's next run cannot write into
+// them. It is not self-healing either: the ownership survives until someone with sudo removes the
+// directories, and the failure it eventually produces is a permission error from inside the container,
+// pointing nowhere near the cause. Creating them here, as whoever invoked the script, is the whole fix.
+//
+// This belongs in the wrapper rather than in the CI workflows that used to carry it: every supported
+// entry point goes through this file, so covering it here covers a plain local run too.
+for (const directory of OUTPUT_DIRECTORIES) {
+    mkdirSync(join(REPOSITORY_ROOT, directory), { recursive: true });
+}
+
+console.time(TIME_LABEL);
+
+const result = spawnSync(
+    docker.command,
+    [
+        ...docker.prefix,
+        'compose',
+        '--file',
+        toDockerPath(COMPOSE_FILE),
+        ...(isUpdatingSnapshots ? ['--file', toDockerPath(COMPOSE_UPDATE_FILE)] : []),
+        'run',
+        '--rm',
+        '--build',
+        'e2e',
+        ...args
+    ],
+    {
+        stdio: 'inherit',
+        env
+    }
+);
+
+console.timeEnd(TIME_LABEL);
+
+if (result.error) {
+    fail(`Failed to run \`${docker.command}\`: ${result.error.message}`);
+}
+
+// Only when there is something to open: the run can also fail before any test executes — a build
+// error, or an image that cannot be pulled — and pointing at a report that was never written sends
+// whoever is debugging in the wrong direction.
+if (result.status !== 0 && existsSync(join(REPOSITORY_ROOT, 'playwright-report/index.html'))) {
+    console.info('To view the test report, run: `npx playwright show-report`');
+}
+
+process.exit(result.status ?? 1);
diff --git a/yarn.lock b/yarn.lock
index 48e452abda..131d9457c7 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -6749,7 +6749,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@playwright/test@npm:^1.55.0":
+"@playwright/test@npm:1.55.0":
   version: 1.55.0
   resolution: "@playwright/test@npm:1.55.0"
   dependencies:
@@ -17316,7 +17316,7 @@ __metadata:
     "@messageformat/core": "npm:^3.4.0"
     "@microsoft/api-extractor": "npm:7.56.0"
     "@octokit/rest": "npm:^18.9.1"
-    "@playwright/test": "npm:^1.55.0"
+    "@playwright/test": "npm:1.55.0"
     "@prettier/plugin-xml": "npm:^3.4.2"
     "@rollup/plugin-commonjs": "npm:^24.0.0"
     "@rollup/plugin-json": "npm:^6.0.0"