@qping/plugin-bus 0.2.0 → 0.4.0

package/dist/node.mjs

@@ -167,6 +167,7 @@ var Routes = {
     Initialize: "host.event.initialize",
     Search: "host.event.search",
     Key: "host.event.key",
+    DetailAction: "host.event.detailAction",
     LanguageChanged: "host.event.languageChanged",
     ThemeChanged: "host.event.themeChanged",
     InputActionCaptured: "host.event.inputActionCaptured"
@@ -339,7 +340,10 @@ var HandlerRouter = class {
     }
     const deadlineMs = deadlineFromTimeoutMs(env.timeoutMs);
     try {
-      const result = await requestScope.run({ deadlineMs }, () => handler(env.payload));
+      const result = await requestScope.run(
+        { deadlineMs },
+        () => handler(env.payload, { sessionId: env.sessionId })
+      );
       this.send(this.responseFor(env, result ?? {}));
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -527,13 +531,120 @@ async function completeHandshake(transport, token, timeoutMs = 1e4) {
   });
 }
 
+// src/hostEnv.ts
+function asTheme(value) {
+  return value === "light" ? "light" : "dark";
+}
+function asHostEnv(payload) {
+  return {
+    locale: typeof payload?.locale === "string" ? payload.locale : "en-US",
+    fallbackLocale: typeof payload?.fallbackLocale === "string" ? payload.fallbackLocale : "en-US",
+    theme: asTheme(payload?.theme)
+  };
+}
+
+// src/actions.ts
+var Key = {
+  Enter: "Enter",
+  Tab: "Tab",
+  Space: "Space",
+  Delete: "Delete",
+  Backspace: "Backspace",
+  Escape: "Escape",
+  Left: "Left",
+  Right: "Right",
+  Up: "Up",
+  Down: "Down",
+  A: "A",
+  B: "B",
+  C: "C",
+  D: "D",
+  E: "E",
+  F: "F",
+  G: "G",
+  H: "H",
+  I: "I",
+  J: "J",
+  K: "K",
+  L: "L",
+  M: "M",
+  N: "N",
+  O: "O",
+  P: "P",
+  Q: "Q",
+  R: "R",
+  S: "S",
+  T: "T",
+  U: "U",
+  V: "V",
+  W: "W",
+  X: "X",
+  Y: "Y",
+  Z: "Z",
+  D0: "D0",
+  D1: "D1",
+  D2: "D2",
+  D3: "D3",
+  D4: "D4",
+  D5: "D5",
+  D6: "D6",
+  D7: "D7",
+  D8: "D8",
+  D9: "D9",
+  F1: "F1",
+  F2: "F2",
+  F3: "F3",
+  F4: "F4",
+  F5: "F5",
+  F6: "F6",
+  F7: "F7",
+  F8: "F8",
+  F9: "F9",
+  F10: "F10",
+  F11: "F11",
+  F12: "F12"
+};
+var Modifiers = {
+  None: 0,
+  Control: 1,
+  Alt: 2,
+  ControlAlt: 3,
+  Shift: 4,
+  ControlShift: 5,
+  AltShift: 6,
+  ControlAltShift: 7
+};
+var HostAction = {
+  Copy: "copy",
+  CopyAndPaste: "copyAndPaste",
+  AddClipboardHistory: "addClipboardHistory",
+  Execute: "execute",
+  OpenInExplorer: "openInExplorer",
+  OpenInBrowser: "openInBrowser",
+  OpenPlugin: "openPlugin",
+  Run: "run",
+  Kill: "kill"
+};
+function toActionManifest(definition) {
+  const entry = {
+    id: definition.id,
+    title: definition.title
+  };
+  if (definition.description) entry.description = definition.description;
+  if (definition.hotkey) entry.hotkey = definition.hotkey;
+  return entry;
+}
+
 // src/node.ts
+var ItemCacheLimit = 1e3;
+var SessionCacheLimit = 8;
 var Plugin = class {
   #handlers = /* @__PURE__ */ new Map();
+  #actions = /* @__PURE__ */ new Map();
   #searchHandler = null;
-  #actionHandler = null;
   #initializeHandler = null;
   #runtime = null;
+  #itemsBySession = /* @__PURE__ */ new Map();
   initialize(handler) {
     this.#initializeHandler = handler;
     return this;
@@ -542,8 +653,27 @@ var Plugin = class {
     this.#searchHandler = handler;
     return this;
   }
-  action(handler) {
-    this.#actionHandler = handler;
+  /**
+   * Registers every action this plugin offers. The list is sent to the host in the initialize
+   * response, so the host knows the ids, labels and hotkeys before any search runs; search items
+   * and the detail page then reference them by id only.
+   */
+  actions(definitions) {
+    if (!Array.isArray(definitions)) {
+      throw new Error("plugin.actions requires an array of action definitions.");
+    }
+    for (const definition of definitions) {
+      if (!definition?.id) {
+        throw new Error("plugin.actions requires every action to have an id.");
+      }
+      if (this.#actions.has(definition.id)) {
+        throw new Error(`plugin.actions has a duplicate action id: ${definition.id}`);
+      }
+      if (typeof definition.execute !== "function") {
+        throw new Error(`plugin.actions requires an execute function for action: ${definition.id}`);
+      }
+      this.#actions.set(definition.id, definition);
+    }
     return this;
   }
   handle(action, handler) {
@@ -592,14 +722,19 @@ var Plugin = class {
    */
   buildRoutes() {
     const routes = {};
-    if (this.#initializeHandler) {
-      routes[Routes.PluginCall.Initialize] = (p) => this.#initializeHandler(asInitializeParams(p));
-    }
+    routes[Routes.PluginCall.Initialize] = async (p) => {
+      const result = this.#initializeHandler ? await this.#initializeHandler(asInitializeParams(p)) : {};
+      const body = result && typeof result === "object" ? { ...result } : {};
+      return { ...body, actions: [...this.#actions.values()].map(toActionManifest) };
+    };
     if (this.#searchHandler) {
-      routes[Routes.PluginCall.Search] = (p) => this.#searchHandler(asSearchParams(p));
+      routes[Routes.PluginCall.Search] = async (p, request) => {
+        const result = await this.#searchHandler(asSearchParams(p));
+        return { items: this.#trackItems(request?.sessionId ?? "default", result?.items ?? []) };
+      };
     }
-    if (this.#actionHandler) {
-      routes[Routes.PluginCall.InvokeAction] = (p) => this.#actionHandler(asActionParams(p));
+    if (this.#actions.size > 0) {
+      routes[Routes.PluginCall.InvokeAction] = (p, request) => this.#invokeAction(request?.sessionId ?? "default", p);
     }
     for (const [action, handler] of this.#handlers) {
       const route = pluginCallRoute(action);
@@ -615,13 +750,69 @@ var Plugin = class {
   async stop() {
     if (this.#runtime) await this.#runtime.close();
   }
+  /** Remembers the full items and returns the trimmed rows the host actually renders. */
+  #trackItems(sessionId, items) {
+    const sessionItems = this.#sessionItems(sessionId);
+    const wire = [];
+    for (const item of items) {
+      if (!item || typeof item !== "object") continue;
+      const id = typeof item.id === "string" ? item.id : "";
+      if (id) {
+        sessionItems.delete(id);
+        sessionItems.set(id, item);
+      }
+      wire.push(toWireItem(item));
+    }
+    while (sessionItems.size > ItemCacheLimit) {
+      const oldest = sessionItems.keys().next();
+      if (oldest.done) break;
+      sessionItems.delete(oldest.value);
+    }
+    return wire;
+  }
+  async #invokeAction(sessionId, payload) {
+    const env = asHostEnv(payload);
+    const actionId = typeof payload?.actionId === "string" ? payload.actionId : "";
+    const itemId = typeof payload?.itemId === "string" ? payload.itemId : "";
+    const query = typeof payload?.query === "string" ? payload.query : "";
+    const definition = this.#actions.get(actionId);
+    if (!definition) {
+      throw new Error(`unknown action: ${actionId}`);
+    }
+    const outcome = await definition.execute({
+      ...env,
+      actionId,
+      itemId,
+      query,
+      item: this.#itemsBySession.get(sessionId)?.get(itemId)
+    });
+    return outcome ?? {};
+  }
+  #sessionItems(sessionId) {
+    const key = sessionId || "default";
+    let items = this.#itemsBySession.get(key);
+    if (!items) {
+      items = /* @__PURE__ */ new Map();
+      this.#itemsBySession.set(key, items);
+      while (this.#itemsBySession.size > SessionCacheLimit) {
+        const oldest = this.#itemsBySession.keys().next();
+        if (oldest.done) break;
+        this.#itemsBySession.delete(oldest.value);
+      }
+    }
+    return items;
+  }
 };
-function asHostEnv(p) {
-  return {
-    locale: typeof p?.locale === "string" ? p.locale : "en-US",
-    fallbackLocale: typeof p?.fallbackLocale === "string" ? p.fallbackLocale : "en-US",
-    theme: asTheme(p?.theme)
+function toWireItem(item) {
+  const wire = {
+    id: item.id,
+    title: item.title
   };
+  if (typeof item.subtitle === "string") wire.subtitle = item.subtitle;
+  if (typeof item.priority === "number") wire.priority = item.priority;
+  if (item.icon) wire.icon = item.icon;
+  if (Array.isArray(item.actions)) wire.actions = item.actions.filter((id) => typeof id === "string");
+  return wire;
 }
 function asInitializeParams(p) {
   const messages = p?.messages;
@@ -637,17 +828,6 @@ function asSearchParams(p) {
     mode: p?.mode === "plugin" ? "plugin" : "global"
   };
 }
-function asActionParams(p) {
-  return {
-    ...asHostEnv(p),
-    itemId: typeof p?.itemId === "string" ? p.itemId : "",
-    actionId: typeof p?.actionId === "string" ? p.actionId : "",
-    query: typeof p?.query === "string" ? p.query : ""
-  };
-}
-function asTheme(value) {
-  return value === "light" ? "light" : "dark";
-}
 function isStringRecord(value) {
   return !!value && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((v) => typeof v === "string");
 }
@@ -663,6 +843,9 @@ function createPlugin() {
   return new Plugin();
 }
 export {
+  HostAction,
+  Key,
+  Modifiers,
   Plugin,
   createPlugin
 };

package/dist/protocol.d.ts

@@ -62,6 +62,7 @@ export declare const Routes: {
         readonly Initialize: "host.event.initialize";
         readonly Search: "host.event.search";
         readonly Key: "host.event.key";
+        readonly DetailAction: "host.event.detailAction";
         readonly LanguageChanged: "host.event.languageChanged";
         readonly ThemeChanged: "host.event.themeChanged";
         readonly InputActionCaptured: "host.event.inputActionCaptured";

package/dist/protocol.mjs

@@ -49,6 +49,7 @@ var Routes = {
     Initialize: "host.event.initialize",
     Search: "host.event.search",
     Key: "host.event.key",
+    DetailAction: "host.event.detailAction",
     LanguageChanged: "host.event.languageChanged",
     ThemeChanged: "host.event.themeChanged",
     InputActionCaptured: "host.event.inputActionCaptured"

package/dist/router.d.ts

@@ -4,7 +4,9 @@
  * and correlate their responses. Mirrors the C# MessageBus routing rules on the Node side.
  */
 import { type Envelope } from "./protocol.ts";
-type Handler = (payload: unknown) => Promise<unknown> | unknown;
+type Handler = (payload: unknown, context: {
+    sessionId: string;
+}) => Promise<unknown> | unknown;
 type Sender = (env: Envelope) => void;
 export declare const DefaultHostCallTimeoutMs = 30000;
 /** Remaining ms of the inbound plugin.call timeout, if currently inside a request. */

package/dist/search.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns whether every character in `pattern` occurs in `target` in the same order.
+ * Matching is case-insensitive and characters do not need to be adjacent.
+ *
+ * @example isSubsequence("gthb", "GitHub") // true
+ */
+export declare function isSubsequence(pattern: string, target: string): boolean;

package/dist/search.mjs

@@ -0,0 +1,17 @@
+// src/search.ts
+function isSubsequence(pattern, target) {
+  if (!pattern) return true;
+  if (!target) return false;
+  const needle = pattern.toLowerCase();
+  const haystack = target.toLowerCase();
+  let patternIndex = 0;
+  for (let targetIndex = 0; targetIndex < haystack.length && patternIndex < needle.length; targetIndex += 1) {
+    if (haystack[targetIndex] === needle[patternIndex]) {
+      patternIndex += 1;
+    }
+  }
+  return patternIndex === needle.length;
+}
+export {
+  isSubsequence
+};

package/dist/webClient.d.ts

@@ -8,8 +8,9 @@
 import { mytoolsI18n } from "./i18n.ts";
 import type { MyToolsThemePayload } from "./webTypes.ts";
 export { mytoolsI18n } from "./i18n.ts";
+export { renderHotkeyKeycaps } from "./hotkeyKeycaps.ts";
 export { HostEvents } from "./webTypes.ts";
-export type { MyToolsHostInitializePayload, MyToolsHostKeyPayload, MyToolsHostSearchPayload, MyToolsInputActionCapturedPayload, MyToolsLanguageChangedPayload, MyToolsThemeChangedPayload, MyToolsThemePayload, } from "./webTypes.ts";
+export type { MyToolsHostActionDefinition, MyToolsHostDetailActionPayload, MyToolsHostInitializePayload, MyToolsHostKeyPayload, MyToolsHostSearchPayload, MyToolsInputActionCapturedPayload, MyToolsLanguageChangedPayload, MyToolsThemeChangedPayload, MyToolsThemePayload, } from "./webTypes.ts";
 export interface WebBusClient {
     /** Sends plugin.call.<method>. Bare names are prefixed; full routes are left as-is. */
     call<T = unknown>(method: string, payload?: unknown, timeoutMs?: number): Promise<T>;

package/dist/webClient.mjs

@@ -2370,6 +2370,7 @@ var Routes = {
     Initialize: "host.event.initialize",
     Search: "host.event.search",
     Key: "host.event.key",
+    DetailAction: "host.event.detailAction",
     LanguageChanged: "host.event.languageChanged",
     ThemeChanged: "host.event.themeChanged",
     InputActionCaptured: "host.event.inputActionCaptured"
@@ -2379,6 +2380,29 @@ function pluginCallRoute(method) {
   return method.startsWith(Routes.Prefix.PluginCall) ? method : `${Routes.Prefix.PluginCall}${method}`;
 }
 
+// src/hotkeyKeycaps.ts
+function renderHotkeyKeycaps(element, hotkey) {
+  const normalized = hotkey.trim();
+  element.hidden = normalized.length === 0;
+  element.setAttribute("aria-label", normalized);
+  element.classList.add("hotkey-keycaps");
+  const keycaps = normalized.length === 0 ? [] : normalized.split("+").map((token) => createKeycap(token.trim()));
+  element.replaceChildren(...keycaps);
+}
+function createKeycap(token) {
+  const keycap = document.createElement("span");
+  keycap.className = "hotkey-keycap";
+  keycap.setAttribute("aria-hidden", "true");
+  if (token.toLowerCase() === "enter" || token.toLowerCase() === "return") {
+    keycap.classList.add("hotkey-keycap-enter");
+    keycap.textContent = "\u21B5";
+    keycap.title = "Enter";
+  } else {
+    keycap.textContent = token;
+  }
+  return keycap;
+}
+
 // src/webTypes.ts
 var HostEvents = Routes.HostEvent;
 
@@ -2595,5 +2619,6 @@ function handshake(timeoutMs) {
 export {
   HostEvents,
   createWebBusClient,
-  mytoolsI18n
+  mytoolsI18n,
+  renderHotkeyKeycaps
 };

package/dist/webTypes.d.ts

@@ -1,3 +1,10 @@
+export interface MyToolsHostActionDefinition {
+    id: string;
+    /** Host-localized action display name. */
+    name: string;
+    /** Host-validated display form, for example `Ctrl+H`; absent means click-only. */
+    hotkey?: string | null;
+}
 export interface MyToolsHostInitializePayload {
     protocolVersion: string;
     pluginId: string;
@@ -10,6 +17,7 @@ export interface MyToolsHostInitializePayload {
     fallbackLocale: string;
     translationRevision: string;
     messages: Record<string, string>;
+    actions: MyToolsHostActionDefinition[];
     theme?: string;
     themeTokens?: Record<string, string>;
 }
@@ -29,6 +37,12 @@ export interface MyToolsHostSearchPayload {
 export interface MyToolsHostKeyPayload {
     key: string;
 }
+/** Payload explicitly returned in an action outcome's `web.payload`. */
+export interface MyToolsHostDetailActionPayload {
+    actionId?: string;
+    action?: string;
+    [key: string]: unknown;
+}
 export interface MyToolsInputActionCapturedPayload {
     requestId: string;
     cancelled?: boolean;
@@ -44,6 +58,7 @@ export declare const HostEvents: {
     readonly Initialize: "host.event.initialize";
     readonly Search: "host.event.search";
     readonly Key: "host.event.key";
+    readonly DetailAction: "host.event.detailAction";
     readonly LanguageChanged: "host.event.languageChanged";
     readonly ThemeChanged: "host.event.themeChanged";
     readonly InputActionCaptured: "host.event.inputActionCaptured";

package/package.json

@@ -1,50 +1,60 @@
-{
-  "name": "@qping/plugin-bus",
-  "version": "0.2.0",
-  "description": "v3 message-bus runtime for MyTools plugins (named-pipe transport).",
-  "type": "module",
-  "files": [
-    "dist",
-    "src"
-  ],
-  "exports": {
-    "./node": {
-      "types": "./dist/node.d.ts",
-      "import": "./dist/node.mjs",
-      "default": "./dist/node.mjs"
-    },
-    "./protocol": {
-      "types": "./dist/protocol.d.ts",
-      "import": "./dist/protocol.mjs",
-      "default": "./dist/protocol.mjs"
-    },
-    "./bootstrap": {
-      "types": "./dist/bootstrap.d.ts",
-      "import": "./dist/bootstrap.mjs",
-      "default": "./dist/bootstrap.mjs"
-    },
-    "./web": {
-      "types": "./dist/webClient.d.ts",
-      "import": "./dist/webClient.mjs",
-      "default": "./dist/webClient.mjs"
-    },
-    "./i18n": {
-      "types": "./dist/i18n.d.ts",
-      "import": "./dist/i18n.mjs",
-      "default": "./dist/i18n.mjs"
-    },
-    "./package.json": "./package.json"
-  },
-  "dependencies": {
-    "i18next": "^25.3.2"
-  },
-  "scripts": {
-    "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && node build-sdk.mjs",
-    "check": "node build-sdk.mjs"
-  },
-  "devDependencies": {
-    "esbuild": "^0.25.8",
-    "typescript": "^7.0.2"
-  }
-}
+{
+  "name": "@qping/plugin-bus",
+  "version": "0.4.0",
+  "description": "v3 message-bus runtime for MyTools plugins (named-pipe transport).",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.mjs",
+      "default": "./dist/node.mjs"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.mjs",
+      "default": "./dist/protocol.mjs"
+    },
+    "./bootstrap": {
+      "types": "./dist/bootstrap.d.ts",
+      "import": "./dist/bootstrap.mjs",
+      "default": "./dist/bootstrap.mjs"
+    },
+    "./web": {
+      "types": "./dist/webClient.d.ts",
+      "import": "./dist/webClient.mjs",
+      "default": "./dist/webClient.mjs"
+    },
+    "./i18n": {
+      "types": "./dist/i18n.d.ts",
+      "import": "./dist/i18n.mjs",
+      "default": "./dist/i18n.mjs"
+    },
+    "./search": {
+      "types": "./dist/search.d.ts",
+      "import": "./dist/search.mjs",
+      "default": "./dist/search.mjs"
+    },
+    "./dev": {
+      "types": "./dist/dev.d.ts",
+      "import": "./dist/dev.mjs",
+      "default": "./dist/dev.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "i18next": "^25.3.2"
+  },
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && node build-sdk.mjs",
+    "check": "node build-sdk.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.8",
+    "typescript": "^7.0.2"
+  }
+}