docs: new ps API

cspell.json

@@ -1 +1 @@
-{"flagWords":[],"words":["linemode","Hyprland","ueberzug","yazi","sxyazi","Discardable","Sixel","downscaling","downscales","keymap","unyank","preloaders","precache","Konsole","Mintty","Ghostty","Zellij","scrolloff"],"version":"0.2","language":"en"}
+{"language":"en","flagWords":[],"words":["linemode","Hyprland","ueberzug","yazi","sxyazi","Discardable","Sixel","downscaling","downscales","keymap","unyank","preloaders","precache","Konsole","Mintty","Ghostty","Zellij","scrolloff","unsub"],"version":"0.2"}

docs/plugins/overview.md

@@ -132,7 +132,7 @@ When a plugin is executed asynchronously, an isolated async context is created f
 
 In this context, you can use all the async functions supported by Yazi, and it operates concurrently with the main thread, ensuring that the main thread is not blocked.
 
-You can also obtain a small amount of app data from the sync context by calling a "sync function":
+You can also obtain [a small amount](#sendable) of app data from the sync context by calling a "sync function":
 
 ```lua
 -- ~/.config/yazi/plugins/my-async-plugin.yazi/init.lua
@@ -239,6 +239,16 @@ When the user specifies [`multi = true`](/docs/configuration/yazi#plugin.preload
 Typically, a preloader only needs to implement one of them - either single or multiple. This depends on the specific task and the magnitude of the workload.
 If it truly requires loading multiple files at once, the user needs to be prompted to enable the `multi` option for it.
 
+## Sendable value {#sendable}
+
+Yazi's plugin can run concurrently on multiple threads. For better performance, only the following types of combinations can be used for inter-thread data exchange:
+
+- nil
+- boolean
+- number
+- string
+- table and nested tables, with the above types as values
+
 ## Debugging {#debugging}
 
 Please ensure that your `~/.config/yazi/init.lua` includes valid Lua code with the correct syntax, otherwise will result in Yazi being unable to parse and execute your `init.lua` to initialize.

docs/plugins/utils.md

@@ -306,6 +306,95 @@ This function is only available on Unix-like systems.
 
 Only available on Unix-like systems. Returns the hostname of the current machine, which is a string if successful; otherwise, `nil`.
 
+## ps {#ps}
+
+Yazi's DDS (Data Distribution Service) uses a Lua-based publish-subscribe model as its carrier. That is, you can achieve cross-instance communication and state persistence through the `ps` API.
+
+### `pub(kind, value)` {#ps.pub}
+
+```lua
+ps.pub("greeting", "Hello, World!")
+```
+
+Publish a message to the current instance, and all plugins subscribed through `sub()` for this `kind` will receive it, achieving internal communication within the instance:
+
+- `kind` - Required, the kind of the message, which is a string. It can only contain letters, numbers, and dashes, and cannot use built-in kinds.
+- `value` - Required, the value of the message, which is a [sendable value](/docs/plugins/overview#sendable)
+
+Since the `kind` is used globally, to add the plugin name as the prefix is a best practice. For example, the combination of the plugin `my-plugin` and the kind `event1` would be `my-plugin-event1`.
+
+### `pub_to(receiver, kind, value)` {#ps.pub_to}
+
+```lua
+ps.pub_to("c3RpbjQ4", "greeting", "Hello, World!")
+```
+
+Publish a message to a specific instance with `receiver` as the identifier:
+
+- `receiver` - Required, the identifier of the receiver, which is a string
+- `kind` - The same as `pub()`
+- `value` - The same as `pub()`
+
+Where:
+
+- If the receiver is the current instance (local), and is subscribed to this `kind` through `sub()`, it will receive this message.
+- If the receiver is not the current instance (remote), and is subscribed to this `kind` through `sub_remote()`, it will receive this message.
+
+### `pub_static(severity, kind, value)` {#ps.pub_static}
+
+```lua
+ps.pub_static(10, "greeting", "Hello, World!")
+```
+
+Broadcast a message to all instances subscribed to this `kind` through `sub_remote()`:
+
+- `severity` - Required, the severity of the message, which is an integer with a range of 1 to 255
+- `kind` - The same as `pub()`
+- `value` - The same as `pub()`
+
+The message will be stored as static data to achieve state persistence, and when a new instance is created, it will receive all static messages broadcasted by `sub_remote()` in descending order of `severity` to restore its state from the data.
+
+### `sub(kind, callback)` {#ps.sub}
+
+```lua
+ps.sub("cd", function(body)
+	ya.err("New cwd", cx.active.current.cwd)
+end)
+```
+
+Subscribe to local messages of `kind` and call the `callback` handler for it:
+
+- `kind` - Required, the kind of the message, which is a string
+- `callback` - Required, the callback function
+
+which runs in a synchronous context, so you can access app data via `cx` for the content of interest.
+
+Note: No time-consuming operations should be done in this callback, and the same `kind` from the same plugin can only be subscribed once, re-subscribing (`sub()`) before unsubscribing (`unsub()`) will throw an error.
+
+### `sub_remote(kind, callback)` {#ps.sub_remote}
+
+Similar to `sub()`, but it subscribes to remote messages of this `kind` instead of local.
+
+### `unsub(kind)` {#ps.unsub}
+
+```lua
+ps.unsub("my-message")
+```
+
+Unsubscribe from local messages of this `kind`:
+
+- `kind` - Required, the kind of the message, which is a string
+
+### `unsub_remote(kind)` {#ps.unsub_remote}
+
+```lua
+ps.unsub_remote("my-message")
+```
+
+Unsubscribe from remote messages of this `kind`:
+
+- `kind` - Required, the kind of the message, which is a string
+
 ## fs
 
 The following functions can only be used within an async context.

package.json

@@ -14,18 +14,18 @@
 		"format": "prettier --write ."
 	},
 	"dependencies": {
-		"@docusaurus/core": "3.1.1",
-		"@docusaurus/preset-classic": "3.1.1",
+		"@docusaurus/core": "3.2.0",
+		"@docusaurus/preset-classic": "3.2.0",
 		"@mdx-js/react": "^3.0.0",
 		"clsx": "^1.2.1",
 		"prism-react-renderer": "^2.1.0",
 		"react": "^18.0.0",
 		"react-dom": "^18.0.0"
 	},
 	"devDependencies": {
-		"@docusaurus/module-type-aliases": "3.1.1",
-		"@docusaurus/tsconfig": "3.1.1",
-		"@docusaurus/types": "3.1.1",
+		"@docusaurus/module-type-aliases": "3.2.0",
+		"@docusaurus/tsconfig": "3.2.0",
+		"@docusaurus/types": "3.2.0",
 		"prettier": "^3.0.3",
 		"typescript": "~5.2.2"
 	},