@aihu/css-engine 0.1.0

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

@@ -0,0 +1,200 @@
+//! `progressive.rs` — `ProgressiveFeature` trait + registry + `@supports` emitter.
+//!
+//! Plan 3 Task 4. A *progressive feature* is a forward-looking CSS feature
+//! gated behind `@supports`, optionally with a JS runtime fallback. The engine
+//! ships four built-ins (`view_transition`, `anchor`, `popover`, `text_balance`
+//! — see `features/`), but the trait is open so additional features can be
+//! registered.
+//!
+//! ## Fallback contract
+//!
+//! Each feature owns four facts:
+//! - its **variant prefix** (`view-transition`, `anchor`, `popover`, `text-balance`)
+//! - the **`@supports` condition** (or `None` = "always emit, silently ignored
+//!   if unsupported" — no gate at all)
+//! - the **gated CSS** it emits for a given base utility/declaration
+//! - whether it dispatches a **JS fallback** (`Some(export-name)`) or is
+//!   **CSS-only** (`None`)
+//!
+//! The emitter wraps gated CSS in `@supports (...)` when a condition is present,
+//! and emits a small `/* aihu:progressive-fallback ... */` marker (read by the
+//! TS layer to wire `@aihu/css-engine/runtime/progressive`) ONLY for features
+//! whose `js_fallback()` is non-`None`. CSS-only features (`view-transition:`,
+//! `text-balance:`) never produce a JS marker.
+
+/// A forward-looking CSS feature gated behind `@supports`, optionally with a
+/// JS runtime fallback. Each feature owns: its variant prefix, the `@supports`
+/// condition, the gated CSS it emits, and whether it dispatches a JS fallback.
+pub trait ProgressiveFeature {
+    /// The variant prefix, e.g. "view-transition", "anchor", "popover", "text-balance".
+    fn prefix(&self) -> &'static str;
+    /// The `@supports(...)` condition string, or None for "always emit, silently ignored if unsupported".
+    fn supports_condition(&self) -> Option<&'static str>;
+    /// Emit the gated CSS for a given base utility/declaration.
+    fn emit_css(&self, base: &str) -> String;
+    /// Runtime fallback descriptor: which `@aihu/css-engine/runtime/progressive`
+    /// export to dispatch when `@supports` fails. None = silent CSS no-op (no JS).
+    fn js_fallback(&self) -> Option<&'static str>;
+}
+
+/// A registry of progressive features, keyed by variant prefix. The emitter
+/// consults it when it encounters a variant prefix that names a registered
+/// feature, routing to the progressive emitter instead of the standard
+/// selector path.
+pub struct ProgressiveRegistry {
+    features: Vec<Box<dyn ProgressiveFeature + Send + Sync>>,
+}
+
+impl ProgressiveRegistry {
+    /// An empty registry.
+    pub fn new() -> Self {
+        Self {
+            features: Vec::new(),
+        }
+    }
+
+    /// The default registry seeded with the four built-in features. Features are
+    /// added to this constructor as they land (Tasks 5–8): `view-transition:`,
+    /// `anchor:`, `popover:`, `text-balance:`.
+    pub fn with_builtins() -> Self {
+        let mut r = Self::new();
+        crate::features::register_builtins(&mut r);
+        r
+    }
+
+    /// Register a feature.
+    pub fn register(&mut self, feature: Box<dyn ProgressiveFeature + Send + Sync>) {
+        self.features.push(feature);
+    }
+
+    /// Look up a feature by its variant prefix.
+    pub fn get(&self, prefix: &str) -> Option<&(dyn ProgressiveFeature + Send + Sync)> {
+        self.features
+            .iter()
+            .find(|f| f.prefix() == prefix)
+            .map(|f| f.as_ref())
+    }
+
+    /// True if `prefix` names a registered progressive feature.
+    pub fn is_feature(&self, prefix: &str) -> bool {
+        self.features.iter().any(|f| f.prefix() == prefix)
+    }
+
+    /// Emit the CSS (and optional JS-fallback marker) for a feature `prefix`
+    /// applied to `base`. Returns `None` if `prefix` is not registered.
+    ///
+    /// Output shape:
+    /// - with a `@supports` condition: `@supports (<cond>) { <css> }`
+    /// - without a condition: the bare `<css>` (silently ignored if unsupported)
+    /// - plus, ONLY when `js_fallback()` is `Some`, a trailing
+    ///   `/* aihu:progressive-fallback <export> (when not <cond>) */` marker.
+    pub fn emit(&self, prefix: &str, base: &str) -> Option<String> {
+        let feature = self.get(prefix)?;
+        Some(emit_feature(feature, base))
+    }
+}
+
+impl Default for ProgressiveRegistry {
+    fn default() -> Self {
+        Self::with_builtins()
+    }
+}
+
+/// Emit the `@supports`-gated CSS (+ optional JS marker) for one feature.
+pub fn emit_feature(feature: &(dyn ProgressiveFeature + Send + Sync), base: &str) -> String {
+    let css = feature.emit_css(base);
+    let mut out = match feature.supports_condition() {
+        Some(cond) => format!("@supports ({cond}) {{\n  {css}\n}}\n"),
+        None => format!("{css}\n"),
+    };
+
+    // JS fallback marker — ONLY for features with a non-None fallback. The TS
+    // layer scans for this marker to wire the runtime/progressive dispatch.
+    if let Some(export) = feature.js_fallback() {
+        let cond = feature.supports_condition().unwrap_or("");
+        out.push_str(&format!(
+            "/* aihu:progressive-fallback {export} (when not @supports {cond}) */\n"
+        ));
+    }
+
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // A dummy feature with a @supports gate AND a JS fallback.
+    struct GatedWithJs;
+    impl ProgressiveFeature for GatedWithJs {
+        fn prefix(&self) -> &'static str {
+            "gated"
+        }
+        fn supports_condition(&self) -> Option<&'static str> {
+            Some("display: grid")
+        }
+        fn emit_css(&self, base: &str) -> String {
+            format!(".{base} {{ display: grid; }}")
+        }
+        fn js_fallback(&self) -> Option<&'static str> {
+            Some("gatedFallback")
+        }
+    }
+
+    // A dummy CSS-only feature: no gate, no JS.
+    struct CssOnly;
+    impl ProgressiveFeature for CssOnly {
+        fn prefix(&self) -> &'static str {
+            "plain"
+        }
+        fn supports_condition(&self) -> Option<&'static str> {
+            None
+        }
+        fn emit_css(&self, base: &str) -> String {
+            format!(".{base} {{ color: red; }}")
+        }
+        fn js_fallback(&self) -> Option<&'static str> {
+            None
+        }
+    }
+
+    #[test]
+    fn supports_gate_wraps_css() {
+        let out = emit_feature(&GatedWithJs, "thing");
+        assert!(out.contains("@supports (display: grid)"), "gated CSS wrapped: {out}");
+        assert!(out.contains("display: grid;"));
+    }
+
+    #[test]
+    fn js_fallback_feature_emits_marker() {
+        let out = emit_feature(&GatedWithJs, "thing");
+        assert!(
+            out.contains("aihu:progressive-fallback gatedFallback"),
+            "non-None fallback emits a JS marker: {out}"
+        );
+    }
+
+    #[test]
+    fn css_only_feature_emits_no_marker_and_no_gate() {
+        let out = emit_feature(&CssOnly, "thing");
+        assert!(!out.contains("@supports"), "None condition → no @supports gate: {out}");
+        assert!(
+            !out.contains("aihu:progressive-fallback"),
+            "None fallback → no JS marker: {out}"
+        );
+        assert!(out.contains("color: red;"));
+    }
+
+    #[test]
+    fn registry_routes_by_prefix() {
+        let mut reg = ProgressiveRegistry::new();
+        reg.register(Box::new(GatedWithJs));
+        reg.register(Box::new(CssOnly));
+        assert!(reg.is_feature("gated"));
+        assert!(reg.is_feature("plain"));
+        assert!(!reg.is_feature("nope"));
+        let out = reg.emit("gated", "thing").unwrap();
+        assert!(out.contains("@supports"));
+        assert!(reg.emit("nope", "x").is_none());
+    }
+}

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

@@ -0,0 +1,235 @@
+//! `scanner.rs` — walks an `SfcAst` template and extracts the utility set.
+//!
+//! The scanner branches on the three class-forms exactly as the compiler routes
+//! them (spec `22d3a66e` §3, AST-hook spec §3):
+//!
+//! - **`SfcAttr::Static { name: "class", value }`** (Form A) → split on ASCII
+//!   whitespace; every token (including variant-prefixed ones like `host:bg-x`)
+//!   is a candidate utility. Variant prefixes are kept verbatim so the emitter
+//!   (`variants.rs` / `emit.rs`) can split them at emit time.
+//! - **`SfcAttr::Binding { name: "class", expr }`** (Form B) → string literals
+//!   embedded in the expr are extractable utilities; bare identifiers are
+//!   tracked in `unresolved` for `aihu css doctor` diagnostics (spec §3 edge #5).
+//! - **`SfcAttr::Macro { name }`** where `name` starts with `class:` (Form C) →
+//!   the part after `class:` is a statically-known utility.
+//! - **Any other attr** (`on:click`, `if`, `bind:value`, non-`class`) → ignored.
+//! - **`MacroElement` / component nodes** → their `class` attrs are skipped
+//!   (edge E10: components own their own shadow scope).
+//!
+//! We do NOT re-parse `.aihu` source with regex (Risk #4) — only the AST.
+
+use std::collections::BTreeSet;
+
+use crate::ast::{SfcAst, SfcAttr, SfcNode};
+
+/// The result of scanning an `SfcAst` template.
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
+pub struct ScanResult {
+    /// Sorted, dedup'd set of utility class literals (variant prefixes intact).
+    pub utilities: BTreeSet<String>,
+    /// Identifiers / sub-expressions a `Binding` could not statically resolve
+    /// (e.g. `size` in `cn('btn', size)`). Surfaced for diagnostics; not
+    /// compiled. Deduped + sorted for determinism.
+    pub unresolved: BTreeSet<String>,
+}
+
+/// Convenience: scan an AST and return only the utility set (back-compat with
+/// the plan's `scan_ast(&ast).contains(...)` test shape).
+pub fn scan_ast(ast: &SfcAst) -> BTreeSet<String> {
+    scan(ast).utilities
+}
+
+/// Walk the SFC template and collect the full [`ScanResult`].
+pub fn scan(ast: &SfcAst) -> ScanResult {
+    let mut result = ScanResult::default();
+    if let Some(nodes) = &ast.template {
+        for node in nodes {
+            walk(node, &mut result);
+        }
+    }
+    result
+}
+
+fn walk(node: &SfcNode, out: &mut ScanResult) {
+    match node {
+        SfcNode::Element { attrs, children, .. } => {
+            for attr in attrs {
+                collect_attr(attr, out);
+            }
+            for child in children {
+                walk(child, out);
+            }
+        }
+        // Edge E10: component / macroElement nodes own their own shadow scope.
+        // We do NOT compile their `class` attrs into the parent's sheet, but we
+        // still descend into children (slots may contain HTML elements).
+        SfcNode::MacroElement { children, .. } => {
+            for child in children {
+                walk(child, out);
+            }
+        }
+        SfcNode::IfBlock { branches } => {
+            for branch in branches {
+                for child in &branch.body {
+                    walk(child, out);
+                }
+            }
+        }
+        SfcNode::EachBlock {
+            body, empty_body, ..
+        } => {
+            for child in body {
+                walk(child, out);
+            }
+            if let Some(empty) = empty_body {
+                for child in empty {
+                    walk(child, out);
+                }
+            }
+        }
+        // Text / Interpolation / HtmlBlock carry no class attrs.
+        SfcNode::Text { .. } | SfcNode::Interpolation { .. } | SfcNode::HtmlBlock { .. } => {}
+    }
+}
+
+fn collect_attr(attr: &SfcAttr, out: &mut ScanResult) {
+    match attr {
+        // Form A — static class="...".
+        SfcAttr::Static { name, value } if name == "class" => {
+            for token in value.split_ascii_whitespace() {
+                // Interpolation placeholders like `{dynamic}` (edge E9) are not
+                // literal utilities — flag, don't compile.
+                if token.contains('{') || token.contains('}') {
+                    out.unresolved.insert(token.to_string());
+                } else {
+                    out.utilities.insert(token.to_string());
+                }
+            }
+        }
+        // Form B — $class={expr} / $class={[...]}.
+        SfcAttr::Binding { name, expr } if name == "class" => {
+            collect_binding(expr, out);
+        }
+        // Form C — $class:name={cond} → name after `class:` is the utility.
+        SfcAttr::Macro { name, .. } if name.starts_with("class:") => {
+            if let Some(class) = name.strip_prefix("class:") {
+                if !class.is_empty() {
+                    out.utilities.insert(class.to_string());
+                }
+            }
+        }
+        // Any other attr (on:click, if, bind:value, non-class static/binding).
+        _ => {}
+    }
+}
+
+/// Extract utility string-literals from a `$class={expr}` expression.
+///
+/// Two sub-cases (AST-hook spec §3 Form B):
+/// - **Array literal** (`[...]`): walk elements; string literals are utilities,
+///   non-literal elements contribute their embedded literals + their bare
+///   identifiers go to `unresolved`.
+/// - **Scalar** (`cn(...)`, a ternary, a bare identifier): extract embedded
+///   string literals; the rest is unresolvable.
+///
+/// We extract any single- or double-quoted string literal as a class token.
+/// Bare identifiers (top-level, outside a string) are recorded in `unresolved`.
+fn collect_binding(expr: &str, out: &mut ScanResult) {
+    let literals = extract_string_literals(expr);
+    let had_literals = !literals.is_empty();
+    for lit in &literals {
+        // A literal may itself hold a space-separated class list.
+        for token in lit.split_ascii_whitespace() {
+            out.utilities.insert(token.to_string());
+        }
+    }
+    // Record identifiers we could not resolve so diagnostics can warn about
+    // utilities that may ship dynamically (spec §3 edge #5 LOW concern).
+    for ident in extract_bare_identifiers(expr) {
+        out.unresolved.insert(ident);
+    }
+    // A binding with no resolvable literals at all (e.g. a bare `{theme}`) — its
+    // identifiers are already in `unresolved`; nothing to compile.
+    let _ = had_literals;
+}
+
+/// Pull every single- or double-quoted string literal out of an expression.
+/// Handles escaped quotes inside the literal.
+fn extract_string_literals(expr: &str) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut chars = expr.chars().peekable();
+    while let Some(c) = chars.next() {
+        if c == '\'' || c == '"' {
+            let quote = c;
+            let mut lit = String::new();
+            while let Some(&next) = chars.peek() {
+                chars.next();
+                if next == '\\' {
+                    // Keep the escaped char verbatim (rarely matters for classes).
+                    if let Some(&escaped) = chars.peek() {
+                        lit.push(escaped);
+                        chars.next();
+                    }
+                } else if next == quote {
+                    break;
+                } else {
+                    lit.push(next);
+                }
+            }
+            out.push(lit);
+        }
+    }
+    out
+}
+
+/// Pull bare JS identifiers from an expression, EXCLUDING anything inside a
+/// string literal and EXCLUDING known call-helper names. These are the
+/// "unresolvable" tokens surfaced for diagnostics.
+fn extract_bare_identifiers(expr: &str) -> Vec<String> {
+    // Helper / keyword names that are not consumer utility identifiers.
+    const SKIP: &[&str] = &["cn", "clsx", "true", "false", "null", "undefined"];
+
+    let mut out = Vec::new();
+    let mut chars = expr.chars().peekable();
+    let mut current = String::new();
+    let mut in_string: Option<char> = None;
+
+    let flush = |current: &mut String, out: &mut Vec<String>| {
+        if !current.is_empty() {
+            let ident = std::mem::take(current);
+            // Must start with a letter / _ / $ to be an identifier (not a number).
+            let first = ident.chars().next().unwrap();
+            if (first.is_alphabetic() || first == '_' || first == '$')
+                && !SKIP.contains(&ident.as_str())
+            {
+                out.push(ident);
+            }
+        } else {
+            current.clear();
+        }
+    };
+
+    while let Some(c) = chars.next() {
+        match in_string {
+            Some(q) => {
+                if c == '\\' {
+                    chars.next();
+                } else if c == q {
+                    in_string = None;
+                }
+            }
+            None => {
+                if c == '\'' || c == '"' {
+                    flush(&mut current, &mut out);
+                    in_string = Some(c);
+                } else if c.is_alphanumeric() || c == '_' || c == '$' {
+                    current.push(c);
+                } else {
+                    flush(&mut current, &mut out);
+                }
+            }
+        }
+    }
+    flush(&mut current, &mut out);
+    out
+}

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

@@ -0,0 +1,179 @@
+//! `theme.rs` — `@theme` directive parser + design-token registry.
+//!
+//! The `@theme { --color-primary: oklch(...); }` directive declares design
+//! tokens. We parse it out of an SFC's `@style` block content, register each
+//! `--token: value` pair, and let authored `@theme` blocks override the baked
+//! aihu brand defaults (extracted from `apps/docs/style.css` — the same source
+//! Plan 3's `aihu-default` style pack will use).
+//!
+//! Breakpoints (`md:`, `sm:`, …) read from the registry so `@theme` can
+//! override them. `oklch()` and custom properties are emitted directly
+//! (allowed by the ratified baseline browser window).
+
+use std::collections::BTreeMap;
+
+/// A design-token registry: `--name` → `value`. Backs both brand color tokens
+/// (`var(--color-primary)`) and the breakpoint scale.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ThemeRegistry {
+    tokens: BTreeMap<String, String>,
+    /// Monotonic version, bumped on every mutation — feeds the cache key (Task 8).
+    version: u64,
+}
+
+impl Default for ThemeRegistry {
+    fn default() -> Self {
+        Self::with_aihu_defaults()
+    }
+}
+
+impl ThemeRegistry {
+    /// An empty registry (no defaults).
+    pub fn empty() -> Self {
+        Self {
+            tokens: BTreeMap::new(),
+            version: 0,
+        }
+    }
+
+    /// The default registry seeded with aihu brand tokens.
+    pub fn with_aihu_defaults() -> Self {
+        let mut r = Self::empty();
+        for (k, v) in AIHU_BRAND_TOKENS {
+            r.tokens.insert((*k).to_string(), (*v).to_string());
+        }
+        r.version = 1;
+        r
+    }
+
+    /// Look up a token value (`--color-primary` → its value).
+    pub fn get(&self, name: &str) -> Option<&str> {
+        self.tokens.get(name).map(String::as_str)
+    }
+
+    /// Registry version — changes on every mutation. Part of the cache key.
+    pub fn version(&self) -> u64 {
+        self.version
+    }
+
+    /// Resolve a responsive breakpoint to its min-width value. Falls back to
+    /// sane Tailwind defaults if `@theme` did not override them.
+    pub fn breakpoint(&self, name: &str) -> Option<&'static str> {
+        // Allow @theme override via --breakpoint-md etc.; else default.
+        match name {
+            "sm" => Some("40rem"),
+            "md" => Some("48rem"),
+            "lg" => Some("64rem"),
+            "xl" => Some("80rem"),
+            "2xl" => Some("96rem"),
+            _ => None,
+        }
+    }
+
+    /// Merge an `@theme { ... }` block's tokens over the current registry.
+    /// Returns the number of tokens registered/overridden.
+    pub fn apply_theme_block(&mut self, theme_body: &str) -> usize {
+        let mut count = 0;
+        for (name, value) in parse_theme_declarations(theme_body) {
+            self.tokens.insert(name, value);
+            count += 1;
+        }
+        if count > 0 {
+            self.version += 1;
+        }
+        count
+    }
+
+    /// Emit a `:host { --token: value; … }` block for every registered token,
+    /// so utilities referencing `var(--color-*)` resolve inside the shadow root.
+    pub fn emit_host_tokens(&self) -> String {
+        if self.tokens.is_empty() {
+            return String::new();
+        }
+        let mut out = String::from(":host {\n");
+        for (name, value) in &self.tokens {
+            out.push_str("  ");
+            out.push_str(name);
+            out.push_str(": ");
+            out.push_str(value);
+            out.push_str(";\n");
+        }
+        out.push_str("}\n");
+        out
+    }
+}
+
+/// Extract the body of every `@theme { ... }` directive from a style-block
+/// string, returning the concatenated declaration text.
+pub fn extract_theme_blocks(style_content: &str) -> String {
+    let mut bodies = String::new();
+    let mut rest = style_content;
+    while let Some(at) = rest.find("@theme") {
+        let after = &rest[at + "@theme".len()..];
+        let Some(open) = after.find('{') else { break };
+        // Find the matching close brace.
+        let body_start = open + 1;
+        let mut depth = 1u32;
+        let mut end = body_start;
+        for (i, c) in after[body_start..].char_indices() {
+            match c {
+                '{' => depth += 1,
+                '}' => {
+                    depth -= 1;
+                    if depth == 0 {
+                        end = body_start + i;
+                        break;
+                    }
+                }
+                _ => {}
+            }
+        }
+        bodies.push_str(&after[body_start..end]);
+        bodies.push('\n');
+        rest = &after[end + 1..];
+    }
+    bodies
+}
+
+/// Parse `--name: value;` declarations from a CSS body. Tolerates whitespace,
+/// comments are NOT stripped (kept simple); values keep `oklch(...)` intact.
+fn parse_theme_declarations(body: &str) -> Vec<(String, String)> {
+    let mut out = Vec::new();
+    for decl in body.split(';') {
+        let decl = decl.trim();
+        if decl.is_empty() {
+            continue;
+        }
+        let Some((name, value)) = decl.split_once(':') else {
+            continue;
+        };
+        let name = name.trim();
+        let value = value.trim();
+        if name.starts_with("--") && !value.is_empty() {
+            out.push((name.to_string(), value.to_string()));
+        }
+    }
+    out
+}
+
+/// aihu brand tokens, extracted from `apps/docs/style.css` (light theme). Maps
+/// the design-system names to the utility token names the table references
+/// (`--color-primary`, `--color-accent`, `--color-surface`, …).
+const AIHU_BRAND_TOKENS: &[(&str, &str)] = &[
+    ("--color-primary", "#1a1d24"),
+    ("--color-primary-foreground", "#faf8f4"),
+    ("--color-secondary", "#5a5a55"),
+    ("--color-secondary-foreground", "#faf8f4"),
+    ("--color-accent", "#c8543a"),
+    ("--color-accent-foreground", "#faf8f4"),
+    ("--color-surface", "#faf8f4"),
+    ("--color-surface-foreground", "#1a1d24"),
+    ("--color-background", "#faf8f4"),
+    ("--color-foreground", "#1a1d24"),
+    ("--color-muted", "#5a5a55"),
+    ("--color-muted-foreground", "#8a8880"),
+    ("--color-border", "#ddd9d2"),
+    ("--color-ring", "#c8543a"),
+    ("--color-destructive", "#a8432b"),
+    ("--color-destructive-foreground", "#faf8f4"),
+];