@pixeyedev/core 0.4.6 → 0.4.7

package/dist/ci.d.ts

@@ -5,9 +5,6 @@ export interface CIEnvironment {
     baseBranch?: string;
     prNumber?: number;
     repository?: string;
-    /** What triggered the run — recorded on the build so "which CI run made
-     *  this build, started by whom" is answerable from the admin without
-     *  opening the provider. All optional: providers differ in what they expose. */
     trigger?: CITrigger;
 }
 export interface CITrigger {
@@ -18,9 +15,4 @@ export interface CITrigger {
     eventName?: string;
     runUrl?: string;
 }
-/**
- * Try to detect the base branch using git merge-base.
- * Checks common default branch names (main, master, develop).
- */
-export declare const detectBaseBranchFromGit: () => string | undefined;
 export declare const detectCIEnvironment: () => CIEnvironment | null;

package/dist/ci.js

@@ -1,7 +1,4 @@
-import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-/** GITHUB_EVENT_PATH is the run's event payload; absent or unreadable means
- *  the env vars alone describe the run. */
 const readGitHubEvent = () => {
     const path = process.env.GITHUB_EVENT_PATH;
     if (!path) {
@@ -19,8 +16,6 @@ const detectGitHubActions = () => {
     if (!process.env.GITHUB_ACTIONS) {
         return null;
     }
-    // On a pull_request run GITHUB_SHA is GitHub's throwaway merge commit, one
-    // per push to the base: the build must carry the PR's own head commit.
     const event = readGitHubEvent();
     const eventPr = event?.pull_request ?? event?.workflow_run?.pull_requests?.[0];
     const commit = event?.pull_request?.head?.sha ?? event?.workflow_run?.head_sha ?? process.env.GITHUB_SHA;
@@ -29,11 +24,8 @@ const detectGitHubActions = () => {
     if (!commit || !branch || !runId) {
         return null;
     }
-    // PR number: explicit env, else the event payload.
     const prRaw = process.env.PIXEYE_PR;
     const prNumber = prRaw ? parseInt(prRaw, 10) : eventPr?.number;
-    // PR target branch: GITHUB_BASE_REF is set on pull_request events; the
-    // payload carries it for workflow_run too.
     const baseBranch = process.env.GITHUB_BASE_REF || eventPr?.base?.ref || undefined;
     const repository = process.env.GITHUB_REPOSITORY;
     const serverUrl = process.env.GITHUB_SERVER_URL;
@@ -81,29 +73,4 @@ const detectGitLabCI = () => {
         }
     };
 };
-/**
- * Try to detect the base branch using git merge-base.
- * Checks common default branch names (main, master, develop).
- */
-export const detectBaseBranchFromGit = () => {
-    const candidates = ['main', 'master', 'develop'];
-    for (const candidate of candidates) {
-        try {
-            execFileSync('git', ['rev-parse', '--verify', `origin/${candidate}`], { stdio: 'ignore' });
-            execFileSync('git', ['merge-base', 'HEAD', `origin/${candidate}`], { stdio: 'ignore' });
-            return candidate;
-        }
-        catch {
-            // Branch doesn't exist or no common ancestor
-        }
-    }
-    return undefined;
-};
-export const detectCIEnvironment = () => {
-    const ci = detectGitHubActions() ?? detectGitLabCI() ?? null;
-    // If CI detected but no baseBranch, try git merge-base
-    if (ci && !ci.baseBranch) {
-        ci.baseBranch = detectBaseBranchFromGit();
-    }
-    return ci;
-};
+export const detectCIEnvironment = () => detectGitHubActions() ?? detectGitLabCI() ?? null;

package/dist/client.d.ts

@@ -3,33 +3,27 @@ export declare class PixeyeError extends Error {
     status: number;
     path: string;
     body: string;
-    /**
-     * Where the failure came from. `'api'` = the Pixeye control-plane (a 4xx
-     * here can be a customer misconfig — token/plan/permissions). `'r2'` = a
-     * data-plane PUT to R2 via a presigned URL (a 403/404 here is a Pixeye-side
-     * fault — expired URL, bucket/credential, clock skew — NEVER the customer's).
-     * Used by `isUploadMisconfig` so an R2 outage can't fail a customer's CI.
-     */
     origin: 'api' | 'r2';
-    constructor(status: number, path: string, body: string, 
-    /**
-     * Where the failure came from. `'api'` = the Pixeye control-plane (a 4xx
-     * here can be a customer misconfig — token/plan/permissions). `'r2'` = a
-     * data-plane PUT to R2 via a presigned URL (a 403/404 here is a Pixeye-side
-     * fault — expired URL, bucket/credential, clock skew — NEVER the customer's).
-     * Used by `isUploadMisconfig` so an R2 outage can't fail a customer's CI.
-     */
-    origin?: 'api' | 'r2');
+    retryAfterMs?: number | undefined;
+    constructor(status: number, path: string, body: string, origin?: 'api' | 'r2', retryAfterMs?: number | undefined);
 }
 export interface PixeyeClientOptions {
     serverUrl: string;
     token: string;
+    timeoutMs?: number;
+    attempts?: number;
 }
 export declare class PixeyeClient {
     private serverUrl;
     private token;
+    private timeoutMs;
+    private attempts;
+    private reporting?;
+    get observes(): boolean;
     constructor(options: PixeyeClientOptions);
+    private send;
     private request;
+    private retryOptions;
     createBuild(opts: {
         projectToken: string;
         commitSha: string;
@@ -59,12 +53,6 @@ export declare class PixeyeClient {
         branch: string;
     }): Promise<ListBuildsResponse>;
     finalizePipeline(pipelineId: string): Promise<PipelineFinalizeResponse>;
-    /** `format` is the SNIFFED format of the bytes we would upload, and it
-     *  scopes the probe to that exact key: the same hash stored under another
-     *  extension by an older CLI is not this file. */
     checkFileExists(hash: string, format?: ScreenshotFormat): Promise<boolean>;
-    /** `format` decides the stored key's extension server-side, so it must be
-     *  the same sniffed value the shard manifest carries. Older servers ignore
-     *  the field and keep storing under `.png`. */
     uploadLegacy(buffer: Buffer, hash: string, filename: string, format?: ScreenshotFormat): Promise<void>;
 }

package/dist/client.js

@@ -1,43 +1,52 @@
 import { createRequire } from 'node:module';
-import { CONTENT_TYPE_BY_FORMAT, CreateBuildResponseSchema, ListBuildsResponseSchema, PipelineFinalizeResponseSchema, PresignUploadResponseSchema, SubmitShardResponseSchema } from '@pixeyedev/shared';
+import { CONTENT_TYPE_BY_FORMAT, CreateBuildResponseSchema, ListBuildsResponseSchema, PipelineFinalizeResponseSchema, PRESIGN_BATCH_MAX, PresignUploadResponseSchema, SubmitShardResponseSchema } from '@pixeyedev/shared';
+import { readClientEnv } from './config.js';
+import { DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_UPLOAD_ATTEMPTS, RETRY_AFTER_MAX_MS } from './constants.js';
 import { isRetryableHttpError, maskPresignedUrl, withRetry } from './retry.js';
 export class PixeyeError extends Error {
     status;
     path;
     body;
     origin;
-    constructor(status, path, body, 
-    /**
-     * Where the failure came from. `'api'` = the Pixeye control-plane (a 4xx
-     * here can be a customer misconfig — token/plan/permissions). `'r2'` = a
-     * data-plane PUT to R2 via a presigned URL (a 403/404 here is a Pixeye-side
-     * fault — expired URL, bucket/credential, clock skew — NEVER the customer's).
-     * Used by `isUploadMisconfig` so an R2 outage can't fail a customer's CI.
-     */
-    origin = 'api') {
+    retryAfterMs;
+    constructor(status, path, body, origin = 'api', retryAfterMs) {
         super(`Pixeye API ${path} failed (${status}): ${body}`);
         this.status = status;
         this.path = path;
         this.body = body;
         this.origin = origin;
+        this.retryAfterMs = retryAfterMs;
         this.name = 'PixeyeError';
     }
 }
+const parseRetryAfter = (response) => {
+    const seconds = Number(response.headers.get('retry-after'));
+    return Number.isFinite(seconds) && seconds > 0
+        ? Math.min(seconds * 1000, RETRY_AFTER_MAX_MS)
+        : undefined;
+};
 const { version } = createRequire(import.meta.url)('../package.json');
-/** What the API records on a build so a failed run can be matched to the client
- *  that sent it: this package's version and the Node it ran on. */
 const USER_AGENT = `@pixeyedev/core/${version} node/${process.versions.node}`;
 export class PixeyeClient {
     serverUrl;
     token;
+    timeoutMs;
+    attempts;
+    reporting;
+    get observes() {
+        return this.reporting === 'observe';
+    }
     constructor(options) {
+        const env = readClientEnv();
         this.serverUrl = options.serverUrl.replace(/\/$/, '');
         this.token = options.token;
+        this.timeoutMs = options.timeoutMs ?? env.timeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+        this.attempts = options.attempts ?? env.attempts ?? DEFAULT_UPLOAD_ATTEMPTS;
     }
-    async request(path, options = {}) {
-        const url = `${this.serverUrl}${path}`;
-        const response = await fetch(url, {
+    async send(path, options = {}) {
+        const response = await fetch(`${this.serverUrl}${path}`, {
             ...options,
+            signal: AbortSignal.timeout(this.timeoutMs),
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${this.token}`,
@@ -46,11 +55,21 @@ export class PixeyeClient {
             }
         });
         if (!response.ok) {
-            const body = await response.text();
-            throw new PixeyeError(response.status, path, body);
+            throw new PixeyeError(response.status, path.split('?')[0], await response.text(), 'api', parseRetryAfter(response));
         }
         return response.json();
     }
+    request(path, options = {}) {
+        return withRetry(() => this.send(path, options), isRetryableHttpError, this.retryOptions(path.split('?')[0]));
+    }
+    retryOptions(what) {
+        return {
+            maxAttempts: this.attempts,
+            onRetry: (attempt, err) => {
+                console.warn(`[pixeye] ${what} retry ${attempt}/${this.attempts}: ${err.message}`);
+            }
+        };
+    }
     async createBuild(opts) {
         const body = { ...opts };
         if (opts.runner) {
@@ -60,19 +79,39 @@ export class PixeyeClient {
             method: 'POST',
             body: JSON.stringify(body)
         });
-        return CreateBuildResponseSchema.parse(raw);
+        const parsed = CreateBuildResponseSchema.parse(raw);
+        this.reporting = parsed.reporting;
+        return parsed;
     }
     async presignUpload(opts) {
-        const raw = await this.request('/api/v1/upload/presign', {
-            method: 'POST',
-            body: JSON.stringify({
-                token: this.token,
-                buildId: opts.buildId,
-                hashes: opts.hashes,
-                ...(opts.formats && Object.keys(opts.formats).length > 0 ? { formats: opts.formats } : {})
-            })
-        });
-        return PresignUploadResponseSchema.parse(raw);
+        const merged = {
+            urls: {},
+            existing: [],
+            uploadCount: 0,
+            skippedCount: 0,
+            warnings: []
+        };
+        for (let start = 0; start < opts.hashes.length; start += PRESIGN_BATCH_MAX) {
+            const hashes = opts.hashes.slice(start, start + PRESIGN_BATCH_MAX);
+            const inChunk = new Set(hashes);
+            const formats = Object.fromEntries(Object.entries(opts.formats ?? {}).filter(([hash]) => inChunk.has(hash)));
+            const raw = await this.request('/api/v1/upload/presign', {
+                method: 'POST',
+                body: JSON.stringify({
+                    token: this.token,
+                    buildId: opts.buildId,
+                    hashes,
+                    ...(Object.keys(formats).length > 0 ? { formats } : {})
+                })
+            });
+            const part = PresignUploadResponseSchema.parse(raw);
+            Object.assign(merged.urls, part.urls);
+            merged.existing.push(...part.existing);
+            merged.uploadCount += part.uploadCount;
+            merged.skippedCount += part.skippedCount;
+            merged.warnings.push(...part.warnings);
+        }
+        return merged;
     }
     async uploadFile(presignedUrl, buffer, contentType) {
         const maskedUrl = maskPresignedUrl(presignedUrl);
@@ -80,23 +119,16 @@ export class PixeyeClient {
             const res = await fetch(presignedUrl, {
                 method: 'PUT',
                 body: new Uint8Array(buffer),
+                signal: AbortSignal.timeout(this.timeoutMs),
                 headers: { 'Content-Type': contentType }
             });
             if (!res.ok) {
-                // 'r2' origin — a PUT failure here is Pixeye-side (expired presigned
-                // URL, bucket/creds, clock skew), never the customer's misconfig.
                 throw new PixeyeError(res.status, maskedUrl, await res.text(), 'r2');
             }
-        }, isRetryableHttpError, {
-            maxAttempts: 3,
-            baseDelayMs: 1000,
-            onRetry: (attempt, err) => {
-                console.warn(`[pixeye] Upload retry ${attempt}/3: ${err.message}`);
-            }
-        });
+        }, isRetryableHttpError, this.retryOptions('Upload'));
     }
     async submitShard(opts) {
-        const raw = await this.request(`/api/v1/builds/${opts.buildId}/shards`, {
+        const raw = await this.send(`/api/v1/builds/${opts.buildId}/shards`, {
             method: 'POST',
             body: JSON.stringify({
                 shardIndex: opts.shardIndex,
@@ -120,17 +152,11 @@ export class PixeyeClient {
         });
         return PipelineFinalizeResponseSchema.parse(raw);
     }
-    /** `format` is the SNIFFED format of the bytes we would upload, and it
-     *  scopes the probe to that exact key: the same hash stored under another
-     *  extension by an older CLI is not this file. */
     async checkFileExists(hash, format = 'png') {
         const result = await this.request(`/api/v1/upload/${encodeURIComponent(hash)}?token=${encodeURIComponent(this.token)}` +
             `&format=${encodeURIComponent(format)}`);
         return result.exists;
     }
-    /** `format` decides the stored key's extension server-side, so it must be
-     *  the same sniffed value the shard manifest carries. Older servers ignore
-     *  the field and keep storing under `.png`. */
     async uploadLegacy(buffer, hash, filename, format = 'png') {
         const blob = new Blob([new Uint8Array(buffer)], { type: CONTENT_TYPE_BY_FORMAT[format] });
         const formData = new FormData();
@@ -139,7 +165,11 @@ export class PixeyeClient {
         formData.append('format', format);
         formData.append('token', this.token);
         const url = `${this.serverUrl}/api/v1/upload`;
-        const response = await fetch(url, { method: 'POST', body: formData });
+        const response = await fetch(url, {
+            method: 'POST',
+            body: formData,
+            signal: AbortSignal.timeout(this.timeoutMs)
+        });
         if (!response.ok) {
             const body = await response.text();
             throw new PixeyeError(response.status, '/api/v1/upload', body);

package/dist/config.d.ts

@@ -30,8 +30,13 @@ export declare const readGlobalConfig: () => Promise<PixeyeConfig>;
 export declare const writeGlobalConfig: (config: PixeyeConfig) => Promise<void>;
 export declare const readProjectConfig: (cwd: string) => Promise<ProjectConfig | null>;
 export declare const writeProjectConfig: (cwd: string, config: ProjectConfig) => Promise<void>;
+export declare const integerSetting: (name: string, raw: string | number | undefined, min: number) => number | undefined;
+export declare const readClientEnv: () => {
+    timeoutMs?: number;
+    attempts?: number;
+};
+export declare const resolveUploadConcurrency: (option: number | undefined) => number;
 export declare const readEnvConfig: () => EnvConfig;
-/** @internal Exported for testing */
 export declare const parseYamlLike: (content: string) => ProjectConfig;
 export declare const resolveConfig: (overrides?: Partial<ResolvedConfig> & {
     cwd?: string;

package/dist/config.js

@@ -2,7 +2,8 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { detectCIEnvironment } from './ci.js';
-import { DEFAULT_SERVER_URL } from './constants.js';
+import { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
+import { CustomerError } from './uploadError.js';
 const GLOBAL_CONFIG_DIR = join(homedir(), '.pixeye');
 const GLOBAL_CONFIG_PATH = join(GLOBAL_CONFIG_DIR, 'config.json');
 const PROJECT_CONFIG_NAME = '.pixeye.yml';
@@ -36,24 +37,33 @@ export const writeProjectConfig = async (cwd, config) => {
     ];
     await writeFile(join(cwd, PROJECT_CONFIG_NAME), lines.join('\n') + '\n');
 };
+export const integerSetting = (name, raw, min) => {
+    if (raw === undefined || raw === '') {
+        return undefined;
+    }
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < min) {
+        throw new CustomerError(`${name} must be an integer of at least ${min}, got "${raw}".`);
+    }
+    return n;
+};
+export const readClientEnv = () => ({
+    timeoutMs: integerSetting('PIXEYE_HTTP_TIMEOUT_MS', process.env.PIXEYE_HTTP_TIMEOUT_MS, 1),
+    attempts: integerSetting('PIXEYE_UPLOAD_ATTEMPTS', process.env.PIXEYE_UPLOAD_ATTEMPTS, 1)
+});
+export const resolveUploadConcurrency = (option) => integerSetting('uploadConcurrency', option, 1) ??
+    integerSetting('PIXEYE_UPLOAD_CONCURRENCY', process.env.PIXEYE_UPLOAD_CONCURRENCY, 1) ??
+    DEFAULT_UPLOAD_CONCURRENCY;
 export const readEnvConfig = () => {
-    const intOrUndef = (val) => {
-        if (val === undefined) {
-            return undefined;
-        }
-        const n = parseInt(val, 10);
-        return isNaN(n) ? undefined : n;
-    };
     return {
         server: process.env.PIXEYE_SERVER || undefined,
         token: process.env.PIXEYE_TOKEN || undefined,
         commit: process.env.PIXEYE_COMMIT || undefined,
         branch: process.env.PIXEYE_BRANCH || undefined,
-        pr: intOrUndef(process.env.PIXEYE_PR),
+        pr: integerSetting('PIXEYE_PR', process.env.PIXEYE_PR, 1),
         runner: process.env.PIXEYE_RUNNER || undefined
     };
 };
-/** @internal Exported for testing */
 export const parseYamlLike = (content) => {
     const result = {};
     for (const line of content.split('\n')) {
@@ -62,12 +72,10 @@ export const parseYamlLike = (content) => {
             let value = match[2].trim();
             const isQuoted = (value.startsWith('"') && value.endsWith('"')) ||
                 (value.startsWith("'") && value.endsWith("'"));
-            // Strip surrounding quotes
             if (isQuoted) {
                 value = value.slice(1, -1);
             }
             else {
-                // Remove inline comments only for unquoted values
                 value = value.replace(/\s+#.*$/, '');
             }
             result[match[1]] = value;

package/dist/constants.d.ts

@@ -1,4 +1,5 @@
-/** Default Pixeye server URL. */
 export declare const DEFAULT_SERVER_URL = "https://pixeye.dev";
-/** Default number of concurrent screenshot uploads. Overridable via PIXEYE_UPLOAD_CONCURRENCY env. */
 export declare const DEFAULT_UPLOAD_CONCURRENCY = 32;
+export declare const DEFAULT_HTTP_TIMEOUT_MS = 60000;
+export declare const DEFAULT_UPLOAD_ATTEMPTS = 3;
+export declare const RETRY_AFTER_MAX_MS = 60000;

package/dist/constants.js

@@ -1,4 +1,5 @@
-/** Default Pixeye server URL. */
 export const DEFAULT_SERVER_URL = 'https://pixeye.dev';
-/** Default number of concurrent screenshot uploads. Overridable via PIXEYE_UPLOAD_CONCURRENCY env. */
 export const DEFAULT_UPLOAD_CONCURRENCY = 32;
+export const DEFAULT_HTTP_TIMEOUT_MS = 60_000;
+export const DEFAULT_UPLOAD_ATTEMPTS = 3;
+export const RETRY_AFTER_MAX_MS = 60_000;

package/dist/discover.d.ts

@@ -3,10 +3,10 @@ export interface DiscoveredFile {
     filePath: string;
     name: string;
     fileHash: string;
-    /** Sniffed from the bytes, not the extension — see `probeImage`. */
     format: ScreenshotFormat;
     width: number;
     height: number;
     metadata?: Record<string, unknown>;
+    library?: string;
 }
 export declare const discoverScreenshots: (directory: string) => Promise<DiscoveredFile[]>;

package/dist/discover.js

@@ -1,28 +1,94 @@
 import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
 import { glob } from 'glob';
 import { probeImage, swapImageExtension } from './imageProbe.js';
+const METADATA_SIDECAR = '.meta.json';
+const SIDECAR_SUFFIX_RE = /\.[^.]+\.json$/;
+const FAILED_NAME_SUFFIX = ' (failed)';
+const sidecarsByOwner = (siblings) => {
+    const byOwner = new Map();
+    for (const name of siblings) {
+        if (SIDECAR_SUFFIX_RE.test(name)) {
+            const owner = name.replace(SIDECAR_SUFFIX_RE, '');
+            byOwner.set(owner, [...(byOwner.get(owner) ?? []), name]);
+        }
+    }
+    return byOwner;
+};
+const readSidecar = async (path) => {
+    try {
+        return JSON.parse(await readFile(path, 'utf-8'));
+    }
+    catch (err) {
+        console.warn(`pixeye: ignoring unreadable sidecar ${path}: ${String(err)}`);
+        return undefined;
+    }
+};
+const testOf = (sidecar) => {
+    const test = sidecar.test;
+    if (!test || typeof test !== 'object') {
+        return undefined;
+    }
+    const { id, title, titlePath, location } = test;
+    const file = location && typeof location === 'object' ? location.file : undefined;
+    const fields = Object.fromEntries(Object.entries({ testId: id, testName: title, testFile: file }).filter(([, v]) => typeof v === 'string'));
+    const key = Array.isArray(titlePath) ? titlePath.join(' › ') : fields.testName;
+    return key ? { key, fields } : undefined;
+};
+const libraryOf = (sidecar) => {
+    const library = sidecar.automationLibrary;
+    const name = library && typeof library === 'object' ? library.name : undefined;
+    return typeof name === 'string' ? name : undefined;
+};
 export const discoverScreenshots = async (directory) => {
     const files = await glob('**/*.{png,webp}', { cwd: directory, posix: true });
     files.sort();
-    const results = [];
+    const sidecarsByDir = new Map();
+    const found = [];
+    const failedTests = new Set();
     for (const relativePath of files) {
         const filePath = `${directory}/${relativePath}`;
         const fileBuffer = await readFile(filePath);
         const fileHash = createHash('sha256').update(fileBuffer).digest('hex');
         const { format, width, height } = probeImage(fileBuffer, relativePath);
         const name = swapImageExtension(relativePath, '');
-        // Check for companion metadata file
-        const metadataPath = swapImageExtension(filePath, '.pixeye.json');
+        const dir = dirname(filePath);
+        const sidecars = sidecarsByDir.get(dir) ?? sidecarsByOwner(await readdir(dir));
+        sidecarsByDir.set(dir, sidecars);
+        const fileName = basename(filePath);
+        const own = [
+            ...(sidecars.get(swapImageExtension(fileName, '')) ?? []),
+            ...(sidecars.get(fileName) ?? [])
+        ];
         let metadata;
-        try {
-            const metadataContent = await readFile(metadataPath, 'utf-8');
-            metadata = JSON.parse(metadataContent);
+        let test;
+        let library;
+        for (const sidecarName of own) {
+            const sidecar = await readSidecar(join(dir, sidecarName));
+            if (!sidecar) {
+                continue;
+            }
+            if (sidecarName === swapImageExtension(fileName, METADATA_SIDECAR)) {
+                metadata = sidecar;
+            }
+            else {
+                test ??= testOf(sidecar);
+            }
+            library ??= libraryOf(sidecar);
         }
-        catch {
-            // No metadata file or invalid JSON — skip
+        if (test && metadata === undefined && name.endsWith(FAILED_NAME_SUFFIX)) {
+            failedTests.add(test.key);
         }
-        results.push({ filePath, name, fileHash, format, width, height, metadata });
+        found.push({ filePath, name, fileHash, format, width, height, metadata, test, library });
     }
+    const results = found.map(({ test, metadata, ...file }) => ({
+        ...file,
+        metadata: metadata ??
+            (test && {
+                ...test.fields,
+                ...(failedTests.has(test.key) ? { testStatus: 'failed' } : {})
+            })
+    }));
     return results;
 };

package/dist/imageProbe.d.ts

@@ -1,22 +1,9 @@
 import type { ScreenshotFormat } from '@pixeyedev/shared';
-/**
- * Format + dimensions read from the FILE'S BYTES, never its name: Playwright
- * writes `type: 'jpeg'` screenshots under `.png` paths, and trusting the
- * extension failed the whole upload on "Invalid PNG file".
- */
 export interface ProbedImage {
     format: ScreenshotFormat;
     width: number;
     height: number;
 }
-/** Swap a screenshot's extension for `replacement` ('' strips it). One owner,
- *  so the glob, the name strip and the sidecar lookup can never disagree. */
 export declare const swapImageExtension: (filePath: string, replacement: string) => string;
-/** Content sniff only — returns null when the bytes are none of the three. */
 export declare const sniffImageFormat: (buffer: Buffer) => ScreenshotFormat | null;
-/**
- * Identify an image from its bytes. Throws naming `filePath` and what we
- * accept — the CLI surfaces the message to a user staring at a CI log, so
- * it must say which file is wrong.
- */
 export declare const probeImage: (buffer: Buffer, filePath: string) => ProbedImage;

package/dist/imageProbe.js

@@ -1,9 +1,5 @@
-/** Every extension `discoverScreenshots` globs. Deliberately NOT jpg/jpeg:
- *  the ask is JPEG BYTES under a `.png` name, not every jpg in the output
- *  directory (owner 2026-09-02). Content decides `format`, the name does not. */
+import { CustomerError } from './uploadError.js';
 const IMAGE_EXTENSION_RE = /\.(png|webp)$/;
-/** Swap a screenshot's extension for `replacement` ('' strips it). One owner,
- *  so the glob, the name strip and the sidecar lookup can never disagree. */
 export const swapImageExtension = (filePath, replacement) => filePath.replace(IMAGE_EXTENSION_RE, replacement);
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const WEBP_RIFF = Buffer.from('RIFF');
@@ -13,7 +9,6 @@ const isJpeg = (buffer) => buffer.length >= 3 && buffer[0] === 0xff && buffer[1]
 const isWebp = (buffer) => buffer.length >= 12 &&
     buffer.subarray(0, 4).equals(WEBP_RIFF) &&
     buffer.subarray(8, 12).equals(WEBP_WEBP);
-/** Content sniff only — returns null when the bytes are none of the three. */
 export const sniffImageFormat = (buffer) => {
     if (isPng(buffer)) {
         return 'png';
@@ -32,13 +27,7 @@ const readPngDimensions = (buffer) => {
     }
     return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
 };
-/** Markers that carry no frame header, so their payload is skipped whole. */
 const JPEG_SOF_EXCLUDED = new Set([0xc4, 0xc8, 0xcc]);
-/**
- * Walk the marker chain to the first Start-Of-Frame (SOF0 baseline, SOF2
- * progressive, the rest of 0xC0–0xCF) and read its height/width. There is no
- * fixed offset: the segments before it vary by encoder.
- */
 const readJpegDimensions = (buffer) => {
     let offset = 2;
     while (offset + 9 < buffer.length) {
@@ -47,8 +36,6 @@ const readJpegDimensions = (buffer) => {
             continue;
         }
         const marker = buffer[offset + 1];
-        // 0xFF is a fill byte: the spec allows any number before a marker, and
-        // reading it AS the marker walks the chain off into the entropy data.
         if (marker === 0xff) {
             offset++;
             continue;
@@ -73,19 +60,16 @@ const readWebpDimensions = (buffer) => {
         throw new Error('WebP header is truncated');
     }
     const chunk = buffer.subarray(12, 16).toString('ascii');
-    // VP8 lossy: dimensions at offset 26-29, masked to 14 bits.
     if (chunk === 'VP8 ') {
         return {
             width: buffer.readUInt16LE(26) & 0x3fff,
             height: buffer.readUInt16LE(28) & 0x3fff
         };
     }
-    // VP8L lossless: 14-bit width and height packed from offset 21.
     if (chunk === 'VP8L') {
         const bits = buffer.readUInt32LE(21);
         return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
     }
-    // VP8X extended: 24-bit canvas dimensions at offset 24-29.
     if (chunk === 'VP8X') {
         return {
             width: (buffer.readUIntLE(24, 3) & 0xffffff) + 1,
@@ -94,15 +78,10 @@ const readWebpDimensions = (buffer) => {
     }
     throw new Error(`Unsupported WebP chunk type: ${chunk}`);
 };
-/**
- * Identify an image from its bytes. Throws naming `filePath` and what we
- * accept — the CLI surfaces the message to a user staring at a CI log, so
- * it must say which file is wrong.
- */
 export const probeImage = (buffer, filePath) => {
     const format = sniffImageFormat(buffer);
     if (format === null) {
-        throw new Error(`${filePath} is not a PNG, JPEG or WebP image (the file is corrupt, ` +
+        throw new CustomerError(`${filePath} is not a PNG, JPEG or WebP image (the file is corrupt, ` +
             `truncated, or a different format saved under an image extension)`);
     }
     try {
@@ -117,7 +96,7 @@ export const probeImage = (buffer, filePath) => {
         return { format, ...dimensions };
     }
     catch (err) {
-        throw new Error(`${filePath} looks like ${format.toUpperCase()} but its dimensions could not be ` +
+        throw new CustomerError(`${filePath} looks like ${format.toUpperCase()} but its dimensions could not be ` +
             `read (${err.message}) — the file is probably truncated`);
     }
 };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export type { PixeyeClientOptions } from './client.js';
 export { PixeyeClient, PixeyeError } from './client.js';
 export type { EnvConfig, PixeyeConfig, ProjectConfig, ResolvedConfig } from './config.js';
-export { parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, writeGlobalConfig, writeProjectConfig } from './config.js';
+export { integerSetting, parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, resolveUploadConcurrency, writeGlobalConfig, writeProjectConfig } from './config.js';
 export type { CIEnvironment } from './ci.js';
-export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
+export { detectCIEnvironment } from './ci.js';
 export type { DiscoveredFile } from './discover.js';
 export { discoverScreenshots } from './discover.js';
 export type { ProbedImage } from './imageProbe.js';
@@ -11,5 +11,5 @@ export { probeImage, sniffImageFormat, swapImageExtension } from './imageProbe.j
 export { runParallel } from './parallel.js';
 export type { RetryOptions } from './retry.js';
 export { isRetryableHttpError, maskPresignedUrl, withRetry } from './retry.js';
-export { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
-export { isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';
+export { DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_SERVER_URL, DEFAULT_UPLOAD_ATTEMPTS, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
+export { CustomerError, isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';

package/dist/index.js

@@ -1,11 +1,9 @@
 export { PixeyeClient, PixeyeError } from './client.js';
-export { parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, writeGlobalConfig, writeProjectConfig } from './config.js';
-export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
+export { integerSetting, parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, resolveUploadConcurrency, writeGlobalConfig, writeProjectConfig } from './config.js';
+export { detectCIEnvironment } from './ci.js';
 export { discoverScreenshots } from './discover.js';
 export { probeImage, sniffImageFormat, swapImageExtension } from './imageProbe.js';
-// Parallel execution
 export { runParallel } from './parallel.js';
 export { isRetryableHttpError, maskPresignedUrl, withRetry } from './retry.js';
-// Constants
-export { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
-export { isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';
+export { DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_SERVER_URL, DEFAULT_UPLOAD_ATTEMPTS, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
+export { CustomerError, isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';

package/dist/parallel.d.ts

@@ -1,4 +1 @@
-/**
- * Run async tasks in parallel with a concurrency limit.
- */
 export declare const runParallel: <T>(items: T[], concurrency: number, fn: (item: T) => Promise<void>) => Promise<void>;

package/dist/parallel.js

@@ -1,6 +1,3 @@
-/**
- * Run async tasks in parallel with a concurrency limit.
- */
 export const runParallel = async (items, concurrency, fn) => {
     let index = 0;
     const worker = async () => {

package/dist/retry.d.ts

@@ -3,12 +3,6 @@ export interface RetryOptions {
     baseDelayMs?: number;
     onRetry?: (attempt: number, error: Error) => void;
 }
-/**
- * Retry an async function with exponential backoff + jitter.
- * Only retries on errors where shouldRetry returns true.
- */
 export declare const withRetry: <T>(fn: () => Promise<T>, shouldRetry: (error: unknown) => boolean, opts?: RetryOptions) => Promise<T>;
-/** Returns true for HTTP 429/5xx responses or transient network errors. */
 export declare const isRetryableHttpError: (error: unknown) => boolean;
-/** Mask presigned URL signature for safe error logging. */
 export declare const maskPresignedUrl: (url: string) => string;

package/dist/retry.js

@@ -1,7 +1,3 @@
-/**
- * Retry an async function with exponential backoff + jitter.
- * Only retries on errors where shouldRetry returns true.
- */
 export const withRetry = async (fn, shouldRetry, opts = {}) => {
     const maxAttempts = opts.maxAttempts ?? 3;
     const baseDelayMs = opts.baseDelayMs ?? 1000;
@@ -13,28 +9,30 @@ export const withRetry = async (fn, shouldRetry, opts = {}) => {
             if (attempt === maxAttempts || !shouldRetry(error)) {
                 throw error;
             }
-            // Exponential backoff with equal jitter (half deterministic + half random)
             const exponential = baseDelayMs * Math.pow(2, attempt - 1);
-            const delay = exponential * (0.5 + 0.5 * Math.random());
+            const delay = retryAfterMsOf(error) ?? exponential * (0.5 + 0.5 * Math.random());
             opts.onRetry?.(attempt, error instanceof Error ? error : new Error(String(error)));
             await new Promise(r => setTimeout(r, delay));
         }
     }
     throw new Error('Unreachable');
 };
+const retryAfterMsOf = (error) => {
+    const ms = error?.retryAfterMs;
+    return typeof ms === 'number' ? ms : undefined;
+};
 const TRANSIENT_NETWORK_RE = /fetch failed|ECONNRESET|ETIMEDOUT|ECONNREFUSED|ENOTFOUND|EPIPE|socket hang up/i;
-/** Returns true for HTTP 429/5xx responses or transient network errors. */
 export const isRetryableHttpError = (error) => {
-    // Check status code first (authoritative when present)
+    if (error instanceof Error && error.name === 'TimeoutError') {
+        return true;
+    }
     const status = error?.status;
     if (status !== undefined) {
         return status === 429 || (status >= 500 && status < 600);
     }
-    // Fall back to message-based detection for genuine network errors (no HTTP response)
     if (error instanceof Error && TRANSIENT_NETWORK_RE.test(error.message)) {
         return true;
     }
     return false;
 };
-/** Mask presigned URL signature for safe error logging. */
 export const maskPresignedUrl = (url) => url.split('?')[0] + '?[signature-masked]';

package/dist/uploadError.d.ts

@@ -1,35 +1,9 @@
-/**
- * Classify an upload failure and render a loud banner — shared by the Playwright
- * reporter and the CLI so a lapsed plan / bad token surfaces identically (P0-2).
- *
- * The rule: distinguish the CUSTOMER's misconfiguration (they must act) from a
- * transient / our-side fault (their CI should not break over our hiccup).
- */
-/**
- * True when the failure is the customer's configuration/billing, not ours.
- * A `PixeyeError` from the R2 data-plane (`origin: 'r2'`) is EXCLUDED — a
- * 403/404 on a presigned PUT (expired URL, bucket/creds, clock skew) is a
- * Pixeye-side fault and must never fail the customer's CI.
- */
+export declare class CustomerError extends Error {
+    constructor(message: string);
+}
 export declare const isUploadMisconfig: (err: unknown) => boolean;
-/**
- * One-line `HTTP <status> — <detail>` summary. Prefers the error's `body`
- * (the meaningful server code, e.g. `SUBSCRIPTION_CANCELLED`) over the full
- * `PixeyeError.message`, which already embeds the status (avoids `HTTP 402 —
- * Pixeye API … failed (402): …`).
- */
 export declare const uploadErrorSummary: (err: unknown) => string;
-/**
- * Resolve the fail-on-error setting identically for the reporter and CLI: fail
- * by default; opt out via EITHER an explicit `false` option OR
- * `PIXEYE_FAIL_ON_ERROR=false`. (The CLI's commander always supplies a boolean
- * option; the reporter's is optional — this keeps both consistent.)
- */
 export declare const resolveFailOnError: (option: boolean | undefined, env: string | undefined) => boolean;
-/**
- * A bright, unmissable banner for a rejected upload. `willFail` toggles the
- * closing line between "failing this step" and "opted out — passing anyway".
- */
 export declare const renderUploadFailureBanner: (err: unknown, opts: {
     willFail: boolean;
 }) => string;

package/dist/uploadError.js

@@ -1,42 +1,23 @@
-/**
- * Classify an upload failure and render a loud banner — shared by the Playwright
- * reporter and the CLI so a lapsed plan / bad token surfaces identically (P0-2).
- *
- * The rule: distinguish the CUSTOMER's misconfiguration (they must act) from a
- * transient / our-side fault (their CI should not break over our hiccup).
- */
-/**
- * HTTP statuses that mean the CUSTOMER must act — a bad/absent token (401),
- * a lapsed subscription or exceeded quota (402), insufficient permissions
- * (403), or a wrong project/endpoint (404). These fail CI by default so a run
- * can't pass green while zero screenshots reached Pixeye. EVERYTHING else
- * (429 rate-limit, 5xx, network, timeouts, no status) is transient / our fault
- * → warn, never break their CI.
- */
-const MISCONFIG_STATUSES = [401, 402, 403, 404];
+export class CustomerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CustomerError';
+    }
+}
 const statusOf = (err) => {
     const status = err?.status;
     return typeof status === 'number' ? status : undefined;
 };
-/**
- * True when the failure is the customer's configuration/billing, not ours.
- * A `PixeyeError` from the R2 data-plane (`origin: 'r2'`) is EXCLUDED — a
- * 403/404 on a presigned PUT (expired URL, bucket/creds, clock skew) is a
- * Pixeye-side fault and must never fail the customer's CI.
- */
 export const isUploadMisconfig = (err) => {
+    if (err instanceof CustomerError) {
+        return true;
+    }
     if (err?.origin === 'r2') {
         return false;
     }
     const status = statusOf(err);
-    return status !== undefined && MISCONFIG_STATUSES.includes(status);
+    return status !== undefined && status >= 400 && status < 500 && status !== 409 && status !== 429;
 };
-/**
- * One-line `HTTP <status> — <detail>` summary. Prefers the error's `body`
- * (the meaningful server code, e.g. `SUBSCRIPTION_CANCELLED`) over the full
- * `PixeyeError.message`, which already embeds the status (avoids `HTTP 402 —
- * Pixeye API … failed (402): …`).
- */
 export const uploadErrorSummary = (err) => {
     const status = statusOf(err);
     const body = err?.body;
@@ -47,34 +28,35 @@ export const uploadErrorSummary = (err) => {
             : String(err);
     return status !== undefined ? `HTTP ${status} — ${detail}` : detail;
 };
-/**
- * Resolve the fail-on-error setting identically for the reporter and CLI: fail
- * by default; opt out via EITHER an explicit `false` option OR
- * `PIXEYE_FAIL_ON_ERROR=false`. (The CLI's commander always supplies a boolean
- * option; the reporter's is optional — this keeps both consistent.)
- */
 export const resolveFailOnError = (option, env) => option !== false && env !== 'false';
-/**
- * A bright, unmissable banner for a rejected upload. `willFail` toggles the
- * closing line between "failing this step" and "opted out — passing anyway".
- */
 export const renderUploadFailureBanner = (err, opts) => {
     const line = '━'.repeat(64);
+    const customer = isUploadMisconfig(err);
+    const cause = customer
+        ? [
+            '  This is a problem in your configuration or account (a setting, the',
+            '  API token, subscription/quota, or project permissions) — not a Pixeye',
+            '  outage. Fix it and re-run this step.'
+        ]
+        : [
+            '  This is a failure on the Pixeye side, not in your configuration: the',
+            '  upload was retried and still did not get through. Re-run this step;',
+            '  if it keeps failing, write to support@pixeye.dev with this output.'
+        ];
     const footer = opts.willFail
         ? [
-            '  Failing this step so it cannot pass silently. Fix the above, or pass',
+            '  Failing this step so lost coverage cannot pass silently. Pass',
             '  failOnError: false (reporter) / --no-fail-on-error (CLI) to opt out.'
         ]
-        : ['  failOnError is OFF — this step passes despite the lost coverage.'];
+        : ['  Not failing this step: the project is in observe mode, or failOnError is off.'];
     return [
         '',
         `\x1b[31m\x1b[1m${line}`,
-        `  ✗ PIXEYE UPLOAD REJECTED — ${uploadErrorSummary(err)}`,
+        `  ✗ PIXEYE UPLOAD ${customer ? 'REJECTED' : 'FAILED'} — ${uploadErrorSummary(err)}`,
         '',
         '  Your screenshots did NOT reach Pixeye. Visual coverage for this run is',
-        '  LOST. This is a configuration or billing problem on your account (API',
-        '  token, subscription/quota, or project permissions) — not a transient',
-        '  Pixeye outage.',
+        '  LOST.',
+        ...cause,
         '',
         ...footer,
         `${line}\x1b[0m`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixeyedev/core",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -25,7 +25,7 @@
     "publish:dry": "npm run build && npm publish --access public --dry-run"
   },
   "dependencies": {
-    "@pixeyedev/shared": "^0.4.0",
+    "@pixeyedev/shared": "^0.4.7",
     "glob": "^11.0.0"
   },
   "devDependencies": {