@siyahi/tools 0.0.0-stage → 0.1.0-next.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jatin Bansal
+
+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/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @siyahi/tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Checks for pages built on [`@siyahi/ui`](https://www.npmjs.com/package/@siyahi/ui).
+Kept apart from the UI package so installing the UI does not pull in Playwright.
+
+## Lint plugin
+
+An [oxlint](https://oxc.rs) JS plugin, `siyahi`. Every rule runs only in files
+that import `@siyahi/ui`.
+
+| Rule                          | Rejects                                                                                                             |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `siyahi/no-color-literal`     | hex, `rgb()`, `hsl()`, `oklch()` and other colour literals in strings                                               |
+| `siyahi/no-scheme-variant`    | `dark:` and `light:` Tailwind variants                                                                              |
+| `siyahi/no-numeric-font-size` | `fontSize: 13`, `fontSize="12px"`                                                                                   |
+| `siyahi/no-chart-theme-map`   | a chart config `theme: { light, dark }` map; shadcn's chart applies the dark half only under a `.dark` class        |
+| `siyahi/no-raw-colors`        | Tailwind palette colours such as `bg-pink-500` ([@shadcn/lint](https://github.com/shadcn-ui/lint))                  |
+| `siyahi/no-arbitrary-values`  | arbitrary values such as `text-[13px]`, `w-[37px]`, `bg-[#fff]` ([@shadcn/lint](https://github.com/shadcn-ui/lint)) |
+
+```json
+{
+  "jsPlugins": ["@siyahi/tools/lint"],
+  "settings": { "shadcn": { "ui": "@siyahi/ui", "themeImports": ["^@siyahi/ui/"] } },
+  "rules": { "siyahi/no-color-literal": "error" }
+}
+```
+
+A Vite+ or ESLint config can spread every rule at once:
+`import { recommended } from "@siyahi/tools/lint"`.
+
+## siyahi-shots
+
+```sh
+npx siyahi-shots http://localhost:5173/#/page [more URLs] [--out shots] [--gutter 16] [--font Geist] [--chrome '[data-slot="sidebar"]']
+```
+
+Renders each URL in Chromium at 1920 and 390 pixels wide, light and dark, and
+writes one full-page PNG per mode to `shots/`. It fails when visible text or a
+card comes closer than `--gutter` pixels to either edge, when the page scrolls
+sideways, or when the body font is not a loaded `--font` family. Content that
+scrolls sideways inside its own box is exempt from the gutter, and so is
+anything inside `--chrome` (by default the shadcn sidebar, which sits flush to
+the edge by design). The font default, Geist, is Siyahi's; pass another family
+for other pages. Run `npx playwright install chromium` once.
+
+## siyahi-contrast
+
+```sh
+npx siyahi-contrast path/to/theme.css
+```
+
+Reads the light `:root` block and the `@variant dark { … }` block inside it.
+Every checked token must be set in both; dark never borrows a light value. It
+fails unless text colours reach 4.5:1 on the canvas, the card and their own
+fills, chart colours reach 3:1 against the card and against the slots next to
+them, and every chart colour sits inside sRGB. Slots two apart share a
+lightness and are told apart by hue, so series take slots in order.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,51 @@
+# Third-party notices
+
+Siyahi is MIT licensed (see `LICENSE`). It contains code copied from the
+projects below, each under the MIT licence. Every copied file starts with a
+header naming its registry item, origin URL, licence and the SHA-256 of the
+file as copied; `packages/ui/registry.lock.json` lists them all and
+`pnpm generate:check` fails if a copied file is not named here.
+
+## Copied into `@siyahi/ui`
+
+| What                                                                  | Where in the package                                     | Origin                                                                                                                                                                                                                                                                                                      | Licence                                                                             |
+| --------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| shadcn/ui core components (installed with `shadcn add`, never edited) | `src/components/ui/*`, `src/hooks/use-mobile.ts`         | https://github.com/shadcn-ui/ui                                                                                                                                                                                                                                                                             | MIT, Copyright (c) 2023 shadcn                                                      |
+| shadcn `tailwind.css` (variants and utilities the components use)     | `styles/shadcn.css`                                      | https://github.com/shadcn-ui/ui/tree/main/packages/shadcn                                                                                                                                                                                                                                                   | MIT, Copyright (c) 2023 shadcn                                                      |
+| shadcn block `sidebar-07`                                             | `src/components/registry/sidebar-07/*`                   | https://ui.shadcn.com/r/styles/base-vega/sidebar-07.json                                                                                                                                                                                                                                                    | MIT, Copyright (c) 2023 shadcn                                                      |
+| shadcn block `dashboard-01`, `SectionCards` only                      | `src/components/registry/dashboard-01/section-cards.tsx` | https://ui.shadcn.com/r/styles/base-vega/dashboard-01.json                                                                                                                                                                                                                                                  | MIT, Copyright (c) 2023 shadcn                                                      |
+| Heatmaps: calendar, weekday by hour, status timeline                  | `src/components/registry/heatmap/*`                      | https://shadcn-heatmap.pages.dev/r/calendar-heatmap.json, https://shadcn-heatmap.pages.dev/r/weekday-heatmap.json, https://shadcn-heatmap.pages.dev/r/status-heatmap.json (source: https://github.com/rutopio/shadcn-heatmap)                                                                               | MIT, Copyright (c) 2026 ChingRu                                                     |
+| niko-table data table on TanStack Table                               | `src/components/registry/niko-table/*`                   | https://niko-table.com/r/data-table.json, https://niko-table.com/r/data-table-core.json, https://niko-table.com/r/data-table-ui.json, https://niko-table.com/r/data-table-faceted-filter.json, https://niko-table.com/r/data-table-column-sort.json (source: https://github.com/Semkoo/niko-table-registry) | MIT, Copyright (c) 2025 Semir N.; original work Copyright (c) 2025 WebDevSimplified |
+| dashboardcn ranked list (`BarList`)                                   | `src/components/registry/dashboardcn/bar-list.tsx`       | https://dashboardcn.com/r/bar-list.json (source: https://github.com/NoahGdev/dashboardcn)                                                                                                                                                                                                                   | MIT, Copyright (c) 2026 dashboardcn contributors                                    |
+
+## Runtime dependencies with attribution terms
+
+| Package                                                         | Licence                                            | Note                                                                                                                                      |
+| --------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `lightweight-charts` (TradingView)                              | Apache-2.0                                         | `PriceChart` keeps the library's attribution logo on by default; see https://github.com/tradingview/lightweight-charts/blob/master/NOTICE |
+| `@fontsource-variable/geist`, `@fontsource-variable/geist-mono` | SIL Open Font License 1.1 (fonts), MIT (packaging) | Geist by Vercel                                                                                                                           |
+
+Every other dependency is installed from npm under its own licence and is not
+copied into this repository.
+
+## The MIT licence text
+
+Each MIT notice above carries this permission text:
+
+> 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/color.mjs

@@ -0,0 +1,103 @@
+// @ts-check
+// OKLCH to sRGB and WCAG 2 contrast, so the theme can be checked without a
+// browser. Formulas from Björn Ottosson's OKLab and the WCAG 2.2 definition
+// of relative luminance.
+
+/** @typedef {{ l: number, c: number, h: number, alpha: number }} Oklch */
+
+const OKLCH = /^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)(?:deg)?\s*(?:\/\s*([\d.]+)(%?))?\s*\)$/i;
+
+/**
+ * Parses a CSS `oklch()` value. Returns null for anything else.
+ * @param {string} value
+ * @returns {Oklch | null}
+ */
+export function parseOklch(value) {
+  const m = OKLCH.exec(value.trim());
+  if (!m) return null;
+  const l = Number(m[1]) / (m[2] ? 100 : 1);
+  const alpha = m[5] === undefined ? 1 : Number(m[5]) / (m[6] ? 100 : 1);
+  return { l, c: Number(m[3]), h: Number(m[4]), alpha };
+}
+
+/**
+ * Linear-light sRGB channels of an OKLCH colour, before any clipping. A channel
+ * outside 0..1 means the colour is outside sRGB.
+ * @param {Oklch} color
+ * @returns {[number, number, number]}
+ */
+function linearSrgb({ l, c, h }) {
+  const hr = (h * Math.PI) / 180;
+  const a = c * Math.cos(hr);
+  const b = c * Math.sin(hr);
+  const lms = [
+    (l + 0.3963377774 * a + 0.2158037573 * b) ** 3,
+    (l - 0.1055613458 * a - 0.0638541728 * b) ** 3,
+    (l - 0.0894841775 * a - 1.291485548 * b) ** 3,
+  ];
+  const [cl = 0, cm = 0, cs = 0] = lms;
+  return [
+    4.0767416621 * cl - 3.3077115913 * cm + 0.2309699292 * cs,
+    -1.2684380046 * cl + 2.6097574011 * cm - 0.3413193965 * cs,
+    -0.0041960863 * cl - 0.7034186147 * cm + 1.707614701 * cs,
+  ];
+}
+
+/**
+ * Whether a colour is inside sRGB, so every screen paints the value as scored.
+ * @param {Oklch} color
+ */
+export function inSrgb(color) {
+  return linearSrgb(color).every((v) => v >= -1e-4 && v <= 1 + 1e-4);
+}
+
+/**
+ * Converts OKLCH to gamma-encoded sRGB channels in 0..1, clipped to the gamut.
+ * @param {Oklch} color
+ * @returns {[number, number, number]}
+ */
+export function oklchToSrgb(color) {
+  const [r, g, bl] = linearSrgb(color).map((v) => {
+    const x = Math.min(1, Math.max(0, v));
+    return x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055;
+  });
+  return [r ?? 0, g ?? 0, bl ?? 0];
+}
+
+/** @param {number} v */
+const lin = (v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+
+/**
+ * WCAG relative luminance of gamma-encoded sRGB channels in 0..1.
+ * @param {[number, number, number]} rgb
+ * @returns {number}
+ */
+export function luminance([r, g, b]) {
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/**
+ * WCAG contrast ratio between two opaque OKLCH colours.
+ * @param {Oklch} a
+ * @param {Oklch} b
+ * @returns {number}
+ */
+export function contrast(a, b) {
+  const [hi, lo] = [luminance(oklchToSrgb(a)), luminance(oklchToSrgb(b))].toSorted((x, y) => y - x);
+  return ((hi ?? 0) + 0.05) / ((lo ?? 0) + 0.05);
+}
+
+/**
+ * Hex form of an OKLCH colour, for messages and tests.
+ * @param {Oklch} color
+ * @returns {string}
+ */
+export function toHex(color) {
+  return `#${oklchToSrgb(color)
+    .map((v) =>
+      Math.round(v * 255)
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("")}`;
+}

package/contrast.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// @ts-check
+// Fails when a theme colour is too faint to read: 4.5:1 for text on the
+// canvas and the card and for a foreground on its own fill, 3:1 for chart
+// colours against the card and against the slot next to them. Slots two apart
+// share a lightness and are told apart by hue, so they are not compared. Chart
+// colours must also sit inside sRGB, so the browser paints what was scored.
+//
+//   siyahi-contrast styles/siyahi.css
+import { readFileSync, realpathSync } from "node:fs";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { contrast, inSrgb, parseOklch, toHex } from "./color.mjs";
+import { readTheme } from "./theme.mjs";
+
+/** @typedef {import("./theme.mjs").Theme} Theme */
+/** @typedef {{ scheme: "light" | "dark", fg: string, bg: string, ratio: number, min: number }} Check */
+
+const TEXT = ["foreground", "muted-foreground", "positive", "negative", "warning", "link", "destructive"];
+const SURFACES = ["background", "card"];
+const FILLS = [
+  ["card-foreground", "card"],
+  ["popover-foreground", "popover"],
+  ["primary-foreground", "primary"],
+  ["secondary-foreground", "secondary"],
+  ["accent-foreground", "accent"],
+  ["positive-foreground", "positive"],
+  ["negative-foreground", "negative"],
+  ["warning-foreground", "warning"],
+  ["sidebar-foreground", "sidebar"],
+];
+const CHARTS = ["chart-1", "chart-2", "chart-3", "chart-4", "chart-5"];
+
+/**
+ * @param {Theme} theme
+ * @returns {Check[]}
+ */
+export function checkContrast(theme) {
+  /** @type {Check[]} */
+  const checks = [];
+  for (const scheme of /** @type {const} */ (["light", "dark"])) {
+    const vars = theme[scheme];
+    const color = (/** @type {string} */ name) => {
+      const value = vars[name];
+      if (value === undefined) throw new Error(`${scheme}: --${name} is not set in the ${scheme} block`);
+      const parsed = parseOklch(value);
+      if (!parsed) throw new Error(`${scheme}: --${name} is "${value}", not an oklch() colour`);
+      if (parsed.alpha < 1) throw new Error(`${scheme}: --${name} is translucent; contrast needs an opaque colour`);
+      return parsed;
+    };
+    const pair = (/** @type {string} */ fg, /** @type {string} */ bg, /** @type {number} */ min) =>
+      checks.push({ scheme, fg, bg, ratio: contrast(color(fg), color(bg)), min });
+    for (const fg of TEXT) for (const bg of SURFACES) pair(fg, bg, 4.5);
+    for (const [fg, bg] of FILLS) pair(/** @type {string} */ (fg), /** @type {string} */ (bg), 4.5);
+    CHARTS.forEach((chart, i) => {
+      pair(chart, "card", 3);
+      const next = CHARTS[i + 1];
+      if (next) pair(chart, next, 3);
+    });
+  }
+  return checks;
+}
+
+/**
+ * Chart colours outside sRGB, named for the error message.
+ * @param {Theme} theme
+ * @returns {string[]}
+ */
+export function checkGamut(theme) {
+  return /** @type {const} */ (["light", "dark"]).flatMap((scheme) =>
+    CHARTS.filter((name) => {
+      const parsed = parseOklch(theme[scheme][name] ?? "");
+      return parsed !== null && !inSrgb(parsed);
+    }).map((name) => `${scheme} --${name} ${theme[scheme][name]} is outside sRGB; lower its chroma`),
+  );
+}
+
+/**
+ * @param {Theme} theme
+ * @param {Check} check
+ */
+function describe(theme, check) {
+  const hex = (/** @type {string} */ name) => {
+    const parsed = parseOklch(theme[check.scheme][name] ?? "");
+    return parsed ? toHex(parsed) : "?";
+  };
+  return `${check.scheme.padEnd(5)} --${check.fg} ${hex(check.fg)} on --${check.bg} ${hex(check.bg)}: ${check.ratio.toFixed(2)}:1 (needs ${check.min}:1)`;
+}
+
+// Run as a command, not when imported. A package manager starts this file
+// through a bin link, so compare real paths.
+const invoked = process.argv[1] ? pathToFileURL(realpathSync(process.argv[1])).href : "";
+if (import.meta.url === invoked) {
+  const file = process.argv[2];
+  if (!file) {
+    console.error("usage: siyahi-contrast <theme.css>");
+    process.exit(2);
+  }
+  const theme = readTheme(readFileSync(file, "utf8"));
+  const checks = checkContrast(theme);
+  const failures = checks.filter((c) => c.ratio < c.min);
+  const outOfGamut = checkGamut(theme);
+  for (const check of failures) console.error(`FAIL ${describe(theme, check)}`);
+  for (const problem of outOfGamut) console.error(`FAIL ${problem}`);
+  const weakest = checks.toSorted((a, b) => a.ratio / a.min - b.ratio / b.min)[0];
+  console.log(
+    `contrast: ${checks.length - failures.length}/${checks.length} pairs pass` +
+      (weakest ? `; closest: ${describe(theme, weakest)}` : ""),
+  );
+  process.exit(failures.length || outOfGamut.length ? 1 : 0);
+}

package/lint/index.mjs

@@ -0,0 +1,160 @@
+// @ts-check
+// Oxlint (and ESLint) plugin `siyahi`. Every rule runs only in files that
+// import `@siyahi/ui`, so pages written before Siyahi stay outside the rules
+// without any configuration. Two rules come from @shadcn/lint as they are;
+// the other three cover what it does not check.
+import { plugin as shadcn } from "@shadcn/lint";
+
+/** @typedef {{ sourceCode: { text: string }, report: (problem: { node: unknown, message: string }) => void }} Context */
+/** @typedef {{ meta?: object, create: (context: any) => Record<string, (node: any) => void> }} Rule */
+
+const IMPORTS_SIYAHI = /(?:\bfrom\s*|\bimport\s*\(?\s*)["']@siyahi\/ui(?:\/[^"']*)?["']/;
+
+/**
+ * @param {Rule} rule
+ * @returns {Rule}
+ */
+function scoped(rule) {
+  return {
+    ...rule,
+    create: (context) => (IMPORTS_SIYAHI.test(context.sourceCode.text) ? rule.create(context) : {}),
+  };
+}
+
+/**
+ * Calls `check` with the text of every string literal and template chunk,
+ * skipping import and export paths.
+ * @param {(node: unknown, text: string) => void} check
+ */
+function eachString(check) {
+  return {
+    /** @param {{ value: unknown, parent?: { type: string } }} node */
+    Literal(node) {
+      const parent = node.parent?.type ?? "";
+      if (typeof node.value !== "string" || /^(Import|Export)/.test(parent)) return;
+      check(node, node.value);
+    },
+    /** @param {{ value: { cooked?: string | null, raw: string } }} node */
+    TemplateElement(node) {
+      check(node, node.value.cooked ?? node.value.raw);
+    },
+  };
+}
+
+const HEX = /(?:^|[^\w&#])#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})(?![\w-])/i;
+const COLOR_FUNCTION = /\b(?:rgba?|hsla?|hwb|oklch|oklab|lab|lch|color)\(/i;
+
+/** @type {Rule} */
+const noColorLiteral = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow hex, rgb(), hsl() and oklch() colour literals; use a theme token." },
+  },
+  create: (/** @type {Context} */ context) =>
+    eachString((node, text) => {
+      if (HEX.test(text) || COLOR_FUNCTION.test(text)) {
+        context.report({
+          node,
+          message:
+            "Colour literal. Use a theme token: a class such as text-positive or bg-card, or var(--chart-1) where a library needs a value.",
+        });
+      }
+    }),
+};
+
+const SCHEME_VARIANT = /(?:^|[\s:])(dark|light):(?=[\w[!-])/;
+
+/** @type {Rule} */
+const noSchemeVariant = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow dark: and light: variants; theme tokens already change with the scheme." },
+  },
+  create: (/** @type {Context} */ context) =>
+    eachString((node, text) => {
+      const m = SCHEME_VARIANT.exec(text);
+      if (m) {
+        context.report({
+          node,
+          message: `"${m[1]}:" variant. Theme tokens follow the device's scheme on their own; use the token, not a per-scheme class.`,
+        });
+      }
+    }),
+};
+
+/**
+ * @param {{ type: string, value?: unknown, expression?: { type: string, value?: unknown } } | null | undefined} value
+ */
+function isNumericSize(value) {
+  const literal = value?.type === "JSXExpressionContainer" ? value.expression : value;
+  if (literal?.type !== "Literal") return false;
+  return typeof literal.value === "number" || (typeof literal.value === "string" && /^\d/.test(literal.value));
+}
+
+/** @type {Rule} */
+const noNumericFontSize = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow numeric font sizes; use the type scale (text-xs to text-2xl)." },
+  },
+  create: (/** @type {Context} */ context) => {
+    const message = "Numeric font size. Use the type scale: a text-xs to text-2xl class on the element.";
+    return {
+      /** @param {{ key: { type: string, name?: string, value?: unknown }, value: any }} node */
+      Property(node) {
+        const key = node.key.type === "Identifier" ? node.key.name : node.key.value;
+        if (key === "fontSize" && isNumericSize(node.value)) context.report({ node, message });
+      },
+      /** @param {{ name: { name?: string }, value: any }} node */
+      JSXAttribute(node) {
+        if (node.name.name === "fontSize" && isNumericSize(node.value)) context.report({ node, message });
+      },
+    };
+  },
+};
+
+/** @type {Rule} */
+const noChartThemeMap = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow per-scheme ChartConfig theme maps; use color: var(--chart-n)." },
+  },
+  // shadcn's ChartStyle writes a theme map's dark entry under a `.dark` class,
+  // which Siyahi never sets, so the light entry would win in dark mode.
+  create: (/** @type {Context} */ context) => ({
+    /** @param {{ key: { type: string, name?: string, value?: unknown }, value: { type: string, properties?: { key?: { name?: string, value?: unknown } }[] } }} node */
+    Property(node) {
+      const key = node.key.type === "Identifier" ? node.key.name : node.key.value;
+      if (key !== "theme" || node.value.type !== "ObjectExpression") return;
+      const keys = new Set((node.value.properties ?? []).map((p) => p.key?.name ?? p.key?.value));
+      if (keys.has("light") || keys.has("dark")) {
+        context.report({
+          node,
+          message:
+            'Chart theme map. Its dark entry only applies under a .dark class, which Siyahi never sets. Use color: "var(--chart-1)"; the variable already follows the scheme.',
+        });
+      }
+    },
+  }),
+};
+
+/** @type {{ meta: { name: string }, rules: Record<string, Rule> }} */
+const plugin = {
+  meta: { name: "siyahi" },
+  rules: {
+    "no-color-literal": scoped(noColorLiteral),
+    "no-scheme-variant": scoped(noSchemeVariant),
+    "no-numeric-font-size": scoped(noNumericFontSize),
+    "no-chart-theme-map": scoped(noChartThemeMap),
+    "no-raw-colors": scoped(shadcn.rules["no-raw-colors"]),
+    "no-arbitrary-values": scoped(shadcn.rules["no-arbitrary-values"]),
+  },
+};
+
+/**
+ * Every rule at "error", for a Vite+ or ESLint config to spread.
+ * @type {Record<string, "error">}
+ */
+export const recommended = Object.fromEntries(Object.keys(plugin.rules).map((name) => [`siyahi/${name}`, "error"]));
+
+export default plugin;

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@siyahi/tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-next.3",
+  "description": "Checks for Siyahi pages: a lint plugin, a theme contrast check and a screenshot script.",
+  "homepage": "https://siyahi.jatinbansal.com",
+  "license": "MIT",
+  "author": "Jatin Bansal",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jatinbansal1998/siyahi.git",
+    "directory": "packages/tools"
+  },
+  "bin": {
+    "siyahi-contrast": "./contrast.mjs",
+    "siyahi-shots": "./shots.mjs"
+  },
+  "files": [
+    "*.mjs",
+    "lint/*.mjs",
+    "types",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./lint": {
+      "types": "./types/lint/index.d.mts",
+      "default": "./lint/index.mjs"
+    },
+    "./contrast": {
+      "types": "./types/contrast.d.mts",
+      "default": "./contrast.mjs"
+    },
+    "./theme": {
+      "types": "./types/theme.d.mts",
+      "default": "./theme.mjs"
+    }
+  },
+  "dependencies": {
+    "@shadcn/lint": "0.2.3",
+    "playwright": "^1.64.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "oxlint": "^1.88.0",
+    "typescript": "7.0.2",
+    "vite-plus": "1.3.0"
+  },
+  "peerDependencies": {
+    "oxlint": ">=1.80.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/shots.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// @ts-check
+// Renders pages in Playwright's Chromium at 1920 and 390 wide, light and dark,
+// checks the layout rules every Siyahi page keeps, and writes one full-page
+// PNG per page and mode.
+//
+//   siyahi-shots <url>... [--out shots] [--gutter 16] [--font Geist]
+//                [--chrome '[data-slot="sidebar"]']
+//
+// Checks: a gutter of at least --gutter px on both sides of visible text and
+// cards, no sideways document scroll (also with a classic scrollbar taking its
+// width), and --font as the loaded body font. Exempt from the gutter: content
+// inside a box that scrolls sideways, and anything inside --chrome, which by
+// default is only the shadcn sidebar, flush to the edge by design. The font
+// default is Siyahi's; other pages pass their own family.
+//
+// The capture first grows the viewport to the page's height and waits, so
+// charts that redraw on resize settle before the picture is taken; a
+// stitched full-page capture catches them mid-animation.
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { chromium } from "playwright";
+
+/** @typedef {{ name: string, width: number, height: number, dark: boolean }} Mode */
+/** @typedef {{ gutterLeft: number | null, gutterRight: number | null, overflow: number, overflowWithScrollbar: number, font: string, fontLoaded: boolean, docHeight: number, h1: string | null }} Probe */
+
+/** @type {Mode[]} */
+const MODES = [
+  { name: "1920-light", width: 1920, height: 1080, dark: false },
+  { name: "1920-dark", width: 1920, height: 1080, dark: true },
+  { name: "390-light", width: 390, height: 844, dark: false },
+  { name: "390-dark", width: 390, height: 844, dark: true },
+];
+const MAX_HEIGHT = 16000;
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    out: { type: "string", default: "shots" },
+    gutter: { type: "string", default: "16" },
+    font: { type: "string", default: "Geist" },
+    chrome: { type: "string", default: '[data-slot="sidebar"]' },
+  },
+});
+if (positionals.length === 0) {
+  console.error("usage: siyahi-shots <url>... [--out shots] [--gutter 16] [--font Geist] [--chrome <selector>]");
+  process.exit(2);
+}
+const outDir = path.resolve(values.out);
+const minGutter = Number(values.gutter);
+mkdirSync(outDir, { recursive: true });
+
+/** @param {string} url */
+function slugOf(url) {
+  const u = new URL(url);
+  const slug = `${u.pathname}${u.hash}`.replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "");
+  return slug || "index";
+}
+
+// Runs in the page. Kept as a string so the bundled code is exactly what runs.
+const PROBE = `((chrome) => {
+  const de = document.documentElement;
+  const scrollsSideways = (el) => {
+    for (let e = el.parentElement; e; e = e.parentElement) {
+      const o = getComputedStyle(e).overflowX;
+      if ((o === "auto" || o === "scroll") && e.scrollWidth > e.clientWidth) return true;
+    }
+    return false;
+  };
+  const visible = [...document.querySelectorAll('h1,h2,h3,h4,p,li,td,th,[data-slot="card"]')].filter((el) => {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 || r.height === 0) return false;
+    if (r.right <= 0 || r.left >= de.clientWidth) return false;
+    if (el.closest(chrome)) return false;
+    const s = getComputedStyle(el);
+    return s.visibility !== "hidden" && !scrollsSideways(el);
+  });
+  const lefts = visible.map((el) => el.getBoundingClientRect().left);
+  const rights = visible.map((el) => de.clientWidth - el.getBoundingClientRect().right);
+  const overflow = de.scrollWidth - de.clientWidth;
+  const prev = de.style.overflowY;
+  de.style.overflowY = "scroll";
+  void document.body.offsetHeight;
+  const overflowWithScrollbar = de.scrollWidth - de.clientWidth;
+  de.style.overflowY = prev;
+  const font = getComputedStyle(document.body).fontFamily;
+  const first = font.split(",")[0].trim().replace(/^["']|["']$/g, "");
+  const h1 = document.querySelector("h1");
+  return {
+    gutterLeft: lefts.length ? Math.round(Math.min(...lefts)) : null,
+    gutterRight: rights.length ? Math.round(Math.min(...rights)) : null,
+    overflow,
+    overflowWithScrollbar,
+    font: first,
+    fontLoaded: document.fonts.check('16px "' + first + '"') && [...document.fonts].some((f) => f.family.replace(/["']/g, "") === first && f.status === "loaded"),
+    docHeight: de.scrollHeight,
+    h1: h1 ? h1.textContent.trim().slice(0, 60) : null,
+  };
+})(${JSON.stringify(values.chrome)})`;
+
+const SETTLE = `(async () => {
+  await document.fonts.ready;
+  await Promise.all([...document.images].map((image) => image.decode().catch(() => {})));
+  await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+})()`;
+
+/**
+ * @param {import("playwright").Browser} browser
+ * @param {string} url
+ * @param {Mode} mode
+ * @returns {Promise<{ probe: Probe, file: string }>}
+ */
+async function shoot(browser, url, mode) {
+  const context = await browser.newContext({
+    viewport: { width: mode.width, height: mode.height },
+    colorScheme: mode.dark ? "dark" : "light",
+  });
+  const page = await context.newPage();
+  await page.goto(url, { waitUntil: "networkidle" });
+  await page.evaluate(SETTLE);
+  /** @type {Probe} */
+  const probe = await page.evaluate(PROBE);
+  await page.setViewportSize({
+    width: mode.width,
+    height: Math.min(Math.max(probe.docHeight, mode.height), MAX_HEIGHT),
+  });
+  await page.waitForTimeout(1500);
+  await page.evaluate(SETTLE);
+  const file = path.join(outDir, `${slugOf(url)}-${mode.name}.png`);
+  await page.screenshot({ path: file });
+  await context.close();
+  return { probe, file };
+}
+
+/**
+ * @param {Probe} p
+ * @returns {string[]}
+ */
+function problemsOf(p) {
+  const problems = [];
+  if (p.gutterLeft !== null && p.gutterLeft < minGutter)
+    problems.push(`left gutter is ${p.gutterLeft}px, under ${minGutter}px`);
+  if (p.gutterRight !== null && p.gutterRight < minGutter)
+    problems.push(`right gutter is ${p.gutterRight}px, under ${minGutter}px`);
+  if (p.overflow > 0) problems.push(`document scrolls sideways by ${p.overflow}px`);
+  if (p.overflowWithScrollbar > 0)
+    problems.push(`scrolls sideways by ${p.overflowWithScrollbar}px once a scrollbar takes its width`);
+  if (!p.font.startsWith(values.font)) problems.push(`body font is ${p.font}, not ${values.font}`);
+  else if (!p.fontLoaded) problems.push(`${p.font} is named but never loaded`);
+  if (p.docHeight > MAX_HEIGHT) problems.push(`page is ${p.docHeight}px tall; the shot stops at ${MAX_HEIGHT}px`);
+  return problems;
+}
+
+const browser = await chromium.launch();
+let failed = false;
+for (const url of positionals) {
+  for (const mode of MODES) {
+    const { probe, file } = await shoot(browser, url, mode);
+    const problems = problemsOf(probe);
+    failed ||= problems.length > 0;
+    console.log(
+      `${problems.length ? "FAIL" : "ok  "} ${mode.name.padEnd(10)} gutter=${probe.gutterLeft}/${probe.gutterRight} ` +
+        `overflow=${probe.overflow}/${probe.overflowWithScrollbar} font=${probe.font} h1=${JSON.stringify(probe.h1)} ${file}`,
+    );
+    for (const problem of problems) console.log(`     ${problem}`);
+  }
+}
+await browser.close();
+process.exit(failed ? 1 : 0);

package/theme.mjs

@@ -0,0 +1,50 @@
+// @ts-check
+// Reads the custom properties of a Siyahi theme file: the top-level `:root`
+// block for light, and the `@variant dark { … }` block nested inside it for
+// dark. Dark holds only what its own block declares: a token the dark block
+// forgets must fail the checks, not borrow its light value.
+
+/** @typedef {Record<string, string>} Variables */
+/** @typedef {{ light: Variables, dark: Variables }} Theme */
+
+/**
+ * The text between the brace that opens at `open` and its matching close.
+ * @param {string} css @param {number} open
+ */
+function blockAt(css, open) {
+  let depth = 0;
+  for (let i = open; i < css.length; i++) {
+    if (css[i] === "{") depth++;
+    else if (css[i] === "}" && --depth === 0) return css.slice(open + 1, i);
+  }
+  throw new Error("theme has an unclosed block");
+}
+
+/**
+ * @param {string} body
+ * @returns {Variables}
+ */
+function declarations(body) {
+  /** @type {Variables} */
+  const vars = {};
+  for (const m of body.matchAll(/--([\w-]+)\s*:\s*([^;]+);/g)) {
+    if (m[1] && m[2]) vars[m[1]] = m[2].trim();
+  }
+  return vars;
+}
+
+/**
+ * @param {string} css
+ * @returns {Theme}
+ */
+export function readTheme(css) {
+  const source = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const rootAt = source.search(/(?:^|\n):root\s*\{/);
+  if (rootAt === -1) throw new Error("theme has no top-level :root block");
+  const root = blockAt(source, source.indexOf("{", rootAt));
+  const variantAt = root.search(/@variant\s+dark\s*\{/);
+  if (variantAt === -1) throw new Error("theme has no `@variant dark { … }` block inside :root");
+  const dark = blockAt(root, root.indexOf("{", variantAt));
+  const light = root.replace(`{${dark}}`, "{}");
+  return { light: declarations(light), dark: declarations(dark) };
+}

package/types/color.d.mts

@@ -0,0 +1,42 @@
+export type Oklch = {
+    l: number;
+    c: number;
+    h: number;
+    alpha: number;
+};
+/**
+ * Parses a CSS `oklch()` value. Returns null for anything else.
+ * @param {string} value
+ * @returns {Oklch | null}
+ */
+export declare function parseOklch(value: string): Oklch | null;
+/**
+ * Whether a colour is inside sRGB, so every screen paints the value as scored.
+ * @param {Oklch} color
+ */
+export declare function inSrgb(color: Oklch): boolean;
+/**
+ * Converts OKLCH to gamma-encoded sRGB channels in 0..1, clipped to the gamut.
+ * @param {Oklch} color
+ * @returns {[number, number, number]}
+ */
+export declare function oklchToSrgb(color: Oklch): [number, number, number];
+/**
+ * WCAG relative luminance of gamma-encoded sRGB channels in 0..1.
+ * @param {[number, number, number]} rgb
+ * @returns {number}
+ */
+export declare function luminance([r, g, b]: [number, number, number]): number;
+/**
+ * WCAG contrast ratio between two opaque OKLCH colours.
+ * @param {Oklch} a
+ * @param {Oklch} b
+ * @returns {number}
+ */
+export declare function contrast(a: Oklch, b: Oklch): number;
+/**
+ * Hex form of an OKLCH colour, for messages and tests.
+ * @param {Oklch} color
+ * @returns {string}
+ */
+export declare function toHex(color: Oklch): string;

package/types/contrast.d.mts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+export type Theme = import("./theme.mjs").Theme;
+export type Check = {
+    scheme: "light" | "dark";
+    fg: string;
+    bg: string;
+    ratio: number;
+    min: number;
+};
+/**
+ * @param {Theme} theme
+ * @returns {Check[]}
+ */
+export declare function checkContrast(theme: Theme): Check[];
+/**
+ * Chart colours outside sRGB, named for the error message.
+ * @param {Theme} theme
+ * @returns {string[]}
+ */
+export declare function checkGamut(theme: Theme): string[];

package/types/lint/index.d.mts

@@ -0,0 +1,26 @@
+export type Context = {
+    sourceCode: {
+        text: string;
+    };
+    report: (problem: {
+        node: unknown;
+        message: string;
+    }) => void;
+};
+export type Rule = {
+    meta?: object;
+    create: (context: any) => Record<string, (node: any) => void>;
+};
+/** @type {{ meta: { name: string }, rules: Record<string, Rule> }} */
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: Record<string, Rule>;
+};
+/**
+ * Every rule at "error", for a Vite+ or ESLint config to spread.
+ * @type {Record<string, "error">}
+ */
+export declare const recommended: Record<string, "error">;
+export default plugin;

package/types/shots.d.mts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+export type Mode = {
+    name: string;
+    width: number;
+    height: number;
+    dark: boolean;
+};
+export type Probe = {
+    gutterLeft: number | null;
+    gutterRight: number | null;
+    overflow: number;
+    overflowWithScrollbar: number;
+    font: string;
+    fontLoaded: boolean;
+    docHeight: number;
+    h1: string | null;
+};

package/types/theme.d.mts

@@ -0,0 +1,10 @@
+export type Variables = Record<string, string>;
+export type Theme = {
+    light: Variables;
+    dark: Variables;
+};
+/**
+ * @param {string} css
+ * @returns {Theme}
+ */
+export declare function readTheme(css: string): Theme;