@aihu/css-engine 0.1.0

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

@@ -0,0 +1,236 @@
+//! `emit.rs` — scoped-output emitter (Plan 2 Tasks 4, 5, 6).
+//!
+//! Turns a scanned utility set into CSS. Two modes:
+//!
+//! - [`OutputMode::Flat`] — Plan 1 back-compat: `.class { … }` global-ish rules.
+//! - [`OutputMode::Scoped`] — the new default for `compile_sfc`. Every rule
+//!   lives inside the SFC's shadow root (the compiler folds the output into the
+//!   component's `<style>`), so there is NO global utility stylesheet. Class
+//!   selectors inside a shadow `<style>` only match that shadow tree — that IS
+//!   the scoping mechanism (per spec §6.3). We also fold the authored `@style`
+//!   block (scoped folded in; `$global` passed through) and the theme tokens.
+//!
+//! Variant resolution (Tasks 5/6) happens here: each scanned token is split via
+//! `variants::split_variants`, the base utility is compiled via `tokens`, then
+//! the variants wrap/append to the selector. Dark-mode variants (`dark:`,
+//! `host-context-dark:`) emit a custom-property cascade — NEVER
+//! `:host-context()` (Firefox workaround, `decision-firefox-host-context-workaround`).
+
+use crate::ast::{SfcAst, SfcStyleScope};
+use crate::progressive::ProgressiveRegistry;
+use crate::scanner::{scan, ScanResult};
+use crate::theme::{extract_theme_blocks, ThemeRegistry};
+use crate::tokens::utility_to_css;
+use crate::variants::{split_variants, Variant};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OutputMode {
+    Flat,
+    Scoped,
+}
+
+/// CSS-escape a class name for use in a selector (`bg-[#fff]` → `bg-\[\#fff\]`).
+fn escape_class(class: &str) -> String {
+    let mut out = String::with_capacity(class.len() + 4);
+    for c in class.chars() {
+        if matches!(c, '[' | ']' | '#' | '(' | ')' | '.' | '%' | '/' | ':' | ',') {
+            out.push('\\');
+        }
+        out.push(c);
+    }
+    out
+}
+
+/// If `token`'s leading prefix names a registered progressive feature, return
+/// its `(prefix, base)` split. `view-transition:slide` → `("view-transition",
+/// "slide")`; `text-balance:` → `("text-balance", "")`.
+fn progressive_split<'a>(token: &'a str, prog: &ProgressiveRegistry) -> Option<(&'a str, &'a str)> {
+    let colon = token.find(':')?;
+    let prefix = &token[..colon];
+    if prog.is_feature(prefix) {
+        Some((prefix, &token[colon + 1..]))
+    } else {
+        None
+    }
+}
+
+/// Compile a single scanned token (which may carry variant prefixes) into a CSS
+/// rule string, or `None` if the base utility is unknown.
+///
+/// Progressive-feature prefixes (`view-transition:`, `anchor:`, `popover:`,
+/// `text-balance:`) are routed to the [`ProgressiveRegistry`] emitter (Plan 3
+/// Task 4) instead of the standard selector path.
+fn emit_token(token: &str, theme: &ThemeRegistry, prog: &ProgressiveRegistry) -> Option<String> {
+    if let Some((prefix, base)) = progressive_split(token, prog) {
+        return prog.emit(prefix, base);
+    }
+
+    let (variants, base) = split_variants(token);
+    let body = utility_to_css(&base)?;
+    let class_sel = format!(".{}", escape_class(token));
+
+    // The base (innermost) selector and declaration body.
+    let mut selector = class_sel;
+    let mut media: Option<String> = None;
+    let mut dark_cascade = false;
+
+    for v in &variants {
+        match v {
+            Variant::Host => selector = format!(":host({selector})"),
+            Variant::Slotted => selector = format!("::slotted({selector})"),
+            Variant::SlottedTag(tag) => selector = format!("::slotted({tag}{selector})"),
+            Variant::Part(name) => selector = format!("::part({name})"),
+            Variant::Pseudo(pc) => selector = format!("{selector}:{pc}"),
+            Variant::ArbitrarySelector(sel) => {
+                // `[&>div]:` → substitute `&` for the base selector.
+                selector = sel.replace('&', &selector);
+            }
+            Variant::Breakpoint(bp) => {
+                if let Some(min) = theme.breakpoint(bp) {
+                    media = Some(format!("(min-width: {min})"));
+                }
+            }
+            Variant::Dark | Variant::HostContextDark => {
+                dark_cascade = true;
+            }
+        }
+    }
+
+    let rule = if dark_cascade {
+        // Firefox-safe dark cascade: gate the rule on the consumer's dark flag
+        // (a `data-theme="dark"` host attr or a `.dark` root class) rather than
+        // the host-context pseudo (unsupported in Firefox). Consumer contract:
+        // set `data-theme="dark"` on the host element OR add `.dark` to :root,
+        // and define the dark token values there. The dark variant's rule then
+        // only applies under those scopes.
+        format!(
+            "/* dark cascade (Firefox-safe; see decision-firefox-host-context-workaround) */\n\
+             :host([data-theme=\"dark\"]) {selector}, \
+             :root.dark {selector} {{ {body} }}\n"
+        )
+    } else {
+        format!("{selector} {{ {body} }}\n")
+    };
+
+    Some(match media {
+        Some(q) => format!("@media {q} {{\n{rule}}}\n"),
+        None => rule,
+    })
+}
+
+/// Emit CSS for a scanned utility set in the given mode.
+pub fn emit(result: &ScanResult, theme: &ThemeRegistry, mode: OutputMode) -> String {
+    emit_with_progressive(result, theme, &ProgressiveRegistry::with_builtins(), mode)
+}
+
+/// As [`emit`], but with an explicit [`ProgressiveRegistry`] (so callers can
+/// share one registry across an SFC compile).
+pub fn emit_with_progressive(
+    result: &ScanResult,
+    theme: &ThemeRegistry,
+    prog: &ProgressiveRegistry,
+    mode: OutputMode,
+) -> String {
+    let mut out = String::new();
+    for token in &result.utilities {
+        match mode {
+            OutputMode::Flat => {
+                // Flat back-compat: only plain utilities, no variant wrapping.
+                if let Some(body) = utility_to_css(token) {
+                    out.push_str(&format!(".{token} {{ {body} }}\n"));
+                }
+            }
+            OutputMode::Scoped => {
+                if let Some(rule) = emit_token(token, theme, prog) {
+                    out.push_str(&rule);
+                }
+            }
+        }
+    }
+    out
+}
+
+/// Compile a full SFC AST to scoped CSS: theme tokens (`:host`-level custom
+/// props) + scanned utility rules + the folded authored `@style` block.
+pub fn emit_sfc_scoped(ast: &SfcAst) -> String {
+    let mut theme = ThemeRegistry::with_aihu_defaults();
+
+    // Parse @theme directives from the authored style block first so utilities
+    // and breakpoints see overrides.
+    if let Some(style) = &ast.style {
+        let theme_bodies = extract_theme_blocks(&style.content);
+        if !theme_bodies.is_empty() {
+            theme.apply_theme_block(&theme_bodies);
+        }
+    }
+
+    let result = scan(ast);
+    let prog = ProgressiveRegistry::with_builtins();
+    let mut out = String::new();
+
+    // 1. Theme tokens at :host so var(--color-*) resolves inside the shadow.
+    out.push_str(&theme.emit_host_tokens());
+
+    // 2. Scanned utility rules (scoped) — progressive prefixes routed via `prog`.
+    out.push_str(&emit_with_progressive(&result, &theme, &prog, OutputMode::Scoped));
+
+    // 3. Fold the authored @style block (minus @theme directives).
+    if let Some(style) = &ast.style {
+        let authored = strip_theme_blocks(&style.content);
+        let authored = authored.trim();
+        if !authored.is_empty() {
+            match style.scope {
+                // Scoped: it already lives in the shadow <style>; pass through.
+                SfcStyleScope::Scoped => {
+                    out.push_str("/* authored @style (scoped) */\n");
+                    out.push_str(authored);
+                    out.push('\n');
+                }
+                // Global ($global): passed through unscoped (edge E6). The
+                // compiler hoists this out of the shadow root.
+                SfcStyleScope::Global => {
+                    out.push_str("/* authored @style ($global — unscoped) */\n");
+                    out.push_str(authored);
+                    out.push('\n');
+                }
+            }
+        }
+    }
+
+    out
+}
+
+/// Remove `@theme { ... }` blocks from style content (they become host tokens,
+/// not raw CSS).
+fn strip_theme_blocks(style_content: &str) -> String {
+    let mut out = String::new();
+    let mut rest = style_content;
+    while let Some(at) = rest.find("@theme") {
+        out.push_str(&rest[..at]);
+        let after = &rest[at + "@theme".len()..];
+        let Some(open) = after.find('{') else {
+            // Malformed — keep the rest verbatim and stop.
+            out.push_str(&rest[at..]);
+            return out;
+        };
+        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;
+                    }
+                }
+                _ => {}
+            }
+        }
+        rest = &after[end + 1..];
+    }
+    out.push_str(rest);
+    out
+}

package/crates/aihu-css-core/src/features/anchor.rs

@@ -0,0 +1,41 @@
+//! `anchor:` — CSS anchor positioning with a JS fallback (Plan 3 Task 6).
+//!
+//! Emits `anchor-name` / `position-anchor` CSS gated behind `@supports
+//! (anchor-name: --a)`. `js_fallback()` returns `"anchorFallback"` — the
+//! `@aihu/css-engine/runtime/progressive` shim positions the element with a
+//! tiny hand-written floating-ui-style shim when native CSS anchor positioning
+//! is unsupported. The shim (~2 KB) is SHARED with `popover:` (Task 7).
+
+use crate::progressive::ProgressiveFeature;
+
+/// `anchor:<name>` → CSS anchor-positioning, `@supports`-gated, with a JS shim.
+pub struct Anchor;
+
+impl ProgressiveFeature for Anchor {
+    fn prefix(&self) -> &'static str {
+        "anchor"
+    }
+
+    fn supports_condition(&self) -> Option<&'static str> {
+        Some("anchor-name: --a")
+    }
+
+    fn emit_css(&self, base: &str) -> String {
+        // `anchor:tooltip` declares an anchor name + binds positioning to it.
+        let name = if base.is_empty() { "anchor" } else { base };
+        let class = if base.is_empty() {
+            "anchor".to_string()
+        } else {
+            format!("anchor\\:{base}")
+        };
+        format!(
+            ".{class} {{ anchor-name: --{name}; position-anchor: --{name}; }}"
+        )
+    }
+
+    fn js_fallback(&self) -> Option<&'static str> {
+        // Native anchor positioning is gated; when absent, the runtime shim
+        // (`anchorFallback`) positions the element with JS.
+        Some("anchorFallback")
+    }
+}

package/crates/aihu-css-core/src/features/mod.rs

@@ -0,0 +1,33 @@
+//! `features/` — the built-in progressive features (Plan 3 Tasks 5–8).
+//!
+//! Each module implements [`crate::progressive::ProgressiveFeature`] for one
+//! forward-looking CSS feature. They are registered into the default
+//! [`crate::progressive::ProgressiveRegistry`] via [`register_builtins`].
+//!
+//! | Feature           | `@supports` gate              | JS fallback        |
+//! |-------------------|-------------------------------|--------------------|
+//! | `view-transition:`| `view-transition-name: none`  | none (CSS-only)    |
+//! | `anchor:`         | `anchor-name: --a`            | `anchorFallback`   |
+//! | `popover:`        | `selector(:popover-open)`     | `popoverFallback`  |
+//! | `text-balance:`   | none                          | none (CSS-only)    |
+
+use crate::progressive::ProgressiveRegistry;
+
+pub mod anchor;
+pub mod popover;
+pub mod text_balance;
+pub mod view_transition;
+
+pub use anchor::Anchor;
+pub use popover::Popover;
+pub use text_balance::TextBalance;
+pub use view_transition::ViewTransition;
+
+/// Register every built-in progressive feature into `registry`. Called by
+/// [`ProgressiveRegistry::with_builtins`](crate::progressive::ProgressiveRegistry::with_builtins).
+pub fn register_builtins(registry: &mut ProgressiveRegistry) {
+    registry.register(Box::new(ViewTransition));
+    registry.register(Box::new(Anchor));
+    registry.register(Box::new(Popover));
+    registry.register(Box::new(TextBalance));
+}

package/crates/aihu-css-core/src/features/popover.rs

@@ -0,0 +1,40 @@
+//! `popover:` — Popover API with a portal+positioning fallback (Plan 3 Task 7).
+//!
+//! Emits popover CSS gated behind `@supports selector(:popover-open)`.
+//! `js_fallback()` returns `"popoverFallback"` — the
+//! `@aihu/css-engine/runtime/progressive` shim emulates the top layer with a
+//! portal and positions the panel using the SAME floating-ui shim as `anchor:`
+//! (no duplication — keeps the `progressive` sub-export under its 3 KB budget).
+
+use crate::progressive::ProgressiveFeature;
+
+/// `popover:<name>` → popover CSS, `@supports`-gated, with a portal JS fallback.
+pub struct Popover;
+
+impl ProgressiveFeature for Popover {
+    fn prefix(&self) -> &'static str {
+        "popover"
+    }
+
+    fn supports_condition(&self) -> Option<&'static str> {
+        Some("selector(:popover-open)")
+    }
+
+    fn emit_css(&self, base: &str) -> String {
+        // The popover panel's open-state styling; native top-layer when supported.
+        let class = if base.is_empty() {
+            "popover".to_string()
+        } else {
+            format!("popover\\:{base}")
+        };
+        format!(
+            ".{class}:popover-open {{ position: fixed; margin: 0; inset: auto; }}"
+        )
+    }
+
+    fn js_fallback(&self) -> Option<&'static str> {
+        // When the Popover API is unavailable, the runtime shim portals the panel
+        // to the top layer and positions it with the shared floating-ui code.
+        Some("popoverFallback")
+    }
+}

package/crates/aihu-css-core/src/features/text_balance.rs

@@ -0,0 +1,36 @@
+//! `text-balance:` — the simplest possible progressive feature (Plan 3 Task 8).
+//!
+//! Emits a single `text-wrap: balance` declaration. `supports_condition()` is
+//! `None` (no `@supports` gate) and `js_fallback()` is `None` (no JS): browsers
+//! that don't understand the `balance` value silently ignore it — standard CSS
+//! forward-compatibility. One declaration, no gate, no runtime cost.
+
+use crate::progressive::ProgressiveFeature;
+
+/// `text-balance:` → `text-wrap: balance`. No gate, no JS.
+pub struct TextBalance;
+
+impl ProgressiveFeature for TextBalance {
+    fn prefix(&self) -> &'static str {
+        "text-balance"
+    }
+
+    fn supports_condition(&self) -> Option<&'static str> {
+        // No gate — unsupported browsers silently ignore the unknown value.
+        None
+    }
+
+    fn emit_css(&self, base: &str) -> String {
+        let class = if base.is_empty() {
+            "text-balance".to_string()
+        } else {
+            format!("text-balance\\:{base}")
+        };
+        format!(".{class} {{ text-wrap: balance; }}")
+    }
+
+    fn js_fallback(&self) -> Option<&'static str> {
+        // CSS-only — no runtime fallback.
+        None
+    }
+}

package/crates/aihu-css-core/src/features/view_transition.rs

@@ -0,0 +1,38 @@
+//! `view-transition:` — the simplest progressive feature (Plan 3 Task 5).
+//!
+//! Emits `view-transition-name` gated behind `@supports (view-transition-name:
+//! none)`. CSS-only: `js_fallback()` is `None`, so when the View Transitions API
+//! is unsupported the browser silently skips the transition (no JS, no error,
+//! no runtime cost). Per spec §6.7 this is the cheapest progressive feature.
+
+use crate::progressive::ProgressiveFeature;
+
+/// `view-transition:<name>` → a `view-transition-name` declaration, `@supports`-gated.
+pub struct ViewTransition;
+
+impl ProgressiveFeature for ViewTransition {
+    fn prefix(&self) -> &'static str {
+        "view-transition"
+    }
+
+    fn supports_condition(&self) -> Option<&'static str> {
+        Some("view-transition-name: none")
+    }
+
+    fn emit_css(&self, base: &str) -> String {
+        // `view-transition:hero` → `.view-transition\:hero { view-transition-name: hero; }`
+        // An empty base (`view-transition:`) defaults to `auto`.
+        let name = if base.is_empty() { "auto" } else { base };
+        let class = if base.is_empty() {
+            "view-transition".to_string()
+        } else {
+            format!("view-transition\\:{base}")
+        };
+        format!(".{class} {{ view-transition-name: {name}; }}")
+    }
+
+    fn js_fallback(&self) -> Option<&'static str> {
+        // CSS-only — unsupported browsers silently skip the transition.
+        None
+    }
+}

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

@@ -0,0 +1,67 @@
+//! aihu-css-core — CSS engine bootstrap.
+//!
+//! See `docs/superpowers/specs/2026-05-10-aihu-css-engine-and-primitives-design.md`
+//! for the full design. This bootstrap implementation supports a fixed subset
+//! of utility classes (see tokens.rs); Plan 2 wires the AST scanner; Plan 3
+//! adds variants and progressive features.
+
+pub mod ast;
+pub mod cache;
+pub mod emit;
+pub mod features;
+pub mod progressive;
+pub mod scanner;
+pub mod theme;
+pub mod tokens;
+pub mod variants;
+
+pub use ast::{parse_ast, AstError, SfcAst, SfcAttr, SfcNode, SfcStyleScope};
+pub use cache::{hash_ast, CssCache};
+pub use emit::{emit, emit_sfc_scoped, OutputMode};
+pub use progressive::{ProgressiveFeature, ProgressiveRegistry};
+pub use scanner::{scan, scan_ast, ScanResult};
+pub use theme::ThemeRegistry;
+pub use variants::{split_variants, Variant};
+
+/// Compile a list of utility class names into CSS rules.
+/// Each known class becomes `.class-name { <body> }`. Unknown classes are skipped.
+///
+/// # Example
+/// ```
+/// use aihu_css_core::compile_classes;
+/// let css = compile_classes(&["bg-primary".to_string(), "p-4".to_string()]);
+/// assert!(css.contains(".bg-primary"));
+/// assert!(css.contains(".p-4"));
+/// ```
+pub fn compile_classes(classes: &[String]) -> String {
+    let mut output = String::new();
+    for class in classes {
+        if let Some(body) = tokens::utility_to_css(class) {
+            output.push('.');
+            output.push_str(class);
+            output.push_str(" { ");
+            output.push_str(&body);
+            output.push_str(" }\n");
+        }
+    }
+    output
+}
+
+/// Compile a parsed `.aihu` SFC AST into CSS by scanning its template for
+/// utility classes and emitting one rule per known utility.
+///
+/// This is the Plan 2 flat-mode entry; [`compile_sfc_scoped`] wraps the output
+/// in shadow-DOM scope (the new default). `compile_classes` stays for
+/// back-compat.
+pub fn compile_sfc(ast: &SfcAst) -> String {
+    let classes = scan_ast(ast);
+    compile_classes(&classes.into_iter().collect::<Vec<_>>())
+}
+
+/// Compile a parsed `.aihu` SFC AST into scoped, shadow-DOM-embedded CSS:
+/// `:host`-level theme tokens, variant-resolved utility rules, and the folded
+/// authored `@style` block. This is the production entry consumed by the TS
+/// bridge / `aihu-css-compile --ast-json`.
+pub fn compile_sfc_scoped(ast: &SfcAst) -> String {
+    emit_sfc_scoped(ast)
+}