@molecule/api-ai-tools 1.16.8 → 1.17.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-11-06T03:40:01.617Z
+Generated: 2026-11-06T13:53:38.704Z
 -->
 
 # @molecule/api-ai-tools
@@ -51,7 +51,7 @@ for await (const event of requireProvider().chat({ system, tools, messages, stre
 ## Installation
 
 ```bash
-npm install @molecule/api-ai-tools @molecule/api-ai
+npm install @molecule/api-ai-tools @molecule/api-ai typescript
 ```
 
 ## API
@@ -404,6 +404,111 @@ interface RunnerOutputFilter {
 }
 ```
 
+#### `FeedbackSource`
+
+A source file already read by the caller. Paths are absolute.
+
+```typescript
+interface FeedbackSource {
+  path: string
+  content: string
+}
+```
+
+#### `FeedbackSpec`
+
+One supplied or scaffolded spec, with its normal, locally targeted runner command.
+
+```typescript
+interface FeedbackSpec extends FeedbackSource {
+  command: string
+  cwd: string
+}
+```
+
+#### `FeedbackProject`
+
+The inputs the host already knows; no suite discovery or vendor selection in the scheduler.
+
+```typescript
+interface FeedbackProject {
+  /** Base for relative source-change paths, already resolved by the host. */
+  root?: string
+  sources: FeedbackSource[]
+  specs: FeedbackSpec[]
+}
+```
+
+#### `PlaywrightFeedbackFailure`
+
+A native failure, never a static prediction or a completed-suite proof.
+
+```typescript
+interface PlaywrightFeedbackFailure {
+  spec: string
+  line: number
+  error: string
+  /** The native runner's locator or assertion, verbatim apart from redaction. */
+  locator: string
+  /** Playwright's own failure-time accessibility snapshot, when recorded. */
+  rendered?: string
+  /** Route render dependencies affected by this write, or the triggering source paths. */
+  sourceFiles: string[]
+}
+```
+
+#### `PlaywrightFeedbackResult`
+
+A diagnosis of one spec file at one source revision. A pass is not whole-suite proof.
+
+```typescript
+interface PlaywrightFeedbackResult {
+  spec: string
+  revision: number
+  durationMs: number
+  status: 'passed' | 'failed' | 'unavailable'
+  failures: PlaywrightFeedbackFailure[]
+  /** Native counts for this one diagnostic selection, never whole-suite proof. */
+  nativeStats?: PlaywrightReportStats
+  reason?: string
+}
+```
+
+#### `PlaywrightFeedbackOptions`
+
+Host operations for the same scheduler in a CLI process or a remote sandbox.
+
+```typescript
+interface PlaywrightFeedbackOptions {
+  load: () => Promise<FeedbackProject>
+  run: (
+    spec: FeedbackSpec,
+    sources: string[],
+    revision: number,
+    emit: (result: PlaywrightFeedbackResult) => void,
+  ) => Promise<PlaywrightFeedbackResult>
+  /** Only current native failures are delivered. Passing apps receive no note. */
+  onFailures?: (result: PlaywrightFeedbackResult) => void
+  /** Operational state is separate from defect feedback. */
+  onResult?: (result: PlaywrightFeedbackResult) => void
+  debounceMs?: number
+}
+```
+
+#### `PlaywrightFeedback`
+
+A nonblocking source-change subscription.
+
+```typescript
+interface PlaywrightFeedback {
+  changed: (paths: readonly string[]) => void
+  takeFailures: () => PlaywrightFeedbackResult[]
+  /** Wait only in tests or shutdown; file writes and deploys must never await this. */
+  settled: () => Promise<void>
+  close: () => Promise<void>
+}
+```
+
 #### `PlaywrightReportAttachment`
 
 One artifact the runner saved for one test, as the report records it.
@@ -2550,6 +2655,96 @@ function pipelineExitCodeNote(command: string, exitCode: number, output: string)
 
 **Returns:** One sentence naming the stage the code came from, or null.
 
+#### `selectFeedbackSpecs(project, changed)`
+
+Prioritize spec files potentially affected by writes. Every file still runs: a click or
+a helper can navigate somewhere a literal-goto index cannot see. This index never excludes work.
+
+```typescript
+function selectFeedbackSpecs(
+  project: FeedbackProject,
+  changed: readonly string[],
+): Array<{ spec: FeedbackSpec; sourceFiles: string[] }>
+```
+
+- `project` — Caller-supplied source and runner inventory.
+- `changed` — Absolute source paths changed since the previous diagnosis.
+
+**Returns:** Spec files to run, with their rendering-source context.
+
+#### `isPlaywrightFeedbackSource(path)`
+
+Whether a source change can alter markup, copy, styling or local runner configuration.
+
+```typescript
+function isPlaywrightFeedbackSource(path: string): boolean
+```
+
+- `path` — The path reported by the host's file-change subscription.
+
+**Returns:** True for app source and data formats; never a correctness judgment.
+
+#### `createPlaywrightFeedback(options)`
+
+Subscribe to writes without making them wait for browser work.
+
+```typescript
+function createPlaywrightFeedback(options: PlaywrightFeedbackOptions): PlaywrightFeedback
+```
+
+- `options` — Source loader, native runner and delivery callbacks.
+
+**Returns:** A source-change subscription; settle/close are for tests and shutdown only.
+
+#### `readFeedbackSources(backend, sourceRoots, suiteFiles)`
+
+Read explicit source roots and supplied helper/spec paths in one backend round trip.
+The standard filesystem and TypeScript parser own traversal/syntax; this is transport batching.
+
+```typescript
+function readFeedbackSources(
+  backend: ExecutionBackend,
+  sourceRoots: readonly string[],
+  suiteFiles: readonly string[],
+): Promise<FeedbackSource[]>
+```
+
+- `backend` — Local or sandbox execution backend.
+- `sourceRoots` — App source directories, absolute.
+- `suiteFiles` — Supplied spec/helper paths, absolute.
+
+**Returns:** Existing, bounded text sources. Missing/unsupported files are ignored.
+
+#### `runPlaywrightFeedback(backend, spec, sourceFiles, revision, options)`
+
+Run ONE spec's native command. Callers supply the correctly configured local command and
+append these runner flags at composition time (rather than modifying shell text here).
+Native failures are diagnosis, never proof that a complete supplied suite passed.
+
+```typescript
+function runPlaywrightFeedback(
+  backend: ExecutionBackend,
+  spec: FeedbackSpec,
+  sourceFiles: string[],
+  revision: number,
+  options: {
+    command: (flags: string[]) => string
+    scratchRoot?: string
+    timeoutMs?: number
+    emit?: (result: PlaywrightFeedbackResult) => void
+    pollMs?: number
+  },
+): Promise<PlaywrightFeedbackResult>
+```
+
+- `backend` — Existing execution backend.
+- `spec` — The supplied spec and its normal per-file command.
+- `sourceFiles` — Triggering component files, known to the write/index.
+- `revision` — Source revision the scheduler will validate before delivery.
+- `options` — Output location, command composition and a bounded backend budget.
+
+**Returns:** The actual native outcome and actionable failures only.
+
 #### `reportCarriesIdentities(status)`
 
 The report statuses for which the report's own per-test identities and attachments may be used.
@@ -5804,7 +5999,15 @@ Peer dependencies:
 ### Runtime Dependencies
 
 - `@molecule/api-ai`
-
+- `typescript`
+
+- **Background Playwright feedback:** `createPlaywrightFeedback({ load, run, onFailures })`
+  coalesces `changed(paths)` events without delaying writes. Use `readFeedbackSources`
+  to batch source reads over either backend and `runPlaywrightFeedback` to run each
+  supplied spec through its native command. Its incremental reporter supplies exact
+  locator failures and the failure-time page snapshot. Healthy runs emit no note;
+  no suite schedules no runner. `settled()`/`close()` are for tests and shutdown,
+  never a deployment barrier. Diagnoses are not whole-suite completion proof.
 - **Opaque command plans:** prepare each logical step with `streamingBackgroundCommand`,
   call `createCommandPlan`, and attach it to the executed wrapper with `commandWithPlan`.
   The launcher prints each step's `startMarker` and `endMarker` on their own lines around

package/dist/backends/local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/backends/local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAsDxE"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/backends/local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CA6FxE"}

package/dist/backends/local.js

@@ -4,7 +4,7 @@
  *
  * @module
  */
-import { execFile } from 'child_process';
+import { spawn } from 'child_process';
 import { mkdir, readdir, readFile, unlink, writeFile } from 'fs/promises';
 import { dirname } from 'path';
 /**
@@ -38,23 +38,69 @@ export function createLocalBackend(projectRoot) {
         },
         run(command, opts) {
             return new Promise((resolve) => {
-                // Use shell: true for command strings (grep pipelines, find, etc.)
-                // Input is sanitized via shellQuote at the tool level
-                execFile('sh', ['-c', command], {
+                // A native runner owns children. execFile's timeout killed only sh,
+                // leaving the runner/browser alive. Use the OS process group, with a
+                // graceful signal followed by a bounded forceful cleanup of that group.
+                const grouped = process.platform !== 'win32';
+                const child = spawn('sh', ['-c', command], {
                     cwd: opts?.cwd || projectRoot,
-                    timeout: opts?.timeout || 30000,
-                    maxBuffer: 10 * 1024 * 1024,
-                    encoding: 'utf8',
-                }, (error, stdout, stderr) => {
-                    if (error && 'code' in error && typeof error.code === 'number') {
-                        resolve({ stdout: stdout || '', stderr: stderr || '', exitCode: error.code });
+                    detached: grouped,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                let stdout = '', stderr = '', closed = false, code = 1;
+                let stopped;
+                let force;
+                const finish = () => {
+                    if (closed && !force)
+                        resolve({ stdout, stderr, exitCode: stopped === 'timeout' ? 124 : stopped ? 1 : code });
+                };
+                const signal = (value) => {
+                    try {
+                        if (grouped && child.pid)
+                            process.kill(-child.pid, value);
+                        else
+                            child.kill(value);
                     }
-                    else if (error) {
-                        resolve({ stdout: stdout || '', stderr: stderr || error.message, exitCode: 1 });
+                    catch (_error) {
+                        /* the owned group already exited */
                     }
-                    else {
-                        resolve({ stdout: stdout || '', stderr: stderr || '', exitCode: 0 });
+                };
+                const stop = (why) => {
+                    if (stopped)
+                        return;
+                    stopped = why;
+                    signal('SIGTERM');
+                    force = setTimeout(() => {
+                        signal('SIGKILL');
+                        force = undefined;
+                        finish();
+                    }, 1000);
+                };
+                const timeout = Math.min(opts?.timeout || 30_000, opts?.budgetMs || Infinity);
+                const deadline = setTimeout(() => stop('timeout'), timeout);
+                const collect = (text, channel) => {
+                    if (stopped)
+                        return;
+                    if (stdout.length + stderr.length + text.length > 10 * 1024 * 1024) {
+                        stderr += '\nCommand exceeded the 10 MB output limit.';
+                        stop('output');
+                        return;
                     }
+                    if (channel === 'stdout')
+                        stdout += text;
+                    else
+                        stderr += text;
+                };
+                child.stdout.setEncoding('utf8').on('data', (text) => collect(text, 'stdout'));
+                child.stderr.setEncoding('utf8').on('data', (text) => collect(text, 'stderr'));
+                child.on('error', (error) => {
+                    stderr += error.message;
+                });
+                child.on('close', (exitCode) => {
+                    closed = true;
+                    code = exitCode ?? 1;
+                    clearTimeout(deadline);
+                    finish();
                 });
             });
         },

package/dist/index.d.ts

@@ -12,6 +12,13 @@
  * (identity, tool listing, project docs, discovered skills).
  *
  * @remarks
+ * - **Background Playwright feedback:** `createPlaywrightFeedback({ load, run, onFailures })`
+ *   coalesces `changed(paths)` events without delaying writes. Use `readFeedbackSources`
+ *   to batch source reads over either backend and `runPlaywrightFeedback` to run each
+ *   supplied spec through its native command. Its incremental reporter supplies exact
+ *   locator failures and the failure-time page snapshot. Healthy runs emit no note;
+ *   no suite schedules no runner. `settled()`/`close()` are for tests and shutdown,
+ *   never a deployment barrier. Diagnoses are not whole-suite completion proof.
  * - **Opaque command plans:** prepare each logical step with `streamingBackgroundCommand`,
  *   call `createCommandPlan`, and attach it to the executed wrapper with `commandWithPlan`.
  *   The launcher prints each step's `startMarker` and `endMarker` on their own lines around
@@ -165,6 +172,9 @@ export * from './line-diff.js';
 export * from './no-test-run.js';
 export * from './output-filter.js';
 export * from './pipeline-exit-note.js';
+export * from './playwright-feedback.js';
+export * from './playwright-feedback-selection.js';
+export * from './playwright-feedback-types.js';
 export * from './playwright-report.js';
 export * from './schemas.js';
 export * from './server-command.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwJG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+JG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oCAAoC,CAAA;AAClD,cAAc,gCAAgC,CAAA;AAC9C,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -12,6 +12,13 @@
  * (identity, tool listing, project docs, discovered skills).
  *
  * @remarks
+ * - **Background Playwright feedback:** `createPlaywrightFeedback({ load, run, onFailures })`
+ *   coalesces `changed(paths)` events without delaying writes. Use `readFeedbackSources`
+ *   to batch source reads over either backend and `runPlaywrightFeedback` to run each
+ *   supplied spec through its native command. Its incremental reporter supplies exact
+ *   locator failures and the failure-time page snapshot. Healthy runs emit no note;
+ *   no suite schedules no runner. `settled()`/`close()` are for tests and shutdown,
+ *   never a deployment barrier. Diagnoses are not whole-suite completion proof.
  * - **Opaque command plans:** prepare each logical step with `streamingBackgroundCommand`,
  *   call `createCommandPlan`, and attach it to the executed wrapper with `commandWithPlan`.
  *   The launcher prints each step's `startMarker` and `endMarker` on their own lines around
@@ -165,6 +172,9 @@ export * from './line-diff.js';
 export * from './no-test-run.js';
 export * from './output-filter.js';
 export * from './pipeline-exit-note.js';
+export * from './playwright-feedback.js';
+export * from './playwright-feedback-selection.js';
+export * from './playwright-feedback-types.js';
 export * from './playwright-report.js';
 export * from './schemas.js';
 export * from './server-command.js';

package/dist/playwright-feedback-reporter.d.ts

@@ -0,0 +1,16 @@
+import type { PlaywrightFeedbackFailure } from './playwright-feedback-types.js';
+/**
+ * A standard Playwright reporter, placed beside each run's private outputs. It
+ * records onTestEnd, so the first exact failure need not wait for the rest of
+ * the spec file. No page injection, test rewrite, screenshots or trace overhead.
+ * @returns A CommonJS reporter loadable by the project's installed Playwright.
+ */
+export declare function feedbackReporterSource(): string;
+/**
+ * Read native failure events; incomplete final lines wait for the next read.
+ * @param text - Reporter JSONL, not runner-log inference.
+ * @param sourceFiles - Triggering source files from the scheduler.
+ * @returns Locator failures only, redacted and bounded.
+ */
+export declare function nativeFeedbackFailures(text: string, sourceFiles: string[]): PlaywrightFeedbackFailure[];
+//# sourceMappingURL=playwright-feedback-reporter.d.ts.map

package/dist/playwright-feedback-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-feedback-reporter.d.ts","sourceRoot":"","sources":["../src/playwright-feedback-reporter.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA;AAG/E;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAyB/C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,GACpB,yBAAyB,EAAE,CAsC7B"}

package/dist/playwright-feedback-reporter.js

@@ -0,0 +1,79 @@
+/**
+ * Native Playwright events for incremental background feedback.
+ *
+ * @module
+ */
+import { stripVTControlCharacters } from 'node:util';
+import { redactSecrets } from './utilities.js';
+/**
+ * A standard Playwright reporter, placed beside each run's private outputs. It
+ * records onTestEnd, so the first exact failure need not wait for the rest of
+ * the spec file. No page injection, test rewrite, screenshots or trace overhead.
+ * @returns A CommonJS reporter loadable by the project's installed Playwright.
+ */
+export function feedbackReporterSource() {
+    return String.raw `
+const fs = require('node:fs');
+module.exports = class FeedbackReporter {
+  onTestEnd(test, result) {
+    if (result.status === test.expectedStatus || !['failed','timedOut'].includes(result.status)) return;
+    const errors = result.errors || [];
+    const error = errors.map(e => e.message || '').join('\n');
+    const location = [...errors].reverse().find(e => e.location)?.location || test.location;
+    const attachment = result.attachments.find(a => a.name === 'error-context' && a.path);
+    let rendered;
+    if (attachment) try {
+      const text = fs.readFileSync(attachment.path, 'utf8');
+      const fence = String.fromCharCode(96).repeat(3);
+      const yaml = text.split(fence + 'yaml\n')[1];
+      if (yaml) rendered = yaml.split(fence)[0].trim().slice(0, 2000);
+      else {
+        const section = text.split('# Page snapshot')[1];
+        if (section) rendered = section.split(fence)[1]?.split('\n').slice(1).join('\n').trim().slice(0, 2000);
+      }
+    } catch {}
+    if (process.env.MOL_TEST_FEEDBACK_EVENTS) fs.appendFileSync(process.env.MOL_TEST_FEEDBACK_EVENTS,
+      JSON.stringify({spec: location.file, line: location.line, error: error.slice(0, 6000), rendered}) + '\n');
+  }
+};`;
+}
+/**
+ * Read native failure events; incomplete final lines wait for the next read.
+ * @param text - Reporter JSONL, not runner-log inference.
+ * @param sourceFiles - Triggering source files from the scheduler.
+ * @returns Locator failures only, redacted and bounded.
+ */
+export function nativeFeedbackFailures(text, sourceFiles) {
+    const out = [];
+    if (text.length > 1_000_000)
+        return out;
+    for (const line of text.split('\n').slice(0, -1)) {
+        try {
+            const event = JSON.parse(line);
+            if (typeof event.spec !== 'string' ||
+                typeof event.line !== 'number' ||
+                typeof event.error !== 'string')
+                continue;
+            const error = redactSecrets(stripVTControlCharacters(event.error).slice(0, 6_000));
+            const locator = /(?:Locator:\s*|waiting for )(locator\([^\n]+|getBy[^\n]+)/.exec(error)?.[1] ??
+                /strict mode violation: ([^\n]+)/.exec(error)?.[1] ??
+                /(?:^|\n)((?:Error: )?expect\([^\n]+|AssertionError:[^\n]+)/.exec(error)?.[1];
+            if (!locator)
+                continue;
+            out.push({
+                spec: event.spec,
+                line: event.line,
+                error,
+                locator,
+                ...(typeof event.rendered === 'string' && event.rendered
+                    ? { rendered: redactSecrets(event.rendered.slice(0, 2000)) }
+                    : {}),
+                sourceFiles,
+            });
+        }
+        catch (_error) {
+            /* not a completed native event */
+        }
+    }
+    return out;
+}

package/dist/playwright-feedback-selection.d.ts

@@ -0,0 +1,13 @@
+import type { FeedbackProject, FeedbackSpec } from './playwright-feedback-types.js';
+/**
+ * Prioritize spec files potentially affected by writes. Every file still runs: a click or
+ * a helper can navigate somewhere a literal-goto index cannot see. This index never excludes work.
+ * @param project - Caller-supplied source and runner inventory.
+ * @param changed - Absolute source paths changed since the previous diagnosis.
+ * @returns Spec files to run, with their rendering-source context.
+ */
+export declare function selectFeedbackSpecs(project: FeedbackProject, changed: readonly string[]): Array<{
+    spec: FeedbackSpec;
+    sourceFiles: string[];
+}>;
+//# sourceMappingURL=playwright-feedback-selection.d.ts.map

package/dist/playwright-feedback-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-feedback-selection.d.ts","sourceRoot":"","sources":["../src/playwright-feedback-selection.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,eAAe,EAAkB,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAsLnG;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,KAAK,CAAC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwBtD"}

package/dist/playwright-feedback-selection.js

@@ -0,0 +1,206 @@
+/**
+ * Prioritize native spec files from explicit route declarations and source imports.
+ * TypeScript parses syntax; Playwright judges behavior. Unreadable/dynamic routing
+ * falls back to all specs, rather than treating an absent index entry as coverage.
+ * @module
+ */
+import { createRequire } from 'node:module';
+import { posix } from 'node:path';
+const require = createRequire(import.meta.url);
+let compiler;
+const typescript = () => (compiler ??= require('typescript'));
+/** Get the text of a literal or the static prefix of a route template. */
+function routeText(node) {
+    const ts = typescript();
+    if (!node)
+        return undefined;
+    if (ts.isJsxExpression(node))
+        return routeText(node.expression);
+    if (ts.isStringLiteralLike(node))
+        return node.text;
+    if (ts.isTemplateExpression(node))
+        return `${node.head.text}*`;
+    return undefined;
+}
+/** Parse each file once, resolving only relative source imports we actually have. */
+function sourceIndex(files) {
+    const ts = typescript();
+    const trees = new Map(files.map((f) => [
+        f.path,
+        ts.createSourceFile(f.path, f.content, ts.ScriptTarget.Latest, true),
+    ]));
+    const imports = new Map();
+    const dependencies = new Map();
+    for (const [file, tree] of trees) {
+        const names = new Map(), deps = new Set();
+        const resolve = (text) => {
+            if (!text.startsWith('.'))
+                return undefined;
+            const base = posix.resolve(posix.dirname(file), text);
+            return [
+                base,
+                base.replace(/\.[cm]?jsx?$/, '.ts'),
+                base.replace(/\.[cm]?jsx?$/, '.tsx'),
+                ...['.ts', '.tsx', '.js', '.jsx', '/index.ts', '/index.tsx'].map((ext) => base + ext),
+            ].find((p) => trees.has(p));
+        };
+        const visit = (node) => {
+            if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+                const target = resolve(node.moduleSpecifier.text);
+                if (target) {
+                    deps.add(target);
+                    const clause = node.importClause;
+                    if (clause?.name)
+                        names.set(clause.name.text, target);
+                    if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings))
+                        for (const n of clause.namedBindings.elements)
+                            names.set(n.name.text, target);
+                }
+            }
+            if (ts.isExportDeclaration(node) &&
+                node.moduleSpecifier &&
+                ts.isStringLiteral(node.moduleSpecifier)) {
+                const target = resolve(node.moduleSpecifier.text);
+                if (target)
+                    deps.add(target);
+            }
+            if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+                const text = routeText(node.arguments[0]), target = text && resolve(text);
+                if (target)
+                    deps.add(target);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(tree);
+        imports.set(file, names);
+        dependencies.set(file, deps);
+    }
+    return { trees, imports, dependencies };
+}
+/** The explicit routes a module declares; unknown framework shapes remain unindexed. */
+function routeFiles(files) {
+    const ts = typescript();
+    const { trees, imports, dependencies } = sourceIndex(files);
+    const out = [];
+    const closure = (file, seen) => {
+        if (seen.has(file))
+            return;
+        seen.add(file);
+        for (const dep of dependencies.get(file) ?? [])
+            closure(dep, seen);
+    };
+    for (const [file, tree] of trees) {
+        const add = (path, element) => {
+            const route = routeText(path);
+            // Relative and nested declarations need the router's own resolution. Do not guess it.
+            if (!route?.startsWith('/') || !element)
+                return;
+            const selected = new Set([file]);
+            const refs = (node) => {
+                if (ts.isIdentifier(node)) {
+                    const target = imports.get(file)?.get(node.text);
+                    if (target)
+                        closure(target, selected);
+                }
+                ts.forEachChild(node, refs);
+            };
+            refs(element);
+            // A local component, namespace or lazy binding cannot be resolved narrowly here.
+            if (selected.size === 1)
+                closure(file, selected);
+            out.push({ route, files: selected });
+        };
+        const visit = (node) => {
+            if (ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) {
+                const attrs = node.attributes.properties.filter(ts.isJsxAttribute);
+                const path = attrs.find((a) => a.name.getText(tree) === 'path')?.initializer;
+                const element = attrs.find((a) => /^(element|component|Component)$/.test(a.name.getText(tree)))?.initializer;
+                add(path, element);
+            }
+            if (ts.isObjectLiteralExpression(node)) {
+                const props = node.properties.filter(ts.isPropertyAssignment);
+                add(props.find((p) => p.name.getText(tree).replace(/['"]/g, '') === 'path')?.initializer, props.find((p) => /^(element|component|Component)$/.test(p.name.getText(tree).replace(/['"]/g, '')))?.initializer);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(tree);
+    }
+    return out;
+}
+/** Goto targets in a spec and its supplied helpers. Unknown targets force a conservative run. */
+function specRoutes(spec, index) {
+    const ts = typescript();
+    const { trees, dependencies } = index;
+    const seen = new Set(), routes = [];
+    let unknown = false;
+    const read = (file) => {
+        if (seen.has(file))
+            return;
+        seen.add(file);
+        const tree = trees.get(file);
+        if (!tree) {
+            unknown = true;
+            return;
+        }
+        const visit = (node) => {
+            if (ts.isCallExpression(node) &&
+                ts.isPropertyAccessExpression(node.expression) &&
+                node.expression.name.text === 'goto') {
+                const route = routeText(node.arguments[0]);
+                if (route?.startsWith('/'))
+                    routes.push(route.split('?')[0].split('#')[0]);
+                else
+                    unknown = true;
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(tree);
+        for (const dep of dependencies.get(file) ?? [])
+            read(dep);
+    };
+    read(spec.path);
+    return { routes, unknown: unknown || routes.length === 0 };
+}
+/** Compare route patterns for selection only, never for a correctness claim. */
+function routeOverlaps(a, b) {
+    const left = a.split('/').filter(Boolean), right = b.split('/').filter(Boolean);
+    const n = Math.max(left.length, right.length);
+    for (let i = 0; i < n; i++) {
+        if (left[i] === '*' || right[i] === '*')
+            return true;
+        if (!left[i] || !right[i])
+            return false;
+        if (!left[i].startsWith(':') && !right[i].startsWith(':') && left[i] !== right[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Prioritize spec files potentially affected by writes. Every file still runs: a click or
+ * a helper can navigate somewhere a literal-goto index cannot see. This index never excludes work.
+ * @param project - Caller-supplied source and runner inventory.
+ * @param changed - Absolute source paths changed since the previous diagnosis.
+ * @returns Spec files to run, with their rendering-source context.
+ */
+export function selectFeedbackSpecs(project, changed) {
+    if (project.specs.length === 0)
+        return [];
+    const routes = routeFiles(project.sources);
+    const affected = routes.filter((r) => changed.some((p) => r.files.has(p)));
+    const index = sourceIndex([...project.sources, ...project.specs]);
+    return project.specs
+        .map((spec) => {
+        const targets = specRoutes(spec, index);
+        const hits = affected.filter((r) => targets.routes.some((path) => routeOverlaps(r.route, path)));
+        return {
+            spec,
+            priority: hits.length,
+            sourceFiles: [
+                ...new Set(hits.length
+                    ? hits.flatMap((r) => [...r.files]).filter((p) => changed.includes(p))
+                    : changed),
+            ],
+        };
+    })
+        .sort((a, b) => b.priority - a.priority);
+}

package/dist/playwright-feedback-types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Native Playwright diagnosis while an app is being written.
+ *
+ * @module
+ */
+import type { PlaywrightReportStats } from './playwright-report.js';
+/** A source file already read by the caller. Paths are absolute. */
+export interface FeedbackSource {
+    path: string;
+    content: string;
+}
+/** One supplied or scaffolded spec, with its normal, locally targeted runner command. */
+export interface FeedbackSpec extends FeedbackSource {
+    command: string;
+    cwd: string;
+}
+/** The inputs the host already knows; no suite discovery or vendor selection in the scheduler. */
+export interface FeedbackProject {
+    /** Base for relative source-change paths, already resolved by the host. */
+    root?: string;
+    sources: FeedbackSource[];
+    specs: FeedbackSpec[];
+}
+/** A native failure, never a static prediction or a completed-suite proof. */
+export interface PlaywrightFeedbackFailure {
+    spec: string;
+    line: number;
+    error: string;
+    /** The native runner's locator or assertion, verbatim apart from redaction. */
+    locator: string;
+    /** Playwright's own failure-time accessibility snapshot, when recorded. */
+    rendered?: string;
+    /** Route render dependencies affected by this write, or the triggering source paths. */
+    sourceFiles: string[];
+}
+/** A diagnosis of one spec file at one source revision. A pass is not whole-suite proof. */
+export interface PlaywrightFeedbackResult {
+    spec: string;
+    revision: number;
+    durationMs: number;
+    status: 'passed' | 'failed' | 'unavailable';
+    failures: PlaywrightFeedbackFailure[];
+    /** Native counts for this one diagnostic selection, never whole-suite proof. */
+    nativeStats?: PlaywrightReportStats;
+    reason?: string;
+}
+/** Host operations for the same scheduler in a CLI process or a remote sandbox. */
+export interface PlaywrightFeedbackOptions {
+    load: () => Promise<FeedbackProject>;
+    run: (spec: FeedbackSpec, sources: string[], revision: number, emit: (result: PlaywrightFeedbackResult) => void) => Promise<PlaywrightFeedbackResult>;
+    /** Only current native failures are delivered. Passing apps receive no note. */
+    onFailures?: (result: PlaywrightFeedbackResult) => void;
+    /** Operational state is separate from defect feedback. */
+    onResult?: (result: PlaywrightFeedbackResult) => void;
+    debounceMs?: number;
+}
+/** A nonblocking source-change subscription. */
+export interface PlaywrightFeedback {
+    changed: (paths: readonly string[]) => void;
+    takeFailures: () => PlaywrightFeedbackResult[];
+    /** Wait only in tests or shutdown; file writes and deploys must never await this. */
+    settled: () => Promise<void>;
+    close: () => Promise<void>;
+}
+//# sourceMappingURL=playwright-feedback-types.d.ts.map

package/dist/playwright-feedback-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-feedback-types.d.ts","sourceRoot":"","sources":["../src/playwright-feedback-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAEnE,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wFAAwF;IACxF,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED,4FAA4F;AAC5F,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAA;IAC3C,QAAQ,EAAE,yBAAyB,EAAE,CAAA;IACrC,gFAAgF;IAChF,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAA;IACpC,GAAG,EAAE,CACH,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,KAC7C,OAAO,CAAC,wBAAwB,CAAC,CAAA;IACtC,gFAAgF;IAChF,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACvD,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IAC3C,YAAY,EAAE,MAAM,wBAAwB,EAAE,CAAA;IAC9C,qFAAqF;IACrF,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B"}

package/dist/playwright-feedback-types.js

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

package/dist/playwright-feedback.d.ts

@@ -0,0 +1,42 @@
+import type { FeedbackSource, FeedbackSpec, PlaywrightFeedback, PlaywrightFeedbackOptions, PlaywrightFeedbackResult } from './playwright-feedback-types.js';
+import type { ExecutionBackend } from './types.js';
+/**
+ * Whether a source change can alter markup, copy, styling or local runner configuration.
+ * @param path - The path reported by the host's file-change subscription.
+ * @returns True for app source and data formats; never a correctness judgment.
+ */
+export declare function isPlaywrightFeedbackSource(path: string): boolean;
+/**
+ * Subscribe to writes without making them wait for browser work.
+ * @param options - Source loader, native runner and delivery callbacks.
+ * @returns A source-change subscription; settle/close are for tests and shutdown only.
+ */
+export declare function createPlaywrightFeedback(options: PlaywrightFeedbackOptions): PlaywrightFeedback;
+/**
+ * Read explicit source roots and supplied helper/spec paths in one backend round trip.
+ * The standard filesystem and TypeScript parser own traversal/syntax; this is transport batching.
+ * @param backend - Local or sandbox execution backend.
+ * @param sourceRoots - App source directories, absolute.
+ * @param suiteFiles - Supplied spec/helper paths, absolute.
+ * @returns Existing, bounded text sources. Missing/unsupported files are ignored.
+ */
+export declare function readFeedbackSources(backend: ExecutionBackend, sourceRoots: readonly string[], suiteFiles: readonly string[]): Promise<FeedbackSource[]>;
+/**
+ * Run ONE spec's native command. Callers supply the correctly configured local command and
+ * append these runner flags at composition time (rather than modifying shell text here).
+ * Native failures are diagnosis, never proof that a complete supplied suite passed.
+ * @param backend - Existing execution backend.
+ * @param spec - The supplied spec and its normal per-file command.
+ * @param sourceFiles - Triggering component files, known to the write/index.
+ * @param revision - Source revision the scheduler will validate before delivery.
+ * @param options - Output location, command composition and a bounded backend budget.
+ * @returns The actual native outcome and actionable failures only.
+ */
+export declare function runPlaywrightFeedback(backend: ExecutionBackend, spec: FeedbackSpec, sourceFiles: string[], revision: number, options: {
+    command: (flags: string[]) => string;
+    scratchRoot?: string;
+    timeoutMs?: number;
+    emit?: (result: PlaywrightFeedbackResult) => void;
+    pollMs?: number;
+}): Promise<PlaywrightFeedbackResult>;
+//# sourceMappingURL=playwright-feedback.d.ts.map

package/dist/playwright-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-feedback.d.ts","sourceRoot":"","sources":["../src/playwright-feedback.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAElB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,gCAAgC,CAAA;AAEvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGlD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAyG/F;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,gBAAgB,EACzB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,OAAO,CAAC,cAAc,EAAE,CAAC,CAkB3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IACP,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GACA,OAAO,CAAC,wBAAwB,CAAC,CAwInC"}

package/dist/playwright-feedback.js

@@ -0,0 +1,318 @@
+/**
+ * Run the project's real Playwright files while an agent keeps writing.
+ *
+ * The native runner, JSON reporter and error-context snapshot already answer what
+ * failed and what rendered. The small scheduler only coalesces writes, prioritizes
+ * route-related spec files, runs one at a time, and discards stale revisions.
+ * No correctness inference, foreground barrier, extra browser or passing-run note.
+ * @module
+ */
+import { randomUUID } from 'node:crypto';
+import { posix } from 'node:path';
+import { feedbackReporterSource, nativeFeedbackFailures } from './playwright-feedback-reporter.js';
+import { selectFeedbackSpecs } from './playwright-feedback-selection.js';
+import { summarizePlaywrightReport } from './playwright-report.js';
+import { redactSecrets, shellQuote } from './utilities.js';
+/**
+ * Whether a source change can alter markup, copy, styling or local runner configuration.
+ * @param path - The path reported by the host's file-change subscription.
+ * @returns True for app source and data formats; never a correctness judgment.
+ */
+export function isPlaywrightFeedbackSource(path) {
+    return /\.(?:[cm]?[jt]sx?|vue|svelte|html?|css|json|mdx?)$/i.test(path);
+}
+/**
+ * Subscribe to writes without making them wait for browser work.
+ * @param options - Source loader, native runner and delivery callbacks.
+ * @returns A source-change subscription; settle/close are for tests and shutdown only.
+ */
+export function createPlaywrightFeedback(options) {
+    let revision = 0, timer, active;
+    let stopped = false;
+    const changed = new Set(), waiting = [];
+    const delivered = new Map();
+    const failing = new Set();
+    const start = () => {
+        if (active || stopped || changed.size === 0)
+            return;
+        const version = revision, paths = [...changed];
+        changed.clear();
+        active = (async () => {
+            let project;
+            try {
+                project = await options.load();
+            }
+            catch (_error) {
+                return;
+            }
+            if (stopped || version !== revision)
+                return;
+            const sourcePaths = project.root ? paths.map((p) => posix.resolve(project.root, p)) : paths;
+            // The native failures already name the files to rerun first after an edit.
+            const selected = selectFeedbackSpecs(project, sourcePaths).sort((a, b) => Number(failing.has(b.spec.path)) - Number(failing.has(a.spec.path)));
+            for (const { spec, sourceFiles } of selected) {
+                if (stopped || version !== revision)
+                    break;
+                const emit = (result) => {
+                    if (stopped || version !== revision || result.status !== 'failed')
+                        return;
+                    failing.add(spec.path);
+                    const identities = delivered.get(spec.path) ?? new Set();
+                    const failures = result.failures.filter((f) => {
+                        const identity = JSON.stringify(f);
+                        if (identities.has(identity))
+                            return false;
+                        identities.add(identity);
+                        return true;
+                    });
+                    delivered.set(spec.path, identities);
+                    if (!failures.length)
+                        return;
+                    const fresh = { ...result, failures };
+                    waiting.push(fresh);
+                    options.onFailures?.(fresh);
+                };
+                let result;
+                try {
+                    result = await options.run(spec, sourceFiles, version, emit);
+                }
+                catch (_error) {
+                    continue;
+                } // runner availability is not a markup defect
+                if (stopped || version !== revision)
+                    break;
+                options.onResult?.(result);
+                if (result.status === 'passed')
+                    failing.delete(spec.path);
+                if (result.status !== 'failed')
+                    delivered.delete(spec.path);
+                emit(result);
+            }
+        })().finally(() => {
+            active = undefined;
+            if (!stopped && changed.size && !timer)
+                schedule();
+        });
+    };
+    const schedule = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            start();
+        }, options.debounceMs ?? 250);
+        timer.unref?.();
+    };
+    const settled = async () => {
+        while (timer || active || (!stopped && changed.size)) {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+                start();
+            }
+            if (active)
+                await active;
+            else if (!stopped && changed.size)
+                start();
+        }
+    };
+    return {
+        changed(paths) {
+            if (stopped || paths.length === 0)
+                return;
+            revision++;
+            for (const path of paths)
+                changed.add(path);
+            waiting.length = 0;
+            // A queued diagnosis can be invalidated before its host delivers it. A
+            // new revision must be allowed to report the same still-failing locator.
+            delivered.clear();
+            schedule();
+        },
+        takeFailures() {
+            return waiting.splice(0).filter((r) => r.revision === revision);
+        },
+        settled,
+        async close() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            changed.clear();
+            waiting.length = 0;
+            if (active)
+                await active;
+        },
+    };
+}
+/**
+ * Read explicit source roots and supplied helper/spec paths in one backend round trip.
+ * The standard filesystem and TypeScript parser own traversal/syntax; this is transport batching.
+ * @param backend - Local or sandbox execution backend.
+ * @param sourceRoots - App source directories, absolute.
+ * @param suiteFiles - Supplied spec/helper paths, absolute.
+ * @returns Existing, bounded text sources. Missing/unsupported files are ignored.
+ */
+export async function readFeedbackSources(backend, sourceRoots, suiteFiles) {
+    if (sourceRoots.length === 0 && suiteFiles.length === 0)
+        return [];
+    const program = `const fs=require('node:fs'),p=require('node:path');const seen=new Set(),out=[];let bytes=0;
+const read=f=>{if(seen.has(f)||out.length>=1000||bytes>=4000000)return;seen.add(f);try{const s=fs.lstatSync(f);if(s.isSymbolicLink())return;if(s.isDirectory()){for(const n of fs.readdirSync(f))if(!['node_modules','.git','dist','build'].includes(n))read(p.join(f,n));}else if(/\\.[cm]?[jt]sx?$/.test(f)&&s.size<=250000){const content=fs.readFileSync(f,'utf8');bytes+=content.length;out.push({path:f,content});}}catch{}};
+for(const f of ${JSON.stringify([...sourceRoots, ...suiteFiles])})read(f);process.stdout.write(JSON.stringify(out));`;
+    const result = await backend.run(`node -e ${shellQuote(program)}`, { timeout: 10_000 });
+    if (result.exitCode !== 0)
+        return [];
+    try {
+        const value = JSON.parse(result.stdout);
+        return Array.isArray(value)
+            ? value.filter((f) => f && typeof f.path === 'string' && typeof f.content === 'string')
+            : [];
+    }
+    catch (_error) {
+        return [];
+    }
+}
+/**
+ * Run ONE spec's native command. Callers supply the correctly configured local command and
+ * append these runner flags at composition time (rather than modifying shell text here).
+ * Native failures are diagnosis, never proof that a complete supplied suite passed.
+ * @param backend - Existing execution backend.
+ * @param spec - The supplied spec and its normal per-file command.
+ * @param sourceFiles - Triggering component files, known to the write/index.
+ * @param revision - Source revision the scheduler will validate before delivery.
+ * @param options - Output location, command composition and a bounded backend budget.
+ * @returns The actual native outcome and actionable failures only.
+ */
+export async function runPlaywrightFeedback(backend, spec, sourceFiles, revision, options) {
+    const started = Date.now();
+    const dir = posix.join(options.scratchRoot ?? posix.join(backend.projectRoot, '.mol', 'test-feedback'), randomUUID());
+    const reportPath = posix.join(dir, 'report.json');
+    const reporterPath = posix.join(dir, 'feedback-reporter.cjs');
+    const eventsPath = posix.join(dir, 'failures.jsonl');
+    const timeout = options.timeoutMs ?? 120_000;
+    const base = { spec: spec.path, revision, failures: [] };
+    const unavailable = (reason) => ({
+        ...base,
+        status: 'unavailable',
+        durationMs: Date.now() - started,
+        reason,
+    });
+    const native = options.command([
+        `--reporter=${shellQuote(reporterPath + ',json')}`,
+        '--workers=1',
+        '--retries=0',
+        `--global-timeout=${timeout}`,
+        `--output=${shellQuote(posix.join(dir, 'results'))}`,
+    ]);
+    // The standard OS priority keeps background diagnosis behind the dev server
+    // and builds when they share one CPU. Playwright owns its global deadline.
+    const command = `export PLAYWRIGHT_JSON_OUTPUT_FILE=${shellQuote(reportPath)} MOL_TEST_FEEDBACK_EVENTS=${shellQuote(eventsPath)}; nice -n 10 sh -c ${shellQuote(native)}`;
+    let poll, reading, done = false;
+    const emitted = new Set();
+    const nativeFailures = new Map();
+    const readEvents = async () => {
+        try {
+            const text = await backend.readFile(eventsPath);
+            for (const failure of nativeFeedbackFailures(text, sourceFiles)) {
+                const identity = JSON.stringify(failure);
+                nativeFailures.set(identity, failure);
+                if (emitted.has(identity))
+                    continue;
+                emitted.add(identity);
+                options.emit?.({
+                    ...base,
+                    failures: [failure],
+                    status: 'failed',
+                    durationMs: Date.now() - started,
+                });
+            }
+        }
+        catch (_error) {
+            /* the first failure has not arrived yet */
+        }
+    };
+    const tick = () => {
+        if (done)
+            return;
+        reading = readEvents().finally(() => {
+            if (!done) {
+                poll = setTimeout(tick, options.pollMs ?? 1000);
+                poll.unref?.();
+            }
+        });
+    };
+    try {
+        await backend.writeFile(reporterPath, feedbackReporterSource());
+        if (options.emit)
+            tick();
+        const result = await backend.run(command, {
+            cwd: spec.cwd,
+            timeout: timeout + 10_000,
+            budgetMs: timeout + 5_000,
+        });
+        done = true;
+        if (poll)
+            clearTimeout(poll);
+        if (reading)
+            await reading;
+        await readEvents();
+        let reportText;
+        try {
+            reportText = await backend.readFile(reportPath);
+        }
+        catch (_error) {
+            return unavailable(`the native runner produced no JSON report: ${redactSecrets((result.stderr || result.stdout).trim().slice(0, 2000))}`);
+        }
+        const report = summarizePlaywrightReport(reportText, {
+            path: reportPath,
+            sanitize: redactSecrets,
+        });
+        if (report.status !== 'complete' ||
+            !report.stats ||
+            report.stats.expected + report.stats.unexpected + report.stats.flaky === 0 ||
+            report.stats.skipped > 0) {
+            let errors = [];
+            try {
+                errors = JSON.parse(reportText).errors ?? [];
+            }
+            catch (_error) {
+                /* the native summary already records malformed JSON */
+            }
+            const detail = errors.map((e) => e.message ?? '').join('\n') ||
+                result.stderr ||
+                report.reason ||
+                'zero executed tests or skipped tests';
+            return {
+                ...unavailable(`the native runner did not complete every selected test: ${redactSecrets(detail.slice(0, 2000))}`),
+                ...(report.stats ? { nativeStats: report.stats } : {}),
+            };
+        }
+        base.failures = [...nativeFailures.values()];
+        if (base.failures.length)
+            return {
+                ...base,
+                nativeStats: report.stats,
+                status: 'failed',
+                durationMs: Date.now() - started,
+            };
+        if (result.exitCode !== 0 || report.stats.unexpected || report.stats.flaky)
+            return unavailable('the native run failed outside a locator assertion');
+        return {
+            ...base,
+            nativeStats: report.stats,
+            status: 'passed',
+            durationMs: Date.now() - started,
+        };
+    }
+    finally {
+        done = true;
+        if (poll)
+            clearTimeout(poll);
+        if (reading)
+            await reading;
+        // Only this run's private generated files; the supplied suite and its outputs stay untouched.
+        await backend
+            .run(`node -e ${shellQuote(`require('node:fs').rmSync(${JSON.stringify(dir)},{recursive:true,force:true})`)}`, { timeout: 5_000 })
+            .catch(() => undefined);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.16.8",
+  "version": "1.17.0",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",
@@ -32,6 +32,7 @@
   },
   "devDependencies": {
     "@molecule/api-ai": "1.6.0",
+    "@playwright/test": "1.64.1",
     "@types/node": "26.6.5",
     "esbuild": "0.28.2",
     "typescript": "6.0.3",
@@ -46,5 +47,8 @@
   "bugs": "https://github.com/molecule-dev/molecule/issues",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "typescript": "6.0.3"
   }
 }