cssints 0.3.0 → 0.4.0

package/docs/API.md

@@ -1084,8 +1084,10 @@ More plugins on `scope()`, each a package of its own with its rules and limits i
 | [`@cssints/layout`](../packages/layout/README.md)           | `stack()`, `cluster()`, `sidebar()`, `switcher()`, `cover()`, `autoGrid()`                     | Every Layout primitives as chain members                                                                                                                                  |
 | [`@cssints/fonts`](../packages/fonts/README.md)             | `font(family, { provider, ... })` → `.family()`, `.trim()`                                     | `@font-face` and a metric-matched fallback face; cap-height trimming by `text-box`, else capsize's margins                                                                |
 | [`@cssints/reset`](../packages/reset/README.md)             | `reset({ media?, prose? })`                                                                    | A modern reset in a top-level `@layer reset` declared before the engine's, below every style; `@cssints/reset/<baseline group>` keeps only the declarations of that group |
-| [`@cssints/tokens`](../packages/tokens/README.md)           | `/open-props`, `/radix`, `/flexoki`, `/reasonable-colors`                                      | DTCG data for `createTokens`                                                                                                                                              |
+| [`@cssints/tokens`](../packages/tokens/README.md)           | `/open-props`, `/radix`, `/flexoki`, `/reasonable-colors`, `/madoromi`                         | DTCG data for `createTokens`                                                                                                                                              |
 | [`@cssints/gradient`](../packages/gradient/README.md)       | `gradient(kind, direction, from, to, easing?, stops?)`                                         | Eased colour stops mixed in oklab at build time                                                                                                                           |
+| [`@cssints/gradient-2d`](../packages/gradient-2d/README.md) | `meshGradient(mesh)`, `freeformGradient(points)`                                               | `mesh-gradient()` / `freeform-gradient()` where the browser has them, else a runtime's canvas (this package's algorithms; lines and shapes not yet)                       |
+| [`@cssints/color-names`](../packages/color-names/README.md) | `named(name)`, `colorNames.<sector>(name)`, `/nearest`                                         | The Color Name List (31,939 names) as hex colours; the ten sector members keep an editor's completion short, `nearest()` is the build-time reverse lookup                 |
 | [`@cssints/motion`](../packages/motion/README.md)           | `motion().preset().duration().delay().easing()`                                                | Animation presets over `keyframes()`, with reduced motion                                                                                                                 |
 | [`@cssints/squircle`](../packages/squircle/README.md)       | `squircle().radius()`                                                                          | `corner-shape: squircle`, else a CSS `mask` of the same shape                                                                                                             |
 | [`@cssints/reveal`](../packages/reveal/README.md)           | `reveal().preset().range().duration().easing()`                                                | motion's entrance presets on `animation-timeline: view()`; for other targets a script plays it once on entry (delivered by the runtime)                                   |
@@ -1248,6 +1250,10 @@ The process must end the exporter or Node stays alive: `vite build` and `server.
 
 `packages/cssints/test/trace.mjs` (in `bun run test`) checks the spans, the file attribute and the error's trace id against an in-process collector. `node packages/cssints/test/trace-live.mjs` builds apps/csssky and runs its HMR test traced, then reads both traces back through Jaeger's API (`GET /api/traces?service=cssints`) and prints span counts and the slowest hooks; it skips when no backend answers. Effect's DevTools (the VS Code extension, `effect/devtools`) is not wired: it needs the editor's extension listening, so neither a script nor an agent can read it.
 
+### Debugging: the limit of an evaluation (`CSSINTS_EVAL_TIMEOUT`, cssints-joex)
+
+A module is evaluated with all it imports in at most 30 seconds, else the build fails with `cssints: evaluating <file> took more than 30 seconds`. The engine cannot stop the code, so it closes the Module Runner: the evaluation ends at the next module it would load, and the next evaluation starts on a new runner. `CSSINTS_EVAL_TIMEOUT=<milliseconds>` changes the limit (read once, when the plugin loads); it is for tests that run on a busy machine, and the default is the one for your code.
+
 ### Checks for tools: `cssints/check` (2026-10-09, cssints-p3d2)
 
 The engine's own checks, as functions, for a tool that answers as a build would (`@cssints/mcp`). Node only (culori, LightningCSS): nothing here reaches a browser, and user code has no reason to import it. Each returns an Effect.
@@ -1370,6 +1376,103 @@ process.stdin.on("data", (bytes) => dispatch(input.scan(follow.feed(bytes)).even
 - **Live in the browser** (cssints-ey13, 2026-10-11). [The TUI page](https://cssints.dev/tui) of this site runs apps/csssky-tui's styles on `@cssints/tui/bomb` in a real terminal: Ghostty's emulator compiled to WebAssembly (ghostty-web) draws csssky's feed and thread from its recorded fixtures, with keys and the mouse. The page is the terminal: it answers the system theme's queries (OSC 10, 11, 4, `CSI ? 996 n`) from the site's display settings and reports a change of them (mode 2031), so the theme is solved again as the palette or the mode changes. OpenTUI is not shown: its renderer is native Zig over `bun:ffi`. On a change notification, `followSystemTheme` of `@cssints/tui/bomb` asks the colours again (`COLOURS` of `@cssints/tui/system`), not the scheme report: its reply is the same sequence as a notification, and asking it looped with a terminal that answers it.
 - **Cost.** A colour member costs what the same web member costs in the types (the `color` grammar); `bench/tui.ts` is 184k instantiations (tsc) for 16 calls and a token set. No terminal HMR in this version. The system theme brings culori's rgb, oklab, oklch and okhsl modes to the app (45 kB unminified in csssky-tui's bundle).
 
+### Clay: `cssints/clay` (2026-10-19, cssints-iwey)
+
+A native UI laid out by [Clay](https://github.com/nicbarker/clay), with no browser and no JS where it runs (an ESP32's firmware), writes its styles with `cssints/clay`. The same Vite plugin compiles each site to an object literal shaped as Clay's own structs, and `header()` prints a module of them as C initializers:
+
+```ts
+import * as css from "cssints/clay" with { type: "cssints" };
+
+export const pill = css.cn(
+  css.width(200),
+  css.height(38),
+  css.justifyContent("center"),
+  css.alignItems("center"),
+  css.bg("rgb(36 40 52)"),
+  css.borderRadius(19),
+  css.border(1, "#969baa"),
+);
+export const label = css.cn(css.color("#ebebf0"), css.fontSize(14));
+css.width("10rem"); // error: Clay counts pixels
+css.boxShadow("0 0 1px red"); // error: no such member in Clay
+```
+
+```c
+static const Clay_ElementDeclaration pill = { .layout = { .sizing = { .width = { .size = { .minMax = { 200, 200 } }, .type = CLAY__SIZING_TYPE_FIXED }, ... }, .backgroundColor = { .r = 36, .g = 40, .b = 52, .a = 255 }, ... };
+static const Clay_TextElementConfig label_text = { .textColor = { .r = 235, .g = 235, .b = 240, .a = 255 }, .fontSize = 14 };
+```
+
+```c
+CLAY(CLAY_ID("Units"), pill) { CLAY_TEXT(CLAY_STRING("switch to g"), label_text); }
+```
+
+- **Members**: `width`, `height` (pixels, `N%`, `auto` for Clay's FIT, `stretch` for GROW), `padding`/`p` and the sides, `gap` (`childGap`), `flexDirection` (`row`, `column`), `justifyContent` and `alignItems` (start, center, end: Clay's `childAlignment`, the axis from `flexDirection`), `backgroundColor`/`bg`, `borderRadius`, `border(width, colour)`, `borderWidth`, `borderColor`, `overflow("hidden")` (`clip`), `float()` (`floating`, below), and for text `color`, `fontSize`, `letterSpacing`, `lineHeight`, `textAlign`, `whiteSpace` (`wrapMode`); `cn` merges, a later prop wins. Any other property is not a member.
+- **Pixels.** A number or `"Npx"`; padding, gap and border widths are whole numbers (`uint16_t` in Clay). Another unit is a type error and a build error.
+- **Colours** are checked by the web's `color` grammar, or are colour tokens of cssints/clay's `createTokens`, and are written as 0-255 `r g b a`.
+- **`header(exports)`** prints a `Clay_ElementDeclaration` per export and, for one with text props, a `Clay_TextElementConfig` named `<name>_text`. A field it does not set is zero, which is Clay's default.
+- **States**: `hover`, `focus`, `active` wrap styles. Clay has no states, so the literal has an overlay per state (`":active": { backgroundColor }`, the fields the state sets, at their values over the base), and `header()` prints the whole declaration again, `<name>_active` (`<name>_hover_text` for text): the page asks Clay and picks one, nothing is merged in C. States do not nest.
+- **Tokens and themes**: `createTokens` and `createGlobalTheme(tokens, name, overrides)` of cssints/clay, on tables of their own (a web or terminal token is not a Clay one, and a theme of one is a build error). Resolved at build time: a site has its colours at the tokens' values and, under `themes`, what each theme changes. `header()` prints every style of a module with a theme again, the theme's name last (`units_light`, `units_active_light`, `title_text_light`), so a page switches at run time by a suffix. A style sees the themes evaluated before it: declare them first, or in a module it imports.
+- **Fonts**: `fonts("Roboto", "Mono")` is the order of the app's font array; `.Mono` is a style that sets Clay's `fontId` to 1, and `header()` prints the order as an enum, `font_Roboto = 0, font_Mono = 1` (the export's name, then the font's).
+
+```ts
+import * as css from "cssints/clay" with { type: "cssints" };
+
+export const t = css.createTokens({
+  color: { $type: "color", surface: { $value: "rgb(36 40 52)" }, pressed: { $value: "#ffc878" } },
+});
+css.createGlobalTheme(t, "light", { color: { surface: "white" } });
+export const font = css.fonts("Roboto", "Mono");
+
+export const units = css.cn(
+  css.width(200),
+  css.bg(t.color.surface),
+  css.active(css.bg(t.color.pressed)),
+);
+export const label = css.cn(font.Mono, css.fontSize(14));
+css.cn(font.Serif); // error: not one of the fonts
+```
+
+```c
+#define T(name) (light ? name##_light : name)
+CLAY(CLAY_ID("Units"), pressed ? T(units_active) : T(units)) { CLAY_TEXT(CLAY_STRING("switch to g"), label_text); }
+```
+
+- **Floating elements**: `float({ ... })` fills Clay's `floating`, the foundation of menus, popovers and dialogs. Every option is optional, and what it leaves out is Clay's own default, so `header()` prints only what is set (`float()` alone is `{ .attachTo = CLAY_ATTACH_TO_PARENT }`). The name is `float` as in CSS: it is a valid binding, and no other Clay member shares it.
+
+  | Option                        | Clay field                                                                                                                                                 | Default                                                   |
+  | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+  | `attach: { element, parent }` | `attachPoints`: which point of the float sits on which point of its parent, each `"left top"`, `"center center"`, `"right bottom"`, ... (x, then y)        | `left top` on `left top`                                  |
+  | `parent: "Units"`             | `parentId` and `attachTo = ELEMENT_WITH_ID`: the string of the parent's `CLAY_ID("Units")` (ASCII; a `CLAY_IDI` or local id is not one)                    | the element the float is a child of (`attachTo = PARENT`) |
+  | `root: true`                  | `attachTo = ROOT`: absolute positioning, a dialog on the screen (not with `parent`)                                                                        | off                                                       |
+  | `offset: { x, y }`            | `offset`: pixels from where `attach` puts it; a negative number goes left or up                                                                            | 0, 0                                                      |
+  | `expand: { width, height }`   | `expand`: pixels the float's own box grows by, its children's not; not negative                                                                            | 0, 0                                                      |
+  | `zIndex`                      | `zIndex`: a whole number, `int16_t`; floats draw in ascending order, with their children                                                                   | 0                                                         |
+  | `capture: false`              | `pointerCaptureMode = PASSTHROUGH`: the pointer reaches what lies under the float (`true` is `CAPTURE`)                                                    | `true`                                                    |
+  | `clip: "parent"`              | `clipTo = ATTACHED_PARENT`: clipped to the box its parent is clipped to (`"none"` is `CLIP_TO_NONE`; with `root` it has nothing to clip to, a build error) | `"none"`                                                  |
+
+  `parentId` is printed as a number, the hash of the id (`Clay__HashString(id, 0)` computed at build time), because `CLAY_ID()` is a call and a `static const` initializer takes constants. A misspelt id is Clay's own `FLOATING_CONTAINER_PARENT_NOT_FOUND` error at run time. A bad value, an option that does not exist, a negative `expand`, a non-ASCII id are build errors (the types catch what a type can: a point such as `"top left"`, an unknown option). Two floats merge in a `cn()` as the other members do: the later one's options win and the rest stay; a state (`hover(float(...))`) is a declaration of its own.
+
+```ts
+import * as css from "cssints/clay" with { type: "cssints" };
+
+export const menu = css.cn(
+  css.width(160),
+  css.bg("#242834"),
+  css.float({ parent: "Units", attach: { parent: "left bottom" }, offset: { y: 4 }, zIndex: 10 }),
+);
+export const dialog = css.float({
+  root: true,
+  attach: { element: "center center", parent: "center center" },
+});
+css.float({ attach: { element: "top left" } }); // error: a point is x, then y
+```
+
+```c
+static const Clay_ElementDeclaration menu = { .layout = { ... }, .backgroundColor = { ... }, .floating = { .offset = { .x = 0, .y = 4 }, .parentId = 3516868942u, .zIndex = 10, .attachPoints = { .element = CLAY_ATTACH_POINT_LEFT_TOP, .parent = CLAY_ATTACH_POINT_LEFT_BOTTOM }, .attachTo = CLAY_ATTACH_TO_ELEMENT_WITH_ID } };
+```
+
+- **Not yet**: min and max sizes, derived colour tokens (`color-mix()` of tokens: a colour Clay is given must parse as one), a theme under a condition (a theme is a name; `media()` has no meaning on a board).
+
 ### Export groups: `cssints/widely-available`, `cssints/css-grid-2`, … (decided 2026-10-11, cssints-n7z3)
 
 A group is a subpath of `cssints` that exports the members of `cssints` which a set of CSS features has, and refuses a value that holds a feature outside the set. It is the same import (`with { type: "cssints" }`), the same members, the same classes:
@@ -1399,7 +1502,7 @@ color("color-mix(in oklab, red, blue)"); // error: color: "color-mix()" is not i
 ```
 
 - **Baseline groups** (web-features 3.42, the status of each BCD key): `widely-available` is Baseline high, `newly-available` is high and low, `limited-availability` is everything (it is `cssints` itself, under its Baseline name) and `not-discouraged` is everything web-features does not mark `discouraged` (`clip`, the `page-break-*` aliases, `ime-mode`, `word-break: break-word`, `text-decoration-line: blink`, device media features). A feature web-features does not know is limited availability.
-- **Downstream groups** (cssints-n12x, 2026-10-11): `widely-available/with-downstream` and `newly-available/with-downstream` are the Baseline group also checked against Opera, Opera Mobile, Samsung Internet, Android WebView, UC and QQ, as `browserslist-config-baseline/with-downstream` is. A feature is in one when the Baseline group has it and every one of those browsers has it, by BCD, at the minimum version that [baseline-browser-mapping](https://www.npmjs.com/package/baseline-browser-mapping) 2.11.28 gives for the target (the rule of the support warnings: no prefix, no flag; UC and QQ are Blink, checked as Chrome at the Blink version of that build). `widely-available/with-downstream` has 520 of the 521 members (not `maskImage`: Opera has `-webkit-mask-image` only) and refuses `inline-size: fit-content` (Samsung Internet), `shape-outside: xywh()` and `prefers-contrast`; `newly-available/with-downstream` has 533 of 567 (UC and QQ are on Blink 123 and 121).
+- **Downstream groups** (cssints-n12x, 2026-10-11): `widely-available/with-downstream` and `newly-available/with-downstream` are the Baseline group also checked against Opera, Opera Mobile, Samsung Internet, Android WebView, UC and QQ, as `browserslist-config-baseline/with-downstream` is. A feature is in one when the Baseline group has it and every one of those browsers has it, by BCD, at the minimum version that [baseline-browser-mapping](https://npmx.dev/package/baseline-browser-mapping) 2.11.28 gives for the target (the rule of the support warnings: no prefix, no flag; UC and QQ are Blink, checked as Chrome at the Blink version of that build). `widely-available/with-downstream` has 520 of the 521 members (not `maskImage`: Opera has `-webkit-mask-image` only) and refuses `inline-size: fit-content` (Samsung Internet), `shape-outside: xywh()` and `prefers-contrast`; `newly-available/with-downstream` has 533 of 567 (UC and QQ are on Blink 123 and 121).
 - **Baseline years:** `baseline-2015` to `baseline-2026` (the first year web-features has to the current one) and `baseline-YYYY/with-downstream`, as `browserslist-config-baseline/YYYY` has them. `baseline-YYYY` is **cumulative**: what was Baseline (newly available, `baseline_low_date`) by the end of YYYY, so `baseline-2022` refuses `color-mix()` (2023) and `baseline-2023` refuses `light-dark()` (2024). 220 members in `baseline-2015`, 387 in `baseline-2020`, 537 in `baseline-2024`. `baseline-2026` is `newly-available` today.
 - **Spec groups** are named by the W3C shortname that @webref/css uses: `cssints/css-grid-2`, `cssints/css-color-4`, `cssints/mediaqueries-4`, `cssints/selectors-4`, … (92 of them). A group holds what the spec defines, and **a level includes the levels of its series before it**: `css-color-5` has what Color 3, 4 and 5 define, `css-color-4` has Color 3 and 4. A level is a delta (Color 5 over Color 4) or a rewrite (Media Queries 4 over 3), and "I write for Color 5" means both. What only a later level defines is refused: `css-color-4` has no `colorMix` and refuses `color-mix()`, `mediaqueries-4` refuses `prefers-color-scheme`. A group has the properties, functions, pseudo-class wrappers and conditions its spec defines, so `display` is in `css-display-4` and `gridTemplateColumns` in `css-grid-2`: import from several groups in one file.
 - **What is a member:** the properties (and their short names), the functions, the pseudo-class wrappers, `media`, `container`, `supports`, `keyframes` and `positionTry`. Everything else (`cn`, `cv`, `firstThatWorks`, `token`, `createTokens`, `createGlobalTheme`, `check`, `style`, `global`, `layers`, `attr`, `within`, `group`, the Typed OM values) is in every group. A group has no `css` object: write `import * as css from "cssints/widely-available"`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssints",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CSS in TypeScript: typed css.* calls compiled to atomic CSS at build time (a Vite plugin)",
   "license": "MIT",
   "repository": {
@@ -54,6 +54,10 @@
       "types": "./dist/tui-types.d.mts",
       "default": "./dist/tui.mjs"
     },
+    "./clay": {
+      "types": "./dist/clay-types.d.mts",
+      "default": "./dist/clay.mjs"
+    },
     "./devtools-link": {
       "types": "./dist/devtools-link.d.mts",
       "default": "./dist/devtools-link.mjs"
@@ -64,7 +68,7 @@
     }
   },
   "dependencies": {
-    "@cssints/css-grammar": "^0.3.0",
+    "@cssints/css-grammar": "^0.4.0",
     "culori": "^4.0.2",
     "effect": "4.0.0",
     "happy-dom": "^20.14.5",

package/skills/cssints/references/plugins.md

@@ -62,6 +62,18 @@ a suggestion.
 **`@cssints/gradient`**: `backgroundImage(gradient("linear", "to bottom", "#000", "transparent", "ease-in-out", 5))`:
 eased stops mixed in oklab. Each argument its own string; the direction is one string (`"to bottom"`).
 
+**`@cssints/gradient-2d`**: `meshGradient("red, blue; green, yellow")` (rows from the top of the box down, separated by
+`;`, stops by `,`) and `freeformGradient("red top left, gold 4 60% 40%, yellow bottom right")` (points, an optional
+weight before the position). One string per call. Where the browser has `mesh-gradient()`, the declaration is native;
+elsewhere a runtime the build adds draws the same points on a canvas, so it needs a script.
+
+**`@cssints/color-names`**: `color(named("tangerine"))` is `#ff9300`. `colorNames.<sector>(name)` is the same name
+restricted to one sector (`red`, `orange`, `yellow`, `green`, `cyan`, `blue`, `purple`, `pink`, `brown`, `neutral`), so
+completion stays short; the colour word in the name picks the sector. An unknown name is a build error with the nearest
+one, and a name outside the sector is one that names the sectors it is in. The list's hex wins over the CSS keyword's
+(`named("green")` is `#00ff00`; `color("green")` is the CSS one). `@cssints/color-names/nearest` maps a hex to the
+closest name at build time.
+
 **`@cssints/placeholder`**: `backgroundImage(placeholder("src/hero.jpg"))` (a gradient of the image's colours) or
 `{ mode: "thumbhash" }` (a tiny PNG; pair it with `backgroundSize("cover")`). JPEG and PNG only; the path is relative
 to the working directory.

package/dist/group-common-9zpBxfUF.d.mts

@@ -1 +0,0 @@
-import "./theme-types-Bqv0Ggz_.mjs";