@tekyzinc/gsd-t 4.4.10 → 4.4.11

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.4.11] - 2026-06-10 (Playwright No-Focus-Steal — patch)
+
+### Added — E2E tests must never steal keyboard focus (all projects)
+
+Headed Playwright runs on macOS ACTIVATE the browser app and yank keyboard focus from the terminal — regardless of window position, so the old "off-screen window" mitigation stopped screen takeover but not focus theft (reported live from binvoice: extension specs commandeered the cursor on every spec). Root cause of the prior "new-headless can't load MV3 extensions" verdict was a binary mix-up: `headless: true` alone launches the chromium_headless_shell (OLD headless, silently no extensions) and a raw `--headless=new` arg fights it. The fix: `channel: 'chromium'` + `headless: true` selects the FULL build's new headless — extensions load, service workers register, zero windows (binvoice: 21/21 in 9.8s).
+
+- `templates/CLAUDE-global.md`: new "Playwright No-Focus-Steal Invariant" section — headless default everywhere, one launch helper owns visibility, `HEADED=1` opt-in only, the channel pitfall documented; mirrored to the live `~/.claude/CLAUDE.md`.
+- `templates/test-helpers/launch-extension.ts`: NEW generalized MV3-extension launch helper (newheadless default / offscreen fallback / HEADED=1), proven in binvoice (commit 87e3233 there).
+
+No code-path changes; propagates via `gsd-t update-all` (CLAUDE-global section sync).
+
 ## [4.4.10] - 2026-06-09 (M85 Model-Tier Policy + Fable 5 — minor)
 
 ### Added — single source of truth for model-tier assignments + the Fable 5 tier

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.4.10",
+  "version": "4.4.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -210,6 +210,29 @@ Operator overrides:
 
 You no longer need to run a check yourself before testing commands — the Workflow stage runs the readiness gate before E2E.
 
+### Playwright No-Focus-Steal Invariant (MANDATORY — all projects)
+
+**E2E tests must NEVER steal keyboard focus or pop visible windows during a normal run.** The developer keeps typing in their terminal while tests run. This is non-negotiable on every project.
+
+```
+RULES:
+  ├── Headless is the DEFAULT everywhere. A visible browser is opt-in only (HEADED=1).
+  ├── Specs/configs MUST NOT hardcode `headless: false` — visibility is decided in ONE
+  │     launch helper (or the config), controlled by env var, never per-spec.
+  ├── MV3 Chrome extensions are NOT an exception: Chrome's NEW headless loads
+  │     extensions. The load-bearing invocation is `channel: 'chromium'` + `headless: true`
+  │     (Playwright ≥1.49). PITFALL: `headless: true` alone launches the
+  │     chromium_headless_shell (OLD headless — silently cannot load extensions), and
+  │     passing `--headless=new` as a raw arg fights that binary. Template:
+  │     `templates/test-helpers/launch-extension.ts`.
+  └── Off-screen windows (`--window-position=-2400,-2400`) are NOT a focus fix on
+        macOS — a headed launch ACTIVATES the app and steals the cursor regardless of
+        window position. Off-screen is a screen-takeover mitigation only; use it solely
+        as a fallback if new-headless regresses extension support.
+```
+
+Origin: binvoice 2026-06-10 — extension specs forced `headless: false`, commandeering the cursor on every spec; the prior "off-screen" mitigation stopped the window takeover but not the focus theft. Fixed permanently by the channel-selected new headless (21/21 in 9.8s, zero windows).
+
 ### Playwright Cleanup
 
 After Playwright tests finish (pass or fail), **kill any app/server processes that were started for the tests**. Playwright often launches a dev server (via `webServer` config or manually). These processes must not be left running:

package/templates/test-helpers/launch-extension.ts

@@ -0,0 +1,81 @@
+/**
+ * launch-extension.ts — GSD-T template: launch Chromium with an unpacked MV3
+ * extension WITHOUT stealing focus or taking over the developer's screen.
+ *
+ * Copy into e2e/helpers/ and set EXTENSION_PATH for your project.
+ * Origin: binvoice 2026-06-10 (see GSD-T CHANGELOG 4.4.11).
+ *
+ * THE INVARIANT: E2E tests must NEVER steal keyboard focus. On macOS a headed
+ * Chromium launch ACTIVATES the app — yanking the cursor out of the terminal —
+ * regardless of window position. Off-screen windows do NOT fix this; only a
+ * truly headless launch does.
+ *
+ * Modes:
+ *   1. NEW HEADLESS (DEFAULT) — full-Chromium new headless via
+ *      `channel: 'chromium'` + `headless: true`. Loads MV3 extensions and
+ *      registers service workers. No window, no activation, no focus theft.
+ *      PITFALL this template exists to encode: `headless: true` ALONE launches
+ *      Playwright's chromium_headless_shell (OLD headless — silently cannot
+ *      load extensions), and passing `--headless=new` as a raw arg fights that
+ *      binary instead of selecting the right one. `channel: 'chromium'` is the
+ *      load-bearing line.
+ *   2. OFF-SCREEN HEADED — fallback if a future Chrome regresses new-headless
+ *      extension support. Prevents screen takeover but NOT macOS focus theft.
+ *   3. HEADED — visible window for watching a run. Opt-in only, never default.
+ *
+ * Env:
+ *   HEADED=1            → mode 3 (visible window).
+ *   E2E_MODE=offscreen  → mode 2 (fallback).
+ *   (unset)             → mode 1 (new headless — the default).
+ */
+
+import { chromium, type BrowserContext } from '@playwright/test';
+import { resolve } from 'path';
+
+// Adjust for your project: path to the built unpacked extension.
+export const EXTENSION_PATH = resolve(__dirname, '../../dist');
+
+type Mode = 'newheadless' | 'offscreen' | 'headed';
+
+function resolveMode(): Mode {
+  if (process.env['HEADED'] === '1') return 'headed';
+  if (process.env['E2E_MODE'] === 'offscreen') return 'offscreen';
+  if (process.env['E2E_MODE'] === 'headed') return 'headed';
+  return 'newheadless';
+}
+
+function baseArgs(): string[] {
+  return [
+    `--disable-extensions-except=${EXTENSION_PATH}`,
+    `--load-extension=${EXTENSION_PATH}`,
+    '--no-sandbox',
+  ];
+}
+
+export async function launchExtensionContext(): Promise<BrowserContext> {
+  const mode = resolveMode();
+  const args = baseArgs();
+
+  if (mode === 'newheadless') {
+    return chromium.launchPersistentContext('', {
+      channel: 'chromium', // load-bearing: full build → new headless → extensions work
+      headless: true,
+      args,
+    });
+  }
+
+  if (mode === 'offscreen') {
+    return chromium.launchPersistentContext('', {
+      headless: false,
+      args: [
+        ...args,
+        '--window-position=-2400,-2400',
+        '--window-size=400,300',
+        '--no-first-run',
+        '--no-default-browser-check',
+      ],
+    });
+  }
+
+  return chromium.launchPersistentContext('', { headless: false, args });
+}