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

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

@@ -0,0 +1,89 @@
+# ohos_window_bridge (OWB) — 鸿蒙 PC 通用视窗桥
+
+> 把「XComponent(SURFACE) → OHNativeWindow」这道**鸿蒙上唯一的原生像素平台缝**形式化成一个可复用公共层，让任意"自绘像素"的视窗/图形库（GLFW / SDL / GTK gdk-ohos / Qt raster QPA / Dear ImGui / bgfx …）**开箱即用**地搬到鸿蒙 PC，而不必每个库都从零踩一遍缝。
+
+第一个消费者是 GLFW（其鸿蒙后端工程随社区适配仓交付）。本层与 GLFW 解耦，是独立、库中立的资产。
+
+> 📦 **本目录是 pc-adapter 插件内的 vendored 方案资产。** 使用方式：整目录拷贝到目标工作区 `deps/ohos-window-bridge/` 后 `bash build/build.sh` 构建——`dist/` 产物由构建生成、不随插件分发；不要在插件安装目录内构建。
+
+> 📐 **权威架构文档：[ARCHITECTURE.md](ARCHITECTURE.md)**（为什么这么设计、四层详解、其他库怎么接、运行时时序）。
+> 📖 **端到端实例：[docs/EXAMPLE-GLFW.md](docs/EXAMPLE-GLFW.md)**（GLFW L0→L3 真实代码走一遍，照着改最快）。
+> 🔧 手把手移植配方见 [docs/PORTING_KIT.md](docs/PORTING_KIT.md)。本 README 只是速览。
+
+## 为什么需要它
+
+鸿蒙是"托管式渲染"：NDK 层**没有** `createWindow`，应用只有一个 `WindowStage` 托管的系统窗口。第三方引擎拿原生像素通道的**唯一绿色通道**是 `XComponent(type: SURFACE)` → 回调抛出 `OHNativeWindow*`。于是"把一个渲染像素的库搬到鸿蒙"平台相关的**只有这一道缝**，其余库逻辑不动。把缝写成库，新库只写薄薄一层后端。
+
+## 四层架构（新库只碰 L3）
+
+```
+L0  ArkTS 宿主      XComponent({type:SURFACE, libraryname:'<lib>'})  ← 9 行
+L1  NAPI 胶水        OH_NativeXComponent 回调 → OWB_PostEvent          ← 可复用(napi/)
+L2  OWB 核心 ★      surface 注册表 + 库中立事件队列 + VSync 帧扇出     ← 本库(src/bridge.c)
+                     + 双上屏 helper：GPU(OWB_GetNativeWindow)/CPU(OWB_AcquireFrame)
+L3  按库后端         OWB_Event → 库自己的事件；选 GPU/CPU 上屏          ← 各库自己写(templates/)
+```
+
+## 双上屏路径（一个缝覆盖 GPU 库和 CPU 工具包）
+
+| 路径 | API | 交给 | 适配 |
+|---|---|---|---|
+| **GPU** | `void* OWB_GetNativeWindow(surfaceId)` | `eglCreateWindowSurface` / `vkCreateSurfaceOHOS`(VK_OHOS_surface) | GLFW / SDL / bgfx |
+| **CPU-blit** | `OWB_AcquireFrame(surfaceId,&fb)` → 写 `fb.pixels`（用 `fb.stride`！）→ `OWB_CommitFrame` | 内部封装 RequestBuffer→mmap→FlushBuffer | GTK gdk-ohos / Qt raster / ImGui 软件后端 |
+
+CPU 路径把 `stride != width*4` 这唯一易错点（BufferHandle 真实行距）封在库里，调用方拿到的 `fb.stride` 就是对的。
+
+## 目录
+
+```
+ohos_window_bridge/
+│  ── ★核心缝（库中立 C，零 NAPI/零线程/零 main，不依赖下面任何宿主胶水）──
+├── include/ohos_window_bridge.h   # 库中立 C API（头文件零 NDK 依赖）
+├── src/bridge.c                   # L2 核心实现（注册表+队列+帧扇出+双 blit）
+│  ── 可选、可插拔宿主胶水（用不用、用几个都行；核心缝不依赖它们）──
+├── 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 变体）：语言绑定库（pyGLFW 等）的 HAP 入口，一行宏
+├── arkts-host/OWBWindowControl.ets # L0 可复用 ArkTS（owbBindWindowControl 接线 helper + README）
+├── templates/skeleton-backend/    # L3 骨架模板，新库照抄
+├── examples/glfw-triangle/        # ★上屏 demo 本体（L0 Index.ets + L1 glfw_triangle.cpp/CMakeLists，真机验证、照抄起步；MVP 矩阵坑已内建正解）
+├── docs/PORTING_KIT.md            # 后端作者指南（OWB→库回调 映射配方）
+├── docs/EXAMPLE-GLFW.md           # GLFW 端到端实例（L0→L3 真实代码）
+├── build/{CMakeLists.txt,build.sh}
+└── dist/                          # 构建产物 libohos_window_bridge.{a,so}（build.sh 生成，4KB 对齐；不随插件分发）
+```
+> **分层**：`include/`+`src/` 是**核心缝**（像素/事件/帧/窗口控制，库中立、不带线程或 main 意见）；`napi/`（含入口壳 `owb_ohos_app.h`）+ `arkts-host/` 是**可选、可插拔的宿主胶水**（依赖方向 `壳→owb_napi→核心`，核心反过来不依赖它们）。入口壳解决"桌面 `main()` 怎么上鸿蒙"这半（Qt QPA 的 `qohmain.cpp` 同位），是**可选便利**——不想要的应用可改用回调式（`OWB_RegisterFrameCallback`/OnFrame），不用壳、不用线程。
+
+## 构建
+
+```bash
+bash build/build.sh   # 用 DevEco 自带 ohos.toolchain.cmake 出 arm64-v8a .a + .so
+```
+
+`.so` NEEDED = `libnative_window.so` + `libc.so`，LOAD 段 4KB 对齐（`-Wl,-z,max-page-size=0x1000`，否则 dlopen SIGSEGV）。静态 `.a` 不链 native_window（消费者最终 `.so` 再链）。
+
+## API 速览
+
+- 生命周期：`OWB_Initialize/Terminate`
+- 注册表（生产者 L1）：`OWB_RegisterSurface/UnregisterSurface/UpdateSurfaceSize`
+- 查询/绑定（消费者 L3）：`OWB_GetSurfaceCount/GetSurfaceInfoByIndex/ById/ByXComponentId`、`OWB_Acquire/ReleaseSurface`、`OWB_WaitForSurface`（线程壳：worker 线程 createWindow 前阻塞等 surface）
+- **线程入口壳（`napi/owb_ohos_app.h`）**：`OWB_OHOS_THREAD_APP("libraryname")` 一行把存量桌面 `int main(){…while…}` 搬上鸿蒙（worker 线程跑 main、Qt 鸿蒙 QPA 同款、真机验证）。详见 [ARCHITECTURE.md §9 接入方式](ARCHITECTURE.md)
+- 事件：`OWB_PollEvent/WaitEvent/PostEvent/PostEmptyEvent`（`OWB_Event` union，mods 与 `GLFW_MOD_*` 同值）
+- 帧：`OWB_Register/UnregisterFrameCallback` + `OWB_InternalDispatchFrame`（L1 在 OnFrame 里调）
+- GPU：`OWB_GetNativeWindow`
+- CPU：`OWB_AcquireFrame/CommitFrame/AbortFrame`
+- 反向（库→宿主）：`OWB_RegisterReverseEventCallback/NotifyWindowClose`
+- 窗口控制（双向）：`OWB_RequestWindowOp`（Tier B 几何 resize/move/min/max/fullscreen/limits → ArkTS `@ohos.window`）、`OWB_LockCursor/UnlockCursor/GetWindowRect/SetWindowTouchable`（Tier A 纯 native `OH_WindowManager_*`）、`OWB_SetWindowId`。详见 [ARCHITECTURE.md §双向窗口控制](ARCHITECTURE.md)
+
+完整契约见 `include/ohos_window_bridge.h`。移植新库看 `docs/PORTING_KIT.md`。
+
+## 设计要点
+
+- **头文件零 NDK 依赖**：`nativeWindow` 一律 `void*`（避开 GLFW C99 下 `OHNativeWindow` typedef 重定义；消费者自己 cast）。
+- **CPU 路径可裁剪**：`#ifdef OWB_HAVE_NATIVE_WINDOW` 包住，OHOS 构建定义它、链 native_window；不定义就是纯 `libc+pthread` 核心，可在任意 host 单测事件队列。
+- **线程安全**：单 mutex 护注册表+事件环，condvar 唤醒 `OWB_WaitEvent`；用户回调（帧/反向）在锁外调，避免重入死锁。
+
+## 相关知识
+
+- 4KB 页对齐陷阱：`pc-knowledge-base/platform/鸿蒙PC-64KB页对齐so崩溃.md`
+- CPU 像素缝与输入的真机原型经验已并入本方案（见 ARCHITECTURE.md §6 双上屏路径）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/solutions/ohos-window-bridge/arkts-host/OWBWindowControl.ets

@@ -0,0 +1,36 @@
+// OWBWindowControl.ets — 可复用 L0（ArkTS）：把 @ohos.window 主窗口交给 native 窗口控制反向桥。
+//
+// 前提：你的 XComponent 的 native 模块在 Init 里调过 OWB_NAPI_InstallWindowControl(env, exports)
+// （见 ../napi/owb_napi.{cpp,h}），它在 XComponentContext 上挂了 setMainWindow/setWindowId。
+//
+// 用法（app 复制此文件到自己的 ets 目录）：
+//   1) EntryAbility.onWindowStageCreate 里存主窗口：
+//        AppStorage.setOrCreate('owbMainWindow', windowStage.getMainWindowSync());
+//   2) 页面里给 XComponent 配一个 controller，onLoad 里绑定：
+//        private xcCtl: XComponentController = new XComponentController();
+//        XComponent({ id:'x', type: XComponentType.SURFACE, libraryname:'你的库', controller: this.xcCtl })
+//          .onLoad(() => owbBindWindowControl(this.xcCtl, AppStorage.get<window.Window>('owbMainWindow')))
+//   之后库里 glfwSetWindowSize / SDL_SetWindowSize / ... 就会真正驱动 @ohos.window。
+
+import window from '@ohos.window';
+
+// native OWB_NAPI_InstallWindowControl 在 XComponentContext 上导出的方法（显式类型，满足 ArkTS 严格模式）
+interface OwbWindowCtx {
+  setMainWindow: (win: window.Window) => void;
+  setWindowId: (id: number) => void;
+}
+
+/**
+ * 在 XComponent 的 .onLoad() 回调里调一次。
+ * @param ctl 该 XComponent 的 XComponentController
+ * @param win windowStage.getMainWindowSync() 的主窗口（app 先经 AppStorage 存/取）
+ * @returns 绑定是否成功（ctx 或 win 缺失时 false）
+ */
+export function owbBindWindowControl(ctl: XComponentController, win?: window.Window): boolean {
+  if (!win) return false;
+  const ctx = ctl.getXComponentContext() as OwbWindowCtx;
+  if (!ctx) return false;
+  ctx.setMainWindow(win);                          // Tier B 几何 → @ohos.window
+  ctx.setWindowId(win.getWindowProperties().id);   // Tier A native OH_WindowManager_* 用 windowId
+  return true;
+}

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

@@ -0,0 +1,39 @@
+# arkts-host — 可复用 L0（ArkTS 宿主片段）
+
+OWB 的 L0 是**应用侧 ArkTS**，天然和 app 的页面/Ability 绑在一起，所以以**可复制片段**形式提供（不是编译成 HAR）。
+
+## 文件
+- `OWBWindowControl.ets` —— 窗口控制接线 helper `owbBindWindowControl(ctl, win)`。复制到你 app 的 ets 目录即可用。
+
+## 最小接线（两处）
+
+**① `EntryAbility.onWindowStageCreate`：存主窗口**
+```ts
+import Window from '@ohos.window';
+onWindowStageCreate(windowStage: Window.WindowStage) {
+  AppStorage.setOrCreate('owbMainWindow', windowStage.getMainWindowSync());
+  windowStage.loadContent('pages/Index', () => {});
+}
+```
+
+**② 页面：XComponent 配 controller，onLoad 里绑定**
+```ts
+import window from '@ohos.window';
+import { owbBindWindowControl } from '../common/OWBWindowControl';
+
+@Entry @Component struct Index {
+  private xcCtl: XComponentController = new XComponentController();
+  build() {
+    XComponent({ id: 'x', type: XComponentType.SURFACE, libraryname: '你的库', controller: this.xcCtl })
+      .onLoad(() => owbBindWindowControl(this.xcCtl, AppStorage.get<window.Window>('owbMainWindow')))
+      .width('100%').height('100%')
+  }
+}
+```
+
+## 前提
+- 你库的 native 模块在 napi `Init(env, exports)` 里调过 `OWB_NAPI_InstallWindowControl(env, exports)`（见 [`../napi/owb_napi.h`](../napi/owb_napi.h)），它在 XComponentContext 上挂了 `setMainWindow`/`setWindowId`。
+- 渲染/输入本身不需要这段——纯渲染只要 `XComponent({type:SURFACE, libraryname})` 9 行（见 [../README.md](../README.md)）。**窗口控制**（几何/光标）才需要这段接线，因为几何控制在鸿蒙**没有 native 路径、必经 @ohos.window**（NDK 头文件穷举实证，详见 [../ARCHITECTURE.md](../ARCHITECTURE.md) §双向窗口控制）。
+
+## 为什么用 `getXComponentContext()` 而不是 `import '你的库.so'`
+XComponent 用 `libraryname` 自动加载 .so，**不要**再 `import` 它（会触发 `@types/.so` 的 CompileArkTS ENOENT 坑）。`XComponentController.getXComponentContext()` 是拿 native 导出的官方通道，且时序正确（onLoad 时 native 已就绪）。

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

@@ -0,0 +1,288 @@
+# 端到端适配实例：GLFW 是怎么坐在 OWB 上跑起来的（L0 → L3）
+
+> 这是一个**真实、已在鸿蒙 PC 真机跑通**的完整例子（旋转彩色三角形，OpenGL ES 3.2）。想拿 `ohos_window_bridge` 适配自己的库？照着这个例子改最快——每一步都给了仓库里的真实代码 + `文件:行号`。
+>
+> 配套阅读：[../examples/glfw-triangle/](../examples/glfw-triangle/)（**L0/L1 代码本体，真机验证、照抄起步**）、[ARCHITECTURE.md](../ARCHITECTURE.md)（为什么这么设计）、[docs/PORTING_KIT.md](PORTING_KIT.md)（后端作者配方）、[templates/skeleton-backend/](../templates/skeleton-backend/)（L3 后端骨架）。
+
+---
+
+## 1. GLFW 的 L3 到底改了什么（一眼看清"改动极小"）
+
+给 GLFW 加鸿蒙后端 = **5 个新文件** + **5 个上游文件微调（共 52 行）**。GLFW 库本体一行没动。
+
+### 5 个新文件（L3 后端本体，`glfw/src/src/`）
+| 文件 | 行数 | 职责 |
+|---|---|---|
+| `ohos_platform.h` | 135 | `_GLFWwindowOhos`（存 `OHNativeWindow*`+surfaceId）等状态结构 + 4 个 `GLFW_OHOS_*_STATE` 宏 + 全部 `_glfw*Ohos` 声明 |
+| `ohos_init.c` | 168 | `_glfwConnectOhos` 填 `_GLFWplatform` vtable + init/terminate + OHOS↔GLFW 键码映射 |
+| `ohos_window.c` | 468 | **核心**：创建窗口（绑 OWB surface + EGL）、事件泵（OWB→`_glfwInput*`）、EGL 访问器、Vulkan surface、窗口 op |
+| `ohos_monitor.c` | 95 | 单显示器模拟 |
+| `ohos_joystick.c` | 36 | 手柄 stub |
+
+### 5 个上游改动（全在 `glfw/patches/0001-glfw-harmonyos-ohos-backend.patch`，可 rebase 重放）
+| 文件 | +行 | 改了什么 |
+|---|---|---|
+| `include/GLFW/glfw3.h` | 4 | `#define GLFW_PLATFORM_OHOS 0x00060006` |
+| `src/platform.h` | 13 | OHOS `#include` 块 + 4 个聚合宏各加 `GLFW_OHOS_*_STATE` |
+| `src/platform.c` | 8 | `supportedPlatforms[]` 注册 `_glfwConnectOhos` + **两处**平台ID 白名单 |
+| `src/CMakeLists.txt` | 19 | `GLFW_BUILD_OHOS` 源/`_GLFW_OHOS`/`_DEFAULT_SOURCE`/EGL soname 覆盖 |
+| `CMakeLists.txt` | 8 | `GLFW_BUILD_OHOS` 选项 |
+
+> **这正是 OWB 分层的价值**：适配一个库 = "加一个后端 + 几行注册"，平台缝的脏活（surface 管理、事件队列、VSync、上屏）全在 OWB 里，不用重写。
+
+---
+
+## 2. 端到端一次完整调用链（按运行时顺序走一遍）
+
+### L0 — ArkTS 声明（应用写，9 行）
+[`examples/glfw-triangle/ets/Index.ets`](../examples/glfw-triangle/ets/Index.ets)（**本资产内、真机验证过，可直接抄**）：
+```ts
+@Entry @Component struct Index {
+  build() {
+    Stack() {
+      XComponent({ id: 'glfw-main', type: XComponentType.SURFACE, libraryname: 'glfw_demo' })
+        .width('100%').height('100%')
+    }.width('100%').height('100%')
+  }
+}
+```
+`type: SURFACE` 才走原生 surface 路径；`libraryname: 'glfw_demo'` → 系统自动加载 `libglfw_demo.so` 并调它的 napi 模块。**ETS 侧到此为止**，不 import .so、不写控制器。
+
+### L1 — 平台入口壳：一行宏占 NAPI 入口 + 起 worker 线程跑 main()
+demo 应用侧是**纯桌面 GLFW 程序**（[`examples/glfw-triangle/cpp/glfw_triangle.cpp`](../examples/glfw-triangle/cpp/glfw_triangle.cpp) 就一个 `int main()`，**本资产内、真机验证过，可直接抄**），平台入口靠末尾一行宏（`napi/owb_ohos_app.h`）：
+```cpp
+OWB_OHOS_THREAD_APP("glfw_demo")   // 模块名 == XComponent libraryname
+```
+它展开成 demo 的 napi 模块（Qt 鸿蒙 QPA 同款：JS 线程占入口、worker 线程跑应用循环）：
+```cpp
+static napi_value owb_app_napi_init(napi_env env, napi_value exports) {
+    OWB_NAPI_HookXComponent(env, exports);        // ← 复用 L1：注册全部 XComponent 回调 → OWB
+    OWB_NAPI_InstallWindowControl(env, exports);  // ← 复用 L1：窗口控制反向桥（TSFN → @ohos.window）
+    pthread_t th; pthread_create(&th, 0, owb_app_worker, 0);  // ← worker 线程跑应用 main()
+    return exports;
+}
+// napi_module{ nm_register_func=owb_app_napi_init, nm_modname="glfw_demo" } + __constructor__ 注册
+```
+`nm_modname` 必须 == `libraryname`（`"glfw_demo"`）。应用**不写这层、也不 include OWB/owb_napi/XComponent**——全被宏吸收。
+
+### libraryname 怎么串到 native（三处名字为什么必须全等）
+
+L0 只写了 `libraryname: 'glfw_demo'`，L1 的 `owb_app_napi_init` 就被调了——中间靠**同一个字符串 `glfw_demo` 三处全等**把 ArkTS 组件钉到 native 模块上：
+
+| `glfw_demo` 出现处 | 作用 | 定义于 |
+|---|---|---|
+| ArkTS `libraryname:'glfw_demo'` | 告诉 ArkUI 这个 SURFACE XComponent 加载哪个 native 模块 | `Index.ets` |
+| `.so` 文件名 `libglfw_demo.so` | libraryname 解析成 `lib`+name+`.so` 去 dlopen | CMake `add_library(glfw_demo SHARED …)` |
+| `nm_modname = "glfw_demo"` | NAPI 模块注册名；dlopen 后按此名在注册表找 Init | `OWB_OHOS_THREAD_APP("glfw_demo")` 宏 |
+
+**加载链路**：
+1. `.so` 一被 dlopen，宏里的 `__attribute__((constructor))` 就跑 `napi_module_register({ nm_modname="glfw_demo", nm_register_func=owb_app_napi_init })`——进程级 NAPI 模块注册表 +1 条（键 = 模块名）。
+2. ArkUI 建 SURFACE XComponent，读 `libraryname="glfw_demo"` → 让 native module manager 加载模块 "glfw_demo"：dlopen `libglfw_demo.so`（触发步骤 1）→ 在注册表按 **`nm_modname == "glfw_demo"`** 找到模块 → 调 `nm_register_func(env, exports)`。**`libraryname` 与 `nm_modname` 按字符串相等对上，就在这一步。**
+3. 因为 `type=SURFACE`，框架已把 `OH_NativeXComponent` 实例挂在 `exports` 的固定属性 `OH_NATIVE_XCOMPONENT_OBJ` 上；`OWB_NAPI_HookXComponent` 里 `napi_get_named_property(exports, OH_NATIVE_XCOMPONENT_OBJ)` + `napi_unwrap`（`owb_napi.cpp:208`）取出它 → `OH_NativeXComponent_RegisterCallback`。至此 ArkTS 占位组件 ↔ native surface 回调接通。
+
+**对不齐会怎样**（移植你的库时最常见的坑）：
+- `nm_modname` ≠ `libraryname`：`.so` dlopen 成功，但注册表里找不到该名的模块 → **Init 根本不被调** → surface 回调永不触发 → 黑屏，且常常没有明显报错（最坑）。
+- CMake target 名 ≠ libraryname（产出的 `.so` 名不对）：ArkUI 找 `libglfw_demo.so` 失败 → 模块加载不了。
+
+所以 demo 的 `CMakeLists.txt` 才特意注释 "nm_modname / XComponent libraryname must both equal glfw_demo"。
+
+**`exports` 是双向交汇点**：上面 `libraryname` 触发"加载模块 + 把 XComponent 实例下发 native"；反过来，若接窗口控制（在 XComponent 上加 `controller: this.xcCtl`，最小版可省），ArkTS 侧 `XComponentController.getXComponentContext()` 返回的**正是同一个 `exports` 对象**——所以 `owbBindWindowControl(xcCtl, win)` 调 `getXComponentContext().setMainWindow(win)`，就调到了 `OWB_NAPI_InstallWindowControl` 挂在 `exports` 上的 `setMainWindow`（窗口控制反向线的起点）。
+
+### L1 → L2 — surface 创建，登记进 OWB 注册表（JS 线程，`owb_napi.cpp`）
+`OWB_NAPI_HookXComponent` 注册的 `OnSurfaceCreated` 在 JS/UI 线程被调，只做**登记**（不启动 GLFW——那在 worker 线程的 main() 里）：
+```cpp
+static void OnSurfaceCreated(OH_NativeXComponent* comp, void* window) {
+    OHNativeWindow* nw = (OHNativeWindow*)window;      // ← window 直接就是 OHNativeWindow*
+    uint64_t sid = 0;  OH_NativeWindow_GetSurfaceId(nw, &sid);
+    uint64_t w = 0, h = 0;  OH_NativeXComponent_GetXComponentSize(comp, window, &w, &h);
+    OWB_Initialize();
+    OWB_RegisterSurface("owb", sid, nw, (int)w, (int)h, 1.0f, comp);   // ← 入 L2 注册表 + broadcast g_cond
+}
+```
+
+### 应用 main()（worker 线程）— 标准桌面 GLFW，`glfwCreateWindow` 阻塞等 surface
+```cpp
+int main(int argc, char** argv) {                     // ← 应用原样的 main()，零平台代码
+    glfwInit();                                        // ← 只编 OHOS 后端时自动选中 → _glfwConnectOhos 填 vtable
+    glfwWindowHint(GLFW_CLIENT_API, GLFW_OPENGL_ES_API);
+    glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
+    GLFWwindow* w = glfwCreateWindow(1280, 720, "GLFW Demo", 0, 0);  // ← 触发 L3；bindSurface 内 OWB_WaitForSurface 阻塞等上面登记
+    glfwMakeContextCurrent(w);
+    glfwSwapInterval(1);                               // ← eglSwapBuffers 按 vsync 节流（不必 XComponent OnFrame）
+    initGL();                                          // 库自己的 GL 资源（shader/VBO）
+    while (!glfwWindowShouldClose(w)) { render(w); glfwPollEvents(); }   // ← 阻塞主循环，在 worker 线程
+    glfwTerminate(); return 0;
+}
+```
+
+### L3 — `glfwInit()` 把 OHOS 后端接上（`ohos_init.c:70`）
+```c
+GLFWbool _glfwConnectOhos(int platformID, _GLFWplatform* platform) {
+    const _GLFWplatform ohos = {
+        .platformID          = GLFW_PLATFORM_OHOS,
+        .init                = _glfwInitOhos,
+        .createWindow        = _glfwCreateWindowOhos,        // ↓ 下面详解
+        .pollEvents          = _glfwPollEventsOhos,          // ↓ 事件泵
+        .getEGLNativeWindow  = _glfwGetEGLNativeWindowOhos,  // ↓ EGL 拿 native window
+        .createWindowSurface = _glfwCreateWindowSurfaceOhos, // Vulkan（VK_OHOS_surface）
+        /* ... _GLFWplatform 74 个字段全部填满 ... */
+    };
+    *platform = ohos;
+    return GLFW_TRUE;
+}
+```
+`_glfwInitOhos` 里 `OWB_Initialize()` + 注册显示器。
+
+### L3 — `glfwCreateWindow()` 绑 OWB surface + 建 EGL 上下文（`ohos_window.c:73`）
+```c
+static GLFWbool bindSurface(_GLFWwindow* window) {          // ohos_window.c:46
+    for (int attempt = 0; attempt < 2; attempt++) {         // ← 线程壳：worker 线程 createWindow 可能早于 OnSurfaceCreated
+        const int count = OWB_GetSurfaceCount();
+        OWB_SurfaceInfo info;
+        for (int i = 0; i < count; i++) {
+            if (OWB_GetSurfaceInfoByIndex(i, &info) == OWB_OK && !info.inUse) {
+                OWB_AcquireSurface(info.surfaceId);
+                window->ohos.nativeWindow = info.nativeWindow;  // ← 存 OHNativeWindow*
+                window->ohos.surfaceId    = info.surfaceId;
+                window->ohos.width = info.width; window->ohos.height = info.height;
+                return GLFW_TRUE;
+            }
+        }
+        if (attempt == 0) OWB_WaitForSurface(10.0);         // ← 阻塞等 JS 线程 OnSurfaceCreated 登记（g_cond 唤醒）
+    }
+    return GLFW_FALSE;
+}
+
+GLFWbool _glfwCreateWindowOhos(_GLFWwindow* window, const _GLFWwndconfig* wndconfig,
+                               const _GLFWctxconfig* ctxconfig, const _GLFWfbconfig* fbconfig) {
+    if (!bindSurface(window)) { _glfwInputError(...); return GLFW_FALSE; }   // ← 从 L2 取 surface
+    if (ctxconfig->client != GLFW_NO_API) {
+        if (!_glfwInitEGL()) return GLFW_FALSE;
+        if (!_glfwCreateContextEGL(window, ctxconfig, fbconfig)) return GLFW_FALSE;  // ← 复用 GLFW 通用 EGL
+        _glfwRefreshContextAttribs(window, ctxconfig);
+    }
+    window->ohos.visible = wndconfig->visible;
+    return GLFW_TRUE;
+}
+```
+GLFW 通用的 `egl_context.c` 不用改，它只经三个访问器回调平台。OHOS 的关键那个：
+```c
+EGLNativeWindowType _glfwGetEGLNativeWindowOhos(_GLFWwindow* window) {
+    return (EGLNativeWindowType) window->ohos.nativeWindow;   // ← EGL surface 绑到 OHNativeWindow
+}
+// 另两个：getEGLPlatform→0；getEGLNativeDisplay→EGL_DEFAULT_DISPLAY
+```
+到这里，`eglCreateWindowSurface(dpy, cfg, OHNativeWindow*, ...)` 成功 → GL ES 3.2 上下文就绪。
+
+### 每一帧 — 应用 main() 的 while 循环驱动（worker 线程），eglSwapBuffers 按 vsync 节流
+```cpp
+// glfw_triangle.cpp —— 应用自己的主循环（worker 线程），没有 XComponent OnFrame
+while (!glfwWindowShouldClose(w)) {
+    render(w);          // glViewport/glClear/glDrawArrays + glfwSwapBuffers（EGL swap 上屏，阻塞到 vblank）
+    glfwPollEvents();   // → L3 _glfwPollEventsOhos → OWB_PollEvent → processEvent → _glfwInput*
+}
+```
+> 线程壳下**没有 XComponent OnFrame**：`glfwSwapInterval(1)` 使 `eglSwapBuffers` 阻塞到 vblank，天然把 worker 循环节流到刷新率（真机实测 CPU 状态 `S`、非忙等）。输入仍从 JS 线程经 L2 队列跨线程送到 worker 的 `glfwPollEvents`。
+>
+> ⚠ **`render()` 里的 MVP 矩阵是上屏头号坑**（GLFW 转换实测止步 partial 的真凶）：透视矩阵写错致 `m[15]=0 → w=0`、顶点被裁到无穷远，或 C **行主序**矩阵直喂**列主序** GLSL → **全黑窗**，且极易被误判成「EGL 失败 / libEGL 缺 / GL 环境不可用」（实则鸿蒙 PC GLES/EGL 开箱即用）。**正解与告警就写在 [`examples/glfw-triangle/cpp/glfw_triangle.cpp`](../examples/glfw-triangle/cpp/glfw_triangle.cpp) 的 `while` 循环注释里**（该 demo 顶点落 NDC ±0.5、用 2D 旋转、无需透视）——**照抄它、别从零写渲染**。黑屏先按矩阵 + `GL_COMPILE_STATUS` + `GL_RENDERER` 打点排查。
+```c
+// ohos_window.c:204（L3）—— GLFW 的事件泵：把 OWB 事件翻成 GLFW 事件
+void _glfwPollEventsOhos(void) {
+    OWB_Event ev;
+    while (OWB_PollEvent(&ev))          // ← 从 L2 队列取
+        processEvent(&ev);             // ↓
+}
+static void processEvent(const OWB_Event* ev) {                 // ohos_window.c:132
+    _GLFWwindow* window = findWindowBySurfaceId(ev->surfaceId);
+    switch (ev->type) {
+        case OWB_EVENT_KEY: {
+            int key = _glfwMapOhosKeyCode(ev->data.key.keyCode); // OHOS 2000段码→GLFW key
+            _glfwInputKey(window, key, ev->data.key.scanCode,
+                          owbActionToGlfw(ev->data.key.action), (int)ev->data.key.mods);
+            break; }
+        case OWB_EVENT_MOUSE:
+            _glfwInputCursorPos(window, ev->data.mouse.x, ev->data.mouse.y);
+            if (ev->data.mouse.action == OWB_ACTION_DOWN)
+                _glfwInputMouseClick(window, ev->data.mouse.button, GLFW_PRESS, (int)ev->data.mouse.mods);
+            break;
+        case OWB_EVENT_SURFACE_CHANGED:
+            _glfwInputWindowSize(window, ev->data.surface.width, ev->data.surface.height);
+            _glfwInputFramebufferSize(window, ev->data.surface.width, ev->data.surface.height);
+            break;
+        /* ... TOUCH / SCROLL / FOCUS / WINDOW_CLOSE ... */
+    }
+}
+```
+
+---
+
+## 3. 输入一次流转（触摸 → GLFW 回调）
+
+```
+用户点屏 [JS/UI 线程]
+  → [L1] DispatchTouchEvent(comp, window)              owb_napi.cpp（HookXComponent 注册）
+        OH_NativeXComponent_GetTouchEvent(&te)
+        ev.type=OWB_EVENT_TOUCH; ev.data.touch={te.x,te.y,action}
+        OWB_PostEvent(&ev)                              → 投进 L2 事件队列
+  → [L2] 事件环（mutex+condvar）暂存                     ══ 线程边界（JS → worker）══
+  → [L3] worker 线程 glfwPollEvents → OWB_PollEvent 取出 → processEvent
+        OWB_EVENT_TOUCH 分支：_glfwInputCursorPos + _glfwInputMouseClick(LEFT)
+  → [App] onMouseButton 回调（worker 线程）→ glfwSetWindowSize/Maximize
+  → [L3→L1] OWB_RequestWindowOp → 反向回调 → TSFN            ══ 线程边界（worker → JS）══
+  → [L0] JS 线程调 @ohos.window.resize/maximize            窗口真的变大小
+```
+生产者（L1 投）与消费者（L3 取）经 L2 队列解耦——这就是为什么 L1 可以完全库无关；跨线程两个方向都由 OWB 兜底（输入队列 + 窗口控制 TSFN），应用不碰线程。
+
+---
+
+## 4. 谁调用谁（跨层 call graph）
+
+```
+ 应用/ArkTS ─┐
+             │ 声明 XComponent(libraryname)
+ 系统 ───────┼─► 加载 libglfw_demo.so ─► 壳 napi Init（owb_ohos_app.h）──► HookXComponent + InstallWindowControl + pthread(main)
+             │                                                        │
+ [JS 线程] OnSurfaceCreated ──► OWB_RegisterSurface ──────────────────┼─► [L2 OWB] surface 注册表（broadcast g_cond）
+ [worker] main(): glfwInit / glfwCreateWindow ───────────────────────┼─► [L3] _glfwConnectOhos / _glfwCreateWindowOhos
+                                     └─ bindSurface: OWB_WaitForSurface 阻塞等 ↑          │
+                                                                     │        └─► OWB_GetSurfaceInfoByIndex / OWB_GetNativeWindow ─► [L2]
+                                                                     │        └─► _glfwInitEGL + getEGLNativeWindow ─► eglCreateWindowSurface(OHNativeWindow)
+ [worker] while(!shouldClose): glfwPollEvents ─► [L3] _glfwPollEventsOhos ─┼─► OWB_PollEvent ─► [L2] 事件队列
+                         └─► render ─► glDrawArrays + glfwSwapBuffers ─┼─► EGL ─► 上屏（vsync 节流）
+ [JS 线程] DispatchTouch ──► OWB_PostEvent ───────────────────────────┘─► [L2] 事件队列 ─(worker 下一轮取)
+```
+**只有 L3（`ohos_*.c`）是 GLFW 特有的。L0/L1/L2 + 线程壳对任何库都一样。**
+
+---
+
+## 5. 换成你的库要改哪些（把 GLFW 的做法映射回通用五步）
+
+GLFW 的 L3 就是 [PORTING_KIT](PORTING_KIT.md) 五步的一个具体实例：
+
+| PORTING_KIT 通用步骤 | GLFW L3 对应实现 |
+|---|---|
+| ① 拿 surface（`OWB_GetSurfaceInfoByIndex`+`Acquire`）| `bindSurface`（`ohos_window.c:46`）|
+| ② 建上下文（EGL native window = `OWB_GetNativeWindow`）| `_glfwGetEGLNativeWindowOhos` + `_glfwCreateContextEGL` |
+| ③ 事件循环（`OWB_PollEvent` → 翻译）| `_glfwPollEventsOhos` + `processEvent`（`:132`）|
+| ④ 帧驱动（线程壳：应用主循环自驱 / 回调式：`OWB_RegisterFrameCallback`）| demo main() `while(!glfwWindowShouldClose){ render; glfwPollEvents }`（worker 线程，`glfwSwapInterval(1)` 节流）|
+| ⑤ 上屏（`eglSwapBuffers` / `OWB_CommitFrame`）| `glfwSwapBuffers`（GLFW 内部 EGL swap）|
+
+**架构映射**：GLFW 用"填 `_GLFWplatform` vtable"这种插件模型接后端；你的库可能是 SDL 的 `SDL_VideoDevice` 驱动、Qt 的 QPA plugin、GTK 的 gdk backend——形式不同，但要做的都是这五件事。CPU 自绘工具包（GTK/Qt-raster）把第②⑤步换成 `OWB_AcquireFrame`/`OWB_CommitFrame` 即可。
+
+**起步**：复制 [`templates/skeleton-backend/skeleton_backend.c`](../templates/skeleton-backend/skeleton_backend.c)（一个把这五步走完的最小可编译 L3），改名，把清屏换成你库的渲染、把 `switch` 换成你库的事件类型。
+
+---
+
+## 附：完整源码位置
+
+| 层 | 文件 | 位置 |
+|---|---|---|
+| L0 | [`examples/glfw-triangle/ets/Index.ets`](../examples/glfw-triangle/ets/Index.ets) | **本资产内，可直接抄** |
+| L1 | [`examples/glfw-triangle/cpp/{glfw_triangle.cpp, CMakeLists.txt}`](../examples/glfw-triangle/) | **本资产内，可直接抄** |
+| L2 | `{include/ohos_window_bridge.h, src/bridge.c}` | 本资产内 |
+| L3 | `glfw/src/src/ohos_{platform.h,init.c,window.c,monitor.c,joystick.c}` | GLFW 社区适配仓（供对照）|
+| 上游改动 | `glfw/patches/0001-glfw-harmonyos-ohos-backend.patch` | GLFW 社区适配仓（可 rebase 重放）|
+
+> **L0/L1/L2 与 `templates/skeleton-backend/` 都在本方案资产内、可直接抄**；L3（GLFW 鸿蒙后端本体）与上游 patch 属 GLFW 社区适配仓，此处按 `文件:行号` 供对照，不进插件包。
+>
+> **构建/装机/上屏取证**（都用插件自带 CLI，无需社区仓脚本）：`harmony-demo` 工程就绪后 → 签名装机 `ohpt-agent sign-demo -w <ws> --install` → 上屏取证 `ohpt-agent verify-demo -w <ws>`（截图 + GL 身份落 `build/demo-verify.json`）。

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

@@ -0,0 +1,120 @@
+# OWB 移植套件 — 把一个视窗/图形库搬到鸿蒙 PC
+
+面向**后端作者**：你有一个库（GLFW/SDL/GTK/Qt/ImGui/bgfx…），想让它在鸿蒙 PC 上创建窗口、渲染、收输入。本套件告诉你**只需写一层 L3**，其余（XComponent 缝、事件队列、上屏）OWB 已包好。
+
+> 🚀 **上屏 demo 别从零写**：L0/L1 应用本体（含正确 MVP 矩阵、GL 排障打点）已 vendored 在 [`../examples/glfw-triangle/`](../examples/glfw-triangle/)（真机验证），照抄改 `render()` 即可；全黑窗十有八九是矩阵坑而非 EGL/GL 环境。端到端走查见 [EXAMPLE-GLFW.md](EXAMPLE-GLFW.md)。
+
+## 心智模型
+
+鸿蒙上"搬一个渲染像素的库"= 把库的**两个接触点**接到 OWB：
+
+1. **渲染输出** → 上屏：GPU 走 `OWB_GetNativeWindow` 交 EGL/Vulkan；CPU 走 `OWB_AcquireFrame/CommitFrame`。
+2. **事件源** → 输入：`OWB_PollEvent` 排空，翻成库自己的事件类型。
+
+其余库逻辑一行不改。判据：*"这个库平台相关的还有别的吗？"* —— 在鸿蒙上答案基本是"没有，只有这道缝"。
+
+## 五步走
+
+1. **拿一个 surface**：`OWB_GetSurfaceCount` + `OWB_GetSurfaceInfoByIndex` 找一个 `!inUse` 的（或 `OWB_GetSurfaceInfoByXComponentId` 显式按 id 绑），`OWB_AcquireSurface(surfaceId)`。存下 `nativeWindow`(void*→OHNativeWindow*) + `surfaceId` + `width/height/scale`。
+2. **建渲染上下文**：
+   - GPU/EGL：`eglGetDisplay(EGL_DEFAULT_DISPLAY)` → `eglInitialize` → 选 config → `eglCreateWindowSurface(dpy,cfg,(EGLNativeWindowType)OWB_GetNativeWindow(sid),NULL)` → `eglCreateContext` → `eglMakeCurrent`。
+   - GPU/Vulkan：`vkCreateSurfaceOHOS(inst,&{sType=1000685000,.window=OWB_GetNativeWindow(sid)},NULL,&surface)`（动态取 `vkGetInstanceProcAddr(inst,"vkCreateSurfaceOHOS")`；实例扩展要 `VK_KHR_surface`+`VK_OHOS_surface`）。
+   - CPU：不用上下文，直接每帧 `OWB_AcquireFrame`。
+3. **事件循环**：在你库的 `pollEvents` 里 `while(OWB_PollEvent(&ev)) translate(&ev)`，把 `OWB_Event` 翻成库事件。`OWB_WaitEvent(&ev,timeout)` 做阻塞版。
+4. **帧驱动**：L1 已 `OH_NativeXComponent_RegisterOnFrameCallback` → `OWB_InternalDispatchFrame`。你 `OWB_RegisterFrameCallback(sid, cb, user)` 收 VSync；或自己 driven-loop。
+5. **上屏**：GPU `eglSwapBuffers`（EGL surface 就是那道缝）；CPU `OWB_AcquireFrame`→写像素→`OWB_CommitFrame`。
+
+## OWB_Event → 库事件 映射表（通用）
+
+| OWB_EventType | 载荷 | 典型翻译 |
+|---|---|---|
+| `SURFACE_CHANGED` | `data.surface.{width,height,scale}` | resize / framebuffer-size / content-scale 回调 |
+| `SURFACE_DESTROYED` / `WINDOW_CLOSE` | — | window-close / quit |
+| `KEY` | `data.key.{keyCode(OHOS码),scanCode,action,mods}` | 键盘（OHOS 码需映射，见下）|
+| `CHAR` | `data.character.codepoint` | 文本输入 |
+| `MOUSE` | `data.mouse.{x,y,button,action,mods}` | 光标移动 / 按键 |
+| `TOUCH` | `data.touch.{x,y,id,action,pressure}` | 触摸（桌面库可退化成 cursor+左键）|
+| `SCROLL` | `data.scroll.{xoffset,yoffset}` | 滚轮 |
+| `FOCUS`/`BLUR` | — | 焦点 |
+
+- **mods 位掩码**故意与 `GLFW_MOD_*` 同值（SHIFT=1/CTRL=2/ALT=4/SUPER=8/CAPS=0x10/NUM=0x20），GLFW 直传；别的库按需换算。
+- **action**：`OWB_ACTION_UP=0/DOWN=1/MOVE=2/CANCEL=3/REPEAT=4`。注意各库 PRESS/RELEASE 常量值不一定同，显式翻。
+- **OHOS 键码**在 2000 段：`KEY_A=2017..Z` 连续、`KEY_0=2000..9`、`ESCAPE=2070`、方向键 `DPAD_UP/DOWN/LEFT/RIGHT=2012/2013/2014/2015`、`SPACE=2050`、`ENTER=2054`。写个 `mapOhosKeyCode()`（GLFW 后端 `ohos_init.c` 有现成参考）。
+
+## 具体配方
+
+### GLFW（GPU/EGL，已实现，作范例）
+填 `_GLFWplatform` vtable：`createWindow`=第1+2步、`pollEvents`=`OWB_PollEvent`→`_glfwInput*`、`getEGLNativeWindow`=`OWB_GetNativeWindow`。完整实现见 GLFW 社区适配仓的 `src/ohos_*.c`。
+
+### SDL2 / SDL3（GPU）
+写一个 `SDL_VideoDevice` 驱动 `ohos`：
+- `VideoInit`：`OWB_Initialize` + 注册一个 display。
+- `CreateSDLWindow`：`OWB_Acquire` + 存 `OHNativeWindow*` 到 `window->driverdata`。
+- `GL_CreateContext` / `GL_SwapWindow`：走 SDL 自带 EGL 路径，`_this->egl_data->egl_display=eglGetDisplay(EGL_DEFAULT_DISPLAY)`，native window = `OWB_GetNativeWindow`。
+- `PumpEvents`：`while(OWB_PollEvent(&ev)) { SDL_SendKeyboardKey / SDL_SendMouseMotion / SDL_SendMouseButton / SDL_SendWindowEvent(RESIZED) … }`。
+- 帧：SDL 通常自 driven，不需要 OnFrame；忽略 `OWB_RegisterFrameCallback` 即可。
+
+### GTK gdk-ohos / Qt raster QPA（CPU-blit）
+软件后端把像素画进内存位图，再 blit 上屏：
+- 每帧/每次重绘：`OWB_AcquireFrame(sid,&fb)` 拿 `{pixels,width,height,stride}`。
+- 把工具包的 image surface 逐行 `memcpy` 进 `fb.pixels + y*fb.stride`（**务必用 fb.stride，不是 width*4**）。
+- **通道序**：cairo `ARGB32` 是预乘、小端字节序 BGRA；OHOS buffer 是 RGBA8888 —— 逐像素换 R/B 或用 cairo 的 RGBA 变体，别直接 memcpy 全图（会红蓝互换）。
+- `OWB_CommitFrame(sid)` 上屏。
+- 事件：QPA `QWindowSystemInterface::handleMouseEvent/handleKeyEvent` 或 gdk 的 `gdk_event_put`，源自 `OWB_PollEvent`。
+- 参考 Qt 鸿蒙移植版 QPA 的 backingstore 实现（见 `qt-toolchain` 能力域）——同样的 AcquireFrame→逐行拷贝→Commit 形态。
+
+### Dear ImGui（最易，第二块拼图）
+- GL 后端：直接用 GLFW-OHOS + `imgui_impl_glfw` + `imgui_impl_opengl3`（ES loader）——零新代码，GLFW 后端已经把缝铺好。
+- 软件后端：`OWB_AcquireFrame` + 自绘 draw list 光栅化。
+
+## L1 NAPI（多数库不用自己写）
+
+`napi/owb_napi.cpp` 是库中立的：ArkTS 声明 `XComponent(libraryname:'<你的库>')`，NAPI 模块 Init 注册 XComponent 回调，把 surface/输入/OnFrame 全转成 `OWB_*`。你的库若想复用它，nm_modname 对上即可；若要在同一个 .so 里做初始化（如 GLFW demo），照 GLFW 社区适配仓 demo 的 `glfw_triangle.cpp` 自带 NAPI 入口。
+
+## 窗口控制（可选，双向）
+
+你库的「设置窗口大小/全屏/最小化/标题」等，OWB 也桥好了（GLFW 后端已用、真机验证）：
+- **几何**（resize/move/min/max/fullscreen/limits/title）：`OWB_RequestWindowOp(sid, OWB_WOP_*, a,b,c,d, str)` → 反向回调 → 宿主 NAPI `threadsafe_function` → ArkTS `@ohos.window`。**几何无 native 路径**（NDK 不暴露，Qt QPA 亦如此），必经此桥。
+- **光标锁定/真实 pos/passthrough**：`OWB_LockCursor/GetWindowRect/SetWindowTouchable`（Tier A 纯 native `OH_WindowManager_*`）。
+- **宿主接线**：ArkTS 经 `XComponentController.getXComponentContext()` 调 native 的 `setMainWindow(win)`+`setWindowId(id)`（把 `@ohos.window` mainWindow 对象 + `getWindowProperties().id` 传下来一次）；NAPI 注册 `OWB_RegisterReverseEventCallback` 在 JS 线程直调 Window 方法。
+
+详见 [ARCHITECTURE.md §双向窗口控制](../ARCHITECTURE.md)；端到端接线实例（`dispatchWindowOp`/`SetMainWindow` + `pages/Index.ets`）见 GLFW 社区适配仓 demo。
+
+### 尺寸限制 / 宽高比：无 WM 强制，客户端必须自己夹
+
+鸿蒙窗口管理器对 resize **原样执行、无 size hints 强制**——X11/Win32 上由 WM 兜底的 `SetWindowSizeLimits` / `SetWindowAspectRatio` 约束，OHOS 后端必须**客户端自己夹**：
+
+```c
+// 伪代码：min 用 max 抬、max 用 min 压，四段独立、不要 else-if 互斥
+void applySizeLimits(win, int* w, int* h) {
+    if (aspect 已设)  *h = *w / (numer / denom);   // 先按宽高比推高
+    if (minw 已设)    *w = max(*w, minw);
+    if (minh 已设)    *h = max(*h, minh);
+    if (maxw 已设)    *w = min(*w, maxw);
+    if (maxh 已设)    *h = min(*h, maxh);
+}
+```
+
+三处硬约束（某 GUI 后端首轮三处全踩、叠加致一条用例 fail）：
+- **调用点**：resize 入口夹一次；set-limits / set-aspect 变更时对当前尺寸再夹一次——别只夹「设置时」那一次
+- **禁 else-if 互斥**：设了 min 就永不夹 max
+- **禁方向写反**：min 是下限（max 抬）、max 是上限（min 压）
+
+> 成品写法以 GLFW 后端为范例：`ohos_window.c` 的 `applySizeLimits`。
+
+### OWB Initialize / Terminate 非引用计数
+
+`OWB_Initialize` / `OWB_Terminate` **不是引用计数**——反复 init/terminate 会清空 XComponent surface 注册表，后续 `bindSurface` 直接失败。共享 init 生命周期（名册 / 多窗口用例）下：**只 init 一次**，用例之间只 create/destroy window，绝不 terminate 再 init。
+
+## 骨架
+
+`templates/skeleton-backend/` 是一个最小可编译 L3：拿 surface → 建 EGL → 事件循环打印 → 清屏上色。复制改名即可起步。
+
+## 语言绑定库（ctypes/FFI，本 kit 之外的一类）
+
+绑定库（pyGLFW / node-ffi / Rust -sys …）**不写 L3 后端**——它调的是已移植的原生库。通用公式（首例 pyGLFW，见社区适配仓）：
+1. 原生库出 **SHARED**（ctypes 只能 CDLL 共享库），且**动态链 OWB.so**（进程内一份 OWB 实例；静态嵌两份注册表/队列必坏）。
+2. 用绑定库自带"**指定库路径**"缝（pyGLFW=`PYGLFW_LIBRARY` 环境变量→直接 CDLL，绕开 app 沙箱里必死的 subprocess 探测）→ 绑定库常可**零补丁**。
+3. HAP 入口用**解释器线程壳** `napi/owb_ohos_python_app.h`：`OWB_OHOS_PYTHON_APP("模块名","app/main.py")` 一行 = worker 线程 `Py_Initialize`+`PyRun(main.py)`。脚本发出的即 worker 线程 C 调用，OWB 链路零改动。
+
+详见 [ARCHITECTURE.md §9 语言绑定库怎么接](../ARCHITECTURE.md)。