@hmos-library-adapter/fast 0.0.17-beta.1 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-libusb-ddk/evaluation.md

@@ -0,0 +1,124 @@
+# USB 适配器链路（F-08）DDK 桥接评估
+
+> **方案资产**（vendored 自 OpenOCD 0.12.0+dev 适配工作区 `build/usb-ddk-evaluation/`，2026-09-11）。
+> 后续库（dfu-util/pyusb/任意 libusb 依赖方）评估 app 域 USB 可用性时**直接引用本目录三份文档**，
+> 不必重做符号级核实与映射梳理。README/PORTING_NOTES 待真机验证后补齐，域条目只路由。
+> 关键结论速览：
+> - 中心仓 `libusb/1.0.27` 为 **usbfs 后端**（`.rodata` 含 `/dev/bus/usb/%h`、`usbfs_scan`），app 域不可用；
+> - NDK 自带 `libusb_ndk.z.so`（17 个 `OH_Usb_*` 转发桩）+ `libhid.z.so` + `libusb_serial_ndk.z.so`；
+> - 社区 `ohos_libusb` 仓空壳（仅 README）——**无现成 libusb→DDK 兼容层，自研 libusb_shim 是唯一正路**；
+> - 前置：`ohos.permission.ACCESS_DDK_USB`（system_basic）+ ArkTS `usbManager.requestRight` + 物理探针。
+
+> 本轮续修（2026-09-11）记录：评估自研 libusb→OHOS USB DDK 桥接层的可行性，
+> 更新 remaining_blockers 归因。设备未连接（hdc list targets = [Empty]），
+> 全部结论为离线评估 + 产物级静态证据，无真机验证。
+
+## 1. 现状与已核实事实链
+
+### 1.1 中心仓 libusb/1.0.27 是 Linux usbfs 后端（不可用于 app 域）
+
+`deps/libusb-1.0.27/dist/lib/libusb-1.0.so.0.4.0`（Conan 中心仓拉取）经符号级审计：
+
+- `.rodata` 含 usbfs 路径字面量：`/dev/bus/usb/%h`、`/sys/bus/usb`、`usbfs_scan`、`usbfs_get_fd`
+- 未定义符号（UND）为 open/ioctl/statfs/readlink 等 Linux usbfs 系统调用
+- **无任何 USB DDK 符号**（无 OH_Usb_* 引用）
+
+hdc shell 域已实测打不开 `/dev/bus/usb`（SELinux 拒绝）；app 域沙箱只会更严。
+**结论：该 usbfs 后端产物在 app 域即使 dlopen 成功也无法枚举/访问 USB 设备。**
+
+### 1.2 NDK sysroot 自带 USB/HID DDK 材料（本轮新核实）
+
+```
+$DEVECO_SDK_HOME/default/openharmony/native/sysroot/usr/lib/aarch64-linux-ohos/
+  libusb_ndk.z.so          (5824 B)  — OH_Usb_* 导出面
+  libhid.z.so              (5744 B)  — OH_Hid_* 导出面
+  libusb_serial_ndk.z.so   (5568 B)  — OH_UsbSerial_* 导出面
+
+$DEVECO_SDK_HOME/default/openharmony/native/sysroot/usr/include/
+  usb/usb_ddk_api.h / usb_ddk_types.h
+  hid/hid_ddk_api.h / hid_ddk_types.h
+  usb_serial/usb_serial_api.h / usb_serial_types.h
+```
+
+`llvm-nm -D libusb_ndk.z.so` 实测导出（17 个 API，全部同址 0x1a64，为 DDK 框架转发桩）：
+
+```
+OH_Usb_Init / OH_Usb_Release / OH_Usb_ReleaseResource
+OH_Usb_GetDevices / OH_Usb_GetDeviceDescriptor / OH_Usb_GetConfigDescriptor
+OH_Usb_FreeConfigDescriptor
+OH_Usb_ClaimInterface / OH_Usb_ReleaseInterface
+OH_Usb_SelectInterfaceSetting / OH_Usb_GetCurrentInterfaceSetting
+OH_Usb_SendControlReadRequest / OH_Usb_SendControlWriteRequest
+OH_Usb_SendPipeRequest / OH_Usb_SendPipeRequestWithAshmem
+OH_Usb_CreateDeviceMemMap / OH_Usb_DestroyDeviceMemMap
+```
+
+### 1.3 社区 ohos_libusb 仓无实质代码
+
+`deps/ohos_libusb_src/`（gitcode.com/OpenHarmonyPCDeveloper/ohos_libusb，shallow clone 已拉取）：
+- `git log` 仅 1 个提交 `097c9dc updateReadMe`
+- 工作树仅 `README.md` 一个文件——README 描述的 lycium 构建脚本与 libusb.hnp
+  产物均**不在仓内**（指路外部 lycium_plusplus 脚手架，未随仓发布）
+- **结论：不存在现成 libusb-API 兼容的 DDK 后端包装，自研是唯一路径。**
+
+## 2. 自研 libusb→DDK 桥接层可行性评估
+
+### 2.1 API 映射面（openocd 用到的 libusb 子集）
+
+| libusb-1.0 API | OHOS DDK 对应 | 缺口 |
+|---|---|---|
+| libusb_init / libusb_exit | OH_Usb_Init / OH_Usb_Release | ✅ 一一对应 |
+| libusb_get_device_list | OH_Usb_GetDevices（since 18） | ⚠️ 无 libusb_device 对象/引用计数模型；需自建 device 包装结构 |
+| libusb_get_device_descriptor | OH_Usb_GetDeviceDescriptor | ✅ 可直接映射 |
+| libusb_get_config_descriptor | OH_Usb_GetConfigDescriptor | ✅ |
+| libusb_open / libusb_close | 无直接对应——DDK 以 deviceId 直接操作 | ⚠️ open 需映射为 claim（语义错位） |
+| libusb_claim_interface | OH_Usb_ClaimInterface | ✅ |
+| libusb_release_interface | OH_Usb_ReleaseInterface | ✅ |
+| libusb_set_configuration | 无 | ❌ 需退化为 SelectInterfaceSetting 或返回 LIBUSB_ERROR_NOT_SUPPORTED |
+| libusb_control_transfer | OH_Usb_SendControlRead/WriteRequest | ✅（同步语义一致） |
+| libusb_bulk_transfer | OH_Usb_SendPipeRequest | ✅（同步；libusb timeout=0 需映射为大超时） |
+| libusb_interrupt_transfer | OH_Usb_SendPipeRequest | ✅（同 bulk 路径） |
+| libusb_set_interface_alt_setting | OH_Usb_SelectInterfaceSetting | ✅ |
+| libusb_get_device_speed / bus_number / port_number | DDK 未暴露 | ❌ 需返回桩值 |
+| libusb_hotplug_* | DDK 无热插拔通知 | ❌ 需退化支持 |
+| libusb_handle_events / async 传输 | DDK 全同步 | ❌ 异步模型整体退化 |
+
+### 2.2 关键阻塞点
+
+1. **权限模型**：`OH_Usb_Init` 等全部 API 需 `ohos.permission.ACCESS_DDK_USB`——
+   该权限在鸿蒙 PC 上属 **system_basic 级**，第三方 HAP 默认不可申请；
+   即便可用，运行时还需用户在系统弹窗对具体设备点「允许」（ArkTS `usbManager.requestRight`），
+   **纯 native 进程无法完成授权**，桥接层必须依赖宿主 ArkTS 侧的授权前置。
+2. **设备发现模型错位**：DDK 是「已授权设备清单」模型（OH_Usb_GetDevices 返回
+   deviceId 数组），libusb 是「总线枚举」模型（libusb_device 树 + 引用计数 +
+   ref/unref 生命周期）。桥接层需要自建 device 对象池与生命周期管理。
+3. **异步模型缺失**：libusb 的 async/event loop 是 openocd 的 libusb 驱动
+   （libusb1_async.c）可选路径；DDK 只有同步 API。openocd 的
+   `--enable-libusb` 会同时用同步与异步路径，桥接只能满足同步子集，
+   异步调用必须返回 LIBUSB_ERROR_NOT_SUPPORTED，**可能改变 openocd 对
+   FTDI/STLink/CMSIS-DAP 等常见适配器的行为语义**。
+4. **验证载体**：桥接层编译产物即使产出，也必须真机验证——需要
+   (a) 鸿蒙 PC 设备 (b) USB 调试器硬件 (c) ArkTS 侧权限授权。
+   当前三项全部不具备。
+
+### 2.3 结论
+
+**DDK 桥接在本轮（离线、无设备、无授权链路）不可行到可验证的完整度。**
+但已确认它是唯一正路，且 API 映射面已梳理清楚（见 2.1），留给后续：
+- 有设备 + 授权环境后：自研 `libusb_shim` .so（导出 libusb-1.0 公共 API 子集，
+  内部走 OH_Usb_*），替换 `deps/libusb-1.0.27/dist/lib/libusb-1.0.so*` 供 openocd 重链；
+- 或按 usbredir 案例的降级模式：openocd 加 have_usb 守卫，让无 USB 时
+  dummy/TCP/telnet 等非 USB 功能不被锁死（当前 dummy 链路已可用，不受影响）。
+
+## 3. 本轮落地物
+
+- `build/usb-ddk-evaluation/evaluation.md` — 本文档（评估结论与证据）
+- `build/usb-ddk-evaluation/libusb-ndk-symbols.txt` — llvm-nm 导出面实录
+- `build/usb-ddk-evaluation/api-mapping.md` — 映射表（2.1 的落盘版）
+- remaining_blockers 更新为准确归因（见 03-adapt.json）
+
+## 4. 状态影响
+
+不改变 openocd CLI 交付形态的验收结论：名册 26 条中 USB 相关仅
+`adapter-list`（配置面，用 dummy 驱动验证，已通过）；真机 USB 调试
+属 PRD scope_out（需物理硬件 + 授权），继续留在 remaining_blockers。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-libusb-ddk/libusb-ndk-symbols.txt

@@ -0,0 +1,21 @@
+OH_Usb_Init                T   0000000000001a64
+OH_Usb_Release             T   0000000000001a64
+OH_Usb_ReleaseResource     T   0000000000001a64
+OH_Usb_GetDevices          T   0000000000001a64
+OH_Usb_GetDeviceDescriptor T   0000000000001a64
+OH_Usb_GetConfigDescriptor T   0000000000001a64
+OH_Usb_FreeConfigDescriptor T  0000000000001a64
+OH_Usb_ClaimInterface      T   0000000000001a64
+OH_Usb_ReleaseInterface    T   0000000000001a64
+OH_Usb_SelectInterfaceSetting     T   0000000000001a64
+OH_Usb_GetCurrentInterfaceSetting  T   0000000000001a64
+OH_Usb_SendControlReadRequest      T   0000000000001a64
+OH_Usb_SendControlWriteRequest     T   0000000000001a64
+OH_Usb_SendPipeRequest    T   0000000000001a64
+OH_Usb_SendPipeRequestWithAshmem   T   0000000000001a64
+OH_Usb_CreateDeviceMemMap  T   0000000000001a64
+OH_Usb_DestroyDeviceMemMap T   0000000000001a64
+# 非 DDK 符号
+__cxa_finalize             w   (weak)
+_init                      T   0000000000001904
+_fini                      T   0000000000001918

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/ARCHITECTURE.md

@@ -0,0 +1,418 @@
+# 鸿蒙 PC 视窗/图形库通用适配方案 — Architecture
+
+> **ohos_window_bridge (OWB)** —— 一次写好"把任意自绘像素的视窗/图形库搬到鸿蒙 PC"这道平台缝，让 GLFW / SDL / GTK / Qt / ImGui / bgfx 等库**开箱即用**地复用，而不必每个库都从零踩坑。
+
+本文是整套解决方案的**权威架构文档**：讲清楚为什么这么设计、每层是什么、以及其他库怎么接。落地细节看 [`docs/PORTING_KIT.md`](docs/PORTING_KIT.md)（后端作者手把手配方）与 [`README.md`](README.md)（速览）。
+
+---
+
+## 0. TL;DR
+
+- **问题**：鸿蒙是托管式渲染，NDK 层没有 `createWindow`，桌面视窗库（GLFW/SDL…）的窗口后端全部失效。
+- **洞见**：鸿蒙上"搬一个渲染像素的库"平台相关的**只有一道缝**——`XComponent(SURFACE) → OHNativeWindow`。其余库逻辑一行不动。
+- **方案**：把这道缝（surface 管理 + 事件 + VSync + GPU/CPU 上屏）封成一层**库中立**的公共库 OWB。新库只写薄薄一层 L3 后端，把自己的渲染输出和事件源接到 OWB。
+- **状态**：GLFW 3.5 是第一个消费者，**已在鸿蒙 PC 真机端到端跑通**（HAD-W32/API23，桌面窗口内旋转彩色三角形，OpenGL ES 3.2，VSync 驱动）。
+
+---
+
+## 1. 问题：鸿蒙为什么不能直接跑桌面视窗库
+
+| 维度 | 桌面端（Windows/Linux X11） | 鸿蒙（Stage 模型） |
+|---|---|---|
+| 窗口创建 | 应用随时 `CreateWindowExW`/`XCreateWindow` 任意建独立窗口 | **NDK 层无 `createWindow`**；应用只有一个 `WindowStage` 托管的系统窗口 |
+| 引擎渲染对接 | 直接绑系统窗口句柄（`HWND`/`Window ID`）→ WGL/GLX/EGL | 必须嵌入 ArkUI 组件 `XComponent`，间接拿 `OHNativeWindow` |
+| 合成 | 窗口管理器合成多个独立窗口 | Render Service 合成 ArkUI 界面 + XComponent 的离屏 buffer |
+
+GLFW 现有 4 个后端（Win32/Cocoa/X11/Wayland）依赖的窗口 API 鸿蒙全无 → **不是重编译能解决的，必须写新后端**。而"新后端"里平台相关的部分，对所有视窗库都是同一道缝。
+
+**破局点：`XComponent`**。它在 ArkTS 声明式布局里是个占位符，但底层系统为它挖空、独立分配一个 Buffer Queue，通过 NAPI 把 `OHNativeWindow*` 抛给 C++ 层。拿到这个句柄，就能 `eglCreateWindowSurface` / `vkCreateSurfaceOHOS` 回到标准 GPU 渲染流程，或 `RequestBuffer`→CPU 写像素→`FlushBuffer`。
+
+---
+
+## 2. 核心思想：把缝抽成一层
+
+**"搬一个自绘像素的库到鸿蒙" = 把库的两个接触点接到 OWB：**
+1. **渲染输出 → 上屏**（GPU 或 CPU）
+2. **事件源/生命周期 → 输入**（surface 创建/销毁、触摸/鼠标/键盘、VSync 帧）
+
+其余库逻辑不动。OWB 把这道缝形式化成四层：
+
+```
+┌─ L0  ArkTS 宿主（应用写，9 行，零控制器代码）────────────────────────────┐
+│  XComponent({ type: SURFACE, libraryname: '<lib>' })                        │
+│  系统按 libraryname 自动加载 lib<lib>.so 的 napi 模块并挂 XComponent 实例    │
+├─ L1  NAPI 胶水（可复用 / 可选）──────────────────────────────────────────┤
+│  注册 OH_NativeXComponent 回调（surface·touch·mouse·key·OnFrame）           │
+│  → 统一投递 OWB_PostEvent() / OWB_RegisterSurface() / OWB_InternalDispatchFrame()│
+│  实现：napi/owb_napi.cpp  ·  入口 OWB_NAPI_HookXComponent(env, exports)      │
+├─ L2  OWB 核心 ★（纯 C，libc+pthread；CPU 路径另需 libnative_window）────────┤
+│  · surface 注册表（id/surfaceId/OHNativeWindow*/w,h/scale，mutex 保护）      │
+│  · 库中立事件队列（环形 + condvar，poll/wait/post/wakeup）                   │
+│  · VSync 帧回调扇出                                                          │
+│  · 反向通道（库 → 宿主：请求关闭等）                                         │
+│  · 双上屏 helper：GPU=OWB_GetNativeWindow / CPU=OWB_AcquireFrame+CommitFrame │
+│  实现：src/bridge.c  ·  契约：include/ohos_window_bridge.h                   │
+├─ L3  按库后端（薄，库相关——新库唯一要写的一层）──────────────────────────┤
+│  把 OWB_Event 翻成库自己的事件类型；选 GPU 或 CPU 上屏路径                   │
+│  GLFW：ohos_*.c 填 _GLFWplatform vtable（glfw/src/src/）—— 已实现、已真机验证│
+│  SDL / GTK-gdk / Qt-raster / ImGui / bgfx：见 §9 配方 + templates/           │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+**契约**：L0–L2 是交付的二进制（`dist/libohos_window_bridge.{a,so}`）+ 头文件 + ArkTS 宿主 + 骨架模板。**新库只写 L3。**
+
+### 术语速查（缝 vs 胶水）
+
+全文用两个比喻：**缝** = 边界 + 契约（两端相接的那条线，及其中立形式化）；**胶水** = 把某个具体一端接到缝上的连接代码。一句话记忆：**一条中立的缝在正中间（L2），两侧各有专用胶水**——一侧接鸿蒙、一侧接具体库。
+
+| 术语 | 含义 | 中立 or 专用 | 对应层 / 代码 |
+|---|---|---|---|
+| **缝**（平台缝）| 库 ↔ 鸿蒙唯一的平台边界 `XComponent(SURFACE) → OHNativeWindow` | 概念 | 上图整体要跨的那道边界 |
+| **核心缝** | 这道缝被形式化出来的**中立契约层**（不可省） | 中立·只一份 | L2 `include/` + `src/bridge.c` |
+| **宿主胶水** | 把鸿蒙这端（XComponent NAPI / ArkTS / app 入口）接到核心缝 | 专用于宿主·可选 | L1 `napi/owb_napi` + 入口壳 `owb_ohos_app.h` + L0 `arkts-host/` |
+| **后端胶水** | 把核心缝接到某个具体库（GLFW/SDL/…） | 每库一份 | L3 库的 `ohos_*.c` |
+
+缝是"接口 / 契约"，胶水是"接到接口上的连接件"：**换宿主机制、换库，只换对应那一侧的胶水，核心缝不动**。其中入口壳是**可选**的宿主胶水（用它 → 存量 `main()` 零改动；不用 → 走回调式，见 §9、§12）。
+
+---
+
+## 3. 分层详解
+
+| 层 | 依赖 | 谁写 | 职责 | 代码 |
+|---|---|---|---|---|
+| L0 ArkTS | — | 应用开发者 | 声明 SURFACE 型 XComponent，`libraryname` 触发 .so 自动加载 | Index.ets（9 行）|
+| L1 NAPI | ace_ndk + OWB | OWB 提供/库可自带 | XComponent 回调 → OWB | `napi/owb_napi.cpp` |
+| L2 OWB | libc+pthread(+native_window) | **本层（一次写好）** | 注册表+队列+帧+双上屏 | `src/bridge.c` |
+| L3 后端 | OWB | 各库作者 | OWB 事件 → 库事件；选上屏路径 | GLFW `ohos_*.c` |
+
+**L0 要点**：`type` 必须是 `SURFACE`（走 onSurfaceCreated→NativeWindow 原生路径）；`libraryname:'x'` → 系统加载 `libx.so` 调其 napi 模块 Init，ETS 侧**不需要 import 该 .so、不要 @types 声明**（否则 CompileArkTS 报 ENOENT）。
+
+**L1 要点**：`nm_modname` 必须等于 `libraryname`。库可以：(a) 直接调 `OWB_NAPI_HookXComponent(env, exports)` 复用现成实现；或 (b) 自带 NAPI 入口（如 GLFW demo 在 `OnSurfaceCreated` 里初始化 GLFW）。
+
+---
+
+## 4. 数据模型（`include/ohos_window_bridge.h`）
+
+```c
+typedef struct {                    // 一个 XComponent surface 的全部信息
+    uint64_t surfaceId;             // OH_NativeWindow_GetSurfaceId
+    void*    nativeWindow;          // OHNativeWindow*（void* 保持头文件 NDK 无关）
+    int32_t  width, height;         // 像素
+    float    scale;                 // 内容缩放（DPI）
+    char     id[128];               // XComponent id
+    int32_t  inUse;                 // 是否已被某库 Acquire
+    void*    xcomponent;            // OH_NativeXComponent*
+} OWB_SurfaceInfo;
+
+typedef struct {                    // 库中立事件——各库后端翻成自己的类型
+    OWB_EventType type;             // SURFACE_CREATED/CHANGED/DESTROYED, TOUCH, MOUSE,
+    uint64_t      surfaceId;        //   KEY, CHAR, FOCUS/BLUR, FRAME, SCROLL, DROP, WINDOW_CLOSE
+    uint64_t      timestamp;
+    union {
+        struct { int32_t width, height; float scale; }                surface;
+        struct { int32_t action, id; float x, y, pressure; }          touch;
+        struct { int32_t action, button; float x, y; uint32_t mods; } mouse;
+        struct { int32_t action, keyCode, scanCode; uint32_t mods; }  key;
+        struct { uint32_t codepoint; }                                character;
+        struct { double xoffset, yoffset; }                           scroll;
+        struct { uint64_t targetTimestamp; }                          frame;
+        /* ... focus / drop ... */
+    } data;
+} OWB_Event;
+
+typedef struct {                    // CPU-blit framebuffer（OWB_AcquireFrame 回填）
+    void*   pixels;                 // mmap 后基址，RGBA8888
+    int32_t width, height;
+    int32_t stride;                 // 行间距（字节）——可能 > width*4，务必用它！
+} OWB_FrameBuffer;
+```
+
+---
+
+## 5. API 全表（按角色）
+
+| 分组 | 函数 | 调用者 | 头文件行 |
+|---|---|---|---|
+| 生命周期 | `OWB_Initialize` / `OWB_Terminate` | 宿主/库 | 123–124 |
+| **注册表（生产者）** | `OWB_RegisterSurface` / `OWB_UnregisterSurface` / `OWB_UpdateSurfaceSize` | L1 宿主 | 127–130 |
+| **查询/绑定（消费者）** | `OWB_GetSurfaceCount` / `GetSurfaceInfoByIndex` / `ById` / `ByXComponentId` / `Acquire` / `Release` | L3 库 | 133–138 |
+| **等 surface（线程壳）** | `OWB_WaitForSurface(timeout)` | L3 库（worker 线程 createWindow 前阻塞等 JS 线程登记）| 139 |
+| **事件** | `OWB_PollEvent` / `OWB_WaitEvent` / `OWB_PostEvent` / `OWB_PostEmptyEvent` | L3 取 / L1 投 | 141–144 |
+| **帧（VSync）** | `OWB_RegisterFrameCallback` / `Unregister` / `InternalDispatchFrame` | L3 收 / L1 派 | 147–149 |
+| 反向通道 | `OWB_RegisterReverseEventCallback` / `OWB_NotifyWindowClose` | L3 → L0 | 152–153 |
+| **GPU 上屏** | `OWB_GetNativeWindow` | L3 | 157 |
+| **CPU 上屏** | `OWB_AcquireFrame` / `OWB_CommitFrame` / `OWB_AbortFrame` | L3 | 161–163 |
+
+实现对应 `src/bridge.c`（如 `OWB_RegisterSurface:113`、`OWB_PollEvent:284`、`OWB_WaitEvent:293`、`OWB_GetNativeWindow:382`、`OWB_AcquireFrame:393`）。
+
+---
+
+## 6. 双上屏路径（一个缝覆盖 GPU 库和 CPU 工具包）
+
+| 路径 | 怎么用 | 交给 | 适配 |
+|---|---|---|---|
+| **GPU** | `void* w = OWB_GetNativeWindow(sid);` | `eglCreateWindowSurface(dpy,cfg,(EGLNativeWindowType)w,NULL)` 或 `vkCreateSurfaceOHOS(inst,&{.window=w},…)` | GLFW / SDL / bgfx |
+| **CPU-blit** | `OWB_AcquireFrame(sid,&fb)` → 逐行写 `fb.pixels + y*fb.stride` → `OWB_CommitFrame(sid)` | 内部封装 `RequestBuffer→GetBufferHandle→mmap→FlushBuffer` | GTK gdk-ohos / Qt raster QPA / ImGui 软件后端 |
+
+**CPU 路径把唯一易错点封在库里**：`fb.stride` 是从 `BufferHandle` 读的真实行距（实测 2090px 宽 → stride≈8448B，**不是** width*4），调用方直接用 `fb.stride` 就不会斜切/花屏。
+
+### 双向：窗口控制（渲染/输入之外的第三条通道）
+XComponent 只管**像素 + 输入**；**窗口本身**（几何/光标/状态）是另一层。OWB 反向通道把它也桥起来，分两 Tier：
+
+| Tier | 能力 | 路径 |
+|---|---|---|
+| **A 纯 native** | 光标锁定（`GLFW_CURSOR_DISABLED`/原始鼠标）、真实窗口 pos、passthrough | `OWB_LockCursor/GetWindowRect/SetWindowTouchable` → `OH_WindowManager_*`（`libnative_window_manager.so`, API15+）|
+| **B 经 ArkTS** | 几何：resize/move/最小化/最大化/全屏/limits/title | `OWB_RequestWindowOp` → 反向回调 → 宿主 NAPI `threadsafe_function` → ArkTS `@ohos.window` |
+
+**为什么 Tier B 必须走 ArkTS**：鸿蒙 NDK **不暴露任何窗口几何 C API**（穷举确认）；能力只在内部 `libwm.z.so`（Rosen/WMS，不在 app ndk 命名空间）。**Qt 鸿蒙 QPA 实证**：它的窗口控制全经 napi 调 `@ohos.window`（`call("resize")`/`call("maximize")`/`call("setWindowLayoutFullScreen")`），native 几何 API 零使用。所以反向桥是对齐 OS 分层的唯一受控正路，不是绕路。（NDK 无窗口几何 C API 为对 NDK 头文件穷举后的实证结论。）
+
+**宿主接线（极少）**：ArkTS 经 `XComponentController.getXComponentContext()` 把 `@ohos.window` mainWindow 对象 + windowId 交给 native 一次（不 import .so）；NAPI 用 `threadsafe_function` marshal 到 JS 线程直调 Window 方法（Qt 的 safeExec 同理）。GLFW 真机验证：`glfwSetWindowSize(900,600)`→窗口 rect 真变 `[.. 900 600]`、maximize→`[0 0 3120 2080]`、restore→还原（真机截图存 GLFW 社区适配仓）。
+
+---
+
+## 7. 运行时流转（时序）
+
+对齐 §9 的两种接入方式，分两种运行模型看。
+
+### 7.1 回调式（Option B，单线程，OnFrame 驱动）
+
+应用无阻塞主循环，渲染拆进 VSync 帧回调；一切在 JS 线程。
+
+```
+① 应用启动 → ArkUI 渲染 XComponent(SURFACE)
+② 系统挖 buffer queue → OnSurfaceCreated(comp, OHNativeWindow*)     ← L1
+      → OWB_RegisterSurface(id, surfaceId, nativeWindow, w, h, ...)  ← 入注册表 + 投 SURFACE_CREATED
+③ 库初始化（L3）：找空闲 surface → OWB_AcquireSurface
+      → GPU: eglCreateWindowSurface(OWB_GetNativeWindow(sid))
+④ 每一帧 VSync：OnFrame(comp, ts, target)                           ← L1
+      → OWB_InternalDispatchFrame(sid, ts, target) → 库的帧回调       ← 扇出
+          → OWB_PollEvent 排空事件 → 翻成库事件 → 渲染 → SwapBuffers
+⑤ 输入：DispatchTouch/Mouse/Key(comp)                               ← L1
+      → OWB_PostEvent(&ev) → 事件环(mutex+condvar) → ④ 里被 PollEvent 取走
+⑥ OnSurfaceDestroyed → OWB_UnregisterSurface → 库销毁窗口
+```
+
+**线程（仅回调式）**：XComponent 回调、OnFrame、输入都在应用 UI/JS 线程；库上下文同线程 current，**无需跨线程**。事件环用一把 mutex 护注册表+队列，condvar 唤醒 `OWB_WaitEvent`；**用户回调（帧/反向）在锁外调**，避免重入死锁。
+
+### 7.2 线程壳（Option C，存量 main() 0 改，GLFW demo 实测）
+
+应用保留自己的阻塞主循环，壳用 worker 线程跑它（见 [`napi/owb_ohos_app.h`](napi/owb_ohos_app.h)）。**有两道线程边界**：输入 JS→worker（走队列）、窗口控制 worker→JS（走 TSFN）。
+
+> ⚠ **单进程双 SURFACE 型 XComponent 的边界**：OWB 注册表按 surfaceId 索引，worker 线程壳绑定 surface 后归该线程。同一进程内并存两个 SURFACE 型 XComponent 时，GLFW 窗口只能稳定绑定其一——第二个 surface 的窗口创建 / 上下文在同一 worker TLS 下不可靠（GLFW threads 用例实证：双窗口双 surface 无法共存，须按「单窗口 + 线程 TLS 等价构造」走）。
+
+**流程 A — 应用启动 → 渲染出三角形**
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant ArkUI as ArkTS/系统 (JS线程)
+    participant L1 as 壳+owb_napi (JS线程)
+    participant OWB as OWB核心 bridge.c
+    participant GLFW as 应用main()+GLFW L3 (worker线程)
+    participant GPU as EGL/GLES · OHNativeWindow
+
+    ArkUI->>L1: 按 libraryname 加载 libglfw_demo.so → napi Init(owb_app_napi_init)
+    L1->>L1: OWB_NAPI_HookXComponent — 注册 surface/mouse/touch/frame 回调
+    L1->>OWB: OWB_NAPI_InstallWindowControl → RegisterReverseEventCallback(onReverseEvent)
+    L1->>GLFW: pthread_create(worker) → 调应用 main()
+    Note over L1,GLFW: Init 立即返回，JS线程不被阻塞
+    ArkUI->>L1: Index.ets .onLoad → owbBindWindowControl → setMainWindow(win)
+    L1->>L1: 建 g_windowRef + g_wopTsfn（窗口控制反向桥就绪，供流程B用）
+
+    par worker线程：应用 main()
+        GLFW->>GLFW: glfwInit()（只编OHOS后端→自动选中）+ glfwWindowHint(GLES3)
+        GLFW->>OWB: glfwCreateWindow → bindSurface → GetSurfaceCount()=0
+        GLFW->>OWB: OWB_WaitForSurface(10s) —— 阻塞等 surface
+    and JS线程：surface 就绪
+        ArkUI->>L1: XComponent OnSurfaceCreated(OHNativeWindow)
+        L1->>OWB: OWB_RegisterSurface(sid, OHNativeWindow) + PostEvent(SURFACE_CREATED)
+        OWB-->>GLFW: broadcast g_cond → 唤醒 WaitForSurface
+    end
+
+    GLFW->>OWB: bindSurface 命中 → OWB_AcquireSurface + 取 OHNativeWindow
+    GLFW->>GPU: _glfwInitEGL + eglCreateWindowSurface(OHNativeWindow) → GLES3 上下文
+    GLFW->>GLFW: glfwMakeContextCurrent + glfwSwapInterval(1) + initGL(shader/VBO)
+    loop while(!glfwWindowShouldClose) —— worker线程
+        GLFW->>GPU: render(): glClear + uAngle=glfwGetTime + glDrawArrays
+        GLFW->>GPU: glfwSwapBuffers → eglSwapBuffers（阻塞到 vblank，上屏+节流）
+        GLFW->>OWB: glfwPollEvents → OWB_PollEvent（排空输入队列）
+    end
+    Note over GPU: 屏幕出现旋转彩色三角形
+```
+
+关键点：`glfwCreateWindow` 在 worker 线程**阻塞**在 `OWB_WaitForSurface`，直到 JS 线程 `OnSurfaceCreated` 登记 surface 并 broadcast `g_cond` 唤醒它——这道同步让存量 `main()` 原样跑。
+
+**流程 B — 点击鼠标 → 窗口变大/变小**
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant User as 用户
+    participant ArkUI as ArkTS/系统 (JS线程)
+    participant L1 as owb_napi (JS线程)
+    participant OWB as OWB核心 bridge.c
+    participant GLFW as 应用+GLFW L3 (worker线程)
+
+    User->>ArkUI: 鼠标点击窗口
+    ArkUI->>L1: XComponent DispatchMouseEvent(x,y,PRESS)
+    L1->>OWB: OWB_PostEvent(MOUSE,DOWN) → 入事件队列
+    Note over OWB,GLFW: ══ 线程边界①：输入 JS → worker（队列 mutex+condvar）══
+
+    GLFW->>OWB: glfwPollEvents → OWB_PollEvent 取出
+    OWB->>GLFW: processEvent(MOUSE) → _glfwInputCursorPos + _glfwInputMouseClick(PRESS)
+    GLFW->>GLFW: GLFW 触发应用回调 onMouseButton(win, LEFT, PRESS)
+    GLFW->>GLFW: 循环 s%3 → glfwSetWindowSize(win, 900, 600)
+    GLFW->>OWB: _glfwSetWindowSizeOhos → OWB_RequestWindowOp(SIZE,900,600)
+    OWB->>OWB: 同步调 onReverseEvent(ev)（仍 worker线程）
+    OWB->>L1: napi_call_threadsafe_function(g_wopTsfn, {SIZE,900,600})
+    Note over OWB,L1: ══ 线程边界②：窗口控制 worker → JS（TSFN 投递）══
+
+    L1->>L1: dispatchWindowOp（JS线程）→ 取 g_windowRef = win
+    L1->>ArkUI: napi_call_function(win, "resize", [900,600])
+    ArkUI->>ArkUI: @ohos.window.resize(900,600) → 窗口真的变小
+    ArkUI->>L1: 尺寸变了 → XComponent OnSurfaceChanged(新尺寸)
+    L1->>OWB: OWB_UpdateSurfaceSize + PostEvent(SURFACE_CHANGED)
+    GLFW->>OWB: 下一帧 glfwPollEvents → processEvent(SURFACE_CHANGED)
+    OWB->>GLFW: _glfwInputFramebufferSize → render() 用新尺寸 glViewport
+    Note over GLFW,ArkUI: 窗口变小，三角形按新尺寸继续旋转渲染
+```
+
+关键点：一次点击穿过**两道线程边界**（输入 JS→worker 队列、窗口控制 worker→JS TSFN），但应用只写了 `onMouseButton` 里一句纯 GLFW 的 `glfwSetWindowSize`——跨线程全被 OWB 兜掉。demo 的 `s%3` 循环：`resize(900,600)` / `glfwMaximizeWindow`→`maximize` / `glfwRestoreWindow`→`recover`。触摸走同一条路（`processEvent` 里也翻成 `_glfwInputMouseClick(LEFT)`），故 tap 与鼠标点击都触发 `onMouseButton`。
+
+---
+
+## 8. 设计决策与取舍
+
+| 决策 | 为什么 |
+|---|---|
+| 头文件 `nativeWindow` 用 `void*` | 零 NDK 依赖，且避开 GLFW C99 构建下 `OHNativeWindow` typedef 重定义；消费者自己 cast |
+| CPU 路径 `#ifdef OWB_HAVE_NATIVE_WINDOW` | 不定义就是纯 `libc+pthread` 核心，可在任意 host 单测事件队列；OHOS 构建才拉 native_window |
+| `OWB_MOD_*` 位掩码 = `GLFW_MOD_*` 同值 | GLFW 直传省一次翻译（其他库按需换算）|
+| 事件环满时丢最旧 | 正常 poll 循环不会满（256 深度）；丢最旧保证流不断 |
+| `.so` 强制 `-Wl,-z,max-page-size=0x1000` | 鸿蒙 PC 是 4KB 页，64KB 对齐段 dlopen 直接 SIGSEGV |
+| 库链进 app 自己的 .so、进程内渲染 | 不 spawn 子进程、不建可执行内存 → **绕开 app 域 HNP-exec/io_uring/JIT 三关**，普通签名 HAP、无需 root |
+| 线程壳跑应用 `main()` 在 worker 线程、不在 JS/UI 线程 | 鸿蒙 JS/UI 线程属 ArkUI，不能被应用的阻塞主循环（`while(!shouldClose)`）占死。独立 worker 线程跑 `main()`，跨线程 marshal 回 JS 调 `@ohos.window`——**Qt 鸿蒙 QPA 实证同款**（`pthread_create`+`startQtApplication`+`safeExec`）。OWB 把 marshal 收进库：输入走 mutex+condvar 队列、窗口控制走 `napi_threadsafe_function`，故存量应用 `main()` 零改动、开发者不碰线程 |
+
+---
+
+## 9. 其他库如何复用（开箱即用）
+
+> 📖 **想看一个真实、真机跑通的完整实例？** [docs/EXAMPLE-GLFW.md](docs/EXAMPLE-GLFW.md) 把 GLFW 从 L0（ArkTS 9 行）一路 trace 到 L3（填 vtable），每步带真实代码——照着改最快。
+
+### 契约
+新库拿到 `libohos_window_bridge.{a,so}` + `ohos_window_bridge.h` + ArkTS 宿主 + 骨架模板，**只写 L3**：接渲染输出、接事件源。
+
+### 五步走
+```c
+// 1. 拿 surface
+OWB_SurfaceInfo info; int n = OWB_GetSurfaceCount();
+for (int i=0;i<n;i++){ if (OWB_GetSurfaceInfoByIndex(i,&info)==OWB_OK && !info.inUse){ OWB_AcquireSurface(info.surfaceId); break; } }
+// 2. 建上下文（GPU/EGL）
+EGLSurface s = eglCreateWindowSurface(dpy, cfg, (EGLNativeWindowType)OWB_GetNativeWindow(info.surfaceId), NULL);
+// 3. 事件循环
+OWB_Event ev; while (OWB_PollEvent(&ev)) translate_to_my_library(&ev);
+// 4. 帧驱动（L1 已接 VSync）
+OWB_RegisterFrameCallback(info.surfaceId, onFrame, user);
+// 5. 上屏
+eglSwapBuffers(dpy, s);   // 或 CPU: OWB_AcquireFrame → 写 → OWB_CommitFrame
+```
+
+### 接入方式：两个正交选择（谁提供 NAPI × 应用主循环放哪）
+
+**谁提供 NAPI**
+- **复用现成 L1（推荐）**：napi 模块 Init 里 `OWB_NAPI_HookXComponent(env, exports)`（`napi/owb_napi.cpp`）自动接管所有 XComponent 回调 → OWB；再 `OWB_NAPI_InstallWindowControl` 接上窗口控制桥。
+- **自带 NAPI**：自己注册 XComponent 回调、在 `OnSurfaceCreated` 里 `OWB_RegisterSurface`。
+
+**应用主循环放哪 —— 决定"存量应用改不改"**
+- **① 线程壳（`napi/owb_ohos_app.h`，Qt 鸿蒙 QPA 同款，✅ 真机验证）**：一行
+  ```c
+  OWB_OHOS_THREAD_APP("glfw_demo")   // 放在应用 .c/.cpp 末尾，模块名 = XComponent libraryname
+  ```
+  把应用**原样的** `int main(){ …; while(!glfwWindowShouldClose(w)){ render(); glfwPollEvents(); } }` 搬上鸿蒙——壳占 NAPI 入口（HookXComponent + InstallWindowControl）、`pthread` 起 worker 线程跑 `main()`。`glfwCreateWindow` 在 worker 线程 `OWB_WaitForSurface` 阻塞等 JS 线程 `OnSurfaceCreated` 登记 surface；`glfwSwapInterval(1)` 让 `eglSwapBuffers` 按 vsync 节流（不必 XComponent OnFrame）。**存量桌面应用 `main()` 零改动**，仅需 `int main(int,char**)` 签名（SDL 同款约束）。应用**不 include** OWB/owb_napi/XComponent 任何头。
+- **② 回调式**：应用无阻塞主循环，把渲染拆进 VSync 帧回调（`OWB_RegisterFrameCallback` / XComponent `OnFrame`）。适合新写的鸿蒙原生应用。
+
+> **线程壳为什么安全**（见 §8）：Qt 用 `pthread_create`+`startQtApplication` 在独立线程跑应用事件循环、`safeExec` marshal 回 JS 调 `@ohos.window`——生产级实证。OWB 把这套 marshal 收进库（输入 mutex+condvar 队列、窗口控制 `napi_threadsafe_function`），GLFW/SDL/bgfx 复用同一个 `owb_ohos_app.h` 壳，开发者不碰线程。
+
+### OWB_Event → 库事件 映射
+| OWB 事件 | 载荷 | 典型翻译 |
+|---|---|---|
+| `SURFACE_CHANGED` | `data.surface.{width,height,scale}` | resize / framebuffer-size / content-scale |
+| `SURFACE_DESTROYED`/`WINDOW_CLOSE` | — | window-close / quit |
+| `KEY` | `data.key.{keyCode(OHOS 2000段),action,mods}` | 键盘（OHOS 码需 map，GLFW `ohos_init.c` 有现成参考）|
+| `CHAR` | `data.character.codepoint` | 文本输入 |
+| `MOUSE`/`TOUCH` | `data.mouse/touch.{x,y,button,action,mods}` | 光标移动/按键（触摸可退化成 cursor+左键）|
+| `SCROLL`/`FOCUS`/`BLUR` | … | 滚轮/焦点 |
+
+> action：`UP=0/DOWN=1/MOVE=2/CANCEL=3/REPEAT=4`（各库 PRESS/RELEASE 常量值不一定同，显式翻）。
+
+### 四个库的配方（详见 [`docs/PORTING_KIT.md`](docs/PORTING_KIT.md)）
+- **GLFW（GPU/EGL，已实现范例）**：填 `_GLFWplatform` vtable — `createWindow`=第1+2步、`pollEvents`=`OWB_PollEvent`→`_glfwInput*`、`getEGLNativeWindow`=`OWB_GetNativeWindow`。
+- **SDL2/3（GPU）**：`SDL_VideoDevice` 驱动 — `CreateSDLWindow`=`OWB_Acquire`、`GL_CreateContext`=EGL、`PumpEvents`=`OWB_PollEvent`→`SDL_Send*`。
+- **GTK gdk-ohos / Qt raster QPA（CPU）**：软件后端输出接 `OWB_AcquireFrame/CommitFrame`（cairo ARGB32 预乘 BGRA ↔ OHOS RGBA8888 需换通道），事件接 `OWB_PollEvent`。
+- **Dear ImGui**：最省——直接用 GLFW-OHOS + `imgui_impl_glfw` + `imgui_impl_opengl3`，零新代码。
+
+### 语言绑定库怎么接（pyGLFW 实例 → 通用公式）
+
+已鸿蒙化的原生库之上的**语言绑定**（Python ctypes / node-ffi / Rust -sys…）不需要新后端——绑定库发出的就是 C 调用。通用公式三步：
+
+1. **原生库共享化**：ctypes/FFI 只能加载共享库。原生库加一轮 `SHARED` 构建（GLFW：`-DGLFW_LIBRARY_TYPE=SHARED`），**以 .so 动态链接 OWB**（`OHOS_WINDOW_BRIDGE_LIBRARY`）——库和宿主壳必须共享**同一个** OWB 实例（注册表/队列是进程级状态，静态嵌两份直接坏）。
+2. **加载缝**：优先找绑定库自带的"指定库路径"机制（pyGLFW = `PYGLFW_LIBRARY` 环境变量 → 直接 `CDLL(路径)`）。这类缝通常还能**绕开库搜索/subprocess 探测**——后者在 app 沙箱（exec 受限）必死。找不到这类缝才谈 patch。
+3. **解释器线程壳**（[`napi/owb_ohos_python_app.h`](napi/owb_ohos_python_app.h)）：线程壳的语言运行时变体——worker 跑的 main() 换成"嵌入解释器执行脚本"（Python：`Py_Initialize`+`PyRun_SimpleFileEx`）。一行 `OWB_OHOS_PYTHON_APP("模块名","app/main.py")` 就是 HAP 的全部 native 侧。脚本里的绑定调用与 C 应用走**完全相同**的 OWB 链路（等 surface/事件队列/TSFN 窗口控制），OWB 核心零改动。
+
+打包（真机踩出的三条铁律，端到端记录见 pyGLFW 社区适配仓）：① `.so` 依赖闭包**递归**查到底（readelf 一层不够：libpython→libintl→libiconv、_ctypes→libffi…，少一个=模块加载失败黑屏无日志）；② **hvigor 打 `libs/` 只收 .so**——解释器 stdlib 的源文件放 `resfile/`（`PYTHONHOME` 指过去）；③ **resfile 不可执行映射**——解释器的扩展 .so（lib-dynload）放 `libs/` 子目录、`PYTHONPATH` 指过去。`extractNativeLibs: true`。首个实例：pyGLFW（**零补丁**，真机验证，见社区适配仓）。
+
+### 起步
+复制 [`templates/skeleton-backend/skeleton_backend.c`](templates/skeleton-backend/skeleton_backend.c)（最小可编译 L3：绑 surface→建 EGL→事件循环→清屏+Swap），改名即用。
+
+---
+
+## 10. 构建与产物
+
+```bash
+# 用 DevEco 自带 ohos.toolchain.cmake 交叉编译（arm64-v8a）
+bash build/build.sh          # → dist/libohos_window_bridge.{a,so}（4KB 对齐）
+```
+- 静态 `.a`（28KB）：消费者（如 `libglfw3.a`）defer 链接，最终 .so 再链 native_window。
+- 动态 `.so`（25KB）：NEEDED = `libnative_window.so` + `libc.so`；随 HAP 打进 `entry/libs/arm64-v8a/`。
+
+---
+
+## 11. 状态与验证
+
+| 消费者 | 状态 | 证据 |
+|---|---|---|
+| **GLFW 3.5** | ✅ **真机端到端跑通** | HAD-W32/API23：`OnSurfaceCreated 2090x1324` → `GL_VERSION=OpenGL ES 3.2` → VSync 驱动旋转三角形，无崩溃。截图存 GLFW 社区适配仓 |
+| **GLFW 线程壳（存量 main() 0 改）** | ✅ **真机验证** | worker 线程建 EGL/GLES3 + JS 线程 OHNativeWindow → 旋转三角形；tap→`glfwSetWindowSize(900,600)`、tap→`glfwMaximizeWindow` 均生效（worker→JS 跨线程窗口控制）；CPU 37% 且状态 `S`（eglSwapBuffers vsync 节流、非忙等）；force-stop 无 cppcrash。demo 应用侧 = 纯桌面 `int main(){…}` |
+| **pyGLFW（解释器壳，语言绑定库首例）** | ✅ **真机验证** | 纯 Python（ctypes）经 `libglfw.so` 走同一链路：旋转三角形 GLES3.2；tap→**Python 回调** `glfw.set_window_size/maximize_window` 窗口真变；CPU 14.8% 状态 `S`；pyGLFW **零补丁**。打包三坑（依赖闭包/hvigor libs 只收 .so/resfile 不可执行）记录于 pyGLFW 社区适配仓 |
+| SDL / GTK / Qt-raster / ImGui / bgfx | 🔜 套件就绪 | `docs/PORTING_KIT.md` + `templates/` |
+
+OWB 核心 `bridge.c` 以 `-std=c99 -Wall -Wextra` 对真 NDK 头交叉编译干净；GPU/CPU 双路径 API 均对 `native_window/external_window.h` 校验通过。
+
+---
+
+## 12. 代码地图 & 延伸阅读
+
+```
+ohos_window_bridge/
+├── ARCHITECTURE.md                 ← 本文（权威架构）
+├── README.md                       ← 速览
+│  ─ ★核心缝（库中立 C，零 NAPI/零线程/零 main，不依赖下面任何宿主胶水）─
+├── include/ohos_window_bridge.h    ← 契约（库中立 C API）
+├── src/bridge.c                    ← L2 核心实现
+│  ─ 可选、可插拔宿主胶水（用不用、用几个都行；核心缝不依赖它们）─
+├── napi/owb_napi.{cpp,h}           ← L1 可复用 NAPI（HookXComponent + InstallWindowControl 窗口控制桥）
+├── napi/owb_ohos_app.h             ← 【可选，非核心契约】线程入口壳（OWB_OHOS_THREAD_APP 宏，库中立；存量 main() 0 改上鸿蒙）
+├── napi/owb_ohos_python_app.h      ← 【可选】解释器线程壳（Python 变体：worker 跑 Py_Initialize+PyRun；语言绑定库用，见 §9）
+├── arkts-host/OWBWindowControl.ets ← L0 可复用 ArkTS（owbBindWindowControl 接线 helper）+ README
+├── templates/skeleton-backend/     ← L3 起步模板
+├── docs/PORTING_KIT.md             ← 后端作者手把手配方
+├── docs/EXAMPLE-GLFW.md            ← GLFW 端到端实例（L0→L3，真实代码走一遍）
+└── dist/libohos_window_bridge.{a,so}
+```
+**核心缝 vs 可选宿主胶水**：`include/`+`src/`（L2 核心缝）是库中立 C，**零 NAPI/零线程/零 main、不依赖任何宿主胶水**（`OWB_WaitForSurface` 也只是和 `OWB_WaitEvent` 同类的通用阻塞原语，不是线程/loop 意见）。`napi/`（L1 owb_napi + **入口壳 owb_ohos_app.h**）、`arkts-host/`（L0）是**可选、可插拔的宿主胶水**——依赖方向是 `壳→owb_napi→核心`，核心反过来不知道它们存在。其中**入口壳是可选便利层、非核心契约**：它把"桌面 `main()` 怎么上鸿蒙"这半自动化（Qt QPA 的 `qohmain.cpp` 同位），不想要的应用可改回调式（`OWB_RegisterFrameCallback`/OnFrame），不用壳、不用线程。
+
+**L0/L1/L2 都在包内**，消费者只写 L3。GLFW demo 就是消费者：应用侧只有纯桌面 `int main(){…}` + 末尾一行 `OWB_OHOS_THREAD_APP("glfw_demo")`，ets 里 `import` `OWBWindowControl.ets`——真机验证过这套可复用代码可用（应用不直接碰 owb_napi/OWB 头，全被线程壳吸收）。
+
+- 第一个消费者（L3 范例）：GLFW 社区适配仓的 `src/ohos_{platform.h,init.c,window.c,monitor.c,joystick.c}`
+- 相关知识：4KB 页对齐陷阱见 `pc-knowledge-base/platform/鸿蒙PC-64KB页对齐so崩溃.md`；其余真机原型经验已并入本文
+- 跨平台窗口原理背景：《跨平台窗口系统与图形渲染架构分析报告》（外部分析资料，非本仓）