cssints 0.0.0-stage → 0.2.0

package/skills/cssints-plugin/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: cssints-plugin
+description: >-
+  Write or fix a cssints plugin: a module or package that exports members of scope() from "cssints/plugin" (kernels,
+  chain/call/value members, conflicts, runtimes with polyfills/css/script/parentVars, lacking(), group markers, token
+  themes). Load it when code imports scope, fn, arg or lacking from "cssints/plugin", when you design a new
+  @cssints/* package or a member like stack(), motion() or fluid(), when a build says "kernel ... sets",
+  "wraps ... the marker of kernel", "scope ... is defined twice", "share a name", "kernels ... both set", or a
+  declaration file fails with TS7056/TS2742, and when you write its fixtures, type tests or browser tests.
+---
+
+# cssints plugins on `scope()`
+
+A plugin is a module that exports the members of `scope(name, table).build(impl).export()` from `cssints/plugin`.
+The table says what the plugin has; the members are typed from it (no types file). User code imports the plugin with
+`with { type: "cssints" }`; there is no registration. In user code a member is a class string (or a CSS value), so it
+goes into `cn()` and conditions. Everything runs at build time in Vite's Module Runner. Read the user skill
+`cssints` first for the styles themselves; the full reference is the "Plugins" section of `docs/API.md`.
+
+If the cssints MCP server is configured, prefer `compile` to see a fixture's classes, sheet, errors and warnings,
+`check_declaration` for a kernel's declarations, `check_support` for the BCD keys of `requires`/`polyfills`, and
+`search_docs` for the API text.
+
+## The shape
+
+```ts
+import { scope } from "cssints/plugin";
+
+export const { ring } = scope("ring", {
+  "#core": {
+    css: (css) => [css.outline("var(--_w)", "solid", "var(--_c)"), css.outlineOffset("2px")],
+  },
+  ring: {
+    uses: ["core"],
+    chain: {
+      width: { args: "<length [0,∞]> | thin | thick", spacing: true, emit: (v) => [["--_w", v]] },
+      color: { args: "<color>", emit: (v) => [["--_c", v]] },
+    },
+  },
+}).export();
+// user code: cn(ring().width(1).color("red")) -> "_ring-core _a _b"; ring().width("red") is a type error
+```
+
+- **Names.** The scope name is lowercase letters, digits and `-`, unique in the process (`cssints`, `derived` are
+  taken). `--_x` anywhere in the scope is `--<scope>-x`; `&` in raw CSS is the kernel's class `_<scope>-<entry>`;
+  `&(mod.key)` is the class of a kernel of an embedded scope. Your CSS never writes the long names.
+- **Private keys** start with `#`: used by other entries, not exported. `uses` names them without the `#`, so `#trim`
+  beside a public `trim` is an error (`#trim and trim share a name: rename one`).
+- **A key is a name** (no dots). A member shown as `fluid.container` is a key `fluidContainer` with
+  `label: "fluid.container"`, attached by hand (`Object.assign`).
+- `.build({ member: fn })` holds the functions of call members; a scope with only chains and values skips it.
+
+The table entries by shape (syntax names, typed `-props`, kernels, globals, layers, runtimes, conflicts, token sets,
+embedded scopes, chain, call and value members): [references/table.md](references/table.md).
+
+## Kernels: styles or raw CSS
+
+A kernel is global CSS printed once in layer `_.k`, keyed to its marker class. Write it **as styles** by default:
+`css: (css) => [...]` gets the `css.*` members, checked by the grammar like a user's declarations, plus:
+
+- conditions: `css.hover(...)`, `css.media("(...)")(...)`, `attr()`, `within()`, `container()`, `supports()`;
+- `css.nest(selector)(...)` for other elements: one complex selector with `&` (the kernel's class) anywhere:
+  `"& > *"`, `"& > * + *"`, `".dark &"`, `":root:has(&)"` (a list is an error);
+- `css.vars({ "--_gap": "1rem" })` for custom properties (values not checked);
+- `keyframes()`/`positionTry()` names as values (`css.vars({ "--_k": fade })`): their rules go with the kernel; a
+  `css.keyframes({ from: css.vars({ "--_p": "100%" }) })` made in the kernel animates the scope's `--<scope>-p`.
+
+A styles kernel **derives its conflicts** (every property that meets one it sets, as `cn()` decides overlap) and its
+support warnings are **covered** by the `polyfills` of a runtime in the same `uses`. Raw CSS (`css: "&{...}"`) is still
+needed for:
+
+- at-rules the styles cannot write: `@container style(...)` alternation (frame, surface), `&&` specificity tricks;
+- a value the grammar does not know yet (write it raw, with a test that fails once the grammar has it);
+- a declaration whose support warning nothing should cover and nothing should print (balance's `pretty()`).
+
+Runtime fallback CSS (`@supports not (...) { & {...} }`) is a raw string in the runtime entry, not a kernel.
+
+A raw kernel derives no conflicts and is not compared with others: list a `conflicts` entry. Two styles kernels of
+one member that set one element property are an error (`kernels zap and view both set animation, ...: write those in
+one kernel`). `atProperty` holds `@property` rules; `requires` holds BCD keys (warnings, never errors);
+`{ key, exact: true }` counts a partial implementation as lacking.
+
+A kernel cannot be conditional per site. A member whose style is only markers (no declarations: no method, no
+arguments) under `hover()` or `media()` is a build error (`:hover wraps _x-core, the marker of kernel x.core, with no
+declaration of its own`). Give the member methods that set custom properties; the kernel reads them, and a condition
+can wrap a method.
+
+## Members
+
+- **Chain** `{ uses, chain: { m: { args, spacing?, excludes?, emit } } }`: `x().m(v)`, each method once. `args` is a
+  grammar of the parts (`""` for no value); `spacing: true` makes a bare number a 0.25rem step; `emit(v)` returns
+  `[prop, value][]` (custom properties unchecked, others checked). Write grammars as literals (`as const` on a
+  `const` string).
+- **Call** `{ args, uses? }` plus `build({ x: (...args) => ({ decls?, uses?, globals?, themes?, layers? }) })`. `args`:
+  a grammar, `arg<T>()` (a TypeScript value, as is), or a tuple of positions: grammars, `"$tokens"`, `"$overrides"`
+  (checked against the `$tokens` before it), `"$selector"`, `arg<T>()`, and at the end one object of named leaves
+  (`{ "size?": "<length>" }`). Use `args: []` for a member with no arguments.
+- **Value** `{ args, value, label? }`: returns a CSS value, not a class. `value` gets the parts as text (a token as
+  its `var(--name)`). With a tuple or `arg<T>()` write `fn({ args, value })`. Return a Typed OM value to keep the
+  type (`new CSSColorValue(...)`, `CSS.rem()`, `class X extends CSSStyleValue<"length">`, `CSSImageValue`, all from
+  `"cssints"` without the attribute in a plugin module); a string (a template literal too) is opaque to the types
+  and checked where it lands.
+- **`group: true`** on a chain or call member adds the group marker `_g-<scope>`, so
+  `within(attr("data-stuck", "top", "~="), "<scope>")(...)` reads that element. One group per scope.
+- **Typed properties**: a key that starts with `-` and a grammar (`"-webkit-font-smoothing": "auto | antialiased"`)
+  is exported camel-cased (`webkitFontSmoothing`). A property mdn-data knows is an error: use `css.<name>`.
+- **Plain functions** the plugin exports (wrapping the user's styles, as `stuck(...styles)`) are fine; anything they
+  throw while a site runs is located at that site.
+
+## Conflicts
+
+- **Derived** from styles kernels: `cn(stack(), display("grid"))` gives
+  `layout: kernel stack-core sets display, flex-direction, gap (this style also sets display)`. Custom properties and
+  `nest()` rules on another subject are left out (a child's margin is not the element's; `.dark &` and `&.on` are
+  the element and count).
+- **Explicit** `{ props: ["outline", /^outline-/], message: "ring() sets the outline: use its methods" }` in `uses`
+  **replaces** what the kernels derive; `props: []` allows everything. Needed for raw kernels, and when a member
+  emits a property its own kernel sets (the check reads the member's emits too).
+
+## Runtimes: fallbacks for targets that lack a feature
+
+`"#fb": { polyfills: [bcdKeys], css?, script?, parentVars? }` in a member's `uses`. A client module that uses the
+member imports `virtual:cssints/runtime/<scope>.<entry>`; it is empty (`export {};`) unless a browserslist target
+lacks a key.
+
+- `css`: fallback rules, added to `_.k` only then (usually `@supports not (...) { & {...} }`); reaches every target.
+- `script`: a module specifier the runtime module imports (`"@cssints/reveal/runtime"`), never evaluated at build
+  time. Ship it as a package subpath with a `development` condition for `src/`; it probes the feature itself
+  (`CSS.supports`) and does nothing where it is native. Reaches every target.
+- `parentVars: { marker: "&", read, write, watch? }`: the shared `cssints/parent-vars` script copies custom
+  properties from parent to child; it stands on `@property`, so it reaches only targets that have it.
+- Coverage: a `requires` key or a styles-kernel warning whose BCD key is in `polyfills` warns only for targets the
+  runtime does not reach. Match keys exactly (the key is in parentheses at the end of the warning).
+- `lacking(...keys)` returns the build's targets that lack a key (`["firefox 140"]`, `[]` when none): emit fallback
+  rules or styles only when needed (`stuck()` adds its attribute rules only then).
+- `dependsOn(path)`: call it for every file the plugin reads (an image, an SVG, a font). In dev an edit of the file
+  runs the modules that read it again; in `vite build --watch` it is a watched file.
+
+## Errors
+
+What `build`, `value`, `emit` or a kernel's styles throw is a located `MemberError` at the call, prefixed with the
+scope. Throw `new Error("cssints: <scope>: <what>, <what to do>")`; name the value and the fix. The grammar errors of
+`args` come for free (`ring.width: unexpected "red" ...`, a tuple's `tint.shade(2).by: ...`).
+
+## Exporting, packaging
+
+When the inferred type is too long to print (TS7056) or names an internal file (TS2742) in `vp pack`/`dts`:
+
+```ts
+const balanceScope = scope("balance", { ... }).build({ balance: () => ({}) });
+type Members = ReturnType<typeof balanceScope.export>;
+const members: Members = balanceScope.export();
+export const balance: Members["balance"] = members.balance;
+```
+
+A package: `cssints` in `peerDependencies`; `exports` with `development` (src) before `types`/`default` (dist); a
+`./runtime` subpath for a script (with `sideEffects` listing it); no `.css` file. Export the scope itself
+(`export const motionScope = ...`) when another plugin should embed it.
+
+## Testing
+
+Fixtures through the engine (output, errors, a re-run per `BROWSERSLIST`), a type test with `@ts-expect-error`, and
+`test:browsers` with a control that must fail: [references/testing.md](references/testing.md).
+
+## Checklist
+
+- [ ] Scope name unique and lowercase; private keys for everything that is not a member.
+- [ ] Kernels as styles unless one of the raw cases above; raw kernels have a `conflicts` entry.
+- [ ] Every member that may go under a condition has a method or argument that emits a declaration.
+- [ ] Defaults of custom properties set on the kernel (`vars()`), so a nested member does not inherit its parent's.
+- [ ] `requires` lists the BCD keys; each has a runtime in `polyfills`, or the warning is intended.
+- [ ] Fallback CSS and scripts only when `lacking()` or a runtime says so; a script probes and stays off natively.
+- [ ] Errors name the scope, the value and the fix; grammars are literals.
+- [ ] Fixtures: output, each error, `BROWSERSLIST` modern and old, the runtime module empty or not.
+- [ ] Type test: valid calls typed `string` (or the value type), invalid ones under `@ts-expect-error`.
+- [ ] Browser test (if there is a runtime or a visual claim): native, fallback forced, and a control that fails.
+- [ ] README: example, the CSS it prints, rules, browsers, limits; `docs/API.md` table row if in the cssints repo.

package/skills/cssints-plugin/references/table.md

@@ -0,0 +1,124 @@
+# The entries of a `scope()` table
+
+Entries are told apart by their shape. A key that starts with `#` is private (not exported, invisible to an embedding
+scope); `uses` names it without the `#`. `--_x` is `--<scope>-x` everywhere in the scope; in raw CSS `&` is the
+kernel's class and `&(mod.key)` the class of a kernel of an embedded scope.
+
+| Shape                                             | What it is                                                                                |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `width: "<length [0,∞]> \| thin"`                 | A local syntax name: `<width>` in this scope's grammars                                   |
+| `"-webkit-font-smoothing": "auto \| antialiased"` | A typed property not in mdn-data, exported camel-cased (`webkitFontSmoothing`)            |
+| `{ css, atProperty?, requires? }`                 | A kernel: `css` a string (raw) or `(css) => style \| style[]`                             |
+| `{ rule, layer? }`                                | A global rule (no class), identified by its content                                       |
+| `{ layers: ["app", "viewer"], before? }`          | Top-level layers, after the engine's (or before with `before: true`)                      |
+| `{ polyfills, css?, script?, parentVars? }`       | A runtime: the fallback for targets that lack a BCD key                                   |
+| `{ props, message }`                              | Conflicts: a `cn()` with the member and one of `props` (names or RegExps) is an error     |
+| `{ tokens }`                                      | A token set from `createTokens`: `<tokens.color.accent>` in grammars is that token's type |
+| `mod: otherScope`                                 | An embedded scope: `uses: ["mod.key"]`, `<mod.name>` in grammars, `&(mod.key)` in raw CSS |
+| `{ uses?, group?, chain: { ... } }`               | A chain member: `x().m(v).n(w)`                                                           |
+| `{ args, uses?, group? }`                         | A call member: its function is the entry of the same name in `.build({ ... })`            |
+| `{ args, value, label? }` / `fn({ ... })`         | A value member: returns a CSS value (`fn()` when `args` is a tuple or `arg<T>()`)         |
+
+## Kernels
+
+```ts
+"#core": {
+  css: (css) => [
+    css.vars({ "--_gap": "1rem", "--_fade": fade }), // defaults on the element; a keyframes() name carries its rule
+    css.display("flex"),
+    css.animation("var(--_fade) 200ms"),
+    css.hover(css.opacity(0.8)),
+    css.media("(width >= 40rem)")(css.padding("1rem")),
+    css.nest("& > * + *")(css.marginInlineStart("var(--_gap)")), // another subject: & anywhere
+  ],
+  requires: ["css.at-rules.property", { key: "css.types.color.oklch.relative_syntax", exact: true }],
+},
+"#raw": {
+  css: "& { --_x: 1 } &(base.mark) > & { --_y: 2 }",
+  atProperty: '@property --_w { syntax: "<length>"; inherits: false; initial-value: 2px; }',
+},
+```
+
+- Printed once in `_.k`, sorted by key (`<scope>.<entry>`), whatever the order of `uses`; at-rule kernels
+  (`keyframes()`) before the kernel that names them. A styles kernel prints in the sheet's order (a shorthand before
+  its longhands; fewer conditions first), so the order you write does not matter.
+- Not allowed in a styles kernel: `firstThatWorks()`, a member's marker (another plugin member), `nest()` without an
+  `&` or with a selector list.
+- Build errors: two keys that declare one custom property, two keys that print one marker, two styles kernels of one
+  member that set one element property.
+
+## Chain members
+
+```ts
+ring: {
+  uses: ["core", "fallback"],
+  group: true, // adds _g-<scope> after the kernel markers
+  chain: {
+    width: { args: "<width>", spacing: true, emit: (v) => [["--_w", v]] },
+    color: { args: "<color>", emit: (v) => [["--_c", v]] },
+    plain: { args: "", excludes: ["color"], emit: () => [["--_c", "currentColor"]] }, // no value; color() no longer offered
+  },
+},
+```
+
+`emit` returns `[property, value][]`: a custom property's value is not checked, any other property is checked like a
+`css.*` call (and counts for conflicts).
+
+## Call members
+
+```ts
+look: { args: ["<color>", "$tokens", "$overrides", { "size?": "<base.gap>", "in?": "app | viewer" }], uses: ["order"] },
+icon: { args: arg<"home" | "star">() },
+reset: { args: [{ "media?": arg<boolean>(), "prose?": arg<boolean>() }] },
+// ...
+.build({
+  look: (color, tokens, overrides, { size, in: source }) => ({
+    decls: [["--_c", color], ["--_s", size ?? "0"]],
+    uses: ["base.mark"],
+    themes: [{ tokens, overrides, selector: ":root", layer: source ?? "app" }],
+  }),
+  icon: (name) => ({ decls: [["--_icon", name]] }),
+  reset: ({ media }) => ({
+    layers: { layers: ["reset"], before: true },
+    globals: media ? [{ css: "img { display: block }", layer: "reset" }] : [],
+  }),
+})
+```
+
+`build` returns `{ decls?, uses?, globals?, themes?, layers? }`:
+
+- `decls`: declarations of the member's own class (in `_.a`, or under the user's condition).
+- `uses`: more kernels, globals, layers or runtimes, by key or `mod.key`.
+- `globals: { css, layer? }[]`: rules with no class, identified by content; may set one custom property in several
+  layers (looks).
+- `themes: { tokens, overrides, selector, layer?, scope? }[]`: `createGlobalTheme` made by a member, checked against
+  the token set and read by `check.contrast`.
+- `layers`: a list, or `{ layers, before: true }`.
+
+The positional form puts a type error on the call, with the position in the message (`look(2): ...`), not on the
+argument. A grammar part arrives as checked text; a token as its `var(--name)`.
+
+## Value members
+
+```ts
+tint: { args: "<color> <percentage>", value: ([color, share]) => new CSSColorValue(`color-mix(in oklab, ${color}, white ${share})`) },
+shade: fn({
+  args: ["<color>", { "by?": "<percentage>", "dark?": arg<boolean>() }],
+  label: "tint.shade",
+  value: ([c, { by = "10%", dark }]): string => `color-mix(in oklab, ${c}, ${dark ? "black" : "white"} ${by})`,
+}),
+```
+
+- With a grammar `args`, the parts are joined by a space, so `"<color> <color>"` cannot tell `"red", "blue"` from
+  `"red blue"`: check `parts.length` or use a tuple.
+- `value` runs at build time, once per call; the call is replaced by its CSS text. It throws for values the grammar
+  cannot reject (units it cannot compute, a failed accessibility rule): `fluid` rejects `em` and fails WCAG 1.4.4.
+- What `value` returns must be a string or a Typed OM value (`cssints: tint() value must return a string or a Typed OM
+value`). A result that does not fit the property is that property's error at the same site.
+
+## Identity and HMR
+
+A scope is its content (the table, the source of its functions, the scopes it embeds), hashed. Running the module
+again with the same content is nothing; another content under the same name replaces it (an edit in dev). Two
+modules that define one name with different content: `scope "x" is defined twice with different content`. A closure
+the hash does not see (icons' collection) is fine as long as the table and code are the same.

package/skills/cssints-plugin/references/testing.md

@@ -0,0 +1,122 @@
+# Testing a plugin
+
+Three layers, as every `@cssints/*` package does them (`packages/balance`, `packages/stuck`, `packages/squircle` in
+the cssints repo are the models): fixtures through the engine, a type test, and a browser test when there is a
+runtime or a visual claim. Tests are plain `node` scripts with `node:assert`; no test runner.
+
+```
+packages/<name>/
+  src/index.ts          the scope
+  src/runtime.ts        a browser script, if any (no imports)
+  test/<name>.mjs       fixtures through the engine
+  test/fixtures/*.ts    modules that use the members (some invalid on purpose)
+  test/types/<name>.ts  the type test
+  test/browsers.mjs     Chrome, Firefox and WebKit (optional)
+```
+
+## Fixtures through the engine
+
+A Vite dev server in middleware mode with the plugin, a client transform per fixture, and the sheet of a module:
+
+```js
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import cssints from "cssints/vite";
+import { createLogger, createServer } from "vite";
+
+const root = `${import.meta.dirname}/fixtures`;
+const mode = process.argv[2];
+const warnings = [];
+const plugins = cssints();
+const server = await createServer({
+  root,
+  configFile: false,
+  customLogger: { ...createLogger("warn"), warn: (m) => warnings.push(m) },
+  server: { middlewareMode: true, watch: null, ws: false },
+  plugins,
+});
+const client = server.environments.client;
+const code = async (f) => (await client.transformRequest(`/${f}`)).code;
+const sheet = (f) => plugins[0].api.sheet([`${root}/${f}`]);
+const flat = (css) => css.replace(/\s+/g, " ").trim();
+
+const use = await code("use.ts"); // class strings in place of the calls
+const out = flat(sheet("use.ts")); // the CSS of that module
+const runtime = (await client.transformRequest("virtual:cssints/runtime/x.fb")).code;
+
+assert.match(use, /export const a = "_x-core _\w+";/);
+assert.ok(out.includes("._x-core{display:flex}"), out);
+assert.deepEqual(warnings, []); // no support warning left uncovered
+await assert.rejects(
+  code("conflict.ts"),
+  /x: kernel core sets display \(this style also sets display\)/,
+);
+await assert.rejects(code("condition.ts"), /:hover wraps _x-core, the marker of kernel x\.core/);
+```
+
+Then the targets: run the same file again per browserslist, in a child process (`BROWSERSLIST` is read once per
+process; a Vite root with its own `.browserslistrc` works in one process too):
+
+```js
+if (mode) {
+  assert.equal(runtime === "export {};", mode === "native"); // empty where every target has the feature
+  assert.equal(out.includes("@supports not"), mode === "old"); // fallback CSS only where needed
+  await server.close();
+  process.exit(0);
+}
+await server.close();
+for (const [m, targets] of [
+  ["native", "chrome 130, safari 18, firefox 130"],
+  ["old", "chrome 110, safari 17.3, firefox 120"],
+])
+  execFileSync(process.execPath, [import.meta.filename, m], {
+    env: { ...process.env, BROWSERSLIST: targets },
+    stdio: "inherit",
+  });
+```
+
+What to cover: the output of each member and method; each build error (`assert.rejects` with the message); the
+warnings for the default targets (none, or the intended ones); the runtime module and the fallback CSS for a modern
+and an old target set; a member under a condition (a method: fine; marker only: the error); nesting (a member inside
+another one does not inherit its custom properties).
+
+To look at one fixture by hand inside the cssints repo: `cd packages/cssints/test && node run.mjs fixtures/x.ts`
+prints the code and the CSS (a plugin fixture must live where `cssints` resolves). With the MCP server, `compile`.
+
+## The type test
+
+`test/types/<name>.ts`, checked by the package's `typecheck` (`tsgo -p tsconfig.json --noEmit`, with
+`test/types/*.ts` in `include`):
+
+```ts
+import { ring } from "../../src/index.ts";
+
+export const a: string = ring().width("2px").color("red");
+// @ts-expect-error not a width
+export const e1 = ring().width("red");
+// @ts-expect-error a method is used once
+export const e2 = ring().width("1px").width("2px");
+```
+
+A value member's result goes into a property in the type test (`color(tint("red", "20%"))`), to catch a result type
+the grammar rejects. Some errors only the build sees (a range in some positions, `em` where px is computed): test
+those in the fixtures, not with `@ts-expect-error`.
+
+## Browser tests
+
+`test/browsers.mjs`, run by `bun run test:browsers` (not in `test`: it needs the browsers). The shape:
+
+1. Build a fixture app with `vite build` (`write: false`) and a `BROWSERSLIST` that makes the fallback ship; set
+   `NODE_ENV=development` so the runtime resolves to `src/`.
+2. Assert on the built CSS and JS first (the `@supports not` rule is there, the script is in the bundle once).
+3. Open it in Chrome (`chromium.launch({ channel: "chrome" })`), Firefox and WebKit from `playwright-core`.
+4. For each browser, three runs:
+   - **native**: the feature works by itself, the fallback stays off;
+   - **fallback forced**: the native feature switched off (an `!important` override, or the declaration cut out of
+     the CSS), the runtime or fallback CSS must produce the same result;
+   - **control**: the same, with the fallback disabled (its observers replaced by no-ops, its rules removed). This
+     run **must fail** the check: it proves that the test can see the difference.
+5. Measure something visible: line widths, pixels of a screenshot, computed styles, the phase of an animation.
+
+A check without a control that fails is not a test of the fallback. `BROWSERS=chrome,webkit node test/browsers.mjs`
+runs some.