@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/client/plugos/syscalls/event.ts

@@ -9,25 +9,56 @@ export function eventSyscalls(
   client: Client,
 ): SysCallMapping {
   return {
-    "event.dispatch": (_ctx, eventName: string, data: any) => {
-      return eventHook.dispatchEvent(eventName, data);
+    "event.dispatch": {
+      callback: (_ctx, eventName: string, data: any) => {
+        return eventHook.dispatchEvent(eventName, data);
+      },
+      description:
+        "Dispatches an event and collects responses from its listeners.",
+      parameters: [
+        { name: "eventName", type: "string", description: "Event name." },
+        { name: "data", description: "Event payload." },
+      ],
+      returns: [{ type: "table", description: "Listener responses." }],
+      examples: [
+        {
+          code: 'local responses = event.dispatch("data.request", {id = 123})',
+        },
+      ],
     },
-    "event.listEvents": () => {
-      return eventHook.listEvents();
+    "event.listEvents": {
+      callback: () => {
+        return eventHook.listEvents();
+      },
+      description: "Lists all event names that currently have listeners.",
+      returns: [{ type: "table", description: "Registered event names." }],
     },
     /**
      * Define a Lua event listener
      */
-    "event.listen": (_ctx, def: EventSubscription) => {
-      // console.log("Registering Lua event listener: ", def.name);
-      client.config.insert(
-        ["eventListeners", def.name],
-        async (...args: any[]) => {
-          // Convert return value to JS
-          const val = await def.run(...args);
-          return luaValueToJS(val, LuaStackFrame.lostFrame);
+    "event.listen": {
+      callback: (_ctx, def: EventSubscription) => {
+        client.config.insert(
+          ["eventListeners", def.name],
+          async (...args: any[]) => {
+            const val = await def.run(...args);
+            return luaValueToJS(val, LuaStackFrame.lostFrame);
+          },
+        );
+      },
+      description: "Registers a Space Lua listener on the event bus.",
+      parameters: [
+        {
+          name: "listener",
+          type: "table",
+          description: "Listener definition with name and run callback.",
+        },
+      ],
+      examples: [
+        {
+          code: 'event.listen { name = "my-event", run = function(e) print(e.data) end }',
         },
-      );
+      ],
     },
   };
 }

package/client/plugos/syscalls/fetch.ts

@@ -15,98 +15,135 @@ import { fsEndpoint } from "../../spaces/constants.ts";
 export function sandboxFetchSyscalls(client: Client): SysCallMapping {
   return {
     // For use in Lua
-    "http.request": async (
-      _ctx,
-      url: string,
-      options: ProxyFetchRequest = {},
-    ): Promise<ProxyFetchResponse> => {
-      console.warn("Deprecated: use net.proxyFetch() instead");
-      // JSONify any non-serializable body
-      if (
-        options?.body &&
-        typeof options.body !== "string" &&
-        !(options.body instanceof Uint8Array)
-      ) {
-        options.body = JSON.stringify(options.body);
-      }
-      const fetchOptions = options
-        ? {
-            method: options.method,
-            headers: {} as Record<string, string>,
-            body: options.body,
-          }
-        : {};
+    "http.request": {
+      callback: async (
+        _ctx,
+        url: string,
+        options: ProxyFetchRequest = {},
+      ): Promise<ProxyFetchResponse> => {
+        console.warn("Deprecated: use net.proxyFetch() instead");
+        if (
+          options?.body &&
+          typeof options.body !== "string" &&
+          !(options.body instanceof Uint8Array)
+        ) {
+          options.body = JSON.stringify(options.body);
+        }
+        const fetchOptions = options
+          ? {
+              method: options.method,
+              headers: {} as Record<string, string>,
+              body: options.body,
+            }
+          : {};
 
-      fetchOptions.headers = buildProxyHeaders(options?.headers);
+        fetchOptions.headers = buildProxyHeaders(options?.headers);
 
-      const resp = await client.httpSpacePrimitives.authenticatedFetch(
-        buildProxyUrl(client, url),
-        fetchOptions,
-      );
-      // Do sensible things with the body based on the content type
-      // Read as ArrayBuffer first to safely handle empty responses (e.g.
-      // PUT/DELETE returning 204 with Content-Type: application/json).
-      // resp.arrayBuffer() never throws on an empty body, whereas
-      // resp.json() would throw a SyntaxError.
-      const rawBytes = new Uint8Array(await resp.arrayBuffer());
-      let body: any;
-      const contentTypeHeader =
-        options.responseEncoding ||
-        resp.headers.get("x-proxy-header-content-type");
-      const statusCode = +(resp.headers.get("x-proxy-status-code") || "200");
-      if (rawBytes.length === 0) {
-        body = null;
-      } else if (contentTypeHeader?.startsWith("application/json")) {
-        body = JSON.parse(new TextDecoder().decode(rawBytes));
-      } else if (
-        contentTypeHeader?.startsWith("application/xml") ||
-        contentTypeHeader?.startsWith("text/")
-      ) {
-        body = new TextDecoder().decode(rawBytes);
-      } else {
-        body = rawBytes;
-      }
-      return {
-        ok: resp.ok,
-        status: statusCode,
-        headers: extractProxyHeaders(resp.headers),
-        body: body,
-      };
+        const resp = await client.httpSpacePrimitives.authenticatedFetch(
+          buildProxyUrl(client, url),
+          fetchOptions,
+        );
+        // Read as ArrayBuffer first to safely handle empty responses (e.g.
+        // PUT/DELETE returning 204 with Content-Type: application/json).
+        // resp.arrayBuffer() never throws on an empty body, whereas
+        // resp.json() would throw a SyntaxError.
+        const rawBytes = new Uint8Array(await resp.arrayBuffer());
+        let body: any;
+        const contentTypeHeader =
+          options.responseEncoding ||
+          resp.headers.get("x-proxy-header-content-type");
+        const statusCode = +(resp.headers.get("x-proxy-status-code") || "200");
+        if (rawBytes.length === 0) {
+          body = null;
+        } else if (contentTypeHeader?.startsWith("application/json")) {
+          body = JSON.parse(new TextDecoder().decode(rawBytes));
+        } else if (
+          contentTypeHeader?.startsWith("application/xml") ||
+          contentTypeHeader?.startsWith("text/")
+        ) {
+          body = new TextDecoder().decode(rawBytes);
+        } else {
+          body = rawBytes;
+        }
+        return {
+          ok: resp.ok,
+          status: statusCode,
+          headers: extractProxyHeaders(resp.headers),
+          body: body,
+        };
+      },
+      description:
+        "Performs an authenticated HTTP request through the server proxy.",
+      parameters: [
+        { name: "url", type: "string", description: "Target URL." },
+        {
+          name: "options",
+          type: "table",
+          description: "Method, headers, body, and response encoding.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "Status, headers, and decoded response body.",
+        },
+      ],
+      deprecated: "Use net.proxyFetch instead.",
+      see: "API/net#net.proxyFetch(url, options?)",
     },
-    "sandboxFetch.fetch": async (
-      _ctx,
-      url: string,
-      options?: ProxyFetchRequest64,
-    ): Promise<ProxyFetchResponse64> => {
-      // console.log("Got sandbox fetch ", url, op);
-      const fetchOptions = options
-        ? {
-            method: options.method,
-            headers: options.headers,
-            body: options.base64Body && base64Decode(options.base64Body),
-          }
-        : {};
-      fetchOptions.headers = buildProxyHeaders(options?.headers);
-      const resp = await client.httpSpacePrimitives.authenticatedFetch(
-        buildProxyUrl(client, url),
-        // Casting to any due to TypeScript fetch type limitations
-        fetchOptions as any,
-      );
-      const statusCode = +(resp.headers.get("x-proxy-status-code") || "200");
-      const body = await resp.arrayBuffer();
-      return {
-        ok: resp.ok,
-        status: statusCode,
-        headers: extractProxyHeaders(resp.headers),
-        base64Body: base64Encode(new Uint8Array(body)),
-      };
+    "sandboxFetch.fetch": {
+      callback: async (
+        _ctx,
+        url: string,
+        options?: ProxyFetchRequest64,
+      ): Promise<ProxyFetchResponse64> => {
+        const fetchOptions = options
+          ? {
+              method: options.method,
+              headers: options.headers,
+              body: options.base64Body && base64Decode(options.base64Body),
+            }
+          : {};
+        fetchOptions.headers = buildProxyHeaders(options?.headers);
+        const resp = await client.httpSpacePrimitives.authenticatedFetch(
+          buildProxyUrl(client, url),
+          // Casting to any due to TypeScript fetch type limitations
+          fetchOptions as any,
+        );
+        const statusCode = +(resp.headers.get("x-proxy-status-code") || "200");
+        const body = await resp.arrayBuffer();
+        return {
+          ok: resp.ok,
+          status: statusCode,
+          headers: extractProxyHeaders(resp.headers),
+          base64Body: base64Encode(new Uint8Array(body)),
+        };
+      },
+      description:
+        "Performs an authenticated proxied fetch for a plug sandbox.",
+      parameters: [
+        { name: "url", type: "string", description: "Target URL." },
+        {
+          name: "options",
+          type: "table",
+          description: "Method, headers, and base64-encoded body.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "Status, headers, and base64-encoded response body.",
+        },
+      ],
+      see: "API/http",
     },
   };
 }
 
 function buildProxyUrl(client: Client, url: string) {
   url = url.replace(/^https?:\/\//, "");
-  // Strip off the /.fs and replace with /.proxy
   return (
     client.httpSpacePrimitives.url.slice(0, -fsEndpoint.length) +
     "/.proxy/" +

package/client/plugos/syscalls/icon.ts

@@ -0,0 +1,46 @@
+import { resolveFeatherIcons } from "../../lib/feather_icons.ts";
+import type { SysCallMapping } from "../system.ts";
+
+export function iconSyscalls(): SysCallMapping {
+  return {
+    "icon.feather": {
+      callback: (_ctx, name: string): string | null => {
+        if (!name) return null;
+        return resolveFeatherIcons([name])[name] ?? null;
+      },
+      description:
+        "Renders a Feather icon to SVG markup by name, or nil when the name isn't a Feather icon. The markup carries no color of its own (`currentColor`) and a default 24x24 size, both of which CSS at the injection site can override.",
+      parameters: [
+        {
+          name: "name",
+          type: "string",
+          description: "A Feather icon name, e.g. `trash-2`.",
+        },
+      ],
+      returns: [
+        {
+          type: "string",
+          description: "The icon's SVG markup, or nil when unknown.",
+        },
+      ],
+      examples: [{ code: 'local lock = icon.feather("lock")' }],
+    },
+    "icon.resolveFeather": {
+      callback: (_ctx, names: string[]): Record<string, string> => {
+        return resolveFeatherIcons(names ?? []);
+      },
+      description:
+        "Renders a batch of Feather icons to SVG markup in one round trip, so panels can show icons without bundling the icon set themselves. Unknown names are omitted from the result. The markup carries no color of its own (`currentColor`) and a default 24x24 size, both of which CSS at the injection site can override.",
+      parameters: [
+        {
+          name: "names",
+          type: "table",
+          description: "Feather icon names, e.g. `trash-2`.",
+        },
+      ],
+      returns: [
+        { type: "table", description: "Map of icon name to SVG markup." },
+      ],
+    },
+  };
+}