feat: add public host file watch API

Author: loybot

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "haloforge-plugin-api"
-version = "0.2.17"
+version = "0.2.18"
 edition = "2021"
 description = "Plugin API for HaloForge — traits and types for building native HaloForge plugins"
 license = "MIT"
@@ -10,6 +10,7 @@ documentation = "https://docs.rs/haloforge-plugin-api"
 keywords = ["haloforge", "plugin", "gamedev", "tauri"]
 categories = ["development-tools", "game-development"]
 readme = "README.md"
+include = ["/src/**", "/Cargo.toml", "/README.md", "/LICENSE"]
 
 [workspace]
 

README.md

@@ -71,13 +71,14 @@ Permission names are strict. For AI Chat access, the only valid manifest permiss
     "homepage": "https://github.com/you/hello-plugin",
     "compatibility": {
         "min_app_version": "0.8.0",
-        "min_host_api_version": "0.2.17"
+        "min_host_api_version": "0.2.18"
     },
     "capability_levels": [2],
     "host_capabilities": [
         "navigation",
         "file_intents",
         "file_dialogs",
+        "file_watch",
         "aichat",
         "theme_read"
     ],

docs/plugin-development-guide.md

@@ -61,7 +61,7 @@ Every plugin needs a `manifest.json` at the repository root.
   "author": "Example",
   "compatibility": {
     "min_app_version": "0.8.0",
-    "min_host_api_version": "0.2.17"
+    "min_host_api_version": "0.2.18"
   },
   "capability_levels": [0],
   "host_capabilities": ["navigation", "file_intents", "theme_read"],
@@ -115,6 +115,7 @@ Rules:
 - `id` is stable forever. Do not rename it after publishing.
 - `version` follows semver. Official plugins should start at `0.1.0`.
 - `host_capabilities` must match SDK helpers used by the frontend.
+- File watching must use `watchHostFile` or `useHostFileWatch` with `file_watch` and `host_file_watch`; do not hard-code host commands or events.
 - `permissions` must be the smallest set needed.
 - `entry.frontend` and `integration.*.panel_entry` should point to the built bundle.
 - Native command IDs in `commands` must match the names registered by the Rust backend before SDK prefixing.

docs/public-host-api.md

@@ -24,13 +24,14 @@ Plugins can now declare:
 {
   "compatibility": {
     "min_app_version": "0.8.0",
-    "min_host_api_version": "0.2.17"
+    "min_host_api_version": "0.2.18"
   },
   "host_capabilities": [
     "navigation",
     "app_state",
     "file_intents",
     "file_dialogs",
+    "file_watch",
     "aichat",
     "enterprise_gateway",
     "deep_links",
@@ -61,6 +62,7 @@ Plugins can now declare:
 - `app_state`
 - `file_intents`
 - `file_dialogs`
+- `file_watch`
 - `aichat`
 - `enterprise_gateway`
 - `deep_links`
@@ -97,6 +99,7 @@ The permission model also includes explicit host-facing permissions:
 - `host_app_state_read`
 - `host_file_intents`
 - `host_file_dialogs`
+- `host_file_watch`
 - `host_aichat_access`
 - `host_enterprise_gateway_access`
 - `host_deep_links`
@@ -115,6 +118,7 @@ import {
   definePlugin,
   useHostNavigation,
   useHostFileIntent,
+  useHostFileWatch,
   useHostAI,
   usePluginDeepLink,
   usePluginNavigation,

docs/zh/plugin-development-guide.md

@@ -61,7 +61,7 @@ my-plugin/
   "author": "Example",
   "compatibility": {
     "min_app_version": "0.8.0",
-    "min_host_api_version": "0.2.17"
+    "min_host_api_version": "0.2.18"
   },
   "capability_levels": [0],
   "host_capabilities": ["navigation", "file_intents", "theme_read"],
@@ -115,6 +115,7 @@ my-plugin/
 - `id` 发布后必须保持稳定，不要改名。
 - `version` 使用 semver，官方插件初版从 `0.1.0` 开始。
 - `host_capabilities` 必须匹配前端实际使用的 SDK helper。
+- 文件监听必须使用 `watchHostFile` 或 `useHostFileWatch`，并声明 `file_watch` 与 `host_file_watch`；不要硬编码宿主命令或事件。
 - `permissions` 必须保持最小权限。
 - `entry.frontend` 和 `integration.*.panel_entry` 应指向构建后的 bundle。
 - `commands` 里的原生命令 ID 要和 Rust 后端注册的名字一致，不能包含 SDK 自动添加的前缀。

pack/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@haloforge/plugin-pack",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "HaloForge plugin packager CLI — validate, build, and bundle plugins into .hfpkg archives",
   "type": "module",
   "bin": {

pack/package.json

@@ -522,6 +522,7 @@ const PERMISSION_SCHEMAS = new Map<string, { value: "none" | "string" | "string-
   ["host_app_state_read", { value: "none" }],
   ["host_file_intents", { value: "none" }],
   ["host_file_dialogs", { value: "none" }],
+  ["host_file_watch", { value: "none" }],
   [HOST_AICHAT_ACCESS_PERMISSION, { value: "none" }],
   ["host_enterprise_gateway_access", { value: "none" }],
   ["host_deep_links", { value: "none" }],
@@ -1454,6 +1455,7 @@ const HOST_CAPABILITIES = new Set([
   "app_state",
   "file_intents",
   "file_dialogs",
+  "file_watch",
   "aichat",
   "enterprise_gateway",
   "deep_links",
@@ -1491,6 +1493,8 @@ const DIRECT_HOST_IPC_COMMANDS = [
   "devkit_pick_file",
   "devkit_pick_directory",
   "devkit_save_file",
+  "plugin_watch_file",
+  "plugin_unwatch_file",
 ];
 
 const IGNORED_PLUGIN_SOURCE_DIRS = new Set([

pack/src/core.ts

@@ -77,6 +77,19 @@ test("hf-pack check accepts plugin deep link host capability and permission", as
   );
 });
 
+test("hf-pack check accepts host file watch capability and permission", async () => {
+  await withPluginDir(
+    {
+      ...BASE_MANIFEST,
+      host_capabilities: ["file_watch"],
+      permissions: [{ type: "host_file_watch" }],
+    },
+    async (pluginDir) => {
+      await assert.doesNotReject(() => checkPlugin(pluginDir));
+    },
+  );
+});
+
 test("hf-pack check accepts plugin window document handlers", async () => {
   await withPluginDir(
     {

pack/tests/permissions.test.mjs

@@ -45,6 +45,7 @@ export default registerPlugin("com.example.hello-plugin", definePlugin({
 - `pluginWindows`, `usePluginWindows`: ask HaloForge to open plugin routes/resources through the host multi-window dispatcher.
 - `pluginCurrentWindow`, `usePluginCurrentWindow`, `usePluginWindowTitle`: update or reset the native title for the active HaloForge window.
 - `pickHostFile`, `pickHostDirectory`, `saveHostFile`: stable host file dialog helpers.
+- `watchHostFile`, `useHostFileWatch`: host-managed cross-platform file change notifications.
 - `usePluginSettings`, `useHostData`, `useSlotContext`: read plugin and host state inside your React components.
 - `useAppTheme`: read HaloForge theme mode and CSS variables inside your plugin.
 - `enterpriseGateway`: call the host-managed image gateway without exposing cloud tokens. The function name is retained for compatibility; user-facing UI should say "HaloForge Cloud gateway" or "Managed gateway".
@@ -62,6 +63,7 @@ Prefer these host helpers over reading `window.__HF_HOST` directly:
 - `pluginWindows()` / `usePluginWindows()` for host-managed route/resource window opening
 - `pluginCurrentWindow()` / `usePluginWindowTitle()` for the current native window title
 - `pickHostFile()` / `pickHostDirectory()` / `saveHostFile()` for host-owned file dialogs
+- `watchHostFile()` / `useHostFileWatch()` for host-managed file change notifications
 - `useHostModels()` / `useAvailableModels()` for model lists and current selection
 - `useHostAI()` for AI transport, session creation, stream-state polling, and generation stop
 - `enterpriseGateway()` for host-managed image generation and image edits
@@ -71,6 +73,36 @@ Prefer these host helpers over reading `window.__HF_HOST` directly:
 
 These helpers currently adapt to HaloForge's existing host bridge internally, but they give plugin authors one documented surface that can keep working as HaloForge evolves.
 
+## File Watching
+
+Declare the public capability and permission:
+
+```json
+{
+  "host_capabilities": ["file_watch"],
+  "permissions": [
+    { "type": "host_file_watch" }
+  ]
+}
+```
+
+React plugins can follow a file without polling or using host internals:
+
+```tsx
+import { useCallback } from "react";
+import { useHostFileWatch } from "@haloforge/plugin-sdk";
+
+export function DocumentPanel({ path }: { path: string }) {
+  useHostFileWatch(path, useCallback((event) => {
+    console.log(event.path, event.kind);
+  }, []));
+
+  return null;
+}
+```
+
+Outside React, call `watchHostFile(path, handler)` and await the returned stop function.
+
 ## Plugin Deep Links
 
 Plugins can opt in to launch URLs such as: