hcie-rust-v3.05/AGENTS.md

# HCIE-Rust v4 — AI-Aware Architecture

## Mission Statement

HCIE-Rust v4 is a pixel-grade image editor built around an atomic project split that prevents automated agents from corrupting the engine while still allowing them to iterate on the graphical user interface.

## Atomic Crate Split (23 crates / 6 layers)

### Layer 1: DATA — locked, agents must not modify

| Crate | Responsibility | Dependencies |
|-------|----------------|--------------|
| `hcie-protocol` | Pure data structures and enumerations. Zero logic. | `serde` |
| `hcie-color` | Color conversions, gamma encode/decode, HSL/Lab. | `hcie-protocol` |

### Layer 2: ENGINE CORE — locked, agents must not modify

| Crate | Responsibility | Dependencies |
|-------|----------------|--------------|
| `hcie-blend` | 30+ blend mode implementations. | `hcie-protocol`, `hcie-color` |
| `hcie-history` | Closure-based undo/redo engine. | `hcie-protocol` |
| `hcie-brush-engine` | Brush mathematics, tip generation, pressure mapping. | `hcie-protocol` |
| `hcie-draw` | Pixel drawing: lines, rectangles, ellipses, strokes, flood fill. | `hcie-protocol`, `hcie-blend`, `hcie-brush-engine` |
| `hcie-composite` | Layer compositing and pixel output. | `hcie-protocol`, `hcie-blend` |
| `hcie-filter` | Image filters. | `hcie-protocol`, `hcie-blend` |
| `hcie-selection` | Selection mask operations: grow, shrink, feather, invert. | `hcie-protocol` |
| `hcie-text` | Vector text rendering via `fontdue`. | `hcie-protocol`, `fontdue` |
| `hcie-vector` | Vector shape engine. | `hcie-protocol` |
| `hcie-tile` | Sparse tile-based layer storage. | `hcie-protocol` |
| `hcie-io` | File I/O for PNG, JPG, WebP, PSD, KRA, HCIE native. | `hcie-protocol`, `image`, `zip`, `psd` |

### Layer 3: DOCUMENT — locked, agents must not modify

| Crate | Responsibility | Dependencies |
|-------|----------------|--------------|
| `hcie-document` | Document state: layers, active layer, dirty tracking, zoom. | `hcie-protocol`, `hcie-blend`, `hcie-history` |

### Layer 4: ENGINE API — locked, agents must not modify

| Crate | Output | Responsibility |
|-------|--------|----------------|
| `hcie-engine-api` | `staticlib` + `rlib` | Public API exposed to the GUI and AI/vision modules. Approximately 20 entry functions. |

### Layer 5: AI / VISION — locked, agents must not modify

These crates depend on `hcie-engine-api` and expose AI and vision features back through it.

| Crate | Responsibility | Dependencies |
|-------|----------------|--------------|
| `hcie-ai` | Ollama / LMStudio / OpenAI-compatible chat client, templates, AI actions. | `hcie-engine-api` |
| `hcie-vision` | ComfyUI pipelines, background removal, inpaint, super-resolution, smart selection. | `hcie-engine-api` |

### Layer 6: GUI — open, agents work here

One GUI workspace exists:

| Crate / Project | Directory | Responsibility | Dependencies |
|-----------------|-----------|----------------|--------------|
| `hcie-egui-app` | `hcie-egui-app/` | Workspace root for the native GUI. | `hcie-engine-api`, `eframe`, panels |
| `hcie-gui-egui` | `hcie-egui-app/crates/hcie-gui-egui/` | Main binary and application orchestration. | `hcie-engine-api`, panels |
| `egui-panel-adapter` | `hcie-egui-app/crates/egui-panel-adapter/` | Dynamic schema-to-widget UI binder. | `hcie-engine-api` |
| `egui-panel-filters` | `hcie-egui-app/crates/egui-panel-filters/` | Filter parameter panels. | `hcie-engine-api` |
| `egui-panel-ai-chat` | `hcie-egui-app/crates/egui-panel-ai-chat/` | AI chat panel. | `hcie-engine-api`, `hcie-ai` |
| `egui-panel-script` | `hcie-egui-app/crates/egui-panel-script/` | Scripting / automation panel. | `hcie-engine-api` |
| `egui-panel-ai-script` | `hcie-egui-app/crates/egui-panel-ai-script/` | AI-assisted script generation panel. | `hcie-engine-api`, `egui-panel-script` |

## Critical Rules

1. **No direct GUI-to-engine bypass.** The GUI may not depend on or import `hcie-protocol`, `hcie-blend`, `hcie-document`, or any other engine crate directly. Use `hcie-engine-api` only.
2. **Engine API is the single entry point.** All engine operations go through `hcie-engine-api`. AI agents may not read or modify internal engine code.
3. **New feature = new file.** Prefer adding new files over editing existing ones; minimize changes to existing files.
4. **Engine library type.** `hcie-engine-api` is built as `crate-type = ["rlib", "staticlib"]`. The GUI links the `.a` / `.rlib` artifacts.
5. **Lock mechanism.** Engine crates are locked with `chmod 444` / directory `555` and owned by the `hcie-guard` user after build. Agents work only in the GUI layer.

## Build Order

```
Layer 1:  hcie-protocol, hcie-color
Layer 2:  hcie-blend, hcie-history, hcie-brush-engine, hcie-draw,
          hcie-composite, hcie-filter, hcie-selection, hcie-text,
          hcie-vector, hcie-tile, hcie-io, hcie-fx, hcie-psd, hcie-kra, hcie-native
Layer 3:  hcie-document
Layer 4:  hcie-engine-api (rlib + staticlib)
Layer 5:  hcie-ai, hcie-vision
Layer 6:  hcie-egui-app / hcie-gui-egui
```

## Performance Protection Notes (CRITICAL — Regression Prevention)

The engine optimizations below directly determine brush performance on 4K / multi-layer documents. Removing, disabling, or bypassing these mechanisms as a "temporary workaround" is forbidden. Before touching them, verify benefit by running:

```bash
cargo test -p hcie-engine-api --test visual_regression
cargo test -p hcie-engine-api --test performance_stroke_4k -- --nocapture
```

| Mechanism | Location | What it does | Why it is protected |
|-----------|----------|--------------|---------------------|
| `active_stroke_mask` pooling | `hcie-engine-api/src/lib.rs` | Keeps an approximately 8MB mask buffer alive between strokes. | Re-allocating the mask per stroke causes allocation pauses during continuous painting. |
| `composite_scratch` pooling | `hcie-engine-api/src/lib.rs` | Keeps an approximately 33MB composite scratch buffer alive between strokes. | Allocating and freeing the composite buffer on every `render_composite_region` call is expensive. |
| `below_cache` + `below_cache_dirty` | `hcie-engine-api/src/lib.rs` | Composites all layers below the active layer once at stroke start and reuses the result while the lower layers remain unchanged. | Re-compositing all layers on every stroke event costs milliseconds per event on 4K canvases. |
| Conditional `effects_dirty` set | `hcie-engine-api/src/lib.rs` | Triggers the effects pass only for layers that actually have effects or styles. | Avoids unnecessary 33MB buffer clones and repeated `apply_layer_effects` calls on unaffected layers. |
| Tile cache over-clear removal | `hcie-engine-api/src/lib.rs` | Does not clear `tile_layers` and re-tile all layers on opacity / visibility / blend / parent / move changes when layer pixels themselves did not change. | Keeps the tile cache valid and avoids redundant dense-to-tile copies. |
| Small-region sequential compositing | `hcie-composite/src/tiled.rs` | Uses a sequential loop instead of `par_chunks_exact_mut` for small dirty regions. | Rayon thread spawn overhead dominates the work when the dirty region is small. |
| Effects cache reuse | `hcie-composite/src/tiled.rs` | Skips `apply_layer_effects` when `layer.effects_cache` is already populated. | Prevents re-running the full effect pipeline on every partial composite. |
| Incremental tile update | `hcie-tile/src/lib.rs` | Updates only the tiles that intersect the dirty rectangle and writes only the changed sub-rectangle when a tile already exists. | Avoids throwing away the whole 33MB dense-to-tile copy on every small dirty region. |
| Vector stroke anti-aliasing density | `hcie-vector/src/lib.rs` | Keeps circle-overlap density high enough along vector strokes and ellipses so shapes do not look jagged/pixelated. | Reducing step counts makes circles, stars, polygons and rounded rectangles visibly tırtıklı. |

### GUI First-Frame Visibility (CRITICAL — Regression Prevention)

Two mechanisms together fix the recurring "default first document canvas is invisible until the tab title is clicked" bug. Removing either half makes the regression come back.

| Mechanism | Location | What it does | Why it is protected |
|-----------|----------|--------------|---------------------|
| Initial document active tab | `hcie-egui-app/crates/hcie-gui-egui/src/app/mod.rs` (`HcieApp::new`) | Sets `Document(0)` as the active dock tab on startup so egui_dock calls the canvas widget's `ui()` on the first frame. | Without this, the canvas widget is skipped and the composite texture is never created until the user clicks the tab title. |
| Extra repaint after new texture | `hcie-egui-app/crates/hcie-gui-egui/src/canvas/mod.rs` | Requests multiple repaints after `render_composition` creates a brand-new texture, because egui uploads GPU textures asynchronously. | A single repaint often leaves the canvas blank on the first frame; the second/third frame actually displays the texture. |
| `DrawingFinished` does NOT clear dirty flags | `hcie-egui-app/crates/hcie-gui-egui/src/app/mod.rs` | Leaves engine dirty flags intact so `render_composition` can upload the result on the next frame. | Calling `clear_dirty_flags()` inside `DrawingFinished` races with the next render pass and makes newly drawn vector shapes disappear. |

**AI AGENT WARNING:** Do not remove, shorten, or "optimize away" the startup active-tab setting, the multi-frame repaint requests, or the `DrawingFinished` no-op. These look like minor details but they are the only thing keeping the first canvas visible. Every past removal has re-introduced the bug. If a change you are making touches any of these three places, stop and verify with an actual app launch (or `HCIE_AUTO_SCREENSHOT`) that the default `Untitled` canvas is visible without clicking the tab title.

If a new feature conflicts with one of these mechanisms, extend the existing API by adding a new function or file rather than bypassing or duplicating the protected code.

## GUI Workspace Architecture (CRITICAL — AI Search Scope)

Only one GUI workspace exists: `hcie-egui-app/`. The GUI crates are `hcie-gui-egui/` and `egui-panel-*/`.

### AI Search Rule

When searching for a crate, module, file, or symbol:

1. Scan the active GUI workspace first (`hcie-egui-app/`).
2. Then scan sibling engine crates (`../hcie-*/`).
3. Follow the `Cargo.toml` dependency chain; if a dependency lives in another workspace, scan that workspace too.
4. If a symbol name appears in two different modules (for example, `plugins/`), examine both.

## Error Isolation

Every crate can be built independently. A crash or failure in one crate does not cascade to the others. The GUI does not see engine code changes until the engine static library is rebuilt.

## Locked Files (agents may not write here)

- `hcie-protocol/src/*.rs`
- `hcie-color/src/*.rs`
- `hcie-blend/src/*.rs`
- `hcie-history/src/*.rs`
- `hcie-brush-engine/src/*.rs`
- `hcie-draw/src/*.rs`
- `hcie-composite/src/*.rs`
- `hcie-filter/src/*.rs`
- `hcie-selection/src/*.rs`
- `hcie-text/src/*.rs`
- `hcie-vector/src/*.rs`
- `hcie-tile/src/*.rs`
- `hcie-io/src/*.rs`
- `hcie-document/src/*.rs`
- `hcie-engine-api/src/*.rs`
- `hcie-ai/src/*.rs`
- `hcie-vision/src/*.rs`
- `hcie-fx/src/*.rs`
- `hcie-psd/src/*.rs`
- `hcie-kra/src/*.rs`
- `hcie-native/src/*.rs`

Use `unlock.sh <crate>` to temporarily open a crate, make the required change, then `lock.sh <crate>` to lock it again.

## Open Files (agents may write here)

### Active egui GUI

- `hcie-egui-app/crates/hcie-gui-egui/src/*.rs`
- `hcie-egui-app/crates/hcie-gui-egui/Cargo.toml`
- `hcie-egui-app/crates/egui-panel-adapter/src/*.rs`
- `hcie-egui-app/crates/egui-panel-filters/src/*.rs`
- `hcie-egui-app/crates/egui-panel-ai-chat/src/*.rs`
- `hcie-egui-app/crates/egui-panel-script/src/*.rs`
- `hcie-egui-app/crates/egui-panel-ai-script/src/*.rs`


## Important Notes

- Never add an `egui` dependency to any engine crate.
- Never access `hcie-protocol` directly from GUI code.
- Never import a locked engine crate directly from GUI code; route everything through `hcie-engine-api`.
- The root `hcie-egui-app/Cargo.toml` currently lists `hcie-protocol`, `hcie-blend`, and `hcie-io` for legacy compatibility. Do not add new direct engine dependencies there.

## Engine API — Public Surface

The GUI uses only the public items exported by `hcie-engine-api`. Example high-level operations:

```rust
use hcie_engine_api::Engine;

let mut engine = Engine::new(800, 600);
let layer_id = engine.add_layer("Background");
engine.set_active_layer(layer_id);
engine.draw_stroke(&points);
let pixels = engine.get_composite_pixels();
```

For the full API, see `hcie-engine-api/src/lib.rs` and `ARCHITECTURE.md`.

## Screenshot & Visual Verification (AI Agent Workflow)

AI agents MUST capture screenshots after every GUI change to verify visual results.
The egui GUI has a built-in screenshot mechanism that agents should use.

### How to Capture

#### Full Viewport Screenshot (F12)
- **Trigger:** Press `F12` while the egui GUI is running
- **Output:** `target/screenshots/toolbox_{unix_timestamp}.png`
- **Scope:** Entire viewport (all panels, menus, canvas)
- **Implementation:** `hcie-egui-app/crates/hcie-gui-egui/src/app/mod.rs:2340-2342`

#### Automated Panel Screenshot (CLI)
```bash
cargo run -p hcie-gui-egui -- --screenshot-panel "PanelName" output.png
```
- **Scope:** Crops to the specified panel's screen-space rect
- **Implementation:** `hcie-egui-app/crates/hcie-gui-egui/src/app/mod.rs:2994-3009`
- **State machine:** 7-frame capture flow (layout settle → screenshot → crop → save)

#### Available Panel Names (exact strings for `--screenshot-panel`)

| Panel Name | Enum Variant | Description |
|------------|-------------|-------------|
| `Tools` | `HciePane::Tools` | Toolbox (brush, eraser, shapes, etc.) |
| `Filters` | `HciePane::Filters` | Filter parameter panels |
| `Brushes & Tips` | `HciePane::Brushes` | Brush presets and tip configuration |
| `Color Palette` | `HciePane::ColorBox` | Color picker and palette |
| `AI Assistant` | `HciePane::AiAssistant` | AI chat panel |
| `Layers` | `HciePane::Layers` | Layer list and management |
| `History` | `HciePane::History` | Undo/redo history timeline |
| `Properties` | `HciePane::Properties` | Active object properties |
| `Plugins` | `HciePane::Plugins` | Plugin management panel |
| `Layer Styles` | `HciePane::LayerStyles` | Layer effects/styles editor |
| `Layer Details` | `HciePane::LayerDetails` | Detailed layer info panel |

> **Note:** Panel names are case-sensitive and must match exactly. The mapping is
> defined in `pane_from_name()` at `mod.rs:926-941`.

### Screenshot Flow (7-Frame State Machine)
```
Frame 0: Ensure target panel exists in dock
Frame 1-5: Wait for layout to settle (50ms repaints each)
Frame 6: Issue ViewportCommand::Screenshot
Frame 7: Receive egui::Event::Screenshot, crop to panel rect, save PNG, close
```

### Helper Functions
| Function | File | Purpose |
|----------|------|---------|
| `crop_colorimage()` | `mod.rs:3373-3391` | Crops `egui::ColorImage` to screen-space rect |
| `save_colorimage()` | `mod.rs:3393-3400` | RGBA bytes → PNG file via `image::save_buffer` |
| `pane_from_name()` | `mod.rs:926-941` | Maps panel name strings to `HciePane` enum |

### Agent GUI Iteration Rules
1. **After every CSS/layout/code change:** Take a screenshot and visually inspect it
2. **Before/after refactoring:** Capture both states for comparison
3. **When user provides a reference image:** Capture current state, compare with reference
4. **Document visual regressions:** If a screenshot shows degradation, log it before fixing
5. **Use `--screenshot-panel`** for focused panel inspection (not full viewport)
6. **Engine pixel-perfect capture:** Use `engine.get_composite_pixels()` for viewport-independent output (bypasses GUI rendering)

### Visual Design Iteration (Reference Image Workflow)

When the user provides reference images or design mockups, the AI agent MUST follow
this workflow to ensure pixel-accurate results:

1. **Study the reference image first.** Before writing any code, analyze the
   reference image's layout, spacing, colours, font sizes, shadows, borders,
   and overall visual hierarchy. Note exact values where possible.

2. **Implement changes incrementally.** Apply one visual change at a time (e.g.
   background colour first, then typography, then spacing). After each change:
   - Take a screenshot (`F12` or `--screenshot-panel`)
   - Compare against the reference image
   - Note discrepancies and fix them before moving on

3. **Report visual diffs to the user.** After completing a set of changes,
   present a before/after comparison. Embed screenshots in the response so the
   user can visually validate the result without running the application.

4. **Respect the user's verbal corrections.** When the user says "move X left",
   "make Y darker", "the spacing is too wide", etc., apply the feedback
   literally and take a new screenshot immediately. Do not re-interpret or
   override the user's aesthetic judgment.

5. **Preserve design tokens across sessions.** If the user establishes a visual
   language (specific colours, font sizes, border radii), document them and
   reuse them consistently in subsequent panels and dialogs.

### API Details
- **egui built-in:** `egui::ViewportCommand::Screenshot` — requests platform viewport capture
- **egui event:** `egui::Event::Screenshot { image, .. }` — delivers `egui::ColorImage` on next frame
- **image crate:** `image::save_buffer()` — writes raw RGBA bytes to PNG

---

# DOCUMENTATION

## Comprehensive Documentation Guidelines

For every function, method, struct, module, and file within the scope of work, add a detailed docstring/comment block at the very beginning. All documentation must be written in clear, professional English.

Each block must include:

* **Purpose:** A clear explanation of what this specific section, module, or function does.
* **Logic & Workflow:** The underlying operational logic, algorithm, or step-by-step mechanism it uses to achieve its goal.
* **Arguments & Returns (for functions/methods):** Explicit descriptions of input parameters (types and purposes) and return values.
* **Side Effects / Dependencies (if any):** Any global state changes, I/O operations, or external system dependencies.

# DEBUGGING

Only apply while debugging operations.

## Role and Objective

Analyze the provided code and improve it by adding detailed documentation and strategic debug logging.

## Strategic Debug Logging Guidelines

To accelerate root-cause analysis and system observability, insert comprehensive debug logs throughout the codebase.

* **Placement:** Place logs at critical execution boundaries:
    * Entry and exit points of major functions (logging input parameters and final return values).
    * Inside conditional branches (`if` / `else`) to track the exact execution path.
    * Immediately before and after complex calculations, external API calls, or database operations.
    * Inside catch/except blocks to capture full error contexts and stack traces.
* **Log Level:** Use the appropriate `DEBUG` or `TRACE` log level so these messages do not clutter production environments but can be fully enabled during troubleshooting.
* **Contextual Data:** Ensure log messages include relevant runtime data variables, identifiers, or state structures (serialized safely) to provide actionable context for debugging.

---

# Execution Output Requirements

* Preserve all existing business logic; do not alter the functionality of the code.
* Maintain the established code formatting style, indentation, and naming conventions of the source file.
* Return the fully updated code enclosed in appropriate markdown code fences.