@exegia/specular 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emmanuel De Freitas
+
+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,10 +1,32 @@
+<div align="center">
+
+<img src="assets/logo.svg" alt="" width="132" height="132">
+
 # @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.
+**✨ Specular lighting for Tailwind v4 + React — a two-layer inset bezel as
+utilities, a `cn()` that keeps them alive, and a rim highlight that tracks the
+pointer.**
+
+[![npm](https://img.shields.io/npm/v/@exegia/specular?color=6366f1&labelColor=1c1917)](https://www.npmjs.com/package/@exegia/specular) [![types](https://img.shields.io/npm/types/@exegia/specular?color=38bdf8&labelColor=1c1917)](https://www.npmjs.com/package/@exegia/specular) [![provenance](https://img.shields.io/badge/npm-provenance-a855f7?labelColor=1c1917)](https://www.npmjs.com/package/@exegia/specular#provenance) [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-f43f5e?labelColor=1c1917)](#install) [![license](https://img.shields.io/npm/l/@exegia/specular?color=fbbf24&labelColor=1c1917)](LICENSE)
+
+<img src="assets/demo.gif" alt="Six avatars whose rim highlights turn to follow the pointer as it moves across them" width="100%">
+
+<sub>Six discs, one window listener. Recorded from <a href="examples/vite-react"><code>examples/vite-react</code></a>.</sub>
+
+</div>
+
+---
+
+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.
+
+## Install
+
+```bash
+npm i @exegia/specular      # or: bun add / pnpm add / yarn add
+```
 
 | export | contents |
 |---|---|
@@ -97,8 +119,8 @@ For a surface `S` and a layer `L`. Every utility also emits the base
 | 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` | the base `box-shadow` only: layer `L` at its configured alpha, so the `dark` preset applies |
+| `S-L/40`, `S-L/[0.4]` | `--tw-S-L-alpha: 40` (fractions are scaled; `/80` ≡ `/[0.8]`); `/100` is explicit full strength |
 | `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` |

package/dist/plugin.js

@@ -20,6 +20,9 @@ export function normalizeAlpha(raw) {
         return String(Math.round(parseFloat(v) * 10000) / 100);
     return v;
 }
+/** The `DEFAULT` value handed to the bare layer class. A sentinel, not a
+ * number, so `S-L-[100]` (an arbitrary value) still writes the alpha. */
+const CONFIGURED = "configured";
 const instanceVar = (s, l, p) => `--tw-${s}-${l}-${p}`;
 const presetVar = (s, l, p) => `--${s}-${l}-${p}`;
 function chain(s, l, p) {
@@ -75,8 +78,14 @@ export function createPlugin(surfaces, options = {}) {
                 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" });
+                // Bare = the configured alpha: the class emits only the composed
+                // box-shadow, so the alpha chain falls through to the preset (the
+                // `dark` block) and then the config. Writing 100 here would make the
+                // canonical `bezel-lit bezel-dim` ignore both. `/40` and `/[0.4]` = 40;
+                // `/100` is the explicit full-strength form.
+                matchUtilities({
+                    [n]: (value, { modifier }) => modifier === null && value === CONFIGURED ? base : { ...base, [v("alpha")]: normalizeAlpha(modifier ?? value) },
+                }, { values: { DEFAULT: CONFIGURED }, 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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/specular",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/emmanuel-defreitas/specular.git"