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

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

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

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

@@ -3,7 +3,7 @@ resolver = "3"
 members = ["crates/f8-core", "crates/f8-python"]
 
 [workspace.package]
-version = "0.1.0"
+version = "0.3.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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: f8-engine
-Version: 0.1.0
+Version: 0.3.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Financial and Insurance Industry
@@ -26,27 +26,27 @@ Project-URL: Repository, https://github.com/mhcfa/f8
 
 # f8
 
-Financial modeling engine with compiler verification and live Excel formulas.
+Author, verify, and automate financial models with code and AI agents, compiled into live Excel workbooks.
 
-## 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
 ```
 
@@ -70,48 +71,50 @@ f8 guide --all   # streams the full DSL, function, and auditing guide to stdout
 ```python
 from f8 import Model
 
+years = ["2025A", "2026E", "2027E"]
+capex = {"2025A": 25.0, "2026E": 30.0, "2027E": 35.0}
+depr = {"2025A": -15.0, "2026E": -18.0, "2027E": -22.0}
+
 model = Model("Operating Forecast")
 sheet = model.add_sheet("Summary")
 
-pnl = sheet.add_table("PnL", "Three-Year Projection", "($ in millions)")
-pnl.add_column("item", role="descriptor", header="Line Item")
-for year in ["2025A", "2026E", "2027E"]:
-    pnl.add_column(year, header=year, format="currency", decimals=1)
+ppe = sheet.add_table("PPE", "PP&E Corkscrew Schedule", "($ in millions)")
+ppe.add_column("item", role="descriptor", header="Line Item")
+for year in years:
+    ppe.add_column(year, header=year, format="currency", decimals=1)
 
-pnl.add_row(
-    "revenue",
-    cells={"item": "Revenue", "2025A": 100.0},
-    expr='PnL["revenue", col.prev] * 1.25',
-)
-pnl.add_row(
-    "cogs",
-    cells={"item": "Cost of Revenue"},
-    expr='PnL["revenue", @col] * 0.30',
+ppe.add_row(
+    "beg_balance",
+    cells={"item": "Beginning Balance", "2025A": 100.0},
+    expr='PPE["end_balance", col.prev]',
 )
-pnl.add_row(
-    "gross_profit",
-    cells={"item": "Gross Profit"},
-    expr='PnL["revenue", @col] - PnL["cogs", @col]',
+ppe.add_row("capex", cells={"item": "Capital Expenditures", **capex})
+ppe.add_row("depreciation", cells={"item": "Depreciation", **depr})
+ppe.add_row(
+    "end_balance",
+    cells={"item": "Ending Balance"},
+    expr='SUM(PPE["beg_balance".."depreciation", @col])',
     style="total",
 )
 
 compiled = model.compile()
 
 # Audit evaluated values in memory (or pass view="formulas" to inspect lowered Excel formulas)
-print(compiled.table("PnL").to_markdown())
+print(compiled.table("PPE").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")
 ```
 
 Output:
 
 ```markdown
-| Line Item        |     2025A |     2026E |      2027E |
-| :--------------- | --------: | --------: | ---------: |
-| Revenue          |    $100.0 |    $125.0 |     $156.2 |
-| Cost of Revenue  |     $30.0 |     $37.5 |      $46.9 |
-| **Gross Profit** | **$70.0** | **$87.5** | **$109.4** |
+| Line Item            |      2025A |      2026E |      2027E |
+| :------------------- | ---------: | ---------: | ---------: |
+| Beginning Balance    |     $100.0 |     $110.0 |     $122.0 |
+| Capital Expenditures |      $25.0 |      $30.0 |      $35.0 |
+| Depreciation         |    ($15.0) |    ($18.0) |    ($22.0) |
+| **Ending Balance**   | **$110.0** | **$122.0** | **$135.0** |
 ```
 
 ## Sample deliverables
@@ -150,9 +153,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.3.0}/README.md

@@ -1,26 +1,26 @@
 # f8
 
-Financial modeling engine with compiler verification and live Excel formulas.
+Author, verify, and automate financial models with code and AI agents, compiled into live Excel workbooks.
 
-## 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
 ```
 
@@ -44,48 +45,50 @@ f8 guide --all   # streams the full DSL, function, and auditing guide to stdout
 ```python
 from f8 import Model
 
+years = ["2025A", "2026E", "2027E"]
+capex = {"2025A": 25.0, "2026E": 30.0, "2027E": 35.0}
+depr = {"2025A": -15.0, "2026E": -18.0, "2027E": -22.0}
+
 model = Model("Operating Forecast")
 sheet = model.add_sheet("Summary")
 
-pnl = sheet.add_table("PnL", "Three-Year Projection", "($ in millions)")
-pnl.add_column("item", role="descriptor", header="Line Item")
-for year in ["2025A", "2026E", "2027E"]:
-    pnl.add_column(year, header=year, format="currency", decimals=1)
+ppe = sheet.add_table("PPE", "PP&E Corkscrew Schedule", "($ in millions)")
+ppe.add_column("item", role="descriptor", header="Line Item")
+for year in years:
+    ppe.add_column(year, header=year, format="currency", decimals=1)
 
-pnl.add_row(
-    "revenue",
-    cells={"item": "Revenue", "2025A": 100.0},
-    expr='PnL["revenue", col.prev] * 1.25',
-)
-pnl.add_row(
-    "cogs",
-    cells={"item": "Cost of Revenue"},
-    expr='PnL["revenue", @col] * 0.30',
+ppe.add_row(
+    "beg_balance",
+    cells={"item": "Beginning Balance", "2025A": 100.0},
+    expr='PPE["end_balance", col.prev]',
 )
-pnl.add_row(
-    "gross_profit",
-    cells={"item": "Gross Profit"},
-    expr='PnL["revenue", @col] - PnL["cogs", @col]',
+ppe.add_row("capex", cells={"item": "Capital Expenditures", **capex})
+ppe.add_row("depreciation", cells={"item": "Depreciation", **depr})
+ppe.add_row(
+    "end_balance",
+    cells={"item": "Ending Balance"},
+    expr='SUM(PPE["beg_balance".."depreciation", @col])',
     style="total",
 )
 
 compiled = model.compile()
 
 # Audit evaluated values in memory (or pass view="formulas" to inspect lowered Excel formulas)
-print(compiled.table("PnL").to_markdown())
+print(compiled.table("PPE").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")
 ```
 
 Output:
 
 ```markdown
-| Line Item        |     2025A |     2026E |      2027E |
-| :--------------- | --------: | --------: | ---------: |
-| Revenue          |    $100.0 |    $125.0 |     $156.2 |
-| Cost of Revenue  |     $30.0 |     $37.5 |      $46.9 |
-| **Gross Profit** | **$70.0** | **$87.5** | **$109.4** |
+| Line Item            |      2025A |      2026E |      2027E |
+| :------------------- | ---------: | ---------: | ---------: |
+| Beginning Balance    |     $100.0 |     $110.0 |     $122.0 |
+| Capital Expenditures |      $25.0 |      $30.0 |      $35.0 |
+| Depreciation         |    ($15.0) |    ($18.0) |    ($22.0) |
+| **Ending Balance**   | **$110.0** | **$122.0** | **$135.0** |
 ```
 
 ## Sample deliverables
@@ -124,9 +127,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.3.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.3.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.3.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 {