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:

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:

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)

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.