@leonidstern/census 0.0.0-stage → 0.2.0

package/dist/color.d.ts

@@ -0,0 +1,9 @@
+/** A CSS color as computed ("rgb(1, 2, 3)", "rgba(1, 2, 3, 0.5)", "color(srgb 0.1 0.2 0.3 / 0.5)") as [r, g, b, a] in 0-255 and 0-1; null when it can't be read. */
+export declare function parseColor(css: string): [number, number, number, number] | null;
+/** A read that asks for many colors hands over its own hidden element: the probe stays in it (one append) until the read hands back null. */
+export declare function colorProbe(host: Element | null): void;
+/** `top` drawn over `under` (opaque): what shows. */
+export declare function over(top: [number, number, number, number], under: [number, number, number, number]): [number, number, number, number];
+/** WCAG contrast ratio of two opaque colors, 1 (none) to 21. */
+export declare function contrast(a: [number, number, number, number], b: [number, number, number, number]): number;
+/** A color as #rrggbb, or #rrggbbaa when see-through. */

package/dist/diff.d.ts

@@ -0,0 +1,15 @@
+import type { Census, CensusItem } from "./census";
+/**
+ * Of two reads of one page with no change between them, the elements that differ: they change on their own (a price,
+ * a clock, a depth bar). Hover and pressed colors aren't compared: the capture's second read doesn't force them.
+ */
+export declare function changesOnItsOwn(a: CensusItem[], b: CensusItem[]): CensusItem[];
+/**
+ * What changed between two censuses taken with rules.items. Sections: elements whose look changed (each property
+ * before→after), elements that came or went, values the page shows now or no longer (with OFF and near), parts with
+ * a new or lost look, and layout problems that appeared or were fixed. Places that only moved are counted.
+ * What changes on its own (live data) is left out of the element lists: what differs between each capture and its
+ * own second read (`again`, which the capture takes by itself), and between `before` and `live` (a second capture
+ * taken before the change), when given. Moves are said grouped: where, how far, and which elements.
+ */
+export declare function diffCensus(before: Census, after: Census, max?: number, live?: Census): string[];

package/dist/findings.d.ts

@@ -0,0 +1,79 @@
+import type { Census, CensusGroup } from "./census";
+export type Level = "rule" | "accessibility" | "max";
+export type Finding = {
+    /** check|subject: no counts or boxes, so the same finding has the same id in two captures */
+    id: string;
+    check: string;
+    level: Level;
+    /** the line, without places */
+    key: string;
+    n: number;
+    note?: string;
+    at: string[];
+    /** the elements it covers, so diff can say what it now also covers */
+    values?: string[];
+    /** computed styles can't decide (a gradient behind words, a ring set by a script): never fails a build */
+    unsure?: boolean;
+};
+/** A check's level and its number, from rules.checks: "off", "rule", a number, or ["rule", number]. */
+export type CheckSetting = "off" | "rule" | number | ["rule", number];
+/** Every check, the level it reports at, and the preset that turns it on (none: on whenever rules.json feeds it). */
+export declare const CHECKS: Record<string, {
+    level: Level;
+    preset?: string;
+    what: string;
+}>;
+export declare const PRESETS: string[];
+/**
+ * How many distinct values a group may hold before the max check says so. Flat: a design system is finite whether it
+ * draws a login box or a trading terminal, and a cap that grows with the page excuses the pages that need it most.
+ * Not every group gets one — states, used and field count occurrences of something that is already a finding, so a
+ * cap there would say the same thing twice.
+ */
+export declare const MAX_DEFAULTS: Record<string, number>;
+/** What rules.json can say about checks. The whole StyleRules is accepted; only these fields are read. */
+type CheckRules = {
+    extends?: string | string[];
+    checks?: Record<string, CheckSetting>;
+    max?: Record<string, number | "off">;
+} & Partial<Record<"colors" | "type" | "radii" | "shadows" | "parts", unknown>>;
+/**
+ * The level a check reports at (null: off) and its number. The rule checks are on whenever rules.json gives what they
+ * compare against; the accessibility checks with `extends: "recommended@1"` or when rules.checks names them. The max
+ * check is on with `extends: "best-practice@1"`, with a `max` of your own, and by default when rules.json gives no
+ * values at all — a first run with no file still says something, which is the whole point of it.
+ */
+export declare function checkSetting(rules: CheckRules, check: string): {
+    level: Level | null;
+    n?: number;
+};
+/** Whether rules ask for the accessibility or max checks (a preset, a check by name, or no values to check against). */
+export declare const asksChecks: (rules: CheckRules) => boolean;
+/**
+ * The groups holding more distinct values than their max, rarest values first — those are both the easiest to drop
+ * and the likeliest to be accidents. One finding per group, so a diff says a group went over or came back under
+ * instead of churning an id every time the tail moves. `groups` are counted whole, trimmed rows included.
+ */
+export declare function maxFindings(groups: CensusGroup[], rules: CheckRules, name?: number): Finding[];
+/**
+ * The accessibility findings as lines, unsure ones last, then the max findings, each with the values to drop under it.
+ * Rule findings are already said OFF in their own groups.
+ */
+export declare function findingLines(c: Census, max?: number): string[];
+/**
+ * Findings of several pages as one: the same id is one finding, counts added, a place from each page. Max findings
+ * are left out — adding two pages' counts says nothing, since the same color on both is one value. mergeCensus
+ * counts them again off the merged groups, which is the number that was meant: the system across all the pages.
+ */
+export declare function mergeFindings(pages: Record<string, Census>): Finding[] | undefined;
+/**
+ * What changed in the findings between two captures. The lines say accessibility findings new and fixed (a value new
+ * off the system is already said by diff's values); both levels' new findings are returned, for --fail-on.
+ */
+export declare function diffFindings(before: Census, after: Census, max?: number): {
+    lines: string[];
+    newRules: Finding[];
+    newAccessibility: Finding[];
+    maxWorse: Finding[];
+};
+export {};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { censusLines, layoutLines, mergeCensus, partOf, shadowLayers, specificity, stateOf, fontDiff, styleData, styleLines, nameOf, ownId, behind } from "./census";
+export type { Census, CensusGroup, CensusItem, CensusLook, CensusRow, StyleRules } from "./census";
+export { changesOnItsOwn, diffCensus } from "./diff";
+export { contrast, over, parseColor } from "./color";
+export { asksChecks, checkSetting, CHECKS, diffFindings, findingLines, maxFindings, MAX_DEFAULTS, mergeFindings, PRESETS } from "./findings";
+export type { CheckSetting, Finding, Level } from "./findings";

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@leonidstern/census",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Eyes for a blind agent: a live web page's styles as text an AI can check, by your design system's own words.",
+  "keywords": [
+    "design-system",
+    "visual-regression",
+    "accessibility",
+    "wcag",
+    "css",
+    "agent",
+    "llm",
+    "playwright",
+    "ci"
+  ],
+  "homepage": "https://github.com/LeonidStern/census#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LeonidStern/census.git"
+  },
+  "bugs": {
+    "url": "https://github.com/LeonidStern/census/issues"
+  },
+  "author": "Leonid Stern",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "census": "cli/census.mjs"
+  },
+  "main": "dist/census.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "cli",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "esbuild src/browser.ts --bundle --format=iife --outfile=dist/census.js --log-level=warning && esbuild src/index.ts --bundle --format=esm --outfile=dist/census.mjs --log-level=warning && tsc -p .",
+    "check": "tsc -p . --noEmit",
+    "test": "npm run build && node test/census-test.mjs",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "esbuild": "0.25.12",
+    "svelte": "^5.57.3",
+    "typescript": "5.6.3",
+    "vue": "3.5"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/census.mjs"
+    },
+    "./playwright": "./cli/playwright.mjs",
+    "./census.js": "./dist/census.js"
+  }
+}