@qping/plugin-bus 0.1.0 → 0.3.0

package/dist/actions.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Action registry types.
+ *
+ * A plugin registers its full action set once at startup via `plugin.actions([...])`. Search
+ * items and the detail page only reference actions by id; the parameters an action needs are
+ * produced inside its own `execute`, never carried on the item.
+ */
+import type { PluginHostEnv } from "./hostEnv.ts";
+/** An i18n message key plus the English fallback the host uses when the key is missing. */
+export type LocalizedText = {
+    key: string;
+    defaultValue: string;
+};
+/** Keys the host deliberately permits for action shortcuts. */
+export declare const Key: {
+    readonly Enter: "Enter";
+    readonly Tab: "Tab";
+    readonly Space: "Space";
+    readonly Delete: "Delete";
+    readonly Backspace: "Backspace";
+    readonly Escape: "Escape";
+    readonly Left: "Left";
+    readonly Right: "Right";
+    readonly Up: "Up";
+    readonly Down: "Down";
+    readonly A: "A";
+    readonly B: "B";
+    readonly C: "C";
+    readonly D: "D";
+    readonly E: "E";
+    readonly F: "F";
+    readonly G: "G";
+    readonly H: "H";
+    readonly I: "I";
+    readonly J: "J";
+    readonly K: "K";
+    readonly L: "L";
+    readonly M: "M";
+    readonly N: "N";
+    readonly O: "O";
+    readonly P: "P";
+    readonly Q: "Q";
+    readonly R: "R";
+    readonly S: "S";
+    readonly T: "T";
+    readonly U: "U";
+    readonly V: "V";
+    readonly W: "W";
+    readonly X: "X";
+    readonly Y: "Y";
+    readonly Z: "Z";
+    readonly D0: "D0";
+    readonly D1: "D1";
+    readonly D2: "D2";
+    readonly D3: "D3";
+    readonly D4: "D4";
+    readonly D5: "D5";
+    readonly D6: "D6";
+    readonly D7: "D7";
+    readonly D8: "D8";
+    readonly D9: "D9";
+    readonly F1: "F1";
+    readonly F2: "F2";
+    readonly F3: "F3";
+    readonly F4: "F4";
+    readonly F5: "F5";
+    readonly F6: "F6";
+    readonly F7: "F7";
+    readonly F8: "F8";
+    readonly F9: "F9";
+    readonly F10: "F10";
+    readonly F11: "F11";
+    readonly F12: "F12";
+};
+export type HotkeyKey = (typeof Key)[keyof typeof Key];
+/** Permitted modifier combinations, e.g. `Modifiers.ControlShift`. */
+export declare const Modifiers: {
+    readonly None: 0;
+    readonly Control: 1;
+    readonly Alt: 2;
+    readonly ControlAlt: 3;
+    readonly Shift: 4;
+    readonly ControlShift: 5;
+    readonly AltShift: 6;
+    readonly ControlAltShift: 7;
+};
+export type HotkeyModifiers = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+export type Hotkey = {
+    key: HotkeyKey;
+    modifiers?: HotkeyModifiers;
+};
+/** Actions the host itself can carry out. Anything else belongs in `execute`. */
+export declare const HostAction: {
+    readonly Copy: "copy";
+    readonly CopyAndPaste: "copyAndPaste";
+    readonly AddClipboardHistory: "addClipboardHistory";
+    readonly Execute: "execute";
+    readonly OpenInExplorer: "openInExplorer";
+    readonly OpenInBrowser: "openInBrowser";
+    readonly OpenPlugin: "openPlugin";
+    readonly Run: "run";
+    readonly Kill: "kill";
+};
+export type HostActionKind = (typeof HostAction)[keyof typeof HostAction];
+/** Command spec for {@link HostAction.Run}. */
+export type RunSpec = {
+    name?: string;
+    command: string;
+    args?: string;
+    workingDirectory?: string;
+    runAsAdmin?: boolean;
+    isBashScript?: boolean;
+    scripts?: string | string[];
+};
+/**
+ * What the host should do, with the parameters that kind actually needs. The discriminated union
+ * is the point: `{ kind: HostAction.Copy, path }` does not compile.
+ */
+export type HostActionRequest = {
+    kind: typeof HostAction.Copy;
+    text: string;
+} | {
+    kind: typeof HostAction.CopyAndPaste;
+    text: string;
+} | {
+    kind: typeof HostAction.AddClipboardHistory;
+    texts: string[];
+} | {
+    kind: typeof HostAction.Execute;
+    path: string;
+    args?: string;
+    runAsAdmin?: boolean;
+} | {
+    kind: typeof HostAction.OpenInExplorer;
+    path: string;
+} | {
+    kind: typeof HostAction.OpenInBrowser;
+    url: string | string[];
+} | {
+    kind: typeof HostAction.OpenPlugin;
+    pluginId: string;
+} | {
+    kind: typeof HostAction.Run;
+    command: RunSpec;
+} | {
+    kind: typeof HostAction.Kill;
+    pid: number;
+};
+/** Opens a web detail page. `page` defaults to the entry declared in plugin.json. */
+export type DetailRequest = {
+    page?: string;
+    title?: string;
+    initialState?: unknown;
+};
+/**
+ * The result of running an action. Every field is optional and they combine: opening an IDE and
+ * closing the search window is `{ host: {...}, close: true }`.
+ */
+export type ActionOutcome = {
+    /** Run a host-side action (clipboard, process launch, browser, ...). */
+    host?: HostActionRequest;
+    /** Hand off to the detail page; arrives as `host.event.detailAction` with this payload. */
+    web?: {
+        payload?: unknown;
+    };
+    /** Open a web detail page. */
+    detail?: DetailRequest;
+    /** Status bar text. */
+    message?: LocalizedText;
+    /** Close the search window afterwards. Defaults to false. */
+    close?: boolean;
+    /** Refresh the current search results afterwards. Defaults to false. */
+    refresh?: boolean;
+};
+/**
+ * What an action sees when it runs. `item` is the original object returned by `search()`,
+ * including fields the host never saw — the SDK keeps it so actions do not have to re-derive
+ * their data from the item id.
+ */
+export type ActionContext<TItem = unknown> = PluginHostEnv & {
+    actionId: string;
+    itemId: string;
+    query: string;
+    item?: TItem;
+};
+/**
+ * One registered action. `hotkey` is optional: without it the first registered action gets Enter
+ * and the rest are click-only, matching search result items.
+ */
+export type ActionDefinition<TItem = any> = {
+    id: string;
+    title: LocalizedText;
+    description?: LocalizedText;
+    hotkey?: Hotkey;
+    execute: (context: ActionContext<TItem>) => ActionOutcome | void | Promise<ActionOutcome | void>;
+};
+/** The registry shape sent to the host in the initialize response (no `execute`). */
+export type ActionManifestEntry = {
+    id: string;
+    title: LocalizedText;
+    description?: LocalizedText;
+    hotkey?: Hotkey;
+};
+export declare function toActionManifest(definition: ActionDefinition): ActionManifestEntry;

package/dist/bootstrap.d.ts

@@ -0,0 +1,36 @@
+/**
+ * v3 Node SDK bootstrap entry. Reads the bootstrap line from stdin (pipePath\ttoken), connects to
+ * the named pipe, completes bus.handshake (presenting the token and receiving bound identity),
+ * and starts a HandlerRouter stamped with that identity.
+ *
+ * This mirrors the C# NodeProcessController's spawn contract: the host writes one line to the
+ * Node process's stdin — "<pipePath>\t<token>" — then waits for the Node side to connect the pipe
+ * and complete handshake before promoting the session to Ready.
+ */
+import { NodeTransport } from "./transport.ts";
+import { HandlerRouter } from "./router.ts";
+export interface PluginHandlers {
+    [route: string]: (payload: any, context: {
+        sessionId: string;
+    }) => Promise<any> | any;
+}
+export interface PluginRuntime {
+    transport: NodeTransport;
+    router: HandlerRouter;
+    close(): Promise<void>;
+}
+/**
+ * Connects to the host pipe (reading the bootstrap line from stdin), completes handshake, and
+ * returns a runtime whose router dispatches inbound plugin.call.* requests to the given handlers.
+ */
+export declare function runPlugin(handlers: PluginHandlers): Promise<PluginRuntime>;
+/**
+ * Sends bus.handshake with the bootstrap token and waits for the host response that binds
+ * plugin/entry/session/endpoint identity. Rejects on HandshakeFailed / ProtocolMismatch / timeout.
+ */
+export declare function completeHandshake(transport: NodeTransport, token: string, timeoutMs?: number): Promise<{
+    pluginId: string;
+    entryId: string;
+    sessionId: string;
+    endpointId: string;
+}>;

package/dist/bootstrap.mjs

@@ -110,12 +110,69 @@ var init_framing = __esm({
 
 // src/bootstrap.ts
 import readline from "node:readline/promises";
+import { randomBytes as randomBytes2 } from "node:crypto";
 
 // src/transport.ts
 init_framing();
 import { connect as netConnect } from "node:net";
 
 // src/protocol.ts
+var MessageKind = {
+  Request: "request",
+  Response: "response",
+  Event: "event"
+};
+var ErrorCode = {
+  ProtocolMismatch: "ProtocolMismatch",
+  HandshakeFailed: "HandshakeFailed",
+  CapabilityNotDeclared: "CapabilityNotDeclared",
+  CapabilityDenied: "CapabilityDenied",
+  InvalidPayload: "InvalidPayload",
+  MessageTooLarge: "MessageTooLarge",
+  RouteNotFound: "RouteNotFound",
+  RequestTimeout: "RequestTimeout",
+  TooManyRequests: "TooManyRequests",
+  TransportDisconnected: "TransportDisconnected",
+  PluginUnavailable: "PluginUnavailable",
+  InternalError: "InternalError",
+  Cancelled: "Cancelled",
+  RateLimited: "RateLimited"
+};
+var ProtocolVersion = "3.0";
+var EndpointIds = {
+  NodeMain: "node-main",
+  Host: "host"
+};
+var Routes = {
+  Bus: {
+    Handshake: "bus.handshake",
+    Ping: "bus.ping",
+    Cancel: "bus.cancel",
+    Subscribe: "bus.subscribe",
+    Unsubscribe: "bus.unsubscribe"
+  },
+  Prefix: {
+    PluginCall: "plugin.call.",
+    HostCall: "host.call.",
+    PluginEvent: "plugin.event.",
+    HostEvent: "host.event.",
+    Diagnostics: "diagnostics."
+  },
+  PluginCall: {
+    Initialize: "plugin.call.initialize",
+    Search: "plugin.call.search",
+    InvokeAction: "plugin.call.invokeAction"
+  },
+  HostEvent: {
+    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"
+  }
+};
 function canonicalStringify(value) {
   return JSON.stringify(stripNulls(value));
 }
@@ -141,6 +198,9 @@ var NodeTransport = class {
   closed = false;
   onMessage(handler) {
     this.messageHandlers.add(handler);
+    return () => {
+      this.messageHandlers.delete(handler);
+    };
   }
   onDisconnect(handler) {
     this.disconnectHandlers.add(handler);
@@ -207,14 +267,37 @@ var NodeTransport = class {
 };
 
 // src/router.ts
+import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes } from "node:crypto";
+var requestScope = new AsyncLocalStorage();
+var DefaultHostCallTimeoutMs = 3e4;
+function remainingTimeoutMs() {
+  const scope = requestScope.getStore();
+  if (!scope || scope.deadlineMs == null) {
+    return void 0;
+  }
+  return scope.deadlineMs - Date.now();
+}
+function resolveHostCallTimeoutMs(explicit) {
+  const remaining = remainingTimeoutMs();
+  if (explicit != null) {
+    return remaining == null ? explicit : Math.min(explicit, remaining);
+  }
+  return remaining ?? DefaultHostCallTimeoutMs;
+}
+function deadlineFromTimeoutMs(timeoutMs) {
+  if (typeof timeoutMs !== "number" || timeoutMs <= 0) {
+    return null;
+  }
+  return Date.now() + timeoutMs;
+}
 var HandlerRouter = class {
   handlers = /* @__PURE__ */ new Map();
   pendingHostCalls = /* @__PURE__ */ new Map();
   pluginId = "p";
   entryId = "e";
   sessionId = "s";
-  endpointId = "node-main";
+  endpointId = EndpointIds.NodeMain;
   /** Injected transport send fn; tests can override `router.send` directly. */
   send;
   constructor(deps) {
@@ -232,43 +315,51 @@ var HandlerRouter = class {
   }
   /** Dispatches an inbound request/response. Returns once handled. */
   async dispatch(env) {
-    if (env.kind === "response") {
+    if (env.kind === MessageKind.Response) {
       this.handleHostResponse(env);
       return;
     }
-    if (env.kind !== "request") return;
-    if (env.route === "bus.ping") {
+    if (env.kind !== MessageKind.Request) return;
+    if (env.route === Routes.Bus.Ping) {
       this.send(this.responseFor(env, { ok: true }));
       return;
     }
     const handler = this.handlers.get(env.route);
     if (!handler) {
-      this.send(this.errorResponseFor(env, "RouteNotFound", `route '${env.route}' has no handler`));
+      this.send(this.errorResponseFor(env, ErrorCode.RouteNotFound, `route '${env.route}' has no handler`));
       return;
     }
+    const deadlineMs = deadlineFromTimeoutMs(env.timeoutMs);
     try {
-      const result = await 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);
-      this.send(this.errorResponseFor(env, "InternalError", message));
+      this.send(this.errorResponseFor(env, ErrorCode.InternalError, message));
     }
   }
   /** Calls a host.call.* capability and resolves with the response payload. */
-  callHost(route, payload, timeoutMs = 3e4) {
+  callHost(route, payload, timeoutMs) {
+    const effectiveTimeoutMs = resolveHostCallTimeoutMs(timeoutMs);
+    if (effectiveTimeoutMs <= 0) {
+      return Promise.reject(new Error(`host call ${route} timed out (no time remaining)`));
+    }
     return new Promise((resolve, reject) => {
       const id = randomBytesHex();
       const req = {
-        version: "3.0",
+        version: ProtocolVersion,
         id,
         traceId: id,
         sessionId: this.sessionId,
         pluginId: this.pluginId,
         entryId: this.entryId,
         endpointId: this.endpointId,
-        kind: "request",
+        kind: MessageKind.Request,
         route,
-        timeoutMs,
+        timeoutMs: effectiveTimeoutMs,
         payload
       };
       const pending = { resolve, reject, route };
@@ -276,9 +367,9 @@ var HandlerRouter = class {
       const timer = setTimeout(() => {
         if (this.pendingHostCalls.has(id)) {
           this.pendingHostCalls.delete(id);
-          reject(new Error(`host call ${route} timed out after ${timeoutMs}ms`));
+          reject(new Error(`host call ${route} timed out after ${effectiveTimeoutMs}ms`));
         }
-      }, timeoutMs);
+      }, effectiveTimeoutMs);
       const origResolve = pending.resolve;
       const origReject = pending.reject;
       pending.resolve = (v) => {
@@ -305,7 +396,7 @@ var HandlerRouter = class {
   }
   responseFor(req, payload) {
     return {
-      version: "3.0",
+      version: ProtocolVersion,
       id: randomBytesHex(),
       correlationId: req.id,
       traceId: req.traceId,
@@ -313,7 +404,7 @@ var HandlerRouter = class {
       pluginId: req.pluginId,
       entryId: req.entryId,
       endpointId: this.endpointId,
-      kind: "response",
+      kind: MessageKind.Response,
       route: req.route,
       payload
     };
@@ -331,12 +422,29 @@ function randomBytesHex() {
 }
 
 // src/bootstrap.ts
+var SUPPORTED_VERSIONS = [ProtocolVersion];
 async function runPlugin(handlers) {
   const { pipePath, token } = await readBootstrapLine();
   const transport = new NodeTransport();
   await transport.connect(pipePath);
+  const identity = await completeHandshake(transport, token);
   const router = new HandlerRouter({ send: (env) => transport.send(env) });
+  router.setIdentity(identity);
+  const HOST_LOST_MS = 15e3;
+  let lastPingAt = Date.now();
+  const watchdog = setInterval(() => {
+    if (Date.now() - lastPingAt > HOST_LOST_MS) {
+      clearInterval(watchdog);
+      process.exit(1);
+    }
+  }, 1e3);
+  watchdog.unref?.();
+  transport.onDisconnect(() => {
+    clearInterval(watchdog);
+    process.exit(1);
+  });
   transport.onMessage((env) => {
+    if (env.route === Routes.Bus.Ping) lastPingAt = Date.now();
     router.dispatch(env);
   });
   for (const [route, handler] of Object.entries(handlers)) {
@@ -345,7 +453,10 @@ async function runPlugin(handlers) {
   return {
     transport,
     router,
-    close: () => transport.close()
+    close: async () => {
+      clearInterval(watchdog);
+      await transport.close();
+    }
   };
 }
 async function readBootstrapLine() {
@@ -364,6 +475,53 @@ async function readBootstrapLine() {
     rl.close();
   }
 }
+async function completeHandshake(transport, token, timeoutMs = 1e4) {
+  const id = randomBytes2(16).toString("hex");
+  const req = {
+    version: ProtocolVersion,
+    id,
+    traceId: id,
+    sessionId: "",
+    pluginId: "",
+    entryId: "",
+    endpointId: EndpointIds.NodeMain,
+    kind: MessageKind.Request,
+    route: Routes.Bus.Handshake,
+    timeoutMs,
+    payload: {
+      version: ProtocolVersion,
+      supportedVersions: SUPPORTED_VERSIONS,
+      token
+    }
+  };
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      unsubscribe();
+      reject(new Error(`bus.handshake timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    const unsubscribe = transport.onMessage((env) => {
+      if (env.kind !== MessageKind.Response || env.correlationId !== id) return;
+      clearTimeout(timer);
+      unsubscribe();
+      if (env.error) {
+        reject(new Error(`${env.error.code}: ${env.error.message}`));
+        return;
+      }
+      const p = env.payload ?? {};
+      const pluginId = String(p.pluginId ?? "");
+      const entryId = String(p.entryId ?? "");
+      const sessionId = String(p.sessionId ?? "");
+      const endpointId = String(p.endpointId ?? EndpointIds.NodeMain);
+      if (!pluginId || !entryId || !sessionId) {
+        reject(new Error("bus.handshake success response missing bound identity"));
+        return;
+      }
+      resolve({ pluginId, entryId, sessionId, endpointId });
+    });
+    transport.send(req);
+  });
+}
 export {
+  completeHandshake,
   runPlugin
 };

package/dist/dev.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Notifies a running MyTools instance that a development plugin was rebuilt.
+ * The request is retried once after a short delay when the pipe is not yet available.
+ */
+export declare function requestDevelopmentPluginRefresh(pluginId: string): Promise<void>;

package/dist/dev.mjs

@@ -0,0 +1,80 @@
+// src/developmentRefresh.ts
+import { createConnection } from "node:net";
+var DEVELOPMENT_REFRESH_PIPE_PATH = "\\\\.\\pipe\\MyTools.DevelopmentPlugins.Refresh";
+var DEFAULT_RETRY_DELAY_MS = 250;
+var DEFAULT_MAX_ATTEMPTS = 2;
+var DEFAULT_REQUEST_TIMEOUT_MS = 2e3;
+var VALID_PLUGIN_ID = /^[a-z0-9](?:[a-z0-9.-]{0,62}[a-z0-9])?$/;
+async function requestDevelopmentPluginRefreshWithOptions(pluginId, options = {}) {
+  if (!VALID_PLUGIN_ID.test(pluginId)) {
+    throw new TypeError(`Invalid MyTools plugin ID: ${pluginId}`);
+  }
+  const pipePath = options.pipePath ?? DEVELOPMENT_REFRESH_PIPE_PATH;
+  const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new RangeError("maxAttempts must be a positive integer");
+  }
+  if (!Number.isFinite(retryDelayMs) || retryDelayMs < 0) {
+    throw new RangeError("retryDelayMs must be a non-negative number");
+  }
+  if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+    throw new RangeError("requestTimeoutMs must be a positive number");
+  }
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      await sendRefreshRequest(pipePath, pluginId, requestTimeoutMs);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxAttempts) {
+        await delay(retryDelayMs);
+      }
+    }
+  }
+  throw new Error(
+    `Failed to request MyTools refresh for ${pluginId} after ${maxAttempts} attempts`,
+    { cause: lastError }
+  );
+}
+function sendRefreshRequest(pipePath, pluginId, requestTimeoutMs) {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(pipePath);
+    let settled = false;
+    let timeout;
+    const settle = (error) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      if (error) reject(error);
+      else resolve();
+    };
+    socket.once("connect", () => {
+      socket.end(`${pluginId}
+`, () => {
+        settle();
+      });
+    });
+    socket.once("error", (error) => {
+      socket.destroy();
+      settle(error);
+    });
+    timeout = setTimeout(() => {
+      socket.destroy();
+      settle(new Error(`Development refresh request timed out after ${requestTimeoutMs}ms`));
+    }, requestTimeoutMs);
+  });
+}
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+// src/dev.ts
+function requestDevelopmentPluginRefresh(pluginId) {
+  return requestDevelopmentPluginRefreshWithOptions(pluginId);
+}
+export {
+  requestDevelopmentPluginRefresh
+};

package/dist/developmentRefresh.d.ts

@@ -0,0 +1,9 @@
+export declare const DEVELOPMENT_REFRESH_PIPE_PATH = "\\\\.\\pipe\\MyTools.DevelopmentPlugins.Refresh";
+export type DevelopmentRefreshRequestOptions = {
+    pipePath?: string;
+    retryDelayMs?: number;
+    maxAttempts?: number;
+    requestTimeoutMs?: number;
+};
+/** Internal implementation with injectable timing and endpoint for protocol tests. */
+export declare function requestDevelopmentPluginRefreshWithOptions(pluginId: string, options?: DevelopmentRefreshRequestOptions): Promise<void>;

package/dist/framing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Length-prefixed framing for the v3 named-pipe transport, mirroring the C# FrameCodec/FrameDecoder.
+ * Wire format: [4-byte little-endian unsigned length][UTF-8 JSON payload].
+ *
+ * The incremental decoder handles fragmented, sticky and truncated streams, and rejects an oversize
+ * length prefix as fatal *before* allocating the payload buffer (so a malicious/buggy peer cannot
+ * force a huge allocation). After a fatal error the decoder stays dead.
+ */
+export declare const MAX_FRAME_BYTES: number;
+export declare const PREFIX_BYTES = 4;
+/** Encodes a raw payload buffer into a length-prefixed frame. */
+export declare function encodeFrame(payload: Buffer): Buffer;
+/** Encodes a UTF-8 JSON string into a length-prefixed frame. */
+export declare function encodeFrameString(json: string): Buffer;
+export interface FrameFeedResult {
+    hasFrame: boolean;
+    payload: Buffer;
+    isFatal: boolean;
+}
+/**
+ * Incremental length-prefixed frame decoder. Feed byte chunks (fragmented/sticky/partial) and get
+ * back one complete payload at a time. Leftover bytes from a chunk that contained more than one
+ * frame are buffered internally and surfaced by subsequent feeds (including an empty buffer).
+ */
+export declare class FrameDecoder {
+    private prefixBuf;
+    private prefixFilled;
+    private payload;
+    private payloadFilled;
+    private payloadLength;
+    private fatal;
+    private pending;
+    feed(chunk: Buffer): FrameFeedResult;
+    private bufferLeftover;
+    private reset;
+}

package/dist/hostEnv.d.ts

@@ -0,0 +1,9 @@
+/** Environment the host stamps onto every plugin.call payload. */
+export type PluginTheme = "light" | "dark";
+export type PluginHostEnv = {
+    locale: string;
+    fallbackLocale: string;
+    theme: PluginTheme;
+};
+export declare function asTheme(value: unknown): PluginTheme;
+export declare function asHostEnv(payload: any): PluginHostEnv;

package/dist/hotkeyKeycaps.d.ts

@@ -0,0 +1,2 @@
+/** Render a host-formatted shortcut as the same sequence of keycaps used by the desktop action bar. */
+export declare function renderHotkeyKeycaps(element: HTMLElement, hotkey: string): void;