@pygmalionjs/pygmalion 0.2.11 → 0.2.12

package/storyboard.d.ts

@@ -0,0 +1,298 @@
+export type StoryboardCaptureStatus =
+  'ready' | 'rendered-with-qa-failure' | 'capture-error';
+
+export interface StoryboardCaptureViewport {
+  width: number;
+  height: number;
+}
+
+export interface StoryboardCaptureDiagnostic {
+  stage: string;
+  code: string;
+  selector?: string;
+  label?: string;
+  message?: string;
+  viewport: StoryboardCaptureViewport;
+}
+
+export interface StoryboardCaptureScreenshot {
+  mediaType: 'image/png';
+  width: number;
+  height: number;
+  bytes: Uint8Array;
+}
+
+export interface StoryboardCaptureResult {
+  id: string;
+  route: string | null;
+  status: StoryboardCaptureStatus;
+  viewport: StoryboardCaptureViewport;
+  snapshot?: string;
+  screenshot?: StoryboardCaptureScreenshot;
+  domTree?: unknown;
+  diagnostics: StoryboardCaptureDiagnostic[];
+}
+
+export interface StoryboardCaptureHookContext<
+  TScreenCase = Record<string, unknown>,
+> {
+  context: unknown;
+  page: unknown;
+  screenCase: TScreenCase;
+  route: string;
+  signal?: AbortSignal;
+}
+
+export interface StoryboardCaptureOptions<
+  TScreenCase extends Record<string, unknown> = Record<string, unknown>,
+> {
+  browser: {
+    newContext(options: Record<string, unknown>): Promise<unknown>;
+  };
+  baseUrl: string | URL;
+  screenCase: TScreenCase;
+  signal?: AbortSignal;
+  hooks?: {
+    beforePreset?(
+      context: StoryboardCaptureHookContext<TScreenCase>,
+    ): void | Promise<void>;
+    afterPreset?(
+      context: StoryboardCaptureHookContext<TScreenCase>,
+    ): void | Promise<void>;
+  };
+  includeDomTree?: boolean;
+  includePreviewSnapshot?: boolean;
+  previewBaseToken?: string;
+  contextOptions?: Record<string, unknown>;
+  navigationOptions?: Record<string, unknown>;
+  screenshotOptions?: Record<string, unknown>;
+}
+
+export declare const STORYBOARD_CAPTURE_STATUSES: Readonly<{
+  ready: 'ready';
+  qaFailure: 'rendered-with-qa-failure';
+  captureError: 'capture-error';
+}>;
+
+export declare class StoryboardCaptureStageError extends Error {
+  readonly stage: string;
+  readonly details: Record<string, unknown>;
+  constructor(stage: string, error: unknown, details?: Record<string, unknown>);
+}
+
+export declare function captureStoryboardCase<
+  TScreenCase extends Record<string, unknown>,
+>(
+  options: StoryboardCaptureOptions<TScreenCase>,
+): Promise<StoryboardCaptureResult>;
+export declare function resolveStoryboardCaptureRoute(
+  screenCase: Record<string, unknown>,
+): unknown;
+export declare function resolveStoryboardCaptureUrl(
+  baseUrl: string | URL,
+  route: unknown,
+  environment?: Record<string, unknown>,
+): string;
+export declare function resolveStoryboardFixedTime(
+  preset: Record<string, unknown> | null | undefined,
+): string | null;
+export declare function hashStoryboardCapture(
+  value: string | Uint8Array,
+): string;
+export declare function normalizeStoryboardDomStructure(node: unknown): string;
+export declare function createStoryboardArtifactRecord(input: {
+  screenCase: {
+    id: string;
+    scenarioIds?: readonly string[];
+    width?: number;
+    height?: number;
+  };
+  domTree: unknown;
+  screenshot: string | Uint8Array;
+  route: string | null;
+}): {
+  id: string;
+  scenarioIds: string[];
+  route: string | null;
+  viewport: StoryboardCaptureViewport;
+  domStructureHash: string;
+  screenshotHash: string;
+};
+export declare function runStoryboardInteraction(
+  page: unknown,
+  interaction: Record<string, unknown>,
+): Promise<void>;
+export declare function runStoryboardAssertion(
+  page: unknown,
+  assertion: Record<string, unknown>,
+): Promise<void>;
+export declare function assertFinalStoryboardState(
+  page: unknown,
+  assertions: readonly Record<string, unknown>[],
+): Promise<void>;
+export declare function waitForStableStoryboardDocument(
+  page: unknown,
+  options?: {
+    attempts?: number;
+    requiredStableSamples?: number;
+    intervalMs?: number;
+    minimumWaitMs?: number;
+  },
+): Promise<boolean>;
+export declare function storyboardDocumentStabilitySignature(): string;
+export declare function storyboardCaptureCandidateTexts(
+  element: Element,
+): string[];
+export declare function findUnassertedStoryboardModal(
+  assertions?: readonly Record<string, unknown>[],
+): { role: string; label: string } | null;
+export declare function collectStoryboardDomTree(): unknown;
+export declare function serializeStoryboardPreviewDocument(
+  baseHref?: string,
+): string | null;
+
+export type StoryboardCaptureSchedulePhase =
+  'warm-up' | 'primary' | 'isolated-retry';
+
+export interface StoryboardCaptureScheduleContext<TResult> {
+  phase: StoryboardCaptureSchedulePhase;
+  attempt: number;
+  index: number;
+  total: number;
+  isolated: boolean;
+  requiresFreshContext: true;
+  previousResult?: TResult;
+  signal?: AbortSignal;
+}
+
+export interface StoryboardScheduledCaptureResult {
+  status: StoryboardCaptureStatus;
+  snapshot?: unknown;
+  screenshot?: unknown;
+  domTree?: unknown;
+  diagnostics?: readonly unknown[];
+  [key: string]: unknown;
+}
+
+export interface StoryboardCaptureScheduleOptions {
+  concurrency?: number;
+  isolatedRetryAttempts?: number;
+  onRetryPass?(pass: {
+    attempt: number;
+    totalAttempts: number;
+    indexes: number[];
+  }): void;
+  signal?: AbortSignal;
+}
+
+export declare const STORYBOARD_CAPTURE_SCHEDULER_LIMITS: Readonly<{
+  defaultConcurrency: 8;
+  maximumConcurrency: 16;
+}>;
+
+export declare function scheduleStoryboardCaptures<
+  TItem,
+  TResult extends StoryboardScheduledCaptureResult,
+>(
+  items: readonly TItem[],
+  capture: (
+    item: TItem,
+    context: StoryboardCaptureScheduleContext<TResult>,
+  ) => TResult | Promise<TResult>,
+  options?: StoryboardCaptureScheduleOptions,
+): Promise<TResult[]>;
+
+export interface RoutePreviewArtifactV3Capture {
+  status: StoryboardCaptureStatus;
+  viewport: StoryboardCaptureViewport;
+  snapshot?: string;
+  screenshot?: {
+    mediaType: 'image/png' | 'image/webp';
+    width: number;
+    height: number;
+    bytes: Uint8Array;
+  };
+  diagnostics?: readonly StoryboardCaptureDiagnostic[];
+}
+
+export interface RoutePreviewArtifactBundleV3 {
+  readonly version: 3;
+  readonly namespace: string;
+  readonly sourceRevision?: string;
+  readonly assets: {
+    readonly head: Readonly<Record<string, string>>;
+    readonly stylesheets: Readonly<Record<string, string>>;
+    readonly screenshots: Readonly<
+      Record<
+        string,
+        {
+          readonly mediaType: 'image/png' | 'image/webp';
+          readonly width: number;
+          readonly height: number;
+          readonly data: string;
+          readonly byteLength: number;
+        }
+      >
+    >;
+  };
+  readonly frames: Readonly<Record<string, unknown>>;
+}
+
+export declare const ROUTE_PREVIEW_ARTIFACT_V3_LIMITS: Readonly<
+  Record<string, number>
+>;
+export declare function createRoutePreviewArtifactV3(input: {
+  namespace: string;
+  sourceRevision?: string;
+  captures: Record<string, RoutePreviewArtifactV3Capture>;
+}): RoutePreviewArtifactBundleV3;
+export declare function validateRoutePreviewArtifactV3(bundle: unknown): {
+  valid: boolean;
+  errors: string[];
+  bytes: number;
+};
+export declare function validateRoutePreviewArtifactBundle(bundle: unknown): {
+  valid: boolean;
+  errors: string[];
+  bytes: number;
+};
+export declare function reconstructRoutePreviewArtifactSnapshotV3(
+  bundle: RoutePreviewArtifactBundleV3,
+  frameId: string,
+): string | null;
+export declare function reconstructRoutePreviewArtifactSnapshotsV3(
+  bundle: RoutePreviewArtifactBundleV3,
+): Record<string, string>;
+export declare function reconstructRoutePreviewArtifactScreenshotV3(
+  bundle: RoutePreviewArtifactBundleV3,
+  frameId: string,
+): {
+  mediaType: 'image/png' | 'image/webp';
+  width: number;
+  height: number;
+  bytes: Uint8Array;
+} | null;
+
+export declare const PYGMALION_STORYBOARD_CANONICAL_CONTROL: string;
+export declare function normalizeStoryboardSnapshot(
+  snapshot: string,
+): string | null;
+export declare function fingerprintStoryboardSnapshot(
+  snapshot: string,
+): string | null;
+export declare function recommendedStoryboardExecutionConcurrency(capabilities?: {
+  parallelism?: number;
+  totalMemoryBytes?: number;
+}): number;
+export declare function executeStoryboardCandidates(
+  candidates: readonly Record<string, unknown>[],
+  capture: (
+    candidate: Record<string, unknown>,
+    context: { signal: AbortSignal; index: number; total: number },
+  ) => unknown | Promise<unknown>,
+  options?: { concurrency?: number; timeoutMs?: number },
+): Promise<unknown[]>;
+export declare function canonicalizeStoryboardExecutions(
+  candidates: readonly Record<string, unknown>[],
+  executions: readonly Record<string, unknown>[],
+): unknown;