chore: update API.md for @utoo/web

xusd320 · xusd320 · commit 3345bb8e1547 · 2025-09-12T16:02:31.000+08:00
diff --git a/packages/utoo-web/API.md b/packages/utoo-web/API.md
@@ -1,21 +1,23 @@
-# `@utoo/web` API Documentation
+# [`@utoo/web`]## Quick Start Guide
 
-`@utoo/web` is a powerful library that enables you to run a complete web development environment, including a virtual file system, dependency management, and a build process, entirely within the browser. It deeply integrates `utoopack`, a new builder based on Rust and Turbopack, and leverages modern web technologies like Web Workers, Service Workers, and the Origin Private File System (OPFS) to provide a seamless and fast development experience without a backend server.
+Getting a project up and running involves four main steps, as demonstrated in `examples/utooweb-demo`. You can also experience the demo online at [`utoo-repl`](https://utoo-repl.vercel.app/).tps://www.npmjs.com/package/@utoo/web) API Documentation
+
+`@utoo/web` is a powerful library that enables you to run a complete web development environment, including a virtual file system, dependency management, and a build process, entirely within the browser. It deeply integrates [`utoopack`](https://github.com/utooland/utoo), a new builder based on [`Rust`](https://www.rust-lang.org/) and [`turbopack`](https://nextjs.org/docs/app/api-reference/turbopack), and leverages modern web technologies like Web Workers, Service Workers, and the Origin Private File System (OPFS) to provide a seamless and fast development experience without a backend server.
 
 ## Core Concepts
 
 Before diving into the API, it's important to understand the four main components that make `@utoo/web` work:
 
 1.  **Virtual File System**: The entire project, including source code and `node_modules`, lives in the browser's Origin Private File System (OPFS). The `Project` class provides a Node.js-like `fs` interface to interact with it.
 2.  **Project Main Worker**: The core logic of the `Project` instance runs within its own Web Worker. The `Project` object you interact with in the main thread is a proxy that delegates all core tasks (like file system operations) to this worker. This architecture is key to keeping the UI responsive.
-3.  **Thread Worker**: Heavy tasks like bundling and compilation are offloaded to a dedicated Web Worker. This ensures the main UI thread remains responsive, even during a build.
+3.  **Thread Worker**: Heavy tasks like bundling and compilation are offloaded to a dedicated Web Worker. This ensures the main UI thread remains responsive, even during a build. We have ported [`tokio`](https://github.com/utooland/tokio) to the browser to take full advantage of multi-core CPUs for improved performance. The **Thread Worker** will be completely taken over by the tokio runtime.
 4.  **Service Worker**: A Service Worker acts as a local server. It intercepts requests from the preview `iframe`, reads the corresponding files from the OPFS, and serves them back, allowing you to preview your built application.
 
 ---
 
 ## Quick Start Guide
 
-Getting a project up and running involves four main steps, as demonstrated in `examples/utooweb-demo`.
+Getting a project up and running involves four main steps, as demonstrated in `examples/utooweb-demo`. You can also experience the demo online at [`utoo-repl`](https://utoo-repl.vercel.app).
 
 ### 1. Instantiate the Project
 
@@ -152,6 +154,20 @@ Creates a new directory.
 
 *   `path` (string): The path to the directory to be created.
 
+#### `project.rm(path, options)`
+
+Removes a file or directory.
+
+*   `path` (string): The path to the file or directory to be removed.
+*   `options` (object, optional):
+    *   `recursive` (boolean): If `true`, performs a recursive directory removal. Defaults to `false`.
+
+#### `project.rmdir(path)`
+
+Removes a directory.
+
+*   `path` (string): The path to the directory to be removed.
+
 ### Preview Functionality
 
 #### `project.installServiceWorker()`
@@ -210,7 +226,7 @@ The `utooweb-demo` shows a complete workflow for editing, building, and previewi
     await project.writeFile("dist/index.html", generatedHtml);
     ```
 
-4.  **Previewing**: The `Preview` component contains an `iframe` whose `src` points to the entry point within the service worker's scope (e.g., `/preview/dist/index.html`). When the build completes, the `iframe` is reloaded, causing the service worker to serve the newly generated files from the OPFS.
+4.  **Previewing**: The `Preview` component contains an `iframe` whose `src` points to the entry point within the service worker's scope (e.g., `/preview/dist/index.html`). When the build completes, the `iframe` reloads from the Service Worker with the newly generated artifact files from OPFS.
 
 This cycle provides a fast and interactive development loop, all running locally in the user's browser.
 
@@ -283,3 +299,8 @@ import "@utoo/web/esm/serviceWorker";
 ```
 
 Your build setup should be configured to output these files to a location that your main application can access, so you can provide their URLs to the `UtooProject` constructor.
+
+## Notes
+* Due to the current default memory allocator for Rust, [`dlmalloc`](https://github.com/alexcrichton/dlmalloc-rs), having less than ideal performance on multi-threaded `wasm`, we are currently trying to support [`mimalloc`](https://github.com/microsoft/mimalloc) with reference to [`emscripten`](https://emscripten.org/docs/tools_reference/settings_reference.html#malloc)'s solution. Once successful, the build speed will be greatly improved;
+* In the future, we will also support the [`HMR`](https://webpack.js.org/concepts/hot-module-replacement/) feature in the browser;
+* Advanced features of turbopack such as [`webpack loaders`](https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopack#configuring-webpack-loaders), [`persistent caching`](https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopackPersistentCaching), are also in the plan and will be supported directly in the browser in the future.
diff --git a/packages/utoo-web/API_zh-CN.md b/packages/utoo-web/API_zh-CN.md
@@ -1,21 +1,21 @@
-# `@utoo/web` API 文档
+# [`@utoo/web`](https://www.npmjs.com/package/@utoo/web) API 文档
 
-`@utoo/web` 是一个功能强大的库，它允许您在浏览器中完整地运行一套 Web 开发环境，包括虚拟文件系统、依赖管理和构建流程。它深度整合了基于 Rust 和 Turbopack 的全新构建器 `utoopack`，并利用 Web Workers、Service Workers 和源私有文件系统（OPFS）等现代 Web 技术，提供无缝且快速的开发体验，无需后端服务器。
+`@utoo/web` 是一个功能强大的库，它允许您在浏览器中完整地运行一套 Web 开发环境，包括虚拟文件系统、依赖管理和构建流程。它深度整合了基于 [`Rust`](https://www.rust-lang.org/) 和 [`turbopack`](https://nextjs.org/docs/app/api-reference/turbopack) 的全新构建器 [`utoopack`](https://github.com/utooland/utoo)，并利用 Web Workers、Service Workers 和源私有文件系统（OPFS）等现代 Web 技术，提供无缝且快速的开发体验，无需后端服务器。
 
 ## 核心概念
 
 在深入了解 API 之前，理解构成 `@utoo/web` 的四个主要组件非常重要：
 
-1.  **虚拟文件系统 (Virtual File System)**：整个项目，包括源代码和 `node_modules`，都存在于浏览器的源私有文件系统（OPFS）中。`Project` 类提供了一个类似 Node.js `fs` 的接口来与其交互。
+1.  **Virtual File System**：整个项目，包括源代码和 `node_modules`，都存在于浏览器的源私有文件系统（OPFS）中。`Project` 类提供了一个类似 Node.js `fs` 的接口来与其交互。
 2.  **Project Main Worker**：`Project` 实例的核心逻辑运行在它自己的 Web Worker 中。您在主线程中与之交互的 `Project` 对象实际上是一个代理，它将所有核心任务（如文件系统操作）委托给此 Worker。这种架构是保持 UI 响应流畅的关键。
-3.  **Thread Worker**：像打包和编译这样的重度任务被卸载到一个专用的 Web Worker 中。这确保了即使在构建过程中，主 UI 线程也能保持响应。
+3.  **Thread Worker**：像打包和编译这样的重度任务被卸载到一个专用的 Web Worker 中。这确保了即使在构建过程中，主 UI 线程也能保持响应。我们将 [`tokio`](https://github.com/utooland/tokio) 移植到了浏览器上，以充分利用多核 CPU 提升性能。**Thread Worker** 将完全被 tokio runtime 接管。
 4.  **Service Worker**：Service Worker 充当本地服务器。它拦截来自预览 `iframe` 的请求，从 OPFS 中读取相应的文件，并将其提供回去，从而允许您预览构建好的应用程序。
 
 ---
 
 ## 快速上手指南
 
-启动一个项目主要涉及四个步骤，如 `examples/utooweb-demo` 中所示。
+启动一个项目主要涉及四个步骤，如 `examples/utooweb-demo` 中所示。你也可以在 [`utoo-repl`](https://utoo-repl.vercel.app) 在线体验演示效果。
 
 ### 1. 实例化项目
 
@@ -152,6 +152,20 @@ await project.writeFile('utoopack.json', JSON.stringify(utoopackConfig, null, 2)
 
 *   `path` (string): 要创建的目录的路径。
 
+#### `project.rm(path, options)`
+
+删除一个文件或目录。
+
+*   `path` (string): 要删除的文件或目录的路径。
+*   `options` (object, 可选):
+    *   `recursive` (boolean): 如果为 `true`，则执行递归目录删除。默认为 `false`。
+
+#### `project.rmdir(path)`
+
+删除一个目录。
+
+*   `path` (string): 要删除的目录的路径。
+
 ### 预览功能
 
 #### `project.installServiceWorker()`
@@ -191,7 +205,7 @@ await project.writeFile('utoopack.json', JSON.stringify(utoopackConfig, null, 2)
     // 在 useBuild.ts 中
     setIsBuilding(true);
     try {
-        await project.build();
+      await project.build();
         // 构建成功
     } catch (e) {
         // 构建失败
@@ -210,7 +224,7 @@ await project.writeFile('utoopack.json', JSON.stringify(utoopackConfig, null, 2)
     await project.writeFile("dist/index.html", generatedHtml);
     ```
 
-4.  **预览**: `Preview` 组件包含一个 `iframe`，其 `src` 指向 Service Worker 范围内的入口点（例如 `/preview/dist/index.html`）。构建完成后，`iframe` 会重新加载，导致 Service Worker 从 OPFS 提供新生成的文件。
+4.  **预览**: `Preview` 组件包含一个 `iframe`，其 `src` 指向 Service Worker 范围内的入口点（例如 `/preview/dist/index.html`）。构建完成后，`iframe` 会重新从 Service Worker 加载 OPFS 中新生成的产物文件。
 
 这个循环提供了一个快速、交互式的开发循环，全部在用户的浏览器中本地运行。
 
@@ -283,3 +297,8 @@ import "@utoo/web/esm/serviceWorker";
 ```
 
 您的构建设置应配置为将这些文件输出到主应用程序可以访问的位置，以便您可以将其 URL 提供给 `UtooProject` 构造函数。
+
+## 注意
+* 由于当前 Rust 上默认的内存分配器 [`dlmalloc`](https://github.com/alexcrichton/dlmalloc-rs) 在多线程 `wasm` 上性能不够理想，我们目前正在尝试参考 [`emscripten`](https://emscripten.org/docs/tools_reference/settings_reference.html#malloc) 的方案支持 [`mimalloc`](https://github.com/microsoft/mimalloc)，一旦成功，构建速度将会有大幅提升；
+* 未来我们也会在浏览器中支持 [`HMR`](https://webpack.js.org/concepts/hot-module-replacement/) 功能;
+* turbopack 的部分高级功能如[`webpack loaders`](https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopack#configuring-webpack-loaders), [`持久化缓存`](https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopackPersistentCaching)，目前也在计划之中，未来会在浏览器内直接支持。
