playwright-intelligence-engine 0.0.0-stage → 2.0.0

package/src/authoring/llm-author.ts

@@ -0,0 +1,282 @@
+import { Project } from 'ts-morph';
+import {
+  Author,
+  AuthorInput,
+  CandidateChange,
+  FullCodeGenerationInput,
+  FullCodeGenerationProvider,
+} from './author.js';
+import { HybridAuthor } from './hybrid-author.js';
+import {
+  buildTierL2SystemPrompt,
+  FullGenerationProposal,
+  normalizeProposalPath,
+  validateFullGenerationProposal,
+} from './generation-contract.js';
+import type { NamePlan, SymbolEntry } from './naming/name-plan.js';
+import { NamePlanner } from './naming/name-planner.js';
+import { toClassName, toSlug } from '../generator/architecture-generator.js';
+
+export interface OpenAiCompatibleFullCodeProviderOptions {
+  endpoint: string;
+  model: string;
+  apiKey?: string | undefined;
+  timeoutMs?: number | undefined;
+  fetchImpl?: typeof fetch | undefined;
+}
+
+/**
+ * Provider-neutral Tier-L2 full-code Playwright generation transport.
+ */
+export class OpenAiCompatibleFullCodeProvider implements FullCodeGenerationProvider {
+  public constructor(private readonly options: OpenAiCompatibleFullCodeProviderOptions) {}
+
+  public async generate(input: FullCodeGenerationInput): Promise<unknown> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs ?? 90_000);
+    try {
+      const response = await (this.options.fetchImpl ?? fetch)(this.options.endpoint, {
+        method: 'POST',
+        signal: controller.signal,
+        headers: {
+          'content-type': 'application/json',
+          ...(this.options.apiKey ? { authorization: `Bearer ${this.options.apiKey}` } : {}),
+        },
+        body: JSON.stringify({
+          model: this.options.model,
+          temperature: 0.1,
+          response_format: { type: 'json_object' },
+          messages: [
+            { role: 'system', content: buildTierL2SystemPrompt() },
+            { role: 'user', content: JSON.stringify(input) },
+          ],
+        }),
+      });
+      if (!response.ok) {
+        throw new Error(`Tier-L2 generation model endpoint returned HTTP ${response.status}`);
+      }
+      const payload = (await response.json()) as {
+        choices?: Array<{ message?: { content?: string | Array<{ text?: string }> | null } }>;
+        output_text?: string;
+      };
+      const content =
+        payload.output_text ??
+        (typeof payload.choices?.[0]?.message?.content === 'string'
+          ? payload.choices[0].message.content
+          : payload.choices?.[0]?.message?.content?.map((part) => part.text ?? '').join(''));
+      if (!content) {
+        throw new Error('Tier-L2 generation model returned empty content');
+      }
+      return content;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+export function configuredFullCodeProvider(): FullCodeGenerationProvider | undefined {
+  const liveAllowed = !process.env.VITEST || process.env.PIE_LIVE_LLM_TESTS === '1';
+  if (!liveAllowed) return undefined;
+  const apiKey = process.env.PIE_LLM_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.DEEPSEEK_API_KEY;
+  const endpoint = process.env.PIE_LLM_ENDPOINT ?? (process.env.OPENAI_API_KEY ? 'https://api.openai.com/v1/chat/completions' : (apiKey ? 'https://api.deepseek.com/chat/completions' : undefined));
+  const model = process.env.PIE_LLM_MODEL ?? (process.env.OPENAI_API_KEY ? 'gpt-4o' : (apiKey ? 'deepseek-chat' : undefined));
+  if (!endpoint || !model) return undefined;
+  return new OpenAiCompatibleFullCodeProvider({
+    endpoint,
+    model,
+    ...(apiKey ? { apiKey } : {}),
+  });
+}
+
+function inferRoleSuffix(propertyName: string): string {
+  const lower = propertyName.toLowerCase();
+  if (lower.includes('input') || lower.includes('field')) return 'textbox';
+  if (lower.includes('button') || lower.includes('btn')) return 'button';
+  if (lower.includes('checkbox')) return 'checkbox';
+  if (lower.includes('select')) return 'combobox';
+  return 'locator';
+}
+
+function extractNamePlanFromGeneratedFiles(featureName: string, proposal: FullGenerationProposal): NamePlan {
+  const rawBase = toClassName(featureName);
+  let pageClassName = rawBase.endsWith('Page') ? rawBase : `${rawBase}Page`;
+  const symbols: SymbolEntry[] = [];
+
+  try {
+    const project = new Project({ useInMemoryFileSystem: true });
+    for (const file of proposal.files) {
+      if (!/\.tsx?$/i.test(file.path)) continue;
+      const sf = project.createSourceFile(file.path, file.content, { overwrite: true });
+      const classes = sf.getClasses();
+      const pageClass = classes.find((c) => c.getName()?.endsWith('Page')) ?? classes[0];
+      if (!pageClass) continue;
+      const clsName = pageClass.getName();
+      if (clsName) {
+        pageClassName = clsName.endsWith('Page') ? clsName : `${clsName}Page`;
+      }
+      const props = pageClass
+        .getProperties()
+        .map((p) => p.getName())
+        .filter((p) => p !== 'page');
+      const methods = pageClass.getMethods().filter((m) => m.getName() !== 'goto');
+      const usedPropNames = new Set<string>();
+
+      for (let i = 0; i < methods.length; i += 1) {
+        const methodDecl = methods[i]!;
+        const method = methodDecl.getName();
+        const bodyText = methodDecl.getBodyText() ?? '';
+        const matchedProp = props.find((p) => !usedPropNames.has(p) && new RegExp(`\\bthis\\.${p}\\b`).test(bodyText));
+        const property = matchedProp ?? `${method}Locator`;
+        usedPropNames.add(property);
+        const verbMatch = method.match(/^([a-z]+)/);
+        symbols.push({
+          ref: `ast-${i + 1}`,
+          role: inferRoleSuffix(property),
+          property,
+          method,
+          verb: verbMatch?.[1] ?? 'click',
+          confidence: 0.9,
+          source: 'llm',
+          assumptions: [],
+        });
+      }
+      if (symbols.length > 0) break;
+    }
+  } catch {
+    // Fallback below if AST extraction fails
+  }
+
+  const pageVariable = pageClassName[0]!.toLowerCase() + pageClassName.slice(1);
+  return {
+    planVersion: '1',
+    pageClassName,
+    pageVariable,
+    symbols,
+    assumptions: proposal.assumptions.map((a) => a.description),
+  };
+}
+
+export interface LlmAuthorOptions {
+  provider?: FullCodeGenerationProvider | undefined;
+}
+
+export class LlmAuthor implements Author {
+  public readonly kind = 'llm';
+  private readonly hybridFallback = new HybridAuthor();
+
+  public constructor(private readonly options: LlmAuthorOptions = {}) {}
+
+  public async propose(input: AuthorInput): Promise<CandidateChange> {
+    const provider = input.fullCodeProvider ?? this.options.provider ?? configuredFullCodeProvider();
+    if (!provider) {
+      const hybridChange = await this.hybridFallback.propose(input);
+      return {
+        ...hybridChange,
+        authorKind: 'llm',
+        fullCodeAuthoring: false,
+        usedFallback: true,
+        status: 'GENERATE',
+        rationale: 'No Tier-L2 full-code provider configured; fell back to deterministic HybridAuthor.',
+      };
+    }
+
+    const generationInput: FullCodeGenerationInput = {
+      featureName: input.featureName,
+      mode: input.mode,
+      baseUrl: input.baseUrl,
+      requirements: input.requirements,
+      steps: input.steps,
+      profile: input.profile,
+      existingFiles: input.existingFiles,
+      exemplars: input.exemplars,
+      contextPacket: input.contextPacket,
+      workflowPlan: input.workflowPlan,
+      explorationBundle: input.explorationBundle,
+      scenarios: input.scenarios,
+      existingFileSnapshots: input.existingFileSnapshots,
+      allowedEvidenceIds: input.allowedEvidenceIds,
+      feedback: input.feedback,
+    };
+
+    let rawProposal: unknown;
+    try {
+      rawProposal = await provider.generate(generationInput);
+    } catch (error) {
+      const hybridChange = await this.hybridFallback.propose(input);
+      return {
+        ...hybridChange,
+        authorKind: 'llm',
+        fullCodeAuthoring: false,
+        usedFallback: true,
+        status: 'GENERATE',
+        validationErrors: [`Tier-L2 provider failed (${error instanceof Error ? error.message : String(error)}); fell back to HybridAuthor.`],
+        rationale: `Tier-L2 provider unavailable; fell back to HybridAuthor (${error instanceof Error ? error.message : String(error)}).`,
+      };
+    }
+
+    const validation = validateFullGenerationProposal(rawProposal, {
+      allowedEvidenceIds: input.allowedEvidenceIds ? new Set(input.allowedEvidenceIds) : undefined,
+      existingFiles: input.existingFiles ? new Set(input.existingFiles) : undefined,
+      requireEvidenceReferences: input.requireEvidenceReferences,
+    });
+
+    if (!validation.isValid || !validation.proposal) {
+      return {
+        files: [],
+        symbols: NamePlanner.planNames(input.featureName, input.steps ?? [], { source: 'llm' }),
+        rationale: `Tier-L2 proposal rejected by contract validation: ${validation.errors.join('; ')}`,
+        authorKind: 'llm',
+        featureName: input.featureName,
+        slug: toSlug(input.featureName),
+        mode: input.mode,
+        status: 'ABSTAIN',
+        fullCodeAuthoring: true,
+        usedFallback: false,
+        validationErrors: validation.errors,
+      };
+    }
+
+    const proposal = validation.proposal;
+    if (proposal.status !== 'GENERATE') {
+      return {
+        files: [],
+        symbols: NamePlanner.planNames(input.featureName, input.steps ?? [], { source: 'llm' }),
+        rationale: proposal.summary,
+        authorKind: 'llm',
+        featureName: input.featureName,
+        slug: toSlug(input.featureName),
+        mode: input.mode,
+        status: proposal.status,
+        fullCodeAuthoring: true,
+        usedFallback: false,
+        proposal,
+        assumptions: proposal.assumptions.map((a) => a.description),
+        requiredClarifications: proposal.requiredClarifications,
+      };
+    }
+
+    const symbols = extractNamePlanFromGeneratedFiles(input.featureName, proposal);
+    return {
+      files: proposal.files.map((f) => ({
+        relativePath: normalizeProposalPath(f.path),
+        content: f.content,
+        purpose: f.rationale,
+        action: f.action === 'modify' ? 'MODIFY' : 'CREATE',
+        rationale: f.rationale,
+        evidenceReferences: f.evidenceReferences,
+        scenarioIds: f.scenarioIds,
+      })),
+      symbols,
+      rationale: proposal.summary,
+      authorKind: 'llm',
+      featureName: input.featureName,
+      slug: toSlug(input.featureName),
+      mode: input.mode,
+      status: 'GENERATE',
+      fullCodeAuthoring: true,
+      usedFallback: false,
+      proposal,
+      assumptions: proposal.assumptions.map((a) => a.description),
+    };
+  }
+}

package/src/authoring/naming/index.ts

@@ -0,0 +1,4 @@
+export * from './name-plan.js';
+export * from './name-planner.js';
+export * from './naming-linter.js';
+

package/src/authoring/naming/name-plan.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+export const SymbolSourceSchema = z.enum(['llm', 'heuristic']);
+export type SymbolSource = z.infer<typeof SymbolSourceSchema>;
+
+export const SymbolEntrySchema = z.object({
+  ref: z.string().min(1),
+  role: z.string().optional(),
+  accessibleName: z.string().optional(),
+  property: z.string().min(1),
+  method: z.string().min(1),
+  verb: z.string().min(1),
+  confidence: z.number().min(0).max(1),
+  source: SymbolSourceSchema,
+  assumptions: z.array(z.string()).default([]),
+  frame: z.string().optional(),
+});
+export type SymbolEntry = z.infer<typeof SymbolEntrySchema>;
+
+export const NamePlanSchema = z.object({
+  planVersion: z.literal('1').default('1'),
+  pageClassName: z.string().min(1),
+  pageVariable: z.string().min(1),
+  symbols: z.array(SymbolEntrySchema),
+  assumptions: z.array(z.string()).default([]),
+});
+export type NamePlan = z.infer<typeof NamePlanSchema>;
+

package/src/authoring/naming/name-planner.ts

@@ -0,0 +1,339 @@
+import type { GeneratedStep } from '../../generator/test-generator.js';
+import type { NamePlan, SymbolEntry } from './name-plan.js';
+
+const RESERVED_WORDS = new Set([
+  'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
+  'else', 'export', 'extends', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof',
+  'new', 'return', 'super', 'switch', 'this', 'throw', 'try', 'typeof', 'var', 'void', 'while',
+  'with', 'yield', 'enum', 'implements', 'interface', 'let', 'package', 'private', 'protected',
+  'public', 'static', 'await', 'abstract', 'boolean', 'byte', 'char', 'double', 'final', 'float',
+  'goto', 'int', 'long', 'native', 'short', 'synchronized', 'throws', 'transient', 'volatile',
+  'page', 'constructor', 'click', 'fill', 'expect', 'locator', 'waitFor', 'reload', 'close',
+]);
+
+const ROLE_SUFFIXES: Record<string, string> = {
+  button: 'Button',
+  textbox: 'Input',
+  input: 'Input',
+  searchbox: 'SearchInput',
+  link: 'Link',
+  checkbox: 'Checkbox',
+  combobox: 'Select',
+  listbox: 'Select',
+  select: 'Select',
+  cell: 'Cell',
+  heading: 'Heading',
+  dialog: 'Dialog',
+  status: 'Status',
+  tab: 'Tab',
+  radio: 'Radio',
+};
+
+const ARTICLES = new Set(['a', 'an', 'the']);
+
+export function stripArticles(text: string): string {
+  const words = text.trim().split(/\s+/);
+  const filtered = words.filter((w) => !ARTICLES.has(w.toLowerCase()));
+  return filtered.length > 0 ? filtered.join(' ') : text.trim();
+}
+
+export function toPascalCase(text: string): string {
+  const words = text
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .match(/[A-Za-z0-9]+/g);
+  if (!words || words.length === 0) return 'Element';
+  return words.map((w) => w[0]!.toUpperCase() + w.slice(1).toLowerCase()).join('');
+}
+
+export function toCamelCase(text: string): string {
+  const pascal = toPascalCase(text);
+  if (!pascal) return 'element';
+  return pascal[0]!.toLowerCase() + pascal.slice(1);
+}
+
+export function sanitizeIdentifier(identifier: string, suffixFallback = 'Element'): string {
+  let cleaned = identifier.replace(/[^a-zA-Z0-9_$]/g, '');
+  if (!cleaned || /^[0-9]/.test(cleaned)) {
+    cleaned = `${suffixFallback.toLowerCase()}${cleaned}`;
+  }
+  if (RESERVED_WORDS.has(cleaned.toLowerCase())) {
+    cleaned = `${cleaned}${suffixFallback}`;
+  }
+  return cleaned;
+}
+
+export function extractPageName(featureOrTitle: string): { className: string; variable: string } {
+  const lower = featureOrTitle.toLowerCase();
+  let canonicalName: string | undefined;
+
+  if (/\b(login|log\s*in|sign\s*in|auth|authenticate)\b/i.test(lower)) {
+    canonicalName = 'LoginPage';
+  } else if (/\b(register|sign\s*up|registration|signup)\b/i.test(lower)) {
+    canonicalName = 'RegisterPage';
+  } else if (/\b(checkout|pay|payment)\b/i.test(lower)) {
+    canonicalName = 'CheckoutPage';
+  } else if (/\b(cart|basket)\b/i.test(lower)) {
+    canonicalName = 'CartPage';
+  } else if (/\b(dashboard|home)\b/i.test(lower)) {
+    canonicalName = 'DashboardPage';
+  } else if (/\b(profile|account|setting)\b/i.test(lower)) {
+    canonicalName = 'ProfilePage';
+  } else if (/\b(product|catalog|search)\b/i.test(lower)) {
+    canonicalName = 'ProductsPage';
+  } else if (/\b(admin)\b/i.test(lower)) {
+    canonicalName = 'AdminPage';
+  }
+
+  if (canonicalName) {
+    const variable = canonicalName[0]!.toLowerCase() + canonicalName.slice(1);
+    return { className: canonicalName, variable };
+  }
+
+  // Strip common testing / scenario noise
+  let cleaned = featureOrTitle
+    .replace(/\b(should|complete|workflow|flow|spec|test|sanity|suite|journey|scenario)\b/gi, '')
+    .replace(/\b(with|for|and|using|valid|invalid|empty|wrong|credentials)\b/gi, '')
+    .replace(/\b(user|admin|customer|client)\b/gi, '')
+    .trim();
+
+  // If stripping left empty or too short, revert to original
+  if (!cleaned || cleaned.length < 3) {
+    cleaned = featureOrTitle;
+  }
+
+  const words = cleaned
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .match(/[A-Za-z0-9]+/g) ?? ['Feature'];
+  // Keep meaningful domain words up to 3 words
+  const domainWords = words.slice(0, 3);
+  let baseName = domainWords.map((w) => w[0]!.toUpperCase() + w.slice(1).toLowerCase()).join('');
+
+  if (!baseName.endsWith('Page')) {
+    baseName = `${baseName}Page`;
+  }
+
+  const className = sanitizeIdentifier(baseName, 'Page');
+  const variable = className[0]!.toLowerCase() + className.slice(1);
+  return { className, variable };
+}
+
+export function derivePropertyIdentifier(step: GeneratedStep, roleSuffix: string): { property: string; isFallback: boolean } {
+  const rawName = step.name ?? step.placeholder ?? step.selector;
+  if (rawName) {
+    const stripped = stripArticles(rawName);
+    const words = stripped
+      .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+      .match(/[A-Za-z0-9]+/g);
+    if (words && words.length > 0) {
+      const base = toCamelCase(stripped);
+      const lowerBase = base.toLowerCase();
+      const lowerSuffix = roleSuffix.toLowerCase();
+      let property = base;
+      if (!lowerBase.endsWith(lowerSuffix)) {
+        if (lowerSuffix === 'searchinput' && lowerBase.endsWith('search')) {
+          property = `${base}Input`;
+        } else {
+          property = `${base}${roleSuffix}`;
+        }
+      }
+      return { property: sanitizeIdentifier(property, roleSuffix), isFallback: false };
+    }
+  }
+
+  // Fallback when no semantic name exists
+  const role = step.role ?? (step.action === 'fill' ? 'textbox' : 'button');
+  const roleBase = toCamelCase(role);
+  let fallbackBase = roleBase;
+  if (roleBase.toLowerCase() === roleSuffix.toLowerCase()) {
+    fallbackBase = role === 'button' ? 'action' : 'input';
+  }
+  const fallback = sanitizeIdentifier(`${fallbackBase}${roleSuffix}`, roleSuffix);
+  return { property: fallback, isFallback: true };
+}
+
+export function deriveMethodIdentifier(step: GeneratedStep, propertyName: string): { method: string; verb: string } {
+  const rawName = step.name ?? step.placeholder ?? step.selector;
+  const stripped = rawName ? stripArticles(rawName) : '';
+  const pascalTarget = stripped ? toPascalCase(stripped) : toPascalCase(propertyName);
+
+  const formatWithVerb = (verb: string, target: string): string => {
+    const lowerVerb = verb.toLowerCase();
+    const lowerTarget = target.toLowerCase();
+    if (lowerTarget.startsWith(lowerVerb)) {
+      const remainder = target.slice(verb.length);
+      return sanitizeIdentifier(remainder.length > 0 ? `${verb}${remainder}` : verb, 'Action');
+    }
+    return sanitizeIdentifier(`${verb}${target}`, 'Action');
+  };
+
+  if (step.action === 'press') {
+    return {
+      method: formatWithVerb('press', pascalTarget || 'Key'),
+      verb: 'press',
+    };
+  }
+
+  if (step.action === 'fill') {
+    return {
+      method: formatWithVerb('fill', pascalTarget),
+      verb: 'fill',
+    };
+  }
+
+  if (step.action === 'click') {
+    const lower = (rawName ?? '').toLowerCase();
+    const roleLower = (step.role ?? '').toLowerCase();
+    if (roleLower === 'link' || roleLower === 'tab' || /\b(open|goto|go\s*to|home|back|nav|view|plans|settings)\b/.test(lower)) {
+      return { method: formatWithVerb('open', pascalTarget), verb: 'open' };
+    }
+    if (/\b(sign\s*in|log\s*in|login|signin)\b/.test(lower)) {
+      return { method: sanitizeIdentifier('signIn', 'Action'), verb: 'signIn' };
+    }
+    if (/\b(sign\s*up|register)\b/.test(lower)) {
+      return { method: sanitizeIdentifier('signUp', 'Action'), verb: 'signUp' };
+    }
+    if (/\b(submit|send|confirm|save|apply|checkout)\b/.test(lower)) {
+      return { method: formatWithVerb('submit', pascalTarget), verb: 'submit' };
+    }
+    return {
+      method: formatWithVerb('click', pascalTarget),
+      verb: 'click',
+    };
+  }
+
+  if (step.action === 'assert-visible') {
+    return {
+      method: sanitizeIdentifier(`expect${pascalTarget}Visible`, 'Action'),
+      verb: 'expectVisible',
+    };
+  }
+
+  if (step.action === 'assert-text') {
+    return {
+      method: sanitizeIdentifier(`expect${pascalTarget}Text`, 'Action'),
+      verb: 'expectText',
+    };
+  }
+
+  if (step.action === 'assert-count') {
+    return {
+      method: sanitizeIdentifier(`expect${pascalTarget}Count`, 'Action'),
+      verb: 'expectCount',
+    };
+  }
+
+  if (step.action === 'assert-value') {
+    return {
+      method: sanitizeIdentifier(`expect${pascalTarget}Value`, 'Action'),
+      verb: 'expectValue',
+    };
+  }
+
+  return {
+    method: sanitizeIdentifier(`perform${pascalTarget}`, 'Action'),
+    verb: 'perform',
+  };
+}
+
+export class NamePlanner {
+  public static planNames(
+    featureOrTitle: string,
+    steps: GeneratedStep[],
+    options?: { existingPageClassName?: string; source?: 'llm' | 'heuristic' }
+  ): NamePlan {
+    const assumptions: string[] = [];
+    const source = options?.source ?? 'heuristic';
+    const page = options?.existingPageClassName
+      ? { className: options.existingPageClassName, variable: options.existingPageClassName[0]!.toLowerCase() + options.existingPageClassName.slice(1) }
+      : extractPageName(featureOrTitle);
+
+    const symbols: SymbolEntry[] = [];
+    const usedProperties = new Set<string>();
+    const usedMethods = new Set<string>();
+
+    const disambiguationQualifiers = ['primary', 'secondary', 'confirm', 'alternate', 'detail', 'modal', 'auxiliary'];
+
+    steps.forEach((step, idx) => {
+      const ref = `step-${idx + 1}`;
+      // Grounding rule: a step with no accessible name AND no selector has no
+      // DOM identity. Never invent a symbol for it (a navigate step must not
+      // silently become a synthetic "button").
+      if (!step.name && !step.selector) {
+        if (step.action !== 'navigate') {
+          assumptions.push(`Step ${ref} (${step.action}) has no accessible name or selector and was skipped as ungrounded.`);
+        }
+        return;
+      }
+      const role = step.role ?? (step.action === 'fill' ? 'textbox' : step.action === 'click' ? 'button' : undefined);
+      const roleSuffix = ROLE_SUFFIXES[role?.toLowerCase() ?? ''] ?? (step.action === 'fill' ? 'Input' : 'Button');
+
+      const propResult = derivePropertyIdentifier(step, roleSuffix);
+      let property = propResult.property;
+
+      if (propResult.isFallback) {
+        assumptions.push(`Step ${ref} has no accessible name; generated generic semantic property '${property}'`);
+      }
+
+      // Disambiguate property collisions using semantic qualifiers, NEVER by bare index numbers
+      if (usedProperties.has(property)) {
+        let disambiguated = false;
+        for (const qualifier of disambiguationQualifiers) {
+          const candidate = `${qualifier}${property[0]!.toUpperCase()}${property.slice(1)}`;
+          if (!usedProperties.has(candidate)) {
+            assumptions.push(`Property name collision for '${property}'; disambiguated to '${candidate}'`);
+            property = candidate;
+            disambiguated = true;
+            break;
+          }
+        }
+        if (!disambiguated) {
+          property = `${property}Alt`;
+        }
+      }
+      usedProperties.add(property);
+
+      const methodResult = deriveMethodIdentifier(step, property);
+      let method = methodResult.method;
+
+      // Disambiguate method collisions
+      if (usedMethods.has(method)) {
+        let disambiguated = false;
+        for (const qualifier of disambiguationQualifiers) {
+          const candidate = `${methodResult.verb}${qualifier[0]!.toUpperCase()}${qualifier.slice(1)}`;
+          if (!usedMethods.has(candidate)) {
+            assumptions.push(`Method name collision for '${method}'; disambiguated to '${candidate}'`);
+            method = candidate;
+            disambiguated = true;
+            break;
+          }
+        }
+        if (!disambiguated) {
+          method = `${method}Alt`;
+        }
+      }
+      usedMethods.add(method);
+
+      const frame = step.frame ?? step.frameSelector;
+      symbols.push({
+        ref,
+        role: step.role,
+        accessibleName: step.name,
+        property,
+        method,
+        verb: methodResult.verb,
+        confidence: propResult.isFallback ? 0.75 : 0.95,
+        source,
+        assumptions: [],
+        ...(frame ? { frame } : {}),
+      });
+    });
+
+    return {
+      planVersion: '1',
+      pageClassName: page.className,
+      pageVariable: page.variable,
+      symbols,
+      assumptions,
+    };
+  }
+}