@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-window-bridge/napi/owb_ohos_python_app.h

@@ -0,0 +1,92 @@
+/*
+ * owb_ohos_python_app.h — 解释器线程壳（Python 变体，库中立）
+ * ---------------------------------------------------------------------------
+ * 线程壳（owb_ohos_app.h）的语言运行时变体：worker 线程跑的"应用 main()"不再是
+ * C 代码，而是**嵌入 CPython 执行一个 Python 脚本**（社区 CPython 嵌入指南同款：
+ * setenv(PYTHONHOME) → Py_Initialize → PySys_SetArgvEx → PyRun_SimpleFileEx）。
+ * 脚本里经 ctypes/FFI 绑定（如 pyGLFW）发出的全是 worker 线程上的普通 C 调用——
+ * 对 OWB/视窗库来说与 C 应用无异：createWindow 照样阻塞等 surface、输入照样走
+ * 事件队列、窗口控制照样走 TSFN。OWB 核心与跨线程设施零改动。
+ *
+ * 用法（HAP 的 native 侧只需这一个 .cpp）：
+ *   #include "owb_ohos_python_app.h"
+ *   OWB_OHOS_PYTHON_APP("pyglfw_demo", "pyglfw-app/main.py")
+ *   //                   ^XComponent libraryname  ^resfile 下的脚本相对路径
+ *
+ * Python 侧约定（main.py 开头）：
+ *   import sys, os
+ *   sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'site-packages'))
+ *   os.environ['PYGLFW_LIBRARY'] = '/data/storage/el1/bundle/libs/arm64/libglfw.so'
+ *   import glfw   # pyGLFW 零补丁：PYGLFW_LIBRARY 分支直接 CDLL，不走 subprocess 探测
+ *
+ * 打包约定（HAP）：
+ *   libs/arm64-v8a/libpython3.12.so.1.0 + Python/lib/python3.12（stdlib，PYTHONHOME 指它）
+ *   libs/arm64-v8a/libglfw.so + libohos_window_bridge.so（绑定库要 dlopen 的原生库）
+ *   resources/resfile/<你的应用>/main.py + site-packages/（纯 py 依赖）
+ *   module.json5: "extractNativeLibs": true（libpython 需真实文件供 dlopen）
+ *
+ * 可覆盖项（include 前 #define）：
+ *   OWB_PY_HOME    PYTHONHOME（默认 /data/storage/el1/bundle/libs/arm64/Python）
+ *   OWB_PY_LOG     stdout/stderr 重定向文件（默认 el2 files 下 owb_python.log；
+ *                  定义为空串 "" 则不重定向）
+ *
+ * 定位：与 owb_ohos_app.h 同族的**可选宿主胶水，非核心契约**——语言胶水（怎么把
+ * 一个"脚本应用"变成 main()）+ 窗口胶水（线程壳）的组合。库中立：无任何 glfw
+ * 符号，SDL/其他库的 Python 绑定同样适用。仅消费者编译时需要 Python.h/libpython。
+ * ---------------------------------------------------------------------------
+ */
+#ifndef OWB_OHOS_PYTHON_APP_H
+#define OWB_OHOS_PYTHON_APP_H
+
+#include <Python.h>          /* CPython 要求先于系统头 include */
+#include <stdio.h>
+#include <stdlib.h>
+#include "owb_ohos_app.h"    /* 线程壳：#define main owb_app_main + OWB_OHOS_THREAD_APP */
+
+/* Python 运行时拆两处（真机踩出的打包铁律）：
+ *   stdlib 的 .py 树 → resfile（hvigor 打包 libs/ **只收 .so**，.py 被静默过滤 →
+ *     Py_Initialize 找不到 encodings）→ PYTHONHOME 指 resfile/Python。
+ *   lib-dynload 扩展 .so → libs/lib-dynload（resfile **不可执行映射**，dlopen 扩展
+ *     "No error information" 失败）→ PYTHONPATH 指过去，import 时按 sys.path 找到。 */
+#ifndef OWB_PY_HOME
+#define OWB_PY_HOME "/data/storage/el1/bundle/entry/resources/resfile/Python"
+#endif
+#ifndef OWB_PY_DYNLOAD
+#define OWB_PY_DYNLOAD "/data/storage/el1/bundle/libs/arm64/lib-dynload"
+#endif
+#ifndef OWB_PY_LOG
+#define OWB_PY_LOG  "/data/storage/el2/base/files/owb_python.log"
+#endif
+#define OWB_PY_RESFILE_ROOT "/data/storage/el1/bundle/entry/resources/resfile/"
+
+/* 展开成应用的 main()（被 owb_ohos_app.h 改名为 owb_app_main，跑在壳的 worker 线程）
+ * + 线程壳三件套（napi 模块入口/注册）。 */
+#define OWB_OHOS_PYTHON_APP(MODNAME, SCRIPT_RELPATH)                                   \
+    int main(int argc, char** argv) {                                                  \
+        (void)argc; (void)argv;                                                        \
+        const char* script = OWB_PY_RESFILE_ROOT SCRIPT_RELPATH;                        \
+        if (OWB_PY_LOG[0]) {   /* python 的 print/异常落文件，真机排障用 */             \
+            freopen(OWB_PY_LOG, "w", stdout);                                          \
+            freopen(OWB_PY_LOG, "a", stderr);                                          \
+            setvbuf(stdout, (char*)0, _IONBF, 0);                                      \
+            setvbuf(stderr, (char*)0, _IONBF, 0);                                      \
+        }                                                                              \
+        setenv("PYTHONHOME", OWB_PY_HOME, 1);                                          \
+        setenv("PYTHONPATH", OWB_PY_DYNLOAD, 1);  /* 扩展 .so 在 libs 下（可执行映射）*/ \
+        setenv("PYTHONUNBUFFERED", "1", 1);                                            \
+        FILE* fp = fopen(script, "r");                                                 \
+        if (!fp) { fprintf(stderr, "owb_py: script not found: %s\n", script); return 1; } \
+        Py_Initialize();     /* 本 worker 线程即 Python 主线程 */                       \
+        int rc = 1;                                                                    \
+        wchar_t* argv0 = Py_DecodeLocale(script, (size_t*)0);                          \
+        if (argv0) {                                                                   \
+            PySys_SetArgvEx(1, &argv0, 1);  /* updatepath=1：脚本目录进 sys.path[0] */  \
+            rc = PyRun_SimpleFileEx(fp, script, 1);   /* closeit=1：跑完关文件 */       \
+            PyMem_RawFree(argv0);                                                      \
+        }                                                                              \
+        if (Py_IsInitialized()) Py_Finalize();                                         \
+        return rc;                                                                     \
+    }                                                                                  \
+    OWB_OHOS_THREAD_APP(MODNAME)
+
+#endif /* OWB_OHOS_PYTHON_APP_H */

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

@@ -0,0 +1,604 @@
+/*
+ * bridge.c — OpenHarmony Window Bridge (OWB) core implementation
+ * See include/ohos_window_bridge.h for the design & API contract.
+ *
+ * Threading: one global mutex guards the surface table + event ring; one
+ * condvar wakes OWB_WaitEvent. User callbacks (frame / reverse) are invoked
+ * OUTSIDE the lock (copied under lock, called after unlock) to avoid deadlock
+ * if a callback re-enters OWB.
+ *
+ * The CPU-blit path (OWB_AcquireFrame/CommitFrame/AbortFrame) needs the OHOS
+ * NativeWindow NDK; it is compiled only when OWB_HAVE_NATIVE_WINDOW is defined
+ * (the OHOS build sets it). Without it the core still builds on any host for
+ * unit-testing the registry + event queue.
+ */
+#define _POSIX_C_SOURCE 200809L   /* expose clock_gettime/CLOCK_REALTIME/timedwait under -std=c99 */
+
+#include "ohos_window_bridge.h"
+
+#include <pthread.h>
+#include <string.h>
+#include <time.h>
+#include <errno.h>
+
+#ifdef OWB_HAVE_NATIVE_WINDOW
+#include <native_window/external_window.h>
+#include <sys/mman.h>
+#include <unistd.h>
+#include <stdbool.h>
+/* window_manager/oh_window.h 误 #include <cstddef>（C++ 专用），无法在纯 C 里包含。
+ * 只包含 C 安全的 comm 头（拿 WindowManager_WindowProperties 等结构），并手动前置声明
+ * 用到的 C-ABI 函数（libnative_window_manager.so 导出 C 符号，nm 已确认无 mangling）。*/
+#include <window_manager/oh_window_comm.h>
+int32_t OH_WindowManager_LockCursor(int32_t windowId, bool isCursorFollowMovement);
+int32_t OH_WindowManager_UnlockCursor(int32_t windowId);
+int32_t OH_WindowManager_GetWindowProperties(int32_t windowId, WindowManager_WindowProperties* props);
+int32_t OH_WindowManager_SetWindowTouchable(int32_t windowId, bool isTouchable);
+#endif
+
+/* ------------------------------------------------------------- internal state */
+typedef struct {
+    int      used;
+    uint64_t surfaceId;
+    void*    nativeWindow;                 /* OHNativeWindow* */
+    int32_t  width, height;
+    float    scale;
+    char     id[OWB_ID_MAX];
+    int32_t  inUse;
+    void*    xcomponent;
+    int32_t  windowId;                     /* @ohos.window 窗口 id（Tier A native 用）*/
+    /* per-surface VSync frame callback */
+    OWB_FrameCallback frameCb;
+    void*             frameUser;
+#ifdef OWB_HAVE_NATIVE_WINDOW
+    /* in-flight CPU-blit buffer */
+    OHNativeWindowBuffer* curBuf;
+    void*                 curPixels;
+    size_t                curSize;
+    int                   curFenceFd;
+#endif
+} OWB_Surface;
+
+static pthread_mutex_t g_lock  = PTHREAD_MUTEX_INITIALIZER;
+static pthread_cond_t  g_cond  = PTHREAD_COND_INITIALIZER;
+static int             g_inited = 0;
+
+static OWB_Surface g_surfaces[OWB_MAX_SURFACES];
+
+static OWB_Event g_queue[OWB_MAX_EVENT_QUEUE];
+static int       g_qhead, g_qtail, g_qcount;
+static int       g_wakeup;                 /* OWB_PostEmptyEvent flag */
+
+static OWB_ReverseEventCallback g_reverseCb;
+static void*                    g_reverseUser;
+static int32_t                  g_windowId;   /* app 主窗口 id（ArkTS 传下，单窗口）*/
+
+/* --------------------------------------------------------------------- utils */
+static OWB_Surface* find_by_id_locked(uint64_t surfaceId)
+{
+    for (int i = 0; i < OWB_MAX_SURFACES; i++)
+        if (g_surfaces[i].used && g_surfaces[i].surfaceId == surfaceId)
+            return &g_surfaces[i];
+    return NULL;
+}
+
+static void fill_info(const OWB_Surface* s, OWB_SurfaceInfo* out)
+{
+    out->surfaceId    = s->surfaceId;
+    out->nativeWindow = s->nativeWindow;
+    out->width        = s->width;
+    out->height       = s->height;
+    out->scale        = s->scale;
+    out->inUse        = s->inUse;
+    out->xcomponent   = s->xcomponent;
+    memcpy(out->id, s->id, OWB_ID_MAX);
+}
+
+/* ----------------------------------------------------------------- lifecycle */
+int OWB_Initialize(void)
+{
+    pthread_mutex_lock(&g_lock);
+    if (!g_inited) {
+        memset(g_surfaces, 0, sizeof(g_surfaces));
+        memset(g_queue, 0, sizeof(g_queue));
+        g_qhead = g_qtail = g_qcount = 0;
+        g_wakeup = 0;
+        g_inited = 1;
+        /* 注意：不清 g_reverseCb/g_reverseUser —— 宿主 NAPI 模块 Init 阶段可能在
+         * OWB_Initialize 之前就注册了反向回调（窗口控制桥），清掉会让它失效。*/
+    }
+    pthread_mutex_unlock(&g_lock);
+    return OWB_OK;
+}
+
+void OWB_Terminate(void)
+{
+    pthread_mutex_lock(&g_lock);
+    g_inited = 0;
+    g_qhead = g_qtail = g_qcount = 0;
+    memset(g_surfaces, 0, sizeof(g_surfaces));
+    pthread_mutex_unlock(&g_lock);
+}
+
+/* -------------------------------------------------------------- surface table */
+int OWB_RegisterSurface(const char* id, uint64_t surfaceId, void* nativeWindow,
+                        int32_t width, int32_t height, float scale, void* xcomponent)
+{
+    pthread_mutex_lock(&g_lock);
+    /* dedup: update in place if the surfaceId already exists */
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    if (!s) {
+        for (int i = 0; i < OWB_MAX_SURFACES; i++)
+            if (!g_surfaces[i].used) { s = &g_surfaces[i]; break; }
+    }
+    if (!s) { pthread_mutex_unlock(&g_lock); return OWB_ERR_FULL; }
+
+    memset(s, 0, sizeof(*s));
+    s->used         = 1;
+    s->surfaceId    = surfaceId;
+    s->nativeWindow = nativeWindow;
+    s->width        = width;
+    s->height       = height;
+    s->scale        = (scale > 0.0f) ? scale : 1.0f;
+    s->xcomponent   = xcomponent;
+    if (id) { strncpy(s->id, id, OWB_ID_MAX - 1); s->id[OWB_ID_MAX - 1] = '\0'; }
+    pthread_mutex_unlock(&g_lock);
+
+    OWB_Event ev; memset(&ev, 0, sizeof(ev));
+    ev.type = OWB_EVENT_SURFACE_CREATED;
+    ev.surfaceId = surfaceId;
+    ev.data.surface.width = width;
+    ev.data.surface.height = height;
+    ev.data.surface.scale = s->scale;
+    OWB_PostEvent(&ev);
+    return OWB_OK;
+}
+
+int OWB_UnregisterSurface(uint64_t surfaceId)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    if (!s) { pthread_mutex_unlock(&g_lock); return OWB_ERR_NOT_FOUND; }
+    memset(s, 0, sizeof(*s));
+    pthread_mutex_unlock(&g_lock);
+
+    OWB_Event ev; memset(&ev, 0, sizeof(ev));
+    ev.type = OWB_EVENT_SURFACE_DESTROYED;
+    ev.surfaceId = surfaceId;
+    OWB_PostEvent(&ev);
+    return OWB_OK;
+}
+
+int OWB_UpdateSurfaceSize(uint64_t surfaceId, int32_t width, int32_t height, float scale)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    if (!s) { pthread_mutex_unlock(&g_lock); return OWB_ERR_NOT_FOUND; }
+    s->width = width;
+    s->height = height;
+    if (scale > 0.0f) s->scale = scale;
+    float sc = s->scale;
+    pthread_mutex_unlock(&g_lock);
+
+    OWB_Event ev; memset(&ev, 0, sizeof(ev));
+    ev.type = OWB_EVENT_SURFACE_CHANGED;
+    ev.surfaceId = surfaceId;
+    ev.data.surface.width = width;
+    ev.data.surface.height = height;
+    ev.data.surface.scale = sc;
+    OWB_PostEvent(&ev);
+    return OWB_OK;
+}
+
+int OWB_GetSurfaceCount(void)
+{
+    int n = 0;
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < OWB_MAX_SURFACES; i++) if (g_surfaces[i].used) n++;
+    pthread_mutex_unlock(&g_lock);
+    return n;
+}
+
+int OWB_GetSurfaceInfoByIndex(int index, OWB_SurfaceInfo* out)
+{
+    if (!out || index < 0) return OWB_ERR_INVALID;
+    int n = 0, rc = OWB_ERR_NOT_FOUND;
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < OWB_MAX_SURFACES; i++) {
+        if (!g_surfaces[i].used) continue;
+        if (n == index) { fill_info(&g_surfaces[i], out); rc = OWB_OK; break; }
+        n++;
+    }
+    pthread_mutex_unlock(&g_lock);
+    return rc;
+}
+
+int OWB_GetSurfaceInfoById(uint64_t surfaceId, OWB_SurfaceInfo* out)
+{
+    if (!out) return OWB_ERR_INVALID;
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    if (s) fill_info(s, out);
+    pthread_mutex_unlock(&g_lock);
+    return s ? OWB_OK : OWB_ERR_NOT_FOUND;
+}
+
+int OWB_GetSurfaceInfoByXComponentId(const char* id, OWB_SurfaceInfo* out)
+{
+    if (!out || !id) return OWB_ERR_INVALID;
+    int rc = OWB_ERR_NOT_FOUND;
+    pthread_mutex_lock(&g_lock);
+    for (int i = 0; i < OWB_MAX_SURFACES; i++) {
+        if (g_surfaces[i].used && strncmp(g_surfaces[i].id, id, OWB_ID_MAX) == 0) {
+            fill_info(&g_surfaces[i], out); rc = OWB_OK; break;
+        }
+    }
+    pthread_mutex_unlock(&g_lock);
+    return rc;
+}
+
+int OWB_AcquireSurface(uint64_t surfaceId)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    int rc = OWB_ERR_NOT_FOUND;
+    if (s) { s->inUse = 1; rc = OWB_OK; }
+    pthread_mutex_unlock(&g_lock);
+    return rc;
+}
+
+int OWB_ReleaseSurface(uint64_t surfaceId)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    int rc = OWB_ERR_NOT_FOUND;
+    if (s) { s->inUse = 0; rc = OWB_OK; }
+    pthread_mutex_unlock(&g_lock);
+    return rc;
+}
+
+/* 阻塞到至少 1 个 surface 登记（线程壳：worker 线程的 glfwCreateWindow 等 JS 线程
+ * OnSurfaceCreated）。复用 g_cond —— OWB_RegisterSurface 里的 OWB_PostEvent 会 broadcast。*/
+int OWB_WaitForSurface(double timeoutSec)
+{
+    int have = 0, i;
+    pthread_mutex_lock(&g_lock);
+    for (i = 0; i < OWB_MAX_SURFACES; i++)
+        if (g_surfaces[i].used) { have = 1; break; }
+
+    if (!have && timeoutSec < 0.0) {
+        while (!have) {
+            pthread_cond_wait(&g_cond, &g_lock);
+            for (i = 0; i < OWB_MAX_SURFACES; i++)
+                if (g_surfaces[i].used) { have = 1; break; }
+        }
+    } else if (!have) {
+        struct timespec ts;
+        clock_gettime(CLOCK_REALTIME, &ts);
+        long secs  = (long)timeoutSec;
+        long nsecs = (long)((timeoutSec - (double)secs) * 1e9);
+        ts.tv_sec  += secs;
+        ts.tv_nsec += nsecs;
+        if (ts.tv_nsec >= 1000000000L) { ts.tv_sec++; ts.tv_nsec -= 1000000000L; }
+        while (!have) {
+            if (pthread_cond_timedwait(&g_cond, &g_lock, &ts) == ETIMEDOUT) break;
+            for (i = 0; i < OWB_MAX_SURFACES; i++)
+                if (g_surfaces[i].used) { have = 1; break; }
+        }
+    }
+    pthread_mutex_unlock(&g_lock);
+    return have ? OWB_OK : OWB_ERR_NOT_FOUND;
+}
+
+/* --------------------------------------------------------------------- events */
+int OWB_PostEvent(const OWB_Event* ev)
+{
+    if (!ev) return OWB_ERR_INVALID;
+    pthread_mutex_lock(&g_lock);
+    if (g_qcount == OWB_MAX_EVENT_QUEUE) {
+        /* queue full: drop oldest to keep the stream flowing */
+        g_qhead = (g_qhead + 1) % OWB_MAX_EVENT_QUEUE;
+        g_qcount--;
+    }
+    g_queue[g_qtail] = *ev;
+    g_qtail = (g_qtail + 1) % OWB_MAX_EVENT_QUEUE;
+    g_qcount++;
+    pthread_cond_broadcast(&g_cond);
+    pthread_mutex_unlock(&g_lock);
+    return OWB_OK;
+}
+
+void OWB_PostEmptyEvent(void)
+{
+    pthread_mutex_lock(&g_lock);
+    g_wakeup = 1;
+    pthread_cond_broadcast(&g_cond);
+    pthread_mutex_unlock(&g_lock);
+}
+
+static int dequeue_locked(OWB_Event* out)
+{
+    if (g_qcount == 0) return 0;
+    *out = g_queue[g_qhead];
+    g_qhead = (g_qhead + 1) % OWB_MAX_EVENT_QUEUE;
+    g_qcount--;
+    return 1;
+}
+
+int OWB_PollEvent(OWB_Event* out)
+{
+    if (!out) return 0;
+    pthread_mutex_lock(&g_lock);
+    int got = dequeue_locked(out);
+    pthread_mutex_unlock(&g_lock);
+    return got;
+}
+
+int OWB_WaitEvent(OWB_Event* out, double timeout)
+{
+    if (!out) return 0;
+    pthread_mutex_lock(&g_lock);
+
+    if (g_qcount == 0 && !g_wakeup) {
+        if (timeout < 0.0) {
+            while (g_qcount == 0 && !g_wakeup)
+                pthread_cond_wait(&g_cond, &g_lock);
+        } else {
+            struct timespec ts;
+            clock_gettime(CLOCK_REALTIME, &ts);
+            long secs  = (long)timeout;
+            long nsecs = (long)((timeout - (double)secs) * 1e9);
+            ts.tv_sec  += secs;
+            ts.tv_nsec += nsecs;
+            if (ts.tv_nsec >= 1000000000L) { ts.tv_sec++; ts.tv_nsec -= 1000000000L; }
+            while (g_qcount == 0 && !g_wakeup) {
+                if (pthread_cond_timedwait(&g_cond, &g_lock, &ts) == ETIMEDOUT)
+                    break;
+            }
+        }
+    }
+    g_wakeup = 0;
+    int got = dequeue_locked(out);
+    pthread_mutex_unlock(&g_lock);
+    return got;
+}
+
+/* ------------------------------------------------------ frame callback (VSync) */
+int OWB_RegisterFrameCallback(uint64_t surfaceId, OWB_FrameCallback cb, void* userData)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    int rc = OWB_ERR_NOT_FOUND;
+    if (s) { s->frameCb = cb; s->frameUser = userData; rc = OWB_OK; }
+    pthread_mutex_unlock(&g_lock);
+    return rc;
+}
+
+int OWB_UnregisterFrameCallback(uint64_t surfaceId)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    int rc = OWB_ERR_NOT_FOUND;
+    if (s) { s->frameCb = NULL; s->frameUser = NULL; rc = OWB_OK; }
+    pthread_mutex_unlock(&g_lock);
+    return rc;
+}
+
+void OWB_InternalDispatchFrame(uint64_t surfaceId, uint64_t ts, uint64_t targetTs)
+{
+    /* snapshot cb under lock, invoke outside */
+    OWB_FrameCallback cb = NULL;
+    void* user = NULL;
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    if (s) { cb = s->frameCb; user = s->frameUser; }
+    pthread_mutex_unlock(&g_lock);
+    if (cb) cb(surfaceId, ts, targetTs, user);
+}
+
+/* ------------------------------------------------ reverse channel（库 → 宿主） */
+int OWB_RegisterReverseEventCallback(OWB_ReverseEventCallback cb, void* userData)
+{
+    pthread_mutex_lock(&g_lock);
+    g_reverseCb = cb;
+    g_reverseUser = userData;
+    pthread_mutex_unlock(&g_lock);
+    return OWB_OK;
+}
+
+void OWB_NotifyWindowClose(uint64_t surfaceId)
+{
+    OWB_ReverseEventCallback cb;
+    void* user;
+    pthread_mutex_lock(&g_lock);
+    cb = g_reverseCb;
+    user = g_reverseUser;
+    pthread_mutex_unlock(&g_lock);
+    if (cb) {
+        OWB_Event ev; memset(&ev, 0, sizeof(ev));
+        ev.type = OWB_EVENT_WINDOW_CLOSE;
+        ev.surfaceId = surfaceId;
+        cb(&ev, user);
+    }
+}
+
+/* --------------------------------------------------- 窗口控制（双向，L3 调用） */
+void OWB_SetWindowId(uint64_t surfaceId, int32_t windowId)
+{
+    pthread_mutex_lock(&g_lock);
+    g_windowId = windowId;                 /* app 级单窗口，全局兜底 */
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    if (s) s->windowId = windowId;
+    pthread_mutex_unlock(&g_lock);
+}
+
+int32_t OWB_GetWindowId(uint64_t surfaceId)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    int32_t wid = (s && s->windowId) ? s->windowId : g_windowId;
+    pthread_mutex_unlock(&g_lock);
+    return wid;
+}
+
+/* Tier B：几何控制无 native 路径，走反向回调 → 宿主 NAPI 直调 @ohos.window */
+int OWB_RequestWindowOp(uint64_t surfaceId, OWB_WindowOp op,
+                        int32_t a, int32_t b, int32_t c, int32_t d, const char* str)
+{
+    OWB_ReverseEventCallback cb;
+    void* user;
+    pthread_mutex_lock(&g_lock);
+    cb = g_reverseCb;
+    user = g_reverseUser;
+    pthread_mutex_unlock(&g_lock);
+    if (!cb) return OWB_ERR_NOT_FOUND;     /* 宿主未注册 ArkTS 窗口控制 → 库应回落 unavailable */
+
+    OWB_Event ev; memset(&ev, 0, sizeof(ev));
+    ev.type = OWB_EVENT_REQ_WINDOW_OP;
+    ev.surfaceId = surfaceId;
+    ev.data.winop.op  = (int32_t)op;
+    ev.data.winop.a   = a;
+    ev.data.winop.b   = b;
+    ev.data.winop.c   = c;
+    ev.data.winop.d   = d;
+    ev.data.winop.str = str;
+    cb(&ev, user);                          /* 同步；宿主负责 marshal 到 JS 线程 */
+    return OWB_OK;
+}
+
+/* Tier A：纯 native 窗口属性（OH_WindowManager_*，需 windowId） */
+#ifdef OWB_HAVE_NATIVE_WINDOW
+int OWB_LockCursor(uint64_t surfaceId, int follow)
+{
+    int32_t wid = OWB_GetWindowId(surfaceId);
+    if (wid <= 0) return OWB_ERR_NOT_FOUND;
+    return (OH_WindowManager_LockCursor(wid, follow ? true : false) == 0) ? OWB_OK : OWB_ERR_STATE;
+}
+
+int OWB_UnlockCursor(uint64_t surfaceId)
+{
+    int32_t wid = OWB_GetWindowId(surfaceId);
+    if (wid <= 0) return OWB_ERR_NOT_FOUND;
+    return (OH_WindowManager_UnlockCursor(wid) == 0) ? OWB_OK : OWB_ERR_STATE;
+}
+
+int OWB_GetWindowRect(uint64_t surfaceId, int32_t* x, int32_t* y, int32_t* w, int32_t* h)
+{
+    int32_t wid = OWB_GetWindowId(surfaceId);
+    if (wid <= 0) return OWB_ERR_NOT_FOUND;
+    WindowManager_WindowProperties props;
+    memset(&props, 0, sizeof(props));
+    if (OH_WindowManager_GetWindowProperties(wid, &props) != 0) return OWB_ERR_STATE;
+    if (x) *x = props.windowRect.posX;
+    if (y) *y = props.windowRect.posY;
+    if (w) *w = (int32_t)props.windowRect.width;
+    if (h) *h = (int32_t)props.windowRect.height;
+    return OWB_OK;
+}
+
+int OWB_SetWindowTouchable(uint64_t surfaceId, int touchable)
+{
+    int32_t wid = OWB_GetWindowId(surfaceId);
+    if (wid <= 0) return OWB_ERR_NOT_FOUND;
+    return (OH_WindowManager_SetWindowTouchable(wid, touchable ? true : false) == 0) ? OWB_OK : OWB_ERR_STATE;
+}
+#else  /* host build: no window_manager NDK */
+int OWB_LockCursor(uint64_t s, int f)        { (void)s; (void)f; return OWB_ERR_STATE; }
+int OWB_UnlockCursor(uint64_t s)             { (void)s; return OWB_ERR_STATE; }
+int OWB_GetWindowRect(uint64_t s, int32_t* x, int32_t* y, int32_t* w, int32_t* h)
+                                             { (void)s;(void)x;(void)y;(void)w;(void)h; return OWB_ERR_STATE; }
+int OWB_SetWindowTouchable(uint64_t s, int t){ (void)s; (void)t; return OWB_ERR_STATE; }
+#endif
+
+/* --------------------------------------------------------------- GPU 上屏路径 */
+void* OWB_GetNativeWindow(uint64_t surfaceId)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    void* w = s ? s->nativeWindow : NULL;
+    pthread_mutex_unlock(&g_lock);
+    return w;
+}
+
+/* ------------------------------------------- CPU-blit 上屏路径（软件渲染工具包） */
+#ifdef OWB_HAVE_NATIVE_WINDOW
+int OWB_AcquireFrame(uint64_t surfaceId, OWB_FrameBuffer* out)
+{
+    if (!out) return OWB_ERR_INVALID;
+
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    if (!s || !s->nativeWindow) { pthread_mutex_unlock(&g_lock); return OWB_ERR_NOT_FOUND; }
+    if (s->curBuf) { pthread_mutex_unlock(&g_lock); return OWB_ERR_STATE; } /* already acquired */
+    OHNativeWindow* win = (OHNativeWindow*)s->nativeWindow;
+    pthread_mutex_unlock(&g_lock);
+
+    OHNativeWindowBuffer* buf = NULL;
+    int fenceFd = -1;
+    if (OH_NativeWindow_NativeWindowRequestBuffer(win, &buf, &fenceFd) != 0 || !buf)
+        return OWB_ERR_STATE;
+
+    BufferHandle* bh = OH_NativeWindow_GetBufferHandleFromNative(buf);
+    if (!bh) { OH_NativeWindow_NativeWindowAbortBuffer(win, buf); return OWB_ERR_STATE; }
+
+    /* map the buffer; stride comes from the handle (may exceed width*4) */
+    void* p = mmap(bh->virAddr, bh->size, PROT_READ | PROT_WRITE, MAP_SHARED, bh->fd, 0);
+    if (p == MAP_FAILED) { OH_NativeWindow_NativeWindowAbortBuffer(win, buf); return OWB_ERR_STATE; }
+
+    pthread_mutex_lock(&g_lock);
+    s = find_by_id_locked(surfaceId);
+    if (!s) { pthread_mutex_unlock(&g_lock); munmap(p, bh->size);
+              OH_NativeWindow_NativeWindowAbortBuffer(win, buf); return OWB_ERR_NOT_FOUND; }
+    s->curBuf     = buf;
+    s->curPixels  = p;
+    s->curSize    = bh->size;
+    s->curFenceFd = fenceFd;
+    pthread_mutex_unlock(&g_lock);
+
+    out->pixels = p;
+    out->width  = bh->width;
+    out->height = bh->height;
+    out->stride = bh->stride;
+    return OWB_OK;
+}
+
+int OWB_CommitFrame(uint64_t surfaceId)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    if (!s || !s->curBuf) { pthread_mutex_unlock(&g_lock); return OWB_ERR_STATE; }
+    OHNativeWindow*       win = (OHNativeWindow*)s->nativeWindow;
+    OHNativeWindowBuffer* buf = s->curBuf;
+    void*  p       = s->curPixels;
+    size_t sz      = s->curSize;
+    int    fenceFd = s->curFenceFd;
+    s->curBuf = NULL; s->curPixels = NULL; s->curSize = 0; s->curFenceFd = -1;
+    pthread_mutex_unlock(&g_lock);
+
+    Region region; region.rects = NULL; region.rectNumber = 0; /* full-surface flush */
+    int rc = OH_NativeWindow_NativeWindowFlushBuffer(win, buf, fenceFd, region);
+    munmap(p, sz);
+    return (rc == 0) ? OWB_OK : OWB_ERR_STATE;
+}
+
+int OWB_AbortFrame(uint64_t surfaceId)
+{
+    pthread_mutex_lock(&g_lock);
+    OWB_Surface* s = find_by_id_locked(surfaceId);
+    if (!s || !s->curBuf) { pthread_mutex_unlock(&g_lock); return OWB_ERR_STATE; }
+    OHNativeWindow*       win = (OHNativeWindow*)s->nativeWindow;
+    OHNativeWindowBuffer* buf = s->curBuf;
+    void*  p  = s->curPixels;
+    size_t sz = s->curSize;
+    s->curBuf = NULL; s->curPixels = NULL; s->curSize = 0; s->curFenceFd = -1;
+    pthread_mutex_unlock(&g_lock);
+
+    munmap(p, sz);
+    OH_NativeWindow_NativeWindowAbortBuffer(win, buf);
+    return OWB_OK;
+}
+#else  /* !OWB_HAVE_NATIVE_WINDOW — host build (no NDK): CPU path unavailable */
+int OWB_AcquireFrame(uint64_t surfaceId, OWB_FrameBuffer* out) { (void)surfaceId; (void)out; return OWB_ERR_STATE; }
+int OWB_CommitFrame(uint64_t surfaceId) { (void)surfaceId; return OWB_ERR_STATE; }
+int OWB_AbortFrame(uint64_t surfaceId)  { (void)surfaceId; return OWB_ERR_STATE; }
+#endif