f8-engine 0.1.0__tar.gz → 0.2.0__tar.gz

{f8_engine-0.1.0 → f8_engine-0.2.0}/Cargo.lock

@@ -37,7 +37,7 @@ checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
 
 [[package]]
 name = "f8-core"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "indexmap",
  "petgraph",
@@ -50,7 +50,7 @@ dependencies = [
 
 [[package]]
 name = "f8-python"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "f8-core",
  "pyo3",

{f8_engine-0.1.0 → f8_engine-0.2.0}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "3"
 members = ["crates/f8-core", "crates/f8-python"]
 
 [workspace.package]
-version = "0.1.0"
+version = "0.2.0"
 edition = "2024"
 description = "Financial modeling engine with compiler verification and live Excel formulas"
 authors = ["Michael (Chencheng) Hu, CFA"]

{f8_engine-0.1.0 → f8_engine-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: f8-engine
-Version: 0.1.0
+Version: 0.2.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Financial and Insurance Industry
@@ -28,25 +28,25 @@ Project-URL: Repository, https://github.com/mhcfa/f8
 
 Financial modeling engine with compiler verification and live Excel formulas.
 
-## Why f8
+## Who is f8 for
 
-I am a CFA charterholder working primarily on private company M&A and project finance, domains that live in complex, bespoke Excel financial models.
+1. **People who want AI to reliably build complex Excel models (financial and beyond)**: Give AI agents a semantic 2D DSL and compile-time verification to produce clean and error-free `.xlsx` workbooks with live formulas.
+2. **People doing financial analysis in pure code (no Excel required)**: Run row-by-row financial statements, corkscrew schedules, and cross-table dependency graphs in Python (where columnar DataFrames fall short), with `compiled.save("model.xlsx")` ready whenever a stakeholder asks for the spreadsheet.
 
-Spreadsheets have always suffered from fragile manual work, silent copy-paste errors, and no version control.
+## Why f8
 
-When AI emerged, I found that AI agents struggle to manipulate Excel effectively (whether via OpenXML, openpyxl, Office.js, or GUI), primarily because of:
+I am a CFA charterholder working in private M&A and project finance, where complex Excel models remain the non-negotiable deliverable despite fragile manual work, silent copy-paste errors, and zero version control.
 
-- Brittle coordinates: Spreadsheets force agents to reason in spatial coordinates rather than semantics; inserting a single row shifts every downstream reference.
-- No verification loop: Standard spreadsheet libraries do not evaluate formulas, so an agent has to inspect the `.xlsx` file just to get feedback.
+AI agents struggle to manipulate raw spreadsheets (`openpyxl`, Office.js, or GUI) for two reasons:
 
-Yet the industry is stubborn: Excel remains the non-negotiable deliverable.
+- Brittle coordinates: Agents must reason in spatial cell addresses (`C42:G42`) instead of domain semantics; inserting one row shifts every downstream reference.
+- No verification loop: Spreadsheet libraries do not evaluate formulas, leaving agents blind until the `.xlsx` file is opened and inspected.
 
-`f8` brings software engineering rigor and AI-native ergonomics to traditional financial modeling. The `.xlsx` workbook becomes a compiled artifact rather than a hand-edited canvas.
+`f8` turns the `.xlsx` workbook into a compiled artifact rather than a hand-edited canvas:
 
-- Semantic 2D modeling: Author models in code using readable coordinates; `f8` handles spatial layout and lowers logic into native Excel formulas.
-- Compiler-enforced rigor: A 6-pass Rust compiler verifies grid completeness (zero unassigned cells or ambiguous formula overlaps) and enforces a strict DAG via Tarjan cycle detection before a file is ever written.
-- Closed-loop AI verification: `f8` evaluates formulas in memory with 100% Excel parity (yes, even the 1900 leap day bug in Excel) so AI agents can audit calculated tables, trace precedent/dependent trees, verify accounting checks, and self-heal errors in milliseconds. This also means the model is directly testable in Python.
-- End-to-end fundamental workflow in code: Keep data ingestion, domain modeling, automated auditing, and live `.xlsx` emission in version-controlled code with full AI agent assistance.
+- Semantic 2D modeling: Author models with readable table, row, and column identifiers; `f8` handles spatial layout and lowers logic into native Excel formulas.
+- Compiler-enforced rigor: A 6-pass Rust compiler verifies grid completeness (zero unassigned cells or formula overlaps) and enforces a strict DAG via Tarjan cycle detection.
+- Closed-loop verification: Evaluates formulas in memory with 100% Excel parity (including the 1900 leap day bug) so AI agents and `pytest` suites can audit tables, trace dependencies, and verify accounting checks in milliseconds.
 
 ## Getting started
 
@@ -62,6 +62,7 @@ If you are working with an AI coding agent, `f8` ships with a bundled modeling s
 
 ```bash
 f8 agent init    # scaffolds .agents/skills/f8-modeling/
+f8 theme init    # generates a customizable theme.json in the workspace root
 f8 guide --all   # streams the full DSL, function, and auditing guide to stdout
 ```
 
@@ -100,7 +101,7 @@ compiled = model.compile()
 # Audit evaluated values in memory (or pass view="formulas" to inspect lowered Excel formulas)
 print(compiled.table("PnL").to_markdown())
 
-# Emit a live .xlsx workbook with native Excel formulas and styling
+# Emit a live .xlsx workbook with native Excel formulas and styling (you don't have to)
 compiled.save("forecast.xlsx")
 ```
 
@@ -150,9 +151,10 @@ Under the hood, `f8` is a Python SDK (`python/f8/`) backed by a 6-pass Rust comp
 `Spec -> IR Expansion -> DAG & Cycle Check -> Topological Evaluation -> Spatial Layout -> Formula Lowering -> .xlsx Emission`
 
 - Architecture overview: `docs/architecture.md`
-- 2D matrix DSL reference: `docs/dsl/spec-format.md`
-- Standard function catalog: `docs/functions/catalog.md`
 - Python modeling skill: `python/f8/skills/f8-modeling/SKILL.md`
+- Syntax, grid, and formatting reference: `python/f8/skills/f8-modeling/references/syntax-and-grid.md`
+- Function reference: `python/f8/skills/f8-modeling/references/functions.md`
+- Auditing and repair reference: `python/f8/skills/f8-modeling/references/auditing-and-repair.md`
 
 ## License
 

{f8_engine-0.1.0 → f8_engine-0.2.0}/README.md

@@ -2,25 +2,25 @@
 
 Financial modeling engine with compiler verification and live Excel formulas.
 
-## Why f8
+## Who is f8 for
 
-I am a CFA charterholder working primarily on private company M&A and project finance, domains that live in complex, bespoke Excel financial models.
+1. **People who want AI to reliably build complex Excel models (financial and beyond)**: Give AI agents a semantic 2D DSL and compile-time verification to produce clean and error-free `.xlsx` workbooks with live formulas.
+2. **People doing financial analysis in pure code (no Excel required)**: Run row-by-row financial statements, corkscrew schedules, and cross-table dependency graphs in Python (where columnar DataFrames fall short), with `compiled.save("model.xlsx")` ready whenever a stakeholder asks for the spreadsheet.
 
-Spreadsheets have always suffered from fragile manual work, silent copy-paste errors, and no version control.
+## Why f8
 
-When AI emerged, I found that AI agents struggle to manipulate Excel effectively (whether via OpenXML, openpyxl, Office.js, or GUI), primarily because of:
+I am a CFA charterholder working in private M&A and project finance, where complex Excel models remain the non-negotiable deliverable despite fragile manual work, silent copy-paste errors, and zero version control.
 
-- Brittle coordinates: Spreadsheets force agents to reason in spatial coordinates rather than semantics; inserting a single row shifts every downstream reference.
-- No verification loop: Standard spreadsheet libraries do not evaluate formulas, so an agent has to inspect the `.xlsx` file just to get feedback.
+AI agents struggle to manipulate raw spreadsheets (`openpyxl`, Office.js, or GUI) for two reasons:
 
-Yet the industry is stubborn: Excel remains the non-negotiable deliverable.
+- Brittle coordinates: Agents must reason in spatial cell addresses (`C42:G42`) instead of domain semantics; inserting one row shifts every downstream reference.
+- No verification loop: Spreadsheet libraries do not evaluate formulas, leaving agents blind until the `.xlsx` file is opened and inspected.
 
-`f8` brings software engineering rigor and AI-native ergonomics to traditional financial modeling. The `.xlsx` workbook becomes a compiled artifact rather than a hand-edited canvas.
+`f8` turns the `.xlsx` workbook into a compiled artifact rather than a hand-edited canvas:
 
-- Semantic 2D modeling: Author models in code using readable coordinates; `f8` handles spatial layout and lowers logic into native Excel formulas.
-- Compiler-enforced rigor: A 6-pass Rust compiler verifies grid completeness (zero unassigned cells or ambiguous formula overlaps) and enforces a strict DAG via Tarjan cycle detection before a file is ever written.
-- Closed-loop AI verification: `f8` evaluates formulas in memory with 100% Excel parity (yes, even the 1900 leap day bug in Excel) so AI agents can audit calculated tables, trace precedent/dependent trees, verify accounting checks, and self-heal errors in milliseconds. This also means the model is directly testable in Python.
-- End-to-end fundamental workflow in code: Keep data ingestion, domain modeling, automated auditing, and live `.xlsx` emission in version-controlled code with full AI agent assistance.
+- Semantic 2D modeling: Author models with readable table, row, and column identifiers; `f8` handles spatial layout and lowers logic into native Excel formulas.
+- Compiler-enforced rigor: A 6-pass Rust compiler verifies grid completeness (zero unassigned cells or formula overlaps) and enforces a strict DAG via Tarjan cycle detection.
+- Closed-loop verification: Evaluates formulas in memory with 100% Excel parity (including the 1900 leap day bug) so AI agents and `pytest` suites can audit tables, trace dependencies, and verify accounting checks in milliseconds.
 
 ## Getting started
 
@@ -36,6 +36,7 @@ If you are working with an AI coding agent, `f8` ships with a bundled modeling s
 
 ```bash
 f8 agent init    # scaffolds .agents/skills/f8-modeling/
+f8 theme init    # generates a customizable theme.json in the workspace root
 f8 guide --all   # streams the full DSL, function, and auditing guide to stdout
 ```
 
@@ -74,7 +75,7 @@ compiled = model.compile()
 # Audit evaluated values in memory (or pass view="formulas" to inspect lowered Excel formulas)
 print(compiled.table("PnL").to_markdown())
 
-# Emit a live .xlsx workbook with native Excel formulas and styling
+# Emit a live .xlsx workbook with native Excel formulas and styling (you don't have to)
 compiled.save("forecast.xlsx")
 ```
 
@@ -124,9 +125,10 @@ Under the hood, `f8` is a Python SDK (`python/f8/`) backed by a 6-pass Rust comp
 `Spec -> IR Expansion -> DAG & Cycle Check -> Topological Evaluation -> Spatial Layout -> Formula Lowering -> .xlsx Emission`
 
 - Architecture overview: `docs/architecture.md`
-- 2D matrix DSL reference: `docs/dsl/spec-format.md`
-- Standard function catalog: `docs/functions/catalog.md`
 - Python modeling skill: `python/f8/skills/f8-modeling/SKILL.md`
+- Syntax, grid, and formatting reference: `python/f8/skills/f8-modeling/references/syntax-and-grid.md`
+- Function reference: `python/f8/skills/f8-modeling/references/functions.md`
+- Auditing and repair reference: `python/f8/skills/f8-modeling/references/auditing-and-repair.md`
 
 ## License
 

{f8_engine-0.1.0 → f8_engine-0.2.0}/crates/f8-core/src/compiler/compiled/mod.rs

@@ -277,6 +277,7 @@ impl CompiledModel {
             decimals: cell_node.decimals,
             currency: cell_node.currency,
             is_highlight: cell_node.is_highlight,
+            shade: cell_node.shade,
             indent: cell_node.indent,
             is_formula,
             formula_expr,
@@ -309,17 +310,21 @@ impl CompiledModel {
             .map(|col| match col {
                 crate::model::table::ColumnSpec::Data(d) => ColumnInspection {
                     id: Some(d.id.clone()),
+                    group: d.group.clone(),
                     headers: d.headers.clone(),
                     is_gutter: false,
                     is_descriptor: d.role.is_descriptor(),
                     style: Some(d.style.unwrap_or(SemanticStyle::Data)),
+                    shade: d.shade.filter(|s| !s.is_none()),
                 },
                 crate::model::table::ColumnSpec::Gutter => ColumnInspection {
                     id: None,
+                    group: None,
                     headers: Vec::new(),
                     is_gutter: true,
                     is_descriptor: false,
                     style: None,
+                    shade: None,
                 },
             })
             .collect();
@@ -346,6 +351,7 @@ impl CompiledModel {
                         is_gutter: false,
                         indent,
                         style: Some(d.style.unwrap_or(SemanticStyle::Data)),
+                        shade: d.shade.filter(|s| !s.is_none()),
                     }
                 }
                 crate::model::table::RowSpec::SectionHeader(s) => RowInspection {
@@ -355,6 +361,7 @@ impl CompiledModel {
                     is_gutter: false,
                     indent: s.indent.unwrap_or(0),
                     style: None,
+                    shade: None,
                 },
                 crate::model::table::RowSpec::Gutter => RowInspection {
                     id: None,
@@ -363,6 +370,7 @@ impl CompiledModel {
                     is_gutter: true,
                     indent: 0,
                     style: None,
+                    shade: None,
                 },
             })
             .collect();
@@ -641,8 +649,10 @@ impl CompiledModel {
                             }
                             ColumnSpec::Data(d) => {
                                 let k_len = d.headers.len();
-                                let mut header_text = if t >= total_tiers - k_len {
-                                    let k = t - (total_tiers - k_len);
+                                let first_hdr_tier = total_tiers.saturating_sub(k_len);
+                                let mut header_text = if t == 0 && d.group.is_some() {
+                                    d.group.clone()
+                                } else if let Some(k) = t.checked_sub(first_hdr_tier) {
                                     d.headers.get(k).cloned()
                                 } else {
                                     None

{f8_engine-0.1.0 → f8_engine-0.2.0}/crates/f8-core/src/compiler/compiled/model.rs

@@ -4,7 +4,7 @@ use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 
 use crate::compiler::ir::id::CellId;
-use crate::model::format::{CurrencyCode, FormatPreset, SemanticStyle};
+use crate::model::format::{CurrencyCode, FormatPreset, SemanticStyle, Shade};
 use crate::model::id::{ColId, RowId, SheetId, TableId};
 use crate::value::CellValue;
 
@@ -81,6 +81,8 @@ pub struct CellInspection {
     pub currency: Option<CurrencyCode>,
     /// Visual highlight emphasis flag.
     pub is_highlight: bool,
+    /// Semantic background shade if assigned.
+    pub shade: Option<Shade>,
     /// Descriptor text indentation level.
     pub indent: u8,
     /// `true` if this cell is calculated by formula, `false` if constant literal.
@@ -177,7 +179,9 @@ where
 pub struct ColumnInspection {
     /// Column identifier if this is a data column.
     pub id: Option<ColId>,
-    /// Multi-tier header labels.
+    /// Horizontal spanning group banner label if declared.
+    pub group: Option<String>,
+    /// Per-column stacked header labels.
     pub headers: Vec<String>,
     /// `true` if this column is a blank spacing gutter.
     pub is_gutter: bool,
@@ -185,6 +189,8 @@ pub struct ColumnInspection {
     pub is_descriptor: bool,
     /// Structural presentation style if this is a data column.
     pub style: Option<SemanticStyle>,
+    /// Semantic background shade if this is a data column.
+    pub shade: Option<Shade>,
 }
 
 /// Row inspection metadata.
@@ -202,6 +208,8 @@ pub struct RowInspection {
     pub indent: u8,
     /// Structural presentation style if this is a calculable data row.
     pub style: Option<SemanticStyle>,
+    /// Semantic background shade if this is a calculable data row.
+    pub shade: Option<Shade>,
 }
 
 /// Cell-level audit information within a table inspection view.

{f8_engine-0.1.0 → f8_engine-0.2.0}/crates/f8-core/src/compiler/emission/format.rs

@@ -5,7 +5,7 @@ use rust_xlsxwriter::{Color, Format, FormatAlign, FormatBorder, FormatUnderline}
 
 use super::error::EmissionError;
 use crate::compiler::layout::StyleRole;
-use crate::model::format::{CurrencyCode, FormatPreset};
+use crate::model::format::{CurrencyCode, FormatPreset, Shade};
 use crate::model::theme::{BorderStyle, PaletteConfig, Theme};
 
 /// Parses a hexadecimal color string (`#RGB`, `#RRGGBB`, or `#RRGGBBAA`) into a `rust_xlsxwriter::Color`.
@@ -94,7 +94,9 @@ struct ParsedPalette {
     total_text: Color,
     input_text: Color,
     formula_text: Color,
-    zebra_fill: Option<Color>,
+    shade_muted_fill: Option<Color>,
+    shade_accent_fill: Option<Color>,
+    shade_alt_fill: Option<Color>,
     highlight_fill: Option<Color>,
     highlight_text: Color,
     gridline_color: Color,
@@ -122,7 +124,9 @@ impl ParsedPalette {
             total_text: parse_hex_color("total_text", &p.total_text)?,
             input_text: parse_hex_color("input_text", &p.input_text)?,
             formula_text: parse_hex_color("formula_text", &p.formula_text)?,
-            zebra_fill: parse_fill_color("zebra_fill", &p.zebra_fill)?,
+            shade_muted_fill: parse_fill_color("shade_muted_fill", &p.shade_muted_fill)?,
+            shade_accent_fill: parse_fill_color("shade_accent_fill", &p.shade_accent_fill)?,
+            shade_alt_fill: parse_fill_color("shade_alt_fill", &p.shade_alt_fill)?,
             highlight_fill: parse_fill_color("highlight_fill", &p.highlight_fill)?,
             highlight_text: parse_hex_color("highlight_text", &p.highlight_text)?,
             gridline_color: parse_hex_color("gridline_color", &p.gridline_color)?,
@@ -184,6 +188,8 @@ pub struct FormatCache {
     title_format: Format,
     subtitle_format: Format,
     super_header_format: Format,
+    col_header_upper_descriptor_format: Format,
+    col_header_upper_measure_format: Format,
     col_header_descriptor_format: Format,
     col_header_measure_format: Format,
     section_header_format: Format,
@@ -239,15 +245,17 @@ impl FormatCache {
         }
 
         // 4. Column Header (Descriptor - Left Aligned)
-        let mut col_header_descriptor_format = Format::new()
+        let mut col_header_upper_descriptor_format = Format::new()
             .set_font_name(&theme.typography.font_family)
             .set_font_size(theme.typography.col_header_size)
             .set_bold()
             .set_font_color(palette.col_header_text)
             .set_align(FormatAlign::Left);
         if let Some(fill) = palette.col_header_fill {
-            col_header_descriptor_format = col_header_descriptor_format.set_background_color(fill);
+            col_header_upper_descriptor_format =
+                col_header_upper_descriptor_format.set_background_color(fill);
         }
+        let mut col_header_descriptor_format = col_header_upper_descriptor_format.clone();
         if theme.borders.header_border_bottom != BorderStyle::None {
             col_header_descriptor_format = col_header_descriptor_format
                 .set_border_bottom(translate_border_style(theme.borders.header_border_bottom))
@@ -255,15 +263,17 @@ impl FormatCache {
         }
 
         // 5. Column Header (Measure - Right Aligned)
-        let mut col_header_measure_format = Format::new()
+        let mut col_header_upper_measure_format = Format::new()
             .set_font_name(&theme.typography.font_family)
             .set_font_size(theme.typography.col_header_size)
             .set_bold()
             .set_font_color(palette.col_header_text)
             .set_align(FormatAlign::Right);
         if let Some(fill) = palette.col_header_fill {
-            col_header_measure_format = col_header_measure_format.set_background_color(fill);
+            col_header_upper_measure_format =
+                col_header_upper_measure_format.set_background_color(fill);
         }
+        let mut col_header_measure_format = col_header_upper_measure_format.clone();
         if theme.borders.header_border_bottom != BorderStyle::None {
             col_header_measure_format = col_header_measure_format
                 .set_border_bottom(translate_border_style(theme.borders.header_border_bottom))
@@ -290,6 +300,8 @@ impl FormatCache {
             title_format,
             subtitle_format,
             super_header_format,
+            col_header_upper_descriptor_format,
+            col_header_upper_measure_format,
             col_header_descriptor_format,
             col_header_measure_format,
             section_header_format,
@@ -328,15 +340,21 @@ impl FormatCache {
         };
 
         // 3. Background Fill Precedence:
-        // is_highlight > total > subtotal > data
+        // is_highlight > total (or shade) > subtotal (or shade) > shade > data
+        let shade_fill = match key.role.shade {
+            Some(Shade::Muted) => self.palette.shade_muted_fill,
+            Some(Shade::Accent) => self.palette.shade_accent_fill,
+            Some(Shade::Alt) => self.palette.shade_alt_fill,
+            Some(Shade::None) | None => None,
+        };
         let fill = if key.role.is_highlight {
             self.palette.highlight_fill
         } else if key.role.horizontal.is_total() || key.role.vertical.is_total() {
-            self.palette.total_fill
+            self.palette.total_fill.or(shade_fill)
         } else if key.role.horizontal.is_subtotal() || key.role.vertical.is_subtotal() {
-            self.palette.subtotal_fill
+            self.palette.subtotal_fill.or(shade_fill)
         } else {
-            self.palette.data_fill
+            shade_fill.or(self.palette.data_fill)
         };
         if let Some(fill_color) = fill {
             format = format.set_background_color(fill_color);
@@ -453,6 +471,16 @@ impl FormatCache {
         self.super_header_format.clone()
     }
 
+    /// Returns the upper-tier stacked column header format (descriptor or measure, without bottom border).
+    #[must_use]
+    pub fn col_header_upper_format(&self, is_descriptor: bool) -> Format {
+        if is_descriptor {
+            self.col_header_upper_descriptor_format.clone()
+        } else {
+            self.col_header_upper_measure_format.clone()
+        }
+    }
+
     /// Returns the column header format (descriptor or measure).
     #[must_use]
     pub fn col_header_format(&self, is_descriptor: bool) -> Format {
@@ -463,6 +491,12 @@ impl FormatCache {
         }
     }
 
+    /// Returns true if the theme defines a background fill for column headers.
+    #[must_use]
+    pub fn has_col_header_fill(&self) -> bool {
+        self.palette.col_header_fill.is_some()
+    }
+
     /// Returns the section header format with optional indentation level.
     #[must_use]
     pub fn section_header_format(&self, indent: Option<u8>) -> Format {

{f8_engine-0.1.0 → f8_engine-0.2.0}/crates/f8-core/src/compiler/emission/workbook.rs

@@ -221,61 +221,24 @@ impl WorkbookEmitter {
                         let tier_row = header_start_row + t as u32;
                         let is_bottom_tier = t == total_tiers - 1;
 
-                        if is_bottom_tier {
-                            // Bottom tier: emit cell-by-cell
-                            for (c_idx, col_spec) in table.columns.iter().enumerate() {
-                                let col_idx = (placement.start_col + c_idx as u32) as u16;
-                                match col_spec {
-                                    ColumnSpec::Gutter => {
-                                        // Gutter column: blank unstyled cell across all header tiers
-                                    }
-                                    ColumnSpec::Data(d) => {
-                                        if let Some(label) = d.bottom_header() {
-                                            let is_desc = d.role.is_descriptor();
-                                            let fmt = format_cache.col_header_format(is_desc);
-                                            worksheet.write_string_with_format(
-                                                tier_row, col_idx, label, &fmt,
-                                            )?;
-                                        }
-                                    }
-                                }
-                            }
-                        } else {
-                            // Super-header tier: CenterAcross contiguous identical runs
+                        // Step A (t == 0 Group Banners): CenterAcross contiguous runs with identical group label
+                        if t == 0 {
                             let mut col_idx = 0;
-                            while col_idx < table.columns.len() {
-                                let col_spec = &table.columns[col_idx];
-                                let label_opt = match col_spec {
+                            while let Some(col_spec) = table.columns.get(col_idx) {
+                                let group_opt = match col_spec {
+                                    ColumnSpec::Data(d) => d.group.as_deref(),
                                     ColumnSpec::Gutter => None,
-                                    ColumnSpec::Data(d) => {
-                                        let k_len = d.headers.len();
-                                        if t >= total_tiers - k_len {
-                                            let k = t - (total_tiers - k_len);
-                                            Some(&d.headers[k])
-                                        } else {
-                                            None
-                                        }
-                                    }
                                 };
 
-                                if let Some(label) = label_opt {
+                                if let Some(label) = group_opt {
                                     let start_c = col_idx;
                                     let mut end_c = col_idx;
-                                    while end_c + 1 < table.columns.len() {
-                                        let next_spec = &table.columns[end_c + 1];
-                                        let next_label_opt = match next_spec {
+                                    while let Some(next_spec) = table.columns.get(end_c + 1) {
+                                        let next_group = match next_spec {
+                                            ColumnSpec::Data(d) => d.group.as_deref(),
                                             ColumnSpec::Gutter => None,
-                                            ColumnSpec::Data(d) => {
-                                                let k_len = d.headers.len();
-                                                if t >= total_tiers - k_len {
-                                                    let k = t - (total_tiers - k_len);
-                                                    Some(&d.headers[k])
-                                                } else {
-                                                    None
-                                                }
-                                            }
                                         };
-                                        if next_label_opt == Some(label) {
+                                        if next_group == Some(label) {
                                             end_c += 1;
                                         } else {
                                             break;
@@ -305,6 +268,39 @@ impl WorkbookEmitter {
                                 }
                             }
                         }
+
+                        // Step B (Per-column stacked headers across all t in 0..total_tiers)
+                        for (c_idx, col_spec) in table.columns.iter().enumerate() {
+                            let col_idx = (placement.start_col + c_idx as u32) as u16;
+                            match col_spec {
+                                ColumnSpec::Gutter => {
+                                    // Gutter column: blank unstyled cell across all header tiers
+                                }
+                                ColumnSpec::Data(d) => {
+                                    if t == 0 && d.group.is_some() {
+                                        continue;
+                                    }
+                                    let k_len = d.headers.len();
+                                    let first_hdr_tier = total_tiers.saturating_sub(k_len);
+                                    let is_desc = d.role.is_descriptor();
+                                    let fmt = if is_bottom_tier {
+                                        format_cache.col_header_format(is_desc)
+                                    } else {
+                                        format_cache.col_header_upper_format(is_desc)
+                                    };
+
+                                    if let Some(label) =
+                                        t.checked_sub(first_hdr_tier).and_then(|k| d.headers.get(k))
+                                    {
+                                        worksheet.write_string_with_format(
+                                            tier_row, col_idx, label, &fmt,
+                                        )?;
+                                    } else if is_bottom_tier || format_cache.has_col_header_fill() {
+                                        worksheet.write_blank(tier_row, col_idx, &fmt)?;
+                                    }
+                                }
+                            }
+                        }
                     }
                 }
 

{f8_engine-0.1.0 → f8_engine-0.2.0}/crates/f8-core/src/compiler/ir/cell.rs

@@ -4,7 +4,7 @@ use serde::{Deserialize, Serialize};
 use super::error::IrError;
 use super::id::CellId;
 use crate::expr::ast::Expr;
-use crate::model::format::{CurrencyCode, FormatPreset, SemanticStyle};
+use crate::model::format::{CurrencyCode, FormatPreset, SemanticStyle, Shade};
 use crate::model::id::{ColId, RowId, SheetId, TableId};
 use crate::model::table::ValueLiteral;
 
@@ -64,6 +64,9 @@ pub struct CellNode {
     pub vertical: SemanticStyle,
     /// Visual highlight emphasis flag.
     pub is_highlight: bool,
+    /// Semantic background shade if assigned.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub shade: Option<Shade>,
     /// Descriptor text indentation level.
     #[serde(default)]
     pub indent: u8,
@@ -85,6 +88,7 @@ impl CellNode {
             horizontal: SemanticStyle::Data,
             vertical: SemanticStyle::Data,
             is_highlight: false,
+            shade: None,
             indent: 0,
             payload,
             note: None,
@@ -122,6 +126,12 @@ impl CellNode {
         self
     }
 
+    /// Builder method attaching a semantic background shade.
+    pub fn with_shade(mut self, shade: Option<Shade>) -> Self {
+        self.shade = shade;
+        self
+    }
+
     /// Builder method attaching typographic indentation.
     pub fn with_indent(mut self, indent: u8) -> Self {
         self.indent = indent;

{f8_engine-0.1.0 → f8_engine-0.2.0}/crates/f8-core/src/compiler/ir/error.rs

@@ -1,7 +1,7 @@
 use thiserror::Error;
 
 use super::id::CellId;
-use crate::model::format::{CurrencyCode, FormatPreset};
+use crate::model::format::{CurrencyCode, FormatPreset, Shade};
 use crate::model::id::{ColId, RowId, SheetId, TableId};
 
 /// Errors encountered during intermediate representation construction and symbol registration.
@@ -102,6 +102,17 @@ pub enum IrError {
         col_currency: CurrencyCode,
     },
 
+    #[error(
+        "Table '{table}': shade conflict at row '{row}' ({row_shade}) and column '{column}' ({col_shade}) (hint: remove 'shade' from either row or column, or specify an explicit cell override)"
+    )]
+    ShadeConflict {
+        table: TableId,
+        row: RowId,
+        column: ColId,
+        row_shade: Shade,
+        col_shade: Shade,
+    },
+
     #[error("model validation error: {0}")]
     Model(String),
 }