npm package: @kingoftac/postcss-plugin-random
Description: A PostCSS plugin for the upcoming CSS random() function.
Author: Nathan Brown
Latest version: 0.1.3

# postcss-plugin-random

> A PostCSS plugin that implements the CSS `random()` function as per the [CSS Values & Units Level 5 draft](https://drafts.csswg.org/css-values-5/#random). This plugin lets you generate random values (optionally stepped) directly in your CSS and supports value sharing semantics.

> [!CAUTION]
> This is an experimental implementation; some parts of the spec require browser/DOM context and are approximated at build time. See [limitations](#limitations) below.

## Roadmap
- [x] `random(min, max[, step])` with:
	- Unit/type consistency checks between `min`, `max` (and `step` if present)
	- Uniform selection; step logic with `epsilon = step / 1000` and “snap-to-max within epsilon”
- [x] `<random-value-sharing>` support (build-time approximation):
	- `auto` (default): distinct base value per function occurrence
	- `--dashed-ident`: shared base value for the same ident within a processing run
	- `element-shared`: shared base value globally within the processing run
	- `fixed <number>`: deterministic base value in `[0,1)` (1 is clamped to the next representable value below 1)
	- Property-aware caching keys (approximate `"PROPERTY N"`) to better mimic default sharing behavior
- [ ] Safer scanning (skip comments/strings; robust tokenization)
- [ ] `<calc-sum>` and percentage resolution (at least partial)
- [ ] Additional edge cases for argument ranges (NaN/Infinity)
- [ ] Add Playwright tests for coverage against the current WebKit implementation
- [ ] Proper demo and docs

### Examples
```
.random-rect {
	width: random(100px, 200px);
	height: random(100px, 200px);
}

.shared-named {
	width: random(--size, 100px, 200px);
	height: random(--size, 100px, 200px); /* same as width */
}

.shared-global {
	width: random(element-shared, 100px, 200px);
	height: random(element-shared, 100px, 200px); /* same across all matches */
}

.fixed {
	width: random(fixed 0.5, 100px, 200px);  /* 150px */
	height: random(fixed 0.5, 100px, 200px); /* 150px */
}
```

## Limitations
- Property-aware caching keys (the spec's default of `"PROPERTY N"`) are not yet implemented; this plugin currently can't know property names in a pure token stream. We simulate sharing through in-process cache keys (dashed ident/global) during the PostCSS run.
- We don't evaluate `<calc-sum>` (e.g. `calc()` or unit mixing). Such values are left as-is; numeric+unit prefixes are parsed only.
- NaN / Infinity edge cases are not fully modeled per spec's Argument Ranges; invalid ranges generally cause the original `random(...)` to be left unchanged.
- Scanning is naive: we don't skip comments/strings yet; nested functions are handled via basic parentheses counting only.
- Type consistency is verified via unit strings; more advanced CSS type resolution (percentages, font-relative units) would require layout context.

## Dev
install `wasm-pack` if you haven't already:
```shell
cargo install wasm-pack
```

The npm dev command will compile the wasm binary and bundle the demo CSS before serving the demo page.
```shell
npm run dev
```

To compile the wasm binary separately:
```shell
wasm-pack build --target nodejs
```