@bridge-ds/visual 0.3.12 → 0.3.14

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Florian Gouloubi
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/capture.d.ts

@@ -38,3 +38,13 @@ export declare function shoot(page: Page, r: ShotRequest): Promise<string | null
  * click a story), much faster than a page load per story. Resolves once the story rendered or failed.
  */
 export declare function switchStory(page: Page, storyId: string): Promise<void>;
+/**
+ * A page for `bridge specs --measure`: an installed Chrome, one page at 1200x800, light scheme, reduced motion. Unlike
+ * the capture context it reaches remote hosts (a team's deployed Storybook). Close it when done.
+ */
+export declare function openMeasurePage(o?: LaunchOptions & {
+    scale?: number;
+}): Promise<{
+    page: Page;
+    close: () => Promise<void>;
+}>;

package/dist/diff.d.ts

@@ -12,6 +12,8 @@ export interface DiffResult {
 }
 export declare const decodePng: (buf: Buffer) => PNG;
 export declare const encodePng: (png: PNG) => Buffer;
+/** The `x, y, width, height` region of `src` (px of the image), clipped to it. */
+export declare function cropPng(src: PNG, x: number, y: number, width: number, height: number): PNG;
 /** Copies `src` onto a `width` x `height` canvas filled with an opaque neutral, so sizes can differ. */
 export declare function padTo(src: PNG, width: number, height: number): PNG;
 /**

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { runImpact, planImpact, changedTokens, type ImpactOptions, type ImpactResult, type Plan } from './run.js';
 export { selectImpact, storiesFromSource, storyId, storyComponent, type SelectInput } from './select.js';
-export { diffPngs, boxesFromDiff, boxesFromCells, padTo, decodePng, encodePng, type DiffResult } from './diff.js';
+export { diffPngs, boxesFromDiff, boxesFromCells, padTo, cropPng, 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 { openMeasurePage } from './capture.js';
 export type * from './types.js';

package/dist/index.js

@@ -121,6 +121,12 @@ var CONFIG_FILE = "bridge.config.json";
 var CHANGES_MODES = ["suggest", "direct"];
 var DEFAULT_CHANGES_MODE = "suggest";
 var DEFAULT_OVERRIDE = { allowed: [], requireReason: true, minReasonLength: 20 };
+var TEAM_NAME_MAX = 60;
+function teamName(value) {
+  if (typeof value !== "string") return void 0;
+  const v = value.trim().replace(/\s+/g, " ");
+  return v && v.length <= TEAM_NAME_MAX ? v : void 0;
+}
 var DEFAULT_TOKEN_PATHS = {
   root: "tokens",
   primitives: "primitives",
@@ -226,6 +232,7 @@ function defineConfig(input) {
   const g = input.governance ?? {};
   const contrastFile = contrastPath ?? [root === "." ? "" : root, paths.contrastChecks].filter(Boolean).join("/");
   return {
+    ...teamName(input.name) ? { name: teamName(input.name) } : {},
     repo: parseRepoInput(input.repo, input.branch),
     tokens: { ...paths, include: input.tokens?.include ?? ["**/*.tokens.json"], exclude: input.tokens?.exclude ?? [], tiers, layers, ...t.usage ? { usage: trimSlashes(t.usage) } : {} },
     axes,
@@ -258,12 +265,14 @@ function defineConfig(input) {
         }
       } : {},
       ...g.rights ? { rights: normalizeRights(g.rights) } : {},
-      ...g.soloOwnerCanApproveBoth === true ? { soloOwnerCanApproveBoth: true } : {}
+      ...g.soloOwnerCanApproveBoth === true ? { soloOwnerCanApproveBoth: true } : {},
+      ...g.leadsPublishTier1 === false ? { leadsPublishTier1: false } : {}
     },
     products: input.products?.length ? input.products.map((p) => ({ ...p })) : DEFAULT_PRODUCTS.map((p) => ({ ...p })),
     changes: input.changes === "direct" ? "direct" : DEFAULT_CHANGES_MODE,
     ...input.storybook?.url ? { storybook: { url: input.storybook.url.trim().replace(/\/+$/, "") } } : {},
     ...input.library?.public === true ? { library: { public: true } } : {},
+    ...input.demo?.viewer?.trim() ? { demo: { viewer: input.demo.viewer.trim(), ...input.demo.role?.trim() ? { role: input.demo.role.trim() } : {} } } : {},
     ...input.audit ? { audit: { ...input.audit } } : {},
     ...input.visualImpact ? { visualImpact: { mode: input.visualImpact.mode === "on-demand" ? "on-demand" : "auto" } } : {},
     ...input.integrations ? { integrations: { ...input.integrations } } : {},
@@ -385,9 +394,11 @@ function loadConfig(source) {
       }
       problems.push(...rightsProblems(gov.rights));
       if (gov.soloOwnerCanApproveBoth !== void 0 && typeof gov.soloOwnerCanApproveBoth !== "boolean") problems.push('"governance.soloOwnerCanApproveBoth" must be true or false');
+      if (gov.leadsPublishTier1 !== void 0 && typeof gov.leadsPublishTier1 !== "boolean") problems.push('"governance.leadsPublishTier1" must be true or false');
     }
   }
   problems.push(...visualImpactProblems(d.visualImpact));
+  if (d.name !== void 0 && teamName(d.name) === void 0) problems.push(`"name" must be the team's name, 1 to ${TEAM_NAME_MAX} characters`);
   if (d.changes !== void 0 && !CHANGES_MODES.includes(d.changes)) problems.push(`"changes" must be "suggest" or "direct" (got ${JSON.stringify(d.changes)})`);
   const sb = d.storybook;
   if (sb !== void 0) {
@@ -403,6 +414,14 @@ function loadConfig(source) {
       for (const k of Object.keys(lib)) if (k !== "public") problems.push(`"library.${k}" is not a known key`);
     }
   }
+  const demo = d.demo;
+  if (demo !== void 0) {
+    if (!isObj(demo) || !isStr(demo.viewer) || !demo.viewer.trim()) problems.push('"demo" must be { "viewer" }, for example { "viewer": "Dana", "role": "DS lead" }');
+    else {
+      if (demo.role !== void 0 && !isStr(demo.role)) problems.push('"demo.role" must be a string, for example "DS lead"');
+      for (const k of Object.keys(demo)) if (k !== "viewer" && k !== "role") problems.push(`"demo.${k}" is not a known key`);
+    }
+  }
   problems.push(...productProblems(d.products));
   const audit = d.audit;
   if (audit !== void 0) {
@@ -897,7 +916,7 @@ var STATE_PSEUDO = {
 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" };
+  if (spec.view === "popup") return planPopup(spec, variant);
   const props = { ...spec.fixed ?? {} };
   let pseudo;
   for (const axis of spec.axes) {
@@ -926,6 +945,7 @@ function planReference(spec, variant, file) {
     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 === "media") return { reason: `Figma shows a media placeholder (${swapTo}); code shows the image it is given, nothing to compare` };
       if (slot.kind !== "text" || !slot.text) return { reason: `Figma shows a placeholder (${swapTo}) that code has no example of` };
       return slot.text.default;
     }
@@ -977,10 +997,13 @@ function planReference(spec, variant, file) {
   }
   const example = spec.example;
   const exampleChildren = example?.children?.length ? example.children : void 0;
+  const component = exportName(example?.c ?? (spec.name.includes("/") ? spec.component ?? spec.name : spec.name));
+  const parent = spec.component ? exportName(spec.component) : void 0;
   return {
     ok: true,
     render: {
-      component: exportName(spec.view || spec.fixed || example ? example?.c ?? spec.component ?? spec.name : spec.name),
+      component,
+      ...parent && parent !== component ? { within: parent } : {},
       props: { ...example?.p ?? {}, ...props },
       ...exampleChildren ? { children: exampleChildren } : {},
       ...text !== void 0 && !exampleChildren ? { text } : {},
@@ -991,6 +1014,28 @@ function planReference(spec, variant, file) {
     }
   };
 }
+function planPopup(spec, variant) {
+  const root = spec.parts.find((p) => !p.parent);
+  const own = {};
+  for (const axis of spec.axes) {
+    const value = variant.props[axis.name];
+    if (!axis.prop || value === void 0) return { ok: false, reason: `${axis.name} has no matching option in code` };
+    own[axis.prop] = value === "true" ? true : value === "false" ? false : value;
+  }
+  const className = /\.module\.css \.([\w-]+)/.exec(root?.source ?? "")?.[1];
+  const component = spec.component ? exportName(spec.component) : void 0;
+  const example = spec.example;
+  if (!component || !example) return { ok: false, reason: "drawn open from no code example: nothing to open in code" };
+  if (!className) return { ok: false, reason: "the popup has no class to find it by in code" };
+  const popup = { className };
+  if (exportName(example.c) === component) {
+    return { ok: true, render: { component, props: { ...example.p ?? {}, ...own, defaultOpen: true }, ...example.children?.length ? { children: example.children } : {}, popup } };
+  }
+  return {
+    ok: true,
+    render: { component, props: { defaultOpen: true }, children: [{ c: `${component}Trigger`, children: ["Open"] }, { ...example, p: { ...example.p ?? {}, ...own } }], popup }
+  };
+}
 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("__");
@@ -1214,6 +1259,17 @@ async function switchStory(page, storyId2) {
   );
   if (!ok) throw new Error("Storybook channel not found");
 }
+async function openMeasurePage(o = {}) {
+  const browser = await launch(o);
+  try {
+    const ctx = await browser.newContext({ viewport: { width: 1200, height: 800 }, deviceScaleFactor: o.scale ?? 1, reducedMotion: "reduce", colorScheme: "light", locale: "en-US", serviceWorkers: "block" });
+    const page = await ctx.newPage();
+    return { page, close: () => browser.close().catch(() => void 0) };
+  } catch (e) {
+    await browser.close().catch(() => void 0);
+    throw e;
+  }
+}
 
 // src/composite.ts
 import { readFile, writeFile as writeFile2 } from "node:fs/promises";
@@ -1265,6 +1321,15 @@ import pixelmatch from "pixelmatch";
 import { PNG } from "pngjs";
 var decodePng = (buf) => PNG.sync.read(buf);
 var encodePng = (png) => PNG.sync.write(png, { colorType: 6 });
+function cropPng(src, x, y, width, height) {
+  const left = Math.max(0, Math.round(x));
+  const top = Math.max(0, Math.round(y));
+  const w = Math.max(1, Math.min(src.width - left, Math.round(width)));
+  const h = Math.max(1, Math.min(src.height - top, Math.round(height)));
+  const out = new PNG({ width: w, height: h });
+  PNG.bitblt(src, out, left, top, w, h, 0, 0);
+  return out;
+}
 function padTo(src, width, height) {
   if (src.width === width && src.height === height) return src;
   const out = new PNG({ width, height });
@@ -2105,9 +2170,12 @@ async function captureFigmaReferences(o) {
   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 });
+    const openStory = async () => {
+      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 });
+    };
+    await openStory();
     log(`Capturing ${jobs.length} variants at ${scale}x (${brand} ${theme})`);
     for (const j of jobs) {
       const variants = manifest.components[j.component].variants;
@@ -2116,25 +2184,17 @@ async function captureFigmaReferences(o) {
         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 }
-      );
+      const shown = await renderPlan(page, JSON.stringify(j.plan.render));
+      if (shown.broken) {
+        variants[j.key] = { skipped: `the code example threw: ${shown.error ?? "the story did not finish rendering"}` };
+        skipped++;
+        await openStory();
+        continue;
+      }
       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()) {
+      if (!error && (j.plan.render.within || j.plan.render.popup || !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 });
@@ -2145,6 +2205,15 @@ async function captureFigmaReferences(o) {
         skipped++;
         continue;
       }
+      const transparent = await target.evaluate((el) => {
+        for (let e = el; e; e = e.parentElement) if (getComputedStyle(e).opacity === "0") return true;
+        return false;
+      });
+      if (transparent) {
+        variants[j.key] = { skipped: "the code example rendered invisible (opacity 0)" };
+        skipped++;
+        continue;
+      }
       const file = referenceImagePath(j.component, j.key);
       const path = join4(o.out, file);
       await mkdir4(dirname3(path), { recursive: true });
@@ -2165,6 +2234,35 @@ async function captureFigmaReferences(o) {
   log(`${captured} images, ${skipped} variants skipped. ${manifestPath}`);
   return { manifest, manifestPath, captured, skipped };
 }
+async function renderPlan(page, plan) {
+  const r = await page.evaluate(
+    ({ id, plan: plan2 }) => new Promise((resolve2) => {
+      const ch = window.__STORYBOOK_ADDONS_CHANNEL__;
+      let error;
+      const failed = (p) => {
+        const e = p;
+        error ??= e?.message ?? e?.title ?? e?.description;
+      };
+      const finish = (rendered) => {
+        clearTimeout(timer);
+        ch.off("storyRendered", done);
+        ch.off("storyThrewException", failed);
+        ch.off("storyErrored", failed);
+        resolve2({ rendered, ...error ? { error } : {} });
+      };
+      const done = () => finish(true);
+      document.querySelectorAll("[data-fidelity-target]").forEach((el) => el.removeAttribute("data-fidelity-target"));
+      const timer = setTimeout(() => finish(false), 1e4);
+      ch.on("storyThrewException", failed);
+      ch.on("storyErrored", failed);
+      ch.on("storyRendered", done);
+      ch.emit("updateStoryArgs", { storyId: id, updatedArgs: { plan: plan2 } });
+    }),
+    { id: FIGMA_REFERENCE_STORY, plan }
+  );
+  const errorScreen = await page.evaluate(() => document.body.classList.contains("sb-show-errordisplay"));
+  return { broken: !r.rendered || !!r.error || errorScreen, ...r.error ? { error: r.error } : {} };
+}
 export {
   COMMENT_MARKER,
   DEFAULT_ROUTES,
@@ -2173,11 +2271,13 @@ export {
   boxesFromDiff,
   captureFigmaReferences,
   changedTokens,
+  cropPng,
   decodePng,
   diffPngs,
   encodePng,
   hasVisualChange,
   linkNodeModules,
+  openMeasurePage,
   padTo,
   planImpact,
   rankShots,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@bridge-ds/visual",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "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",
+  "license": "FSL-1.1-MIT",
   "author": "Florian Gouloubi",
   "homepage": "https://github.com/peterbono/ai-design-system-demo/tree/main/packages/visual#readme",
   "repository": {
@@ -47,7 +47,7 @@
     "build:package": "node ../../scripts/build-packages.mjs visual"
   },
   "dependencies": {
-    "@bridge-ds/core": "^0.18.0",
+    "@bridge-ds/core": "^0.20.0",
     "pixelmatch": "7.1.0",
     "playwright-core": "1.63.0",
     "pngjs": "7.0.0"