@cementic/cementic-test 0.2.12 → 0.2.14

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   genCmd
-} from "./chunk-RG26I5FB.js";
+} from "./chunk-3S26OWNR.js";
 
 // src/cli.ts
 import { Command as Command9 } from "commander";
@@ -18,6 +18,8 @@ import { platform, release } from "os";
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
 var LEGACY_MACOS_DARWIN_MAJOR = 23;
+var LEGACY_PLAYWRIGHT_VERSION = "^1.48.2";
+var LEGACY_ALLURE_VERSION = "^2.15.1";
 function resolveTemplatePath(templateDir) {
   const candidates = [
     resolve(__dirname, `templates/${templateDir}`),
@@ -27,13 +29,73 @@ function resolveTemplatePath(templateDir) {
   ];
   return candidates.find((candidate) => existsSync(candidate));
 }
+function getHostPlatform(env = process.env) {
+  return (env.CT_OS_PLATFORM_OVERRIDE ?? platform()).trim().toLowerCase();
+}
+function getHostRelease(env = process.env) {
+  return (env.CT_OS_RELEASE_OVERRIDE ?? release()).trim();
+}
+function isLegacyMacOs(env = process.env) {
+  if (getHostPlatform(env) !== "darwin") return false;
+  const majorVersion = parseInt(getHostRelease(env).split(".")[0], 10);
+  return Number.isFinite(majorVersion) && majorVersion < LEGACY_MACOS_DARWIN_MAJOR;
+}
+function resolveBrowserInstallProfile(raw) {
+  const profile = String(raw ?? "auto").trim().toLowerCase();
+  if (profile === "auto" || profile === "all" || profile === "chromium") return profile;
+  console.error(`\u274C Unsupported browser install profile "${raw}". Use "auto", "all", or "chromium".`);
+  process.exit(1);
+}
+function resolveBootstrapPlan(browserProfile, env = process.env) {
+  const legacyMacOs = isLegacyMacOs(env);
+  const resolvedProfile = browserProfile === "auto" ? legacyMacOs ? "chromium" : "all" : browserProfile;
+  return {
+    browserInstallArgs: resolvedProfile === "chromium" ? ["playwright", "install", "chromium"] : ["playwright", "install"],
+    browserProfile: resolvedProfile,
+    isLegacyMacOs: legacyMacOs,
+    packageVersionOverrides: legacyMacOs ? {
+      "@playwright/test": LEGACY_PLAYWRIGHT_VERSION,
+      "allure-playwright": LEGACY_ALLURE_VERSION
+    } : {},
+    reason: legacyMacOs ? "Detected macOS 13 or older. Using a legacy-compatible Playwright toolchain and Chromium-only browser install." : void 0
+  };
+}
+function applyPackageVersionOverrides(projectPath, versionOverrides) {
+  if (Object.keys(versionOverrides).length === 0) return;
+  const pkgJsonPath = join(projectPath, "package.json");
+  if (!existsSync(pkgJsonPath)) return;
+  try {
+    const pkgContent = readFileSync(pkgJsonPath, "utf-8");
+    const pkg = JSON.parse(pkgContent);
+    const devDependencies = pkg.devDependencies ?? {};
+    let changed = false;
+    for (const [name, version2] of Object.entries(versionOverrides)) {
+      if (typeof devDependencies[name] !== "string") continue;
+      devDependencies[name] = version2;
+      changed = true;
+    }
+    if (!changed) return;
+    pkg.devDependencies = devDependencies;
+    writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2));
+    console.log("\u2705 Applied compatibility dependency pins for this machine.");
+  } catch (err) {
+    console.warn("\u26A0\uFE0F Failed to adjust package.json for OS compatibility:", err);
+  }
+}
 function newCmd() {
   const cmd = new Command("new").arguments("<projectName>").description("Scaffold a new CementicTest + Playwright project from scratch").addHelpText("after", `
 Examples:
   $ ct new my-awesome-test-suite
   $ ct new e2e-ts --lang ts
   $ ct new e2e-tests --no-browsers
-`).option("--mode <mode>", "greenfield|enhance", "greenfield").option("--lang <lang>", "Scaffold language (js|ts)", "js").option("--no-browsers", 'do not run "npx playwright install" during setup').action((projectName, opts) => {
+`).option("--mode <mode>", "greenfield|enhance", "greenfield").option("--lang <lang>", "Scaffold language (js|ts)", "js").option("--browser-set <profile>", "Browser install profile (auto|all|chromium)", "auto").option("--no-browsers", 'do not run "npx playwright install" during setup').action((projectName, opts) => {
+    const mode = String(opts.mode ?? "greenfield").trim().toLowerCase();
+    if (mode !== "greenfield") {
+      console.error(`\u274C Unsupported scaffold mode "${opts.mode}". Only "greenfield" is currently implemented.`);
+      process.exit(1);
+    }
+    const browserInstallProfile = resolveBrowserInstallProfile(opts.browserSet);
+    const bootstrapPlan = resolveBootstrapPlan(browserInstallProfile);
     const root = process.cwd();
     const projectPath = join(root, projectName);
     console.log(`\u{1F680} Initializing new CementicTest project in ${projectName}...`);
@@ -62,25 +124,10 @@ Examples:
       }
     }
     copyRecursive(templatePath, projectPath);
-    const legacyMacOs = isLegacyMacOs();
-    if (legacyMacOs) {
-      console.log("\u{1F34E} Detected macOS 13 or older. Adjusting versions for compatibility...");
-      const pkgJsonPath = join(projectPath, "package.json");
-      if (existsSync(pkgJsonPath)) {
-        try {
-          const pkgContent = readFileSync(pkgJsonPath, "utf-8");
-          const pkg = JSON.parse(pkgContent);
-          if (pkg.devDependencies) {
-            pkg.devDependencies["@playwright/test"] = "^1.48.2";
-            pkg.devDependencies["allure-playwright"] = "^2.15.1";
-            writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2));
-            console.log("\u2705 Pinned Playwright packages for legacy macOS compatibility.");
-          }
-        } catch (err) {
-          console.warn("\u26A0\uFE0F Failed to adjust package.json for OS compatibility:", err);
-        }
-      }
+    if (bootstrapPlan.reason) {
+      console.log(`\u{1F34E} ${bootstrapPlan.reason}`);
     }
+    applyPackageVersionOverrides(projectPath, bootstrapPlan.packageVersionOverrides);
     try {
       execSync("git init", { cwd: projectPath, stdio: "ignore" });
       const gitignorePath = join(projectPath, ".gitignore");
@@ -101,17 +148,19 @@ Examples:
     if (opts.browsers !== false && dependenciesInstalled) {
       console.log("\u{1F310} Installing Playwright browsers...");
       try {
-        if (legacyMacOs) {
+        const installCommand = `npx ${bootstrapPlan.browserInstallArgs.join(" ")}`;
+        if (bootstrapPlan.browserProfile === "chromium" && bootstrapPlan.isLegacyMacOs) {
           console.log("\u26A0\uFE0F WebKit is not supported on this macOS version. Installing Chromium only...");
-          execSync("npx playwright install chromium", { cwd: projectPath, stdio: "inherit" });
-          console.log("\u2705 Chromium installed successfully.");
-        } else {
-          execSync("npx playwright install", { cwd: projectPath, stdio: "inherit" });
-          console.log("\u2705 Playwright browsers installed successfully.");
+        } else if (bootstrapPlan.browserProfile === "chromium") {
+          console.log("\u2139\uFE0F Installing Chromium only because --browser-set chromium was requested.");
         }
+        execSync(installCommand, { cwd: projectPath, stdio: "inherit" });
+        console.log(
+          bootstrapPlan.browserProfile === "chromium" ? "\u2705 Chromium installed successfully." : "\u2705 Playwright browsers installed successfully."
+        );
       } catch (e) {
         console.warn("\u26A0\uFE0F Browser installation did not complete. You can finish setup with:");
-        console.warn("  npx playwright install chromium");
+        console.warn(`  npx ${bootstrapPlan.browserInstallArgs.join(" ")}`);
       }
     }
     console.log(`
@@ -126,11 +175,6 @@ Happy testing! \u{1F9EA}`);
   });
   return cmd;
 }
-function isLegacyMacOs() {
-  if (platform() !== "darwin") return false;
-  const majorVersion = parseInt(release().split(".")[0], 10);
-  return Number.isFinite(majorVersion) && majorVersion < LEGACY_MACOS_DARWIN_MAJOR;
-}
 
 // src/commands/normalize.ts
 import { Command as Command2 } from "commander";
@@ -321,7 +365,7 @@ Examples:
     }
     console.log(`\u2705 Normalized ${index.summary.parsed} case(s). Output \u2192 .cementic/normalized/`);
     if (opts.andGen) {
-      const { gen } = await import("./gen-6Y65IYXO.js");
+      const { gen } = await import("./gen-AGWFMHTO.js");
       await gen({ lang: opts.lang || "ts", out: "tests/generated" });
     }
   });
@@ -501,6 +545,315 @@ function buildProviderConfigs(env) {
 function getAvailableCtVarKeys() {
   return Object.keys(process.env).filter((key) => /^CT_VAR_[A-Z0-9_]+$/.test(key)).sort();
 }
+var RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE = `
+RULE 10 - PLAYWRIGHT KNOWLEDGE BASE
+(sourced from playwright.dev official documentation)
+
+You are an expert in Playwright TypeScript. Apply this knowledge
+when generating test code. Always use web-first assertions that
+auto-wait. Never use manual waits or non-awaited assertions.
+
+LOCATOR PRIORITY (use in this order)
+1. page.getByRole('button', { name: 'Submit' })     <- best
+2. page.getByLabel('Email address')
+3. page.getByPlaceholder('Enter email')
+4. page.getByText('Welcome')
+5. page.getByAltText('logo')
+6. page.getByTitle('Close')
+7. page.getByTestId('submit-btn')
+8. page.locator('#id') or page.locator('.class')    <- last resort
+
+Chain locators to narrow scope:
+  page.getByRole('listitem').filter({ hasText: 'Product 2' })
+    .getByRole('button', { name: 'Add to cart' }).click()
+
+LOCATOR ASSERTIONS (always await, always web-first)
+Visibility:
+  await expect(locator).toBeVisible()
+  await expect(locator).toBeHidden()
+  await expect(locator).toBeInViewport()
+
+State:
+  await expect(locator).toBeEnabled()
+  await expect(locator).toBeDisabled()
+  await expect(locator).toBeChecked()
+  await expect(locator).not.toBeChecked()
+  await expect(locator).toBeFocused()
+  await expect(locator).toBeEditable()
+  await expect(locator).toBeEmpty()
+  await expect(locator).toBeAttached()
+
+Text content:
+  await expect(locator).toHaveText('exact text')
+  await expect(locator).toHaveText(/regex/)
+  await expect(locator).toContainText('partial')
+  await expect(locator).toContainText(['item1', 'item2'])
+
+Value and attributes:
+  await expect(locator).toHaveValue('input value')
+  await expect(locator).toHaveValues(['opt1', 'opt2'])  // multi-select
+  await expect(locator).toHaveAttribute('href', /pattern/)
+  await expect(locator).toHaveClass(/active/)
+  await expect(locator).toHaveCSS('color', 'rgb(0,0,0)')
+  await expect(locator).toHaveId('submit-btn')
+  await expect(locator).toHaveAccessibleName('Submit form')
+  await expect(locator).toHaveAccessibleDescription('...')
+
+Counting (PREFER toHaveCount over .count() to avoid flakiness):
+  await expect(locator).toHaveCount(3)
+  await expect(locator).toHaveCount(0)   // none exist
+  // Only use .count() when you need the actual number:
+  const n = await page.getByRole('button').count();
+  console.log(\`Found \${n} buttons\`);
+
+PAGE ASSERTIONS
+  await expect(page).toHaveTitle(/Playwright/)
+  await expect(page).toHaveTitle('Exact Title')
+  await expect(page).toHaveURL('https://example.com/dashboard')
+  await expect(page).toHaveURL(/\\/dashboard/)
+
+ACTIONS (Playwright auto-waits before each action)
+Navigation:
+  await page.goto('https://example.com')
+  await page.goBack()
+  await page.goForward()
+  await page.reload()
+
+Clicking:
+  await locator.click()
+  await locator.dblclick()
+  await locator.click({ button: 'right' })
+  await locator.click({ modifiers: ['Shift'] })
+
+Forms:
+  await locator.fill('text')           // clears then types
+  await locator.clear()
+  await locator.pressSequentially('slow typing', { delay: 50 })
+  await locator.selectOption('value')
+  await locator.selectOption({ label: 'Blue' })
+  await locator.check()
+  await locator.uncheck()
+  await locator.setInputFiles('path/to/file.pdf')
+
+Hover and focus:
+  await locator.hover()
+  await locator.focus()
+  await locator.blur()
+
+Keyboard:
+  await page.keyboard.press('Enter')
+  await page.keyboard.press('Tab')
+  await page.keyboard.press('Escape')
+  await page.keyboard.press('Control+A')
+
+Scroll:
+  await locator.scrollIntoViewIfNeeded()
+  await page.mouse.wheel(0, 500)
+
+BEST PRACTICES (from playwright.dev/docs/best-practices)
+DO use web-first assertions:
+   await expect(page.getByText('welcome')).toBeVisible()
+
+NEVER use synchronous assertions:
+   expect(await page.getByText('welcome').isVisible()).toBe(true)
+
+DO chain locators:
+   page.getByRole('listitem').filter({ hasText: 'Product 2' })
+     .getByRole('button', { name: 'Add to cart' })
+
+NEVER use fragile CSS/XPath selectors:
+   page.locator('button.buttonIcon.episode-actions-later')
+
+DO use role-based locators:
+   page.getByRole('button', { name: 'submit' })
+
+INTENT -> PATTERN MAPPING
+
+COUNTING:
+  "how many X" / "count X" / "number of X" / "return the count"
+  -> const n = await page.getByRole('X').count();
+    console.log(\`Found \${n} X elements\`);
+    expect(n).toBeGreaterThan(0);
+
+  "there are N X" / "exactly N X"
+  -> await expect(page.getByRole('X')).toHaveCount(N);
+
+  CRITICAL: Never use getByText("how many X") - count intent
+  means call .count() or toHaveCount(), not search for text.
+
+PRESENCE:
+  "X is present/visible/shown/exists"
+  -> await expect(locator).toBeVisible()
+
+  "X is hidden/not present/gone"
+  -> await expect(locator).toBeHidden()
+
+TEXT:
+  "text says X" / "shows X" / "message is X"
+  -> await expect(locator).toHaveText('X')
+
+  "contains X" / "includes X"
+  -> await expect(locator).toContainText('X')
+
+  "page title is X"
+  -> await expect(page).toHaveTitle(/X/i)
+
+  "heading says X"
+  -> await expect(page.getByRole('heading')).toContainText('X')
+
+  "error says X"
+  -> await expect(page.getByRole('alert')).toContainText('X')
+
+STATE:
+  "X is enabled/disabled"
+  -> await expect(locator).toBeEnabled() / toBeDisabled()
+
+  "X is checked/unchecked"
+  -> await expect(locator).toBeChecked() / not.toBeChecked()
+
+  "X has value Y"
+  -> await expect(locator).toHaveValue('Y')
+
+  "X is active / has class Y"
+  -> await expect(locator).toHaveClass(/Y/)
+
+NAVIGATION:
+  "redirects to X" / "goes to X" / "URL contains X"
+  -> await expect(page).toHaveURL(/X/)
+
+  "stays on same page"
+  -> await expect(page).toHaveURL(/currentPath/)
+
+  "opens new tab"
+  -> const [newPage] = await Promise.all([
+      context.waitForEvent('page'),
+      locator.click()
+    ]);
+
+FORMS:
+  "form submits successfully"
+  -> fill fields + click submit + assert URL change or success message
+
+  "validation error shown"
+  -> submit empty + await expect(page.getByRole('alert')).toBeVisible()
+
+  "required field X"
+  -> submit without X + assert error message for X visible
+
+AUTH:
+  "login with valid credentials"
+  -> fill(CT_VAR_USERNAME) + fill(CT_VAR_PASSWORD) + click login
+    + await expect(page).toHaveURL(/dashboard|home|app/)
+
+  "login fails / invalid credentials"
+  -> fill bad values + click login
+    + await expect(page.getByRole('alert')).toBeVisible()
+
+  "logout works"
+  -> click logout + await expect(page).toHaveURL(/login|home/)
+
+THEME / VISUAL:
+  "dark mode / theme toggle"
+  -> await locator.click()
+    + await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark')
+    // OR: await expect(page.locator('body')).toHaveClass(/dark/)
+
+TIMING:
+  "X loads / X appears"
+  -> await expect(locator).toBeVisible({ timeout: 10000 })
+
+  "spinner disappears / loader gone"
+  -> await expect(spinner).toBeHidden({ timeout: 10000 })
+
+  "modal closes"
+  -> await expect(modal).toBeHidden()
+
+ACCESSIBILITY:
+  "has alt text"
+  -> await expect(page.locator('img')).toHaveAttribute('alt', /.+/)
+
+  "keyboard navigable"
+  -> await page.keyboard.press('Tab')
+    + await expect(firstFocusable).toBeFocused()
+
+CRITICAL RULES
+1. NEVER use intent words as locator text.
+   "count buttons" != getByText("count buttons")
+   "verify heading" != getByText("verify heading")
+
+2. ALWAYS use web-first assertions (await expect).
+   NEVER use: expect(await locator.isVisible()).toBe(true)
+
+3. For counting, prefer toHaveCount() over .count() unless
+   you need the actual number for logging.
+
+4. Auto-waiting: Playwright automatically waits for elements
+   to be actionable before click/fill/etc. Do not add
+   manual waitForTimeout() unless testing timing specifically.
+
+5. Use not. prefix for negative assertions:
+   await expect(locator).not.toBeVisible()
+   await expect(locator).not.toBeChecked()
+`.trim();
+var ADVANCED_DOC_MAP = {
+  upload: "https://playwright.dev/docs/input",
+  "file upload": "https://playwright.dev/docs/input",
+  intercept: "https://playwright.dev/docs/mock",
+  mock: "https://playwright.dev/docs/mock",
+  "api mock": "https://playwright.dev/docs/mock",
+  accessibility: "https://playwright.dev/docs/accessibility-testing",
+  "screen reader": "https://playwright.dev/docs/accessibility-testing",
+  visual: "https://playwright.dev/docs/screenshots",
+  screenshot: "https://playwright.dev/docs/screenshots",
+  mobile: "https://playwright.dev/docs/emulation",
+  responsive: "https://playwright.dev/docs/emulation",
+  viewport: "https://playwright.dev/docs/emulation",
+  network: "https://playwright.dev/docs/network",
+  "api call": "https://playwright.dev/docs/network",
+  iframe: "https://playwright.dev/docs/frames",
+  frame: "https://playwright.dev/docs/frames",
+  auth: "https://playwright.dev/docs/auth",
+  "sign in": "https://playwright.dev/docs/auth",
+  "stay logged": "https://playwright.dev/docs/auth",
+  cookie: "https://playwright.dev/docs/auth",
+  storage: "https://playwright.dev/docs/auth",
+  download: "https://playwright.dev/docs/downloads",
+  pdf: "https://playwright.dev/docs/downloads",
+  dialog: "https://playwright.dev/docs/dialogs",
+  alert: "https://playwright.dev/docs/dialogs",
+  confirm: "https://playwright.dev/docs/dialogs",
+  "new tab": "https://playwright.dev/docs/pages",
+  "new page": "https://playwright.dev/docs/pages",
+  popup: "https://playwright.dev/docs/pages"
+};
+async function fetchDocContext(intent) {
+  const intentLower = intent.toLowerCase();
+  const matched = /* @__PURE__ */ new Set();
+  for (const [keyword, url] of Object.entries(ADVANCED_DOC_MAP)) {
+    if (intentLower.includes(keyword)) {
+      matched.add(url);
+    }
+  }
+  if (matched.size === 0) return "";
+  const fetched = [];
+  for (const url of matched) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
+      const html = await res.text();
+      const text = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s{3,}/g, "\n\n").slice(0, 3e3);
+      fetched.push(`
+// From ${url}:
+${text}`);
+    } catch {
+    }
+  }
+  if (fetched.length === 0) return "";
+  return `
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ADDITIONAL PLAYWRIGHT DOCS (fetched for this intent)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501${fetched.join("\n")}`;
+}
 function buildSystemMessage() {
   return `
 You are a senior software test architect with 10 years of Playwright experience.
@@ -567,6 +920,8 @@ Match scenario count to intent complexity:
 - Full flow: 4 to 8 scenarios maximum
 Never exceed 8 scenarios.
 
+${RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE}
+
 COMMON TESTING VOCABULARY
 "verify/check X is present/visible" -> toBeVisible()
 "verify title/heading" -> heading is visible
@@ -725,7 +1080,8 @@ async function callOpenAiCompatible(apiKey, model, baseUrl, displayName, system,
 }
 async function generateTcMarkdownWithAi(ctx) {
   const providerConfig = resolveLlmProvider();
-  const system = buildSystemMessage();
+  const docContext = await fetchDocContext(ctx.feature);
+  const system = buildSystemMessage() + docContext;
   const user = buildUserMessage(ctx);
   console.log(`\u{1F916} Using ${providerConfig.displayName} (${providerConfig.model})`);
   if (providerConfig.transport === "anthropic") {
@@ -742,24 +1098,351 @@ async function generateTcMarkdownWithAi(ctx) {
 }
 
 // src/core/analyse.ts
+function escapeForRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
+}
+var RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE2 = `
+RULE 10 - PLAYWRIGHT KNOWLEDGE BASE
+(sourced from playwright.dev official documentation)
+
+You are an expert in Playwright TypeScript. Apply this knowledge
+when generating test code. Always use web-first assertions that
+auto-wait. Never use manual waits or non-awaited assertions.
+
+LOCATOR PRIORITY (use in this order)
+1. page.getByRole('button', { name: 'Submit' })     <- best
+2. page.getByLabel('Email address')
+3. page.getByPlaceholder('Enter email')
+4. page.getByText('Welcome')
+5. page.getByAltText('logo')
+6. page.getByTitle('Close')
+7. page.getByTestId('submit-btn')
+8. page.locator('#id') or page.locator('.class')    <- last resort
+
+Chain locators to narrow scope:
+  page.getByRole('listitem').filter({ hasText: 'Product 2' })
+    .getByRole('button', { name: 'Add to cart' }).click()
+
+LOCATOR ASSERTIONS (always await, always web-first)
+Visibility:
+  await expect(locator).toBeVisible()
+  await expect(locator).toBeHidden()
+  await expect(locator).toBeInViewport()
+
+State:
+  await expect(locator).toBeEnabled()
+  await expect(locator).toBeDisabled()
+  await expect(locator).toBeChecked()
+  await expect(locator).not.toBeChecked()
+  await expect(locator).toBeFocused()
+  await expect(locator).toBeEditable()
+  await expect(locator).toBeEmpty()
+  await expect(locator).toBeAttached()
+
+Text content:
+  await expect(locator).toHaveText('exact text')
+  await expect(locator).toHaveText(/regex/)
+  await expect(locator).toContainText('partial')
+  await expect(locator).toContainText(['item1', 'item2'])
+
+Value and attributes:
+  await expect(locator).toHaveValue('input value')
+  await expect(locator).toHaveValues(['opt1', 'opt2'])  // multi-select
+  await expect(locator).toHaveAttribute('href', /pattern/)
+  await expect(locator).toHaveClass(/active/)
+  await expect(locator).toHaveCSS('color', 'rgb(0,0,0)')
+  await expect(locator).toHaveId('submit-btn')
+  await expect(locator).toHaveAccessibleName('Submit form')
+  await expect(locator).toHaveAccessibleDescription('...')
+
+Counting (PREFER toHaveCount over .count() to avoid flakiness):
+  await expect(locator).toHaveCount(3)
+  await expect(locator).toHaveCount(0)   // none exist
+  // Only use .count() when you need the actual number:
+  const n = await page.getByRole('button').count();
+  console.log(\`Found \${n} buttons\`);
+
+PAGE ASSERTIONS
+  await expect(page).toHaveTitle(/Playwright/)
+  await expect(page).toHaveTitle('Exact Title')
+  await expect(page).toHaveURL('https://example.com/dashboard')
+  await expect(page).toHaveURL(/\\/dashboard/)
+
+ACTIONS (Playwright auto-waits before each action)
+Navigation:
+  await page.goto('https://example.com')
+  await page.goBack()
+  await page.goForward()
+  await page.reload()
+
+Clicking:
+  await locator.click()
+  await locator.dblclick()
+  await locator.click({ button: 'right' })
+  await locator.click({ modifiers: ['Shift'] })
+
+Forms:
+  await locator.fill('text')           // clears then types
+  await locator.clear()
+  await locator.pressSequentially('slow typing', { delay: 50 })
+  await locator.selectOption('value')
+  await locator.selectOption({ label: 'Blue' })
+  await locator.check()
+  await locator.uncheck()
+  await locator.setInputFiles('path/to/file.pdf')
+
+Hover and focus:
+  await locator.hover()
+  await locator.focus()
+  await locator.blur()
+
+Keyboard:
+  await page.keyboard.press('Enter')
+  await page.keyboard.press('Tab')
+  await page.keyboard.press('Escape')
+  await page.keyboard.press('Control+A')
+
+Scroll:
+  await locator.scrollIntoViewIfNeeded()
+  await page.mouse.wheel(0, 500)
+
+BEST PRACTICES (from playwright.dev/docs/best-practices)
+DO use web-first assertions:
+   await expect(page.getByText('welcome')).toBeVisible()
+
+NEVER use synchronous assertions:
+   expect(await page.getByText('welcome').isVisible()).toBe(true)
+
+DO chain locators:
+   page.getByRole('listitem').filter({ hasText: 'Product 2' })
+     .getByRole('button', { name: 'Add to cart' })
+
+NEVER use fragile CSS/XPath selectors:
+   page.locator('button.buttonIcon.episode-actions-later')
+
+DO use role-based locators:
+   page.getByRole('button', { name: 'submit' })
+
+INTENT -> PATTERN MAPPING
+
+COUNTING:
+  "how many X" / "count X" / "number of X" / "return the count"
+  -> const n = await page.getByRole('X').count();
+    console.log(\`Found \${n} X elements\`);
+    expect(n).toBeGreaterThan(0);
+
+  "there are N X" / "exactly N X"
+  -> await expect(page.getByRole('X')).toHaveCount(N);
+
+  CRITICAL: Never use getByText("how many X") - count intent
+  means call .count() or toHaveCount(), not search for text.
+
+PRESENCE:
+  "X is present/visible/shown/exists"
+  -> await expect(locator).toBeVisible()
+
+  "X is hidden/not present/gone"
+  -> await expect(locator).toBeHidden()
+
+TEXT:
+  "text says X" / "shows X" / "message is X"
+  -> await expect(locator).toHaveText('X')
+
+  "contains X" / "includes X"
+  -> await expect(locator).toContainText('X')
+
+  "page title is X"
+  -> await expect(page).toHaveTitle(/X/i)
+
+  "heading says X"
+  -> await expect(page.getByRole('heading')).toContainText('X')
+
+  "error says X"
+  -> await expect(page.getByRole('alert')).toContainText('X')
+
+STATE:
+  "X is enabled/disabled"
+  -> await expect(locator).toBeEnabled() / toBeDisabled()
+
+  "X is checked/unchecked"
+  -> await expect(locator).toBeChecked() / not.toBeChecked()
+
+  "X has value Y"
+  -> await expect(locator).toHaveValue('Y')
+
+  "X is active / has class Y"
+  -> await expect(locator).toHaveClass(/Y/)
+
+NAVIGATION:
+  "redirects to X" / "goes to X" / "URL contains X"
+  -> await expect(page).toHaveURL(/X/)
+
+  "stays on same page"
+  -> await expect(page).toHaveURL(/currentPath/)
+
+  "opens new tab"
+  -> const [newPage] = await Promise.all([
+      context.waitForEvent('page'),
+      locator.click()
+    ]);
+
+FORMS:
+  "form submits successfully"
+  -> fill fields + click submit + assert URL change or success message
+
+  "validation error shown"
+  -> submit empty + await expect(page.getByRole('alert')).toBeVisible()
+
+  "required field X"
+  -> submit without X + assert error message for X visible
+
+AUTH:
+  "login with valid credentials"
+  -> fill(CT_VAR_USERNAME) + fill(CT_VAR_PASSWORD) + click login
+    + await expect(page).toHaveURL(/dashboard|home|app/)
+
+  "login fails / invalid credentials"
+  -> fill bad values + click login
+    + await expect(page.getByRole('alert')).toBeVisible()
+
+  "logout works"
+  -> click logout + await expect(page).toHaveURL(/login|home/)
+
+THEME / VISUAL:
+  "dark mode / theme toggle"
+  -> await locator.click()
+    + await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark')
+    // OR: await expect(page.locator('body')).toHaveClass(/dark/)
+
+TIMING:
+  "X loads / X appears"
+  -> await expect(locator).toBeVisible({ timeout: 10000 })
+
+  "spinner disappears / loader gone"
+  -> await expect(spinner).toBeHidden({ timeout: 10000 })
+
+  "modal closes"
+  -> await expect(modal).toBeHidden()
+
+ACCESSIBILITY:
+  "has alt text"
+  -> await expect(page.locator('img')).toHaveAttribute('alt', /.+/)
+
+  "keyboard navigable"
+  -> await page.keyboard.press('Tab')
+    + await expect(firstFocusable).toBeFocused()
+
+CRITICAL RULES
+1. NEVER use intent words as locator text.
+   "count buttons" != getByText("count buttons")
+   "verify heading" != getByText("verify heading")
+
+2. ALWAYS use web-first assertions (await expect).
+   NEVER use: expect(await locator.isVisible()).toBe(true)
+
+3. For counting, prefer toHaveCount() over .count() unless
+   you need the actual number for logging.
+
+4. Auto-waiting: Playwright automatically waits for elements
+   to be actionable before click/fill/etc. Do not add
+   manual waitForTimeout() unless testing timing specifically.
+
+5. Use not. prefix for negative assertions:
+   await expect(locator).not.toBeVisible()
+   await expect(locator).not.toBeChecked()
+`.trim();
+var ADVANCED_DOC_MAP2 = {
+  upload: "https://playwright.dev/docs/input",
+  "file upload": "https://playwright.dev/docs/input",
+  intercept: "https://playwright.dev/docs/mock",
+  mock: "https://playwright.dev/docs/mock",
+  "api mock": "https://playwright.dev/docs/mock",
+  accessibility: "https://playwright.dev/docs/accessibility-testing",
+  "screen reader": "https://playwright.dev/docs/accessibility-testing",
+  visual: "https://playwright.dev/docs/screenshots",
+  screenshot: "https://playwright.dev/docs/screenshots",
+  mobile: "https://playwright.dev/docs/emulation",
+  responsive: "https://playwright.dev/docs/emulation",
+  viewport: "https://playwright.dev/docs/emulation",
+  network: "https://playwright.dev/docs/network",
+  "api call": "https://playwright.dev/docs/network",
+  iframe: "https://playwright.dev/docs/frames",
+  frame: "https://playwright.dev/docs/frames",
+  auth: "https://playwright.dev/docs/auth",
+  "sign in": "https://playwright.dev/docs/auth",
+  "stay logged": "https://playwright.dev/docs/auth",
+  cookie: "https://playwright.dev/docs/auth",
+  storage: "https://playwright.dev/docs/auth",
+  download: "https://playwright.dev/docs/downloads",
+  pdf: "https://playwright.dev/docs/downloads",
+  dialog: "https://playwright.dev/docs/dialogs",
+  alert: "https://playwright.dev/docs/dialogs",
+  confirm: "https://playwright.dev/docs/dialogs",
+  "new tab": "https://playwright.dev/docs/pages",
+  "new page": "https://playwright.dev/docs/pages",
+  popup: "https://playwright.dev/docs/pages"
+};
+async function fetchDocContext2(intent) {
+  const intentLower = intent.toLowerCase();
+  const matched = /* @__PURE__ */ new Set();
+  for (const [keyword, url] of Object.entries(ADVANCED_DOC_MAP2)) {
+    if (intentLower.includes(keyword)) {
+      matched.add(url);
+    }
+  }
+  if (matched.size === 0) return "";
+  const fetched = [];
+  for (const url of matched) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
+      const html = await res.text();
+      const text = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s{3,}/g, "\n\n").slice(0, 3e3);
+      fetched.push(`
+// From ${url}:
+${text}`);
+    } catch {
+    }
+  }
+  if (fetched.length === 0) return "";
+  return `
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ADDITIONAL PLAYWRIGHT DOCS (fetched for this intent)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501${fetched.join("\n")}`;
+}
 async function analyseElements(elementMap, options = {}) {
   const { verbose = false, feature } = options;
-  const providerConfig = resolveLlmProvider();
   const requestedFeature = normalizeRequestedFeature(feature, elementMap);
+  let providerConfig;
+  try {
+    providerConfig = resolveLlmProvider();
+  } catch (error) {
+    log(verbose, `
+[analyse] ${shortErrorMessage(error)}`);
+    log(verbose, "[analyse] Falling back to deterministic capture analysis.");
+    return buildDeterministicAnalysis(elementMap, requestedFeature);
+  }
   log(verbose, `
 [analyse] Sending capture to ${providerConfig.displayName} (${providerConfig.model})`);
-  const systemPrompt = buildSystemPrompt();
-  const userPrompt = buildUserPrompt(elementMap, requestedFeature);
-  const rawResponse = providerConfig.transport === "anthropic" ? await callAnthropic2(providerConfig.apiKey, providerConfig.model, systemPrompt, userPrompt) : await callOpenAiCompatible2(
-    providerConfig.apiKey,
-    providerConfig.model,
-    providerConfig.baseUrl ?? "https://api.openai.com/v1",
-    providerConfig.displayName,
-    systemPrompt,
-    userPrompt
-  );
-  const parsed = parseAnalysisJson(rawResponse);
-  return sanitizeAnalysis(parsed, elementMap, requestedFeature);
+  try {
+    const docContext = await fetchDocContext2(requestedFeature);
+    const systemPrompt = buildSystemPrompt() + docContext;
+    const userPrompt = buildUserPrompt(elementMap, requestedFeature);
+    const rawResponse = providerConfig.transport === "anthropic" ? await callAnthropic2(providerConfig.apiKey, providerConfig.model, systemPrompt, userPrompt) : await callOpenAiCompatible2(
+      providerConfig.apiKey,
+      providerConfig.model,
+      providerConfig.baseUrl ?? "https://api.openai.com/v1",
+      providerConfig.displayName,
+      systemPrompt,
+      userPrompt
+    );
+    const parsed = parseAnalysisJson(rawResponse);
+    return sanitizeAnalysis(parsed, elementMap, requestedFeature);
+  } catch (error) {
+    log(verbose, `[analyse] Remote analysis failed: ${shortErrorMessage(error)}`);
+    log(verbose, "[analyse] Falling back to deterministic capture analysis.");
+    return buildDeterministicAnalysis(elementMap, requestedFeature);
+  }
 }
 function buildSystemPrompt() {
   return `
@@ -778,11 +1461,12 @@ RULES:
 7. If no status or alert region was captured, avoid scenarios that depend on unseen server-side validation messages.
 8. Scope must match intent complexity. Simple 1 to 2 claim requests should produce only 1 to 2 scenarios.
 9. For presence-only intents such as "verify X" or "X is present", only assert visibility. Do not click and do not assert outcomes after clicking.
-10. For fill steps, never use the literal word "value". If matching CT_VAR_* variables are listed in the prompt, use them in human-readable step text and use a realistic non-generic runtime value in the JSON value field. Otherwise use a field-specific fallback such as test-username or test-password.
-11. The "selector" field must be a raw selector expression such as locator("#username") or getByRole('button', { name: "Login" }). Never wrap selectors in page. or page.locator("...") inside JSON.
-12. Tie-breaker for multiple matching elements: prefer highest confidence, then interactive elements, then the first visible-looking candidate.
-13. If a page clearly contains login or auth fields, do not create submit scenarios that only click the button. Include realistic fill steps for captured username/email and password inputs when the intent asks for auth interaction.
-14. "verify title" means the main visible heading on the page, not the browser tab title, unless the intent explicitly says browser title, tab title, or page title.
+${RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE2}
+11. For fill steps, never use the literal word "value". If matching CT_VAR_* variables are listed in the prompt, use them in human-readable step text and use a realistic non-generic runtime value in the JSON value field. Otherwise use a field-specific fallback such as test-username or test-password.
+12. The "selector" field must be a raw selector expression such as locator("#username") or getByRole('button', { name: "Login" }). Never wrap selectors in page. or page.locator("...") inside JSON.
+13. Tie-breaker for multiple matching elements: prefer highest confidence, then interactive elements, then the first visible-looking candidate.
+14. If a page clearly contains login or auth fields, do not create submit scenarios that only click the button. Include realistic fill steps for captured username/email and password inputs when the intent asks for auth interaction.
+15. "verify title" means the main visible heading on the page, not the browser tab title, unless the intent explicitly says browser title, tab title, or page title.
 
 OUTPUT SCHEMA:
 {
@@ -982,7 +1666,7 @@ function sanitizeAnalysis(analysis, elementMap, requestedFeature) {
     resolvedPrefix
   ).slice(0, intentProfile.maxScenarios);
   const useAuthFallback = shouldUseAuthFallback(authElements, intentAlignedScenarios, intentProfile);
-  const fallbackScenarios = intentProfile.mode === "presence" ? buildPresenceOnlyScenarios(elementMap, requestedFeature, resolvedPrefix) : useAuthFallback ? buildAuthFallbackScenarios(elementMap, resolvedPrefix, authElements) : buildFallbackScenarios(elementMap, resolvedPrefix);
+  const fallbackScenarios = intentProfile.mode === "presence" ? buildPresenceOnlyScenarios(elementMap, requestedFeature, resolvedPrefix) : useAuthFallback ? buildAuthFallbackScenarios(elementMap, resolvedPrefix, authElements, requestedFeature) : buildFallbackScenarios(elementMap, resolvedPrefix, requestedFeature);
   const finalScenarios = useAuthFallback ? fallbackScenarios.slice(0, intentProfile.maxScenarios) : intentAlignedScenarios.length > 0 ? intentAlignedScenarios : fallbackScenarios.slice(0, intentProfile.maxScenarios);
   return {
     ...analysis,
@@ -1048,13 +1732,72 @@ function normalizeAssertion(candidate, selectors) {
   return assertion;
 }
 function buildFallbackScenarios(elementMap, prefix) {
+  return buildFallbackScenariosForFeature(elementMap, prefix, "");
+}
+function buildFallbackScenariosForFeature(elementMap, prefix, feature) {
+  const normalizedFeature = feature.toLowerCase();
   const heading = elementMap.elements.find((element) => element.category === "heading");
   const emailInput = elementMap.elements.find((element) => element.category === "input" && (element.attributes.type === "email" || /email/.test(`${element.name ?? ""} ${String(element.attributes.label ?? "")}`.toLowerCase())));
   const passwordInput = elementMap.elements.find((element) => element.category === "input" && element.attributes.type === "password");
   const submitButton = elementMap.elements.find((element) => element.category === "button" && /login|sign in|submit|continue/i.test(element.name ?? "")) ?? elementMap.elements.find((element) => element.category === "button");
+  const alert = findAlertElement(elementMap);
   const scenarios = [];
   const tag = (value) => normalizeTag(value);
   const nextId = (index) => `${prefix}-${String(900 + index).padStart(3, "0")}`;
+  const wantsHiddenAlertOnLoad = /\b(error|alert|message)\b/.test(normalizedFeature) && /\b(not shown|not visible|hidden|not present|gone|absent)\b/.test(normalizedFeature) && /\b(first load|first loads|first loads?|page first loads|initial load|on load)\b/.test(normalizedFeature);
+  const wantsVisibleAlert = /\b(error|alert|message|invalid|incorrect|required|validation)\b/.test(normalizedFeature) && !wantsHiddenAlertOnLoad;
+  if (wantsHiddenAlertOnLoad && alert) {
+    return [{
+      id: `${prefix}-001`,
+      title: "Error message is hidden on initial load",
+      tags: [tag("negative"), tag("ui")],
+      steps: [
+        {
+          action: "navigate",
+          selector: "page",
+          value: elementMap.url,
+          human: "Navigate to the captured page"
+        }
+      ],
+      assertions: [
+        {
+          type: "hidden",
+          selector: alert.selector,
+          expected: "hidden",
+          human: `${alert.name || "Error message"} is not shown when the page first loads`,
+          playwright: `await expect(page.${alert.selector}).toBeHidden();`
+        }
+      ],
+      narrator: "We verify that the page does not expose an error surface before any user action.",
+      codeLevel: "beginner"
+    }];
+  }
+  if (wantsVisibleAlert && alert) {
+    return [{
+      id: `${prefix}-001`,
+      title: "Page exposes an alert message when requested",
+      tags: [tag("negative"), tag("ui")],
+      steps: [
+        {
+          action: "navigate",
+          selector: "page",
+          value: elementMap.url,
+          human: "Navigate to the captured page"
+        }
+      ],
+      assertions: [
+        {
+          type: "text",
+          selector: alert.selector,
+          expected: alert.name || "error",
+          human: "An alert message is shown",
+          playwright: `await expect(page.${alert.selector}).toContainText(/invalid|error|required/i);`
+        }
+      ],
+      narrator: "We validate the alert channel directly when the intent asks about an error message.",
+      codeLevel: "beginner"
+    }];
+  }
   if (heading) {
     scenarios.push({
       id: nextId(scenarios.length + 1),
@@ -1129,16 +1872,115 @@ function buildFallbackScenarios(elementMap, prefix) {
   }
   return scenarios.slice(0, 5);
 }
-function buildAuthFallbackScenarios(elementMap, prefix, authElements) {
+function buildAuthFallbackScenarios(elementMap, prefix, authElements, feature) {
   const { usernameInput, passwordInput, submitButton, heading } = authElements;
   if (!usernameInput || !passwordInput || !submitButton) {
-    return buildFallbackScenarios(elementMap, prefix);
+    return buildFallbackScenariosForFeature(elementMap, prefix, feature);
   }
+  const normalizedFeature = feature.toLowerCase();
   const scenarios = [];
   const tag = (value) => normalizeTag(value);
   const nextId = (index) => `${prefix}-${String(index).padStart(3, "0")}`;
   const usernameValue = inferAuthValue(usernameInput, "username");
   const passwordValue = inferAuthValue(passwordInput, "password");
+  const alert = findAlertElement(elementMap);
+  const wantsNavigation = /\b(valid credentials|correct credentials|successful login|log in successfully|login succeeds|sign in succeeds)\b/.test(normalizedFeature) || /\b(redirect|redirects|redirected|secure area|dashboard|redirected to|goes to|navigates? to)\b/.test(normalizedFeature);
+  const wantsError = /\b(wrong password|wrong credentials|invalid|incorrect|error message|shows an error|alert)\b/.test(normalizedFeature);
+  const successUrlPattern = deriveSuccessUrlPattern(elementMap, normalizedFeature);
+  if (wantsNavigation) {
+    return [{
+      id: `${prefix}-001`,
+      title: "Valid credentials redirect to the authenticated area",
+      tags: [tag("auth"), tag("happy-path")],
+      steps: [
+        {
+          action: "navigate",
+          selector: "page",
+          value: elementMap.url,
+          human: "Navigate to the login page"
+        },
+        {
+          action: "fill",
+          selector: usernameInput.selector,
+          value: usernameValue,
+          human: buildFillHuman("Fill in the username field", usernameInput.selector, usernameValue)
+        },
+        {
+          action: "fill",
+          selector: passwordInput.selector,
+          value: passwordValue,
+          human: buildFillHuman("Fill in the password field", passwordInput.selector, passwordValue)
+        },
+        {
+          action: "click",
+          selector: submitButton.selector,
+          value: "",
+          human: "Click the login button"
+        }
+      ],
+      assertions: [
+        {
+          type: "url",
+          selector: "page",
+          expected: successUrlPattern,
+          human: "User is redirected to the secure area",
+          playwright: `await expect(page).toHaveURL(/${successUrlPattern}/);`
+        }
+      ],
+      narrator: "We submit valid credentials and confirm that authentication changes the page URL.",
+      codeLevel: "beginner"
+    }];
+  }
+  if (wantsError) {
+    return [{
+      id: `${prefix}-001`,
+      title: "Wrong password shows an authentication error",
+      tags: [tag("auth"), tag("negative")],
+      steps: [
+        {
+          action: "navigate",
+          selector: "page",
+          value: elementMap.url,
+          human: "Navigate to the login page"
+        },
+        {
+          action: "fill",
+          selector: usernameInput.selector,
+          value: usernameValue,
+          human: buildFillHuman("Fill in the username field", usernameInput.selector, usernameValue)
+        },
+        {
+          action: "fill",
+          selector: passwordInput.selector,
+          value: "wrong-password",
+          human: buildFillHuman("Fill in the password field", passwordInput.selector, "wrong-password")
+        },
+        {
+          action: "click",
+          selector: submitButton.selector,
+          value: "",
+          human: "Click the login button"
+        }
+      ],
+      assertions: [
+        alert ? {
+          type: "text",
+          selector: alert.selector,
+          expected: alert.name || "error",
+          human: "An alert communicates the login failure",
+          playwright: `await expect(page.${alert.selector}).toContainText(/invalid|error|required/i);`
+        } : {
+          type: "text",
+          selector: usernameInput.selector,
+          expected: "error",
+          human: "An authentication error message is shown",
+          playwright: `await expect(page.getByRole('alert')).toContainText(/invalid|error|required/i);`
+        }
+      ],
+      narrator: "We use an invalid password and confirm the page surfaces an authentication error.",
+      codeLevel: "beginner"
+    }];
+  }
   scenarios.push({
     id: nextId(1),
     title: "Login form renders expected controls",
@@ -1298,17 +2140,18 @@ function getAvailableCtVarKeys2() {
 }
 function buildIntentProfile(feature) {
   const normalized = feature.toLowerCase();
+  const countIntent = /\b(?:how many|count|number of|return the count|exactly\s+\d+|there (?:is|are)\s+\d+)/.test(normalized);
   const wantsHeading = /\b(?:title|heading)\b/.test(normalized) && !/\b(?:browser title|tab title|page title)\b/.test(normalized);
   const presenceOnly = isPresenceOnlyIntent(normalized);
   const authIntent = /\b(?:login|log in|sign in|auth|credentials?)\b/.test(normalized) && !presenceOnly;
   const formIntent = /\b(?:form|submit|field|input|enter|fill|type)\b/.test(normalized) && !presenceOnly && !authIntent;
   const flowIntent = /\b(?:flow|journey|checkout|purchase|complete|works?)\b/.test(normalized) && !presenceOnly && !authIntent && !formIntent;
-  const mode = presenceOnly ? "presence" : authIntent ? "auth" : formIntent ? "form" : flowIntent ? "flow" : "generic";
+  const mode = countIntent ? "count" : presenceOnly ? "presence" : authIntent ? "auth" : formIntent ? "form" : flowIntent ? "flow" : "generic";
   const claimCount = countIntentClaims(feature);
   return {
     feature,
     mode,
-    maxScenarios: mode === "presence" ? Math.min(Math.max(claimCount, 1), 2) : mode === "auth" || mode === "form" ? Math.min(Math.max(claimCount, 3), 5) : mode === "flow" ? Math.min(Math.max(claimCount, 4), 6) : Math.min(Math.max(claimCount, 1), 3),
+    maxScenarios: mode === "count" ? 1 : mode === "presence" ? Math.min(Math.max(claimCount, 1), 2) : mode === "auth" || mode === "form" ? Math.min(Math.max(claimCount, 3), 5) : mode === "flow" ? Math.min(Math.max(claimCount, 4), 6) : Math.min(Math.max(claimCount, 1), 3),
     wantsHeading
   };
 }
@@ -1323,11 +2166,42 @@ function isPresenceOnlyIntent(normalizedFeature) {
   return presenceWords && !actionWords;
 }
 function applyIntentPolicy(scenarios, elementMap, intentProfile, prefix) {
+  if (intentProfile.mode === "count") {
+    return buildCountScenarios(elementMap, intentProfile.feature, prefix);
+  }
   if (intentProfile.mode !== "presence") {
     return scenarios.slice(0, intentProfile.maxScenarios);
   }
   return buildPresenceOnlyScenarios(elementMap, intentProfile.feature, prefix);
 }
+function buildCountScenarios(elementMap, feature, prefix) {
+  const normalized = feature.toLowerCase();
+  const countedElements = pickCountedElements(elementMap, normalized);
+  const selector = countSelectorForFeature(normalized, countedElements);
+  const count = countedElements.length;
+  return [{
+    id: `${prefix}-${String(1).padStart(3, "0")}`,
+    title: feature,
+    tags: ["@smoke", "@ui"],
+    steps: [
+      {
+        action: "navigate",
+        selector: "page",
+        value: elementMap.url,
+        human: `Navigate to ${elementMap.url}`
+      }
+    ],
+    assertions: [{
+      type: "count",
+      selector,
+      expected: String(count),
+      human: `There are exactly ${count} matching elements`,
+      playwright: `await expect(page.${selector}).toHaveCount(${count});`
+    }],
+    narrator: "We count only the element type requested by the user.",
+    codeLevel: "beginner"
+  }];
+}
 function buildPresenceOnlyScenarios(elementMap, feature, prefix) {
   const claims = extractPresenceClaims(feature, elementMap);
   if (claims.length === 0) return buildFallbackScenarios(elementMap, prefix).slice(0, 1);
@@ -1360,11 +2234,9 @@ function extractPresenceClaims(feature, elementMap) {
   for (const segment of segments) {
     const normalized = segment.toLowerCase();
     if (/\b(?:title|heading)\b/.test(normalized) && !/\b(?:browser title|tab title|page title)\b/.test(normalized)) {
-      const heading = chooseHeadingElement(elementMap);
-      const selector2 = heading?.selector ?? `getByRole('heading')`;
       claims.push({
-        selector: selector2,
-        human: `${heading?.name || "Main page heading"} is visible`
+        selector: `getByRole('heading')`,
+        human: `${chooseHeadingElement(elementMap)?.name || "Main page heading"} is visible`
       });
       continue;
     }
@@ -1431,8 +2303,55 @@ function detectAuthElements(elementMap) {
   const heading = elementMap.elements.find((element) => element.category === "heading" && /login|sign in|auth/.test((element.name ?? "").toLowerCase())) ?? elementMap.elements.find((element) => element.category === "heading");
   return { usernameInput, passwordInput, submitButton, heading };
 }
+function findAlertElement(elementMap) {
+  return elementMap.elements.find((element) => element.role === "alert" || element.category === "status" || String(element.attributes.role ?? "").toLowerCase() === "alert");
+}
+function deriveSuccessUrlPattern(elementMap, normalizedFeature) {
+  const explicitPath = normalizedFeature.match(/\/[a-z0-9/_-]+/i)?.[0] ?? (/\bsecure area\b/.test(normalizedFeature) ? "/secure" : void 0);
+  if (explicitPath) {
+    return explicitPath.replace(/^\/+/, "").split("/").map(escapeForRegex).join("\\/");
+  }
+  const authLink = elementMap.elements.find((element) => {
+    if (element.category !== "link") return false;
+    const href2 = String(element.attributes.href ?? "");
+    const label = `${element.name ?? ""} ${href2}`.toLowerCase();
+    return /\b(secure|dashboard|home|app)\b/.test(label);
+  });
+  const href = String(authLink?.attributes.href ?? "");
+  if (href.startsWith("/")) {
+    return href.replace(/^\/+/, "").split("/").map(escapeForRegex).join("\\/");
+  }
+  return "secure|dashboard|home|app";
+}
+function buildDeterministicAnalysis(elementMap, requestedFeature) {
+  const intentProfile = buildIntentProfile(requestedFeature);
+  const suggestedPrefix = inferPrefix({
+    featureText: requestedFeature,
+    url: elementMap.url
+  }).toUpperCase();
+  const authElements = detectAuthElements(elementMap);
+  let scenarios = intentProfile.mode === "count" ? buildCountScenarios(elementMap, requestedFeature, suggestedPrefix) : intentProfile.mode === "presence" ? buildPresenceOnlyScenarios(elementMap, requestedFeature, suggestedPrefix) : intentProfile.mode === "auth" || intentProfile.mode === "form" ? buildAuthFallbackScenarios(elementMap, suggestedPrefix, authElements, requestedFeature) : buildFallbackScenariosForFeature(elementMap, suggestedPrefix, requestedFeature);
+  if (scenarios.length === 0 && (authElements.usernameInput || authElements.passwordInput || authElements.submitButton)) {
+    scenarios = buildAuthFallbackScenarios(elementMap, suggestedPrefix, authElements, requestedFeature);
+  }
+  if (scenarios.length === 0) {
+    scenarios = buildFallbackScenariosForFeature(elementMap, suggestedPrefix, requestedFeature);
+  }
+  const finalScenarios = scenarios.slice(0, intentProfile.maxScenarios);
+  return {
+    url: elementMap.url,
+    feature: requestedFeature,
+    suggestedPrefix,
+    scenarios: finalScenarios,
+    analysisNotes: "Generated deterministic capture-backed scenarios because LLM analysis was unavailable.",
+    audioSummary: buildAudioSummary(requestedFeature, finalScenarios)
+  };
+}
+function shortErrorMessage(error) {
+  return String(error?.message ?? error ?? "Unknown error").split("\n")[0];
+}
 function shouldUseAuthFallback(authElements, scenarios, intentProfile) {
-  if (intentProfile.mode === "presence") return false;
+  if (intentProfile.mode !== "auth" && intentProfile.mode !== "form") return false;
   if (!authElements.usernameInput || !authElements.passwordInput || !authElements.submitButton) return false;
   if (scenarios.length === 0) return true;
   const hasCredentialEntry = scenarios.some((scenario) => {
@@ -1456,8 +2375,26 @@ function defaultStepHuman(action, selector, value) {
 function normalizeStepHuman(human, action, selector, value) {
   if (action !== "fill" && action !== "select") return human;
   if (!value) return human;
-  if (/\bwith\s+['"`]/i.test(human) || /\$\{CT_VAR_[A-Z0-9_]+\}/.test(human)) return human;
-  return buildFillHuman(human, selector, value);
+  const explicitTemplate = /\$\{CT_VAR_[A-Z0-9_]+\}/.test(human);
+  const quotedValue = human.match(/\bwith\s+['"`]([^'"`]+)['"`]/i)?.[1];
+  if (explicitTemplate) return human;
+  if (quotedValue && !isGenericFillValue(quotedValue)) return human;
+  const rewrittenBase = human.replace(/\s+with\s+['"`][^'"`]+['"`]\s*$/i, "").trim() || human;
+  return buildFillHuman(rewrittenBase, selector, value);
+}
+function pickCountedElements(elementMap, normalizedFeature) {
+  const category = /\bbutton/.test(normalizedFeature) ? "button" : /\blink/.test(normalizedFeature) ? "link" : /\bheading|title/.test(normalizedFeature) ? "heading" : /\binput|field|textbox|text box/.test(normalizedFeature) ? "input" : void 0;
+  if (category) {
+    return elementMap.elements.filter((element) => element.category === category);
+  }
+  return elementMap.elements.filter((element) => element.category === "button" || element.category === "link" || element.category === "input");
+}
+function countSelectorForFeature(normalizedFeature, elements) {
+  if (/\bbutton/.test(normalizedFeature)) return `getByRole('button')`;
+  if (/\blink/.test(normalizedFeature)) return `getByRole('link')`;
+  if (/\bheading|title/.test(normalizedFeature)) return `getByRole('heading')`;
+  if (/\binput|field|textbox|text box/.test(normalizedFeature)) return `getByRole('textbox')`;
+  return elements[0]?.selector ?? `locator('*')`;
 }
 function normalizePlaywrightAssertion(assertion) {
   const repaired = scopeBareSelectorsInAssertion(unwrapWrappedSelectorAssertion(assertion.playwright));
@@ -2251,7 +3188,7 @@ function saveSpecPreview(analysis, outputDir = "tests/preview") {
       if (step.action === "hover") lines.push(`  await ${selector}.hover();`);
     }
     for (const assertion of scenario.assertions) {
-      lines.push(`  ${ensureStatement2(assertion.playwright)}`);
+      lines.push(`  ${renderPreviewAssertion(assertion.playwright, assertion.human)}`);
     }
     lines.push("});");
     lines.push("");
@@ -2275,6 +3212,15 @@ function ensureStatement2(value) {
   if (!trimmed) return "// TODO: add assertion";
   return trimmed.endsWith(";") ? trimmed : `${trimmed};`;
 }
+function renderPreviewAssertion(playwright, human) {
+  const statement = ensureStatement2(playwright);
+  const headingMatch = statement.match(/^await expect\(page\.getByRole\((['"])heading\1\)\)\.toBeVisible\(\);$/);
+  const visibleSubject = String(human ?? "").match(/^(.+?) is visible$/)?.[1]?.trim();
+  if (headingMatch && visibleSubject && !/main page heading/i.test(visibleSubject)) {
+    return `await expect(page.getByRole("heading", { name: ${JSON.stringify(visibleSubject)} })).toBeVisible();`;
+  }
+  return statement;
+}
 
 // src/commands/tc.ts
 function slugify2(text) {