@tangle-network/browser-agent-driver 0.33.2 → 0.34.0

package/dist/design/audit/tokens/extract.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Design token extraction — pure DOM mining, no LLM calls.
+ *
+ * Leaf module: loads a page at multiple viewports, mines colours, typography,
+ * spacing, components, and brand/asset references inside `page.evaluate`,
+ * clusters them into a `DesignTokens` artifact, downloads referenced assets,
+ * and zips the result. Imported (often lazily) by the CLI design-audit handler,
+ * the design-compare diff, and the reference-DNA page adapter.
+ */
+import type { DesignTokens } from '../../../types.js';
+import type { RawScrollCapture } from '../reference/contracts.js';
+export interface ExtractDesignTokensOptions {
+    url: string;
+    headless?: boolean;
+    outputDir?: string;
+    viewports?: Array<{
+        name: string;
+        width: number;
+        height: number;
+    }>;
+    onProgress?: (viewport: string, width: number, height: number, stats: {
+        colors: number;
+        fonts: number;
+        buttons: number;
+        inputs: number;
+        cards: number;
+    }) => void;
+    /**
+     * Opt in to the live scroll-motion capture pass (default OFF). When set, a
+     * stepped top→bottom scroll runs on the desktop viewport after token
+     * extraction and the observed `RawScrollCapture` is returned on
+     * `ExtractionResult.scrollMotion`. Off by default — it adds page time and is
+     * only meaningful for live audits / corpus authoring.
+     */
+    captureScrollMotion?: boolean;
+}
+export interface ExtractionResult {
+    tokens: DesignTokens;
+    outputDir: string;
+    screenshotPaths: Record<string, string>;
+    /**
+     * Live scroll-motion observation, present only when `captureScrollMotion` was
+     * set AND the desktop page was actually scrollable. `undefined` otherwise
+     * (not captured) — never read its absence as "no scroll motion".
+     */
+    scrollMotion?: RawScrollCapture;
+}
+/**
+ * Extract design tokens from a URL at multiple viewports.
+ * Pure DOM extraction — no LLM calls.
+ *
+ * ```typescript
+ * import { extractDesignTokens } from '@tangle-network/browser-agent-driver'
+ *
+ * const { tokens } = await extractDesignTokens({ url: 'https://stripe.com' })
+ * console.log(tokens.colors.filter(c => c.cluster === 'primary'))
+ * console.log(tokens.typography.families)
+ * console.log(tokens.brand)
+ * ```
+ */
+/**
+ * Reduce a candidate asset filename to a safe, separator-free basename so a
+ * DOM-controlled value (e.g. a hostile `@font-face` family `../../../tmp/evil`)
+ * can never escape the output directory when joined to it. Strips any path
+ * components and leading dots (no traversal, no dotfiles); returns `fallback`
+ * when nothing usable remains.
+ */
+export declare function safeAssetFilename(raw: string, fallback: string): string;
+export declare function extractDesignTokens(opts: ExtractDesignTokensOptions): Promise<ExtractionResult>;
+export declare function createZipBundle(outputDir: string, tokens: DesignTokens): Promise<string>;
+//# sourceMappingURL=extract.d.ts.map

package/dist/design/audit/tokens/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../../../src/design/audit/tokens/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAoJ,MAAM,mBAAmB,CAAA;AACvM,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAiuBjE,MAAM,WAAW,0BAA0B;IACzC,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAClE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAChK;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC;;;;OAIG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAA;CAChC;AAED;;;;;;;;;;;;GAYG;AACH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+RrG;AAMD,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9F"}