stixis 0.1.0__tar.gz

stixis-0.1.0/.agents/docs/grammar-and-codegen.md

@@ -0,0 +1,85 @@
+# Grammar Compiler and Code Generation Guide
+
+## Overview
+
+Stixis separates build-time specification ingestion (`codegen/`) from its zero-dependency runtime kernel (`src/stixis/syntax.py`). Both structured Python values (`serialize_value`) and raw CSS token streams (`canonicalize`) are evaluated against the same compiled `ValueNode` combinator tree.
+
+## Value Definition Syntax (`src/stixis/syntax.py`)
+
+`compile_value_syntax(syntax_str)` compiles W3C CSS Value Definition Syntax strings (`css-values-4` §5) into an immutable `ValueNode` hierarchy:
+
+* `KeywordNode(name)` and `DelimNode(delim)`: Literal keywords (case-insensitively matched, serialized in ASCII lowercase) and punctuation delimiters (`,`, `/`, `:`).
+* `PrimitiveNode(kind, min_val, max_val, min_unit, max_unit)`: Terminal and microsyntax types (`<number>`, `<integer>`, `<length>`, `<angle>`, `<time>`, `<frequency>`, `<resolution>`, `<percentage>`, `<string>`, `<url>`, `<ident>`, `<custom-ident>`, `<dashed-ident>`, `<urange>`, `<opentype-tag>`, `<feature-tag-value>`, `<family-name>`, `<generic-family>`, `<font-src>`, `<font-src-list>`, `<font-format>`, `<font-tech>`, `<hex-color>`, `<declaration-value>`, `<any-value>`), including bracketed range constraints such as `<number [1,1000]>` or `<angle [-90deg,90deg]>`.
+* `RefNode(name, is_property, min_val, max_val)`: Non-terminal references (`<color>`) and property references (`<'font-width'>`), resolved lazily via `lookup_value_node` with cycle protection (`_active_refs`).
+* `FunctionNode(name, arg)`: Typed CSS functions (`generic(...)`, `palette-mix(...)`, `fit-content(...)`).
+* Combinators:
+  * `JuxtaposeNode(items)`: Ordered sequence `A B`.
+  * `AllOfNode(items)`: Unordered conjunction `A && B`. Matches branches in any input order (allowing optional `MultiplierNode(min_count=0)` branches to be omitted) and serializes matched branches in the canonical grammar order `0 .. k-1`.
+  * `AnyOrderNode(items)`: Unordered inclusive-or `A || B`. Requires at least one branch and serializes matched branches in canonical grammar order `0 .. k-1`.
+  * `ExclusiveOrNode(items)`: Ordered choice `A | B`.
+  * `MultiplierNode(child, min_count, max_count, comma_separated)`: Multipliers `?` (`0..1`), `*` (`0..∞`), `+` (`1..∞`), `{A,B}`, `#` (`comma_separated=True`), and `#{A,B}`.
+  * `NonEmptyGroupNode(child)`: Required group `[ ... ]!`.
+
+### PEP 750 `Template` Rendering (`render_css_template`)
+
+When `serialize_value`, `StyleRule`, `AtRule`, `FontFace`, or `StyleSheet` receives a Python 3.14+ `string.templatelib.Template` (`t"..."`), `render_css_template` inspects the lexical context preceding each `Interpolation` slot:
+
+1. **Inside a CSS comment (`/* ... */`)**: Replaces any `*/` in the interpolated value with `* /` so untrusted text cannot prematurely close the comment and inject rules.
+2. **Inside a quoted string (`"..."` or `'...'`)**: Escapes characters using CSSOM string rules without adding outer quotes.
+3. **Inside `url(...)`**: Escapes the URL string via `serialize_string` so spaces, quotes, and parentheses cannot break out of `url(...)`.
+4. **Top-level value slot**: Formats `int`/`float` via `serialize_number`, `Dimension`/`Percentage`/`Url`/`LocalFont`/`Keyword` via their primitive serializers, and plain `str` via `serialize_string` (unless `!r` conversion is specified), then passes the assembled CSS string through `evaluate_canonicalize` for full `ValueNode` grammar validation.
+
+## Declarative Spec Patches (`codegen/spec_patches.toml`)
+
+W3C `@webref/css` (`ed/css/*.json`) has prose-defined aliases and delta specifications (`css-fonts-5.json`, `css-values-5.json`, `css-color-5.json`). Never hardcode spec overrides inside `codegen/gen_specs.py`; declare them in `codegen/spec_patches.toml`:
+
+* `[support]`: Controls browser implementation filtering (`default_min_engines = 2`, `allow_properties = [...]`, `exclude_specs = [...]`) using engine counts (`0..3` across Blink, Gecko, WebKit) extracted from `@mdn/browser-compat-data` (`PROPERTY_ENGINE_COUNTS` in `src/stixis/_generated/specs.py`). At runtime, callers can lower the threshold with `SerializationOptions(min_engines=1)` / `SerializationOptions.cleome(min_engines=1)` or enable specific single-engine properties via `SerializationOptions(extra_properties=frozenset({"..."}))`.
+* `[extra_units]`: Units defined in prose or pending upstream extraction (such as container query length units `cqw`..`cqmax` and speech units `dB`, `st`).
+* `[delta_merges]`: Explicit ordering of base and delta JSON files so delta descriptors (`@font-face/size-adjust`, two-value `ascent-override`, `<font-features-tech>` with `avar2`) extend or override base definitions cleanly.
+* `[values]`: Non-terminal syntax aliases defined in prose (`<font-src-list> = "<font-src>#"`, `<palette-identifier> = "<dashed-ident>"`, `<counter-name> = "<custom-ident>"`).
+* `[atrule_preludes]`: Prelude grammars validated by `AtRule` (such as `@font-palette-values = "<dashed-ident>"`, `@property = "<custom-property-name>#"`, `@layer = "<layer-name>? | <layer-name>#"`).
+* `[atrule_descriptors."@font-face"]`: Prose-defined descriptor aliases (`font-stretch = "auto | <'font-width'>{1,2}"`).
+* `[properties]`: Property syntax overrides where a draft omits prose keywords (`font-synthesis` with `oblique-only`, `font-stretch = "<'font-width'>"`).
+
+After editing `codegen/spec_patches.toml`, run:
+
+```bash
+uv run python codegen/gen_specs.py
+uv run python codegen/gen_specs.py --check
+```
+
+## WPT Test Generation (`codegen/gen_wpt_tests.py`)
+
+`codegen/gen_wpt_tests.py` extracts test vectors from local WPT HTML files into `tests/_generated/`:
+
+* `test_wpt_urange.py`: All 94 valid and invalid `<urange>` vectors from `css-syntax/urange-parsing.html`.
+* `test_wpt_font_family.py`: `<family-name>` and `<generic-family>` quoting and normalization vectors from `cssom/font-family-serialization-001.html` and `css-fonts/support/font-family-keywords.js`.
+* `test_wpt_font_face.py`: `@font-face` descriptor tests from `css-fonts/parsing/font-face-*.html`.
+* `test_wpt_css_fonts.py`: All property parsing vectors from `css-fonts/parsing/*-{valid,invalid}.html`.
+* `test_wpt_css_properties.py`: General CSS property vectors across `css-*/parsing/*-{valid,invalid}.html`.
+
+Always verify that generated files are synchronized before committing:
+
+```bash
+uv run python codegen/gen_wpt_tests.py --check
+uv run pytest
+```
+
+## Upstream Sync & Agent Triage (`codegen/check_upstream.py` & `codegen/upstream.json`)
+
+`codegen/upstream.json` records the baseline commit SHAs and generated counts for `w3c/webref` (`ed/css`) and `web-platform-tests/wpt` (`css`).
+
+When upstream repositories advance (or when `.github/workflows/upstream-watch.yml` opens or updates an `upstream-sync` GitHub Issue), run `codegen/check_upstream.py` to classify what changed:
+
+1. **Auto-applicable updates**: New or modified properties, descriptors, units, or WPT vectors that compile and pass with the existing `src/stixis/syntax.py` kernel and `codegen/spec_patches.toml`.
+2. **Action-required items**:
+   * **Unresolved non-terminals (`<new-type>`)**: Add prose aliases to `[values]` in `codegen/spec_patches.toml`, or add a microsyntax handler under `src/stixis/microsyntax/`.
+   * **Failing WPT vectors**: Inspect the target grammar with `uv run stixis inspect <target> --json`, reproduce with `uv run stixis check <target> <raw_css>`, and adjust `codegen/spec_patches.toml` or `src/stixis/syntax.py`.
+
+After resolving any action items, regenerate all tables, tests, and baseline metadata:
+
+```bash
+uv run python codegen/gen_specs.py --webref-dir <path-to-webref-ed-css>
+uv run python codegen/gen_wpt_tests.py --wpt-dir <path-to-wpt-css>
+uv run python codegen/check_upstream.py --webref-dir <path-to-webref-ed-css> --wpt-dir <path-to-wpt-css> --update-baseline
+```

stixis-0.1.0/.agents/docs/microsyntaxes-and-cssom.md

@@ -0,0 +1,53 @@
+# CSSOM Serialization and Microsyntaxes Guide
+
+## CSSOM Primitive Serialization (`src/stixis/primitives.py`)
+
+All primitive serializers implement W3C CSSOM §2.1 (`Common Serializing Idioms`) and §6.7.2 (`Serializing CSS Values`):
+
+* **Identifiers (`serialize_ident`, `serialize_custom_ident`, `serialize_dashed_ident`)**:
+  * Replaces `U+0000` with `U+FFFD`.
+  * Escapes `U+0001`..`U+001F` and `U+007F` as hex code points (`\1f ` with trailing space).
+  * Escapes leading ASCII digits (`0`..`9`) or leading hyphen followed by a digit (`-[0-9]`) as hex code points (`\31 `), and lone `-` as `\-`.
+  * `serialize_custom_ident` rejects CSS-wide keywords (`initial`, `inherit`, `unset`, `default`, `revert`, `revert-layer`, `revert-rule`) and any grammar-specific forbidden keywords.
+  * `serialize_dashed_ident` requires a leading `--` (`len >= 2`, including `--`).
+* **Strings and URLs (`serialize_string`, `serialize_url`)**:
+  * Wraps in `options.quote_char` (`"` by default and in `.cssom()`, `'` in `.cleome()`).
+  * Escapes `U+0001`..`U+001F` and `U+007F` as hex code points, and escapes `options.quote_char` and `\` with a backslash.
+  * `serialize_url` formats `url(...)` with a quoted inner string.
+* **Numbers, Integers, Percentages, and Dimensions (`serialize_number`, `serialize_integer`, `serialize_percentage`, `serialize_dimension`)**:
+  * Rejects `bool` (`isinstance(v, bool)`) and non-finite floats (`nan`, `inf`, `-inf`).
+  * Formats numbers as shortest decimal strings without scientific notation, rounded to at most 6 fractional digits with trailing zeros stripped (`400.0` -> `"400"`, `-0.0` -> `"0"`).
+  * Enforces bracketed bounds (`[min, max]`) and validates units against `src/stixis/_generated/units.py`, normalizing unit names to their canonical lowercase form (except `Hz`/`kHz` or `Q` where specified, and `dB`/`st`).
+
+## Five Microsyntaxes (`src/stixis/microsyntax/`)
+
+### 1. `<urange>` and Cascade Shadowing Compaction (`urange.py`)
+
+* `parse_urange(text)` implements CSS Syntax Level 3 §8 and passes all 94 cases in WPT `urange-parsing.html`. Because CSS tokenizers absorb `U+...` into `ident`, `number` (including scientific notation like `u+1e3`), or `dimension` tokens, `parse_urange` strips comments first while verifying that no comment separated the leading `u`/`U` from `+` (rejecting `u/**/0` while accepting `u/**/+/**/0`).
+* `compact_urange(sorted_target_cps, forbidden_sorted, max_gap=0x80)` merges adjacent ranges when `gap <= max_gap` **only** if `bisect_right` confirms that no code point in `forbidden_sorted` lies inside `(prev_end, next_start)`. This minimizes `unicode-range` string length without shadowing glyphs in subsequent `@font-face` slices.
+
+### 2. `<opentype-tag>` and Feature/Variation Settings (`opentype.py`)
+
+* `validate_opentype_tag` enforces exactly 4 printable ASCII bytes (`0x20`..`0x7E`), escaping `"` and `\`.
+* `serialize_font_feature_settings` accepts `Mapping[str, int | bool | str]` or `Sequence[tuple[str, int | bool | str]]`. Per CSSOM shortest serialization, value `1` / `True` / `"on"` is omitted (`"liga"`), `0` / `False` / `"off"` serializes as `0` (`"dlig" 0`), and integers `>= 2` serialize as `"swsh" 2`.
+* `serialize_font_variation_settings` accepts `Mapping[str, int | float]` or `Sequence[tuple[str, int | float]]` and formats each pair as `"tag" <number>`.
+* `serialize_font_language_override` validates `normal` or a 1..4 printable ASCII string and strips trailing spaces per WPT `font-language-override-valid.html`.
+
+### 3. `<font-src-list>` (`font_src.py`)
+
+* Enforces WPT `font-face-src-tech.html`, `font-face-src-format.html`, and `font-face-src-local.html`:
+  * `format()` must precede `tech()`; reversed `tech(...) format(...)` is rejected.
+  * `tech()` accepts only comma-separated `<font-tech>` keywords (serialized in ASCII lowercase) and rejects quoted strings.
+  * `format()` accepts `<font-format>` keywords (`woff2`, `woff`, `opentype`, `truetype`, `collection`, `embedded-opentype`, `svg`) or strings; `options.quote_font_format` controls whether keywords are emitted bare (`format(woff2)`) or quoted (`format('woff2')` in `.cleome()`).
+  * `local()` rejects single-word unquoted CSS-wide keywords (`local(inherit)`), accepts multi-word unquoted names containing CSS-wide keywords (`local(default A)`), and accepts quoted CSS-wide keywords (`local("inherit")`).
+
+### 4. `<family-name>` and `<generic-family>` (`family_name.py`)
+
+* In `serialize_value`, a Python `str` is always treated as `<family-name>` (never `<generic-family>`). Use `generic("serif")`, `GenericFamily("serif")`, or `Keyword("serif")` for generic families.
+* With `DEFAULT_OPTIONS` (`always_quote_family_name=True`), `<family-name>` is always quoted.
+* With `SerializationOptions.cssom()` (`always_quote_family_name=False`), valid `<custom-ident>+` names serialize unquoted (`Times New Roman`), while names starting with a digit (`"34J"`), containing multiple spaces (`"A  B"`), or colliding case-insensitively with `<generic-family>` or CSS-wide keywords (`"Serif"`, `"inherit"`) remain quoted per WPT `font-family-serialization-001.html`.
+
+### 5. `{1,2}` Descriptor and Property Ranges (`ranges.py`)
+
+* Supports single values and 2-tuples `(lo, hi)` for `font-weight` (`[1, 1000]`), `font-width` / `font-stretch` (`[0%, ∞]`), `font-style` (`oblique <angle [-90deg,90deg]>{1,2}`), and metric overrides (`ascent-override`, `descent-override`, `line-gap-override`).
+* In property context (`is_descriptor=False`), `oblique 0deg` normalizes to `normal` when `options.normalize_zero_oblique=True`.

stixis-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+.mypy_cache/
+.upstream/
+.DS_Store

stixis-0.1.0/AGENTS.md

@@ -0,0 +1,33 @@
+# Stixis
+
+Stixis (`stixis`) is a zero-dependency, spec-driven CSS serializer and validator for Python 3.14+ that generates its grammar tables and `TypedDict` types from W3C `@webref/css` and its conformance test suites from Web Platform Tests (WPT) and Hypothesis.
+
+## Commands
+
+* Install dependencies: `uv sync`
+* Run test suite: `uv run pytest`
+* Lint and format check: `uv run ruff check`
+* Regenerate spec tables and types: `uv run python codegen/gen_specs.py`
+* Verify generated spec tables are current: `uv run python codegen/gen_specs.py --check`
+* Regenerate WPT test suite: `uv run python codegen/gen_wpt_tests.py --wpt-dir <path-to-wpt-css>`
+* Verify generated WPT tests are current: `uv run python codegen/gen_wpt_tests.py --check`
+* Diff upstream `@webref/css` & WPT and emit an agent Issue report: `uv run python codegen/check_upstream.py [--webref-dir <dir>] [--wpt-dir <dir>] [--min-engines 0..3] [--format markdown|json] [--update-baseline]`
+* Inspect CSS syntax or `@font-face` descriptors: `uv run stixis inspect <target> [--json]`
+* Validate and canonicalize a CSS value: `uv run stixis check <target> <value> [--at-rule <name>] [--min-engines 0..3]`
+
+## Architecture & Invariants
+
+* **Zero runtime dependencies**: Everything under `src/stixis/` must use only the Python 3.14+ standard library (`string.templatelib`, `dataclasses`, `bisect`, `math`, `re`, `argparse`, `json`).
+* **Never hand-edit generated files**: `src/stixis/_generated/` (`units.py`, `specs.py`, `types.py`) and `tests/_generated/` (`test_wpt_*.py`) are produced by `codegen/gen_specs.py` and `codegen/gen_wpt_tests.py`. Put grammar fixes, prose aliases, and `[support]` thresholds in `codegen/spec_patches.toml` and rerun the generators.
+* **Multi-engine stability gate with 1-engine toggle**: By default (`SerializationOptions(min_engines=2)`), Stixis enables properties implemented in 2+ core browser engines (Blink, Gecko, WebKit) plus `ALWAYS_ALLOWED_PROPERTIES` in `codegen/spec_patches.toml`, avoiding single-engine spec churn. Pass `SerializationOptions(min_engines=1)` (or `SerializationOptions.cleome(min_engines=1)`), `extra_properties=frozenset({"prop-name"})`, or add to `[support] allow_properties` in `codegen/spec_patches.toml` to enable 1-engine features on demand.
+* **Eager validation on AST nodes**: `StyleRule`, `AtRule`, `FontFace`, `StyleSheet`, `CommentNode`, and `RawDeclaration` (`src/stixis/nodes.py`) are frozen dataclasses (`dataclass(frozen=True, slots=True)`) that validate all selectors, preludes, descriptors, declarations, and comments inside `__post_init__`.
+* **Value vs. raw CSS boundary**:
+  * `serialize_value(target, value)` serializes structured Python values (`int`, `float`, `tuple`, `list`, `dict`, `set`, `Dimension`, `Pct`, `Deg`, `Url`, `LocalFont`, `FontSrc`, `Keyword`, `GenericFamily`, and PEP 750 `Template`). A plain Python `str` passed to `<family-name>` or `font-family` is always treated as a font family name (quoted by default); generic families require `generic("serif")` or `Keyword("serif")`.
+  * `canonicalize(target, css_text)` tokenizes and validates raw CSS value text against the compiled `ValueNode` grammar and emits canonical CSSOM text.
+* **Entrypoint guard**: Any runnable Python snippet in `README.md` or any script using `multiprocessing` must wrap top-level execution in `if __name__ == "__main__":`.
+* **CLI contract**: `src/stixis/cli.py` is strictly read-only, never branches on agent-detection environment variables, never mixes `nargs="*"`/`"+"` optional flags with positional arguments, and exits with `0` (valid), `1` (validation error), `2` (usage error), or `4` (unknown target).
+
+## Domain Guides
+
+* Read [.agents/docs/grammar-and-codegen.md](.agents/docs/grammar-and-codegen.md) when modifying the Value Definition Syntax parser/evaluator (`src/stixis/syntax.py`), adding spec overrides in `codegen/spec_patches.toml`, or updating `codegen/gen_specs.py` and `codegen/gen_wpt_tests.py`.
+* Read [.agents/docs/microsyntaxes-and-cssom.md](.agents/docs/microsyntaxes-and-cssom.md) when modifying CSSOM primitive serialization (`src/stixis/primitives.py`), `SerializationOptions` presets (`src/stixis/options.py`), or the five microsyntax modules (`src/stixis/microsyntax/`).

stixis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Masataka Yakura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stixis-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: stixis
+Version: 0.1.0
+Summary: Spec-driven CSS serializer and validator generated from W3C @webref/css and Web Platform Tests
+Project-URL: Homepage, https://github.com/myakura/stixis
+Project-URL: Repository, https://github.com/myakura/stixis.git
+Project-URL: Issues, https://github.com/myakura/stixis/issues
+Author-email: Masataka Yakura <myakura.web@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: css,cssom,font-face,pep-750,serializer,validator,webref,wpt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Stixis
+
+**Stixis** (`stixis`) is a spec-driven, zero-dependency CSS serializer and validator for Python 3.14+ that generates its grammar tables and `TypedDict` definitions from W3C `@webref/css` (`ed/css/*.json`) and its conformance test suites from Web Platform Tests (WPT) and Hypothesis.
+
+## Highlights
+
+* **100% `@webref/css` property & descriptor coverage**: Compiles W3C Value Definition Syntax (`|`, `||`, `&&`, juxtaposition, `?`, `*`, `+`, `#`, `{A,B}`, `[...]!`, `<type [min,max]>`, `<'prop'>`) into a dual-mode `ValueNode` evaluator that serializes structured Python objects (`serialize_value`) and canonicalizes raw CSS token streams (`canonicalize`).
+* **Eagerly validated immutable AST nodes**: `FontFace`, `StyleRule`, `AtRule`, `StyleSheet`, `CommentNode`, and `RawDeclaration` (`dataclass(frozen=True, slots=True)`) validate selectors, preludes, descriptors, and declarations inside `__post_init__`.
+* **First-class Python 3.14+ PEP 750 `Template` (`t"..."`) support**: Separates static CSS syntax from dynamic `Interpolation` slots, applying context-aware escaping inside comments (`/* ... */`), strings, `url(...)`, and numeric slots before validating the resulting token stream against the `ValueNode` grammar.
+* **Five built-in CSS microsyntaxes**:
+  1. `<urange>` (`parse_urange`, `format_urange`, and `bisect`-based cascade-shadowing range compaction `compact_urange`).
+  2. `<opentype-tag>` (`font-feature-settings`, `font-variation-settings`, `font-language-override`).
+  3. `<font-src-list>` (`FontSrc`, `Url`, `LocalFont` with `format()` -> `tech()` ordering and keyword validation).
+  4. `<family-name>` & `<generic-family>` (safe default quoting of Python `str` family names, explicit `generic("serif")` / `Keyword("serif")`, and WPT `font-family-serialization-001.html` conformance).
+  5. `{1,2}` descriptor and property ranges (`font-weight`, `font-width` / `font-stretch`, `font-style: oblique`, metric overrides).
+* **Agent-first read-only CLI**: `stixis inspect` and `stixis check` with deterministic exit codes (`0` valid, `1` invalid value, `2` usage error, `4` unknown target).
+
+## Quickstart
+
+```python
+from stixis import (
+    Deg,
+    FontFace,
+    FontSrc,
+    Pct,
+    Px,
+    SerializationOptions,
+    StyleRule,
+    StyleSheet,
+    compact_urange,
+    dumps,
+    generic,
+)
+
+if __name__ == "__main__":
+    woff2_url = "https://example.com/fonts/noto-sans-jp-slice0.woff2"
+    slice_id = "kana"
+    size_kb = 18.4
+
+    urange = compact_urange(
+        sorted_target_cps=[0x3000, 0x3041, 0x3042, 0x3044],
+        forbidden_sorted=[0x3043],
+        max_gap=0x80,
+    )
+
+    sheet = StyleSheet(
+        header_comment="Generated by Stixis",
+        rules=[
+            FontFace(
+                comment=t"Slice [{slice_id}] ({size_kb:.1f} KB)",
+                font_family="Noto Sans JP",
+                font_style=("oblique", Deg(-10), Deg(20)),
+                font_weight=(100, 900),
+                font_width=(Pct(75), Pct(125)),
+                font_display="swap",
+                src=t"url({woff2_url}) format(woff2) tech(variations)",
+                unicode_range=urange,
+            ),
+            StyleRule(
+                "body",
+                {
+                    "font_family": ["Noto Sans JP", generic("sans-serif")],
+                    "font_feature_settings": {"liga": True, "dlig": False},
+                    "margin": Px(0),
+                },
+            ),
+        ],
+    )
+
+    print(dumps(sheet))
+    print(dumps(sheet, options=SerializationOptions.cleome()))
+```
+
+## CLI Usage
+
+```bash
+# Inspect an at-rule, property, or <type>
+uv run stixis inspect @font-face
+uv run stixis inspect font-style --json
+uv run stixis inspect "<font-src>"
+
+# Validate and canonicalize CSS values
+uv run stixis check font-weight "100 900" --at-rule @font-face
+uv run stixis check unicode-range "u+3040-309f" --at-rule @font-face
+```
+
+## Development & Verification
+
+```bash
+uv sync
+uv run python codegen/gen_specs.py --check
+uv run python codegen/gen_wpt_tests.py --check
+uv run pytest
+uv run ruff check
+```

stixis-0.1.0/README.md

@@ -0,0 +1,95 @@
+# Stixis
+
+**Stixis** (`stixis`) is a spec-driven, zero-dependency CSS serializer and validator for Python 3.14+ that generates its grammar tables and `TypedDict` definitions from W3C `@webref/css` (`ed/css/*.json`) and its conformance test suites from Web Platform Tests (WPT) and Hypothesis.
+
+## Highlights
+
+* **100% `@webref/css` property & descriptor coverage**: Compiles W3C Value Definition Syntax (`|`, `||`, `&&`, juxtaposition, `?`, `*`, `+`, `#`, `{A,B}`, `[...]!`, `<type [min,max]>`, `<'prop'>`) into a dual-mode `ValueNode` evaluator that serializes structured Python objects (`serialize_value`) and canonicalizes raw CSS token streams (`canonicalize`).
+* **Eagerly validated immutable AST nodes**: `FontFace`, `StyleRule`, `AtRule`, `StyleSheet`, `CommentNode`, and `RawDeclaration` (`dataclass(frozen=True, slots=True)`) validate selectors, preludes, descriptors, and declarations inside `__post_init__`.
+* **First-class Python 3.14+ PEP 750 `Template` (`t"..."`) support**: Separates static CSS syntax from dynamic `Interpolation` slots, applying context-aware escaping inside comments (`/* ... */`), strings, `url(...)`, and numeric slots before validating the resulting token stream against the `ValueNode` grammar.
+* **Five built-in CSS microsyntaxes**:
+  1. `<urange>` (`parse_urange`, `format_urange`, and `bisect`-based cascade-shadowing range compaction `compact_urange`).
+  2. `<opentype-tag>` (`font-feature-settings`, `font-variation-settings`, `font-language-override`).
+  3. `<font-src-list>` (`FontSrc`, `Url`, `LocalFont` with `format()` -> `tech()` ordering and keyword validation).
+  4. `<family-name>` & `<generic-family>` (safe default quoting of Python `str` family names, explicit `generic("serif")` / `Keyword("serif")`, and WPT `font-family-serialization-001.html` conformance).
+  5. `{1,2}` descriptor and property ranges (`font-weight`, `font-width` / `font-stretch`, `font-style: oblique`, metric overrides).
+* **Agent-first read-only CLI**: `stixis inspect` and `stixis check` with deterministic exit codes (`0` valid, `1` invalid value, `2` usage error, `4` unknown target).
+
+## Quickstart
+
+```python
+from stixis import (
+    Deg,
+    FontFace,
+    FontSrc,
+    Pct,
+    Px,
+    SerializationOptions,
+    StyleRule,
+    StyleSheet,
+    compact_urange,
+    dumps,
+    generic,
+)
+
+if __name__ == "__main__":
+    woff2_url = "https://example.com/fonts/noto-sans-jp-slice0.woff2"
+    slice_id = "kana"
+    size_kb = 18.4
+
+    urange = compact_urange(
+        sorted_target_cps=[0x3000, 0x3041, 0x3042, 0x3044],
+        forbidden_sorted=[0x3043],
+        max_gap=0x80,
+    )
+
+    sheet = StyleSheet(
+        header_comment="Generated by Stixis",
+        rules=[
+            FontFace(
+                comment=t"Slice [{slice_id}] ({size_kb:.1f} KB)",
+                font_family="Noto Sans JP",
+                font_style=("oblique", Deg(-10), Deg(20)),
+                font_weight=(100, 900),
+                font_width=(Pct(75), Pct(125)),
+                font_display="swap",
+                src=t"url({woff2_url}) format(woff2) tech(variations)",
+                unicode_range=urange,
+            ),
+            StyleRule(
+                "body",
+                {
+                    "font_family": ["Noto Sans JP", generic("sans-serif")],
+                    "font_feature_settings": {"liga": True, "dlig": False},
+                    "margin": Px(0),
+                },
+            ),
+        ],
+    )
+
+    print(dumps(sheet))
+    print(dumps(sheet, options=SerializationOptions.cleome()))
+```
+
+## CLI Usage
+
+```bash
+# Inspect an at-rule, property, or <type>
+uv run stixis inspect @font-face
+uv run stixis inspect font-style --json
+uv run stixis inspect "<font-src>"
+
+# Validate and canonicalize CSS values
+uv run stixis check font-weight "100 900" --at-rule @font-face
+uv run stixis check unicode-range "u+3040-309f" --at-rule @font-face
+```
+
+## Development & Verification
+
+```bash
+uv sync
+uv run python codegen/gen_specs.py --check
+uv run python codegen/gen_wpt_tests.py --check
+uv run pytest
+uv run ruff check
+```