@tempo-ai/visual-review 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,245 @@
+export { CaptureSession, looksBlank, sha256Hex, startCaptureSession, storyboardRenderId } from './src/capture';
+export { CHROMIUM_LAUNCH_ARGS, FREEZE_MOTION_CSS, FROZEN_EPOCH_MS, buildFreezeInitScript, settlePage } from './src/determinism';
+export { DevserverSession, startDevserverSession } from './src/devserver';
+export { DEVICE_SCALE_FACTOR, FONTS_BUNDLE_VERSION, KIT_VERSION, buildEnvFingerprint } from './src/fingerprint';
+export { TimingReport, percentile, summarize } from './src/timing';
+import { CaptureStatus } from './src/types';
+export { CaptureStatus, EnvFingerprint } from './src/types';
+
+declare function main$3(argv?: string[]): Promise<number>;
+
+type VrtIgnoreRegion = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** One tracked storyboard, as enumerated from the canvas AST. */
+type TrackedStoryboard = {
+    /** Canvas page folder path relative to the tempo dir — the store's
+     *  `canvasPath` and the Design tab's comment `contentPath`, e.g.
+     *  "designs/canvases/buttons". */
+    canvasPath: string;
+    /** The canvas file path relative to the PROJECT root (the canvas-host
+     *  module key), e.g. "tempo/designs/canvases/buttons/index.canvas.tsx" —
+     *  what the direct-render URL's `canvasPath` param takes. */
+    hostCanvasPath: string;
+    storyboardId: string;
+    name?: string;
+    layout: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    threshold?: number;
+    ignore?: VrtIgnoreRegion[];
+};
+type EnumerationResult = {
+    tracked: TrackedStoryboard[];
+    /** Tracked but `vrt={{ skip: true }}` — paused: rides the manifest with
+     *  `skip: true` (so pausing is not misread as deletion) but is neither
+     *  captured nor gated. */
+    paused: TrackedStoryboard[];
+    /** Total storyboards seen (tracked or not) — for the log line. */
+    totalStoryboards: number;
+    totalCanvases: number;
+    /** Structural parse errors — enumeration is AST truth, so these fail the
+     *  run loudly instead of silently shrinking the manifest. */
+    errors: Array<{
+        filePath: string;
+        message: string;
+    }>;
+};
+type RunManifest = {
+    repoKey: string;
+    githubRepo?: string;
+    headSha: string;
+    branch: string;
+    trigger: "pr" | "main" | "manual";
+    prNumber?: number;
+    baseCandidates: string[];
+    /** Opaque lease ownership proof when this run is publishing a baseline
+     *  claimed before rendering began. */
+    baselineClaimToken?: string;
+    envFingerprint: string;
+    expected: Array<TrackedStoryboard["layout"] & {
+        canvasPath: string;
+        storyboardId: string;
+        name?: string;
+        threshold?: number;
+        ignore?: VrtIgnoreRegion[];
+        /** Paused (`vrt={{ skip: true }}`) — in the manifest, not gated. */
+        skip?: boolean;
+    }>;
+    snapshots: Array<{
+        canvasPath: string;
+        storyboardId: string;
+        pngHash?: string;
+        htmlHash?: string;
+        status: CaptureStatus;
+        error?: string;
+    }>;
+};
+
+/**
+ * The producer credential. In production (and any customer repo) this is a
+ * GitHub Actions OIDC token minted with `audience: tempo-visual-review`; the
+ * global shared secret is accepted only by non-prod deployments (previews,
+ * e2e, local capture). See the Convex `visualReviewAuthenticate` gate.
+ */
+type IngestCredential = {
+    kind: "oidc";
+    value: string;
+} | {
+    kind: "secret";
+    value: string;
+};
+/**
+ * A credential source. GitHub OIDC id-tokens expire 5 minutes after minting,
+ * and a capture run spans many minutes between its first authenticated call
+ * (the mid-capture baseline fetch) and its last (finalize) — so the client
+ * resolves the credential PER REQUEST from a provider that can re-mint,
+ * instead of pinning one token at construction.
+ */
+type IngestCredentialProvider = () => Promise<IngestCredential>;
+type BaselineClaimResult = {
+    status: "unsupported";
+    reason?: string;
+} | {
+    status: "ready";
+    commitSha: string;
+} | {
+    status: "capturing";
+    commitSha: string;
+    leaseExpiresAt: number;
+} | {
+    status: "claimed";
+    commitSha: string;
+    leaseExpiresAt: number;
+};
+type BaselineClaimIdentity = {
+    repoKey: string;
+    commitSha: string;
+    envFingerprint: string;
+    ownerToken: string;
+};
+declare class VisualReviewHttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Client for the Convex `/visual-review/*` ingest routes (TEM-1775 §4.3):
+ * hash-negotiated, idempotent, resumable. A retried CI job re-uploads
+ * nothing (negotiate reports every hash present) and re-finalizes safely
+ * (the mutation dedups on repo+sha+env+trigger+branch).
+ */
+declare class VisualReviewIngestClient {
+    /** Convex site origin, e.g. https://dapper-heron-945.convex.site */
+    private readonly baseUrl;
+    private readonly credential;
+    private lastCredentialKind;
+    constructor(baseUrl: string, credential: IngestCredential | IngestCredentialProvider);
+    private authHeader;
+    private request;
+    /** Best-effort read of the typed `reason`/`error` from an error body. */
+    private errorReason;
+    /** → the subset of `hashes` the store lacks. */
+    negotiate(hashes: string[]): Promise<string[]>;
+    uploadBlob(hash: string, bytes: Uint8Array, size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    claimBaseline(input: {
+        repoKey: string;
+        commitSha: string;
+        envFingerprint: string;
+        ownerToken: string;
+    }): Promise<BaselineClaimResult>;
+    renewBaselineClaim(input: BaselineClaimIdentity): Promise<{
+        renewed: true;
+        leaseExpiresAt: number;
+    }>;
+    failBaselineClaim(input: Omit<BaselineClaimIdentity, "envFingerprint"> & {
+        envFingerprint?: string;
+        error: string;
+    }): Promise<{
+        released: boolean;
+    }>;
+    baselineManifest(repoKey: string, commitSha: string, envFingerprint: string): Promise<Pick<RunManifest, "expected" | "snapshots">>;
+    finalize(manifest: RunManifest): Promise<{
+        runId: string;
+        reportKey: string;
+        state: string;
+        deduped: boolean;
+        reportUrl: string;
+        statusUrl: string;
+    }>;
+}
+
+declare function resolveOrClaimBaseline(options: {
+    ingest: VisualReviewIngestClient;
+    repoKey: string;
+    commitSha: string;
+    envFingerprint: string;
+    ownerToken: string;
+    log: (line: string) => void;
+    waitTimeoutMs?: number;
+    pollIntervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<BaselineClaimResult>;
+declare function main$2(argv?: string[]): Promise<number>;
+
+/** The production Convex HTTP origin customers ingest visual-review runs to. */
+declare const DEFAULT_VISUAL_REVIEW_INGEST_URL = "https://greedy-jackal-526.convex.site";
+
+/**
+ * Enumerates the tracked set (TEM-1775 §3.2): every `<Storyboard>` under the
+ * canvases root carrying a literal `vrt` prop, minus `skip: true`. Route and
+ * html storyboards are out of scope in v1 — the parser only attaches `vrt`
+ * to component storyboards, so they can never enter the manifest.
+ *
+ * The generic AST walk lives in `@tempo-modules/canvas-capture-headless`;
+ * this layers the vrt POLICY on top:
+ * - Structural parse errors FAIL enumeration for that file (its storyboards
+ *   can't be trusted); they are returned for the caller to report loudly
+ *   rather than silently shrinking the tracked set.
+ * - A malformed `vrt` declaration (dynamic expression, bad threshold,
+ *   broken ignore region) is DEGRADED to the editor but FATAL here: the
+ *   author expressed tracking intent, and silently proceeding would either
+ *   drop the board from the gate or gate it with different settings than
+ *   written.
+ * - An ignore configuration masking ≥90% of the board is fatal — "tracked"
+ *   must not be a lie.
+ */
+declare function enumerateTrackedStoryboards(options: {
+    /** The tempo dir (holding tempo.config.json), e.g. `<repo>/tempo`. */
+    tempoDir: string;
+    /** The canvases root, e.g. `<repo>/tempo/designs`. */
+    pagesDir: string;
+}): Promise<EnumerationResult>;
+
+/**
+ * Authors declare `vrt.ignore` regions in storyboard-local CSS px; the
+ * compare engine masks the DEVICE-pixel snapshot. The run manifest carries
+ * device px — this is the single conversion point.
+ */
+declare function scaleIgnoreRegionsToDevicePx(regions: VrtIgnoreRegion[] | undefined): VrtIgnoreRegion[] | undefined;
+
+/**
+ * `tempo-visual-review install-browsers` — install the Chromium build that
+ * matches the playwright THIS package depends on.
+ *
+ * A bare `npx playwright install` resolves registry-latest playwright and can
+ * fetch a browser revision the pinned driver cannot launch; resolving the
+ * installer from our own dependency tree removes that drift for every
+ * consumer of the generated workflow. Linux adds `--with-deps` (Chromium's
+ * shared libraries via apt) because CI VMs are ephemeral; other platforms
+ * already carry those libraries.
+ */
+declare function main$1(argv?: string[]): Promise<number>;
+
+declare function main(argv?: string[]): Promise<number>;
+
+export { type BaselineClaimIdentity, type BaselineClaimResult, DEFAULT_VISUAL_REVIEW_INGEST_URL, type EnumerationResult, type RunManifest, type TrackedStoryboard, VisualReviewHttpError, VisualReviewIngestClient, type VrtIgnoreRegion, enumerateTrackedStoryboards, resolveOrClaimBaseline, main$2 as runCaptureCli, main$3 as runClaimCli, main$1 as runInstallBrowsersCli, main as runReportCli, scaleIgnoreRegionsToDevicePx };

package/dist/index.js

@@ -0,0 +1,69 @@
+import { createRequire as __tempoCreateRequire } from 'node:module'; const require = __tempoCreateRequire(import.meta.url);
+import {
+  main
+} from "./chunk-DJGBIRN5.js";
+import {
+  CHROMIUM_LAUNCH_ARGS,
+  DEVICE_SCALE_FACTOR,
+  FONTS_BUNDLE_VERSION,
+  FREEZE_MOTION_CSS,
+  FROZEN_EPOCH_MS,
+  KIT_VERSION,
+  TimingReport,
+  VisualReviewHttpError,
+  VisualReviewIngestClient,
+  buildEnvFingerprint,
+  buildFreezeInitScript,
+  enumerateTrackedStoryboards,
+  looksBlank,
+  main as main2,
+  percentile,
+  resolveOrClaimBaseline,
+  scaleIgnoreRegionsToDevicePx,
+  settlePage,
+  sha256Hex,
+  startCaptureSession,
+  startDevserverSession,
+  storyboardRenderId,
+  summarize
+} from "./chunk-4QAZFBC3.js";
+import {
+  DEFAULT_VISUAL_REVIEW_INGEST_URL
+} from "./chunk-QLAJNWA2.js";
+import {
+  main as main3
+} from "./chunk-EYRAT56C.js";
+import {
+  main as main4
+} from "./chunk-HMPQK5ZG.js";
+import "./chunk-W7PBID4V.js";
+export {
+  CHROMIUM_LAUNCH_ARGS,
+  DEFAULT_VISUAL_REVIEW_INGEST_URL,
+  DEVICE_SCALE_FACTOR,
+  FONTS_BUNDLE_VERSION,
+  FREEZE_MOTION_CSS,
+  FROZEN_EPOCH_MS,
+  KIT_VERSION,
+  TimingReport,
+  VisualReviewHttpError,
+  VisualReviewIngestClient,
+  buildEnvFingerprint,
+  buildFreezeInitScript,
+  enumerateTrackedStoryboards,
+  looksBlank,
+  percentile,
+  resolveOrClaimBaseline,
+  main2 as runCaptureCli,
+  main as runClaimCli,
+  main3 as runInstallBrowsersCli,
+  main4 as runReportCli,
+  scaleIgnoreRegionsToDevicePx,
+  settlePage,
+  sha256Hex,
+  startCaptureSession,
+  startDevserverSession,
+  storyboardRenderId,
+  summarize
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/install-browsers-5RCJN3AK.js

@@ -0,0 +1,8 @@
+import { createRequire as __tempoCreateRequire } from 'node:module'; const require = __tempoCreateRequire(import.meta.url);
+import {
+  main
+} from "./chunk-EYRAT56C.js";
+export {
+  main
+};
+//# sourceMappingURL=install-browsers-5RCJN3AK.js.map

package/dist/install-browsers-5RCJN3AK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/report-RCKB2CVS.js

@@ -0,0 +1,9 @@
+import { createRequire as __tempoCreateRequire } from 'node:module'; const require = __tempoCreateRequire(import.meta.url);
+import {
+  main
+} from "./chunk-HMPQK5ZG.js";
+import "./chunk-W7PBID4V.js";
+export {
+  main
+};
+//# sourceMappingURL=report-RCKB2CVS.js.map

package/dist/report-RCKB2CVS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tempo-ai/visual-review",
+  "version": "0.0.1",
+  "type": "module",
+  "bin": {
+    "tempo-visual-review": "./dist/bin.js"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TempoLabsAI/tempo-monorepo.git",
+    "directory": "tempo-modules/visual-review"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@parcel/watcher": "^2.5.1",
+    "oxc-parser": "^0.110.0",
+    "picomatch": "^4.0.5",
+    "playwright": "1.58.2",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@tempo-modules/canvas-capture-headless": "workspace:*",
+    "@types/node": "^25.0.8",
+    "@types/pngjs": "^6.0.5",
+    "tsup": "^8.5.1",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "capture": "bun src/cli.ts",
+    "prepare": "tsup",
+    "prepublishOnly": "pnpm build && pnpm test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/templates/visual-review.yml

@@ -0,0 +1,169 @@
+# Written by Tempo visual-review onboarding (visual_review_init). The pnpm
+# setup and the two install lines are the package-manager-specific part;
+# init rewrites them for npm / yarn / bun. Keep every
+# `npx --yes @tempo-ai/visual-review@latest …` line as it is: Tempo's own
+# repository runs these exact commands, so each release is exercised there
+# before it reaches you. Nothing from your checkout executes — the checkout
+# is the subject of the capture.
+name: Visual Review
+
+on:
+  pull_request:
+    # labeled/unlabeled: the bypass label takes effect (and is revocable)
+    # without pushing a new commit.
+    types: [opened, synchronize, reopened, edited, labeled, unlabeled]
+  push:
+    # Your default branch: pushes here publish the baseline PRs compare against.
+    branches: [main]
+
+permissions:
+  contents: read
+  statuses: write
+  pull-requests: write
+  # GitHub OIDC is the only credential Tempo accepts. No secret is stored.
+  id-token: write
+
+concurrency:
+  # A new push never queues behind a stale run. Label events get their own
+  # group so an unrelated label added mid-capture cannot cancel it.
+  group: visual-review-${{ github.event.pull_request.number || github.sha }}-${{ (github.event.action == 'labeled' || github.event.action == 'unlabeled') && 'label' || 'code' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # `visual-review:bypass` label — the incident escape hatch. Posts success
+  # and skips capture entirely.
+  bypass:
+    if: >-
+      github.event_name == 'pull_request'
+      && contains(github.event.pull_request.labels.*.name, 'visual-review:bypass')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - run: npx --yes @tempo-ai/visual-review@latest report --bypass --sha ${{ github.event.pull_request.head.sha }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  # `<!-- tempo-no-visual-change -->` in the PR body — a 100%-certainty claim
+  # that the PR changes no UI and no tested storyboard. Posts success and
+  # skips capture.
+  no-visual-change:
+    if: >-
+      github.event_name == 'pull_request'
+      && !contains(github.event.pull_request.labels.*.name, 'visual-review:bypass')
+      && contains(github.event.pull_request.body, '<!-- tempo-no-visual-change -->')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - run: npx --yes @tempo-ai/visual-review@latest report --no-visual-change --pr ${{ github.event.pull_request.number }} --sha ${{ github.event.pull_request.head.sha }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  capture:
+    # Pushes to the default branch, real code events without either skip
+    # declaration, and bypass-label removal (to restore the real gate).
+    if: >-
+      !cancelled()
+      && (
+        github.event_name == 'push'
+        || (
+          contains(fromJSON('["opened","synchronize","reopened","edited"]'), github.event.action)
+          && !contains(github.event.pull_request.labels.*.name, 'visual-review:bypass')
+          && !contains(github.event.pull_request.body, '<!-- tempo-no-visual-change -->')
+        )
+        || (
+          github.event.action == 'unlabeled'
+          && github.event.label.name == 'visual-review:bypass'
+          && !contains(github.event.pull_request.body, '<!-- tempo-no-visual-change -->')
+        )
+      )
+    runs-on: ubuntu-latest
+    # A PR may first wait for another run's baseline and then render both the
+    # merge-base and its own head.
+    timeout-minutes: 90
+    outputs:
+      status_url: ${{ steps.capture.outputs.status_url }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history: the merge-base ancestor chain is the baseline key.
+          fetch-depth: 0
+          # Capture the PR head, not GitHub's synthetic merge commit.
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      # Announces intent before dependency/browser setup so stacked PRs wait
+      # on the baseline lease instead of duplicating a capture. Purely an
+      # optimization, so a registry hiccup must not fail the run.
+      - run: npx --yes @tempo-ai/visual-review@latest claim || echo "::warning::capture claim announcement unavailable; capture claims after setup"
+
+      - if: github.event_name == 'pull_request'
+        run: |
+          gh api "repos/${{ github.repository }}/statuses/${{ github.event.pull_request.head.sha }}" \
+            -f state=pending -f context=visual-review \
+            -f "description=capturing storyboards…"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      # The canvas host under `tempo/` is its own package. Capture never
+      # mutates this checkout (TEMPO_DEVSERVER_PROTECTED_ROOTS below), so the
+      # host's dependencies are installed here, explicitly.
+      - run: cd tempo && pnpm install --no-frozen-lockfile
+
+      # Chromium matching the CLI's own pinned playwright, plus its shared
+      # libraries on Linux.
+      - run: npx --yes @tempo-ai/visual-review@latest install-browsers
+
+      - uses: actions/cache@v4
+        with:
+          path: tempo/node_modules/.vite
+          key: visual-review-vite-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
+
+      # `capture` infers PR-vs-main, head SHA, branch, merge-base and
+      # repository from GitHub's event payload and the standard GITHUB_*
+      # environment, and authenticates with short-lived OIDC tokens it mints
+      # itself.
+      - id: capture
+        run: npx --yes @tempo-ai/visual-review@latest capture --parallel 2
+        env:
+          # Forbid the capture's canvas-host supervisor from running package
+          # manager installs or updates inside this checkout; those would
+          # churn the Vite cache mid-run and rewrite lockfiles.
+          TEMPO_DEVSERVER_PROTECTED_ROOTS: ${{ github.workspace }}
+
+      # A finished capture has already consumed its claim; this only releases
+      # a lease left behind by a setup failure or cancellation.
+      - if: always()
+        run: npx --yes @tempo-ai/visual-review@latest claim --release || echo "::warning::capture claim release unavailable; the lease expires on its own"
+
+      - if: failure() && github.event_name == 'pull_request'
+        run: |
+          gh api "repos/${{ github.repository }}/statuses/${{ github.event.pull_request.head.sha }}" \
+            -f state=failure -f context=visual-review \
+            -f "description=capture failed — see workflow logs"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  # Polls the run until Tempo has compared it, then posts the verdict and the
+  # sticky PR comment. Approvals in the Tempo report flip the check afterwards
+  # without a CI re-run.
+  report:
+    needs: capture
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - run: npx --yes @tempo-ai/visual-review@latest report --status-url "${{ needs.capture.outputs.status_url }}" --pr ${{ github.event.pull_request.number }} --sha ${{ github.event.pull_request.head.sha }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      # A crashed report must not strand the check at pending. Only stomps
+      # pending/absent — a verdict Tempo already delivered stays.
+      - if: failure()
+        run: npx --yes @tempo-ai/visual-review@latest report --fallback-failure --sha ${{ github.event.pull_request.head.sha }}
+        env:
+          GH_TOKEN: ${{ github.token }}