@pcamarajr/scout 0.9.0 → 0.11.0

package/dist/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -33,6 +33,44 @@ export interface GeoCoords {
     latitude: number;
     longitude: number;
 }
+/**
+ * A named viewport descriptor, declared in `scout.config.json` `viewports` (or
+ * shipped as a built-in). A `device` Playwright preset is the base; explicit
+ * fields override it (`{ device: "iPhone 13", height: 844 }` = the preset with
+ * its height pinned). `width`/`height` are required only when there is no
+ * `device` to take them from. Resolved into Playwright context options by
+ * `resolveViewport` at launch — never baked into the recorded script.
+ */
+export interface Viewport {
+    /** Playwright device preset name (e.g. "iPhone 13"); the base for overrides. */
+    device?: string;
+    width?: number;
+    height?: number;
+    deviceScaleFactor?: number;
+    isMobile?: boolean;
+    hasTouch?: boolean;
+    userAgent?: string;
+}
+/**
+ * One cookie applied to the browser context before the scenario runs. Resolved
+ * fresh from the spec each run (profile default + per-scenario frontmatter /
+ * override, merged by name) and set via Playwright `context.addCookies()` —
+ * never a replayable Step, like storageState/permissions. `value` may carry a
+ * `$ENV:VAR` placeholder, resolved at launch so the secret never lands in the
+ * committed spec or the LLM context. `domain`/`path` default to the host of
+ * `baseUrl` and `/` when omitted; `expires` is unix seconds (Playwright
+ * convention) and omitting it yields a session cookie.
+ */
+export interface ScenarioCookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
 /**
  * Browser permission policy resolved from a scenario's spec (file frontmatter
  * is the default, per-section keys override it, merged per-axis). Three states
@@ -121,13 +159,28 @@ export interface Scenario {
     notes?: string;
     /** Free-form tags (file-level + per-scenario, merged) */
     tags?: string[];
+    /**
+     * Viewport names this scenario runs in (file frontmatter default, replaced —
+     * not merged — by a per-section `viewports:` override). Each name must resolve
+     * against the built-in/config registry. Omitted = the config's default
+     * viewport. Declaring N names fans the scenario out into N verification units.
+     */
+    viewports?: string[];
     /** Browser permission policy (frontmatter default + per-section override). */
     permissions?: PermissionPolicy;
+    /**
+     * Cookies declared on the scenario (file frontmatter + per-section override,
+     * merged by name). The profile's cookies are merged in at launch, under
+     * these. Carries raw `$ENV:VAR` placeholders — resolved only at launch.
+     */
+    cookies?: ScenarioCookie[];
     /** Source spec file, relative to the project root */
     file: string;
 }
 export interface RunResult {
     slug: string;
+    /** Viewport name this run executed in — part of the run identity (`slug@viewport`). */
+    viewport: string;
     /** replay = cached deterministic steps; ai = agent-driven run */
     mode: "replay" | "ai";
     verdict: Verdict;
@@ -139,7 +192,7 @@ export interface RunResult {
     durationMs: number;
     screenshots: string[];
     trace?: string;
-    /** Paced preview clip (MP4, or WebM fallback) — only when --record-video and verified */
+    /** Paced demo clip (MP4, or WebM fallback) — only when --demo-video and verified */
     video?: string;
     /** true when this AI run replaced a broken cached script */
     healed?: boolean;

package/dist/viewports.d.ts

@@ -0,0 +1,54 @@
+import type { ScoutConfig } from "./config.js";
+import type { Scenario, Viewport } from "./types.js";
+/**
+ * A named viewport resolved into the browser-context parameters Playwright
+ * needs. Produced by {@link resolveViewport} from a {@link Viewport} descriptor
+ * (built-in or from config), spreading a `device` preset and letting explicit
+ * fields win on top. `width`/`height` are always present; the rest are omitted
+ * when neither the preset nor the descriptor sets them (Playwright defaults).
+ */
+export interface ResolvedViewport {
+    /** The registry name — also the script-file token and report key. */
+    name: string;
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+    isMobile?: boolean;
+    hasTouch?: boolean;
+    userAgent?: string;
+}
+/** The built-in default when neither the scenario nor the config picks one. */
+export declare const DEFAULT_VIEWPORT = "mobile";
+/**
+ * Curated viewports available without any config. A same-named entry in
+ * `scout.config.json` `viewports` overrides one of these. `mobile` emulates an
+ * iPhone 13 (touch + mobile UA + dsf 3) but pins the canonical 390×844 portrait
+ * so the demo-video aspect stays stable across runs.
+ */
+export declare const BUILTIN_VIEWPORTS: Record<string, Viewport>;
+export declare function isValidViewportName(name: string): boolean;
+/** The full viewport registry for a config: built-ins, overridden by config. */
+export declare function viewportRegistry(config: ScoutConfig): Record<string, Viewport>;
+/** The default viewport name — config override, else the built-in. */
+export declare function defaultViewportName(config: ScoutConfig): string;
+/**
+ * Resolve a named viewport into Playwright context options. Fail-loud on an
+ * unknown name, a `device` preset Playwright doesn't ship, or a descriptor that
+ * provides neither dimensions nor a preset to take them from.
+ */
+export declare function resolveViewport(name: string, config: ScoutConfig): ResolvedViewport;
+/**
+ * The viewports a scenario runs in: the explicit per-invocation `override`
+ * (ad-hoc, single), else the scenario's declared list, else the config default.
+ * Names only — existence is validated at resolution time ({@link resolveViewport}).
+ */
+export declare function runnableViewports(scenario: Scenario, config: ScoutConfig, override?: string): string[];
+/** One (scenario × viewport) verification unit. */
+export interface ScenarioViewport {
+    scenario: Scenario;
+    viewport: string;
+}
+/** Expand scenarios into their (scenario × viewport) units, for list/report. */
+export declare function expandScenarios(scenarios: Scenario[], config: ScoutConfig): ScenarioViewport[];
+/** The store key for a (scenario × viewport) run: `<slug>@<viewport>`. */
+export declare function runKey(slug: string, viewport: string): string;

package/dist/viewports.js

@@ -0,0 +1,83 @@
+import { devices } from "playwright";
+/** The built-in default when neither the scenario nor the config picks one. */
+export const DEFAULT_VIEWPORT = "mobile";
+/**
+ * Curated viewports available without any config. A same-named entry in
+ * `scout.config.json` `viewports` overrides one of these. `mobile` emulates an
+ * iPhone 13 (touch + mobile UA + dsf 3) but pins the canonical 390×844 portrait
+ * so the demo-video aspect stays stable across runs.
+ */
+export const BUILTIN_VIEWPORTS = {
+    mobile: { device: "iPhone 13", width: 390, height: 844 },
+    desktop: { width: 1280, height: 800 },
+    tablet: { device: "iPad Mini" },
+};
+/**
+ * Viewport names double as filesystem tokens (`<slug>@<name>.json`) and report
+ * keys, so they are constrained to a safe, stable charset — a typo or a name
+ * with a path/`@` character fails loud instead of writing a broken script path.
+ */
+const VIEWPORT_NAME_RE = /^[a-z0-9-]+$/;
+export function isValidViewportName(name) {
+    return VIEWPORT_NAME_RE.test(name);
+}
+/** The full viewport registry for a config: built-ins, overridden by config. */
+export function viewportRegistry(config) {
+    return { ...BUILTIN_VIEWPORTS, ...(config.viewports ?? {}) };
+}
+/** The default viewport name — config override, else the built-in. */
+export function defaultViewportName(config) {
+    return config.defaultViewport ?? DEFAULT_VIEWPORT;
+}
+function knownNames(registry) {
+    return Object.keys(registry).sort().join(", ");
+}
+/**
+ * Resolve a named viewport into Playwright context options. Fail-loud on an
+ * unknown name, a `device` preset Playwright doesn't ship, or a descriptor that
+ * provides neither dimensions nor a preset to take them from.
+ */
+export function resolveViewport(name, config) {
+    const registry = viewportRegistry(config);
+    const vp = registry[name];
+    if (!vp) {
+        throw new Error(`Unknown viewport "${name}". Known viewports: ${knownNames(registry)}.`);
+    }
+    const base = vp.device ? devices[vp.device] : undefined;
+    if (vp.device && !base) {
+        throw new Error(`Viewport "${name}" references unknown Playwright device "${vp.device}". See https://playwright.dev/docs/emulation#devices for valid names.`);
+    }
+    const width = vp.width ?? base?.viewport.width;
+    const height = vp.height ?? base?.viewport.height;
+    if (width == null || height == null) {
+        throw new Error(`Viewport "${name}" needs explicit width and height (or a "device" preset that provides them).`);
+    }
+    return {
+        name,
+        width,
+        height,
+        deviceScaleFactor: vp.deviceScaleFactor ?? base?.deviceScaleFactor,
+        isMobile: vp.isMobile ?? base?.isMobile,
+        hasTouch: vp.hasTouch ?? base?.hasTouch,
+        userAgent: vp.userAgent ?? base?.userAgent,
+    };
+}
+/**
+ * The viewports a scenario runs in: the explicit per-invocation `override`
+ * (ad-hoc, single), else the scenario's declared list, else the config default.
+ * Names only — existence is validated at resolution time ({@link resolveViewport}).
+ */
+export function runnableViewports(scenario, config, override) {
+    if (override)
+        return [override];
+    return scenario.viewports?.length ? scenario.viewports : [defaultViewportName(config)];
+}
+/** Expand scenarios into their (scenario × viewport) units, for list/report. */
+export function expandScenarios(scenarios, config) {
+    return scenarios.flatMap((scenario) => runnableViewports(scenario, config).map((viewport) => ({ scenario, viewport })));
+}
+/** The store key for a (scenario × viewport) run: `<slug>@<viewport>`. */
+export function runKey(slug, viewport) {
+    return `${slug}@${viewport}`;
+}
+//# sourceMappingURL=viewports.js.map

package/dist/viewports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewports.js","sourceRoot":"","sources":["../src/viewports.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcamarajr/scout",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Self-healing browser QA: natural-language scenarios verified by an AI agent, replayed deterministically in CI",
   "type": "module",
   "license": "MIT",

package/templates/AGENTS.md

@@ -38,25 +38,62 @@ Format:
 feature: Paywall          # optional; defaults to the filename
 profile: anon             # optional; default auth profile for scenarios below
 tags: [monetization]      # optional
+viewports: [mobile]       # optional; viewports each scenario below runs in
 ---
 
 ## Free user hits paywall on ep 3
 Open ep 3 of series X without login; the paywall appears with a signup CTA.
 
 ## Subscriber bypasses paywall
-profile: qa               # per-scenario override (also: notes, tags)
+profile: qa               # per-scenario override (also: notes, tags, viewports)
+viewports: [mobile, desktop]
 
 Logged-in subscriber opens ep 3; the episode plays with no paywall.
 ```
 
 Rules that matter when you author:
 
-- **Frontmatter** (YAML, optional): `feature` (defaults to the filename), `profile` (default auth profile), `tags`.
+- **Frontmatter** (YAML, optional): `feature` (defaults to the filename), `profile` (default auth profile), `tags`, `viewports`.
 - **Each `## heading` is one scenario.** Its logical slug is `<file-slug>/<scenario-slug>` (e.g. `paywall/free-user-hits-paywall-on-ep-3`) and must be unique across the suite. Duplicate headings in a file, or a scenario with no body text, are hard errors.
-- **Per-scenario overrides:** immediately under a heading you may place `profile:`, `notes:`, `tags:`, `grantPermissions:`, `denyPermissions:`, and `geolocation:` lines (before the prose) to override the file-level defaults.
+- **Per-scenario overrides:** immediately under a heading you may place `profile:`, `notes:`, `tags:`, `viewports:`, `grantPermissions:`, `denyPermissions:`, and `geolocation:` lines (before the prose) to override the file-level defaults.
 - **Body = flow + expected behavior, in plain language.** Describe what the user does and what must (or must not) be true. No CSS selectors, no Playwright code — the agent discovers the real elements at run time and records them.
 - A `.scout.md` whose every `##` lives inside a fenced ```` ``` ```` block parses as **zero scenarios** (that is how `example.scout.md` documents the format without polluting the suite).
 
+## Viewports (screen sizes)
+
+Each scenario runs in one or more **named viewports**. Declaring more than one fans the scenario out into independent verification units — each viewport gets its own recorded script (`<slug>@<viewport>.json`), its own verdict, and its own demo video. This is how you cover responsive behavior (the mobile hamburger vs the desktop nav).
+
+Built-in viewports, usable without any config:
+
+- **`mobile`** — iPhone 13 emulation (touch + mobile UA), pinned to 390×844.
+- **`desktop`** — 1280×800, no touch.
+- **`tablet`** — iPad Mini (768×1024, touch).
+
+Declare them in the **frontmatter** (default for every scenario in the file) and override **per scenario** — a per-scenario `viewports:` list **replaces** the file-level one (it does not merge like tags), so a scenario explicitly chooses its sizes. Omitting `viewports` everywhere uses the config's `defaultViewport` (`mobile`).
+
+```markdown
+---
+feature: Navigation
+viewports: [mobile, desktop]   # file default: every scenario runs in both
+---
+
+## Primary nav is reachable
+Open the home page and reach the "Pricing" link from the main navigation.
+
+## Hamburger menu opens on small screens
+viewports: [mobile]            # this one only matters on mobile
+
+Open the home page; tapping the menu button reveals the navigation drawer.
+```
+
+Add or override viewports in `scout.config.json` (`viewports`), where each entry is a Playwright `device` preset and/or explicit fields (`width`, `height`, `deviceScaleFactor`, `isMobile`, `hasTouch`, `userAgent`) — they compose, so `{ "device": "iPhone 13", "width": 414 }` is the preset with its width overridden. Set the fallback with `defaultViewport`.
+
+Notes:
+
+- Viewport names are limited to `[a-z0-9-]` (they become script-file tokens). A name not in the registry, or an unknown `device` preset, fails the run with a clear error.
+- `scout go --viewport <name>` forces one viewport ad-hoc for debugging (must exist in the registry); that run never persists a script.
+- The demo video follows the viewport — a `desktop` scenario records a landscape clip.
+
 ## Browser permissions
 
 Some flows hit native browser permission prompts (geolocation, notifications, camera, microphone) that the agent cannot click — they live outside the page DOM. Declare a permission policy so Scout sets it at browser launch, for both the AI run and deterministic replay. Three states **per permission**: