@silverbulletmd/silverbullet 2.10.0 → 2.12.0

package/client/space_lua/runtime.ts

@@ -1,4 +1,5 @@
 import type { ASTCtx, LuaFunctionBody, NumericType } from "./ast.ts";
+import type { LuaBudget } from "./budget.ts";
 import { evalStatement } from "./eval.ts";
 import { asyncQuickSort } from "./util.ts";
 import { isPromise, rpAll } from "./rp.ts";
@@ -10,6 +11,15 @@ import type {
   LuaFunctionInfo,
 } from "../../plug-api/types/index.ts";
 
+let boundaryBudgetFactory: (() => LuaBudget) | undefined;
+export const luaFunctionInfo = Symbol("luaFunctionInfo");
+
+export function setBoundaryBudgetFactory(
+  f: (() => LuaBudget) | undefined,
+): void {
+  boundaryBudgetFactory = f;
+}
+
 export type LuaType =
   | "nil"
   | "boolean"
@@ -20,7 +30,6 @@ export type LuaType =
   | "userdata"
   | "thread";
 
-// These types are for documentation only
 export type LuaValue = any;
 export type JSValue = any;
 
@@ -31,29 +40,28 @@ export type LuaFunctionDefinition<Callback> = {
   callback: Callback;
 } & LuaFunctionDefinitionMetadata;
 
-export interface ILuaFunction {
+export type ILuaFunction = {
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue;
 
   asString(): string;
 
   info?: LuaFunctionInfo;
-}
+};
 
-export interface ILuaSettable {
+export type ILuaSettable = {
   set(
     key: LuaValue,
     value: LuaValue,
     sf?: LuaStackFrame,
     numType?: NumericType,
   ): void | Promise<void>;
-}
+};
 
-export interface ILuaGettable {
+export type ILuaGettable = {
   get(key: LuaValue, sf?: LuaStackFrame): LuaValue | Promise<LuaValue> | null;
   getNumericType?(key: LuaValue): NumericType | undefined;
-}
+};
 
-// Small helpers for type safety/readability
 export function isILuaFunction(v: unknown): v is ILuaFunction {
   return !!v && typeof (v as any).call === "function";
 }
@@ -81,11 +89,11 @@ const EMPTY_CTX = {} as ASTCtx;
 
 const MAX_TAG_LOOP = 200;
 
-// Close-stack support
 export type LuaCloseEntry = { value: LuaValue; ctx: ASTCtx };
 
 type LuaThreadState = {
   closeStack?: LuaCloseEntry[];
+  budget?: LuaBudget;
 };
 
 function isLuaNumber(v: any): boolean {
@@ -336,14 +344,10 @@ export class LuaEnv implements ILuaSettable, ILuaGettable {
   }
 
   get(name: string, _sf?: LuaStackFrame): Promise<LuaValue> | LuaValue | null {
-    // Fast path: single Map.get() instead of has() + get() for the common case
-    // where the variable exists and has a non-undefined value (null = Lua nil is fine).
     const v = this.variables.get(name);
     if (v !== undefined) {
       return v;
     }
-    // Variable set to null (Lua nil) returns null from Map.get() which is !== undefined,
-    // so it's handled above. Only fall through when the key is truly absent.
     if (this.parent) {
       return this.parent.get(name, _sf);
     }
@@ -488,39 +492,31 @@ export class LuaFunction implements ILuaFunction {
   }
 
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue {
-    // Create a new environment that chains to the captured environment
     const env = new LuaEnv(this.capturedEnv);
-    // Set _CTX to the thread local environment from the stack frame
     env.setLocal("_CTX", sf.threadLocal);
 
-    // Eval using a stack frame that knows the current function
     const sfWithFn = sf.currentFunction === this ? sf : sf.withFunction(this);
 
     const params = this.body.parameters;
     const hasVarargs = params.length > 0 && params[params.length - 1] === "...";
 
-    // Resolve args (sync-first)
     const argsRP = rpAll(args as any[]);
     const resolveArgs = (resolvedArgs: any[]) => {
       if (hasVarargs) {
-        // Variadic function: bind named params, collect rest into varargs
         const varargStart = params.length - 1;
         for (let i = 0; i < varargStart; i++) {
           env.setLocal(params[i], resolvedArgs[i] ?? null);
         }
         env.setLocal("...", new LuaMultiRes(resolvedArgs.slice(varargStart)));
       } else {
-        // Non-variadic: bind all named params directly
         for (let i = 0; i < params.length; i++) {
           env.setLocal(params[i], resolvedArgs[i] ?? null);
         }
       }
 
-      // Evaluate the function body with returnOnReturn set to true
       const r = evalStatement(this.body.block, env, sfWithFn, true);
 
       if (!isPromise(r)) {
-        // Fast path: synchronous result
         if (r === undefined) return;
         if (r && typeof r === "object" && r.ctrl === "return") {
           return mapFunctionReturnValue(r.values);
@@ -675,14 +671,10 @@ export class LuaBuiltinFunction implements ILuaFunction {
 }
 
 export class LuaTable implements ILuaSettable, ILuaGettable {
-  // To optimize the table implementation we use a combination of different data structures
   public metatable: LuaTable | null;
 
-  // When tables are used as maps, the common case is that they are string keys, so we use a simple object for that
   private stringKeys: Record<string, any>;
-  // Other keys we can support using a Map as a fallback
   private otherKeys: Map<any, any> | null;
-  // When tables are used as arrays, we use a native JavaScript array for that
   private arrayPart: any[];
 
   // Numeric type metadata at storage boundaries (lazily allocated)
@@ -719,15 +711,12 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
 
     const numVal = LuaTable.numKeyValue(key);
     if (numVal !== null) {
-      // Normalize -0 to +0
       if (isNegativeZero(numVal)) {
         return 0;
       }
-      // Integer-valued numbers normalize to integers
       if (Number.isInteger(numVal)) {
         return numVal;
       }
-      // Non-integer floats
       return numVal;
     }
     return key;
@@ -799,7 +788,6 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
       return this.stringKeys[key] !== undefined;
     }
 
-    // Fast path for plain integer keys (common in for loops)
     if (typeof key === "number") {
       if (key >= 1 && (key | 0) === key) {
         if (this.arrayPart[key - 1] !== undefined) return true;
@@ -892,7 +880,6 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
       return value.then((v) => this.rawSet(key, v, numType));
     }
 
-    // Fast path: string keys (the dominant case)
     if (typeof key === "string") {
       if (value === null || value === undefined) {
         delete this.stringKeys[key];
@@ -951,7 +938,6 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
           this.promoteIntegerKeysFromHash();
         }
 
-        // Trailing nil shrink
         if (value === null || value === undefined) {
           let n = this.arrayPart.length;
           while (n > 0) {
@@ -971,7 +957,6 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
         return;
       }
 
-      // Sparse numeric key
       if (!this.otherKeys) {
         this.otherKeys = new Map();
       }
@@ -1033,12 +1018,10 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
       );
     }
 
-    // Fast path: no metatable — skip has() check and metamethod machinery
     if (this.metatable === null) {
       return this.rawSet(key, value, numType);
     }
 
-    // Key exists — rawSet directly, no metamethod needed
     if (this.has(key)) {
       return this.rawSet(key, value, numType);
     }
@@ -1049,7 +1032,6 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
       return this.rawSet(key, value, numType);
     }
 
-    // Slow path: __newindex metamethod chain (rare)
     const errSf = sf || LuaStackFrame.lostFrame;
     const ctx = sf?.astCtx ?? EMPTY_CTX;
     const k: LuaValue = key;
@@ -1078,12 +1060,10 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
           return t.rawSet(k, v, nt);
         }
 
-        // Function metamethod: call and stop
         if (typeof mm === "function" || isILuaFunction(mm)) {
           return luaCall(mm, [t, k, v], ctx, errSf);
         }
 
-        // Table/env metamethod: forward assignment
         if (mm instanceof LuaTable || mm instanceof LuaEnv) {
           target = mm;
           continue;
@@ -1113,7 +1093,6 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
     if (typeof key === "string") {
       return this.stringKeyTypes ? this.stringKeyTypes.get(key) : undefined;
     }
-    // Fast path for plain integer keys
     if (typeof key === "number") {
       if (key >= 1 && (key | 0) === key) {
         return this.arrayTypes ? this.arrayTypes[key - 1] : undefined;
@@ -1136,7 +1115,6 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
       return this.stringKeys[key];
     }
 
-    // Fast path for plain integer keys (common in for loops)
     if (typeof key === "number") {
       if (key >= 1 && (key | 0) === key) {
         const v = this.arrayPart[key - 1];
@@ -1144,7 +1122,6 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
         if (this.otherKeys) return this.otherKeys.get(key);
         return undefined;
       }
-      // Non-integer or zero/negative number keys
       if (this.otherKeys) return this.otherKeys.get(key);
       return undefined;
     }
@@ -1178,7 +1155,6 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
   }
 
   get(key: LuaValue, sf?: LuaStackFrame): LuaValue | Promise<LuaValue> | null {
-    // Fast path: no metatable means rawGet is the final answer (most tables in SilverBullet)
     if (this.metatable === null) {
       const raw = this.rawGet(key);
       return raw !== undefined ? raw : null;
@@ -1212,11 +1188,9 @@ export class LuaTable implements ILuaSettable, ILuaGettable {
         result[k] = luaValueToJS(this.stringKeys[k], sf);
       }
     }
-    // Include array part with 1-based keys
     for (let i = 0; i < this.arrayPart.length; i++) {
       result[i + 1] = luaValueToJS(this.arrayPart[i], sf);
     }
-    // Include other keys
     if (this.otherKeys) {
       for (const [key, val] of this.otherKeys) {
         result[key] = luaValueToJS(val, sf);
@@ -1299,14 +1273,12 @@ export function luaIndexValue(
   let t: LuaValue = value;
 
   for (let loop = 0; loop < MAX_TAG_LOOP; loop++) {
-    // Primitive get when table
     if (t instanceof LuaTable) {
       const raw = t.rawGet(key);
       if (raw !== undefined) {
         if (isSqlNull(raw)) return null;
         return raw;
       }
-      // If no metatable, raw miss => nil
       if (t.metatable === null) {
         return null;
       }
@@ -1328,18 +1300,15 @@ export function luaIndexValue(
       );
     }
 
-    // Function metamethod
     if (typeof mm === "function" || isILuaFunction(mm)) {
       return luaCall(mm, [t, key], ctx, errSf);
     }
 
-    // Table/metatable delegation: repeat with mm as new "t"
     if (mm instanceof LuaTable || mm instanceof LuaEnv) {
       t = mm;
       continue;
     }
 
-    // Bad metamethod type: make it a Lua-like type error
     const ty = luaTypeOf(mm) as any as string;
     throw new LuaRuntimeError(
       `attempt to index a ${ty} value`,
@@ -1413,11 +1382,9 @@ export function luaGet(
   if (isTaggedFloat(key)) {
     return (obj as any[])[key.value - 1] ?? null;
   }
-  // Native JS object
   const k = toNumKey(key);
   const val = (obj as Record<string | number, any>)[k];
   if (typeof val === "function") {
-    // Automatically bind the function to the object
     return val.bind(obj);
   }
   if (val === undefined) {
@@ -1438,7 +1405,6 @@ export function luaLen(
     return obj.length;
   }
   if (obj instanceof LuaTable) {
-    // Check __len metamethod unless raw access is requested
     if (!raw) {
       const mt = getMetatable(obj, sf || LuaStackFrame.lostFrame);
       const mm = mt ? mt.rawGet("__len") : null;
@@ -1473,7 +1439,6 @@ export function luaCall(
     );
   }
 
-  // Fast path: native JS function
   if (typeof callee === "function") {
     const baseSf = sf || LuaStackFrame.lostFrame;
     const len = args.length;
@@ -1494,7 +1459,6 @@ export function luaCall(
     return (callee as (...a: any[]) => any)(...args);
   }
 
-  // Lua table: may be callable via __call metamethod
   if (callee instanceof LuaTable) {
     const metatable = getMetatable(callee, sf);
 
@@ -1525,7 +1489,6 @@ export function luaCall(
     }
   }
 
-  // ILuaFunction (LuaFunction/LuaBuiltinFunction/LuaNativeJSFunction/etc.)
   if (isILuaFunction(callee)) {
     // Fast path for builtins: skip withFunction, defer withCtx
     if (callee instanceof LuaBuiltinFunction) {
@@ -1550,7 +1513,6 @@ export function luaCall(
 }
 
 export function luaEquals(a: any, b: any): boolean {
-  // Normalize nil variants (null, undefined, SQL NULL) to null
   const an =
     a === null || a === undefined || isSqlNull(a)
       ? null
@@ -1630,7 +1592,6 @@ export class LuaRuntimeError extends Error {
       if (!ctx || !ctx.from || !ctx.to) {
         break;
       }
-      // Find the line and column
       let line = 1;
       let column = 0;
       let lastNewline = -1;
@@ -1644,7 +1605,6 @@ export class LuaRuntimeError extends Error {
         }
       }
 
-      // Get the full line of code for context
       const lineStart = lastNewline + 1;
       const lineEnd = code.indexOf("\n", ctx.from);
       const codeLine = code.substring(
@@ -1652,7 +1612,6 @@ export class LuaRuntimeError extends Error {
         lineEnd === -1 ? undefined : lineEnd,
       );
 
-      // Add position indicator
       const pointer = `${" ".repeat(column)}^`;
 
       traceStr +=
@@ -1704,12 +1663,10 @@ export function luaToString(
     return luaFormatNumber(value);
   }
 
-  // Check for circular references
   if (typeof value === "object" && visited.has(value)) {
     return "<circular reference>";
   }
   if ((value as any).toStringAsync) {
-    // Add to visited before recursing
     visited.add(value);
     return (value as any).toStringAsync();
   }
@@ -1721,15 +1678,12 @@ export function luaToString(
     // Don't recurse into the function body, just show the function signature
     return `<lua-function (${value.body.parameters.join(", ")})>`;
   }
-  // Handle plain JavaScript objects in a Lua-like format
   if (typeof value === "object") {
-    // Add to visited before recursing
     visited.add(value);
     return (async () => {
       let result = "{";
       let first = true;
 
-      // Handle arrays
       if (Array.isArray(value)) {
         for (const val of value) {
           if (first) {
@@ -1737,14 +1691,12 @@ export function luaToString(
           } else {
             result += ", ";
           }
-          // Recursively stringify the value, passing the visited set
           const strVal = await luaToString(val, visited);
           result += strVal;
         }
         return `${result}}`;
       }
 
-      // Handle objects
       for (const [key, val] of Object.entries(value)) {
         if (first) {
           first = false;
@@ -1756,7 +1708,6 @@ export function luaToString(
         } else {
           result += `["${key}"] = `;
         }
-        // Recursively stringify the value, passing the visited set
         const strVal = await luaToString(val, visited);
         result += strVal;
       }
@@ -1777,7 +1728,6 @@ export function luaFormatNumber(n: number, kind?: "int" | "float"): string {
   if (n === 0) {
     return 1 / n === -Infinity ? "-0.0" : "0.0";
   }
-  // Delegate to luaFormat for `%.14g`
   const s = luaFormat("%.14g", n);
   // Guarantee `.01 suffix for integer-valued floats
   if (s.indexOf(".") === -1 && s.indexOf("e") === -1) {
@@ -1834,7 +1784,6 @@ export function jsToLuaValue(value: any): any {
     return value;
   }
   if (Array.isArray(value) && "index" in value && "input" in value) {
-    // This is a RegExpMatchArray
     const regexMatch = value as RegExpMatchArray;
     const regexMatchTable = new LuaTable();
     for (let i = 0; i < regexMatch.length; i++) {
@@ -1865,7 +1814,6 @@ export function jsToLuaValue(value: any): any {
   return value;
 }
 
-// Inverse of jsToLuaValue
 export function luaValueToJS(value: any, sf: LuaStackFrame): any {
   if (isPromise(value)) {
     return (value as Promise<any>).then((v) => luaValueToJS(v, sf));
@@ -1878,16 +1826,55 @@ export function luaValueToJS(value: any, sf: LuaStackFrame): any {
     value instanceof LuaFunction ||
     value instanceof LuaBuiltinFunction
   ) {
-    return (...args: any[]) => {
-      const jsArgs = rpAll(args.map((v) => luaValueToJS(v, sf)));
-      if (isPromise(jsArgs)) {
-        return luaValueToJS(
-          jsArgs.then((jsArgs) => (value as ILuaFunction).call(sf, ...jsArgs)),
-          sf,
-        );
+    const fn = (...args: any[]) => {
+      // A converted closure captures one frame forever; without a fresh
+      // thread state per call, every invocation would share one budget.
+      const boundaryBudget = boundaryBudgetFactory?.();
+      const callSf =
+        boundaryBudget === undefined
+          ? sf
+          : new LuaStackFrame(sf.threadLocal, sf.astCtx, undefined, undefined, {
+              closeStack: undefined,
+              budget: boundaryBudget,
+            });
+      // Marks this call's own budget (if any) done, so a Stop click that
+      // arrives after the call has already returned is a no-op rather than
+      // quarantining/disabling something that isn't running anymore.
+      const markFinished = () => {
+        if (boundaryBudget !== undefined) {
+          boundaryBudget.finished = true;
+        }
+      };
+      try {
+        const jsArgs = rpAll(args.map((v) => luaValueToJS(v, callSf)));
+        if (isPromise(jsArgs)) {
+          return luaValueToJS(
+            jsArgs
+              .then((jsArgs) => (value as ILuaFunction).call(callSf, ...jsArgs))
+              .finally(markFinished),
+            callSf,
+          );
+        }
+        const result = (value as ILuaFunction).call(callSf, ...jsArgs);
+        if (isPromise(result)) {
+          return luaValueToJS(
+            (result as Promise<any>).finally(markFinished),
+            callSf,
+          );
+        }
+        markFinished();
+        return luaValueToJS(result, callSf);
+      } catch (e) {
+        markFinished();
+        throw e;
       }
-      return luaValueToJS((value as ILuaFunction).call(sf, ...jsArgs), sf);
     };
+    if (value instanceof LuaFunction) {
+      (fn as typeof fn & { [luaFunctionInfo]: LuaFunctionInfo })[
+        luaFunctionInfo
+      ] = value.info;
+    }
+    return fn;
   }
   if (isTaggedFloat(value)) {
     return value.value;

package/client/space_lua/stdlib/format.ts

@@ -56,7 +56,6 @@ function parseSpec(
     }
   }
 
-  // Parse width
   let width = 0;
   if (i < len && fmt.charCodeAt(i) === 42) {
     // '*'
@@ -69,7 +68,6 @@ function parseSpec(
     }
   }
 
-  // Parse precision
   let hasPrec = false;
   let prec = 0;
   if (i < len && fmt.charCodeAt(i) === 46) {
@@ -183,7 +181,6 @@ function formatInt(n: number, spec: FormatSpec): string {
 
   if (upper) digits = digits.toUpperCase();
 
-  // Precision
   if (spec.hasPrec) {
     if (spec.prec === 0 && v === 0) {
       digits = "";
@@ -192,7 +189,6 @@ function formatInt(n: number, spec: FormatSpec): string {
     }
   }
 
-  // Alt flag
   let prefix = "";
   if (spec.flags & FLAG_HASH) {
     if (base === 8 && (digits.length === 0 || digits.charCodeAt(0) !== 48)) {
@@ -277,7 +273,6 @@ function formatFloat(n: number, spec: FormatSpec): string {
   // Alt flag for 'f'/'e': ensure decimal point exists
   if (spec.flags & FLAG_HASH && lower !== 103) {
     if (body.indexOf(".") === -1) {
-      // Insert dot before 'e' if present, else append
       const eIdx = body.indexOf("e");
       const EIdx = body.indexOf("E");
       const expIdx = eIdx !== -1 ? eIdx : EIdx;
@@ -348,7 +343,6 @@ function stripTrailingZerosG(s: string): string {
     // '0'
     end--;
   }
-  // Remove dot if nothing after it
   if (end === dotIdx + 1) {
     end = dotIdx;
   }
@@ -452,13 +446,11 @@ function hexFloatBody(abs: number, spec: FormatSpec): string {
   let mantBits: bigint;
 
   if (biasedExp === 0) {
-    // Subnormal
     if (frac === 0n) return "0x0p+0";
     const shift = 52 - bitLength(frac) + 1;
     mantBits = frac << BigInt(shift);
     exponent = -1022 - shift;
   } else {
-    // Normal
     exponent = biasedExp - 1023;
     mantBits = frac | (1n << 52n);
   }
@@ -680,8 +672,6 @@ export function luaFormat(fmt: string, ...args: any[]): string {
   while (i < len) {
     const c = fmt.charCodeAt(i);
     if (c !== 37) {
-      // not '%'
-      // Fast path: scan for next '%' or end
       let j = i + 1;
       while (j < len && fmt.charCodeAt(j) !== 37) j++;
       out += fmt.slice(i, j);
@@ -689,7 +679,6 @@ export function luaFormat(fmt: string, ...args: any[]): string {
       continue;
     }
 
-    // '%' found
     i++;
     if (i >= len) {
       throw new Error("invalid format (ends with '%')");
@@ -705,7 +694,6 @@ export function luaFormat(fmt: string, ...args: any[]): string {
     const { spec, end } = parseSpec(fmt, i);
     i = end + 1;
 
-    // Resolve `*` width and precision from args
     let width = spec.width;
     if (width === -1) {
       width = Number(args[ai++]) || 0;

package/client/space_lua/stdlib/js.ts

@@ -41,7 +41,6 @@ export const jsApi = new LuaTable({
   import: new LuaBuiltinFunction({
     callback: async (_sf, url) => {
       let m = await import(url);
-      // Unwrap default if it exists
       if (Object.keys(m).length === 1 && m.default) {
         m = m.default;
       }
@@ -179,6 +178,5 @@ export const jsApi = new LuaTable({
     examples: [{ code: "print(js.stringify({1, 2, 3})) -- [1,2,3]" }],
   }),
 
-  // Expose the global window object
   window: globalThis,
 });

package/client/space_lua/stdlib/load.ts

@@ -16,7 +16,6 @@ export function luaLoad(code: LuaValue, sf: LuaStackFrame): LuaValue {
     const block = parseBlock(s, sf.astCtx || {});
     const globalEnvMaybe = sf.threadLocal.get("_GLOBAL");
 
-    // Be vocal when no _GLOBAL is set
     if (!globalEnvMaybe) {
       console.warn("load() called without _GLOBAL in thread-local environment");
       return new LuaMultiRes([null, "Global environment not set"]);

package/client/space_lua/stdlib/math.ts

@@ -18,7 +18,6 @@ function untagNumber(x: any): number {
 }
 
 export const mathApi = new LuaTable({
-  // math constants
   huge: 1 / 0,
   pi: Math.PI,
 
@@ -145,7 +144,6 @@ export const mathApi = new LuaTable({
     ],
   }),
 
-  // Basic functions
   abs: new LuaBuiltinFunction({
     callback: (_sf, x: number) => Math.abs(untagNumber(x)),
     description: "Returns the absolute value of `x`.",
@@ -177,7 +175,6 @@ export const mathApi = new LuaTable({
     returns: [{ type: "number" }],
   }),
 
-  // Rounding and remainder
   fmod: new LuaBuiltinFunction({
     callback: (_sf, x: number, y: number) => untagNumber(x) % untagNumber(y),
     description:
@@ -248,7 +245,6 @@ export const mathApi = new LuaTable({
     returns: [{ type: "number" }],
   }),
 
-  // Power and logarithms
   exp: new LuaBuiltinFunction({
     callback: (_sf, x: number) => Math.exp(untagNumber(x)),
     description: "Returns `e` raised to `x`.",
@@ -289,7 +285,6 @@ export const mathApi = new LuaTable({
     returns: [{ type: "number" }],
   }),
 
-  // Trigonometric functions
   cos: new LuaBuiltinFunction({
     callback: (_sf, x: number) => Math.cos(untagNumber(x)),
     description: "Returns the cosine of `x` radians.",
@@ -359,7 +354,6 @@ export const mathApi = new LuaTable({
     deprecated: "Retained for compatibility with older Lua versions.",
   }),
 
-  // Additional utility
   deg: new LuaBuiltinFunction({
     callback: (_sf, x: number) => (untagNumber(x) * 180) / Math.PI,
     description: "Converts an angle from radians to degrees.",
@@ -386,7 +380,6 @@ export const mathApi = new LuaTable({
     examples: [{ code: "print(math.ult(2, 3)) -- true" }],
   }),
 
-  // Keep the cosineSimilarity utility function
   cosineSimilarity: new LuaBuiltinFunction({
     callback: (sf, vecA: LuaTable | number[], vecB: LuaTable | number[]) => {
       if (vecA instanceof LuaTable) {