@harmonyos-arkts/d2h 0.1.11 → 0.1.13

package/skills/android2hmos_resources_convert/references/image-conversion-rules.md

@@ -1,230 +1,230 @@
-# Android to HarmonyOS Image Resource Conversion Rules
-
-Complete rules for converting Android **image resources** — bitmap files, nine-patch images, launcher icons (mipmap), adaptive icons — into HarmonyOS `media/` resources. XML drawables → SVG are covered separately in `xml-drawable-to-svg-rules.md`; this document defines what routes to SVG, plus the qualifier directory algorithm and reference resolution needed by image conversion.
-
-## Table of Contents
-1. [Target Directory Structure](#target-directory-structure)
-2. [Bitmap Images → media](#bitmap-images--media)
-3. [Nine-Patch Images](#nine-patch-images)
-4. [Mipmap → media](#mipmap--media)
-5. [Adaptive Icon → Layered-Image JSON](#adaptive-icon--layered-image-json)
-6. [Identifying XML vs Image Drawables](#identifying-xml-vs-image-drawables)
-7. [Qualifier Mapping](#qualifier-mapping)
-8. [Reference Resolution for Images](#reference-resolution-for-images)
-9. [Special Cases and Edge Cases](#special-cases-and-edge-cases)
-
----
-
-## Target Directory Structure
-
-HarmonyOS image resources live under the `media/` resource group:
-
-```
-entry/src/main/resources/
-├── base/media/           # default images (no qualifier)
-├── ldpi/media/           # density-qualified
-├── dark/media/           # night mode
-├── zh_CN/media/          # locale-qualified
-└── zh_CN-dark-ldpi/media/  # combined qualifiers
-```
-
-HarmonyOS supported image formats: PNG, JPG, GIF, SVG, WEBP, BMP — all common Android bitmap formats copy directly.
-
----
-
-## Bitmap Images → media
-
-Copy image files from Android `drawable*/` (and `mipmap*/`) to the qualifier-mapped `media/` directory:
-
-- `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp` → direct copy, filename unchanged
-- Resource names are preserved exactly as Android spells them — they are identifiers
-- Do NOT copy XML files in this step — classify them first (see [Identifying XML vs Image Drawables](#identifying-xml-vs-image-drawables))
-
----
-
-## Nine-Patch Images
-
-Android nine-patch files (`.9.png`) have no native HarmonyOS equivalent:
-
-1. **Rename**: `.9.png` → `<name>_9.png`. HarmonyOS forbids `.` in resource filenames except the final extension separator, so `btn_bg.9.png` would be invalid — it becomes `btn_bg_9.png`.
-2. **Semantics lost**: the 1-px stretch/padding border markers are rendered as ordinary pixels; nine-patch stretching behavior does not carry over. The developer must implement stretching at the ArkUI component level (`.borderRadius` + `.resizable` or 9-slice via `ResizableOptions` where supported).
-3. Always log nine-patch conversions in the report with the rename and the lost-semantics note.
-
----
-
-## Mipmap → media
-
-Launcher icons from `mipmap*/` directories go to the qualifier-mapped `media/` directory:
-
-- PNG/WEBP launcher icons (`ic_launcher.png`, `ic_launcher_round.png`, `ic_launcher_foreground.png`, `ic_launcher_background.png`, …) → direct copy
-- **Adaptive icon XML** (root `<adaptive-icon>`, commonly in `mipmap-anydpi-v26/`) → layered-image JSON (see below)
-- **VectorDrawable XML in mipmap** (root `<vector>`) → convert to SVG exactly like drawable vectors
-
-**Common pattern**: `mipmap-anydpi-v26/` is extremely common. Parse the qualifier as `anydpi` (→ `base`) + `v26` (→ strip) → target `base/media/`. Classify the files inside by their XML root element, never by the directory name.
-
----
-
-## Adaptive Icon → Layered-Image JSON
-
-Convert `<adaptive-icon>` XML to `<original_name>_layered_image.json` in the target `media/` directory.
-
-**Conversion rules:**
-
-1. Parse the XML and extract the `<background>` and `<foreground>` elements.
-2. Only `background` and `foreground` are valid keys in the output JSON. Skip `monochrome` (and any other elements) **from the JSON output** — HarmonyOS layered-image has no equivalent. However, the resource *referenced* by `monochrome` is a real asset that must still be converted as a normal image.
-3. Convert references:
-   - `@drawable/xxx` → `$media:xxx`
-   - `@mipmap/xxx` → `$media:xxx`
-   - `@color/xxx` → **generate a solid-color PNG** (below) — layered-image only accepts `$media:` references, never `$color:`
-4. **Color background handling (critical)**:
-   a. Resolve `@color/xxx` to its hex value from `values*/colors.xml`, following reference chains to a concrete value.
-   b. Generate a solid-color PNG filled entirely with that hex (any small size, e.g. 1×1 or 108×108 px).
-   c. Save as `<color_name>_bg.png` in `base/media/`.
-   d. Reference it as `$media:<color_name>_bg` in the JSON.
-   e. If the color cannot be resolved (library resource, source `res/` fallback), log it as an unresolved dependency in the report.
-5. A layer may carry artwork as a **child element** instead of an `android:drawable` attribute (`<foreground><vector …/></foreground>`). Convert that inline drawable to its own media file named `<icon_name>_<layer>.svg` and reference it as `$media:<icon_name>_<layer>`. Never emit the JSON with the layer simply absent. A `<bitmap android:src="@drawable/x"/>` wrapper is just a reference — point at `$media:x`.
-
-**Example:**
-
-```xml
-<!-- mipmap-anydpi-v26/ic_launcher.xml -->
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/md_orange_700" />
-    <foreground android:drawable="@mipmap/ic_launcher_foreground" />
-    <monochrome android:drawable="@drawable/ic_launcher_monochrome" />
-</adaptive-icon>
-```
-
-Suppose `@color/md_orange_700` resolves to `#F57C00`. Generate `base/media/md_orange_700_bg.png` (solid `#F57C00`), then write `base/media/ic_launcher_layered_image.json`:
-
-```json
-{
-  "layered-image": {
-    "background": "$media:md_orange_700_bg",
-    "foreground": "$media:ic_launcher_foreground"
-  }
-}
-```
-
-`@drawable/ic_launcher_monochrome` is additionally converted as a normal drawable (SVG or bitmap per its type) even though it never appears in the JSON.
-
----
-
-## Identifying XML vs Image Drawables
-
-In `drawable*/` and `mipmap*/` directories, classify every `.xml` file by its **root element** (never by filename or directory):
-
-| Root element | Type | Route |
-|---|---|---|
-| `<vector>` | VectorDrawable | → SVG (`xml-drawable-to-svg-rules.md`) |
-| `<shape>` | ShapeDrawable | → SVG |
-| `<layer-list>` | LayerListDrawable | → SVG |
-| `<selector>` | StateListDrawable | Extract default state → SVG; log dropped state variants |
-| `<adaptive-icon>` | Adaptive icon | → layered-image JSON (above) |
-| `<ripple>`, `<animated-vector>`, `<animated-selector>`, `<transition>`, `<level-list>`, `<scale>`, `<rotate>`, `<inset>` | Runtime behavior | Unmappable — log. Exception: `<inset>`/`<rotate>` with fixed values may be applied statically and the inner drawable converted; log either way |
-
-When several drawable directories provide the same resource name (`drawable/x.xml` and `drawable-anydpi/x.xml` both landing in `base/media/`), the source with **fewer qualifiers** wins; record the loser in the report as a collision — never silently drop it.
-
----
-
-## Qualifier Mapping
-
-Android uses qualifier suffixes on resource directories; HarmonyOS uses a different qualifier naming scheme. Images are always placed under the `media/` group of the mapped qualifier directory.
-
-### Density Qualifiers
-
-The DPI range labels differ between platforms:
-
-| Android Qualifier | Approx DPI | HarmonyOS Qualifier | HarmonyOS DPI Range |
-|---|---|---|---|
-| `ldpi` | 120 | `sdpi` | (0, 120] |
-| `mdpi` | 160 | `mdpi` | (120, 160] |
-| `tvdpi` | 213 | `ldpi` | (160, 240] |
-| `hdpi` | 240 | `ldpi` | (160, 240] |
-| `xhdpi` | 320 | `xldpi` | (240, 320] |
-| `xxhdpi` | 480 | `xxldpi` | (320, 480] |
-| `xxxhdpi` | 640 | `xxxldpi` | (480, 640] |
-| `nodpi` | N/A | `base` | No density qualifier |
-| `anydpi` | N/A | `base` | No density qualifier |
-
-Note the deliberate mismatch: Android `hdpi` (~240) maps to HarmonyOS **`ldpi`** because HarmonyOS labels the (160, 240] range `ldpi`.
-
-### Language/Region Qualifiers
-
-| Android | HarmonyOS |
-|---|---|
-| `drawable-ar` | `ar/media/` |
-| `drawable-zh` | `zh/media/` |
-| `drawable-zh-rCN` | `zh_CN/media/` |
-| `drawable-zh-rTW` | `zh_TW/media/` |
-| `drawable-en-rUS` | `en_US/media/` |
-| `drawable-fr-rFR` | `fr_FR/media/` |
-
-Parsing: language = 2–3 lowercase letters (ISO 639); region = `r` + 2 uppercase letters, strip the `r`; script = `b+sr+Latn` → `sr_Latn`. Language and region join with `_`.
-
-### Orientation Qualifiers
-
-| Android | HarmonyOS |
-|---|---|
-| `land` | `horizontal` |
-| `port` | `vertical` |
-
-### Night Mode Qualifiers
-
-| Android | HarmonyOS |
-|---|---|
-| `night` | `dark` |
-| `notnight` | `light` |
-
-### Combining Multiple Qualifiers
-
-**Parsing algorithm for any Android drawable/mipmap directory name:**
-
-1. Split the directory name by `-`; the first segment is the resource type
-2. Parse remaining qualifiers left-to-right: language/region, density, orientation, night mode, API level (`v<N>`), screen-size constraints
-3. Map each recognized qualifier to its HarmonyOS equivalent
-4. **Strip silently** (do not reject): API level `v<N>`, layout direction (`ldrtl`/`ldltr`), screen shape (`round`/`notround`), HDR (`highdr`/`lowdr`), aspect (`long`/`notlong`)
-5. **Skip the entire directory** (mark all resources unmapped) when screen-size qualifiers remain: `sw<N>dp`, `w<N>dp`, `h<N>dp`, `small`, `normal`, `large`, `xlarge` — HarmonyOS has no equivalent; do NOT convert them to `base/`
-6. If no qualifiers remain after stripping, use `base/`
-7. Reassemble in HarmonyOS order: MCC_MNC-language_script_country/region-orientation-device-colormode-density
-
-**Examples:**
-
-| Android Directory | Qualifiers | HarmonyOS Target |
-|---|---|---|
-| `drawable-hdpi` | hdpi→ldpi | `ldpi/media/` |
-| `mipmap-anydpi-v26` | anydpi→base, v26 stripped | `base/media/` |
-| `drawable-zh-rCN-night-hdpi` | zh_CN, dark, ldpi | `zh_CN-dark-ldpi/media/` |
-| `drawable-night-v21` | dark, v21 stripped | `dark/media/` |
-| `drawable-hdpi-v4` | ldpi, v4 stripped | `ldpi/media/` |
-| `drawable-sw600dp` | **skip — unmapped** | N/A |
-
-Never reject a directory just because one qualifier is unsupported — strip it and continue.
-
----
-
-## Reference Resolution for Images
-
-Image conversion encounters value references in three places. Build a lookup table from `values*/colors.xml` and `values*/dimens.xml` before converting drawables.
-
-**In converted SVG files:**
-- `@color/name` used as `fillColor`/`strokeColor` → resolve to the hex value during SVG generation (follow chains; fallback `#000000` + log)
-- `@dimen/name` used as a dimension → resolve to the numeric value (fallback: sensible default + log)
-- `@android:color/*` system colors → map known ones (`white`→`#FFFFFF`, `black`→`#000000`, `transparent`→`#00000000`); unknown → `#000000` + log
-
-**In layered-image JSON files:**
-- `@drawable/xxx` / `@mipmap/xxx` → keep as `$media:xxx` (file references — the files themselves are converted)
-- `@color/xxx` → resolve to hex and generate the solid-color PNG (see adaptive icon rules)
-
-**Reference chain depth**: follow at most 5 levels (`A → B → C → concrete value`). Unresolved references are expected — library resources are absent from source `res/`; record them in the report with likely library provenance (e.g. `@drawable/abc_*` → AndroidX AppCompat, `@drawable/mtrl_*`/`design_*` → Material Components) so the developer can supply them manually.
-
----
-
-## Special Cases and Edge Cases
-
-- **Same name in multiple density directories** (`drawable-hdpi/x.png`, `drawable-xxhdpi/x.png`) → each copies to its own qualifier directory (`ldpi/media/x.png`, `xxldpi/media/x.png`) — no conflict.
-- **Same name from qualified and unqualified dirs** (`drawable/x.png` and `drawable-anydpi/x.xml` both → `base/media/`) → the source with fewer qualifiers wins; the loser is recorded as a collision.
-- **Existing files in the HarmonyOS project**: merge, do not overwrite — an existing media file with the same name keeps its position; the attempted copy is logged as a collision for the developer to review.
-- **Empty/corrupt image files**: skip and log; do not copy zero-byte files into `media/`.
-- **Filenames illegal in HarmonyOS** (`.` inside the name, leading digits are fine but uppercase is kept as-is): only the `.9.png` rename is automatic; any other illegal name is copied with a logged `unmappable` entry explaining the manual rename needed.
-- **Large image sets**: first inventory, then group by (classification × qualifier), then convert group by group, then verify — never convert while still scanning.
+# Android to HarmonyOS Image Resource Conversion Rules
+
+Complete rules for converting Android **image resources** — bitmap files, nine-patch images, launcher icons (mipmap), adaptive icons — into HarmonyOS `media/` resources. XML drawables → SVG are covered separately in `xml-drawable-to-svg-rules.md`; this document defines what routes to SVG, plus the qualifier directory algorithm and reference resolution needed by image conversion.
+
+## Table of Contents
+1. [Target Directory Structure](#target-directory-structure)
+2. [Bitmap Images → media](#bitmap-images--media)
+3. [Nine-Patch Images](#nine-patch-images)
+4. [Mipmap → media](#mipmap--media)
+5. [Adaptive Icon → Layered-Image JSON](#adaptive-icon--layered-image-json)
+6. [Identifying XML vs Image Drawables](#identifying-xml-vs-image-drawables)
+7. [Qualifier Mapping](#qualifier-mapping)
+8. [Reference Resolution for Images](#reference-resolution-for-images)
+9. [Special Cases and Edge Cases](#special-cases-and-edge-cases)
+
+---
+
+## Target Directory Structure
+
+HarmonyOS image resources live under the `media/` resource group:
+
+```
+entry/src/main/resources/
+├── base/media/           # default images (no qualifier)
+├── ldpi/media/           # density-qualified
+├── dark/media/           # night mode
+├── zh_CN/media/          # locale-qualified
+└── zh_CN-dark-ldpi/media/  # combined qualifiers
+```
+
+HarmonyOS supported image formats: PNG, JPG, GIF, SVG, WEBP, BMP — all common Android bitmap formats copy directly.
+
+---
+
+## Bitmap Images → media
+
+Copy image files from Android `drawable*/` (and `mipmap*/`) to the qualifier-mapped `media/` directory:
+
+- `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp` → direct copy, filename unchanged
+- Resource names are preserved exactly as Android spells them — they are identifiers
+- Do NOT copy XML files in this step — classify them first (see [Identifying XML vs Image Drawables](#identifying-xml-vs-image-drawables))
+
+---
+
+## Nine-Patch Images
+
+Android nine-patch files (`.9.png`) have no native HarmonyOS equivalent:
+
+1. **Rename**: `.9.png` → `<name>_9.png`. HarmonyOS forbids `.` in resource filenames except the final extension separator, so `btn_bg.9.png` would be invalid — it becomes `btn_bg_9.png`.
+2. **Semantics lost**: the 1-px stretch/padding border markers are rendered as ordinary pixels; nine-patch stretching behavior does not carry over. The developer must implement stretching at the ArkUI component level (`.borderRadius` + `.resizable` or 9-slice via `ResizableOptions` where supported).
+3. Always log nine-patch conversions in the report with the rename and the lost-semantics note.
+
+---
+
+## Mipmap → media
+
+Launcher icons from `mipmap*/` directories go to the qualifier-mapped `media/` directory:
+
+- PNG/WEBP launcher icons (`ic_launcher.png`, `ic_launcher_round.png`, `ic_launcher_foreground.png`, `ic_launcher_background.png`, …) → direct copy
+- **Adaptive icon XML** (root `<adaptive-icon>`, commonly in `mipmap-anydpi-v26/`) → layered-image JSON (see below)
+- **VectorDrawable XML in mipmap** (root `<vector>`) → convert to SVG exactly like drawable vectors
+
+**Common pattern**: `mipmap-anydpi-v26/` is extremely common. Parse the qualifier as `anydpi` (→ `base`) + `v26` (→ strip) → target `base/media/`. Classify the files inside by their XML root element, never by the directory name.
+
+---
+
+## Adaptive Icon → Layered-Image JSON
+
+Convert `<adaptive-icon>` XML to `<original_name>_layered_image.json` in the target `media/` directory.
+
+**Conversion rules:**
+
+1. Parse the XML and extract the `<background>` and `<foreground>` elements.
+2. Only `background` and `foreground` are valid keys in the output JSON. Skip `monochrome` (and any other elements) **from the JSON output** — HarmonyOS layered-image has no equivalent. However, the resource *referenced* by `monochrome` is a real asset that must still be converted as a normal image.
+3. Convert references:
+   - `@drawable/xxx` → `$media:xxx`
+   - `@mipmap/xxx` → `$media:xxx`
+   - `@color/xxx` → **generate a solid-color PNG** (below) — layered-image only accepts `$media:` references, never `$color:`
+4. **Color background handling (critical)**:
+   a. Resolve `@color/xxx` to its hex value from `values*/colors.xml`, following reference chains to a concrete value.
+   b. Generate a solid-color PNG filled entirely with that hex (any small size, e.g. 1×1 or 108×108 px).
+   c. Save as `<color_name>_bg.png` in `base/media/`.
+   d. Reference it as `$media:<color_name>_bg` in the JSON.
+   e. If the color cannot be resolved (library resource, source `res/` fallback), log it as an unresolved dependency in the report.
+5. A layer may carry artwork as a **child element** instead of an `android:drawable` attribute (`<foreground><vector …/></foreground>`). Convert that inline drawable to its own media file named `<icon_name>_<layer>.svg` and reference it as `$media:<icon_name>_<layer>`. Never emit the JSON with the layer simply absent. A `<bitmap android:src="@drawable/x"/>` wrapper is just a reference — point at `$media:x`.
+
+**Example:**
+
+```xml
+<!-- mipmap-anydpi-v26/ic_launcher.xml -->
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/md_orange_700" />
+    <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+    <monochrome android:drawable="@drawable/ic_launcher_monochrome" />
+</adaptive-icon>
+```
+
+Suppose `@color/md_orange_700` resolves to `#F57C00`. Generate `base/media/md_orange_700_bg.png` (solid `#F57C00`), then write `base/media/ic_launcher_layered_image.json`:
+
+```json
+{
+  "layered-image": {
+    "background": "$media:md_orange_700_bg",
+    "foreground": "$media:ic_launcher_foreground"
+  }
+}
+```
+
+`@drawable/ic_launcher_monochrome` is additionally converted as a normal drawable (SVG or bitmap per its type) even though it never appears in the JSON.
+
+---
+
+## Identifying XML vs Image Drawables
+
+In `drawable*/` and `mipmap*/` directories, classify every `.xml` file by its **root element** (never by filename or directory):
+
+| Root element | Type | Route |
+|---|---|---|
+| `<vector>` | VectorDrawable | → SVG (`xml-drawable-to-svg-rules.md`) |
+| `<shape>` | ShapeDrawable | → SVG |
+| `<layer-list>` | LayerListDrawable | → SVG |
+| `<selector>` | StateListDrawable | Extract default state → SVG; log dropped state variants |
+| `<adaptive-icon>` | Adaptive icon | → layered-image JSON (above) |
+| `<ripple>`, `<animated-vector>`, `<animated-selector>`, `<transition>`, `<level-list>`, `<scale>`, `<rotate>`, `<inset>` | Runtime behavior | Unmappable — log. Exception: `<inset>`/`<rotate>` with fixed values may be applied statically and the inner drawable converted; log either way |
+
+When several drawable directories provide the same resource name (`drawable/x.xml` and `drawable-anydpi/x.xml` both landing in `base/media/`), the source with **fewer qualifiers** wins; record the loser in the report as a collision — never silently drop it.
+
+---
+
+## Qualifier Mapping
+
+Android uses qualifier suffixes on resource directories; HarmonyOS uses a different qualifier naming scheme. Images are always placed under the `media/` group of the mapped qualifier directory.
+
+### Density Qualifiers
+
+The DPI range labels differ between platforms:
+
+| Android Qualifier | Approx DPI | HarmonyOS Qualifier | HarmonyOS DPI Range |
+|---|---|---|---|
+| `ldpi` | 120 | `sdpi` | (0, 120] |
+| `mdpi` | 160 | `mdpi` | (120, 160] |
+| `tvdpi` | 213 | `ldpi` | (160, 240] |
+| `hdpi` | 240 | `ldpi` | (160, 240] |
+| `xhdpi` | 320 | `xldpi` | (240, 320] |
+| `xxhdpi` | 480 | `xxldpi` | (320, 480] |
+| `xxxhdpi` | 640 | `xxxldpi` | (480, 640] |
+| `nodpi` | N/A | `base` | No density qualifier |
+| `anydpi` | N/A | `base` | No density qualifier |
+
+Note the deliberate mismatch: Android `hdpi` (~240) maps to HarmonyOS **`ldpi`** because HarmonyOS labels the (160, 240] range `ldpi`.
+
+### Language/Region Qualifiers
+
+| Android | HarmonyOS |
+|---|---|
+| `drawable-ar` | `ar/media/` |
+| `drawable-zh` | `zh/media/` |
+| `drawable-zh-rCN` | `zh_CN/media/` |
+| `drawable-zh-rTW` | `zh_TW/media/` |
+| `drawable-en-rUS` | `en_US/media/` |
+| `drawable-fr-rFR` | `fr_FR/media/` |
+
+Parsing: language = 2–3 lowercase letters (ISO 639); region = `r` + 2 uppercase letters, strip the `r`; script = `b+sr+Latn` → `sr_Latn`. Language and region join with `_`.
+
+### Orientation Qualifiers
+
+| Android | HarmonyOS |
+|---|---|
+| `land` | `horizontal` |
+| `port` | `vertical` |
+
+### Night Mode Qualifiers
+
+| Android | HarmonyOS |
+|---|---|
+| `night` | `dark` |
+| `notnight` | `light` |
+
+### Combining Multiple Qualifiers
+
+**Parsing algorithm for any Android drawable/mipmap directory name:**
+
+1. Split the directory name by `-`; the first segment is the resource type
+2. Parse remaining qualifiers left-to-right: language/region, density, orientation, night mode, API level (`v<N>`), screen-size constraints
+3. Map each recognized qualifier to its HarmonyOS equivalent
+4. **Strip silently** (do not reject): API level `v<N>`, layout direction (`ldrtl`/`ldltr`), screen shape (`round`/`notround`), HDR (`highdr`/`lowdr`), aspect (`long`/`notlong`)
+5. **Skip the entire directory** (mark all resources unmapped) when screen-size qualifiers remain: `sw<N>dp`, `w<N>dp`, `h<N>dp`, `small`, `normal`, `large`, `xlarge` — HarmonyOS has no equivalent; do NOT convert them to `base/`
+6. If no qualifiers remain after stripping, use `base/`
+7. Reassemble in HarmonyOS order: MCC_MNC-language_script_country/region-orientation-device-colormode-density
+
+**Examples:**
+
+| Android Directory | Qualifiers | HarmonyOS Target |
+|---|---|---|
+| `drawable-hdpi` | hdpi→ldpi | `ldpi/media/` |
+| `mipmap-anydpi-v26` | anydpi→base, v26 stripped | `base/media/` |
+| `drawable-zh-rCN-night-hdpi` | zh_CN, dark, ldpi | `zh_CN-dark-ldpi/media/` |
+| `drawable-night-v21` | dark, v21 stripped | `dark/media/` |
+| `drawable-hdpi-v4` | ldpi, v4 stripped | `ldpi/media/` |
+| `drawable-sw600dp` | **skip — unmapped** | N/A |
+
+Never reject a directory just because one qualifier is unsupported — strip it and continue.
+
+---
+
+## Reference Resolution for Images
+
+Image conversion encounters value references in three places. Build a lookup table from `values*/colors.xml` and `values*/dimens.xml` before converting drawables.
+
+**In converted SVG files:**
+- `@color/name` used as `fillColor`/`strokeColor` → resolve to the hex value during SVG generation (follow chains; fallback `#000000` + log)
+- `@dimen/name` used as a dimension → resolve to the numeric value (fallback: sensible default + log)
+- `@android:color/*` system colors → map known ones (`white`→`#FFFFFF`, `black`→`#000000`, `transparent`→`#00000000`); unknown → `#000000` + log
+
+**In layered-image JSON files:**
+- `@drawable/xxx` / `@mipmap/xxx` → keep as `$media:xxx` (file references — the files themselves are converted)
+- `@color/xxx` → resolve to hex and generate the solid-color PNG (see adaptive icon rules)
+
+**Reference chain depth**: follow at most 5 levels (`A → B → C → concrete value`). Unresolved references are expected — library resources are absent from source `res/`; record them in the report with likely library provenance (e.g. `@drawable/abc_*` → AndroidX AppCompat, `@drawable/mtrl_*`/`design_*` → Material Components) so the developer can supply them manually.
+
+---
+
+## Special Cases and Edge Cases
+
+- **Same name in multiple density directories** (`drawable-hdpi/x.png`, `drawable-xxhdpi/x.png`) → each copies to its own qualifier directory (`ldpi/media/x.png`, `xxldpi/media/x.png`) — no conflict.
+- **Same name from qualified and unqualified dirs** (`drawable/x.png` and `drawable-anydpi/x.xml` both → `base/media/`) → the source with fewer qualifiers wins; the loser is recorded as a collision.
+- **Existing files in the HarmonyOS project**: merge, do not overwrite — an existing media file with the same name keeps its position; the attempted copy is logged as a collision for the developer to review.
+- **Empty/corrupt image files**: skip and log; do not copy zero-byte files into `media/`.
+- **Filenames illegal in HarmonyOS** (`.` inside the name, leading digits are fine but uppercase is kept as-is): only the `.9.png` rename is automatic; any other illegal name is copied with a logged `unmappable` entry explaining the manual rename needed.
+- **Large image sets**: first inventory, then group by (classification × qualifier), then convert group by group, then verify — never convert while still scanning.