@pixeyedev/shared 0.4.0

package/dist/attributes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * DOM attributes for controlling visual testing behavior.
+ *
+ * Native attributes are the canonical Pixeye attributes.
+ * Compat attributes are recognized from competitor tools and mapped to native equivalents.
+ */
+/** Pixeye native DOM attributes. */
+export declare const PIXEYE_ATTRIBUTES: {
+    /** Element should be masked (replaced with solid color) in diff comparison. */
+    readonly MASK: "data-pixeye-mask";
+    /** Element should be completely excluded from diff comparison. */
+    readonly IGNORE: "data-pixeye-ignore";
+    /** Element contains dynamic content (timestamps, counters). Triggers dom-flagged classification. */
+    readonly DYNAMIC: "data-pixeye-dynamic";
+    /** Wait for this element to appear before capturing screenshot. */
+    readonly WAIT: "data-pixeye-wait";
+    /** Element is a loading indicator. Wait for it to disappear before capturing. */
+    readonly LOADING: "data-pixeye-loading";
+};
+/** Region type that each attribute maps to in the metadata sidecar. */
+export type RegionType = 'mask' | 'ignore' | 'dynamic';
+/**
+ * Competitor attribute mappings. Each entry maps an external attribute + value
+ * to a Pixeye region type.
+ */
+export declare const COMPAT_ATTRIBUTES: Record<string, RegionType | Record<string, RegionType>>;
+/**
+ * All attribute selectors to scan in the DOM, with their resolved region types.
+ * Used by @pixeyedev/browser's scanRegions() function.
+ */
+export declare const ALL_ATTRIBUTE_SELECTORS: {
+    selector: string;
+    type: RegionType;
+}[];

package/dist/attributes.js

@@ -0,0 +1,57 @@
+/**
+ * DOM attributes for controlling visual testing behavior.
+ *
+ * Native attributes are the canonical Pixeye attributes.
+ * Compat attributes are recognized from competitor tools and mapped to native equivalents.
+ */
+/** Pixeye native DOM attributes. */
+export const PIXEYE_ATTRIBUTES = {
+    /** Element should be masked (replaced with solid color) in diff comparison. */
+    MASK: 'data-pixeye-mask',
+    /** Element should be completely excluded from diff comparison. */
+    IGNORE: 'data-pixeye-ignore',
+    /** Element contains dynamic content (timestamps, counters). Triggers dom-flagged classification. */
+    DYNAMIC: 'data-pixeye-dynamic',
+    /** Wait for this element to appear before capturing screenshot. */
+    WAIT: 'data-pixeye-wait',
+    /** Element is a loading indicator. Wait for it to disappear before capturing. */
+    LOADING: 'data-pixeye-loading'
+};
+/**
+ * Competitor attribute mappings. Each entry maps an external attribute + value
+ * to a Pixeye region type.
+ */
+export const COMPAT_ATTRIBUTES = {
+    // Argos CI
+    'data-visual-test': {
+        blackout: 'mask',
+        removed: 'ignore',
+        transparent: 'mask'
+    },
+    // Percy (BrowserStack)
+    'data-percy-ignore': 'ignore',
+    'data-percy-mask': 'mask',
+    // Chromatic
+    'data-chromatic': {
+        ignore: 'ignore'
+    }
+};
+/**
+ * All attribute selectors to scan in the DOM, with their resolved region types.
+ * Used by @pixeyedev/browser's scanRegions() function.
+ */
+export const ALL_ATTRIBUTE_SELECTORS = [
+    // Native
+    { selector: `[${PIXEYE_ATTRIBUTES.MASK}]`, type: 'mask' },
+    { selector: `[${PIXEYE_ATTRIBUTES.IGNORE}]`, type: 'ignore' },
+    { selector: `[${PIXEYE_ATTRIBUTES.DYNAMIC}]`, type: 'dynamic' },
+    // Argos compat
+    { selector: '[data-visual-test="blackout"]', type: 'mask' },
+    { selector: '[data-visual-test="removed"]', type: 'ignore' },
+    { selector: '[data-visual-test="transparent"]', type: 'mask' },
+    // Percy compat
+    { selector: '[data-percy-ignore]', type: 'ignore' },
+    { selector: '[data-percy-mask]', type: 'mask' },
+    // Chromatic compat
+    { selector: '[data-chromatic="ignore"]', type: 'ignore' }
+];

package/dist/failureReasons.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Customer-facing translation for `fail_reason` codes.
+ *
+ * Lives in `@pixeyedev/shared` so the API and the UI render identical copy
+ * — backend uses it for emails / commit-status descriptions, UI uses it for
+ * the FailureCard at the top of failed pipeline / build detail pages.
+ *
+ * Adding a new failure code: add it to the `FailReason` type in `types.ts`
+ * AND add a row here. The TypeScript compiler enforces exhaustiveness.
+ */
+import type { FailReason } from './types.js';
+export interface FailureCopy {
+    /** Short, customer-facing title. Goes in the FailureCard headline + email subject. */
+    title: string;
+    /** One-sentence remedy / next-step. Plain text, customer-friendly. */
+    remedy: string;
+    /** Optional CTA the UI can render as a button (label + relative URL). */
+    cta?: {
+        label: string;
+        href: string;
+    };
+}
+export declare const FAILURE_COPY: Record<FailReason, FailureCopy>;
+/** Resolve a `fail_reason` code to its customer copy. Falls back to a generic message. */
+export declare const failureCopyFor: (reason: FailReason | string | null | undefined) => FailureCopy;

package/dist/failureReasons.js

@@ -0,0 +1,80 @@
+/**
+ * Customer-facing translation for `fail_reason` codes.
+ *
+ * Lives in `@pixeyedev/shared` so the API and the UI render identical copy
+ * — backend uses it for emails / commit-status descriptions, UI uses it for
+ * the FailureCard at the top of failed pipeline / build detail pages.
+ *
+ * Adding a new failure code: add it to the `FailReason` type in `types.ts`
+ * AND add a row here. The TypeScript compiler enforces exhaustiveness.
+ */
+export const FAILURE_COPY = {
+    'storage-quota-exceeded': {
+        title: 'Storage limit reached',
+        remedy: 'Your organization has hit its storage cap. Upgrade your plan or delete older builds to free space, then re-run the build.',
+        cta: { label: 'Upgrade plan', href: '/billing' }
+    },
+    'screenshot-quota-exceeded': {
+        title: 'Monthly screenshot limit reached',
+        remedy: 'Your organization has used all of its monthly screenshots. Upgrade your plan or wait for the next billing cycle.',
+        cta: { label: 'Upgrade plan', href: '/billing' }
+    },
+    'invalid-upload': {
+        title: 'Invalid upload payload',
+        remedy: 'The CLI sent screenshots that the server could not accept (bad hash, missing field, or unsupported format). Update your CLI to the latest version and re-run.'
+    },
+    'upload-size-exceeded': {
+        title: 'Screenshot too large',
+        remedy: 'One or more screenshots exceeded the maximum file size. Reduce screenshot resolution or split into smaller batches.'
+    },
+    'cli-aborted': {
+        title: 'CI run aborted',
+        remedy: 'Your CLI explicitly told us the run was aborted (Ctrl+C, SIGTERM, or an unhandled error in the CLI process). Check your CI logs for the underlying cause.'
+    },
+    'cli-silent': {
+        title: 'CI never finished',
+        remedy: "We didn't hear from your CI within the configured silence window. Either the CI job timed out, was killed, or lost network. Check your CI logs and re-run."
+    },
+    'worker-error': {
+        title: 'Internal processing error',
+        remedy: 'Our diff engine hit an unexpected error while processing this build. Our team has been alerted automatically. Re-run the build, and contact support if the error persists.'
+    },
+    'worker-stall': {
+        title: 'Internal timeout',
+        remedy: 'Diff processing took longer than expected and was aborted. This is usually transient — re-run the build. If it happens repeatedly, contact support.'
+    },
+    'rerun-cancelled': {
+        title: 'Cancelled by re-run',
+        remedy: 'This build was superseded by a re-run on the same commit. The new build is the active one.'
+    },
+    'manual-cancelled': {
+        title: 'Cancelled',
+        remedy: 'A team member manually cancelled this build from the dashboard.'
+    },
+    'gh-workflow-failed': {
+        title: 'GitHub workflow failed',
+        remedy: 'The GitHub Actions workflow that produced this build reported a failure. Check the workflow run on GitHub for details.'
+    },
+    'gh-workflow-cancelled': {
+        title: 'GitHub workflow cancelled',
+        remedy: 'The GitHub Actions workflow was cancelled before it could finish uploading screenshots.'
+    },
+    'glab-pipeline-failed': {
+        title: 'GitLab pipeline failed',
+        remedy: 'The GitLab CI pipeline that produced this build reported a failure. Check the pipeline on GitLab for details.'
+    },
+    'glab-pipeline-cancelled': {
+        title: 'GitLab pipeline cancelled',
+        remedy: 'The GitLab CI pipeline was cancelled before it could finish uploading screenshots.'
+    }
+};
+/** Resolve a `fail_reason` code to its customer copy. Falls back to a generic message. */
+export const failureCopyFor = (reason) => {
+    if (!reason || !(reason in FAILURE_COPY)) {
+        return {
+            title: 'Build failed',
+            remedy: 'This build did not complete successfully. Re-run the build, and contact support if the issue persists.'
+        };
+    }
+    return FAILURE_COPY[reason];
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { FailureCopy } from './failureReasons.js';
+export { FAILURE_COPY, failureCopyFor } from './failureReasons.js';
+export type { ApproveDiffRequest, Baseline, Build, BuildStatus, BuildSummary, ClassificationCategory, ClassificationResult, Decision, Diff, DiffRegion, DiffResult, DiffStatus, FailReason, PipelineStatus, Project, RegionCause, RegionFeedback, Screenshot } from './types.js';
+export { FAILURE_PIPELINE_STATUSES, isFailureStatus, isTerminalStatus, TERMINAL_PIPELINE_STATUSES } from './types.js';
+export type { AdhocBuildRequest, AdhocBuildResponse, AdhocSessionRequest, AdhocSessionResponse, AuthMeResponse, CreateBuildRequest, CreateBuildResponse, DynamicRegion, ListBuildsResponse, PipelineFinalizeResponse, PresignUploadRequest, PresignUploadResponse, ScreenshotManifestEntry, ScreenshotMetadata, StorybookBuildRequest, StorybookBuildResponse, SubmitShardRequest, SubmitShardResponse } from './schemas/index.js';
+export { AdhocBuildRequestSchema, AdhocBuildResponseSchema, AdhocSessionRequestSchema, AdhocSessionResponseSchema, AuthMeResponseSchema, CreateBuildRequestSchema, CreateBuildResponseSchema, DynamicRegionSchema, ListBuildsResponseSchema, PipelineFinalizeResponseSchema, PresignUploadRequestSchema, PresignUploadResponseSchema, ScreenshotManifestEntrySchema, ScreenshotMetadataSchema, StorybookBuildRequestSchema, StorybookBuildResponseSchema, SubmitShardRequestSchema, SubmitShardResponseSchema } from './schemas/index.js';
+export type { RegionType } from './attributes.js';
+export { ALL_ATTRIBUTE_SELECTORS, COMPAT_ATTRIBUTES, PIXEYE_ATTRIBUTES } from './attributes.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { FAILURE_COPY, failureCopyFor } from './failureReasons.js';
+export { FAILURE_PIPELINE_STATUSES, isFailureStatus, isTerminalStatus, TERMINAL_PIPELINE_STATUSES } from './types.js';
+export { AdhocBuildRequestSchema, AdhocBuildResponseSchema, AdhocSessionRequestSchema, AdhocSessionResponseSchema, AuthMeResponseSchema, CreateBuildRequestSchema, CreateBuildResponseSchema, DynamicRegionSchema, ListBuildsResponseSchema, PipelineFinalizeResponseSchema, PresignUploadRequestSchema, PresignUploadResponseSchema, ScreenshotManifestEntrySchema, ScreenshotMetadataSchema, StorybookBuildRequestSchema, StorybookBuildResponseSchema, SubmitShardRequestSchema, SubmitShardResponseSchema } from './schemas/index.js';
+export { ALL_ATTRIBUTE_SELECTORS, COMPAT_ATTRIBUTES, PIXEYE_ATTRIBUTES } from './attributes.js';

package/dist/schemas/adhoc.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export declare const AdhocSessionRequestSchema: z.ZodObject<{
+    displayName: z.ZodString;
+}, z.core.$strip>;
+export type AdhocSessionRequest = z.infer<typeof AdhocSessionRequestSchema>;
+export declare const AdhocBuildRequestSchema: z.ZodObject<{
+    shardCount: z.ZodOptional<z.ZodNumber>;
+    runner: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AdhocBuildRequest = z.infer<typeof AdhocBuildRequestSchema>;
+export declare const AdhocSessionResponseSchema: z.ZodObject<{
+    session: z.ZodObject<{
+        id: z.ZodString;
+        displayName: z.ZodString;
+        createdBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        createdAt: z.ZodUnion<readonly [z.ZodString, z.ZodDate]>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AdhocSessionResponse = z.infer<typeof AdhocSessionResponseSchema>;
+export declare const AdhocBuildResponseSchema: z.ZodObject<{
+    build: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$loose>;
+    session: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+        isNew: z.ZodBoolean;
+    }, z.core.$strip>;
+    workspaceToken: z.ZodString;
+}, z.core.$strip>;
+export type AdhocBuildResponse = z.infer<typeof AdhocBuildResponseSchema>;

package/dist/schemas/adhoc.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+// --- Request schemas ---
+export const AdhocSessionRequestSchema = z.object({
+    displayName: z.string().min(1).max(200)
+});
+export const AdhocBuildRequestSchema = z.object({
+    shardCount: z.number().int().min(1).optional(),
+    runner: z.string().min(1).optional()
+});
+// --- Response schemas ---
+export const AdhocSessionResponseSchema = z.object({
+    session: z.object({
+        id: z.string(),
+        displayName: z.string(),
+        createdBy: z.string().nullable().optional(),
+        createdAt: z.union([z.string(), z.date()])
+    })
+});
+export const AdhocBuildResponseSchema = z.object({
+    build: z
+        .object({
+        id: z.string()
+    })
+        .passthrough(),
+    session: z.object({
+        id: z.string().optional(),
+        displayName: z.string().optional(),
+        isNew: z.boolean()
+    }),
+    workspaceToken: z.string()
+});

package/dist/schemas/auth.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const AuthMeResponseSchema: z.ZodObject<{
+    authType: z.ZodEnum<{
+        adhoc: "adhoc";
+        project: "project";
+        session: "session";
+    }>;
+    organizationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    projectName: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AuthMeResponse = z.infer<typeof AuthMeResponseSchema>;

package/dist/schemas/auth.js

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export const AuthMeResponseSchema = z.object({
+    authType: z.enum(['adhoc', 'project', 'session']),
+    organizationId: z.string().nullable().optional(),
+    projectName: z.string().optional(),
+    email: z.string().optional()
+});

package/dist/schemas/build.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+export declare const CreateBuildRequestSchema: z.ZodObject<{
+    projectToken: z.ZodString;
+    commitSha: z.ZodString;
+    branch: z.ZodString;
+    prNumber: z.ZodOptional<z.ZodNumber>;
+    shardCount: z.ZodOptional<z.ZodNumber>;
+    partial: z.ZodOptional<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    runner: z.ZodOptional<z.ZodString>;
+    baseBranch: z.ZodOptional<z.ZodString>;
+    authorName: z.ZodOptional<z.ZodString>;
+    commitMessage: z.ZodOptional<z.ZodString>;
+    authorAvatar: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CreateBuildRequest = z.infer<typeof CreateBuildRequestSchema>;
+/** Minimal build fields the CLI needs from create-build response. */
+export declare const CreateBuildResponseSchema: z.ZodObject<{
+    build: z.ZodObject<{
+        id: z.ZodString;
+        projectId: z.ZodString;
+        pipelineId: z.ZodNullable<z.ZodString>;
+        status: z.ZodString;
+        number: z.ZodNumber;
+        commitSha: z.ZodString;
+        branch: z.ZodString;
+        runner: z.ZodString;
+        shardCount: z.ZodNumber;
+        shardsCompleted: z.ZodNumber;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export type CreateBuildResponse = z.infer<typeof CreateBuildResponseSchema>;
+/** Build list response (used by pipeline-finalize to find pipelineId). */
+export declare const ListBuildsResponseSchema: z.ZodObject<{
+    builds: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        pipelineId: z.ZodNullable<z.ZodString>;
+        status: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export type ListBuildsResponse = z.infer<typeof ListBuildsResponseSchema>;

package/dist/schemas/build.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+// --- Request schemas ---
+export const CreateBuildRequestSchema = z.object({
+    projectToken: z.string().min(1),
+    commitSha: z.string().min(1),
+    branch: z.string().min(1),
+    prNumber: z.number().int().positive().optional(),
+    shardCount: z.number().int().min(1).optional(),
+    partial: z.boolean().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    runner: z.string().min(1).max(64).optional(),
+    baseBranch: z.string().min(1).optional(),
+    authorName: z.string().optional(),
+    commitMessage: z.string().optional(),
+    authorAvatar: z.string().optional()
+});
+// --- Response schemas ---
+/** Minimal build fields the CLI needs from create-build response. */
+export const CreateBuildResponseSchema = z.object({
+    build: z
+        .object({
+        id: z.string(),
+        projectId: z.string(),
+        pipelineId: z.string().nullable(),
+        status: z.string(),
+        number: z.number(),
+        commitSha: z.string(),
+        branch: z.string(),
+        runner: z.string(),
+        shardCount: z.number(),
+        shardsCompleted: z.number()
+    })
+        .passthrough()
+});
+/** Build list response (used by pipeline-finalize to find pipelineId). */
+export const ListBuildsResponseSchema = z.object({
+    builds: z.array(z
+        .object({
+        id: z.string(),
+        pipelineId: z.string().nullable(),
+        status: z.string()
+    })
+        .passthrough())
+});

package/dist/schemas/index.d.ts

@@ -0,0 +1,16 @@
+export type { AuthMeResponse } from './auth.js';
+export { AuthMeResponseSchema } from './auth.js';
+export type { CreateBuildRequest, CreateBuildResponse, ListBuildsResponse } from './build.js';
+export { CreateBuildRequestSchema, CreateBuildResponseSchema, ListBuildsResponseSchema } from './build.js';
+export type { ScreenshotManifestEntry, SubmitShardRequest, SubmitShardResponse } from './shard.js';
+export { ScreenshotManifestEntrySchema, SubmitShardRequestSchema, SubmitShardResponseSchema } from './shard.js';
+export type { PresignUploadRequest, PresignUploadResponse } from './upload.js';
+export { PresignUploadRequestSchema, PresignUploadResponseSchema } from './upload.js';
+export type { PipelineFinalizeResponse } from './pipeline.js';
+export { PipelineFinalizeResponseSchema } from './pipeline.js';
+export type { AdhocBuildRequest, AdhocBuildResponse, AdhocSessionRequest, AdhocSessionResponse } from './adhoc.js';
+export { AdhocBuildRequestSchema, AdhocBuildResponseSchema, AdhocSessionRequestSchema, AdhocSessionResponseSchema } from './adhoc.js';
+export type { StorybookBuildRequest, StorybookBuildResponse } from './storybook.js';
+export { StorybookBuildRequestSchema, StorybookBuildResponseSchema } from './storybook.js';
+export type { DynamicRegion, ScreenshotMetadata } from './metadata.js';
+export { DynamicRegionSchema, ScreenshotMetadataSchema } from './metadata.js';

package/dist/schemas/index.js

@@ -0,0 +1,8 @@
+export { AuthMeResponseSchema } from './auth.js';
+export { CreateBuildRequestSchema, CreateBuildResponseSchema, ListBuildsResponseSchema } from './build.js';
+export { ScreenshotManifestEntrySchema, SubmitShardRequestSchema, SubmitShardResponseSchema } from './shard.js';
+export { PresignUploadRequestSchema, PresignUploadResponseSchema } from './upload.js';
+export { PipelineFinalizeResponseSchema } from './pipeline.js';
+export { AdhocBuildRequestSchema, AdhocBuildResponseSchema, AdhocSessionRequestSchema, AdhocSessionResponseSchema } from './adhoc.js';
+export { StorybookBuildRequestSchema, StorybookBuildResponseSchema } from './storybook.js';
+export { DynamicRegionSchema, ScreenshotMetadataSchema } from './metadata.js';

package/dist/schemas/metadata.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/**
+ * Region detected by DOM attribute scanning before screenshot capture.
+ * Used by integration packages (@pixeyedev/playwright, @pixeyedev/cypress)
+ * to communicate dynamic/masked/ignored regions to the diff engine.
+ */
+export declare const DynamicRegionSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        mask: "mask";
+        ignore: "ignore";
+        dynamic: "dynamic";
+    }>;
+    selector: z.ZodString;
+    bounds: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DynamicRegion = z.infer<typeof DynamicRegionSchema>;
+/**
+ * Screenshot metadata sidecar (.meta.json) written by integration packages.
+ * Accompanies each captured screenshot with context for the diff engine.
+ */
+export declare const ScreenshotMetadataSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    browser: z.ZodOptional<z.ZodString>;
+    colorScheme: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+    }>>;
+    testFile: z.ZodOptional<z.ZodString>;
+    testName: z.ZodOptional<z.ZodString>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+    regions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            mask: "mask";
+            ignore: "ignore";
+            dynamic: "dynamic";
+        }>;
+        selector: z.ZodString;
+        bounds: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    componentBounds: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ScreenshotMetadata = z.infer<typeof ScreenshotMetadataSchema>;

package/dist/schemas/metadata.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+/**
+ * Region detected by DOM attribute scanning before screenshot capture.
+ * Used by integration packages (@pixeyedev/playwright, @pixeyedev/cypress)
+ * to communicate dynamic/masked/ignored regions to the diff engine.
+ */
+export const DynamicRegionSchema = z.object({
+    type: z.enum(['mask', 'ignore', 'dynamic']),
+    selector: z.string(),
+    bounds: z.object({
+        x: z.number().min(0),
+        y: z.number().min(0),
+        width: z.number().positive(),
+        height: z.number().positive()
+    })
+});
+/**
+ * Screenshot metadata sidecar (.meta.json) written by integration packages.
+ * Accompanies each captured screenshot with context for the diff engine.
+ */
+export const ScreenshotMetadataSchema = z.object({
+    version: z.literal(1),
+    viewport: z
+        .object({
+        width: z.number().int().positive(),
+        height: z.number().int().positive()
+    })
+        .optional(),
+    browser: z.string().optional(),
+    colorScheme: z.enum(['light', 'dark']).optional(),
+    testFile: z.string().optional(),
+    testName: z.string().optional(),
+    threshold: z.number().min(0).max(1).optional(),
+    regions: z.array(DynamicRegionSchema).optional(),
+    componentBounds: z
+        .object({
+        x: z.number(),
+        y: z.number(),
+        width: z.number(),
+        height: z.number()
+    })
+        .nullable()
+        .optional()
+});

package/dist/schemas/pipeline.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+/** Response from POST /api/v1/pipelines/:id/finalize. */
+export declare const PipelineFinalizeResponseSchema: z.ZodObject<{
+    status: z.ZodString;
+    finalized: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type PipelineFinalizeResponse = z.infer<typeof PipelineFinalizeResponseSchema>;

package/dist/schemas/pipeline.js

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+// --- Response schemas ---
+/** Response from POST /api/v1/pipelines/:id/finalize. */
+export const PipelineFinalizeResponseSchema = z.object({
+    status: z.string(),
+    finalized: z.literal(true)
+});

package/dist/schemas/shard.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export declare const ScreenshotManifestEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    fileHash: z.ZodString;
+    format: z.ZodOptional<z.ZodEnum<{
+        png: "png";
+        webp: "webp";
+    }>>;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ScreenshotManifestEntry = z.infer<typeof ScreenshotManifestEntrySchema>;
+export declare const SubmitShardRequestSchema: z.ZodObject<{
+    shardIndex: z.ZodDefault<z.ZodNumber>;
+    screenshots: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        fileHash: z.ZodString;
+        format: z.ZodOptional<z.ZodEnum<{
+            png: "png";
+            webp: "webp";
+        }>>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    projectToken: z.ZodString;
+}, z.core.$strip>;
+export type SubmitShardRequest = z.infer<typeof SubmitShardRequestSchema>;
+export declare const SubmitShardResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    shardIndex: z.ZodNumber;
+    shardsCompleted: z.ZodOptional<z.ZodNumber>;
+    shardCount: z.ZodOptional<z.ZodNumber>;
+    processing: z.ZodBoolean;
+}, z.core.$strip>;
+export type SubmitShardResponse = z.infer<typeof SubmitShardResponseSchema>;

package/dist/schemas/shard.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+// --- Screenshot manifest entry (used in shard submission) ---
+export const ScreenshotManifestEntrySchema = z.object({
+    name: z.string().min(1),
+    fileHash: z.string().min(1),
+    format: z.enum(['png', 'webp']).optional(),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    metadata: z.record(z.string(), z.unknown()).optional()
+});
+// --- Request schemas ---
+export const SubmitShardRequestSchema = z.object({
+    shardIndex: z.number().int().min(0).default(0),
+    screenshots: z.array(ScreenshotManifestEntrySchema).min(1),
+    projectToken: z.string().min(1)
+});
+// --- Response schemas ---
+export const SubmitShardResponseSchema = z.object({
+    ok: z.literal(true),
+    shardIndex: z.number(),
+    shardsCompleted: z.number().optional(),
+    shardCount: z.number().optional(),
+    processing: z.boolean()
+});

package/dist/schemas/storybook.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/** POST /api/v1/storybook/builds — register a Storybook build after file upload. */
+export declare const StorybookBuildRequestSchema: z.ZodObject<{
+    projectToken: z.ZodString;
+    commitSha: z.ZodString;
+    branch: z.ZodString;
+    fileCount: z.ZodNumber;
+    totalBytes: z.ZodNumber;
+    storagePrefix: z.ZodString;
+}, z.core.$strip>;
+export type StorybookBuildRequest = z.infer<typeof StorybookBuildRequestSchema>;
+export declare const StorybookBuildResponseSchema: z.ZodObject<{
+    build: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$loose>;
+    storybookUrl: z.ZodString;
+}, z.core.$strip>;
+export type StorybookBuildResponse = z.infer<typeof StorybookBuildResponseSchema>;

package/dist/schemas/storybook.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+// --- Request schemas ---
+/** POST /api/v1/storybook/builds — register a Storybook build after file upload. */
+export const StorybookBuildRequestSchema = z.object({
+    projectToken: z.string().min(1),
+    commitSha: z.string().min(1),
+    branch: z.string().min(1),
+    fileCount: z.number().int().positive(),
+    totalBytes: z.number().int().min(0),
+    storagePrefix: z.string().min(1)
+});
+// --- Response schemas ---
+export const StorybookBuildResponseSchema = z.object({
+    build: z
+        .object({
+        id: z.string()
+    })
+        .passthrough(),
+    storybookUrl: z.string()
+});

package/dist/schemas/upload.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export declare const PresignUploadRequestSchema: z.ZodObject<{
+    token: z.ZodString;
+    buildId: z.ZodString;
+    hashes: z.ZodArray<z.ZodString>;
+    formats: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        png: "png";
+        webp: "webp";
+    }>>>;
+}, z.core.$strip>;
+export type PresignUploadRequest = z.infer<typeof PresignUploadRequestSchema>;
+export declare const PresignUploadResponseSchema: z.ZodObject<{
+    urls: z.ZodRecord<z.ZodString, z.ZodString>;
+    existing: z.ZodArray<z.ZodString>;
+    uploadCount: z.ZodNumber;
+    skippedCount: z.ZodNumber;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type PresignUploadResponse = z.infer<typeof PresignUploadResponseSchema>;

package/dist/schemas/upload.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+// --- Request schemas ---
+export const PresignUploadRequestSchema = z.object({
+    token: z.string().min(1),
+    buildId: z.string().min(1),
+    hashes: z.array(z.string().min(1)).min(1),
+    formats: z.record(z.string(), z.enum(['png', 'webp'])).optional()
+});
+// --- Response schemas ---
+export const PresignUploadResponseSchema = z.object({
+    urls: z.record(z.string(), z.string()),
+    existing: z.array(z.string()),
+    uploadCount: z.number(),
+    skippedCount: z.number(),
+    warnings: z.array(z.string())
+});

package/dist/types.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Pipeline / build status — prefix-namespaced by source of truth.
+ *
+ * The prefix tells you WHO last knew the state of this resource:
+ * - `cli_*`    — the CLI is in charge (uploads in progress, or CLI explicitly aborted/went silent)
+ * - `pixeye_*` — Pixeye infrastructure is in charge (diff worker, reviewer actions, our janitor)
+ * - `gh_*`     — GitHub told us (future, via workflow_run webhook)
+ * - `glab_*`   — GitLab told us (future)
+ *
+ * The prefix answers the customer's "why is this stuck / who failed" question:
+ * if status is `cli_silent` the answer is "your CI never finished talking to us";
+ * if status is `pixeye_failed` the answer is "our worker hit an error".
+ *
+ * Builds and pipelines share this enum because pipeline status is a roll-up
+ * over its builds — same vocabulary, same prefixes, same friendly labels.
+ */
+export type PipelineStatus = 'cli_pending' | 'cli_running' | 'pixeye_processing' | 'pixeye_success' | 'pixeye_changes' | 'pixeye_approved' | 'pixeye_rejected' | 'pixeye_failed' | 'pixeye_cancelled' | 'cli_aborted' | 'cli_silent' | 'gh_failed' | 'gh_cancelled' | 'glab_failed' | 'glab_cancelled';
+/** Builds use the same status vocabulary as pipelines. */
+export type BuildStatus = PipelineStatus;
+/** Statuses where no further automatic transition is expected. */
+export declare const TERMINAL_PIPELINE_STATUSES: readonly PipelineStatus[];
+/** Statuses that indicate the resource failed for a reason the customer must see. */
+export declare const FAILURE_PIPELINE_STATUSES: readonly PipelineStatus[];
+export declare const isTerminalStatus: (status: PipelineStatus) => boolean;
+export declare const isFailureStatus: (status: PipelineStatus) => boolean;
+/**
+ * Stable codes for the `fail_reason` column. The friendly title + remedy + CTA
+ * for each code is rendered from a translation map in the UI / API utils.
+ * Adding a new code requires adding it to that map AND to this enum.
+ */
+export type FailReason = 'storage-quota-exceeded' | 'screenshot-quota-exceeded' | 'invalid-upload' | 'upload-size-exceeded' | 'cli-aborted' | 'cli-silent' | 'worker-error' | 'worker-stall' | 'rerun-cancelled' | 'manual-cancelled' | 'gh-workflow-failed' | 'gh-workflow-cancelled' | 'glab-pipeline-failed' | 'glab-pipeline-cancelled';
+export type DiffStatus = 'added' | 'removed' | 'changed' | 'unchanged' | 'ignored' | 'failed';
+export interface Project {
+    id: string;
+    name: string;
+    githubRepo: string;
+    defaultBranch: string;
+    autoApproveBranches: string | null;
+    flakinessThreshold: number | null;
+    ignorePatterns: string | null;
+    notifyOnBuild: boolean;
+    organizationId: string | null;
+    githubInstallationId: number | null;
+    userId: string | null;
+    token: string;
+    createdAt: Date;
+}
+export interface Build {
+    id: string;
+    projectId: string;
+    number: number;
+    projectNumber?: number;
+    commitSha: string;
+    branch: string;
+    prNumber: number | null;
+    status: BuildStatus;
+    baselineBuildId: string | null;
+    shardCount: number;
+    shardsCompleted: number;
+    githubCheckId: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface Screenshot {
+    id: string;
+    buildId: string;
+    name: string;
+    fileHash: string;
+    storagePath: string;
+    width: number;
+    height: number;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+}
+export interface Diff {
+    id: string;
+    buildId: string;
+    screenshotId: string;
+    baselineScreenshotId: string | null;
+    status: DiffStatus;
+    diffPercentage: number | null;
+    diffPixelCount: number | null;
+    diffImagePath: string | null;
+    reviewed: boolean;
+    approved: boolean | null;
+    reviewedBy: string | null;
+    reviewedAt: Date | null;
+    createdAt: Date;
+}
+export interface Baseline {
+    id: string;
+    projectId: string;
+    branch: string;
+    screenshotName: string;
+    screenshotId: string;
+    buildId: string;
+    updatedAt: Date;
+}
+export interface Test {
+    id: string;
+    projectId: string;
+    name: string;
+    totalBuilds: number;
+    totalChanges: number;
+    flakinessScore: number;
+    firstSeenBuildId: string | null;
+    lastSeenBuildId: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface CreateBuildRequest {
+    projectToken: string;
+    commitSha: string;
+    branch: string;
+    prNumber?: number;
+    shardCount?: number;
+}
+export interface UploadShardRequest {
+    buildId: string;
+    shardIndex: number;
+    shardTotal: number;
+    screenshots: ScreenshotManifestEntry[];
+}
+export interface ScreenshotManifestEntry {
+    name: string;
+    fileHash: string;
+    format?: 'png' | 'webp';
+    width: number;
+    height: number;
+    metadata?: Record<string, unknown>;
+}
+export interface ApproveDiffRequest {
+    diffIds?: string[];
+    all?: boolean;
+    reviewedBy?: string;
+}
+export interface BuildSummary {
+    build: Build;
+    counts: {
+        total: number;
+        changed: number;
+        added: number;
+        removed: number;
+        unchanged: number;
+        ignored: number;
+    };
+}
+export type RegionCause = 'noise' | 'dynamic-text' | 'dynamic-number'
+/** OCR confirmed the text matches a timestamp pattern (PR F). Noise-class. */
+ | 'dynamic-timestamp'
+/** OCR confirmed the text is identical between baseline and current (PR F). Noise-class. */
+ | 'font-rendering' | 'shift' | 'content-change' | 'text-change' | 'color-change' | 'font-size' | 'element-resize' | 'layout-change'
+/** Region matched a known-dynamic fingerprint via Phase 5 hot zones — auto-suppressed. */
+ | 'known-dynamic' | 'antialiasing' | 'unknown';
+/**
+ * Reviewer-facing category bucket. Each classifier rule declares exactly
+ * one category; a single region may carry multiple classifications in
+ * different categories (e.g. a redesigned button that is simultaneously
+ * color + geometry + position + content).
+ *
+ * Auto-approval policy: a region is `autoApprovable` only when EVERY
+ * classification falls into a "noise-class" category (`noise`,
+ * `known-dynamic`, `dynamic-text`, `dom-flagged`). A single classification
+ * in a "real-change" category blocks auto-approval.
+ *
+ * Noise-class categories: `noise`, `known-dynamic`, `dynamic-text`, `dom-flagged`
+ * Real-change categories: all others
+ */
+export type ClassificationCategory = 
+/** Background/fill/text color shifted, shape preserved. */
+'color'
+/** Many regions shifted color uniformly (dark-mode toggle, brand recolor). */
+ | 'theme'
+/** Element scaled/resized without changing what it depicts. */
+ | 'geometry'
+/** Same content moved to a new location. */
+ | 'position'
+/** Font size/weight/family changed but glyphs identical. */
+ | 'typography'
+/** Actual text characters changed (label edited). */
+ | 'text'
+/** Timestamp/counter/live value changed (recurring noise). Noise-class. */
+ | 'dynamic-text'
+/** Shape replaced — different image, icon, illustration, component. */
+ | 'content'
+/** Multiple elements reflowed, large band-width changes. */
+ | 'layout'
+/** Pixels new — nothing there in baseline. */
+ | 'element-added'
+/** Pixels gone — nothing there in current. */
+ | 'element-removed'
+/** Sub-pixel jitter, AA, font hinting, JPEG noise. Noise-class. */
+ | 'noise'
+/** Reviewer-approved 3+ times, auto-suppressed. Noise-class. */
+ | 'known-dynamic'
+/** DOM `data-dynamic` attribute or testid in project allowlist. Noise-class. */
+ | 'dom-flagged';
+/**
+ * A single classification produced by one classifier rule. Multiple
+ * classifications can be attached to a single region — the multi-cause
+ * model enumerates all firing rules instead of picking a cascade winner.
+ *
+ * Top-level `cause`/`confidence`/`summary` on `DiffRegion` remain for
+ * backwards compatibility and are derived from the highest-confidence
+ * classification (`classifications[0]` after sorting).
+ */
+export interface ClassificationResult {
+    /** Stable identifier for the firing rule, e.g. 'P1-phase-corr', 'P2-A-ssim'. */
+    ruleId: string;
+    /** Reviewer-facing category bucket. Governs auto-approval policy. */
+    category: ClassificationCategory;
+    /** Legacy cause string (kept for the derived top-level field). */
+    cause: RegionCause;
+    /** 0..1 — how confident this rule is in its verdict. */
+    confidence: number;
+    /** Short human-readable summary shown in the reviewer UI. */
+    summary: string;
+    /** Whether THIS rule considers the region auto-approvable in isolation. */
+    autoApprovable: boolean;
+    /** Feature values that triggered this rule (shown in the reviewer "why?" tooltip). */
+    evidence?: Record<string, unknown>;
+}
+/**
+ * Per-region ground-truth label supplied by a reviewer. Used as training
+ * data for classifier threshold tuning and rule combination design.
+ */
+export interface RegionFeedback {
+    /** 'approve' = the classifier got it right, 'reject' = got it wrong. */
+    verdict: 'approve' | 'reject';
+    /** Free-text explanation from the reviewer. */
+    comment?: string;
+    /**
+     * When the verdict is 'reject', the reviewer can supply what the region
+     * REALLY is (from the `RegionCause` enum). This is the labeled
+     * correction signal for future classifier training.
+     */
+    actualCause?: RegionCause;
+    /** Auth user id of the reviewer who labeled this region. */
+    userId?: string;
+    /** ISO timestamp when the feedback was saved. */
+    createdAt?: string;
+}
+export interface DiffRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Derived from classifications[0]?.cause — kept for backwards compatibility. */
+    cause?: RegionCause;
+    /** Derived from classifications[0]?.confidence — kept for backwards compatibility. */
+    confidence?: number;
+    /** Derived from the unanimous-consent auto-approval rule over `classifications`. */
+    autoApprovable?: boolean;
+    approved?: boolean;
+    /** Derived from classifications[0]?.summary — kept for backwards compatibility. */
+    summary?: string;
+    /**
+     * All rules that fired against this region, sorted by confidence descending.
+     * Empty array means the cascade reached its default (unknown) case.
+     * Optional for backwards compatibility — old diffs without this field
+     * continue to render via the derived top-level fields.
+     */
+    classifications?: ClassificationResult[];
+    /** Unique set of categories across `classifications`. */
+    categories?: ClassificationCategory[];
+    /**
+     * Stable rule identifier for the top-level (highest-confidence) rule.
+     * Derived from `classifications[0]?.ruleId` for display/filter convenience.
+     * A post-processor override (e.g. `P4-theme-coverage`) may set this
+     * independently of the classifications array.
+     */
+    ruleId?: string;
+    /**
+     * Full feature vector captured during classification. Present when the
+     * Python worker's multi-cause driver ran — exposes every feature
+     * (ssim, lab_delta, palette_emd, freq_*_delta, aa_residual_ratio,
+     * mask_cc_*, etc.) so reviewers can see WHY rules did or didn't fire.
+     * Used for threshold calibration and ground-truth labeling.
+     */
+    features?: Record<string, unknown>;
+    /**
+     * Reviewer-supplied ground-truth feedback on this specific region.
+     * Populated by the per-region labeling UI in DetailSpotlight. Every
+     * field is optional so a reviewer can supply any combination of
+     * (verdict, comment, actualCause). The object exists on the region
+     * only after the first label is saved.
+     */
+    feedback?: RegionFeedback;
+    shiftDx?: number;
+    shiftDy?: number;
+    baselineText?: string;
+    currentText?: string;
+    dynamicPattern?: string;
+    explanation?: string;
+    /** Logical group id when post-processor merges related regions (e.g. table row). */
+    groupId?: string;
+    /**
+     * Cross-screenshot linkage id assigned by `linkRegionsAcrossBuild` after
+     * all screenshots in a build finish post-processing. Regions that share
+     * this id are visually identical (matching perceptual hash + similar
+     * size + same cause family) across the whole build — e.g. the same
+     * button changed on 5 different pages. The reviewer UI uses it to show
+     * an occurrence count, navigate between occurrences, and label all of
+     * them in one action. Optional for backwards compatibility; builds
+     * processed before this feature shipped simply have no linkage.
+     */
+    linkedGroupId?: string;
+    /**
+     * 64-bit DCT perceptual hash of the baseline patch for this region,
+     * computed by the classifier pipeline. Used by hot-zones for cross-build
+     * dedup and by `linkRegionsAcrossBuild` for within-build cross-screenshot
+     * linkage. Persisted on the region so downstream passes don't have to
+     * re-download baseline buffers. Hex-encoded.
+     */
+    fingerprint?: string;
+}
+export interface DiffResult {
+    status: DiffStatus;
+    diffPercentage: number;
+    diffPixelCount: number;
+    diffImageBuffer: Buffer | null;
+    diffRegions: DiffRegion[];
+}
+export interface Decision {
+    type: 'static' | 'pixeye-ai' | 'pixeye-ai-cache' | 'pixeye-ai-dedup' | 'human';
+    decision: 'approved' | 'rejected' | 'needs-review';
+    cause?: RegionCause;
+    confidence?: number;
+    reason?: string;
+    model?: string;
+    tokens?: number;
+    cost?: number;
+    userId?: string;
+    fingerprint?: string;
+    timestamp: string;
+}

package/dist/types.js

@@ -0,0 +1,29 @@
+// --- Enums ---
+/** Statuses where no further automatic transition is expected. */
+export const TERMINAL_PIPELINE_STATUSES = [
+    'pixeye_success',
+    'pixeye_changes',
+    'pixeye_approved',
+    'pixeye_rejected',
+    'pixeye_failed',
+    'pixeye_cancelled',
+    'cli_aborted',
+    'cli_silent',
+    'gh_failed',
+    'gh_cancelled',
+    'glab_failed',
+    'glab_cancelled'
+];
+/** Statuses that indicate the resource failed for a reason the customer must see. */
+export const FAILURE_PIPELINE_STATUSES = [
+    'pixeye_failed',
+    'pixeye_cancelled',
+    'cli_aborted',
+    'cli_silent',
+    'gh_failed',
+    'gh_cancelled',
+    'glab_failed',
+    'glab_cancelled'
+];
+export const isTerminalStatus = (status) => TERMINAL_PIPELINE_STATUSES.includes(status);
+export const isFailureStatus = (status) => FAILURE_PIPELINE_STATUSES.includes(status);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@pixeyedev/shared",
+  "version": "0.4.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "echo 'ok'",
+    "ai-check": "exit 0",
+    "publish:dry": "npm run build && npm publish --access public --dry-run"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}