CSS static extraction and atomization (#573)

Author: davesnx

.cursor/documents/css-property-parser/rule-module-analysis.md

@@ -16,7 +16,7 @@ single token system backed by `Tokens.re` and consumed via external tokens in
 | System | Lexer Function | Returns | Used By |
 |--------|---------------|---------|---------|
 | Parser.mly | `get_next_tokens_with_location` | `Tokens.token_with_location` | `driver.re`, menhir parser |
-| Tokens.re | `consume` | `Tokens.token` | `css-property-parser` |
+| Tokens.re | `consume` | `Tokens.token` | `css-grammar` |
 
 ---
 
@@ -237,9 +237,9 @@ HASH of (string * [`ID | `UNRESTRICTED])
 - Selector parsing (needs `DOT`, `COMBINATOR`, `OPERATOR`, `TAG`, etc.)
 
 ### Tokens.re tokens are used for:
-- CSS property value validation (`css-property-parser` package)
+- CSS property value validation (`css-grammar` package)
 - `Rule.re` pattern matching on token streams
-- `Standard.re` primitive extractors (`length`, `angle`, `percentage`, etc.)
+- `Css_value_types.re` primitive extractors (`length`, `angle`, `percentage`, etc.)
 
 ---
 
@@ -292,5 +292,5 @@ Merge `get_next_token` and `consume` into single function returning the unified
 | `packages/parser/lib/Parser.mly` | Menhir grammar + token declarations |
 | `packages/parser/lib/driver.re` | Parser entry points |
 | `packages/parser/test/Lexer_test.re` | Tests for both lexers |
-| `packages/css-property-parser/lib/Rule.re` | Token stream parsing monad |
-| `packages/css-property-parser/lib/Standard.re` | Primitive value extractors |
+| `packages/css-grammar/lib/Rule.re` | Token stream parsing monad |
+| `packages/css-grammar/lib/Css_value_types.re` | Primitive value extractors |

.cursor/documents/lexer/current-state-lexers.md

@@ -11,7 +11,7 @@ Remove the `tokenize` API and consolidate around `from_string` for batch tokeniz
 | API | Signature | Error Handling | Encoding | Used By |
 |-----|-----------|----------------|----------|---------|
 | `tokenize` | `string => result(list((token, pos, pos)), string)` | Catches `LexingError`, returns `Error(string)` | Utf8 | `Lexer_test.re`, `lexer_renderer.re` |
-| `from_string` | `string => list(token_with_location)` | **Mixed**: soft errors in stream, hard errors raise | Utf8 | `css-property-parser`, `Lexer_from_string_test.re` |
+| `from_string` | `string => list(token_with_location)` | **Mixed**: soft errors in stream, hard errors raise | Utf8 | `css-grammar`, `Lexer_from_string_test.re` |
 | `get_next_tokens_with_location` | `lexbuf => (token, pos, pos)` | Raises `LexingError` | N/A (caller provides lexbuf) | `driver.re` (menhir parser) |
 
 ### Important: `from_string` Has Dual Error Handling
@@ -53,7 +53,7 @@ eval $(opam env --switch=. --set-switch)
 make test-parser
 make test-ppx-native
 make test-css-support
-make test-css-property-parser
+make test-css-grammar
 ```
 
 ---
@@ -227,7 +227,7 @@ let tokenize:
 make test-parser
 make test-ppx-native
 make test-css-support
-make test-css-property-parser
+make test-css-grammar
 make build
 ```
 
@@ -265,7 +265,7 @@ After each phase:
 - [ ] `make test-parser` passes
 - [ ] `make test-ppx-native` passes
 - [ ] `make test-css-support` passes
-- [ ] `make test-css-property-parser` passes
+- [ ] `make test-css-grammar` passes
 
 ---
 

.cursor/documents/lexer/lexer-unification-plan.md

@@ -9,16 +9,18 @@ alwaysApply: true
 File structure and test commands for each package:
 
 packages
-├── css-property-parser
-│  └── test (to run those tests `make test-css-property-parser`)
+├── css-grammar
+│  ├── lib
+│  ├── ppx
+│  └── test (to run those tests `make test-css-grammar`)
 │      ├── Combinators_test.re
 │      ├── Modifiers_test.re
 │      ├── Rules_test.re
 │      ├── Runner.re
 │      ├── Standard_test.re
-│      ├── Types_test.re
-│      ├── dune
-│      └── snapshots
+│      ├── Parser_test.re
+│      ├── Interpolation_extraction_test.re
+│      └── dune
 ├── css-spec-parser
 │  └── test (to run those tests `make test-css-spec-parser`)
 │      ├── dune

.cursor/hooks/state/continual-learning.json

@@ -88,6 +88,9 @@ jobs:
           chmod +x "$OPAM_PATH"
           dirname "$OPAM_PATH" >> "$GITHUB_PATH"
 
+      - name: Pin dependencies
+        run: make pin
+
       - name: Install dependencies
         run: make install
 

.cursor/rules/md-documents.mdc

@@ -1,4 +1,3 @@
-version=0.28.1
 quiet=true
 profile=default
 

.cursor/rules/testing.mdc

@@ -30,28 +30,18 @@ The project consists of three main components:
 - Record observed failures with enough context (command, exit code, snippet of output) for reproducibility.
 
 ## Architecture Orientation
-- **Parser & Type Checker** (`packages/parser`, `packages/css-property-parser`): builds the CSS AST, validates properties via generated combinators (`[%value.rec ...]`), and produces rich error messages for invalid CSS.
+- **Parser & Type Checker** (`packages/parser`, `packages/css-grammar`): builds the CSS AST, validates properties via generated combinators (`[%spec ...]`), and produces rich error messages for invalid CSS.
 - **PPX Transformer** (`packages/ppx/src/ppx.re`): exposes interfaces like `[%styled.tag]`, `[%cx]`, `[%css]`, `[%cx2]`, and `[%keyframes]`; orchestrates parsing, validation, and code generation.
 - **Property → Runtime Bridge** (`packages/ppx/src/Property_to_runtime.re`): maps validated properties to runtime constructors, preserves interpolations, and decides extraction vs runtime emission.
 - **Runtimes** (`packages/runtime/native`, `.../melange`, `.../rescript`): emit CSS for native servers, JS environments, and ReScript compatibility. Shared types live in `packages/runtime/native/shared/Css_types.ml`.
 - **Extraction Pipeline**: `[%cx2]` is the only statically extracted path today; it generates CSS assets during compilation for zero runtime overhead.
 
-## Common Tasks & Playbooks
-- **Feature work**: locate the relevant package, add parser rules or runtime constructors, extend PPX mapping, and update tests.
-- **Bug fixes**: reproduce with minimal repro (fixture or snapshot), craft targeted patches, and add regression coverage.
-- **Docs**: keep developer guides (like this file) up to date; cross-link to tooling instructions and testing docs.
-- **Reviews**: inspect diffs critically, reason about downstream impact (compile-time + runtime), and recommend follow-up tests when missing.
+## Reference Documents
+- Consult `documents/design.md` before making structural changes across `packages/parser`, `packages/css-grammar`, `packages/ppx`, or the runtime pipeline.
+- Consult `documents/primitives.md` for the shared glossary and preferred terminology used by humans and agents in architecture discussions.
 
 ## Troubleshooting Tips
 - Regenerate snapshots via the appropriate dune alias if expect tests fail after legitimate changes.
 - If opam tooling appears missing, double-check the `_opam` switch integrity before troubleshooting dune.
 - Watch for generated code churn; understand the source generator before editing outputs directly.
 - When PPX errors are opaque, reproduce with `dune exec -- <binary>` or `dune build --verbose` to capture the PPX invocation.
-
-## Reference
-- Repository root: `/Users/davesnx/Code/github/davesnx/styled-ppx`
-- Dune binary: `/Users/davesnx/Code/github/davesnx/styled-ppx/_opam/bin/dune`
-- Key docs: `AGENT.md` (this guide), `testing.mdc` (testing policies), `docs/` (additional design notes), `packages/*` (source code).
-- Prefer absolute paths in tool calls and explanations so transcripts remain unambiguous.
-
-Stay curious, verify assumptions, and leave the repo healthier than you found it.