hcie-rust-v3.05/.kilo/plans/1784862272150-kra-format-fix.md

# KRA Format Fix Plan

## Root Causes (confirmed by analysis)

### 1. VERSION Header Mismatch — Krita Crash + Self-Import Failures
**File:** `hcie-kra/src/kra_saver.rs` lines 324–329, 409–415

The saver writes `VERSION 2\n` in the VERS tile header, but the compressed payload uses
version byte `1` (meaning **no** delta decoding). Krita's VERS parser sees VERSION 2 and
applies delta decoding after decompression, producing garbage or a crash.

Our own importer (`hcie-kra/src/lib.rs` line 158) also checks `if version >= 2` and
would apply delta decoding, producing wrong pixel data.

**Fix:** Change both `encode_layer_vers` and `encode_mask_vers` to write `VERSION 1`
instead of `VERSION 2`.

### 2. Fake "LZF" Compression — Bloated Files + Non-Standard
**File:** `hcie-kra/src/kra_saver.rs` lines 308–316, 394–403

The "LZF" compression is a custom RLE scheme that adds 513 bytes of overhead per tile
(1 version byte + 512 control bytes), making files **larger** than uncompressed. A full
1920×1080 layer (510 tiles) goes from 8.29 MB to 8.62 MB (+4%). The format happens to
look like real LZF literal runs, so our `lzf_decompress` function processes it correctly,
but a real LZF decoder would fail on tiles requiring back-references.

**Fix:** Store tiles as RAW (uncompressed). Remove the fake compression logic and write
raw planar pixel data. Label tiles as `RAW` instead of `LZF` in the tile header. The
importer already handles RAW tiles correctly (lib.rs line 166–168).

### 3. Invalid UUID Format — Krita Rejects Our XML
**File:** `hcie-kra/src/kra_saver.rs` line 240

UUIDs are generated from a single `u64` (8 bytes) and formatted as 32 hex digits with
leading zeros: `{00000000000000003aeba3f7cf423ad9}`. Proper UUIDs are 128 bits (16 bytes)
with dashed formatting: `{3aeba3f7-cf42-3ad9-…}`. Krita may validate UUID format and
reject our non-standard forms.

**Fix:** Generate proper 128-bit random UUIDs using two `rand::random::<u64>()` calls
and format with dashes per standard UUID layout.

### 4. Color Space / Bit Depth Ignored — Wrong Colors on Import
**File:** `hcie-kra/src/lib.rs` lines 647–698

The importer reads `colorspacename`, `channeldepth`, and `profile` attributes from the
`<IMAGE>` and `<layer>` tags but ignores them. If the source file uses a non-RGBA color
space (e.g., CMYK, Grayscale) or 16-bit channel depth, the raw pixel bytes are
misinterpreted, producing wrong colors.

**Fix:** At minimum, validate on import that:
- `colorspacename` is `"RGBA"`
- `channeldepth` is `"U8"` or `"U16"` (for U16, convert to U8 via shifting)
- Return an error if the format is unsupported

### 5. Silent Layer Failures — Data Loss Without Notice
**File:** `hcie-kra/src/lib.rs` lines 790, 808, 814, 837

When a layer file can't be found, VERS parsing fails, or image decoding fails, the
layer is silently skipped or turned into a transparent layer. The user has no indication
that data was lost.

**Fix:** Add `log::warn!` calls at each failure point, including the layer name and
reason for failure.

### 6. Missing `layers.xml` Fallback
**File:** `hcie-kra/src/lib.rs` line 626

The main importer only tries `maindoc.xml`. Some Krita variants write `layers.xml`
instead. The v2 loader (`custom_loaders_kra_v2.rs`) has this fallback but it's separate.

**Fix:** Add `layers.xml` as a secondary attempt in `try_import_krita_maindoc`.

### 7. Inconsistent `DATA` Line Format
**File:** `hcie-kra/src/kra_saver.rs` lines 329 vs 415

`encode_layer_vers` writes `DATA {tiles.len()}\n` but `encode_mask_vers` writes `DATA\n`
(no count). The parser handles both, but it's inconsistent.

**Fix:** Make both use `DATA\n` (no count) — the parser ignores the count anyway, and
removing it avoids an extra format requirement.

---

## Implementation Tasks

### Task A: Fix VERS header and compression (`kra_saver.rs`)
1. Change `writeln!(output, "VERSION 2")` → `writeln!(output, "VERSION 1")` in `encode_layer_vers`
2. Change `b"VERSION 2\n"` → `b"VERSION 1\n"` in `encode_mask_vers`
3. Remove the fake LZF compression loop in `encode_layer_vers` (lines 308–316)
4. Replace with writing raw planar pixel data directly (no version byte, no control bytes)
5. Update tile header tag from `"LZF"` to `"RAW"` (line 333)
6. Repeat steps 3–5 for `encode_mask_vers` (lines 394–403)

### Task B: Fix UUID format (`kra_saver.rs`)
7. Replace `let uuid = format!("{{{:032x}}}", layer.id)` with proper 128-bit UUID:
   ```rust
   let high = rand::random::<u64>();
   let low = rand::random::<u64>();
   let uuid = format!(
       "{{{:08x}-{:04x}-{:04x}-{:04x}-{:012x}}}",
       (high >> 32) as u32,
       (high >> 16) as u16 & 0xFFFF,
       high as u16,
       (low >> 48) as u16,
       low & 0x0000_FFFF_FFFF_FFFF
   );
   ```
8. Apply same fix to mask UUID generation on line 257

### Task C: Add color space validation (`lib.rs`)
9. In `try_import_krita_maindoc`, after reading width/height from `<IMAGE>`:
   - Read `colorspacename` and `channeldepth` attributes
   - If `colorspacename != "RGBA"`, return error: "Unsupported color space: {name}"
   - If `channeldepth != "U8"`, return error: "Unsupported channel depth: {depth}"
   - (Future: add U16→U8 conversion)

### Task D: Add error logging (`lib.rs`)
10. Add `log::warn!` before each `continue` / silent fallback:
    - Line 790 (layer file not found): warn with layer name
    - Line 808 (SVG rasterization failed): warn with layer name
    - Line 814 (VERS parse failed): warn with layer name
    - Line 837 (image load failed): warn with layer name

### Task E: Add `layers.xml` fallback (`lib.rs`)
11. In `try_import_krita_maindoc`, after the `maindoc.xml` attempt fails, try
    `archive.by_name("layers.xml")` before returning `Ok(vec![])`.

### Task F: Normalize `DATA` line format (`kra_saver.rs`)
12. Change line 329: `writeln!(output, "DATA {}", tiles.len())` → `writeln!(output, "DATA")`
13. The mask encoder already uses `b"DATA\n"` — leave unchanged.

---

## Files to Modify

| File | Changes |
|------|---------|
| `hcie-kra/src/kra_saver.rs` | Tasks A, B, F |
| `hcie-kra/src/lib.rs` | Tasks C, D, E |

---

## Validation

After implementing, verify with:

1. **Roundtrip test:** Save a multi-layer document as KRA, then import it back. Compare
   pixels and layer names against the original.

2. **Krita compatibility:** Open the exported KRA in Krita ≥ 5.x. Verify it opens without
   crash and displays correct colors. Also open the PSD→KRA exported file and verify it
   matches the mergedimage.png preview.

3. **Existing test suite:** Run `cargo test -p hcie-kra` and
   `cargo test -p hcie-engine-api --test visual_regression` to ensure no regressions.

4. **Edge cases:**
   - Empty layers (all-transparent pixels)
   - Layers with masks
   - Group layers
   - Layer names containing special characters (`&`, `<`, `>`, Unicode)
   - Error on unsupported color space (e.g., CMYK, Grayscale)
   - Error on unsupported bit depth (e.g., U16, F16)