Prepare browser releases matched to consumer Playwright pins (#41)

A consumer Playwright bump can leave the runner without an accepted
matching browser image. The watcher checks flowbite-xor main hourly,
resolves the selected ref to an immutable commit, validates the exact
manifest/lock pin, and proposes a matching browser release. Manual and
repository-dispatch triggers support coordinating the release before the
consumer bump merges.

Each runtime minor owns its npm lock and parity fixture. COPY inputs,
fingerprints and validation selection isolate line changes. The watcher
captures an accepted application-image digest once and preserves it on
retries, even as the catalog grows. Inventory must match the authored
Playwright version. Candidates retain RGB rendering and committed
screenshot parity.

Includes #39's publication isolation: consumer code executes only on a
fresh job without repository permissions, persisted checkout credentials
or registry login, using controlled Compose configuration and a minimal
environment. Separate finalization accepts evidence only for the exact
public digest, source, image inputs and fixture.

Depends on #39; merge #39 first. The input-layout change allocates
revision 1.0.2 rather than reusing 1.0.1. The current consumer remains
on 1.58.2. Publication/catalog acceptance and review still gate
availability; automatic merge is not enabled.

Validation: all 261 combined tests pass, including cross-line isolation,
retry idempotence, application-pin stability, evidence binding and
publication isolation. Catalog, compilation, shell/YAML and whitespace
checks pass. Updated CI is running. Both existing Codex findings have
fixes and resolved threads; #40 had no findings.

Author: xormania

.github/workflows/browser-refresh.yml

@@ -0,0 +1,37 @@
+name: Match consumer Playwright
+on:
+  schedule:
+    - cron: '37 * * * *'
+  workflow_dispatch:
+    inputs:
+      consumer_ref:
+        description: flowbite-xor branch or commit containing the proposed Playwright bump
+        type: string
+        default: main
+  repository_dispatch:
+    types: [playwright-bump]
+permissions:
+  contents: write
+  pull-requests: write
+concurrency:
+  group: browser-refresh
+  cancel-in-progress: false
+jobs:
+  propose:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    env:
+      GH_TOKEN: ${{ secrets.LIBRARY_BOT_TOKEN || github.token }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.LIBRARY_BOT_TOKEN || github.token }}
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+      - run: python3 -m pip install -r requirements-ci.txt
+      - name: Propose the exact consumer pin
+        env:
+          CONSUMER_REF: ${{ inputs.consumer_ref || github.event.client_payload.consumer_ref || 'main' }}
+        run: python3 scripts/refresh_browser.py --consumer-ref "$CONSUMER_REF" --pr

README.md

@@ -124,6 +124,7 @@ and direct usage pages remains sufficient.
 - [Reusable PHP test tasks and per-process coverage](docs/php-tests.md)
 - [Prepared Serena v2 REPL, shell access and editing](docs/serena.md)
 - [Agent feedback implementation and runner operations](docs/agent-feedback.md)
+- [Browser releases matched to consumer Playwright pins](docs/browser-releases.md)
 - [Isolated Toolkit validation and fresh Symfony applications](docs/php-toolkit.md)
 - [Cloud prerequisites and verification evidence](docs/compatibility.md)
 - [Versions, pins, upgrades, and rollback](docs/versioning.md)

docs/browser-releases.md

@@ -0,0 +1,41 @@
+# Browser releases matched to the consuming lock
+
+The flowbite-xor runner selects an accepted browser image whose measured
+Playwright version equals the application's exact lock. An authored proposal
+does not change availability or existing digest pins.
+
+`Match consumer Playwright` checks flowbite-xor main hourly and opens a PR
+when its exact Playwright pin changes. For a coordinated bump before merging
+the consumer, manually run that workflow with the consumer branch or commit,
+or send its `playwright-bump` repository dispatch with `consumer_ref` in the
+payload. The workflow resolves that ref to an immutable commit and requires
+the manifest and lock to agree. It never upgrades to an unrelated latest version.
+
+Each runtime minor line has its own npm lock, copied and fingerprinted separately.
+Changing one line does not change another line's package inputs. A patch bump
+within a runtime line receives a fresh packaging revision; a new runtime minor
+starts at 1.0.0. The old exact releases and pins remain usable.
+
+Every candidate keeps RGB subpixel rendering, launches Chromium/Firefox/WebKit
+offline, and compares Chromium screenshots with committed baselines at its
+own pinned consumer commit and accepted application-image digest. The watcher
+records that digest when preparing the proposal; later catalog updates do not
+change an existing fixture or retry. Baseline updates and test retries are disabled for
+that parity run. A mismatch stops acceptance and retains the report/diff files.
+
+Merge the passing source PR, then review the normal publication/catalog PR.
+After catalog acceptance, the runner discovers the matching verified digest
+from the consuming Playwright pin; it needs no separate browser-version edit.
+Hourly detection supports preparing a release the same day, but publication
+still depends on successful CI and timely review/merge. `LIBRARY_BOT_TOKEN`
+allows validation of bot-created PRs to start automatically.
+
+To prepare the same proposal locally without pushing:
+
+```sh
+python3 scripts/refresh_browser.py --consumer-ref CONSUMER_COMMIT
+```
+
+New rendering or packaging fixes belong in a normal feature PR with a fresh
+revision. The watcher proposes changed consumer versions, not repeated releases
+for every consumer source commit.

images/playwright-browser/Dockerfile

@@ -3,7 +3,8 @@ ARG BASE_IMAGE
 FROM ${BASE_IMAGE}
 ARG APT_REFRESH
 ENV DEBIAN_FRONTEND=noninteractive PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers HOME=/home/dev
-COPY images/playwright-browser/package*.json /opt/playwright/
+ARG IMAGE_LINE
+COPY images/playwright-browser/lines/${IMAGE_LINE}/package*.json /opt/playwright/
 RUN npm ci --prefix /opt/playwright --ignore-scripts --no-audit --no-fund \
     && /opt/playwright/node_modules/.bin/playwright install --with-deps chromium firefox webkit \
     && mv /etc/fonts/conf.d/10-sub-pixel-none.conf /etc/fonts/10-sub-pixel-none.conf.disabled \

images/playwright-browser/definition.json

@@ -36,7 +36,7 @@
     "1.58-trixie": {
       "runtime_line": "1.58",
       "os": "debian-trixie",
-      "revision": "1.0.1",
+      "revision": "1.0.2",
       "platforms": [
         "linux/amd64"
       ],
@@ -45,9 +45,10 @@
         "digest": "sha256:154ba2f4d6fec323d28e4f4bb86bba4677f1223391a1979cf521304e03a98dfa"
       },
       "changes": [
-        "Use RGB subpixel rendering to match the consuming project's Noble Chromium screenshot baselines; verify fontconfig and committed screenshot parity."
+        "Retain RGB screenshot parity and isolate browser locks and fixtures by runtime line; prepare matched releases when the consumer Playwright pin changes."
       ],
-      "migration": "Compatible rendering fix. Select the accepted 1.0.1 digest after publication; existing 1.0.0 digest pins remain unchanged."
+      "migration": "Select the accepted 1.0.2 digest after publication for isolated browser inputs and RGB rendering. Existing exact release pins remain unchanged.",
+      "playwright_version": "1.58.2"
     }
   }
 }

…ges/playwright-browser/package-lock.json …wser/lines/1.58-trixie/package-lock.jsonimages/playwright-browser/package-lock.json renamed to images/playwright-browser/lines/1.58-trixie/package-lock.json images/playwright-browser/package-lock.json renamed to images/playwright-browser/lines/1.58-trixie/package-lock.json

@@ -82,6 +82,10 @@
           "runtime_line": {
             "type": "string"
           },
+          "playwright_version": {
+            "type": "string",
+            "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$"
+          },
           "os": {
             "const": "debian-trixie"
           },

images/playwright-browser/package.json …t-browser/lines/1.58-trixie/package.jsonimages/playwright-browser/package.json renamed to images/playwright-browser/lines/1.58-trixie/package.json images/playwright-browser/package.json renamed to images/playwright-browser/lines/1.58-trixie/package.json

@@ -32,7 +32,7 @@ def build(line, image, source, parent=None, cache=None):
     d = definitions()[line]
     tools = read(ROOT / "images/tools.json")
     args = {"BASE_IMAGE": parent or pinned(d["base"]), "SOURCE_COMMIT": source,
-            "IMAGE_VERSION": d["revision"], "APT_REFRESH": d["revision"]}
+            "IMAGE_VERSION": d["revision"], "APT_REFRESH": d["revision"], "IMAGE_LINE": d["line"]}
     if d["family"] in ("php-dev", "php-frankenphp"):
         args.update(COMPOSER_IMAGE=pinned(tools["composer"]), REDIS_VERSION=tools["redis_version"],
                     XDEBUG_VERSION=tools["xdebug_version"], PCOV_VERSION=tools["pcov_version"],

schemas/definition.schema.json

@@ -17,13 +17,13 @@
 }
 
 
-def sources(family, root):
+def sources(family, root, line=None):
     """Read COPY sources; stage copies are already represented by pinned inputs."""
     recipe = Path(root) / "images" / family / "Dockerfile"
     result = {str(recipe.relative_to(root)), ".dockerignore"}
     text = recipe.read_text().replace("\\\n", " ")
-    for line in text.splitlines():
-        instruction = re.match(r"^\s*(COPY|ADD)\s+(.+)$", line, re.I)
+    for recipe_line in text.splitlines():
+        instruction = re.match(r"^\s*(COPY|ADD)\s+(.+)$", recipe_line, re.I)
         if not instruction:
             continue
         if instruction[1].upper() == "ADD":
@@ -37,20 +37,24 @@ def sources(family, root):
             continue
         tokens = json.loads(value) if value.startswith("[") else shlex.split(value)
         for source in tokens[:-1]:
+            if "${IMAGE_LINE}" in source:
+                if line is not None and not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9._-]*", line):
+                    raise ValueError(f"Unsupported image line: {line}")
+                source = source.replace("${IMAGE_LINE}", line if line is not None else "*")
             if source.startswith("/") or ".." in Path(source).parts or "$" in source:
                 raise ValueError(f"Unsupported COPY source: {source}")
             result.add(source.rstrip("/"))
     return sorted(result)
 
 
-def consumes(family, path, root):
+def consumes(family, path, root, line=None):
     return any(path == source or path.startswith(source + "/")
-               or Path(path).match(source) for source in sources(family, root))
+               or Path(path).match(source) for source in sources(family, root, line))
 
 
-def files(family, root):
+def files(family, root, line=None):
     result = set()
-    for source in sources(family, root):
+    for source in sources(family, root, line):
         for path in Path(root).glob(source):
             if path.is_dir():
                 result.update(item for item in path.rglob("*") if item.is_file())