test: add real browser QA

Author: cardmagic

.github/workflows/ci.yml

@@ -55,3 +55,15 @@ jobs:
       - run: corepack enable
       - run: pnpm install --frozen-lockfile
       - run: pnpm run test:postgresql
+
+  browser:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38
+        with:
+          node-version: "24.15.0"
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm run test:browser

.gitignore

@@ -2,6 +2,8 @@ node_modules/
 dist/
 .test-dist/
 coverage/
+playwright-report/
+test-results/
 *.tgz
 *.sqlite3
 .DS_Store

CHANGELOG.md

@@ -35,6 +35,8 @@
   per runtime and polling as the correctness fallback.
 - Add a typed browser component registry with keyed dependencies, replace/morph
   strategies, batch coalescing, cancellation, and per-target revision fencing.
+- Add Chromium QA for native WebSocket subscription replay, realtime fences,
+  personalized payloads, component batching, and request cancellation.
 
 ## 0.1.0 - 2026-08-13
 

README.md

@@ -649,6 +649,9 @@ application's synchronous `apply` callback; the library does not assume a DOM
 framework. The refresh endpoint must authenticate the request and reauthorize
 every requested component and dependency.
 
+Run `pnpm run test:browser` after installing Playwright's Chromium build to
+exercise the browser entry through native WebSocket and browser APIs.
+
 For subscriber-specific views, declare a static payload map with a TypeScript
 `satisfies` check:
 

docs/browser-protocol.md

@@ -81,6 +81,11 @@ target as authorization. The application-owned refresh endpoint authenticates
 the browser and reauthorizes every requested component before returning render
 results.
 
+`pnpm run test:browser` builds the browser entry and runs its Playwright suite
+in Chromium. It covers native WebSocket subscription replay, stale revision and
+incarnation handling, personalized payloads, component batching, and
+superseded-request cancellation.
+
 `runtime.realtime` delivers directly to sessions in its own Node process. For
 several WebSocket processes, the configured `broadcast` callback publishes the
 committed envelope through a shared transport and each process passes received

docs/parity.md

@@ -74,7 +74,7 @@ Reference: Ruby `solid_objects` 0.12.0 at commit `a01b6f5`.
 | Turbo scalar replacement                                     | Not applicable | The browser client exposes invalidations to application rendering code. Framework adapters can be separate packages.                                                                                           |
 | Keyed component refresh, morph/replace, and batch coalescing | Native         | A typed framework-neutral registry selects explicit dependencies, coalesces batch requests, aborts superseded work, fences each target, and delegates synchronous application strategy to the host.            |
 | Personalized payload broadcasts                              | Native         | Static typed projections run against committed state under each fresh subscriber context, reauthorize as queries, isolate failures, and carry independent revision fences.                                     |
-| Real-browser compatibility suite                             | Planned        | Exercise reconnection, incarnation changes, stale revisions, cancellation, batching, and payload delivery in Chromium.                                                                                         |
+| Real-browser compatibility suite                             | Native         | Playwright exercises subscription replay over native WebSocket, incarnation/revision fences, payload delivery, component batching, and cancellation in Chromium.                                               |
 
 ## Rails-specific surfaces
 

package.json

@@ -48,20 +48,24 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "vitest run",
+    "test:browser": "pnpm run build && playwright test",
     "test:coverage": "vitest run --coverage",
     "test:postgresql": "vitest run test/postgresql.test.ts",
     "test:watch": "vitest",
     "pack:check": "pnpm pack --dry-run",
     "prepack": "pnpm run build"
   },
   "devDependencies": {
+    "@playwright/test": "^1.62.1",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.21.0",
+    "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.1.10",
     "pg": "^8.23.0",
     "prettier": "^3.9.6",
     "typescript": "^5.9.0",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "ws": "^8.21.3"
   },
   "peerDependencies": {
     "pg": "^8.23.0"

playwright.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from "@playwright/test"
+
+export default defineConfig({
+  testDir: "./test/browser",
+  testMatch: "**/*.browser.ts",
+  fullyParallel: false,
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: "line",
+  use: {
+    baseURL: "http://127.0.0.1:4179",
+    browserName: "chromium",
+    headless: true,
+  },
+  webServer: {
+    command: "node test/browser-server.mjs",
+    url: "http://127.0.0.1:4179",
+    reuseExistingServer: false,
+  },
+})

pnpm-lock.yaml

@@ -249,14 +249,25 @@ export class SolidObjectsComponentRegistry<Rendered> {
     pending: PendingRefresh
     results: readonly ComponentRefreshResult<Rendered>[]
   }): void {
+    if (!Array.isArray(options.results)) throw new TypeError("component results must be an array")
     const requested = options.pending.components
     const seen = new Set<string>()
+    const validated: Array<{
+      component: RegisteredComponent
+      result: ComponentRefreshResult<Rendered>
+    }> = []
     for (const result of options.results) {
+      if (!isComponentRefreshResult<Rendered>(result)) {
+        throw new TypeError("component results must contain a target and rendered value")
+      }
       if (seen.has(result.target))
         throw new TypeError(`duplicate component result ${result.target}`)
       seen.add(result.target)
       const component = requested.get(result.target)
       if (!component) throw new TypeError(`unexpected component result ${result.target}`)
+      validated.push({ component, result })
+    }
+    for (const { component, result } of validated) {
       if (this.#components.get(componentIdentity(component)) !== component) continue
       const current = this.#applied.get(result.target)
       if (
@@ -366,3 +377,12 @@ function supersedes(current: ActiveRefresh, previous: ActiveRefresh): boolean {
 function isAbortError(error: unknown): boolean {
   return error instanceof Error && error.name === "AbortError"
 }
+
+function isComponentRefreshResult<Rendered>(
+  value: unknown,
+): value is ComponentRefreshResult<Rendered> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  return (
+    typeof (value as { target?: unknown }).target === "string" && Object.hasOwn(value, "rendered")
+  )
+}