@pre.style/core 3.1.0-alpha.0 → 3.1.0-alpha.2

package/README.md

@@ -1,11 +1,11 @@
 # pre.style
 
-[![npm version](https://badge.fury.io/js/pre.style.svg)](https://www.npmjs.com/package/pre.style)
+[![npm version](https://img.shields.io/npm/v/@pre.style/core/next)](https://www.npmjs.com/package/@pre.style/core)
 
 Zero-runtime CSS-in-JS. Write plain CSS or SCSS next to your markup, and pre.style compiles it at build time into atomic CSS classes: one small class per declaration, shared across your whole project.
 
 ```js
-import { css } from '@pre.style/core';
+import { css } from "@pre.style/core";
 
 const button = css`
   background-color: #0071ba;
@@ -25,14 +25,28 @@ const button = css`
 After the build, `button` is a plain string, `"B C E D A G F"`. The block is replaced, and these classes are added to a single CSS file:
 
 ```css
-.B{background-color:#0071ba}
-.C{color:#fff}
-.E{padding-block-start:.5em}
-.D{padding-block-end:.5em}
-.A:hover{background-color:#005a94}
+.B {
+  background-color: #0071ba;
+}
+.C {
+  color: #fff;
+}
+.E {
+  padding-block-start: 0.5em;
+}
+.D {
+  padding-block-end: 0.5em;
+}
+.A:hover {
+  background-color: #005a94;
+}
 @media (width>=768px) {
-  .G{padding-block-start:1em}
-  .F{padding-block-end:1em}
+  .G {
+    padding-block-start: 1em;
+  }
+  .F {
+    padding-block-end: 1em;
+  }
 }
 ```
 
@@ -59,8 +73,8 @@ npm install --save-dev sass
 Add the plugin to `vite.config.ts`:
 
 ```ts
-import { defineConfig } from 'vite';
-import preStyle from '@pre.style/vite';
+import { defineConfig } from "vite";
+import preStyle from "@pre.style/vite";
 
 export default defineConfig({
   plugins: [preStyle()],
@@ -70,7 +84,7 @@ export default defineConfig({
 Then import `css` (or `scss`) from `@pre.style/core` and use the class strings:
 
 ```jsx
-import { css } from '@pre.style/core';
+import { css } from "@pre.style/core";
 
 export function Card({ children }) {
   return (
@@ -95,7 +109,7 @@ You can also write styles in `.css` and `.scss` files and import their classes,
 Frameworks that render on the server, such as React Router's framework mode, don't use `index.html`. Import pre.style's CSS in your root module instead:
 
 ```ts
-import 'virtual:pre.style.css';
+import "virtual:pre.style.css";
 ```
 
 Vite then bundles the CSS with your app's other CSS, and the framework links it when rendering on the server, both in builds and in dev. The plugin doesn't write `output.file` when the CSS is imported this way.
@@ -106,8 +120,8 @@ Add the plugin to Astro's Vite config, and import the CSS in your layout's front
 
 ```js
 // astro.config.mjs
-import { defineConfig } from 'astro/config';
-import preStyle from '@pre.style/vite';
+import { defineConfig } from "astro/config";
+import preStyle from "@pre.style/vite";
 
 export default defineConfig({
   vite: { plugins: [preStyle()] },
@@ -127,7 +141,7 @@ const title = css`
 <h1 class={title}>Hello</h1>
 ```
 
-Blocks work in frontmatter, in template expressions such as `` class={css`…`} ``, in `<script>` tags, and in the islands of any framework. Astro links the CSS on every page that uses the layout, prerendered or rendered on demand. Astro compiles components before the plugin sees them, but errors and source maps still point to the component.
+Blocks work in frontmatter, in template expressions such as ``class={css`…`}``, in `<script>` tags, and in the islands of any framework. Astro links the CSS on every page that uses the layout, prerendered or rendered on demand. Astro compiles components before the plugin sees them, but errors and source maps still point to the component.
 
 ## Writing blocks
 
@@ -138,7 +152,7 @@ A block styles one element. Each block is treated as its own small stylesheet, w
 `css` blocks are plain CSS. `scss` blocks are compiled with Sass first, so you can use variables, mixins, functions, and everything else Sass supports:
 
 ```js
-import { scss } from '@pre.style/core';
+import { scss } from "@pre.style/core";
 
 const title = scss`
   $size: 2rem;
@@ -161,7 +175,8 @@ css`
   &::before { content: '→'; }
   & > * + * { margin-top: 1rem; }
   .dark & { color: white; }
-  a { text-decoration: underline; } /* the same as `& a` */
+  a { text-decoration: underline; } /* the same as ` &
+  a` */
 `;
 ```
 
@@ -174,20 +189,32 @@ Other at-rules, such as `@keyframes`, `@font-face`, and `@property`, are copied
 ```js
 css`
   @keyframes fade-in {
-    from { opacity: 0; }
+    from {
+      opacity: 0;
+    }
   }
 
   animation: fade-in 200ms ease-out;
 `;
 ```
 
+#### Local keyframes
+
+By default, keyframes names are global, so two blocks that each define a different `@keyframes spin` collide, and the last one wins everywhere. Set `"keyframeLocalization": true` in your `package.json`'s `pre.style` field to give each `@keyframes` a generated name, as styled-components' `keyframes` helper does:
+
+- A block's or stylesheet file's `@keyframes` get a short generated name, and its `animation` and `animation-name` declarations use it. In a stylesheet file, every class in the file shares the file's keyframes, as in CSS Modules.
+- Keyframes with the same contents get the same name wherever they're defined, so they're written once.
+- Keyframes from [prepended files](#sharing-values-with-prepended-files) are localized too. Every block gets the same copy, so prepended files are the way to share keyframes between blocks.
+- Names a block or file doesn't define are left as they are, so `animation-name: spin` still refers to a global `@keyframes spin`, for example one in a CSS file that pre.style doesn't process. That also means a block can't use keyframes another block defines.
+- Names in custom properties (`--anim: spin`) aren't renamed, because pre.style can't tell they name keyframes.
+
 ### `composes` in blocks
 
 A block can build on classes from a [stylesheet file](#stylesheet-files), or on global class names, with `composes`, as in CSS Modules:
 
 ```js
 css`
-  composes: button from './button.css';
+  composes: button from "./button.css";
   composes: legacy-btn from global;
   color: white;
 `;
@@ -208,7 +235,7 @@ HTML can't import anything, so blocks in HTML files that Vite processes, such as
 Atomic classes all have the same specificity, so when two classes on one element set the same property, the order of the CSS file decides which wins, not the order in your `class` attribute. Use `cn` to combine class strings: when two classes conflict, it keeps the later one.
 
 ```js
-import { css, cn } from '@pre.style/core';
+import { css, cn } from "@pre.style/core";
 
 const button = css`
   background-color: #0071ba;
@@ -225,7 +252,7 @@ const className = cn(button, isDanger && danger);
 
 Two classes conflict when they set the same property under the same at-rules and selector. A later shorthand also removes earlier longhands it covers.
 
-When every argument is a block or a string literal, the plugin resolves the call during the build, so it costs nothing at runtime. Other calls use a small lookup table the plugin generates for your project.
+When every argument is a block or a string literal, the plugin resolves the call during the build, so it costs nothing at runtime. Arguments can also name a top-level `const` holding one of these, or holding another call that's resolved this way (`const base = css`…`;` then `cn(base, …)`). Other calls use a small lookup table the plugin generates for your project.
 
 > **Note:** `cn` removes `!important` declarations too. A later class that sets the same property wins, even when the earlier one is `!important`.
 
@@ -251,7 +278,10 @@ Styles can also live in `.css` and `.scss` files, imported with the `pre.style`
 ```
 
 ```jsx
-import { button, 'primary-button' as primaryButton } from './button.css' with { type: 'pre.style' };
+import {
+  button,
+  "primary-button" as primaryButton,
+} from "./button.css" with { type: "pre.style" };
 
 <button className={primaryButton}>Save</button>;
 ```
@@ -276,15 +306,27 @@ In `.scss` files, relative `@use`, `@forward`, and `@import` resolve from the fi
 Atomic classes are shared, so no single class in a class string identifies one export. When an exported class is used as context for another, as `card` is in `.card:hover .title`, pre.style gives it a **marker**: one extra class, added to `card`'s class string, that the selector uses.
 
 ```css
-.card { padding-top: 1rem; }
-.title { color: black; }
-.card:hover .title { color: red; }
+.card {
+  padding-top: 1rem;
+}
+.title {
+  color: black;
+}
+.card:hover .title {
+  color: red;
+}
 ```
 
 ```css
-.D{padding-top:1rem}
-.C{color:#000}
-.A:hover .B{color:red}
+.D {
+  padding-top: 1rem;
+}
+.C {
+  color: #000;
+}
+.A:hover .B {
+  color: red;
+}
 ```
 
 `card` is `"D A"`, where `A` is its marker, and `title` is `"C B"`.
@@ -297,10 +339,20 @@ Atomic classes are shared, so no single class in a class string identifies one e
 `composes` works as in CSS Modules:
 
 ```css
-.base { color: gray; padding: 1rem; }
-.primary { composes: base; color: blue; }
-.wide { composes: card from './card.css'; }
-.legacy { composes: old-btn from global; }
+.base {
+  color: gray;
+  padding: 1rem;
+}
+.primary {
+  composes: base;
+  color: blue;
+}
+.wide {
+  composes: card from "./card.css";
+}
+.legacy {
+  composes: old-btn from global;
+}
 ```
 
 > [!IMPORTANT]
@@ -318,7 +370,9 @@ TypeScript 7.1 adds [content mappers](https://devblogs.microsoft.com/typescript/
 
 ```json
 {
-  "contentMappers": [{ "package": "@pre.style/core", "extensions": [".css", ".scss"] }]
+  "contentMappers": [
+    { "package": "@pre.style/core", "extensions": [".css", ".scss"] }
+  ]
 }
 ```
 
@@ -327,11 +381,11 @@ Content mappers run code from a package, so `tsc` needs the `--runExternalCode`
 Before TypeScript 7.1, add this declaration to your project instead (for example as `src/stylesheets.d.ts`):
 
 ```ts
-declare module '*.css' {
+declare module "*.css" {
   const classes: { readonly [name: string]: string };
   export = classes;
 }
-declare module '*.scss' {
+declare module "*.scss" {
   const classes: { readonly [name: string]: string };
   export = classes;
 }
@@ -340,7 +394,7 @@ declare module '*.scss' {
 TypeScript can't type named imports from it, so use a namespace import:
 
 ```ts
-import * as styles from './button.css' with { type: 'pre.style' };
+import * as styles from "./button.css" with { type: "pre.style" };
 
 styles.button;
 ```
@@ -411,11 +465,12 @@ A library's class names depend on the whole app, so they differ between apps. Do
 }
 ```
 
-| Field          | Default                      | Description |
-| -------------- | ---------------------------- | ----------- |
-| `include`      | Every JS, TS, and Astro file | Globs of the files with blocks, relative to the package. A glob or an array of them. Stylesheet files the library imports are found from its imports. |
-| `exclude`      |                              | Globs removed from `include`. |
-| `prependFiles` |                              | Files added to the start of the library's blocks and stylesheet files, relative to the package. They apply only to the library's, not the app's, so the library's tokens and mixins are always available to it and never leak into the app. |
+| Field                  | Default                      | Description                                                                                                                                                                                                                                       |
+| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `include`              | Every JS, TS, and Astro file | Globs of the files with blocks, relative to the package. A glob or an array of them. Stylesheet files the library imports are found from its imports.                                                                                             |
+| `exclude`              |                              | Globs removed from `include`.                                                                                                                                                                                                                     |
+| `prependFiles`         |                              | Files added to the start of the library's blocks and stylesheet files, relative to the package. They apply only to the library's, not the app's, so the library's tokens and mixins are always available to it and never leak into the app.       |
+| `keyframeLocalization` | `false`                      | Give each `@keyframes` in the library's blocks and stylesheet files a generated name. See [Local keyframes](#local-keyframes). The library's setting applies to its blocks, whatever the app sets, since the library's styles are written for it. |
 
 `"pre.style": true` uses the defaults. A library's field uses the same name and shape as an app's (see [Configuration](#configuration)). `libraries` and `quirksMode` only apply to the app, so in a library's field they're ignored, with a warning. A package that is both, such as a library with its own demo app, is read as the app when it's the Vite root, and as a library when it's a dependency.
 
@@ -438,20 +493,33 @@ Production builds scan your files first, so names are stable between builds. In
 Shorthand properties are expanded into their longhands, so `cn` can resolve conflicts between them:
 
 ```js
-css`margin: auto;`;
+css`
+  margin: auto;
+`;
 ```
 
 ```css
-.D{margin-top:auto}
-.C{margin-right:auto}
-.A{margin-bottom:auto}
-.B{margin-left:auto}
+.D {
+  margin-top: auto;
+}
+.C {
+  margin-right: auto;
+}
+.A {
+  margin-bottom: auto;
+}
+.B {
+  margin-left: auto;
+}
 ```
 
 `border` (which sets 12 longhands), shorthands whose values aren't known until runtime (values with `var()`, `env()`, or `attr()`), and shorthands set to a CSS-wide keyword (`font: inherit`, `margin: initial`) are kept as one class. They're written before longhands, so a longhand still wins:
 
 ```js
-css`padding: var(--space); padding-top: 0;`;
+css`
+  padding: var(--space);
+  padding-top: 0;
+`;
 ```
 
 Expanding means some shorthands produce many classes. For example, `font` also resets the `font-variant-*` properties, among others, so it becomes about 20 classes. The CSS file barely grows, because the classes are shared across your project, but class strings get longer.
@@ -460,7 +528,7 @@ Expanding means some shorthands produce many classes. For example, `font` also r
 
 Within one block, a later declaration overrides an earlier one, as in plain CSS. Across blocks, the CSS file is ordered so the usual rules hold:
 
-1. Hoisted at-rules (`@layer` statements, `@import`, `@namespace`), then other copied at-rules.
+1. Hoisted at-rules (`@layer` statements, `@import`, `@namespace`), then other copied at-rules. With the `layer` option, everything but `@import` and `@namespace` is inside the layer.
 2. Classes on the element.
 3. Selector variants, with pseudo-classes in LVHFA order (`:link`, `:visited`, `:hover`, `:focus`, `:active`).
 4. At-rule groups. `@media` queries with only a `min-width` come last, smallest first (mobile-first).
@@ -492,13 +560,14 @@ Options every tool that reads your styles has to agree on (the bundler plugin, a
 }
 ```
 
-| Option         | Default                                           | Description |
-| -------------- | ------------------------------------------------- | ----------- |
-| `include`      | `**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts,html,astro}` | Globs of the files with blocks, relative to the `package.json`. A glob or an array of them. Scanned before a build to assign names; stylesheet files are found from the scanned files' imports. `node_modules` and the output directory are always skipped. |
-| `exclude`      |                                                   | Globs removed from `include`. |
-| `prependFiles` |                                                   | Files added to the start of the app's blocks and stylesheet files. See [Sharing values with prepended files](#sharing-values-with-prepended-files). |
-| `libraries`    |                                                   | Component libraries to compile, by package name, in addition to dependencies with a `pre.style` field. A config replaces the package's field, `true` uses the defaults, and `false` leaves the package out. See [Component libraries](#component-libraries). |
-| `quirksMode`   | `false`                                           | **You probably don't want this.** Use lowercase class names only, for pages in quirks mode. Names get longer. See [Quirks mode](#quirks-mode). |
+| Option                 | Default                                           | Description                                                                                                                                                                                                                                                  |
+| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `include`              | `**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts,html,astro}` | Globs of the files with blocks, relative to the `package.json`. A glob or an array of them. Scanned before a build to assign names; stylesheet files are found from the scanned files' imports. `node_modules` and the output directory are always skipped.  |
+| `exclude`              |                                                   | Globs removed from `include`.                                                                                                                                                                                                                                |
+| `prependFiles`         |                                                   | Files added to the start of the app's blocks and stylesheet files. See [Sharing values with prepended files](#sharing-values-with-prepended-files).                                                                                                          |
+| `libraries`            |                                                   | Component libraries to compile, by package name, in addition to dependencies with a `pre.style` field. A config replaces the package's field, `true` uses the defaults, and `false` leaves the package out. See [Component libraries](#component-libraries). |
+| `quirksMode`           | `false`                                           | **You probably don't want this.** Use lowercase class names only, for pages in quirks mode. Names get longer. See [Quirks mode](#quirks-mode).                                                                                                               |
+| `keyframeLocalization` | `false`                                           | Give each `@keyframes` in the app's blocks and stylesheet files a generated name, used only in the block or file that defines it. See [Local keyframes](#local-keyframes). Libraries use their own setting.                                                  |
 
 The plugin warns about keys it doesn't know, and fails the build on values of the wrong type. For completion and validation in your editor, `@pre.style/core` includes a JSON Schema for the field, at `node_modules/@pre.style/core/package.schema.json`. In VS Code, add it to your settings:
 
@@ -509,7 +578,9 @@ The plugin warns about keys it doesn't know, and fails the build on values of th
       "fileMatch": ["package.json"],
       "schema": {
         "properties": {
-          "pre.style": { "$ref": "./node_modules/@pre.style/core/package.schema.json" }
+          "pre.style": {
+            "$ref": "./node_modules/@pre.style/core/package.schema.json"
+          }
         }
       }
     }
@@ -525,27 +596,37 @@ Options about how a build writes its output go to the plugin. All options are op
 preStyle({
   lightningcss: { minify: true, targets: { safari: 16 << 16 } },
   sourceMap: true,
-  quotes: 'single-quote',
+  layer: "pre.style",
+  quotes: "single-quote",
   output: {
-    file: 'css/pre.style.css',
-    banner: '/* Generated by pre.style */',
+    file: "css/pre.style.css",
+    banner: "/* Generated by pre.style */",
   },
 });
 ```
 
-| Option         | Default                                           | Description |
-| -------------- | ------------------------------------------------- | ----------- |
-| `lightningcss` |                                                   | [Lightning CSS options](https://lightningcss.dev/transforms.html), such as `minify`, `targets`, `drafts`, and `visitor`. A `visitor` runs before pre.style processes each block. `filename`, `code`, `sourceMap`, `projectRoot`, `inputSourceMap`, and `cssModules` are ignored. |
-| `sourceMap`    | `false`                                           | Generate a source map for the CSS, mapping each class to the first block it appears in. In dev, it's shown in the browser (the plugin turns on Vite's `css.devSourcemap`). In builds, it's written next to `output.file`. When you import `virtual:pre.style.css`, builds have no CSS source map, because Vite doesn't write them for bundled CSS. |
-| `quotes`       | `'double-quote'`                                  | Quotes around the class string that replaces each block in JS: `'single-quote'`, `'double-quote'`, or `'backtick'`. |
-| `output.file`  | `'pre.style.css'`                                  | Path and name of the CSS file, relative to Vite's `build.outDir`. |
-| `output.banner`|                                                   | Text added to the start of the CSS file. |
-| `output.footer`|                                                   | Text added to the end of the CSS file. |
+| Option          | Default                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lightningcss`  |                                  | [Lightning CSS options](https://lightningcss.dev/transforms.html), such as `minify`, `targets`, `drafts`, and `visitor`. A `visitor` runs before pre.style processes each block. `filename`, `code`, `sourceMap`, `projectRoot`, `inputSourceMap`, and `cssModules` are ignored.                                                                                                                                                                                             |
+| `sourceMap`     | `true` in dev, `false` in builds | Generate a source map for the CSS, mapping each class to the first block it appears in (a source map can only point to one place; the [DevTools extension](#tracing-classes-with-the-devtools-extension) lists them all). In dev, it's shown in the browser (the plugin turns on Vite's `css.devSourcemap`, unless you set it). In builds, it's written next to `output.file`. When you import `virtual:pre.style.css`, builds have no CSS source map, because Vite doesn't write them for bundled CSS.                                                                                                        |
+| `layer`         | `false`                          | Wrap the CSS in a [cascade layer](https://developer.mozilla.org/docs/Web/CSS/@layer): `false` for none, `""` for an unnamed layer, or the layer's name, such as `"pre.style"` or `"vendor.pre-style"`. `@import` and `@namespace` rules stay before the layer, since they can't be inside one. `@layer` rules from blocks become layers nested in it. Browsers without cascade layers (Chrome before 99, Safari before 15.4, Firefox before 97) ignore everything inside it. |
+| `quotes`        | `'double-quote'`                 | Quotes around the class string that replaces each block in JS: `'single-quote'`, `'double-quote'`, or `'backtick'`.                                                                                                                                                                                                                                                                                                                                                          |
+| `output.file`   | `'pre.style.css'`                | Path and name of the CSS file, relative to Vite's `build.outDir`.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `output.banner` |                                  | Text added to the start of the CSS file.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `output.footer` |                                  | Text added to the end of the CSS file.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 
 The CSS isn't minified unless you set `lightningcss: { minify: true }`.
 
 Before 3.1, `include`, `exclude`, `prependFiles`, `libraries`, and `quirksMode` were plugin options. Passing them to the plugin now fails with a message pointing to `package.json`.
 
+### Tracing classes with the DevTools extension
+
+Classes are shared, so one class can come from many blocks, and a source map can only point to one of them. The [pre.style DevTools extension](packages/devtools) adds a **pre.style** tab to the Elements panel in Chrome and Firefox. For the selected element, it lists each pre.style rule like the Styles pane does, with a link to every block that uses it.
+
+It works with the Vite dev server while `sourceMap` is on, which is the default in dev. Setting `sourceMap: false` turns it off. It only runs on `localhost`, `*.localhost`, loopback addresses, and hostnames you add in its settings, and sends other sites no requests.
+
+Its links open your editor through Vite, which guesses which one you use. When the dev server runs in VS Code's terminal, the plugin sets the `LAUNCH_EDITOR` environment variable to `code` if it isn't set, which also applies to Vite's error overlay. To choose an editor yourself, set `LAUNCH_EDITOR`.
+
 ### Quirks mode
 
 > [!WARNING]
@@ -591,10 +672,11 @@ The build fails, with the file, line, and column, when:
 
 ## Packages
 
-| Package                 | Description                                            |
-| ----------------------- | ------------------------------------------------------ |
-| `@pre.style/core`             | `css`, `scss`, and `cn`, the compiler at `@pre.style/core/compiler` for bundler plugins, TypeScript's content mapper for stylesheet files, and the JSON Schema for the `package.json` field. |
-| `@pre.style/vite` | The Vite plugin.                                       |
+| Package           | Description                                                                                                                                                                                  |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@pre.style/core` | `css`, `scss`, and `cn`, the compiler at `@pre.style/core/compiler` for bundler plugins, TypeScript's content mapper for stylesheet files, and the JSON Schema for the `package.json` field. |
+| `@pre.style/vite` | The Vite plugin.                                                                                                                                                                             |
+| [pre.style DevTools](packages/devtools) | A side pane for the Elements panel in Chrome and Firefox that lists every block using each class. Not published to the extension stores yet. |
 
 ## Development
 

package/dist/compiler/block.d.ts

@@ -69,6 +69,7 @@ export interface ParseOptions {
     prepend: Record<Lang, string>;
     sass: SassCompiler | null;
     warn: (message: string) => void;
+    keyframeLocalization: boolean;
 }
 export declare const key: (value: unknown) => string;
 export declare function parseBlock(code: string, lang: Lang, options: ParseOptions): ParsedBlock;
@@ -85,6 +86,7 @@ export declare function addDeclarations(block: {
     importantDeclarations?: Declaration[];
 } | undefined, atRules: AtRuleSegment[], selectors: SelectorList, atoms: Atom[], composes: Compose[] | null, position: Position | null): void;
 export declare function addGlobal(rule: Rule, atRules: AtRuleSegment[], globals: GlobalRule[], position: ToPosition): void;
+export declare function overrideKey(rule: Rule): string;
 export declare function propertyOf(declaration: Declaration): {
     property: string;
     shorthand: boolean;

package/dist/compiler/block.js

@@ -1,6 +1,7 @@
 import { composeVisitors, transform } from 'lightningcss';
 import { atRuleInfo } from './at-rules.js';
 import { expand } from './expand.js';
+import { localizeKeyframes } from './keyframes.js';
 import { compose, fromPlaceholder, isElement, PLACEHOLDER, repair } from './selectors.js';
 import { splitBlock } from './split.js';
 import { SHORTHANDS } from '../shorthands.js';
@@ -82,11 +83,11 @@ export function parseBlock(code, lang, options) {
     // Sass output positions don't match the block, so scss atoms have none.
     const position = (loc) => lang === 'css' && loc ? toBlock(loc.line, loc.column) : null;
     parseRules(css, options.lightningcss, position, (rules) => walk(rules, [], null, parsed, position));
-    return {
-        atoms: dropOverridden(parsed.atoms),
-        globals: parsed.globals,
-        composes: parsed.composes,
-    };
+    const atoms = dropOverridden(parsed.atoms);
+    if (!options.keyframeLocalization)
+        return { atoms, globals: parsed.globals, composes: parsed.composes };
+    const local = localizeKeyframes(parsed.globals);
+    return { atoms: local.atoms(atoms), globals: local.globals, composes: parsed.composes };
 }
 // Parses CSS with Lightning CSS, and passes its rules to `collect` once the
 // user's visitor has changed them. `position` converts error locations.
@@ -276,11 +277,12 @@ export function addGlobal(rule, atRules, globals, position) {
     });
 }
 // The identity of an overridable at-rule: its type and name.
-function overrideKey(rule) {
+export function overrideKey(rule) {
     const value = valueOf(rule);
     switch (rule.type) {
         case 'keyframes':
-            return `keyframes ${key(value.name)}`;
+            // `@-webkit-keyframes x` doesn't replace `@keyframes x`.
+            return `keyframes ${key(value.vendorPrefix ?? [])} ${key(value.name)}`;
         case 'font-face': {
             // A font face is identified by its family, style, weight, and stretch.
             const descriptors = Object.fromEntries(value.properties

package/dist/compiler/compiler.d.ts

@@ -8,6 +8,7 @@ export type PrependFiles = string[] | {
 export interface Library {
     dir: string;
     prependFiles?: PrependFiles;
+    keyframeLocalization?: boolean;
 }
 export interface CompilerOptions {
     prependFiles?: PrependFiles;
@@ -17,6 +18,8 @@ export interface CompilerOptions {
     root?: string;
     warn?: (message: string) => void;
     quirksMode?: boolean;
+    keyframeLocalization?: boolean;
+    layer?: false | string;
 }
 export interface Block {
     code: string;
@@ -34,6 +37,23 @@ export interface CompiledStylesheet {
     exports: [name: string, classString: string][];
     dependencies: string[];
 }
+export interface Source {
+    file: string;
+    line: number;
+    column: number;
+}
+export interface ClassUsage {
+    className: string;
+    selector: string;
+    atRules: string[];
+    declaration: string;
+    property: string;
+    covers: string[];
+    important: boolean;
+    specificity: [ids: number, classes: number, types: number];
+    order: number;
+    sources: Source[];
+}
 export declare function createCompiler(options?: CompilerOptions): Promise<Compiler>;
 export declare class Compiler {
     #private;
@@ -45,6 +65,8 @@ export declare class Compiler {
     classString(block: Block): string;
     dependencies(block: Block): string[];
     classNames(sheet: Stylesheet): string[];
+    usages(classNames: Iterable<string>): ClassUsage[];
+    forgetSources(file: string): void;
     stylesheet(sheet: Stylesheet): CompiledStylesheet;
     css(): Printed;
     cnTable(): CnTable;