线程模型

两条规则，都不难，违反了很难查。

规则一：引擎函数只在创建它的那条线程上调用

所有 ysu_engine_* 函数都必须从 ysu_engine_new 所在的那条线程调用。包括查询类的函数——ysu_engine_document_height 也算。

原因在底下：引擎内部持有 wgpu 的设备与队列，wgpu 设备不跨线程共享。这不是可以绕过的限制，是 GPU API 的性质。

代码里没有任何运行时检查。 YsuEngine 在 Rust 侧不是 Send / Sync，但一旦变成 C 指针，这层保护就没了。C 编译器也看不见。所以这条规则靠调用方自律。

实际的约束是：外壳的界面线程建引擎，界面线程用它。

规则二：`ysu_fetch` 的回调在后台线程上执行

这是唯一的例外，也是唯一一处跨线程。

void ysu_fetch(const char *url, bool as_page, YsuFetchCallback callback, void *userdata);

每次调用起一条新线程：在那条线程上建连接、取内容、然后在那条线程上调用回调。

也就是说回调函数体里：

不能碰界面。 任何 GUI 工具包都要求界面对象只在界面线程上访问。Qt 会直接崩或者在调试模式下报 QObject: Cannot create children for a parent that is in a different thread。

不能碰引擎。 回调里调 ysu_engine_load_html 是违规的——见规则一。

可以碰 userdata。 那是调用方自己的内存，但要注意它必须活到回调返回。

外壳是怎么处理的

ui/src/main_window.cpp 里的回调是个静态自由函数，它只做一件事：把 C 字符串拷成 Qt 的 QString，然后用队列连接投回界面线程。

static void onFetched(void *userdata, const char *url, const char *payload, const char *error) {
    auto *request = static_cast<FetchRequest *>(userdata);
    const QString urlText = QString::fromUtf8(url != nullptr ? url : "");
    const QString bodyText = QString::fromUtf8(payload != nullptr ? payload : "");
    const QString errorText = error != nullptr ? QString::fromUtf8(error) : QString();

    QMetaObject::invokeMethod(
        request->window,
        [request, urlText, bodyText, errorText] {
            if (request->window != nullptr) {
                request->window->finishFetch(request, urlText, bodyText, errorText);
            }
            delete request;
        },
        Qt::QueuedConnection);
}