@exegia/specular 0.1.0

package/README.md

@@ -0,0 +1,236 @@
+# @exegia/specular
+
+Specular lighting for Tailwind v4 + React: a highlight that tracks the pointer.
+Declare a surface, get a utility
+family that draws a two-layer inset "bezel" one axis at a time, a
+tailwind-merge config that keeps those utilities alive in `cn()`, and React
+primitives that light the surface with the pointer.
+
+| export | contents |
+|---|---|
+| `@exegia/specular` | `defineSurfaces` + types — the shared module both consumers import |
+| `@exegia/specular/plugin` | `createPlugin(surfaces)` — Tailwind v4 plugin factory, pure JS |
+| `@exegia/specular/merge` | `mergeConfig(surfaces)`, `createCn(surfaces)` — tailwind-merge |
+| `@exegia/specular/react` | `usePointerLight`, `<Rim>`, `measureRimTone`, `toneToAlphas`, `useRimTone` |
+
+Peers: `tailwindcss@^4.1 <5`; `react@^19` and `tailwind-merge@^3` only if you
+use `/react` or `/merge`. No runtime dependencies.
+
+## Setup
+
+One config, two consumers. It has to be a JS module: `@plugin` options are
+flat scalars only, and tailwind-merge runs in the browser.
+
+```ts
+// bezel.config.ts
+import { defineSurfaces } from "@exegia/specular"
+
+export const surfaces = defineSurfaces({
+  bezel: {
+    layers: {
+      lit: { color: "#fff", y: 2, blur: 3, alpha: 80, dark: { y: 1, blur: 1, alpha: 5 } },
+      dim: { color: "#000", y: -1, blur: 2, alpha: 15, dark: { y: -8, alpha: 20 } },
+    },
+  },
+  card: {
+    layers: {
+      lit:  { inset: true,  color: "#fff", y: 1, alpha: 60 },
+      drop: { inset: false, color: "#000", y: 4, blur: 8, alpha: 15 },
+    },
+  },
+})
+```
+
+```js
+// tailwind.plugin.js
+import { createPlugin } from "@exegia/specular/plugin"
+import { surfaces } from "./bezel.config"
+export default createPlugin(surfaces)
+```
+
+```css
+@import "tailwindcss";
+@plugin "./tailwind.plugin.js";
+```
+
+```ts
+// lib/utils.ts
+import { createCn } from "@exegia/specular/merge"
+import { surfaces } from "./bezel.config"
+export const cn = createCn(surfaces)
+```
+
+Then: `<div class="bezel-lit bezel-dim rounded-full" />`. The `dark` blocks
+land in a `.dark { --bezel-lit-y: … }` token block, so the element carries no
+`dark:` classes. Set `darkSelector` per surface for other strategies
+(`"@media (prefers-color-scheme: dark)"` wraps `:root`).
+
+### Layer config
+
+```ts
+type LayerConfig = {
+  inset?: boolean          // default true; false = outer drop layer
+  color?: string           // default "#fff" for the first layer, "#000" after
+  x?: number | string      // px number or any CSS length; default 0
+  y?: number | string
+  blur?: number | string   // default 0
+  spread?: number | string // default 0 — the knob that turns a hairline into a ring
+  alpha?: number           // 0-100, default 100
+  dark?: Partial<Omit<LayerConfig, "inset" | "dark">>
+}
+```
+
+Layer order in the map is paint order in `box-shadow`. `defineSurfaces` throws
+on a surface named after a core Tailwind root (`shadow`, `inset-shadow`,
+`ring`, `blur`, …), on names with `/`, `:`, whitespace or uppercase, and on a
+layer named `blur`, `spread`, `base` or `color`.
+
+> Dark mode is not the light values dimmed. On a dark page the white highlight
+> has to all but vanish (5% against 80%) while the shadow grows long and soft
+> (8px against 1px), or the disc reads as a lit dome on black.
+
+## Utilities
+
+For a surface `S` and a layer `L`. Every utility also emits the base
+`box-shadow`, so any single class stands alone.
+
+| utility | writes |
+|---|---|
+| `S-base` (or `baseClass`) | `box-shadow: var(--tw-S-shadow)` |
+| `S-L` | `--tw-S-L-alpha: 100` |
+| `S-L/40`, `S-L/[0.4]` | `--tw-S-L-alpha: 40` (fractions are scaled; `/80` ≡ `/[0.8]`) |
+| `S-L-t-N` | `--tw-S-L-y: calc(N * 1px)` — light enters from the top, pushes the layer down |
+| `S-L-b-N` | `--tw-S-L-y: calc(N * -1px)` |
+| `S-L-l-N` / `S-L-r-N` | `--tw-S-L-x` |
+| `S-L-blur-N`, `S-L-spread-N` | `--tw-S-L-blur`, `--tw-S-L-spread` |
+| `S-L-color-red-500`, `S-L-color-[#fff]` | `--tw-S-L-color` |
+| `S-blur-N`, `S-spread-N` | every layer at once |
+
+`N` is a bare integer, a decimal, or `[<length>]`. `-t-`/`-b-` write the same
+variable, as do `-l-`/`-r-`: pick one per layer per axis. `-t-[2]` passes
+through as the unitless `2`, which is invalid in `box-shadow` — core behaves
+the same.
+
+### How it works: three tiers
+
+| tier | name | set by | inherits |
+|---|---|---|---|
+| composed | `--tw-S-shadow` | universal selector in `@layer base` | set everywhere |
+| instance | `--tw-S-L-{x,y,blur,spread,color,alpha}` | utilities; `@property { syntax: "*"; inherits: false }`, no `initial-value` | no |
+| preset | `--S-L-{…}` | the `dark` block, or your CSS | yes |
+
+Each component is `var(--tw-S-L-y, var(--S-L-y, <default>))`: the utility's
+value if set on this element, else the inherited preset, else the config
+default. Registering the instance tier without an `initial-value` gives it
+the guaranteed-invalid value, so `var()` falls through; `inherits: false`
+stops a nested bezel from picking up its ancestor's offsets. Verified in
+Chromium 152 (a registered `--x: 20px` on the parent leaves the child at the
+fallback; an unregistered one leaks). Not yet verified in WebKit — if it
+ever leaks there, drop the `@property` block and everything else still works.
+
+## `cn()` and why the merge config ships here
+
+`twMerge("inset-shadow-lit-t-2 inset-shadow-dim-b-1")` with stock
+tailwind-merge returns `"inset-shadow-dim-b-1"`: any custom utility whose
+name shares a prefix with a core group is filed under that group and only the
+last survives. That shipped once — the CSS compiled, a `toContain` test
+passed on the survivor, and the lit layer never reached the screen.
+
+`mergeConfig(surfaces)` generates one class group per custom property,
+bidirectional conflicts with core `shadow`/`inset-shadow`, all-layer groups
+that displace their per-layer twins, and the full cross-surface matrix (two
+surfaces on one element means one `box-shadow` wins outright). Group ids are
+a template-literal union, so a typo in your own `conflictingClassGroups` is a
+compile error.
+
+`createCn` accepts what tailwind-merge accepts (strings, arrays, falsy). For
+clsx's object form: `extendTailwindMerge(mergeConfig(surfaces))(clsx(...))`.
+
+## React
+
+Every entry carries `"use client"`. SSR renders the static emboss; nothing
+touches `window` at module scope.
+
+```tsx
+import { usePointerLight, Rim, useRimTone, toneToAlphas } from "@exegia/specular/react"
+
+function Avatar({ src }: { src: string }) {
+  const ref = useRef<HTMLSpanElement>(null)
+  const angle = usePointerLight(ref)               // raw bearing, 0 = 12 o'clock
+  const tone = useRimTone(src)                     // 0–1 rim lightness, or null
+  const alphas = tone === null ? undefined : toneToAlphas(tone)
+  return (
+    <span ref={ref} className="relative size-16 rounded-full bezel-lit bezel-dim">
+      <img src={src} className="size-full rounded-full" />
+      <Rim angle={angle * 0.8} hi={alphas?.hi} lo={alphas?.lo} className="rounded-full" />
+    </span>
+  )
+}
+```
+
+- **`usePointerLight(ref, options?)`** — one shared window listener and one
+  rAF per frame for every subscriber on the page; 1.5° epsilon; shortest-arc
+  unwrapping so `rotate()` never spins the long way round; no subscription
+  under `prefers-reduced-motion`. Damping is yours (`angle * 0.8`).
+  `{ mode: "var", property: "--light-angle" }` writes `<angle>deg` on the
+  element with no re-render — the escape hatch for lists.
+- **`<Rim>`** — the masked conic sweep, `rotate()` as the animated property,
+  radius-relative mask so it reads the same at 32px and 64px. Radius is
+  yours: pass `rounded-full`. Alphas come from `--rim-hi-a` / `--rim-lo-a`
+  (light 1 / 0.2 baked in; the plugin emits the dark 0.18 / 0.4 block).
+- **`measureRimTone(src)`** — Rec. 709 luma over the outer band of a 16×16
+  sample; `null` on SSR, decode error or a host without CORS headers;
+  memoised per `src`, a `null` is evicted so a later mount retries.
+- **`toneToAlphas(t, ends?)`** — `{ hi: 0.7 + 0.3t, lo: 0.6 − 0.4t }`,
+  retunable through `ends`.
+
+## Things worth knowing
+
+- **An inset shadow paints under the root's children.** A `size-full` image
+  hides it. That is why `<Rim>` is a separate overlay, and why a fallback
+  must stay transparent for the emboss to show.
+- **The family owns `box-shadow`.** Never pair a surface with `shadow-*` or
+  `ring-*`; `cn()` deletes one, and raw class strings leave the stylesheet to
+  pick an arbitrary winner.
+- **`S-blur-N` and `S-L-blur-N` write the same var.** In the stylesheet (and
+  in `@apply`) the winner is Tailwind's sort order, not class order. `cn()`
+  resolves it: all-layer displaces per-layer.
+- **Browser floor: `color-mix()`** (Chrome 111, Safari 16.2, Firefox 113).
+  Tailwind's fallback branch drops the alpha, so below that the surface
+  paints opaque. Accepted: all three are 2023.
+- **`@apply` of a surface inside `@layer components` works.**
+- **Opposite edges of one layer overwrite; they do not add.** Two layers is
+  the way to light two edges.
+
+## Migrating an existing `inset-shadow-*` family
+
+A surface named `inset-shadow` with `baseClass: "inset-shadow-bezel"`,
+`allowCoreCollision: true` and layers `lit` / `dim` reproduces the class API
+exactly (`inset-shadow-lit-t-3 inset-shadow-lit/80 …`), and the merge config
+handles the core collision. The tests cover this shape class by class.
+
+## Example app
+
+`examples/vite-react` is a Vite + React 19 + Tailwind v4 page that walks
+through every surface, offset, alpha, blur and colour utility, the `glow`
+hover halo, the pointer-lit rims and the `cn()` merge. It runs against the
+library in this checkout:
+
+```bash
+make example-dev       # build the library, install the example, start Vite
+make example-build     # production build, what CI runs
+```
+
+See [`examples/vite-react/README.md`](examples/vite-react/README.md) for what
+each section shows.
+
+## Development
+
+```bash
+make ci        # lint (tsc), build, test, smoke
+make help      # every target, including the release pipeline
+```
+
+Tests run on `node --test` with no framework. The Tailwind harness compiles
+in memory in under a second. See `.github/WORKFLOW.md` for branching and
+releases.

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `defineSurfaces()` — the shared module.
+ *
+ * Both the Tailwind plugin (`@exegia/specular/plugin`) and the tailwind-merge
+ * generator (`@exegia/specular/merge`) consume the same surface config. It has
+ * to be a JS module because `@plugin` options are flat scalars only and
+ * tailwind-merge runs in the browser where `@plugin` options do not exist.
+ * One source of truth, two consumers.
+ */
+export type Length = number | string;
+export type LayerConfig = {
+    /** `false` = an outer drop layer. Default `true`. */
+    inset?: boolean;
+    /** Default `#fff` for the first layer, `#000` after. */
+    color?: string;
+    /** px when a number, any CSS length as a string. Default 0. */
+    x?: Length;
+    y?: Length;
+    blur?: Length;
+    /** The knob that turns a hairline into a ring. Default 0. */
+    spread?: Length;
+    /** 0–100. Default 100. */
+    alpha?: number;
+    /**
+     * Dark-mode preset, emitted under `darkSelector`.
+     *
+     * Dark mode is not the light values dimmed. On a dark page the white
+     * highlight has to all but vanish (5% against 80%) while the shadow grows
+     * long and soft (8px against 1px), or the disc reads as a lit dome on black.
+     */
+    dark?: Partial<Omit<LayerConfig, "inset" | "dark">>;
+};
+export type SurfaceConfig = {
+    /** Paint order in `box-shadow` is map order. */
+    layers: Record<string, LayerConfig>;
+    /** Default `${surface}-base`. */
+    baseClass?: string;
+    /** Where the `dark` presets land. A selector, or an at-rule prelude
+     * (`@media (prefers-color-scheme: dark)`) which wraps `:root`. Default `.dark`. */
+    darkSelector?: string;
+    /** Only for migrating an existing `inset-shadow-*` family in place. */
+    allowCoreCollision?: boolean;
+};
+export type Surfaces = Record<string, SurfaceConfig>;
+export declare function defineSurfaces<const T extends Surfaces>(surfaces: T): T;
+export type ResolvedLayer = {
+    name: string;
+    inset: boolean;
+    color: string;
+    x: string;
+    y: string;
+    blur: string;
+    spread: string;
+    alpha: string;
+    dark: Partial<Record<"color" | "x" | "y" | "blur" | "spread" | "alpha", string>>;
+};
+export type ResolvedSurface = {
+    name: string;
+    baseClass: string;
+    darkSelector: string;
+    layers: ResolvedLayer[];
+};
+export declare const LAYER_PROPS: readonly ["x", "y", "blur", "spread", "color", "alpha"];
+export type LayerProp = (typeof LAYER_PROPS)[number];
+export declare function length(v: Length | undefined, fallback?: string): string;
+export declare function resolveSurfaces(surfaces: Surfaces): ResolvedSurface[];

package/dist/index.js

@@ -0,0 +1,85 @@
+/**
+ * `defineSurfaces()` — the shared module.
+ *
+ * Both the Tailwind plugin (`@exegia/specular/plugin`) and the tailwind-merge
+ * generator (`@exegia/specular/merge`) consume the same surface config. It has
+ * to be a JS module because `@plugin` options are flat scalars only and
+ * tailwind-merge runs in the browser where `@plugin` options do not exist.
+ * One source of truth, two consumers.
+ */
+/** Tailwind roots our utilities would shadow — and that tailwind-merge would
+ * fold ours into (§6). */
+const CORE_ROOTS = new Set([
+    "shadow",
+    "inset-shadow",
+    "ring",
+    "inset-ring",
+    "blur",
+    "drop-shadow",
+    "text-shadow",
+    "outline",
+]);
+/** Layer names that would collide with the all-layer / base utilities. */
+const RESERVED_LAYERS = new Set(["blur", "spread", "base", "color"]);
+const BAD_NAME = /[/:\s]|[A-Z]/;
+export function defineSurfaces(surfaces) {
+    for (const [surface, config] of Object.entries(surfaces)) {
+        if (BAD_NAME.test(surface))
+            throw new Error(`bezel: surface "${surface}" may not contain "/", ":", whitespace or uppercase`);
+        if (CORE_ROOTS.has(surface) && !config.allowCoreCollision)
+            throw new Error(`bezel: surface "${surface}" collides with a core Tailwind root; set allowCoreCollision: true only to migrate an existing family in place`);
+        const layers = Object.keys(config.layers);
+        if (layers.length === 0)
+            throw new Error(`bezel: surface "${surface}" declares no layers`);
+        for (const layer of layers) {
+            if (BAD_NAME.test(layer))
+                throw new Error(`bezel: layer "${surface}.${layer}" may not contain "/", ":", whitespace or uppercase`);
+            if (RESERVED_LAYERS.has(layer))
+                throw new Error(`bezel: layer "${surface}.${layer}" is reserved (blur, spread, base, color)`);
+        }
+    }
+    return surfaces;
+}
+export const LAYER_PROPS = ["x", "y", "blur", "spread", "color", "alpha"];
+export function length(v, fallback = "0") {
+    if (v === undefined)
+        return fallback;
+    if (typeof v === "number")
+        return v === 0 ? "0" : `${v}px`;
+    return v;
+}
+export function resolveSurfaces(surfaces) {
+    return Object.entries(surfaces).map(([name, config]) => ({
+        name,
+        baseClass: config.baseClass ?? `${name}-base`,
+        darkSelector: config.darkSelector ?? ".dark",
+        layers: Object.entries(config.layers).map(([layer, l], i) => {
+            const dark = {};
+            if (l.dark) {
+                if (l.dark.color !== undefined)
+                    dark.color = l.dark.color;
+                if (l.dark.x !== undefined)
+                    dark.x = length(l.dark.x);
+                if (l.dark.y !== undefined)
+                    dark.y = length(l.dark.y);
+                if (l.dark.blur !== undefined)
+                    dark.blur = length(l.dark.blur);
+                if (l.dark.spread !== undefined)
+                    dark.spread = length(l.dark.spread);
+                if (l.dark.alpha !== undefined)
+                    dark.alpha = String(l.dark.alpha);
+            }
+            return {
+                name: layer,
+                inset: l.inset ?? true,
+                color: l.color ?? (i === 0 ? "#fff" : "#000"),
+                x: length(l.x),
+                y: length(l.y),
+                blur: length(l.blur),
+                spread: length(l.spread),
+                alpha: String(l.alpha ?? 100),
+                dark,
+            };
+        }),
+    }));
+}

package/dist/merge.d.ts

@@ -0,0 +1,31 @@
+/**
+ * tailwind-merge config generator.
+ *
+ * `twMerge("inset-shadow-lit-t-2 inset-shadow-dim-b-1")` with stock
+ * tailwind-merge returns `"inset-shadow-dim-b-1"`: every unknown class that
+ * shares a prefix with a core group is filed under that group, which holds
+ * one `box-shadow`, and only the last survives. Utilities and merge config
+ * therefore ship as one artifact from one config.
+ *
+ * One class group per custom property. Every group displaces core `shadow`
+ * and `inset-shadow` and is displaced by them; all-layer groups displace
+ * their per-layer twins; and the full N×N cross-surface matrix is generated,
+ * because two surfaces on one element means one `box-shadow` wins outright.
+ */
+import { type ClassNameValue, type ConfigExtension, type DefaultClassGroupIds, type DefaultThemeGroupIds } from "tailwind-merge";
+import { type LayerProp, type Surfaces } from "./index.ts";
+/** Template-literal union of every group id, so a typo in a consumer's
+ * `conflictingClassGroups` is a compile error. */
+export type BezelGroupId<T extends Surfaces> = {
+    [S in keyof T & string]: `${S}-base` | `${S}-blur` | `${S}-spread` | {
+        [L in keyof T[S]["layers"] & string]: `${S}-${L}-${LayerProp}`;
+    }[keyof T[S]["layers"] & string];
+}[keyof T & string];
+export type BezelMergeConfig<T extends Surfaces> = ConfigExtension<DefaultClassGroupIds | BezelGroupId<T>, DefaultThemeGroupIds>;
+export declare function mergeConfig<const T extends Surfaces>(surfaces: T): BezelMergeConfig<T>;
+/**
+ * A ready `cn`. Accepts what tailwind-merge accepts: strings, arrays, and
+ * falsy values — not clsx's object form. For that, run clsx first:
+ * `extendTailwindMerge(mergeConfig(surfaces))(clsx(...))`.
+ */
+export declare function createCn<const T extends Surfaces>(surfaces: T): (...inputs: ClassNameValue[]) => string;

package/dist/merge.js

@@ -0,0 +1,63 @@
+/**
+ * tailwind-merge config generator.
+ *
+ * `twMerge("inset-shadow-lit-t-2 inset-shadow-dim-b-1")` with stock
+ * tailwind-merge returns `"inset-shadow-dim-b-1"`: every unknown class that
+ * shares a prefix with a core group is filed under that group, which holds
+ * one `box-shadow`, and only the last survives. Utilities and merge config
+ * therefore ship as one artifact from one config.
+ *
+ * One class group per custom property. Every group displaces core `shadow`
+ * and `inset-shadow` and is displaced by them; all-layer groups displace
+ * their per-layer twins; and the full N×N cross-surface matrix is generated,
+ * because two surfaces on one element means one `box-shadow` wins outright.
+ */
+import { extendTailwindMerge, validators, } from "tailwind-merge";
+import { LAYER_PROPS, resolveSurfaces } from "./index.js";
+const { isAny } = validators;
+export function mergeConfig(surfaces) {
+    const resolved = resolveSurfaces(surfaces);
+    const classGroups = {};
+    const conflicts = {};
+    const own = new Map();
+    for (const s of resolved) {
+        const ids = [`${s.name}-base`, `${s.name}-blur`, `${s.name}-spread`];
+        classGroups[`${s.name}-base`] = [s.baseClass];
+        classGroups[`${s.name}-blur`] = [{ [s.name]: [{ blur: [isAny] }] }];
+        classGroups[`${s.name}-spread`] = [{ [s.name]: [{ spread: [isAny] }] }];
+        for (const l of s.layers) {
+            const n = `${s.name}-${l.name}`;
+            classGroups[`${n}-x`] = [{ [n]: [{ l: [isAny], r: [isAny] }] }];
+            classGroups[`${n}-y`] = [{ [n]: [{ t: [isAny], b: [isAny] }] }];
+            classGroups[`${n}-blur`] = [{ [n]: [{ blur: [isAny] }] }];
+            classGroups[`${n}-spread`] = [{ [n]: [{ spread: [isAny] }] }];
+            classGroups[`${n}-color`] = [{ [n]: [{ color: [isAny] }] }];
+            // The bare class and its `/40` modifier.
+            classGroups[`${n}-alpha`] = [n];
+            ids.push(...LAYER_PROPS.map((p) => `${n}-${p}`));
+        }
+        own.set(s.name, ids);
+    }
+    const all = [...own.values()].flat();
+    for (const s of resolved) {
+        const mine = own.get(s.name) ?? [];
+        const foreign = all.filter((g) => !mine.includes(g));
+        for (const g of mine)
+            conflicts[g] = ["shadow", "inset-shadow", ...foreign];
+        for (const p of ["blur", "spread"])
+            conflicts[`${s.name}-${p}`]?.push(...s.layers.map((l) => `${s.name}-${l.name}-${p}`));
+    }
+    conflicts.shadow = all;
+    conflicts["inset-shadow"] = all;
+    // Built as plain records; the group ids are typed at the boundary.
+    return { extend: { classGroups, conflictingClassGroups: conflicts } };
+}
+/**
+ * A ready `cn`. Accepts what tailwind-merge accepts: strings, arrays, and
+ * falsy values — not clsx's object form. For that, run clsx first:
+ * `extendTailwindMerge(mergeConfig(surfaces))(clsx(...))`.
+ */
+export function createCn(surfaces) {
+    const merge = extendTailwindMerge(mergeConfig(surfaces));
+    return (...inputs) => merge(...inputs);
+}

package/dist/plugin.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tailwind v4 plugin factory. Pure JS, no CSS file: the whole utility family
+ * for every surface comes out of `createPlugin(surfaces)`.
+ *
+ *   // tailwind.plugin.js
+ *   import { createPlugin } from "@exegia/specular/plugin"
+ *   import { surfaces } from "./bezel.config"
+ *   export default createPlugin(surfaces)
+ *
+ *   // app.css
+ *   @plugin "./tailwind.plugin.js";
+ *
+ * Three tiers of custom property make presets and dark mode work with no
+ * `dark:` classes on the element:
+ *
+ *   composed  --tw-{S}-shadow          universal selector, @layer base
+ *   instance  --tw-{S}-{L}-{prop}      utilities; @property { syntax: "*"; inherits: false }
+ *   preset    --{S}-{L}-{prop}         darkSelector block / consumer CSS; inherits
+ *
+ * Each component in the composed string is `var(instance, var(preset, default))`.
+ * The instance tier is registered WITHOUT an initial-value so its initial
+ * value is the guaranteed-invalid value and `var()` falls through to the
+ * preset; `inherits: false` keeps a nested surface from picking up its
+ * ancestor's offsets (verified in Chromium, see README).
+ */
+import type { PluginAPI } from "tailwindcss/plugin";
+import { type ResolvedSurface, type Surfaces } from "./index.ts";
+export type RimTokens = {
+    hi: number;
+    lo: number;
+};
+export type PluginOptions = {
+    /**
+     * `<Rim>` reads `--rim-hi-a` / `--rim-lo-a`. Light defaults are the
+     * fallbacks baked into the component; the dark block is emitted here so a
+     * consumer never writes `dark:` classes on the rim. `false` emits nothing.
+     */
+    rim?: {
+        darkSelector?: string;
+        dark?: RimTokens;
+    } | false;
+};
+export declare const RIM_DARK_DEFAULTS: RimTokens;
+/**
+ * `/80` and `/[0.8]` both mean 80%. Tailwind hands `/[0.8]` over as `0.8`,
+ * which `calc(… * 1%)` would read as 0.8%, so a fraction is scaled up.
+ */
+export declare function normalizeAlpha(raw: string): string;
+/** The whole `box-shadow` for one surface, every component a var chain. */
+export declare function composedShadow(s: ResolvedSurface): string;
+export declare function createPlugin(surfaces: Surfaces, options?: PluginOptions): ({ addBase, addUtilities, matchUtilities, theme }: PluginAPI) => void;
+export default createPlugin;

package/dist/plugin.js

@@ -0,0 +1,94 @@
+import { LAYER_PROPS, resolveSurfaces, } from "./index.js";
+/** Five selectors, not fewer: `file:bezel-lit-t-2` resolves to
+ * `::file-selector-button`, which must see the hoisted var too. */
+const UNIVERSAL = "*, ::before, ::after, ::backdrop, ::file-selector-button";
+export const RIM_DARK_DEFAULTS = { hi: 0.18, lo: 0.4 };
+const BARE = /^\d+(\.\d+)?$/;
+const BARE_NEG = /^calc\(\d+(\.\d+)? \* -1px\)$/;
+/** `-t-2` → `calc(2 * 1px)`, `-t-1.5` → `calc(1.5 * 1px)`; `[0.5rem]` passes through. */
+const bare = (u) => (BARE.test(u.value) ? `calc(${u.value} * 1px)` : undefined);
+/** The opposite edge of the same axis. */
+const bareNeg = (u) => (BARE.test(u.value) ? `calc(${u.value} * -1px)` : undefined);
+const negate = (v) => (BARE_NEG.test(v) ? v : `calc(${v} * -1)`);
+/**
+ * `/80` and `/[0.8]` both mean 80%. Tailwind hands `/[0.8]` over as `0.8`,
+ * which `calc(… * 1%)` would read as 0.8%, so a fraction is scaled up.
+ */
+export function normalizeAlpha(raw) {
+    const v = raw.replace(/^\[|\]$/g, "");
+    if (/^0?\.\d+$/.test(v))
+        return String(Math.round(parseFloat(v) * 10000) / 100);
+    return v;
+}
+const instanceVar = (s, l, p) => `--tw-${s}-${l}-${p}`;
+const presetVar = (s, l, p) => `--${s}-${l}-${p}`;
+function chain(s, l, p) {
+    return `var(${instanceVar(s, l.name, p)}, var(${presetVar(s, l.name, p)}, ${l[p]}))`;
+}
+/** The whole `box-shadow` for one surface, every component a var chain. */
+export function composedShadow(s) {
+    return s.layers
+        .map((l) => {
+        const c = (p) => chain(s.name, l, p);
+        return `${l.inset ? "inset " : ""}${c("x")} ${c("y")} ${c("blur")} ${c("spread")} color-mix(in srgb, ${c("color")} calc(${c("alpha")} * 1%), transparent)`;
+    })
+        .join(", ");
+}
+/** A selector wraps the declarations; an at-rule prelude wraps `:root`. */
+function darkBlock(selector, decls) {
+    return selector.startsWith("@") ? { [selector]: { ":root": decls } } : { [selector]: decls };
+}
+export function createPlugin(surfaces, options = {}) {
+    const resolved = resolveSurfaces(surfaces);
+    const rim = options.rim === false ? null : { darkSelector: ".dark", dark: RIM_DARK_DEFAULTS, ...options.rim };
+    return function bezel({ addBase, addUtilities, matchUtilities, theme }) {
+        if (rim) {
+            addBase(darkBlock(rim.darkSelector, { "--rim-hi-a": String(rim.dark.hi), "--rim-lo-a": String(rim.dark.lo) }));
+        }
+        for (const s of resolved) {
+            const base = { "box-shadow": `var(--tw-${s.name}-shadow)` };
+            // Composed tier, hoisted once. Tailwind splits the color-mix() into a
+            // plain fallback plus an @supports branch; doing this per utility
+            // would duplicate that pair per utility per surface.
+            addBase({ [UNIVERSAL]: { [`--tw-${s.name}-shadow`]: composedShadow(s) } });
+            // Instance tier. No initial-value on purpose (see the header).
+            const registrations = {};
+            for (const l of s.layers)
+                for (const p of LAYER_PROPS)
+                    registrations[`@property ${instanceVar(s.name, l.name, p)}`] = { syntax: '"*"', inherits: "false" };
+            addBase(registrations);
+            // Preset tier: the dark block.
+            const dark = {};
+            for (const l of s.layers)
+                for (const [p, v] of Object.entries(l.dark))
+                    dark[presetVar(s.name, l.name, p)] = v;
+            if (Object.keys(dark).length > 0)
+                addBase(darkBlock(s.darkSelector, dark));
+            addUtilities({ [`.${s.baseClass}`]: base });
+            // `values` is typed as a string record; the bare-value hook is the one
+            // documented exception (`NamedUtilityValue` is not exported).
+            const lengths = (neg) => ({
+                type: ["number", "length"],
+                values: { __BARE_VALUE__: neg ? bareNeg : bare },
+            });
+            for (const l of s.layers) {
+                const n = `${s.name}-${l.name}`;
+                const v = (p) => instanceVar(s.name, l.name, p);
+                const set = (p, f = (x) => x) => (value) => ({ ...base, [v(p)]: f(value) });
+                // Bare = full alpha; `/40` and `/[0.4]` = 40.
+                matchUtilities({ [n]: (value, { modifier }) => ({ ...base, [v("alpha")]: normalizeAlpha(modifier ?? value) }) }, { values: { DEFAULT: "100" }, modifiers: "any" });
+                // The letter names the edge the light enters from.
+                matchUtilities({ [`${n}-t`]: set("y"), [`${n}-l`]: set("x"), [`${n}-blur`]: set("blur"), [`${n}-spread`]: set("spread") }, lengths(false));
+                matchUtilities({ [`${n}-b`]: set("y", negate), [`${n}-r`]: set("x", negate) }, lengths(true));
+                matchUtilities({ [`${n}-color`]: set("color") }, { type: ["color"], values: theme("colors") });
+            }
+            // All layers at once.
+            const all = (p) => (value) => ({
+                ...base,
+                ...Object.fromEntries(s.layers.map((l) => [instanceVar(s.name, l.name, p), value])),
+            });
+            matchUtilities({ [`${s.name}-blur`]: all("blur"), [`${s.name}-spread`]: all("spread") }, lengths(false));
+        }
+    };
+}
+export default createPlugin;

package/dist/pointer-light.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pointer → bearing, shared across every lit surface on the page.
+ *
+ * One window `pointermove` listener and one rAF per frame flush a registry
+ * of subscribers, so fifty avatars are one handler, not fifty. Each
+ * subscriber keeps its own unwrapped angle so `rotate()` never spins the
+ * long way round.
+ */
+import { type RefObject } from "react";
+/** Below this the write is skipped: a rim cannot show a sub-degree change. */
+export declare const ANGLE_EPSILON = 1.5;
+/** Bearing of (x, y) from (cx, cy): 0 = 12 o'clock, clockwise grows. */
+export declare function bearingFrom(cx: number, cy: number, x: number, y: number): number;
+/**
+ * Step from `last` toward `bearing` along the shortest arc. The result is
+ * continuous (it may exceed 360 or go negative). `null` when the move is
+ * under `ANGLE_EPSILON`. A NaN `last` means "no previous value".
+ */
+export declare function unwrap(last: number, bearing: number): number | null;
+/** Register a target; the listener exists only while the set is non-empty. */
+export declare function subscribe(target: () => Element | null, emit: (angle: number) => void): () => void;
+/** For tests. */
+export declare const subscriberCount: () => number;
+/** `false` on the server and on first render; tracks the media query after. */
+export declare function useReducedMotion(): boolean;
+export type PointerLightOptions = {
+    mode?: "state";
+    enabled?: boolean;
+} | {
+    mode: "var";
+    property?: string;
+    enabled?: boolean;
+};
+/**
+ * `mode: "state"` (default) returns the raw bearing and re-renders on change.
+ * `mode: "var"` writes `<property>: <angle>deg` (default `--light-angle`) on
+ * the element with `style.setProperty` and never re-renders — the escape
+ * hatch for lists. Damping stays with the consumer: `rotate(angle * 0.8)`.
+ * Reduced motion: no subscription, `0`.
+ */
+export declare function usePointerLight(ref: RefObject<Element | null>, options?: {
+    mode?: "state";
+    enabled?: boolean;
+}): number;
+export declare function usePointerLight(ref: RefObject<Element | null>, options: {
+    mode: "var";
+    property?: string;
+    enabled?: boolean;
+}): void;

package/dist/pointer-light.js

@@ -0,0 +1,109 @@
+"use client";
+/**
+ * Pointer → bearing, shared across every lit surface on the page.
+ *
+ * One window `pointermove` listener and one rAF per frame flush a registry
+ * of subscribers, so fifty avatars are one handler, not fifty. Each
+ * subscriber keeps its own unwrapped angle so `rotate()` never spins the
+ * long way round.
+ */
+import { useEffect, useState } from "react";
+/** Below this the write is skipped: a rim cannot show a sub-degree change. */
+export const ANGLE_EPSILON = 1.5;
+/** Bearing of (x, y) from (cx, cy): 0 = 12 o'clock, clockwise grows. */
+export function bearingFrom(cx, cy, x, y) {
+    // atan2 measures from 3 o'clock anticlockwise-positive in screen space.
+    return ((Math.atan2(y - cy, x - cx) * 180) / Math.PI + 90 + 360) % 360;
+}
+/**
+ * Step from `last` toward `bearing` along the shortest arc. The result is
+ * continuous (it may exceed 360 or go negative). `null` when the move is
+ * under `ANGLE_EPSILON`. A NaN `last` means "no previous value".
+ */
+export function unwrap(last, bearing) {
+    if (Number.isNaN(last))
+        return bearing;
+    let delta = bearing - (((last % 360) + 360) % 360);
+    if (delta > 180)
+        delta -= 360;
+    if (delta < -180)
+        delta += 360;
+    if (Math.abs(delta) < ANGLE_EPSILON)
+        return null;
+    return last + delta;
+}
+const subscribers = new Set();
+let frame = 0;
+let pointer = null;
+function flush() {
+    frame = 0;
+    if (!pointer)
+        return;
+    for (const s of subscribers) {
+        const el = s.target();
+        if (!el)
+            continue;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0)
+            continue;
+        const next = unwrap(s.last, bearingFrom(rect.left + rect.width / 2, rect.top + rect.height / 2, pointer.x, pointer.y));
+        if (next === null)
+            continue;
+        s.last = next;
+        s.emit(next);
+    }
+}
+function onMove(event) {
+    pointer = { x: event.clientX, y: event.clientY };
+    if (frame === 0)
+        frame = requestAnimationFrame(flush);
+}
+/** Register a target; the listener exists only while the set is non-empty. */
+export function subscribe(target, emit) {
+    const sub = { target, last: Number.NaN, emit };
+    if (subscribers.size === 0)
+        window.addEventListener("pointermove", onMove, { passive: true });
+    subscribers.add(sub);
+    return () => {
+        subscribers.delete(sub);
+        if (subscribers.size === 0) {
+            window.removeEventListener("pointermove", onMove);
+            if (frame !== 0)
+                cancelAnimationFrame(frame);
+            frame = 0;
+        }
+    };
+}
+/** For tests. */
+export const subscriberCount = () => subscribers.size;
+const REDUCE = "(prefers-reduced-motion: reduce)";
+/** `false` on the server and on first render; tracks the media query after. */
+export function useReducedMotion() {
+    const [reduce, setReduce] = useState(false);
+    useEffect(() => {
+        if (typeof window.matchMedia !== "function")
+            return;
+        const mq = window.matchMedia(REDUCE);
+        const update = () => setReduce(mq.matches);
+        update();
+        mq.addEventListener("change", update);
+        return () => mq.removeEventListener("change", update);
+    }, []);
+    return reduce;
+}
+export function usePointerLight(ref, options = {}) {
+    const [angle, setAngle] = useState(0);
+    const reduce = useReducedMotion();
+    const enabled = options.enabled ?? true;
+    const mode = options.mode ?? "state";
+    const property = options.mode === "var" ? (options.property ?? "--light-angle") : null;
+    useEffect(() => {
+        if (!enabled || reduce)
+            return;
+        const emit = property === null
+            ? setAngle
+            : (a) => ref.current?.style.setProperty(property, `${a}deg`);
+        return subscribe(() => ref.current, emit);
+    }, [enabled, reduce, property, ref]);
+    return mode === "state" ? angle : undefined;
+}

package/dist/react.d.ts

@@ -0,0 +1,3 @@
+export { usePointerLight, useReducedMotion, ANGLE_EPSILON, type PointerLightOptions } from "./pointer-light.ts";
+export { Rim, RIM_TRANSITION, type RimProps } from "./rim.tsx";
+export { measureRimTone, toneToAlphas, useRimTone, DEFAULT_TONE_ENDS, type ToneAlphas, type ToneEnds, } from "./tone.ts";

package/dist/react.js

@@ -0,0 +1,4 @@
+"use client";
+export { usePointerLight, useReducedMotion, ANGLE_EPSILON } from "./pointer-light.js";
+export { Rim, RIM_TRANSITION } from "./rim.js";
+export { measureRimTone, toneToAlphas, useRimTone, DEFAULT_TONE_ENDS, } from "./tone.js";

package/dist/rim.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The masked conic sweep that rotates toward the pointer.
+ *
+ *   <Rim angle={angle * 0.8} hi={0.7} lo={0.4} className="rounded-full" />
+ *
+ * An inset shadow paints under the root's children, so a `size-full` image
+ * hides the emboss completely; this overlay sits above the image instead.
+ * The gradient starts at 6 o'clock with the highlight peaking at 12, so
+ * `rotate(angle)` puts the highlight exactly `angle` degrees clockwise from
+ * 12. Rotation is the animated property, not the gradient's `from` angle:
+ * `transform` transitions, a gradient angle does not. The mask is
+ * radius-relative so the rim reads the same at 32px and 64px. Radius is the
+ * consumer's: pass `rounded-full` or `rounded-[20px]`.
+ */
+import type { HTMLAttributes } from "react";
+export type RimProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+    /** Degrees clockwise from 12 o'clock. Apply damping before passing. */
+    angle?: number;
+    /** Highlight alpha, 0–1. Unset = `--rim-hi-a` (light 1, dark 0.18 via the plugin). */
+    hi?: number;
+    /** Shadow alpha, 0–1. Unset = `--rim-lo-a` (light 0.2, dark 0.4 via the plugin). */
+    lo?: number;
+};
+/** transitions.dev `--duration-quick` / `--ease-smooth-out`. */
+export declare const RIM_TRANSITION = "transform 150ms cubic-bezier(0.22, 1, 0.36, 1)";
+export declare function Rim({ angle, hi, lo, style, ...rest }: RimProps): import("react").JSX.Element;

package/dist/rim.js

@@ -0,0 +1,30 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useReducedMotion } from "./pointer-light.js";
+const GRADIENT = "conic-gradient(from 180deg, var(--rim-lo) 0%, transparent 24%, transparent 28%, var(--rim-hi) 50%, transparent 72%, transparent 76%, var(--rim-lo) 100%)";
+const MASK = "radial-gradient(farthest-side, transparent 78%, #000 92%)";
+/** transitions.dev `--duration-quick` / `--ease-smooth-out`. */
+export const RIM_TRANSITION = "transform 150ms cubic-bezier(0.22, 1, 0.36, 1)";
+export function Rim({ angle = 0, hi, lo, style, ...rest }) {
+    const reduce = useReducedMotion();
+    const vars = {
+        "--rim-hi": "color-mix(in oklab, white calc(var(--rim-hi-a, 1) * 50%), transparent)",
+        "--rim-lo": "color-mix(in oklab, black calc(var(--rim-lo-a, 0.2) * 50%), transparent)",
+    };
+    if (hi !== undefined)
+        vars["--rim-hi-a"] = String(hi);
+    if (lo !== undefined)
+        vars["--rim-lo-a"] = String(lo);
+    return (_jsx("span", { "aria-hidden": "true", "data-slot": "rim", ...rest, style: {
+            position: "absolute",
+            inset: 0,
+            pointerEvents: "none",
+            background: GRADIENT,
+            maskImage: MASK,
+            WebkitMaskImage: MASK,
+            transition: reduce ? "none" : RIM_TRANSITION,
+            transform: `rotate(${angle}deg)`,
+            ...vars,
+            ...style,
+        } }));
+}

package/dist/tone.d.ts

@@ -0,0 +1,44 @@
+/** 16² px is enough to average a rim. */
+export declare const TONE_SAMPLE_SIZE = 16;
+/** Pixels this far (in radii) from the centre count as rim — the band the
+ * bezel sits on. Matches the ring's mask, which fades in from ~78%. */
+export declare const TONE_RIM_RADIUS = 0.6;
+/**
+ * Rec. 709 luma, 0 (black) → 1 (white), averaged over the pixels outside
+ * `TONE_RIM_RADIUS × radius` of a `size × size` RGBA buffer. Pure, so the
+ * maths is testable without a canvas.
+ */
+export declare function rimLuma(data: ArrayLike<number>, size?: number): number | null;
+/** Exported for tests. A `null` result is evicted so a later mount retries. */
+export declare const toneCache: Map<string, Promise<number | null>>;
+/**
+ * Average perceived lightness of an image's outer band, or `null` when it
+ * cannot be measured: no DOM/canvas (SSR), a decode failure, or a host
+ * without CORS headers (a tainted canvas throws on `getImageData`). The
+ * image's own `<img>` is untouched, so a non-CORS host still displays.
+ * Memoised per `src`; a `null` is not kept.
+ */
+export declare function measureRimTone(src: string): Promise<number | null>;
+export type ToneAlphas = {
+    hi: number;
+    lo: number;
+};
+/** Alphas at tone 0 (a black rim) and tone 1 (a white rim); linear between. */
+export type ToneEnds = {
+    dark: ToneAlphas;
+    light: ToneAlphas;
+};
+/** Tuned by eye on a dark and a light photo in both themes. */
+export declare const DEFAULT_TONE_ENDS: ToneEnds;
+/**
+ * Against a dark rim the white highlight glares, so it eases off and the
+ * shadow pushes up; against a pale rim the reverse. `tone` is clamped to
+ * [0, 1]. Defaults: `{ hi: 0.7 + 0.3t, lo: 0.6 − 0.4t }`.
+ */
+export declare function toneToAlphas(tone: number, ends?: ToneEnds): ToneAlphas;
+/**
+ * `measureRimTone` as state. Resets to `null` whenever `src` changes so a
+ * stale tone never lights the new image for a frame; a slow sample that
+ * lands after a change is dropped. Pass `enabled = status === "loaded"`.
+ */
+export declare function useRimTone(src: string | undefined, enabled?: boolean): number | null;

package/dist/tone.js

@@ -0,0 +1,123 @@
+"use client";
+/**
+ * Image tone sampling: how light is the band the rim overlays?
+ */
+import { useEffect, useState } from "react";
+/** 16² px is enough to average a rim. */
+export const TONE_SAMPLE_SIZE = 16;
+/** Pixels this far (in radii) from the centre count as rim — the band the
+ * bezel sits on. Matches the ring's mask, which fades in from ~78%. */
+export const TONE_RIM_RADIUS = 0.6;
+/**
+ * Rec. 709 luma, 0 (black) → 1 (white), averaged over the pixels outside
+ * `TONE_RIM_RADIUS × radius` of a `size × size` RGBA buffer. Pure, so the
+ * maths is testable without a canvas.
+ */
+export function rimLuma(data, size = TONE_SAMPLE_SIZE) {
+    const centre = (size - 1) / 2;
+    const rim = TONE_RIM_RADIUS * centre;
+    let sum = 0;
+    let count = 0;
+    for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+            const dx = x - centre;
+            const dy = y - centre;
+            if (dx * dx + dy * dy < rim * rim)
+                continue;
+            const o = (y * size + x) * 4;
+            const r = data[o] ?? 0;
+            const g = data[o + 1] ?? 0;
+            const b = data[o + 2] ?? 0;
+            sum += (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+            count++;
+        }
+    }
+    return count === 0 ? null : sum / count;
+}
+/** Exported for tests. A `null` result is evicted so a later mount retries. */
+export const toneCache = new Map();
+/**
+ * Average perceived lightness of an image's outer band, or `null` when it
+ * cannot be measured: no DOM/canvas (SSR), a decode failure, or a host
+ * without CORS headers (a tainted canvas throws on `getImageData`). The
+ * image's own `<img>` is untouched, so a non-CORS host still displays.
+ * Memoised per `src`; a `null` is not kept.
+ */
+export function measureRimTone(src) {
+    if (!src)
+        return Promise.resolve(null);
+    const cached = toneCache.get(src);
+    if (cached)
+        return cached;
+    const promise = new Promise((resolve) => {
+        if (typeof document === "undefined" || typeof Image === "undefined") {
+            resolve(null);
+            return;
+        }
+        const image = new Image();
+        image.crossOrigin = "anonymous";
+        image.decoding = "async";
+        image.onerror = () => resolve(null);
+        image.onload = () => {
+            try {
+                const size = TONE_SAMPLE_SIZE;
+                const canvas = document.createElement("canvas");
+                canvas.width = size;
+                canvas.height = size;
+                const context = canvas.getContext("2d", { willReadFrequently: true });
+                if (!context) {
+                    resolve(null);
+                    return;
+                }
+                context.drawImage(image, 0, 0, size, size);
+                resolve(rimLuma(context.getImageData(0, 0, size, size).data, size));
+            }
+            catch {
+                resolve(null);
+            }
+        };
+        image.src = src;
+    });
+    toneCache.set(src, promise);
+    void promise.then((tone) => {
+        if (tone === null)
+            toneCache.delete(src);
+    });
+    return promise;
+}
+/** Tuned by eye on a dark and a light photo in both themes. */
+export const DEFAULT_TONE_ENDS = { dark: { hi: 0.7, lo: 0.6 }, light: { hi: 1, lo: 0.2 } };
+/**
+ * Against a dark rim the white highlight glares, so it eases off and the
+ * shadow pushes up; against a pale rim the reverse. `tone` is clamped to
+ * [0, 1]. Defaults: `{ hi: 0.7 + 0.3t, lo: 0.6 − 0.4t }`.
+ */
+export function toneToAlphas(tone, ends = DEFAULT_TONE_ENDS) {
+    const t = Math.min(1, Math.max(0, tone));
+    return {
+        hi: ends.dark.hi + (ends.light.hi - ends.dark.hi) * t,
+        lo: ends.dark.lo + (ends.light.lo - ends.dark.lo) * t,
+    };
+}
+/**
+ * `measureRimTone` as state. Resets to `null` whenever `src` changes so a
+ * stale tone never lights the new image for a frame; a slow sample that
+ * lands after a change is dropped. Pass `enabled = status === "loaded"`.
+ */
+export function useRimTone(src, enabled = true) {
+    const [tone, setTone] = useState(null);
+    useEffect(() => {
+        setTone(null);
+        if (!enabled || !src)
+            return;
+        let cancelled = false;
+        void measureRimTone(src).then((t) => {
+            if (!cancelled)
+                setTone(t);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [src, enabled]);
+    return tone;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@exegia/specular",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emmanuel-defreitas/specular.git"
+  },
+  "description": "Specular lighting for Tailwind v4 + React: pointer-tracking rim highlights, two-layer inset bezels as utilities, and a tailwind-merge config that keeps them alive in cn().",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
+    "./merge": {
+      "types": "./dist/merge.d.ts",
+      "import": "./dist/merge.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "tsc --noEmit",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "smoke": "node --test src/plugin.smoke.test.ts"
+  },
+  "peerDependencies": {
+    "react": "^19",
+    "tailwind-merge": "^3",
+    "tailwindcss": "^4.1 <5"
+  },
+  "peerDependenciesMeta": {
+    "tailwind-merge": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.18",
+    "react": "^19.2.8",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "~5.9"
+  }
+}