@molecule/api-ai-tools 1.16.7 → 1.17.0

package/dist/command-plan.js

@@ -0,0 +1,116 @@
+/** Logical commands and ordered log boundaries for launchers that execute opaque wrappers. */
+import { randomUUID } from 'node:crypto';
+import { gunzipSync, gzipSync } from 'node:zlib';
+const HEADER = '# mol-command-plan-v1 ';
+const TRUNCATED = '__MOL_COMMAND_LOG_TRUNCATED__';
+/**
+ * Give already-prepared logical commands unique log boundaries.
+ * @param steps - Commands in execution order.
+ * @returns Metadata for the wrapper and the launcher that executes its steps.
+ */
+export function createCommandPlan(steps) {
+    const id = randomUUID();
+    return {
+        id,
+        steps: steps.map((step, index) => ({
+            ...step,
+            startMarker: `__MOL_COMMAND_STEP_${id}_${index}_START__`,
+            endMarker: `__MOL_COMMAND_STEP_${id}_${index}_END__`,
+        })),
+    };
+}
+/**
+ * Preserve a wrapper's typed logical plan in its durable shell script, including across restarts.
+ * Shell comments keep this independent of the wrapper's executable, arguments and payload format.
+ * @param command - Executed wrapper.
+ * @param plan - Commands the launcher will actually execute and delimit.
+ * @returns A shell command with a passive metadata header.
+ */
+export function commandWithPlan(command, plan) {
+    return `${HEADER}${gzipSync(JSON.stringify(plan)).toString('base64')}\n${command}`;
+}
+/**
+ * Read the shared descriptor, never a launcher's private wrapper format.
+ * @param command - Command or recovered task script.
+ * @returns A valid logical plan, or null for an ordinary command.
+ */
+export function commandPlan(command) {
+    const header = command.split('\n').find((line) => line.startsWith(HEADER));
+    if (!header || header.length > 1024 * 1024)
+        return null;
+    try {
+        const plan = JSON.parse(gunzipSync(Buffer.from(header.slice(HEADER.length), 'base64'), {
+            maxOutputLength: 1024 * 1024,
+        }).toString('utf8'));
+        if (!plan ||
+            !/^[a-f0-9-]{36}$/.test(plan.id) ||
+            !Array.isArray(plan.steps) ||
+            plan.steps.length === 0 ||
+            !plan.steps.every((step, index) => typeof step?.id === 'string' &&
+                typeof step.command === 'string' &&
+                step.startMarker === `__MOL_COMMAND_STEP_${plan.id}_${index}_START__` &&
+                step.endMarker === `__MOL_COMMAND_STEP_${plan.id}_${index}_END__`))
+            return null;
+        return plan;
+    }
+    catch (_error) {
+        // Metadata is advisory. An absent or malformed descriptor supplies no logical commands.
+        return null;
+    }
+}
+/**
+ * Commands a wrapper will run, for static classification; live diagnostics use commandStepView.
+ * @param command - Executed command.
+ * @returns Logical commands in order, or the direct command unchanged.
+ */
+export function logicalCommandText(command) {
+    return (commandPlan(command)
+        ?.steps.map((step) => step.command)
+        .join(';\n') ?? command);
+}
+/**
+ * Select only the step that owns the latest log boundary. Completed steps cannot supply a live
+ * failure, target, retry policy, file selection or rerun. Before the first boundary and between
+ * steps the live command is unknown; no diagnostic is permitted.
+ * @param command - Wrapper or direct command.
+ * @param output - Whole log, or the boundary-preserving bounded read.
+ * @returns Active command and its output, plus whether the entire step's output is available.
+ */
+export function commandStepView(command, output) {
+    const plan = commandPlan(command);
+    if (!plan)
+        return { command, output, complete: true };
+    let at = -1;
+    let selected;
+    let offset = 0;
+    for (const line of output.split('\n')) {
+        for (const step of plan.steps) {
+            if (line === step.startMarker || line === step.endMarker) {
+                at = offset + line.length + 1;
+                selected = line === step.startMarker ? step : undefined;
+            }
+        }
+        offset += line.length + 1;
+    }
+    const text = selected && at >= 0 ? output.slice(at) : '';
+    return {
+        stepKey: selected?.startMarker,
+        command: selected?.command ?? '',
+        output: text.replace(`${TRUNCATED}\n`, ''),
+        complete: !text.startsWith(TRUNCATED),
+    };
+}
+/**
+ * AWK program for a bounded read that retains the active boundary even after a long step and
+ * discards prior steps. A truncated step cannot establish a universal failure across its history.
+ * @param plan - Logical plan whose boundaries the launcher emits.
+ * @param limit - Maximum output characters retained for diagnosis.
+ * @returns An AWK program; callers shell-quote it like every other argument.
+ */
+export function commandPlanLogRead(plan, limit) {
+    const markers = plan.steps.flatMap((step) => [step.startMarker, step.endMarker]);
+    return (`BEGIN { ${markers.map((marker) => `marks["${marker}"]=1`).join('; ')} }\n` +
+        '$0 in marks { marker=$0; text=""; cut=0; next }\n' +
+        `{ text=text $0 "\\n"; if(length(text)>${limit}) { text=substr(text,length(text)-${limit}+1); cut=1 } }\n` +
+        `END { if(marker!="") { print marker; if(cut) print "${TRUNCATED}"; printf "%s",text } }`);
+}

package/dist/index.d.ts

@@ -12,6 +12,19 @@
  * (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
+ *   execution. `commandStepView` reads the active step for diagnostics; `logicalCommandText`
+ *   exposes the planned commands for static classification. Preserve the descriptor when
+ *   wrapping again. The metadata is advisory and never establishes a completed test result.
  * - **`yieldOnFirstFailureFor`** can yield one still-running deployed task's concrete diagnostic; callers opt out after a prior wait result or unknown history.
  * - **`wait_for_task` state probes report current progress without guessing log growth.**
  *   A call shorter than one normal two-second poll omits both growth and no-growth
@@ -149,6 +162,7 @@ export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './browser-probe.js';
+export * from './command-plan.js';
 export * from './command-position.js';
 export * from './cut-run.js';
 export * from './failure-kind.js';
@@ -158,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkJG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,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,19 @@
  * (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
+ *   execution. `commandStepView` reads the active step for diagnostics; `logicalCommandText`
+ *   exposes the planned commands for static classification. Preserve the descriptor when
+ *   wrapping again. The metadata is advisory and never establishes a completed test result.
  * - **`yieldOnFirstFailureFor`** can yield one still-running deployed task's concrete diagnostic; callers opt out after a prior wait result or unknown history.
  * - **`wait_for_task` state probes report current progress without guessing log growth.**
  *   A call shorter than one normal two-second poll omits both growth and no-growth
@@ -149,6 +162,7 @@ export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './browser-probe.js';
+export * from './command-plan.js';
 export * from './command-position.js';
 export * from './cut-run.js';
 export * from './failure-kind.js';
@@ -158,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"}