js-confuser-vm 0.0.2 → 0.0.4

package/src/transforms/bytecode/macroOpcodes.ts

@@ -0,0 +1,177 @@
+import type { Bytecode, Instruction } from "../../types.ts";
+import { Compiler, SOURCE_NODE_SYM } from "../../compiler.ts";
+import { nextFreeSlot, U16_MAX } from "../utils/op-utils.ts";
+
+// Opcodes that must not appear inside a macro window.
+// Jump ops: modifying frame._pc mid-execution causes the macro handler to
+//   run subsequent sub-bodies even after the jump already fired.
+// Frame-changing ops (CALL, CALL_METHOD, NEW, RETURN, THROW): push/pop call
+//   frames mid-macro, leaving the `frame` variable stale for later sub-bodies.
+// Variable-operand ops (MAKE_CLOSURE): the number of _operand() calls depends
+//   on uvCount at runtime, so a static handler cannot be generated.
+// Infrastructure ops (DATA, PATCH, TRY_SETUP, TRY_END, DEBUGGER):
+//   either illegal here or nonsensical to fold.
+
+// Scan bytecode for repeating instruction sequences and fold them into
+// macro opcodes.  Runs after selfModifying but before resolveLabels so
+// IR-ref operands (label/constant) are carried through transparently.
+//
+// Algorithm:
+//   1. Count every eligible window of length 2–5 by its op-code signature.
+//   2. Keep sequences that appear >= 2 times; sort by frequency then length.
+//   3. Assign unused opcode values (0–255, not already claimed by compiler.OP)
+//      to the most-frequent candidates and store in compiler.MACRO_OPS.
+//   4. Re-scan bytecode, replacing each matched sequence with a single
+//      multi-operand instruction:
+//        [macroOpCode, operands_of_instr_0..., operands_of_instr_1..., ...]
+//      The runtime macro handler inlines each sub-instruction body; those
+//      bodies call this._operand() themselves to consume the inline operands.
+export function macroOpcodes(
+  bc: Bytecode,
+  compiler: Compiler,
+): { bytecode: Bytecode } {
+  const originalOpToName = new Map<number, string>();
+  for (const name in compiler.OP) {
+    const opVal = compiler.OP[name];
+    originalOpToName.set(opVal, name);
+  }
+
+  function isEligible(op: number | null, compiler: Compiler): boolean {
+    if (op === null) return false;
+    const { OP, JUMP_OPS } = compiler;
+    if (JUMP_OPS.has(op)) return false;
+    const excluded = new Set<number | undefined>([
+      OP.RETURN,
+      OP.PATCH,
+      OP.TRY_SETUP,
+      OP.TRY_END,
+      OP.DEBUGGER,
+      OP.CALL,
+      OP.CALL_METHOD,
+      OP.NEW,
+      OP.THROW,
+      OP.MAKE_CLOSURE, // variable-length operands — cannot generate a static handler
+    ]);
+    return !excluded.has(op) && originalOpToName.has(op); // Only original Ops are eligible (specialized disallowed)
+  }
+
+  // Collect every opcode value already in use so we can find free slots.
+  const usedOpcodes = new Set<number>(
+    Object.values(compiler.OP).filter((v) => v !== undefined) as number[],
+  );
+  if (usedOpcodes.size > U16_MAX) return { bytecode: bc };
+
+  // ── Step 1: count window frequencies ──────────────────────────────────────
+  const freqMap = new Map<string, { ops: number[]; count: number }>();
+
+  for (let i = 0; i < bc.length; i++) {
+    for (let len = 2; len <= 5; len++) {
+      if (i + len > bc.length) break;
+
+      const ops: number[] = [];
+      let valid = true;
+      for (let j = 0; j < len; j++) {
+        const op = bc[i + j][0];
+        if (!isEligible(op, compiler)) {
+          valid = false;
+          break;
+        }
+        ops.push(op as number);
+      }
+      // If position (i+j) is ineligible, longer windows from i are also invalid.
+      if (!valid) break;
+
+      const key = ops.join(",");
+      const entry = freqMap.get(key);
+      if (entry) {
+        entry.count++;
+      } else {
+        freqMap.set(key, { ops, count: 1 });
+      }
+    }
+  }
+
+  // ── Step 2: keep repeated candidates, prioritise by frequency then length ─
+  const candidates = Array.from(freqMap.values())
+    .filter((e) => e.count >= 2)
+    .sort((a, b) => b.count - a.count || b.ops.length - a.ops.length);
+
+  if (candidates.length === 0) return { bytecode: bc };
+
+  // ── Step 3: assign free opcode slots to the best candidates ───────────────
+  for (let i = 0; i < candidates.length; i++) {
+    const macroOp = nextFreeSlot(usedOpcodes);
+    if (macroOp === -1) break;
+    const ops = candidates[i].ops;
+    compiler.MACRO_OPS[macroOp] = ops;
+    // Register a combined name so OP_NAME and comment generation both work.
+    let combinedName = ops
+      .map((v) => compiler.OP_NAME[v] ?? `OP_${v}`)
+      .join(",");
+    compiler.OP_NAME[macroOp] = combinedName;
+  }
+
+  // ── Step 4: build signature → macro opcode lookup ─────────────────────────
+  const sigToMacro = new Map<string, number>();
+  for (const [macroOpStr, ops] of Object.entries(compiler.MACRO_OPS)) {
+    sigToMacro.set((ops as number[]).join(","), Number(macroOpStr));
+  }
+
+  // ── Step 5: replace sequences with a single multi-operand macro instruction ─
+  // Emit [macroOpCode, ...all operands from all constituent instructions].
+  // The runtime handler inlines each sub-instruction body; those bodies call
+  // this._operand() themselves to consume the operands in order.
+  const result: Bytecode = [];
+  let i = 0;
+
+  while (i < bc.length) {
+    let matched = false;
+
+    for (let len = 5; len >= 2; len--) {
+      if (i + len > bc.length) continue;
+
+      const instructions: Instruction[] = [];
+      let valid = true;
+      for (let j = 0; j < len; j++) {
+        const instr = bc[i + j];
+        const op = instr[0];
+        if (!isEligible(op, compiler)) {
+          valid = false;
+          break;
+        }
+        instructions.push(instr);
+      }
+      if (!valid) continue;
+
+      const key = instructions.map((instr) => instr[0]).join(",");
+      if (!sigToMacro.has(key)) continue;
+
+      const macroOpCode = sigToMacro.get(key)!;
+
+      // Collect all operands from every constituent instruction, in order.
+      // Each instruction contributes instr.slice(1) — zero or more operands.
+      const allOperands: any[] = [];
+      for (let j = 0; j < len; j++) {
+        allOperands.push(...bc[i + j].slice(1));
+      }
+
+      const newInstr: Instruction = [macroOpCode, ...allOperands];
+      (newInstr as any)[SOURCE_NODE_SYM] = (instructions[0] as any)[
+        SOURCE_NODE_SYM
+      ];
+
+      result.push(newInstr);
+
+      i += len;
+      matched = true;
+      break;
+    }
+
+    if (!matched) {
+      result.push(bc[i]);
+      i++;
+    }
+  }
+
+  return { bytecode: result };
+}

package/src/transforms/bytecode/resolveContants.ts

@@ -0,0 +1,62 @@
+import type * as b from "../../types.ts";
+import { SOURCE_NODE_SYM } from "../../compiler.ts";
+
+// Resolve all {type:"constant", value} operands to integer indices into the
+// constants pool.  Returns both the resolved bytecode and the constants array
+// so the Serializer can use it for comment generation and output.
+// Constant refs may appear at any operand position (index 1, 2, 3, …).
+export function resolveConstants(bc: b.Bytecode): {
+  bytecode: b.Bytecode;
+  constants: any[];
+} {
+  const constants: any[] = [];
+  const constantsMap = new Map<any, number>();
+
+  function intern(operand: b.InstrOperand): b.Operand {
+    const operandAsObject =
+      typeof operand === "object" && operand ? operand : {};
+
+    const value = (operand as any).value;
+
+    let idx = constantsMap.get(value);
+    if (typeof idx !== "number") {
+      idx = constants.length;
+      constantsMap.set(value, idx);
+      constants.push(value);
+    }
+
+    const newOperand = {
+      ...operandAsObject,
+      type: "number",
+      resolvedValue: idx,
+    };
+
+    return newOperand;
+  }
+
+  const resolved: b.Bytecode = [];
+  for (const instr of bc) {
+    const [op, ...operands] = instr;
+
+    const hasConstant = operands.some(
+      (o) =>
+        o !== undefined &&
+        o !== null &&
+        typeof o === "object" &&
+        (o as any).type === "constant",
+    );
+
+    if (hasConstant) {
+      const newOperands = operands.map((operand) =>
+        (operand as any)?.type === "constant" ? intern(operand) : operand,
+      );
+      const newInstr = [op, ...newOperands] as b.Instruction;
+      (newInstr as any)[SOURCE_NODE_SYM] = (instr as any)[SOURCE_NODE_SYM];
+      resolved.push(newInstr);
+    } else {
+      resolved.push(instr);
+    }
+  }
+
+  return { bytecode: resolved, constants };
+}

package/src/transforms/bytecode/resolveLabels.ts

@@ -0,0 +1,107 @@
+// --- Label IR ---
+// During compilation, jump targets are symbolic labels instead of hard-coded
+// PC numbers.  Two IR "pseudo operands" carry the label information:
+//
+//   defineLabel operand  : [null, {type:"defineLabel", label:"FN_ENTRY_1"}]
+//     Marks a position in the bytecode array.
+//     resolveLabels() strips these out entirely.
+//
+//   label ref operand      : [OP.JUMP, {type:"label", label:"FN_ENTRY_1"}]
+//     Used as the operand of any jump instruction. resolveLabels() replaces
+//     it with the integer PC that the corresponding defineLabel resolves to.
+//
+// The output bytecode is still a nested array of instructions.
+// Flattening (one u16 slot per op, one per operand) happens in the Serializer.
+// PC values computed here reflect the FLAT slot index so that jump targets,
+// startPc, and LOAD_INT label operands are all correct after flattening.
+
+import type { Instruction } from "../../types.ts";
+import { Compiler, SOURCE_NODE_SYM } from "../../compiler.ts";
+
+// Resolve symbolic labels to absolute flat-PC indices within a bytecode array.
+// defineLabel pseudo-instructions are stripped; label-ref operands become ints.
+// Each instruction [op, ...operands] occupies (1 + operands.length) flat slots,
+// so realPc advances by instr.length for every non-pseudo instruction.
+export function resolveLabels(
+  bc: Instruction[],
+  compiler: Compiler,
+): {
+  bytecode: Instruction[];
+} {
+  // Pass 1 – walk the array and record each label's flat PC, counting
+  // real instructions by their full flat width (1 op + N operands).
+  const labelToPc = new Map<string, number>();
+  let realPc = 0;
+  for (const instr of bc) {
+    const op = instr[0];
+    const operand = instr[1];
+    if (
+      op === null &&
+      operand !== null &&
+      typeof operand === "object" &&
+      (operand as any).type === "defineLabel"
+    ) {
+      labelToPc.set((operand as any).label, realPc);
+    } else {
+      // Each instruction occupies 1 slot for the opcode + 1 per operand.
+      // IMPORTANT: 'placeholder' operands are not counted
+      realPc += instr.filter((x) => (x as any)?.placeholder !== true).length;
+    }
+  }
+
+  // Pass 2 – build the resolved instruction list.
+  // Label refs may appear at any operand position, so scan all of them.
+  const resolved: any[] = [];
+  for (const instr of bc) {
+    const [op, ...operands] = instr;
+
+    // Strip defineLabel pseudo-ops.
+    if (
+      op === null &&
+      typeof operands[0] === "object" &&
+      (operands[0] as any)?.type === "defineLabel"
+    ) {
+      continue;
+    }
+
+    // Replace label-ref operands with their resolved flat PC (any position).
+    const newOperands = operands.map((operand) => {
+      if (
+        operand !== undefined &&
+        operand !== null &&
+        typeof operand === "object" &&
+        (operand as any).type === "label"
+      ) {
+        const pc = labelToPc.get((operand as any).label);
+        if (pc === undefined)
+          throw new Error(`Undefined label: ${(operand as any).label}`);
+
+        var operandAsObject =
+          typeof operand === "object" && operand ? operand : {};
+
+        const newOperand = {
+          ...operandAsObject, // Preverse original operand properties
+          type: "number",
+          resolvedValue: pc + ((operand as any).offset ?? 0),
+        };
+
+        return newOperand;
+      }
+      return operand;
+    });
+
+    const newInstr = [op, ...newOperands];
+    (newInstr as any)[SOURCE_NODE_SYM] = (instr as any)[SOURCE_NODE_SYM];
+    resolved.push(newInstr);
+  }
+
+  // Patch each function descriptor's startPc now that labels are resolved.
+  for (const desc of compiler.fnDescriptors) {
+    desc.startPc =
+      labelToPc.get(desc.startLabel) ?? labelToPc.get(desc.entryLabel);
+  }
+
+  return {
+    bytecode: resolved,
+  };
+}

package/src/transforms/bytecode/selfModifying.ts

@@ -0,0 +1,121 @@
+import type { Bytecode, Instruction } from "../../types.ts";
+import { Compiler } from "../../compiler.ts";
+import { choice } from "../utils/random-utils.ts";
+
+export function selfModifying(
+  bc: Bytecode,
+  compiler: Compiler,
+): { bytecode: Bytecode } {
+  // Walk the bytecode looking for "defineLabel" pseudo-ops, which start basic
+  // blocks. For each block we collect the body (instructions between the label
+  // and the next label/jump terminator), move it to the end of the bytecode
+  // under a fresh "patch_LXX" label, and replace it in-place with:
+  //
+  //   defineLabel ("originalLabel")               ← kept as-is (pseudo-op)
+  //   PATCH  destPc  sliceStart  sliceEnd          ← 4 flat slots total
+  //   Garbage Opcodes  × bodyFlatSize                         ← placeholder slots
+  //
+  // PATCH reads three inline operands via _operand():
+  //   destPc     = originalLabel + 4  (first slot after PATCH's own 4 slots)
+  //   sliceStart = patchLabel          (flat PC of appended body)
+  //   sliceEnd   = patchLabel + bodyFlatSize
+  //
+  // On first execution PATCH copies bytecode[sliceStart..sliceEnd) over the
+  // placeholder region starting at destPc.  Execution then falls through into
+  // the freshly-patched body.  Subsequent calls are idempotent.
+
+  const { OP, JUMP_OPS } = compiler;
+
+  const result: Bytecode = [];
+  const appended: Bytecode = [];
+  let patchCount = 0;
+
+  let i = 0;
+  while (i < bc.length) {
+    const instr = bc[i];
+    const [op, operand] = instr;
+
+    // Detect a defineLabel pseudo-op — start of a new basic block.
+    if (
+      op === null &&
+      operand !== null &&
+      typeof operand === "object" &&
+      (operand as any).type === "defineLabel"
+    ) {
+      const originalLabel = (operand as any).label as string;
+      result.push(instr); // keep the defineLabel marker
+      i++;
+
+      // Collect body: everything after the label until the next terminator.
+      let j = i;
+      while (j < bc.length) {
+        const [nextOp, nextOperand] = bc[j];
+
+        // Another defineLabel = boundary of the next block.
+        if (
+          nextOp === null &&
+          typeof nextOperand === "object" &&
+          (nextOperand as any)?.type === "defineLabel"
+        ) {
+          break;
+        }
+
+        // Jump instructions, RETURN all terminate the body.
+        if (nextOp !== null && (JUMP_OPS.has(nextOp) || nextOp === OP.RETURN)) {
+          break;
+        }
+
+        j++;
+      }
+
+      const body = bc.slice(i, j);
+      const N = body.length;
+
+      if (N === 0) {
+        // Nothing to transform — label is immediately followed by a terminator.
+        continue;
+      }
+
+      const patchLabel = `patch_${originalLabel}_${patchCount++}`;
+
+      // Flat size of the body (each instruction occupies instr.length slots).
+      const bodyFlatSize = body.reduce(
+        (acc, instr) =>
+          acc + instr.filter((x) => (x as any)?.placeholder !== true).length,
+        0,
+      );
+
+      // ── PATCH instruction (4 flat slots: opcode + 3 operands) ───────────
+      //   destPc     = originalLabel + 4  (slot right after PATCH's 4 slots)
+      //   sliceStart = patchLabel
+      //   sliceEnd   = patchLabel + bodyFlatSize
+      result.push([
+        OP.PATCH as number,
+        { type: "label", label: originalLabel, offset: 4 },
+        { type: "label", label: patchLabel },
+        { type: "label", label: patchLabel, offset: bodyFlatSize },
+      ] as unknown as Instruction);
+
+      // ── Placeholders (Garbage Opcodes * bodyFlatSize, each 1 flat slot) ────────────
+      // These are overwritten by PATCH on first execution.
+      for (let p = 0; p < bodyFlatSize; p++) {
+        const randomOpcode = choice(Object.values(compiler.OP));
+        result.push([+randomOpcode]);
+      }
+
+      // ── Append real body at end ─────────────────────────────────────────
+      appended.push([null, { type: "defineLabel", label: patchLabel }]);
+      for (const bodyInstr of body) {
+        appended.push(bodyInstr);
+      }
+
+      i = j; // skip over the original body in the input array
+      continue;
+    }
+
+    result.push(instr);
+    i++;
+  }
+
+  return { bytecode: [...result, ...appended] };
+}

package/src/transforms/bytecode/specializedOpcodes.ts

@@ -0,0 +1,118 @@
+import type { Bytecode, InstrOperand, Instruction } from "../../types.ts";
+import { Compiler, SOURCE_NODE_SYM } from "../../compiler.ts";
+import { nextFreeSlot, U16_MAX } from "../utils/op-utils.ts";
+
+// Creates specialized opcodes for the most frequent (OPCODE + single_integer_operand) pairs.
+// Example: [OP.LOAD_CONST, 1] becomes [SPECIALIZED_LOAD_CONST_1].
+// Only instructions with *exactly one numeric operand* are considered.
+// MAKE_CLOSURE and any instruction with zero / multiple operands are skipped.
+// Runs after selfModifying but before resolveLabels (operands stay plain numbers).
+export function specializedOpcodes(
+  bc: Bytecode,
+  compiler: Compiler,
+): { bytecode: Bytecode } {
+  // ── Collect used opcodes exactly as specified ─────────────────────────────
+  const usedOpcodes = new Set<number>(
+    Object.keys(compiler.OP_NAME)
+      .map((k) => parseInt(k, 10))
+      .filter((v) => !isNaN(v)) as number[],
+  );
+
+  if (usedOpcodes.size > U16_MAX) return { bytecode: bc };
+
+  // ── Step 1: count frequency of eligible (op, operand) pairs ───────────────
+  const freqMap = new Map<
+    string,
+    { op: number; operand: InstrOperand; count: number }
+  >();
+
+  for (const instr of bc) {
+    const op = instr[0];
+    if (op === null || op === compiler.OP.MAKE_CLOSURE) continue;
+
+    // Must have exactly one operand and it must be a plain number
+    if (instr.length !== 2) continue;
+    const operand = instr[1];
+
+    const key = `${op},${operand}`;
+    const entry = freqMap.get(key);
+    if (entry) {
+      entry.count++;
+    } else {
+      freqMap.set(key, { op, operand, count: 1 });
+    }
+  }
+
+  // ── Step 2: keep combinations that appear >= 2 times, sort by frequency ───
+  const candidates = Array.from(freqMap.values())
+    .filter((e) => e.count >= 1)
+    .sort((a, b) => b.count - a.count);
+
+  if (candidates.length === 0) return { bytecode: bc };
+
+  // ── Step 3: assign free opcode slots to the best candidates ───────────────
+  const sigToSpecial = new Map<string, number>();
+  const specializedOps: Compiler["SPECIALIZED_OPS"] = {};
+
+  for (let i = 0; i < candidates.length; i++) {
+    const specialOp = nextFreeSlot(usedOpcodes);
+    if (specialOp === -1) break;
+    const { op: originalOp, operand } = candidates[i];
+
+    const key = `${originalOp},${JSON.stringify(operand)}`;
+    sigToSpecial.set(key, specialOp);
+
+    specializedOps[specialOp] = { originalOp, operand };
+
+    // Register a human-readable name for disassembly / debugging
+    const originalName = compiler.OP_NAME[originalOp] ?? `OP_${originalOp}`;
+    compiler.OP_NAME[specialOp] = `${originalName}_${JSON.stringify(operand)}`;
+  }
+
+  // Store mapping so the interpreter knows how to dispatch the specialized op
+  compiler.SPECIALIZED_OPS = specializedOps;
+
+  // ── Step 4: replace matching instructions with the new single-byte opcode ─
+  const result: Bytecode = [];
+
+  for (const instr of bc) {
+    const op = instr[0];
+    // Only consider instructions with exactly one numeric operand
+    if (op === null || instr.length !== 2 || op === compiler.OP.MAKE_CLOSURE) {
+      result.push(instr);
+      continue;
+    }
+
+    const operand = instr[1];
+    const key = `${op},${JSON.stringify(operand)}`;
+
+    if (sigToSpecial.has(key)) {
+      const specialOpCode = sigToSpecial.get(key)!;
+
+      const operandAsObject =
+        typeof operand === "object" && operand
+          ? operand
+          : {
+              type: "number",
+              value: operand,
+              resolvedValue: operand,
+            };
+
+      const newOperand = {
+        ...operandAsObject,
+        placeholder: true,
+      } as any as InstrOperand;
+
+      const newInstr: Instruction = [specialOpCode, newOperand];
+
+      // Preserve source-node information for error reporting
+      (newInstr as any)[SOURCE_NODE_SYM] = (instr as any)[SOURCE_NODE_SYM];
+
+      result.push(newInstr);
+    } else {
+      result.push(instr);
+    }
+  }
+
+  return { bytecode: result };
+}

package/src/transforms/runtime/macroOpcodes.ts

@@ -0,0 +1,111 @@
+import * as t from "@babel/types";
+import traverseImport from "@babel/traverse";
+import { ok } from "assert";
+import { Compiler } from "../../compiler.ts";
+const traverse = (traverseImport.default ||
+  traverseImport) as typeof traverseImport.default;
+
+// Extract the real statement list from a SwitchCase consequent, normalising
+// the two forms that appear in the runtime:
+//   • A single wrapping BlockStatement  →  use its .body
+//   • Statements listed directly        →  use as-is
+// In both cases trailing BreakStatement / EmptyStatement are filtered out.
+function extractCaseBody(switchCase: t.SwitchCase): t.Statement[] {
+  let stmts: t.Statement[];
+  if (
+    switchCase.consequent.length === 1 &&
+    t.isBlockStatement(switchCase.consequent[0])
+  ) {
+    stmts = (switchCase.consequent[0] as t.BlockStatement).body;
+  } else {
+    stmts = switchCase.consequent as t.Statement[];
+  }
+  return stmts.filter((s) => !t.isBreakStatement(s) && !t.isEmptyStatement(s));
+}
+
+// Append a generated switch case for every entry in compiler.MACRO_OPS.
+// Each case inlines the constituent case bodies directly — no operand stack,
+// no substitution needed.  Because every opcode handler now reads its own
+// operands via this._operand(), those calls naturally consume the inline
+// operands that macroOpcodes.ts embedded on the macro instruction.
+// Must be called BEFORE applyShuffleOpcodes so the new cases get shuffled.
+export function applyMacroOpcodes(ast: t.File, compiler: Compiler): void {
+  let switchStatement: t.SwitchStatement | null = null;
+  traverse(ast, {
+    SwitchStatement(path) {
+      if (path.node.leadingComments?.some((c) => c.value.includes("@SWITCH"))) {
+        switchStatement = path.node;
+        path.stop();
+      }
+    },
+  });
+
+  ok(switchStatement, "Could not find @SWITCH statement for macro opcodes");
+
+  // Build a map  opName → SwitchCase  from the existing OP.xxx case tests.
+  const nameToCaseMap = new Map<string, t.SwitchCase>();
+  for (const sc of (switchStatement as t.SwitchStatement).cases) {
+    const test = sc.test;
+    if (
+      test &&
+      t.isMemberExpression(test) &&
+      t.isIdentifier(test.object, { name: "OP" }) &&
+      t.isIdentifier(test.property)
+    ) {
+      nameToCaseMap.set((test.property as t.Identifier).name, sc);
+    }
+  }
+
+  for (const [macroOpStr, constituentOps] of Object.entries(
+    compiler.MACRO_OPS,
+  )) {
+    const macroOpCode = Number(macroOpStr);
+    const N = constituentOps.length;
+
+    // Resolve each constituent op value → case node via OP_NAME lookup.
+    const constituentCases: t.SwitchCase[] = [];
+    let allFound = true;
+    for (const opVal of constituentOps) {
+      const opName = compiler.OP_NAME[opVal];
+      if (!opName) {
+        allFound = false;
+        break;
+      }
+      const found = nameToCaseMap.get(opName);
+      if (!found) {
+        allFound = false;
+        break;
+      }
+      constituentCases.push(found);
+    }
+    if (!allFound) continue;
+
+    const opNames = constituentOps.map((v) => compiler.OP_NAME[v] ?? `OP_${v}`);
+
+    // ── Build the macro case body ──────────────────────────────────────────
+    // Clone and inline each sub-instruction's case body directly.
+    // No operand substitution needed: each body already calls this._operand()
+    // to read its own operands, which will consume the inline operands that
+    // macroOpcodes.ts embedded on the macro instruction in order.
+    const bodyStmts: t.Statement[] = [];
+
+    for (let i = 0; i < N; i++) {
+      const subStmts = extractCaseBody(constituentCases[i]).map(
+        (s) => t.cloneNode(s, true) as t.Statement,
+      );
+
+      if (subStmts.length > 0) {
+        t.addComment(subStmts[0], "leading", ` ${opNames[i]}`, true);
+        bodyStmts.push(...subStmts);
+      }
+    }
+
+    bodyStmts.push(t.breakStatement());
+
+    (switchStatement as t.SwitchStatement).cases.push(
+      t.switchCase(t.numericLiteral(macroOpCode), [
+        t.blockStatement(bodyStmts),
+      ]),
+    );
+  }
+}