expo-harmony-toolkit 1.5.0 → 1.5.2

package/README.en.md

@@ -7,9 +7,9 @@
     <a href="./README.en.md">English</a>
   </p>
   <p>
-    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Plugin/actions/workflows/ci.yml"><img alt="Checks" src="https://img.shields.io/badge/checks-passing-16a34a?style=flat-square&logo=githubactions&logoColor=white"></a>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Toolkit/actions/workflows/ci.yml"><img alt="Checks" src="https://img.shields.io/badge/checks-passing-16a34a?style=flat-square&logo=githubactions&logoColor=white"></a>
     <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-0f766e?style=flat-square"></a>
-    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Plugin/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.5.0-111827?style=flat-square"></a>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Toolkit/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.5.2-111827?style=flat-square"></a>
     <a href="./docs/support-matrix.md"><img alt="Matrix" src="https://img.shields.io/badge/matrix-expo55--rnoh082--ui--stack-2563eb?style=flat-square"></a>
     <img alt="Input" src="https://img.shields.io/badge/input-Managed%2FCNG-059669?style=flat-square">
   </p>
@@ -23,10 +23,10 @@
 </div>
 
 > [!IMPORTANT]
-> `v1.5.0` makes one formal public promise only: `expo55-rnoh082-ui-stack`. This is not a claim that arbitrary Expo applications can be published to HarmonyOS unchanged.
+> `v1.5.2` continues to make one formal public promise only: `expo55-rnoh082-ui-stack`. This is not a claim that arbitrary Expo applications can be published to HarmonyOS unchanged.
 
 > [!TIP]
-> The three validated `@react-native-oh-tpl/*` adapters are currently consumed via exact Git URLs and commits. For repository development and the official UI-stack sample, prefer `pnpm install --ignore-scripts` so adapter prepare hooks do not fail on private upstream resources.
+> The two validated `@react-native-oh-tpl/*` adapters in the public matrix are currently consumed via exact Git URLs and commits. For repository development and the official UI-stack sample, prefer `pnpm install --ignore-scripts` so adapter prepare hooks do not fail on private upstream resources.
 
 ## Overview
 
@@ -46,10 +46,10 @@
 
 | Item | Status |
 | --- | --- |
-| Current version | `v1.5.0` |
+| Current version | `v1.5.2` |
 | Public matrix | `expo55-rnoh082-ui-stack` |
 | Supported input | Managed/CNG Expo projects |
-| Validated JS/UI capabilities | `expo-router`, `expo-linking`, `expo-constants`, `react-native-reanimated`, `react-native-svg`, `react-native-gesture-handler` |
+| Validated JS/UI capabilities | `expo-router`, `expo-linking`, `expo-constants`, `react-native-reanimated`, `react-native-svg` |
 | Build path | `doctor -> init -> bundle -> build-hap` |
 | Primary sample | `examples/official-ui-stack-sample` |
 | Regression baselines | `examples/official-app-shell-sample`, `examples/official-minimal-sample` |
@@ -67,58 +67,121 @@
 
 </details>
 
-## Quick Start
+## Installation
 
-For this repository:
+Published npm package:
 
 ```bash
-pnpm install --ignore-scripts
-pnpm build
-pnpm test
+pnpm add -D expo-harmony-toolkit
+# or
+npm install -D expo-harmony-toolkit
+```
+
+After installation, prefer invoking the CLI through the local project dependency:
+
+```bash
+pnpm exec expo-harmony doctor --project-root .
+# or
+npx expo-harmony doctor --project-root .
 ```
 
-For any Expo project:
+If you are developing inside this repository or running the official UI-stack sample directly, still prefer:
 
 ```bash
-expo-harmony doctor --project-root /path/to/app
-expo-harmony doctor --project-root /path/to/app --strict
-expo-harmony init --project-root /path/to/app
-expo-harmony sync-template --project-root /path/to/app
+pnpm install --ignore-scripts
 ```
 
-Inside the project root:
+This avoids adapter prepare hooks failing on private upstream resources.
+
+## Recommended Plugin Wiring
+
+Add the config plugin to your Expo config so prebuild metadata and CLI-derived Harmony identifiers stay aligned:
+
+```json
+{
+  "expo": {
+    "android": {
+      "package": "com.example.app"
+    },
+    "plugins": [
+      "expo-router",
+      [
+        "expo-harmony-toolkit",
+        {
+          "entryModuleName": "entry"
+        }
+      ]
+    ]
+  }
+}
+```
+
+Notes:
+
+- If `android.package` or `ios.bundleIdentifier` is already set, you usually do not need to pass `bundleName`
+- `entryModuleName` defaults to `entry`; only pin it explicitly when you want to make that choice obvious
+- the toolkit does not auto-install validated UI-stack dependencies; use `doctor --strict` as the real admission gate
+
+## Usage
+
+1. Run the admission check first:
 
 ```bash
 cd /path/to/app
-expo-harmony env --strict
-expo-harmony build-hap --mode debug
+pnpm exec expo-harmony doctor --project-root .
+pnpm exec expo-harmony doctor --project-root . --strict
 ```
 
-If you only need the JavaScript artifact:
+2. Generate or refresh the managed Harmony sidecar:
 
 ```bash
-expo-harmony bundle
+pnpm exec expo-harmony init --project-root .
+pnpm exec expo-harmony sync-template --project-root .
 ```
 
+3. Generate the JavaScript bundle, or continue into Harmony build steps:
+
+```bash
+pnpm exec expo-harmony bundle --project-root .
+pnpm exec expo-harmony env --strict
+pnpm exec expo-harmony build-hap --mode debug
+```
+
+4. For a release build, verify signing first and then run:
+
+```bash
+pnpm exec expo-harmony env
+pnpm exec expo-harmony build-hap --mode release
+```
+
+Common decision points:
+
+- Want to know whether the current project still matches the public matrix: run `doctor --strict`
+- Changed dependencies, Expo config, or plugin wiring: run `sync-template`
+- Only want to verify JavaScript/UI portability: run `bundle`
+- About to open DevEco Studio or build a HAP locally: run `env` first
+
 ## Support Matrix
 
-`v1.5.0` stays on one public matrix: `expo55-rnoh082-ui-stack`.
+`v1.5.2` stays on one public matrix: `expo55-rnoh082-ui-stack`.
 
 - Expo SDK: `55`
-- React: `19.2.x`
-- React Native: `0.83.x`
+- React: `19.1.1`
+- React Native: `0.82.1`
 - RNOH and `@react-native-oh/react-native-harmony-cli`: `0.82.18`
 - App Shell packages: `expo-router`, `expo-linking`, `expo-constants`
-- UI stack packages: `react-native-reanimated`, `react-native-svg`, `react-native-gesture-handler`
+- UI stack packages: `react-native-reanimated`, `react-native-svg`
 - Harmony adapters: the matching `@react-native-oh-tpl/*` exact Git specifiers
 - Native identifier: at least `android.package` or `ios.bundleIdentifier`
 
+`react-native-gesture-handler` is no longer part of the public matrix. It remains a manual exploration path until the current `@react-native-oh-tpl/react-native-gesture-handler` and `@react-native-oh/react-native-harmony@0.82.18` runtime pairing passes on-device validation.
+
 See [docs/support-matrix.md](./docs/support-matrix.md) for the full allowlist, pairing rules, exact specifiers, issue codes, and release gates.
 
 ## Official Samples
 
 - `examples/official-ui-stack-sample`
-  The primary public sample for `v1.5.0`, covering router, linking, constants, SVG, gesture, reanimated, and Harmony sidecar build flow.
+  The primary public sample for `v1.5.0`, covering router, linking, constants, SVG, reanimated, and Harmony sidecar build flow.
 - `examples/official-app-shell-sample`
   The `v1.1` App Shell regression baseline that protects router behavior while UI-stack support is finalized.
 - `examples/official-minimal-sample`
@@ -169,13 +232,14 @@ Automatic publishing defaults to hosted CI only:
 
 - GitHub workflow runs `build/test/pack/tarball smoke`
 - `build-hap --mode debug` does not block npm publish
-- npm publish uses the `latest` dist-tag and provenance
+- GitHub auto-publish uses the `latest` dist-tag and provenance
+- local manual publishing uses the `latest` dist-tag
 
 Manual Harmony acceptance still requires:
 
 - `official-ui-stack-sample` launches successfully
 - SVG renders correctly
-- the gesture triggers visible animation
+- pressing the home-screen motion rail triggers visible animation
 - routing still works after the animation completes
 - `Build Debug Hap(s)` succeeds
 

package/README.md

@@ -7,9 +7,9 @@
     <a href="./README.en.md">English</a>
   </p>
   <p>
-    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Plugin/actions/workflows/ci.yml"><img alt="Checks" src="https://img.shields.io/badge/checks-passing-16a34a?style=flat-square&logo=githubactions&logoColor=white"></a>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Toolkit/actions/workflows/ci.yml"><img alt="Checks" src="https://img.shields.io/badge/checks-passing-16a34a?style=flat-square&logo=githubactions&logoColor=white"></a>
     <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-0f766e?style=flat-square"></a>
-    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Plugin/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.5.0-111827?style=flat-square"></a>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Toolkit/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.5.2-111827?style=flat-square"></a>
     <a href="./docs/support-matrix.md"><img alt="Matrix" src="https://img.shields.io/badge/matrix-expo55--rnoh082--ui--stack-2563eb?style=flat-square"></a>
     <img alt="Input" src="https://img.shields.io/badge/input-Managed%2FCNG-059669?style=flat-square">
   </p>
@@ -23,10 +23,10 @@
 </div>
 
 > [!IMPORTANT]
-> `v1.5.0` 只对 `expo55-rnoh082-ui-stack` 做正式公开承诺。这不是“任意 Expo 项目都能原样发布到 HarmonyOS”的声明，而是对一条受限、可验证矩阵的稳定承诺。
+> `v1.5.2` 继续只对 `expo55-rnoh082-ui-stack` 做正式公开承诺。这不是“任意 Expo 项目都能原样发布到 HarmonyOS”的声明，而是对一条受限、可验证矩阵的稳定承诺。
 
 > [!TIP]
-> 由于当前三套 `@react-native-oh-tpl/*` adapter 依赖以 Git URL + exact commit 形式接入，仓库开发和官方 UI-stack sample 推荐使用 `pnpm install --ignore-scripts`，避免 Git adapter 在 prepare 阶段拉取私有资源而中断安装。
+> 由于当前公开矩阵内的两套 `@react-native-oh-tpl/*` adapter 依赖以 Git URL + exact commit 形式接入，仓库开发和官方 UI-stack sample 推荐使用 `pnpm install --ignore-scripts`，避免 Git adapter 在 prepare 阶段拉取私有资源而中断安装。
 
 ## 概览
 
@@ -46,10 +46,10 @@
 
 | 项目 | 说明 |
 | --- | --- |
-| 当前版本 | `v1.5.0` |
+| 当前版本 | `v1.5.2` |
 | 唯一公开矩阵 | `expo55-rnoh082-ui-stack` |
 | 输入范围 | Managed/CNG Expo 项目 |
-| 已验证 JS/UI 能力 | `expo-router`、`expo-linking`、`expo-constants`、`react-native-reanimated`、`react-native-svg`、`react-native-gesture-handler` |
+| 已验证 JS/UI 能力 | `expo-router`、`expo-linking`、`expo-constants`、`react-native-reanimated`、`react-native-svg` |
 | 构建链 | `doctor -> init -> bundle -> build-hap` |
 | 主 sample | `examples/official-ui-stack-sample` |
 | 回归基线 | `examples/official-app-shell-sample`、`examples/official-minimal-sample` |
@@ -67,58 +67,121 @@
 
 </details>
 
-## 快速开始
+## 安装方式
 
-仓库自身：
+已发布 npm 包：
 
 ```bash
-pnpm install --ignore-scripts
-pnpm build
-pnpm test
+pnpm add -D expo-harmony-toolkit
+# 或
+npm install -D expo-harmony-toolkit
+```
+
+安装完成后，推荐通过本地项目依赖调用 CLI：
+
+```bash
+pnpm exec expo-harmony doctor --project-root .
+# 或
+npx expo-harmony doctor --project-root .
 ```
 
-任意 Expo 项目：
+如果你是在这个仓库里开发，或直接运行官方 UI-stack sample，仍推荐：
 
 ```bash
-expo-harmony doctor --project-root /path/to/app
-expo-harmony doctor --project-root /path/to/app --strict
-expo-harmony init --project-root /path/to/app
-expo-harmony sync-template --project-root /path/to/app
+pnpm install --ignore-scripts
 ```
 
-进入项目根目录后的 CLI 构建链：
+因为当前公开矩阵内的两套 `@react-native-oh-tpl/*` adapter 在 prepare 阶段可能访问私有上游资源。
+
+## 推荐接入方式
+
+建议把 config plugin 写进 Expo 配置，这样 `prebuild` 元数据和 CLI 读取的 Harmony 标识会保持一致：
+
+```json
+{
+  "expo": {
+    "android": {
+      "package": "com.example.app"
+    },
+    "plugins": [
+      "expo-router",
+      [
+        "expo-harmony-toolkit",
+        {
+          "entryModuleName": "entry"
+        }
+      ]
+    ]
+  }
+}
+```
+
+说明：
+
+- 如果已经配置了 `android.package` 或 `ios.bundleIdentifier`，通常不需要额外传 `bundleName`
+- `entryModuleName` 默认就是 `entry`，只有你需要显式固定时才需要写出来
+- toolkit 不会替你自动补齐 UI-stack 依赖；依赖是否落入公开矩阵，以 `doctor --strict` 结果为准
+
+## 使用方法
+
+1. 先做准入检查：
 
 ```bash
 cd /path/to/app
-expo-harmony env --strict
-expo-harmony build-hap --mode debug
+pnpm exec expo-harmony doctor --project-root .
+pnpm exec expo-harmony doctor --project-root . --strict
 ```
 
-如果你只想单独生成 JS bundle：
+2. 生成或刷新受管 Harmony sidecar：
 
 ```bash
-expo-harmony bundle
+pnpm exec expo-harmony init --project-root .
+pnpm exec expo-harmony sync-template --project-root .
 ```
 
+3. 生成 JS bundle，或继续发起 Harmony 构建：
+
+```bash
+pnpm exec expo-harmony bundle --project-root .
+pnpm exec expo-harmony env --strict
+pnpm exec expo-harmony build-hap --mode debug
+```
+
+4. 如果需要 release 构建，先确认签名环境已就绪，再执行：
+
+```bash
+pnpm exec expo-harmony env
+pnpm exec expo-harmony build-hap --mode release
+```
+
+常见使用判断：
+
+- 想知道当前项目是否还在公开矩阵里：跑 `doctor --strict`
+- 刚改过依赖、Expo 配置或插件：先跑 `sync-template`
+- 只想验证 JS/UI 侧是否能打包：跑 `bundle`
+- 准备进 DevEco Studio 或本机构建 HAP：先跑 `env`
+
 ## 支持矩阵
 
-`v1.5.0` 继续坚持单矩阵路线：`expo55-rnoh082-ui-stack`。
+`v1.5.2` 继续坚持单矩阵路线：`expo55-rnoh082-ui-stack`。
 
 - Expo SDK：`55`
-- React：`19.2.x`
-- React Native：`0.83.x`
+- React：`19.1.1`
+- React Native：`0.82.1`
 - RNOH / `@react-native-oh/react-native-harmony-cli`：`0.82.18`
 - App Shell 依赖：`expo-router`、`expo-linking`、`expo-constants`
-- UI stack 依赖：`react-native-reanimated`、`react-native-svg`、`react-native-gesture-handler`
-- Harmony adapter：对应三项 `@react-native-oh-tpl/*` exact Git specifier
+- UI stack 依赖：`react-native-reanimated`、`react-native-svg`
+- Harmony adapter：对应两项 `@react-native-oh-tpl/*` exact Git specifier
 - 原生标识：至少配置 `android.package` 或 `ios.bundleIdentifier`
 
+当前不再把 `react-native-gesture-handler` 放进公开矩阵。它仍可作为手动探索项，但当前 `@react-native-oh-tpl/react-native-gesture-handler` 与 `@react-native-oh/react-native-harmony@0.82.18` 的设备侧 runtime 组合还没有通过正式验收。
+
 完整白名单、配对规则、exact specifier、issue code 与 release gate 见 [docs/support-matrix.md](./docs/support-matrix.md)。
 
 ## 官方 Samples
 
 - `examples/official-ui-stack-sample`
-  当前唯一对外主 sample，同时覆盖 router、linking、constants、SVG、gesture、reanimated 和 Harmony sidecar 构建链。
+  当前唯一对外主 sample，同时覆盖 router、linking、constants、SVG、reanimated 和 Harmony sidecar 构建链。
 - `examples/official-app-shell-sample`
   `v1.1` App Shell 回归基线，用来防止 UI-stack 收口引入 router 退化。
 - `examples/official-minimal-sample`
@@ -169,13 +232,14 @@ expo-harmony bundle
 
 - GitHub workflow 跑 `build/test/pack/tarball smoke`
 - `build-hap --mode debug` 不阻塞 npm publish
-- npm 发布使用 `latest` dist-tag 和 provenance
+- GitHub 自动发布使用 `latest` dist-tag 和 provenance
+- 本地手动发布使用 `latest` dist-tag
 
 手动 Harmony 验收继续要求：
 
 - `official-ui-stack-sample` 成功启动
 - SVG 正常渲染
-- gesture 能触发可见动画
+- 点击首页 motion rail 后能触发可见动画
 - 动画完成后路由跳转仍正常
 - `Build Debug Hap(s)` 成功