Prepare release v1.7.0

.github/copilot-instructions.md

@@ -0,0 +1,34 @@
+# Copilot instructions (grimoire-css)
+
+## Project shape (architecture guide)
+
+Note: This document captures the current architecture conventions for this repo.
+- Rust workspace is a single crate with **bin + lib**: `src/main.rs` calls `grimoire_css_lib::start_as_cli` (keep `main.rs` thin).
+- Command routing lives in `src/commands/handler.rs` (`init` / `build` / `shorten`). Add new CLI modes by wiring them here.
+- Core pipeline logic lives in `src/core/` (config → parse → build → optimize → output). Keep it side-effect-light where practical.
+- External integrations live in `src/infrastructure/` (e.g. LightningCSS optimizer + miette diagnostics). Don’t mix vendor glue into `src/core/`.
+
+## Runtime modes & config conventions
+- FS mode uses a single repo config file at `grimoire/config/grimoire.config.json` (created by `init`; used by `build`). See `src/core/filesystem.rs` and `src/commands/init.rs`.
+- Optimizer uses `.browserslistrc` from repo root; if missing, it is created with `defaults` (see `src/infrastructure/lightning_css_optimizer.rs`).
+- Parallel project builds are opt-in via `GRIMOIRE_CSS_JOBS` (project-level isolation) — see `src/core/css_builder/css_builder_fs.rs`.
+- Locking: setting `lock: true` in config enables tracking + cleanup of stale generated files via `grimoire/grimoire.lock.json` (see `src/core/file_tracker.rs`).
+- Config supports external scroll/variable files: `grimoire.*.scrolls.json` and `grimoire.*.variables.json` are loaded and merged during `ConfigFs::load` (see `src/core/config/config_fs.rs`).
+
+## Error/reporting pattern
+- Prefer returning `GrimoireCssError` from core logic; attach source context when you have file content/spans using `GrimoireCssError::with_source(...)` and `SourceFile` (pattern in `src/core/parser/parser_fs.rs`).
+- CLI pretty-printing goes through `GrimoireCssDiagnostic` + `miette` (see `src/infrastructure/diagnostics.rs` and `src/lib.rs`).
+
+## Developer workflows (match CI)
+- Format: `cargo fmt -- --check`
+- Lint: `cargo clippy -- -D warnings`
+- Tests: `cargo test`
+- Coverage (CI uses this): `./scripts/coverage.sh` (requires `grcov` + `llvm-tools-preview`).
+
+## Local running tips
+- CLI (debug): `cargo run -- build` / `cargo run -- init` / `cargo run -- shorten`
+- Release binary: `cargo build --release` → `target/release/grimoire_css`
+- Benchmark harness expects the release binary at `../target/release/grimoire_css` (see `benchmark/README.md`).
+
+## Versioning convention
+- PR branches `rc/x.y.z` must match `version = "x.y.z"` in `Cargo.toml` (enforced by `.github/workflows/version_check.yml`).

CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [v1.7.0] - 2025-12-27
+
+> Full release notes: [releases/v1.7.0.md](./releases/v1.7.0.md)
+
+### Added
+
+- **Scroll templates in `g!…;`**: Use config-defined `scrolls` inside templated syntax with variable arguments.
+- **Rustc-like diagnostics**: File/snippet output with labeled spans and optional help text.
+- **Opt-in parallel builds**: Enable multi-core filesystem builds via `GRIMOIRE_CSS_JOBS`.
+- **Repro sandbox**: Added `repro/` scenarios for quickly validating features and diagnostics.
+- **Contributor instructions**: Added `.github/copilot-instructions.md` describing the repo’s architecture conventions.
+
+### Improved
+
+- Deterministic scroll expansion under templated selectors, including correct propagation of prefixes (`md__`, `{...}`, `hover:`).
+- Reduced redundant work and lowered clone/allocation pressure in hot paths (output unchanged).
+
+### Fixed
+
+- Malformed function-like spell values now produce clearer, earlier errors.
+- Color function argument validation now returns a proper error instead of being silently ignored.
+
+---
+
+## [v1.6.0] - 2025-07-21
+
+> Full release notes: [releases/v1.6.0.md](./releases/v1.6.0.md)
+
+### Added
+
+- Extracted the color module into `grimoire_css_color_toolkit` for independent usage.
+- Comprehensive support for curly-bracket class syntax (`class={}`, `className={}`) with nested bracket handling.
+
+### Improved
+
+- Migrated unit handling from `u32` to `f64` for better precision in responsive calculations.
+- Upgraded to Rust Edition 2024 and set MSRV to Rust 1.88.
+
+---
+
 ## [v1.5.0] - 2025-05-19
 
 > Full release notes: [releases/v1.5.0.md](./releases/v1.5.0.md)

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "grimoire_css"
-version = "1.6.0"
+version = "1.7.0"
 edition = "2024"
 rust-version = "1.88"
 authors = ["Dmitrii Shatokhin <[email protected]>"]

README.md

@@ -4,25 +4,20 @@
 </div>
 
 ---
-
 <!-- END HERO IMAGE -->
 
 <!-- START BADGES -->
-
 [![Current Crates.io Version](https://img.shields.io/crates/v/grimoire_css.svg)](https://crates.io/crates/grimoire_css)
 [![Crates.io Downloads](https://img.shields.io/crates/d/grimoire_css.svg)](https://crates.io/crates/grimoire_css)
 [![Test Status](https://github.com/persevie/grimoire-css/actions/workflows/quality.yml/badge.svg)](https://github.com/persevie/grimoire-css/actions/workflows/quality.yml)
 [![codecov](https://codecov.io/github/persevie/grimoire-css/graph/badge.svg?token=3QE08UYS3S)](https://codecov.io/github/persevie/grimoire-css)
 ![license](https://shields.io/badge/license-MIT-blue)
 
 ---
-
 <!-- END BADGES -->
 
 <!-- START NOTE -->
-
 > For the best experience and access to advanced features like playgrounds and interactive previews, please visit the [Grimoire CSS site](https://grimoirecss.com). The documentation is the same in both places.
-
 <!-- END NOTE -->
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
@@ -316,7 +311,6 @@ For example, the predefined scroll `g-anim` allows you to apply an animation and
   <summary>Full Animations List (use [grimoirecss.com](https://grimoirecss.com) for better experience with preview)</summary>
 
 <!-- START ANIMATIONS LIST  -->
-
 - back-in-down
 - back-in-left
 - back-in-right
@@ -1047,9 +1041,9 @@ For example, the predefined scroll `g-anim` allows you to apply an animation and
 - zoom-out-left
 - zoom-out-right
 - zoom-out-up
-  <!-- END ANIMATIONS LIST -->
-  </details>
-  <!-- END ANIMATIONS SECTION -->
+<!-- END ANIMATIONS LIST -->
+</details>
+<!-- END ANIMATIONS SECTION -->
 
 ## Create Your Own Animations
 
@@ -1098,6 +1092,8 @@ This means you’re not limited by file types or formats - you define the `input
 
 If you want to use spells outside the traditional `class` or `className` attributes, Grimoire CSS provides a clever solution with its **template syntax**: `g!<spell>;`. This syntax lets you wrap your spell in a template, enabling the parser to collect spells from any text-based content.
 
+Template syntax works for scrolls too, by the same rules as spells (including prefixes and modifiers). For example: `g!complex-card=120px_red_100px;`.
+
 Let’s say you have both a classic spell and a templated spell that are essentially the same. Don’t worry - Grimoire CSS is smart enough to combine them into one, as long as it doesn’t affect the CSS cascade. The result? Clean, efficient CSS output like this:
 
 ```css
@@ -1465,6 +1461,8 @@ Migrating to Grimoire CSS is simple thanks to the Grimoire CSS Transmutator. You
 
 In both modes, the Transmutator returns JSON that conforms to the external Scrolls convention by default, so you can immediately leverage your existing CSS classes as Grimoire CSS Scrolls.
 
+You can also run the compiled CSS from Tailwind or any other framework through the Transmutator, include the produced JSON as external scrolls alongside your config, and keep using your existing class names powered by Grimoire CSS.
+
 ```json
 {
   "classes": [
@@ -1527,9 +1525,7 @@ The core of Grimoire CSS is architected entirely in Rust, ensuring top-notch per
 The `grimoire-css-js` takes the core crate and wraps it into a Node.js-compatible interface, which is then compiled into an npm package. Whether you’re working with Rust, Node.js, or need a direct CLI, Grimoire CSS is ready to integrate into your workflow and bring powerful CSS management wherever you need it.
 
 <!-- START DESK -->
-
 > For the best experience and access to online playground and transmutator (aka **Desk**), please visit the [Grimoire CSS site](https://grimoirecss.com). The documentation is the same in both places.
-
 <!-- END DESK -->
 
 ## Installation
@@ -1586,7 +1582,6 @@ grimoire-css-js build
 ```
 
 <!-- START CIRCLE -->
-
 # The Arcane Circle
 
 Grimoire CSS gives you the freedom to create styles that work exactly the way you want them to - no rigid rules or constraints. Whether you’re crafting dynamic interactions or fine-tuning layouts, Grimoire adapts to your needs, making each step straightforward and rewarding.
@@ -1599,18 +1594,16 @@ The Arcane Circle, or simply the Circle, is a place where you can share your con
 
 ## The First Member
 
-Hello! My name is Dmitrii Shatokhin, and I am the creator of Grimoire CSS. I invented the Spell concept and all the other ideas behind the project. Grimoire CSS is the result of countless hours of work and dedication, and I am proud to have made it open source.
+Hello! My name is [Dmitrii Shatokhin](https://dmtrshat.github.io/), and I am the creator of Grimoire CSS. I invented the Spell concept and all the other ideas behind the project. Grimoire CSS is the result of countless hours of work and dedication, and I am proud to have made it open source.
 
 But this is just the beginning. I am committed to the ongoing development of Grimoire CSS and its entire ecosystem - there are many plans and tasks ahead, which I strive to manage transparently on GitHub. My vision is to grow the Arcane Circle community and bring all these ideas to life.
 
 I would be truly grateful for any support you can offer - whether it’s starring the project on GitHub, leaving feedback, recommending it to others, contributing to its development, helping to promote Grimoire CSS, or even sponsoring the project or my work.
 
 Thank you!
-
 <!-- END CIRCLE -->
 
 <!-- START RELEASE INFO -->
-
 # Release Information
 
 ## Release Notes
@@ -1620,11 +1613,8 @@ For detailed information about each release, including new features, improvement
 ### Changelog
 
 A concise list of version-specific changes can be found in our [Changelog](https://github.com/persevie/grimoire-css/blob/main/CHANGELOG.md).
-
 <!-- END RELEASE INFO -->
 
 <!-- START SLOGAN -->
-
 Craft Your Code, Cast Your Spells
-
 <!-- END SLOGAN -->

RELEASES.md

@@ -4,6 +4,85 @@
 
 This document combines all release notes in chronological order, providing a comprehensive view of Grimoire CSS's evolution.
 
+
+---
+
+# v1.7.0 Scryforge: Deterministic Scrollcraft
+
+Grimoire CSS sharpens both **power** and **clarity** with **Scryforge** — a release focused on templated scroll composition, rustc-like diagnostics, and measurable performance wins. Spells now expand more deterministically under templated selectors, errors read like a compiler, and large projects build faster with an opt-in multi-core path.
+
+## Key Highlights
+
+- **Scroll Templates Inside `g!…;`**: Use config-defined `scrolls` directly in `g!…;` with variable arguments (e.g. `g!complex-card=120px_red_100px;`) while keeping output deterministic.
+- **Prefix-Safe Expansion**: Prefix modifiers like `md__`, focus blocks `{...}`, and `hover:` are preserved by applying them to each expanded spell.
+- **Rustc-like Diagnostics**: Errors render with file context + labeled span + optional help text, powered by a structured error model and `miette` diagnostics.
+- **Faster Builds (Same Output)**: Reduced redundant work and clone/allocation pressure; optional parallel project builds via `GRIMOIRE_CSS_JOBS`.
+- **Better Repro & Contributor UX**: Added a `repro/` sandbox for feature/error scenarios and added `.github/copilot-instructions.md` as an architecture guide.
+
+## Full Details
+
+### Scroll Templates Inside `g!…;`
+
+You can now reference scrolls in templated `g!…;` syntax, including argument passing:
+
+- Example: `g!complex-card=120px_red_100px;`
+- Supports variable-like arguments and prefix modifiers.
+- Scroll expansion is flattened into real property spells so generated CSS is emitted under the *outer templated selector*.
+- Output remains deterministic and the template-flattening path avoids unnecessary cloning.
+
+### Prefix Semantics Preserved
+
+Scrolls expanded under templates keep the semantics that made Grimoire CSS predictable in complex UIs:
+
+- Responsive prefixes like `md__`.
+- Focus blocks using `{...}`.
+- Effects like `hover:`.
+
+These prefixes apply to each expanded spell during flattening so behavior matches user intent.
+
+### Rustc-like Diagnostics (File + Span)
+
+This release substantially upgrades the error/reporting system:
+
+- Introduced `SourceFile` to carry file identity + full content, enabling readable snippets for every error.
+- Parsing now tracks spans (`start`, `len`) for each extracted class/spell token and propagates them through spell generation.
+- Error model upgraded from plain strings to structured compile errors (message / label / help / span / source).
+- Added a diagnostics adapter mapping `GrimoireCssError` to `miette::Diagnostic` for polished CLI output.
+
+User-facing validation got stricter and clearer:
+
+- Better errors for malformed function-like values / parentheses (`spell_value_validator`).
+- Color function argument validation now returns a proper error instead of being silently ignored.
+
+### Performance Improvements + Opt-in Parallelism
+
+Grimoire CSS stays output-stable while getting faster and leaner:
+
+- Reduced redundant passes and duplicated work.
+- Lowered allocation and clone pressure in hot paths.
+- Added opt-in parallelism for filesystem builds via `GRIMOIRE_CSS_JOBS`.
+
+Safe default remains single-threaded; scaling is opt-in based on machine and project size.
+
+### Repro Sandbox + Architecture Guide
+
+To improve maintenance and debugging velocity:
+
+- Added `repro/` containing minimal scenarios for reproducing features and diagnostics.
+- Added `.github/copilot-instructions.md` documenting the project’s architecture conventions.
+
+## Migration Notes
+
+### For Users
+
+- **Optional parallel builds**: Set `GRIMOIRE_CSS_JOBS` to enable multi-core builds in filesystem mode. Without it, behavior remains unchanged.
+- **Stricter validation**: Invalid color function arguments that were previously ignored now raise proper errors (with spans and help text).
+
+### For Contributors
+
+- Prefer adding/using minimal scenarios under `repro/` when improving parser/diagnostics behavior.
+- Follow the architecture guide in `.github/copilot-instructions.md` when introducing new commands, core pipeline changes, or infrastructure glue.
+
 ---
 
 # v1.6.0 Chromaspire: The Color Convergence
@@ -174,19 +253,16 @@ Grimoire CSS enhances its magical arsenal with the **v1.4.0 Aetheric Flow** rele
 ### Enhancements
 
 #### Argument Handling Improvements
-
 - Replaced `&[String]` with `Vec<String>` for more flexible argument processing
 - Enhanced compatibility with NodeJS wrapper implementation
 - Improved argument collection and processing through `env::args()`
 
 #### Visual Feedback Enhancement
-
 - Added new spinner variations for different operation states
 - Enhanced progress visualization during lengthy operations
 - Improved user experience with more engaging loading indicators
 
 #### CLI Flow Optimization
-
 - Streamlined `start_as_cli` workflow for better usability
 - Enhanced command processing and execution flow
 - Improved overall CLI interaction experience

content/about.md

@@ -295,6 +295,8 @@ This means you’re not limited by file types or formats - you define the `input
 
 If you want to use spells outside the traditional `class` or `className` attributes, Grimoire CSS provides a clever solution with its **template syntax**: `g!<spell>;`. This syntax lets you wrap your spell in a template, enabling the parser to collect spells from any text-based content.
 
+Template syntax works for scrolls too, by the same rules as spells (including prefixes and modifiers). For example: `g!complex-card=120px_red_100px;`.
+
 Let’s say you have both a classic spell and a templated spell that are essentially the same. Don’t worry - Grimoire CSS is smart enough to combine them into one, as long as it doesn’t affect the CSS cascade. The result? Clean, efficient CSS output like this:
 
 ```css
@@ -634,6 +636,21 @@ There are only 3 commands you need to know:
 - **`build`**: Kicks off the build process, parsing all your input files and generating the compiled CSS. If you haven’t already run `init`, the `build` command will handle that for you automatically.
 - **`shorten`**: Automatically converts all full-length component names in your spells (as defined in your config) to their corresponding shorthand forms. This helps keep your code concise and consistent. Run this command to refactor your files, making your spell syntax as brief as possible without losing clarity or functionality.
 
+**Optional parallel project builds**
+
+If your config defines multiple independent projects (multiple output files), Grimoire CSS can build them in parallel.
+
+- Enable by setting the `GRIMOIRE_CSS_JOBS` environment variable to a positive integer (e.g. `4`).
+- Default is `1` (fully sequential; same behavior as before).
+- Values are capped to the machine’s available parallelism.
+- Higher values can reduce wall-clock build time, but may increase peak memory usage due to multiple optimizations running simultaneously.
+
+Example:
+
+```bash
+GRIMOIRE_CSS_JOBS=4 grimoire_css build
+```
+
 Grimoire CSS’s CLI is built for developers who want power without bloat. It’s direct, no-nonsense, and integrates smoothly into any project or bundler.
 
 Here’s a refined version of the remaining parts, keeping the technical depth and making them more engaging and polished: