@skyramp/mcp 0.3.2 → 0.3.3

package/node_modules/playwright/node_modules/playwright-core/src/server/codegen/skyramp/specReader.ts

@@ -0,0 +1,1028 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import path from 'path';
+
+import { locatorOrSelectorAsSelector } from '../../../utils/isomorphic/locatorParser';
+
+import type * as actions from '@recorder/actions';
+
+// ---------------------------------------------------------------------------
+// Spec reader (zip channel / manual recorder)
+//
+// This is the playwright-core counterpart to the MCP package's specImport.ts
+// (packages/playwright/src/mcp/skyramp/specImport.ts). The npm channel cannot
+// import modded core sources and core cannot depend on the playwright package,
+// so the parser is mirrored here alongside the JsonlReader duplication. Keep
+// the two files in sync; see project_jsonl_reader_writer_duplication for the
+// planned shared refactor.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Spec import: parse a GENERATED Skyramp test file (.spec.ts / .ts / .js /
+// .py) into the same ActionInContext[] that parseJsonl produces, so
+// skyramp_load_trace can replay a test file when the original trace zip/JSONL
+// was not kept.
+//
+// A generated spec is lossy + enriched relative to the trace it came from
+// (codegen adds waitForResponse/getValue/hydration/scaffolding and drops
+// pageGuid/timestamps/signals), so this recovers the REPLAYABLE INTERACTION
+// SKELETON, not a byte-faithful re-record. Every statement is either parsed
+// into an action, consumed as a binding, dropped as known scaffolding, or
+// reported in `diagnostics` — never silently skipped.
+//
+// Locator source → selector conversion is delegated to the upstream
+// isomorphic locatorParser (the "Pick locator" engine), which understands the
+// full locator grammar in both javascript and python. Only the statement-level
+// vocabulary (a finite set emitted by the Go codegen, see
+// fixes-contexts/loadtrace-from-spec-plan.md) is parsed here.
+// ---------------------------------------------------------------------------
+
+const TEST_ID_ATTRIBUTE = 'data-testid';
+
+export type SpecLanguage = 'javascript' | 'python';
+
+export type SpecDiagnostic = {
+  /** 1-based line number of the statement's first line in the spec file. */
+  line: number;
+  /** The statement text (truncated for display). */
+  text: string;
+  reason: string;
+};
+
+export type SpecImportResult = {
+  actions: actions.ActionInContext[];
+  diagnostics: SpecDiagnostic[];
+};
+
+/** Infer the spec language from a file path (.py → python, .ts/.js → javascript). */
+export function specLanguageForPath(specPath: string): SpecLanguage | undefined {
+  if (specPath.endsWith('.py'))
+    return 'python';
+  if (specPath.endsWith('.ts') || specPath.endsWith('.js') || specPath.endsWith('.mjs') || specPath.endsWith('.cjs'))
+    return 'javascript';
+  return undefined;
+}
+
+/**
+ * Parse a generated test file into replayable actions.
+ * `specDir` resolves relative upload paths (`path.join(__dirname, ...)` /
+ * `os.path.join(os.path.dirname(__file__), ...)`).
+ */
+export function specToActions(content: string, language: SpecLanguage, specDir?: string): SpecImportResult {
+  const dir = specDir ?? '.';
+  return language === 'python'
+    ? new PySpecParser(content, dir).parse()
+    : new JsSpecParser(content, dir).parse();
+}
+
+// ---------------------------------------------------------------------------
+// Statement scanning
+// ---------------------------------------------------------------------------
+
+type Statement = { text: string, line: number, indent: number };
+
+/**
+ * Join physical lines into logical statements by tracking bracket depth
+ * outside string literals (generated specs span statements across lines only
+ * inside (), {} or [] — e.g. multi-line playwrightRequestN object literals).
+ * `indent` is the first physical line's leading whitespace width (used by the
+ * Python parser to skip non-test function bodies).
+ */
+function scanStatements(content: string, commentPrefix: string): Statement[] {
+  const statements: Statement[] = [];
+  let buffer = '';
+  let startLine = 0;
+  let indent = 0;
+  let depth = 0;
+
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i].trim();
+    if (!buffer) {
+      if (!raw || raw.startsWith(commentPrefix))
+        continue;
+      startLine = i + 1;
+      indent = lines[i].length - lines[i].trimStart().length;
+    }
+    buffer = buffer ? `${buffer} ${raw}` : raw;
+    depth = bracketDepth(buffer);
+    // The JS test-function opener (`test('testUi', async ({ page }) => {`)
+    // opens a brace that only closes at the very end of the file — flush it as
+    // its own (scaffolding) statement instead of swallowing the whole body.
+    // Same for the matching closers (`});`), whose depth goes negative.
+    if (depth > 0 && !/^test\(/.test(buffer))
+      continue;
+    statements.push({ text: buffer, line: startLine, indent });
+    buffer = '';
+  }
+  if (buffer)
+    statements.push({ text: buffer, line: startLine, indent });
+  return statements;
+}
+
+/** Net bracket depth of `text`, ignoring brackets inside string literals. */
+function bracketDepth(text: string): number {
+  let depth = 0;
+  let quote: string | undefined;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\')
+        i++;
+      else if (c === quote)
+        quote = undefined;
+      continue;
+    }
+    if (c === '\'' || c === '"' || c === '`')
+      quote = c;
+    else if (c === '(' || c === '{' || c === '[')
+      depth++;
+    else if (c === ')' || c === '}' || c === ']')
+      depth--;
+  }
+  return depth;
+}
+
+// Keyboard modifier names → the recorder's bitmask (skyRampExport
+// modifiersArrayToMask: Alt=1, Control=2, Meta=4, Shift=8; ControlOrMeta=6).
+const MODIFIER_MASKS: Record<string, number> = {
+  'Alt': 1, 'Control': 2, 'Meta': 4, 'Shift': 8, 'ControlOrMeta': 6,
+};
+
+// ---------------------------------------------------------------------------
+// Shared parser state + emission (language-specific statement matching lives
+// in the subclasses)
+// ---------------------------------------------------------------------------
+
+abstract class SpecParserBase {
+  protected _statements: Statement[];
+  protected _specDir: string;
+  protected _actions: actions.ActionInContext[] = [];
+  protected _diagnostics: SpecDiagnostic[] = [];
+  // const playwrightRequestN / expectedPayloadN = {...} — data bindings whose
+  // values are inlined where getValue() references them.
+  protected _bindings = new Map<string, any>();
+  // Variables that hold pages (test fixture `page` + pageN/popupPage
+  // declarations). Value is the pageAlias used in the emitted actions.
+  protected _pageAliases = new Map<string, string>([['page', 'page']]);
+  // Variables consumed by the waitForResponse / fileChooser patterns.
+  protected _promiseVars = new Set<string>();
+  // A pending expect-filechooser: the next click is the chooser trigger and is
+  // folded into the fileChooser action (replay performs the trigger click
+  // itself — see loadTraceTool performClientAction).
+  protected _pendingFileChooser = false;
+  protected _heldChooserTrigger: { selector: string, framePath: string[], pageAlias: string } | undefined;
+
+  /** locatorParser language + the pattern that splits iframe frame hops. */
+  protected abstract readonly _locatorLanguage: 'javascript' | 'python';
+  protected abstract readonly _frameHopSplit: RegExp;
+
+  constructor(statements: Statement[], specDir: string) {
+    this._statements = statements;
+    this._specDir = specDir;
+  }
+
+  parse(): SpecImportResult {
+    for (const stmt of this._statements)
+      this._parseStatement(stmt);
+    if (this._pendingFileChooser)
+      this._diagnostics.push({ line: 0, text: 'expect filechooser', reason: 'file chooser was opened but no setFiles/set_files followed' });
+    return { actions: this._actions, diagnostics: this._diagnostics };
+  }
+
+  protected abstract _parseStatement(stmt: Statement): void;
+
+  protected _diag(stmt: Statement, reason: string) {
+    this._diagnostics.push({ line: stmt.line, text: stmt.text.length > 120 ? stmt.text.slice(0, 117) + '...' : stmt.text, reason });
+  }
+
+  protected _push(pageAlias: string, framePath: string[], action: Record<string, any>) {
+    const index = this._actions.length;
+    this._actions.push({
+      frame: { pageGuid: '', pageAlias, framePath },
+      action: { signals: [], timestamp: String(index + 1), ...action } as unknown as actions.Action,
+      startTime: index + 1,
+    });
+  }
+
+  /**
+   * Split a locator chain into iframe frame hops + leaf, converting each part
+   * to a selector via the upstream locator parser. Generated chains pierce
+   * frames only via contentFrame()/content_frame:
+   *   locator("iframe[title=\"x\"]").contentFrame().getByRole(...) →
+   *   framePath ['iframe[title="x"]'], leaf getByRole(...)
+   */
+  protected _resolveLocatorChain(chain: string): { selector: string, framePath: string[] } | undefined {
+    const segments = chain.split(this._frameHopSplit);
+    const framePath: string[] = [];
+    for (let i = 0; i < segments.length - 1; i++) {
+      const hop = locatorOrSelectorAsSelector(this._locatorLanguage, segments[i], TEST_ID_ATTRIBUTE);
+      if (!hop)
+        return undefined;
+      framePath.push(hop);
+    }
+    const leafSource = segments[segments.length - 1];
+    if (!leafSource)
+      return undefined;
+    const selector = locatorOrSelectorAsSelector(this._locatorLanguage, leafSource, TEST_ID_ATTRIBUTE);
+    if (!selector)
+      return undefined;
+    return { selector, framePath };
+  }
+
+  /** Emit the action for a parsed `<locator chain>.<method>(<args>)` statement. */
+  protected _emitLocatorAction(stmt: Statement, pageAlias: string, chain: string, method: string, args: string) {
+    const resolved = this._resolveLocatorChain(chain);
+    if (!resolved) {
+      this._diag(stmt, 'could not parse the locator chain — not replayed');
+      return;
+    }
+    const { selector, framePath } = resolved;
+
+    // A pending filechooser marks this click as the chooser trigger; it is
+    // folded into the upcoming fileChooser action instead of emitted.
+    if (method === 'click' && this._pendingFileChooser) {
+      this._pendingFileChooser = false;
+      this._heldChooserTrigger = { selector, framePath, pageAlias };
+      return;
+    }
+
+    switch (method) {
+      case 'click':
+      case 'dblclick': {
+        const opts = this._parseCallOptions(args);
+        const action: Record<string, any> = { name: 'click', selector, button: opts.button ?? 'left', modifiers: opts.modifiers ?? 0, clickCount: method === 'dblclick' ? 2 : (opts.clickCount ?? 1) };
+        if (opts.position)
+          action.position = opts.position;
+        this._push(pageAlias, framePath, action);
+        return;
+      }
+      case 'hover': {
+        const opts = this._parseCallOptions(args);
+        const action: Record<string, any> = { name: 'hover', selector };
+        if (opts.position)
+          action.position = opts.position;
+        this._push(pageAlias, framePath, action);
+        return;
+      }
+      case 'fill':
+      case 'pressSequentially': {
+        const text = this._resolveStringArg(args);
+        if (text === undefined) {
+          this._diag(stmt, `could not resolve the ${method}() argument — not replayed`);
+          return;
+        }
+        this._push(pageAlias, framePath, { name: method, selector, text });
+        return;
+      }
+      case 'press': {
+        const shortcut = this._resolveStringArg(args);
+        if (shortcut === undefined) {
+          this._diag(stmt, 'could not resolve the press() argument — not replayed');
+          return;
+        }
+        // "Shift+Enter" → key Enter + modifier mask, mirroring the JSONL shape.
+        const parts = shortcut.split('+');
+        const key = parts.pop()!;
+        let modifiers = 0;
+        for (const p of parts)
+          modifiers |= MODIFIER_MASKS[p] ?? 0;
+        this._push(pageAlias, framePath, { name: 'press', selector, key, modifiers });
+        return;
+      }
+      case 'check':
+      case 'uncheck':
+        this._push(pageAlias, framePath, { name: method, selector });
+        return;
+      case 'select': {
+        const options = this._parseStringArray(args);
+        if (!options) {
+          this._diag(stmt, 'could not resolve the select option argument — not replayed');
+          return;
+        }
+        this._push(pageAlias, framePath, { name: 'select', selector, options });
+        return;
+      }
+      case 'setInputFiles': {
+        this._push(pageAlias, framePath, { name: 'setInputFiles', selector, files: this._parseFileArgs(args) });
+        return;
+      }
+      case 'dragTo': {
+        // Argument is a locator expression on a page variable.
+        const targetMatch = args.match(/^\s*(\w+)\.([\s\S]+?)\s*(?:,\s*\{[\s\S]*\})?$/);
+        const target = targetMatch && this._pageAliases.has(targetMatch[1]) ? this._resolveLocatorChain(targetMatch[2]) : undefined;
+        if (!target) {
+          this._diag(stmt, 'could not parse the drag target locator — not replayed');
+          return;
+        }
+        this._push(pageAlias, framePath, { name: 'dragTo', selector, target: target.selector });
+        return;
+      }
+    }
+  }
+
+  /**
+   * Emit the bare assertApiRequest MARKER for a checkRequestPayload statement.
+   * The payload assertion cannot execute during replay (no primitive), but its
+   * trace-side representation is just a marker whose payload/URL live in the
+   * HAR — the Go codegen re-correlates them at generate time. Emitting the
+   * marker means a combined export + regenerate keeps the assertion instead of
+   * silently losing it (SKYR-4083). Attributed to the last action's tab (the
+   * statement itself names no page).
+   */
+  protected _emitApiRequestMarker(stmt: Statement) {
+    const pageAlias = this._actions.length ? this._actions[this._actions.length - 1].frame.pageAlias : 'page';
+    this._push(pageAlias, [], { name: 'assertApiRequest' });
+    this._diag(stmt, 'payload assertion is not executed during replay; preserved as an assertApiRequest marker for export/regeneration');
+  }
+
+  /** Emit the fileChooser action for a setFiles/set_files on a chooser variable. */
+  protected _emitSetFiles(stmt: Statement, args: string) {
+    const trigger = this._heldChooserTrigger;
+    this._heldChooserTrigger = undefined;
+    if (!trigger) {
+      this._diag(stmt, 'setFiles without a preceding chooser trigger click — not replayed');
+      return;
+    }
+    this._push(trigger.pageAlias, trigger.framePath, { name: 'fileChooser', selector: trigger.selector, files: this._parseFileArgs(args) });
+  }
+
+  /** Emit the assert/visualSnapshot action for an expect() statement. */
+  protected _emitExpect(stmt: Statement, subject: string, matcher: 'assertText' | 'assertTextSub' | 'assertValue' | 'assertChecked' | 'assertVisible' | 'screenshot', args: string) {
+    if (matcher === 'screenshot') {
+      this._emitScreenshot(stmt, subject, args);
+      return;
+    }
+
+    // Subject must be a locator on a known page variable.
+    const subjMatch = subject.match(/^(\w+)\.([\s\S]+)$/);
+    const resolved = subjMatch && this._pageAliases.has(subjMatch[1]) ? this._resolveLocatorChain(subjMatch[2]) : undefined;
+    if (!resolved) {
+      this._diag(stmt, 'could not parse the expect() subject locator — not replayed');
+      return;
+    }
+    const { selector, framePath } = resolved;
+    const pageAlias = this._pageAliases.get(subjMatch![1])!;
+
+    switch (matcher) {
+      case 'assertText':
+      case 'assertTextSub': {
+        const text = this._resolveStringArg(args);
+        if (text === undefined) {
+          this._diag(stmt, 'could not resolve the text assertion argument — not replayed');
+          return;
+        }
+        this._push(pageAlias, framePath, { name: 'assertText', selector, text, substring: matcher === 'assertTextSub' });
+        return;
+      }
+      case 'assertValue': {
+        const value = this._resolveStringArg(args);
+        if (value === undefined) {
+          this._diag(stmt, 'could not resolve the value assertion argument — not replayed');
+          return;
+        }
+        this._push(pageAlias, framePath, { name: 'assertValue', selector, value });
+        return;
+      }
+      case 'assertChecked':
+        this._push(pageAlias, framePath, { name: 'assertChecked', selector, checked: !/checked\s*[:=]\s*(false|False)/.test(args) });
+        return;
+      case 'assertVisible':
+        this._push(pageAlias, framePath, { name: 'assertVisible', selector });
+        return;
+    }
+  }
+
+  private _emitScreenshot(stmt: Statement, subject: string, args: string) {
+    const filenameMatch = args.match(/^\s*(["'])((?:[^\\]|\\.)*?)\1/);
+    const filename = filenameMatch ? unescapeString(filenameMatch[2]) : '';
+    const fullPage = /full_?[pP]age\s*[:=]\s*(true|True)/.test(args);
+    const clipMatch = args.match(/clip\s*[:=]\s*(\{[^}]*\})/);
+
+    // expect(page).toHaveScreenshot → page (or region when clipped).
+    if (this._pageAliases.has(subject.trim())) {
+      const pageAlias = this._pageAliases.get(subject.trim())!;
+      if (clipMatch)
+        this._push(pageAlias, [], { name: 'visualSnapshot', snapshotType: 'region', filename, clip: parseLooseObject(clipMatch[1]) });
+      else
+        this._push(pageAlias, [], { name: 'visualSnapshot', snapshotType: 'page', filename, ...(fullPage ? { fullPage: true } : {}) });
+      return;
+    }
+
+    // expect(page.<locator>).toHaveScreenshot → element.
+    const subjMatch = subject.match(/^(\w+)\.([\s\S]+)$/);
+    const resolved = subjMatch && this._pageAliases.has(subjMatch[1]) ? this._resolveLocatorChain(subjMatch[2]) : undefined;
+    if (!resolved) {
+      this._diag(stmt, 'could not parse the screenshot subject locator — not replayed');
+      return;
+    }
+    this._push(this._pageAliases.get(subjMatch![1])!, resolved.framePath, { name: 'visualSnapshot', snapshotType: 'element', selector: resolved.selector, filename });
+  }
+
+  /** Emit page.mouse.* actions (coordinates + kwargs are language-neutral). */
+  protected _emitMouse(stmt: Statement, pageAlias: string, method: string, args: string) {
+    const nums = [...args.matchAll(/-?\d+(?:\.\d+)?/g)].map(m => Number(m[0]));
+    switch (method) {
+      case 'move': {
+        if (nums.length < 2)
+          break;
+        const stepsMatch = args.match(/steps\s*[:=]\s*(\d+)/);
+        const action: Record<string, any> = { name: 'mouse.move', position: { x: nums[0], y: nums[1] } };
+        if (stepsMatch)
+          action.steps = Number(stepsMatch[1]);
+        this._push(pageAlias, [], action);
+        return;
+      }
+      case 'down':
+      case 'up': {
+        const buttonMatch = args.match(/button\s*[:=]\s*["'](\w+)["']/);
+        const action: Record<string, any> = { name: `mouse.${method}` };
+        if (buttonMatch)
+          action.button = buttonMatch[1];
+        this._push(pageAlias, [], action);
+        return;
+      }
+      case 'wheel': {
+        if (nums.length < 2)
+          break;
+        this._push(pageAlias, [], { name: 'mouse.wheel', position: { x: 0, y: 0 }, deltaX: nums[0], deltaY: nums[1], modifiers: 0 });
+        return;
+      }
+      case 'click': {
+        if (nums.length < 2)
+          break;
+        this._push(pageAlias, [], { name: 'click', selector: 'body', position: { x: nums[0], y: nums[1] }, button: 'left', modifiers: 0, clickCount: 1 });
+        return;
+      }
+    }
+    this._diag(stmt, `could not parse mouse.${method}() arguments — not replayed`);
+  }
+
+  // --- Argument helpers (subclasses provide the getValue call shape) --------
+
+  /** The data-binding accessor pattern, e.g. getValue(x, "k") / skyramp.get_value(x, "k"). */
+  protected abstract _matchGetValue(args: string): { binding: string, key: string } | undefined;
+
+  /**
+   * Resolve a single string-valued call argument: a literal, or a
+   * getValue(playwrightRequestN, "key") reference whose value is inlined from
+   * the tracked binding.
+   */
+  protected _resolveStringArg(args: string): string | undefined {
+    const literal = args.match(/^\s*(["'])((?:[^\\]|\\.|(?!\1).)*?)\1\s*$/s);
+    if (literal)
+      return unescapeString(literal[2]);
+
+    const getValue = this._matchGetValue(args);
+    if (getValue) {
+      const binding = this._bindings.get(getValue.binding);
+      if (binding === undefined)
+        return undefined;
+      // The key is a gjson-style path; generated UI specs use flat keys, but
+      // resolve dotted paths for safety.
+      let value: any = binding;
+      for (const part of getValue.key.split('.'))
+        value = value?.[part];
+      if (value === undefined)
+        return undefined;
+      return String(value);
+    }
+    return undefined;
+  }
+
+  /** Parse select-option args: a string literal or an array of string literals. */
+  protected _parseStringArray(args: string): string[] | undefined {
+    const single = this._resolveStringArg(args);
+    if (single !== undefined)
+      return [single];
+    const arrayMatch = args.match(/^\s*\[([\s\S]*)\]\s*$/);
+    if (arrayMatch)
+      return [...arrayMatch[1].matchAll(/(["'])((?:[^\\]|\\.|(?!\1).)*?)\1/g)].map(m => unescapeString(m[2]));
+    return undefined;
+  }
+
+  /**
+   * Parse setFiles/set_input_files arguments into file paths. Generated specs
+   * emit a spec-relative join (`path.join(__dirname, 'fixtures', "data.csv")`
+   * / `os.path.join(os.path.dirname(__file__), ...)`) — resolved against the
+   * spec file's directory — or plain string literals.
+   */
+  protected _parseFileArgs(args: string): string[] {
+    const files: string[] = [];
+    const joinRe = /(?:path\.join\(\s*__dirname|os\.path\.join\(\s*os\.path\.dirname\(__file__\))\s*((?:,\s*(["'])(?:[^\\]|\\.)*?\2\s*)+)\)/g;
+    let joinMatch: RegExpExecArray | null;
+    let rest = args;
+    while ((joinMatch = joinRe.exec(args))) {
+      const parts = [...joinMatch[1].matchAll(/(["'])((?:[^\\]|\\.)*?)\1/g)].map(m => unescapeString(m[2]));
+      files.push(path.join(this._specDir, ...parts));
+      rest = rest.replace(joinMatch[0], '');
+    }
+    for (const m of rest.matchAll(/(["'])((?:[^\\]|\\.)*?)\1/g)) {
+      const p = unescapeString(m[2]);
+      files.push(path.isAbsolute(p) ? p : path.join(this._specDir, p));
+    }
+    return files;
+  }
+
+  /** Parse the trailing options of a click/hover call (button, clickCount/click_count, position, modifiers). */
+  protected _parseCallOptions(args: string): { button?: 'left' | 'middle' | 'right', clickCount?: number, position?: { x: number, y: number }, modifiers?: number } {
+    const out: { button?: 'left' | 'middle' | 'right', clickCount?: number, position?: { x: number, y: number }, modifiers?: number } = {};
+    const buttonMatch = args.match(/button\s*[:=]\s*["'](left|middle|right)["']/);
+    if (buttonMatch)
+      out.button = buttonMatch[1] as 'left' | 'middle' | 'right';
+    const clickCountMatch = args.match(/click_?[cC]ount\s*[:=]\s*(\d+)/);
+    if (clickCountMatch)
+      out.clickCount = Number(clickCountMatch[1]);
+    const positionMatch = args.match(/position\s*[:=]\s*(\{[^}]*\})/);
+    if (positionMatch) {
+      const pos = parseLooseObject(positionMatch[1]);
+      if (typeof pos.x === 'number' && typeof pos.y === 'number')
+        out.position = { x: pos.x, y: pos.y };
+    }
+    const modifiersMatch = args.match(/modifiers\s*[:=]\s*\[([^\]]*)\]/);
+    if (modifiersMatch) {
+      let mask = 0;
+      for (const m of modifiersMatch[1].matchAll(/["'](\w+)["']/g))
+        mask |= MODIFIER_MASKS[m[1]] ?? 0;
+      out.modifiers = mask;
+    }
+    return out;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JS/TS parser (TypeScript specs differ from JavaScript only in imports and
+// type annotations, which the matchers below ignore)
+// ---------------------------------------------------------------------------
+
+// Statements that are pure scaffolding — dropped without a diagnostic.
+const JS_SCAFFOLDING: RegExp[] = [
+  /^import\b/,
+  /^const\s+.*=\s*require\(/,
+  /^const\s+pageTimeout\b/,
+  /^test\(/,
+  /^test\.setTimeout\(/,
+  /^test\.use\(/,
+  /^\}\)?;?$/,
+  /^(await\s+)?\w+\.setDefaultTimeout\(/,
+  /^page\s*=\s*newSkyrampPlaywrightPage\(/,
+  /^'use strict'/,
+];
+
+const JS_LOCATOR_METHODS = 'click|dblclick|hover|fill|press|pressSequentially|check|uncheck|selectOption|setInputFiles|dragTo';
+
+// Spec method name → the canonical action-dispatch key used by _emitLocatorAction.
+const JS_METHOD_MAP: Record<string, string> = {
+  selectOption: 'select',
+  dragTo: 'dragTo',
+  setInputFiles: 'setInputFiles',
+};
+
+class JsSpecParser extends SpecParserBase {
+  protected override readonly _locatorLanguage = 'javascript' as const;
+  protected override readonly _frameHopSplit = /\.contentFrame\(\)\.?/;
+
+  constructor(content: string, specDir: string) {
+    super(scanStatements(content, '//'), specDir);
+  }
+
+  protected override _matchGetValue(args: string): { binding: string, key: string } | undefined {
+    const m = args.match(/^\s*getValue\(\s*(\w+)\s*,\s*(["'])((?:[^\\]|\\.)*?)\2\s*\)(\.toString\(\))?\s*$/);
+    return m ? { binding: m[1], key: unescapeString(m[3]) } : undefined;
+  }
+
+  protected override _parseStatement(stmt: Statement) {
+    const text = stmt.text.replace(/;$/, '');
+
+    for (const re of JS_SCAFFOLDING) {
+      if (re.test(text))
+        return;
+    }
+
+    // --- Bindings ---------------------------------------------------------
+
+    // const playwrightRequestN(: <type>)? = {...} / const expectedPayloadN = {...}
+    const bindingMatch = text.match(/^const\s+(\w+)\s*(?::[^=]+)?=\s*(\{[\s\S]*\})$/);
+    if (bindingMatch) {
+      try {
+        this._bindings.set(bindingMatch[1], JSON.parse(bindingMatch[2]));
+      } catch {
+        this._diag(stmt, 'object literal is not plain JSON; getValue() references to it cannot be inlined');
+        this._bindings.set(bindingMatch[1], undefined);
+      }
+      return;
+    }
+
+    // const responsePromiseN = page.waitForResponse("...") — network
+    // correlation added by codegen from the HAR; there is no replay primitive,
+    // so it is consumed (the triggering action itself is preserved).
+    const responsePromiseMatch = text.match(/^const\s+(\w+)\s*=\s*(\w+)\.waitForResponse\(/);
+    if (responsePromiseMatch) {
+      this._promiseVars.add(responsePromiseMatch[1]);
+      this._diag(stmt, 'waitForResponse is a codegen enrichment with no replay primitive — not replayed');
+      return;
+    }
+
+    // const fileChooserPromiseN = page.waitForEvent("filechooser") — the next
+    // click is the chooser trigger; hold it for the setFiles statement.
+    const chooserPromiseMatch = text.match(/^const\s+(\w+)\s*=\s*(\w+)\.waitForEvent\(\s*["']filechooser["']\s*\)/);
+    if (chooserPromiseMatch) {
+      this._promiseVars.add(chooserPromiseMatch[1]);
+      this._pendingFileChooser = true;
+      return;
+    }
+
+    // const responseN = await responsePromiseN / const fileChooserN = await fileChooserPromiseN
+    const awaitPromiseMatch = text.match(/^const\s+(\w+)\s*=\s*await\s+(\w+)$/);
+    if (awaitPromiseMatch && this._promiseVars.has(awaitPromiseMatch[2])) {
+      this._promiseVars.add(awaitPromiseMatch[1]);
+      return;
+    }
+
+    // const page1 = await page.context().newPage()
+    const newPageMatch = text.match(/^const\s+(\w+)\s*=\s*await\s+(\w+)\.context\(\)\.newPage\(\)$/);
+    if (newPageMatch) {
+      this._pageAliases.set(newPageMatch[1], newPageMatch[1]);
+      this._push(newPageMatch[1], [], { name: 'openPage', url: 'about:blank' });
+      return;
+    }
+
+    // const popupPage = await page.waitForPage('/match/') — SkyrampPlaywrightPage
+    // popup binding. Register the alias; the load-trace popup machinery binds it
+    // to a live tab at replay time.
+    const waitForPageMatch = text.match(/^const\s+(\w+)\s*=\s*await\s+(\w+)\.waitForPage\(/);
+    if (waitForPageMatch) {
+      this._pageAliases.set(waitForPageMatch[1], waitForPageMatch[1]);
+      this._push(waitForPageMatch[1], [], { name: 'openPage', url: 'about:blank' });
+      return;
+    }
+
+    // fileChooserN.setFiles(...) → the held trigger click + files become one
+    // fileChooser action (replay clicks the trigger and sets the files).
+    const setFilesMatch = text.match(/^await\s+(\w+)\.setFiles\(([\s\S]*)\)$/);
+    if (setFilesMatch && this._promiseVars.has(setFilesMatch[1])) {
+      this._emitSetFiles(stmt, setFilesMatch[2]);
+      return;
+    }
+
+    // checkRequestPayload(...) — network payload assertion. Not executable at
+    // replay time, but preserved as an assertApiRequest marker (SKYR-4083).
+    if (/^(await\s+)?checkRequestPayload\(/.test(text)) {
+      this._emitApiRequestMarker(stmt);
+      return;
+    }
+
+    // --- Actions ----------------------------------------------------------
+
+    // await page.goto("URL")
+    const gotoMatch = text.match(/^await\s+(\w+)\.goto\(\s*(["'])((?:[^\\]|\\.)*?)\2/);
+    if (gotoMatch && this._pageAliases.has(gotoMatch[1])) {
+      this._push(this._pageAliases.get(gotoMatch[1])!, [], { name: 'navigate', url: unescapeString(gotoMatch[3]) });
+      return;
+    }
+
+    // await page.waitForTimeout(N) — hydration/settle wait; replayable, kept.
+    const waitTimeoutMatch = text.match(/^await\s+(\w+)\.waitForTimeout\(\s*(\d+)\s*\)$/);
+    if (waitTimeoutMatch && this._pageAliases.has(waitTimeoutMatch[1])) {
+      this._push(this._pageAliases.get(waitTimeoutMatch[1])!, [], { name: 'waitForTimeout', duration: Number(waitTimeoutMatch[2]) });
+      return;
+    }
+
+    // await page.evaluate(<function source>) — browser_evaluate replay
+    // (SKYR-3831/3914). The argument is an unquoted function literal; the
+    // replay engine IIFE-wraps the source string.
+    const evaluateMatch = text.match(/^await\s+(\w+)\.evaluate\(([\s\S]*)\)$/);
+    if (evaluateMatch && this._pageAliases.has(evaluateMatch[1])) {
+      this._push(this._pageAliases.get(evaluateMatch[1])!, [], { name: 'evaluate', expression: evaluateMatch[2].trim() });
+      return;
+    }
+
+    // await pageN.close()
+    const closeMatch = text.match(/^await\s+(\w+)\.close\(\)$/);
+    if (closeMatch && this._pageAliases.has(closeMatch[1])) {
+      this._push(this._pageAliases.get(closeMatch[1])!, [], { name: 'closePage' });
+      return;
+    }
+
+    // await page.mouse.move/down/up/wheel(...)
+    const mouseMatch = text.match(/^await\s+(\w+)\.mouse\.(move|down|up|wheel|click)\(([\s\S]*)\)$/);
+    if (mouseMatch && this._pageAliases.has(mouseMatch[1])) {
+      this._emitMouse(stmt, this._pageAliases.get(mouseMatch[1])!, mouseMatch[2], mouseMatch[3]);
+      return;
+    }
+
+    // await expect(...).toHaveScreenshot / assertion matchers
+    const expectMatch = text.match(/^await\s+expect\(\s*([\s\S]+?)\s*\)\.(not\.)?(\w+)\(([\s\S]*)\)$/);
+    if (expectMatch) {
+      if (expectMatch[2]) {
+        this._diag(stmt, `negated expect matcher .not.${expectMatch[3]} has no trace equivalent — not replayed`);
+        return;
+      }
+      const matcher = ({
+        toHaveScreenshot: 'screenshot',
+        toHaveText: 'assertText',
+        toContainText: 'assertTextSub',
+        toHaveValue: 'assertValue',
+        toBeChecked: 'assertChecked',
+        toBeVisible: 'assertVisible',
+      } as const)[expectMatch[3] as string];
+      if (!matcher) {
+        this._diag(stmt, `expect matcher .${expectMatch[3]}() has no trace equivalent — not replayed`);
+        return;
+      }
+      this._emitExpect(stmt, expectMatch[1], matcher, expectMatch[4]);
+      return;
+    }
+
+    // await <pageVar>.<locator chain>.<action>(<args>)
+    const actionMatch = text.match(new RegExp(`^await\\s+(\\w+)\\.([\\s\\S]+)\\.(${JS_LOCATOR_METHODS})\\(([\\s\\S]*)\\)$`));
+    if (actionMatch && this._pageAliases.has(actionMatch[1])) {
+      this._emitLocatorAction(stmt, this._pageAliases.get(actionMatch[1])!, actionMatch[2], JS_METHOD_MAP[actionMatch[3]] ?? actionMatch[3], actionMatch[4]);
+      return;
+    }
+
+    this._diag(stmt, 'unrecognized statement — not replayed');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Python parser (pytest specs from `skyramp generate --language python`).
+// Sync API: no await; `with` blocks wrap network/file-chooser expectations and
+// their INDENTED BODIES contain real actions, parsed like any other statement.
+// ---------------------------------------------------------------------------
+
+const PY_SCAFFOLDING: RegExp[] = [
+  /^import\b/,
+  /^from\s+[\w.]+\s+import\b/,
+  /^@/,
+  /^def\s+test_\w+\(/,
+  /^\w+\.set_default_timeout\(/,
+  /^page\s*=\s*skyramp\.new_skyramp_playwright_page\(/,
+];
+
+// The Python emitter snake_cases method names — but has a known bug leaving
+// pressSequentially camelCase (invalid Python API, tolerated here; see
+// fixes-contexts/loadtrace-from-spec-plan.md M0 findings).
+const PY_LOCATOR_METHODS = 'click|dblclick|hover|fill|press|press_sequentially|pressSequentially|check|uncheck|select_option|set_input_files|drag_to';
+
+const PY_METHOD_MAP: Record<string, string> = {
+  press_sequentially: 'pressSequentially',
+  select_option: 'select',
+  set_input_files: 'setInputFiles',
+  drag_to: 'dragTo',
+};
+
+const PY_EXPECT_MATCHERS: Record<string, 'assertText' | 'assertTextSub' | 'assertValue' | 'assertChecked' | 'assertVisible' | 'screenshot'> = {
+  to_have_screenshot: 'screenshot',
+  to_have_text: 'assertText',
+  to_contain_text: 'assertTextSub',
+  to_have_value: 'assertValue',
+  to_be_checked: 'assertChecked',
+  to_be_visible: 'assertVisible',
+};
+
+class PySpecParser extends SpecParserBase {
+  protected override readonly _locatorLanguage = 'python' as const;
+  protected override readonly _frameHopSplit = /\.content_frame\./;
+  // Inside a non-test function body (e.g. the pytest browser_context_args
+  // fixture): statements indented deeper than this are dropped silently.
+  private _skipBlockIndent: number | undefined;
+
+  constructor(content: string, specDir: string) {
+    super(scanStatements(content, '#'), specDir);
+  }
+
+  protected override _matchGetValue(args: string): { binding: string, key: string } | undefined {
+    // skyramp.get_value(x, "k"), optionally str(...)-wrapped for numbers.
+    const m = args.match(/^\s*(?:str\(\s*)?skyramp\.get_value\(\s*(\w+)\s*,\s*(["'])((?:[^\\]|\\.)*?)\2\s*\)\s*\)?\s*$/);
+    return m ? { binding: m[1], key: unescapeString(m[3]) } : undefined;
+  }
+
+  protected override _parseStatement(stmt: Statement) {
+    // Skip the body of a non-test function (fixture defs) by indentation.
+    if (this._skipBlockIndent !== undefined) {
+      if (stmt.indent > this._skipBlockIndent)
+        return;
+      this._skipBlockIndent = undefined;
+    }
+    const defMatch = stmt.text.match(/^def\s+(\w+)\(/);
+    if (defMatch && !defMatch[1].startsWith('test_')) {
+      this._skipBlockIndent = stmt.indent;
+      return;
+    }
+
+    const text = stmt.text;
+
+    for (const re of PY_SCAFFOLDING) {
+      if (re.test(text))
+        return;
+    }
+
+    // --- with-blocks (their bodies arrive as separate statements) ----------
+
+    // with page.expect_response("...") as response_0:
+    const expectResponseMatch = text.match(/^with\s+(\w+)\.expect_response\([\s\S]*\)\s+as\s+(\w+)\s*:$/);
+    if (expectResponseMatch) {
+      this._promiseVars.add(expectResponseMatch[2]);
+      this._diag(stmt, 'waitForResponse is a codegen enrichment with no replay primitive — not replayed');
+      return;
+    }
+
+    // with page.expect_file_chooser() as file_chooser_info_0:
+    const expectChooserMatch = text.match(/^with\s+(\w+)\.expect_file_chooser\(\)\s+as\s+(\w+)\s*:$/);
+    if (expectChooserMatch) {
+      this._promiseVars.add(expectChooserMatch[2]);
+      this._pendingFileChooser = true;
+      return;
+    }
+
+    // --- Bindings ---------------------------------------------------------
+
+    // playwright_request_0 = {...} / expected_payload_1 = {...}
+    const bindingMatch = text.match(/^(\w+)\s*=\s*(\{[\s\S]*\})$/);
+    if (bindingMatch) {
+      const json = pyLiteralToJson(bindingMatch[2]);
+      try {
+        this._bindings.set(bindingMatch[1], JSON.parse(json));
+      } catch {
+        this._diag(stmt, 'dict literal could not be parsed; get_value() references to it cannot be inlined');
+        this._bindings.set(bindingMatch[1], undefined);
+      }
+      return;
+    }
+
+    // page1 = page.context.new_page()
+    const newPageMatch = text.match(/^(\w+)\s*=\s*(\w+)\.context\.new_page\(\)$/);
+    if (newPageMatch) {
+      this._pageAliases.set(newPageMatch[1], newPageMatch[1]);
+      this._push(newPageMatch[1], [], { name: 'openPage', url: 'about:blank' });
+      return;
+    }
+
+    // popup_page = page.wait_for_page('/match/')
+    const waitForPageMatch = text.match(/^(\w+)\s*=\s*(\w+)\.wait_for_page\(/);
+    if (waitForPageMatch) {
+      this._pageAliases.set(waitForPageMatch[1], waitForPageMatch[1]);
+      this._push(waitForPageMatch[1], [], { name: 'openPage', url: 'about:blank' });
+      return;
+    }
+
+    // file_chooser_0 = file_chooser_info_0.value
+    const valueMatch = text.match(/^(\w+)\s*=\s*(\w+)\.value$/);
+    if (valueMatch && this._promiseVars.has(valueMatch[2])) {
+      this._promiseVars.add(valueMatch[1]);
+      return;
+    }
+
+    // file_chooser_0.set_files(...)
+    const setFilesMatch = text.match(/^(\w+)\.set_files\(([\s\S]*)\)$/);
+    if (setFilesMatch && this._promiseVars.has(setFilesMatch[1])) {
+      this._emitSetFiles(stmt, setFilesMatch[2]);
+      return;
+    }
+
+    // skyramp.check_request_payload(...) — network payload assertion. Not
+    // executable at replay time, but preserved as an assertApiRequest marker
+    // (SKYR-4083).
+    if (/^skyramp\.check_request_payload\(/.test(text)) {
+      this._emitApiRequestMarker(stmt);
+      return;
+    }
+
+    // --- Actions ----------------------------------------------------------
+
+    // page.goto("URL")
+    const gotoMatch = text.match(/^(\w+)\.goto\(\s*(["'])((?:[^\\]|\\.)*?)\2/);
+    if (gotoMatch && this._pageAliases.has(gotoMatch[1])) {
+      this._push(this._pageAliases.get(gotoMatch[1])!, [], { name: 'navigate', url: unescapeString(gotoMatch[3]) });
+      return;
+    }
+
+    // page.wait_for_timeout(N)
+    const waitTimeoutMatch = text.match(/^(\w+)\.wait_for_timeout\(\s*(\d+)\s*\)$/);
+    if (waitTimeoutMatch && this._pageAliases.has(waitTimeoutMatch[1])) {
+      this._push(this._pageAliases.get(waitTimeoutMatch[1])!, [], { name: 'waitForTimeout', duration: Number(waitTimeoutMatch[2]) });
+      return;
+    }
+
+    // page.evaluate("<function source>") — in Python the JS function source is
+    // passed as a STRING (the sync API forwards it to the same evaluate).
+    const evaluateMatch = text.match(/^(\w+)\.evaluate\(([\s\S]*)\)$/);
+    if (evaluateMatch && this._pageAliases.has(evaluateMatch[1])) {
+      const expression = this._resolveStringArg(evaluateMatch[2]) ?? evaluateMatch[2].trim();
+      this._push(this._pageAliases.get(evaluateMatch[1])!, [], { name: 'evaluate', expression });
+      return;
+    }
+
+    // page1.close()
+    const closeMatch = text.match(/^(\w+)\.close\(\)$/);
+    if (closeMatch && this._pageAliases.has(closeMatch[1])) {
+      this._push(this._pageAliases.get(closeMatch[1])!, [], { name: 'closePage' });
+      return;
+    }
+
+    // page.mouse.move/down/up/wheel(...)
+    const mouseMatch = text.match(/^(\w+)\.mouse\.(move|down|up|wheel|click)\(([\s\S]*)\)$/);
+    if (mouseMatch && this._pageAliases.has(mouseMatch[1])) {
+      this._emitMouse(stmt, this._pageAliases.get(mouseMatch[1])!, mouseMatch[2], mouseMatch[3]);
+      return;
+    }
+
+    // expect(<subject>).<matcher>(<args>) — from skyramp import expect.
+    const expectMatch = text.match(/^expect\(\s*([\s\S]+?)\s*\)\.(not_)?(\w+)\(([\s\S]*)\)$/);
+    if (expectMatch) {
+      if (expectMatch[2]) {
+        this._diag(stmt, `negated expect matcher .not_${expectMatch[3]} has no trace equivalent — not replayed`);
+        return;
+      }
+      const matcher = PY_EXPECT_MATCHERS[expectMatch[3]];
+      if (!matcher) {
+        this._diag(stmt, `expect matcher .${expectMatch[3]}() has no trace equivalent — not replayed`);
+        return;
+      }
+      this._emitExpect(stmt, expectMatch[1], matcher, expectMatch[4]);
+      return;
+    }
+
+    // Extension-frame actions target a frame by URL (wait_for_frame) — the
+    // frame chain is not expressible in the JSONL framePath model yet.
+    if (/\bwait_for_frame\(/.test(text)) {
+      this._diag(stmt, 'wait_for_frame (extension frame) replay is not supported yet — not replayed');
+      return;
+    }
+
+    // <pageVar>.<locator chain>.<action>(<args>)
+    const actionMatch = text.match(new RegExp(`^(\\w+)\\.([\\s\\S]+)\\.(${PY_LOCATOR_METHODS})\\(([\\s\\S]*)\\)$`));
+    if (actionMatch && this._pageAliases.has(actionMatch[1])) {
+      this._emitLocatorAction(stmt, this._pageAliases.get(actionMatch[1])!, actionMatch[2], PY_METHOD_MAP[actionMatch[3]] ?? actionMatch[3], actionMatch[4]);
+      return;
+    }
+
+    this._diag(stmt, 'unrecognized statement — not replayed');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Small literal parsers
+// ---------------------------------------------------------------------------
+
+function unescapeString(text: string): string {
+  return text.replace(/\\(.)/g, (_, c) => c === 'n' ? '\n' : c === 't' ? '\t' : c === 'r' ? '\r' : c);
+}
+
+/**
+ * Convert a Python dict literal to JSON: True/False/None → true/false/null,
+ * applied outside string literals only (generated dicts are otherwise
+ * JSON-shaped: double-quoted keys/strings, numbers, nesting).
+ */
+function pyLiteralToJson(text: string): string {
+  let out = '';
+  let quote: string | undefined;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      out += c;
+      if (c === '\\')
+        out += text[++i] ?? '';
+      else if (c === quote)
+        quote = undefined;
+      continue;
+    }
+    if (c === '"' || c === '\'') {
+      quote = c;
+      out += c;
+      continue;
+    }
+    if (/\w/.test(c)) {
+      let word = c;
+      while (i + 1 < text.length && /\w/.test(text[i + 1]))
+        word += text[++i];
+      out += word === 'True' ? 'true' : word === 'False' ? 'false' : word === 'None' ? 'null' : word;
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
+/** Parse `{ x: 1, y: 2, ... }` / `{"x": 1, ...}` with number/bool values. */
+function parseLooseObject(text: string): Record<string, any> {
+  const out: Record<string, any> = {};
+  for (const m of text.matchAll(/["']?(\w+)["']?\s*[:=]\s*(-?\d+(?:\.\d+)?|true|false|True|False)/g))
+    out[m[1]] = /^true$/i.test(m[2]) ? true : /^false$/i.test(m[2]) ? false : Number(m[2]);
+  return out;
+}