@democraft/playwright 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Democraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @democraft/playwright
+
+Playwright runtime for executing compiled Democraft IR against a real Chromium browser and writing a reusable recording manifest.
+
+This package consumes generated IR. It does not add a second public authoring API.

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+import { CaptureArtifactMetadata, DemoIR, RecordedDemoManifest, TargetSnapshot, RecordedStep } from '@democraft/schema';
+
+type RuntimeEnvironment = {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Device pixel ratio for screenshot capture. Higher values produce sharper
+     * screenshots (more device pixels per CSS pixel). Defaults to 2, which
+     * captures at 2× resolution — e.g. a 1920×1080 viewport yields 3840×2160
+     * PNGs. This gives the Remotion renderer enough pixel density for camera
+     * zoom without pixelation.
+     */
+    deviceScaleFactor?: number;
+    locale?: string;
+    timezone?: string;
+    storageState?: string;
+    /**
+     * How the capture runtime decides a page is "ready" before taking each
+     * screenshot. When omitted, the runtime uses sensible defaults
+     * (`DEFAULT_SETTLE_STRATEGY`) so demos are captured after the page settles
+     * without any author configuration. Pass `false` to disable settling and
+     * fall back to a fixed hold before each screenshot.
+     *
+     * See {@link SettleStrategy} for the tunables (idle window, timeout, signal).
+     */
+    settle?: SettleStrategy | false;
+};
+/**
+ * Strategy for detecting that a page has settled before a screenshot is taken.
+ *
+ * Modern web apps keep loading content after the DOM is ready — data fetches,
+ * hydration, animations, lazy images. A screenshot taken the instant an action
+ * returns often captures a half-rendered view, so downstream captions/callouts
+ * narrate something the screen isn't showing yet.
+ *
+ * Rather than wait a fixed duration (too short for slow pages, dead air for
+ * fast ones), the settle gate waits for the page to **stop changing**. Two
+ * signals detect that, chosen because they measure what the viewer actually
+ * sees (not network activity, which `networkidle` relies on and is flaky with
+ * polling/analytics/SSE — officially discouraged by Playwright):
+ *
+ * - `"dom"` — a `MutationObserver` counts DOM mutations; idle when none occur
+ *   for `idleWindowMs`.
+ * - `"visual"` — periodic low-resolution screenshots are compared; idle when
+ *   two consecutive samples are identical within `idleWindowMs`. Catches
+ *   pure-visual motion (CSS animations, fade-ins) that doesn't touch the DOM.
+ * - `"both"` (default) — idle only when both signals agree. Most robust.
+ *
+ * Settling is best-effort: if the page never quiets down, the gate gives up at
+ * `timeoutMs` and captures anyway (never throws), so a pathological page can't
+ * stall the whole capture.
+ */
+type SettleStrategy = {
+    /**
+     * How long the page must stay quiet (no DOM mutations and/or no visual
+     * changes, per `signal`) before it's considered settled. Shorter is more
+     * responsive; longer is more conservative. Default 350ms.
+     */
+    idleWindowMs?: number;
+    /**
+     * Maximum time to wait for the page to settle before capturing anyway
+     * (best-effort). Should be long enough for real loads but bounded so a
+     * misbehaving page (infinite animation, endless polling UI) can't stall the
+     * capture. Default 4000ms.
+     */
+    timeoutMs?: number;
+    /**
+     * Which signal(s) to use to detect "quiet".
+     * - `"dom"` — DOM mutations only (structural rendering).
+     * - `"visual"` — screenshot diffing only (pure-visual motion).
+     * - `"network"` — in-flight fetch/XHR only (pending data requests).
+     * - `"both"` (default) — all three; settled only when every signal agrees.
+     *   Most robust, since each catches a different kind of in-flight work
+     *   (e.g. the network signal reveals a pending data fetch even when the DOM
+     *   is momentarily quiet).
+     */
+    signal?: "dom" | "visual" | "network" | "both";
+};
+/**
+ * Default settle strategy: both signals, 350ms idle window, 4s timeout. Tuned
+ * for typical SaaS apps (App Router / SPA with hydration + data fetch).
+ */
+declare const DEFAULT_SETTLE_STRATEGY: Required<SettleStrategy>;
+type RunDemoOptions = {
+    outputDir?: string;
+    /** Managed capture root used only when outputDir is omitted. */
+    captureRootDir?: string;
+    headless?: boolean;
+    environment?: RuntimeEnvironment;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Called after the capture directory and initial metadata exist. */
+    onArtifactCreated?: (artifact: {
+        captureRunId: string;
+        outputDir: string;
+        manifestPath: string;
+        metadataPath: string;
+    }) => void | Promise<void>;
+};
+type BrowserLike = {
+    close(): Promise<void>;
+    newContext(options?: Record<string, unknown>): Promise<BrowserContextLike>;
+};
+type BrowserContextLike = {
+    newPage(): Promise<PageLike>;
+    close(): Promise<void>;
+    tracing?: {
+        start(options?: Record<string, unknown>): Promise<void>;
+        stop(options?: Record<string, unknown>): Promise<void>;
+    };
+};
+type PageLike = {
+    goto(url: string): Promise<unknown>;
+    url(): string;
+    getByRole(role: string, options?: {
+        name?: string;
+    }): LocatorLike;
+    getByLabel(text: string): LocatorLike;
+    getByTestId(id: string): LocatorLike;
+    getByText(text: string): LocatorLike;
+    video?(): {
+        path(): Promise<string>;
+    } | null;
+    screenshot?(options?: Record<string, unknown>): Promise<Buffer>;
+    waitForTimeout?(durationMs: number): Promise<void>;
+    /**
+     * Optional navigation gate. SPAs (Next.js App Router, React Router) resolve
+     * client-side navigation AFTER `<a>`/`<Link>` click resolves, so a click
+     * that changes the route returns before the new view is mounted. When
+     * present, the runtime races this against a short timeout after a click so
+     * the next step sees the navigated page — without stalling on clicks that
+     * don't navigate (dialogs, toggles).
+     */
+    waitForLoadState?(state?: string): Promise<void>;
+    waitForURL?(url: string | RegExp, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Evaluate a function in the page context. Used by the settle gate to
+     * install/read a MutationObserver for DOM-idle detection. Absent in
+     * lightweight mocks (settle falls back to the visual signal only).
+     */
+    evaluate?<T>(fn: () => T | Promise<T>): Promise<T>;
+};
+type LocatorLike = {
+    click(): Promise<void>;
+    fill(value: string): Promise<void>;
+    selectOption(value: string): Promise<unknown>;
+    boundingBox(options?: {
+        timeout?: number;
+    }): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null>;
+    isVisible(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    textContent(): Promise<string | null>;
+    /**
+     * Optional auto-polling visibility gate. Unlike `isVisible` (which reports
+     * the *current* state), `waitFor({ state: "visible" })` blocks until the
+     * element is visible or the timeout elapses — the right primitive for SPA
+     * views that mount a frame after navigation. Absent in lightweight mocks.
+     */
+    waitFor?(state: {
+        state: "visible";
+        timeout?: number;
+    }): Promise<unknown>;
+};
+type PlaywrightBindings = {
+    chromium: {
+        launch(options?: {
+            headless?: boolean;
+        }): Promise<BrowserLike>;
+    };
+};
+
+declare const CAPTURE_ENVIRONMENT_HASH_PREFIX = "capture-env-v1:sha256:";
+type CaptureRuntimeIdentity = {
+    node: string;
+    platform: string;
+    arch: string;
+    engine: "chromium";
+};
+declare function resolveCaptureEnvironment(options?: Pick<RunDemoOptions, "environment" | "headless" | "timeoutMs">, runtime?: CaptureRuntimeIdentity): Promise<{
+    environment: CaptureArtifactMetadata["environment"];
+    captureEnvironmentHash: string;
+}>;
+
+declare function runDemo(ir: DemoIR, options?: RunDemoOptions): Promise<RecordedDemoManifest>;
+declare function runDemoWithBindings(ir: DemoIR, bindings: PlaywrightBindings, options?: RunDemoOptions): Promise<RecordedDemoManifest>;
+
+declare function resolveTarget(ir: DemoIR, page: PageLike, targetId: string, timeoutMs?: number): Promise<{
+    locator?: LocatorLike;
+    snapshot: TargetSnapshot;
+}>;
+
+declare function canonicalScreenshotFilename(sceneId: string, stepId: string): string;
+declare function screenshotRelativePath(sceneId: string, stepId: string): string;
+declare function resolveRecordedScreenshotPath(captureDirectory: string, step: Pick<RecordedStep, "sceneId" | "stepId" | "screenshotPath">): string | undefined;
+
+type CaptureArtifact = {
+    captureRunId: string;
+    demoId: string;
+    directory: string;
+    metadataPath: string;
+    manifestPath: string;
+    screenshotsPath: string;
+    tracePath: string;
+    metadata: CaptureArtifactMetadata;
+    managed: boolean;
+    demoDirectory?: string;
+    releaseLock?: () => Promise<void>;
+};
+type CaptureEnvironmentMetadata = CaptureArtifactMetadata["environment"];
+type CreateCaptureArtifactOptions = {
+    rootDirectory: string;
+    outputDirectory?: string;
+    demoId: string;
+    definitionHash?: string;
+    captureHash?: string;
+    captureEnvironmentHash?: string;
+    environment: CaptureEnvironmentMetadata;
+    /** Internal/test tuning; production defaults use a 30s renewable lease. */
+    lockOptions?: CaptureLeaseOptions;
+};
+type ArtifactDependencies = {
+    now?: () => Date;
+    randomId?: () => string;
+};
+declare function createCaptureArtifact(options: CreateCaptureArtifactOptions, dependencies?: ArtifactDependencies): Promise<CaptureArtifact>;
+declare function startCaptureArtifact(artifact: CaptureArtifact, now?: Date): Promise<void>;
+declare function completeCaptureArtifact(artifact: CaptureArtifact, options?: {
+    recordingPath?: string;
+    traceAvailable?: boolean;
+    now?: Date;
+}): Promise<void>;
+declare function failCaptureArtifact(artifact: CaptureArtifact, error: unknown, now?: Date): Promise<void>;
+declare function cancelCaptureArtifact(artifact: CaptureArtifact, now?: Date): Promise<void>;
+declare function writeCaptureManifestAtomic(artifact: CaptureArtifact, json: string): Promise<void>;
+declare function resolveLatestCompletedCapture(rootDirectory: string, demoId: string): Promise<{
+    captureDir: string;
+    manifestPath: string;
+    captureRunId?: string;
+    legacy: boolean;
+} | undefined>;
+declare function isReusableCaptureDirectory(directory: string, demoId: string): Promise<boolean>;
+declare function captureSlug(demoId: string): string;
+declare function captureNamespace(demoId: string): string;
+declare class CaptureAbortError extends Error {
+    constructor();
+}
+type CaptureLeaseOptions = {
+    leaseMs?: number;
+    retryMs?: number;
+    maxAttempts?: number;
+    malformedStaleMs?: number;
+    insideReleaseGuard?: () => void | Promise<void>;
+    insideRecoveryGuard?: () => void | Promise<void>;
+};
+type CaptureLeaseRelease = (() => Promise<void>) & {
+    refresh: () => Promise<boolean>;
+};
+declare function acquireCaptureLeaseLock(lockPath: string, options?: CaptureLeaseOptions): Promise<CaptureLeaseRelease>;
+declare function redactCaptureErrorMessage(error: unknown, directory?: string): string;
+
+export { type BrowserContextLike, type BrowserLike, CAPTURE_ENVIRONMENT_HASH_PREFIX, CaptureAbortError, type CaptureArtifact, type CaptureLeaseOptions, type CaptureLeaseRelease, type CaptureRuntimeIdentity, type CreateCaptureArtifactOptions, DEFAULT_SETTLE_STRATEGY, type LocatorLike, type PageLike, type PlaywrightBindings, type RunDemoOptions, type RuntimeEnvironment, type SettleStrategy, acquireCaptureLeaseLock, cancelCaptureArtifact, canonicalScreenshotFilename, captureNamespace, captureSlug, completeCaptureArtifact, createCaptureArtifact, failCaptureArtifact, isReusableCaptureDirectory, redactCaptureErrorMessage, resolveCaptureEnvironment, resolveLatestCompletedCapture, resolveRecordedScreenshotPath, resolveTarget, runDemo, runDemoWithBindings, screenshotRelativePath, startCaptureArtifact, writeCaptureManifestAtomic };