@aihu/css-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fellwork
+
+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.

package/README.md

@@ -0,0 +1,122 @@
+# @aihu/css-engine
+
+> **Aihu** — agentic discovery and interaction, for human purpose.
+
+aihu CSS engine — Tailwind v4 hard fork with WC-native scoped output.
+
+Part of the **compiler + toolchain** layer of Aihu. Build-time only — does not ship to the client. The compiler reads `.aihu` SFC source (per the [Block Structure spec](../../docs/superpowers/specs/2026-05-02-spec-block-structure.md)) and emits standards-compliant Web Components.
+
+<!-- BEGIN_HANDWRITTEN: prose -->
+> aihu CSS engine — a hard fork of Tailwind v4 with Web-Component-native scoped output, AST-aware scanning, and progressive feature emission.
+
+**Status:** v0 — bootstrap. The fork's identity, perf optimizations, and scoped emitter are all under construction. See [`docs/superpowers/specs/2026-05-10-aihu-css-engine-and-primitives-design.md`](../../docs/superpowers/specs/2026-05-10-aihu-css-engine-and-primitives-design.md) for the full design.
+
+### Status by capability (Plan 1 bootstrap)
+
+| Capability | Plan that lands it |
+|---|---|
+| Package builds; compile pipeline scaffolded | **Plan 1 (this one)** |
+| AST scanner consuming `@aihu/compiler` | Plan 2 |
+| Scoped-output mode (`:host` embedding) | Plan 2 |
+| WC-native variants (`host:`, `slotted:`, `part-*:`) | Plan 2 |
+| Progressive features (`view-transition:`, `anchor:`, etc.) | Plan 3 |
+| Style packs (`aihu-default`, `aihu-graphite`) | Plan 3 |
+| `cn()` runtime helper | Plan 3 |
+
+### Local development
+
+```bash
+# Build Rust core (run from repo root or this dir)
+cargo build --release -p aihu-css-core
+
+# Build TS layer
+bun run build
+
+# Run tests
+bun run test         # vitest e2e
+bun run test:rust    # cargo + insta snapshots
+```
+<!-- END_HANDWRITTEN: prose -->
+
+## Install
+
+<!-- BEGIN_AUTOGEN: install -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+```bash
+npm install @aihu/css-engine
+# or
+bun add @aihu/css-engine
+```
+
+<sub><i>Auto-generated against `@aihu/css-engine@0.1.0`.</i></sub>
+
+<!-- END_AUTOGEN: install -->
+
+## Package facts
+
+<!-- BEGIN_AUTOGEN: stats -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+| | |
+|---|---|
+| **Version** | `0.1.0` |
+| **Tier** | D — Compiler — CSS engine (Tailwind v4 hard fork, WC-native scoped output) |
+| **Published files** | 5 entries |
+| **License** | MIT |
+
+<sub><i>Auto-generated against `@aihu/css-engine@0.1.0`.</i></sub>
+
+<!-- END_AUTOGEN: stats -->
+
+## Exports
+
+<!-- BEGIN_AUTOGEN: exports -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+| Subpath | ESM | CJS |
+|---|---|---|
+| `.` | `./dist/index.js` | `—` |
+| `./runtime/cn` | `./dist/runtime/cn.js` | `—` |
+| `./runtime/progressive` | `./dist/runtime/progressive.js` | `—` |
+
+<sub><i>Auto-generated against `@aihu/css-engine@0.1.0`.</i></sub>
+
+<!-- END_AUTOGEN: exports -->
+
+## Dependencies
+
+<!-- BEGIN_AUTOGEN: deps -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+**Dependencies:**
+
+- `@aihu/compiler` — `workspace:*`
+
+<sub><i>Auto-generated against `@aihu/css-engine@0.1.0`.</i></sub>
+
+<!-- END_AUTOGEN: deps -->
+
+## See also
+
+<!-- BEGIN_AUTOGEN: see-also -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+- [CSS Engine + Primitives design spec](../../docs/superpowers/specs/2026-05-10-aihu-css-engine-and-primitives-design.md)
+- [@aihu/compiler](../compiler)
+- [Aihu framework root](../../README.md)
+
+<sub><i>Auto-generated against `@aihu/css-engine@0.1.0`.</i></sub>
+
+<!-- END_AUTOGEN: see-also -->
+
+## License
+
+<!-- BEGIN_AUTOGEN: license -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+MIT — see [LICENSE](../../LICENSE).
+
+<sub><i>Auto-generated against `@aihu/css-engine@0.1.0`.</i></sub>
+
+<!-- END_AUTOGEN: license -->

package/crates/aihu-css-core/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "aihu-css-core"
+version = "0.0.0"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "aihu CSS engine core — utility compilation and CSS emission."
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+path = "src/lib.rs"
+
+[[bin]]
+name = "aihu-css-compile"
+path = "src/bin/main.rs"
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+[dev-dependencies]
+insta = { version = "1", features = ["yaml"] }

package/crates/aihu-css-core/src/ast.rs

@@ -0,0 +1,173 @@
+//! `ast.rs` — serde `Deserialize` mirror of the compiler's `--ast-json` output.
+//!
+//! This is the wire-format contract the scanner consumes. It mirrors the
+//! `SfcAst` shape emitted by `@aihu/compiler`'s `compile_to_ast` /
+//! `aihu-compile --ast-json` (see `docs/superpowers/specs/compiler-ast-export-hook.md`
+//! §4.1 / §4.3, CSS-engine spec `22d3a66e` §3 edge #1).
+//!
+//! The three `SfcAttr` variants (Static / Binding / Macro) are frozen as part
+//! of the v1.0 stability contract — the scanner's class-extraction correctness
+//! depends entirely on them staying distinct. `ast_version` is asserted on
+//! entry (§6 Q3 evolution policy): additive changes keep `1`; a breaking shape
+//! change bumps it and is rejected here with a clear error.
+
+use serde::Deserialize;
+
+/// The AST schema version this scanner understands. A mismatch is rejected by
+/// [`parse_ast`].
+pub const SUPPORTED_AST_VERSION: u32 = 1;
+
+/// Top-level AST export — one per `.aihu` SFC. Mirrors the compiler's
+/// `SfcAstOwned` / the TS `SfcAst` interface (spec §4.1).
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+pub struct SfcAst {
+    /// Resolved custom-element tag name (`meta.name` → `route.name` → file stem).
+    pub tag: String,
+    /// The `@style` block, if the SFC declared one.
+    #[serde(default)]
+    pub style: Option<SfcStyleBlock>,
+    /// Parsed template tree. `None` when the SFC has no `@template` block.
+    #[serde(default)]
+    pub template: Option<Vec<SfcNode>>,
+    /// SFC-level metadata.
+    pub meta: SfcMeta,
+    /// AST schema version — bumped on any breaking shape change.
+    #[serde(rename = "astVersion")]
+    pub ast_version: u32,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+pub struct SfcStyleBlock {
+    /// Verbatim CSS body of the `@style` block (braces stripped, `$global`
+    /// token removed by the compiler).
+    pub content: String,
+    /// `Scoped` (default) or `Global` (`@style { $global ... }`).
+    pub scope: SfcStyleScope,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum SfcStyleScope {
+    Scoped,
+    Global,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+pub struct SfcMeta {
+    /// From `@meta { name }` / `@route { name }` / file stem.
+    pub name: String,
+}
+
+/// Discriminated union mirroring the compiler's `SfcNodeOwned` (spec §4.1).
+/// Serialized with a `kind` tag (camelCase: `element`, `macroElement`, …).
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(tag = "kind", rename_all = "camelCase")]
+pub enum SfcNode {
+    Element {
+        tag: String,
+        #[serde(default)]
+        attrs: Vec<SfcAttr>,
+        #[serde(default)]
+        children: Vec<SfcNode>,
+    },
+    MacroElement {
+        name: String,
+        #[serde(default)]
+        attrs: Vec<SfcAttr>,
+        #[serde(default)]
+        children: Vec<SfcNode>,
+    },
+    Text {
+        value: String,
+    },
+    Interpolation {
+        expr: String,
+    },
+    IfBlock {
+        #[serde(default)]
+        branches: Vec<SfcIfBranch>,
+    },
+    #[serde(rename_all = "camelCase")]
+    EachBlock {
+        list: String,
+        item: String,
+        idx: Option<String>,
+        key: Option<String>,
+        #[serde(default)]
+        body: Vec<SfcNode>,
+        empty_body: Option<Vec<SfcNode>>,
+    },
+    HtmlBlock {
+        expr: String,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+pub struct SfcIfBranch {
+    pub cond: String,
+    #[serde(default)]
+    pub body: Vec<SfcNode>,
+}
+
+/// Discriminated union mirroring the compiler's `SfcAttrOwned` `Attr` — the
+/// three class-forms key on `kind` (lowercase: `static` / `binding` / `macro`).
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(tag = "kind", rename_all = "lowercase")]
+pub enum SfcAttr {
+    /// Form A — `class="btn primary"`.
+    Static { name: String, value: String },
+    /// Form B — `$class={expr}` (and array `$class={[a, b]}`).
+    Binding { name: String, expr: String },
+    /// Form C — `$class:active={cond}` (and `on:`/`bind:`/`emit:`/`if`/…).
+    Macro {
+        name: String,
+        #[allow(dead_code)]
+        value: SfcMacroValue,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(tag = "form", rename_all = "lowercase")]
+pub enum SfcMacroValue {
+    Quoted { value: String },
+    Curly { expr: String },
+    Boolean,
+}
+
+/// Parse a `--ast-json` payload into the typed [`SfcAst`], validating the
+/// schema version (spec §6 Q3). A version mismatch returns a descriptive
+/// error rather than silently mis-scanning a future shape.
+pub fn parse_ast(json: &str) -> Result<SfcAst, AstError> {
+    let ast: SfcAst = serde_json::from_str(json).map_err(AstError::Deserialize)?;
+    if ast.ast_version != SUPPORTED_AST_VERSION {
+        return Err(AstError::Version {
+            found: ast.ast_version,
+            supported: SUPPORTED_AST_VERSION,
+        });
+    }
+    Ok(ast)
+}
+
+/// Errors from [`parse_ast`].
+#[derive(Debug)]
+pub enum AstError {
+    /// JSON did not match the `SfcAst` wire shape.
+    Deserialize(serde_json::Error),
+    /// `astVersion` is not the version this scanner supports.
+    Version { found: u32, supported: u32 },
+}
+
+impl std::fmt::Display for AstError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            AstError::Deserialize(e) => write!(f, "failed to deserialize SfcAst: {e}"),
+            AstError::Version { found, supported } => write!(
+                f,
+                "unsupported astVersion {found} (this engine supports {supported}); \
+                 rebuild @aihu/compiler and @aihu/css-engine to matching versions"
+            ),
+        }
+    }
+}
+
+impl std::error::Error for AstError {}

package/crates/aihu-css-core/src/bin/main.rs

@@ -0,0 +1,73 @@
+//! aihu-css-compile — CLI entry for the engine.
+//!
+//! Two input modes:
+//!
+//! - **Class-list mode** (Plan 1, default): reads utility class names (one per
+//!   line / whitespace-separated) from stdin or a file argument, emits flat
+//!   `.class { … }` CSS to stdout.
+//! - **AST mode** (Plan 2, `--ast-json`): reads an `SfcAst` JSON (the output of
+//!   `aihu-compile --ast-json`) from stdin, emits scoped shadow-DOM CSS.
+
+use std::io::{self, Read, Write};
+
+fn main() {
+    let argv: Vec<String> = std::env::args().collect();
+
+    // Build-time mode: dump the conflict-group map (Plan 3 Task 9). The TS build
+    // step (`scripts/gen-cn-conflict-map.ts`) reads this to generate the `cn()`
+    // conflict map, so the runtime merge map never drifts from the utility table.
+    if argv.iter().any(|a| a == "--dump-conflict-groups") {
+        let groups = aihu_css_core::tokens::conflict_groups();
+        let json = serde_json::to_string(&groups).expect("serialize conflict groups");
+        println!("{json}");
+        return;
+    }
+
+    let ast_mode = argv.iter().any(|a| a == "--ast-json");
+
+    // Positional file arg = first non-flag argument after argv[0].
+    let file_arg = argv
+        .iter()
+        .skip(1)
+        .find(|a| !a.starts_with("--"))
+        .cloned();
+
+    let mut buf = String::new();
+    match &file_arg {
+        Some(path) => {
+            buf = std::fs::read_to_string(path).unwrap_or_else(|e| {
+                eprintln!("aihu-css-compile: failed to read {path}: {e}");
+                std::process::exit(2);
+            });
+        }
+        None => {
+            io::stdin()
+                .read_to_string(&mut buf)
+                .expect("failed reading stdin");
+        }
+    }
+
+    let css = if ast_mode {
+        match aihu_css_core::parse_ast(&buf) {
+            Ok(ast) => aihu_css_core::compile_sfc_scoped(&ast),
+            Err(e) => {
+                eprintln!("aihu-css-compile: {e}");
+                std::process::exit(1);
+            }
+        }
+    } else {
+        let classes: Vec<String> = buf
+            .lines()
+            .flat_map(|line| line.split_whitespace())
+            .filter(|s| !s.is_empty())
+            .map(String::from)
+            .collect();
+        aihu_css_core::compile_classes(&classes)
+    };
+
+    let stdout = io::stdout();
+    let mut handle = stdout.lock();
+    handle
+        .write_all(css.as_bytes())
+        .expect("failed writing stdout");
+}

package/crates/aihu-css-core/src/cache.rs

@@ -0,0 +1,182 @@
+//! `cache.rs` — AST-hashed per-SFC incremental compilation cache (Plan 2 Task 8).
+//!
+//! Keyed by a stable hash over `(SfcAst, ThemeRegistry version)`: a change to
+//! either input invalidates the entry. The hash is a fast non-cryptographic
+//! `DefaultHasher` — we want change detection, not security. The cache lives
+//! in-process (the Vite plugin / `aihu css build` holds it across the dev
+//! session) so an unchanged SFC recompiles in near-zero time (the `css-6`
+//! perf gate later asserts < 30 ms across a 50-SFC fixture).
+
+use std::collections::HashMap;
+use std::hash::{Hash, Hasher};
+
+use crate::ast::{SfcAst, SfcAttr, SfcNode, SfcStyleScope};
+use crate::emit::emit_sfc_scoped;
+
+/// An in-process compilation cache. Construct one per dev session / build run.
+#[derive(Debug, Default)]
+pub struct CssCache {
+    entries: HashMap<u64, String>,
+    /// Number of full recompiles performed — used by tests/benches to prove a
+    /// cache hit skipped the compile path.
+    recompiles: u64,
+    /// Number of cache hits served.
+    hits: u64,
+}
+
+impl CssCache {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Compile an SFC, returning a cached result on an unchanged-input hit.
+    /// `theme_version` participates in the key so a theme change invalidates
+    /// every entry.
+    pub fn compile(&mut self, ast: &SfcAst, theme_version: u64) -> String {
+        let key = hash_ast(ast, theme_version);
+        if let Some(cached) = self.entries.get(&key) {
+            self.hits += 1;
+            return cached.clone();
+        }
+        self.recompiles += 1;
+        let css = emit_sfc_scoped(ast);
+        self.entries.insert(key, css.clone());
+        css
+    }
+
+    /// Total full recompiles since construction.
+    pub fn recompiles(&self) -> u64 {
+        self.recompiles
+    }
+
+    /// Total cache hits since construction.
+    pub fn hits(&self) -> u64 {
+        self.hits
+    }
+
+    /// Number of distinct entries currently cached.
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    /// Drop all cached entries (keeps the hit/recompile counters).
+    pub fn clear(&mut self) {
+        self.entries.clear();
+    }
+}
+
+/// Compute a stable change-detection hash over the AST + theme version.
+pub fn hash_ast(ast: &SfcAst, theme_version: u64) -> u64 {
+    let mut h = std::collections::hash_map::DefaultHasher::new();
+    theme_version.hash(&mut h);
+    hash_sfc(ast, &mut h);
+    h.finish()
+}
+
+fn hash_sfc(ast: &SfcAst, h: &mut impl Hasher) {
+    ast.tag.hash(h);
+    ast.ast_version.hash(h);
+    match &ast.style {
+        Some(s) => {
+            1u8.hash(h);
+            s.content.hash(h);
+            matches!(s.scope, SfcStyleScope::Global).hash(h);
+        }
+        None => 0u8.hash(h),
+    }
+    match &ast.template {
+        Some(nodes) => {
+            1u8.hash(h);
+            for n in nodes {
+                hash_node(n, h);
+            }
+        }
+        None => 0u8.hash(h),
+    }
+}
+
+fn hash_node(node: &SfcNode, h: &mut impl Hasher) {
+    match node {
+        SfcNode::Element { tag, attrs, children } => {
+            0u8.hash(h);
+            tag.hash(h);
+            for a in attrs {
+                hash_attr(a, h);
+            }
+            for c in children {
+                hash_node(c, h);
+            }
+        }
+        SfcNode::MacroElement { name, attrs, children } => {
+            1u8.hash(h);
+            name.hash(h);
+            for a in attrs {
+                hash_attr(a, h);
+            }
+            for c in children {
+                hash_node(c, h);
+            }
+        }
+        SfcNode::Text { value } => {
+            2u8.hash(h);
+            value.hash(h);
+        }
+        SfcNode::Interpolation { expr } => {
+            3u8.hash(h);
+            expr.hash(h);
+        }
+        SfcNode::IfBlock { branches } => {
+            4u8.hash(h);
+            for b in branches {
+                b.cond.hash(h);
+                for c in &b.body {
+                    hash_node(c, h);
+                }
+            }
+        }
+        SfcNode::EachBlock { list, item, idx, key, body, empty_body } => {
+            5u8.hash(h);
+            list.hash(h);
+            item.hash(h);
+            idx.hash(h);
+            key.hash(h);
+            for c in body {
+                hash_node(c, h);
+            }
+            if let Some(eb) = empty_body {
+                for c in eb {
+                    hash_node(c, h);
+                }
+            }
+        }
+        SfcNode::HtmlBlock { expr } => {
+            6u8.hash(h);
+            expr.hash(h);
+        }
+    }
+}
+
+fn hash_attr(attr: &SfcAttr, h: &mut impl Hasher) {
+    // Only the class-bearing attrs affect CSS output, but hashing all attrs is
+    // cheap and keeps the key robust against future emit changes.
+    match attr {
+        SfcAttr::Static { name, value } => {
+            0u8.hash(h);
+            name.hash(h);
+            value.hash(h);
+        }
+        SfcAttr::Binding { name, expr } => {
+            1u8.hash(h);
+            name.hash(h);
+            expr.hash(h);
+        }
+        SfcAttr::Macro { name, .. } => {
+            2u8.hash(h);
+            name.hash(h);
+        }
+    }
+}