expo-harmony-toolkit 1.7.2 → 1.7.3

package/docs/v1.6.0-acceptance.md

@@ -1,193 +0,0 @@
-# v1.6.0 验收记录
-
-日期：2026-03-31
-
-基线：
-
-- 仓库：`Expo-Harmony-Toolkit`
-- 版本：`1.6.0`
-- 发布目标：npm 包 `expo-harmony-toolkit@latest`
-
-## 结论
-
-这次 `v1.6.0` 已完成发版前验收，满足 npm 发布条件。
-
-- `doctor --strict` 既有 verified 矩阵 `expo55-rnoh082-ui-stack` 仍然可用。
-- 新增的 tiered support model、preview capability skeleton、permission generation、official native capabilities sample 已完成本地构建与设备侧验证。
-- `pnpm release:check` 已通过，包含 `build`、`test`、`npm pack --dry-run`、tarball 文件清单检查、tarball 安装 smoke，以及临时 sample 的 `build-hap --mode debug`。
-- 当前未完成项只剩 release HAP signing；这不属于 npm 发版 gate。
-
-## 环境
-
-- macOS `26.3` (`25D125`)
-- Node `v20.19.6`
-- pnpm `10.32.1`
-- npm `10.8.2`
-- DevEco Studio：`/Applications/DevEco-Studio.app`
-- Harmony SDK：`/Applications/DevEco-Studio.app/Contents/sdk`
-- Java：`/usr/bin/java`
-- ohpm：`/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm`
-- hvigor：`/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js`
-- hdc：`/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc`
-- 在线目标：`127.0.0.1:5555`
-
-## 验收范围
-
-### 1. 核心构建与测试
-
-执行：
-
-```bash
-pnpm build
-pnpm test
-pnpm release:check
-```
-
-结果：
-
-- `pnpm build`：通过。
-- `pnpm test`：`11` 个 suite、`57` 个测试全部通过。
-- `pnpm release:check`：通过。
-- tarball 文件清单符合预期，没有把 `examples/`、`fixtures/`、`tests/` 打进 npm 包。
-- tarball smoke 在临时 sample 上完成：
-  - `expo-harmony doctor --strict`
-  - `expo-harmony init --force`
-  - `expo-harmony bundle`
-  - `expo-harmony build-hap --mode debug`
-
-### 2. Verified 矩阵回归
-
-对象：
-
-- `examples/official-ui-stack-sample`
-
-执行：
-
-```bash
-node ../../bin/expo-harmony.js doctor --project-root . --strict
-node ../../bin/expo-harmony.js init --project-root .
-node ../../bin/expo-harmony.js bundle --project-root .
-node ../../bin/expo-harmony.js build-hap --project-root . --mode debug
-```
-
-结果：
-
-- `doctor --strict`：通过，矩阵识别为 `expo55-rnoh082-ui-stack`。
-- `init`：通过。
-- `bundle`：通过。
-- `build-hap --mode debug`：通过，产出：
-
-```text
-examples/official-ui-stack-sample/harmony/entry/build/default/outputs/default/entry-default-unsigned.hap
-```
-
-设备侧验证：
-
-```bash
-hdc install -r entry-default-unsigned.hap
-hdc shell aa start -a EntryAbility -b com.blackishgreen.expoharmonyuistack
-```
-
-结果：
-
-- HAP 安装成功。
-- `EntryAbility` 启动成功。
-- 通过 `uitest dumpLayout` 验证首页可见：
-  - `Official UI Stack Sample`
-  - `Expo Harmony UI Stack Sample`
-  - `expoharmonyuistack:///details`
-  - `RNSVGSvgView(...)` 节点存在
-  - `Run reanimated spring`
-  - `Open details route`
-- 点击一次 motion rail 后，再点击 `Open details route`，`/details` 页面可见：
-  - `UI Stack Details`
-  - `doctor -> init -> bundle -> build-hap -> runtime`
-  - `Back to home`
-
-当前判断：
-
-- `expo-router`
-- `expo-linking`
-- `expo-constants`
-- `react-native-svg`
-- `react-native-reanimated`
-
-都仍然落在可启动、可渲染、可跳转的 verified 运行时路径内。
-
-### 3. Preview Native Capabilities 验证
-
-对象：
-
-- `examples/official-native-capabilities-sample`
-
-执行：
-
-```bash
-node ../../bin/expo-harmony.js doctor --project-root . --target-tier preview
-node ../../bin/expo-harmony.js init --project-root .
-node ../../bin/expo-harmony.js bundle --project-root .
-node ../../bin/expo-harmony.js build-hap --project-root . --mode debug
-```
-
-结果：
-
-- `doctor --target-tier preview`：通过，`expo-file-system` / `expo-image-picker` 识别为 `manual/preview`。
-- `init`：通过，并生成 Harmony permission declaration 与 preview shim。
-- `bundle`：通过。
-- `build-hap --mode debug`：通过，产出：
-
-```text
-examples/official-native-capabilities-sample/harmony/entry/build/default/outputs/default/entry-default-unsigned.hap
-```
-
-设备侧验证：
-
-```bash
-hdc install -r entry-default-unsigned.hap
-hdc shell aa start -a EntryAbility -b com.blackishgreen.expoharmonynativepreview
-```
-
-结果：
-
-- HAP 安装成功。
-- `EntryAbility` 启动成功。
-- `bm dump` 可见 request permissions：
-  - `ohos.permission.CAMERA`
-  - `ohos.permission.READ_IMAGEVIDEO`
-  - 对应 `$string:` reason 已写入 bundle metadata。
-- 通过 `uitest dumpLayout` 与点击事件验证：
-  - 首页可见 `Official Native Capabilities Sample`
-  - `/file-system` 页面可见 `expo-file-system preview`
-  - 点击 `Attempt preview write` 后，message 更新为 preview bridge 文案，不 crash
-  - `/image-picker` 页面可见 `expo-image-picker preview`
-  - 点击 `Attempt preview pick` 后，message 更新为 preview bridge 文案，不 crash
-
-当前判断：
-
-- preview tier 的承诺已经达到：
-  - 可被 `doctor` 分级识别
-  - 可 `init`
-  - 可 `bundle`
-  - 可 `build-hap --mode debug`
-  - 可安装与启动
-  - 点击 capability demo 不会 crash，而是稳定落到 preview bridge 提示
-
-## 非阻塞观察
-
-- `env.signing.missing` 仍然存在；当前 sidecar 没有 release signing config，这不阻塞 npm 发版，也不阻塞 debug HAP 验证。
-- 设备日志里仍可看到一些非致命 debug 噪音，例如：
-  - `StatusBar is translucent by default`
-  - `DevMenu` / `ACCELEROMETER` 相关提示
-  - 若干 websocket retry / `epoll wait event` 噪音
-- 本轮没有观察到阻止应用启动、阻止页面渲染、或导致 preview / verified sample route 崩溃的 fatal runtime 问题。
-
-## 对 v1.6.0 的最终判断
-
-- `doctor / init / bundle / build-hap(debug)`：可用
-- verified UI-stack matrix：通过设备侧回归
-- preview native capabilities skeleton：通过设备侧回归
-- tarball smoke：通过
-- npm 发布前 gate：通过
-- release HAP signing：未配置，不纳入本次 npm 发版阻塞项
-
-因此，`v1.6.0` 已具备进入 npm 正式发布流程的条件。

package/docs/v1.7.0-acceptance.md

@@ -1,111 +0,0 @@
-# v1.7.0 验收记录（模拟器收口版）
-
-日期：2026-04-02
-
-基线：
-
-- 仓库：`Expo-Harmony-Toolkit`
-- 版本：`1.7.0`
-- 验收约束：当前无真机，只做模拟器与构建层收口
-
-## 当前结论
-
-`v1.7.0` 这一轮的正确结论不是“所有 preview capability 已 verified”，而是：
-
-- 四个 official sample 都已经收口成可理解、可上手、可重复操作的官方示例
-- `official-minimal-sample` 不再只是空白 smoke 卡片，而是最短链路说明页
-- `official-app-shell-sample` 不再只是回归页，而是 router / linking / constants 的最小 onboarding sample
-- `official-ui-stack-sample` 继续作为 verified UI-stack 主 sample，并把成功信号写得更显式
-- `official-native-capabilities-sample` 现在按“每页一个模块、只讲核心支持子集、unsupported 边界明确”的方式收口
-- `expo-file-system`、`expo-image-picker`、`expo-location`、`expo-camera` 仍然全部保持 `preview`
-- 在没有真机前，不把任何 preview capability 提升到 `verified`
-
-这份记录里默认使用以下判读：
-
-- `🟡` 表示实现已到位，主要只差真机 / release 证据
-- `🟠` 表示包已进入 `preview`，但这个具体子 API 还没补齐到可信实现；不是“只差真机”
-
-## 本轮实现范围
-
-- 统一重做四个 official sample 的页面表达和使用文档
-- `expo-file-system` sample 补齐目录创建、写入、读回、列目录、复制、移动、清理
-- `expo-image-picker` sample 保留单图选择 / 单次拍照 / denied / canceled / asset-return 主路径
-- `expo-location` sample 收口到 foreground permission、current、last-known、geocode、reverse-geocode
-- `expo-camera` sample 收口到 camera permission + still capture through Harmony system camera UI
-- `expo-location` shim 明确把 `watchPositionAsync`、background permission、heading API 降为 unsupported
-- `expo-camera` shim 明确把 embedded preview、pause/resume、microphone、video 相关入口降为 unsupported
-- sample 指南、support matrix、README、acceptance 记录同步到真实状态
-
-## 自动化检查结果
-
-执行：
-
-- `pnpm build`
-- `pnpm test`
-
-结果：
-
-- `pnpm build`：通过
-- `pnpm test`：通过，`11` suites / `61` tests
-
-另外，sample 相关针对性回归也已通过：
-
-- `tests/officialSample.test.ts`
-- `tests/officialAppShellSample.test.ts`
-- `tests/officialUiStackSample.test.ts`
-- `tests/officialNativeCapabilitiesSample.test.ts`
-- `tests/init.test.ts`
-- `tests/docs.test.ts`
-
-## 这版 sample 的实际完成度
-
-### Official Minimal Sample
-
-- 页面现在明确说明它验证的是最短 `doctor -> init -> bundle -> build-hap` 链路
-- 页面明确写出成功标准与故意不覆盖的范围
-- 适合作为新开发者的最小入口，而不是仅供维护者理解的 smoke baseline
-
-### Official App Shell Sample
-
-- 首页明确展示 app name、pathname、observed URL、generated details URL
-- 同时提供 router push、`Link` 组件、generated deep link 三条入口
-- `/details` 页面也会回显当前 pathname / URL，便于判断 deep-link 是否真正解析成功
-
-### Official UI Stack Sample
-
-- 保留 router、linking、constants、SVG、reanimated 的 verified 主线
-- 首页新增“Success signals”表达，降低验收歧义
-- `/details` 页面会回显 route / URL，帮助判断动画和路由是否互相影响
-
-### Official Native Capabilities Sample
-
-- `/file-system`
-  - 现在是完整 sandbox 文件流 sample
-  - 覆盖目录创建、读写、inspect、列目录、copy、move、cleanup
-- `/image-picker`
-  - 继续聚焦 permission、单图选择、单次拍照、deny/cancel/success 三类结果
-- `/location`
-  - `🟡` foreground permission、current、last-known、geocode、reverse-geocode 可直接操作
-  - `🟠` `watchPositionAsync`、background permission、heading API 已不再伪装成主路径支持；这些不是“只差真机”
-- `/camera`
-  - `🟡` 相机权限和 through-system-ui 的 still capture 可直接操作
-  - `🟠` embedded preview、pause/resume、microphone、video 已不再伪装成主路径支持；这些不是“只差真机”
-
-## 当前未完成的边界
-
-在没有真机前，以下内容仍未完成：
-
-- 任一 preview capability 的 `verified` 晋升
-- `🟡` 已实现子集的真机与 release 证据补齐
-- `🟠` `expo-location` 的真实 continuous watch、background permission parity、heading API 实现与验收
-- `🟠` `expo-camera` 的 embedded live preview、preview pause/resume、microphone / video API 实现与验收
-- release signing 配置以外的真机 release HAP 运行证据
-
-## 版本结论
-
-因此，`v1.7.0` 现在可以对外保持的准确说法是：
-
-- verified 主线仍然只有 `expo55-rnoh082-ui-stack`
-- 四个 native capability 已经收口成“模拟器下真正可用的高质量 preview sample”
-- 工具链、sample、矩阵、README、acceptance 文档现在口径一致
-- 下一步只有在拿到真机后，才应该讨论 capability promotion

package/docs/v1.7.1-acceptance.md

@@ -1,111 +0,0 @@
-# v1.7.1 验收记录（模拟器收口版）
-
-日期：2026-04-02
-
-基线：
-
-- 仓库：`Expo-Harmony-Toolkit`
-- 版本：`1.7.1`
-- 验收约束：当前无真机，只做模拟器与构建层收口
-
-## 当前结论
-
-`v1.7.1` 这一轮的正确结论不是“所有 preview capability 已 verified”，而是：
-
-- 四个 official sample 都已经收口成可理解、可上手、可重复操作的官方示例
-- `official-minimal-sample` 不再只是空白 smoke 卡片，而是最短链路说明页
-- `official-app-shell-sample` 不再只是回归页，而是 router / linking / constants 的最小 onboarding sample
-- `official-ui-stack-sample` 继续作为 verified UI-stack 主 sample，并把成功信号写得更显式
-- `official-native-capabilities-sample` 现在按“每页一个模块、只讲核心支持子集、unsupported 边界明确”的方式收口
-- `expo-file-system`、`expo-image-picker`、`expo-location`、`expo-camera` 仍然全部保持 `preview`
-- 在没有真机前，不把任何 preview capability 提升到 `verified`
-
-这份记录里默认使用以下判读：
-
-- `🟡` 表示实现已到位，主要只差真机 / release 证据
-- `🟠` 表示包已进入 `preview`，但这个具体子 API 还没补齐到可信实现；不是“只差真机”
-
-## 本轮实现范围
-
-- 统一重做四个 official sample 的页面表达和使用文档
-- `expo-file-system` sample 补齐目录创建、写入、读回、列目录、复制、移动、清理
-- `expo-image-picker` sample 保留单图选择 / 单次拍照 / denied / canceled / asset-return 主路径
-- `expo-location` sample 收口到 foreground permission、current、last-known、geocode、reverse-geocode
-- `expo-camera` sample 收口到 camera permission + still capture through Harmony system camera UI
-- `expo-location` shim 明确把 `watchPositionAsync`、background permission、heading API 降为 unsupported
-- `expo-camera` shim 明确把 embedded preview、pause/resume、microphone、video 相关入口降为 unsupported
-- sample 指南、support matrix、README、acceptance 记录同步到真实状态
-
-## 自动化检查结果
-
-执行：
-
-- `pnpm build`
-- `pnpm test`
-
-结果：
-
-- `pnpm build`：通过
-- `pnpm test`：通过，`11` suites / `61` tests
-
-另外，sample 相关针对性回归也已通过：
-
-- `tests/officialSample.test.ts`
-- `tests/officialAppShellSample.test.ts`
-- `tests/officialUiStackSample.test.ts`
-- `tests/officialNativeCapabilitiesSample.test.ts`
-- `tests/init.test.ts`
-- `tests/docs.test.ts`
-
-## 这版 sample 的实际完成度
-
-### Official Minimal Sample
-
-- 页面现在明确说明它验证的是最短 `doctor -> init -> bundle -> build-hap` 链路
-- 页面明确写出成功标准与故意不覆盖的范围
-- 适合作为新开发者的最小入口，而不是仅供维护者理解的 smoke baseline
-
-### Official App Shell Sample
-
-- 首页明确展示 app name、pathname、observed URL、generated details URL
-- 同时提供 router push、`Link` 组件、generated deep link 三条入口
-- `/details` 页面也会回显当前 pathname / URL，便于判断 deep-link 是否真正解析成功
-
-### Official UI Stack Sample
-
-- 保留 router、linking、constants、SVG、reanimated 的 verified 主线
-- 首页新增“Success signals”表达，降低验收歧义
-- `/details` 页面会回显 route / URL，帮助判断动画和路由是否互相影响
-
-### Official Native Capabilities Sample
-
-- `/file-system`
-  - 现在是完整 sandbox 文件流 sample
-  - 覆盖目录创建、读写、inspect、列目录、copy、move、cleanup
-- `/image-picker`
-  - 继续聚焦 permission、单图选择、单次拍照、deny/cancel/success 三类结果
-- `/location`
-  - `🟡` foreground permission、current、last-known、geocode、reverse-geocode 可直接操作
-  - `🟠` `watchPositionAsync`、background permission、heading API 已不再伪装成主路径支持；这些不是“只差真机”
-- `/camera`
-  - `🟡` 相机权限和 through-system-ui 的 still capture 可直接操作
-  - `🟠` embedded preview、pause/resume、microphone、video 已不再伪装成主路径支持；这些不是“只差真机”
-
-## 当前未完成的边界
-
-在没有真机前，以下内容仍未完成：
-
-- 任一 preview capability 的 `verified` 晋升
-- `🟡` 已实现子集的真机与 release 证据补齐
-- `🟠` `expo-location` 的真实 continuous watch、background permission parity、heading API 实现与验收
-- `🟠` `expo-camera` 的 embedded live preview、preview pause/resume、microphone / video API 实现与验收
-- release signing 配置以外的真机 release HAP 运行证据
-
-## 版本结论
-
-因此，`v1.7.1` 现在可以对外保持的准确说法是：
-
-- verified 主线仍然只有 `expo55-rnoh082-ui-stack`
-- 四个 native capability 已经收口成“模拟器下真正可用的高质量 preview sample”
-- 工具链、sample、矩阵、README、acceptance 文档现在口径一致
-- 下一步只有在拿到真机后，才应该讨论 capability promotion

package/docs/v1.7.2-acceptance.md

@@ -1,37 +0,0 @@
-# v1.7.2 验收记录（Preview 子集收口版）
-
-- 版本：`1.7.2`
-- 日期：`2026-04-02`
-- 目标：把 `expo-file-system`、`expo-image-picker`、`expo-location`、`expo-camera` 当前文档中的 `🟠` 子项全部收口到明确 `🟡` 子集
-
-## 结论
-
-`v1.7.2` 的正确结论不是“preview capability 已 verified”，而是：
-
-- 四项能力继续全部保持 `preview`
-- `runtimeMode` 继续保持 `adapter`
-- `evidence.release` 继续保持 `false`
-- 公开文档、official sample、模板生成与测试口径已收口到新的 yellow subset
-
-## 这轮收口内容
-
-- `expo-file-system`
-  - base64、append / partial read、`getInfoAsync({ md5: true })`、`downloadAsync`
-- `expo-image-picker`
-  - multi-select、mixed library selection、camera photo/video capture、`getPendingResultAsync`
-- `expo-location`
-  - background permission、`watchPositionAsync`、`getHeadingAsync`、`watchHeadingAsync`
-- `expo-camera`
-  - embedded `CameraView`、preview pause/resume、video recording、microphone permission
-
-## 文档与 sample 口径
-
-- [support-matrix](./support-matrix.md) 已更新为新的 yellow subset
-- [official-native-capabilities-sample](./official-native-capabilities-sample.md) 已改成四条 route 的收口版 walkthrough
-- README 中英、acceptance link、sample route copy 已同步更新
-
-## 保持不变的边界
-
-- 这轮不做 `preview -> verified` 晋升
-- 这轮不扩张到 `expo-notifications`、scanner parity、resumable task 家族等非目标能力
-- 真机与 release 证据仍需后续验收补齐