@calibrate-ds/core 0.1.41 → 0.1.42

package/dist/verify/index.d.ts

@@ -1,4 +1,5 @@
-export type { VerifyReport, VerifyScreenshots, PixelMatchResult, AIFeedback, AIDifference, } from "./types.js";
+export type { VerifyReport, VerifyScreenshots, PixelMatchResult, AIFeedback, AIDifference, StructureExpectations, StructureFound, } from "./types.js";
 export { fetchFigmaScreenshot } from "./fetch-figma-screenshot.js";
 export { runPixelDiff } from "./pixel-diff.js";
+export { extractStructuralExpectations, computeStructureScore } from "./structure-check.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/verify/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACR,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,YAAY,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACR,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,qBAAqB,EACrB,cAAc,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/verify/index.js

@@ -1,3 +1,4 @@
 export { fetchFigmaScreenshot } from "./fetch-figma-screenshot.js";
 export { runPixelDiff } from "./pixel-diff.js";
+export { extractStructuralExpectations, computeStructureScore } from "./structure-check.js";
 //# sourceMappingURL=index.js.map

package/dist/verify/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/verify/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/verify/structure-check.d.ts

@@ -0,0 +1,21 @@
+import type { StructureExpectations, StructureFound } from "./types.js";
+/**
+ * Walks a LayoutTreeNode tree (children only, not childOverrides which are
+ * variant branches) and counts structural slot types that must be present
+ * in the rendered DOM for a faithful implementation.
+ */
+export declare function extractStructuralExpectations(renderTree: any): StructureExpectations;
+/**
+ * Returns a 0–1 structure score — the fraction of expected structural slots
+ * that are present and non-empty in the rendered DOM.
+ *
+ * Returns undefined when there are no trackable slots (e.g. icon components),
+ * signalling the caller to fall back to the pixel score.
+ *
+ * Scoring weights:
+ *   - text slots: 70% of the total (more numerous and meaningful)
+ *   - image slots: 30% (binary — either the <img> exists or it doesn't)
+ * When only one slot type is present its weight becomes 100%.
+ */
+export declare function computeStructureScore(exp: StructureExpectations, found: StructureFound): number | undefined;
+//# sourceMappingURL=structure-check.d.ts.map

package/dist/verify/structure-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure-check.d.ts","sourceRoot":"","sources":["../../src/verify/structure-check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,GAAG,GAAG,qBAAqB,CA8BpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACjC,GAAG,EAAE,qBAAqB,EAC1B,KAAK,EAAE,cAAc,GACtB,MAAM,GAAG,SAAS,CAqBpB"}

package/dist/verify/structure-check.js

@@ -0,0 +1,63 @@
+/**
+ * Walks a LayoutTreeNode tree (children only, not childOverrides which are
+ * variant branches) and counts structural slot types that must be present
+ * in the rendered DOM for a faithful implementation.
+ */
+export function extractStructuralExpectations(renderTree) {
+    let textSlots = 0;
+    let imageSlots = 0;
+    const TEXT_ROLES = new Set([
+        "text", "title", "label", "description",
+        "placeholder-text", "error-text", "helper-text",
+    ]);
+    function walk(node) {
+        if (!node)
+            return;
+        const isTextByRole = TEXT_ROLES.has(node.role ?? "");
+        const isTextByType = node.rawStyles?.nodeType === "TEXT";
+        const isTextByValue = node.textContent !== undefined && node.type === "leaf";
+        if (isTextByRole || isTextByType || isTextByValue) {
+            textSlots++;
+        }
+        if (node.imageAssetPath) {
+            imageSlots++;
+        }
+        for (const child of node.children ?? [])
+            walk(child);
+        // intentionally skip childOverrides — those are variant branches, not distinct slots
+    }
+    walk(renderTree);
+    return { textSlots, imageSlots };
+}
+/**
+ * Returns a 0–1 structure score — the fraction of expected structural slots
+ * that are present and non-empty in the rendered DOM.
+ *
+ * Returns undefined when there are no trackable slots (e.g. icon components),
+ * signalling the caller to fall back to the pixel score.
+ *
+ * Scoring weights:
+ *   - text slots: 70% of the total (more numerous and meaningful)
+ *   - image slots: 30% (binary — either the <img> exists or it doesn't)
+ * When only one slot type is present its weight becomes 100%.
+ */
+export function computeStructureScore(exp, found) {
+    const hasText = exp.textSlots > 0;
+    const hasImage = exp.imageSlots > 0;
+    if (!hasText && !hasImage)
+        return undefined;
+    const parts = [];
+    if (hasText) {
+        // Partial credit: having MORE text nodes than expected is fine (min cap at 1).
+        // A rendered component that has all slots is worth 1; each missing slot reduces.
+        parts.push({ value: Math.min(1, found.textNodes / exp.textSlots), weight: 0.7 });
+    }
+    if (hasImage) {
+        // Binary: either the image region is rendered or it isn't.
+        parts.push({ value: found.imageElements > 0 ? 1 : 0, weight: 0.3 });
+    }
+    const totalWeight = parts.reduce((s, p) => s + p.weight, 0);
+    const weighted = parts.reduce((s, p) => s + p.value * p.weight, 0);
+    return parseFloat((weighted / totalWeight).toFixed(4));
+}
+//# sourceMappingURL=structure-check.js.map

package/dist/verify/structure-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure-check.js","sourceRoot":"","sources":["../../src/verify/structure-check.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,UAAe;IACzD,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;QACvB,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa;QACvC,kBAAkB,EAAE,YAAY,EAAE,aAAa;KAClD,CAAC,CAAC;IAEH,SAAS,IAAI,CAAC,IAAS;QACnB,IAAI,CAAC,IAAI;YAAE,OAAO;QAElB,MAAM,YAAY,GAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QACtD,MAAM,YAAY,GAAI,IAAI,CAAC,SAAS,EAAE,QAAQ,KAAK,MAAM,CAAC;QAC1D,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;QAE7E,IAAI,YAAY,IAAI,YAAY,IAAI,aAAa,EAAE,CAAC;YAChD,SAAS,EAAE,CAAC;QAChB,CAAC;QAED,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,UAAU,EAAE,CAAC;QACjB,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE;YAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACrD,qFAAqF;IACzF,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,CAAC;IACjB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACjC,GAA0B,EAC1B,KAAqB;IAErB,MAAM,OAAO,GAAI,GAAG,CAAC,SAAS,GAAI,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC;IAEpC,IAAI,CAAC,OAAO,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAE5C,MAAM,KAAK,GAA6C,EAAE,CAAC;IAE3D,IAAI,OAAO,EAAE,CAAC;QACV,+EAA+E;QAC/E,iFAAiF;QACjF,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACX,2DAA2D;QAC3D,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAM,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACtE,OAAO,UAAU,CAAC,CAAC,QAAQ,GAAG,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/verify/types.d.ts

@@ -5,6 +5,18 @@ export type VerifyScreenshots = {
     impl: string | null;
     diff: string | null;
 };
+export type StructureExpectations = {
+    /** Number of text-type leaf slots detected in the Figma renderTree. */
+    textSlots: number;
+    /** Number of image-fill slots detected in the Figma renderTree. */
+    imageSlots: number;
+};
+export type StructureFound = {
+    /** Non-empty leaf text elements in the rendered DOM. */
+    textNodes: number;
+    /** <img> elements + elements with a background-image CSS value. */
+    imageElements: number;
+};
 export type PixelMatchResult = {
     /** Full-frame raw pixel match score (0–1, 1 = identical). */
     score: number;
@@ -43,5 +55,16 @@ export type VerifyReport = {
     resolvedStoryId?: string;
     /** Human-readable error when resolved=false. */
     error?: string;
+    /**
+     * Structural slot presence score (0–1). Measures whether the expected number
+     * of text and image regions from the Figma renderTree are rendered in the DOM —
+     * independent of what text is actually shown (props are dynamic).
+     * Undefined for components with no trackable slots (e.g. icons).
+     */
+    structureScore?: number;
+    /** Slot counts extracted from the Figma renderTree. */
+    structureExpectations?: StructureExpectations;
+    /** Slot counts found in the rendered Storybook DOM. */
+    structureFound?: StructureFound;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/verify/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/verify/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yFAAyF;IACzF,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IACzC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC3B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,YAAY,EAAE,CAAC;IAC5B,iBAAiB,EAAE,SAAS,GAAG,mBAAmB,GAAG,yBAAyB,CAAC;CAClF,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,EAAE,OAAO,CAAC;IAClB,gGAAgG;IAChG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/verify/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yFAAyF;IACzF,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IACzC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAChC,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IACzB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC3B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,YAAY,EAAE,CAAC;IAC5B,iBAAiB,EAAE,SAAS,GAAG,mBAAmB,GAAG,yBAAyB,CAAC;CAClF,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,EAAE,OAAO,CAAC;IAClB,gGAAgG;IAChG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,uDAAuD;IACvD,cAAc,CAAC,EAAE,cAAc,CAAC;CACnC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calibrate-ds/core",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -27,8 +27,8 @@
     "pixelmatch": "^6.0.0",
     "pngjs": "^7.0.0",
     "zod": "^4.3.6",
-    "@calibrate-ds/shared-types": "^0.1.41",
-    "@calibrate-ds/figma-client": "^0.1.41"
+    "@calibrate-ds/shared-types": "^0.1.42",
+    "@calibrate-ds/figma-client": "^0.1.42"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",