js-confuser-vm 0.1.0 → 0.1.1

package/dist/disassembler.js

@@ -0,0 +1,317 @@
+/**
+ * Simple bytecode disassembler for debugging.
+ *
+ * Takes the bytecode debug comment block (as generated by the compiler)
+ * and produces a flat pseudo-code listing with registers, gotos, and labels.
+ */
+
+// Regex to match a single instruction line from the debug comment block.
+// Groups: raw array, opcode name, annotation (rest of line after opcode name)
+const INSTR_RE = /^\s*\/\/\s*\[([^\]]+)\],\s+(\w+)\s+(.*?)$/;
+
+// Label line: // label_name:
+const LABEL_RE = /^\s*\/\/\s*(\w+):$/;
+function parseBlock(commentBlock) {
+  const lines = [];
+  for (const raw of commentBlock.split("\n")) {
+    const trimmed = raw.trim();
+    if (!trimmed || !trimmed.startsWith("//")) continue;
+    const instrMatch = trimmed.match(INSTR_RE);
+    if (instrMatch) {
+      const nums = instrMatch[1].split(",").map(s => parseInt(s.trim(), 10));
+      lines.push({
+        kind: "instr",
+        instr: {
+          raw: nums,
+          opName: instrMatch[2],
+          annotation: instrMatch[3].trim()
+        }
+      });
+      continue;
+    }
+    const labelMatch = trimmed.match(LABEL_RE);
+    if (labelMatch) {
+      lines.push({
+        kind: "label",
+        label: labelMatch[1]
+      });
+    }
+  }
+  return lines;
+}
+
+// Extract a label name from an annotation string like "[4, while_exit_8]" or "while_top_7"
+// Also handles "PC=fn_1_1" for closures
+function extractLabel(annotation) {
+  // Strip trailing source location info like "3:4-7:5"
+  const stripped = annotation.replace(/\s+\d+:\d+-\d+:\d+\s*$/, "").trim();
+  const bracketMatch = stripped.match(/\[\d+,\s*(\w+)\]/);
+  if (bracketMatch) return bracketMatch[1];
+  const pcMatch = stripped.match(/\bPC=(\w+)/);
+  if (pcMatch) return pcMatch[1];
+  const gotoMatch = stripped.match(/\bgoto\s+(\w+)/);
+  if (gotoMatch) return gotoMatch[1];
+
+  // Bare label at end: last whitespace-separated token
+  const lastToken = stripped.split(/\s+/).pop();
+  if (lastToken && /^[a-zA-Z_]\w*$/.test(lastToken)) return lastToken;
+  return null;
+}
+const ARITH_SYMBOLS = {
+  ADD: "+",
+  SUB: "-",
+  MUL: "*",
+  DIV: "/",
+  MOD: "%",
+  BAND: "&",
+  BOR: "|",
+  BXOR: "^",
+  SHL: "<<",
+  SHR: ">>",
+  USHR: ">>>"
+};
+const CMP_SYMBOLS = {
+  LT: "<",
+  GT: ">",
+  LTE: "<=",
+  GTE: ">=",
+  EQ: "===",
+  NEQ: "!==",
+  LOOSE_EQ: "==",
+  LOOSE_NEQ: "!=",
+  IN: "in",
+  INSTANCEOF: "instanceof"
+};
+const UNARY_SYMBOLS = {
+  UNARY_NEG: "-",
+  UNARY_POS: "+",
+  UNARY_NOT: "!",
+  UNARY_BITNOT: "~"
+};
+
+// Extract value from annotation like 'reg[1] = "Hello"' or 'reg[1] = 42'
+function extractConstValue(annotation) {
+  const m = annotation.match(/=\s*(.+?)(?:\s+\d+:\d+-\d+:\d+)?$/);
+  return m ? m[1].trim() : null;
+}
+function disassembleInstr(instr) {
+  const {
+    raw,
+    opName,
+    annotation
+  } = instr;
+  const r = i => `r${raw[i]}`;
+  switch (opName) {
+    case "LOAD_CONST":
+      {
+        const val = extractConstValue(annotation);
+        return `${r(1)} = ${val ?? `const[${raw[2]}]`}`;
+      }
+    case "LOAD_INT":
+      return `${r(1)} = ${raw[2]}`;
+    case "LOAD_GLOBAL":
+      {
+        const val = extractConstValue(annotation);
+        return `${r(1)} = ${val ?? `global[${raw[2]}]`}`;
+      }
+    case "LOAD_UPVALUE":
+      return `${r(1)} = upvalue[${raw[2]}]`;
+    case "LOAD_THIS":
+      return `${r(1)} = this`;
+    case "MOVE":
+      return `${r(1)} = ${r(2)}`;
+    case "STORE_GLOBAL":
+      {
+        // annotation: globals[name] = reg[src]
+        const val = extractConstValue(annotation);
+        return `global[${val ?? raw[1]}] = ${r(2)}`;
+      }
+    case "STORE_UPVALUE":
+      return `upvalue[${raw[1]}] = ${r(2)}`;
+    case "GET_PROP":
+      return `${r(1)} = ${r(2)}[${r(3)}]`;
+    case "SET_PROP":
+      return `${r(1)}[${r(2)}] = ${r(3)}`;
+    case "DELETE_PROP":
+      return `${r(1)} = delete ${r(2)}[${r(3)}]`;
+
+    // Arithmetic / bitwise
+    case "ADD":
+    case "SUB":
+    case "MUL":
+    case "DIV":
+    case "MOD":
+    case "BAND":
+    case "BOR":
+    case "BXOR":
+    case "SHL":
+    case "SHR":
+    case "USHR":
+      return `${r(1)} = ${r(2)} ${ARITH_SYMBOLS[opName]} ${r(3)}`;
+
+    // Comparison
+    case "LT":
+    case "GT":
+    case "LTE":
+    case "GTE":
+    case "EQ":
+    case "NEQ":
+    case "LOOSE_EQ":
+    case "LOOSE_NEQ":
+    case "IN":
+    case "INSTANCEOF":
+      return `${r(1)} = ${r(2)} ${CMP_SYMBOLS[opName]} ${r(3)}`;
+
+    // Unary
+    case "UNARY_NEG":
+    case "UNARY_POS":
+    case "UNARY_NOT":
+    case "UNARY_BITNOT":
+      return `${r(1)} = ${UNARY_SYMBOLS[opName]}${r(2)}`;
+    case "TYPEOF":
+      return `${r(1)} = typeof ${r(2)}`;
+    case "VOID":
+      return `${r(1)} = void ${r(2)}`;
+    case "TYPEOF_SAFE":
+      {
+        const val = extractConstValue(annotation);
+        return `${r(1)} = typeof ${val ?? `safe[${raw[2]}]`}`;
+      }
+
+    // Control flow
+    case "JUMP":
+      {
+        const label = extractLabel(annotation);
+        return `goto: ${label ?? `pc:${raw[1]}`}`;
+      }
+    case "JUMP_IF_FALSE":
+      {
+        const label = extractLabel(annotation);
+        return `if (!${r(1)}) goto: ${label ?? `pc:${raw[2]}`}`;
+      }
+    case "JUMP_IF_TRUE":
+      {
+        const label = extractLabel(annotation);
+        return `if (${r(1)}) goto: ${label ?? `pc:${raw[2]}`}`;
+      }
+    case "JUMP_REG":
+      return `goto: *${r(1)}`;
+
+    // Calls
+    case "CALL":
+      {
+        const dst = r(1);
+        const callee = r(2);
+        const argc = raw[3];
+        const args = raw.slice(4, 4 + argc).map((_, i) => `r${raw[4 + i]}`);
+        return `${dst} = ${callee}(${args.join(", ")})`;
+      }
+    case "CALL_METHOD":
+      {
+        const dst = r(1);
+        const recv = r(2);
+        const callee = r(3);
+        const argc = raw[4];
+        const args = raw.slice(5, 5 + argc).map((_, i) => `r${raw[5 + i]}`);
+        return `${dst} = ${callee}.call(${recv}, ${args.join(", ")})`;
+      }
+    case "NEW":
+      {
+        const dst = r(1);
+        const callee = r(2);
+        const argc = raw[3];
+        const args = raw.slice(4, 4 + argc).map((_, i) => `r${raw[4 + i]}`);
+        return `${dst} = new ${callee}(${args.join(", ")})`;
+      }
+    case "RETURN":
+      return `return ${r(1)}`;
+    case "THROW":
+      return `throw ${r(1)}`;
+
+    // Closures
+    case "MAKE_CLOSURE":
+      {
+        const dst = r(1);
+        const startPc = raw[2];
+        const paramCount = raw[3];
+        const regCount = raw[4];
+        const uvCount = raw[5];
+        const label = extractLabel(annotation);
+        const uvParts = [];
+        for (let i = 0; i < uvCount; i++) {
+          const isLocal = raw[6 + i * 2];
+          const idx = raw[6 + i * 2 + 1];
+          uvParts.push(isLocal ? `local[${idx}]` : `uv[${idx}]`);
+        }
+        const uvStr = uvCount > 0 ? `, upvalues=[${uvParts.join(", ")}]` : "";
+        return `${dst} = MakeClosure(${label ?? `pc:${startPc}`}, params=${paramCount}, regs=${regCount}${uvStr})`;
+      }
+
+    // Collections
+    case "BUILD_ARRAY":
+      {
+        const dst = r(1);
+        const count = raw[2];
+        const elems = raw.slice(3, 3 + count).map((_, i) => `r${raw[3 + i]}`);
+        return `${dst} = [${elems.join(", ")}]`;
+      }
+    case "BUILD_OBJECT":
+      {
+        const dst = r(1);
+        const pairCount = raw[2];
+        const pairs = [];
+        for (let i = 0; i < pairCount; i++) {
+          pairs.push(`[r${raw[3 + i * 2]}]: r${raw[4 + i * 2]}`);
+        }
+        return `${dst} = {${pairs.join(", ")}}`;
+      }
+
+    // Property definitions
+    case "DEFINE_GETTER":
+      return `Object.defineGetter(${r(1)}, ${r(2)}, ${r(3)})`;
+    case "DEFINE_SETTER":
+      return `Object.defineSetter(${r(1)}, ${r(2)}, ${r(3)})`;
+
+    // For-in
+    case "FOR_IN_SETUP":
+      return `${r(1)} = ForInSetup(${r(2)})`;
+    case "FOR_IN_NEXT":
+      {
+        const label = extractLabel(annotation);
+        return `${r(1)} = ForInNext(${r(2)}) else goto ${label ?? `pc:${raw[3]}`}`;
+      }
+
+    // Exception handling
+    case "TRY_SETUP":
+      {
+        return `try { catch -> pc:${raw[1]}, exReg=${r(2)}`;
+      }
+    case "TRY_END":
+      return `} // end try`;
+
+    // Self-modifying
+    case "PATCH":
+      return `patch(dest=pc:${raw[1]}, src=pc:${raw[2]}..${raw[3]})`;
+    case "DEBUGGER":
+      return `debugger`;
+    default:
+      return `??? ${opName} [${raw.join(", ")}]`;
+  }
+}
+export function disassembleCommentBlock(commentBlock) {
+  const lines = parseBlock(commentBlock);
+  let bodies = [];
+  let currentBody = [];
+  for (const line of lines) {
+    if (line.kind === "label") {
+      let newBody = [];
+      newBody.push(`// ${line.label}:`);
+      bodies.push(newBody);
+      currentBody = newBody;
+    } else if (line.instr) {
+      currentBody.push(`  ${disassembleInstr(line.instr)}`);
+    }
+  }
+  const out = bodies.flatMap(body => body);
+  return out.join("\n");
+}

package/dist/index.js

@@ -1,10 +1,15 @@
 import { compileAndSerialize } from "./compiler.js";
 import { DEFAULT_OPTIONS } from "./options.js";
+import { disassembleCommentBlock } from "./disassembler.js";
 async function obfuscate(source, options = DEFAULT_OPTIONS) {
-  const result = compileAndSerialize(source, options);
+  const result = await compileAndSerialize(source, options);
   return result;
 }
+async function disassemble(bytecodeComments) {
+  return disassembleCommentBlock(bytecodeComments);
+}
 export const JsConfuserVM = {
-  obfuscate
+  obfuscate,
+  disassemble
 };
 export default JsConfuserVM;

package/dist/runtime.js

@@ -8,14 +8,17 @@ const TIMING_CHECKS = false;
 // The text above is not included in the compiled output - for type intellisense only
 // @START
 
-function decodeBytecode(s) {
-  if (!ENCODE_BYTECODE) return s;
-  var b = typeof Buffer !== "undefined" ? Buffer.from(s, "base64") : Uint8Array.from(atob(s), function (c) {
+function base64ToBytes(s) {
+  return typeof Buffer !== "undefined" ? Buffer.from(s, "base64") : Uint8Array.from(atob(s), function (c) {
     return c.charCodeAt(0);
   });
-  // Each slot is a u16 stored as 2 little-endian bytes.
-  var r = new Uint16Array(b.length / 2);
-  for (var i = 0; i < r.length; i++) r[i] = b[i * 2] | b[i * 2 + 1] << 8;
+}
+function decodeBytecode(s) {
+  if (!ENCODE_BYTECODE) return s;
+  var b = base64ToBytes(s);
+  // Each slot is a u32 stored as 4 little-endian bytes.
+  var r = new Uint32Array(b.length / 4);
+  for (var i = 0; i < r.length; i++) r[i] = (b[i * 4] | b[i * 4 + 1] << 8 | b[i * 4 + 2] << 16 | b[i * 4 + 3] << 24) >>> 0;
   return r;
 }
 
@@ -88,7 +91,6 @@ function VM(bytecode, mainStartPc, mainRegCount, constants, globals) {
     startPc: mainStartPc
   };
   this._currentFrame = new Frame(new Closure(mainFn), null, null, undefined, 0, 0);
-  this._internals = {};
 }
 
 // Consume the next slot from the flat bytecode stream and advance the PC.
@@ -124,9 +126,7 @@ VM.prototype._constant = function (idxIn, keyIn) {
   if (!key) return v;
   if (typeof v === "number") return v ^ key;
   // String: base64-decode to u16 LE byte pairs, then XOR each code with (key+i).
-  var b = typeof Buffer !== "undefined" ? Buffer.from(v, "base64") : Uint8Array.from(atob(v), function (c) {
-    return c.charCodeAt(0);
-  });
+  var b = base64ToBytes(v);
   var out = "";
   for (var i = 0; i < b.length / 2; i++) {
     var code = b[i * 2] | b[i * 2 + 1] << 8; // u16 LE
@@ -187,6 +187,7 @@ VM.prototype.run = function () {
     try {
       var regs = this._regs;
       var base = frame._base;
+
       /* @SWITCH */
       switch (op) {
         case OP.LOAD_CONST:
@@ -231,8 +232,7 @@ VM.prototype.run = function () {
           }
         case OP.STORE_GLOBAL:
           {
-            // nameIdx and key are consumed inline so the concealConstants runtime
-            // transform can rewrite this._constant() consistently.
+            // globals[globalName] = regs[src]
             this.globals[this._constant()] = regs[base + this._operand()];
             break;
           }
@@ -257,13 +257,14 @@ VM.prototype.run = function () {
             var obj = regs[base + this._operand()];
             var key = regs[base + this._operand()];
             var val = regs[base + this._operand()];
-            // Reflect.set performs [[Set]] without throwing on failure,
-            // correctly simulating sloppy-mode assignment from a strict-mode host.
+            // Reflect.set performs [[Set]] without throwing on failure (non-strict mode behavior)
             Reflect.set(obj, key, val);
             break;
           }
         case OP.DELETE_PROP:
           {
+            // regs[dst] = delete regs[obj][regs[key]]
+            // The delete operator returns true if successful which is most cases
             var dst = this._operand();
             var obj = regs[base + this._operand()];
             var key = regs[base + this._operand()];
@@ -271,7 +272,7 @@ VM.prototype.run = function () {
             break;
           }
 
-        // ── Arithmetic  (dst, src1, src2) ────────────────────────────────────
+        // Arithmetic  (dst, src1, src2)
         case OP.ADD:
           {
             var dst = this._operand();
@@ -350,7 +351,7 @@ VM.prototype.run = function () {
             break;
           }
 
-        // ── Comparison  (dst, src1, src2) ─────────────────────────────────────
+        // Comparison  (dst, src1, src2)
         case OP.LT:
           {
             var dst = this._operand();
@@ -416,13 +417,14 @@ VM.prototype.run = function () {
           }
         case OP.INSTANCEOF:
           {
+            // regs[dst] = regs[obj] instanceof regs[ctor]
             var dst = this._operand();
             var obj = regs[base + this._operand()];
             var ctor = regs[base + this._operand()];
             if (typeof ctor === "function") {
               regs[base + dst] = obj instanceof ctor;
             } else {
-              // VM Closure - walk prototype chain for identity with ctor.prototype.
+              // TODO: Why is this needed?
               var proto = ctor.prototype;
               var target = Object.getPrototypeOf(obj);
               var result = false;
@@ -438,7 +440,7 @@ VM.prototype.run = function () {
             break;
           }
 
-        // ── Unary  (dst, src) ─────────────────────────────────────────────────
+        // Unary  (dst, src)
         case OP.UNARY_NEG:
           {
             var dst = this._operand();
@@ -472,13 +474,14 @@ VM.prototype.run = function () {
         case OP.VOID:
           {
             var dst = this._operand();
-            this._operand(); // consume src — evaluated for side-effects by compiler
+            this._operand(); // consumes argument (intended)
             regs[base + dst] = undefined;
             break;
           }
         case OP.TYPEOF_SAFE:
           {
-            // dst, nameConstIdx — safe typeof for potentially-undeclared globals.
+            // regs[dst] = typeof window[name]
+            // Never throws ReferenceError, instead returns undefined for undeclared variables
             var dst = this._operand();
             var name = this._constant();
             var val = Object.prototype.hasOwnProperty.call(this.globals, name) ? this.globals[name] : undefined;
@@ -486,7 +489,7 @@ VM.prototype.run = function () {
             break;
           }
 
-        // ── Control flow ──────────────────────────────────────────────────────
+        // Control flow
         case OP.JUMP:
           frame._pc = this._operand();
           break;
@@ -506,7 +509,7 @@ VM.prototype.run = function () {
             break;
           }
 
-        // ── Calls ─────────────────────────────────────────────────────────────
+        // Calls
         case OP.CALL:
           {
             // dst, calleeReg, argc, [argReg...]
@@ -521,8 +524,12 @@ VM.prototype.run = function () {
               this._ensureRegisterWindow(newBase, closure.fn.regCount);
               this._regsTop = newBase + closure.fn.regCount;
               var f = new Frame(closure, frame._pc, frame, this.globals, dst, newBase);
-              for (var i = 0; i < args.length && i < closure.fn.regCount; i++) {
-                this._regs[newBase + i] = args[i];
+              if (closure.fn.hasRest) {
+                var restSlot = closure.fn.paramCount - 1;
+                for (var i = 0; i < restSlot; i++) this._regs[newBase + i] = i < args.length ? args[i] : undefined;
+                this._regs[newBase + restSlot] = args.slice(restSlot);
+              } else {
+                for (var i = 0; i < args.length && i < closure.fn.regCount; i++) this._regs[newBase + i] = args[i];
               }
               if (closure.fn.paramCount < closure.fn.regCount) {
                 this._regs[newBase + closure.fn.paramCount] = args;
@@ -549,8 +556,12 @@ VM.prototype.run = function () {
               this._ensureRegisterWindow(newBase, closure.fn.regCount);
               this._regsTop = newBase + closure.fn.regCount;
               var f = new Frame(closure, frame._pc, frame, receiver, dst, newBase);
-              for (var i = 0; i < args.length && i < closure.fn.regCount; i++) {
-                this._regs[newBase + i] = args[i];
+              if (closure.fn.hasRest) {
+                var restSlot = closure.fn.paramCount - 1;
+                for (var i = 0; i < restSlot; i++) this._regs[newBase + i] = i < args.length ? args[i] : undefined;
+                this._regs[newBase + restSlot] = args.slice(restSlot);
+              } else {
+                for (var i = 0; i < args.length && i < closure.fn.regCount; i++) this._regs[newBase + i] = args[i];
               }
               if (closure.fn.paramCount < closure.fn.regCount) {
                 this._regs[newBase + closure.fn.paramCount] = args;
@@ -577,8 +588,12 @@ VM.prototype.run = function () {
               this._ensureRegisterWindow(newBase, closure.fn.regCount);
               this._regsTop = newBase + closure.fn.regCount;
               var f = new Frame(closure, frame._pc, frame, newObj, dst, newBase);
-              for (var i = 0; i < args.length && i < closure.fn.regCount; i++) {
-                this._regs[newBase + i] = args[i];
+              if (closure.fn.hasRest) {
+                var restSlot = closure.fn.paramCount - 1;
+                for (var i = 0; i < restSlot; i++) this._regs[newBase + i] = i < args.length ? args[i] : undefined;
+                this._regs[newBase + restSlot] = args.slice(restSlot);
+              } else {
+                for (var i = 0; i < args.length && i < closure.fn.regCount; i++) this._regs[newBase + i] = args[i];
               }
               if (closure.fn.paramCount < closure.fn.regCount) {
                 this._regs[newBase + closure.fn.paramCount] = args;
@@ -597,10 +612,14 @@ VM.prototype.run = function () {
           {
             var retVal = regs[base + this._operand()];
             this._closeUpvaluesFor(frame); // must happen before frame is abandoned
+
+            // Zero out callee's register window to limit exposing runtime values
+            var hi = frame._base + frame.closure.fn.regCount;
+            for (var i = frame._base; i < hi; i++) this._regs[i] = undefined;
             this._regsTop = frame._base;
             if (this._frameStack.length === 0) return retVal; // main script returning
 
-            // new-call rule: primitive return -> discard, use the constructed object instead
+            // NewExpression: When invoking from the 'new' keyword, the newly constructed object is returned instead (if the original function doesn't return an object)
             if (frame._newObj !== null) {
               if (typeof retVal !== "object" || retVal === null) retVal = frame._newObj;
             }
@@ -612,15 +631,17 @@ VM.prototype.run = function () {
         case OP.THROW:
           throw regs[base + this._operand()];
 
-        // ── Closures ──────────────────────────────────────────────────────────
+        // Closures
         case OP.MAKE_CLOSURE:
           {
-            // dst, startPc, paramCount, regCount, uvCount, [isLocal, idx, ...]
+            // dst, startPc, paramCount, regCount, uvCount, hasRest, [isLocal, idx, ...]
             var dst = this._operand();
             var startPc = this._operand();
             var paramCount = this._operand();
             var regCount = this._operand();
             var uvCount = this._operand();
+            var hasRest = this._operand(); // 1 if last param is a rest element
+
             var uvDescs = new Array(uvCount);
             for (var i = 0; i < uvCount; i++) {
               var isLocalRaw = this._operand();
@@ -634,7 +655,8 @@ VM.prototype.run = function () {
               paramCount: paramCount,
               regCount: regCount,
               startPc: startPc,
-              upvalueDescriptors: uvDescs
+              upvalueDescriptors: uvDescs,
+              hasRest: hasRest
             };
             var closure = new Closure(fn);
             for (var i = 0; i < uvDescs.length; i++) {
@@ -656,8 +678,12 @@ VM.prototype.run = function () {
                 var sub = new VM(self.bytecode, 0, c.fn.regCount, self.constants, self.globals);
                 var f = new Frame(c, null, null, this == null ? self.globals : this, 0, 0);
                 sub._currentFrame = f;
-                for (var i = 0; i < args.length && i < c.fn.regCount; i++) {
-                  sub._regs[i] = args[i];
+                if (c.fn.hasRest) {
+                  var restSlot = c.fn.paramCount - 1;
+                  for (var i = 0; i < restSlot; i++) sub._regs[i] = i < args.length ? args[i] : undefined;
+                  sub._regs[restSlot] = args.slice(restSlot);
+                } else {
+                  for (var i = 0; i < args.length && i < c.fn.regCount; i++) sub._regs[i] = args[i];
                 }
                 if (c.fn.paramCount < c.fn.regCount) {
                   sub._regs[c.fn.paramCount] = args;
@@ -671,7 +697,7 @@ VM.prototype.run = function () {
             break;
           }
 
-        // ── Collections ───────────────────────────────────────────────────────
+        // Collections
         case OP.BUILD_ARRAY:
           {
             // dst, count, [elemReg...]
@@ -697,7 +723,7 @@ VM.prototype.run = function () {
             break;
           }
 
-        // ── Property definitions (getters / setters) ──────────────────────────
+        // Object methods (getters / setters)
         case OP.DEFINE_GETTER:
           {
             // obj, key, fn
@@ -799,7 +825,7 @@ VM.prototype.run = function () {
             break;
           }
 
-        // ── Self-modifying bytecode ───────────────────────────────────────────
+        // Self-modifying bytecode
         case OP.PATCH:
           {
             // destPc, sliceStart, sliceEnd
@@ -813,10 +839,7 @@ VM.prototype.run = function () {
           }
         case OP.JUMP_REG:
           {
-            // Indirect jump: target PC is read from a register rather than a
-            // bytecode immediate. Used by the jumpDispatcher pass so that static
-            // analysis cannot determine the jump destination without tracking the
-            // register value (which contains an encoded PC resolved at runtime).
+            // Indirect jump: allows VM to jump based on runtime values.
             frame._pc = regs[base + this._operand()];
             break;
           }
@@ -829,9 +852,8 @@ VM.prototype.run = function () {
           throw new Error("Unknown opcode: " + op + " at pc " + (frame._pc - 1));
       }
     } catch (err) {
-      // Exception handler unwinding (CPython-style frame walk, Lua-style upvalue close).
-      // Walk from the current frame upward until we find a frame that has an open
-      // exception handler (TRY_SETUP without a matching TRY_END).
+      // Exception handler unwinding
+      // Walk from the current frame upward until we find a frame that has an open exception handler (TRY_SETUP without a matching TRY_END).
       // For every frame we abandon along the way, close its captured upvalues.
       var handledFrame = null;
       var searchFrame = this._currentFrame;
@@ -847,7 +869,7 @@ VM.prototype.run = function () {
         searchFrame = this._frameStack.pop();
         this._currentFrame = searchFrame;
       }
-      if (!handledFrame) throw err; // no handler anywhere — propagate to host
+      if (!handledFrame) throw err; // if there's no handler, propagate back to host
 
       var h = handledFrame._handlerStack.pop();
       // Discard any call-frames that were pushed inside the try body.
@@ -862,7 +884,7 @@ VM.prototype.run = function () {
   }
 };
 
-// Boot
+/* @BOOT */ // <- This comment can't be removed!
 var globals = {}; // global object for globals
 
 // Always pull built-ins from globalThis so eval() scoping can't shadow them