@molecule/api-ai-tools 1.16.8 → 1.17.1

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-06T15:20:37.703Z
 -->
 
 # @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, assertion or timed-out browser operation, 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.
@@ -1350,7 +1455,7 @@ interface ToolBuildConfig {
   /** Maximum time (ms) one `wait_for_task` call may wait, independently of the foreground {@link commandBudgetMs}. */
   waitBudgetMs?: number
 
-  /** Opt in to one partial diagnostic return for a task driving this known deployed URL. */
+  /** Opt in to partial diagnostics for new final failure causes at this known deployed URL. */
   yieldOnFirstFailureFor?: (taskId: string) => string | null
 
   /** How long (ms) exec_command waits for a command it backgrounded only because the command asked for more than {@link commandBudgetMs}, before handing back a task… */
@@ -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.
@@ -4712,13 +4907,13 @@ With `finalOnly`, only a failure the run has FINISHED with counts; a pending ret
 function logShowsInlineFailureBodies(
   log: string,
   excluded?: readonly string[],
-  options?: { finalOnly?: boolean; noRetries?: boolean },
+  options?: { finalOnly?: boolean; noRetries?: boolean; onCause?: (cause: string) => void },
 ): boolean
 ```
 
 - `log` — A log, or the slice of one a wait reads.
 - `excluded` — The test titles the request carves out, if the caller knows them.
-- `options` — `finalOnly` reads only a failure the run has finished with; `noRetries` says the command proves the run cannot retry (`--retries=0`), so its first failure is final.
+- `options` — `finalOnly` reads only a failure the run has finished with; `noRetries` says the command proves the run cannot retry (`--retries=0`), so its first failure is final. `onCause` receives each distinct normalized native error from the matching bodies.
 
 **Returns:** True when a `✘` row's own test, outside the request's exclusions, has a failure body under it — and, with `finalOnly`, that failure is final in the log read so far.
 
@@ -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 Native locator/assertion failures and timed-out browser operations, 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,CA4C7B"}

package/dist/playwright-feedback-reporter.js

@@ -0,0 +1,85 @@
+/**
+ * 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 Native locator/assertion failures and timed-out browser operations, 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] ??
+                // A UI loop can exhaust the test budget between actions. Playwright then names
+                // page.waitForTimeout/locator.count rather than a locator. That is still the
+                // supplied test's real failure, with its native location and page snapshot.
+                (/Test timeout of \d+ms exceeded\./.test(error)
+                    ? /(?:^|\n)Error: ((?:page|locator)\.[\w.]+):/.exec(error)?.[1]
+                    : undefined);
+            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"}