@bridge-ds/visual 0.2.3 → 0.3.1

package/dist/capture.d.ts

@@ -7,7 +7,7 @@ export interface LaunchOptions {
     channel?: string;
 }
 export declare function launch(o?: LaunchOptions): Promise<Browser>;
-export declare function newContext(browser: Browser, viewport: Viewport): Promise<BrowserContext>;
+export declare function newContext(browser: Browser, viewport: Viewport, deviceScaleFactor?: number): Promise<BrowserContext>;
 export declare function newPage(ctx: BrowserContext): Promise<Page>;
 /** Waits for fonts, images, two frames, and a DOM whose markup stops changing (bounded). */
 export declare function settle(page: Page, o?: {

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export { selectImpact, storiesFromSource, storyId, storyComponent, type SelectIn
 export { diffPngs, boxesFromDiff, boxesFromCells, padTo, decodePng, encodePng, type DiffResult } from './diff.js';
 export { COMMENT_MARKER, hasVisualChange, rankShots, renderComment, summarize, summaryLine, type CommentOptions } from './manifest.js';
 export { DEFAULT_ROUTES, DEFAULT_TENANTS, routeUrl, storyUrl, shotKey } from './routes.js';
+export { captureFigmaReferences, type ReferencesOptions, type ReferencesResult } from './references.js';
 export { linkNodeModules } from './workspace.js';
 export type * from './types.js';

package/dist/index.js

@@ -75,6 +75,47 @@ function visualImpactProblems(raw) {
   return out;
 }
 
+// ../core/src/products.ts
+var DEFAULT_PRODUCTS = [
+  { key: "admin", name: "Admin demo", path: "apps/admin", framework: "react" },
+  { key: "library", name: "Library", default: true }
+];
+var KEY = /^[a-z0-9][a-z0-9-]*$/;
+var REPO = /^[\w.-]+\/[\w.-]+$/;
+var FIELDS = ["key", "name", "repo", "path", "preview", "framework", "default"];
+function productProblems(raw) {
+  if (raw === void 0) return [];
+  if (!Array.isArray(raw)) return ['"products" must be a list of { "key", "name" } objects'];
+  if (!raw.length) return ['"products" must list at least one product, or be left out to use the defaults'];
+  const problems = [];
+  const seen = /* @__PURE__ */ new Set();
+  let defaults = 0;
+  raw.forEach((p, i) => {
+    const at = `"products[${i}]`;
+    if (!p || typeof p !== "object" || Array.isArray(p)) {
+      problems.push(`${at}" must be an object with a "key" and a "name"`);
+      return;
+    }
+    const o = p;
+    for (const k of Object.keys(o)) if (!FIELDS.includes(k)) problems.push(`${at}.${k}" is not a known field (${FIELDS.join(", ")})`);
+    if (typeof o.key !== "string" || !KEY.test(o.key)) problems.push(`${at}.key" must be lowercase letters, digits and dashes, such as "admin"`);
+    else if (seen.has(o.key)) problems.push(`${at}.key" ("${o.key}") is used twice: give each product its own key`);
+    else seen.add(o.key);
+    if (typeof o.name !== "string" || !o.name.trim()) problems.push(`${at}.name" must be the name people read, such as "Admin demo"`);
+    if (o.repo !== void 0 && (typeof o.repo !== "string" || !REPO.test(o.repo))) problems.push(`${at}.repo" must be "owner/name"`);
+    if (o.path !== void 0) {
+      const bad = typeof o.path !== "string" || !o.path.trim() || o.path.startsWith("/") || o.path.split("/").includes("..");
+      if (bad) problems.push(`${at}.path" must be a folder relative to the repository root, without a leading "/" or "..", such as "apps/admin"`);
+    }
+    if (o.preview !== void 0 && (typeof o.preview !== "string" || !/^https?:\/\//.test(o.preview))) problems.push(`${at}.preview" must be an http(s) URL template, such as "https://app-git-{branch}.vercel.app"`);
+    if (o.framework !== void 0 && (typeof o.framework !== "string" || !o.framework.trim())) problems.push(`${at}.framework" must be a name such as "react", "vue" or "other"`);
+    if (o.default !== void 0 && typeof o.default !== "boolean") problems.push(`${at}.default" must be true or false`);
+    if (o.default === true) defaults++;
+  });
+  if (defaults > 1) problems.push('"products" marks more than one product as default: keep "default": true on the library only');
+  return problems;
+}
+
 // ../core/src/config.ts
 var CONFIG_FILE = "bridge.config.json";
 var DEFAULT_OVERRIDE = { allowed: [], requireReason: true, minReasonLength: 20 };
@@ -215,6 +256,7 @@ function defineConfig(input) {
       } : {},
       ...g.rights ? { rights: normalizeRights(g.rights) } : {}
     },
+    products: input.products?.length ? input.products.map((p) => ({ ...p })) : DEFAULT_PRODUCTS.map((p) => ({ ...p })),
     ...input.audit ? { audit: { ...input.audit } } : {},
     ...input.visualImpact ? { visualImpact: { mode: input.visualImpact.mode === "on-demand" ? "on-demand" : "auto" } } : {},
     ...input.integrations ? { integrations: { ...input.integrations } } : {},
@@ -337,6 +379,7 @@ function loadConfig(source) {
     }
   }
   problems.push(...visualImpactProblems(d.visualImpact));
+  problems.push(...productProblems(d.products));
   const audit = d.audit;
   if (audit !== void 0) {
     if (!isObj(audit)) problems.push('"audit" must be an object');
@@ -793,6 +836,148 @@ function impactedModules(index, input) {
   return { modules, globalHits };
 }
 
+// ../core/src/component-spec.ts
+var COMPONENT_SPECS_VERSION = 1;
+var variantKeyOf = (props) => Object.keys(props).sort().map((k) => `${k}=${props[k]}`).join(", ") || "Default";
+function parseComponentSpecs(text) {
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new Error("component-specs.json is not valid JSON.");
+  }
+  const f = data;
+  if (!f || typeof f !== "object" || !Array.isArray(f.components)) throw new Error('component-specs.json has no "components" list.');
+  if (f.version !== COMPONENT_SPECS_VERSION) throw new Error(`component-specs.json is version ${String(f.version)}; this tool reads version ${COMPONENT_SPECS_VERSION}.`);
+  return f;
+}
+
+// ../core/src/fidelity-references.ts
+var FIGMA_REFERENCES_DIR = "figma-references";
+var FIGMA_REFERENCES_MANIFEST = `${FIGMA_REFERENCES_DIR}/manifest.json`;
+var FIGMA_REFERENCE_STORY = "internal-figma-reference--variant";
+var FIGMA_FILL_WIDTH_TOKEN = "size.80";
+var STATE_PSEUDO = {
+  default: "rest",
+  rest: "rest",
+  enabled: "rest",
+  hover: "hover",
+  hovered: "hover",
+  pressed: "active",
+  active: "active",
+  focus: "focus-visible",
+  focused: "focus-visible",
+  "focus visible": "focus-visible",
+  disabled: "disabled"
+};
+var iconName = (component) => component.replace(/^Icon\//, "");
+var exportName = (name) => name.replace(/[^A-Za-z0-9]+/g, "");
+function planReference(spec, variant, file) {
+  if (spec.view === "popup") return { ok: false, reason: "drawn open in Figma; the code image shows it closed" };
+  const props = { ...spec.fixed ?? {} };
+  let pseudo;
+  for (const axis of spec.axes) {
+    const value = variant.props[axis.name];
+    if (value === void 0) return { ok: false, reason: `the variant has no ${axis.name} value` };
+    if (axis.prop) {
+      props[axis.prop] = value === "true" ? true : value === "false" ? false : value;
+      continue;
+    }
+    if (axis.name === "Checked") {
+      props.checked = value === "true";
+      if (value === "mixed") props.indeterminate = true;
+      continue;
+    }
+    if (axis.name.toLowerCase() !== "state") return { ok: false, reason: `${axis.name} has no matching option in code` };
+    const s = STATE_PSEUDO[value.toLowerCase()];
+    if (!s) return { ok: false, reason: `the ${value} state has no code equivalent to render` };
+    if (s === "disabled") props.disabled = true;
+    else if (s !== "rest") pseudo = s;
+  }
+  const root = spec.parts.find((p) => !p.parent);
+  if (!root) return { ok: false, reason: "the spec has no root layer" };
+  const children = (id) => spec.parts.filter((p) => p.parent === id);
+  const textOf = (part) => {
+    const swapTo = variant.slots?.[part.id] ?? part.swap?.default;
+    if (part.swap && swapTo) {
+      const slot = file?.slots?.find((s) => s.name === swapTo);
+      if (!slot) return { reason: `${swapTo} is not in the specs` };
+      if (slot.kind !== "text" || !slot.text) return { reason: `Figma shows a placeholder (${swapTo}) that code has no example of` };
+      return slot.text.default;
+    }
+    const prop = spec.properties.find((p) => p.name === part.text && p.type === "TEXT");
+    return typeof prop?.default === "string" ? prop.default : part.name;
+  };
+  let text;
+  const icons = {};
+  for (const prop of spec.properties) {
+    if (prop.type === "TEXT") {
+      const hidden = spec.properties.some((b) => b.type === "BOOLEAN" && b.prop === prop.prop && b.default === false);
+      if (hidden && prop.prop) continue;
+      if (prop.prop === "children") text = String(prop.default);
+      else if (prop.prop) props[prop.prop] = String(prop.default);
+      continue;
+    }
+    const iconPart = spec.parts.find((p) => p.kind === "icon" && p.visible === prop.name);
+    if (prop.default === true && !iconPart && prop.prop && props[prop.prop] === void 0 && spec.example?.p?.[prop.prop] === void 0) props[prop.prop] = true;
+  }
+  for (const part of spec.parts) {
+    if (part.kind !== "icon" || !part.swap) continue;
+    const shown = part.visible ? spec.properties.find((p) => p.name === part.visible)?.default === true : true;
+    if (!shown) continue;
+    if (!part.swap.prop) return { ok: false, reason: `the ${part.name} icon has no matching option in code` };
+    icons[part.swap.prop] = iconName(variant.slots?.[part.id] ?? part.swap.default);
+  }
+  let parts;
+  const loose = spec.properties.filter((p) => p.type === "TEXT" && !p.prop);
+  const frames = children(root.id).filter((p) => p.kind === "frame");
+  const compound = text === void 0 && frames.length > 0 && frames.every((f) => spec.parts.some((p) => p.parent === f.id && p.kind === "text" && (p.swap || p.text === f.name)));
+  if (compound) {
+    parts = [];
+    for (const f of frames) {
+      const t = spec.parts.find((p) => p.parent === f.id && p.kind === "text");
+      const value = textOf(t);
+      if (typeof value !== "string") return { ok: false, reason: value.reason };
+      parts.push({ component: `${exportName(spec.name)}${exportName(f.name)}`, text: value });
+    }
+  }
+  for (const p of loose) {
+    if (p.name === "Value") continue;
+    const part = spec.parts.find((x) => x.text === p.name);
+    if (compound && part && part.parent !== root.id) continue;
+    if (part && /placeholder$/.test(part.id)) {
+      props.placeholder = String(p.default);
+      continue;
+    }
+    return { ok: false, reason: `the ${p.name} text has no matching option in code` };
+  }
+  const example = spec.example;
+  const exampleChildren = example?.children?.length ? example.children : void 0;
+  return {
+    ok: true,
+    render: {
+      component: exportName(spec.view || spec.fixed || example ? example?.c ?? spec.component ?? spec.name : spec.name),
+      props: { ...example?.p ?? {}, ...props },
+      ...exampleChildren ? { children: exampleChildren } : {},
+      ...text !== void 0 && !exampleChildren ? { text } : {},
+      ...parts && !exampleChildren ? { parts } : {},
+      ...Object.keys(icons).length ? { icons } : {},
+      ...pseudo ? { pseudo } : {},
+      ...root.fill ? { width: FIGMA_FILL_WIDTH_TOKEN } : {}
+    }
+  };
+}
+function referenceImagePath(component, key) {
+  const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  const file = key.split(",").map((kv) => slug(kv)).filter(Boolean).join("__");
+  return `${slug(component)}/${file || "default"}.png`;
+}
+function planReferences(file) {
+  return file.components.flatMap(
+    (spec) => spec.variants.map((v) => ({ component: spec.name, specHash: spec.hash, key: variantKeyOf(v.props), plan: planReference(spec, v, file) }))
+  );
+}
+
 // ../core/src/node/git-local.ts
 import { execFile } from "node:child_process";
 function git(root, args, opts = {}) {
@@ -838,8 +1023,8 @@ async function launch(o = {}) {
     args: ["--lang=en-US", "--disable-gpu", "--font-render-hinting=none", "--disable-lcd-text", "--force-color-profile=srgb", "--hide-scrollbars", "--disable-skia-runtime-opts", "--disable-renderer-backgrounding"]
   });
 }
-async function newContext(browser, viewport) {
-  const ctx = await browser.newContext({ viewport, deviceScaleFactor: 1, reducedMotion: "reduce", colorScheme: "light", locale: "en-US", timezoneId: "UTC", serviceWorkers: "block" });
+async function newContext(browser, viewport, deviceScaleFactor = 1) {
+  const ctx = await browser.newContext({ viewport, deviceScaleFactor, reducedMotion: "reduce", colorScheme: "light", locale: "en-US", timezoneId: "UTC", serviceWorkers: "block" });
   await ctx.addInitScript(INIT_SCRIPT);
   await ctx.route(
     /^https?:\/\/(?!127\.0\.0\.1[:/]|localhost[:/])/,
@@ -1272,9 +1457,9 @@ function selectImpact(input) {
     app
   };
 }
-function storyId(title, exportName) {
+function storyId(title, exportName2) {
   const sanitize = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+/, "").replace(/-+$/, "");
-  const startCase = exportName.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2").replace(/[_-]+/g, " ").trim();
+  const startCase = exportName2.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2").replace(/[_-]+/g, " ").trim();
   return `${sanitize(title)}--${sanitize(startCase)}`;
 }
 function storiesFromSource(files) {
@@ -1788,12 +1973,106 @@ async function runImpact(o) {
   log(`${result.summary} Manifest: ${relative2(process.cwd(), result.manifestPath) || result.manifestPath}`);
   return result;
 }
+
+// src/references.ts
+import { existsSync as existsSync4 } from "node:fs";
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises";
+import { dirname as dirname3, join as join4 } from "node:path";
+async function captureFigmaReferences(o) {
+  const log = o.log ?? (() => void 0);
+  const scale = o.scale ?? 2;
+  const brand = o.brand ?? "bridge";
+  const theme = o.theme ?? "light";
+  if (!existsSync4(join4(o.storybook, "index.json"))) throw new Error(`No built Storybook in ${o.storybook}: run npm run build-storybook first.`);
+  const index = JSON.parse(await readFile4(join4(o.storybook, "index.json"), "utf8"));
+  if (!index.entries[FIGMA_REFERENCE_STORY]) throw new Error(`The Storybook build has no ${FIGMA_REFERENCE_STORY} story (packages/react/src/stories/FigmaReference.stories.tsx).`);
+  const specs = parseComponentSpecs(await readFile4(o.specs, "utf8"));
+  const jobs = planReferences(specs).filter((j) => !o.only?.length || o.only.includes(j.component));
+  const manifest = {
+    version: 1,
+    tool: "@bridge-ds/visual",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    sha: o.sha,
+    scale,
+    mode: { brand, theme, density: "comfortable" },
+    storyId: FIGMA_REFERENCE_STORY,
+    components: {}
+  };
+  for (const j of jobs) manifest.components[j.component] ??= { specHash: j.specHash, variants: {} };
+  let captured = 0;
+  let skipped = 0;
+  const served = await serveDir(o.storybook);
+  const browser = await launch();
+  try {
+    const ctx = await newContext(browser, { width: 1200, height: 800 }, scale);
+    const page = await newPage(ctx);
+    await page.goto(storyUrl(served.url, FIGMA_REFERENCE_STORY, brand, theme), { waitUntil: "load", timeout: 3e4 });
+    await page.waitForSelector("[data-fidelity-root], [data-fidelity-error]", { state: "attached", timeout: 2e4 });
+    await settle(page, { busy: false });
+    log(`Capturing ${jobs.length} variants at ${scale}x (${brand} ${theme})`);
+    for (const j of jobs) {
+      const variants = manifest.components[j.component].variants;
+      if (!j.plan.ok) {
+        variants[j.key] = { skipped: j.plan.reason };
+        skipped++;
+        continue;
+      }
+      const plan = JSON.stringify(j.plan.render);
+      await page.evaluate(
+        ({ id, plan: plan2 }) => new Promise((resolve2) => {
+          const ch = window.__STORYBOOK_ADDONS_CHANNEL__;
+          const done = () => {
+            clearTimeout(timer);
+            ch.off("storyRendered", done);
+            resolve2();
+          };
+          const timer = setTimeout(done, 1e4);
+          ch.on("storyRendered", done);
+          ch.emit("updateStoryArgs", { storyId: id, updatedArgs: { plan: plan2 } });
+        }),
+        { id: FIGMA_REFERENCE_STORY, plan }
+      );
+      await settle(page, { network: false, quiet: 2, interval: 40, busy: false });
+      const error = await page.locator("[data-fidelity-error]").first().textContent({ timeout: 200 }).catch(() => null);
+      let target = page.locator("[data-fidelity-root] > *").first();
+      if (!error && !await target.count()) {
+        const marked = page.locator("[data-fidelity-target]").first();
+        await marked.waitFor({ state: "visible", timeout: 3e3 }).catch(() => void 0);
+        await settle(page, { network: false, quiet: 2, interval: 40, busy: false });
+        target = marked;
+      }
+      if (error || !await target.count()) {
+        variants[j.key] = { skipped: error ?? "the code example did not render" };
+        skipped++;
+        continue;
+      }
+      const file = referenceImagePath(j.component, j.key);
+      const path = join4(o.out, file);
+      await mkdir4(dirname3(path), { recursive: true });
+      await target.screenshot({ path, omitBackground: true, animations: "disabled", caret: "hide", scale: "device" });
+      const box = await target.boundingBox();
+      variants[j.key] = { file, width: Math.round(box?.width ?? 0), height: Math.round(box?.height ?? 0) };
+      captured++;
+    }
+    await ctx.close();
+  } finally {
+    await browser.close().catch(() => void 0);
+    await served.close();
+  }
+  await mkdir4(o.out, { recursive: true });
+  const manifestPath = join4(o.out, "manifest.json");
+  await writeFile4(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  log(`${captured} images, ${skipped} variants skipped. ${manifestPath}`);
+  return { manifest, manifestPath, captured, skipped };
+}
 export {
   COMMENT_MARKER,
   DEFAULT_ROUTES,
   DEFAULT_TENANTS,
   boxesFromCells,
   boxesFromDiff,
+  captureFigmaReferences,
   changedTokens,
   decodePng,
   diffPngs,

package/dist/references.d.ts

@@ -0,0 +1,22 @@
+import { type FigmaReferenceManifest } from '@bridge-ds/core';
+export interface ReferencesOptions {
+    /** Built Storybook folder (storybook-static). */
+    storybook: string;
+    /** component-specs.json path. */
+    specs: string;
+    out: string;
+    sha: string;
+    scale?: number;
+    brand?: string;
+    theme?: string;
+    /** Only these components (names). */
+    only?: string[];
+    log?: (line: string) => void;
+}
+export interface ReferencesResult {
+    manifest: FigmaReferenceManifest;
+    manifestPath: string;
+    captured: number;
+    skipped: number;
+}
+export declare function captureFigmaReferences(o: ReferencesOptions): Promise<ReferencesResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/visual",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "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",
@@ -47,7 +47,7 @@
     "build:package": "node ../../scripts/build-packages.mjs visual"
   },
   "dependencies": {
-    "@bridge-ds/core": "^0.5.0",
+    "@bridge-ds/core": "^0.7.0",
     "pixelmatch": "7.1.0",
     "playwright-core": "1.63.0",
     "pngjs": "7.0.0"