# Component support / Suporte a componentes

## File and protocol scope

- ZIP project interchange only; binary files are handled by the external editor.
- Type C: project.json preferred; watchface.txt fallback supported.
- FaceN: watchface.json, API35, 240x240, reserved header 0xFFFF.
- Native FaceN API1 and other unknown APIs are rejected; versions are not relabelled.
- Sending requires a compatible Jieli template76 / device API53 functions3 family.
- Existing 16 collection variants remain byte-identical to the reference converter.
- Software checks and BLE simulation do not confirm appearance on every firmware.

## Newly supported paths

- Type C AM/PM (0x45/0x46) converts to native record17.
- Type C seconds tens/units (0x47/0x48) converts to native record24.
  Both remain dynamic; the preview uses sample values. Raw digit glyphs,
  coordinates, independent fonts and layer order are preserved.
  Only adjacent complementary layers are merged. A missing peer is transparent.
  Preview defaults to 12-hour display when AM/PM exists; the render API accepts
  `hour12: false` for a 24-hour sample. Actual watch time mode is firmware-controlled.

- Native FaceN ZIP import, including filled battery (type5), battery digits (21),
  temperature (28), month names (14), metadata (29), and both weekday subtypes.
- Variable-size native progress bars and weather image sets preserve following
  record offsets; they no longer assume exactly11 or9 images respectively.
- Type C split background (0x00) converts into ten positioned images.
- Chinese weekday set (0x61) preserves its own supplied glyphs.
- KM/MI static label assets (0xA5/0xA6) are retained as supplied.
- Legacy TXT ZIPs retain layer order and all referenced BMP assets.

## Remaining firmware mapping limits

Type C year, Bluetooth status, distance, distance progress, steps goal,
animations/tap-to-change and the ambiguous digit code 0x69 do not yet have a
confirmed mapping to the target API35 records. Known roles can be previewed;
ambiguous digit roles are reported. Any of these fields blocks sending of the
whole project; no element is silently omitted, baked into a screenshot or
assigned an invented opcode. Physical samples/documentation are needed to
complete those mappings. This update does not claim universal component support.

## Type C matrix

| Code | Role | Preview | Send to API35 |
| --- | --- | --- | --- |
| `0x00` | BACKGROUNDS | Sample values / frame0 for animation | Supported |
| `0x01` | BACKGROUND | Sample values / frame0 for animation | Supported |
| `0x10` | MONTH_NAME | Sample values / frame0 for animation | Supported |
| `0x11` | MONTH_NUM | Sample values / frame0 for animation | Supported |
| `0x12` | YEAR | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0x30` | DAY_NUM | Sample values / frame0 for animation | Supported |
| `0x40` | TIME_H1 | Sample values / frame0 for animation | Supported |
| `0x41` | TIME_H2 | Sample values / frame0 for animation | Supported |
| `0x43` | TIME_M1 | Sample values / frame0 for animation | Supported |
| `0x44` | TIME_M2 | Sample values / frame0 for animation | Supported |
| `0x45` | TIME_AM | Sample AM/PM | Supported |
| `0x46` | TIME_PM | Sample AM/PM | Supported |
| `0x47` | SECONDS_TENS | Sample seconds | Supported |
| `0x48` | SECONDS_UNITS | Sample seconds | Supported |
| `0x60` | DAY_NAME | Sample values / frame0 for animation | Supported |
| `0x61` | DAY_NAME_CN | Sample values / frame0 for animation | Supported |
| `0x62` | STEPS | Sample values / frame0 for animation | Supported |
| `0x63` | STEPS_CA | Sample values / frame0 for animation | Supported |
| `0x64` | STEPS_RA | Sample values / frame0 for animation | Supported |
| `0x65` | HR | Sample values / frame0 for animation | Supported |
| `0x66` | HR_CA | Sample values / frame0 for animation | Supported |
| `0x67` | HR_RA | Sample values / frame0 for animation | Supported |
| `0x68` | KCAL | Sample values / frame0 for animation | Supported |
| `0x69` | DIGIT_69 | Unavailable: role not established | Blocked: mapping not confirmed |
| `0x6B` | MONTH_NUM_B | Sample values / frame0 for animation | Supported |
| `0x6C` | DAY_NUM_B | Sample values / frame0 for animation | Supported |
| `0x70` | STEPS_PROGBAR | Sample values / frame0 for animation | Supported |
| `0x71` | STEPS_LOGO | Sample values / frame0 for animation | Supported |
| `0x72` | STEPS_B | Sample values / frame0 for animation | Supported |
| `0x73` | STEPS_B_CA | Sample values / frame0 for animation | Supported |
| `0x74` | STEPS_B_RA | Sample values / frame0 for animation | Supported |
| `0x76` | STEPS_GOAL | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0x80` | HR_PROGBAR | Sample values / frame0 for animation | Supported |
| `0x81` | HR_LOGO | Sample values / frame0 for animation | Supported |
| `0x82` | HR_B | Sample values / frame0 for animation | Supported |
| `0x83` | HR_B_CA | Sample values / frame0 for animation | Supported |
| `0x84` | HR_B_RA | Sample values / frame0 for animation | Supported |
| `0x90` | KCAL_PROGBAR | Sample values / frame0 for animation | Supported |
| `0x91` | KCAL_LOGO | Sample values / frame0 for animation | Supported |
| `0x92` | KCAL_B | Sample values / frame0 for animation | Supported |
| `0x93` | KCAL_B_CA | Sample values / frame0 for animation | Supported |
| `0x94` | KCAL_B_RA | Sample values / frame0 for animation | Supported |
| `0xA0` | DIST_PROGBAR | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0xA1` | DIST_LOGO | Sample values / frame0 for animation | Supported |
| `0xA2` | DIST | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0xA3` | DIST_CA | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0xA4` | DIST_RA | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0xA5` | DIST_KM | Sample values / frame0 for animation | Supported |
| `0xA6` | DIST_MI | Sample values / frame0 for animation | Supported |
| `0xC0` | BTLINK_UP | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0xC1` | BTLINK_DOWN | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0xCE` | BATT_IMG | Sample values / frame0 for animation | Supported |
| `0xD0` | BATT_IMG_B | Sample values / frame0 for animation | Supported |
| `0xD1` | BATT_IMG_C | Sample values / frame0 for animation | Supported |
| `0xD2` | BATT | Sample values / frame0 for animation | Supported |
| `0xD3` | BATT_CA | Sample values / frame0 for animation | Supported |
| `0xD4` | BATT_RA | Sample values / frame0 for animation | Supported |
| `0xD6` | ICON_SET_D6 | Sample values / frame0 for animation | Supported |
| `0xD7` | WEATHER_TEMP | Sample values / frame0 for animation | Supported |
| `0xD8` | WEATHER_TEMP_CA | Sample values / frame0 for animation | Supported |
| `0xD9` | WEATHER_TEMP_RA | Sample values / frame0 for animation | Supported |
| `0xDA` | BATT_IMG_D | Sample values / frame0 for animation | Supported |
| `0xF0` | SEPERATOR | Sample values / frame0 for animation | Supported |
| `0xF1` | HAND_HOUR | Sample values / frame0 for animation | Supported |
| `0xF2` | HAND_MINUTE | Sample values / frame0 for animation | Supported |
| `0xF3` | HAND_SEC | Sample values / frame0 for animation | Supported |
| `0xF4` | HAND_PIN_UPPER | Sample values / frame0 for animation | Supported |
| `0xF5` | HAND_PIN_LOWER | Sample values / frame0 for animation | Supported |
| `0xF6` | TAP_TO_CHANGE | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0xF7` | ANIMATION | Sample values / frame0 for animation | Blocked: mapping not confirmed |
| `0xF8` | ANIMATION_F8 | Sample values / frame0 for animation | Blocked: mapping not confirmed |

## Native FaceN API35 matrix

| Record type | Component | Status |
| --- | --- | --- |
| 0 | Static image | Import / preview / send |
| 2 | Four-position clock digits | Import / preview / send |
| 4 | Weekday image set, subtypes0/1 | Import / preview / send |
| 5 | Filled battery gauge | Import / preview / send |
| 6 | Heart-rate digits | Import / preview / send |
| 7 | Step digits | Import / preview / send |
| 9 | Calorie digits (API35 record length17) | Import / preview / send |
| 10 | Analog hand | Import / preview / send |
| 13 | Day digits | Import / preview / send |
| 14 | Month names | Import / preview / send |
| 15 | Month digits | Import / preview / send |
| 17 | AM/PM image pair, observed subtype0 | Import / preview / send |
| 18 | Progress image set, data sources0/2/5/6 | Import / preview / send |
| 21 | Battery digits | Import / preview / send |
| 24 | Two-position seconds digits | Import / preview / send |
| 27 | Weather image set | Import / preview / send |
| 28 | Temperature digits, minus/C/F assets | Import / preview / send |
| 29 | Preserved one-byte metadata | Import / preserve / send |
| 35 | Required separator/placeholder | Import / preserve / send |

Native JSON uses the extrathundertool schema for its documented components.
API35 extensions use `month_name`, `battery_num`, `temperature`, `am_pm` and
`seconds_num`. `am_pm` supplies `mode: 0`, two `xys` entries (AM, PM) and two
`img_data` references. `seconds_num` supplies two `digit_sets` and two `xys`
entries (tens, units). These extension names are local schema additions, not
a claim that an upstream editor exports them. A temperature
record supplies `minus`, `celsius`, `fahrenheit` image references, each with
`w`, `h`, `file_name`. Unknown element names, missing assets, invalid dimensions,
unsafe ZIP paths and mismatched CRCs are rejected rather than partially loaded.

See PROTOCOL-TIME.md for byte layouts and the sample evidence behind records17/24.

## Sources and licenses

- https://github.com/david47k/dawft (Type C roles)
- https://github.com/david47k/extrathundertool (FaceN record layout)
- https://github.com/e-labInnovations/dafit-canvas (project ZIP interchange)
- https://pub.dev/packages/moyoung_ble_plugin (BLE capability / upload protocol)
- Reference ZL02CPRO observations and byte-for-byte regression fixtures.

The complete runtime source is unminified in assets/. See LICENSES/NOTICE.txt
and LICENSES/GPL-2.txt. No copy of the external editor or catalogue face assets
is distributed in this package.