@bridge-ds/visual 0.0.0-stage → 0.2.0

package/dist/manifest.d.ts

@@ -0,0 +1,31 @@
+import type { Manifest, ShotResult, Summary } from './types.js';
+export declare const COMMENT_MARKER = "<!-- bridge-visual-impact -->";
+export declare function summarize(shots: ShotResult[]): Summary;
+/** Changed first (largest change first), then added, removed, errors, unchanged; stable within a group. */
+export declare function rankShots(shots: ShotResult[]): ShotResult[];
+export declare const hasVisualChange: (m: Pick<Manifest, "summary">) => boolean;
+/** One-paragraph plain-text summary (CLI output, MCP tool result). */
+export declare function summaryLine(m: Manifest): string;
+interface Group {
+    label: string;
+    shots: ShotResult[];
+}
+/** Shots grouped by label, in the order of their first (largest) shot. */
+export declare function groupByLabel(shots: ShotResult[]): Group[];
+/**
+ * Images for the comment: variety first. App screens (up to 2) and then one image per story, largest change
+ * first, before a second mode of the same story.
+ */
+export declare function pickImages(shots: ShotResult[], max: number): ShotResult[];
+export interface CommentOptions {
+    /** Base URL the manifest's relative image paths resolve against (raw.githubusercontent.com/.../pr-1/sha). */
+    imageBase?: string;
+    /** Link to the workflow run artifact with every image. */
+    artifactUrl?: string;
+    /** Composite images shown inline. */
+    maxImages?: number;
+    maxRows?: number;
+}
+/** The sticky PR comment: summary table plus before/after/diff composites of the largest changes. */
+export declare function renderComment(m: Manifest, o?: CommentOptions): string;
+export {};

package/dist/routes.d.ts

@@ -0,0 +1,11 @@
+import type { AppRoute, Tenant } from './types.js';
+export declare const DEFAULT_ROUTES: AppRoute[];
+export declare const DEFAULT_TENANTS: Tenant[];
+export declare const THEMES: readonly ["light", "dark"];
+export declare const BRANDS: readonly ["bridge", "ocean"];
+/** URL of a route in the built admin (hash router), with tenant, theme and language pinned in the query. */
+export declare function routeUrl(base: string, route: AppRoute, tenant: string, theme: string): string;
+/** URL of one story in the built Storybook, with brand and theme set as Storybook globals. */
+export declare function storyUrl(base: string, id: string, brand: string, theme: string): string;
+/** File-safe shot key. */
+export declare const shotKey: (...parts: string[]) => string;

package/dist/run.d.ts

@@ -0,0 +1,69 @@
+import { buildUsageIndex, LayeredTokenSet, type BridgeConfig } from '@bridge-ds/core';
+import type { AppRoute, Manifest, Only, Selection, StoryEntry, Tenant, Viewport } from './types.js';
+import { type BuildConfig, type Log } from './workspace.js';
+export interface ImpactOptions {
+    /** Repo root (a git checkout with node_modules installed). */
+    root: string;
+    base: string;
+    head: string;
+    /** Output folder for manifest.json and images. Default: <root>/visual-impact. */
+    out?: string;
+    only?: Only[];
+    /** pixelmatch threshold, 0..1. Default 0.03 (one step of a color ramp is about 0.1). */
+    threshold?: number;
+    /** Build cache folder, keyed by commit. Default: <root>/node_modules/.cache/bridge-visual. */
+    cacheDir?: string;
+    /** Temp folder for worktrees. Default: OS temp. */
+    workDir?: string;
+    /** Only compute the selection; no build, no browser. */
+    plan?: boolean;
+    /** Raw URL base for images in comment.md (the bridge-visual branch folder of this run). */
+    imageBase?: string;
+    artifactUrl?: string;
+    maxStoriesPerComponent?: number;
+    routes?: AppRoute[];
+    tenants?: Tenant[];
+    modes?: {
+        brand: string;
+        theme: string;
+    }[];
+    viewport?: {
+        stories?: Viewport;
+        app?: Viewport;
+    };
+    build?: BuildConfig;
+    /** Pages (tabs) capturing stories in parallel in the one browser. Default 2. */
+    concurrency?: number;
+    /** Keep before/after images of unchanged shots (off: only changed shots keep images). */
+    keepUnchanged?: boolean;
+    log?: Log;
+}
+export interface ImpactResult {
+    manifest: Manifest;
+    outDir: string;
+    manifestPath: string;
+    commentPath?: string;
+    summary: string;
+}
+/** Token paths whose resolved CSS value differs in at least one mode, with the modes. Direct edits flagged. */
+export declare function changedTokens(before: LayeredTokenSet, after: LayeredTokenSet): Selection['tokens'];
+export interface Plan {
+    base: {
+        ref: string;
+        sha: string;
+    };
+    head: {
+        ref: string;
+        sha: string;
+    };
+    config: BridgeConfig;
+    selection: Selection;
+    sources: {
+        stories: StoryEntry[];
+        librarySrc: string;
+        usage: ReturnType<typeof buildUsageIndex>;
+    };
+}
+/** Works out what to capture between two refs (no build, no browser). The base is the merge base. */
+export declare function planImpact(o: Pick<ImpactOptions, 'root' | 'base' | 'head' | 'only' | 'maxStoriesPerComponent' | 'build'>): Promise<Plan>;
+export declare function runImpact(o: ImpactOptions): Promise<ImpactResult>;

package/dist/select.d.ts

@@ -0,0 +1,31 @@
+import { type UsageIndex } from '@bridge-ds/core';
+import type { Selection, StoryEntry } from './types.js';
+export interface SelectInput {
+    /** Files changed between base and head (repo-relative). */
+    files: string[];
+    /** Token paths whose resolved value changed. */
+    tokens: Selection['tokens'];
+    cssVar: (path: string) => string;
+    usage: UsageIndex;
+    stories: StoryEntry[];
+    /** Root of the component library source, e.g. packages/react/src. Shared code here affects everything. */
+    librarySrc: string;
+    /** Files that change every story when edited (Storybook config, token build). Prefixes. */
+    globalPaths?: string[];
+    /** App source folder whose edits put the app screens in scope. */
+    appDir?: string;
+    maxStoriesPerComponent?: number;
+}
+/** Story entries grouped by component folder, or null for stories outside it (foundations). */
+export declare function storyComponent(s: StoryEntry, componentsDir: string): string | null;
+export declare function selectImpact(input: SelectInput): Selection;
+/** Storybook's id rules (CSF): "Feedback/Alert" + export "AllStates" -> "feedback-alert--all-states". */
+export declare function storyId(title: string, exportName: string): string;
+/**
+ * Stories read from CSF source without building Storybook (plan mode). Story ids follow Storybook's rules, so
+ * they match storybook-static/index.json for the usual `title` + named exports.
+ */
+export declare function storiesFromSource(files: {
+    path: string;
+    text: string;
+}[]): StoryEntry[];

package/dist/serve.d.ts

@@ -0,0 +1,5 @@
+export interface Served {
+    url: string;
+    close: () => Promise<void>;
+}
+export declare function serveDir(dir: string): Promise<Served>;

package/dist/types.d.ts

@@ -0,0 +1,141 @@
+export type Only = 'stories' | 'app';
+export interface Mode {
+    brand: string;
+    theme: string;
+}
+export interface StoryEntry {
+    id: string;
+    title: string;
+    name: string;
+    importPath: string;
+}
+export interface AppRoute {
+    /** Stable key used in file names: "orders-list". */
+    id: string;
+    label: string;
+    /** Hash route of the admin app (ra-core uses a hash router): "/orders". */
+    path: string;
+    /** Per-tenant path when record ids differ between seeded datasets (tenant id -> path). */
+    pathByTenant?: Record<string, string>;
+    /** CSS selector that must be visible before the screenshot (a drawer, a form). */
+    waitFor?: string;
+    /** Extra selectors painted over before the screenshot (volatile content). */
+    mask?: string[];
+}
+export interface Tenant {
+    id: string;
+    name: string;
+    brand: string;
+}
+export interface SelectedComponent {
+    id: string;
+    reasons: string[];
+    indirect: boolean;
+}
+export interface Selection {
+    /** Token paths whose resolved value differs between base and head, direct edits first. */
+    tokens: {
+        path: string;
+        kind: 'direct' | 'alias';
+        modes: string[];
+    }[];
+    vars: string[];
+    files: string[];
+    components: SelectedComponent[];
+    /** Story ids to capture, AllStates first per component. */
+    stories: string[];
+    /** Why every AllStates story is captured instead of a targeted list, or null. */
+    fallback: string | null;
+    /** Whether the admin screens are captured, and why. */
+    app: {
+        include: boolean;
+        reason: string;
+    };
+}
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type ShotStatus = 'changed' | 'unchanged' | 'added' | 'removed' | 'error';
+export interface ShotResult {
+    /** File-safe key: "story__feedback-alert--all-states__bridge-light". */
+    key: string;
+    kind: 'story' | 'route';
+    /** Human label: "Feedback/Alert: All states" or "Orders list". */
+    label: string;
+    storyId?: string;
+    route?: string;
+    tenant?: string;
+    brand: string;
+    theme: string;
+    status: ShotStatus;
+    changedPixels: number;
+    totalPixels: number;
+    /** Changed pixels in percent of the larger image, two decimals. */
+    percent: number;
+    boxes: Box[];
+    size: {
+        before: {
+            width: number;
+            height: number;
+        } | null;
+        after: {
+            width: number;
+            height: number;
+        } | null;
+    };
+    /** Paths relative to the manifest folder. Only changed shots keep diff and composite images. */
+    images: {
+        before?: string;
+        after?: string;
+        diff?: string;
+        composite?: string;
+    };
+    error?: string;
+}
+export interface Manifest {
+    version: 1;
+    tool: '@bridge-ds/visual';
+    createdAt: string;
+    durationMs: number;
+    base: {
+        ref: string;
+        sha: string;
+    };
+    head: {
+        ref: string;
+        sha: string;
+    };
+    options: {
+        only: Only[];
+        threshold: number;
+        plan?: boolean;
+        planned?: {
+            modes: number;
+            appScreens: number;
+        };
+        viewport: {
+            stories: Viewport;
+            app: Viewport;
+        };
+    };
+    selection: Selection;
+    summary: Summary;
+    shots: ShotResult[];
+}
+export interface Summary {
+    shots: number;
+    changed: number;
+    unchanged: number;
+    added: number;
+    removed: number;
+    errors: number;
+    /** Largest change, in percent. */
+    maxPercent: number;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}

package/dist/workspace.d.ts

@@ -0,0 +1,39 @@
+export type Log = (msg: string) => void;
+/**
+ * Gives `dst` (a worktree of the same repo) a node_modules that reuses the installed packages of `src`
+ * while its workspace packages (@bridge/*, @bridge-ds/*...) point at `dst`'s own sources. Per-checkout caches
+ * stay private. Nested workspace node_modules are linked too.
+ */
+export declare function linkNodeModules(src: string, dst: string): Promise<void>;
+export declare function addWorktree(repo: string, sha: string, dir: string): Promise<void>;
+export declare function removeWorktree(repo: string, dir: string): Promise<void>;
+export declare function run(cmd: string, args: string[], cwd: string, log: Log, root?: string, env?: Record<string, string>): Promise<void>;
+export interface BuildPlan {
+    storybook: boolean;
+    app: boolean;
+}
+export interface BuildConfig {
+    /** Folder of the app to build with Vite (relative to the repo root). */
+    appDir: string;
+    storybookConfigDir: string;
+    tokensBuild: string[];
+}
+export declare const DEFAULT_BUILD: BuildConfig;
+export interface Built {
+    storybook?: string;
+    app?: string;
+}
+/**
+ * Builds what `plan` asks for at commit `sha`, in a temporary worktree under `work`, into `cache/<sha>`.
+ * A build already in the cache is reused, so re-running against the same base is fast.
+ */
+export declare function buildRef(o: {
+    repo: string;
+    sha: string;
+    work: string;
+    cache: string;
+    plan: BuildPlan;
+    config?: BuildConfig;
+    log: Log;
+    keep?: boolean;
+}): Promise<Built>;

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@bridge-ds/visual",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Bridge visual impact analysis: screenshots the stories and app screens a design system change touches, at the base and head refs, and pixel-diffs them into before/after/diff images and a JSON manifest.",
+  "license": "MIT",
+  "author": "Florian Gouloubi",
+  "homepage": "https://github.com/peterbono/ai-design-system-demo/tree/main/packages/visual#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peterbono/ai-design-system-demo.git",
+    "directory": "packages/visual"
+  },
+  "bugs": {
+    "url": "https://github.com/peterbono/ai-design-system-demo/issues"
+  },
+  "keywords": [
+    "visual-regression",
+    "screenshots",
+    "design-system",
+    "bridge"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "node build.mjs",
+    "build:package": "node ../../scripts/build-packages.mjs visual"
+  },
+  "dependencies": {
+    "@bridge-ds/core": "^0.2.0",
+    "pixelmatch": "7.1.0",
+    "playwright-core": "1.63.0",
+    "pngjs": "7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.9",
+    "@types/pngjs": "6.0.5",
+    "esbuild": "0.27.7"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.