peaks-loop 4.0.54 → 4.1.0

package/dist/services/verdict/envelopes.js

@@ -1,95 +1,7 @@
-/**
- * peaks-loop v2.13.3 — Envelope unification (AC-1: real markdown parse).
- *
- * The 5 input envelopes feeding `aggregateVerdict()` have always been
- * heterogeneous (peaks-security-audit / peaks-perf-audit / karpathy /
- * peaks-mut / peaks-qa). v2.13.1 shipped precedence wiring without
- * touching the on-disk shapes. v2.13.2 introduced a discriminated-union
- * type projection `AnyEnvelope` and 5 pure parser functions.
- *
- * v2.13.3 dogfood bug #1: parseSecurity/Perf previously only supported
- * a JSON.parse path. The real v2.12.0 audit files at
- * `.peaks/_runtime/<sid>/audit/security.md` and `audit/perf.md` are
- * YAML frontmatter + markdown body — NOT JSON. The fix preserves
- * the JSON.parse path (back-compat for unit tests + any consumer that
- * passed JSON explicitly) and adds a markdown fallback that extracts
- * `verdict:` from the frontmatter and parses `## Findings` bullets.
- *
- * Karpathy §2 (Simplicity First):
- *   - single file, ~210 lines, zero new IO.
- *   - re-uses existing strict-shape guards (isSecurityAuditEnvelope /
- *     isPerfAuditEnvelope) — no duplicate validation logic.
- *   - parsers return `null` on malformed input (mirrors loadMutReport's
- *     "missing → null" contract). Callers can detect "envelope missing"
- *     without throwing.
- */
-import { isPerfAuditEnvelope, isSecurityAuditEnvelope } from '../audit-independent/index.js';
-// ─── 5 parsers (pure, never throw) ─────────────────────────────────────
-/**
- * v2.13.3 AC-1 — parse real v2.12.0 audit markdown.
- *
- * Strategy (per PRD AC-1 mitigation):
- *   1. Try JSON.parse first (back-compat with prior unit tests + any
- *      consumer that passes a JSON string explicitly).
- *   2. Fall back to markdown parse: extract `verdict:` from YAML
- *      frontmatter, parse `## Findings` bullets in the body, return
- *      a SecurityAuditEnvelope.
- *   3. Return null when neither path yields a valid envelope.
- */
-export function parseSecurityEnvelope(md) {
-    if (typeof md !== 'string' || md.length === 0)
-        return null;
-    // Path 1: JSON (legacy / back-compat)
-    try {
-        const jsonValue = JSON.parse(md);
-        if (isSecurityAuditEnvelope(jsonValue))
-            return jsonValue;
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        // not JSON — fall through to markdown parse
-    }
-    // Path 2: real v2.12.0 markdown (YAML frontmatter + body)
-    return parseAuditMarkdown(md, isSecurityAuditEnvelope);
-}
-export function parsePerfEnvelope(md) {
-    if (typeof md !== 'string' || md.length === 0)
-        return null;
-    // Path 1: JSON (legacy / back-compat)
-    try {
-        const jsonValue = JSON.parse(md);
-        if (isPerfAuditEnvelope(jsonValue))
-            return jsonValue;
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        // not JSON — fall through to markdown parse
-    }
-    // Path 2: real v2.12.0 markdown (YAML frontmatter + body)
-    return parseAuditMarkdown(md, isPerfAuditEnvelope);
-}
-/**
- * Karpathy review is stored as markdown (`.peaks/_runtime/<sid>/rd/karpathy-review.md`).
- * We parse the 3 state lines that drive the aggregator:
- *   - `gateAction: pass | warn | block`
- *   - `verdict: pass | warn | block`  (alias for gateAction)
- *   - `passed: true | false`
- * Plus the violations list under a `## Violations` heading, where each
- * bullet begins with `[SEVERITY] file:line — hint` and declares a
- * guideline tag like `(simplicity-first)`.
- */
-export function parseKarpathyEnvelope(md) {
-    if (typeof md !== 'string' || md.length === 0)
-        return null;
-    const gateAction = matchEnum(md, /^\s*(?:gateAction|verdict)\s*:\s*(pass|warn|block)\s*$/m);
-    const passedMatch = md.match(/^\s*passed\s*:\s*(true|false)\s*$/m);
-    if (gateAction === null || passedMatch === null)
-        return null;
-    const violations = parseKarpathyViolations(md);
-    return {
-        passed: passedMatch[1] === 'true',
-        violations,
-        gateAction
-    };
-}
+import { extractSection, parseFindingBullets } from './envelope-parsers.js';
+// ─── Re-exports: parsers that live in ./envelope-parsers.js ───────────
+export { envelopesToAggregatorInput, parseKarpathyEnvelope, parsePerfEnvelope, parseSecurityEnvelope } from './envelope-parsers.js';
+// ─── Karpathy violation reader (called by parseKarpathyEnvelope) ───────
 const KARPATHY_GUIDELINES = [
     'think-before-coding',
     'simplicity-first',
@@ -97,7 +9,7 @@ const KARPATHY_GUIDELINES = [
     'goal-driven-execution'
 ];
 const KARPATHY_SEVERITIES = ['CRITICAL', 'HIGH', 'MED', 'LOW'];
-function parseKarpathyViolations(md) {
+export function parseKarpathyViolations(md) {
     const section = md.split(/^##\s+Violations\s*$/m)[1];
     if (section === undefined)
         return [];
@@ -108,7 +20,11 @@ function parseKarpathyViolations(md) {
         if (m === null)
             continue;
         const [, severity, file, lineNo, hint, guideline] = m;
-        if (severity === undefined || file === undefined || lineNo === undefined || hint === undefined || guideline === undefined)
+        if (severity === undefined ||
+            file === undefined ||
+            lineNo === undefined ||
+            hint === undefined ||
+            guideline === undefined)
             continue;
         if (!KARPATHY_SEVERITIES.includes(severity))
             continue;
@@ -180,31 +96,6 @@ export function parseQaEnvelope(md) {
         ...(reportPathMatch !== null ? { reportPath: reportPathMatch[1].trim() } : {})
     };
 }
-// ─── Adapter: union → AggregatorInput (zero call-site churn) ──────────
-/**
- * Convert a partial list of `AnyEnvelope` values to the legacy
- * `AggregatorInput` shape. `null` envelopes are skipped (a missing
- * envelope is treated as "audit not run" — same semantics as
- * `AggregatorInput` without that key).
- */
-export function envelopesToAggregatorInput(list) {
-    const out = {};
-    for (const item of list) {
-        if (item === null)
-            continue;
-        if (item.kind === 'security')
-            out.security = item.envelope;
-        else if (item.kind === 'perf')
-            out.perf = item.envelope;
-        else if (item.kind === 'karpathy')
-            out.karpathy = item.envelope;
-        else if (item.kind === 'mut')
-            out.mut = item.envelope;
-        else if (item.kind === 'qa')
-            out.qa = item.envelope;
-    }
-    return out;
-}
 /**
  * Parse a v2.12.0 audit markdown file:
  *   ---
@@ -235,7 +126,7 @@ export function envelopesToAggregatorInput(list) {
  *      guard. Return null if the guard rejects (per the parser
  *      contract: parsers never throw).
  */
-function parseAuditMarkdown(md, guard) {
+export function parseAuditMarkdown(md, guard) {
     const frontmatterMatch = md.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
     // The v2.12.0 audit artifact contract is YAML frontmatter + body.
     // The CLI also writes a body-only variant (no frontmatter) when the
@@ -270,46 +161,17 @@ function parseAuditMarkdown(md, guard) {
     };
     return guard(candidate) ? candidate : null;
 }
-/** Extract the body of a `## Heading` section (text up to the next
- *  `## ` heading or EOF). Returns null when the heading is absent. */
-function extractSection(body, heading) {
-    const re = new RegExp(`^##\\s+${heading}\\s*$`, 'm');
-    const sectionStart = body.search(re);
-    if (sectionStart === -1)
-        return null;
-    const afterHeading = body.slice(sectionStart).split('\n');
-    // skip the heading line
-    afterHeading.shift();
-    // collect lines until next `## ` heading
-    const lines = [];
-    for (const line of afterHeading) {
-        if (/^##\s+/.test(line))
-            break;
-        lines.push(line);
-    }
-    return lines.join('\n').trim();
-}
-/** Parse `## Findings` bullets. Accepts the 3 real v2.12.0 shapes. */
-function parseFindingBullets(body) {
-    const section = body.split(/^##\s+Findings\s*$/m)[1];
-    if (section === undefined)
-        return [];
-    const lines = section.split('\n').filter((l) => l.trim().startsWith('- '));
-    const out = [];
-    for (const line of lines) {
-        const v = parseFindingBullet(line);
-        if (v !== null)
-            out.push(v);
-    }
-    return out;
-}
 /** Parse a single finding bullet. Returns null on malformed input. */
-function parseFindingBullet(line) {
+export function parseFindingBullet(line) {
     // Shape A (rendered by renderSecurityAuditArtifact): `- [SEV] dim @ file:line — hint`
     const a = line.match(/^\s*-\s*\[(CRITICAL|HIGH|MED|LOW)\]\s+(\S+)\s+@\s+([^:\s]+):(\d+)\s+[—-]\s+(.+)$/);
     if (a !== null) {
         const [, severity, dimension, file, lineNo, hint] = a;
-        if (severity === undefined || dimension === undefined || file === undefined || lineNo === undefined || hint === undefined)
+        if (severity === undefined ||
+            dimension === undefined ||
+            file === undefined ||
+            lineNo === undefined ||
+            hint === undefined)
             return null;
         return {
             severity: severity,
@@ -342,7 +204,7 @@ function parseFindingBullet(line) {
     // future dimension-extraction contract. Already covered above.
     return null;
 }
-function matchEnum(md, regex) {
+export function matchEnum(md, regex) {
     const m = md.match(regex);
     return m === null ? null : m[1];
 }

package/dist/services/verdict/verdict-aggregator.js

@@ -49,7 +49,15 @@ export function aggregateVerdict(input) {
         const env = input.security;
         elevate(env.verdict);
         for (const v of env.violations) {
-            pushFix(state, { source: 'security-audit', sources: ['security-audit'], signal: env.verdict, severity: v.severity, file: v.file, line: v.line, hint: v.hint }, { file: v.file, line: v.line, hint: v.hint });
+            pushFix(state, {
+                source: 'security-audit',
+                sources: ['security-audit'],
+                signal: env.verdict,
+                severity: v.severity,
+                file: v.file,
+                line: v.line,
+                hint: v.hint
+            }, { file: v.file, line: v.line, hint: v.hint });
         }
     }
     // 2. Perf audit envelope (v2.12.0 schema — preserved).
@@ -57,7 +65,15 @@ export function aggregateVerdict(input) {
         const env = input.perf;
         elevate(env.verdict);
         for (const v of env.violations) {
-            pushFix(state, { source: 'perf-audit', sources: ['perf-audit'], signal: env.verdict, severity: v.severity, file: v.file, line: v.line, hint: v.hint }, { file: v.file, line: v.line, hint: v.hint });
+            pushFix(state, {
+                source: 'perf-audit',
+                sources: ['perf-audit'],
+                signal: env.verdict,
+                severity: v.severity,
+                file: v.file,
+                line: v.line,
+                hint: v.hint
+            }, { file: v.file, line: v.line, hint: v.hint });
         }
     }
     // 3. Karpathy reviewer — gateAction drives precedence.
@@ -65,7 +81,15 @@ export function aggregateVerdict(input) {
         const env = input.karpathy;
         elevate(env.gateAction);
         for (const v of env.violations) {
-            pushFix(state, { source: 'karpathy-reviewer', sources: ['karpathy-reviewer'], signal: env.gateAction, severity: v.severity, file: v.file, line: v.line, hint: v.hint }, { file: v.file, line: v.line, hint: v.hint });
+            pushFix(state, {
+                source: 'karpathy-reviewer',
+                sources: ['karpathy-reviewer'],
+                signal: env.gateAction,
+                severity: v.severity,
+                file: v.file,
+                line: v.line,
+                hint: v.hint
+            }, { file: v.file, line: v.line, hint: v.hint });
         }
     }
     // 4. peaks-mut — passed:false → block with per-violation reason.

package/dist/services/vm/vm-lease.js

@@ -22,7 +22,9 @@ import { randomBytes } from 'node:crypto';
 import { posix as path } from 'node:path';
 import { normalizePath } from '../../shared/path-utils.js';
 export const VM_HYPERVISORS = Object.freeze([
-    'kvm', 'hyperkit', 'hyperv'
+    'kvm',
+    'hyperkit',
+    'hyperv'
 ]);
 // PRD-002b slice 2 — extract lease-TTL primitives (same shape as
 // container-lease.ts / worktree-lease.ts). See config diff comment.
@@ -90,8 +92,18 @@ export function deserializeVmLease(raw) {
     }
     const obj = parsed;
     const required = [
-        'leaseId', 'rid', 'role', 'path', 'hypervisor', 'image', 'vmId',
-        'createdAt', 'expiresAt', 'purpose', 'status', 'consumedBySubAgents'
+        'leaseId',
+        'rid',
+        'role',
+        'path',
+        'hypervisor',
+        'image',
+        'vmId',
+        'createdAt',
+        'expiresAt',
+        'purpose',
+        'status',
+        'consumedBySubAgents'
     ];
     for (const k of required) {
         if (!(k in obj))

package/dist/services/web/aria-node.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `ariaSnapshotJSON()` node type (slice S1, AC2 — the mechanism).
+ *
+ * Split out of `snapshot-pruner.ts` to keep the pruner under the
+ * 300-raw-line file cap; it is the data model the pruner, the renderer and
+ * external consumers (browser-session-manager, tests) all share. The pruner
+ * re-exports this name, so importers keep using `snapshot-pruner.js`
+ * unchanged.
+ */
+export interface AriaNode {
+    readonly role: string;
+    readonly name?: string;
+    readonly text?: string;
+    readonly children?: readonly AriaNode[];
+    readonly checked?: boolean | 'mixed';
+    readonly disabled?: boolean;
+    readonly expanded?: boolean;
+    readonly active?: boolean;
+    readonly invalid?: boolean | 'mixed';
+    readonly level?: number;
+    readonly pressed?: boolean | 'mixed';
+    readonly selected?: boolean;
+    readonly url?: string;
+    readonly placeholder?: string;
+    readonly ref?: string;
+    readonly cursor?: string;
+}

package/dist/services/web/aria-node.js

@@ -0,0 +1 @@
+export {};

package/dist/services/web/browser-acquire.js

@@ -59,7 +59,9 @@ export async function acquireChromium() {
 }
 /** One sentence, shared by both refusal paths, naming the command that fixes it. */
 function installRequiredDetail(version) {
-    const held = version === null ? 'the pinned Playwright is not resolvable' : `playwright@${version} is cached`;
+    const held = version === null
+        ? 'the pinned Playwright is not resolvable'
+        : `playwright@${version} is cached`;
     return (`${held} but its browser is not launched-ready; run \`peaks web install\` ` +
         `(\`npx ${installCommandLine().join(' ')}\`)`);
 }

package/dist/services/web/browser-cache-probe.d.ts

@@ -0,0 +1,18 @@
+import type { BrowserProbe } from './web-install-types.js';
+/**
+ * Is the pinned browser on disk? Never throws, never spawns, never downloads.
+ *
+ * **It answers about the artifact `launch()` starts** (R6). `executablePath()`
+ * names the `chromium` build, but `chromium.launch()` with no options and
+ * `headless` defaulting true resolves `chromium-headless-shell`
+ * (`registry.getExecutableName`) — a SEPARATE ~271 MiB download. Probing the
+ * full chromium therefore answered "installed" for a machine on which no op
+ * could launch: `launch()` failed, S1's net downloaded, the probe kept saying
+ * installed, and `peaks web install` short-circuited to a no-op success. See
+ * `headlessShellDir` for how the right path is obtained.
+ *
+ * `version` is reported even when the executable is missing, because "the
+ * package is cached but its browser is not" is a different diagnosis from
+ * "nothing is installed" — the first is one `peaks web install` away.
+ */
+export declare function probeBrowserInstalled(): Promise<BrowserProbe>;

package/dist/services/web/browser-cache-probe.js

@@ -0,0 +1,110 @@
+/**
+ * `src/services/web/browser-cache-probe.ts`
+ *
+ * The browser-cache probe (slice S3, file 18; R6, tech-doc §5.3): it asks the
+ * resolved Playwright package where its executable WOULD be and checks the
+ * filesystem — no download, no spawn, so `peaks web status` can report cache
+ * state on a machine with nothing installed. Moved verbatim (wave 3, file-size
+ * cap campaign) together with the two path derivations and the readdir guard it
+ * depends on, so `web-install-service.ts` stays under the 300 raw-line cap.
+ * `web-install-service.ts` re-exports `probeBrowserInstalled` so importers keep
+ * resolving it from `web-install-service.js` unchanged; the three helpers were
+ * module-private there and are not re-exported.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { loadPlaywright, playwrightVersion } from './playwright-loader.js';
+/**
+ * Is the pinned browser on disk? Never throws, never spawns, never downloads.
+ *
+ * **It answers about the artifact `launch()` starts** (R6). `executablePath()`
+ * names the `chromium` build, but `chromium.launch()` with no options and
+ * `headless` defaulting true resolves `chromium-headless-shell`
+ * (`registry.getExecutableName`) — a SEPARATE ~271 MiB download. Probing the
+ * full chromium therefore answered "installed" for a machine on which no op
+ * could launch: `launch()` failed, S1's net downloaded, the probe kept saying
+ * installed, and `peaks web install` short-circuited to a no-op success. See
+ * `headlessShellDir` for how the right path is obtained.
+ *
+ * `version` is reported even when the executable is missing, because "the
+ * package is cached but its browser is not" is a different diagnosis from
+ * "nothing is installed" — the first is one `peaks web install` away.
+ */
+export async function probeBrowserInstalled() {
+    const version = await playwrightVersion();
+    if (version === null) {
+        return { installed: false, version: null, executablePath: null };
+    }
+    try {
+        const chromiumPath = (await loadPlaywright()).chromium.executablePath();
+        const shellDir = headlessShellDir(chromiumPath);
+        if (shellDir === null) {
+            // Not a registry shape we recognise: answer about the path Playwright
+            // handed us, exactly as this probe did before R6, rather than about a
+            // directory we invented.
+            return { installed: existsSync(chromiumPath), version, executablePath: chromiumPath };
+        }
+        // Absent is the answer, and the whole point: `null` here is what steers
+        // `peaks web install` to download and `acquireChromium` to refuse.
+        const executablePath = headlessShellExecutable(shellDir);
+        return { installed: executablePath !== null, version, executablePath };
+    }
+    catch {
+        // The package resolved but would not load — a broken cache, not a download.
+        return { installed: false, version, executablePath: null };
+    }
+}
+/**
+ * The `chromium_headless_shell-<rev>` directory that sits beside
+ * `chromiumExecutablePath`'s own revision directory, or `null` when the path is
+ * not shaped like Playwright's registry.
+ *
+ * Playwright's public API cannot name the shell — `BrowserType.executablePath()`
+ * takes no options and always answers with the `chromium` build — so it is
+ * derived from the one path Playwright does hand out. One naming rule is
+ * assumed, and it is the one the cache itself shows: `<rev>` directories are
+ * named after the browser, `chromium-1243` beside `chromium_headless_shell-1243`.
+ */
+function headlessShellDir(chromiumExecutablePath) {
+    const segments = chromiumExecutablePath.split(/[\\/]/);
+    let revision = -1;
+    for (let i = segments.length - 1; i > 0; i -= 1) {
+        if (/^chromium-\d+$/.test(segments[i] ?? '')) {
+            revision = i;
+            break;
+        }
+    }
+    const revisionDir = segments[revision];
+    if (revision <= 0 || revisionDir === undefined) {
+        return null;
+    }
+    return join(segments.slice(0, revision).join(sep), revisionDir.replace('chromium-', 'chromium_headless_shell-'));
+}
+/**
+ * The shell executable inside `shellDir`, or `null`.
+ *
+ * The shell's own platform directory is deliberately NOT assumed — it is
+ * `chrome-headless-shell-<platform>` where chromium's is `chrome-<platform>` —
+ * so the file is looked for rather than named from a copy of Playwright's
+ * per-platform path table.
+ */
+function headlessShellExecutable(shellDir) {
+    for (const entry of safeReaddir(shellDir)) {
+        const platformDir = join(shellDir, entry);
+        for (const file of safeReaddir(platformDir)) {
+            if (/^chrome-headless-shell(\.exe)?$/.test(file)) {
+                return join(platformDir, file);
+            }
+        }
+    }
+    return null;
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        // Absent is the normal case on a machine that never installed the shell.
+        return [];
+    }
+}

package/dist/services/web/browser-session-manager.js

@@ -233,7 +233,9 @@ export class BrowserSessionManager {
         const page = await this.pageFor(dispatchId);
         await page.locator(selector).click();
         // The interpolated title is page-controlled; only the selector is ours.
-        return { result: capText(`clicked ${selector} (page: ${await page.title()})`, MAX_TEXT_BYTES).text };
+        return {
+            result: capText(`clicked ${selector} (page: ${await page.title()})`, MAX_TEXT_BYTES).text
+        };
     }
     /**
      * Screenshot to an absolute path under `web/`. Always an explicit `path`:
@@ -363,7 +365,9 @@ function asAriaNodes(raw) {
     if (!Array.isArray(raw)) {
         throw new Error(`WEB_SNAP_SHAPE_UNEXPECTED: ariaSnapshotJSON returned ${typeof raw}, not a node array`);
     }
-    const nodes = raw.filter((node) => typeof node === 'object' && node !== null && typeof node.role === 'string');
+    const nodes = raw.filter((node) => typeof node === 'object' &&
+        node !== null &&
+        typeof node.role === 'string');
     if (nodes.length !== raw.length) {
         throw new Error(`WEB_SNAP_SHAPE_UNEXPECTED: ariaSnapshotJSON returned ${raw.length - nodes.length} node(s) without a string role`);
     }

package/dist/services/web/daemon-registry.js

@@ -45,7 +45,10 @@ export function writeDaemonInfo(projectRoot, sessionId, info) {
     const target = webDaemonInfoPath(projectRoot, sessionId);
     assertUnder(target, webDaemonDir(projectRoot, sessionId));
     mkdirSync(dirname(target), { recursive: true, mode: DAEMON_DIR_MODE });
-    writeFileSync(target, JSON.stringify(info, null, 2), { encoding: 'utf8', mode: DAEMON_FILE_MODE });
+    writeFileSync(target, JSON.stringify(info, null, 2), {
+        encoding: 'utf8',
+        mode: DAEMON_FILE_MODE
+    });
 }
 /**
  * Read + validate `daemon.json`. `null` when absent, malformed, a stale

package/dist/services/web/playwright-loader.d.ts

@@ -1,79 +1,11 @@
+import type { PlaywrightModule, PwBrowser, PwContext, PwLocator, PwPage } from './playwright-types.js';
 /**
  * Exact pin, no caret (tech-doc §3.2). AC2 is a BYTE-COUNT contract and the
  * aria engine moves with the version, so upgrading is a deliberate,
  * re-measured change — never a floating range.
  */
 export declare const PLAYWRIGHT_VERSION_PIN = "1.63.0";
-/**
- * The structural slice of the Playwright API this feature actually calls.
- * Typed locally because the package is not a dependency and therefore has no
- * importable type declarations.
- */
-export interface PwLocator {
-    ariaSnapshotJSON?(options?: {
-        boxes?: boolean;
-        depth?: number;
-        mode?: 'ai' | 'default';
-        timeout?: number;
-    }): Promise<unknown>;
-    click(): Promise<void>;
-    innerText(): Promise<string>;
-    screenshot(options?: {
-        path?: string;
-        type?: 'png' | 'jpeg';
-    }): Promise<Buffer>;
-}
-export interface PwPage {
-    goto(url: string, options?: {
-        waitUntil?: string;
-        timeout?: number;
-    }): Promise<unknown>;
-    title(): Promise<string>;
-    url(): string;
-    locator(selector: string): PwLocator;
-    screenshot(options?: {
-        path?: string;
-        type?: 'png' | 'jpeg';
-    }): Promise<Buffer>;
-    evaluate<T>(expression: string): Promise<T>;
-}
-export interface PwContext {
-    newPage(): Promise<PwPage>;
-    addInitScript(script: string): Promise<void>;
-    storageState(options?: {
-        path?: string;
-    }): Promise<unknown>;
-    close(): Promise<void>;
-}
-export interface PwBrowser {
-    newContext(options?: Record<string, unknown>): Promise<PwContext>;
-    version(): string;
-    /**
-     * `disconnected` is the only signal that the user CLOSED the headed window
-     * (S4 repair), which is what completes a login: once the browser is gone a
-     * non-persistent context cannot be read, so the wait has to end here.
-     *
-     * OPTIONAL: the doubles that exercise the other verbs have no disconnect to
-     * report, and demanding the method made three of them type-broken. A browser
-     * that cannot report the event is treated as never disconnecting (S4 repair,
-     * code review F1).
-     */
-    on?(event: 'disconnected', listener: () => void): void;
-    /**
-     * Whether the browser is still connected. Real Playwright exposes it; the
-     * login checks it ONCE before the wait starts, so a browser that is already
-     * gone fails fast instead of running out the full ten-minute bound — the
-     * `disconnected` event is not replayed for it (S4 repair, code review F3).
-     */
-    isConnected?(): boolean;
-    close(): Promise<void>;
-}
-export interface PlaywrightModule {
-    chromium: {
-        launch(options?: Record<string, unknown>): Promise<PwBrowser>;
-        executablePath(): string;
-    };
-}
+export type { PlaywrightModule, PwBrowser, PwContext, PwLocator, PwPage };
 /**
  * Absolute path of the `playwright` main entry.
  *

package/dist/services/web/playwright-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The structural slice of the Playwright API this feature actually calls
+ * (slice S1, file 9).
+ *
+ * Split out of `playwright-loader.ts` to keep the loader under the
+ * 300-raw-line file cap — types only, no resolution or admission behaviour
+ * lives here. The loader re-exports every name below, so importers keep
+ * using `playwright-loader.js` unchanged. Typed locally because the package
+ * is not a dependency and therefore has no importable type declarations.
+ */
+export interface PwLocator {
+    ariaSnapshotJSON?(options?: {
+        boxes?: boolean;
+        depth?: number;
+        mode?: 'ai' | 'default';
+        timeout?: number;
+    }): Promise<unknown>;
+    click(): Promise<void>;
+    innerText(): Promise<string>;
+    screenshot(options?: {
+        path?: string;
+        type?: 'png' | 'jpeg';
+    }): Promise<Buffer>;
+}
+export interface PwPage {
+    goto(url: string, options?: {
+        waitUntil?: string;
+        timeout?: number;
+    }): Promise<unknown>;
+    title(): Promise<string>;
+    url(): string;
+    locator(selector: string): PwLocator;
+    screenshot(options?: {
+        path?: string;
+        type?: 'png' | 'jpeg';
+    }): Promise<Buffer>;
+    evaluate<T>(expression: string): Promise<T>;
+}
+export interface PwContext {
+    newPage(): Promise<PwPage>;
+    addInitScript(script: string): Promise<void>;
+    storageState(options?: {
+        path?: string;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}
+export interface PwBrowser {
+    newContext(options?: Record<string, unknown>): Promise<PwContext>;
+    version(): string;
+    /**
+     * `disconnected` is the only signal that the user CLOSED the headed window
+     * (S4 repair), which is what completes a login: once the browser is gone a
+     * non-persistent context cannot be read, so the wait has to end here.
+     *
+     * OPTIONAL: the doubles that exercise the other verbs have no disconnect to
+     * report, and demanding the method made three of them type-broken. A browser
+     * that cannot report the event is treated as never disconnecting (S4 repair,
+     * code review F1).
+     */
+    on?(event: 'disconnected', listener: () => void): void;
+    /**
+     * Whether the browser is still connected. Real Playwright exposes it; the
+     * login checks it ONCE before the wait starts, so a browser that is already
+     * gone fails fast instead of running out the full ten-minute bound — the
+     * `disconnected` event is not replayed for it (S4 repair, code review F3).
+     */
+    isConnected?(): boolean;
+    close(): Promise<void>;
+}
+export interface PlaywrightModule {
+    chromium: {
+        launch(options?: Record<string, unknown>): Promise<PwBrowser>;
+        executablePath(): string;
+    };
+}

package/dist/services/web/playwright-types.js

@@ -0,0 +1 @@
+export {};