android2harmony 0.1.3 → 0.1.5

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

@@ -310,6 +310,17 @@ Recommended fallback in `notes`:
 - `Original Android type: raw`
 - `Original Android type: menu`
 
+### 8.4 Lottie Animation Special Case
+
+Lottie JSON files live under Android `assets/` (passthrough) or `res/raw/` (raw type). Both normalize to HarmonyOS `rawfile/`. Record them with `type_category = raw` and identify the Lottie subtype in `notes` (`Lottie animation JSON`). Do NOT invent a new top-level `lottie` type category.
+
+For each Lottie row:
+- `source_category` follows the normal rules. Local Lottie under app/module `assets/` or `res/raw/` → `应用自身资源` or `项目内模块资源`. Runtime URL (`lottie_url` or code loading a `Uri`) → `运行时远程资源`.
+- `screens` MUST identify the Activity/Fragment that plays the animation, using the evidence sources listed in `references/lottie-conversion-rules.md` (XML host layout → hosting Activity/Fragment, factory-call enclosing class, or picker navigation target). The `Screens` value is the Android host; the proposed HarmonyOS page name goes into `notes` as `page=<PageName>` (or into an optional `Suggested HarmonyOS Page` column if the mapping template exposes one).
+- `function` should describe the animation's role, e.g. `Refresh loading animation`, `Splash intro animation`, `Wave background animation`.
+
+See `references/lottie-conversion-rules.md` for the complete Lottie handling rules.
+
 ---
 
 ## 9. Mapping Kind Rules
@@ -321,6 +332,7 @@ Suggested `mapping_kind` values:
 - `layered-image conversion`
 - `generated media`
 - `merged into json`
+- `lottie migration` — Lottie JSON copied from Android `assets/` or `res/raw/` to `rawfile/lottie/<normalized>.json`. Use in place of plain `direct copy` for Lottie assets so the row is easy to filter.
 - `unmappable`
 - `fallback applied`
 - `placeholder created`
@@ -336,7 +348,7 @@ Use the simplest accurate label.
 ### 10.1 One-to-One
 
 Example:
-- `res/drawable/home_login_btn.png` → `entry/src/main/resources/base/media/home_login_btn.png`
+- `res/drawable/home_login_btn.png` → `<ui_module>/src/main/resources/base/media/home_login_btn.png`
 
 Emit one mapping row.
 
@@ -389,7 +401,7 @@ Include bullets for:
 - `harmony_project_dir` (HarmonyOS project output path)
 - Resource source
 - Resource source path
-- Build result
+- Decode result
 - Generation timestamp
 
 ### 11.3 Android Resource Inventory
@@ -425,6 +437,19 @@ Include a compact summary table or grouped bullets covering:
 - library-only resources inferred from dependencies or APK
 - runtime remote resources
 
+### 11.5.1 Lottie Animation Table
+
+If the project contains any Lottie animation JSONs (identified by structure signature per `references/lottie-conversion-rules.md`), include a dedicated table listing every detected animation. Required columns:
+
+- `Android Source` — full path (e.g., `assets/AndroidWave.json`, `res/raw/lottielogo.json`, or `(remote) https://...`)
+- `Target Rawfile Path` — `rawfile/lottie/<normalized>.json` or `N/A`
+- `Host Activity/Fragment` — the Android class that plays the animation (or `Global` / `Launcher` / `Unknown`)
+- `Host Layout / Loader` — the layout XML with `lottie_fileName` / `lottie_rawRes`, or the Kotlin/Java call site
+- `Suggested HarmonyOS Page` — proposed ArkUI page name (e.g., `PlayerPage`)
+- `Notes` — rename records, collision disambiguation, remote URL, or "no static references found"
+
+This is the audit surface used by the HarmonyOS developer to wire `@ohos/lottie` calls to the correct pages. Never omit a detected Lottie asset from this table.
+
 ### 11.6 Quick Findings
 
 Provide short bullets highlighting review-relevant findings, such as:

package/skills/{hmos-resources-convert → a2h-resource-convert}/references/xml-drawable-to-svg-rules.md

@@ -161,6 +161,65 @@ Only include transform components that differ from defaults (translate 0,0; scal
 
 Generate unique IDs for clip paths (e.g., `clip_1`, `clip_2`, or derive from `android:name`).
 
+#### `clip-path` is geometry, not decoration — it is mandatory
+
+A `<clip-path>` changes the **position, size, and visible extent** of every sibling path in its
+group. Dropping it does not degrade the icon slightly; it renders a different shape. Two forms
+both occur in real icon sets and **both must be preserved**:
+
+| Form | Example | Effect if dropped |
+|---|---|---|
+| Full-viewport clip | `M0 0hWvHz` where `W`/`H` equal `viewportWidth`/`viewportHeight` | Visually equivalent, but do not use "it looks full-size" as licence to skip clips in general — verify the numbers first |
+| **Sub-region clip** | clip origin or extent differs from the viewport | Geometry breaks. Two sub-cases are especially damaging: (a) the artwork occupies only part of the viewport, so the icon lands at the wrong offset and scale; (b) the path deliberately **floods the whole viewport** and relies on the clip to cut the visible figure out of it — dropping the clip yields a solid filled rectangle |
+
+Case (b) is worth calling out because the path data alone looks like a plain background
+rectangle; nothing about the `<path>` element hints that a clip is load-bearing. Never decide a
+clip is redundant by reading the path — compare the clip's bounds against the viewport.
+
+**Self-check after emitting each `<vector>`-derived SVG** (do not defer this to a later step):
+
+1. count of `<clip-path>` in the Android source == count of `<clipPath>` in the SVG
+2. every path that sat inside a clipped `<group>` carries `clip-path="url(#…)"`
+3. each `clipPath` `id` referenced actually exists in `<defs>`
+
+If any check fails, fix the SVG before moving to the next file.
+
+---
+
+## Vector Fidelity Checklist
+
+Run this per `<vector>`-derived SVG before considering the file converted. It is the `<vector>`
+counterpart to the ShapeDrawable rules below, and it exists because **a file that exists and
+parses can still be visually wrong** — existence checks cannot catch any of the items here.
+
+| # | Check | Failure signature |
+|---|---|---|
+| 1 | `clip-path` count preserved; clipped paths reference their `clipPath` | Icon offset/scaled wrong, or a solid rectangle where a figure was expected |
+| 2 | `fill` follows the three-branch rule (`fill="none"` for stroke-only paths) | Outline icon renders as a solid blob |
+| 3 | All `stroke*` attributes carried over (`stroke`, `stroke-width`, `-linecap`, `-linejoin`, `-miterlimit`, `-opacity`) | Outline too thin/thick, or corners/caps visibly wrong |
+| 4 | `viewportWidth`/`viewportHeight` == `viewBox="0 0 W H"`; `width`/`height` carried from `android:width/height` | Whole icon scaled or cropped |
+| 5 | `<group>` transforms emitted in order translate → scale → rotate, with pivot preserved | Artwork rotated about the wrong point or displaced |
+| 6 | `fillType="evenOdd"` → `fill-rule="evenodd"` | Holes in the shape fill in (donuts become discs) |
+| 7 | `#AARRGGBB` split into color + `fill-opacity`/`stroke-opacity` | Opaque where it should be translucent |
+| 8 | Inline `<aapt:attr name="android:fillColor"><gradient>` → `<defs><linearGradient\|radialGradient>` + `fill="url(#id)"` | Gradient collapses to a flat color — and because the `<path>` carries no `fillColor` *attribute*, a converter that ignores `aapt:attr` typically falls back to the black default, so the shape turns solid black |
+
+Item 8 deserves attention because the gradient lives in a **child element**, not an attribute. Any
+converter that only reads `<path>` attributes sees a path with no `fillColor` and takes the default
+branch. Treat `<aapt:attr>` children as a fill source on equal footing with the attribute form.
+
+Item 8 has a second form that only shows up in a **compiled** APK, which is exactly what this skill
+converts. At build time aapt hoists the inline `<gradient>` out into its own drawable resource and
+leaves behind an ordinary attribute: `android:fillColor="@drawable/$icon__0"`, decoding to a file
+`res/drawable*/_icon__0.xml` whose root is `<gradient>` (`$` is written as `_`). Here the attribute
+*is* present, so the `aapt:attr` branch never fires; the reference simply fails to resolve as a color
+and the path falls back to black. Follow the reference into the drawable and build the gradient from
+it — search the unqualified `drawable/` first, then any `drawable-*` directory. When the hoisted
+gradient's own stops are unresolvable (framework dynamic colors such as `@android:0106xxxx`), the
+black fallback is correct, but it must still be recorded as an unresolved paint.
+
+Record any file that fails a check in the conversion report rather than silently re-emitting it,
+so the same defect is not reintroduced on the next run.
+
 ---
 
 ## ShapeDrawable Conversion
@@ -488,10 +547,68 @@ Convert the gradient to an SVG `<linearGradient>` in `<defs>` and reference via
 ### Default Values
 
 If an Android drawable doesn't specify certain attributes, use these defaults:
-- `fillColor`: `#000000` (black) for paths in `<vector>`, transparent for shapes without `<solid>`
 - `strokeWidth`: `0` (no stroke)
 - `alpha`: `1.0`
 - `fillType`: `nonZero`
+- `fillColor`: see the three-branch rule below — **never blanket-default it to black**
+
+#### `fill` on `<path>`: three branches, decided per path
+
+An omitted `android:fillColor` does **not** always mean black. Because SVG's own `fill`
+default *is* black, writing `fill="#000000"` where Android meant "no fill" silently turns a
+stroke-only outline into a solid black blob. Decide per `<path>`:
+
+| Android `<path>` has | Emit | Why |
+|---|---|---|
+| `fillColor` (with or without `strokeColor`) | `fill="<converted color>"` | Explicit fill; convert per the color-format table |
+| **no `fillColor`, but has `strokeColor`** | **`fill="none"`** (required, explicit) | Stroke-only geometry. Omitting `fill` — or worse, emitting `fill="#000000"` — fills the outline solid |
+| neither `fillColor` nor `strokeColor` | `fill="#000000"` | Matches the Android platform default for an otherwise unpainted path |
+
+Rule of thumb: in SVG, *omitting* `fill` and *writing black* are equivalent, so `fill="none"`
+must be emitted **explicitly** for stroke-only paths. This applies per path, not per file — one
+`<vector>` may legitimately mix filled and stroke-only paths.
+
+Icons built as "white/colored outline on transparent background" are the common case that this
+branch protects; they are widespread in Material-style icon sets, so a blanket black default
+tends to corrupt many files at once rather than just one.
+
+**MANDATORY STROKE-ONLY DETECTION (runtime, not static check):**
+
+After converting each `<vector>` to SVG, run this detection **before writing the file**:
+
+```javascript
+function checkStrokeOnlyPaths(svgContent, filename) {
+  // Parse all <path> elements
+  const pathRegex = /<path[^>]*>/g;
+  const paths = svgContent.match(pathRegex) || [];
+  
+  for (const pathTag of paths) {
+    const hasStroke = /stroke=["'](?!none)[^"']+/.test(pathTag);
+    const hasFill = /fill=["'](?!none)[^"']+/.test(pathTag);
+    
+    // ERROR: stroke-only path without explicit fill="none"
+    if (hasStroke && !hasFill) {
+      return {
+        severity: 'error',
+        file: filename,
+        issue: 'STROKE_ONLY_WITHOUT_FILL_NONE',
+        evidence: `Path has stroke="${pathTag.match(/stroke=["']([^"']+)/)?.[1]}" but no fill attribute`,
+        fix: 'Add fill="none" explicitly to this <path> element'
+      };
+    }
+  }
+  
+  return null; // Pass
+}
+```
+
+**Why this check is mandatory:**
+- A stroke-only path *without* `fill="none"` inherits SVG's default `fill="black"`, rendering as a solid blob instead of an outline
+- This defect is invisible to existence checks (the file exists and parses correctly)
+- It only surfaces at runtime when the icon renders incorrectly
+- The three-branch rule above states the requirement; this check enforces it mechanically
+
+**Integration point:** This check must run in the same loop that generates the SVG files, not as a separate pass. If it returns an error object, DO NOT write that SVG file — fix the conversion and re-check until it returns `null`.
 
 ---