@ggui-ai/ui-visual-tester 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Public surface for `@ggui-ai/ui-visual-tester`.
+ *
+ * One function — {@link validateContractBehavior} — drives a generated
+ * component through every entry in its `actionSpec`, observes whether
+ * each click actually does something (mutates DOM that is bound to
+ * `contextSpec` state OR dispatches an action), and reports per-action
+ * failures.
+ *
+ * Closes the gap structural validators (zod schema, wire-preservation,
+ * compile/lint) miss: a component whose buttons render correctly but
+ * are wired to no-op handlers. The motivating regression: synthesized
+ * Counter contracts that wired increment/decrement to `useAction(...)`
+ * (one-shot dispatch to agent) instead of local state, so the visible
+ * `count` never updated.
+ *
+ * Playwright is an OPTIONAL peer dep. Callers must pass the
+ * `playwright-core` module (or compatible) via factory dep injection:
+ *
+ *   import { chromium } from 'playwright-core';
+ *   const result = await validateContractBehavior({
+ *     componentCode, contract,
+ *     playwright: { chromium },
+ *   });
+ *
+ * If `playwright` is omitted, the validator throws a clear error
+ * pointing the operator at the advanced-pod opt-in. This keeps the
+ * default OSS install free of the Chromium binary (~300MB).
+ *
+ * Classification gate:
+ *
+ *   For each `actionSpec[name]`:
+ *     - If the action's handler mutates a `contextSpec` slot (detected by
+ *       `nextStep` ABSENT on the entry — the action is "context-bound"),
+ *       require a DOM change as the success signal.
+ *     - If the action's handler dispatches to the agent (detected by
+ *       `nextStep` PRESENT on the entry — the action is "agent-bound"),
+ *       require a `dispatch(...)` call as the success signal.
+ *
+ *   When neither holds (label-only entry, no `nextStep`), accept EITHER
+ *   signal — DOM mutation OR dispatch — as success. This is the safest
+ *   default for actions whose authoring intent is ambiguous from the
+ *   contract alone.
+ *
+ *   This aligns with the actions-vs-context principle: `nextStep`
+ *   declares the agent-route intent at authoring time; without it,
+ *   the action is observation-only or local-only.
+ *
+ * Behavior
+ * --------
+ *
+ * For each entry in `contract.actionSpec`:
+ *
+ *   1. Render the component in a real Chromium tab via Playwright.
+ *   2. Find a button matching the action's `label` (aria-label first,
+ *      then visible-text contains, case-insensitive).
+ *   3. Snapshot the current DOM state.
+ *   4. Click the button.
+ *   5. Wait up to `timeoutMs` for the required signal (per the gate
+ *      above) to fire.
+ *   6. Classify: ok / action-no-effect / action-not-rendered /
+ *      render-failed.
+ *
+ * Empty `actionSpec` returns `{ ok: true, failures: [] }` (not
+ * applicable — nothing to test).
+ */
+import type { DataContract } from '@ggui-ai/protocol';
+import type { Browser as PlaywrightBrowser, BrowserContext as PlaywrightBrowserContext, Page as PlaywrightPage, LaunchOptions as PlaywrightLaunchOptions } from 'playwright-core';
+/**
+ * Minimal Playwright `chromium` surface the validator depends on.
+ *
+ * The full `playwright-core` shape is intentionally NOT imported here
+ * — we only require `chromium.launch(...)`. Callers may pass any
+ * module satisfying this shape (real Playwright, a stub for tests,
+ * `playwright` instead of `playwright-core`).
+ */
+export interface PlaywrightModule {
+    readonly chromium: {
+        launch(options?: PlaywrightLaunchOptions): Promise<PlaywrightBrowser>;
+    };
+}
+/** Re-exported for callers building their own driver. */
+export type { PlaywrightBrowser, PlaywrightBrowserContext, PlaywrightPage, };
+export interface ValidateContractBehaviorInput {
+    readonly componentCode: string;
+    readonly contract: DataContract;
+    readonly timeoutMs?: number;
+    /**
+     * Playwright module. Pass `{ chromium }` from `playwright-core` or
+     * `playwright`. Required — when absent the validator throws with a
+     * pointer to the advanced-pod opt-in.
+     */
+    readonly playwright: PlaywrightModule;
+}
+export type BehaviorFailureKind = 'action-no-effect' | 'action-not-rendered' | 'render-failed' | 'timeout';
+export interface BehaviorFailure {
+    readonly kind: BehaviorFailureKind;
+    readonly actionName?: string;
+    readonly diagnostic: string;
+}
+export interface ValidateContractBehaviorResult {
+    readonly ok: boolean;
+    readonly failures: readonly BehaviorFailure[];
+}
+export { validateContractBehavior } from './validate.js';
+/**
+ * Error thrown when {@link validateContractBehavior} is called without
+ * a `playwright` module. Surfaced verbatim so operator scripts can
+ * branch on it.
+ */
+export declare class PlaywrightNotAvailableError extends Error {
+    readonly name = "PlaywrightNotAvailableError";
+    constructor();
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EACV,OAAO,IAAI,iBAAiB,EAC5B,cAAc,IAAI,wBAAwB,EAC1C,IAAI,IAAI,cAAc,EACtB,aAAa,IAAI,uBAAuB,EACzC,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE;QACjB,MAAM,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;KACvE,CAAC;CACH;AAED,yDAAyD;AACzD,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,GACf,CAAC;AAEF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;CACvC;AAED,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,qBAAqB,GACrB,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAED,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEzD;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,SAAkB,IAAI,iCAAiC;;CASxD"}

package/dist/index.js

@@ -0,0 +1,15 @@
+export { validateContractBehavior } from './validate.js';
+/**
+ * Error thrown when {@link validateContractBehavior} is called without
+ * a `playwright` module. Surfaced verbatim so operator scripts can
+ * branch on it.
+ */
+export class PlaywrightNotAvailableError extends Error {
+    name = 'PlaywrightNotAvailableError';
+    constructor() {
+        super('@ggui-ai/ui-visual-tester: a Playwright module is required but was not passed. ' +
+            'Behavioral validation needs a Playwright module + Chromium binary. ' +
+            'Pass `{ chromium }` from `playwright-core` via the `playwright` field on the input. ' +
+            'Playwright is an optional peer dependency — install it only if you run behavioral validation.');
+    }
+}

package/dist/validate.d.ts

@@ -0,0 +1,31 @@
+import type { DataContract } from '@ggui-ai/protocol';
+import type { ValidateContractBehaviorInput, ValidateContractBehaviorResult } from './index.js';
+/**
+ * Per-action signal-classification, derived from the contract via
+ * Option C (the actions-vs-context principle).
+ *
+ * - `agent-bound`   — `actionSpec[name].nextStep` is present. The
+ *                     author has hinted that the agent should pick up
+ *                     this action; success ⇔ a dispatch fired.
+ * - `context-bound` — `nextStep` is absent. The action is observed
+ *                     locally (the rest of the page reads via
+ *                     `contextSpec`/local state) without agent routing;
+ *                     success ⇔ DOM changed.
+ *
+ * The classification is computed up-front in Node and forwarded into
+ * the page so the fixture's branch is deterministic.
+ */
+export type ActionClassification = 'agent-bound' | 'context-bound';
+/**
+ * Per Option C: classify each action by the contract shape alone.
+ *
+ *   `nextStep` present → agent-bound (dispatch required)
+ *   `nextStep` absent  → context-bound (DOM change required)
+ *
+ * The classification is deterministic and fully contract-derivable;
+ * no source-AST inspection, no LLM call. When a contract evolves to
+ * include `nextStep` mid-flight, the classification follows.
+ */
+export declare function classifyAction(contract: DataContract, actionName: string): ActionClassification;
+export declare function validateContractBehavior(input: ValidateContractBehaviorInput): Promise<ValidateContractBehaviorResult>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAIV,6BAA6B,EAC7B,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAYpB;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,eAAe,CAAC;AAqKnE;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,MAAM,GACjB,oBAAoB,CAMtB;AAeD,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,6BAA6B,GACnC,OAAO,CAAC,8BAA8B,CAAC,CAsCzC"}

package/dist/validate.js

@@ -0,0 +1,195 @@
+/**
+ * Node-side Playwright driver for `validateContractBehavior`.
+ *
+ * Spins up one headless Chromium browser per call, then iterates each
+ * `actionSpec` entry: one fresh `BrowserContext` + `Page` per action
+ * for isolation. Inside the page, the IIFE-bundled fixture runtime
+ * (built by `scripts/build-fixture-bundle.mjs` → `fixture/fixture-runtime.js`)
+ * mounts the component and runs the click-and-observe loop.
+ *
+ * The fixture is loaded via `addScriptTag({content: ...})` rather than
+ * a file URL — works around CORS in headless launch, lets us cache
+ * the bundle source on the Node side.
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PlaywrightNotAvailableError } from './index.js';
+const DEFAULT_TIMEOUT_MS = 5000;
+const SETTLE_MS = 200;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLE_PATH = resolve(__dirname, '../fixture/fixture-runtime.js');
+let bundleSourceCache = null;
+async function loadBundleSource() {
+    if (bundleSourceCache !== null)
+        return bundleSourceCache;
+    const src = await readFile(BUNDLE_PATH, 'utf8');
+    bundleSourceCache = src;
+    return src;
+}
+const FIXTURE_HTML = `<!doctype html>
+<html><head><meta charset="utf-8"><title>ggui-vt</title></head>
+<body><div id="root"></div></body></html>`;
+async function preparePage(browser) {
+    const ctx = await browser.newContext();
+    const page = await ctx.newPage();
+    await page.setContent(FIXTURE_HTML, { waitUntil: 'load' });
+    const bundle = await loadBundleSource();
+    await page.addScriptTag({ content: bundle });
+    await page.waitForFunction(() => typeof window
+        .__validateContractBehavior_run__ === 'function', undefined, { timeout: 10_000 });
+    return page;
+}
+function parseRunOutcome(value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        typeof value.status !== 'string') {
+        return {
+            status: 'render-failed',
+            diagnostic: `fixture returned unparseable result: ${JSON.stringify(value)}`,
+        };
+    }
+    const status = value.status;
+    switch (status) {
+        case 'render-failed': {
+            const diagnostic = value.diagnostic;
+            return {
+                status: 'render-failed',
+                diagnostic: typeof diagnostic === 'string' ? diagnostic : 'unknown',
+            };
+        }
+        case 'action-not-rendered':
+            return { status: 'action-not-rendered' };
+        case 'action-no-effect': {
+            const diagnostic = value.diagnostic;
+            return {
+                status: 'action-no-effect',
+                diagnostic: typeof diagnostic === 'string' ? diagnostic : 'no signal',
+            };
+        }
+        case 'ok': {
+            const dispatchFired = value.dispatchFired === true;
+            const domChanged = value.domChanged === true;
+            return { status: 'ok', dispatchFired, domChanged };
+        }
+        default:
+            return {
+                status: 'render-failed',
+                diagnostic: `fixture returned unknown status: ${status}`,
+            };
+    }
+}
+async function runOne(page, input) {
+    const serialized = {
+        componentCode: input.componentCode,
+        contractJson: JSON.stringify(input.contract),
+        actionName: input.actionName,
+        classification: input.classification,
+        settleMs: input.settleMs,
+        waitMs: input.waitMs,
+    };
+    const result = await page.evaluate(async (arg) => {
+        const fn = window.__validateContractBehavior_run__;
+        if (fn === undefined) {
+            return { status: 'render-failed', diagnostic: 'fixture runtime not loaded' };
+        }
+        return await fn({
+            componentCode: arg.componentCode,
+            contract: JSON.parse(arg.contractJson),
+            actionName: arg.actionName,
+            classification: arg.classification,
+            settleMs: arg.settleMs,
+            waitMs: arg.waitMs,
+        });
+    }, serialized);
+    return parseRunOutcome(result);
+}
+function classify(actionName, outcome) {
+    switch (outcome.status) {
+        case 'ok':
+            return null;
+        case 'render-failed':
+            return {
+                kind: 'render-failed',
+                actionName,
+                diagnostic: outcome.diagnostic,
+            };
+        case 'action-not-rendered':
+            return {
+                kind: 'action-not-rendered',
+                actionName,
+                diagnostic: `no button found matching actionSpec.${actionName}.label`,
+            };
+        case 'action-no-effect':
+            return {
+                kind: 'action-no-effect',
+                actionName,
+                diagnostic: `clicking actionSpec.${actionName} produced no required signal — ` +
+                    outcome.diagnostic,
+            };
+    }
+}
+/**
+ * Per Option C: classify each action by the contract shape alone.
+ *
+ *   `nextStep` present → agent-bound (dispatch required)
+ *   `nextStep` absent  → context-bound (DOM change required)
+ *
+ * The classification is deterministic and fully contract-derivable;
+ * no source-AST inspection, no LLM call. When a contract evolves to
+ * include `nextStep` mid-flight, the classification follows.
+ */
+export function classifyAction(contract, actionName) {
+    const entry = contract.actionSpec?.[actionName];
+    if (entry && typeof entry.nextStep === 'string' && entry.nextStep.length > 0) {
+        return 'agent-bound';
+    }
+    return 'context-bound';
+}
+function assertPlaywright(playwright) {
+    if (playwright === undefined ||
+        playwright === null ||
+        typeof playwright !== 'object' ||
+        typeof playwright.chromium !== 'object') {
+        throw new PlaywrightNotAvailableError();
+    }
+}
+export async function validateContractBehavior(input) {
+    const actionSpec = input.contract.actionSpec;
+    const actionNames = actionSpec ? Object.keys(actionSpec) : [];
+    if (actionNames.length === 0) {
+        return { ok: true, failures: [] };
+    }
+    assertPlaywright(input.playwright);
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const failures = [];
+    let browser = null;
+    try {
+        browser = await input.playwright.chromium.launch({ headless: true });
+        for (const name of actionNames) {
+            const page = await preparePage(browser);
+            try {
+                const classification = classifyAction(input.contract, name);
+                const outcome = await runOne(page, {
+                    componentCode: input.componentCode,
+                    contract: input.contract,
+                    actionName: name,
+                    classification,
+                    settleMs: SETTLE_MS,
+                    waitMs: timeoutMs,
+                });
+                const f = classify(name, outcome);
+                if (f !== null)
+                    failures.push(f);
+            }
+            finally {
+                await page.context().close();
+            }
+        }
+    }
+    finally {
+        if (browser !== null)
+            await browser.close();
+    }
+    return { ok: failures.length === 0, failures };
+}