@termix-ssh/plugin-sdk 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.0.9
+
+### Added
+
+- Worker entries in `package.json` `termix.workers`, each bundled on its own into `dist/workers/<name>.js`
+- A `.wasm`, `.ttf` or `.otf` import gives the file's bytes, in `termix-plugin build` and in plugin tests
+
+### Fixed
+
+- The plugin guide listed jszip, guacamole-lite and @anthropic-ai/sdk as shared packages, but they are bundled
+
+## 1.0.8
+
+### Added
+
+- `publicRateLimit` on `ctx.http.router()`, for a plugin whose public routes serve a proxied page
+
 ## 1.0.7
 
 ### Fixed

package/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.7 | Plugin API 1.2.0
+SDK 1.0.9 | Plugin API 1.2.0
 
 This guide is for anyone, person or AI coding tool, building a Termix plugin. It ships inside
 `@termix-ssh/plugin-sdk`, so the copy in your `node_modules` always matches the SDK you have installed.
@@ -283,7 +283,8 @@ router.post("/notes", async (req, res) => {
 - The `@openapi` path is the full path, starting with `/plugin-api/<id>/`. `build` turns these into
   `dist/openapi.json` and the docs site renders them.
 - `ctx.http.router({ public: ["/webhook/:token"], bodyLimit: "20mb", rawBody: false })`. Public routes
-  have no actor: check their token yourself and rate limit them.
+  have no actor: check their token yourself. Core allows 120 public requests a minute per address;
+  `publicRateLimit` raises that for a proxied page that loads its own assets.
 - `ctx.http.baseUrl(req)` is the public address, for callback URLs.
 - `ctx.ws.route("/live", (socket, conn) => ...)`. Long lived sockets should check
   `conn.isDataUnlocked()` per message.
@@ -333,8 +334,27 @@ ctx.schedule.every(60_000, () => refresh(), { jitterMs: 5_000 });
 ### Shared packages
 
 These come from Termix and are never bundled: `@termix-ssh/plugin-sdk`, `express`, `ssh2`, `ws`, `multer`,
-`cookie-parser`, `axios`, `jszip`, `guacamole-lite`, `@anthropic-ai/sdk`, `drizzle-orm`, `sharp` and every
-Node builtin. List the ones you use in `peerDependencies`. Any other npm package is bundled.
+`cookie-parser`, `axios`, `drizzle-orm`, `sharp` and every Node builtin. List the ones you use in
+`peerDependencies`. Any other npm package is bundled.
+
+### Workers and WebAssembly
+
+Heavy work (decoding, encoding, parsing) belongs in a worker thread so it never blocks the server. Name
+each worker entry in `package.json`:
+
+```json
+"termix": { "workers": { "engine": "src/backend/engine/worker.ts" } }
+```
+
+`build` bundles it alone into `dist/workers/engine.js`; start it with
+`new Worker(new URL("./workers/engine.js", import.meta.url))`. A worker bundles everything it imports and
+can't use the shared packages above, so it must not import `@termix-ssh/plugin-sdk`. Talk to it with
+`postMessage`.
+
+Importing a `.wasm`, `.ttf` or `.otf` file gives its bytes as a `Uint8Array`, in `build` and in tests, so a module ships
+inside the bundle with no file to find. Compile it once on the main thread with `new WebAssembly.Module`
+and post that to each worker. Add `declare module "*.wasm" { const bytes: Uint8Array; export default bytes; }`
+to a `.d.ts` in the plugin.
 
 ## Database
 
@@ -682,20 +702,20 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 
 ## termix-plugin CLI
 
-| Command                        | What it does                                                                                   |
-| ------------------------------ | ---------------------------------------------------------------------------------------------- |
-| `build`                        | Bundle `dist/backend.js` and `dist/frontend.js`, CSS, locales, migrations, `dist/openapi.json` |
-| `validate`                     | Check the manifest, its files, migrations for every database, the changelog and `package.json` |
-| `test`                         | Apply patches, run Vitest                                                                      |
-| `migrations`                   | Write a migration per database from `tables.ts`. `--check` fails when one is missing           |
-| `openapi`                      | Write `dist/openapi.json` from `@openapi` blocks                                               |
-| `pack`                         | Validate, then write `<id>-<version>.tmxplug`. `--out <dir>`                                   |
-| `sign <file>`                  | Sign a `.tmxplug` with `TERMIX_PLUGIN_SIGNING_KEY`                                             |
-| `verify <file> --key <base64>` | Check a `.tmxplug` against its `.sig`                                                          |
-| `keygen`                       | Write a new signing key pair. `--out <dir>`                                                    |
-| `changelog`                    | Print one version's notes. `--version x.y.z`                                                   |
-| `patch`                        | Apply the plugin's dependency patches (`build` and `test` do this too)                         |
-| `dev`                          | Build, pack and install on a server, again on every change. `--server`, `--key`, `--once`      |
+| Command                        | What it does                                                                                    |
+| ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `build`                        | Bundle `dist/backend.js`, `dist/frontend.js`, workers, CSS, locales, migrations, `openapi.json` |
+| `validate`                     | Check the manifest, its files, migrations for every database, the changelog and `package.json`  |
+| `test`                         | Apply patches, run Vitest                                                                       |
+| `migrations`                   | Write a migration per database from `tables.ts`. `--check` fails when one is missing            |
+| `openapi`                      | Write `dist/openapi.json` from `@openapi` blocks                                                |
+| `pack`                         | Validate, then write `<id>-<version>.tmxplug`. `--out <dir>`                                    |
+| `sign <file>`                  | Sign a `.tmxplug` with `TERMIX_PLUGIN_SIGNING_KEY`                                              |
+| `verify <file> --key <base64>` | Check a `.tmxplug` against its `.sig`                                                           |
+| `keygen`                       | Write a new signing key pair. `--out <dir>`                                                     |
+| `changelog`                    | Print one version's notes. `--version x.y.z`                                                    |
+| `patch`                        | Apply the plugin's dependency patches (`build` and `test` do this too)                          |
+| `dev`                          | Build, pack and install on a server, again on every change. `--server`, `--key`, `--once`       |
 
 ## SDK entry points
 

package/cli/commands/build.mjs

@@ -52,6 +52,43 @@ export function externalRequireInterop(externals) {
   };
 }
 
+// A .wasm or font import becomes its bytes (a Uint8Array) inside the bundle,
+// so it ships in backend.js or a worker with no separate file to find.
+export const BINARY_EXTENSIONS = [".wasm", ".ttf", ".otf"];
+const BINARY_LOADERS = Object.fromEntries(
+  BINARY_EXTENSIONS.map((ext) => [ext, "binary"]),
+);
+
+const REQUIRE_BANNER =
+  "import { createRequire as __termixCreateRequire } from 'node:module'; const require = __termixCreateRequire(import.meta.url);";
+
+/**
+ * package.json "termix": { "workers": { "engine": "src/backend/engine/worker.ts" } }
+ * bundles each entry on its own into dist/workers/<name>.js, for
+ * new Worker(new URL("./workers/<name>.js", import.meta.url)). Nothing is left
+ * external: core's import fallback only runs on the main thread, so a worker
+ * can't rely on host packages and must not import the SDK.
+ */
+export function readWorkerEntries(cwd, pluginId) {
+  const pkgPath = path.join(cwd, "package.json");
+  const pkg = fs.existsSync(pkgPath)
+    ? JSON.parse(fs.readFileSync(pkgPath, "utf8"))
+    : {};
+  const workers = pkg.termix?.workers ?? {};
+  return Object.entries(workers).map(([name, entry]) => {
+    if (!/^[a-z0-9-]+$/.test(name)) {
+      throw new Error(`${pluginId}: worker name "${name}" must be lowercase`);
+    }
+    const file = path.resolve(cwd, String(entry));
+    if (!fs.existsSync(file)) {
+      throw new Error(
+        `${pluginId}: worker "${name}" entry ${entry} is missing`,
+      );
+    }
+    return { name, file };
+  });
+}
+
 const SDK_PATCHES = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
   "..",
@@ -216,13 +253,27 @@ export async function build({ cwd }) {
     // node_modules import instead, resolved at runtime like a host-provided
     // package.
     external: [...BACKEND_EXTERNALS, ...(manifest.nativeDependencies ?? [])],
+    loader: BINARY_LOADERS,
     // Bundled CJS deps still call require() for Node builtins at runtime.
     // ESM has no ambient require, so give esbuild's require shim a real one.
-    banner: {
-      js: "import { createRequire as __termixCreateRequire } from 'node:module'; const require = __termixCreateRequire(import.meta.url);",
-    },
+    banner: { js: REQUIRE_BANNER },
   });
 
+  for (const worker of readWorkerEntries(cwd, pluginId)) {
+    await esbuild.build({
+      entryPoints: [worker.file],
+      outfile: path.join(outDir, "workers", `${worker.name}.js`),
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node22",
+      sourcemap: true,
+      logLevel: "warning",
+      loader: BINARY_LOADERS,
+      banner: { js: REQUIRE_BANNER },
+    });
+  }
+
   // Without this Node finds the host's typeless package.json, tries backend.js
   // as CommonJS first and warns before reparsing it as ESM.
   fs.writeFileSync(

package/dist/backend.d.ts

@@ -303,6 +303,13 @@ export interface PluginRouterOptions {
      * (multer, a raw body for signature checking, a proxied stream).
      */
     rawBody?: boolean;
+    /**
+     * Requests per minute one address may make to this plugin's public routes.
+     * Defaults to 120, which a proxied page loading its own scripts and images
+     * can pass on its own. Capped at 10000, and an admin's
+     * TERMIX_PLUGIN_PUBLIC_RATE_LIMIT wins over it.
+     */
+    publicRateLimit?: number;
 }
 /**
  * HTTP routes, served at /plugin-api/<id>/ by the main backend server.

package/dist/host/{chunk-LKN6OILD.js → chunk-G346FUE4.js}

@@ -52016,6 +52016,8 @@ var en_default = {
         pinAppRailDesc: "Keep the left sidebar app rail always expanded instead of expanding on hover",
         expandAppRailOnHover: "Expand App Rail on Hover",
         expandAppRailOnHoverDesc: "Allow the left sidebar app rail to expand when the pointer moves over it",
+        appRailHoverPushesContent: "Push content when it expands",
+        appRailHoverPushesContentDesc: "Make room for the expanded rail instead of opening it over the page. Open sessions, like remote desktop, resize each time",
         showPinAppRailButton: "Show Pin App Rail Button",
         showPinAppRailButtonDesc: "Show a button in the app rail to pin it open. Off by default.",
         settingsNavigation: "Navigation",
@@ -53584,7 +53586,7 @@ async function pluginWsUrl(pluginId, path2, options2 = {}) {
   }
   const token = await fetchSocketTicket() ?? localStorage.getItem("jwt");
   const protocols2 = websocketAuthProtocols(token);
-  const devProxy = !define_import_meta_env_default.VITE_API_HOST && (window.location.port === "3000" || window.location.port === "5173");
+  const devProxy = !define_import_meta_env_default.VITE_API_HOST;
   const wsProtocol = window.location.protocol === "https:" ? "wss" : "ws";
   if (devProxy) {
     return {

package/dist/host/testing-host.js

@@ -40,7 +40,7 @@ import {
   setShellCallbacks,
   setShellHosts,
   setShellLayoutProvider
-} from "./chunk-LKN6OILD.js";
+} from "./chunk-G346FUE4.js";
 import {
   setPermissionsForTesting
 } from "./chunk-DIOJ3KW2.js";

package/dist/host/ui.js

@@ -139,7 +139,7 @@ import {
   useSurfaceKind,
   useTheme,
   verifySecondFactor
-} from "./chunk-LKN6OILD.js";
+} from "./chunk-G346FUE4.js";
 import "./chunk-DIOJ3KW2.js";
 import {
   TabProvider,

package/dist/vitest-preset.d.ts

@@ -8,11 +8,25 @@
  *
  * Two projects: tests/backend runs in node, tests/frontend in jsdom.
  */
+/**
+ * termix-plugin build turns a .wasm or font import into its bytes. Tests get the same,
+ * so code that imports a module compiles it the same way under vitest.
+ */
+export declare function wasmBinaryPlugin(): {
+    name: string;
+    enforce: "pre";
+    load(id: string): string;
+};
 export interface PluginVitestOptions {
     /** Extra aliases merged over the defaults. */
     alias?: Record<string, string>;
 }
 export declare function pluginVitestConfig(configUrl: string, options?: PluginVitestOptions): {
+    plugins: {
+        name: string;
+        enforce: "pre";
+        load(id: string): string;
+    }[];
     resolve: {
         alias: Record<string, string>;
     };
@@ -21,6 +35,11 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
         setupFiles: string[];
         pool: "threads";
         projects: ({
+            plugins: {
+                name: string;
+                enforce: "pre";
+                load(id: string): string;
+            }[];
             resolve: {
                 alias: Record<string, string>;
             };
@@ -35,6 +54,11 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
                 server?: undefined;
             };
         } | {
+            plugins: {
+                name: string;
+                enforce: "pre";
+                load(id: string): string;
+            }[];
             resolve: {
                 alias: Record<string, string>;
             };

package/dist/vitest-preset.js

@@ -29,6 +29,24 @@ function findRepoRoot(startDir) {
         dir = parent;
     }
 }
+/**
+ * termix-plugin build turns a .wasm or font import into its bytes. Tests get the same,
+ * so code that imports a module compiles it the same way under vitest.
+ */
+export function wasmBinaryPlugin() {
+    return {
+        name: "termix-wasm-binary",
+        enforce: "pre",
+        load(id) {
+            const file = id.split("?")[0];
+            if (![".wasm", ".ttf", ".otf"].some((ext) => file.endsWith(ext))) {
+                return null;
+            }
+            const base64 = fs.readFileSync(file).toString("base64");
+            return `export default new Uint8Array(Buffer.from(${JSON.stringify(base64)}, "base64"));`;
+        },
+    };
+}
 export function pluginVitestConfig(configUrl, options = {}) {
     const pluginDir = path.dirname(fileURLToPath(configUrl));
     const manifestPath = path.join(pluginDir, "manifest.json");
@@ -61,7 +79,9 @@ export function pluginVitestConfig(configUrl, options = {}) {
     // Forks workers on Windows abort now and then with "Worker exited
     // unexpectedly". Threads don't.
     const pool = "threads";
+    const plugins = [wasmBinaryPlugin()];
     return {
+        plugins,
         resolve: { alias },
         test: {
             globals: true,
@@ -69,6 +89,7 @@ export function pluginVitestConfig(configUrl, options = {}) {
             pool,
             projects: [
                 {
+                    plugins,
                     resolve: { alias },
                     test: {
                         name: `${pluginId}:backend`,
@@ -81,6 +102,7 @@ export function pluginVitestConfig(configUrl, options = {}) {
                     },
                 },
                 {
+                    plugins,
                     resolve: { alias },
                     test: {
                         name: `${pluginId}:frontend`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termix-ssh/plugin-sdk",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "The contract between Termix core and a plugin: types, the capability catalog and the manifest schema.",
   "license": "Apache-2.0",
   "repository": {