lumiview 0.1.0.dev2__tar.gz → 0.1.0.dev3__tar.gz

{lumiview-0.1.0.dev2 → lumiview-0.1.0.dev3}/Cargo.lock

@@ -804,7 +804,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "lumiview"
-version = "0.1.0-dev2"
+version = "0.1.0-dev3"
 dependencies = [
  "gtk",
  "pyo3",

{lumiview-0.1.0.dev2 → lumiview-0.1.0.dev3}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lumiview"
-version = "0.1.0-dev2"
+version = "0.1.0-dev3"
 edition = "2021"
 description = "Python binding for tao — cross-platform window management."
 readme = "README.md"

{lumiview-0.1.0.dev2 → lumiview-0.1.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumiview
-Version: 0.1.0.dev2
+Version: 0.1.0.dev3
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -82,6 +82,14 @@ flowchart TB
 
 **Threading model:** Main thread (event loop + native ops) → Async thread (asyncio + user coroutines) → Thread pool (synchronous code).
 
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Architecture & Threading Model](docs/architecture.md)
+- [Custom Plugins](docs/plugins.md)
+- [Third-Party Integrations](docs/integrations.md)
+- [Serve Protocol](docs/serve.md)
+
 ## Installation
 
 ```bash
@@ -91,17 +99,17 @@ pip install --pre lumiview
 ## Quick Start
 
 ```python
-from lumiview import App, Window
+from lumiview import App, Window, WindowOptions
 
 app = App(name="HelloLumiView")
 
 async def main():
-    win = await Window.create(
+    win = await Window.create(WindowOptions(
         title="Hello LumiView!",
         url="https://example.com",
         width=900, height=640,
         devtools=True,
-    )
+    ))
     title = await win.eval_js("document.title")
     print(f"Page title: {title}")
 
@@ -135,7 +143,7 @@ For runnable code, see the [`examples/`](examples/) directory.
 - [x] Window management (TaoWindow + Window)
 - [x] WebView embedding (wryview)
 - [x] JS ↔ Python Bridge (invoke/listen IPC)
-- [x] Hook event system (AppHookEvent / WindowHookEvent)
+- [x] Event class system (WindowEvent / AppEvent)
 - [x] Unified async/sync `Task` interface
 - [x] Static file serving + WSGI proxy
 - [x] ASGI adapter (FastAPI, Starlette, etc.)
@@ -148,6 +156,8 @@ For runnable code, see the [`examples/`](examples/) directory.
 
 This is an early-stage project — **your feedback is crucial**.
 
+Due to limited personal time, some features may not be completed promptly — PRs and other contributions are warmly welcomed.
+
 - 🐛 [Report Bugs](https://github.com/xiaosuawa/LumiView/issues)
 - 💡 [Share Ideas](https://github.com/xiaosuawa/LumiView/discussions)
 - 🔧 [Contribution Guide](CONTRIBUTING.md)

{lumiview-0.1.0.dev2 → lumiview-0.1.0.dev3}/README.md

@@ -50,6 +50,14 @@ flowchart TB
 
 **Threading model:** Main thread (event loop + native ops) → Async thread (asyncio + user coroutines) → Thread pool (synchronous code).
 
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Architecture & Threading Model](docs/architecture.md)
+- [Custom Plugins](docs/plugins.md)
+- [Third-Party Integrations](docs/integrations.md)
+- [Serve Protocol](docs/serve.md)
+
 ## Installation
 
 ```bash
@@ -59,17 +67,17 @@ pip install --pre lumiview
 ## Quick Start
 
 ```python
-from lumiview import App, Window
+from lumiview import App, Window, WindowOptions
 
 app = App(name="HelloLumiView")
 
 async def main():
-    win = await Window.create(
+    win = await Window.create(WindowOptions(
         title="Hello LumiView!",
         url="https://example.com",
         width=900, height=640,
         devtools=True,
-    )
+    ))
     title = await win.eval_js("document.title")
     print(f"Page title: {title}")
 
@@ -103,7 +111,7 @@ For runnable code, see the [`examples/`](examples/) directory.
 - [x] Window management (TaoWindow + Window)
 - [x] WebView embedding (wryview)
 - [x] JS ↔ Python Bridge (invoke/listen IPC)
-- [x] Hook event system (AppHookEvent / WindowHookEvent)
+- [x] Event class system (WindowEvent / AppEvent)
 - [x] Unified async/sync `Task` interface
 - [x] Static file serving + WSGI proxy
 - [x] ASGI adapter (FastAPI, Starlette, etc.)
@@ -116,6 +124,8 @@ For runnable code, see the [`examples/`](examples/) directory.
 
 This is an early-stage project — **your feedback is crucial**.
 
+Due to limited personal time, some features may not be completed promptly — PRs and other contributions are warmly welcomed.
+
 - 🐛 [Report Bugs](https://github.com/xiaosuawa/LumiView/issues)
 - 💡 [Share Ideas](https://github.com/xiaosuawa/LumiView/discussions)
 - 🔧 [Contribution Guide](CONTRIBUTING.md)

{lumiview-0.1.0.dev2 → lumiview-0.1.0.dev3}/README_zh.md

@@ -50,6 +50,14 @@ flowchart TB
 
 **线程模型：** 主线程（事件循环 + 原生操作）→ 异步线程（asyncio + 用户协程）→ 线程池（同步代码）。
 
+## 文档
+
+- [快速入门](docs/getting-started.md)
+- [架构与线程模型](docs/architecture.md)
+- [自定义插件](docs/plugins.md)
+- [第三方集成](docs/integrations.md)
+- [Serve 协议](docs/serve.md)
+
 ## 安装
 
 ```bash
@@ -59,17 +67,17 @@ pip install --pre lumiview
 ## 快速开始
 
 ```python
-from lumiview import App, Window
+from lumiview import App, Window, WindowOptions
 
 app = App(name="HelloLumiView")
 
 async def main():
-    win = await Window.create(
+    win = await Window.create(WindowOptions(
         title="Hello LumiView!",
         url="https://example.com",
         width=900, height=640,
         devtools=True,
-    )
+    ))
     title = await win.eval_js("document.title")
     print(f"Page title: {title}")
 
@@ -103,7 +111,7 @@ app.run(main)
 - [x] 窗口管理 (TaoWindow + Window)
 - [x] WebView 嵌入 (wryview)
 - [x] JS ↔ Python Bridge (invoke/listen IPC)
-- [x] 钩子事件系统 (AppHookEvent / WindowHookEvent)
+- [x] 事件类体系 (WindowEvent / AppEvent)
 - [x] 统一 async/sync `Task` 接口
 - [x] 静态文件服务 + WSGI 代理
 - [x] ASGI 适配 (FastAPI, Starlette 等)
@@ -116,6 +124,8 @@ app.run(main)
 
 这是一个早期项目——**你的反馈至关重要**。
 
+受个人时间所限，部分功能可能无法及时完成，欢迎各位通过 PR 等贡献方式一同实现。
+
 - 🐛 [报告 Bug](https://github.com/xiaosuawa/LumiView/issues)
 - 💡 [分享想法](https://github.com/xiaosuawa/LumiView/discussions)
 - 🔧 [贡献指南](CONTRIBUTING.md)

lumiview-0.1.0.dev3/docs/architecture.md

@@ -0,0 +1,117 @@
+# 架构
+
+## 分层
+
+```
+Rust 层                       Python 层
+──────────────────────       ──────────────────────────────────
+tao（窗口/事件循环）           lumiview.app    — App 单例、2+N 线程编排
+  │                            lumiview.window — Window / WindowOptions
+  ▼                            lumiview.bridge — Bridge / BridgeError（IPC）
+wryview（WebView 绑定）        lumiview.scope  — Scope / Plugin / 权限链
+  │                            lumiview.task   — Task / run_async
+  ▼                            lumiview.events — 事件类体系
+lumiview._core（PyO3）         lumiview.utils  — match_pattern / navigation_policy
+                              lumiview.serve  — lumiview:// 自定义协议
+```
+
+- Rust 层只做薄绑定：`TaoEventLoop` / `TaoWindow` 等对象是 `#[pyclass(unsendable)]`，方法即原生调用。
+- 低层绑定入口是 `lumiview._core`；日常开发用顶层 `lumiview` API。
+- 所有跨线程/延迟操作统一返回 `Task[T]`：`await`、`.result()`、`.on_done()` 三用一体。
+
+## 2+N 线程模型
+
+| 线程 | 职责 |
+|---|---|
+| **主线程** | tao 事件循环 + 所有原生窗口/WebView 操作 |
+| **asyncio 线程** | 运行用户协程（`app.run(entry)` 的 entry）与事件 handler |
+| **线程池** | 同步 `task()` 调用、同步事件 handler（大小由 `App(max_workers=N)` 配置） |
+
+关键推论：
+
+- **事件 handler 从不运行在主线程**——它们跑在 asyncio 线程（同步 handler 经由线程池）。
+- 主线程 GUI 库操作必须显式调度：`app.call_on_main(...)`。
+
+## 事件流
+
+```
+tao 事件
+  → Rust build_event() 构造 TaoEvent 子类（ResizedEvent 等）
+  → App._on_tao_event（主线程）按 window_id 路由
+  → Window._on_tao_event → 构造事件类实例（WindowEvent.ResizedEvent 等）
+  → Window._emit(event)：按 type(event) 找到 handler，投递到 asyncio 线程
+  → handler(event) 收到事件对象（event.window 已填充）
+```
+
+可阻止事件（`CloseRequestedEvent` / `NavigationRequestedEvent` / `NewWindowRequestedEvent` / `DownloadStartedEvent`）走 `_dispatch_preventable`：先派发并**等待** handler 完成，再检查 `event.prevented` 决定是否执行默认行为（如关闭窗口、放行导航、允许下载）。
+
+## 事件类体系
+
+```text
+Event                     # 所有事件的公共祖先
+├── WindowBaseEvent       # 窗口事件基类：数据 + prevent()/prevented
+│     window: Window | None
+└── AppBaseEvent          # 应用事件基类（ReadyEvent / AppCloseEvent）
+
+WindowEvent               # 纯命名空间容器（非基类）
+├── WindowEvent.TitleChangedEvent(WindowBaseEvent)
+├── WindowEvent.CloseRequestedEvent(WindowBaseEvent) # 可 prevent()
+├── WindowEvent.NavigationRequestedEvent             # 可 prevent()
+├── WindowEvent.DownloadStartedEvent                 # 可 save_to(path) / prevent()
+└── ...
+```
+
+命名空间访问与 isinstance 检查同时成立：
+
+```python
+from lumiview.events import WindowEvent, WindowBaseEvent
+
+e = WindowEvent.TitleChangedEvent(title="x")
+assert isinstance(e, WindowBaseEvent)
+assert e is not None and e.title == "x"
+```
+
+## 主线程调度机制
+
+| API | 说明 |
+|---|---|
+| `app.call_on_main(fn, *args)` | 把 *fn* 排到主线程执行，返回 `Task[T]`；主线程上直接执行 |
+| `@main_thread` | 装饰器版：同步方法变成返回 `Task[R]` 并在主线程跑方法体 |
+| `Task` | `concurrent.futures.Future` 子类；`await` / `.result()` / `.on_done()` |
+| `run_async(fn, pool=...)` | 轻量派发（无 Task 开销）：async 直接 await，sync 走线程池 |
+
+```python
+from lumiview import App
+from lumiview.task import run_async
+
+app = App.get()
+
+# 异步代码：直接 await
+result = await app.call_on_main(lambda: window_op())
+
+# 同步代码：.result() 阻塞
+result = app.call_on_main(lambda: window_op()).result()
+
+# 混合回调：async 直接跑、sync 去线程池
+await run_async(mixed_callback, pool=app._threadpool)
+```
+
+> 经验：任何「从别的线程操作原生窗口」的崩溃（尤其 macOS）基本都是没走 `call_on_main`。典型案例：TimeFlow 用 pystray 时，状态栏菜单回调线程直接操作 `NSWindow` 崩溃——改为主线程调度后稳定。见 [integrations.md](integrations.md)。
+
+## 不可跨线程对象（unsendable）
+
+| 对象 | 跨线程 | 说明 |
+|---|---|---|
+| `TaoEventLoop` | ❌ | tao `!Send`（Rust 侧标记） |
+| `TaoEventLoopProxy` | ✅ | 跨线程唤醒通道（`send_event`） |
+| `TaoWindow` | ❌ | 主线程操作（含 Windows 透明 surface 重绘） |
+| `WebView`（wryview） | ❌ | 主线程 |
+| `Window`（Python 层） | ✅ 方法走 `@main_thread` | 唯一的线程安全通道 |
+
+`Window` 把不可跨线程的原生对象直接存在实例上（`win._window` / `win._webview`），所有访问经 `call_on_main` 派发到主线程——外部永远不直接触碰原生对象。
+
+## 设计原则
+
+1. **跨线程/延迟操作返回 `Task`** —— 类型和行为可预测，不做上下文相关的自动解包。
+2. **事件 handler 不跑主线程** —— 主线程只属于 tao 循环与原生操作，事件处理在 asyncio 线程。
+3. **配置即数据** —— `WindowOptions` 是（可变的）dataclass：可 `replace`、可子类做模板（子类需重新应用 `@dataclass`）、可跨线程传递。

lumiview-0.1.0.dev3/docs/getting-started.md

@@ -0,0 +1,157 @@
+# 快速入门
+
+## 安装
+
+```bash
+pip install --pre lumiview
+```
+
+当前为预览阶段（`0.1.0.dev*`），API 尚未冻结，升级时请留意变更。
+
+## 最小应用
+
+```python
+import asyncio
+
+from lumiview import App, Window, WindowOptions
+
+app = App(name="MyApp")
+
+
+async def main():
+    win = await Window.create(WindowOptions(
+        title="Hello",
+        html="<h1>Hello from LumiView!</h1>",
+    ))
+
+    # 演示：5 秒后自动关闭。默认 exit_on_last_window=True，
+    # 最后一个窗口关闭时应用自动退出。
+    await asyncio.sleep(5)
+    await win.close()
+
+
+app.run(main)
+```
+
+要点：
+
+- `Window.create(options)` 是 `@main_thread` 方法，返回 `Task[Window]` —— 异步代码里 `await`，同步代码里 `.result()`。
+- `app.run(main)` 阻塞主线程直到应用退出；`main` 可以是异步函数（跑在 asyncio 线程）或同步函数（跑在线程池）。
+- `html=` 直接渲染字符串；加载 URL 用 `url=`；加载本地目录用 `source=`（见 [serve.md](serve.md)）。
+
+## 事件订阅
+
+用 `win.on(事件类)` 装饰器注册 handler，handler 收到**事件对象**：
+
+```python
+from lumiview import App, Window, WindowOptions
+from lumiview.events import WindowEvent
+
+
+async def main():
+    win = await Window.create(WindowOptions(
+        title="Events",
+        html="<p id='t'>hi</p>",
+    ))
+
+    @win.on(WindowEvent.TitleChangedEvent)
+    def on_title(event):
+        print("新标题:", event.title)
+
+    @win.on(WindowEvent.NavigationRequestedEvent)
+    def on_navigation(event):
+        print("导航到:", event.url)
+        if event.url.startswith("https://evil.com"):
+            event.prevent()          # 阻止这次导航
+
+    @win.on(WindowEvent.CloseRequestedEvent)
+    def on_close(event):
+        if not saved:
+            event.prevent()          # 取消关闭
+```
+
+- 事件类集中在 `WindowEvent` 命名空间。
+- 所有 handler 都运行在 **asyncio 线程**（不是主线程、不是 wryview 回调线程）——不要在里面直接操作原生 GUI。
+- 可阻止事件（`CloseRequestedEvent` / `NavigationRequestedEvent` / `NewWindowRequestedEvent` / `DownloadStartedEvent`）调用 `event.prevent()` 后，默认行为会被取消。
+- `event.window` 指向触发事件的窗口实例。
+
+## 窗口配置：WindowOptions
+
+所有配置集中在一个（可变的）dataclass 里，字段即 `create()` 的旧关键字参数：
+
+| 字段 | 说明 |
+|---|---|
+| `title` / `width` / `height` | 标题与尺寸（逻辑像素） |
+| `transparent` | 透明背景（配合 CSS `background: transparent`） |
+| `decorations` | 原生标题栏与边框（自定义标题栏时设 `False`） |
+| `devtools` | 启用浏览器开发者工具 |
+| `visible` / `resizable` / `focused` | 可见 / 可缩放 / 聚焦 |
+| `always_on_top` / `maximized` | 置顶 / 启动即最大化 |
+| `close_behavior` | 关闭行为（见下文「关闭流程」） |
+| `bridge` | `Bridge` 实例（JS ↔ Python IPC，见 [plugins.md](plugins.md)） |
+| `untrusted` | 不注入任何初始化脚本（与 `bridge` 互斥） |
+| `prepare` | 创建前钩子（见下文） |
+
+局部修改用 `dataclasses.replace`；配置模板用**子类**：
+
+```python
+from dataclasses import dataclass, replace
+
+base = WindowOptions(title="A", width=800)
+opts = replace(base, width=1024)      # 新对象；base 不变
+
+
+@dataclass(frozen=True)
+class MyAppOptions(WindowOptions):
+    title: str = "MyApp"
+    devtools: bool = True
+
+
+opts2 = MyAppOptions()                # title="MyApp", devtools=True
+```
+
+> **注意**：子类模板**必须重新应用 `@dataclass(...)`**（是否 `frozen` 自选）。dataclass 生成的 `__init__` 在生成时固化基类默认值——不加装饰器的普通子类继承到的仍是基类默认值（`"lumiview"`），类属性声明不会生效。
+
+## `prepare` 钩子：注册早期事件
+
+tao 窗口创建、webview 加载的那一刻事件流就开始了（`PageLoadStarted` 等可能立即触发），而 `win.on()` 通常只能在 `create()` 返回后调用。`prepare` 在 tao/webview 创建**之前**收到 Window 空壳实例（hooks 注册能力已就绪），可以提前订阅：
+
+```python
+def prepare(win):
+    win.on(WindowEvent.PageLoadStartedEvent)(
+        lambda event: print("开始加载:", event.url)
+    )
+
+win = await Window.create(WindowOptions(
+    html="<h1>hi</h1>",
+    prepare=prepare,
+))
+```
+
+## 多窗口
+
+多次调用 `Window.create` 即可；每个窗口有独立 id（`win._id`），应用内部以 `app._windows`（`dict[window_id, Window]`）跟踪。默认 `exit_on_last_window=True`，最后一个窗口关闭时应用退出；托盘类应用可设 `App(name=..., exit_on_last_window=False)`。
+
+## 关闭流程
+
+`CloseBehavior` 控制收到关闭请求时的行为：
+
+- `CloseBehavior.Close`（默认）——销毁窗口；
+- `CloseBehavior.Hide`——隐藏而不是销毁；
+- `CloseBehavior.Ignore`——什么都不做。
+
+`CloseRequestedEvent` 可在任何行为之前 `prevent()`：
+
+```python
+from lumiview import CloseBehavior
+
+win = await Window.create(WindowOptions(
+    close_behavior=CloseBehavior.Hide,   # 先隐藏
+))
+
+
+@win.on(WindowEvent.CloseRequestedEvent)
+def on_close(event):
+    if not saved:
+        event.prevent()                    # 未保存 → 什么都不发生
+```

lumiview-0.1.0.dev3/docs/integrations.md

@@ -0,0 +1,120 @@
+# 第三方集成
+
+核心规则只有一条：**任何操作原生 GUI 的代码必须跑在主线程**（tao 事件循环线程）。事件 handler 运行在 asyncio 线程，第三方库的回调可能运行在任何线程——需要跨线程操作窗口时，统一走 `app.call_on_main(...)`。
+
+```python
+from lumiview import App
+
+app = App.get()
+
+handle = app.call_on_main(lambda: native_operation())   # → Task[T]
+result = handle.result()                                 # 同步等待
+```
+
+## 1. pystray 系统托盘（macOS 案例）
+
+macOS 上 `NSApplication` 是进程级单例，由 tao 创建。pystray 自己启动的 run 循环会与之冲突——**不要调用 `icon.run()` / `icon.run_detached()`**：状态栏 item 的呈现与事件由 tao 的主线程事件循环驱动，菜单回调里再调度回主线程。
+
+```python
+import pystray
+from PIL import Image
+
+from lumiview import App, Window, WindowOptions
+
+app = App(name="TrayApp", exit_on_last_window=False)
+
+
+def on_quit(icon, item):
+    app.exit()
+
+
+def on_toggle(icon, item):
+    # 回调运行在状态栏事件线程 —— 原生操作调度回主线程
+    app.call_on_main(lambda: win.set_title("toggled"))
+
+
+icon = pystray.Icon(
+    "tray",
+    Image.new("RGBA", (64, 64), (0, 120, 215, 255)),
+    menu=pystray.Menu(
+        pystray.MenuItem("切换标题", on_toggle),
+        pystray.MenuItem("退出", on_quit),
+    ),
+)
+icon.visible = True          # 不调用 icon.run() / icon.run_detached()
+
+
+async def main():
+    global win
+    win = await Window.create(WindowOptions(title="Tray"))
+    # 关闭窗口不退出（exit_on_last_window=False）
+
+
+app.run(main)
+```
+
+Windows / Linux 上 pystray 自带线程循环可用，但同样的主线程调度规则仍然适用：菜单回调里操作窗口一律 `app.call_on_main(...)`。
+
+## 2. 原生对话框（tkinter / PySide6）
+
+对话框属于 GUI 操作，必须在主线程创建；且阻塞式对话框会阻塞主线程事件循环，需要先关闭对话框再继续处理：
+
+```python
+import tkinter as tk
+
+from lumiview import App
+
+app = App.get()
+
+
+def pick_file():
+    root = tk.Tk()
+    root.withdraw()
+    path = tk.filedialog.askopenfilename()
+    root.destroy()
+    return path
+
+
+# 在主线程弹对话框；期间 tao 事件循环被阻塞（模态），结束后恢复
+path = app.call_on_main(pick_file).result()
+```
+
+## 3. AppKit / Cocoa 直接操作（macOS，pyobjc）
+
+所有 AppKit 调用必须在主线程；在事件 handler 里直接操作会崩溃（NSWindow 非线程安全）：
+
+```python
+def bring_to_front():
+    from AppKit import NSApp
+
+    NSApp.activateIgnoringOtherApps_(True)
+
+
+app.call_on_main(bring_to_front)
+```
+
+## 4. GTK 工具（Linux）
+
+GTK 不是线程安全的：所有 GTK 调用（对话框、窗口操作、Clipboard 等）必须主线程。tao 的 GTK 主循环是唯一允许操作 GTK 对象的线程；从 handler 里调用前先 `app.call_on_main(...)`。
+
+## 5. 无 UI 约束的系统 API
+
+不触碰 GUI 的调用（截图、文件读写、网络请求、子进程等）没有线程约束——直接在事件 handler / 命令里跑即可（异步函数在 asyncio 线程，同步函数自动走线程池）：
+
+```python
+from lumiview import WindowEvent
+
+@win.on(WindowEvent.TitleChangedEvent)   # win 来自 Window.create(...)
+def on_title(event):
+    # 后台直接做：写日志、截图、上报……
+    save_screenshot()          # 同步函数 → 线程池执行
+```
+
+如果要在同步 handler 里显式使用线程池，用 `lumiview.task.run_async`：
+
+```python
+from lumiview.task import run_async
+
+# 在异步上下文里混合同步/异步回调
+await run_async(sync_work, pool=app._threadpool)
+```