android2harmony 0.1.4 → 0.1.5

package/skills/a2h-resource-convert/SKILL.md

@@ -0,0 +1,902 @@
+---
+name: a2h-resource-convert
+description: Convert Android project resources to HarmonyOS project resources. Use this skill when the user wants to migrate, convert, or transfer resource files (strings, colors, dimensions, images, drawables, icons, etc.) from an Android project to a HarmonyOS project. Also trigger when the user mentions Android-to-HarmonyOS migration involving resource files, qualifier directories (like drawable-hdpi, values-zh), or resource format conversion (XML to JSON). Even partial mentions of "Android resources to HarmonyOS" or "migrate Android res" should trigger this skill.
+---
+
+# Android to HarmonyOS Resource Converter
+
+This skill converts resource files from an Android project into the resource format used by HarmonyOS projects. It decodes the APK supplied as `apk_path` with the `a2h-resource` npm package (a pure-Node.js resource decoder) to obtain the complete merged resource set, including all library dependencies. If decoding fails, it falls back to converting directly from the project's source `res/` directory — which may be missing library-provided resources, but still produces a useful conversion with clear reporting of what is missing and why. In addition to the standard conversion report, it also produces a dedicated Android resources ↔ HarmonyOS resources mapping markdown document at the user-provided `resource_mapping_path`.
+
+It also covers icons that a Jetpack Compose application draws from **code** rather than from `res/` (`androidx.compose.material:material-icons-*`). Those are compiled `ImageVector` objects that never appear in `res/` or `resources.arsc`, so every `res/`-based step below is blind to them; Step 4.1.3 recovers them from `classes*.dex` and synthesizes the matching HarmonyOS media assets.
+
+`apk_path` is decoded as given. `harmony_project_dir` is an initialized HarmonyOS project; converted resources are written into it.
+
+## Inputs
+
+Declare all inputs up front as explicit `snake_case` variables — do not rely on semantically guessing natural-language phrases:
+
+| Variable | Required | Meaning | Typical Phrases |
+|---|---|---|---|
+| `android_project_dir` | yes | Root directory of the Android project (contains `build.gradle` or `build.gradle.kts`) | "Android project path", "安卓项目", "source project" |
+| `harmony_project_dir` | yes | An **initialized** HarmonyOS project. Converted resources are written into it. | "HarmonyOS project path", "鸿蒙项目", "target project" |
+| `resource_mapping_path` | yes | Full output path of the markdown file that records the Android resource inventory and the Android ↔ HarmonyOS mapping details. Write this file in 中文. | "resource mapping path", "资源映射文档" |
+| `apk_path` | yes | Full path of the APK corresponding to `android_project_dir`. It is decoded as given in Step 3 and is the conversion source. | "APK path", "apk文件", "安卓apk" |
+| `material_icon_snapshot_dir` | no | Local copy of `google/material-design-icons`, for environments with no network access. Normally omitted: Step 4.1.3 fetches artwork from a pinned upstream commit. | "图标快照目录", "material icons snapshot" |
+
+If any required input cannot be determined from the invocation, ask the user — do not guess. `material_icon_snapshot_dir` is optional: never block on it.
+
+## Toolchain — mandatory
+
+**Do not write your own conversion scripts.** This skill ships a canonical implementation; use it.
+
+The reason is measured, not stylistic. When this skill was run across 10 applications with agents implementing the conversion themselves, each run produced its own converter — 10 implementations, 3 languages, ~10,000 lines of throwaway code, 3 of them pulling floating-version npm dependencies. The results were not comparable: `converted` counts meant different things per run (file-level in one, entry-level in another), mapping documents ranged from 266 rows to 120,750 for similar inputs, and defect classes appeared in some outputs but not others — 9 of 15 committed patches carried unrenderable `d="@string/…"` path data, one dropped whitespace that Android's quoting syntax deliberately preserves, another lost `clip-path` geometry. Every one of those is a rule stated in `references/`, implemented correctly by some runs and incorrectly by others.
+
+Run these four steps in order:
+
+```bash
+# 1. Resources: values, qualifiers, media, XML drawables, adaptive icons, reference resolution
+# <ui_module> below is the UI module resolved from build-profile.json5 (+ the project's
+# architecture doc). It is NOT always `entry` — layered projects use e.g. products/phone.
+node ./scripts/a2h_resource_convert.js \
+    --res <decoded_output_path>/res --harmony <harmony_project_dir> \
+    --ui-module <ui_module> \
+    --records <work_dir>/records.json
+
+# 2. Code-defined vector icons — REQUIRED for any Jetpack Compose app (see Step 4.1.3)
+#    --fetch pulls artwork from a pinned upstream commit, never a moving branch.
+#    Requires network access to raw.githubusercontent.com.
+#    Prefer a *minified* (release) APK's decoded dir. On a debug APK the icon library
+#    is unshrunk, so the dex lists the whole catalogue (~11k names for
+#    material-icons-extended) rather than what the app uses; the script refuses to
+#    fetch in that case and tells you to add --attributed-only.
+node ./scripts/code_vector_icons.js \
+    --dex <decoded_output_path> --android-src <android_project_dir> \
+    --out <harmony_project_dir>/<ui_module>/src/main/resources/base/media \
+    --fetch --json <work_dir>/icons.json
+
+# 3. Vector fidelity gate — any error blocks completion
+node ./scripts/svg_fidelity_check.js \
+    --android-res <decoded_output_path>/res \
+    --harmony-media <harmony_project_dir>/<ui_module>/src/main/resources/base/media \
+    --json <work_dir>/fidelity.json
+
+# 4. Documents, rebuilt from the records of step 1 plus the results of steps 2-3
+node ./scripts/a2h_resource_convert.js --docs-only \
+    --records <work_dir>/records.json \
+    --icons-json <work_dir>/icons.json --fidelity-json <work_dir>/fidelity.json \
+    --report <work_dir>/resource_conversion_report.md \
+    --mapping <resource_mapping_path> \
+    --apk <apk_path> --android-commit <commit> --app-module <app_module> \
+    --harmony <harmony_project_dir>
+```
+
+Step 4 is separate because the documents need the fidelity and icon results, which in turn need the artifacts step 1 produces. It re-reads `records.json` rather than re-running the conversion.
+
+**What remains your job:**
+
+- resolving the inputs, including the Step 2 application-module decision (the converter cannot make it when several modules apply `com.android.application` — ask the user);
+- reading the tool output and acting on it: a non-zero exit, any fidelity `error`, or any unresolved icon is a finding to address or report, never something to paper over;
+- writing the final Chinese summary for the caller.
+
+**What you must not do:** re-implement any rule from `references/` in an ad-hoc script, hand-edit generated resources to make a check pass, or create undocumented placeholder resources.
+
+The tables and rules in the rest of this document describe **what the converter implements**. Read them to review its output and to judge edge cases — not as a specification to code against yourself.
+
+## Workflow
+
+### Step 1: Validate Inputs
+
+1. **`apk_path`** — verify the file exists and is readable. If it is missing or unreadable, **stop and ask the user** for the correct path.
+
+2. **`android_project_dir`** — verify it exists and contains `build.gradle` or `build.gradle.kts`. The source `res/` fallback in Step 3 and the library-dependency correlation in Step 5 both read from it.
+
+The main resource target directory is `<harmony_project_dir>/<ui_module>/src/main/resources/`, where `<ui_module>` is resolved in Step 2 and passed to the scripts as `--ui-module`. It defaults to `entry` for single-module projects but is a multi-segment path in layered ones (e.g. `products/phone`) — never hardcode `entry`.
+
+### Step 2: Resolve the Application Module
+
+Resolve `<app_module>` — the module whose Gradle file applies the `com.android.application` plugin (grep `com.android.application` across `<android_project_dir>/*/build.gradle` and `*/build.gradle.kts`). It is **usually** `app/`, but do not assume that name: many projects use `mobile/`, `client/`, `androidApp/`, or a nested path. Store it relative to `<android_project_dir>` and use it everywhere below instead of a literal `app`. If several modules apply the plugin, ask the user which one corresponds to `apk_path`.
+
+`<app_module>` is used by the source `res/` fallback (Step 3 / Step 4) and by the library-dependency correlation in the report. Resolve it now so those steps do not have to re-derive it.
+
+Why the decoded APK is the preferred source: it carries all merged resources from application source **and** library dependencies (AARs, Maven artifacts). The source `res/` fallback is missing library resources, so some resource references become unresolvable. The conversion report flags this explicitly.
+
+### Step 3: Decode the APK's resources
+
+Decode `apk_path` into `<decoded_output_path>` with the `a2h-resource` decoder.
+
+First make sure the `a2h-resource` CLI is installed (published to npm). Install it once, globally:
+
+```bash
+npm install -g a2h-resource
+```
+
+Then run it directly:
+
+```bash
+a2h-resource <apk_path> -o <decoded_output_path>
+```
+
+Alternatively, if you prefer not to install globally, run it on-demand with `npx` (which fetches the package automatically):
+
+```bash
+npx --yes a2h-resource <apk_path> -o <decoded_output_path>
+```
+
+`a2h-resource` is a pure-Node.js resource decoder distributed as an npm package and requires only Node.js `>= 20`. It reads the APK's `resources.arsc` — the fully-merged resource table produced at build time — so its output at `<decoded_output_path>/res/` is the **complete merged resource set** (source + all library/AAR resources merged in at build time). It produces:
+
+- `<decoded_output_path>/AndroidManifest.xml` — decoded, id references resolved (`@id/…`, `@string/…`, `@android:…`).
+- `<decoded_output_path>/res/` — qualifier directories with **real resource names** and decoded content:
+  - `values*/`: `strings`, `colors`, `dimens`, `bools`, `integers`, `ids`, `<string-array>`/`<integer-array>`/`<array>`, `plurals` (plus `styles`/`attrs`, which this skill logs as unmappable).
+  - `drawable*/`, `mipmap*/`, `layout*/`, `menu/`, `xml/`, `color/`: binary XML decoded to text — `<vector>`, `<shape>`, `<selector>`, `<layer-list>`, `<adaptive-icon>`, layouts, menus — ready for the Step 4 conversions.
+  - `.9.png`: restored to **source form** (1-px border with stretch/padding markers).
+  - `raw/`, `font/`, and other file resources placed under their qualifier dirs.
+- passthrough directories (`assets/`, `lib/`, `classes.dex`, …) copied as-is.
+- `<decoded_output_path>/svg/` — VectorDrawables pre-converted to SVG. **This skill runs its own SVG conversion** per `references/xml-drawable-to-svg-rules.md`, so this directory is supplementary; ignore it and use the decoded XML under `res/drawable*/` as the conversion source.
+
+On success, set `resource_source = "decoded_apk"` and use `<decoded_output_path>/res/` as the conversion source.
+
+**If decoding fails** (the command errors out — e.g. a rare APK `a2h-resource` cannot parse, or a multi-package/split APK where only the first package is decoded): record the error, then fall back to the project's source `res/` directory at `<android_project_dir>/<app_module>/src/main/res/` (`<app_module>` from Step 2). Set `resource_source = "source_res"` and state in the report that decoding failed, so the developer knows library-merged resources may be missing.
+
+### Step 4: Convert Resources
+
+Conversion is performed by `scripts/a2h_resource_convert.js` (Toolchain step 1). It reads the resource source directory, converts every resource type described below, and records an inventory row and a mapping row for each one — including skips, fallbacks, and unmappable cases — into `records.json`.
+
+Read `references/conversion-rules.md` and `references/resource-mapping-rules.md` so you can **review** what it produced and reason about edge cases. Do not re-implement them.
+
+**Determining the source `res/` directory when the Step 3 decode fallback applies:**
+- Check `<android_project_dir>/<app_module>/src/main/res/` (`<app_module>` = the application module resolved in Step 2; do not hardcode `app`)
+- If multi-module, also check other module directories
+- If the project uses flavor source sets, include those too (e.g., `<app_module>/src/debug/res/`, `<app_module>/src/flavor/res/`)
+
+#### 4.1 Resource Type Mapping
+
+| Android Resource Dir | HarmonyOS Target | Notes |
+|---|---|---|
+| `drawable/` (images: png, jpg, webp, gif) | `base/media/` | Direct file copy |
+| `drawable/` (nine-patch: `*.9.png`) | `base/media/` as `*_9.png` | Rename `.9.png` → `_9.png`; HarmonyOS does not allow `.` in resource filenames except for the final extension separator. Nine-patch stretching behavior is lost — log in report. |
+| `drawable/` (Android vector drawables: `<vector>`) | `base/media/` as `.svg` | Convert VectorDrawable XML to SVG format |
+| `drawable/` (shape drawables: `<shape>`) | `base/media/` as `.svg` | Convert shape XML to SVG |
+| `drawable/` (layer-list drawables: `<layer-list>`) | `base/media/` as `.svg` | Convert layered drawable to SVG with nested elements |
+| `drawable/` (selector/state-list drawables) | `base/media/` (default state as `.svg`) | Extract default state item and convert to SVG; log state variants in report |
+| `drawable/` (ripple, animated-vector, transition) | No direct equivalent | Log as unmappable; note in report |
+| `mipmap/` (PNG/WEBP images) | `base/media/` | App launcher icons — direct copy; rename `.9.png` → `_9.png` if nine-patch |
+| `mipmap/` (adaptive-icon XML: `<adaptive-icon>`) | `base/media/` as `xxx_layered_image.json` | Convert to layered-image JSON (see below) |
+| `mipmap/` (vector XML: `<vector>`) | `base/media/` as `.svg` | Convert VectorDrawable to SVG |
+| `values/strings.xml` | `base/element/string.json` | XML → JSON conversion |
+| `values/colors.xml` | `base/element/color.json` | XML → JSON; fix color format |
+| `values/dimens.xml` | `base/element/float.json` | XML → JSON; convert units |
+| `values/integers.xml` | `base/element/integer.json` | XML → JSON |
+| `values/bools.xml` | `base/element/boolean.json` | XML → JSON |
+| `values/arrays.xml` (string-array) | `base/element/strarray.json` | XML → JSON |
+| `values/arrays.xml` (integer-array) | `base/element/intarray.json` | XML → JSON |
+| `values/plurals.xml` | `base/element/plural.json` | XML → JSON |
+| `values/styles.xml` | No direct equivalent | Log in report |
+| `values/attrs.xml` | No direct equivalent | Log in report |
+| `raw/` (non-Lottie) | `rawfile/` | Direct file copy |
+| `raw/` (Lottie JSON: `v`+`fr`+`ip`+`op`+`layers` signature) | `rawfile/lottie/<normalized>.json` | Identify by JSON structure signature; normalize filename to lowercase `[a-z0-9_]`. See `references/lottie-conversion-rules.md`. |
+| `assets/` (Lottie JSON: `v`+`fr`+`ip`+`op`+`layers` signature) | `rawfile/lottie/<normalized>.json` | Same identification and normalization rules as `raw/` Lottie. `assets/` is a passthrough dir in APK decoding — scan `<decoded_output_path>/assets/` recursively. |
+| `assets/` (non-Lottie files) | Passthrough | Not part of this skill's default conversion scope — reserved for future rules. Record inventory rows with `mapping_kind = unmappable`. |
+| `font/` | `rawfile/fonts/` | Copy fonts to rawfile |
+| `xml/` | `base/profile/` | Only config-like XML; rename to .json if possible |
+| `anim/`, `animator/` | No direct equivalent | Log in report |
+| `layout/` | No direct equivalent | ArkUI uses declarative UI; log in report |
+| `menu/` | No direct equivalent | Log in report |
+| `color/` (color state lists) | No direct equivalent | Log in report |
+
+#### 4.1.1 Adaptive Icon → Layered-Image JSON Conversion
+
+Android adaptive-icon XML files (root element `<adaptive-icon>`, commonly found in `mipmap-anydpi-v26/`) are converted to HarmonyOS layered-image JSON files.
+
+**Conversion rules:**
+1. Parse the `<adaptive-icon>` 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 has no layered-image equivalent. However, the resource *referenced* by `monochrome` (e.g., `@drawable/ic_launcher_monochrome`) is a real asset that should still be converted as a normal drawable.
+3. Convert Android resource references to HarmonyOS format:
+   - `@drawable/xxx` → `$media:xxx`
+   - `@mipmap/xxx` → `$media:xxx`
+   - `@color/xxx` → **generate a solid color PNG** (see rule 4 below)
+4. **Critical — color background handling**: HarmonyOS `layered-image` only accepts `$media:xxx` references. It does NOT support `$color:xxx`. When the `background` (or `foreground`) references a color (`@color/xxx`):
+   a. Look up the **resolved hex value** of `@color/xxx` from the resource source's `res/values*/colors.xml`. Follow reference chains if the color itself references another color — keep resolving until you reach a concrete hex value.
+   b. Generate a solid-color PNG filled entirely with that hex color. A minimal valid PNG of any small size (e.g., 1×1 or 108×108 pixels) is sufficient.
+   c. Name the PNG `<color_name>_bg.png` (e.g., `md_orange_700_bg.png`) and place it in `base/media/`.
+   d. Reference it as `$media:<color_name>_bg` in the layered-image JSON.
+   e. **If the color cannot be resolved** (e.g., it comes from a library and we're using source `res/`), log it as an unsatisfied dependency in the report and use a placeholder reference.
+5. **Critical — inline layer content**: a layer can carry its artwork as a *child element* instead of an `android:drawable` reference (`<foreground><vector …/></foreground>`, common for shortcut icons). 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 layered-image JSON with the layer simply absent: the icon then renders with no artwork, and no existence check catches it because the JSON is present and valid. A `<bitmap android:src="@drawable/x"/>` wrapper is just a reference — point at `$media:x`. An inline drawable with no static SVG equivalent becomes an `unmappable` mapping row with the reason stated.
+6. Output filename: `<original_name>_layered_image.json` (e.g., `ic_launcher.xml` → `ic_launcher_layered_image.json`)
+7. Store in the target `media/` directory (typically `base/media/`)
+
+**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` (a solid `#F57C00` filled PNG). Then convert to `base/media/ic_launcher_layered_image.json`:
+```json
+{
+  "layered-image": {
+    "background": "$media:md_orange_700_bg",
+    "foreground": "$media:ic_launcher_foreground"
+  }
+}
+```
+
+#### 4.1.2 Lottie Animation JSON Migration
+
+Android projects that use `com.airbnb.android:lottie` ship their animations as JSON in `assets/` or `res/raw/`. On HarmonyOS these are consumed by `@ohos/lottie` (installed with `ohpm install @ohos/lottie`) which loads them from `rawfile/` at runtime. This skill migrates the JSON asset and records the host-screen binding — it does NOT generate ArkTS code.
+
+**Identification (always required — do not rely on `.json` extension):**
+
+A file is a Lottie animation JSON if its parsed root object contains ALL of these fields: `v`, `fr`, `ip`, `op`, `w`, `h`, and `layers` (array). Non-Lottie JSON in `raw/` continues to follow the normal raw-file rule.
+
+**Sources scanned:**
+
+- `<decoded_output_path>/assets/` (recursive) — assets is a passthrough directory in APK decoding
+- `<decoded_output_path>/res/raw/`
+- Source-fallback equivalents: every module's `src/*/assets/` and `src/*/res/raw/`, including flavor source sets
+
+**Target:**
+
+`<ui_module>/src/main/resources/rawfile/lottie/<normalized>.json`. The load path recorded for the developer (used later as `lottie.loadAnimation({ path: ... })`) is `lottie/<normalized>.json`, relative to `rawfile/`, no leading slash.
+
+**Filename normalization:** lowercase; replace `[^a-z0-9_]` in the base name with `_`; collapse consecutive `_`; trim leading/trailing `_`; if starts with a digit, prefix `lottie_`. Examples:
+
+| Original | Normalized |
+|---|---|
+| `AndroidWave.json` | `androidwave.json` |
+| `Lottie Logo 1.json` | `lottie_logo_1.json` |
+| `HamburgerArrow.json` | `hamburgerarrow.json` |
+| `01-intro.json` | `lottie_01_intro.json` |
+
+**Filename collision:** if `assets/logo.json` and `res/raw/logo.json` both target `lottie/logo.json`, disambiguate as `lottie/assets_logo.json` and `lottie/raw_logo.json`. Record both in `notes`.
+
+**Reference extraction (in addition to the generic `@type/name` scan of `references/dependency-analysis-rules.md`):**
+
+XML attribute patterns (namespace-agnostic — match by local name):
+
+| Attribute | Points at | Migration action |
+|---|---|---|
+| `lottie_fileName="Xxx.json"` | `assets/Xxx.json` | Migrate the JSON. Attribute the JSON to the Activity/Fragment inflating the layout XML. |
+| `lottie_rawRes="@raw/name"` | `res/raw/name.json` | Same. |
+| `lottie_url="https://..."` | Runtime URL | No local file — record with `mapping_kind = remote resource (no local target)` and `source_category = 运行时远程资源`. |
+| `lottie_fallbackRes="@drawable/xxx"` | Fallback drawable | Not a Lottie asset; use the normal drawable rules, but link it to the Lottie row in `notes`. |
+
+Code patterns (grep across `.kt` / `.java`):
+
+- Literal string arg to `LottieCompositionFactory.fromAsset(...)` / `.fromRawRes(...)` / `.fromJsonInputStream(...)` / `.fromUrl(...)` or `LottieAnimationView.setAnimation(...)`.
+- `AssetManager.list(...)` results filtered by `.json` and dispatched to a factory method — this is the "dynamic picker" pattern. In this case attribute every listed JSON to the **detail screen** that the picker's click handler navigates to (via `startActivity`), not the picker itself. (See the airbnb `lottie-android` sample: `PreviewFragment` picker → `PlayerActivity` detail.)
+- Data classes carrying `assetName` / `fileUri` / `url` consumed by a factory method — chase to the actual factory call site to classify local vs remote.
+
+**Host-screen binding (required for every Lottie row):**
+
+Attribute the JSON to the Activity/Fragment that plays it. Evidence sources, in priority order:
+
+1. XML host layout → the Activity/Fragment that inflates it (`setContentView(R.layout.<name>)`, `AppCompatActivity(R.layout.<name>)` constructor form, `Fragment(R.layout.<name>)`, ViewBinding/DataBinding class name derived from the layout).
+2. Code-loaded (literal): the enclosing class. If it is a ViewModel/repository, walk one hop up to its observing Fragment/Activity.
+3. Code-loaded (dynamic picker): the navigation target of the picker's click handler, not the picker itself.
+4. Manifest / Application / splash: `Global` or `Launcher`.
+5. No evidence: `Unknown` (explain in notes).
+
+Then propose a HarmonyOS page name: strip the `Activity` / `Fragment` suffix and append `Page` (e.g., `PlayerActivity` → `PlayerPage`). Collapse Activity+Fragment pairs of the same screen to one page. `Launcher` → `EntryAbility`, `Global` → `App`, `Unknown` → `Unknown`. Mark this as a suggestion in notes: "HarmonyOS page name inferred from Android host; verify against actual ArkUI pages".
+
+**Embedded image assets in a Lottie JSON:** if the JSON declares an `images` array pointing at external files, copy each referenced image to `rawfile/lottie/images/<relative_path>` preserving the JSON's `imagePath` layout, and record each image as its own inventory + mapping row.
+
+**Read `references/lottie-conversion-rules.md` for the full, detailed rules** (identification thresholds, edge cases like dead assets and invalid JSON, mapping-record schema).
+
+#### 4.1.3 Code-Defined Vector Icons (Jetpack Compose)
+
+Jetpack Compose applications take most of their iconography from `androidx.compose.material:material-icons-core` / `-extended`. Those icons are Kotlin-generated `ImageVector` objects compiled into `classes*.dex`. They are **not** in `res/drawable*/` and **not** in `resources.arsc`, so they are absent from the decoded `res/` tree that every other step of this skill reads.
+
+This blind spot fails silently and must be handled explicitly: Step 5.3's layout/menu scan finds nothing (a Compose app has no layout XML) and Step 6.8's `$r('app.media.…')` cross-check finds nothing (the HarmonyOS shell has no such references yet), so both gates report success while the migrated page renders no icons at all. On a real Compose app, 9 of the 10 icons on one screen were code-defined and produced no output and no warning.
+
+**Run this analysis when any of these hold** — otherwise record `Code-defined vector icons: none detected` and skip:
+- `build.gradle` / `build.gradle.kts` / `gradle/libs.versions.toml` declares `material-icons-core` or `material-icons-extended`
+- any `.kt` file imports `androidx.compose.material.icons.`
+- `classes*.dex` contains icon name strings (the checker below detects this on its own)
+
+Three questions need three different sources — do not try to answer them all from one place:
+
+| Question | Source | Needs `android_project_dir`? |
+|---|---|---|
+| **Which** icons the app uses | `classes*.dex` string pool | No |
+| **What** each looks like | Pinned upstream Material Icons snapshot | No |
+| **Where** each is used (screen attribution) | Android source `.kt` files | **Yes** |
+
+The dex is authoritative for scope — it includes icons used by library code and excludes icons R8 removed as dead code — but it cannot give attribution, because R8 obfuscates the icon package and leaves only a flat, sorted string pool. Attribution comes from the one readable line in the Kotlin source (`icon = Icons.Outlined.GetApp`). `android_project_dir` is already a required input, so this adds no new dependency.
+
+Run the bundled helper:
+
+```
+node ./scripts/code_vector_icons.js --dex <decoded_output_path> \
+    --android-src <android_project_dir> \
+    --out <harmony_project_dir>/<ui_module>/src/main/resources/base/media \
+    --snapshot <material_icon_snapshot_dir> \
+    --json <harmony_project_dir>/code_vector_icons.json
+```
+
+**`--android-src` is required, not decorative, and a debug APK needs `--attributed-only`.** The dex string pool is a *superset* of what the app uses: it contains whatever the icon library shipped. R8 narrows it to the real set, but `isMinifyEnabled` is typically only on for `release`, so a debug APK's dex lists the entire catalogue. `--android-src` is what lets the script attribute names to actual source references and tell the two apart; without `--attributed-only` on an unshrunk dex it would fetch and write every catalogue entry (thousands of files, tens of minutes, and a polluted `base/media` that must then be cleaned by hand). The script detects this and refuses to fetch, naming the two ways out.
+
+`--fetch` is the normal mode: it pulls artwork from a pinned upstream commit — never a moving branch — and therefore needs network access to `raw.githubusercontent.com`. Use `--snapshot <dir>` instead only on network-isolated machines. Exit code 1 means some references could not be resolved; those MUST be recorded as `unmappable` rows, never dropped.
+
+Targets are named `base/media/ic_<material_name>_<style>.svg`. The style suffix is mandatory: in the classic Material Icons set `Outlined.X` is sometimes different artwork from `Filled.X` (`bookmark`) and sometimes byte-identical (`favorite`), so naming by bare `ic_<name>.svg` silently drops one of the pair. `AutoMirrored` is **not** part of the filename — HarmonyOS qualifier directories have no right-to-left dimension, so mirroring is handled at the ArkUI component level and recorded in `notes`.
+
+**Read `references/code-vector-icon-rules.md` for the full rules** (extraction patterns, the exact name transform, the `symbols`-category trap in the upstream index, SVG post-processing, collision handling with `res/`-derived media, and the fallback table for unresolvable or app-defined `ImageVector`s).
+
+#### 4.2 Qualifier Directory Mapping
+
+Android uses qualifiers as directory suffixes (e.g., `drawable-hdpi`, `values-ar`). HarmonyOS uses a different qualifier directory naming convention. Convert as follows:
+
+**Screen density mapping** (Android DPI names differ from HarmonyOS):
+
+| Android Qualifier | Android DPI | HarmonyOS Qualifier | HarmonyOS DPI Range |
+|---|---|---|---|
+| `ldpi` | ~120 | `sdpi` | (0, 120] |
+| `mdpi` | ~160 | `mdpi` | (120, 160] |
+| `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; use base |
+| `anydpi` | N/A | `base` | No density qualifier; use base |
+
+**Language/region mapping**:
+- `values-ar` → `ar/element/`
+- `values-zh-rCN` or `values-zh` → `zh_CN/element/` or `zh/element/`
+- `values-en-rUS` → `en_US/element/`
+- `drawable-ar` → `ar/media/`
+
+The pattern: strip the base type prefix (e.g., `values-`, `drawable-`), convert the qualifier to HarmonyOS format, then place resources under the appropriate resource group directory (`element/`, `media/`, or `profile/`).
+
+**Multi-qualifier directories**: Android directories can combine multiple qualifiers with hyphens (e.g., `mipmap-anydpi-v26`, `drawable-night-v21`). Parse ALL qualifiers individually, map each one, strip unsupported ones, and use whatever valid qualifiers remain. Never reject a directory just because one of its qualifiers is unsupported — strip it and keep going. If all qualifiers are stripped, use `base/`.
+
+**Qualifiers to strip** (only these are silently removed):
+- API level `v<N>` (e.g., `v26`, `v21`)
+
+**Qualifiers without a HarmonyOS equivalent** (skip entirely):
+- Smallest width `sw<N>dp` (e.g., `sw600dp`)
+- Available width `w<N>dp` (e.g., `w480dp`)
+- Available height `h<N>dp`
+- Screen size (`small`, `normal`, `large`, `xlarge`)
+
+These qualifiers have no HarmonyOS mapping. When a directory's only remaining qualifiers (after stripping API level etc.) are from this list, **skip all resources in that directory** and mark them as "unmapped" in the conversion report with reason "Unsupported qualifier: no HarmonyOS equivalent". Do NOT convert them to `base/` or preserve the qualifier as-is — skipping ensures correct conversion output.
+
+**Common example**: `mipmap-anydpi-v26` → qualifiers: `anydpi` (→ `base`) + `v26` (→ strip) → target: `base/media/`. The files inside (typically `<adaptive-icon>` XML) should be processed normally by reading their XML content to determine the type — adaptive-icon XML gets converted to layered-image JSON.
+
+**HarmonyOS qualifier directory naming rules**:
+- Language and region are joined by underscore: `zh_CN`, `en_US`
+- Multiple qualifier types are separated by hyphens: `zh_CN-dark-ldpi`
+- Order: MCC_MNC-language_script_country/region-orientation-device-colormode-density
+
+**Orientation mapping**:
+- `land` → `horizontal`
+- `port` → `vertical`
+
+**Night mode mapping**:
+- `night` → `dark`
+- `notnight` → `light`
+
+**Handling values with non-mappable qualifiers** (e.g., `values-sw600dp`, `values-w480dp`, `values-w600dp`):
+These directories contain value resources qualified by screen-size constraints that HarmonyOS does not support. **Skip all resources in these directories** and mark them as "unmapped" in the conversion report with reason "Unsupported qualifier: `sw600dp` / `w480dp` / etc. — no HarmonyOS equivalent". Do NOT convert them to `base/element/` or preserve the qualifier as-is.
+
+#### 4.2.1 Record Resource Mapping Metadata
+
+As each Android resource is processed, maintain two parallel data sets for the final mapping document:
+
+1. **Android resource inventory records** — one record per Android resource item
+2. **Android ↔ HarmonyOS mapping records** — one record per conversion or non-conversion outcome
+
+Use the rules in `references/resource-mapping-rules.md`.
+
+**Minimum fields for each Android resource inventory record:**
+- Android resource path
+- Android resource name
+- Function description
+- Screen(s)
+- Source category
+- Type category
+- Status
+- Notes / evidence
+
+**Minimum fields for each mapping record:**
+- Android resource path
+- Android screen(s)
+- Android source category
+- Android type category
+- HarmonyOS target path (or `N/A`)
+- Mapping kind
+- Notes
+
+**Recording granularity:**
+- File resources (`drawable`, `mipmap`, `xml`, `font`, `raw`) → record at file level
+- `values/*.xml` resources → record at entry level using `file_path#tag/name` notation, e.g. `app/src/main/res/values/strings.xml#string/app_name`
+- One-to-many conversions (for example adaptive icon XML producing layered-image JSON plus generated PNG assets) → record each target as its own mapping row
+- Many-to-one conversions (for example multiple Android value entries ending up in one HarmonyOS JSON file) → still record each Android source entry separately
+- Unmappable resources, system resources, third-party-library-only resources, and runtime remote resources must also be recorded; never silently omit them from the mapping metadata
+#### 4.3 Value Format Conversions
+
+When converting `values/*.xml` to HarmonyOS JSON format:
+
+**Colors**:
+- Android `#RRGGBB` → HarmonyOS `#ffRRGGBB` (prepend `ff` for full opacity)
+- Android `#AARRGGBB` → HarmonyOS `#AARRGGBB` (already in correct format, HarmonyOS uses same order)
+- Android `#RGB` → expand to `#ffRRGGBB`
+- Android `#ARGB` → expand to `#AARRGGBB`
+
+**Dimensions** (for `dimens.xml` → `float.json`):
+- `dp` → `vp` (virtual pixels, similar concept)
+- `sp` → `fp` (font pixels)
+- `px` → keep as `px`
+- Plain numbers → append `vp`
+
+**Strings**:
+- XML entities (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&apos;`) → decoded characters
+- `\n`, `\t` → preserved
+- CDATA sections → extract text content
+- String format placeholders (`%1$s`, `%2$d`) → preserved (HarmonyOS uses same format)
+
+**Booleans**:
+- `"true"` / `"false"` → `true` / `false` (as JSON booleans)
+
+**Integers**:
+- Integer values from `integers.xml` MUST be stored as JSON number type, NOT as JSON strings
+- `<integer name="max_lines">3</integer>` → `{"name": "max_lines", "value": 3}` (JSON number `3`, NOT string `"3"`)
+- Integer-array item values must also be JSON numbers: `{"value": 100}` not `{"value": "100"}`
+- If the source value contains non-numeric content (e.g., a resource reference), resolve the reference first, then convert the resolved value to a JSON number
+- If a value cannot be parsed as a number after resolution, log a warning and use `0` as a fallback
+
+**Plurals**:
+- Android quantities: `zero`, `one`, `two`, `few`, `many`, `other`
+- HarmonyOS quantities: `zero`, `one`, `two`, `few`, `many`, `other` (same set)
+
+### Step 5: Analyze and Resolve Resource Dependencies
+
+Android resources often reference other resources using `@type/name` syntax (e.g., `@color/primary`, `@drawable/icon`). Dependency analysis runs regardless of whether resources came from a decoded APK or source `res/` — the difference is that source-based conversion may have more unresolvable references because library resources are absent.
+
+Read `references/dependency-analysis-rules.md` for the complete dependency extraction patterns. Also use `references/resource-mapping-rules.md` during this step to infer resource function, screen ownership, source category, and type category for the mapping document.
+
+For Lottie references (`lottie_fileName`, `lottie_rawRes`, `lottie_url`, and factory-method calls in Kotlin/Java code), follow the additional extraction and host-screen-binding rules in `references/lottie-conversion-rules.md`. Each detected Lottie asset must be attributed to the Activity/Fragment that plays it and paired with a suggested HarmonyOS page name; these facts are consumed by the report and mapping document in Step 7 and Step 8.
+
+Dependency analysis here is `@type/name`-based and therefore covers only resources that exist in `res/`. It does **not** see the code-defined Compose icons handled in Step 4.1.3 — their references live in compiled code, not in XML. Carry the inventory produced by `scripts/code_vector_icons.js` forward into Step 6, Step 7, and Step 8 alongside the `res/`-derived records; do not expect this step to rediscover them.
+
+#### 5.1 Build a Resource Value Lookup Table
+
+Before resolving references, build a complete lookup table from whichever resource source is being used. This table maps every resource name to its concrete value:
+
+- **Value resources** (`colors.xml`, `dimens.xml`, `strings.xml`, etc.): parse all `values*/*.xml` files and build `type → name → value` mappings across all qualifier directories
+- **File resources** (`drawable/`, `mipmap/`): record `type → name → file_path` for each image or XML drawable
+- **Mapping support metadata**: build and maintain side tables for Android screen candidates, resource usage sites, module ownership, and likely library provenance so these can be attached to inventory and mapping rows later
+
+When working from source `res/`, this table will be **incomplete** — it won't contain resources defined in library dependencies. That's expected. The dependency analysis in Step 5.3 will identify these gaps.
+
+#### 5.2 Resolve References to True Values
+
+Scan all converted HarmonyOS resource files and replace resource references with their resolved concrete values:
+
+**In element JSON files** (`color.json`, `float.json`, `string.json`, etc.):
+- If a value field contains a HarmonyOS reference like `$color:name`, `$float:name`, `$string:name`, etc., look up the referenced resource in the lookup table
+- Replace the reference with the actual resolved value
+- Follow reference chains (resource A → resource B → concrete value) up to 5 levels deep to handle transitive references
+- If a reference cannot be resolved (e.g., it points to a library resource not in source `res/`, or to a theme attribute `?attr/name`), keep the reference as-is and log it in the report
+
+**Android system resource references** (`@android:color/*`, `@android:dimen/*`, `@android:string/*`, `@android:integer/*`):
+
+These reference Android framework built-in resources that do NOT exist in HarmonyOS. They MUST be resolved to concrete values — never leave `@android:` references in the output. Use the following built-in lookup table for `@android:color/*`:
+
+| Android System Color | Hex Value |
+|---|---|
+| `@android:color/white` | `#ffffffff` |
+| `@android:color/black` | `#ff000000` |
+| `@android:color/transparent` | `#00000000` |
+| `@android:color/background_dark` | `#ff000000` |
+| `@android:color/background_light` | `#ffffffff` |
+| `@android:color/darker_gray` | `#ffaaaaaa` |
+| `@android:color/holo_blue_bright` | `#ff00ddff` |
+| `@android:color/holo_blue_dark` | `#ff0099cc` |
+| `@android:color/holo_blue_light` | `#ff33b5e5` |
+| `@android:color/holo_green_dark` | `#ff669900` |
+| `@android:color/holo_green_light` | `#ff99cc00` |
+| `@android:color/holo_orange_dark` | `#ffff8800` |
+| `@android:color/holo_orange_light` | `#ffffbb33` |
+| `@android:color/holo_purple` | `#ffaa66cc` |
+| `@android:color/holo_red_dark` | `#ffcc0000` |
+| `@android:color/holo_red_light` | `#ffff4444` |
+| `@android:color/primary_text_dark` | `#ffffffff` |
+| `@android:color/primary_text_light` | `#de000000` |
+| `@android:color/secondary_text_dark` | `#b3ffffff` |
+| `@android:color/secondary_text_light` | `#8a000000` |
+| `@android:color/tab_indicator_text` | `#ff808080` |
+| `@android:color/tertiary_text_dark` | `#80ffffff` |
+| `@android:color/tertiary_text_light` | `#54000000` |
+| `@android:color/widget_edittext_dark` | `#ff000000` |
+
+For `@android:color/*` values not in this table: if converting from a decoded APK, look up the color in the decoded framework resources (`res/values/colors.xml` from the APK). Otherwise, log a warning and use `#ff000000` (black) as a safe fallback.
+
+For `@android:dimen/*` system dimensions: use the following common values:
+
+| Android System Dimen | Value |
+|---|---|
+| `@android:dimen/app_icon_size` | `48vp` |
+| `@android:dimen/thumbnail_width` | `96vp` |
+| `@android:dimen/thumbnail_height` | `96vp` |
+| `@android:dimen/dialog_min_width_major` | `65%` |
+| `@android:dimen/dialog_min_width_minor` | `95%` |
+| `@android:dimen/notification_large_icon_width` | `64vp` |
+| `@android:dimen/notification_large_icon_height` | `64vp` |
+
+For any other `@android:type/*` not covered by the tables above, log a warning in the report and substitute a reasonable default value for the type (colors → `#ff000000`, dimens → `0vp`, integers → `0`, strings → `""`).
+
+**Example — system color resolution:**
+```json
+// Before resolution:
+{"name": "bg_default", "value": "@android:color/white"}
+
+// After resolution:
+{"name": "bg_default", "value": "#ffffffff"}
+```
+
+**Example — color reference resolution:**
+```json
+// Before resolution:
+{"name": "primary_light", "value": "$color:primary"}
+
+// After resolution (primary resolves to #ff6200EE):
+{"name": "primary_light", "value": "#ff6200EE"}
+```
+
+**Example — dimension reference resolution:**
+```json
+// Before resolution:
+{"name": "margin_double", "value": "$float:margin_base"}
+
+// After resolution (margin_base resolves to "16vp"):
+{"name": "margin_double", "value": "16vp"}
+```
+
+**In SVG files** (converted XML drawables):
+- If a fill or stroke color was a resource reference, resolve it to the actual hex color during SVG generation
+- If a dimension was a resource reference, resolve it to the actual numeric value
+
+**In layered-image JSON files**:
+- `@drawable/xxx` and `@mipmap/xxx` references → keep as `$media:xxx` (these are file references, not value references — the files themselves are converted)
+- `@color/xxx` references → resolve to hex and generate solid-color PNG (as described in section 4.1.1)
+
+**Fallback strategy for unresolvable references in element JSON files:**
+
+After completing the reference resolution pass, scan all element JSON files for any remaining unresolved `$type:xxx` references. These MUST be replaced with concrete fallback values — leaving unresolved references in the output will cause HarmonyOS compilation errors.
+
+- When the resource source is a **decoded APK** (which contains the complete merged resource set), unresolved references indicate a bug in the resolution logic. Still apply fallbacks, but log prominently as errors.
+- When the resource source is **source `res/`**, unresolved references are expected for library resources. Apply fallbacks and log as warnings.
+
+**Fallback values by type:**
+
+| Reference Type | Fallback Value | Notes |
+|---|---|---|
+| `$color:xxx` | `#ff000000` (black) | Safe default for any missing color |
+| `$float:xxx` | `0vp` | Zero-dimension fallback |
+| `$string:xxx` | `""` (empty string) | Empty string fallback |
+| `$integer:xxx` | `0` | Zero integer fallback |
+| `$boolean:xxx` | `false` | False boolean fallback |
+
+**Resolution for cross-file references:**
+- When building the lookup table (Step 5.1), ensure ALL qualifier directories are scanned, not just `base/`. Color references may chain across qualifier variants (e.g., `base/` defines `primary`, `dark/` overrides it). Use the `base/` variant as the canonical value for resolution.
+- When a reference exists in a non-base qualifier but not in `base/`, include it in the lookup table with its qualifier noted.
+
+**Example — fallback applied:**
+```json
+// Before fallback (unresolvable library color):
+{"name": "design_fab_stroke_top_outer_color", "value": "$color:design_fab_stroke_top_outer_color"}
+
+// After fallback:
+{"name": "design_fab_stroke_top_outer_color", "value": "#ff000000"}
+// Report logs: "WARNING: Unresolved $color:design_fab_stroke_top_outer_color — replaced with fallback #ff000000. Likely source: com.google.android.material:material"
+```
+
+#### 5.3 Verify All Dependencies Are Satisfied
+
+After resolution, scan all converted resources for any remaining unresolved references:
+
+1. **Converted resource dependencies**: check that every `$media:xxx`, `$color:xxx`, `$float:xxx`, etc. reference in converted files points to an existing resource in the HarmonyOS output
+2. **Layout and menu file dependencies**: scan all `layout*/` and `menu/` files from the resource source for `@type/name` references. Even though layouts and menus won't be migrated as-is (ArkUI uses declarative UI), the resources they reference — strings, colors, drawables, dimensions — must exist in the converted output so the developer has everything needed when rebuilding the UI
+3. Mark each dependency as **satisfied** or **unsatisfied**
+4. **When using source `res/`**: unsatisfied dependencies are expected — they likely come from library resources. Parse `build.gradle` / `build.gradle.kts` to identify declared library dependencies (e.g., AndroidX, Material Components, third-party libraries). In the report, correlate unsatisfied references with likely library sources where possible (e.g., `@color/material_xxx` likely comes from Material Components library)
+5. Use the dependency graph and reference locations to infer screen ownership for resources whenever possible. If a resource is referenced from multiple screens, record all of them or mark it `Common`; if it is app-wide (launcher icon, theme resource, app name), mark it `Global` or `Launcher` as appropriate.
+
+### Step 6: Verify Completeness
+
+Items 1-9 and 11 below are performed by `scripts/a2h_resource_convert.js` and reported in `records.json`; items 10 and 12 are the two separate gates (`svg_fidelity_check.js` and `code_vector_icons.js`). Your job is to confirm each one actually ran and to act on what it found — a gate whose output nobody read is not a gate.
+
+The checks are:
+
+1. Build a list of all resource files found in the resource source directory
+2. For each, check if it was converted or marked as unmappable
+3. For converted resources, verify the target file exists in the HarmonyOS project
+4. For `values/*.xml` entries, verify each individual resource entry (string, color, dimen, etc.) appears in the corresponding JSON file
+5. Flag any resources that were missed
+6. Verify all dependencies from converted resources are satisfied (all references resolved to true values)
+7. Verify all dependencies from layout and menu files are satisfied — any missing resources should appear in the Unsatisfied Dependencies section of the report
+8. **Cross-validate with existing HarmonyOS UI code**: If `harmony_project_dir` already contains `.ets` source files (i.e., it's an existing project with UI code already converted), scan ALL `.ets` files for `$r('app.media.xxx')` resource references and cross-check against the converted `media/` resources:
+   a. For each `$r('app.media.xxx')` reference found in `.ets` files, verify that a corresponding file `xxx.*` (any extension: .png, .svg, .jpg, etc.) exists in the output `resources/base/media/` directory
+   b. For any referenced but missing media resource, **create a placeholder SVG** file: a simple 24x24 SVG with a colored rectangle and the resource name as text, placed in `base/media/`. This ensures the project compiles.
+   c. Log all placeholder-created resources prominently in the conversion report under a dedicated "Placeholder Resources Created" section, so the developer knows these need to be replaced with real assets
+   d. Also scan for `$r('app.string.xxx')`, `$r('app.color.xxx')`, `$r('app.float.xxx')` references and verify those exist in the corresponding element JSON files
+   e. For any `lottie.loadAnimation({ path: 'lottie/xxx.json' })` (or equivalent `@ohos/lottie` call) found in `.ets` files, verify that `xxx.json` exists at `rawfile/lottie/xxx.json`. If missing, do NOT create a placeholder — Lottie animations have no meaningful placeholder — instead log it as an unresolved Lottie reference in the report so the developer can drop in the correct JSON or fix the path.
+9. Before finishing verification, ensure every Android resource inventory row and every mapping row has the required metadata fields from `references/resource-mapping-rules.md`. If some fields cannot be proven, populate them with the rule-defined fallback labels (`Unknown`, `Common`, `Global`, `N/A`) rather than leaving them blank.
+10. **Vector content fidelity (static, required)**: steps 1-9 above all check *existence* — that a file or key is present. **A file that exists and parses can still be visually wrong**, and existence checks cannot detect a dropped `clip-path` or a `fill` injected onto a stroke-only path. Run the bundled checker:
+
+    ```
+    node ./scripts/svg_fidelity_check.js --android-res <resource_source_res_dir> \
+        --harmony-media <harmony_project_dir>/<ui_module>/src/main/resources/base/media \
+        --json <harmony_project_dir>/svg_fidelity.json
+    ```
+
+    It statically compares each Android `<vector>` against its converted `.svg` and reports `CLIP_PATH_LOST`, `FILL_INJECTED`, `FILL_LOST`, `GRADIENT_LOST`, `VIEWBOX_MISMATCH`, and `STROKE_ONLY_WITHOUT_FILL_NONE` (exit code 1 when any error is found; no device or emulator involved). Write the findings into the report section **Vector Fidelity Issues** with columns file / rule / severity / Android evidence / SVG evidence.
+
+    **Any `error`-severity finding blocks completion**: re-convert those drawables per the three-branch `fill` rule and the mandatory `clip-path` rule in `references/xml-drawable-to-svg-rules.md`, then re-run until only warnings remain. Do not mark the conversion complete while errors are outstanding, and do not silently re-emit the same output — a defect here propagates into every page that later references the icon, where it will again pass existence-based checks.
+    
+    **Critical: STROKE_ONLY_WITHOUT_FILL_NONE detection** — This error indicates a `<path>` element has a `stroke` attribute but no `fill` attribute. Without an explicit `fill="none"`, SVG's default `fill="black"` applies, turning outline icons into solid blobs. The converter MUST add `fill="none"` to every stroke-only path during generation, not as a post-processing fix. See the mandatory stroke-only detection function in `references/xml-drawable-to-svg-rules.md` for the runtime check that prevents this defect.
+11. **String escape self-check**: `references/conversion-rules.md` already requires stripping the outer quotes from Android's `"…"` quoting syntax (which exists to protect leading/trailing whitespace, and is *not* part of the literal text). Verify it was actually applied: scan every `element/string.json` for values that both begin and end with a `"` character. Each hit renders visible quote marks in the UI. Fix them and list them in the report. Apply the same check to every qualifier directory (`base/`, locale variants, etc.), not just `base/`.
+12. **Code-defined vector icon completeness**: steps 1-11 all reason about `res/`. If Step 4.1.3 applied, verify its output too:
+    a. Every icon reference in `code_vector_icons.json` is either `resolved` with its `.svg` present in `base/media/`, or carries an explicit `reason` and appears as an `unmappable` row in the report and mapping document. There is no third state — a reference that is neither written nor recorded is a silent omission.
+    b. No synthesized icon overwrote a `res/`-derived media file. The helper renames on collision (`…_material.svg`); confirm the rename is recorded in `notes`.
+    c. The pinned snapshot ref used for artwork is recorded in the report and in the mapping document metadata. A run whose artwork came from a moving branch is not reproducible and must be re-run against a pinned ref.
+
+    Unlike item 10, a failure here does not block completion — an unresolved icon is a recorded gap, not a corrupt asset. But an *unrecorded* icon does block: it reproduces exactly the defect this step exists to catch.
+
+**Placeholder SVG template** (for missing media resources):
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <rect width="24" height="24" fill="#CCCCCC"/>
+  <text x="12" y="16" font-size="4" text-anchor="middle" fill="#666666">RESOURCE_NAME</text>
+</svg>
+```
+Replace `RESOURCE_NAME` with the actual resource name (truncated if too long).
+
+### Step 7: Generate Report
+
+The report is written by Toolchain step 4 (`--docs-only --report`). It is deliberately **aggregated** so a human can read it end to end: counts by type, qualifier mappings, the full reference-resolution table, unmappable reasons grouped by cause, fidelity findings, code-defined icons, and warnings grouped by kind with a per-kind sample. The exhaustive per-resource listing belongs in the mapping document (Step 8), not here.
+
+Your job is to read it and act on what it says — an unresolved reference, a fidelity error, or a target collision is a finding, not a formatting detail.
+
+The generated report follows this structure:
+
+```
+# Android to HarmonyOS Resource Conversion Report
+
+## Resource Source
+- APK: <apk_path>
+- Decode result: Success / Failed
+- Decode error (if failed): <error summary>
+- Resource source: <"decoded APK (complete)" / "source res/ (may be missing library resources)">
+- Resource source path: <path>
+- Application module: <app_module>
+
+⚠️ **Note** (only when the decode failed and source `res/` was used): Resources were converted from the project's source `res/` directory because the APK could not be decoded. Library-provided resources (from Maven dependencies, AARs) are NOT included. References to library resources will appear as unsatisfied dependencies below. To get a complete conversion, supply an APK that decodes cleanly and re-run.
+
+## Library Dependencies (from build.gradle)
+Libraries declared in the project's build.gradle that may provide resources:
+| Library | Group:Artifact | Likely Resource Prefixes |
+|---|---|---|
+| Material Components | com.google.android.material:material | @color/material_*, @dimen/material_*, @style/Widget.Material* |
+| AndroidX AppCompat | androidx.appcompat:appcompat | @color/abc_*, @drawable/abc_* |
+| ... | ... | ... |
+
+(This section helps identify which unsatisfied dependencies come from which libraries.)
+
+## Summary
+- Resource source: <decoded APK / source res/>
+- Total Android resource files found: <count>
+- Successfully converted: <count>
+- Unmappable (no HarmonyOS equivalent): <count>
+- Failed: <count>
+- Resource references resolved: <count>
+- Unresolved references (library resources missing): <count>
+- Unresolved references (other reasons): <count>
+- Total Lottie animations found: <count>
+- Lottie migrated to rawfile/lottie/: <count>
+- Lottie remote / URL (no local target): <count>
+- Lottie filename collisions disambiguated: <count>
+- Code-defined icon references found (dex): <count | "none detected">
+- Code-defined icons resolved to artwork: <count>
+- Code-defined icons unresolved (recorded as unmappable): <count>
+- Code-defined icon media files written: <count>
+- Code-defined icons screen-attributed / Unknown: <count> / <count>
+- Material Icons snapshot ref: <pinned commit or vendored snapshot path>
+
+## Conversion Details
+
+### Successfully Converted Resources
+| Android Source | HarmonyOS Target | Type | Notes |
+|---|---|---|---|
+| res/values/strings.xml | resources/base/element/string.json | values→element | 25 strings converted |
+| res/drawable/icon.png | resources/base/media/icon.png | media copy | Direct copy |
+| res/drawable-hdpi/bg.png | resources/ldpi/media/bg.png | qualified media | hdpi→ldpi |
+| ... | ... | ... | ... |
+
+### Qualifier Mappings Applied
+| Android Qualifier Dir | HarmonyOS Qualifier Dir | Files Converted |
+|---|---|---|
+| drawable-hdpi | ldpi/media | 5 |
+| values-ar | ar/element | 3 |
+| ... | ... | ... |
+
+### Resource Reference Resolution
+References in converted resources that were resolved to their actual values.
+
+| Resource File | Reference | Resolved Value | Resolution Chain |
+|---|---|---|---|
+| base/element/color.json → primary_light | $color:primary | #ff6200EE | @color/primary → @color/md_blue_500 → #6200EE |
+| base/element/float.json → margin_double | $float:margin_base | 16vp | @dimen/margin_base → 16dp → 16vp |
+| ... | ... | ... | ... |
+
+### Layout & Menu Resource Dependencies
+Dependencies from layout/menu files (not converted to HarmonyOS, but needed when rebuilding the UI in ArkUI).
+
+| Source File (not converted) | Dependencies | All Satisfied? |
+|---|---|---|
+| layout/activity_main.xml | @string/app_name ✅, @drawable/bg_header ✅, @color/primary ✅ | Yes |
+| layout/fragment_settings.xml | @string/settings_title ✅, @drawable/ic_back ❌ (library) | No |
+| menu/main_menu.xml | @string/menu_share ✅, @drawable/ic_share ❌ (library) | No |
+| ... | ... | ... |
+
+### Unmappable Resources
+| Android Source | Reason |
+|---|---|
+| res/layout/activity_main.xml | Layout XML has no HarmonyOS equivalent (use ArkUI) |
+| res/drawable/ripple_effect.xml | XML drawable not supported |
+| ... | ... |
+
+### Unmapped Resources (Unsupported Qualifiers)
+| Android Source Dir | Qualifier | Reason |
+|---|---|---|
+| res/values-sw600dp/ | sw600dp | No HarmonyOS equivalent — skipped |
+| res/values-w480dp/ | w480dp | No HarmonyOS equivalent — skipped |
+| ... | ... | ... |
+
+### Unresolved References (Fallback Applied)
+| Resource File | Original Reference | Fallback Value | Reason | Likely Source |
+|---|---|---|---|---|
+| drawable/bg_themed.xml | ?attr/colorSurface | N/A (kept as-is) | Theme attribute — cannot resolve statically | N/A |
+| element/color.json → material_blue | @color/design_default_color_primary | #ff000000 | Library resource not in source res/ | com.google.android.material:material |
+| ... | ... | ... | ... | ... |
+
+### System Resources Resolved
+| Resource File | System Reference | Resolved Value |
+|---|---|---|
+| element/color.json → bg_white | @android:color/white | #ffffffff |
+| element/color.json → divider | @android:color/darker_gray | #ffaaaaaa |
+| ... | ... | ... |
+
+### Nine-Patch Files Renamed
+| Original Name | Renamed To | Source Directory |
+|---|---|---|
+| abc_btn_default.9.png | abc_btn_default_9.png | drawable-mdpi |
+| ... | ... | ... |
+
+### Lottie Animation Resources
+Every Lottie JSON detected in the project (identified by structure signature: `v`+`fr`+`ip`+`op`+`layers`) and where it lands in HarmonyOS. Each row also identifies the Android Activity/Fragment that plays the animation and proposes the corresponding HarmonyOS page name so the developer knows where to call `@ohos/lottie`'s `lottie.loadAnimation({ path: 'lottie/<name>.json' })`.
+
+| Android Source | Target Rawfile Path | Host Activity/Fragment | Host Layout / Loader | HarmonyOS Page (suggested) | Notes |
+|---|---|---|---|---|---|
+| assets/AndroidWave.json | rawfile/lottie/androidwave.json | DynamicActivity (via lottie_fileName) | res/layout/dynamic_activity.xml | DynamicPage | XML `lottie_fileName` reference |
+| assets/Lottie Logo 1.json | rawfile/lottie/lottie_logo_1.json | PlayerActivity → PlayerFragment | PreviewFragment picker (AssetManager.list) → PlayerActivity.intent(...) | PlayerPage | Renamed from "Lottie Logo 1.json" (spaces normalized). Loaded via runtime picker, dispatches to PlayerActivity. |
+| res/raw/lottielogo.json | rawfile/lottie/lottielogo.json | (multiple) | res/layout/auto_play.xml, auto_play_gone.xml, no_auto_play.xml (`lottie_rawRes="@raw/lottielogo"`) | AutoPlayPage / NoAutoPlayPage | Referenced by three demo layouts. |
+| (remote) https://...  | N/A | ... | code call to LottieCompositionFactory.fromUrl(...) | ... | Remote resource, no local target. |
+| ... | ... | ... | ... | ... | ... |
+
+### Code-Defined Vector Icons
+Icons the Android app draws from code (`androidx.compose.material:material-icons-*`) rather than from `res/`. These never appear in the decoded resource tree, so they are recovered from `classes*.dex` and synthesized from the pinned Material Icons snapshot. Omit this section only when no code-defined icons were detected.
+
+Artwork source: `<pinned commit or vendored snapshot path>`
+
+| Compose Reference | Material Name | Style | HarmonyOS Target | Host Screen(s) | Suggested Page | Notes |
+|---|---|---|---|---|---|---|
+| Icons.Outlined.GetApp | get_app | Outlined | base/media/ic_get_app_outlined.svg | MoreScreen | MorePage | |
+| Icons.AutoMirrored.Outlined.Label | label | Outlined | base/media/ic_label_outlined.svg | MoreScreen | MorePage | AutoMirrored: mirror horizontally under right-to-left locales |
+| Icons.Filled.DateRange | date_range | Filled | base/media/ic_date_range_filled.svg | Unknown | — | dex-only; no source reference found (likely used by a library) |
+| ... | ... | ... | ... | ... | ... | ... |
+
+Unresolved references (no artwork produced — these are real gaps, list every one):
+
+| Compose Reference | Material Name | Reason |
+|---|---|---|
+| ... | ... | not found in Material Icons index / app-defined ImageVector / snapshot unavailable |
+
+### Placeholder Resources Created
+Media resources referenced in `.ets` UI code but not found in converted resources. Placeholder SVGs were created to allow compilation — these MUST be replaced with real assets.
+| Resource Name | Referenced In | Placeholder File |
+|---|---|---|
+| ic_tab_home | pages/MainPage.ets | base/media/ic_tab_home.svg |
+| ic_tab_profile | pages/MainPage.ets | base/media/ic_tab_profile.svg |
+| ... | ... | ... |
+
+### Failed Conversions
+| Android Source | Error |
+|---|---|
+| ... | ... |
+
+### Verification Results
+- All resources accounted for: Yes/No
+- Missing resources: <list if any>
+- All references resolved: Yes/No
+- Unresolved references: <count> (<count> due to missing library resources, <count> other)
+- Vector fidelity errors: <count> (warnings: <count>) — from `scripts/svg_fidelity_check.js`
+- String escape artifacts: <count> (values still wrapped in literal quotes)
+- Code-defined icons unrecorded: <count> (MUST be 0 — every reference is either written or listed as unmappable)
+
+### Vector Fidelity Issues
+<Omit this section only when the checker reports zero findings.>
+
+| File | Rule | Severity | Android evidence | SVG evidence |
+|---|---|---|---|---|
+| <name> | CLIP_PATH_LOST / FILL_INJECTED / FILL_LOST / GRADIENT_LOST / VIEWBOX_MISMATCH | error/warn | <clip count, fillColor, gradient stops, viewport…> | <clipPath count, fill value, gradient defs, viewBox…> |
+```
+
+### Step 8: Generate Resource Mapping Document
+
+The second document, at `resource_mapping_path`, is written by the same Toolchain step 4 invocation (`--mapping`). It is the audit surface: **every** observed Android resource appears as its own row, `values` at entry granularity. It does not sample, summarise, or aggregate — those are the report's job. Expect it to be large (measured range: 4 MB to 22 MB); that size is the cost of the no-omission requirement, and the dataset tracks these files with Git LFS for exactly that reason.
+
+Do not hand-write or hand-trim this document. If it looks too large, that is not a reason to sample it.
+
+The generated mapping markdown contains these required sections:
+
+1. **Metadata**
+   - `android_project_dir`
+   - `harmony_project_dir`
+   - Resource source
+   - Resource source path
+   - Decode result
+   - Generation timestamp
+   - Material Icons snapshot ref — only when Step 4.1.3 applied; the pinned commit or vendored snapshot path used to synthesize code-defined icons
+
+2. **Android Resource Inventory**
+   - One row per Android resource item
+   - Required columns: Android Resource Path, Resource Name, Function, Screen(s), Source Category, Type Category, Status, Notes
+
+3. **Android → HarmonyOS Mapping Details**
+   - One row per mapping record
+   - Required columns: Android Resource Path, Android Screen(s), Android Source Category, Android Type Category, HarmonyOS Target, Mapping Kind, Notes
+
+4. **Unmapped / Unmappable / System / Remote Summary**
+   - Explicitly list resources with no direct HarmonyOS target, Android framework resources, library-only resources inferred from the APK or dependency graph, and runtime remote resources
+
+5. **Code-Defined Vector Icons** (only when Step 4.1.3 applied)
+   - One row per icon reference recovered from `classes*.dex`, including references that could not be resolved
+   - Required columns: Compose Reference, Material Name, Style, HarmonyOS Target (or `N/A`), Host Screen(s), Suggested HarmonyOS Page, Notes
+   - These rows are additional to — not a substitute for — the inventory and mapping rows required in sections 2 and 3. Record them there with `source_category = 第三方库资源`, `type_category = drawable`, and `mapping_kind = code-vector synthesized` (or `unmappable`), using `<source file>#Icons.<Style>.<Name>` as the Android resource path (or `classes.dex#Icons.<Style>.<Name>` when dex-only)
+
+6. **Quick Findings**
+   - Summarize important review findings such as launcher icons from `mipmap`, probable third-party library assets (`abc_*`, `mtrl_*`, `design_*`), and resources present only in the decoded APK but not in source `res/`
+
+**Hard requirements for the mapping markdown:**
+- Never omit an Android resource silently
+- Never omit a code-defined icon reference silently — an icon that could not be resolved is an `N/A` row with a stated reason, never an absent row
+- For `values/*.xml`, inventory and mapping rows must be at entry granularity using `file_path#tag/name`
+- Every mapping row must include the Android-side Screen(s), Source Category, and Type Category columns
+- If one Android resource maps to multiple HarmonyOS outputs, emit multiple mapping rows
+- If no HarmonyOS target exists, write `N/A` in the HarmonyOS Target column and explain why in Notes
+
+
+## Important Notes
+
+- **Never write your own conversion script.** `scripts/a2h_resource_convert.js` is the canonical implementation of every rule in `references/`; `scripts/code_vector_icons.js` and `scripts/svg_fidelity_check.js` complete the toolchain. Re-implementing any of it produces results that are not comparable across runs — that is the measured failure this toolchain exists to remove (see "Toolchain — mandatory"). If a rule appears wrong or a case is unhandled, fix the script and say so; do not route around it with a one-off converter, a hand-edited resource, or an undocumented placeholder.
+- **`scripts/code_vector_icons.js` is required, not optional, for Jetpack Compose applications.** Their icons live in `classes*.dex`, not `res/`, so every `res/`-based check in this skill will report success while the migrated page renders no icons at all. Skipping it is the one omission that passes every other gate.
+- Always read `references/conversion-rules.md` for the complete, detailed conversion rules before starting conversions. The tables above are summaries.
+- Always read `references/resource-mapping-rules.md` before producing `resource_mapping_path`. It defines the inventory schema, mapping schema, screen attribution rules, source categorization rules, type categorization rules, and markdown output format.
+- **Decoding is best-effort**: `apk_path` is decoded first because the decoded APK is the most complete resource source (it includes library dependencies merged in at build time). This skill does **not** build the APK — it decodes the one the caller supplies. If decoding fails, conversion proceeds from the project's source `res/` at `<android_project_dir>/<app_module>/src/main/res/` — a partial conversion with clear reporting is far more useful than no conversion at all.
+- **XML drawable conversion is critical**: Android XML drawables (`<vector>`, `<shape>`, `<layer-list>`, `<selector>`) must be converted to SVG format, not skipped. HarmonyOS supports SVG in `media/`. Read `references/xml-drawable-to-svg-rules.md` for the detailed conversion rules for each drawable type.
+- **Lottie animations are special**: Android projects that use `com.airbnb.android:lottie` ship JSON files in `assets/` or `res/raw/`. These migrate to `<ui_module>/src/main/resources/rawfile/lottie/<normalized>.json` for consumption by `@ohos/lottie` (installed via `ohpm install @ohos/lottie`). Identify Lottie JSON by structure signature (must contain `v`+`fr`+`ip`+`op`+`layers`), not by extension. Every Lottie row in the mapping document MUST bind the JSON to the Android Activity/Fragment that plays it and propose a HarmonyOS page name. Read `references/lottie-conversion-rules.md` for the complete rules including reference extraction (`lottie_fileName` / `lottie_rawRes` / `lottie_url`), filename normalization, host-screen binding, and remote/dynamic edge cases.
+- **Code-defined icons are invisible to `res/` scanning**: Jetpack Compose apps draw most icons from `androidx.compose.material:material-icons-*`. Those are compiled `ImageVector` objects in `classes*.dex` — not in `res/drawable*/`, not in `resources.arsc`, therefore not in the decoded `res/` tree. Every existence-based check in this skill will report success while the migrated page shows no icons. Step 4.1.3 and `scripts/code_vector_icons.js` recover them: the dex gives the authoritative inventory, the Android source gives screen attribution, and a **pinned** Material Icons snapshot gives the artwork. Read `references/code-vector-icon-rules.md` for the complete rules. An icon this process cannot resolve must still become a visible `unmappable` row — never a silent omission.
+- **Dependency analysis always runs**: Read `references/dependency-analysis-rules.md` for the complete dependency extraction patterns and reference formats. Even when converting from source `res/` with missing library resources, dependency analysis is essential — it tells the developer exactly which references are broken and why, so they can address them manually or fix the build.
+- **APK decoding**: The decoder is `a2h-resource`, a pure-Node.js resource decoder published to npm (requires Node.js `>= 20`; no other runtime). Install it with `npm install -g a2h-resource` and run `a2h-resource <apk> -o <out>`, or run it on-demand with `npx --yes a2h-resource <apk> -o <out>`. It covers resource extraction only — it does not disassemble `classes.dex` or repackage APKs, neither of which this skill needs. It decodes a single resource package (the app's); if it errors out or the APK is a rare multi-package/split APK, fall back to converting from the project's source `res/` directory (as in Step 3).
+The following are **behaviours the converter already guarantees**. They are listed so you know what to expect and what to check in its output — not as instructions to implement:
+
+- Android XML is parsed with namespaces, comments, and CDATA handled; attributes are matched by local name, so any `android:` prefix works.
+- Every entry of every `<resources>` element is extracted; multiple value files contributing the same type are merged into one HarmonyOS JSON file.
+- Resource names are preserved exactly as Android spells them — they are identifiers.
+- An element JSON that already exists in the HarmonyOS project is **merged**, not overwritten: existing entries keep their order and position, DevEco scaffold defaults are replaced when a real resource has the same name, and the replacement is recorded.
+- Android's `"…"` quoting syntax is consumed as syntax, so leading and trailing whitespace it protects is preserved in the value. Do not "clean up" such strings; Android renders that whitespace.
+- Decoded fixed-point dimensions are rounded to 3 decimals, so values like `6.500001dip` do not carry float noise into the output.
+- When several Android sources map to one HarmonyOS target (`drawable/x.xml` and `drawable-anydpi/x.xml` both land in `base/media/`), the source with **fewer qualifiers** wins and the loser is recorded as an `unmappable` mapping row — never silently dropped.