android2harmony 0.1.4 → 0.1.6

package/skills/a2h-resource-convert/references/code-vector-icon-rules.md

@@ -0,0 +1,335 @@
+# Android to HarmonyOS Code-Defined Vector Icon Rules
+
+This document defines how to migrate vector icons that an Android project draws from **code** rather than from `res/`. Read this before converting any project that uses Jetpack Compose. Every code-defined icon observed during conversion must produce an inventory row and a mapping row per the rules in `references/resource-mapping-rules.md`.
+
+## Table of Contents
+1. [Scope: Why `res/` Scanning Misses These Icons](#scope-why-res-scanning-misses-these-icons)
+2. [Detection: When to Run This Analysis](#detection-when-to-run-this-analysis)
+3. [Three Sources of Truth](#three-sources-of-truth)
+4. [Extracting the Icon Inventory from `classes*.dex`](#extracting-the-icon-inventory-from-classesdex)
+5. [Extracting Screen Attribution from Android Source](#extracting-screen-attribution-from-android-source)
+6. [Resolving an Icon Name to Upstream Artwork](#resolving-an-icon-name-to-upstream-artwork)
+7. [HarmonyOS Target Path and Filename](#harmonyos-target-path-and-filename)
+8. [SVG Post-Processing](#svg-post-processing)
+9. [AutoMirrored and Right-to-Left](#automirrored-and-right-to-left)
+10. [Report and Mapping Requirements](#report-and-mapping-requirements)
+11. [Fallbacks and Out-of-Scope Cases](#fallbacks-and-out-of-scope-cases)
+
+---
+
+## Scope: Why `res/` Scanning Misses These Icons
+
+Jetpack Compose applications take most of their iconography from `androidx.compose.material:material-icons-core` and `androidx.compose.material:material-icons-extended`. Those icons are **Kotlin-generated `ImageVector` objects** built with a path DSL. They are compiled into `classes*.dex` and never appear in:
+
+- the project's `res/drawable*/`,
+- the APK's `resources.arsc`,
+- therefore also not in `<decoded_output_path>/res/` after Step 3.
+
+Every other step of this skill reads a `res/` tree. That makes these icons **structurally invisible** to the rest of the pipeline, and the failure is silent in a particularly bad way:
+
+- Step 5.3 scans `layout*/` and `menu/` for `@type/name` references. A Compose app has no layout XML, so the scan finds nothing missing.
+- Step 6.8 cross-checks `$r('app.media.xxx')` references that already exist in `.ets` files. A HarmonyOS shell project that has not been written yet contains no such references, so the check finds nothing missing.
+
+Both gates report "all dependencies satisfied" while the migrated page renders no icons at all.
+
+**Observed case.** On a real Compose application (Mihon), the More screen displays 10 icons. Exactly **one** of them (`R.drawable.ic_glasses_24dp`) is an Android resource. The other nine — including the icons in front of *Download queue* and *Categories* — come from `Icons.Outlined.*` / `Icons.AutoMirrored.Outlined.*`. Resource conversion converted the one resource correctly and produced nothing for the other nine, with no warning anywhere in the report.
+
+## Detection: When to Run This Analysis
+
+Run this analysis when **any** of the following is true:
+
+1. `build.gradle`, `build.gradle.kts`, or `gradle/libs.versions.toml` declares `androidx.compose.material:material-icons-core` or `androidx.compose.material:material-icons-extended`.
+2. Any `.kt` file in the project imports a path under `androidx.compose.material.icons.`.
+3. `classes*.dex` in the decoded APK contains at least one string matching the icon-name pattern in the next section.
+
+Condition 3 alone is sufficient — a project can pull the icon library in transitively through another dependency without declaring it.
+
+If none hold, write `Code-defined vector icons: none detected` in the report's summary and skip the rest of this document.
+
+## Three Sources of Truth
+
+Three separate questions need three separate sources. Do not try to answer all three from one place.
+
+| Question | Source | Needs `android_project_dir`? |
+|---|---|---|
+| **Which** icons does this app use? | `classes*.dex` string pool | No |
+| **What** does each icon look like? | Upstream Material Icons snapshot | No |
+| **Where** is each icon used (screen attribution)? | Android source `.kt` files | **Yes** |
+
+### Why the dex is authoritative for scope
+
+The dex reflects what was actually packaged: it covers icons used by **library** code as well as application code, and it **excludes** icons eliminated as dead code by R8. Grepping the Kotlin source alone both over-reports (references that were shrunk away) and under-reports (library-internal usage, and references reached through import aliases or indirection).
+
+### Why the dex cannot give attribution
+
+R8 obfuscates the icon library. In a release APK the package path `androidx/compose/material/icons` is absent from every dex, and the surviving icon identifiers are the plain name strings passed to the `materialIcon(name = "...")` builder, sitting in a flat, sorted string pool:
+
+```
+... Outlined.Public  Outlined.PushPin  Outlined.QueryStats  Outlined.RadioButt ...
+```
+
+The string tells you `QueryStats` is used. It does not tell you the *Statistics* row uses it. Recovering that link from the dex would require disassembly plus call-graph analysis to connect an obfuscated getter to both its name string and its call sites. Application class names typically **do** survive (e.g. `Leu/kanade/presentation/more/MoreScreenKt`), so the analysis is tractable — but reading the one line of Kotlin source is exact and costs nothing:
+
+```kotlin
+TextPreferenceWidget(
+    title = stringResource(MR.strings.label_download_queue),
+    icon = Icons.Outlined.GetApp,          // <- attribution, directly readable
+    onPreferenceClick = onClickDownloadQueue,
+)
+```
+
+`android_project_dir` is already a required input of this skill (Step 2 resolves the application module from it; Step 5 correlates library dependencies from it), so attribution adds no new input requirement.
+
+## Extracting the Icon Inventory from `classes*.dex`
+
+Read each `classes*.dex` at `<decoded_output_path>/` as raw bytes and match this pattern against the byte stream (the strings are plain ASCII inside the DEX string pool):
+
+```
+(AutoMirrored\.)?(Filled|Outlined|Rounded|Sharp|TwoTone)\.[A-Z_][A-Za-z0-9_]*
+```
+
+Deduplicate across all dex files. Each unique match is one **icon reference**.
+
+Notes:
+
+- **The name must start with an uppercase letter or `_`.** Compose icon names are PascalCase, and digit-leading names carry a `_` prefix. Without this constraint the pattern also captures Kotlin source filenames that the compiler embeds as debug strings — `Outlined.kt`, `Filled.kt`, `Rounded.kt` fit the shape exactly. Three such false positives were measured on one real application.
+- `Icons.Default` is an alias of `Icons.Filled`, and `Icons.AutoMirrored.Default` of `Icons.AutoMirrored.Filled`. The string recorded in the dex is always the `Filled` form; no normalization is needed on the dex side (it *is* needed on the source side — see below).
+- Names that begin with a digit are prefixed with `_` in Compose (`Icons.Filled._360`). Strip the leading `_` before name resolution.
+- Do not silently drop a captured string that fails to resolve. Report it. A capture that resolves to nothing is either a false positive worth knowing about or a genuine gap in the snapshot.
+
+When the decoded APK is unavailable (the Step 3 decode fell back to source `res/`), fall back to source-only extraction using the patterns in the next section, and record in the report that the inventory is source-derived and therefore may miss library-internal icon usage.
+
+### When the icon library was not shrunk
+
+The dex is authoritative for scope **only when R8 actually shrank the icon library**. When it did not, the entire `material-icons-extended` set is packaged and the dex inventory stops meaning "icons this app uses".
+
+The signal is a large reference count that is almost entirely unattributed. One measured application produced **2149** dex references against **92** source-attributed ones — 96% dex-only. Synthesizing artwork for all of them would write ~2100 unused SVGs into `base/media/`.
+
+When the reference count is at or above 300 **and** at least 80% of references have no source attribution, treat the library as unshrunk:
+
+- synthesize artwork only for source-attributed references (`--attributed-only`),
+- still emit an inventory and mapping row for every other reference, with `mapping_kind = unmappable` and reason `packaged by an unshrunk icon library; not referenced by application code`,
+- state the situation in the report.
+
+This is a deliberate trade-off, not a failure: the rows are all still there, so nothing is silently omitted, and the output stays proportionate to what the application actually renders.
+
+## Extracting Screen Attribution from Android Source
+
+Grep `.kt` files under `android_project_dir` for:
+
+```
+Icons\.(AutoMirrored\.)?(Filled|Outlined|Rounded|Sharp|TwoTone|Default)\.[A-Z_][A-Za-z0-9_]*
+```
+
+Normalize `Default` → `Filled` so source matches join cleanly against dex matches.
+
+Attribute each match to a screen using this evidence priority — the same best-effort discipline as `references/resource-mapping-rules.md` §6:
+
+1. **Enclosing composable.** The nearest preceding `fun <Name>(` declaration in the file. If that name ends in `Screen`, `Page`, `Tab`, or `Dialog`, use it directly.
+2. **File name.** `MoreScreen.kt` → `MoreScreen`.
+3. **Shared widget.** If the enclosing composable is a reusable widget referenced from several screens, record the known screens, or `Common` when the list is too broad to be useful.
+4. **No evidence.** `Unknown`.
+
+Then propose a HarmonyOS page name the same way `references/lottie-conversion-rules.md` does: strip the `Screen` / `Activity` / `Fragment` / `Tab` suffix and append `Page` (`MoreScreen` → `MorePage`). Record it in `notes` as `page=<PageName>` and mark it as a suggestion to verify against the actual ArkUI pages.
+
+An icon that appears in the dex but has **no** source match is still a required row. Record `Screen(s) = Unknown` and note `dex-only; no source reference found (likely used by a library)`.
+
+## Resolving an Icon Name to Upstream Artwork
+
+The Compose icon set is generated from the classic Material Icons in `google/material-design-icons`. The mapping is a pure string transform plus one index lookup.
+
+### Step 1 — name transform
+
+Strip any leading `_`, then split on **case boundaries only** and lowercase:
+
+```
+(?<=[a-z0-9])(?=[A-Z])      -> _        aB  -> a_B
+(?<=[A-Z])(?=[A-Z][a-z])    -> _        ABc -> A_Bc
+```
+
+**Do not split on digit boundaries.** Upstream has no consistent rule there, and any fixed rule gets a batch of names wrong:
+
+| Compose name | Material name | A digit rule would produce |
+|---|---|---|
+| `Filter1` | `filter_1` | — (needs the split) |
+| `Co2` | `co2` | `co_2` ✗ |
+| `Rotate90DegreesCcw` | `rotate_90_degrees_ccw` | — (needs the split) |
+| `StarPurple500` | `star_purple500` | `star_purple_500` ✗ |
+| `Grid3x3` | `grid_3x3` | `grid_3_x_3` ✗ |
+| `Crop169` | `crop_16_9` | `crop_169` ✗ |
+| `_3dRotation` | `3d_rotation` | `3_d_rotation` ✗ |
+
+### Step 2 — three-stage lookup
+
+Resolve the transformed name against the index in this order. Every stage is deterministic.
+
+1. **Exact match.** `GetApp` → `get_app`, present in the index. Covers the large majority.
+2. **Underscore-insensitive match.** Compare after deleting every `_` on both sides. This absorbs the entire digit-boundary problem in one rule: `crop169` matches `crop_16_9`, `grid3x3` matches `grid_3x3`, `filter1` matches `filter_1`, `starpurple500` matches `star_purple500`, `3drotation` matches `3d_rotation`. Measured across the upstream index, 2208 of 2209 names remain unique after deleting underscores; the single collision (`add_chart` / `addchart`, a legacy upstream duplicate) is already settled by stage 1, and otherwise breaks ties lexicographically.
+3. **Alias table.** A few icons were renamed upstream while Compose kept the old name. Only entries verified against the index belong here — never guess:
+
+   | Compose name | Upstream name |
+   |---|---|
+   | `Motorcycle` | `two_wheeler` |
+   | `LeaveBagsAtHome` | `no_luggage` |
+
+Anything still unresolved after stage 3 becomes an `unmappable` row. Do not invent artwork.
+
+Measured over 10 real applications (2500 icon references), stage 1 resolved 2408, stage 2 resolved 91, the alias table resolved 2, and nothing was left unresolved.
+
+### Step 3 — category lookup
+
+The upstream repository stores icons at `src/<category>/<name>/<style_dir>/24px.svg`, and the category is not derivable from the name. Build a `name → category` index once from `update/current_versions.json`, whose keys have the form `<category>::<name>`.
+
+**Exclude the `symbols` category.** That key namespace is the parallel *Material Symbols* set, which lives at `symbols/web/<name>/...` with a different on-disk layout. It duplicates nearly every classic icon name, so leaving it in makes every single lookup ambiguous and can produce paths that do not exist in `src/`.
+
+After excluding `symbols`, a name that still maps to more than one category is a genuine ambiguity: pick the first in lexicographic order for determinism and record the alternatives in `notes`.
+
+### Step 4 — style directory
+
+| Compose style | Upstream directory | Filename suffix |
+|---|---|---|
+| `Filled` (and `Default`) | `materialicons` | `filled` |
+| `Outlined` | `materialiconsoutlined` | `outlined` |
+| `Rounded` | `materialiconsround` | `round` |
+| `Sharp` | `materialiconssharp` | `sharp` |
+| `TwoTone` | `materialiconstwotone` | `twotone` |
+
+`AutoMirrored` is **not** a style. `AutoMirrored.Outlined.Label` and a hypothetical `Outlined.Label` resolve to the same upstream file.
+
+### Step 5 — assemble
+
+```
+src/<category>/<material_name>/<style_dir>/24px.svg
+```
+
+Worked examples from the Mihon More screen:
+
+| Compose reference | Upstream path |
+|---|---|
+| `Outlined.GetApp` | `src/action/get_app/materialiconsoutlined/24px.svg` |
+| `AutoMirrored.Outlined.Label` | `src/action/label/materialiconsoutlined/24px.svg` |
+| `Outlined.QueryStats` | `src/editor/query_stats/materialiconsoutlined/24px.svg` |
+| `Outlined.Storage` | `src/device/storage/materialiconsoutlined/24px.svg` |
+| `Outlined.CloudOff` | `src/file/cloud_off/materialiconsoutlined/24px.svg` |
+| `Filled.VolunteerActivism` | `src/maps/volunteer_activism/materialicons/24px.svg` |
+
+### Snapshot pinning
+
+The artwork source MUST be a pinned snapshot, not a moving branch. Reproducibility is the whole point of Step 2 resource patches: two runs of the same commit must produce byte-identical output. Record the pinned ref in the report and in the mapping document metadata.
+
+**The default is `--fetch`: artwork is downloaded from a pinned upstream commit at run time.** The pin is what makes the run reproducible — never point the tool at a moving branch.
+
+This carries one operational requirement worth recording in the run environment: **the machine needs network access to `raw.githubusercontent.com`**. A network-isolated runner (a hardened container, an offline test bench) will fail this step. Two consequences follow, and both should be handled by reporting rather than by silently degrading:
+
+- the step exits non-zero and the icons are recorded as `unmappable` with reason `icon snapshot unavailable`;
+- the `res/` conversion is unaffected and still valuable, so the run continues.
+
+For such environments, `--snapshot <dir>` reads a local copy instead. It does not need the whole upstream repository — the clone is dominated by PNG exports, the Android XML tree, and the Material Symbols tree, none of which this skill reads. Only these are required (measured at commit `50f0603`: 10,751 files, 5.4 MB):
+
+```
+<material_icon_snapshot_dir>/
+  update/current_versions.json          # the name -> category index
+  src/<category>/<name>/<style_dir>/24px.svg
+```
+
+Record which upstream commit the copy was taken from.
+
+## HarmonyOS Target Path and Filename
+
+```
+<ui_module>/src/main/resources/base/media/ic_<material_name>_<style_suffix>.svg
+```
+
+**The style suffix is mandatory.** In the classic Material Icons set, `Outlined.X` is sometimes different artwork from `Filled.X` and sometimes byte-identical:
+
+```
+bookmark  filled    d="M17 3H7c-1.1 0-1.99.9-1.99 2L5 21l7-3 7 3V5c0-1.1-.9-2-2-2z"
+bookmark  outlined  d="M17 3H7c-1.1 0-2 .9-2 2v16l7-3 7 3V5c0-1.1-.9-2-2-2z"        <- differs
+favorite  filled / outlined                                                          <- identical
+```
+
+Naming by bare `ic_<name>.svg` therefore silently drops one of the two whenever they differ. Always include the style. Keeping the byte-identical duplicates costs a few hundred bytes each and keeps the naming rule free of special cases.
+
+`AutoMirrored` is **not** part of the filename — it is a property of the *reference*, handled at the component level (next section). So `AutoMirrored.Filled.KeyboardArrowLeft` and `Filled.KeyboardArrowLeft` correctly share one file.
+
+**Collision with a `res/`-derived media file.** If the target filename already exists in the HarmonyOS output because a real Android drawable produced it, append `_material` (`ic_settings_outlined_material.svg`) and record both the collision and the rename in `notes`. Never overwrite a `res/`-derived asset.
+
+## SVG Post-Processing
+
+The upstream files are already 24×24 SVG with `viewBox="0 0 24 24"`, so no geometry transform is required. Apply exactly two transforms:
+
+1. **Remove the no-op guard path.** Upstream files open with a transparent bounding rectangle that carries no visual information:
+
+   ```xml
+   <path d="M0 0h24v24H0V0z" fill="none"/>
+   <path d="M0 0h24v24H0z" fill="none"/>      <!-- variant -->
+   ```
+
+   Both variants are removed.
+
+2. **Do not inject `fill`.** The remaining path deliberately carries no `fill` attribute. That matches Compose semantics, where the icon is tinted at the use site by `LocalContentColor`; on HarmonyOS the equivalent is `Image($r('app.media.…')).fillColor('#666666')`. Injecting a hard-coded `fill` here is the same defect that `references/xml-drawable-to-svg-rules.md` calls `FILL_INJECTED`, reached from a different source.
+
+Keep `viewBox`, `width`, and `height` as upstream emits them.
+
+## AutoMirrored and Right-to-Left
+
+HarmonyOS qualifier directories have no left-to-right / right-to-left dimension — the qualifier order is `MCC_MNC-language_script_country/region-orientation-device-colormode-density`. Mirroring therefore **cannot** be expressed as a resource variant the way Android's `-ldrtl` does.
+
+Handle it at the component level in ArkUI and record the requirement so the developer does not lose it:
+
+- set `auto_mirrored = true` on the mapping record,
+- write `AutoMirrored: mirror horizontally under right-to-left locales` into `notes`.
+
+Do not emit a second, pre-mirrored SVG file. A pre-mirrored asset would have to be selected by code anyway, and it doubles the assets for no gain.
+
+## Report and Mapping Requirements
+
+### Conversion report
+
+Add a dedicated section (see SKILL.md Step 7 for its position):
+
+```
+### Code-Defined Vector Icons
+
+| 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 under RTL |
+```
+
+and these summary counters:
+
+- Code-defined icon references found (dex)
+- Resolved to upstream artwork
+- Unresolved (recorded as unmappable)
+- Distinct media files written
+- AutoMirrored references
+- Screen-attributed / `Unknown`
+
+### Mapping document
+
+Every icon reference gets one inventory row and one mapping row.
+
+- **`android_resource_path`** — use `<source file>#Icons.<Style>.<Name>` when a source reference was found (e.g. `app/src/main/java/eu/kanade/presentation/more/MoreScreen.kt#Icons.Outlined.GetApp`); otherwise `classes.dex#Icons.<Style>.<Name>`.
+- **`android_resource_name`** — the material snake_case name (`get_app`).
+- **`function`** — describe the role from the host row's label when known (`Download queue row icon`), otherwise a conservative fallback (`Material icon used in code`).
+- **`screens`** — per the attribution rules above; `Unknown` when dex-only.
+- **`source_category`** — `第三方库资源`, with `notes` naming `androidx.compose.material:material-icons-extended`. These icons are library-provided; they are not application `res/` assets.
+- **`type_category`** — `drawable`. Do not invent a new top-level type category.
+- **`mapping_kind`** — `code-vector synthesized`, or `unmappable` when unresolved.
+- **`notes`** — MUST record the upstream path and the pinned snapshot ref, so a reviewer can verify the artwork.
+
+**Hard requirement:** never silently omit a code-defined icon reference. This is the same rule as §13 of `references/resource-mapping-rules.md`, and it is the rule whose absence caused the whole class of defects this document exists to fix.
+
+## Fallbacks and Out-of-Scope Cases
+
+| Situation | Handling |
+|---|---|
+| Name captured from dex does not resolve in the index | Emit the row with `harmony_target = N/A`, `mapping_kind = unmappable`, reason `not found in Material Icons index`. **Never invent artwork.** |
+| Snapshot unavailable (no vendored copy, no network) | Emit every icon row as `unmappable` with reason `icon snapshot unavailable`, and state it prominently in the report. Do **not** fail the whole conversion — the `res/` conversion is still valuable. |
+| `android_project_dir` unavailable or unreadable | Inventory still comes from the dex; set every `screens` to `Unknown` and note the limitation. |
+| Decode failed, only source `res/` available | Extract from source `.kt` only; note that library-internal icon usage may be missing. |
+| App-defined `ImageVector` built by hand in application code | **Out of scope.** Detect via `ImageVector.Builder` in application source, record as `unmappable` with reason `app-defined ImageVector, no upstream artwork`, and list it in the report so the developer redraws it manually. |
+| Non-Material code icon libraries (e.g. a third-party Compose icon pack) | Out of scope for artwork. Record the references as `unmappable` with the library name in `notes` so the gap is visible. |
+
+The last three rows matter: this document narrows a known blind spot, it does not close it completely. Anything it cannot resolve must become a visible row, never a silent omission.

package/skills/{hmos-resources-convert → a2h-resource-convert}/references/conversion-rules.md

@@ -37,7 +37,7 @@ Android resources live under `app/src/main/res/`. Common subdirectories:
 
 ## HarmonyOS Resource Directory Structure
 
-HarmonyOS resources live under `entry/src/main/resources/`. Structure:
+HarmonyOS resources live under `<ui_module>/src/main/resources/` (where `<ui_module>` is typically `entry` for single-module projects, or a path like `products/phone` for layered projects). Structure:
 
 ```
 resources/
@@ -533,6 +533,19 @@ HarmonyOS format: `<language>` or `<language>_<REGION>`
 | `land` | `horizontal` |
 | `port` | `vertical` |
 
+### Device Type Qualifiers
+
+HarmonyOS has a device dimension in its qualifier order, so Android UI-mode qualifiers that name a device map onto it rather than being stripped.
+
+| Android | HarmonyOS |
+|---|---|
+| `watch` | `wearable` |
+| `television` | `tv` |
+| `car` | `car` |
+| `desk`, `appliance` | `phone` (no distinct HarmonyOS target; note the approximation in the report) |
+
+Do not silently drop these. Dropping `watch` merges wearable-specific artwork into `base/`, where it can overwrite the phone variant of the same resource name.
+
 ### Night Mode Qualifiers
 
 | Android | HarmonyOS |
@@ -550,7 +563,7 @@ Android directory names can contain multiple qualifiers separated by hyphens, e.
 2. The first segment is the resource type (`drawable`, `mipmap`, `values`, etc.)
 3. The remaining segments are qualifiers. Parse them left-to-right, recognizing:
    - Language codes: 2-3 lowercase letters (e.g., `zh`, `ar`, `en`)
-   - Region codes: `r` + 2 uppercase letters (e.g., `rCN`, `rUS`) — always follows a language
+   - Region codes: `r` + 2 uppercase letters (e.g., `rCN`, `rUS`) **or** `r` + 3 digits, the UN M.49 numeric region code (e.g., `r419` = Latin America) — always follows a language. HarmonyOS accepts both forms, so `values-es-r419` → `es_419/element/`. Treating the numeric form as unrecognized and stripping it merges that locale into the bare language directory (`es`), where its entries silently overwrite the other variant's — a mistranslation no existence check can see.
    - Density: `ldpi`, `mdpi`, `hdpi`, `xhdpi`, `xxhdpi`, `xxxhdpi`, `nodpi`, `anydpi`, `tvdpi`
    - Orientation: `land`, `port`
    - Night mode: `night`, `notnight`

package/skills/{hmos-resources-convert → a2h-resource-convert}/references/dependency-analysis-rules.md

@@ -93,6 +93,27 @@ Resource references can appear in several places within Android XML files:
 <color name="margin_double">@dimen/margin_base</color>
 ```
 
+### Lottie-Specific Reference Patterns (Extended)
+
+Lottie asset references do NOT use the generic `@type/name` syntax and are not caught by the reference regex above. They need their own extraction pass — see `references/lottie-conversion-rules.md` for the full rules. Summary:
+
+**XML attribute patterns** (namespace prefix varies; match by local name only):
+
+| Attribute | Points at | Migration classification |
+|---|---|---|
+| `lottie_fileName="Xxx.json"` | Assets-relative path under `assets/` | Local Lottie asset — migrate to `rawfile/lottie/<normalized>.json` |
+| `lottie_rawRes="@raw/name"` | `res/raw/name.json` | Local Lottie asset — migrate to `rawfile/lottie/<normalized>.json` |
+| `lottie_url="https://..."` | Runtime URL | Remote resource — no local target |
+| `lottie_fallbackRes="@drawable/xxx"` | Fallback drawable | Handled by normal drawable rules; note the association in the Lottie row |
+
+**Code patterns** (Kotlin/Java):
+
+- Literal string / resource id arg to `LottieCompositionFactory.fromAsset(...)`, `.fromRawRes(...)`, `.fromJsonInputStream(...)`, `.fromUrl(...)`, or to `LottieAnimationView.setAnimation(...)`.
+- `AssetManager.list(...)` results filtered by `.json` and dispatched to any factory method above — the "dynamic picker" pattern. Attribute the listed JSONs to the **detail screen** navigated to by the picker's click handler, not the picker itself.
+- `CompositionArgs`-style data classes carrying `assetName` / `fileUri` / `url` fields consumed by a factory method — resolve to the actual factory call site.
+
+**Host-screen binding.** For each Lottie asset, additionally record the Activity/Fragment that plays it (evidence: layout inflation, factory call site, or picker navigation target). This host attribution is required by `references/lottie-conversion-rules.md` and is consumed by the mapping document.
+
 ## Screen and Source Attribution Support
 
 Use dependency analysis not only to resolve resources, but also to collect evidence for the mapping markdown.
@@ -294,7 +315,8 @@ Layout and menu files are **not** converted to HarmonyOS (they use ArkUI instead
 
 ### Skip (no meaningful dependencies)
 
-- Raw files (`raw/`)
+- Raw files (`raw/`) — **except** when the file is a Lottie animation JSON (identified by signature `v`+`fr`+`ip`+`op`+`layers`), which must be recorded per `references/lottie-conversion-rules.md`. The Lottie JSON itself has no `@type/name` references to resolve, but it must be inventoried and bound to a host screen.
+- `assets/` — same rule: skip generic files, but detect and record Lottie JSON.
 - Font files (`font/`) — unless font XML family definitions reference other fonts
 - Image files (PNG, JPG, WEBP, etc.) — binary files, no references
 
@@ -330,7 +352,7 @@ When a dependency is satisfied, also verify qualifier coverage. If the dependent
 
 ## Handling Missing Library Resources
 
-When converting from source `res/` (because the APK build failed or no APK was available), library-provided resources will be absent from the lookup table. This section describes how to handle these gaps gracefully.
+When converting from source `res/` (because decoding `apk_path` failed), library-provided resources will be absent from the lookup table. This section describes how to handle these gaps gracefully.
 
 ### Identifying Library Resources
 

package/skills/a2h-resource-convert/references/lottie-conversion-rules.md

@@ -0,0 +1,219 @@
+# Android to HarmonyOS Lottie Animation Conversion Rules
+
+This document defines how to migrate Lottie animation resources from an Android project to a HarmonyOS project that uses `@ohos/lottie`. Read this before converting any Lottie animation. Every Lottie resource observed during conversion must produce an inventory row and a mapping row per the rules in `references/resource-mapping-rules.md`.
+
+## Table of Contents
+1. [Scope and Runtime Context](#scope-and-runtime-context)
+2. [How to Identify a Lottie JSON File](#how-to-identify-a-lottie-json-file)
+3. [Source Locations in an Android Project](#source-locations-in-an-android-project)
+4. [Target Path in the HarmonyOS Project](#target-path-in-the-harmonyos-project)
+5. [Filename Normalization](#filename-normalization)
+6. [Extracting Lottie References from Android Code](#extracting-lottie-references-from-android-code)
+7. [Binding Each Lottie JSON to a HarmonyOS Page](#binding-each-lottie-json-to-a-harmonyos-page)
+8. [Unmappable / Deferred Cases](#unmappable--deferred-cases)
+9. [Report and Mapping Requirements](#report-and-mapping-requirements)
+
+---
+
+## Scope and Runtime Context
+
+On HarmonyOS the animation library is `@ohos/lottie` (installed via `ohpm install @ohos/lottie`). The JSON files are consumed at runtime via `lottie.loadAnimation({ path: 'lottie/animation.json', ... })`, where `path` is resolved under `<ui_module>/src/main/resources/rawfile/`. This skill handles **only** the JSON asset migration and its reference bookkeeping — it does NOT generate ArkTS UI code. The developer rewrites the hosting screen(s) in ArkUI and calls `@ohos/lottie` from that screen using the paths this skill produced.
+
+## How to Identify a Lottie JSON File
+
+The `.json` extension is not enough on its own — HarmonyOS projects can contain unrelated JSON. A file is a Lottie animation JSON if and only if its parsed root object contains **all** of the following top-level fields:
+
+| Field | Meaning |
+|---|---|
+| `v` | Bodymovin exporter version, e.g. `"5.7.4"` |
+| `fr` | Frame rate, number |
+| `ip` | In-point (start frame), number |
+| `op` | Out-point (end frame), number |
+| `w` | Composition width, number |
+| `h` | Composition height, number |
+| `layers` | Array of layer objects |
+
+If a JSON file has this signature, treat it as a Lottie animation regardless of the directory it lives in. If a JSON file is missing any of these fields, do not classify it as a Lottie asset; process it under the ordinary rules for its host directory (e.g., a raw JSON config in `res/raw/` follows the raw-file rules).
+
+If a file cannot be parsed as JSON (broken, binary), record it as an inventory row with `Status = failed to parse` and `mapping_kind = failed conversion`.
+
+## Source Locations in an Android Project
+
+Android projects place Lottie JSON in one of two directories. This skill scans both:
+
+| Android Location | Access Pattern in Android | Example |
+|---|---|---|
+| `app/src/main/assets/` (recursive) | `AssetManager.open(...)`, `LottieCompositionFactory.fromAsset(context, "AndroidWave.json")` | `assets/AndroidWave.json`, `assets/lottie/checkmark.json` |
+| `app/src/main/res/raw/` | `R.raw.name`, `LottieCompositionFactory.fromRawRes(context, R.raw.lottielogo)` | `res/raw/lottielogo.json` |
+
+`assets/` is a passthrough directory in APK decoding (unlike `res/`), so its files stay under `<decoded_output_path>/assets/` after decoding. Scan both `<decoded_output_path>/assets/` and `<decoded_output_path>/res/raw/` (or the source-fallback equivalents `app/src/main/assets/` and `app/src/main/res/raw/`).
+
+When multi-module: scan every module's `src/*/assets/` and `src/*/res/raw/`, including flavor source sets (`src/debug/`, `src/<flavor>/`).
+
+## Target Path in the HarmonyOS Project
+
+All migrated Lottie animations land under a dedicated subdirectory of `rawfile/`:
+
+```
+<ui_module>/src/main/resources/rawfile/lottie/<name>.json
+```
+
+- The `lottie/` subdirectory keeps them separate from unrelated raw assets and matches the load-path convention used by `@ohos/lottie` examples (`path: 'common/lottie/animation.json'` style paths).
+- Preserve the base filename (after normalization — see below). Discard any Android source subdirectory. If a project has `assets/animations/wave.json`, the target is still `rawfile/lottie/wave.json`.
+- The load path recorded in the mapping document (for the developer to feed into `lottie.loadAnimation({ path: ... })`) is `lottie/<name>.json` — relative to `rawfile/`, no leading slash.
+
+**Filename collision handling.** If two source files would normalize to the same target filename (e.g., `assets/logo.json` and `res/raw/logo.json` both target `lottie/logo.json`), disambiguate by prefixing the source category: `lottie/assets_logo.json` and `lottie/raw_logo.json`. Record both original paths in the mapping row's `notes`.
+
+## Filename Normalization
+
+HarmonyOS resource filenames must be all-lowercase, use only `[a-z0-9_]` in the base name, and only one `.` before the extension. Apply the following transforms to every Lottie source filename:
+
+1. Strip the `.json` extension, transform the base name, then reattach `.json`.
+2. Replace whitespace and any character in `[^a-zA-Z0-9_]` with `_`.
+3. Collapse consecutive `_` into a single `_`.
+4. Trim leading/trailing `_`.
+5. Lowercase the entire base name.
+6. If the base name starts with a digit after normalization, prefix with `lottie_`.
+
+Examples:
+
+| Android source filename | Normalized target under `rawfile/lottie/` |
+|---|---|
+| `AndroidWave.json` | `androidwave.json` |
+| `HamburgerArrow.json` | `hamburgerarrow.json` |
+| `Lottie Logo 1.json` | `lottie_logo_1.json` |
+| `Lottie Logo 2.json` | `lottie_logo_2.json` |
+| `lottielogo.json` (from `res/raw/`) | `lottielogo.json` |
+| `01-intro.json` | `lottie_01_intro.json` |
+
+When a filename is renamed, record the rename in the mapping row's `notes` (`renamed from "Lottie Logo 1.json"`) and — if the reference is code-loaded via a literal string in Kotlin/Java — flag it in the report so the developer updates the code.
+
+## Extracting Lottie References from Android Code
+
+Lottie assets are wired to Android screens through three attribute-based reference patterns (in XML) plus a code-loaded pattern (in Kotlin/Java). Extend the reference-scanning defined in `references/dependency-analysis-rules.md` with the patterns below.
+
+### XML attribute references
+
+Namespace prefix varies (`app:`, `airbnb:`, custom bindings) — match by local name.
+
+| Attribute | Reference target | Notes |
+|---|---|---|
+| `lottie_fileName` | Filename under `assets/` (e.g., `"AndroidWave.json"`) | Treat the string value as an assets-relative path. Match to the migrated `rawfile/lottie/<normalized>.json`. |
+| `lottie_rawRes` | `@raw/<name>` | Match `<name>.json` inside `res/raw/`. The migrated target is `rawfile/lottie/<normalized>.json`. |
+| `lottie_url` | Runtime URL string | No local file to migrate. Mark the reference as **remote** — `mapping_kind = remote resource (no local target)` and `source_category = 运行时远程资源`. Record the URL in `notes`. |
+| `lottie_fallbackRes` | `@drawable/<name>` | Not a Lottie asset — falls under the normal drawable rules. Note the association in the Lottie row's `notes` because it is the fallback shown when the animation fails. |
+
+For each XML reference, record the host layout file. That is the input to page binding (next section).
+
+### Code-loaded Lottie
+
+Some apps load Lottie JSON purely from code, including scanning `assets/` at runtime with `AssetManager.list("")`. Detection heuristics:
+
+1. String literal ending in `.json` passed to `LottieCompositionFactory.fromAsset(...)`, `.fromRawRes(...)`, `.fromJsonInputStream(...)`, `.fromUrl(...)`, or to `LottieAnimationView.setAnimation(...)`.
+2. `AssetManager.list(...)` results filtered by `.json` and passed into any of the factory methods above — this is the "dynamic dialog listing all assets" pattern (see `PreviewFragment` in the airbnb `lottie-android` sample).
+3. Any `CompositionArgs`-like data class carrying an `assetName` / `fileUri` / `url` field consumed by a factory method.
+
+For every code-loaded reference:
+- If the source file is `assets/*.json` or `res/raw/*.json` → treat exactly like an XML reference in terms of migration (copy to `rawfile/lottie/<normalized>.json`).
+- If the source is a URL or a user-picked file URI → mark as runtime remote resource, no local target.
+- Record the Kotlin/Java source file and, if identifiable, the containing Activity/Fragment for page binding.
+
+### Extending the reference table
+
+Add the Lottie patterns above to whatever reference-extraction pipeline the skill runs. They are not covered by the generic `@type/name` regex in `references/dependency-analysis-rules.md`, so they need their own passes:
+
+1. XML pass: for every layout / view XML file, extract every attribute whose local name matches `^lottie_(fileName|rawRes|url|fallbackRes)$`. Value handling is as described above.
+2. Code pass: grep the project's Kotlin/Java sources for the factory method names listed above and, for each hit, capture the argument (literal filename, resource id, or URL) plus the enclosing class name.
+
+## Binding Each Lottie JSON to a HarmonyOS Page
+
+The whole point of the mapping report is telling the HarmonyOS developer **which screen in the new project plays which animation**. For every Lottie JSON, produce a *host* attribution using the same evidence sources as the standard screen-attribution rules (`references/resource-mapping-rules.md` §6, `references/dependency-analysis-rules.md` "Screen Attribution"), plus these Lottie-specific rules:
+
+### Attribution priority
+
+1. **XML host layout → hosting Activity/Fragment.**
+   - Find the layout XML(s) that reference the JSON via `lottie_fileName` / `lottie_rawRes`.
+   - Walk backward: which Activity/Fragment inflates that layout? Evidence includes `setContentView(R.layout.<name>)`, `AppCompatActivity(R.layout.<name>)` constructor form, `BaseFragment(R.layout.<name>)` / `Fragment.onCreateView` returning `R.layout.<name>`, and DataBinding/ViewBinding class names derived from the layout.
+   - Record `<Activity/Fragment class name>` in the `Host Activity/Fragment` column and `<layout file>` in `notes`.
+
+2. **Code-loaded (literal filename in factory call).**
+   - Take the enclosing class as the host. If the class is a ViewModel or repository (not a screen), walk one hop up to the Fragment/Activity that observes it.
+
+3. **Code-loaded (dynamic list from `AssetManager`).**
+   - This is the "preview / picker" pattern where the animation is rendered on whatever detail screen the user navigates to. Attribute every listed JSON to that **detail screen** (the target of the `startActivity` call from the picker), not the picker itself. The picker is the browser; the detail screen is the actual host.
+   - Example (from the airbnb `lottie-android` sample): `PreviewFragment` lists `assets/*.json` in an `AlertDialog` and calls `PlayerActivity.Companion.intent(context, CompositionArgs(asset = <name>))`. Attribute all listed JSONs to `PlayerActivity` (which in turn hosts `PlayerFragment` with the `LottieAnimationView`).
+
+4. **Manifest / global.**
+   - If the JSON is loaded from `Application.onCreate`, a splash screen, or shared UI (nav header, tab bar), attribute to `Global` or `Launcher` per the shared-component / global rules in `resource-mapping-rules.md`.
+
+5. **Fallback.**
+   - If no evidence exists, use `Unknown` and mention the reason in `notes` (e.g., "loaded via runtime string from unrecognized code path").
+
+### Suggested HarmonyOS Page
+
+Alongside the Android host, propose a HarmonyOS page name so the developer knows where to place the `@ohos/lottie` call. Use these rules:
+
+- Strip the `Activity` / `Fragment` suffix and append `Page`. Examples: `PlayerActivity` → `PlayerPage`, `PlayerFragment` → `PlayerPage`, `LoginActivity` → `LoginPage`.
+- Multiple hosts collapse to one page if they share the same base name (Activity + Fragment pair for the same screen).
+- `Launcher` → `EntryAbility` (or the equivalent entry ability of the HarmonyOS project).
+- `Global` → `App` / global scope.
+- `Unknown` → `Unknown`.
+
+This is a **suggestion column** — the mapping row's `notes` should say `HarmonyOS page name inferred from Android host; verify against actual ArkUI pages`.
+
+## Unmappable / Deferred Cases
+
+Record each of these with an explicit `mapping_kind` and keep the inventory row, never silently drop:
+
+| Case | `mapping_kind` | Notes |
+|---|---|---|
+| `lottie_url="https://..."` | `remote resource (no local target)` | HarmonyOS Target = `N/A`. Developer must fetch and re-render at runtime. |
+| JSON referenced only by a runtime `Uri` from a file picker (`Intent.ACTION_GET_CONTENT`) | `remote resource (no local target)` | HarmonyOS Target = `N/A`. Developer handles user-provided files with the equivalent Picker API. |
+| JSON present in `assets/` but not referenced anywhere in XML or code (dead asset) | `direct copy` still applies | Migrate anyway, mark screens = `Unknown`, note "no static references found — possibly loaded via string concatenation or dead asset". |
+| JSON exists but fails Lottie signature check (missing `v`/`fr`/`layers` etc.) | `unmappable` | HarmonyOS Target = `N/A`. Notes: "JSON in assets/raw is not a valid Lottie composition; falls back to raw-file rules". |
+| Lottie with embedded image assets (`images` field pointing to external files) | `direct copy` for the JSON + `direct copy` for each referenced image | Copy images alongside the JSON under `rawfile/lottie/images/<name>` (preserve relative structure declared by the Lottie `imagePath`). Record each image as its own inventory + mapping row. |
+| Lottie referenced by `lottie_fallbackRes` only (used as fallback for another animation) | `direct copy` | Attribute to same host as the primary animation. Mention "fallback for @drawable/xxx or another JSON" in notes. |
+
+## Report and Mapping Requirements
+
+### Standard conversion report (Step 7)
+
+Add a dedicated section:
+
+```
+### Lottie Animation Resources
+Every Lottie JSON detected in the project (via structure signature) and where it maps in HarmonyOS.
+
+| Android Source | Target Rawfile Path | Host Activity/Fragment | Host Layout | HarmonyOS Page (suggested) | Notes |
+|---|---|---|---|---|---|
+| assets/AndroidWave.json | rawfile/lottie/androidwave.json | (none — XML host only) | res/layout/dynamic_activity.xml | DynamicPage | XML host inflated by DynamicActivity (inferred) |
+| assets/Lottie Logo 1.json | rawfile/lottie/lottie_logo_1.json | PlayerActivity (via PreviewFragment picker) | N/A | PlayerPage | Renamed from "Lottie Logo 1.json" (spaces stripped). Loaded via AssetManager.list() in PreviewFragment; picker dispatches to PlayerActivity. |
+| ... | ... | ... | ... | ... | ... |
+```
+
+Also add these summary counters to the "Summary" section:
+- `Total Lottie animations found: <count>`
+- `Migrated to rawfile/lottie/: <count>`
+- `Remote / URL Lottie (no local target): <count>`
+- `Filename collisions disambiguated: <count>`
+
+### Mapping markdown (Step 8)
+
+- Every Lottie JSON is one inventory row and at least one mapping row.
+- Inventory row: `type_category = raw` (Lottie JSON lives under Android `assets/` or `res/raw/`, both of which normalize to Harmony's `rawfile/`). Explain the Lottie subtype in `notes` (`Lottie animation JSON`).
+- Mapping row `harmony_target` values:
+  - Local migration → `<ui_module>/src/main/resources/rawfile/lottie/<normalized>.json`
+  - Remote / URL / user-picked → `N/A` with `mapping_kind = remote resource (no local target)`
+- Mapping row `mapping_kind`:
+  - `direct copy` — for a straight assets/raw → rawfile move
+  - `rename` — used **in addition to** `direct copy` when the filename was normalized (emit as a second mapping row or record both in `notes`; the simpler option is one row with `mapping_kind = direct copy` and a `notes` entry `renamed from "<original>"`)
+  - `remote resource (no local target)` — URL / picker cases
+  - `unmappable` — JSON that fails the Lottie signature check
+- Every Lottie mapping row MUST populate the Host Activity/Fragment (via `notes` if the mapping template does not have a dedicated column) and the suggested HarmonyOS page so the developer can wire the `@ohos/lottie` call to the correct ArkUI page.
+- If the mapping markdown template supports extra columns, add `Host Activity/Fragment` and `Suggested HarmonyOS Page` columns to the Lottie section. Otherwise, put both facts in `notes` in the format `host=<class>; page=<PageName>`.
+
+### Cross-check during Step 6 verification
+
+- Verify every migrated Lottie file is present under `rawfile/lottie/` in the HarmonyOS output.
+- Verify every `lottie_fileName` / `lottie_rawRes` reference discovered in XML has a corresponding entry in the report's Lottie table.
+- If `harmony_project_dir` already contains ArkTS code and any `.ets` file already calls `lottie.loadAnimation({ path: 'lottie/xxx.json' })`, verify the file exists at `rawfile/lottie/xxx.json`. If missing, do **not** create a placeholder SVG (that's the drawable rule) — instead log it prominently as an unresolved Lottie reference so the developer can either drop in the JSON manually or fix the path.